chore: version packages (#80 )

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>
next release (#79 )
2026-10-02 12:00:58 +08:00 · 2026-02-07 12:31:01 -06:00 · 2026-02-07 12:17:32 -06:00 · 2026-02-07 12:09:53 -06:00 · 2026-02-07 11:46:16 -06:00
38 changed files with 933 additions and 621 deletions
@@ -273,8 +273,8 @@ compiler.reset();`}</Code>
      </p>
      <Code lang="typescript">{`import { compileSpecStream } from '@json-render/core';

-const jsonl = \`{"op":"set","path":"/root","value":{}}
-{"op":"set","path":"/root/type","value":"Card"}\`;
+const jsonl = \`{"op":"add","path":"/root","value":{}}
+{"op":"add","path":"/root/type","value":"Card"}\`;

 const spec = compileSpecStream<MySpec>(jsonl);`}</Code>

@@ -285,22 +285,36 @@ const spec = compileSpecStream<MySpec>(jsonl);`}</Code>
 } from '@json-render/core';

 // Parse a single line
-const patch = parseSpecStreamLine('{"op":"set","path":"/root","value":{}}');
+const patch = parseSpecStreamLine('{"op":"add","path":"/root","value":{}}');

 // Apply patch to object (mutates in place)
 const obj = {};
 applySpecStreamPatch(obj, patch);`}</Code>

      <h3 className="text-lg font-semibold mt-8 mb-4">SpecStream Types</h3>
+      <p className="text-sm text-muted-foreground mb-4">
+        Fully compliant with{" "}
+        <a
+          href="https://datatracker.ietf.org/doc/html/rfc6902"
+          className="underline"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          RFC 6902
+        </a>
+        :
+      </p>
      <Code lang="typescript">{`interface SpecStreamLine {
-  op: 'set' | 'add' | 'replace' | 'remove';
+  op: 'add' | 'remove' | 'replace' | 'move' | 'copy' | 'test';
  path: string;
-  value?: unknown;
+  value?: unknown;  // Required for add, replace, test
+  from?: string;    // Required for move, copy
 }

 interface SpecStreamCompiler<T> {
  push(chunk: string): { result: T; newPatches: SpecStreamLine[] };
  getResult(): T;
+  getPatches(): SpecStreamLine[];
  reset(): void;
 }`}</Code>

@@ -275,11 +275,9 @@ export const openapiCatalog = createCatalog({
 }

 interface SpecElement {
-  key: string;
  type: string;
  props: Record<string, unknown>;
  children: string[];
-  parentKey: string;
 }

 function schemaToSpec(
@@ -295,7 +293,6 @@ function schemaToSpec(

  if (schema.enum) {
    elements.set(key, {
-      key,
      type: 'EnumField',
      props: {
        name,
@@ -306,11 +303,9 @@ function schemaToSpec(
        defaultValue: schema.default as string,
      },
      children: [],
-      parentKey,
    });
  } else if (schema.type === 'string') {
    elements.set(key, {
-      key,
      type: 'StringField',
      props: {
        name,
@@ -323,11 +318,9 @@ function schemaToSpec(
        defaultValue: schema.default as string,
      },
      children: [],
-      parentKey,
    });
  } else if (schema.type === 'integer' || schema.type === 'number') {
    elements.set(key, {
-      key,
      type: 'NumberField',
      props: {
        name,
@@ -340,11 +333,9 @@ function schemaToSpec(
        defaultValue: schema.default as number,
      },
      children: [],
-      parentKey,
    });
  } else if (schema.type === 'boolean') {
    elements.set(key, {
-      key,
      type: 'BooleanField',
      props: {
        name,
@@ -353,7 +344,6 @@ function schemaToSpec(
        defaultValue: schema.default as boolean,
      },
      children: [],
-      parentKey,
    });
  } else if (schema.type === 'array' && schema.items) {
    const childKeys: string[] = [];
@@ -361,7 +351,6 @@ function schemaToSpec(
    childKeys.push(itemKey);

    elements.set(key, {
-      key,
      type: 'ArrayField',
      props: {
        name,
@@ -369,7 +358,6 @@ function schemaToSpec(
        description: schema.description,
      },
      children: childKeys,
-      parentKey,
    });
  } else if (schema.type === 'object' && schema.properties) {
    const childKeys: string[] = [];
@@ -386,7 +374,6 @@ function schemaToSpec(
    }

    elements.set(key, {
-      key,
      type: 'ObjectField',
      props: {
        name,
@@ -394,7 +381,6 @@ function schemaToSpec(
        description: schema.description,
      },
      children: childKeys,
-      parentKey,
    });
  }

@@ -428,7 +414,6 @@ export function operationToSpec(
  }

  elements.set(rootKey, {
-    key: rootKey,
    type: 'Form',
    props: {
      operationId,
@@ -438,7 +423,6 @@ export function operationToSpec(
      description,
    },
    children: childKeys,
-    parentKey: '',
  });

  return {
@@ -98,25 +98,19 @@ export default function SchemasPage() {
  "root": "card-1",
  "elements": {
    "card-1": {
-      "key": "card-1",
      "type": "Card",
      "props": { "title": "Dashboard" },
-      "children": ["text-1", "button-1"],
-      "parentKey": ""
+      "children": ["text-1", "button-1"]
    },
    "text-1": {
-      "key": "text-1",
      "type": "Text",
      "props": { "content": "Welcome, $data.user.name" },
-      "children": [],
-      "parentKey": "card-1"
+      "children": []
    },
    "button-1": {
-      "key": "button-1",
      "type": "Button",
      "props": { "label": "Click me" },
-      "children": [],
-      "parentKey": "card-1"
+      "children": []
    }
  }
 }`}</Code>
@@ -129,11 +123,9 @@ export default function SchemasPage() {
        structure:
      </p>
      <Code lang="typescript">{`interface Element {
-  key: string;                 // Unique identifier
  type: string;                // Component type from catalog
  props: Record<string, any>;  // Component properties
  children: string[];          // Array of child element keys
-  parentKey: string;           // Parent element key (empty for root)
  visible?: VisibilityRule;    // Conditional display
 }`}</Code>

@@ -143,14 +135,12 @@ export default function SchemasPage() {
        <code className="text-foreground">$data</code> prefix in props:
      </p>
      <Code lang="json">{`{
-  "key": "greeting",
  "type": "Text",
  "props": {
    "content": "$data.user.name",
    "count": "$data.items.length"
  },
-  "children": [],
-  "parentKey": "card-1"
+  "children": []
 }`}</Code>

      <h3 className="text-lg font-medium mt-8 mb-3">Action Format</h3>
@@ -50,18 +50,14 @@ export default function SpecsPage() {
  "root": "card-1",
  "elements": {
    "card-1": {
-      "key": "card-1",
      "type": "Card",
      "props": { "title": "Welcome" },
-      "children": ["text-1"],
-      "parentKey": ""
+      "children": ["text-1"]
    },
    "text-1": {
-      "key": "text-1",
      "type": "Text",
      "props": { "content": "Hello, $data.user.name!" },
-      "children": [],
-      "parentKey": "card-1"
+      "children": []
    }
  }
 }`}</Code>
@@ -74,53 +70,39 @@ export default function SpecsPage() {
  "root": "card-1",
  "elements": {
    "card-1": {
-      "key": "card-1",
      "type": "Card",
      "props": { "title": "User Profile", "padding": "md" },
-      "children": ["row-1", "button-1"],
-      "parentKey": ""
+      "children": ["row-1", "button-1"]
    },
    "row-1": {
-      "key": "row-1",
      "type": "Row",
      "props": { "gap": "md" },
-      "children": ["avatar-1", "stack-1"],
-      "parentKey": "card-1"
+      "children": ["avatar-1", "stack-1"]
    },
    "avatar-1": {
-      "key": "avatar-1",
      "type": "Avatar",
      "props": { "src": "$data.user.avatar", "alt": "$data.user.name" },
-      "children": [],
-      "parentKey": "row-1"
+      "children": []
    },
    "stack-1": {
-      "key": "stack-1",
      "type": "Stack",
      "props": { "gap": "sm" },
-      "children": ["name-text", "email-text"],
-      "parentKey": "row-1"
+      "children": ["name-text", "email-text"]
    },
    "name-text": {
-      "key": "name-text",
      "type": "Text",
      "props": { "content": "$data.user.name", "variant": "heading" },
-      "children": [],
-      "parentKey": "stack-1"
+      "children": []
    },
    "email-text": {
-      "key": "email-text",
      "type": "Text",
      "props": { "content": "$data.user.email", "variant": "caption" },
-      "children": [],
-      "parentKey": "stack-1"
+      "children": []
    },
    "button-1": {
-      "key": "button-1",
      "type": "Button",
      "props": { "label": "Edit Profile" },
-      "children": [],
-      "parentKey": "card-1"
+      "children": []
    }
  }
 }`}</Code>
@@ -133,21 +115,16 @@ export default function SpecsPage() {
  "root": "page",
  "elements": {
    "page": {
-      "key": "page",
      "type": "Page",
      "props": {},
-      "children": ["header", "hero", "features", "footer"],
-      "parentKey": ""
+      "children": ["header", "hero", "features", "footer"]
    },
    "header": {
-      "key": "header",
      "type": "Header",
      "props": { "logo": "/logo.svg", "navItems": ["Products", "Pricing", "Docs"] },
-      "children": [],
-      "parentKey": "page"
+      "children": []
    },
    "hero": {
-      "key": "hero",
      "type": "Hero",
      "props": {
        "title": "Build UIs with JSON",
@@ -155,43 +132,32 @@ export default function SpecsPage() {
        "ctaLabel": "Get Started",
        "ctaHref": "/docs"
      },
-      "children": [],
-      "parentKey": "page"
+      "children": []
    },
    "features": {
-      "key": "features",
      "type": "Features",
      "props": { "columns": 3 },
-      "children": ["feature-1", "feature-2", "feature-3"],
-      "parentKey": "page"
+      "children": ["feature-1", "feature-2", "feature-3"]
    },
    "feature-1": {
-      "key": "feature-1",
      "type": "Feature",
      "props": { "icon": "zap", "title": "Fast", "description": "Render UIs in milliseconds" },
-      "children": [],
-      "parentKey": "features"
+      "children": []
    },
    "feature-2": {
-      "key": "feature-2",
      "type": "Feature",
      "props": { "icon": "shield", "title": "Secure", "description": "Validate all specs against your catalog" },
-      "children": [],
-      "parentKey": "features"
+      "children": []
    },
    "feature-3": {
-      "key": "feature-3",
      "type": "Feature",
      "props": { "icon": "sparkles", "title": "AI-Ready", "description": "Generate prompts from your catalog" },
-      "children": [],
-      "parentKey": "features"
+      "children": []
    },
    "footer": {
-      "key": "footer",
      "type": "Footer",
      "props": { "copyright": "2025 Acme Inc", "links": ["Privacy", "Terms", "Contact"] },
-      "children": [],
-      "parentKey": "page"
+      "children": []
    }
  }
 }`}</Code>
@@ -209,11 +175,9 @@ export default function SpecsPage() {
  "root": "card-1",
  "elements": {
    "card-1": {
-      "key": "card-1",
      "type": "Card",
      "props": { "title": "My Card" },
-      "children": ["text-1"],
-      "parentKey": ""
+      "children": ["text-1"]
    },
    "text-1": { ... }
  }
@@ -224,17 +188,11 @@ export default function SpecsPage() {
        Each element in the map has a consistent shape:
      </p>
      <Code lang="json">{`{
-  "key": "unique-id",
  "type": "ComponentName",
  "props": { "label": "Hello" },
-  "children": ["child-1", "child-2"],
-  "parentKey": "parent-id"
+  "children": ["child-1", "child-2"]
 }`}</Code>
      <ul className="list-disc list-inside text-sm text-muted-foreground space-y-1 mt-3 mb-4">
-        <li>
-          <code className="text-foreground">key</code> — Unique identifier for
-          this element
-        </li>
        <li>
          <code className="text-foreground">type</code> — Component type from
          your catalog
@@ -246,10 +204,6 @@ export default function SpecsPage() {
          <code className="text-foreground">children</code> — Array of child
          element keys
        </li>
-        <li>
-          <code className="text-foreground">parentKey</code> — Key of parent
-          element (empty string for root)
-        </li>
      </ul>

      <h3 className="text-lg font-medium mt-8 mb-3">Dynamic Data</h3>
@@ -258,15 +212,13 @@ export default function SpecsPage() {
        <code className="text-foreground">$data</code> paths:
      </p>
      <Code lang="json">{`{
-  "key": "metric-1",
  "type": "Metric",
  "props": {
    "label": "Total Revenue",
    "value": "$data.metrics.revenue",
    "change": "$data.metrics.revenueChange"
  },
-  "children": [],
-  "parentKey": "dashboard"
+  "children": []
 }`}</Code>

      <h3 className="text-lg font-medium mt-8 mb-3">Conditional Visibility</h3>
@@ -275,13 +227,11 @@ export default function SpecsPage() {
        <code className="text-foreground">visible</code> property:
      </p>
      <Code lang="json">{`{
-  "key": "alert-1",
  "type": "Alert",
  "props": {
    "message": "You have unsaved changes"
  },
  "children": [],
-  "parentKey": "form",
  "visible": {
    "path": "$data.form.isDirty",
    "operator": "eq",
@@ -18,9 +18,10 @@ export default function StreamingPage() {
        format where each line is a JSON patch operation that progressively
        builds your spec:
      </p>
-      <Code lang="json">{`{"op":"set","path":"/root","value":{"key":"root","type":"Card","props":{"title":"Dashboard"}}}
-{"op":"set","path":"/root/children/0","value":{"key":"metric-1","type":"Metric","props":{"label":"Revenue"}}}
-{"op":"set","path":"/root/children/1","value":{"key":"metric-2","type":"Metric","props":{"label":"Users"}}}`}</Code>
+      <Code lang="json">{`{"op":"add","path":"/root","value":"root"}
+{"op":"add","path":"/elements/root","value":{"type":"Card","props":{"title":"Dashboard"},"children":["metric-1","metric-2"]}}
+{"op":"add","path":"/elements/metric-1","value":{"type":"Metric","props":{"label":"Revenue"}}}
+{"op":"add","path":"/elements/metric-2","value":{"type":"Metric","props":{"label":"Users"}}}`}</Code>

      <h2 className="text-xl font-semibold mt-12 mb-4">useUIStream Hook</h2>
      <p className="text-sm text-muted-foreground mb-4">
@@ -42,26 +43,47 @@ function App() {
  });
 }`}</Code>

-      <h2 className="text-xl font-semibold mt-12 mb-4">Patch Operations</h2>
+      <h2 className="text-xl font-semibold mt-12 mb-4">
+        Patch Operations (RFC 6902)
+      </h2>
      <p className="text-sm text-muted-foreground mb-4">
-        Supported operations:
+        SpecStream uses{" "}
+        <a
+          href="https://datatracker.ietf.org/doc/html/rfc6902"
+          className="underline"
+          target="_blank"
+          rel="noopener noreferrer"
+        >
+          RFC 6902 JSON Patch
+        </a>{" "}
+        operations:
      </p>
      <ul className="list-disc list-inside text-sm text-muted-foreground space-y-2 mb-4">
        <li>
-          <code className="text-foreground">set</code> — Set the value at a path
-          (creates if needed)
+          <code className="text-foreground">add</code> — Add a value at a path
+          (creates or replaces for objects, inserts for arrays)
        </li>
        <li>
-          <code className="text-foreground">add</code> — Add to an array at a
-          path
+          <code className="text-foreground">remove</code> — Remove the value at
+          a path
        </li>
        <li>
-          <code className="text-foreground">replace</code> — Replace value at a
-          path
+          <code className="text-foreground">replace</code> — Replace an existing
+          value at a path
        </li>
        <li>
-          <code className="text-foreground">remove</code> — Remove value at a
-          path
+          <code className="text-foreground">move</code> — Move a value from one
+          path to another (requires{" "}
+          <code className="text-foreground">from</code>)
+        </li>
+        <li>
+          <code className="text-foreground">copy</code> — Copy a value from one
+          path to another (requires{" "}
+          <code className="text-foreground">from</code>)
+        </li>
+        <li>
+          <code className="text-foreground">test</code> — Assert that a value at
+          a path equals the given value
        </li>
      </ul>

@@ -169,8 +191,8 @@ async function processStream(reader: ReadableStreamDefaultReader) {
      </p>
      <Code lang="typescript">{`import { compileSpecStream } from '@json-render/core';

-const jsonl = \`{"op":"set","path":"/root","value":{"type":"Card"}}
-{"op":"set","path":"/root/props","value":{"title":"Hello"}}\`;
+const jsonl = \`{"op":"add","path":"/root","value":{"type":"Card"}}
+{"op":"add","path":"/root/props","value":{"title":"Hello"}}\`;

 const spec = compileSpecStream<MySpec>(jsonl);
 // { root: { type: "Card", props: { title: "Hello" } } }`}</Code>
@@ -127,15 +127,16 @@ export const catalog = createCatalog({
                Constrained output that your components render natively.
              </p>
              <Code lang="json">{`{
-  "key": "dashboard",
-  "type": "Card",
-  "props": {
-    "title": "Revenue Dashboard",
-    "description": null
-  },
-  "children": [
-    {
-      "key": "revenue",
+  "root": "dashboard",
+  "elements": {
+    "dashboard": {
+      "type": "Card",
+      "props": {
+        "title": "Revenue Dashboard"
+      },
+      "children": ["revenue"]
+    },
+    "revenue": {
      "type": "Metric",
      "props": {
        "label": "Total Revenue",
@@ -143,7 +144,7 @@ export const catalog = createCatalog({
        "format": "currency"
      }
    }
-  ]
+  }
 }`}</Code>
            </div>
          </div>
@@ -170,13 +171,11 @@ export const catalog = createCatalog({
  "root": "card",
  "elements": {
    "card": {
-      "key": "card",
      "type": "Card",
      "props": { "title": "Revenue" },
      "children": ["metric", "chart"]
    },
    "metric": {
-      "key": "metric",
      "type": "Metric",
      "props": {
        "label": "Total Revenue",
@@ -185,7 +184,6 @@ export const catalog = createCatalog({
      }
    },
    "chart": {
-      "key": "chart",
      "type": "Chart",
      "props": {
        "dataPath": "analytics/salesByRegion"
@@ -62,8 +62,9 @@ USER REQUEST: ${sanitizedPrompt}

 IMPORTANT: The current UI is already loaded. Output ONLY the patches needed to make the requested change:
 - To add a new element: {"op":"add","path":"/elements/new-key","value":{...}}
- To modify an existing element: {"op":"set","path":"/elements/existing-key","value":{...}}
- To update the root: {"op":"set","path":"/root","value":"new-root-key"}
+- To modify an existing element: {"op":"replace","path":"/elements/existing-key","value":{...}}
+- To remove an element: {"op":"remove","path":"/elements/old-key"}
+- To update the root: {"op":"replace","path":"/root","value":"new-root-key"}
 - To add children: update the parent element with new children array

 DO NOT output patches for elements that don't need to change. Only output what's necessary for the requested modification.`;
@@ -29,124 +29,109 @@ const SIMULATION_STAGES: SimulationStage[] = [
      root: "card",
      elements: {
        card: {
-          key: "card",
          type: "Card",
          props: { title: "Contact Us", maxWidth: "md" },
          children: [],
        },
      },
    },
-    stream: '{"op":"set","path":"/root","value":"card"}',
+    stream: '{"op":"add","path":"/root","value":"card"}',
  },
  {
    tree: {
      root: "card",
      elements: {
        card: {
-          key: "card",
          type: "Card",
          props: { title: "Contact Us", maxWidth: "md" },
          children: ["name"],
        },
        name: {
-          key: "name",
          type: "Input",
          props: { label: "Name", name: "name" },
        },
      },
    },
    stream:
-      '{"op":"add","path":"/elements/card","value":{"key":"card","type":"Card","props":{"title":"Contact Us","maxWidth":"md"},"children":["name"]}}',
+      '{"op":"add","path":"/elements/card","value":{"type":"Card","props":{"title":"Contact Us","maxWidth":"md"},"children":["name"]}}',
  },
  {
    tree: {
      root: "card",
      elements: {
        card: {
-          key: "card",
          type: "Card",
          props: { title: "Contact Us", maxWidth: "md" },
          children: ["name", "email"],
        },
        name: {
-          key: "name",
          type: "Input",
          props: { label: "Name", name: "name" },
        },
        email: {
-          key: "email",
          type: "Input",
          props: { label: "Email", name: "email" },
        },
      },
    },
    stream:
-      '{"op":"add","path":"/elements/email","value":{"key":"email","type":"Input","props":{"label":"Email","name":"email"}}}',
+      '{"op":"add","path":"/elements/email","value":{"type":"Input","props":{"label":"Email","name":"email"}}}',
  },
  {
    tree: {
      root: "card",
      elements: {
        card: {
-          key: "card",
          type: "Card",
          props: { title: "Contact Us", maxWidth: "md" },
          children: ["name", "email", "message"],
        },
        name: {
-          key: "name",
          type: "Input",
          props: { label: "Name", name: "name" },
        },
        email: {
-          key: "email",
          type: "Input",
          props: { label: "Email", name: "email" },
        },
        message: {
-          key: "message",
          type: "Textarea",
          props: { label: "Message", name: "message" },
        },
      },
    },
    stream:
-      '{"op":"add","path":"/elements/message","value":{"key":"message","type":"Textarea","props":{"label":"Message","name":"message"}}}',
+      '{"op":"add","path":"/elements/message","value":{"type":"Textarea","props":{"label":"Message","name":"message"}}}',
  },
  {
    tree: {
      root: "card",
      elements: {
        card: {
-          key: "card",
          type: "Card",
          props: { title: "Contact Us", maxWidth: "md" },
          children: ["name", "email", "message", "submit"],
        },
        name: {
-          key: "name",
          type: "Input",
          props: { label: "Name", name: "name" },
        },
        email: {
-          key: "email",
          type: "Input",
          props: { label: "Email", name: "email" },
        },
        message: {
-          key: "message",
          type: "Textarea",
          props: { label: "Message", name: "message" },
        },
        submit: {
-          key: "submit",
          type: "Button",
          props: { label: "Send Message", variant: "primary" },
        },
      },
    },
    stream:
-      '{"op":"add","path":"/elements/submit","value":{"key":"submit","type":"Button","props":{"label":"Send Message","variant":"primary"}}}',
+      '{"op":"add","path":"/elements/submit","value":{"type":"Button","props":{"label":"Send Message","variant":"primary"}}}',
  },
 ];

@@ -70,25 +70,19 @@ const spec: Spec = {
  root: "container",
  elements: {
    container: {
-      key: "container",
      type: "Stack",
      props: { direction: "vertical", gap: "medium" },
      children: ["heading", "metric"],
-      parentKey: null,
    },
    heading: {
-      key: "heading",
      type: "Heading",
      props: { text: "Revenue", size: "large" },
      children: [],
-      parentKey: "container",
    },
    metric: {
-      key: "metric",
      type: "Metric",
      props: { label: "Total", value: "$12,345", format: "currency" },
      children: [],
-      parentKey: "container",
    },
  },
 };
@@ -84,14 +84,11 @@ function createCustomerDetailSpec(

  const elements: Spec["elements"] = {
    root: {
-      key: "root",
      type: "Stack",
      props: { direction: "vertical", gap: "large" },
      children: ["header", "details", "sections"],
-      parentKey: null,
    },
    header: {
-      key: "header",
      type: "Stack",
      props: {
        direction: "horizontal",
@@ -99,38 +96,28 @@ function createCustomerDetailSpec(
        distribute: "space-between",
      },
      children: ["customerInfo", "actions"],
-      parentKey: "root",
    },
    customerInfo: {
-      key: "customerInfo",
      type: "Stack",
      props: { direction: "vertical", gap: "xsmall" },
      children: ["customerName", "customerEmail"],
-      parentKey: "header",
    },
    customerName: {
-      key: "customerName",
      type: "Heading",
      props: { text: customer?.name ?? "Unknown Customer", size: "xlarge" },
      children: [],
-      parentKey: "customerInfo",
    },
    customerEmail: {
-      key: "customerEmail",
      type: "Text",
      props: { content: customer?.email ?? "", color: "secondary" },
      children: [],
-      parentKey: "customerInfo",
    },
    actions: {
-      key: "actions",
      type: "Stack",
      props: { direction: "horizontal", gap: "small" },
      children: ["editBtn", "portalBtn"],
-      parentKey: "header",
    },
    editBtn: {
-      key: "editBtn",
      type: "Button",
      props: {
        label: "Edit",
@@ -139,10 +126,8 @@ function createCustomerDetailSpec(
        type: "secondary",
      },
      children: [],
-      parentKey: "actions",
    },
    portalBtn: {
-      key: "portalBtn",
      type: "Button",
      props: {
        label: "Billing Portal",
@@ -151,31 +136,23 @@ function createCustomerDetailSpec(
        type: "primary",
      },
      children: [],
-      parentKey: "actions",
    },
    details: {
-      key: "details",
      type: "PropertyList",
      props: { orientation: "horizontal" },
      children: ["detailStatus", "detailCreated", "detailBalance"],
-      parentKey: "root",
    },
    detailStatus: {
-      key: "detailStatus",
      type: "PropertyListItem",
      props: { label: "Status", value: customer?.status ?? "Unknown" },
      children: [],
-      parentKey: "details",
    },
    detailCreated: {
-      key: "detailCreated",
      type: "PropertyListItem",
      props: { label: "Created", value: customer?.created ?? "Unknown" },
      children: [],
-      parentKey: "details",
    },
    detailBalance: {
-      key: "detailBalance",
      type: "PropertyListItem",
      props: {
        label: "Balance",
@@ -184,42 +161,32 @@ function createCustomerDetailSpec(
          : "$0.00",
      },
      children: [],
-      parentKey: "details",
    },
    sections: {
-      key: "sections",
      type: "Accordion",
      props: {},
      children: ["paymentsSection", "subscriptionsSection", "invoicesSection"],
-      parentKey: "root",
    },

    // Payments Section
    paymentsSection: {
-      key: "paymentsSection",
      type: "AccordionItem",
      props: { title: `Payments (${payments?.total ?? 0})`, defaultOpen: true },
      children: paymentsList.length > 0 ? ["paymentsList"] : ["noPayments"],
-      parentKey: "sections",
    },
    paymentsList: {
-      key: "paymentsList",
      type: "Stack",
      props: { direction: "vertical", gap: "small" },
      children: paymentsList.slice(0, 5).map((_, i) => `payment${i}`),
-      parentKey: "paymentsSection",
    },
    noPayments: {
-      key: "noPayments",
      type: "Text",
      props: { content: "No payments found", color: "secondary" },
      children: [],
-      parentKey: "paymentsSection",
    },

    // Subscriptions Section
    subscriptionsSection: {
-      key: "subscriptionsSection",
      type: "AccordionItem",
      props: {
        title: `Subscriptions (${subscriptions?.total ?? 0})`,
@@ -229,54 +196,42 @@ function createCustomerDetailSpec(
        subscriptionsList.length > 0
          ? ["subscriptionsList"]
          : ["noSubscriptions"],
-      parentKey: "sections",
    },
    subscriptionsList: {
-      key: "subscriptionsList",
      type: "Stack",
      props: { direction: "vertical", gap: "small" },
      children: subscriptionsList.slice(0, 5).map((_, i) => `subscription${i}`),
-      parentKey: "subscriptionsSection",
    },
    noSubscriptions: {
-      key: "noSubscriptions",
      type: "Text",
      props: { content: "No subscriptions found", color: "secondary" },
      children: [],
-      parentKey: "subscriptionsSection",
    },

    // Invoices Section
    invoicesSection: {
-      key: "invoicesSection",
      type: "AccordionItem",
      props: {
        title: `Invoices (${invoices?.total ?? 0})`,
        defaultOpen: false,
      },
      children: invoicesList.length > 0 ? ["invoicesList"] : ["noInvoices"],
-      parentKey: "sections",
    },
    invoicesList: {
-      key: "invoicesList",
      type: "Stack",
      props: { direction: "vertical", gap: "small" },
      children: invoicesList.slice(0, 5).map((_, i) => `invoice${i}`),
-      parentKey: "invoicesSection",
    },
    noInvoices: {
-      key: "noInvoices",
      type: "Text",
      props: { content: "No invoices found", color: "secondary" },
      children: [],
-      parentKey: "invoicesSection",
    },
  };

  // Add payment cards
  paymentsList.slice(0, 5).forEach((p, i) => {
    elements[`payment${i}`] = {
-      key: `payment${i}`,
      type: "PaymentCard",
      props: {
        amount: 0,
@@ -286,14 +241,12 @@ function createCustomerDetailSpec(
        paymentId: p.id,
      },
      children: [],
-      parentKey: "paymentsList",
    };
  });

  // Add subscription cards
  subscriptionsList.slice(0, 5).forEach((s, i) => {
    elements[`subscription${i}`] = {
-      key: `subscription${i}`,
      type: "SubscriptionCard",
      props: {
        planName: s.planName,
@@ -304,14 +257,12 @@ function createCustomerDetailSpec(
        currentPeriodEnd: s.currentPeriodEnd,
      },
      children: [],
-      parentKey: "subscriptionsList",
    };
  });

  // Add invoice cards
  invoicesList.slice(0, 5).forEach((inv, i) => {
    elements[`invoice${i}`] = {
-      key: `invoice${i}`,
      type: "InvoiceCard",
      props: {
        invoiceNumber: inv.invoiceNumber,
@@ -321,7 +272,6 @@ function createCustomerDetailSpec(
        dueDate: inv.dueDate,
      },
      children: [],
-      parentKey: "invoicesList",
    };
  });

@@ -36,28 +36,21 @@ function createCustomersListSpec(data: Record<string, unknown>): Spec {

  const elements: Spec["elements"] = {
    root: {
-      key: "root",
      type: "Stack",
      props: { direction: "vertical", gap: "large" },
      children: ["heading", "stats", "actions", "list", "pagination"],
-      parentKey: null,
    },
    heading: {
-      key: "heading",
      type: "Heading",
      props: { text: "Customer Directory", size: "xlarge" },
      children: [],
-      parentKey: "root",
    },
    stats: {
-      key: "stats",
      type: "Stack",
      props: { direction: "horizontal", gap: "medium" },
      children: ["totalMetric"],
-      parentKey: "root",
    },
    totalMetric: {
-      key: "totalMetric",
      type: "Metric",
      props: {
        label: "Total Customers",
@@ -65,17 +58,13 @@ function createCustomersListSpec(data: Record<string, unknown>): Spec {
        changeType: "neutral",
      },
      children: [],
-      parentKey: "stats",
    },
    actions: {
-      key: "actions",
      type: "Stack",
      props: { direction: "horizontal", gap: "small" },
      children: ["refreshBtn", "exportBtn"],
-      parentKey: "root",
    },
    refreshBtn: {
-      key: "refreshBtn",
      type: "Button",
      props: {
        label: "Refresh",
@@ -83,10 +72,8 @@ function createCustomersListSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "actions",
    },
    exportBtn: {
-      key: "exportBtn",
      type: "Button",
      props: {
        label: "Export CSV",
@@ -95,24 +82,18 @@ function createCustomersListSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "actions",
    },
    list: {
-      key: "list",
      type: "Stack",
      props: { direction: "vertical", gap: "small" },
      children: customerList.slice(0, 10).map((_, i) => `customer${i}`),
-      parentKey: "root",
    },
    pagination: {
-      key: "pagination",
      type: "Stack",
      props: { direction: "horizontal", gap: "small" },
      children: customers?.hasMore ? ["loadMore"] : [],
-      parentKey: "root",
    },
    loadMore: {
-      key: "loadMore",
      type: "Button",
      props: {
        label: "Load More",
@@ -124,13 +105,11 @@ function createCustomersListSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "pagination",
    },
  };

  customerList.slice(0, 10).forEach((c, i) => {
    elements[`customer${i}`] = {
-      key: `customer${i}`,
      type: "CustomerCard",
      props: {
        name: c.name,
@@ -139,7 +118,6 @@ function createCustomersListSpec(data: Record<string, unknown>): Spec {
        customerId: c.id,
      },
      children: [],
-      parentKey: "list",
    };
  });

@@ -38,28 +38,21 @@ function createRevenueSpec(data: Record<string, unknown>): Spec {
    root: "root",
    elements: {
      root: {
-        key: "root",
        type: "Stack",
        props: { direction: "vertical", gap: "large" },
        children: ["heading", "metrics", "refresh"],
-        parentKey: null,
      },
      heading: {
-        key: "heading",
        type: "Heading",
        props: { text: "Revenue Dashboard", size: "xlarge" },
        children: [],
-        parentKey: "root",
      },
      metrics: {
-        key: "metrics",
        type: "Stack",
        props: { direction: "horizontal", gap: "medium" },
        children: ["m1", "m2", "m3"],
-        parentKey: "root",
      },
      m1: {
-        key: "m1",
        type: "Metric",
        props: {
          label: "Payment Volume",
@@ -70,10 +63,8 @@ function createRevenueSpec(data: Record<string, unknown>): Spec {
          changeType: "positive",
        },
        children: [],
-        parentKey: "metrics",
      },
      m2: {
-        key: "m2",
        type: "Metric",
        props: {
          label: "Active Subscriptions",
@@ -84,10 +75,8 @@ function createRevenueSpec(data: Record<string, unknown>): Spec {
          changeType: "positive",
        },
        children: [],
-        parentKey: "metrics",
      },
      m3: {
-        key: "m3",
        type: "Metric",
        props: {
          label: "Total Customers",
@@ -95,10 +84,8 @@ function createRevenueSpec(data: Record<string, unknown>): Spec {
          changeType: "neutral",
        },
        children: [],
-        parentKey: "metrics",
      },
      refresh: {
-        key: "refresh",
        type: "Button",
        props: {
          label: "Refresh Data",
@@ -106,7 +93,6 @@ function createRevenueSpec(data: Record<string, unknown>): Spec {
          type: "secondary",
        },
        children: [],
-        parentKey: "root",
      },
    },
  };
@@ -129,28 +115,21 @@ function createPaymentsSpec(data: Record<string, unknown>): Spec {

  const elements: Spec["elements"] = {
    root: {
-      key: "root",
      type: "Stack",
      props: { direction: "vertical", gap: "large" },
      children: ["heading", "stats", "payments", "refresh"],
-      parentKey: null,
    },
    heading: {
-      key: "heading",
      type: "Heading",
      props: { text: "Recent Payments", size: "xlarge" },
      children: [],
-      parentKey: "root",
    },
    stats: {
-      key: "stats",
      type: "Stack",
      props: { direction: "horizontal", gap: "medium" },
      children: ["s1", "s2"],
-      parentKey: "root",
    },
    s1: {
-      key: "s1",
      type: "Metric",
      props: {
        label: "Total Volume",
@@ -158,10 +137,8 @@ function createPaymentsSpec(data: Record<string, unknown>): Spec {
        changeType: "positive",
      },
      children: [],
-      parentKey: "stats",
    },
    s2: {
-      key: "s2",
      type: "Metric",
      props: {
        label: "Success Rate",
@@ -169,17 +146,13 @@ function createPaymentsSpec(data: Record<string, unknown>): Spec {
        changeType: "positive",
      },
      children: [],
-      parentKey: "stats",
    },
    payments: {
-      key: "payments",
      type: "Stack",
      props: { direction: "vertical", gap: "small" },
      children: paymentsList.slice(0, 5).map((_, i) => `p${i}`),
-      parentKey: "root",
    },
    refresh: {
-      key: "refresh",
      type: "Button",
      props: {
        label: "Refresh Payments",
@@ -187,13 +160,11 @@ function createPaymentsSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "root",
    },
  };

  paymentsList.slice(0, 5).forEach((p, i) => {
    elements[`p${i}`] = {
-      key: `p${i}`,
      type: "PaymentCard",
      props: {
        amount: 0, // We'll use formattedAmount in description
@@ -203,7 +174,6 @@ function createPaymentsSpec(data: Record<string, unknown>): Spec {
        paymentId: p.id,
      },
      children: [],
-      parentKey: "payments",
    };
  });

@@ -229,28 +199,21 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {

  const elements: Spec["elements"] = {
    root: {
-      key: "root",
      type: "Stack",
      props: { direction: "vertical", gap: "large" },
      children: ["heading", "metrics", "alert", "subs", "refresh"],
-      parentKey: null,
    },
    heading: {
-      key: "heading",
      type: "Heading",
      props: { text: "Subscriptions Overview", size: "xlarge" },
      children: [],
-      parentKey: "root",
    },
    metrics: {
-      key: "metrics",
      type: "Stack",
      props: { direction: "horizontal", gap: "medium" },
      children: ["m1", "m2", "m3"],
-      parentKey: "root",
    },
    m1: {
-      key: "m1",
      type: "Metric",
      props: {
        label: "Active",
@@ -258,10 +221,8 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        changeType: "positive",
      },
      children: [],
-      parentKey: "metrics",
    },
    m2: {
-      key: "m2",
      type: "Metric",
      props: {
        label: "Trialing",
@@ -269,10 +230,8 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        changeType: "positive",
      },
      children: [],
-      parentKey: "metrics",
    },
    m3: {
-      key: "m3",
      type: "Metric",
      props: {
        label: "Past Due",
@@ -280,27 +239,21 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        changeType: subscriptions?.pastDue ? "negative" : "neutral",
      },
      children: [],
-      parentKey: "metrics",
    },
    alert: {
-      key: "alert",
      type: "Banner",
      props: {
        title: `${subscriptions?.trialing ?? 0} subscriptions currently trialing`,
        type: "default",
      },
      children: [],
-      parentKey: "root",
    },
    subs: {
-      key: "subs",
      type: "Stack",
      props: { direction: "vertical", gap: "small" },
      children: subsList.slice(0, 5).map((_, i) => `sub${i}`),
-      parentKey: "root",
    },
    refresh: {
-      key: "refresh",
      type: "Button",
      props: {
        label: "Refresh Subscriptions",
@@ -308,13 +261,11 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "root",
    },
  };

  subsList.slice(0, 5).forEach((s, i) => {
    elements[`sub${i}`] = {
-      key: `sub${i}`,
      type: "SubscriptionCard",
      props: {
        planName: s.planName,
@@ -323,7 +274,6 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        interval: (s.interval as "month" | "year") ?? "month",
      },
      children: [],
-      parentKey: "subs",
    };
  });

@@ -346,28 +296,21 @@ function createCustomersSpec(data: Record<string, unknown>): Spec {

  const elements: Spec["elements"] = {
    root: {
-      key: "root",
      type: "Stack",
      props: { direction: "vertical", gap: "large" },
      children: ["heading", "stats", "customers", "refresh"],
-      parentKey: null,
    },
    heading: {
-      key: "heading",
      type: "Heading",
      props: { text: "Customer Directory", size: "xlarge" },
      children: [],
-      parentKey: "root",
    },
    stats: {
-      key: "stats",
      type: "Stack",
      props: { direction: "horizontal", gap: "medium" },
      children: ["s1"],
-      parentKey: "root",
    },
    s1: {
-      key: "s1",
      type: "Metric",
      props: {
        label: "Total Customers",
@@ -375,17 +318,13 @@ function createCustomersSpec(data: Record<string, unknown>): Spec {
        changeType: "neutral",
      },
      children: [],
-      parentKey: "stats",
    },
    customers: {
-      key: "customers",
      type: "Stack",
      props: { direction: "vertical", gap: "small" },
      children: customersList.slice(0, 5).map((_, i) => `c${i}`),
-      parentKey: "root",
    },
    refresh: {
-      key: "refresh",
      type: "Button",
      props: {
        label: "Refresh Customers",
@@ -393,13 +332,11 @@ function createCustomersSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "root",
    },
  };

  customersList.slice(0, 5).forEach((c, i) => {
    elements[`c${i}`] = {
-      key: `c${i}`,
      type: "CustomerCard",
      props: {
        name: c.name,
@@ -408,7 +345,6 @@ function createCustomersSpec(data: Record<string, unknown>): Spec {
        customerId: c.id,
      },
      children: [],
-      parentKey: "customers",
    };
  });

@@ -434,28 +370,21 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {

  const elements: Spec["elements"] = {
    root: {
-      key: "root",
      type: "Stack",
      props: { direction: "vertical", gap: "large" },
      children: ["heading", "stats", "invoices", "refresh"],
-      parentKey: null,
    },
    heading: {
-      key: "heading",
      type: "Heading",
      props: { text: "Invoice Management", size: "xlarge" },
      children: [],
-      parentKey: "root",
    },
    stats: {
-      key: "stats",
      type: "Stack",
      props: { direction: "horizontal", gap: "medium" },
      children: ["s1", "s2", "s3"],
-      parentKey: "root",
    },
    s1: {
-      key: "s1",
      type: "Metric",
      props: {
        label: "Outstanding",
@@ -463,10 +392,8 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {
        changeType: "neutral",
      },
      children: [],
-      parentKey: "stats",
    },
    s2: {
-      key: "s2",
      type: "Metric",
      props: {
        label: "Paid",
@@ -474,10 +401,8 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {
        changeType: "positive",
      },
      children: [],
-      parentKey: "stats",
    },
    s3: {
-      key: "s3",
      type: "Metric",
      props: {
        label: "Overdue",
@@ -485,17 +410,13 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {
        changeType: invoices?.overdue !== "$0.00" ? "negative" : "neutral",
      },
      children: [],
-      parentKey: "stats",
    },
    invoices: {
-      key: "invoices",
      type: "Stack",
      props: { direction: "vertical", gap: "small" },
      children: invoicesList.slice(0, 5).map((_, i) => `inv${i}`),
-      parentKey: "root",
    },
    refresh: {
-      key: "refresh",
      type: "Button",
      props: {
        label: "Refresh Invoices",
@@ -503,13 +424,11 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "root",
    },
  };

  invoicesList.slice(0, 5).forEach((inv, i) => {
    elements[`inv${i}`] = {
-      key: `inv${i}`,
      type: "InvoiceCard",
      props: {
        invoiceNumber: inv.invoiceNumber,
@@ -518,7 +437,6 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {
        dueDate: inv.dueDate,
      },
      children: [],
-      parentKey: "invoices",
    };
  });

@@ -41,7 +41,6 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {

  const elements: Spec["elements"] = {
    root: {
-      key: "root",
      type: "Stack",
      props: { direction: "vertical", gap: "large" },
      children: [
@@ -52,24 +51,18 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {
        "list",
        "pagination",
      ],
-      parentKey: null,
    },
    heading: {
-      key: "heading",
      type: "Heading",
      props: { text: "Invoices", size: "xlarge" },
      children: [],
-      parentKey: "root",
    },
    metrics: {
-      key: "metrics",
      type: "Stack",
      props: { direction: "horizontal", gap: "medium" },
      children: ["outstandingMetric", "paidMetric", "overdueMetric"],
-      parentKey: "root",
    },
    outstandingMetric: {
-      key: "outstandingMetric",
      type: "Metric",
      props: {
        label: "Outstanding",
@@ -77,10 +70,8 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {
        changeType: "neutral",
      },
      children: [],
-      parentKey: "metrics",
    },
    paidMetric: {
-      key: "paidMetric",
      type: "Metric",
      props: {
        label: "Paid",
@@ -88,10 +79,8 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {
        changeType: "positive",
      },
      children: [],
-      parentKey: "metrics",
    },
    overdueMetric: {
-      key: "overdueMetric",
      type: "Metric",
      props: {
        label: "Overdue",
@@ -99,10 +88,8 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {
        changeType: invoices?.overdue !== "$0.00" ? "negative" : "neutral",
      },
      children: [],
-      parentKey: "metrics",
    },
    alert: {
-      key: "alert",
      type: "Banner",
      props: {
        title:
@@ -112,24 +99,18 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {
        type: invoices?.overdue !== "$0.00" ? "caution" : "default",
      },
      children: [],
-      parentKey: "root",
    },
    filters: {
-      key: "filters",
      type: "Stack",
      props: { direction: "horizontal", gap: "small" },
      children: ["refreshBtn", "createBtn", "exportBtn"],
-      parentKey: "root",
    },
    refreshBtn: {
-      key: "refreshBtn",
      type: "Button",
      props: { label: "Refresh", action: "refreshInvoices", type: "secondary" },
      children: [],
-      parentKey: "filters",
    },
    createBtn: {
-      key: "createBtn",
      type: "Button",
      props: {
        label: "Create Invoice",
@@ -138,10 +119,8 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {
        type: "primary",
      },
      children: [],
-      parentKey: "filters",
    },
    exportBtn: {
-      key: "exportBtn",
      type: "Button",
      props: {
        label: "Export CSV",
@@ -150,24 +129,18 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "filters",
    },
    list: {
-      key: "list",
      type: "Stack",
      props: { direction: "vertical", gap: "small" },
      children: invoicesList.slice(0, 10).map((_, i) => `invoice${i}`),
-      parentKey: "root",
    },
    pagination: {
-      key: "pagination",
      type: "Stack",
      props: { direction: "horizontal", gap: "small" },
      children: invoices?.hasMore ? ["loadMore"] : [],
-      parentKey: "root",
    },
    loadMore: {
-      key: "loadMore",
      type: "Button",
      props: {
        label: "Load More",
@@ -176,13 +149,11 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "pagination",
    },
  };

  invoicesList.slice(0, 10).forEach((inv, i) => {
    elements[`invoice${i}`] = {
-      key: `invoice${i}`,
      type: "InvoiceCard",
      props: {
        invoiceNumber: inv.invoiceNumber,
@@ -198,7 +169,6 @@ function createInvoicesSpec(data: Record<string, unknown>): Spec {
        customerEmail: inv.customerEmail,
      },
      children: [],
-      parentKey: "list",
    };
  });

@@ -56,14 +56,11 @@ function createPaymentDetailSpec(

  const elements: Spec["elements"] = {
    root: {
-      key: "root",
      type: "Stack",
      props: { direction: "vertical", gap: "large" },
      children: ["header", "details", "actions", "refundsSection"],
-      parentKey: null,
    },
    header: {
-      key: "header",
      type: "Stack",
      props: {
        direction: "horizontal",
@@ -71,31 +68,23 @@ function createPaymentDetailSpec(
        distribute: "space-between",
      },
      children: ["paymentInfo", "statusBadge"],
-      parentKey: "root",
    },
    paymentInfo: {
-      key: "paymentInfo",
      type: "Stack",
      props: { direction: "vertical", gap: "xsmall" },
      children: ["paymentAmount", "paymentId"],
-      parentKey: "header",
    },
    paymentAmount: {
-      key: "paymentAmount",
      type: "Heading",
      props: { text: payment?.formattedAmount ?? "$0.00", size: "xlarge" },
      children: [],
-      parentKey: "paymentInfo",
    },
    paymentId: {
-      key: "paymentId",
      type: "Text",
      props: { content: paymentId, color: "secondary", size: "small" },
      children: [],
-      parentKey: "paymentInfo",
    },
    statusBadge: {
-      key: "statusBadge",
      type: "Badge",
      props: {
        label: payment?.status ?? "unknown",
@@ -107,10 +96,8 @@ function createPaymentDetailSpec(
              : "negative",
      },
      children: [],
-      parentKey: "header",
    },
    details: {
-      key: "details",
      type: "PropertyList",
      props: { orientation: "vertical" },
      children: [
@@ -119,54 +106,42 @@ function createPaymentDetailSpec(
        "detailCurrency",
        "detailCustomer",
      ],
-      parentKey: "root",
    },
    detailDescription: {
-      key: "detailDescription",
      type: "PropertyListItem",
      props: {
        label: "Description",
        value: payment?.description ?? "No description",
      },
      children: [],
-      parentKey: "details",
    },
    detailCreated: {
-      key: "detailCreated",
      type: "PropertyListItem",
      props: { label: "Created", value: payment?.created ?? "Unknown" },
      children: [],
-      parentKey: "details",
    },
    detailCurrency: {
-      key: "detailCurrency",
      type: "PropertyListItem",
      props: {
        label: "Currency",
        value: (payment?.currency ?? "usd").toUpperCase(),
      },
      children: [],
-      parentKey: "details",
    },
    detailCustomer: {
-      key: "detailCustomer",
      type: "PropertyListItem",
      props: { label: "Customer", value: payment?.customerId ?? "Guest" },
      children: [],
-      parentKey: "details",
    },
    actions: {
-      key: "actions",
      type: "Stack",
      props: { direction: "horizontal", gap: "small" },
      children:
        payment?.status === "succeeded"
          ? ["refundBtn", "viewBtn"]
          : ["viewBtn"],
-      parentKey: "root",
    },
    refundBtn: {
-      key: "refundBtn",
      type: "Button",
      props: {
        label: "Refund Payment",
@@ -175,10 +150,8 @@ function createPaymentDetailSpec(
        type: "destructive",
      },
      children: [],
-      parentKey: "actions",
    },
    viewBtn: {
-      key: "viewBtn",
      type: "Button",
      props: {
        label: "View in Dashboard",
@@ -187,44 +160,34 @@ function createPaymentDetailSpec(
        type: "secondary",
      },
      children: [],
-      parentKey: "actions",
    },
    refundsSection: {
-      key: "refundsSection",
      type: "Accordion",
      props: {},
      children: ["refundsAccordion"],
-      parentKey: "root",
    },
    refundsAccordion: {
-      key: "refundsAccordion",
      type: "AccordionItem",
      props: {
        title: `Refunds (${refunds?.total ?? 0})`,
        defaultOpen: refundsList.length > 0,
      },
      children: refundsList.length > 0 ? ["refundsList"] : ["noRefunds"],
-      parentKey: "refundsSection",
    },
    refundsList: {
-      key: "refundsList",
      type: "Stack",
      props: { direction: "vertical", gap: "small" },
      children: refundsList.slice(0, 5).map((_, i) => `refund${i}`),
-      parentKey: "refundsAccordion",
    },
    noRefunds: {
-      key: "noRefunds",
      type: "Text",
      props: { content: "No refunds", color: "secondary" },
      children: [],
-      parentKey: "refundsAccordion",
    },
  };

  refundsList.slice(0, 5).forEach((r, i) => {
    elements[`refund${i}`] = {
-      key: `refund${i}`,
      type: "RefundCard",
      props: {
        amount: r.amount,
@@ -233,7 +196,6 @@ function createPaymentDetailSpec(
        reason: r.reason,
      },
      children: [],
-      parentKey: "refundsList",
    };
  });

@@ -38,28 +38,21 @@ function createPaymentsSpec(data: Record<string, unknown>): Spec {

  const elements: Spec["elements"] = {
    root: {
-      key: "root",
      type: "Stack",
      props: { direction: "vertical", gap: "large" },
      children: ["heading", "metrics", "filters", "list", "pagination"],
-      parentKey: null,
    },
    heading: {
-      key: "heading",
      type: "Heading",
      props: { text: "Payments", size: "xlarge" },
      children: [],
-      parentKey: "root",
    },
    metrics: {
-      key: "metrics",
      type: "Stack",
      props: { direction: "horizontal", gap: "medium" },
      children: ["volumeMetric", "rateMetric", "countMetric"],
-      parentKey: "root",
    },
    volumeMetric: {
-      key: "volumeMetric",
      type: "Metric",
      props: {
        label: "Total Volume",
@@ -67,10 +60,8 @@ function createPaymentsSpec(data: Record<string, unknown>): Spec {
        changeType: "positive",
      },
      children: [],
-      parentKey: "metrics",
    },
    rateMetric: {
-      key: "rateMetric",
      type: "Metric",
      props: {
        label: "Success Rate",
@@ -78,10 +69,8 @@ function createPaymentsSpec(data: Record<string, unknown>): Spec {
        changeType: "positive",
      },
      children: [],
-      parentKey: "metrics",
    },
    countMetric: {
-      key: "countMetric",
      type: "Metric",
      props: {
        label: "Total Payments",
@@ -89,24 +78,18 @@ function createPaymentsSpec(data: Record<string, unknown>): Spec {
        changeType: "neutral",
      },
      children: [],
-      parentKey: "metrics",
    },
    filters: {
-      key: "filters",
      type: "Stack",
      props: { direction: "horizontal", gap: "small" },
      children: ["refreshBtn", "exportBtn"],
-      parentKey: "root",
    },
    refreshBtn: {
-      key: "refreshBtn",
      type: "Button",
      props: { label: "Refresh", action: "refreshPayments", type: "secondary" },
      children: [],
-      parentKey: "filters",
    },
    exportBtn: {
-      key: "exportBtn",
      type: "Button",
      props: {
        label: "Export CSV",
@@ -115,24 +98,18 @@ function createPaymentsSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "filters",
    },
    list: {
-      key: "list",
      type: "Stack",
      props: { direction: "vertical", gap: "small" },
      children: paymentsList.slice(0, 10).map((_, i) => `payment${i}`),
-      parentKey: "root",
    },
    pagination: {
-      key: "pagination",
      type: "Stack",
      props: { direction: "horizontal", gap: "small" },
      children: payments?.hasMore ? ["loadMore"] : [],
-      parentKey: "root",
    },
    loadMore: {
-      key: "loadMore",
      type: "Button",
      props: {
        label: "Load More",
@@ -144,13 +121,11 @@ function createPaymentsSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "pagination",
    },
  };

  paymentsList.slice(0, 10).forEach((p, i) => {
    elements[`payment${i}`] = {
-      key: `payment${i}`,
      type: "PaymentCard",
      props: {
        amount: 0,
@@ -160,7 +135,6 @@ function createPaymentsSpec(data: Record<string, unknown>): Spec {
        paymentId: p.id,
      },
      children: [],
-      parentKey: "list",
    };
  });

@@ -49,28 +49,21 @@ function createProductsSpec(data: Record<string, unknown>): Spec {

  const elements: Spec["elements"] = {
    root: {
-      key: "root",
      type: "Stack",
      props: { direction: "vertical", gap: "large" },
      children: ["heading", "metrics", "filters", "list", "pagination"],
-      parentKey: null,
    },
    heading: {
-      key: "heading",
      type: "Heading",
      props: { text: "Products & Prices", size: "xlarge" },
      children: [],
-      parentKey: "root",
    },
    metrics: {
-      key: "metrics",
      type: "Stack",
      props: { direction: "horizontal", gap: "medium" },
      children: ["productsMetric", "pricesMetric", "activeMetric"],
-      parentKey: "root",
    },
    productsMetric: {
-      key: "productsMetric",
      type: "Metric",
      props: {
        label: "Total Products",
@@ -78,10 +71,8 @@ function createProductsSpec(data: Record<string, unknown>): Spec {
        changeType: "neutral",
      },
      children: [],
-      parentKey: "metrics",
    },
    pricesMetric: {
-      key: "pricesMetric",
      type: "Metric",
      props: {
        label: "Total Prices",
@@ -89,10 +80,8 @@ function createProductsSpec(data: Record<string, unknown>): Spec {
        changeType: "neutral",
      },
      children: [],
-      parentKey: "metrics",
    },
    activeMetric: {
-      key: "activeMetric",
      type: "Metric",
      props: {
        label: "Active Products",
@@ -100,24 +89,18 @@ function createProductsSpec(data: Record<string, unknown>): Spec {
        changeType: "positive",
      },
      children: [],
-      parentKey: "metrics",
    },
    filters: {
-      key: "filters",
      type: "Stack",
      props: { direction: "horizontal", gap: "small" },
      children: ["refreshBtn", "createBtn"],
-      parentKey: "root",
    },
    refreshBtn: {
-      key: "refreshBtn",
      type: "Button",
      props: { label: "Refresh", action: "fetchProducts", type: "secondary" },
      children: [],
-      parentKey: "filters",
    },
    createBtn: {
-      key: "createBtn",
      type: "Button",
      props: {
        label: "Create Product",
@@ -126,24 +109,18 @@ function createProductsSpec(data: Record<string, unknown>): Spec {
        type: "primary",
      },
      children: [],
-      parentKey: "filters",
    },
    list: {
-      key: "list",
      type: "Stack",
      props: { direction: "vertical", gap: "small" },
      children: productsList.slice(0, 10).map((_, i) => `product${i}`),
-      parentKey: "root",
    },
    pagination: {
-      key: "pagination",
      type: "Stack",
      props: { direction: "horizontal", gap: "small" },
      children: products?.hasMore ? ["loadMore"] : [],
-      parentKey: "root",
    },
    loadMore: {
-      key: "loadMore",
      type: "Button",
      props: {
        label: "Load More",
@@ -152,7 +129,6 @@ function createProductsSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "pagination",
    },
  };

@@ -169,15 +145,12 @@ function createProductsSpec(data: Record<string, unknown>): Spec {
        : "No prices";

    elements[`product${i}`] = {
-      key: `product${i}`,
      type: "Stack",
      props: { direction: "vertical", gap: "small" },
      children: [`productCard${i}`],
-      parentKey: "list",
    };

    elements[`productCard${i}`] = {
-      key: `productCard${i}`,
      type: "PropertyList",
      props: { orientation: "vertical" },
      children: [
@@ -186,39 +159,30 @@ function createProductsSpec(data: Record<string, unknown>): Spec {
        `productPrice${i}`,
        `productStatus${i}`,
      ],
-      parentKey: `product${i}`,
    };

    elements[`productName${i}`] = {
-      key: `productName${i}`,
      type: "PropertyListItem",
      props: { label: "Name", value: p.name },
      children: [],
-      parentKey: `productCard${i}`,
    };

    elements[`productDesc${i}`] = {
-      key: `productDesc${i}`,
      type: "PropertyListItem",
      props: { label: "Description", value: p.description || "No description" },
      children: [],
-      parentKey: `productCard${i}`,
    };

    elements[`productPrice${i}`] = {
-      key: `productPrice${i}`,
      type: "PropertyListItem",
      props: { label: "Prices", value: priceDisplay },
      children: [],
-      parentKey: `productCard${i}`,
    };

    elements[`productStatus${i}`] = {
-      key: `productStatus${i}`,
      type: "PropertyListItem",
      props: { label: "Status", value: p.active ? "Active" : "Archived" },
      children: [],
-      parentKey: `productCard${i}`,
    };
  });

@@ -42,7 +42,6 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {

  const elements: Spec["elements"] = {
    root: {
-      key: "root",
      type: "Stack",
      props: { direction: "vertical", gap: "large" },
      children: [
@@ -53,17 +52,13 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        "list",
        "pagination",
      ],
-      parentKey: null,
    },
    heading: {
-      key: "heading",
      type: "Heading",
      props: { text: "Subscriptions", size: "xlarge" },
      children: [],
-      parentKey: "root",
    },
    metrics: {
-      key: "metrics",
      type: "Stack",
      props: { direction: "horizontal", gap: "medium" },
      children: [
@@ -72,10 +67,8 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        "pastDueMetric",
        "canceledMetric",
      ],
-      parentKey: "root",
    },
    activeMetric: {
-      key: "activeMetric",
      type: "Metric",
      props: {
        label: "Active",
@@ -83,10 +76,8 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        changeType: "positive",
      },
      children: [],
-      parentKey: "metrics",
    },
    trialingMetric: {
-      key: "trialingMetric",
      type: "Metric",
      props: {
        label: "Trialing",
@@ -94,10 +85,8 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        changeType: "positive",
      },
      children: [],
-      parentKey: "metrics",
    },
    pastDueMetric: {
-      key: "pastDueMetric",
      type: "Metric",
      props: {
        label: "Past Due",
@@ -105,10 +94,8 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        changeType: subscriptions?.pastDue ? "negative" : "neutral",
      },
      children: [],
-      parentKey: "metrics",
    },
    canceledMetric: {
-      key: "canceledMetric",
      type: "Metric",
      props: {
        label: "Canceled",
@@ -116,10 +103,8 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        changeType: "neutral",
      },
      children: [],
-      parentKey: "metrics",
    },
    alert: {
-      key: "alert",
      type: "Banner",
      props: {
        title: subscriptions?.pastDue
@@ -128,17 +113,13 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        type: subscriptions?.pastDue ? "caution" : "default",
      },
      children: [],
-      parentKey: "root",
    },
    filters: {
-      key: "filters",
      type: "Stack",
      props: { direction: "horizontal", gap: "small" },
      children: ["refreshBtn", "exportBtn"],
-      parentKey: "root",
    },
    refreshBtn: {
-      key: "refreshBtn",
      type: "Button",
      props: {
        label: "Refresh",
@@ -146,10 +127,8 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "filters",
    },
    exportBtn: {
-      key: "exportBtn",
      type: "Button",
      props: {
        label: "Export CSV",
@@ -158,26 +137,20 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "filters",
    },
    list: {
-      key: "list",
      type: "Stack",
      props: { direction: "vertical", gap: "small" },
      children: subscriptionsList
        .slice(0, 10)
        .map((_, i) => `subscription${i}`),
-      parentKey: "root",
    },
    pagination: {
-      key: "pagination",
      type: "Stack",
      props: { direction: "horizontal", gap: "small" },
      children: subscriptions?.hasMore ? ["loadMore"] : [],
-      parentKey: "root",
    },
    loadMore: {
-      key: "loadMore",
      type: "Button",
      props: {
        label: "Load More",
@@ -186,13 +159,11 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        type: "secondary",
      },
      children: [],
-      parentKey: "pagination",
    },
  };

  subscriptionsList.slice(0, 10).forEach((s, i) => {
    elements[`subscription${i}`] = {
-      key: `subscription${i}`,
      type: "SubscriptionCard",
      props: {
        planName: s.planName,
@@ -208,7 +179,6 @@ function createSubscriptionsSpec(data: Record<string, unknown>): Spec {
        currentPeriodEnd: s.currentPeriodEnd,
      },
      children: [],
-      parentKey: "list",
    };
  });

@@ -1,5 +1,13 @@
 # @json-render/codegen

+## 0.4.4
+
+### Patch Changes
+
+- dd17549: remove key/parentKey from flat specs, RFC 6902 compliance for SpecStream
+- Updated dependencies [dd17549]
+  - @json-render/core@0.4.4
+
 ## 0.4.3

 ### Patch Changes
@@ -1,6 +1,6 @@
 {
  "name": "@json-render/codegen",
-  "version": "0.4.3",
+  "version": "0.4.4",
  "license": "Apache-2.0",
  "description": "Utilities for generating code from json-render UI trees",
  "keywords": [
@@ -13,18 +13,15 @@ describe("traverseSpec", () => {
      root: "root",
      elements: {
        root: {
-          key: "root",
          type: "Card",
          props: {},
          children: ["child1", "child2"],
        },
        child1: {
-          key: "child1",
          type: "Text",
          props: {},
        },
        child2: {
-          key: "child2",
          type: "Button",
          props: {},
        },
@@ -32,8 +29,8 @@ describe("traverseSpec", () => {
    };

    const visited: string[] = [];
-    traverseSpec(spec, (element) => {
-      visited.push(element.key);
+    traverseSpec(spec, (_element, key) => {
+      visited.push(key);
    });

    expect(visited).toEqual(["root", "child1", "child2"]);
@@ -41,8 +38,8 @@ describe("traverseSpec", () => {

  it("handles empty spec", () => {
    const visited: string[] = [];
-    traverseSpec(null as unknown as Spec, (element) => {
-      visited.push(element.key);
+    traverseSpec(null as unknown as Spec, (_element, key) => {
+      visited.push(key);
    });
    expect(visited).toEqual([]);
  });
@@ -54,18 +51,15 @@ describe("collectUsedComponents", () => {
      root: "root",
      elements: {
        root: {
-          key: "root",
          type: "Card",
          props: {},
          children: ["child1", "child2"],
        },
        child1: {
-          key: "child1",
          type: "Text",
          props: {},
        },
        child2: {
-          key: "child2",
          type: "Text",
          props: {},
        },
@@ -83,7 +77,6 @@ describe("collectDataPaths", () => {
      root: "root",
      elements: {
        root: {
-          key: "root",
          type: "Metric",
          props: { valuePath: "analytics/revenue" },
        },
@@ -99,7 +92,6 @@ describe("collectDataPaths", () => {
      root: "root",
      elements: {
        root: {
-          key: "root",
          type: "Text",
          props: { content: { path: "user/name" } },
        },
@@ -117,7 +109,6 @@ describe("collectActions", () => {
      root: "root",
      elements: {
        root: {
-          key: "root",
          type: "Button",
          props: { action: "submit_form" },
        },
@@ -4,7 +4,12 @@ import type { Spec, UIElement } from "@json-render/core";
 * Visitor function for spec traversal
 */
 export interface TreeVisitor {
-  (element: UIElement, depth: number, parent: UIElement | null): void;
+  (
+    element: UIElement,
+    key: string,
+    depth: number,
+    parent: UIElement | null,
+  ): void;
 }

 /**
@@ -25,7 +30,7 @@ export function traverseSpec(
    const element = spec.elements[key];
    if (!element) return;

-    visitor(element, depth, parent);
+    visitor(element, key, depth, parent);

    if (element.children) {
      for (const childKey of element.children) {
@@ -43,7 +48,7 @@ export function traverseSpec(
 export function collectUsedComponents(spec: Spec): Set<string> {
  const components = new Set<string>();

-  traverseSpec(spec, (element) => {
+  traverseSpec(spec, (element, _key) => {
    components.add(element.type);
  });

@@ -56,7 +61,7 @@ export function collectUsedComponents(spec: Spec): Set<string> {
 export function collectDataPaths(spec: Spec): Set<string> {
  const paths = new Set<string>();

-  traverseSpec(spec, (element) => {
+  traverseSpec(spec, (element, _key) => {
    // Check props for data paths
    for (const [propName, propValue] of Object.entries(element.props)) {
      // Check for path props (e.g., valuePath, dataPath, bindPath)
@@ -141,7 +146,7 @@ function collectPathsFromCondition(
 export function collectActions(spec: Spec): Set<string> {
  const actions = new Set<string>();

-  traverseSpec(spec, (element) => {
+  traverseSpec(spec, (element, _key) => {
    for (const propValue of Object.values(element.props)) {
      // Check for action prop (string action name)
      if (typeof propValue === "string" && propValue.startsWith("action:")) {
@@ -1,5 +1,11 @@
 # @json-render/core

+## 0.4.4
+
+### Patch Changes
+
+- dd17549: remove key/parentKey from flat specs, RFC 6902 compliance for SpecStream
+
 ## 0.4.3

 ### Patch Changes
@@ -116,14 +116,16 @@ while (streaming) {
 const finalSpec = compiler.getResult();
 ```

-SpecStream format (each line is a JSON patch):
+SpecStream format uses [RFC 6902 JSON Patch](https://datatracker.ietf.org/doc/html/rfc6902) operations (each line is a patch):

 ```jsonl
-{"op":"set","path":"/root/type","value":"Card"}
-{"op":"set","path":"/root/props","value":{"title":"Hello"}}
-{"op":"set","path":"/root/children/0","value":{"type":"Button","props":{"label":"Click"}}}
+{"op":"add","path":"/root/type","value":"Card"}
+{"op":"add","path":"/root/props","value":{"title":"Hello"}}
+{"op":"add","path":"/root/children/0","value":{"type":"Button","props":{"label":"Click"}}}
 ```

+All six RFC 6902 operations are supported: `add`, `remove`, `replace`, `move`, `copy`, `test`.
+
 ### Low-Level Utilities

 ```typescript
@@ -134,8 +136,8 @@ import {
 } from "@json-render/core";

 // Parse a single line
-const patch = parseSpecStreamLine('{"op":"set","path":"/root","value":{}}');
-// { op: "set", path: "/root", value: {} }
+const patch = parseSpecStreamLine('{"op":"add","path":"/root","value":{}}');
+// { op: "add", path: "/root", value: {} }

 // Apply a patch to an object
 const obj = {};
@@ -1,6 +1,6 @@
 {
  "name": "@json-render/core",
-  "version": "0.4.3",
+  "version": "0.4.4",
  "license": "Apache-2.0",
  "description": "JSON becomes real things. Define your catalog, register your components, let AI generate.",
  "keywords": [
@@ -72,12 +72,10 @@ describe("createCatalog", () => {
    });

    const validElement = {
-      key: "1",
      type: "text",
      props: { content: "Hello" },
    };
    const invalidElement = {
-      key: "1",
      type: "text",
      props: { content: 123 },
    };
@@ -96,7 +94,7 @@ describe("createCatalog", () => {
    const validSpec = {
      root: "1",
      elements: {
-        "1": { key: "1", type: "text", props: { content: "Hello" } },
+        "1": { type: "text", props: { content: "Hello" } },
      },
    };

@@ -120,16 +118,13 @@ describe("createCatalog", () => {
      root: "card-1",
      elements: {
        "card-1": {
-          key: "card-1",
          type: "card",
          props: { title: "Hello" },
          children: ["text-1"],
        },
        "text-1": {
-          key: "text-1",
          type: "text",
          props: { content: "World" },
-          parentKey: "card-1",
        },
      },
    };
@@ -147,7 +142,7 @@ describe("createCatalog", () => {
    const invalidSpec = {
      root: "1",
      elements: {
-        "1": { key: "1", type: "nonexistent", props: { content: "Hello" } },
+        "1": { type: "nonexistent", props: { content: "Hello" } },
      },
    };

@@ -398,7 +393,6 @@ describe("defineCatalog (new schema API)", () => {
      root: s.string(),
      elements: s.record(
        s.object({
-          key: s.string(),
          type: s.ref("catalog.components"),
          props: s.any(),
          children: s.array(s.string()),
@@ -489,7 +483,6 @@ describe("defineCatalog (new schema API)", () => {
      root: "text-1",
      elements: {
        "text-1": {
-          key: "text-1",
          type: "Text",
          props: { content: "Hello" },
          children: [],
@@ -558,7 +551,6 @@ describe("defineCatalog (new schema API)", () => {
      root: "text-1",
      elements: {
        "text-1": {
-          key: "text-1",
          type: "Text",
          props: { content: "Hello" },
          children: [],
@@ -143,11 +143,9 @@ export function createCatalog<
    const def = components[componentName]!;

    return z.object({
-      key: z.string(),
      type: z.literal(componentName as string),
      props: def.props,
      children: z.array(z.string()).optional(),
-      parentKey: z.string().nullable().optional(),
      visible: VisibilityConditionSchema.optional(),
    });
  });
@@ -157,11 +155,9 @@ export function createCatalog<

  if (componentSchemas.length === 0) {
    elementSchema = z.object({
-      key: z.string(),
      type: z.string(),
      props: z.record(z.string(), z.unknown()),
      children: z.array(z.string()).optional(),
-      parentKey: z.string().nullable().optional(),
      visible: VisibilityConditionSchema.optional(),
    }) as unknown as z.ZodType<UIElement>;
  } else if (componentSchemas.length === 1) {
@@ -497,10 +493,10 @@ export function generateSystemPrompt<
  }

  // Output format
-  lines.push("OUTPUT FORMAT (JSONL):");
-  lines.push('{"op":"set","path":"/root","value":"element-key"}');
+  lines.push("OUTPUT FORMAT (JSONL, RFC 6902 JSON Patch):");
+  lines.push('{"op":"add","path":"/root","value":"element-key"}');
  lines.push(
-    '{"op":"add","path":"/elements/key","value":{"key":"...","type":"...","props":{...},"children":[...]}}',
+    '{"op":"add","path":"/elements/key","value":{"type":"...","props":{...},"children":[...]}}',
  );
  lines.push('{"op":"remove","path":"/elements/key"}');
  lines.push("");
@@ -508,12 +504,12 @@ export function generateSystemPrompt<
  // Rules
  lines.push("RULES:");
  const baseRules = [
-    "First line sets /root to root element key",
-    "Add elements with /elements/{key}",
+    'First line sets /root to root element key: {"op":"add","path":"/root","value":"<key>"}',
+    'Add elements with /elements/{key}: {"op":"add","path":"/elements/<key>","value":{...}}',
    "Remove elements with op:remove - also update the parent's children array to exclude the removed key",
    "Children array contains string keys, not objects",
    "Parent first, then children",
-    "Each element needs: key, type, props",
+    "Each element needs: type, props",
    "ONLY use props listed above - never invent new props",
  ];
  const allRules = [...baseRules, ...customRules];
@@ -5,6 +5,7 @@ export type {
  DynamicNumber,
  DynamicBoolean,
  UIElement,
+  FlatElement,
  Spec,
  VisibilityCondition,
  LogicExpression,
@@ -27,8 +28,10 @@ export {
  resolveDynamicValue,
  getByPath,
  setByPath,
+  addByPath,
+  removeByPath,
  findFormValue,
-  // SpecStream - streaming format for building specs
+  // SpecStream - streaming format for building specs (RFC 6902)
  parseSpecStreamLine,
  applySpecStreamPatch,
  compileSpecStream,
@@ -545,10 +545,10 @@ function generatePrompt<TDef extends SchemaDefinition, TCatalog>(
  lines.push("");
  lines.push("Example output (each line is a separate JSON object):");
  lines.push("");
-  lines.push(`{"op":"set","path":"/root","value":"card-1"}
-{"op":"set","path":"/elements/card-1","value":{"key":"card-1","type":"Card","props":{"title":"Dashboard"},"children":["metric-1","chart-1"],"parentKey":""}}
-{"op":"set","path":"/elements/metric-1","value":{"key":"metric-1","type":"Metric","props":{"label":"Revenue","valuePath":"analytics.revenue","format":"currency"},"children":[],"parentKey":"card-1"}}
-{"op":"set","path":"/elements/chart-1","value":{"key":"chart-1","type":"Chart","props":{"type":"bar","dataPath":"analytics.salesByRegion"},"children":[],"parentKey":"card-1"}}`);
+  lines.push(`{"op":"add","path":"/root","value":"card-1"}
+{"op":"add","path":"/elements/card-1","value":{"type":"Card","props":{"title":"Dashboard"},"children":["metric-1","chart-1"]}}
+{"op":"add","path":"/elements/metric-1","value":{"type":"Metric","props":{"label":"Revenue","valuePath":"analytics.revenue","format":"currency"},"children":[]}}
+{"op":"add","path":"/elements/chart-1","value":{"type":"Chart","props":{"type":"bar","dataPath":"analytics.salesByRegion"},"children":[]}}`);
  lines.push("");

  // Components section
@@ -591,12 +591,11 @@ function generatePrompt<TDef extends SchemaDefinition, TCatalog>(
  lines.push("RULES:");
  const baseRules = [
    "Output ONLY JSONL patches - one JSON object per line, no markdown, no code fences",
-    'First line sets root: {"op":"set","path":"/root","value":"<root-key>"}',
-    'Then add each element: {"op":"set","path":"/elements/<key>","value":{...}}',
+    'First line sets root: {"op":"add","path":"/root","value":"<root-key>"}',
+    'Then add each element: {"op":"add","path":"/elements/<key>","value":{...}}',
    "ONLY use components listed above",
-    "Each element value needs: key, type, props, children (array of child keys), parentKey",
-    "Use unique keys (e.g., 'header', 'metric-1', 'chart-revenue')",
-    "Root element's parentKey is empty string, children reference their parent's key",
+    "Each element value needs: type, props, children (array of child keys)",
+    "Use unique keys for the element map entries (e.g., 'header', 'metric-1', 'chart-revenue')",
  ];
  const allRules = [...baseRules, ...customRules];
  allRules.forEach((rule, i) => {
@@ -1,5 +1,14 @@
 import { describe, it, expect } from "vitest";
-import { resolveDynamicValue, getByPath, setByPath } from "./types";
+import {
+  resolveDynamicValue,
+  getByPath,
+  setByPath,
+  addByPath,
+  removeByPath,
+  applySpecStreamPatch,
+  compileSpecStream,
+  createSpecStreamCompiler,
+} from "./types";

 describe("getByPath", () => {
  it("gets nested values with JSON pointer paths", () => {
@@ -123,3 +132,428 @@ describe("resolveDynamicValue", () => {
    ).toBeUndefined();
  });
 });
+
+// =============================================================================
+// JSON Pointer (RFC 6901) escaping
+// =============================================================================
+
+describe("JSON Pointer escaping (RFC 6901)", () => {
+  it("getByPath unescapes ~1 to /", () => {
+    const data = { "a/b": { c: 42 } };
+    expect(getByPath(data, "/a~1b/c")).toBe(42);
+  });
+
+  it("getByPath unescapes ~0 to ~", () => {
+    const data = { "a~b": 99 };
+    expect(getByPath(data, "/a~0b")).toBe(99);
+  });
+
+  it("getByPath handles combined ~0 and ~1 escaping", () => {
+    const data = { "a~/b": "found" };
+    expect(getByPath(data, "/a~0~1b")).toBe("found");
+  });
+
+  it("setByPath unescapes ~1 to / in keys", () => {
+    const data: Record<string, unknown> = {};
+    setByPath(data, "/a~1b", "value");
+    expect(data["a/b"]).toBe("value");
+  });
+
+  it("setByPath unescapes ~0 to ~ in keys", () => {
+    const data: Record<string, unknown> = {};
+    setByPath(data, "/a~0b", "value");
+    expect(data["a~b"]).toBe("value");
+  });
+
+  it("getByPath reads array elements properly", () => {
+    const data = { items: [10, 20, 30] };
+    expect(getByPath(data, "/items/0")).toBe(10);
+    expect(getByPath(data, "/items/2")).toBe(30);
+  });
+});
+
+// =============================================================================
+// addByPath (RFC 6902 "add" semantics)
+// =============================================================================
+
+describe("addByPath", () => {
+  it("adds a property to an object", () => {
+    const data: Record<string, unknown> = { a: 1 };
+    addByPath(data, "/b", 2);
+    expect(data.b).toBe(2);
+  });
+
+  it("replaces an existing object property (add semantics)", () => {
+    const data: Record<string, unknown> = { a: 1 };
+    addByPath(data, "/a", 99);
+    expect(data.a).toBe(99);
+  });
+
+  it("inserts into an array at a specific index", () => {
+    const data: Record<string, unknown> = { arr: [1, 2, 3] };
+    addByPath(data, "/arr/1", 99);
+    expect(data.arr).toEqual([1, 99, 2, 3]);
+  });
+
+  it("appends to an array with - (end-of-array)", () => {
+    const data: Record<string, unknown> = { arr: [1, 2] };
+    addByPath(data, "/arr/-", 3);
+    expect(data.arr).toEqual([1, 2, 3]);
+  });
+
+  it("inserts at index 0 of an array", () => {
+    const data: Record<string, unknown> = { arr: ["b", "c"] };
+    addByPath(data, "/arr/0", "a");
+    expect(data.arr).toEqual(["a", "b", "c"]);
+  });
+
+  it("creates intermediate objects", () => {
+    const data: Record<string, unknown> = {};
+    addByPath(data, "/x/y/z", "deep");
+    expect(
+      ((data.x as Record<string, unknown>).y as Record<string, unknown>).z,
+    ).toBe("deep");
+  });
+});
+
+// =============================================================================
+// removeByPath (RFC 6902 "remove" semantics)
+// =============================================================================
+
+describe("removeByPath", () => {
+  it("deletes an object property", () => {
+    const data: Record<string, unknown> = { a: 1, b: 2 };
+    removeByPath(data, "/a");
+    expect(data).toEqual({ b: 2 });
+    expect("a" in data).toBe(false);
+  });
+
+  it("removes an element from an array by index", () => {
+    const data: Record<string, unknown> = { arr: [1, 2, 3] };
+    removeByPath(data, "/arr/1");
+    expect(data.arr).toEqual([1, 3]);
+  });
+
+  it("removes nested properties", () => {
+    const data: Record<string, unknown> = { user: { name: "John", age: 30 } };
+    removeByPath(data, "/user/age");
+    expect(data.user).toEqual({ name: "John" });
+  });
+
+  it("is a no-op for non-existent paths", () => {
+    const data: Record<string, unknown> = { a: 1 };
+    removeByPath(data, "/b/c/d");
+    expect(data).toEqual({ a: 1 });
+  });
+});
+
+// =============================================================================
+// applySpecStreamPatch - RFC 6902 operations
+// =============================================================================
+
+describe("applySpecStreamPatch", () => {
+  describe("add operation", () => {
+    it("adds a new object property", () => {
+      const obj: Record<string, unknown> = {};
+      applySpecStreamPatch(obj, { op: "add", path: "/name", value: "Alice" });
+      expect(obj.name).toBe("Alice");
+    });
+
+    it("adds nested properties creating intermediates", () => {
+      const obj: Record<string, unknown> = {};
+      applySpecStreamPatch(obj, {
+        op: "add",
+        path: "/user/name",
+        value: "Bob",
+      });
+      expect((obj.user as Record<string, unknown>).name).toBe("Bob");
+    });
+
+    it("inserts into array at index", () => {
+      const obj: Record<string, unknown> = { items: [1, 3] };
+      applySpecStreamPatch(obj, { op: "add", path: "/items/1", value: 2 });
+      expect(obj.items).toEqual([1, 2, 3]);
+    });
+
+    it("appends to array with -", () => {
+      const obj: Record<string, unknown> = { items: [1, 2] };
+      applySpecStreamPatch(obj, { op: "add", path: "/items/-", value: 3 });
+      expect(obj.items).toEqual([1, 2, 3]);
+    });
+  });
+
+  describe("remove operation", () => {
+    it("removes an object property", () => {
+      const obj: Record<string, unknown> = { name: "Alice", age: 30 };
+      applySpecStreamPatch(obj, { op: "remove", path: "/age" });
+      expect(obj).toEqual({ name: "Alice" });
+      expect("age" in obj).toBe(false);
+    });
+
+    it("removes from array by index", () => {
+      const obj: Record<string, unknown> = { items: ["a", "b", "c"] };
+      applySpecStreamPatch(obj, { op: "remove", path: "/items/1" });
+      expect(obj.items).toEqual(["a", "c"]);
+    });
+  });
+
+  describe("replace operation", () => {
+    it("replaces an existing value", () => {
+      const obj: Record<string, unknown> = { name: "Alice" };
+      applySpecStreamPatch(obj, {
+        op: "replace",
+        path: "/name",
+        value: "Bob",
+      });
+      expect(obj.name).toBe("Bob");
+    });
+
+    it("replaces nested values", () => {
+      const obj: Record<string, unknown> = { user: { name: "Alice" } };
+      applySpecStreamPatch(obj, {
+        op: "replace",
+        path: "/user/name",
+        value: "Bob",
+      });
+      expect((obj.user as Record<string, unknown>).name).toBe("Bob");
+    });
+  });
+
+  describe("move operation", () => {
+    it("moves a value from one path to another", () => {
+      const obj: Record<string, unknown> = { a: 1, b: 2 };
+      applySpecStreamPatch(obj, { op: "move", path: "/c", from: "/a" });
+      expect(obj).toEqual({ b: 2, c: 1 });
+      expect("a" in obj).toBe(false);
+    });
+
+    it("moves nested values", () => {
+      const obj: Record<string, unknown> = {
+        source: { val: 42 },
+        target: {},
+      };
+      applySpecStreamPatch(obj, {
+        op: "move",
+        path: "/target/val",
+        from: "/source/val",
+      });
+      expect((obj.target as Record<string, unknown>).val).toBe(42);
+      expect("val" in (obj.source as Record<string, unknown>)).toBe(false);
+    });
+
+    it("is a no-op if from is missing", () => {
+      const obj: Record<string, unknown> = { a: 1 };
+      applySpecStreamPatch(obj, { op: "move", path: "/b" });
+      expect(obj).toEqual({ a: 1 });
+    });
+  });
+
+  describe("copy operation", () => {
+    it("copies a value from one path to another", () => {
+      const obj: Record<string, unknown> = { a: 1 };
+      applySpecStreamPatch(obj, { op: "copy", path: "/b", from: "/a" });
+      expect(obj).toEqual({ a: 1, b: 1 });
+    });
+
+    it("copies complex values", () => {
+      const obj: Record<string, unknown> = {
+        source: { nested: { value: 42 } },
+      };
+      applySpecStreamPatch(obj, {
+        op: "copy",
+        path: "/dest",
+        from: "/source/nested",
+      });
+      expect(obj.dest).toEqual({ value: 42 });
+      // Source should still exist
+      expect((obj.source as Record<string, unknown>).nested).toEqual({
+        value: 42,
+      });
+    });
+
+    it("is a no-op if from is missing", () => {
+      const obj: Record<string, unknown> = { a: 1 };
+      applySpecStreamPatch(obj, { op: "copy", path: "/b" });
+      expect(obj).toEqual({ a: 1 });
+    });
+  });
+
+  describe("test operation", () => {
+    it("succeeds when values match", () => {
+      const obj: Record<string, unknown> = { name: "Alice" };
+      expect(() =>
+        applySpecStreamPatch(obj, {
+          op: "test",
+          path: "/name",
+          value: "Alice",
+        }),
+      ).not.toThrow();
+    });
+
+    it("succeeds for matching objects", () => {
+      const obj: Record<string, unknown> = { user: { name: "Alice", age: 30 } };
+      expect(() =>
+        applySpecStreamPatch(obj, {
+          op: "test",
+          path: "/user",
+          value: { name: "Alice", age: 30 },
+        }),
+      ).not.toThrow();
+    });
+
+    it("succeeds for matching arrays", () => {
+      const obj: Record<string, unknown> = { items: [1, 2, 3] };
+      expect(() =>
+        applySpecStreamPatch(obj, {
+          op: "test",
+          path: "/items",
+          value: [1, 2, 3],
+        }),
+      ).not.toThrow();
+    });
+
+    it("throws when values do not match", () => {
+      const obj: Record<string, unknown> = { name: "Alice" };
+      expect(() =>
+        applySpecStreamPatch(obj, {
+          op: "test",
+          path: "/name",
+          value: "Bob",
+        }),
+      ).toThrow('Test operation failed: value at "/name" does not match');
+    });
+
+    it("throws when path does not exist", () => {
+      const obj: Record<string, unknown> = {};
+      expect(() =>
+        applySpecStreamPatch(obj, {
+          op: "test",
+          path: "/missing",
+          value: "anything",
+        }),
+      ).toThrow();
+    });
+  });
+});
+
+// =============================================================================
+// compileSpecStream
+// =============================================================================
+
+describe("compileSpecStream", () => {
+  it("compiles a series of add patches", () => {
+    const stream = `{"op":"add","path":"/name","value":"Alice"}
+{"op":"add","path":"/age","value":30}`;
+    const result = compileSpecStream(stream);
+    expect(result).toEqual({ name: "Alice", age: 30 });
+  });
+
+  it("handles remove operations", () => {
+    const stream = `{"op":"add","path":"/a","value":1}
+{"op":"add","path":"/b","value":2}
+{"op":"remove","path":"/a"}`;
+    const result = compileSpecStream(stream);
+    expect(result).toEqual({ b: 2 });
+    expect("a" in result).toBe(false);
+  });
+
+  it("handles replace operations", () => {
+    const stream = `{"op":"add","path":"/name","value":"Alice"}
+{"op":"replace","path":"/name","value":"Bob"}`;
+    const result = compileSpecStream(stream);
+    expect(result).toEqual({ name: "Bob" });
+  });
+
+  it("handles move operations", () => {
+    const stream = `{"op":"add","path":"/old","value":"data"}
+{"op":"move","path":"/new","from":"/old"}`;
+    const result = compileSpecStream(stream);
+    expect(result).toEqual({ new: "data" });
+  });
+
+  it("handles copy operations", () => {
+    const stream = `{"op":"add","path":"/original","value":"data"}
+{"op":"copy","path":"/duplicate","from":"/original"}`;
+    const result = compileSpecStream(stream);
+    expect(result).toEqual({ original: "data", duplicate: "data" });
+  });
+
+  it("skips empty lines", () => {
+    const stream = `{"op":"add","path":"/a","value":1}
+
+{"op":"add","path":"/b","value":2}`;
+    const result = compileSpecStream(stream);
+    expect(result).toEqual({ a: 1, b: 2 });
+  });
+
+  it("uses initial value", () => {
+    const stream = `{"op":"add","path":"/b","value":2}`;
+    const result = compileSpecStream(stream, { a: 1 });
+    expect(result).toEqual({ a: 1, b: 2 });
+  });
+});
+
+// =============================================================================
+// createSpecStreamCompiler
+// =============================================================================
+
+describe("createSpecStreamCompiler", () => {
+  it("processes chunks incrementally", () => {
+    const compiler = createSpecStreamCompiler();
+    const { result, newPatches } = compiler.push(
+      '{"op":"add","path":"/name","value":"Alice"}\n',
+    );
+    expect(newPatches).toHaveLength(1);
+    expect(result).toEqual({ name: "Alice" });
+  });
+
+  it("handles partial lines across chunks", () => {
+    const compiler = createSpecStreamCompiler();
+
+    // First chunk is incomplete
+    const r1 = compiler.push('{"op":"add","path":"/na');
+    expect(r1.newPatches).toHaveLength(0);
+
+    // Complete the line
+    const r2 = compiler.push('me","value":"Alice"}\n');
+    expect(r2.newPatches).toHaveLength(1);
+    expect(r2.result).toEqual({ name: "Alice" });
+  });
+
+  it("processes remaining buffer on getResult", () => {
+    const compiler = createSpecStreamCompiler();
+    compiler.push('{"op":"add","path":"/name","value":"Alice"}');
+    // No newline, so not processed yet
+    const result = compiler.getResult();
+    expect(result).toEqual({ name: "Alice" });
+  });
+
+  it("resets to clean state", () => {
+    const compiler = createSpecStreamCompiler();
+    compiler.push('{"op":"add","path":"/name","value":"Alice"}\n');
+    compiler.reset();
+    const result = compiler.getResult();
+    expect(result).toEqual({});
+  });
+
+  it("tracks all applied patches", () => {
+    const compiler = createSpecStreamCompiler();
+    compiler.push('{"op":"add","path":"/a","value":1}\n');
+    compiler.push('{"op":"add","path":"/b","value":2}\n');
+    const patches = compiler.getPatches();
+    expect(patches).toHaveLength(2);
+    expect(patches[0]!.op).toBe("add");
+    expect(patches[1]!.op).toBe("add");
+  });
+
+  it("handles all RFC 6902 operations", () => {
+    const compiler = createSpecStreamCompiler();
+    compiler.push('{"op":"add","path":"/x","value":1}\n');
+    compiler.push('{"op":"add","path":"/y","value":2}\n');
+    compiler.push('{"op":"move","path":"/z","from":"/x"}\n');
+    compiler.push('{"op":"copy","path":"/w","from":"/y"}\n');
+    compiler.push('{"op":"remove","path":"/y"}\n');
+    const result = compiler.getResult();
+    expect(result).toEqual({ z: 1, w: 2 });
+  });
+});
@@ -53,20 +53,31 @@ export interface UIElement<
  T extends string = string,
  P = Record<string, unknown>,
 > {
-  /** Unique key for reconciliation */
-  key: string;
  /** Component type from the catalog */
  type: T;
  /** Component props */
  props: P;
  /** Child element keys (flat structure) */
  children?: string[];
-  /** Parent element key (null for root) */
-  parentKey?: string | null;
  /** Visibility condition */
  visible?: VisibilityCondition;
 }

+/**
+ * Element with key and parentKey for use with flatToTree.
+ * When elements are in an array (not a keyed map), key and parentKey
+ * are needed to establish identity and parent-child relationships.
+ */
+export interface FlatElement<
+  T extends string = string,
+  P = Record<string, unknown>,
+> extends UIElement<T, P> {
+  /** Unique key identifying this element */
+  key: string;
+  /** Parent element key (null for root) */
+  parentKey?: string | null;
+}
+
 /**
 * Visibility condition types
 */
@@ -125,17 +136,20 @@ export type ComponentSchema = z.ZodType<Record<string, unknown>>;
 export type ValidationMode = "strict" | "warn" | "ignore";

 /**
- * JSON patch operation types
+ * JSON patch operation types (RFC 6902)
 */
-export type PatchOp = "add" | "remove" | "replace" | "set";
+export type PatchOp = "add" | "remove" | "replace" | "move" | "copy" | "test";

 /**
- * JSON patch operation
+ * JSON patch operation (RFC 6902)
 */
 export interface JsonPatch {
  op: PatchOp;
  path: string;
+  /** Required for add, replace, test */
  value?: unknown;
+  /** Required for move, copy (source location) */
+  from?: string;
 }

 /**
@@ -157,16 +171,30 @@ export function resolveDynamicValue<T>(
 }

 /**
- * Get a value from an object by JSON Pointer path
+ * Unescape a JSON Pointer token per RFC 6901 Section 4.
+ * ~1 is decoded to / and ~0 is decoded to ~ (order matters).
+ */
+function unescapeJsonPointer(token: string): string {
+  return token.replace(/~1/g, "/").replace(/~0/g, "~");
+}
+
+/**
+ * Parse a JSON Pointer path into unescaped segments.
+ */
+function parseJsonPointer(path: string): string[] {
+  const raw = path.startsWith("/") ? path.slice(1).split("/") : path.split("/");
+  return raw.map(unescapeJsonPointer);
+}
+
+/**
+ * Get a value from an object by JSON Pointer path (RFC 6901)
 */
 export function getByPath(obj: unknown, path: string): unknown {
  if (!path || path === "/") {
    return obj;
  }

-  const segments = path.startsWith("/")
-    ? path.slice(1).split("/")
-    : path.split("/");
+  const segments = parseJsonPointer(path);

  let current: unknown = obj;

@@ -175,7 +203,10 @@ export function getByPath(obj: unknown, path: string): unknown {
      return undefined;
    }

-    if (typeof current === "object") {
+    if (Array.isArray(current)) {
+      const index = parseInt(segment, 10);
+      current = current[index];
+    } else if (typeof current === "object") {
      current = (current as Record<string, unknown>)[segment];
    } else {
      return undefined;
@@ -193,7 +224,7 @@ function isNumericIndex(str: string): boolean {
 }

 /**
- * Set a value in an object by JSON Pointer path.
+ * Set a value in an object by JSON Pointer path (RFC 6901).
 * Automatically creates arrays when the path segment is a numeric index.
 */
 export function setByPath(
@@ -201,9 +232,7 @@ export function setByPath(
  path: string,
  value: unknown,
 ): void {
-  const segments = path.startsWith("/")
-    ? path.slice(1).split("/")
-    : path.split("/");
+  const segments = parseJsonPointer(path);

  if (segments.length === 0) return;

@@ -213,7 +242,8 @@ export function setByPath(
    const segment = segments[i]!;
    const nextSegment = segments[i + 1];
    const nextIsNumeric =
-      nextSegment !== undefined && isNumericIndex(nextSegment);
+      nextSegment !== undefined &&
+      (isNumericIndex(nextSegment) || nextSegment === "-");

    if (Array.isArray(current)) {
      const index = parseInt(segment, 10);
@@ -231,13 +261,131 @@ export function setByPath(

  const lastSegment = segments[segments.length - 1]!;
  if (Array.isArray(current)) {
-    const index = parseInt(lastSegment, 10);
-    current[index] = value;
+    if (lastSegment === "-") {
+      current.push(value);
+    } else {
+      const index = parseInt(lastSegment, 10);
+      current[index] = value;
+    }
  } else {
    current[lastSegment] = value;
  }
 }

+/**
+ * Add a value per RFC 6902 "add" semantics.
+ * For objects: create-or-replace the member.
+ * For arrays: insert before the given index, or append if "-".
+ */
+export function addByPath(
+  obj: Record<string, unknown>,
+  path: string,
+  value: unknown,
+): void {
+  const segments = parseJsonPointer(path);
+
+  if (segments.length === 0) return;
+
+  let current: Record<string, unknown> | unknown[] = obj;
+
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i]!;
+    const nextSegment = segments[i + 1];
+    const nextIsNumeric =
+      nextSegment !== undefined &&
+      (isNumericIndex(nextSegment) || nextSegment === "-");
+
+    if (Array.isArray(current)) {
+      const index = parseInt(segment, 10);
+      if (current[index] === undefined || typeof current[index] !== "object") {
+        current[index] = nextIsNumeric ? [] : {};
+      }
+      current = current[index] as Record<string, unknown> | unknown[];
+    } else {
+      if (!(segment in current) || typeof current[segment] !== "object") {
+        current[segment] = nextIsNumeric ? [] : {};
+      }
+      current = current[segment] as Record<string, unknown> | unknown[];
+    }
+  }
+
+  const lastSegment = segments[segments.length - 1]!;
+  if (Array.isArray(current)) {
+    if (lastSegment === "-") {
+      current.push(value);
+    } else {
+      const index = parseInt(lastSegment, 10);
+      current.splice(index, 0, value);
+    }
+  } else {
+    current[lastSegment] = value;
+  }
+}
+
+/**
+ * Remove a value per RFC 6902 "remove" semantics.
+ * For objects: delete the property.
+ * For arrays: splice out the element at the given index.
+ */
+export function removeByPath(obj: Record<string, unknown>, path: string): void {
+  const segments = parseJsonPointer(path);
+
+  if (segments.length === 0) return;
+
+  let current: Record<string, unknown> | unknown[] = obj;
+
+  for (let i = 0; i < segments.length - 1; i++) {
+    const segment = segments[i]!;
+
+    if (Array.isArray(current)) {
+      const index = parseInt(segment, 10);
+      if (current[index] === undefined || typeof current[index] !== "object") {
+        return; // path does not exist
+      }
+      current = current[index] as Record<string, unknown> | unknown[];
+    } else {
+      if (!(segment in current) || typeof current[segment] !== "object") {
+        return; // path does not exist
+      }
+      current = current[segment] as Record<string, unknown> | unknown[];
+    }
+  }
+
+  const lastSegment = segments[segments.length - 1]!;
+  if (Array.isArray(current)) {
+    const index = parseInt(lastSegment, 10);
+    if (index >= 0 && index < current.length) {
+      current.splice(index, 1);
+    }
+  } else {
+    delete current[lastSegment];
+  }
+}
+
+/**
+ * Deep equality check for RFC 6902 "test" operation.
+ */
+function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (a === null || b === null) return false;
+  if (typeof a !== typeof b) return false;
+  if (typeof a !== "object") return false;
+
+  if (Array.isArray(a)) {
+    if (!Array.isArray(b)) return false;
+    if (a.length !== b.length) return false;
+    return a.every((item, i) => deepEqual(item, b[i]));
+  }
+
+  const aObj = a as Record<string, unknown>;
+  const bObj = b as Record<string, unknown>;
+  const aKeys = Object.keys(aObj);
+  const bKeys = Object.keys(bObj);
+
+  if (aKeys.length !== bKeys.length) return false;
+  return aKeys.every((key) => deepEqual(aObj[key], bObj[key]));
+}
+
 /**
 * Find a form value from params and/or data.
 * Useful in action handlers to locate form input values regardless of path format.
@@ -334,17 +482,50 @@ export function parseSpecStreamLine(line: string): SpecStreamLine | null {
 }

 /**
- * Apply a single SpecStream patch to an object.
+ * Apply a single RFC 6902 JSON Patch operation to an object.
 * Mutates the object in place.
+ *
+ * Supports all six RFC 6902 operations: add, remove, replace, move, copy, test.
+ *
+ * @throws {Error} If a "test" operation fails (value mismatch).
 */
 export function applySpecStreamPatch<T extends Record<string, unknown>>(
  obj: T,
  patch: SpecStreamLine,
 ): T {
-  if (patch.op === "set" || patch.op === "add" || patch.op === "replace") {
-    setByPath(obj, patch.path, patch.value);
-  } else if (patch.op === "remove") {
-    setByPath(obj, patch.path, undefined);
+  switch (patch.op) {
+    case "add":
+      addByPath(obj, patch.path, patch.value);
+      break;
+    case "replace":
+      // RFC 6902: target must exist. For streaming tolerance we set regardless.
+      setByPath(obj, patch.path, patch.value);
+      break;
+    case "remove":
+      removeByPath(obj, patch.path);
+      break;
+    case "move": {
+      if (!patch.from) break;
+      const moveValue = getByPath(obj, patch.from);
+      removeByPath(obj, patch.from);
+      addByPath(obj, patch.path, moveValue);
+      break;
+    }
+    case "copy": {
+      if (!patch.from) break;
+      const copyValue = getByPath(obj, patch.from);
+      addByPath(obj, patch.path, copyValue);
+      break;
+    }
+    case "test": {
+      const actual = getByPath(obj, patch.path);
+      if (!deepEqual(actual, patch.value)) {
+        throw new Error(
+          `Test operation failed: value at "${patch.path}" does not match`,
+        );
+      }
+      break;
+    }
  }
  return obj;
 }
@@ -354,8 +535,8 @@ export function applySpecStreamPatch<T extends Record<string, unknown>>(
 * Each line should be a patch operation.
 *
 * @example
- * const stream = `{"op":"set","path":"/name","value":"Alice"}
- * {"op":"set","path":"/age","value":30}`;
+ * const stream = `{"op":"add","path":"/name","value":"Alice"}
+ * {"op":"add","path":"/age","value":30}`;
 * const result = compileSpecStream(stream);
 * // { name: "Alice", age: 30 }
 */
@@ -1,5 +1,13 @@
 # @json-render/react

+## 0.4.4
+
+### Patch Changes
+
+- dd17549: remove key/parentKey from flat specs, RFC 6902 compliance for SpecStream
+- Updated dependencies [dd17549]
+  - @json-render/core@0.4.4
+
 ## 0.4.3

 ### Patch Changes
@@ -1,6 +1,6 @@
 {
  "name": "@json-render/react",
-  "version": "0.4.3",
+  "version": "0.4.4",
  "license": "Apache-2.0",
  "description": "React renderer for @json-render/core. JSON becomes React components.",
  "keywords": [
@@ -1,8 +1,18 @@
 "use client";

 import { useState, useCallback, useRef, useEffect } from "react";
-import type { Spec, UIElement, JsonPatch } from "@json-render/core";
-import { setByPath } from "@json-render/core";
+import type {
+  Spec,
+  UIElement,
+  FlatElement,
+  JsonPatch,
+} from "@json-render/core";
+import {
+  setByPath,
+  getByPath,
+  addByPath,
+  removeByPath,
+} from "@json-render/core";

 /**
 * Parse a single JSON patch line
@@ -20,56 +30,104 @@ function parsePatchLine(line: string): JsonPatch | null {
 }

 /**
- * Apply a JSON patch to the current spec
+ * Set a value at a spec path (for add/replace operations).
+ */
+function setSpecValue(newSpec: Spec, path: string, value: unknown): void {
+  if (path === "/root") {
+    newSpec.root = value as string;
+    return;
+  }
+
+  if (path.startsWith("/elements/")) {
+    const pathParts = path.slice("/elements/".length).split("/");
+    const elementKey = pathParts[0];
+    if (!elementKey) return;
+
+    if (pathParts.length === 1) {
+      newSpec.elements[elementKey] = value as UIElement;
+    } else {
+      const element = newSpec.elements[elementKey];
+      if (element) {
+        const propPath = "/" + pathParts.slice(1).join("/");
+        const newElement = { ...element };
+        setByPath(
+          newElement as unknown as Record<string, unknown>,
+          propPath,
+          value,
+        );
+        newSpec.elements[elementKey] = newElement;
+      }
+    }
+  }
+}
+
+/**
+ * Remove a value at a spec path.
+ */
+function removeSpecValue(newSpec: Spec, path: string): void {
+  if (path.startsWith("/elements/")) {
+    const pathParts = path.slice("/elements/".length).split("/");
+    const elementKey = pathParts[0];
+    if (!elementKey) return;
+
+    if (pathParts.length === 1) {
+      const { [elementKey]: _, ...rest } = newSpec.elements;
+      newSpec.elements = rest;
+    } else {
+      const element = newSpec.elements[elementKey];
+      if (element) {
+        const propPath = "/" + pathParts.slice(1).join("/");
+        const newElement = { ...element };
+        removeByPath(
+          newElement as unknown as Record<string, unknown>,
+          propPath,
+        );
+        newSpec.elements[elementKey] = newElement;
+      }
+    }
+  }
+}
+
+/**
+ * Get a value at a spec path.
+ */
+function getSpecValue(spec: Spec, path: string): unknown {
+  if (path === "/root") return spec.root;
+  return getByPath(spec as unknown as Record<string, unknown>, path);
+}
+
+/**
+ * Apply an RFC 6902 JSON patch to the current spec.
+ * Supports add, remove, replace, move, copy, and test operations.
 */
 function applyPatch(spec: Spec, patch: JsonPatch): Spec {
  const newSpec = { ...spec, elements: { ...spec.elements } };

  switch (patch.op) {
-    case "set":
    case "add":
    case "replace": {
-      // Handle root path
-      if (patch.path === "/root") {
-        newSpec.root = patch.value as string;
-        return newSpec;
-      }
-
-      // Handle elements paths
-      if (patch.path.startsWith("/elements/")) {
-        const pathParts = patch.path.slice("/elements/".length).split("/");
-        const elementKey = pathParts[0];
-
-        if (!elementKey) return newSpec;
-
-        if (pathParts.length === 1) {
-          // Setting entire element
-          newSpec.elements[elementKey] = patch.value as UIElement;
-        } else {
-          // Setting property of element
-          const element = newSpec.elements[elementKey];
-          if (element) {
-            const propPath = "/" + pathParts.slice(1).join("/");
-            const newElement = { ...element };
-            setByPath(
-              newElement as unknown as Record<string, unknown>,
-              propPath,
-              patch.value,
-            );
-            newSpec.elements[elementKey] = newElement;
-          }
-        }
-      }
+      setSpecValue(newSpec, patch.path, patch.value);
      break;
    }
    case "remove": {
-      if (patch.path.startsWith("/elements/")) {
-        const elementKey = patch.path.slice("/elements/".length).split("/")[0];
-        if (elementKey) {
-          const { [elementKey]: _, ...rest } = newSpec.elements;
-          newSpec.elements = rest;
-        }
-      }
+      removeSpecValue(newSpec, patch.path);
+      break;
+    }
+    case "move": {
+      if (!patch.from) break;
+      const moveValue = getSpecValue(newSpec, patch.from);
+      removeSpecValue(newSpec, patch.from);
+      setSpecValue(newSpec, patch.path, moveValue);
+      break;
+    }
+    case "copy": {
+      if (!patch.from) break;
+      const copyValue = getSpecValue(newSpec, patch.from);
+      setSpecValue(newSpec, patch.path, copyValue);
+      break;
+    }
+    case "test": {
+      // test is a no-op for rendering purposes (validation only)
      break;
    }
  }
@@ -236,18 +294,18 @@ export function useUIStream({
 }

 /**
- * Convert a flat element list to a Spec
+ * Convert a flat element list to a Spec.
+ * Input elements use key/parentKey to establish identity and relationships.
+ * Output spec uses the map-based format where key is the map entry key
+ * and parent-child relationships are expressed through children arrays.
 */
-export function flatToTree(
-  elements: Array<UIElement & { parentKey?: string | null }>,
-): Spec {
+export function flatToTree(elements: FlatElement[]): Spec {
  const elementMap: Record<string, UIElement> = {};
  let root = "";

  // First pass: add all elements to map
  for (const element of elements) {
    elementMap[element.key] = {
-      key: element.key,
      type: element.type,
      props: element.props,
      children: [],
@@ -15,16 +15,12 @@ export const schema = defineSchema((s) => ({
    /** Flat map of elements by key */
    elements: s.record(
      s.object({
-        /** Unique key for this element */
-        key: s.string(),
        /** Component type from catalog */
        type: s.ref("catalog.components"),
        /** Component props */
        props: s.propsOf("catalog.components"),
        /** Child element keys (flat reference) */
        children: s.array(s.string()),
-        /** Parent element key (null for root) */
-        parentKey: s.string(),
        /** Visibility condition */
        visible: s.any(),
      }),
@@ -1,5 +1,13 @@
 # @json-render/remotion

+## 0.4.4
+
+### Patch Changes
+
+- dd17549: remove key/parentKey from flat specs, RFC 6902 compliance for SpecStream
+- Updated dependencies [dd17549]
+  - @json-render/core@0.4.4
+
 ## 0.4.3

 ### Patch Changes
@@ -1,6 +1,6 @@
 {
  "name": "@json-render/remotion",
-  "version": "0.4.3",
+  "version": "0.4.4",
  "license": "Apache-2.0",
  "description": "Remotion renderer for @json-render/core. JSON becomes video compositions.",
  "keywords": [
@@ -25,11 +25,12 @@ function remotionPromptTemplate(context: PromptContext): string {
  lines.push("");
  lines.push("Example output (each line is a separate JSON object):");
  lines.push("");
-  lines.push(`{"op":"set","path":"/composition","value":{"id":"intro","fps":30,"width":1920,"height":1080,"durationInFrames":300}}
-{"op":"set","path":"/tracks","value":[{"id":"main","name":"Main","type":"video","enabled":true},{"id":"overlay","name":"Overlay","type":"overlay","enabled":true}]}
-{"op":"set","path":"/clips/0","value":{"id":"clip-1","trackId":"main","component":"TitleCard","props":{"title":"Welcome","subtitle":"Getting Started"},"from":0,"durationInFrames":90,"transitionIn":{"type":"fade","durationInFrames":15},"transitionOut":{"type":"fade","durationInFrames":15},"motion":{"enter":{"opacity":0,"y":50,"scale":0.9,"duration":25},"spring":{"damping":15}}}}
-{"op":"set","path":"/clips/1","value":{"id":"clip-2","trackId":"main","component":"TitleCard","props":{"title":"Features"},"from":90,"durationInFrames":90,"motion":{"enter":{"opacity":0,"x":-100,"duration":20},"exit":{"opacity":0,"x":100,"duration":15}}}}
-{"op":"set","path":"/audio","value":{"tracks":[]}}`);
+  lines.push(`{"op":"add","path":"/composition","value":{"id":"intro","fps":30,"width":1920,"height":1080,"durationInFrames":300}}
+{"op":"add","path":"/tracks","value":[{"id":"main","name":"Main","type":"video","enabled":true},{"id":"overlay","name":"Overlay","type":"overlay","enabled":true}]}
+{"op":"add","path":"/clips","value":[]}
+{"op":"add","path":"/clips/-","value":{"id":"clip-1","trackId":"main","component":"TitleCard","props":{"title":"Welcome","subtitle":"Getting Started"},"from":0,"durationInFrames":90,"transitionIn":{"type":"fade","durationInFrames":15},"transitionOut":{"type":"fade","durationInFrames":15},"motion":{"enter":{"opacity":0,"y":50,"scale":0.9,"duration":25},"spring":{"damping":15}}}}
+{"op":"add","path":"/clips/-","value":{"id":"clip-2","trackId":"main","component":"TitleCard","props":{"title":"Features"},"from":90,"durationInFrames":90,"motion":{"enter":{"opacity":0,"x":-100,"duration":20},"exit":{"opacity":0,"x":100,"duration":15}}}}
+{"op":"add","path":"/audio","value":{"tracks":[]}}`);
  lines.push("");

  // Components
@@ -107,10 +108,10 @@ function remotionPromptTemplate(context: PromptContext): string {
  lines.push("RULES:");
  const baseRules = [
    "Output ONLY JSONL patches - one JSON object per line, no markdown, no code fences",
-    "First set /composition with {id, fps:30, width:1920, height:1080, durationInFrames}",
-    "Then set /tracks array with video/overlay tracks",
-    "Then set each clip: /clips/0, /clips/1, etc.",
-    "Finally set /audio with {tracks:[]}",
+    'First add /composition with {id, fps:30, width:1920, height:1080, durationInFrames}: {"op":"add","path":"/composition","value":{...}}',
+    'Then add /tracks array with video/overlay tracks: {"op":"add","path":"/tracks","value":[...]}',
+    'Then add each clip by appending to the array: {"op":"add","path":"/clips/-","value":{...}}',
+    'Finally add /audio with {tracks:[]}: {"op":"add","path":"/audio","value":{...}}',
    "ONLY use components listed above",
    "fps is always 30 (1 second = 30 frames, 10 seconds = 300 frames)",
    'Clips on "main" track flow sequentially (from = previous clip\'s from + durationInFrames)',
Author	SHA1	Message	Date
github-actions[bot]	e9ea9c782b	chore: version packages (#80 ) Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>	2026-02-07 12:31:01 -06:00
Chris Tate	dd17549ee8	next release (#79 )	2026-02-07 12:17:32 -06:00
Chris Tate	1eb6212dd7	fix json patch (#78 )	2026-02-07 12:09:53 -06:00
Chris Tate	711e79b069	remove key/parentKey from flat specs (#77 )	2026-02-07 11:46:16 -06:00