fix: two-pass widget registration for parse-order dependency (#87) (#88)

* fix: resolve 12 open bug issues (#66–#84)

- #66: Make template literal interpolation loop string-aware (skip quoted
  strings and nested backtick templates)
- #67: Use consistent hook values in Computed macro instead of mixing
  getState() with hook-derived values
- #68: Add useEffect cleanup to clear SaveManager status timeout on unmount
- #69: Refactor ForIteration to derive localState from props each render
  (WidgetBody pattern), fixing stale parent locals
- #70: Disable CommonMark codeIndented via micromark extension and remove
  the regex that collapsed 4+ space indentation
- #71: Replace unsafe (err as Error).message with instanceof guard in
  Passage.tsx and PassageDialog.tsx
- #74: Keep StoryInit mounted in hidden container so async effects fire
- #75: Use visibleCharsRef in Type macro to prevent stale closure in guard
- #76: Propagate NobrContext into detached renders in Button and MacroLink
- #77: Add proper dependencies to Widget registration useLayoutEffect
- #83: Tag Date/RegExp in serialize with __Date__/__RegExp__ markers and
  reconstitute in deserialize for proper round-tripping
- #84: Reject empty history arrays in isSavePayload/isSaveExport validators
  and add guard in loadFromPayload

release-npm

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* fix: two-pass widget registration to resolve parse-order dependency (#87)

Block widgets used inside other widget definitions failed to parse if
their defining passage hadn't been processed yet. Pre-scan all widget
passages with regex to register block macros before any AST parsing.

release-npm

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: clem <clem@envy-new>
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: 3 people

src/index.tsx

@@ -108,7 +108,27 @@ function boot() {
     useStoryStore.getState().loadFromPayload(sessionPayload);
   }
 
-  // Register widgets from passages tagged "widget"
+  // Pass 1: Pre-scan all widget passages to discover block widgets.
+  // Register them as block macros BEFORE any tokenize/buildAST calls,
+  // so that widget bodies using other block widgets parse correctly
+  // regardless of passage order.
+  const blockWidgetPattern =
+    /\{widget\s+["']?(\w+)["']?[^}]*\}([\s\S]*?)\{\/widget\}/g;
+  for (const [, passage] of storyData.passages) {
+    if (passage.tags.includes('widget')) {
+      let match;
+      while ((match = blockWidgetPattern.exec(passage.content)) !== null) {
+        const name = match[1]!;
+        const body = match[2]!;
+        if (/\{@children\}/.test(body)) {
+          registerBlockMacro(name);
+        }
+      }
+      blockWidgetPattern.lastIndex = 0;
+    }
+  }
+
+  // Pass 2: Full parse and register widgets from passages tagged "widget"
   for (const [, passage] of storyData.passages) {
     if (passage.tags.includes('widget')) {
       const widgetTokens = tokenize(passage.content);

test/dom/block-widget.test.tsx

@@ -186,6 +186,35 @@ describe('block widgets', () => {
     expect(isBlockWidget('plain')).toBe(false);
   });
 
+  it('block widget used inside another widget definition parses regardless of order', () => {
+    // Simulate the two-pass approach from index.tsx:
+    // Pass 1: pre-scan raw text to discover block widgets
+    const passageA =
+      '{widget "Section" @title}<section><h3>{@title}</h3>{@children}</section>{/widget}';
+    const passageB =
+      '{widget "Card" @name}{Section "Details"}{@name}{/Section}{/widget}';
+
+    // If we parse passage B first WITHOUT pre-scanning, Section isn't
+    // in BLOCK_MACROS and buildAST would fail on {/Section}.
+    // Pre-scan passageA to register Section as block macro first.
+    const pattern = /\{widget\s+["']?(\w+)["']?[^}]*\}([\s\S]*?)\{\/widget\}/g;
+    let m;
+    while ((m = pattern.exec(passageA)) !== null) {
+      if (/\{@children\}/.test(m[2]!)) {
+        registerBlockMacro(m[1]!);
+        registeredBlockMacros.push(m[1]!);
+      }
+    }
+
+    // Now parse B first (the problematic order), then A
+    defineWidget(passageB);
+    defineWidget(passageA);
+
+    const el = renderPassage('{Card "Alice"}');
+    expect(el.textContent).toContain('Details');
+    expect(el.textContent).toContain('Alice');
+  });
+
   it('renders @children inside {if} within widget body', () => {
     defineAndTrack(
       '{widget "Conditional" @show}{if @show}<div class="wrap">{@children}</div>{/if}{/widget}',