feat: registry-based macro dispatch (#31)

## Summary
- Replace 370-line switch statement in `renderMacro()` with
`getMacro()`/`isSubMacro()` registry lookups (render.tsx: 627→258 lines)
- Each of 34 macro components self-registers via `registerMacro()` at
module level
- Sub-macros (`option`, `case`, `default`, `next`) registered via
`registerSubMacro()`
- `MacroProps` extended with `children?: ASTNode[]` and `branches?:
Branch[]` to cover all macro prop shapes
- New `src/macros/register-builtins.ts` import manifest triggers all
registrations
- Updated custom macro docs to reflect new `children` type (raw AST
nodes instead of pre-rendered)

Closes #21

## Test plan
- [x] `npx tsc --noEmit` passes
- [x] `npx vitest run` — all 656 tests pass
- [x] `npm run test:e2e` — all 177 e2e tests pass
- [x] Every case from old switch has a corresponding `registerMacro()`
call
- [x] All sub-macro names have `registerSubMacro()` calls

release-npm

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Author: rohal12

docs/custom-macros.md

@@ -10,7 +10,7 @@ Call `Story.registerMacro()` from a `{do}` block in `StoryInit`:
 :: StoryInit
 {do}
   Story.registerMacro("alert", (props) => {
-    return <div class="alert">{props.children}</div>;
+    return <div class="alert">{renderNodes(props.children ?? [])}</div>;
   });
 {/do}
 ```
@@ -27,12 +27,13 @@ Macro names are case-insensitive: `{alert}`, `{Alert}`, and `{ALERT}` all resolv
 
 Every custom macro receives these props:
 
-| Prop        | Type                       | Description                                                                         |
-| ----------- | -------------------------- | ----------------------------------------------------------------------------------- |
-| `rawArgs`   | `string`                   | The raw argument string after the macro name, e.g. `"$x + 1"` in `{mymacro $x + 1}` |
-| `className` | `string \| undefined`      | CSS class from selector syntax: `{.highlight mymacro}`                              |
-| `id`        | `string \| undefined`      | CSS id from selector syntax: `{#foo mymacro}`                                       |
-| `children`  | `preact.ComponentChildren` | Rendered child content (for block macros with `{/mymacro}`)                         |
+| Prop        | Type                     | Description                                                                                                                     |
+| ----------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
+| `rawArgs`   | `string`                 | The raw argument string after the macro name, e.g. `"$x + 1"` in `{mymacro $x + 1}`                                             |
+| `className` | `string \| undefined`    | CSS class from selector syntax: `{.highlight mymacro}`                                                                          |
+| `id`        | `string \| undefined`    | CSS id from selector syntax: `{#foo mymacro}`                                                                                   |
+| `children`  | `ASTNode[] \| undefined` | Raw AST child nodes (for block macros with `{/mymacro}`). Render with `renderNodes(children)` or `renderInlineNodes(children)`. |
+| `branches`  | `Branch[] \| undefined`  | Branch nodes from sub-macros like `{case}`, `{default}`, `{next}`. Only present for macros that define branching sub-macros.    |
 
 ## Reading State
 
@@ -114,7 +115,9 @@ function MyButton({ rawArgs, children }) {
     }
   };
 
-  return <button onClick={handleClick}>{children}</button>;
+  return (
+    <button onClick={handleClick}>{renderInlineNodes(children ?? [])}</button>
+  );
 }
 ```
 
@@ -184,7 +187,9 @@ const { update, getValues } = useContext(LocalsUpdateContext);
 const handleClick = () => {
   executeMutation(rawArgs, stripLocalsPrefix(getValues()), update);
 };
-return <button onClick={handleClick}>{children}</button>;
+return (
+  <button onClick={handleClick}>{renderInlineNodes(children ?? [])}</button>
+);
 ```
 
 ## Variable Namespaces at a Glance
@@ -212,7 +217,7 @@ function MyOutput({ rawArgs, className, id, children }) {
       id={id}
       class={className}
     >
-      {children}
+      {renderNodes(children ?? [])}
     </div>
   );
 }
@@ -246,7 +251,7 @@ A `{confirm}` macro that shows a confirmation dialog before executing code:
 
     return (
       <button id={props.id} class={cls} onClick={handleClick}>
-        {props.children}
+        {renderInlineNodes(props.children ?? [])}
       </button>
     );
   });

src/components/macros/Back.tsx

@@ -1,12 +1,9 @@
 import { useStoryStore } from '../../store';
 import { useAction } from '../../hooks/use-action';
+import { registerMacro } from '../../registry';
+import type { MacroProps } from '../../registry';
 
-interface BackProps {
-  className?: string;
-  id?: string;
-}
-
-export function Back({ className, id }: BackProps) {
+export function Back({ className, id }: MacroProps) {
   const goBack = useStoryStore((s) => s.goBack);
   const canGoBack = useStoryStore((s) => s.historyIndex > 0);
   const cls = className ? `menubar-button ${className}` : 'menubar-button';
@@ -31,3 +28,5 @@ export function Back({ className, id }: BackProps) {
     </button>
   );
 }
+
+registerMacro('back', Back);

src/components/macros/Button.tsx

@@ -5,16 +5,10 @@ import { useAction } from '../../hooks/use-action';
 import { useInterpolate } from '../../hooks/use-interpolate';
 import { executeMutation } from '../../execute-mutation';
 import { currentSourceLocation } from '../../utils/source-location';
-import type { ASTNode } from '../../markup/ast';
+import { registerMacro } from '../../registry';
+import type { MacroProps } from '../../registry';
 
-interface ButtonProps {
-  rawArgs: string;
-  children: ASTNode[];
-  className?: string;
-  id?: string;
-}
-
-export function Button({ rawArgs, children, className, id }: ButtonProps) {
+export function Button({ rawArgs, children = [], className, id }: MacroProps) {
   const resolve = useInterpolate();
   className = resolve(className);
   id = resolve(id);
@@ -51,3 +45,5 @@ export function Button({ rawArgs, children, className, id }: ButtonProps) {
     </button>
   );
 }
+
+registerMacro('button', Button);

src/components/macros/Checkbox.tsx

@@ -1,11 +1,7 @@
 import { useStoryStore } from '../../store';
 import { useAction } from '../../hooks/use-action';
-
-interface CheckboxProps {
-  rawArgs: string;
-  className?: string;
-  id?: string;
-}
+import { registerMacro } from '../../registry';
+import type { MacroProps } from '../../registry';
 
 function parseArgs(rawArgs: string): { varName: string; label: string } {
   const match = rawArgs.match(/^\s*(["']?\$\w+["']?)\s+["']?(.+?)["']?\s*$/);
@@ -17,7 +13,7 @@ function parseArgs(rawArgs: string): { varName: string; label: string } {
   return { varName, label };
 }
 
-export function Checkbox({ rawArgs, className, id }: CheckboxProps) {
+export function Checkbox({ rawArgs, className, id }: MacroProps) {
   const { varName, label } = parseArgs(rawArgs);
   const name = varName.startsWith('$') ? varName.slice(1) : varName;
 
@@ -50,3 +46,5 @@ export function Checkbox({ rawArgs, className, id }: CheckboxProps) {
     </label>
   );
 }
+
+registerMacro('checkbox', Checkbox);

src/components/macros/Computed.tsx

@@ -3,10 +3,8 @@ import { useStoryStore } from '../../store';
 import { evaluate } from '../../expression';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
 import { currentSourceLocation } from '../../utils/source-location';
-
-interface ComputedProps {
-  rawArgs: string;
-}
+import { registerMacro } from '../../registry';
+import type { MacroProps } from '../../registry';
 
 function parseComputedArgs(rawArgs: string): { target: string; expr: string } {
   const trimmed = rawArgs.trim();
@@ -87,7 +85,7 @@ function computeAndApply(
   }
 }
 
-export function Computed({ rawArgs }: ComputedProps) {
+export function Computed({ rawArgs }: MacroProps) {
   const [mergedVars, mergedTemps, mergedLocals] = useMergedLocals();
 
   let target: string;
@@ -138,3 +136,5 @@ export function Computed({ rawArgs }: ComputedProps) {
 
   return null;
 }
+
+registerMacro('computed', Computed);

src/components/macros/Cycle.tsx

@@ -1,16 +1,10 @@
 import { useStoryStore } from '../../store';
 import { extractOptions } from './option-utils';
 import { useAction } from '../../hooks/use-action';
-import type { ASTNode } from '../../markup/ast';
+import { registerMacro } from '../../registry';
+import type { MacroProps } from '../../registry';
 
-interface CycleProps {
-  rawArgs: string;
-  children: ASTNode[];
-  className?: string;
-  id?: string;
-}
-
-export function Cycle({ rawArgs, children, className, id }: CycleProps) {
+export function Cycle({ rawArgs, children = [], className, id }: MacroProps) {
   const varName = rawArgs.trim().replace(/["']/g, '');
   const name = varName.startsWith('$') ? varName.slice(1) : varName;
 
@@ -55,3 +49,5 @@ export function Cycle({ rawArgs, children, className, id }: CycleProps) {
     </button>
   );
 }
+
+registerMacro('cycle', Cycle);

src/components/macros/Do.tsx

@@ -1,15 +1,12 @@
 import { useLayoutEffect, useContext } from 'preact/hooks';
-import type { ASTNode } from '../../markup/ast';
 import { LocalsUpdateContext } from '../../markup/render';
 import { executeMutation } from '../../execute-mutation';
 import { currentSourceLocation } from '../../utils/source-location';
 import { collectText } from '../../utils/extract-text';
+import { registerMacro } from '../../registry';
+import type { MacroProps } from '../../registry';
 
-interface DoProps {
-  children: ASTNode[];
-}
-
-export function Do({ children }: DoProps) {
+export function Do({ children = [] }: MacroProps) {
   const code = collectText(children);
   const { update, getValues } = useContext(LocalsUpdateContext);
 
@@ -23,3 +20,5 @@ export function Do({ children }: DoProps) {
 
   return null;
 }
+
+registerMacro('do', Do);

src/components/macros/For.tsx

@@ -14,15 +14,10 @@ import {
 import { useMergedLocals } from '../../hooks/use-merged-locals';
 import { useInterpolate } from '../../hooks/use-interpolate';
 import { currentSourceLocation } from '../../utils/source-location';
+import { registerMacro } from '../../registry';
+import type { MacroProps } from '../../registry';
 import type { ASTNode } from '../../markup/ast';
 
-interface ForProps {
-  rawArgs: string;
-  children: ASTNode[];
-  className?: string;
-  id?: string;
-}
-
 /**
  * Parse for-loop args: "@item, @i of $list" or "@item of $list"
  */
@@ -94,7 +89,7 @@ function ForIteration({
   );
 }
 
-export function For({ rawArgs, children, className, id }: ForProps) {
+export function For({ rawArgs, children = [], className, id }: MacroProps) {
   const resolve = useInterpolate();
   className = resolve(className);
   id = resolve(id);
@@ -167,3 +162,5 @@ export function For({ rawArgs, children, className, id }: ForProps) {
     );
   return <>{content}</>;
 }
+
+registerMacro('for', For);

src/components/macros/Forward.tsx

@@ -1,12 +1,9 @@
 import { useStoryStore } from '../../store';
 import { useAction } from '../../hooks/use-action';
+import { registerMacro } from '../../registry';
+import type { MacroProps } from '../../registry';
 
-interface ForwardProps {
-  className?: string;
-  id?: string;
-}
-
-export function Forward({ className, id }: ForwardProps) {
+export function Forward({ className, id }: MacroProps) {
   const goForward = useStoryStore((s) => s.goForward);
   const canGoForward = useStoryStore(
     (s) => s.historyIndex < s.history.length - 1,
@@ -33,3 +30,5 @@ export function Forward({ className, id }: ForwardProps) {
     </button>
   );
 }
+
+registerMacro('forward', Forward);

src/components/macros/Goto.tsx

@@ -2,12 +2,10 @@ import { useLayoutEffect } from 'preact/hooks';
 import { useStoryStore } from '../../store';
 import { evaluate } from '../../expression';
 import { useMergedLocals } from '../../hooks/use-merged-locals';
+import { registerMacro } from '../../registry';
+import type { MacroProps } from '../../registry';
 
-interface GotoProps {
-  rawArgs: string;
-}
-
-export function Goto({ rawArgs }: GotoProps) {
+export function Goto({ rawArgs }: MacroProps) {
   const [variables, temporary, locals] = useMergedLocals();
 
   useLayoutEffect(() => {
@@ -23,3 +21,5 @@ export function Goto({ rawArgs }: GotoProps) {
 
   return null;
 }
+
+registerMacro('goto', Goto);