@ggui-ai/ui-gen 0.15.0 → 0.17.0

package/dist/compose.js

@@ -18,7 +18,7 @@ var renderFragments = {
     axis: "render",
     value: "grid",
     cacheTier: "axisDelta",
-    promptText: "## Render: grid\n2D tile layout. Use <CardGrid> or CSS `display: grid` with `grid-template-columns: repeat(N, 1fr)`. If items carry row/col fields, position each tile at (row, col). Do not scroll horizontally."
+    promptText: '## Render: grid\nTwo shapes share this axis \u2014 read the contract:\n- A TILE grid (a gallery, a stat grid, items that may carry row/col fields): `<Grid columns={N} gap="md">` (or `<CardGrid>`); if items carry row/col fields, position each tile at (row, col).\n- A BOARD (a columns / lanes / stages array whose items are cards \u2014 a kanban): the columns sit SIDE BY SIDE at md and wider \u2014 `<Grid columns={{ base: 1, md: columns.length }} gap="md">` wrapping the columns map, each column its own `<Stack>` of `<Card>`s with its header and count; NEVER a `<Stack>` of column sections (that is a list \u2014 tier-0 fails it).\nNever hand-roll `display: grid`. Do not scroll horizontally.'
   },
   spatial: {
     axis: "render",

package/dist/compose.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/fragments/render.ts","../src/fragments/state.ts","../src/fragments/writes.ts","../src/fragments/realtime.ts","../src/fragments/fetch.ts","../src/fragments/layout.ts","../src/fragments/tooling.ts","../src/fragments/index.ts","../src/compose.ts"],"names":[],"mappings":";AAQO,IAAM,eAAA,GAAmD;AAAA,EAC9D,MAAA,EAAQ;AAAA,IACN,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,QAAA;AAAA,IACP,SAAA,EAAW;AAAA;AAAA;AAAA;AAAA,GAIb;AAAA,EACA,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,MAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,MAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,OAAA,EAAS;AAAA,IACP,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,SAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,QAAA,EAAU;AAAA,IACR,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,UAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,OAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,eAAA,EAAiB;AAAA,IACf,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,eAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA;AAEN,CAAA;;;ACpDO,IAAM,cAAA,GAAkD;AAAA,EAC7D,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,OAAA;AAAA,IACN,KAAA,EAAO,MAAA;AAAA,IACP,SAAA,EAAW;AAAA;AAAA,GAEb;AAAA,EACA,eAAA,EAAiB;AAAA,IACf,IAAA,EAAM,OAAA;AAAA,IACN,KAAA,EAAO,eAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,OAAA;AAAA,IACN,KAAA,EAAO,OAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE,ulBAAA;AAAA,IACF,iBAAA,EAAmB;AAAA,MACjB,EAAA;AAAA,MACA,gEAAA;AAAA,MACA,yHAAA;AAAA,MACA;AAAA,KACF,CAAE,KAAK,IAAI;AAAA,GACb;AAAA,EACA,OAAA,EAAS;AAAA,IACP,IAAA,EAAM,OAAA;AAAA,IACN,KAAA,EAAO,SAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE,6MAAA;AAAA,IACF,iBAAA,EAAmB;AAAA,MACjB,EAAA;AAAA,MACA,6CAAA;AAAA,MACA,uFAAA;AAAA,MACA;AAAA,KACF,CAAE,KAAK,IAAI;AAAA,GACb;AAAA,EACA,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,OAAA;AAAA,IACN,KAAA,EAAO,OAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA;AAEN,CAAA;;;AChDO,IAAM,cAAA,GAAkD;AAAA,EAC7D,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,MAAA;AAAA,IACP,SAAA,EAAW;AAAA,GACb;AAAA,EACA,MAAA,EAAQ;AAAA,IACN,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,QAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,cAAA,EAAgB;AAAA,IACd,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,cAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,UAAA,EAAY;AAAA,IACV,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,UAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE,yMAAA;AAAA,IACF,iBAAA,EAAmB;AAAA,MACjB,EAAA;AAAA,MACA,iDAAA;AAAA,MACA,+EAAA;AAAA,MACA;AAAA,KACF,CAAE,KAAK,IAAI;AAAA,GACb;AAAA,EACA,MAAA,EAAQ;AAAA,IACN,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,QAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,OAAA,EAAS;AAAA,IACP,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,SAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA;AAEN,CAAA;AAGO,IAAM,qBAAA,GAAyD;AAAA,EACpE,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,cAAA;AAAA,IACN,KAAA,EAAO,OAAA;AAAA,IACP,SAAA,EAAW;AAAA;AAAA,GAEb;AAAA,EACA,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,cAAA;AAAA,IACN,KAAA,EAAO,MAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE,4PAAA;AAAA,IACF,iBAAA,EAAmB;AAAA,MACjB,EAAA;AAAA,MACA,2CAAA;AAAA,MACA,iFAAA;AAAA,MACA;AAAA,KACF,CAAE,KAAK,IAAI;AAAA,GACb;AAAA,EACA,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,cAAA;AAAA,IACN,KAAA,EAAO,OAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,SAAA,EAAW;AAAA,IACT,IAAA,EAAM,cAAA;AAAA,IACN,KAAA,EAAO,WAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,cAAA;AAAA,IACN,KAAA,EAAO,MAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA;AAEN,CAAA;;;AC1FO,IAAM,iBAAA,GAAqD;AAAA,EAChE,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,UAAA;AAAA,IACN,KAAA,EAAO,MAAA;AAAA,IACP,SAAA,EAAW;AAAA,GACb;AAAA,EACA,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,UAAA;AAAA,IACN,KAAA,EAAO,OAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,MAAA,EAAQ;AAAA,IACN,IAAA,EAAM,UAAA;AAAA,IACN,KAAA,EAAO,QAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,MAAA,EAAQ;AAAA,IACN,IAAA,EAAM,UAAA;AAAA,IACN,KAAA,EAAO,QAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,QAAA,EAAU;AAAA,IACR,IAAA,EAAM,UAAA;AAAA,IACN,KAAA,EAAO,UAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,UAAA;AAAA,IACN,KAAA,EAAO,OAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE,6sCAAA;AAAA,IACF,iBAAA,EAAmB;AAAA,MACjB,EAAA;AAAA,MACA,sDAAA;AAAA,MACA,mFAAA;AAAA,MACA;AAAA,KACF,CAAE,KAAK,IAAI;AAAA;AAEf,CAAA;;;AC9CO,IAAM,cAAA,GAAkD;AAAA,EAC7D,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,OAAA;AAAA,IACN,KAAA,EAAO,MAAA;AAAA,IACP,SAAA,EAAW;AAAA,GACb;AAAA,EACA,UAAA,EAAY;AAAA,IACV,IAAA,EAAM,OAAA;AAAA,IACN,KAAA,EAAO,YAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,MAAA,EAAQ;AAAA,IACN,IAAA,EAAM,OAAA;AAAA,IACN,KAAA,EAAO,QAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,YAAA,EAAc;AAAA,IACZ,IAAA,EAAM,OAAA;AAAA,IACN,KAAA,EAAO,YAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,OAAA,EAAS;AAAA,IACP,IAAA,EAAM,OAAA;AAAA,IACN,KAAA,EAAO,SAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA;AAEN,CAAA;;;ACpCO,IAAM,eAAA,GAAmD;AAAA,EAC9D,MAAA,EAAQ;AAAA,IACN,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,QAAA;AAAA,IACP,SAAA,EAAW;AAAA,GACb;AAAA,EACA,YAAA,EAAc;AAAA,IACZ,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,YAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,IAMX,UAAA,EACE;AAAA,GAiDJ;AAAA,EACA,eAAA,EAAiB;AAAA,IACf,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,eAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,OAAA,EAAS;AAAA,IACP,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,SAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,QAAA;AAAA,IACN,KAAA,EAAO,OAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA;AAEN,CAAA;;;AC1EO,IAAM,gBAAA,GAAoD;AAAA,EAC/D,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,SAAA;AAAA,IACN,KAAA,EAAO,MAAA;AAAA,IACP,SAAA,EAAW;AAAA;AAAA;AAAA,GAGb;AAAA,EACA,KAAA,EAAO;AAAA,IACL,IAAA,EAAM,SAAA;AAAA,IACN,KAAA,EAAO,OAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,MAAA,EAAQ;AAAA,IACN,IAAA,EAAM,SAAA;AAAA,IACN,KAAA,EAAO,QAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA,GACJ;AAAA,EACA,IAAA,EAAM;AAAA,IACJ,IAAA,EAAM,SAAA;AAAA,IACN,KAAA,EAAO,MAAA;AAAA,IACP,SAAA,EAAW,WAAA;AAAA,IACX,UAAA,EACE;AAAA;AAEN,CAAA;;;ACtBO,IAAM,iBAAA,GAAsE;AAAA,EACjF,MAAA,EAAQ,eAAA;AAAA,EACR,KAAA,EAAO,cAAA;AAAA,EACP,MAAA,EAAQ,cAAA;AAAA,EACR,YAAA,EAAc,qBAAA;AAAA,EACd,QAAA,EAAU,iBAAA;AAAA,EACV,KAAA,EAAO,cAAA;AAAA,EACP,MAAA,EAAQ,eAAA;AAAA,EACR,OAAA,EAAS;AACX,CAAA;AAEO,SAAS,cAAA,CAAe,MAAe,KAAA,EAA4C;AACxF,EAAA,OAAO,iBAAA,CAAkB,IAAI,CAAA,GAAI,KAAK,CAAA;AACxC;;;ACnBA,IAAM,UAAA,GAAwB;AAAA,EAC5B,QAAA;AAAA,EACA,QAAA;AAAA,EACA,OAAA;AAAA,EACA,QAAA;AAAA,EACA,cAAA;AAAA,EACA,UAAA;AAAA,EACA,OAAA;AAAA,EACA;AACF,CAAA;AAEO,SAAS,QAAQ,cAAA,EAAiD;AACvE,EAAA,MAAM,IAAI,cAAA,CAAe,MAAA;AACzB,EAAA,MAAM,UAA6B,EAAC;AAEpC,EAAA,KAAA,MAAW,QAAQ,UAAA,EAAY;AAC7B,IAAA,MAAM,KAAA,GAAQ,EAAE,IAAI,CAAA;AACpB,IAAA,IAAI,CAAC,KAAA,EAAO;AACZ,IAAA,MAAM,IAAA,GAAO,cAAA,CAAe,IAAA,EAAM,KAAK,CAAA;AACvC,IAAA,IAAI,IAAA,EAAM,OAAA,CAAQ,IAAA,CAAK,IAAI,CAAA;AAAA,EAC7B;AAEA,EAAA,MAAM,WAAA,GAAc,QACjB,MAAA,CAAO,CAAC,MAAM,CAAA,CAAE,UAAA,IAAc,EAAE,UAAA,CAAW,IAAA,GAAO,MAAA,GAAS,CAAC,EAC5D,GAAA,CAAI,CAAC,MAAM,CAAA,CAAE,UAAA,CAAY,MAAM,CAAA;AAElC,EAAA,MAAM,mBAAmB,OAAA,CACtB,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,CAAE,qBAAqB,CAAA,CAAE,iBAAA,CAAkB,IAAA,EAAK,CAAE,SAAS,CAAC,CAAA,CAC1E,IAAI,CAAC,CAAA,KAAM,EAAE,iBAAkB,CAAA;AAElC,EAAA,OAAO;AAAA,IACL,UAAA,EAAY,WAAA,CAAY,IAAA,CAAK,MAAM,CAAA;AAAA,IACnC,mBAAA,EAAqB,gBAAA,CAAiB,IAAA,CAAK,EAAE,CAAA;AAAA,IAC7C,SAAA,EAAW;AAAA,GACb;AACF","file":"compose.js","sourcesContent":["// packages/ui-gen/src/fragments/render.ts\n//\n// Render-axis fragments. One per RenderShape. Kept minimal — the stable\n// prefix already covers primitives + design tokens. These only add the\n// per-shape layout pattern the LLM needs to commit to up front.\n\nimport type { HarnessFragment } from \"./types.js\";\n\nexport const renderFragments: Record<string, HarnessFragment> = {\n  static: {\n    axis: \"render\",\n    value: \"static\",\n    cacheTier: \"axisDelta\",\n    // Static = single entity detail. Stable prefix already covers the\n    // obvious pattern (Card + Stack + Heading + fields). No prompt text\n    // here keeps low-risk fixtures fast.\n  },\n  list: {\n    axis: \"render\",\n    value: \"list\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Render: list\\nVertical column of items. Each item is a <Card> with <Row> + <Text>. Use key={item.id} on each item. Do not paginate unless the contract has a fetch tool with cursor/offset.\",\n  },\n  grid: {\n    axis: \"render\",\n    value: \"grid\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Render: grid\\n2D tile layout. Use <CardGrid> or CSS `display: grid` with `grid-template-columns: repeat(N, 1fr)`. If items carry row/col fields, position each tile at (row, col). Do not scroll horizontally.\",\n  },\n  spatial: {\n    axis: \"render\",\n    value: \"spatial\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Render: spatial\\nGeo/coord-positioned items. Use absolute positioning inside a relative container, or a map primitive if available. Normalize coords to the container's bounds. Treat lat/lng as y/x, not strings.\",\n  },\n  timeline: {\n    axis: \"render\",\n    value: \"timeline\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Render: timeline\\nGroup items by day (or other temporal bucket). Render a sticky date header per group, then the grouped items. Sort newest-first unless the contract says otherwise. Memoize the grouping with useMemo.\",\n  },\n  chart: {\n    axis: \"render\",\n    value: \"chart\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Render: chart\\nNumeric → visual. Render with inline SVG (no chart library). Compute the viewBox from data min/max. Add axis labels and one value label on the latest/peak point. Keep it readable on a 400px container.\",\n  },\n  \"master-detail\": {\n    axis: \"render\",\n    value: \"master-detail\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Render: master-detail\\nSplit view: list on one side, detail panel on the other. Track `selectedId` in useState, default to the first item's id. Desktop = side-by-side; mobile/chat shell = stacked with back button.\",\n  },\n};\n","// packages/ui-gen/src/fragments/state.ts\n//\n// State-axis fragments. This is the most error-prone axis — \"merge\" in\n// particular collapses into append-only bugs without explicit guidance.\n\nimport type { HarnessFragment } from \"./types.js\";\n\nexport const stateFragments: Record<string, HarnessFragment> = {\n  none: {\n    axis: \"state\",\n    value: \"none\",\n    cacheTier: \"axisDelta\",\n    // Pure props → JSX. Stable prefix is enough — no useState call at all.\n  },\n  \"ui-affordance\": {\n    axis: \"state\",\n    value: \"ui-affordance\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## State: ui-affordance\\nLocal UI state for filter text / selected id / active tab / quantity. Use useState with a sensible default. Do NOT mirror props into state — read props directly and track only the affordance value.\",\n  },\n  merge: {\n    axis: \"state\",\n    value: \"merge\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## State: merge (live entity reconciliation)\\n1. Seed `const [items, setItems] = useState(props.items ?? [])` AND re-seed on prop change: `useEffect(() => setItems(props.items ?? []), [props.items])` — a `ggui_amend` repaint must move the list.\\n2. On stream updates: `setItems(prev => prev.map(it => it.id === event.id ? { ...it, ...event } : it))` — merge by id, do NOT append.\\n3. Memoize derived views (grouping/sorting/filtering) with useMemo.\\n4. Per-item actions pass `{ id, ... }` in the payload.\\n5. Never push the stream payload into an append-only list unless realtime=append.\",\n    boilerplateMarker: [\n      \"\",\n      \"  // ── Live entity state (merge-by-id) ──\",\n      \"  // useState(props.items ?? []); re-seed via useEffect on [props.items]; merge stream events by item.id; never append.\",\n      \"\",\n    ].join(\"\\n\"),\n  },\n  payload: {\n    axis: \"state\",\n    value: \"payload\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## State: payload (form assembly)\\nAccumulate form fields in a single state object. Validate on blur or on submit — do NOT block keystrokes. The submit action fires once, with the assembled payload.\",\n    boilerplateMarker: [\n      \"\",\n      \"  // ── Form payload ──\",\n      \"  // useState<FormData> seeded with defaults from props or empty; validate on submit.\",\n      \"\",\n    ].join(\"\\n\"),\n  },\n  draft: {\n    axis: \"state\",\n    value: \"draft\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## State: draft (in-place editor)\\nEdit one item at a time. Track `draft` as a separate useState (not mutating the source). Support cancel (discard draft) and save (commit draft → fire action).\",\n  },\n};\n","// packages/ui-gen/src/fragments/writes.ts\n//\n// Writes-axis fragments. Covers both WriteShape (what) and WriteTrigger (how).\n\nimport type { HarnessFragment } from \"./types.js\";\n\nexport const writeFragments: Record<string, HarnessFragment> = {\n  none: {\n    axis: \"writes\",\n    value: \"none\",\n    cacheTier: \"axisDelta\",\n  },\n  commit: {\n    axis: \"writes\",\n    value: \"commit\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Writes: commit\\nOne action with a small payload (e.g., addToCart). Wire useAction on a single Button. Do not block the UI on completion — this is fire-and-forget.\",\n  },\n  \"multi-commit\": {\n    axis: \"writes\",\n    value: \"multi-commit\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Writes: multi-commit\\nMultiple unrelated single-commit actions (e.g., cancel / change destination / contact driver). Each action has its own Button. No shared payload assembly.\",\n  },\n  \"per-item\": {\n    axis: \"writes\",\n    value: \"per-item\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Writes: per-item\\nEach item in the entity list has its own action button(s). The payload must include the item's id. Example: `onClick={() => toggle({ id: item.id, completed: !item.completed })}`.\",\n    boilerplateMarker: [\n      \"\",\n      \"  // ── Per-item actions ──\",\n      \"  // Pass {id, ...} in the payload; wire to a Button inside each item's card.\",\n      \"\",\n    ].join(\"\\n\"),\n  },\n  submit: {\n    axis: \"writes\",\n    value: \"submit\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Writes: submit\\nTerminal form submit. One action fires with the full assembled payload at the end. Disable the submit button while pending and after success.\",\n  },\n  compose: {\n    axis: \"writes\",\n    value: \"compose\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Writes: compose (cross-entity action)\\nOne trigger references ids from two or more entity lists (e.g., {eventId, calendarId}). Track both selections in local state. Only enable the trigger once both are chosen.\",\n  },\n};\n\n// WriteTrigger is a separate axis but lives in the same file for locality.\nexport const writeTriggerFragments: Record<string, HarnessFragment> = {\n  click: {\n    axis: \"writeTrigger\",\n    value: \"click\",\n    cacheTier: \"axisDelta\",\n    // Default case — covered by stable prefix.\n  },\n  drag: {\n    axis: \"writeTrigger\",\n    value: \"drag\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Trigger: drag\\nDrag-drop interaction. Use HTML5 drag events (onDragStart, onDragOver, onDrop) on the item and drop zones. Track the dragged item id in useState. Set data-ggui-draggable on draggable elements. Do NOT pull in an external dnd library.\",\n    boilerplateMarker: [\n      \"\",\n      \"  // ── Drag state ──\",\n      \"  // Track the dragged item id; fire the action on drop with {id, destination}.\",\n      \"\",\n    ].join(\"\\n\"),\n  },\n  swipe: {\n    axis: \"writeTrigger\",\n    value: \"swipe\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Trigger: swipe\\nTouch gesture → one of N actions. Use onTouchStart/onTouchMove/onTouchEnd. Also expose fallback Buttons so desktop users can trigger the same actions by click.\",\n  },\n  keystroke: {\n    axis: \"writeTrigger\",\n    value: \"keystroke\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Trigger: keystroke\\nKeyboard shortcut. Attach onKeyDown to the container (with tabIndex={0}) or use a window listener inside useEffect with cleanup. Document visible shortcuts in the UI.\",\n  },\n  auto: {\n    axis: \"writeTrigger\",\n    value: \"auto\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Trigger: auto\\nEffect-driven. Use useEffect with a debounce (setTimeout + clearTimeout). Do not fire the action on every keystroke.\",\n  },\n};\n","// packages/ui-gen/src/fragments/realtime.ts\n//\n// Realtime-axis fragments. Stream semantics drive whether you merge,\n// append, replace, or do nothing. \"mixed\" needs per-event kind dispatch.\n\nimport type { HarnessFragment } from \"./types.js\";\n\nexport const realtimeFragments: Record<string, HarnessFragment> = {\n  none: {\n    axis: \"realtime\",\n    value: \"none\",\n    cacheTier: \"axisDelta\",\n  },\n  merge: {\n    axis: \"realtime\",\n    value: \"merge\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Realtime: merge\\nStream events carry an id; merge into LOCAL STATE. Subscribing alone is not enough — the local list must update on each event for the DOM to re-render.\\n\\n```tsx\\nconst stream = useStream<UpdateT>('streamName');\\nconst [items, setItems] = useState(props.items);\\nuseEffect(() => setItems(props.items), [props.items]); // re-seed on ggui_amend repaint — props stay the source of truth\\nuseEffect(() => {\\n  if (!stream.latest) return;\\n  setItems((prev) => prev.map((it) => it.id === stream.latest!.id ? { ...it, ...stream.latest } : it));\\n}, [stream.latest]);\\n// Render `items.map(...)` — NOT props.items, NOT stream.all.\\n```\\n\\nNever append — stream=merge means the entity already exists locally.\",\n  },\n  append: {\n    axis: \"realtime\",\n    value: \"append\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Realtime: append\\nStream events are new entities; APPEND to local state. Subscribing alone is not enough — the local list must update for the DOM to re-render.\\n\\n```tsx\\nconst stream = useStream<EventT>('streamName');\\nconst [items, setItems] = useState(props.items);\\nuseEffect(() => setItems(props.items), [props.items]); // re-seed on ggui_amend repaint — props stay the source of truth\\nuseEffect(() => {\\n  if (!stream.latest) return;\\n  setItems((prev) => [...prev, stream.latest!]);\\n}, [stream.latest]);\\n// Render `items.map(...)` — NOT props.items, NOT stream.all (which accumulates only post-mount).\\n```\\n\\nUse head for newest-first, tail for chat-style. Cap list length if needed. Do not dedupe unless the contract guarantees at-most-once.\",\n  },\n  status: {\n    axis: \"realtime\",\n    value: \"status\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Realtime: status\\nStream replaces a singleton (e.g., marketStatus, rideStatus). `stream.latest` is the current value — bind directly into JSX, no local state needed for the singleton itself:\\n\\n```tsx\\nconst statusStream = useStream<StatusT>('streamName');\\nconst status = statusStream.latest;\\n// Render `<Badge>{status?.state ?? 'loading'}</Badge>`.\\n```\\n\\nIf you also need the timestamp of the last update, derive it from `useEffect` on `statusStream.latest`.\",\n  },\n  presence: {\n    axis: \"realtime\",\n    value: \"presence\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Realtime: presence\\nEphemeral per-user state (typing, cursors, online). Do NOT persist to a list. Sync into a `Set` and clear entries based on the active flag or a timeout:\\n\\n```tsx\\nconst stream = useStream<{ sender: string; active: boolean }>('streamName');\\nconst [active, setActive] = useState<Set<string>>(new Set());\\nuseEffect(() => {\\n  if (!stream.latest) return;\\n  setActive((prev) => {\\n    const next = new Set(prev);\\n    if (stream.latest!.active) next.add(stream.latest!.sender);\\n    else next.delete(stream.latest!.sender);\\n    return next;\\n  });\\n}, [stream.latest]);\\n```\",\n  },\n  mixed: {\n    axis: \"realtime\",\n    value: \"mixed\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Realtime: mixed\\nMultiple stream channels with DIFFERENT semantics. Each `streamKinds` entry in the contract maps to one of: merge, append, status, presence. Subscribe + sync to local state PER CHANNEL — subscribing alone never re-renders the DOM.\\n\\nExample (chat-interface — message=append, typing=presence):\\n\\n```tsx\\nconst messages = useStream<MessageT>('message');\\nconst typing = useStream<TypingT>('typing');\\nconst [messageList, setMessageList] = useState(props.messages);\\nconst [typingUsers, setTypingUsers] = useState<Set<string>>(new Set());\\n\\nuseEffect(() => setMessageList(props.messages), [props.messages]); // re-seed on ggui_amend repaint\\n\\nuseEffect(() => {\\n  if (!messages.latest) return;\\n  setMessageList((prev) => [...prev, messages.latest!]);\\n}, [messages.latest]);\\n\\nuseEffect(() => {\\n  if (!typing.latest) return;\\n  setTypingUsers((prev) => {\\n    const next = new Set(prev);\\n    if (typing.latest!.active) next.add(typing.latest!.sender);\\n    else next.delete(typing.latest!.sender);\\n    return next;\\n  });\\n}, [typing.latest]);\\n```\\n\\nDo NOT treat all events the same. Do NOT skip the local-state sync — `useStream` alone won't trigger DOM updates of your derived view.\",\n    boilerplateMarker: [\n      \"\",\n      \"  // ── Mixed stream handlers ──\",\n      \"  // One useStream + useEffect+setState per channel — see realtime fragment.\",\n      \"\",\n    ].join(\"\\n\"),\n  },\n};\n","// packages/ui-gen/src/fragments/fetch.ts\n//\n// Fetch-axis fragments. Covers how the component reacts to agent-fetched\n// data — agent-side tools live in `agentCapabilities.tools` (catalog\n// only); the component itself never invokes them directly.\n\nimport type { HarnessFragment } from \"./types.js\";\n\nexport const fetchFragments: Record<string, HarnessFragment> = {\n  none: {\n    axis: \"fetch\",\n    value: \"none\",\n    cacheTier: \"axisDelta\",\n  },\n  pagination: {\n    axis: \"fetch\",\n    value: \"pagination\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Fetch: pagination\\nTrack `cursor` (or offset/page) in useState. Expose a 'Load more' Button that calls the tool with the next cursor and appends results. Show a spinner while tool.isPending.\",\n  },\n  search: {\n    axis: \"fetch\",\n    value: \"search\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Fetch: search\\nDebounced query → tool call. Track `query` in useState; fire the tool inside useEffect after a 300ms debounce. Replace (don't append) results on each call. Guard against stale responses.\",\n  },\n  \"drill-down\": {\n    axis: \"fetch\",\n    value: \"drill-down\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Fetch: drill-down\\nOn item click, call the tool with the item's id and show the detail. Track `selectedId` and `detail` separately; render a loading placeholder while tool.isPending.\",\n  },\n  refresh: {\n    axis: \"fetch\",\n    value: \"refresh\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Fetch: refresh\\nUser-triggered re-fetch (e.g., pull-to-refresh or a Refresh button). Re-call the tool with the same args; show a small spinner while pending.\",\n  },\n};\n","// packages/ui-gen/src/fragments/layout.ts\n//\n// Layout-axis fragments. Structural composition — how the screen is split.\n\nimport type { HarnessFragment } from \"./types.js\";\n\nexport const layoutFragments: Record<string, HarnessFragment> = {\n  single: {\n    axis: \"layout\",\n    value: \"single\",\n    cacheTier: \"axisDelta\",\n  },\n  \"multi-step\": {\n    axis: \"layout\",\n    value: \"multi-step\",\n    cacheTier: \"axisDelta\",\n    // 2026-04-27: anti-pattern warnings added after 6× n=3 benches showed\n    // survey-form + onboarding-wizard accounted for 9 of 11 probe FAILs\n    // (\"Too many re-renders\" 6×, \"function is not iterable\" 2×, TDZ 1×).\n    // All 3 classes trace to the same multi-step-specific anti-patterns\n    // below; non-multi-step fixtures had 0 fails across the same benches.\n    promptText:\n      \"## Layout: multi-step\\n\" +\n      \"Wizard. Track `step` in useState (0-indexed). Render \" +\n      \"`<Stepper steps={STEPS} current={step} />` as the progress \" +\n      \"indicator — do NOT hand-roll a '2 of 4' counter, and do NOT \" +\n      \"reach for Tabs/Progress/Breadcrumb. Stepper is display-only: \" +\n      \"your Next/Back buttons move `step`. Keep all step state in a \" +\n      \"single payload object; do NOT reset previous-step data on \" +\n      \"navigation.\\n\\n\" +\n      \"### Anti-patterns that crash at runtime — DO NOT do these:\\n\\n\" +\n      \"1. **No setState in render body** — causes 'Too many re-renders'.\\n\" +\n      \"```tsx\\n\" +\n      \"// ❌ WRONG — fires every render, infinite loop\\n\" +\n      \"const Form = () => {\\n\" +\n      \"  const [errors, setErrors] = useState({});\\n\" +\n      \"  setErrors(validate(values));  // setState in render → loop\\n\" +\n      \"};\\n\" +\n      \"// ✅ RIGHT — derive with useMemo (no state)\\n\" +\n      \"const Form = () => {\\n\" +\n      \"  const errors = useMemo(() => validate(values), [values]);\\n\" +\n      \"};\\n\" +\n      \"```\\n\\n\" +\n      \"2. **No setState in useEffect with state-derived deps** — also \" +\n      \"causes 'Too many re-renders'.\\n\" +\n      \"```tsx\\n\" +\n      \"// ❌ WRONG — payload identity changes → setIsValid → re-render → ...\\n\" +\n      \"useEffect(() => { setIsValid(check(payload)); }, [payload]);\\n\" +\n      \"// ✅ RIGHT — useMemo, no setState\\n\" +\n      \"const isValid = useMemo(() => check(payload), [payload]);\\n\" +\n      \"```\\n\\n\" +\n      \"3. **Declare `steps` array as a top-level `const`, NEVER state.** \" +\n      \"Default arrays (`fields`, `options`) the same way. Iterating over \" +\n      \"an undefined or unstable array throws 'function is not iterable'.\\n\" +\n      \"```tsx\\n\" +\n      \"// ❌ WRONG — useState('steps array...') is a string, .map crashes\\n\" +\n      \"const [steps] = useState('Welcome,Profile,Done');\\n\" +\n      \"// ✅ RIGHT — top-level const\\n\" +\n      \"const STEPS = ['Welcome', 'Profile', 'Done'] as const;\\n\" +\n      \"```\\n\\n\" +\n      \"4. **Hooks/`const` declarations come BEFORE any useEffect/\" +\n      \"useMemo/useCallback that reads them.** Otherwise: TDZ 'Cannot \" +\n      \"access X before initialization'.\\n\" +\n      \"```tsx\\n\" +\n      \"// ❌ WRONG — useEffect reads `total` before its `const` line\\n\" +\n      \"useEffect(() => log(total), [total]);\\n\" +\n      \"const total = items.reduce(sum, 0);\\n\" +\n      \"// ✅ RIGHT — declare first, read after\\n\" +\n      \"const total = items.reduce(sum, 0);\\n\" +\n      \"useEffect(() => log(total), [total]);\\n\" +\n      \"```\",\n  },\n  \"master-detail\": {\n    axis: \"layout\",\n    value: \"master-detail\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Layout: master-detail\\nSplit container: master list on the left/top, detail panel on the right/bottom. Track `selectedId` and show a 'select an item' placeholder in the detail panel when null.\",\n  },\n  overlay: {\n    axis: \"layout\",\n    value: \"overlay\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Layout: overlay\\nFloating controls layered on top of content. Use position: absolute with explicit insets. Ensure the overlay does not block critical content (leave a safe area).\",\n  },\n  modal: {\n    axis: \"layout\",\n    value: \"modal\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Layout: modal\\nUse the <Modal> primitive. Track `isOpen` in useState. Provide a clear close affordance (X button + clicking backdrop). Trap focus inside the modal.\",\n  },\n};\n","// packages/ui-gen/src/fragments/tooling.ts\n//\n// tooling-axis fragments. The contract carries two tooling surfaces:\n//\n//   - `agentCapabilities.tools` — catalog of agent-invoked tools the\n//     contract references via `actionSpec[*].nextStep` and\n//     `streamSpec[*].source.tool`. NO component-side hook surface.\n//   - `clientCapabilities.gadgets` — catalog of browser-capability\n//     gadget hooks (geolocation, mic, camera, clipboard, file picker,\n//     notifications). The component imports + calls these hooks\n//     from `@ggui-ai/gadgets` (or the third-party package named in\n//     `entry.package`).\n//\n// The `wired` / `client` / `both` axis values map onto these surfaces\n// by what the contract carries; the prompt text steers the LLM toward\n// the correct patterns.\n\nimport type { HarnessFragment } from \"./types.js\";\n\nexport const toolingFragments: Record<string, HarnessFragment> = {\n  none: {\n    axis: \"tooling\",\n    value: \"none\",\n    cacheTier: \"axisDelta\",\n    // Nothing to say — contract carries no agentCapabilities.tools /\n    // clientCapabilities.gadgets.\n  },\n  wired: {\n    axis: \"tooling\",\n    value: \"wired\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Tooling: agent-side tools (catalog only)\\nThe contract declares `agentCapabilities.tools[X]` for tools the AGENT invokes — the component never calls these directly. References surface via `actionSpec[Y].nextStep = 'X'` (the agent's next-turn hint forwarded on action events) and `streamSpec[Z].source.tool = 'X'` (the runtime polls / subscribes the tool, deliveries land on the stream channel). Author UI controls fire actions via `useAction`; data feeds appear via `useStream`. The `useWiredTool` hook from before 2026-05-11 is RETIRED.\",\n  },\n  client: {\n    axis: \"tooling\",\n    value: \"client\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Tooling: gadgets (browser-capability hooks)\\nThe contract declares `clientCapabilities.gadgets[X]` for browser-capability gadget hooks the UI mounts. The boilerplate has pre-emitted a direct import per gadget package — `import { useFoo, useBar } from '<package>';` — above a `// DO NOT EDIT` banner (STDLIB hooks come from `@ggui-ai/gadgets`, third-party hooks from the package on `clientCapabilities.gadgets[*].package`). Call the imported hook inside the component (`const loc = useGeolocation();`) and trigger via `.start()` from a UI control. Read `.value` / `.status` to render. If the agent needs to observe the result, thread `.value` into a `contextSpec` slot or an `actionSpec` payload. Library hooks are UI-owned lifecycle; the agent never invokes them. **KEEP every pre-emitted gadget import — do NOT delete it and do NOT change its package**; self_check rejects the code with `gadget_preservation:<hook>` if a gadget import disappears. The pre-2026-05-11 `useClientTool(name, handler)` shape is RETIRED, as is the `@ggui-ai/client-tools` package name (renamed to `@ggui-ai/gadgets`).\",\n  },\n  both: {\n    axis: \"tooling\",\n    value: \"both\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Tooling: both surfaces present\\nThe contract declares BOTH `agentCapabilities.tools` (agent-invoked catalog; referenced via `actionSpec.nextStep` / `streamSpec.source.tool` — NO component hook) AND `clientCapabilities.gadgets` (browser-capability gadget hooks the component direct-imports — the boilerplate pre-emits `import { useCamera } from '@ggui-ai/gadgets';` (STDLIB) or `import { useFoo } from '<package>';` (third-party) above a `// DO NOT EDIT` banner). Don't conflate: agentCapabilities entries are catalog declarations the agent uses, NOT component hooks. clientCapabilities entries DO emit component-side hook calls (e.g., `const cam = useCamera();`).\",\n  },\n};\n","// packages/ui-gen/src/fragments/index.ts\n//\n// Public barrel for the `@ggui-ai/ui-gen/fragments` subpath.\n//\n// Stable public surface (what external consumers should build against):\n//   - `FRAGMENT_REGISTRY`  — the axis-keyed registry\n//   - `lookupFragment`     — the one-call lookup helper\n//   - fragment types       — HarnessFragment, ComposedHarness, CacheTier, AxisKey\n//\n// Per-axis fragment records (renderFragments, stateFragments, etc.) are\n// intentionally NOT re-exported here — consumers who genuinely need one\n// can read `FRAGMENT_REGISTRY.render` / `.state` / etc. Keeping the public\n// surface to a single entry point preserves our freedom to reshape the\n// per-axis files without breaking semver.\n\nimport type { AxisKey, HarnessFragment } from \"./types.js\";\nimport { renderFragments } from \"./render.js\";\nimport { stateFragments } from \"./state.js\";\nimport { writeFragments, writeTriggerFragments } from \"./writes.js\";\nimport { realtimeFragments } from \"./realtime.js\";\nimport { fetchFragments } from \"./fetch.js\";\nimport { layoutFragments } from \"./layout.js\";\nimport { toolingFragments } from \"./tooling.js\";\n\nexport type { HarnessFragment, ComposedHarness, CacheTier, AxisKey } from \"./types.js\";\n\nexport const FRAGMENT_REGISTRY: Record<AxisKey, Record<string, HarnessFragment>> = {\n  render: renderFragments,\n  state: stateFragments,\n  writes: writeFragments,\n  writeTrigger: writeTriggerFragments,\n  realtime: realtimeFragments,\n  fetch: fetchFragments,\n  layout: layoutFragments,\n  tooling: toolingFragments,\n};\n\nexport function lookupFragment(axis: AxisKey, value: string): HarnessFragment | undefined {\n  return FRAGMENT_REGISTRY[axis]?.[value];\n}\n","// packages/ui-gen/src/compose.ts\n//\n// Materializes a Classification into prompt sections + boilerplate markers.\n// Sits between the stable prefix (design system docs, pitfalls) and the\n// volatile feedback (eval issues) in the system prompt's cache tiering.\n//\n// Consumes the `./classifier` and `./fragments` subpaths — it's the\n// bridge between an axis vector and the prompt/boilerplate the LLM\n// actually sees.\n\nimport type { Classification } from \"./classifier/axes.js\";\nimport {\n  lookupFragment,\n  type AxisKey,\n  type ComposedHarness,\n  type HarnessFragment,\n} from \"./fragments/index.js\";\n\n// Axis processing order inside axisDelta. Puts the most behaviourally\n// consequential axes first so the LLM reads them before scanning details.\nconst AXIS_ORDER: AxisKey[] = [\n  \"render\",\n  \"layout\",\n  \"state\",\n  \"writes\",\n  \"writeTrigger\",\n  \"realtime\",\n  \"fetch\",\n  \"tooling\",\n];\n\nexport function compose(classification: Classification): ComposedHarness {\n  const v = classification.vector;\n  const matched: HarnessFragment[] = [];\n\n  for (const axis of AXIS_ORDER) {\n    const value = v[axis] as string | undefined;\n    if (!value) continue;\n    const frag = lookupFragment(axis, value);\n    if (frag) matched.push(frag);\n  }\n\n  const promptParts = matched\n    .filter((f) => f.promptText && f.promptText.trim().length > 0)\n    .map((f) => f.promptText!.trim());\n\n  const boilerplateParts = matched\n    .filter((f) => f.boilerplateMarker && f.boilerplateMarker.trim().length > 0)\n    .map((f) => f.boilerplateMarker!);\n\n  return {\n    promptText: promptParts.join(\"\\n\\n\"),\n    boilerplateSections: boilerplateParts.join(\"\"),\n    fragments: matched,\n  };\n}\n\nexport type { ComposedHarness };\n"]}
+{"version":3,"sources":["../src/fragments/render.ts","../src/fragments/state.ts","../src/fragments/writes.ts","../src/fragments/realtime.ts","../src/fragments/fetch.ts","../src/fragments/layout.ts","../src/fragments/tooling.ts","../src/fragments/index.ts","../src/compose.ts"],"names":[],"mappings":"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","file":"compose.js","sourcesContent":["// packages/ui-gen/src/fragments/render.ts\n//\n// Render-axis fragments. One per RenderShape. Kept minimal — the stable\n// prefix already covers primitives + design tokens. These only add the\n// per-shape layout pattern the LLM needs to commit to up front.\n\nimport type { HarnessFragment } from \"./types.js\";\n\nexport const renderFragments: Record<string, HarnessFragment> = {\n  static: {\n    axis: \"render\",\n    value: \"static\",\n    cacheTier: \"axisDelta\",\n    // Static = single entity detail. Stable prefix already covers the\n    // obvious pattern (Card + Stack + Heading + fields). No prompt text\n    // here keeps low-risk fixtures fast.\n  },\n  list: {\n    axis: \"render\",\n    value: \"list\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Render: list\\nVertical column of items. Each item is a <Card> with <Row> + <Text>. Use key={item.id} on each item. Do not paginate unless the contract has a fetch tool with cursor/offset.\",\n  },\n  grid: {\n    axis: \"render\",\n    value: \"grid\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Render: grid\\nTwo shapes share this axis — read the contract:\\n- A TILE grid (a gallery, a stat grid, items that may carry row/col fields): `<Grid columns={N} gap=\\\"md\\\">` (or `<CardGrid>`); if items carry row/col fields, position each tile at (row, col).\\n- A BOARD (a columns / lanes / stages array whose items are cards — a kanban): the columns sit SIDE BY SIDE at md and wider — `<Grid columns={{ base: 1, md: columns.length }} gap=\\\"md\\\">` wrapping the columns map, each column its own `<Stack>` of `<Card>`s with its header and count; NEVER a `<Stack>` of column sections (that is a list — tier-0 fails it).\\nNever hand-roll `display: grid`. Do not scroll horizontally.\",\n  },\n  spatial: {\n    axis: \"render\",\n    value: \"spatial\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Render: spatial\\nGeo/coord-positioned items. Use absolute positioning inside a relative container, or a map primitive if available. Normalize coords to the container's bounds. Treat lat/lng as y/x, not strings.\",\n  },\n  timeline: {\n    axis: \"render\",\n    value: \"timeline\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Render: timeline\\nGroup items by day (or other temporal bucket). Render a sticky date header per group, then the grouped items. Sort newest-first unless the contract says otherwise. Memoize the grouping with useMemo.\",\n  },\n  chart: {\n    axis: \"render\",\n    value: \"chart\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Render: chart\\nNumeric → visual. Render with inline SVG (no chart library). Compute the viewBox from data min/max. Add axis labels and one value label on the latest/peak point. Keep it readable on a 400px container.\",\n  },\n  \"master-detail\": {\n    axis: \"render\",\n    value: \"master-detail\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Render: master-detail\\nSplit view: list on one side, detail panel on the other. Track `selectedId` in useState, default to the first item's id. Desktop = side-by-side; mobile/chat shell = stacked with back button.\",\n  },\n};\n","// packages/ui-gen/src/fragments/state.ts\n//\n// State-axis fragments. This is the most error-prone axis — \"merge\" in\n// particular collapses into append-only bugs without explicit guidance.\n\nimport type { HarnessFragment } from \"./types.js\";\n\nexport const stateFragments: Record<string, HarnessFragment> = {\n  none: {\n    axis: \"state\",\n    value: \"none\",\n    cacheTier: \"axisDelta\",\n    // Pure props → JSX. Stable prefix is enough — no useState call at all.\n  },\n  \"ui-affordance\": {\n    axis: \"state\",\n    value: \"ui-affordance\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## State: ui-affordance\\nLocal UI state for filter text / selected id / active tab / quantity. Use useState with a sensible default. Do NOT mirror props into state — read props directly and track only the affordance value.\",\n  },\n  merge: {\n    axis: \"state\",\n    value: \"merge\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## State: merge (live entity reconciliation)\\n1. Seed `const [items, setItems] = useState(props.items ?? [])` AND re-seed on prop change: `useEffect(() => setItems(props.items ?? []), [props.items])` — a `ggui_amend` repaint must move the list.\\n2. On stream updates: `setItems(prev => prev.map(it => it.id === event.id ? { ...it, ...event } : it))` — merge by id, do NOT append.\\n3. Memoize derived views (grouping/sorting/filtering) with useMemo.\\n4. Per-item actions pass `{ id, ... }` in the payload.\\n5. Never push the stream payload into an append-only list unless realtime=append.\",\n    boilerplateMarker: [\n      \"\",\n      \"  // ── Live entity state (merge-by-id) ──\",\n      \"  // useState(props.items ?? []); re-seed via useEffect on [props.items]; merge stream events by item.id; never append.\",\n      \"\",\n    ].join(\"\\n\"),\n  },\n  payload: {\n    axis: \"state\",\n    value: \"payload\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## State: payload (form assembly)\\nAccumulate form fields in a single state object. Validate on blur or on submit — do NOT block keystrokes. The submit action fires once, with the assembled payload.\",\n    boilerplateMarker: [\n      \"\",\n      \"  // ── Form payload ──\",\n      \"  // useState<FormData> seeded with defaults from props or empty; validate on submit.\",\n      \"\",\n    ].join(\"\\n\"),\n  },\n  draft: {\n    axis: \"state\",\n    value: \"draft\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## State: draft (in-place editor)\\nEdit one item at a time. Track `draft` as a separate useState (not mutating the source). Support cancel (discard draft) and save (commit draft → fire action).\",\n  },\n};\n","// packages/ui-gen/src/fragments/writes.ts\n//\n// Writes-axis fragments. Covers both WriteShape (what) and WriteTrigger (how).\n\nimport type { HarnessFragment } from \"./types.js\";\n\nexport const writeFragments: Record<string, HarnessFragment> = {\n  none: {\n    axis: \"writes\",\n    value: \"none\",\n    cacheTier: \"axisDelta\",\n  },\n  commit: {\n    axis: \"writes\",\n    value: \"commit\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Writes: commit\\nOne action with a small payload (e.g., addToCart). Wire useAction on a single Button. Do not block the UI on completion — this is fire-and-forget.\",\n  },\n  \"multi-commit\": {\n    axis: \"writes\",\n    value: \"multi-commit\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Writes: multi-commit\\nMultiple unrelated single-commit actions (e.g., cancel / change destination / contact driver). Each action has its own Button. No shared payload assembly.\",\n  },\n  \"per-item\": {\n    axis: \"writes\",\n    value: \"per-item\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Writes: per-item\\nEach item in the entity list has its own action button(s). The payload must include the item's id. Example: `onClick={() => toggle({ id: item.id, completed: !item.completed })}`.\",\n    boilerplateMarker: [\n      \"\",\n      \"  // ── Per-item actions ──\",\n      \"  // Pass {id, ...} in the payload; wire to a Button inside each item's card.\",\n      \"\",\n    ].join(\"\\n\"),\n  },\n  submit: {\n    axis: \"writes\",\n    value: \"submit\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Writes: submit\\nTerminal form submit. One action fires with the full assembled payload at the end. Disable the submit button while pending and after success.\",\n  },\n  compose: {\n    axis: \"writes\",\n    value: \"compose\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Writes: compose (cross-entity action)\\nOne trigger references ids from two or more entity lists (e.g., {eventId, calendarId}). Track both selections in local state. Only enable the trigger once both are chosen.\",\n  },\n};\n\n// WriteTrigger is a separate axis but lives in the same file for locality.\nexport const writeTriggerFragments: Record<string, HarnessFragment> = {\n  click: {\n    axis: \"writeTrigger\",\n    value: \"click\",\n    cacheTier: \"axisDelta\",\n    // Default case — covered by stable prefix.\n  },\n  drag: {\n    axis: \"writeTrigger\",\n    value: \"drag\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Trigger: drag\\nDrag-drop interaction. Use HTML5 drag events (onDragStart, onDragOver, onDrop) on the item and drop zones. Track the dragged item id in useState. Set data-ggui-draggable on draggable elements. Do NOT pull in an external dnd library.\",\n    boilerplateMarker: [\n      \"\",\n      \"  // ── Drag state ──\",\n      \"  // Track the dragged item id; fire the action on drop with {id, destination}.\",\n      \"\",\n    ].join(\"\\n\"),\n  },\n  swipe: {\n    axis: \"writeTrigger\",\n    value: \"swipe\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Trigger: swipe\\nTouch gesture → one of N actions. Use onTouchStart/onTouchMove/onTouchEnd. Also expose fallback Buttons so desktop users can trigger the same actions by click.\",\n  },\n  keystroke: {\n    axis: \"writeTrigger\",\n    value: \"keystroke\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Trigger: keystroke\\nKeyboard shortcut. Attach onKeyDown to the container (with tabIndex={0}) or use a window listener inside useEffect with cleanup. Document visible shortcuts in the UI.\",\n  },\n  auto: {\n    axis: \"writeTrigger\",\n    value: \"auto\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Trigger: auto\\nEffect-driven. Use useEffect with a debounce (setTimeout + clearTimeout). Do not fire the action on every keystroke.\",\n  },\n};\n","// packages/ui-gen/src/fragments/realtime.ts\n//\n// Realtime-axis fragments. Stream semantics drive whether you merge,\n// append, replace, or do nothing. \"mixed\" needs per-event kind dispatch.\n\nimport type { HarnessFragment } from \"./types.js\";\n\nexport const realtimeFragments: Record<string, HarnessFragment> = {\n  none: {\n    axis: \"realtime\",\n    value: \"none\",\n    cacheTier: \"axisDelta\",\n  },\n  merge: {\n    axis: \"realtime\",\n    value: \"merge\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Realtime: merge\\nStream events carry an id; merge into LOCAL STATE. Subscribing alone is not enough — the local list must update on each event for the DOM to re-render.\\n\\n```tsx\\nconst stream = useStream<UpdateT>('streamName');\\nconst [items, setItems] = useState(props.items);\\nuseEffect(() => setItems(props.items), [props.items]); // re-seed on ggui_amend repaint — props stay the source of truth\\nuseEffect(() => {\\n  if (!stream.latest) return;\\n  setItems((prev) => prev.map((it) => it.id === stream.latest!.id ? { ...it, ...stream.latest } : it));\\n}, [stream.latest]);\\n// Render `items.map(...)` — NOT props.items, NOT stream.all.\\n```\\n\\nNever append — stream=merge means the entity already exists locally.\",\n  },\n  append: {\n    axis: \"realtime\",\n    value: \"append\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Realtime: append\\nStream events are new entities; APPEND to local state. Subscribing alone is not enough — the local list must update for the DOM to re-render.\\n\\n```tsx\\nconst stream = useStream<EventT>('streamName');\\nconst [items, setItems] = useState(props.items);\\nuseEffect(() => setItems(props.items), [props.items]); // re-seed on ggui_amend repaint — props stay the source of truth\\nuseEffect(() => {\\n  if (!stream.latest) return;\\n  setItems((prev) => [...prev, stream.latest!]);\\n}, [stream.latest]);\\n// Render `items.map(...)` — NOT props.items, NOT stream.all (which accumulates only post-mount).\\n```\\n\\nUse head for newest-first, tail for chat-style. Cap list length if needed. Do not dedupe unless the contract guarantees at-most-once.\",\n  },\n  status: {\n    axis: \"realtime\",\n    value: \"status\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Realtime: status\\nStream replaces a singleton (e.g., marketStatus, rideStatus). `stream.latest` is the current value — bind directly into JSX, no local state needed for the singleton itself:\\n\\n```tsx\\nconst statusStream = useStream<StatusT>('streamName');\\nconst status = statusStream.latest;\\n// Render `<Badge>{status?.state ?? 'loading'}</Badge>`.\\n```\\n\\nIf you also need the timestamp of the last update, derive it from `useEffect` on `statusStream.latest`.\",\n  },\n  presence: {\n    axis: \"realtime\",\n    value: \"presence\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Realtime: presence\\nEphemeral per-user state (typing, cursors, online). Do NOT persist to a list. Sync into a `Set` and clear entries based on the active flag or a timeout:\\n\\n```tsx\\nconst stream = useStream<{ sender: string; active: boolean }>('streamName');\\nconst [active, setActive] = useState<Set<string>>(new Set());\\nuseEffect(() => {\\n  if (!stream.latest) return;\\n  setActive((prev) => {\\n    const next = new Set(prev);\\n    if (stream.latest!.active) next.add(stream.latest!.sender);\\n    else next.delete(stream.latest!.sender);\\n    return next;\\n  });\\n}, [stream.latest]);\\n```\",\n  },\n  mixed: {\n    axis: \"realtime\",\n    value: \"mixed\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Realtime: mixed\\nMultiple stream channels with DIFFERENT semantics. Each `streamKinds` entry in the contract maps to one of: merge, append, status, presence. Subscribe + sync to local state PER CHANNEL — subscribing alone never re-renders the DOM.\\n\\nExample (chat-interface — message=append, typing=presence):\\n\\n```tsx\\nconst messages = useStream<MessageT>('message');\\nconst typing = useStream<TypingT>('typing');\\nconst [messageList, setMessageList] = useState(props.messages);\\nconst [typingUsers, setTypingUsers] = useState<Set<string>>(new Set());\\n\\nuseEffect(() => setMessageList(props.messages), [props.messages]); // re-seed on ggui_amend repaint\\n\\nuseEffect(() => {\\n  if (!messages.latest) return;\\n  setMessageList((prev) => [...prev, messages.latest!]);\\n}, [messages.latest]);\\n\\nuseEffect(() => {\\n  if (!typing.latest) return;\\n  setTypingUsers((prev) => {\\n    const next = new Set(prev);\\n    if (typing.latest!.active) next.add(typing.latest!.sender);\\n    else next.delete(typing.latest!.sender);\\n    return next;\\n  });\\n}, [typing.latest]);\\n```\\n\\nDo NOT treat all events the same. Do NOT skip the local-state sync — `useStream` alone won't trigger DOM updates of your derived view.\",\n    boilerplateMarker: [\n      \"\",\n      \"  // ── Mixed stream handlers ──\",\n      \"  // One useStream + useEffect+setState per channel — see realtime fragment.\",\n      \"\",\n    ].join(\"\\n\"),\n  },\n};\n","// packages/ui-gen/src/fragments/fetch.ts\n//\n// Fetch-axis fragments. Covers how the component reacts to agent-fetched\n// data — agent-side tools live in `agentCapabilities.tools` (catalog\n// only); the component itself never invokes them directly.\n\nimport type { HarnessFragment } from \"./types.js\";\n\nexport const fetchFragments: Record<string, HarnessFragment> = {\n  none: {\n    axis: \"fetch\",\n    value: \"none\",\n    cacheTier: \"axisDelta\",\n  },\n  pagination: {\n    axis: \"fetch\",\n    value: \"pagination\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Fetch: pagination\\nTrack `cursor` (or offset/page) in useState. Expose a 'Load more' Button that calls the tool with the next cursor and appends results. Show a spinner while tool.isPending.\",\n  },\n  search: {\n    axis: \"fetch\",\n    value: \"search\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Fetch: search\\nDebounced query → tool call. Track `query` in useState; fire the tool inside useEffect after a 300ms debounce. Replace (don't append) results on each call. Guard against stale responses.\",\n  },\n  \"drill-down\": {\n    axis: \"fetch\",\n    value: \"drill-down\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Fetch: drill-down\\nOn item click, call the tool with the item's id and show the detail. Track `selectedId` and `detail` separately; render a loading placeholder while tool.isPending.\",\n  },\n  refresh: {\n    axis: \"fetch\",\n    value: \"refresh\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Fetch: refresh\\nUser-triggered re-fetch (e.g., pull-to-refresh or a Refresh button). Re-call the tool with the same args; show a small spinner while pending.\",\n  },\n};\n","// packages/ui-gen/src/fragments/layout.ts\n//\n// Layout-axis fragments. Structural composition — how the screen is split.\n\nimport type { HarnessFragment } from \"./types.js\";\n\nexport const layoutFragments: Record<string, HarnessFragment> = {\n  single: {\n    axis: \"layout\",\n    value: \"single\",\n    cacheTier: \"axisDelta\",\n  },\n  \"multi-step\": {\n    axis: \"layout\",\n    value: \"multi-step\",\n    cacheTier: \"axisDelta\",\n    // 2026-04-27: anti-pattern warnings added after 6× n=3 benches showed\n    // survey-form + onboarding-wizard accounted for 9 of 11 probe FAILs\n    // (\"Too many re-renders\" 6×, \"function is not iterable\" 2×, TDZ 1×).\n    // All 3 classes trace to the same multi-step-specific anti-patterns\n    // below; non-multi-step fixtures had 0 fails across the same benches.\n    promptText:\n      \"## Layout: multi-step\\n\" +\n      \"Wizard. Track `step` in useState (0-indexed). Render \" +\n      \"`<Stepper steps={STEPS} current={step} />` as the progress \" +\n      \"indicator — do NOT hand-roll a '2 of 4' counter, and do NOT \" +\n      \"reach for Tabs/Progress/Breadcrumb. Stepper is display-only: \" +\n      \"your Next/Back buttons move `step`. Keep all step state in a \" +\n      \"single payload object; do NOT reset previous-step data on \" +\n      \"navigation.\\n\\n\" +\n      \"### Anti-patterns that crash at runtime — DO NOT do these:\\n\\n\" +\n      \"1. **No setState in render body** — causes 'Too many re-renders'.\\n\" +\n      \"```tsx\\n\" +\n      \"// ❌ WRONG — fires every render, infinite loop\\n\" +\n      \"const Form = () => {\\n\" +\n      \"  const [errors, setErrors] = useState({});\\n\" +\n      \"  setErrors(validate(values));  // setState in render → loop\\n\" +\n      \"};\\n\" +\n      \"// ✅ RIGHT — derive with useMemo (no state)\\n\" +\n      \"const Form = () => {\\n\" +\n      \"  const errors = useMemo(() => validate(values), [values]);\\n\" +\n      \"};\\n\" +\n      \"```\\n\\n\" +\n      \"2. **No setState in useEffect with state-derived deps** — also \" +\n      \"causes 'Too many re-renders'.\\n\" +\n      \"```tsx\\n\" +\n      \"// ❌ WRONG — payload identity changes → setIsValid → re-render → ...\\n\" +\n      \"useEffect(() => { setIsValid(check(payload)); }, [payload]);\\n\" +\n      \"// ✅ RIGHT — useMemo, no setState\\n\" +\n      \"const isValid = useMemo(() => check(payload), [payload]);\\n\" +\n      \"```\\n\\n\" +\n      \"3. **Declare `steps` array as a top-level `const`, NEVER state.** \" +\n      \"Default arrays (`fields`, `options`) the same way. Iterating over \" +\n      \"an undefined or unstable array throws 'function is not iterable'.\\n\" +\n      \"```tsx\\n\" +\n      \"// ❌ WRONG — useState('steps array...') is a string, .map crashes\\n\" +\n      \"const [steps] = useState('Welcome,Profile,Done');\\n\" +\n      \"// ✅ RIGHT — top-level const\\n\" +\n      \"const STEPS = ['Welcome', 'Profile', 'Done'] as const;\\n\" +\n      \"```\\n\\n\" +\n      \"4. **Hooks/`const` declarations come BEFORE any useEffect/\" +\n      \"useMemo/useCallback that reads them.** Otherwise: TDZ 'Cannot \" +\n      \"access X before initialization'.\\n\" +\n      \"```tsx\\n\" +\n      \"// ❌ WRONG — useEffect reads `total` before its `const` line\\n\" +\n      \"useEffect(() => log(total), [total]);\\n\" +\n      \"const total = items.reduce(sum, 0);\\n\" +\n      \"// ✅ RIGHT — declare first, read after\\n\" +\n      \"const total = items.reduce(sum, 0);\\n\" +\n      \"useEffect(() => log(total), [total]);\\n\" +\n      \"```\",\n  },\n  \"master-detail\": {\n    axis: \"layout\",\n    value: \"master-detail\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Layout: master-detail\\nSplit container: master list on the left/top, detail panel on the right/bottom. Track `selectedId` and show a 'select an item' placeholder in the detail panel when null.\",\n  },\n  overlay: {\n    axis: \"layout\",\n    value: \"overlay\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Layout: overlay\\nFloating controls layered on top of content. Use position: absolute with explicit insets. Ensure the overlay does not block critical content (leave a safe area).\",\n  },\n  modal: {\n    axis: \"layout\",\n    value: \"modal\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Layout: modal\\nUse the <Modal> primitive. Track `isOpen` in useState. Provide a clear close affordance (X button + clicking backdrop). Trap focus inside the modal.\",\n  },\n};\n","// packages/ui-gen/src/fragments/tooling.ts\n//\n// tooling-axis fragments. The contract carries two tooling surfaces:\n//\n//   - `agentCapabilities.tools` — catalog of agent-invoked tools the\n//     contract references via `actionSpec[*].nextStep` and\n//     `streamSpec[*].source.tool`. NO component-side hook surface.\n//   - `clientCapabilities.gadgets` — catalog of browser-capability\n//     gadget hooks (geolocation, mic, camera, clipboard, file picker,\n//     notifications). The component imports + calls these hooks\n//     from `@ggui-ai/gadgets` (or the third-party package named in\n//     `entry.package`).\n//\n// The `wired` / `client` / `both` axis values map onto these surfaces\n// by what the contract carries; the prompt text steers the LLM toward\n// the correct patterns.\n\nimport type { HarnessFragment } from \"./types.js\";\n\nexport const toolingFragments: Record<string, HarnessFragment> = {\n  none: {\n    axis: \"tooling\",\n    value: \"none\",\n    cacheTier: \"axisDelta\",\n    // Nothing to say — contract carries no agentCapabilities.tools /\n    // clientCapabilities.gadgets.\n  },\n  wired: {\n    axis: \"tooling\",\n    value: \"wired\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Tooling: agent-side tools (catalog only)\\nThe contract declares `agentCapabilities.tools[X]` for tools the AGENT invokes — the component never calls these directly. References surface via `actionSpec[Y].nextStep = 'X'` (the agent's next-turn hint forwarded on action events) and `streamSpec[Z].source.tool = 'X'` (the runtime polls / subscribes the tool, deliveries land on the stream channel). Author UI controls fire actions via `useAction`; data feeds appear via `useStream`. The `useWiredTool` hook from before 2026-05-11 is RETIRED.\",\n  },\n  client: {\n    axis: \"tooling\",\n    value: \"client\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Tooling: gadgets (browser-capability hooks)\\nThe contract declares `clientCapabilities.gadgets[X]` for browser-capability gadget hooks the UI mounts. The boilerplate has pre-emitted a direct import per gadget package — `import { useFoo, useBar } from '<package>';` — above a `// DO NOT EDIT` banner (STDLIB hooks come from `@ggui-ai/gadgets`, third-party hooks from the package on `clientCapabilities.gadgets[*].package`). Call the imported hook inside the component (`const loc = useGeolocation();`) and trigger via `.start()` from a UI control. Read `.value` / `.status` to render. If the agent needs to observe the result, thread `.value` into a `contextSpec` slot or an `actionSpec` payload. Library hooks are UI-owned lifecycle; the agent never invokes them. **KEEP every pre-emitted gadget import — do NOT delete it and do NOT change its package**; self_check rejects the code with `gadget_preservation:<hook>` if a gadget import disappears. The pre-2026-05-11 `useClientTool(name, handler)` shape is RETIRED, as is the `@ggui-ai/client-tools` package name (renamed to `@ggui-ai/gadgets`).\",\n  },\n  both: {\n    axis: \"tooling\",\n    value: \"both\",\n    cacheTier: \"axisDelta\",\n    promptText:\n      \"## Tooling: both surfaces present\\nThe contract declares BOTH `agentCapabilities.tools` (agent-invoked catalog; referenced via `actionSpec.nextStep` / `streamSpec.source.tool` — NO component hook) AND `clientCapabilities.gadgets` (browser-capability gadget hooks the component direct-imports — the boilerplate pre-emits `import { useCamera } from '@ggui-ai/gadgets';` (STDLIB) or `import { useFoo } from '<package>';` (third-party) above a `// DO NOT EDIT` banner). Don't conflate: agentCapabilities entries are catalog declarations the agent uses, NOT component hooks. clientCapabilities entries DO emit component-side hook calls (e.g., `const cam = useCamera();`).\",\n  },\n};\n","// packages/ui-gen/src/fragments/index.ts\n//\n// Public barrel for the `@ggui-ai/ui-gen/fragments` subpath.\n//\n// Stable public surface (what external consumers should build against):\n//   - `FRAGMENT_REGISTRY`  — the axis-keyed registry\n//   - `lookupFragment`     — the one-call lookup helper\n//   - fragment types       — HarnessFragment, ComposedHarness, CacheTier, AxisKey\n//\n// Per-axis fragment records (renderFragments, stateFragments, etc.) are\n// intentionally NOT re-exported here — consumers who genuinely need one\n// can read `FRAGMENT_REGISTRY.render` / `.state` / etc. Keeping the public\n// surface to a single entry point preserves our freedom to reshape the\n// per-axis files without breaking semver.\n\nimport type { AxisKey, HarnessFragment } from \"./types.js\";\nimport { renderFragments } from \"./render.js\";\nimport { stateFragments } from \"./state.js\";\nimport { writeFragments, writeTriggerFragments } from \"./writes.js\";\nimport { realtimeFragments } from \"./realtime.js\";\nimport { fetchFragments } from \"./fetch.js\";\nimport { layoutFragments } from \"./layout.js\";\nimport { toolingFragments } from \"./tooling.js\";\n\nexport type { HarnessFragment, ComposedHarness, CacheTier, AxisKey } from \"./types.js\";\n\nexport const FRAGMENT_REGISTRY: Record<AxisKey, Record<string, HarnessFragment>> = {\n  render: renderFragments,\n  state: stateFragments,\n  writes: writeFragments,\n  writeTrigger: writeTriggerFragments,\n  realtime: realtimeFragments,\n  fetch: fetchFragments,\n  layout: layoutFragments,\n  tooling: toolingFragments,\n};\n\nexport function lookupFragment(axis: AxisKey, value: string): HarnessFragment | undefined {\n  return FRAGMENT_REGISTRY[axis]?.[value];\n}\n","// packages/ui-gen/src/compose.ts\n//\n// Materializes a Classification into prompt sections + boilerplate markers.\n// Sits between the stable prefix (design system docs, pitfalls) and the\n// volatile feedback (eval issues) in the system prompt's cache tiering.\n//\n// Consumes the `./classifier` and `./fragments` subpaths — it's the\n// bridge between an axis vector and the prompt/boilerplate the LLM\n// actually sees.\n\nimport type { Classification } from \"./classifier/axes.js\";\nimport {\n  lookupFragment,\n  type AxisKey,\n  type ComposedHarness,\n  type HarnessFragment,\n} from \"./fragments/index.js\";\n\n// Axis processing order inside axisDelta. Puts the most behaviourally\n// consequential axes first so the LLM reads them before scanning details.\nconst AXIS_ORDER: AxisKey[] = [\n  \"render\",\n  \"layout\",\n  \"state\",\n  \"writes\",\n  \"writeTrigger\",\n  \"realtime\",\n  \"fetch\",\n  \"tooling\",\n];\n\nexport function compose(classification: Classification): ComposedHarness {\n  const v = classification.vector;\n  const matched: HarnessFragment[] = [];\n\n  for (const axis of AXIS_ORDER) {\n    const value = v[axis] as string | undefined;\n    if (!value) continue;\n    const frag = lookupFragment(axis, value);\n    if (frag) matched.push(frag);\n  }\n\n  const promptParts = matched\n    .filter((f) => f.promptText && f.promptText.trim().length > 0)\n    .map((f) => f.promptText!.trim());\n\n  const boilerplateParts = matched\n    .filter((f) => f.boilerplateMarker && f.boilerplateMarker.trim().length > 0)\n    .map((f) => f.boilerplateMarker!);\n\n  return {\n    promptText: promptParts.join(\"\\n\\n\"),\n    boilerplateSections: boilerplateParts.join(\"\"),\n    fragments: matched,\n  };\n}\n\nexport type { ComposedHarness };\n"]}

package/dist/create-ui-generator-C8Ki9Wz1.d.ts

@@ -0,0 +1,189 @@
+import { SingleComponentParams } from './harness/runtime.js';
+import { ModelRef } from '@ggui-ai/protocol';
+import { GadgetCatalogAdapter } from '@ggui-ai/gadgets';
+import { GeneratorTier, UiGenerator } from '@ggui-ai/mcp-server-core';
+import { GenerationResult } from './harness/result-types.js';
+import { D as DesignMode } from './design-mode-DLufhrNp.js';
+import { Q as QualityConfig } from './types-public-DVSssdc-.js';
+import { EvaluationConfig } from './evaluation/types.js';
+import { A as AgentConfig } from './llm-router-D7fjBhtr.js';
+
+/**
+ * `createUiGenerator` — full-harness UI generation factory.
+ *
+ * Returns a {@link UiGenerator} backed by `dispatchGeneration` — the
+ * same multi-turn coding-agent path the benchmark validates. OSS
+ * production (`ggui serve`, hosted `ggui_render`) all route through
+ * this seam, so bench == prod by construction.
+ *
+ * Pipeline:
+ *
+ *   1. `resolveRoute` + `applyRouteToEnv` — install BYOK key into
+ *      the process env so dispatch's adapters can read it.
+ *   2. `createGeneratorTools` — assemble the coding-agent tool surface
+ *      (compile_component, validate_component, self_check,
+ *      get_primitives, get_design_system).
+ *   3. `injectRenderingContext` + `injectContracts` — enrich the user
+ *      prompt with rendering hints + contract docs.
+ *   4. `dispatchGeneration` — multi-turn loop with apply_changes,
+ *      self-check, evaluate, regenerate. The harness builds its own
+ *      rich system prompt with primitives doc + design-system docs +
+ *      pitfalls.
+ *
+ * This factory deliberately keeps a minimal surface — provider
+ * routing, compilation, and the system prompt are all internal:
+ *
+ *   - `adapter` option — provider routing is internal to dispatch
+ *   - `compileFn` option — `compile_component` tool runs inline
+ *   - `systemPromptBuilder` option — harness builds its own
+ *   - `withBrowserCompile` wrapper — dispatch returns compiled JS
+ *
+ * Callers who want a lightweight single-shot path can build it
+ * themselves.
+ */
+
+interface CreateUiGeneratorOptions {
+    /**
+     * Wire `DEFAULT_RUNTIME_RENDER_CHECK` into the harness's check leg.
+     * When `true`, every coding turn ends with a happy-dom runtime-render
+     * probe that catches contract-wiring bugs (missing `useAction()`,
+     * wrong stream channel name, etc.).
+     *
+     * Default: `false` for OSS — keeps cold-start light. The probe pulls
+     * happy-dom + @testing-library on first use (~700-1500ms cold). Bench
+     * enables it via dispatch's own default for stricter quality gating.
+     */
+    readonly enableRuntimeRender?: boolean;
+    /** Maximum coding attempts per generation pass. */
+    readonly maxAttempts?: number;
+    /** Maximum evaluation rounds. */
+    readonly maxEvalRounds?: number;
+    /**
+     * In-loop LLM evaluation config (ggui#1001). When set, every generation
+     * runs the evaluator tiers after the coding leg (`maxRounds` defaults to
+     * `maxEvalRounds`) and the harness result carries `evalResult` — the
+     * probe verdict a downstream judge reads. Default: none, as today —
+     * a serving deployment leaves it unset; offline minting jobs set a round.
+     */
+    readonly evaluation?: EvaluationConfig;
+    /**
+     * In-loop visual round config (per-canvas judging, a sample, the
+     * stylesheet to render under). Forwarded verbatim; never part of the
+     * prompt or the identity. Default: none — the round runs as today.
+     */
+    readonly visualEvaluation?: SingleComponentParams['visualEvaluation'];
+    /** Quality config controlling eval tiers + improvement behavior. */
+    readonly qualityConfig?: QualityConfig;
+    /**
+     * Generator identity — registry key + declared model.
+     *
+     * The tier alone determines the {@link UiGenerator.slug} the factory
+     * bakes onto the returned generator (`ui-gen-<tier>`); `model` is the
+     * generator's declared model field and is never part of the slug
+     * (ggui#923). Defaults to tier `'default'` → slug `ui-gen-default`,
+     * the OSS seed, with the factory's default model.
+     *
+     * The actual model used per request still comes from
+     * `UiGenerateInput.llm.model` (operators may override via BYOK).
+     * The identity here is the registry-level handle, not a runtime
+     * model constraint.
+     *
+     * Mutually-exclusive shortcut: pass `slug` instead of `tier` and the
+     * factory parses the tier from it; `model` may accompany either form.
+     * The factory throws if `slug` and `tier` are both supplied.
+     */
+    readonly tier?: GeneratorTier;
+    readonly model?: ModelRef;
+    readonly slug?: string;
+    /**
+     * Per-deployment gadget descriptor source. Wired once at factory
+     * time; the generator resolves descriptors per-call via
+     * `gadgetCatalog.list(input.appId)` when `input.appGadgets` is
+     * absent. See {@link GadgetCatalogAdapter} (`@ggui-ai/gadgets`) for
+     * the port + the two batteries-included implementations.
+     *
+     * Wiring patterns:
+     *
+     *   ```ts
+     *   // OSS: stdlib seed, no app-specific catalogs.
+     *   createUiGenerator({
+     *     gadgetCatalog: InMemoryGadgetCatalog.withDefault(STDLIB_GADGETS),
+     *   });
+     *
+     *   // Cloud / prod: TTL cache over a registry-backed adapter.
+     *   createUiGenerator({
+     *     gadgetCatalog: new CachingGadgetCatalog(
+     *       new DynamoGadgetCatalog(appMetadataStore),
+     *       { ttlMs: 30_000 },
+     *     ),
+     *   });
+     *   ```
+     *
+     * Per-call resolution precedence (in {@link UiGenerator.generate}):
+     *
+     *   1. `input.appGadgets` (pre-fetched by caller — handler-side path)
+     *   2. `gadgetCatalog.list(input.appId)` (factory path, this option)
+     *   3. empty list (legacy callers — no gadgets resolved)
+     *
+     * Optional. When omitted, callers MUST pre-fetch and pass
+     * `appGadgets` themselves; the legacy handler path stays unchanged.
+     */
+    readonly gadgetCatalog?: GadgetCatalogAdapter;
+    /**
+     * When `true`, `generate()` never mutates `process.env` — the
+     * resolved provider route is threaded structurally into the
+     * dispatch call instead of being written to and restored from the
+     * process environment. Use this when running concurrent
+     * generations in one process (the default backup/mutate/restore
+     * dance is NOT concurrency-safe: two simultaneous calls race on
+     * the shared `process.env`).
+     *
+     * Default `false` — preserves the original env-mutation behavior
+     * for callers that don't need concurrent generations in-process.
+     */
+    readonly disableEnvMutation?: boolean;
+    /**
+     * Retry observer (#489) — see `AgentConfig.onRetry`. Bound ONCE at
+     * factory construction time (mirrors `disableEnvMutation`), not
+     * per-call: `generate()` is invoked once per request, but the
+     * generator instance itself is typically long-lived and cached by
+     * the caller, so a single observer covers every generation it runs.
+     * Fires whenever any agent's `apiCall()` retries a rate-limited
+     * request. Absent (default) is a no-op — retries still happen and
+     * still log via `console.warn`, just without a caller-side hook.
+     */
+    readonly onRetry?: AgentConfig['onRetry'];
+    /**
+     * Generation observer. Invoked once per successful `generate()` with
+     * the FULL harness result — source, compiled code, token counters,
+     * timing breakdown, evaluation rounds and (when configured) the
+     * per-canvas visual scores — before it is projected onto the
+     * `UiGenerateResult` envelope, which carries only what the protocol
+     * needs. Lets a host record or forward the complete run without
+     * re-deriving it from the envelope. Bound ONCE at construction
+     * (mirrors `onRetry`); not invoked when generation fails. An
+     * exception thrown by the observer is the caller's own and fails
+     * that generation like any other error on the path — keep it
+     * non-throwing.
+     */
+    readonly onGenerated?: (result: GenerationResult) => void;
+    /**
+     * Which generation triad to run. `constrained` (default) is the
+     * design-system triad — byte-identical to the generator's behaviour
+     * before this option existed. `free` relaxes only the design
+     * vocabulary (raw HTML, inline CSS, literal spacing / typography /
+     * radius; the design package importable but optional) while keeping
+     * every hard contract: the boilerplate-typed wire hooks, the import
+     * allowlist + security bans, the host envelope, the budgets, the
+     * blueprint-reuse shape, and brand-bearing color on the closed
+     * `--ggui-color-*` token manifest. Reaches the prompt, boilerplate,
+     * tier-0 gate, axis checks and evaluator criteria through the harness.
+     * The rendering canvas the `free` prompt states is derived from
+     * `input.rendering` (device × shell, refined by viewport width).
+     */
+    readonly designMode?: DesignMode;
+}
+declare function createUiGenerator(options?: CreateUiGeneratorOptions): UiGenerator;
+declare function extractComponentCode(raw: string): string;
+
+export { type CreateUiGeneratorOptions as C, createUiGenerator as c, extractComponentCode as e };

package/dist/design-mode-DLufhrNp.d.ts

@@ -0,0 +1,61 @@
+declare const DESIGN_MODES: readonly ["constrained", "free"];
+type DesignMode = (typeof DESIGN_MODES)[number];
+declare const DEFAULT_DESIGN_MODE: DesignMode;
+declare const CANVAS_CLASSES: readonly ["xs-chat-card", "mobile-fullscreen-small", "md", "lg", "xl"];
+type CanvasClass = (typeof CANVAS_CLASSES)[number];
+interface CanvasViewport {
+    readonly width: number;
+    readonly height: number;
+}
+/** The viewport (CSS px) each class is rendered + judged at. */
+declare const CANVAS_VIEWPORTS: Readonly<Record<CanvasClass, CanvasViewport>>;
+/**
+ * The two display modes the canvas derivation distinguishes. `inline`
+ * is the chat card (MCP Apps `inline` display mode / the `chat` shell);
+ * `fullscreen` is every surface the component owns edge to edge or as
+ * a panel (`fullscreen`, `pip`, the `spatial` and `partial` shells) —
+ * there the width decides the class.
+ */
+type CanvasDisplayMode = "inline" | "fullscreen";
+declare function canvasDisplayModeForShell(shell: string | undefined): CanvasDisplayMode;
+/** Fullscreen-class breakpoints (inclusive lower bounds), CSS px. */
+declare const CANVAS_BREAKPOINTS: {
+    readonly md: 600;
+    readonly lg: 1024;
+    readonly xl: 1440;
+};
+/**
+ * Derive the canvas class from display mode + container width.
+ *
+ *   inline      → `xs-chat-card` at every width
+ *   fullscreen  → width <  600  → `mobile-fullscreen-small`
+ *                 600 – 1023    → `md`
+ *                 1024 – 1439   → `lg`
+ *                 ≥ 1440        → `xl`
+ */
+declare function canvasForViewportWidth(mode: CanvasDisplayMode, width: number): CanvasClass;
+/**
+ * Map today's shell × screen descriptors onto a canvas class when no
+ * width is known. `chat` is always the inline card; `spatial` is a
+ * ~600px floating panel (`md`); `fullscreen` follows the screen. Unknown
+ * values fall back to `lg` (the widest common fullscreen), matching the
+ * skeleton's `fullscreen` / `universal` defaults.
+ */
+declare function canvasForRendering(shellType: string | undefined, screen: string | undefined): CanvasClass;
+interface CanvasDescriptor {
+    /** Short human label. */
+    readonly label: string;
+    /** Inclusive width range the component must look right across, CSS px. */
+    readonly minWidthPx: number;
+    readonly maxWidthPx: number;
+    /** What the host draws around the component at this canvas. */
+    readonly host: string;
+}
+declare const CANVAS_DESCRIPTORS: Readonly<Record<CanvasClass, CanvasDescriptor>>;
+/**
+ * The explicit sentence the `free` prompt renders for a canvas — the
+ * agent is TOLD the canvas, it never guesses it.
+ */
+declare function describeCanvas(canvas: CanvasClass): string;
+
+export { type CanvasClass as C, type DesignMode as D, CANVAS_BREAKPOINTS as a, CANVAS_CLASSES as b, CANVAS_DESCRIPTORS as c, CANVAS_VIEWPORTS as d, type CanvasDescriptor as e, type CanvasDisplayMode as f, type CanvasViewport as g, DEFAULT_DESIGN_MODE as h, DESIGN_MODES as i, canvasDisplayModeForShell as j, canvasForRendering as k, canvasForViewportWidth as l, describeCanvas as m };

package/dist/{dispatch-BuZfTh9r.d.ts → dispatch-D2htzi9h.d.ts}

@@ -1,12 +1,15 @@
 import { DataContract } from '@ggui-ai/protocol';
 import { C as Classification } from './axes-CzLEMDeB.js';
-import { E as EvalIssue } from './types-public-CkNWEov9.js';
+import { E as EvalIssue } from './types-public-DVSssdc-.js';
+import { D as DesignMode } from './design-mode-DLufhrNp.js';
 
 interface RunAxisChecksInput {
     sourceCode: string;
     compiledCode: string | null;
     contract?: DataContract;
     originalPrompt: string;
+    /** Which triad produced the source — see `AxisCheckInput.designMode`. */
+    designMode?: DesignMode;
 }
 declare function runAxisChecks(classification: Classification, input: RunAxisChecksInput): EvalIssue[];
 

package/dist/evaluation/axis-checks/index.d.ts

@@ -1,9 +1,10 @@
-export { R as RunAxisChecksInput, r as runAxisChecks } from '../../dispatch-BuZfTh9r.js';
+export { R as RunAxisChecksInput, r as runAxisChecks } from '../../dispatch-D2htzi9h.js';
 export { REGISTRY } from './registry.js';
-import { A as AxisCheck } from '../../types-public-CkNWEov9.js';
-export { a as AxisCheckInput, m as matches } from '../../types-public-CkNWEov9.js';
+import { A as AxisCheck } from '../../types-public-DVSssdc-.js';
+export { a as AxisCheckInput, m as matches } from '../../types-public-DVSssdc-.js';
 import '@ggui-ai/protocol';
 import '../../axes-CzLEMDeB.js';
+import '../../design-mode-DLufhrNp.js';
 import '../../types-BOvHNG7K.js';
 
 declare const EXTRA_CHECKS: readonly AxisCheck[];