@rippling/pebble-sdui-web 0.4.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/sdk-docs.cjs CHANGED
@@ -1,4 +1,4 @@
1
- "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const o=[{key:"shared.readme",filePath:"sdk-docs/README.md",title:"Pebble Kit SDK documentation"},{key:"shared.ai-authoring",filePath:"sdk-docs/ai-authoring.md",title:"AI authoring guide"},{key:"shared.catalogs",filePath:"sdk-docs/catalogs.md",title:"Catalogs"},{key:"shared.concepts",filePath:"sdk-docs/concepts.md",title:"Concepts"},{key:"shared.validation",filePath:"sdk-docs/validation.md",title:"Validation"},{key:"typescript.readme",filePath:"sdk-docs/typescript/README.md",title:"TypeScript SDK"},{key:"typescript.components-actions-rendering",filePath:"sdk-docs/typescript/components-actions-rendering.md",title:"TypeScript components, actions, and rendering"},{key:"typescript.state-expressions",filePath:"sdk-docs/typescript/state-expressions.md",title:"TypeScript state and expressions"}],n={"sdk-docs/README.md":`# Pebble Kit SDK documentation
1
+ "use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const a=[{key:"shared.readme",filePath:"sdk-docs/README.md",title:"Pebble Kit SDK documentation"},{key:"shared.ai-authoring",filePath:"sdk-docs/ai-authoring.md",title:"AI authoring guide"},{key:"shared.catalogs",filePath:"sdk-docs/catalogs.md",title:"Catalogs"},{key:"shared.concepts",filePath:"sdk-docs/concepts.md",title:"Concepts"},{key:"shared.validation",filePath:"sdk-docs/validation.md",title:"Validation"},{key:"typescript.readme",filePath:"sdk-docs/typescript/README.md",title:"TypeScript SDK"},{key:"typescript.components-actions-rendering",filePath:"sdk-docs/typescript/components-actions-rendering.md",title:"TypeScript components, actions, and rendering"},{key:"typescript.state-expressions",filePath:"sdk-docs/typescript/state-expressions.md",title:"TypeScript state and expressions"}],n={"sdk-docs/README.md":`# Pebble Kit SDK documentation
2
2
 
3
3
  Pebble Kit is a server-driven UI (SDUI) SDK for producing JSON specs that the \`json-render\` runtime can render. The SDK is designed for two authors:
4
4
 
@@ -81,9 +81,9 @@ For humans:
81
81
 
82
82
  For LLMs:
83
83
 
84
- - First inspect the target catalog with \`get_components()\`, \`get_component()\`, \`get_actions()\`, and \`get_action()\`.
84
+ - First inspect the target catalog with \`get_components()\`, \`get_component()\`, \`get_actions()\`, \`get_action()\`, and \`get_computed_functions()\`.
85
85
  - Generate a small component tree before adding dynamic behavior.
86
- - Never invent component names, prop names, event names, or action names.
86
+ - Never invent component names, prop names, event names, action names, or computed function names.
87
87
  - Run \`validate(spec)\` and repair from the returned error messages.
88
88
  - Prefer SDK code generation over raw JSON because the SDK handles IDs, refs, and serialization.
89
89
  `,"sdk-docs/ai-authoring.md":`# AI authoring guide
@@ -95,7 +95,7 @@ This guide explains how an LLM should use the SDK and catalog metadata to produc
95
95
  Prefer this loop:
96
96
 
97
97
  1. **Identify target platform and catalog.** Example: web + \`AiChatCatalogV1\`.
98
- 2. **Inspect catalog capabilities.** Use \`get_components()\`, \`get_component()\`, \`get_actions()\`, and \`get_action()\`.
98
+ 2. **Inspect catalog capabilities.** Use \`get_components()\`, \`get_component()\`, \`get_actions()\`, \`get_action()\`, and \`get_computed_functions()\`.
99
99
  3. **Plan a small tree.** Pick the root and children. Confirm each component supports children before nesting.
100
100
  4. **Generate SDK code, not raw JSON.** SDK code gives better type hints and automatic serialization.
101
101
  5. **Render.** Call the catalog \`render(root, state)\`.
@@ -132,6 +132,7 @@ Rules:
132
132
  - Include all required props.
133
133
  - Use only events listed by the component definition.
134
134
  - Use only actions returned by get_actions().
135
+ - Use only computed functions returned by get_computed_functions().
135
136
  - Prefer generated SDK code over hand-written JSON.
136
137
  - Call render(root, state) and then validate(spec).
137
138
  - If validate returns errors, fix the code and validate again.
@@ -187,6 +188,7 @@ Repair strategy:
187
188
  - Missing required prop: add the prop with a safe value or state ref.
188
189
  - Unknown event: use one of the component's listed events.
189
190
  - Unknown action: use one from \`get_actions()\`.
191
+ - Unknown computed function: use one from \`get_computed_functions()\`.
190
192
  - Children not accepted: remove children or choose a container component.
191
193
  - Root missing: render the actual root returned by the tree.
192
194
 
@@ -274,6 +276,9 @@ Generated catalog modules export:
274
276
  - \`get_component(name)\`
275
277
  - \`get_actions()\`
276
278
  - \`get_action(name)\`
279
+ - \`get_functions()\`
280
+ - \`get_function(name)\`
281
+ - \`get_computed_functions()\`
277
282
  - \`render(root, state=None)\`
278
283
  - \`validate(spec)\`
279
284
 
@@ -321,12 +326,34 @@ print(submit["description"])
321
326
  print(submit.get("paramsSchema"))
322
327
  \`\`\`
323
328
 
329
+ ## Computed function discovery
330
+
331
+ Use \`get_functions()\` for a compact computed-function list:
332
+
333
+ \`\`\`python
334
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import get_functions
335
+
336
+ print(get_functions())
337
+ \`\`\`
338
+
339
+ Use \`get_computed_functions()\` or \`get_function(name)\` for params, return schemas, and docs:
340
+
341
+ \`\`\`python
342
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import get_computed_functions, get_function
343
+
344
+ functions = get_computed_functions()
345
+ definition = get_function("dateTime_format")
346
+ print(functions)
347
+ print(definition.get("paramsSchema"))
348
+ print(definition.get("returnsSchema"))
349
+ \`\`\`
350
+
324
351
  ## How humans should use catalogs
325
352
 
326
353
  1. Start with the catalog for the target surface.
327
354
  2. Use component docstrings and generated types in your editor.
328
355
  3. Read \`get_component()\` when a prop's runtime meaning is unclear.
329
- 4. Prefer generated action creators over raw dictionaries.
356
+ 4. Prefer generated action creators and computed-function helpers over raw dictionaries.
330
357
  5. Validate rendered specs in tests or at service boundaries.
331
358
 
332
359
  ## How LLMs should use catalogs
@@ -336,9 +363,10 @@ LLMs should treat the catalog as hard constraints:
336
363
  1. Call or inspect \`get_components()\` to choose candidates.
337
364
  2. Call or inspect \`get_component(name)\` for exact prop names, required props, events, and child support.
338
365
  3. Call or inspect \`get_actions()\` and \`get_action(name)\` for allowed action names and params.
339
- 4. Generate SDK code using only exported component and action symbols.
340
- 5. Render the tree.
341
- 6. Validate and repair any errors.
366
+ 4. Call or inspect \`get_computed_functions()\` before using computed values.
367
+ 5. Generate SDK code using only exported component, action, and computed-function symbols.
368
+ 6. Render the tree.
369
+ 7. Validate and repair any errors.
342
370
 
343
371
  LLMs must not invent:
344
372
 
@@ -346,6 +374,7 @@ LLMs must not invent:
346
374
  - prop names
347
375
  - event names
348
376
  - action names
377
+ - computed function names
349
378
  - enum/literal values
350
379
  - child support on leaf components
351
380
 
@@ -933,6 +962,7 @@ Generated catalogs export compact and detailed introspection helpers:
933
962
  import {
934
963
  getActions,
935
964
  getAction,
965
+ getComputedFunctions,
936
966
  getComponents,
937
967
  getComponent,
938
968
  } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
@@ -941,6 +971,7 @@ console.log(getComponents());
941
971
  console.log(getComponent('Button'));
942
972
  console.log(getActions());
943
973
  console.log(getAction('showNotification'));
974
+ console.log(getComputedFunctions());
944
975
  \`\`\`
945
976
 
946
977
  LLMs should call or inspect these helpers before generating SDK code.
@@ -1111,5 +1142,5 @@ Use the core helper only in low-level tests or core-only tooling.
1111
1142
  | \`item.$index()\` | \`{ "$index": true }\` | repeat index |
1112
1143
  | \`$template\\\`...\\\`\` | \`{ "$template": "..." }\` | string interpolation |
1113
1144
  | \`$cond(...)\` | \`{ "$cond": ..., "$then": ..., "$else": ... }\` | conditional prop value |
1114
- `};function s(){return o.map(({key:e,filePath:t,title:a})=>({key:e,filePath:t,title:a}))}function r(e){if(!(e in n))throw new Error(`Unknown SDK doc filePath: ${e}`);return n[e]}exports.listSdkDocs=s;exports.readSdkDoc=r;
1145
+ `};function s(){return a.map(({key:e,filePath:t,title:o})=>({key:e,filePath:t,title:o}))}function r(e){if(!(e in n))throw new Error(`Unknown SDK doc filePath: ${e}`);return n[e]}exports.listSdkDocs=s;exports.readSdkDoc=r;
1115
1146
  //# sourceMappingURL=sdk-docs.cjs.map
@@ -1 +1 @@
1
- {"version":3,"file":"sdk-docs.cjs","sources":["../src/sdk-docs.generated.ts","../src/sdk-docs.ts"],"sourcesContent":["// This file is generated by codegen/generate-sdk-docs.ts.\n// Do not edit this file directly.\n\nimport type { SdkDoc } from './sdk-docs';\n\nexport const SDK_DOCS: readonly SdkDoc[] = [\n {\n key: 'shared.readme',\n filePath: 'sdk-docs/README.md',\n title: 'Pebble Kit SDK documentation',\n },\n {\n key: 'shared.ai-authoring',\n filePath: 'sdk-docs/ai-authoring.md',\n title: 'AI authoring guide',\n },\n {\n key: 'shared.catalogs',\n filePath: 'sdk-docs/catalogs.md',\n title: 'Catalogs',\n },\n {\n key: 'shared.concepts',\n filePath: 'sdk-docs/concepts.md',\n title: 'Concepts',\n },\n {\n key: 'shared.validation',\n filePath: 'sdk-docs/validation.md',\n title: 'Validation',\n },\n {\n key: 'typescript.readme',\n filePath: 'sdk-docs/typescript/README.md',\n title: 'TypeScript SDK',\n },\n {\n key: 'typescript.components-actions-rendering',\n filePath: 'sdk-docs/typescript/components-actions-rendering.md',\n title: 'TypeScript components, actions, and rendering',\n },\n {\n key: 'typescript.state-expressions',\n filePath: 'sdk-docs/typescript/state-expressions.md',\n title: 'TypeScript state and expressions',\n },\n];\n\nexport const SDK_DOC_CONTENT_BY_PATH: Readonly<Record<string, string>> = {\n 'sdk-docs/README.md':\n '# Pebble Kit SDK documentation\\n\\nPebble Kit is a server-driven UI (SDUI) SDK for producing JSON specs that the `json-render` runtime can render. The SDK is designed for two authors:\\n\\n- **Humans** write typed Python or TypeScript code, compose component trees, bind props to state, and render a validated spec.\\n- **LLMs** use catalog metadata, examples, and validation errors to generate SDK code or JSON specs safely, then iterate until validation passes.\\n\\nThis documentation focuses on the public authoring model: catalogs, components, actions, state expressions, rendering, and validation.\\n\\n## What the SDK does\\n\\nThe SDK lets an author describe UI as a tree:\\n\\n1. Choose a platform package, such as `pebble_sdui_web` or `pebble_sdui_mobile`.\\n2. Import a generated catalog module, such as `pebble_sdui_web.catalogs.AiChatCatalogV1`.\\n3. Define initial state with plain annotated Python classes.\\n4. Create components and wire events to generated action creators.\\n5. Use expressions (`$state`, `$bindState`, `$item`, `$cond`, `$template`) for runtime behavior.\\n6. Call the catalog `render()` function to produce the flat JSON wire format.\\n7. Call the catalog `validate()` function when specs may be generated or transformed.\\n\\n## Documentation map\\n\\nThese links point to the canonical files in the repo so they still work when this README is shown inside another site or tool.\\n\\n- [ai-authoring.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/ai-authoring.md) — how to prompt and constrain LLM authors.\\n- [concepts.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/concepts.md) — core SDUI concepts shared by humans and LLMs.\\n- [catalogs.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/catalogs.md) — generated catalogs, component discovery, and action discovery.\\n- [validation.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/validation.md) — validation workflow and error repair loop.\\n- [python/README.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/python/README.md) — Python SDK quick start.\\n- [python/components-actions-rendering.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/python/components-actions-rendering.md) — Python components, events, actions, and render output.\\n- [python/state-expressions.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/python/state-expressions.md) — Python state, refs, repeat, templates, conditions, and conditional expressions.\\n- [typescript/README.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/typescript/README.md) — TypeScript SDK quick start.\\n- [typescript/components-actions-rendering.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/typescript/components-actions-rendering.md) — TypeScript components, events, actions, and render output.\\n- [typescript/state-expressions.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/typescript/state-expressions.md) — TypeScript state, refs, repeat, templates, conditions, and conditional expressions.\\n\\n## Quick Python example\\n\\n```python\\nfrom pebble_sdui_web import create_state, template, truthy\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import (\\n ConfirmationCard,\\n render,\\n submit_tool_output,\\n validate,\\n)\\n\\nclass AppState:\\n employee_name: str\\n is_ready: bool\\n\\nstate = create_state(AppState, {\\n \"employee_name\": \"Alice Nguyen\",\\n \"is_ready\": True,\\n})\\n\\nroot = ConfirmationCard(\\n id=\"confirm-employee\",\\n question=template(\"Confirm action for \", state.ref(lambda s: s.employee_name), \"?\"),\\n description=\"This choice will be submitted back to the workflow.\",\\n events={\\n \"confirm\": submit_tool_output(output={\"confirmed\": True}),\\n \"cancel\": submit_tool_output(output={\"confirmed\": False}),\\n },\\n visible=truthy(state.ref(lambda s: s.is_ready)),\\n)\\n\\nspec = render(root, state.to_dict())\\nerrors = validate(spec)\\nassert errors == [], errors\\n```\\n\\n## Authoring guidance\\n\\nFor humans:\\n\\n- Prefer SDK builders over hand-writing JSON.\\n- Let type checkers catch prop, event, and state reference mistakes early.\\n- Keep state explicit and small; pass only data the rendered UI needs.\\n- Use catalog `validate()` before returning specs from untrusted or generated paths.\\n\\nFor LLMs:\\n\\n- First inspect the target catalog with `get_components()`, `get_component()`, `get_actions()`, and `get_action()`.\\n- Generate a small component tree before adding dynamic behavior.\\n- Never invent component names, prop names, event names, or action names.\\n- Run `validate(spec)` and repair from the returned error messages.\\n- Prefer SDK code generation over raw JSON because the SDK handles IDs, refs, and serialization.\\n',\n 'sdk-docs/ai-authoring.md':\n '# AI authoring guide\\n\\nThis guide explains how an LLM should use the SDK and catalog metadata to produce correct SDUI specs. It is also useful for humans building agent workflows around Pebble Kit.\\n\\n## Recommended LLM workflow\\n\\nPrefer this loop:\\n\\n1. **Identify target platform and catalog.** Example: web + `AiChatCatalogV1`.\\n2. **Inspect catalog capabilities.** Use `get_components()`, `get_component()`, `get_actions()`, and `get_action()`.\\n3. **Plan a small tree.** Pick the root and children. Confirm each component supports children before nesting.\\n4. **Generate SDK code, not raw JSON.** SDK code gives better type hints and automatic serialization.\\n5. **Render.** Call the catalog `render(root, state)`.\\n6. **Validate.** Call the catalog `validate(spec)`.\\n7. **Repair from errors.** Treat validation errors as the next prompt context.\\n8. **Return the spec or checked-in code.** Include validation status.\\n\\n## Why SDK code is better than raw JSON\\n\\nSDK code avoids common LLM mistakes:\\n\\n- element IDs are generated or checked for duplicates\\n- component props are spelled by generated dataclass fields\\n- action creators serialize params correctly\\n- state refs serialize as `$state`, `$bindState`, `$item`, and `$index`\\n- catalog renderers add platform/catalog metadata\\n- validation catches schema and structural problems\\n\\nRaw JSON is acceptable only when an integration cannot execute SDK code. In that mode, the LLM must still use catalog definitions and `validate()`.\\n\\n## Prompt pattern for LLMs\\n\\nUse a prompt like this when asking an LLM to author a UI:\\n\\n```text\\nYou are authoring a Pebble Kit SDUI spec.\\nTarget package: pebble_sdui_web\\nTarget catalog: pebble_sdui_web.catalogs.AiChatCatalogV1\\n\\nRules:\\n- Use only components returned by get_components().\\n- Before using a component, inspect get_component(name).\\n- Use only props defined in propsSchema.\\n- Include all required props.\\n- Use only events listed by the component definition.\\n- Use only actions returned by get_actions().\\n- Prefer generated SDK code over hand-written JSON.\\n- Call render(root, state) and then validate(spec).\\n- If validate returns errors, fix the code and validate again.\\n\\nUser goal:\\n<goal here>\\n```\\n\\n## Minimal executable harness\\n\\n```python\\nfrom pebble_sdui_web import create_state\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import (\\n ConfirmationCard,\\n render,\\n submit_tool_output,\\n validate,\\n)\\n\\nclass AppState:\\n is_ready: bool\\n\\nstate = create_state(AppState, {\"is_ready\": True})\\n\\nroot = ConfirmationCard(\\n question=\"Do you want to continue?\",\\n events={\"confirm\": submit_tool_output(output=\"yes\")},\\n)\\n\\nspec = render(root, state.to_dict())\\nerrors = validate(spec)\\nif errors:\\n raise ValueError(\"Invalid spec:\\\\n\" + \"\\\\n\".join(errors))\\n```\\n\\n## Repair loop\\n\\nWhen validation fails, preserve the full error text. Then ask the model to make the smallest change that fixes the first error.\\n\\nExample repair prompt:\\n\\n```text\\nThe spec failed validation:\\n- Element \\'confirm\\': unknown event \\'submit\\'. Valid: [\\'confirm\\', \\'cancel\\']\\n\\nFix the SDK code. Do not change the user\\'s intent. Do not invent new events.\\n```\\n\\nRepair strategy:\\n\\n- Unknown component: choose a component from `get_components()`.\\n- Unknown prop: remove it or map it to a documented prop from `propsSchema`.\\n- Missing required prop: add the prop with a safe value or state ref.\\n- Unknown event: use one of the component\\'s listed events.\\n- Unknown action: use one from `get_actions()`.\\n- Children not accepted: remove children or choose a container component.\\n- Root missing: render the actual root returned by the tree.\\n\\n## LLM safety rules\\n\\nAn LLM should not:\\n\\n- invent schema fields because they sound plausible\\n- depend on undocumented renderer behavior\\n- manually serialize Python SDK objects unless using `render()` helpers\\n- mix components from different catalogs\\n- output a spec without reporting validation status\\n- ignore validation errors because the UI “looks close”\\n\\n## Human review checklist for AI-authored specs\\n\\nBefore accepting an AI-authored spec, check:\\n\\n- Does the UI satisfy the user goal with the smallest reasonable tree?\\n- Are all component names, props, events, and actions catalog-backed?\\n- Is state minimal and free of sensitive data not needed by the UI?\\n- Are bindings used only for data the UI should write back?\\n- Are action payloads safe and expected by the receiving workflow?\\n- Did `validate(spec)` return `[]`?\\n\\n## Good output format from an AI authoring service\\n\\n```json\\n{\\n \"status\": \"valid\",\\n \"catalog\": \"AiChatCatalogV1\",\\n \"catalogVersion\": \"1.0.0\",\\n \"spec\": { \"root\": \"...\", \"elements\": {}, \"state\": {} },\\n \"validationErrors\": []\\n}\\n```\\n\\nIf invalid, return the errors and do not send the spec to production rendering.\\n',\n 'sdk-docs/catalogs.md':\n '# Catalogs\\n\\nCatalogs are generated SDK modules that define the allowed components, actions, schemas, docs, examples, and validators for a target UI surface.\\n\\n## Why catalogs matter\\n\\nA catalog is the source of truth for what an author may use. Humans should read catalog docs for intent and prop semantics. LLMs should inspect catalog metadata before generating code or JSON.\\n\\nA spec should be authored against one catalog at a time. The catalog renderer adds metadata such as:\\n\\n```json\\n{\\n \"platform\": \"web\",\\n \"catalog\": \"AiChatCatalogV1\",\\n \"catalogVersion\": \"1.0.0\"\\n}\\n```\\n\\n## Python catalog imports\\n\\nExamples:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import (\\n ConfirmationCard,\\n SingleSelectDisambiguation,\\n render,\\n submit_tool_output,\\n validate,\\n)\\n\\nfrom pebble_sdui_mobile.catalogs.MobileGenUICatalogV1 import (\\n Button,\\n render,\\n validate,\\n)\\n```\\n\\nGenerated catalog modules export:\\n\\n- component classes and nested prop types\\n- event TypedDicts\\n- action creators\\n- `CATALOG_NAME`\\n- `CATALOG_VERSION`\\n- `get_components()`\\n- `get_component(name)`\\n- `get_actions()`\\n- `get_action(name)`\\n- `render(root, state=None)`\\n- `validate(spec)`\\n\\n## Component discovery\\n\\nUse `get_components()` for a compact list of names and descriptions:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import get_components\\n\\nfor name, description in get_components().items():\\n print(name, \"-\", description)\\n```\\n\\nUse `get_component(name)` before selecting props, events, or children:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import get_component\\n\\ndefinition = get_component(\"AIChat_ConfirmationCard\")\\nprint(definition[\"description\"])\\nprint(definition[\"docs\"])\\nprint(definition[\"events\"])\\nprint(definition[\"propsSchema\"])\\nprint(definition[\"acceptsChildren\"])\\n```\\n\\n## Action discovery\\n\\nUse `get_actions()` for a compact action list:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import get_actions\\n\\nprint(get_actions())\\n```\\n\\nUse `get_action(name)` for params and docs:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import get_action\\n\\nsubmit = get_action(\"submitToolOutput\")\\nprint(submit[\"description\"])\\nprint(submit.get(\"paramsSchema\"))\\n```\\n\\n## How humans should use catalogs\\n\\n1. Start with the catalog for the target surface.\\n2. Use component docstrings and generated types in your editor.\\n3. Read `get_component()` when a prop\\'s runtime meaning is unclear.\\n4. Prefer generated action creators over raw dictionaries.\\n5. Validate rendered specs in tests or at service boundaries.\\n\\n## How LLMs should use catalogs\\n\\nLLMs should treat the catalog as hard constraints:\\n\\n1. Call or inspect `get_components()` to choose candidates.\\n2. Call or inspect `get_component(name)` for exact prop names, required props, events, and child support.\\n3. Call or inspect `get_actions()` and `get_action(name)` for allowed action names and params.\\n4. Generate SDK code using only exported component and action symbols.\\n5. Render the tree.\\n6. Validate and repair any errors.\\n\\nLLMs must not invent:\\n\\n- component names\\n- prop names\\n- event names\\n- action names\\n- enum/literal values\\n- child support on leaf components\\n\\n## Choosing a component\\n\\nPrefer the most specific component that matches the user\\'s intent. If two components look similar:\\n\\n- Prefer a component whose description mentions the target workflow.\\n- Prefer fewer props over many unused props.\\n- Prefer built-in component behavior documented in `docs` instead of recreating it with custom state.\\n- If the catalog says a component auto-binds or auto-disables behavior, do not duplicate that behavior unless required.\\n\\n## Catalog upgrades\\n\\nWhen a catalog version changes:\\n\\n- Re-run validation on representative specs.\\n- Check changed component definitions for prop/event differences.\\n- For LLM prompt packs, regenerate the catalog excerpt used by the model.\\n- Keep examples small so they are easy to update.\\n',\n 'sdk-docs/concepts.md':\n '# Concepts\\n\\nPebble Kit authors UI specs for a server-driven UI runtime. Humans and LLMs should use the same mental model: a catalog defines what can be rendered, the SDK builds a component tree, and `render()` converts that tree into the runtime wire format.\\n\\n## Spec\\n\\nA **spec** is the JSON object sent to the renderer. It contains:\\n\\n- `platform` — target platform, such as `web` or `mobile`.\\n- `catalog` and `catalogVersion` — the component/action vocabulary used by the spec.\\n- `root` — the ID of the root element.\\n- `elements` — a flat map of element ID to element definition.\\n- `state` — optional initial state for runtime expressions.\\n\\nSDK authors normally build a tree and let `render()` create this flat spec.\\n\\n## Catalog\\n\\nA **catalog** is a generated module for one UI vocabulary. It contains:\\n\\n- component classes/builders\\n- action creators\\n- catalog metadata\\n- introspection helpers\\n- a catalog-scoped `render()` function\\n- a catalog-scoped `validate()` function\\n\\nCatalogs are isolated. Do not mix components from different catalogs in one tree unless the catalog explicitly supports it.\\n\\n## Component\\n\\nA **component** is a generated class that represents a renderable UI element. Component fields become runtime props. Common element-level fields include:\\n\\n- `id` — optional explicit element ID.\\n- `children` — nested child elements when supported.\\n- `events` — event handlers keyed by event name.\\n- `visible` — condition controlling visibility.\\n- `watch_handlers` — actions triggered by state path changes.\\n- `repeat` — list repetition binding.\\n\\n## Action\\n\\nAn **action** is an event-side effect. Catalog action creators return opaque `ActionBinding` values. Use generated action creators instead of constructing action dictionaries by hand.\\n\\nActions may accept `ActionOptions` for confirmation, success handling, error handling, or `preventDefault` where supported.\\n\\n## State\\n\\n**State** is the runtime data model. Python authors define state shape with annotated classes and initial values with dictionaries. State paths are serialized into expressions such as:\\n\\n```json\\n{ \"$state\": \"/user/name\" }\\n```\\n\\nUse state for values that the runtime can read, bind, compare, or update.\\n\\n## Binding\\n\\nA **binding** is a two-way reference. It lets an input-like component write back to state:\\n\\n```json\\n{ \"$bindState\": \"/form/email\" }\\n```\\n\\nUse read-only refs for display and comparisons. Use bindings only when the component is expected to update state.\\n\\n## Expressions\\n\\nExpressions are runtime-resolved values used inside props, visibility, action params, and repeat definitions.\\n\\nCommon expression forms:\\n\\n- `$state` — read a state path.\\n- `$bindState` — two-way bind a state path.\\n- `$item` — read a field from the current repeated item.\\n- `$bindItem` — two-way bind a repeated item field.\\n- `$index` — current repeat index.\\n- `$template` — interpolate state refs into a string.\\n- `$cond` — choose between two values based on a condition.\\n\\n## Conditions\\n\\nA **condition** controls visibility or conditional expressions. Conditions can compare refs against literals or other state refs:\\n\\n- equals / not equals\\n- greater than / greater than or equal\\n- less than / less than or equal\\n- truthy / falsy\\n- logical `and_`, `or_`, `not_`\\n\\n## Repeat\\n\\nA **repeat** renders an element once per item in a list state path. It provides:\\n\\n- a repeat binding attached to the repeated component\\n- an item accessor for `$item`, `$bindItem`, and `$index`\\n\\nUse repeat for data-driven lists instead of manually creating fixed children when the list length is dynamic.\\n\\n## Rendering\\n\\n`render(root, state)` walks the tree, assigns IDs where needed, serializes props and expressions, and returns the flat spec. Generated catalog renderers also stamp `platform`, `catalog`, and `catalogVersion`.\\n\\n## Validation\\n\\n`validate(spec)` checks a rendered or generated spec against the catalog. Validation returns a list of error strings; an empty list means valid.\\n\\nUse validation especially when:\\n\\n- an LLM created or edited the spec\\n- JSON was hand-written\\n- a spec crosses service boundaries\\n- a component catalog was upgraded\\n',\n 'sdk-docs/validation.md':\n '# Validation\\n\\nValidation checks a spec against a catalog\\'s component schemas and structural rules. It is required for LLM-authored or hand-authored JSON and recommended for service boundaries.\\n\\n## API\\n\\nGenerated catalog modules export `validate(spec)`:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import validate\\n\\nerrors: list[str] = validate(spec)\\nif errors:\\n raise ValueError(\"Invalid SDUI spec:\\\\n\" + \"\\\\n\".join(errors))\\n```\\n\\nAn empty list means the spec is valid:\\n\\n```python\\nassert validate(spec) == []\\n```\\n\\n## What validation checks\\n\\nCatalog validation checks:\\n\\n- the root ID exists in the `elements` map\\n- every element `type` is known by the catalog\\n- element props match the component `propsSchema`\\n- reactive refs are accepted where literal props are accepted\\n- event names are valid for the component\\n- leaf components do not receive children\\n\\nValidation does not prove the receiving business action will succeed. It proves the UI spec matches the catalog shape.\\n\\n## Validate after rendering\\n\\nHumans should usually validate the rendered spec, not the component tree:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import ConfirmationCard, render, submit_tool_output, validate\\n\\nroot = ConfirmationCard(\\n question=\"Proceed?\",\\n events={\"confirm\": submit_tool_output(output=True)},\\n)\\n\\nspec = render(root)\\nerrors = validate(spec)\\nassert errors == [], errors\\n```\\n\\n## Validate generated JSON\\n\\nIf an LLM or external service emits raw JSON, validate before rendering it in a client:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import validate\\n\\nerrors = validate(candidate_spec)\\nif errors:\\n return {\"status\": \"invalid\", \"validationErrors\": errors}\\n\\nreturn {\"status\": \"valid\", \"spec\": candidate_spec, \"validationErrors\": []}\\n```\\n\\n## Common errors and fixes\\n\\n| Error type | Likely cause | Fix |\\n|---|---|---|\\n| `Root element ... not found` | `root` points to a missing ID | Render from the real root or fix the ID |\\n| `unknown type` | Component name is not in the catalog | Use `get_components()` and generated component classes |\\n| `props ... is a required property` | Required prop omitted | Add the required prop |\\n| `additional properties are not allowed` | Invented or misspelled prop | Use exact `propsSchema` names |\\n| `unknown event` | Invented or wrong event name | Use events from `get_component(name)[\"events\"]` |\\n| `does not accept children` | Children passed to a leaf component | Remove children or use a container component |\\n| Type mismatch | Prop value shape is wrong | Match the JSON Schema type or use a compatible reactive ref |\\n\\n## LLM repair workflow\\n\\nFor AI-generated specs, repair one validation class at a time:\\n\\n1. Run `validate(spec)`.\\n2. Feed all errors back to the LLM.\\n3. Require the LLM to cite the catalog field it used to fix each error.\\n4. Regenerate SDK code or JSON.\\n5. Validate again.\\n6. Stop only when errors are empty.\\n\\nPrompt template:\\n\\n```text\\nValidation failed for this Pebble Kit spec:\\n<errors>\\n\\nRepair rules:\\n- Make the smallest change.\\n- Use only catalog-backed component, prop, event, and action names.\\n- Preserve the user intent.\\n- Return updated SDK code and validation status.\\n```\\n\\n## Testing pattern\\n\\nAdd tests around representative specs:\\n\\n```python\\ndef test_confirmation_card_spec_is_valid() -> None:\\n from pebble_sdui_web.catalogs.AiChatCatalogV1 import ConfirmationCard, render, submit_tool_output, validate\\n\\n spec = render(\\n ConfirmationCard(\\n question=\"Approve?\",\\n events={\"confirm\": submit_tool_output(output=\"approved\")},\\n )\\n )\\n\\n assert validate(spec) == []\\n```\\n\\n## Production guidance\\n\\n- Validate specs from LLMs before sending them to clients.\\n- Validate during CI for checked-in examples or fixture specs.\\n- Log validation errors with catalog name and version.\\n- Treat validation failures as authoring bugs, not renderer bugs.\\n- Keep validation close to the catalog used to render or consume the spec.\\n',\n 'sdk-docs/typescript/README.md':\n \"# TypeScript SDK\\n\\nThe TypeScript SDK lets frontend and backend TypeScript code author type-safe SDUI specs. Platform packages export shared expression helpers, while generated catalog subpaths export components, actions, rendering, introspection, and validation.\\n\\n## Packages and imports\\n\\nCore authoring helpers come from the platform package:\\n\\n```ts\\nimport { createSpec, equals, truthy, and_ } from '@rippling/pebble-sdui-web';\\n```\\n\\nCatalog-specific builders come from generated catalog subpaths:\\n\\n```ts\\nimport {\\n Button,\\n Text,\\n VStack,\\n render,\\n showNotification,\\n validate,\\n} from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n```\\n\\n## Quick start\\n\\n```ts\\nimport { createSpec, truthy } from '@rippling/pebble-sdui-web';\\nimport {\\n Button,\\n Text,\\n VStack,\\n render,\\n showNotification,\\n validate,\\n} from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n\\ninterface AppState {\\n userName: string;\\n isReady: boolean;\\n}\\n\\nconst { $state, $template } = createSpec<AppState>({\\n state: {\\n userName: 'Alice Nguyen',\\n isReady: true,\\n },\\n});\\n\\nconst root = VStack({\\n id: 'root',\\n props: { gap: 12 },\\n visible: truthy($state('isReady')),\\n children: [\\n Text({\\n props: {\\n text: $template`Hello ${$state('userName')}`,\\n },\\n }),\\n Button({\\n props: {\\n label: 'Continue',\\n appearance: 'PRIMARY',\\n },\\n on: {\\n press: showNotification({\\n message: 'Continuing',\\n variant: 'success',\\n }),\\n },\\n }),\\n ],\\n});\\n\\nconst spec = render({\\n root,\\n state: {\\n userName: 'Alice Nguyen',\\n isReady: true,\\n },\\n});\\n\\nconst errors = validate(spec);\\nif (errors.length > 0) {\\n throw new Error(`Invalid spec:\\\\n${errors.join('\\\\n')}`);\\n}\\n```\\n\\n## Authoring steps\\n\\n1. Define a TypeScript state interface.\\n2. Create state helpers with `createSpec<State>({ state })`.\\n3. Import components/actions from one generated catalog subpath.\\n4. Compose a component tree with generated builder functions.\\n5. Use `$state()`, `$bindState()`, `$template`, `$cond()`, and `repeat()` for dynamic behavior.\\n6. Call the catalog `render({ root, state })`.\\n7. Call the catalog `validate(spec)` for generated, hand-authored, or externally consumed specs.\\n\\n## Human authoring benefits\\n\\n- Editor autocomplete for component props and event names.\\n- TypeScript validates state paths and expression result types.\\n- Component builders enforce whether `children` and `on` are allowed.\\n- Action creators enforce action params.\\n- Catalog `render()` stamps platform/catalog metadata.\\n\\n## LLM authoring benefits\\n\\n- Catalog introspection gives exact names and schemas.\\n- SDK code is easier to validate and repair than raw JSON.\\n- Generated builders prevent many invalid tree shapes.\\n- Validation errors provide deterministic repair feedback.\\n\\n## More TypeScript docs\\n\\n- [components-actions-rendering.md](./components-actions-rendering.md)\\n- [state-expressions.md](./state-expressions.md)\\n\",\n 'sdk-docs/typescript/components-actions-rendering.md':\n \"# TypeScript components, actions, and rendering\\n\\nGenerated catalog subpaths provide component builder functions, prop/event types, action creators, introspection helpers, a catalog `render()` function, and `validate()`.\\n\\n## Import from one catalog\\n\\nKeep a tree within one generated catalog:\\n\\n```ts\\nimport {\\n Button,\\n Text,\\n VStack,\\n render,\\n showNotification,\\n validate,\\n} from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n```\\n\\nDo not mix components from different platforms or catalogs in one spec.\\n\\n## Components\\n\\nComponents are generated builder functions. They accept an input object with:\\n\\n- `id` — optional explicit element ID.\\n- `props` — component props.\\n- `visible` — visibility condition or boolean.\\n- `repeat` — repeat binding.\\n- `on` — event handlers, only when the component has events.\\n- `children` — child elements, only when the component accepts children.\\n\\n```ts\\nconst title = Text({\\n id: 'title',\\n props: {\\n text: 'Welcome',\\n typestyle: 'title3',\\n },\\n});\\n```\\n\\nContainer components accept children when generated with child support:\\n\\n```ts\\nconst root = VStack({\\n id: 'root',\\n props: { gap: 12 },\\n children: [\\n Text({ props: { text: 'Welcome' } }),\\n Button({ props: { label: 'Continue', appearance: 'PRIMARY' } }),\\n ],\\n});\\n```\\n\\nIf TypeScript rejects `children`, the component is a leaf. Choose a container component or remove the children.\\n\\n## Props and expression values\\n\\nGenerated component props accept either literal values or compatible expressions.\\n\\n```ts\\nimport { createSpec } from '@rippling/pebble-sdui-web';\\nimport { Text } from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n\\ninterface AppState {\\n title: string;\\n}\\n\\nconst { $state } = createSpec<AppState>({ state: { title: 'Hello' } });\\n\\nconst title = Text({\\n props: {\\n text: $state('title'),\\n },\\n});\\n```\\n\\n## Events\\n\\nEvents are component-specific and type checked. For example, `Button` supports events such as `press`.\\n\\n```ts\\nconst button = Button({\\n props: { label: 'Save', appearance: 'PRIMARY' },\\n on: {\\n press: showNotification({\\n message: 'Saved',\\n variant: 'success',\\n }),\\n },\\n});\\n```\\n\\nUse catalog introspection when generating code or when unsure:\\n\\n```ts\\nimport { getComponent } from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n\\nconst definition = getComponent('Button');\\nconsole.log(definition.events);\\nconsole.log(definition.propsSchema);\\n```\\n\\n## Actions\\n\\nAction creators are generated from the catalog and return opaque action bindings. Use generated creators instead of manually building action dictionaries.\\n\\n```ts\\nimport { navigate, setState, showNotification } from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n\\nconst notify = showNotification({\\n message: 'Saved',\\n variant: 'success',\\n});\\n\\nconst nav = navigate({\\n path: '/home',\\n openInNewTab: false,\\n});\\n\\nconst update = setState({\\n statePath: 'form.status',\\n value: 'submitted',\\n});\\n```\\n\\nAction creators can also take shared action options:\\n\\n```ts\\nconst dangerous = setState(\\n { statePath: 'record.deleted', value: true },\\n {\\n confirm: {\\n title: 'Delete record?',\\n message: 'This cannot be undone.',\\n confirmLabel: 'Delete',\\n cancelLabel: 'Cancel',\\n variant: 'danger',\\n },\\n }\\n);\\n```\\n\\n## Rendering\\n\\nUse the generated catalog `render()`:\\n\\n```ts\\nconst spec = render({\\n root,\\n state: {\\n title: 'Welcome',\\n },\\n});\\n```\\n\\nThe catalog renderer:\\n\\n- flattens the tree into `elements`\\n- generates IDs for elements without explicit IDs\\n- checks duplicate explicit IDs during render\\n- serializes props, events, expressions, children, and repeats\\n- adds `platform`, `catalog`, and `catalogVersion`\\n\\nExample output shape:\\n\\n```json\\n{\\n \\\"root\\\": \\\"root\\\",\\n \\\"elements\\\": {\\n \\\"root\\\": {\\n \\\"type\\\": \\\"VStack\\\",\\n \\\"props\\\": { \\\"gap\\\": 12 },\\n \\\"children\\\": [\\\"element-0\\\", \\\"element-1\\\"]\\n },\\n \\\"element-0\\\": {\\n \\\"type\\\": \\\"Text\\\",\\n \\\"props\\\": { \\\"text\\\": \\\"Welcome\\\" }\\n }\\n },\\n \\\"state\\\": { \\\"title\\\": \\\"Welcome\\\" },\\n \\\"platform\\\": \\\"web\\\",\\n \\\"catalog\\\": \\\"custom-apps\\\",\\n \\\"catalogVersion\\\": \\\"1.0.0\\\"\\n}\\n```\\n\\n## Validation\\n\\nValidate after render:\\n\\n```ts\\nconst errors = validate(spec);\\nif (errors.length > 0) {\\n throw new Error(errors.join('\\\\n'));\\n}\\n```\\n\\nUse validation in tests, LLM workflows, and service boundaries.\\n\\n## Introspection\\n\\nGenerated catalogs export compact and detailed introspection helpers:\\n\\n```ts\\nimport {\\n getActions,\\n getAction,\\n getComponents,\\n getComponent,\\n} from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n\\nconsole.log(getComponents());\\nconsole.log(getComponent('Button'));\\nconsole.log(getActions());\\nconsole.log(getAction('showNotification'));\\n```\\n\\nLLMs should call or inspect these helpers before generating SDK code.\\n\\n## Practical authoring rules\\n\\n- Use generated component builders and action creators.\\n- Keep `props` explicit and small.\\n- Use exact event names from generated types or `getComponent()`.\\n- Do not pass `children` to leaf components.\\n- Prefer catalog `render()` over core `createSpec().render()` for app specs.\\n- Validate any spec produced by an LLM or external transformation.\\n\",\n 'sdk-docs/typescript/state-expressions.md':\n \"# TypeScript state and expressions\\n\\nState and expressions make TypeScript-authored specs dynamic. The SDK uses typed path strings and phantom-typed expression objects so props and action params can accept runtime values while remaining type checked.\\n\\n## Define state\\n\\nDefine state as a TypeScript interface or type:\\n\\n```ts\\ninterface Todo {\\n id: string;\\n text: string;\\n done: boolean;\\n}\\n\\ninterface AppState {\\n user: {\\n name: string;\\n role: 'admin' | 'employee';\\n };\\n todos: Todo[];\\n count: number;\\n active: boolean;\\n}\\n```\\n\\nCreate helpers with `createSpec`:\\n\\n```ts\\nimport { createSpec } from '@rippling/pebble-sdui-web';\\n\\nconst specContext = createSpec<AppState>({\\n state: {\\n user: { name: 'Alice', role: 'admin' },\\n todos: [{ id: '1', text: 'Review', done: false }],\\n count: 1,\\n active: true,\\n },\\n});\\n\\nconst { $state, $bindState, $template, $cond, repeat } = specContext;\\n```\\n\\n## Read state paths\\n\\nUse `$state(path)` for read-only runtime refs.\\n\\n```ts\\nconst nameRef = $state('user.name');\\n// Renders as: { \\\"$state\\\": \\\"user.name\\\" }\\n```\\n\\nThe path is type checked against `AppState`. Invalid paths should fail TypeScript type checking.\\n\\n## Bind state\\n\\nUse `$bindState(path)` when a component should write back to state.\\n\\n```ts\\nconst nameBinding = $bindState('user.name');\\n// Renders as: { \\\"$bindState\\\": \\\"user.name\\\" }\\n```\\n\\nUse bindings only for props documented as writable, such as form values or selected values.\\n\\n## Templates\\n\\n`$template` is a tagged template helper for string interpolation.\\n\\n```ts\\nconst greeting = $template`Hello ${$state('user.name')}!`;\\n// Renders as: { \\\"$template\\\": \\\"Hello ${user.name}!\\\" }\\n```\\n\\nTemplate interpolations may include state refs, item refs, indexes, `null`, or `undefined`.\\n\\n## Conditions\\n\\nConditions are used for `visible` and `$cond()`.\\n\\n```ts\\nimport { equals, gt, truthy, and_, or_, not_ } from '@rippling/pebble-sdui-web';\\n\\nconst isAdmin = equals($state('user.role'), 'admin');\\nconst hasTodos = gt($state('count'), 0);\\nconst show = and_(isAdmin, hasTodos);\\n```\\n\\nAvailable condition helpers:\\n\\n- `equals(ref, value)`\\n- `neq(ref, value)`\\n- `gt(ref, value)`\\n- `gte(ref, value)`\\n- `lt(ref, value)`\\n- `lte(ref, value)`\\n- `truthy(ref)`\\n- `falsy(ref)`\\n- `not_(condition)`\\n- `and_(...conditions)` / `$and(...conditions)`\\n- `or_(...conditions)` / `$or(...conditions)`\\n\\n## Conditional expressions\\n\\nUse `$cond(condition, thenValue, elseValue)` for runtime prop values.\\n\\n```ts\\nconst statusColor = $cond(\\n equals($state('active'), true),\\n 'green',\\n 'gray'\\n);\\n```\\n\\nBoth branches should resolve to the same prop type.\\n\\n## Repeat over lists\\n\\n`repeat(path, key?)` creates a repeat binding and a typed item accessor.\\n\\n```ts\\nconst [todoRepeat, todo] = repeat('todos', 'id');\\n\\nconst textRef = todo.$('text'); // { \\\"$item\\\": \\\"text\\\" }\\nconst doneBind = todo.$bind('done'); // { \\\"$bindItem\\\": \\\"done\\\" }\\nconst indexRef = todo.$index(); // { \\\"$index\\\": true }\\n```\\n\\nAttach the repeat binding to the component that should render once per item:\\n\\n```ts\\nimport { Text } from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n\\nconst repeatedText = Text({\\n repeat: todoRepeat,\\n props: {\\n text: todo.$('text'),\\n },\\n});\\n```\\n\\n## Render helper on `createSpec`\\n\\n`createSpec()` includes a core `render(root)` helper, but catalog authors should prefer the generated catalog `render({ root, state })` because it stamps platform and catalog metadata.\\n\\nUse the core helper only in low-level tests or core-only tooling.\\n\\n## Serialization summary\\n\\n| TypeScript helper | Rendered shape | Use |\\n|---|---|---|\\n| `$state('path')` | `{ \\\"$state\\\": \\\"path\\\" }` | read state |\\n| `$bindState('path')` | `{ \\\"$bindState\\\": \\\"path\\\" }` | two-way state binding |\\n| `item.$('field')` | `{ \\\"$item\\\": \\\"field\\\" }` | read repeated item field |\\n| `item.$bind('field')` | `{ \\\"$bindItem\\\": \\\"field\\\" }` | bind repeated item field |\\n| `item.$index()` | `{ \\\"$index\\\": true }` | repeat index |\\n| `$template\\\\`...\\\\`` | `{ \\\"$template\\\": \\\"...\\\" }` | string interpolation |\\n| `$cond(...)` | `{ \\\"$cond\\\": ..., \\\"$then\\\": ..., \\\"$else\\\": ... }` | conditional prop value |\\n\",\n};\n","import { SDK_DOC_CONTENT_BY_PATH, SDK_DOCS } from './sdk-docs.generated';\n\n/** Metadata for a packaged SDK documentation file. */\nexport interface SdkDoc {\n /** Stable identifier for the documentation file. */\n key: string;\n /** Repo-relative Markdown file path, e.g. \"sdk-docs/typescript/README.md\". */\n filePath: string;\n /** Documentation title extracted from the file's first H1. */\n title: string;\n}\n\n/** Return the SDK documentation files packaged with this SDK. */\nexport function listSdkDocs(): SdkDoc[] {\n return SDK_DOCS.map(({ key, filePath, title }) => ({\n key,\n filePath,\n title,\n }));\n}\n\n/** Read a packaged SDK documentation file by repo-relative file path. */\nexport function readSdkDoc(filePath: string): string {\n if (!(filePath in SDK_DOC_CONTENT_BY_PATH)) {\n throw new Error(`Unknown SDK doc filePath: ${filePath}`);\n }\n\n return SDK_DOC_CONTENT_BY_PATH[filePath];\n}\n"],"names":["SDK_DOCS","SDK_DOC_CONTENT_BY_PATH","listSdkDocs","key","filePath","title","readSdkDoc"],"mappings":"gFAKO,MAAMA,EAA8B,CACzC,CACE,IAAK,gBACL,SAAU,qBACV,MAAO,8BAAA,EAET,CACE,IAAK,sBACL,SAAU,2BACV,MAAO,oBAAA,EAET,CACE,IAAK,kBACL,SAAU,uBACV,MAAO,UAAA,EAET,CACE,IAAK,kBACL,SAAU,uBACV,MAAO,UAAA,EAET,CACE,IAAK,oBACL,SAAU,yBACV,MAAO,YAAA,EAET,CACE,IAAK,oBACL,SAAU,gCACV,MAAO,gBAAA,EAET,CACE,IAAK,0CACL,SAAU,sDACV,MAAO,+CAAA,EAET,CACE,IAAK,+BACL,SAAU,2CACV,MAAO,kCAAA,CAEX,EAEaC,EAA4D,CACvE,qBACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EACF,2BACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EACF,uBACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EACF,uBACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EACF,yBACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EACF,gCACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EACF,sDACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EACF,2CACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,CACJ,ECpDO,SAASC,GAAwB,CACtC,OAAOF,EAAS,IAAI,CAAC,CAAE,IAAAG,EAAK,SAAAC,EAAU,MAAAC,MAAa,CACjD,IAAAF,EACA,SAAAC,EACA,MAAAC,CAAA,EACA,CACJ,CAGO,SAASC,EAAWF,EAA0B,CACnD,GAAI,EAAEA,KAAYH,GAChB,MAAM,IAAI,MAAM,6BAA6BG,CAAQ,EAAE,EAGzD,OAAOH,EAAwBG,CAAQ,CACzC"}
1
+ {"version":3,"file":"sdk-docs.cjs","sources":["../src/sdk-docs.generated.ts","../src/sdk-docs.ts"],"sourcesContent":["// This file is generated by codegen/generate-sdk-docs.ts.\n// Do not edit this file directly.\n\nimport type { SdkDoc } from './sdk-docs';\n\nexport const SDK_DOCS: readonly SdkDoc[] = [\n {\n key: 'shared.readme',\n filePath: 'sdk-docs/README.md',\n title: 'Pebble Kit SDK documentation',\n },\n {\n key: 'shared.ai-authoring',\n filePath: 'sdk-docs/ai-authoring.md',\n title: 'AI authoring guide',\n },\n {\n key: 'shared.catalogs',\n filePath: 'sdk-docs/catalogs.md',\n title: 'Catalogs',\n },\n {\n key: 'shared.concepts',\n filePath: 'sdk-docs/concepts.md',\n title: 'Concepts',\n },\n {\n key: 'shared.validation',\n filePath: 'sdk-docs/validation.md',\n title: 'Validation',\n },\n {\n key: 'typescript.readme',\n filePath: 'sdk-docs/typescript/README.md',\n title: 'TypeScript SDK',\n },\n {\n key: 'typescript.components-actions-rendering',\n filePath: 'sdk-docs/typescript/components-actions-rendering.md',\n title: 'TypeScript components, actions, and rendering',\n },\n {\n key: 'typescript.state-expressions',\n filePath: 'sdk-docs/typescript/state-expressions.md',\n title: 'TypeScript state and expressions',\n },\n];\n\nexport const SDK_DOC_CONTENT_BY_PATH: Readonly<Record<string, string>> = {\n 'sdk-docs/README.md':\n '# Pebble Kit SDK documentation\\n\\nPebble Kit is a server-driven UI (SDUI) SDK for producing JSON specs that the `json-render` runtime can render. The SDK is designed for two authors:\\n\\n- **Humans** write typed Python or TypeScript code, compose component trees, bind props to state, and render a validated spec.\\n- **LLMs** use catalog metadata, examples, and validation errors to generate SDK code or JSON specs safely, then iterate until validation passes.\\n\\nThis documentation focuses on the public authoring model: catalogs, components, actions, state expressions, rendering, and validation.\\n\\n## What the SDK does\\n\\nThe SDK lets an author describe UI as a tree:\\n\\n1. Choose a platform package, such as `pebble_sdui_web` or `pebble_sdui_mobile`.\\n2. Import a generated catalog module, such as `pebble_sdui_web.catalogs.AiChatCatalogV1`.\\n3. Define initial state with plain annotated Python classes.\\n4. Create components and wire events to generated action creators.\\n5. Use expressions (`$state`, `$bindState`, `$item`, `$cond`, `$template`) for runtime behavior.\\n6. Call the catalog `render()` function to produce the flat JSON wire format.\\n7. Call the catalog `validate()` function when specs may be generated or transformed.\\n\\n## Documentation map\\n\\nThese links point to the canonical files in the repo so they still work when this README is shown inside another site or tool.\\n\\n- [ai-authoring.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/ai-authoring.md) — how to prompt and constrain LLM authors.\\n- [concepts.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/concepts.md) — core SDUI concepts shared by humans and LLMs.\\n- [catalogs.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/catalogs.md) — generated catalogs, component discovery, and action discovery.\\n- [validation.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/validation.md) — validation workflow and error repair loop.\\n- [python/README.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/python/README.md) — Python SDK quick start.\\n- [python/components-actions-rendering.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/python/components-actions-rendering.md) — Python components, events, actions, and render output.\\n- [python/state-expressions.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/python/state-expressions.md) — Python state, refs, repeat, templates, conditions, and conditional expressions.\\n- [typescript/README.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/typescript/README.md) — TypeScript SDK quick start.\\n- [typescript/components-actions-rendering.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/typescript/components-actions-rendering.md) — TypeScript components, events, actions, and render output.\\n- [typescript/state-expressions.md](https://github.com/Rippling/pebble-kit/blob/main/sdk-docs/typescript/state-expressions.md) — TypeScript state, refs, repeat, templates, conditions, and conditional expressions.\\n\\n## Quick Python example\\n\\n```python\\nfrom pebble_sdui_web import create_state, template, truthy\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import (\\n ConfirmationCard,\\n render,\\n submit_tool_output,\\n validate,\\n)\\n\\nclass AppState:\\n employee_name: str\\n is_ready: bool\\n\\nstate = create_state(AppState, {\\n \"employee_name\": \"Alice Nguyen\",\\n \"is_ready\": True,\\n})\\n\\nroot = ConfirmationCard(\\n id=\"confirm-employee\",\\n question=template(\"Confirm action for \", state.ref(lambda s: s.employee_name), \"?\"),\\n description=\"This choice will be submitted back to the workflow.\",\\n events={\\n \"confirm\": submit_tool_output(output={\"confirmed\": True}),\\n \"cancel\": submit_tool_output(output={\"confirmed\": False}),\\n },\\n visible=truthy(state.ref(lambda s: s.is_ready)),\\n)\\n\\nspec = render(root, state.to_dict())\\nerrors = validate(spec)\\nassert errors == [], errors\\n```\\n\\n## Authoring guidance\\n\\nFor humans:\\n\\n- Prefer SDK builders over hand-writing JSON.\\n- Let type checkers catch prop, event, and state reference mistakes early.\\n- Keep state explicit and small; pass only data the rendered UI needs.\\n- Use catalog `validate()` before returning specs from untrusted or generated paths.\\n\\nFor LLMs:\\n\\n- First inspect the target catalog with `get_components()`, `get_component()`, `get_actions()`, `get_action()`, and `get_computed_functions()`.\\n- Generate a small component tree before adding dynamic behavior.\\n- Never invent component names, prop names, event names, action names, or computed function names.\\n- Run `validate(spec)` and repair from the returned error messages.\\n- Prefer SDK code generation over raw JSON because the SDK handles IDs, refs, and serialization.\\n',\n 'sdk-docs/ai-authoring.md':\n '# AI authoring guide\\n\\nThis guide explains how an LLM should use the SDK and catalog metadata to produce correct SDUI specs. It is also useful for humans building agent workflows around Pebble Kit.\\n\\n## Recommended LLM workflow\\n\\nPrefer this loop:\\n\\n1. **Identify target platform and catalog.** Example: web + `AiChatCatalogV1`.\\n2. **Inspect catalog capabilities.** Use `get_components()`, `get_component()`, `get_actions()`, `get_action()`, and `get_computed_functions()`.\\n3. **Plan a small tree.** Pick the root and children. Confirm each component supports children before nesting.\\n4. **Generate SDK code, not raw JSON.** SDK code gives better type hints and automatic serialization.\\n5. **Render.** Call the catalog `render(root, state)`.\\n6. **Validate.** Call the catalog `validate(spec)`.\\n7. **Repair from errors.** Treat validation errors as the next prompt context.\\n8. **Return the spec or checked-in code.** Include validation status.\\n\\n## Why SDK code is better than raw JSON\\n\\nSDK code avoids common LLM mistakes:\\n\\n- element IDs are generated or checked for duplicates\\n- component props are spelled by generated dataclass fields\\n- action creators serialize params correctly\\n- state refs serialize as `$state`, `$bindState`, `$item`, and `$index`\\n- catalog renderers add platform/catalog metadata\\n- validation catches schema and structural problems\\n\\nRaw JSON is acceptable only when an integration cannot execute SDK code. In that mode, the LLM must still use catalog definitions and `validate()`.\\n\\n## Prompt pattern for LLMs\\n\\nUse a prompt like this when asking an LLM to author a UI:\\n\\n```text\\nYou are authoring a Pebble Kit SDUI spec.\\nTarget package: pebble_sdui_web\\nTarget catalog: pebble_sdui_web.catalogs.AiChatCatalogV1\\n\\nRules:\\n- Use only components returned by get_components().\\n- Before using a component, inspect get_component(name).\\n- Use only props defined in propsSchema.\\n- Include all required props.\\n- Use only events listed by the component definition.\\n- Use only actions returned by get_actions().\\n- Use only computed functions returned by get_computed_functions().\\n- Prefer generated SDK code over hand-written JSON.\\n- Call render(root, state) and then validate(spec).\\n- If validate returns errors, fix the code and validate again.\\n\\nUser goal:\\n<goal here>\\n```\\n\\n## Minimal executable harness\\n\\n```python\\nfrom pebble_sdui_web import create_state\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import (\\n ConfirmationCard,\\n render,\\n submit_tool_output,\\n validate,\\n)\\n\\nclass AppState:\\n is_ready: bool\\n\\nstate = create_state(AppState, {\"is_ready\": True})\\n\\nroot = ConfirmationCard(\\n question=\"Do you want to continue?\",\\n events={\"confirm\": submit_tool_output(output=\"yes\")},\\n)\\n\\nspec = render(root, state.to_dict())\\nerrors = validate(spec)\\nif errors:\\n raise ValueError(\"Invalid spec:\\\\n\" + \"\\\\n\".join(errors))\\n```\\n\\n## Repair loop\\n\\nWhen validation fails, preserve the full error text. Then ask the model to make the smallest change that fixes the first error.\\n\\nExample repair prompt:\\n\\n```text\\nThe spec failed validation:\\n- Element \\'confirm\\': unknown event \\'submit\\'. Valid: [\\'confirm\\', \\'cancel\\']\\n\\nFix the SDK code. Do not change the user\\'s intent. Do not invent new events.\\n```\\n\\nRepair strategy:\\n\\n- Unknown component: choose a component from `get_components()`.\\n- Unknown prop: remove it or map it to a documented prop from `propsSchema`.\\n- Missing required prop: add the prop with a safe value or state ref.\\n- Unknown event: use one of the component\\'s listed events.\\n- Unknown action: use one from `get_actions()`.\\n- Unknown computed function: use one from `get_computed_functions()`.\\n- Children not accepted: remove children or choose a container component.\\n- Root missing: render the actual root returned by the tree.\\n\\n## LLM safety rules\\n\\nAn LLM should not:\\n\\n- invent schema fields because they sound plausible\\n- depend on undocumented renderer behavior\\n- manually serialize Python SDK objects unless using `render()` helpers\\n- mix components from different catalogs\\n- output a spec without reporting validation status\\n- ignore validation errors because the UI “looks close”\\n\\n## Human review checklist for AI-authored specs\\n\\nBefore accepting an AI-authored spec, check:\\n\\n- Does the UI satisfy the user goal with the smallest reasonable tree?\\n- Are all component names, props, events, and actions catalog-backed?\\n- Is state minimal and free of sensitive data not needed by the UI?\\n- Are bindings used only for data the UI should write back?\\n- Are action payloads safe and expected by the receiving workflow?\\n- Did `validate(spec)` return `[]`?\\n\\n## Good output format from an AI authoring service\\n\\n```json\\n{\\n \"status\": \"valid\",\\n \"catalog\": \"AiChatCatalogV1\",\\n \"catalogVersion\": \"1.0.0\",\\n \"spec\": { \"root\": \"...\", \"elements\": {}, \"state\": {} },\\n \"validationErrors\": []\\n}\\n```\\n\\nIf invalid, return the errors and do not send the spec to production rendering.\\n',\n 'sdk-docs/catalogs.md':\n '# Catalogs\\n\\nCatalogs are generated SDK modules that define the allowed components, actions, schemas, docs, examples, and validators for a target UI surface.\\n\\n## Why catalogs matter\\n\\nA catalog is the source of truth for what an author may use. Humans should read catalog docs for intent and prop semantics. LLMs should inspect catalog metadata before generating code or JSON.\\n\\nA spec should be authored against one catalog at a time. The catalog renderer adds metadata such as:\\n\\n```json\\n{\\n \"platform\": \"web\",\\n \"catalog\": \"AiChatCatalogV1\",\\n \"catalogVersion\": \"1.0.0\"\\n}\\n```\\n\\n## Python catalog imports\\n\\nExamples:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import (\\n ConfirmationCard,\\n SingleSelectDisambiguation,\\n render,\\n submit_tool_output,\\n validate,\\n)\\n\\nfrom pebble_sdui_mobile.catalogs.MobileGenUICatalogV1 import (\\n Button,\\n render,\\n validate,\\n)\\n```\\n\\nGenerated catalog modules export:\\n\\n- component classes and nested prop types\\n- event TypedDicts\\n- action creators\\n- `CATALOG_NAME`\\n- `CATALOG_VERSION`\\n- `get_components()`\\n- `get_component(name)`\\n- `get_actions()`\\n- `get_action(name)`\\n- `get_functions()`\\n- `get_function(name)`\\n- `get_computed_functions()`\\n- `render(root, state=None)`\\n- `validate(spec)`\\n\\n## Component discovery\\n\\nUse `get_components()` for a compact list of names and descriptions:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import get_components\\n\\nfor name, description in get_components().items():\\n print(name, \"-\", description)\\n```\\n\\nUse `get_component(name)` before selecting props, events, or children:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import get_component\\n\\ndefinition = get_component(\"AIChat_ConfirmationCard\")\\nprint(definition[\"description\"])\\nprint(definition[\"docs\"])\\nprint(definition[\"events\"])\\nprint(definition[\"propsSchema\"])\\nprint(definition[\"acceptsChildren\"])\\n```\\n\\n## Action discovery\\n\\nUse `get_actions()` for a compact action list:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import get_actions\\n\\nprint(get_actions())\\n```\\n\\nUse `get_action(name)` for params and docs:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import get_action\\n\\nsubmit = get_action(\"submitToolOutput\")\\nprint(submit[\"description\"])\\nprint(submit.get(\"paramsSchema\"))\\n```\\n\\n## Computed function discovery\\n\\nUse `get_functions()` for a compact computed-function list:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import get_functions\\n\\nprint(get_functions())\\n```\\n\\nUse `get_computed_functions()` or `get_function(name)` for params, return schemas, and docs:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import get_computed_functions, get_function\\n\\nfunctions = get_computed_functions()\\ndefinition = get_function(\"dateTime_format\")\\nprint(functions)\\nprint(definition.get(\"paramsSchema\"))\\nprint(definition.get(\"returnsSchema\"))\\n```\\n\\n## How humans should use catalogs\\n\\n1. Start with the catalog for the target surface.\\n2. Use component docstrings and generated types in your editor.\\n3. Read `get_component()` when a prop\\'s runtime meaning is unclear.\\n4. Prefer generated action creators and computed-function helpers over raw dictionaries.\\n5. Validate rendered specs in tests or at service boundaries.\\n\\n## How LLMs should use catalogs\\n\\nLLMs should treat the catalog as hard constraints:\\n\\n1. Call or inspect `get_components()` to choose candidates.\\n2. Call or inspect `get_component(name)` for exact prop names, required props, events, and child support.\\n3. Call or inspect `get_actions()` and `get_action(name)` for allowed action names and params.\\n4. Call or inspect `get_computed_functions()` before using computed values.\\n5. Generate SDK code using only exported component, action, and computed-function symbols.\\n6. Render the tree.\\n7. Validate and repair any errors.\\n\\nLLMs must not invent:\\n\\n- component names\\n- prop names\\n- event names\\n- action names\\n- computed function names\\n- enum/literal values\\n- child support on leaf components\\n\\n## Choosing a component\\n\\nPrefer the most specific component that matches the user\\'s intent. If two components look similar:\\n\\n- Prefer a component whose description mentions the target workflow.\\n- Prefer fewer props over many unused props.\\n- Prefer built-in component behavior documented in `docs` instead of recreating it with custom state.\\n- If the catalog says a component auto-binds or auto-disables behavior, do not duplicate that behavior unless required.\\n\\n## Catalog upgrades\\n\\nWhen a catalog version changes:\\n\\n- Re-run validation on representative specs.\\n- Check changed component definitions for prop/event differences.\\n- For LLM prompt packs, regenerate the catalog excerpt used by the model.\\n- Keep examples small so they are easy to update.\\n',\n 'sdk-docs/concepts.md':\n '# Concepts\\n\\nPebble Kit authors UI specs for a server-driven UI runtime. Humans and LLMs should use the same mental model: a catalog defines what can be rendered, the SDK builds a component tree, and `render()` converts that tree into the runtime wire format.\\n\\n## Spec\\n\\nA **spec** is the JSON object sent to the renderer. It contains:\\n\\n- `platform` — target platform, such as `web` or `mobile`.\\n- `catalog` and `catalogVersion` — the component/action vocabulary used by the spec.\\n- `root` — the ID of the root element.\\n- `elements` — a flat map of element ID to element definition.\\n- `state` — optional initial state for runtime expressions.\\n\\nSDK authors normally build a tree and let `render()` create this flat spec.\\n\\n## Catalog\\n\\nA **catalog** is a generated module for one UI vocabulary. It contains:\\n\\n- component classes/builders\\n- action creators\\n- catalog metadata\\n- introspection helpers\\n- a catalog-scoped `render()` function\\n- a catalog-scoped `validate()` function\\n\\nCatalogs are isolated. Do not mix components from different catalogs in one tree unless the catalog explicitly supports it.\\n\\n## Component\\n\\nA **component** is a generated class that represents a renderable UI element. Component fields become runtime props. Common element-level fields include:\\n\\n- `id` — optional explicit element ID.\\n- `children` — nested child elements when supported.\\n- `events` — event handlers keyed by event name.\\n- `visible` — condition controlling visibility.\\n- `watch_handlers` — actions triggered by state path changes.\\n- `repeat` — list repetition binding.\\n\\n## Action\\n\\nAn **action** is an event-side effect. Catalog action creators return opaque `ActionBinding` values. Use generated action creators instead of constructing action dictionaries by hand.\\n\\nActions may accept `ActionOptions` for confirmation, success handling, error handling, or `preventDefault` where supported.\\n\\n## State\\n\\n**State** is the runtime data model. Python authors define state shape with annotated classes and initial values with dictionaries. State paths are serialized into expressions such as:\\n\\n```json\\n{ \"$state\": \"/user/name\" }\\n```\\n\\nUse state for values that the runtime can read, bind, compare, or update.\\n\\n## Binding\\n\\nA **binding** is a two-way reference. It lets an input-like component write back to state:\\n\\n```json\\n{ \"$bindState\": \"/form/email\" }\\n```\\n\\nUse read-only refs for display and comparisons. Use bindings only when the component is expected to update state.\\n\\n## Expressions\\n\\nExpressions are runtime-resolved values used inside props, visibility, action params, and repeat definitions.\\n\\nCommon expression forms:\\n\\n- `$state` — read a state path.\\n- `$bindState` — two-way bind a state path.\\n- `$item` — read a field from the current repeated item.\\n- `$bindItem` — two-way bind a repeated item field.\\n- `$index` — current repeat index.\\n- `$template` — interpolate state refs into a string.\\n- `$cond` — choose between two values based on a condition.\\n\\n## Conditions\\n\\nA **condition** controls visibility or conditional expressions. Conditions can compare refs against literals or other state refs:\\n\\n- equals / not equals\\n- greater than / greater than or equal\\n- less than / less than or equal\\n- truthy / falsy\\n- logical `and_`, `or_`, `not_`\\n\\n## Repeat\\n\\nA **repeat** renders an element once per item in a list state path. It provides:\\n\\n- a repeat binding attached to the repeated component\\n- an item accessor for `$item`, `$bindItem`, and `$index`\\n\\nUse repeat for data-driven lists instead of manually creating fixed children when the list length is dynamic.\\n\\n## Rendering\\n\\n`render(root, state)` walks the tree, assigns IDs where needed, serializes props and expressions, and returns the flat spec. Generated catalog renderers also stamp `platform`, `catalog`, and `catalogVersion`.\\n\\n## Validation\\n\\n`validate(spec)` checks a rendered or generated spec against the catalog. Validation returns a list of error strings; an empty list means valid.\\n\\nUse validation especially when:\\n\\n- an LLM created or edited the spec\\n- JSON was hand-written\\n- a spec crosses service boundaries\\n- a component catalog was upgraded\\n',\n 'sdk-docs/validation.md':\n '# Validation\\n\\nValidation checks a spec against a catalog\\'s component schemas and structural rules. It is required for LLM-authored or hand-authored JSON and recommended for service boundaries.\\n\\n## API\\n\\nGenerated catalog modules export `validate(spec)`:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import validate\\n\\nerrors: list[str] = validate(spec)\\nif errors:\\n raise ValueError(\"Invalid SDUI spec:\\\\n\" + \"\\\\n\".join(errors))\\n```\\n\\nAn empty list means the spec is valid:\\n\\n```python\\nassert validate(spec) == []\\n```\\n\\n## What validation checks\\n\\nCatalog validation checks:\\n\\n- the root ID exists in the `elements` map\\n- every element `type` is known by the catalog\\n- element props match the component `propsSchema`\\n- reactive refs are accepted where literal props are accepted\\n- event names are valid for the component\\n- leaf components do not receive children\\n\\nValidation does not prove the receiving business action will succeed. It proves the UI spec matches the catalog shape.\\n\\n## Validate after rendering\\n\\nHumans should usually validate the rendered spec, not the component tree:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import ConfirmationCard, render, submit_tool_output, validate\\n\\nroot = ConfirmationCard(\\n question=\"Proceed?\",\\n events={\"confirm\": submit_tool_output(output=True)},\\n)\\n\\nspec = render(root)\\nerrors = validate(spec)\\nassert errors == [], errors\\n```\\n\\n## Validate generated JSON\\n\\nIf an LLM or external service emits raw JSON, validate before rendering it in a client:\\n\\n```python\\nfrom pebble_sdui_web.catalogs.AiChatCatalogV1 import validate\\n\\nerrors = validate(candidate_spec)\\nif errors:\\n return {\"status\": \"invalid\", \"validationErrors\": errors}\\n\\nreturn {\"status\": \"valid\", \"spec\": candidate_spec, \"validationErrors\": []}\\n```\\n\\n## Common errors and fixes\\n\\n| Error type | Likely cause | Fix |\\n|---|---|---|\\n| `Root element ... not found` | `root` points to a missing ID | Render from the real root or fix the ID |\\n| `unknown type` | Component name is not in the catalog | Use `get_components()` and generated component classes |\\n| `props ... is a required property` | Required prop omitted | Add the required prop |\\n| `additional properties are not allowed` | Invented or misspelled prop | Use exact `propsSchema` names |\\n| `unknown event` | Invented or wrong event name | Use events from `get_component(name)[\"events\"]` |\\n| `does not accept children` | Children passed to a leaf component | Remove children or use a container component |\\n| Type mismatch | Prop value shape is wrong | Match the JSON Schema type or use a compatible reactive ref |\\n\\n## LLM repair workflow\\n\\nFor AI-generated specs, repair one validation class at a time:\\n\\n1. Run `validate(spec)`.\\n2. Feed all errors back to the LLM.\\n3. Require the LLM to cite the catalog field it used to fix each error.\\n4. Regenerate SDK code or JSON.\\n5. Validate again.\\n6. Stop only when errors are empty.\\n\\nPrompt template:\\n\\n```text\\nValidation failed for this Pebble Kit spec:\\n<errors>\\n\\nRepair rules:\\n- Make the smallest change.\\n- Use only catalog-backed component, prop, event, and action names.\\n- Preserve the user intent.\\n- Return updated SDK code and validation status.\\n```\\n\\n## Testing pattern\\n\\nAdd tests around representative specs:\\n\\n```python\\ndef test_confirmation_card_spec_is_valid() -> None:\\n from pebble_sdui_web.catalogs.AiChatCatalogV1 import ConfirmationCard, render, submit_tool_output, validate\\n\\n spec = render(\\n ConfirmationCard(\\n question=\"Approve?\",\\n events={\"confirm\": submit_tool_output(output=\"approved\")},\\n )\\n )\\n\\n assert validate(spec) == []\\n```\\n\\n## Production guidance\\n\\n- Validate specs from LLMs before sending them to clients.\\n- Validate during CI for checked-in examples or fixture specs.\\n- Log validation errors with catalog name and version.\\n- Treat validation failures as authoring bugs, not renderer bugs.\\n- Keep validation close to the catalog used to render or consume the spec.\\n',\n 'sdk-docs/typescript/README.md':\n \"# TypeScript SDK\\n\\nThe TypeScript SDK lets frontend and backend TypeScript code author type-safe SDUI specs. Platform packages export shared expression helpers, while generated catalog subpaths export components, actions, rendering, introspection, and validation.\\n\\n## Packages and imports\\n\\nCore authoring helpers come from the platform package:\\n\\n```ts\\nimport { createSpec, equals, truthy, and_ } from '@rippling/pebble-sdui-web';\\n```\\n\\nCatalog-specific builders come from generated catalog subpaths:\\n\\n```ts\\nimport {\\n Button,\\n Text,\\n VStack,\\n render,\\n showNotification,\\n validate,\\n} from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n```\\n\\n## Quick start\\n\\n```ts\\nimport { createSpec, truthy } from '@rippling/pebble-sdui-web';\\nimport {\\n Button,\\n Text,\\n VStack,\\n render,\\n showNotification,\\n validate,\\n} from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n\\ninterface AppState {\\n userName: string;\\n isReady: boolean;\\n}\\n\\nconst { $state, $template } = createSpec<AppState>({\\n state: {\\n userName: 'Alice Nguyen',\\n isReady: true,\\n },\\n});\\n\\nconst root = VStack({\\n id: 'root',\\n props: { gap: 12 },\\n visible: truthy($state('isReady')),\\n children: [\\n Text({\\n props: {\\n text: $template`Hello ${$state('userName')}`,\\n },\\n }),\\n Button({\\n props: {\\n label: 'Continue',\\n appearance: 'PRIMARY',\\n },\\n on: {\\n press: showNotification({\\n message: 'Continuing',\\n variant: 'success',\\n }),\\n },\\n }),\\n ],\\n});\\n\\nconst spec = render({\\n root,\\n state: {\\n userName: 'Alice Nguyen',\\n isReady: true,\\n },\\n});\\n\\nconst errors = validate(spec);\\nif (errors.length > 0) {\\n throw new Error(`Invalid spec:\\\\n${errors.join('\\\\n')}`);\\n}\\n```\\n\\n## Authoring steps\\n\\n1. Define a TypeScript state interface.\\n2. Create state helpers with `createSpec<State>({ state })`.\\n3. Import components/actions from one generated catalog subpath.\\n4. Compose a component tree with generated builder functions.\\n5. Use `$state()`, `$bindState()`, `$template`, `$cond()`, and `repeat()` for dynamic behavior.\\n6. Call the catalog `render({ root, state })`.\\n7. Call the catalog `validate(spec)` for generated, hand-authored, or externally consumed specs.\\n\\n## Human authoring benefits\\n\\n- Editor autocomplete for component props and event names.\\n- TypeScript validates state paths and expression result types.\\n- Component builders enforce whether `children` and `on` are allowed.\\n- Action creators enforce action params.\\n- Catalog `render()` stamps platform/catalog metadata.\\n\\n## LLM authoring benefits\\n\\n- Catalog introspection gives exact names and schemas.\\n- SDK code is easier to validate and repair than raw JSON.\\n- Generated builders prevent many invalid tree shapes.\\n- Validation errors provide deterministic repair feedback.\\n\\n## More TypeScript docs\\n\\n- [components-actions-rendering.md](./components-actions-rendering.md)\\n- [state-expressions.md](./state-expressions.md)\\n\",\n 'sdk-docs/typescript/components-actions-rendering.md':\n \"# TypeScript components, actions, and rendering\\n\\nGenerated catalog subpaths provide component builder functions, prop/event types, action creators, introspection helpers, a catalog `render()` function, and `validate()`.\\n\\n## Import from one catalog\\n\\nKeep a tree within one generated catalog:\\n\\n```ts\\nimport {\\n Button,\\n Text,\\n VStack,\\n render,\\n showNotification,\\n validate,\\n} from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n```\\n\\nDo not mix components from different platforms or catalogs in one spec.\\n\\n## Components\\n\\nComponents are generated builder functions. They accept an input object with:\\n\\n- `id` — optional explicit element ID.\\n- `props` — component props.\\n- `visible` — visibility condition or boolean.\\n- `repeat` — repeat binding.\\n- `on` — event handlers, only when the component has events.\\n- `children` — child elements, only when the component accepts children.\\n\\n```ts\\nconst title = Text({\\n id: 'title',\\n props: {\\n text: 'Welcome',\\n typestyle: 'title3',\\n },\\n});\\n```\\n\\nContainer components accept children when generated with child support:\\n\\n```ts\\nconst root = VStack({\\n id: 'root',\\n props: { gap: 12 },\\n children: [\\n Text({ props: { text: 'Welcome' } }),\\n Button({ props: { label: 'Continue', appearance: 'PRIMARY' } }),\\n ],\\n});\\n```\\n\\nIf TypeScript rejects `children`, the component is a leaf. Choose a container component or remove the children.\\n\\n## Props and expression values\\n\\nGenerated component props accept either literal values or compatible expressions.\\n\\n```ts\\nimport { createSpec } from '@rippling/pebble-sdui-web';\\nimport { Text } from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n\\ninterface AppState {\\n title: string;\\n}\\n\\nconst { $state } = createSpec<AppState>({ state: { title: 'Hello' } });\\n\\nconst title = Text({\\n props: {\\n text: $state('title'),\\n },\\n});\\n```\\n\\n## Events\\n\\nEvents are component-specific and type checked. For example, `Button` supports events such as `press`.\\n\\n```ts\\nconst button = Button({\\n props: { label: 'Save', appearance: 'PRIMARY' },\\n on: {\\n press: showNotification({\\n message: 'Saved',\\n variant: 'success',\\n }),\\n },\\n});\\n```\\n\\nUse catalog introspection when generating code or when unsure:\\n\\n```ts\\nimport { getComponent } from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n\\nconst definition = getComponent('Button');\\nconsole.log(definition.events);\\nconsole.log(definition.propsSchema);\\n```\\n\\n## Actions\\n\\nAction creators are generated from the catalog and return opaque action bindings. Use generated creators instead of manually building action dictionaries.\\n\\n```ts\\nimport { navigate, setState, showNotification } from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n\\nconst notify = showNotification({\\n message: 'Saved',\\n variant: 'success',\\n});\\n\\nconst nav = navigate({\\n path: '/home',\\n openInNewTab: false,\\n});\\n\\nconst update = setState({\\n statePath: 'form.status',\\n value: 'submitted',\\n});\\n```\\n\\nAction creators can also take shared action options:\\n\\n```ts\\nconst dangerous = setState(\\n { statePath: 'record.deleted', value: true },\\n {\\n confirm: {\\n title: 'Delete record?',\\n message: 'This cannot be undone.',\\n confirmLabel: 'Delete',\\n cancelLabel: 'Cancel',\\n variant: 'danger',\\n },\\n }\\n);\\n```\\n\\n## Rendering\\n\\nUse the generated catalog `render()`:\\n\\n```ts\\nconst spec = render({\\n root,\\n state: {\\n title: 'Welcome',\\n },\\n});\\n```\\n\\nThe catalog renderer:\\n\\n- flattens the tree into `elements`\\n- generates IDs for elements without explicit IDs\\n- checks duplicate explicit IDs during render\\n- serializes props, events, expressions, children, and repeats\\n- adds `platform`, `catalog`, and `catalogVersion`\\n\\nExample output shape:\\n\\n```json\\n{\\n \\\"root\\\": \\\"root\\\",\\n \\\"elements\\\": {\\n \\\"root\\\": {\\n \\\"type\\\": \\\"VStack\\\",\\n \\\"props\\\": { \\\"gap\\\": 12 },\\n \\\"children\\\": [\\\"element-0\\\", \\\"element-1\\\"]\\n },\\n \\\"element-0\\\": {\\n \\\"type\\\": \\\"Text\\\",\\n \\\"props\\\": { \\\"text\\\": \\\"Welcome\\\" }\\n }\\n },\\n \\\"state\\\": { \\\"title\\\": \\\"Welcome\\\" },\\n \\\"platform\\\": \\\"web\\\",\\n \\\"catalog\\\": \\\"custom-apps\\\",\\n \\\"catalogVersion\\\": \\\"1.0.0\\\"\\n}\\n```\\n\\n## Validation\\n\\nValidate after render:\\n\\n```ts\\nconst errors = validate(spec);\\nif (errors.length > 0) {\\n throw new Error(errors.join('\\\\n'));\\n}\\n```\\n\\nUse validation in tests, LLM workflows, and service boundaries.\\n\\n## Introspection\\n\\nGenerated catalogs export compact and detailed introspection helpers:\\n\\n```ts\\nimport {\\n getActions,\\n getAction,\\n getComputedFunctions,\\n getComponents,\\n getComponent,\\n} from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n\\nconsole.log(getComponents());\\nconsole.log(getComponent('Button'));\\nconsole.log(getActions());\\nconsole.log(getAction('showNotification'));\\nconsole.log(getComputedFunctions());\\n```\\n\\nLLMs should call or inspect these helpers before generating SDK code.\\n\\n## Practical authoring rules\\n\\n- Use generated component builders and action creators.\\n- Keep `props` explicit and small.\\n- Use exact event names from generated types or `getComponent()`.\\n- Do not pass `children` to leaf components.\\n- Prefer catalog `render()` over core `createSpec().render()` for app specs.\\n- Validate any spec produced by an LLM or external transformation.\\n\",\n 'sdk-docs/typescript/state-expressions.md':\n \"# TypeScript state and expressions\\n\\nState and expressions make TypeScript-authored specs dynamic. The SDK uses typed path strings and phantom-typed expression objects so props and action params can accept runtime values while remaining type checked.\\n\\n## Define state\\n\\nDefine state as a TypeScript interface or type:\\n\\n```ts\\ninterface Todo {\\n id: string;\\n text: string;\\n done: boolean;\\n}\\n\\ninterface AppState {\\n user: {\\n name: string;\\n role: 'admin' | 'employee';\\n };\\n todos: Todo[];\\n count: number;\\n active: boolean;\\n}\\n```\\n\\nCreate helpers with `createSpec`:\\n\\n```ts\\nimport { createSpec } from '@rippling/pebble-sdui-web';\\n\\nconst specContext = createSpec<AppState>({\\n state: {\\n user: { name: 'Alice', role: 'admin' },\\n todos: [{ id: '1', text: 'Review', done: false }],\\n count: 1,\\n active: true,\\n },\\n});\\n\\nconst { $state, $bindState, $template, $cond, repeat } = specContext;\\n```\\n\\n## Read state paths\\n\\nUse `$state(path)` for read-only runtime refs.\\n\\n```ts\\nconst nameRef = $state('user.name');\\n// Renders as: { \\\"$state\\\": \\\"user.name\\\" }\\n```\\n\\nThe path is type checked against `AppState`. Invalid paths should fail TypeScript type checking.\\n\\n## Bind state\\n\\nUse `$bindState(path)` when a component should write back to state.\\n\\n```ts\\nconst nameBinding = $bindState('user.name');\\n// Renders as: { \\\"$bindState\\\": \\\"user.name\\\" }\\n```\\n\\nUse bindings only for props documented as writable, such as form values or selected values.\\n\\n## Templates\\n\\n`$template` is a tagged template helper for string interpolation.\\n\\n```ts\\nconst greeting = $template`Hello ${$state('user.name')}!`;\\n// Renders as: { \\\"$template\\\": \\\"Hello ${user.name}!\\\" }\\n```\\n\\nTemplate interpolations may include state refs, item refs, indexes, `null`, or `undefined`.\\n\\n## Conditions\\n\\nConditions are used for `visible` and `$cond()`.\\n\\n```ts\\nimport { equals, gt, truthy, and_, or_, not_ } from '@rippling/pebble-sdui-web';\\n\\nconst isAdmin = equals($state('user.role'), 'admin');\\nconst hasTodos = gt($state('count'), 0);\\nconst show = and_(isAdmin, hasTodos);\\n```\\n\\nAvailable condition helpers:\\n\\n- `equals(ref, value)`\\n- `neq(ref, value)`\\n- `gt(ref, value)`\\n- `gte(ref, value)`\\n- `lt(ref, value)`\\n- `lte(ref, value)`\\n- `truthy(ref)`\\n- `falsy(ref)`\\n- `not_(condition)`\\n- `and_(...conditions)` / `$and(...conditions)`\\n- `or_(...conditions)` / `$or(...conditions)`\\n\\n## Conditional expressions\\n\\nUse `$cond(condition, thenValue, elseValue)` for runtime prop values.\\n\\n```ts\\nconst statusColor = $cond(\\n equals($state('active'), true),\\n 'green',\\n 'gray'\\n);\\n```\\n\\nBoth branches should resolve to the same prop type.\\n\\n## Repeat over lists\\n\\n`repeat(path, key?)` creates a repeat binding and a typed item accessor.\\n\\n```ts\\nconst [todoRepeat, todo] = repeat('todos', 'id');\\n\\nconst textRef = todo.$('text'); // { \\\"$item\\\": \\\"text\\\" }\\nconst doneBind = todo.$bind('done'); // { \\\"$bindItem\\\": \\\"done\\\" }\\nconst indexRef = todo.$index(); // { \\\"$index\\\": true }\\n```\\n\\nAttach the repeat binding to the component that should render once per item:\\n\\n```ts\\nimport { Text } from '@rippling/pebble-sdui-web/catalogs/custom-apps';\\n\\nconst repeatedText = Text({\\n repeat: todoRepeat,\\n props: {\\n text: todo.$('text'),\\n },\\n});\\n```\\n\\n## Render helper on `createSpec`\\n\\n`createSpec()` includes a core `render(root)` helper, but catalog authors should prefer the generated catalog `render({ root, state })` because it stamps platform and catalog metadata.\\n\\nUse the core helper only in low-level tests or core-only tooling.\\n\\n## Serialization summary\\n\\n| TypeScript helper | Rendered shape | Use |\\n|---|---|---|\\n| `$state('path')` | `{ \\\"$state\\\": \\\"path\\\" }` | read state |\\n| `$bindState('path')` | `{ \\\"$bindState\\\": \\\"path\\\" }` | two-way state binding |\\n| `item.$('field')` | `{ \\\"$item\\\": \\\"field\\\" }` | read repeated item field |\\n| `item.$bind('field')` | `{ \\\"$bindItem\\\": \\\"field\\\" }` | bind repeated item field |\\n| `item.$index()` | `{ \\\"$index\\\": true }` | repeat index |\\n| `$template\\\\`...\\\\`` | `{ \\\"$template\\\": \\\"...\\\" }` | string interpolation |\\n| `$cond(...)` | `{ \\\"$cond\\\": ..., \\\"$then\\\": ..., \\\"$else\\\": ... }` | conditional prop value |\\n\",\n};\n","import { SDK_DOC_CONTENT_BY_PATH, SDK_DOCS } from './sdk-docs.generated';\n\n/** Metadata for a packaged SDK documentation file. */\nexport interface SdkDoc {\n /** Stable identifier for the documentation file. */\n key: string;\n /** Repo-relative Markdown file path, e.g. \"sdk-docs/typescript/README.md\". */\n filePath: string;\n /** Documentation title extracted from the file's first H1. */\n title: string;\n}\n\n/** Return the SDK documentation files packaged with this SDK. */\nexport function listSdkDocs(): SdkDoc[] {\n return SDK_DOCS.map(({ key, filePath, title }) => ({\n key,\n filePath,\n title,\n }));\n}\n\n/** Read a packaged SDK documentation file by repo-relative file path. */\nexport function readSdkDoc(filePath: string): string {\n if (!(filePath in SDK_DOC_CONTENT_BY_PATH)) {\n throw new Error(`Unknown SDK doc filePath: ${filePath}`);\n }\n\n return SDK_DOC_CONTENT_BY_PATH[filePath];\n}\n"],"names":["SDK_DOCS","SDK_DOC_CONTENT_BY_PATH","listSdkDocs","key","filePath","title","readSdkDoc"],"mappings":"gFAKO,MAAMA,EAA8B,CACzC,CACE,IAAK,gBACL,SAAU,qBACV,MAAO,8BAAA,EAET,CACE,IAAK,sBACL,SAAU,2BACV,MAAO,oBAAA,EAET,CACE,IAAK,kBACL,SAAU,uBACV,MAAO,UAAA,EAET,CACE,IAAK,kBACL,SAAU,uBACV,MAAO,UAAA,EAET,CACE,IAAK,oBACL,SAAU,yBACV,MAAO,YAAA,EAET,CACE,IAAK,oBACL,SAAU,gCACV,MAAO,gBAAA,EAET,CACE,IAAK,0CACL,SAAU,sDACV,MAAO,+CAAA,EAET,CACE,IAAK,+BACL,SAAU,2CACV,MAAO,kCAAA,CAEX,EAEaC,EAA4D,CACvE,qBACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EACF,2BACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EACF,uBACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EACF,uBACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EACF,yBACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EACF,gCACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EACF,sDACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EACF,2CACE;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,CACJ,ECpDO,SAASC,GAAwB,CACtC,OAAOF,EAAS,IAAI,CAAC,CAAE,IAAAG,EAAK,SAAAC,EAAU,MAAAC,MAAa,CACjD,IAAAF,EACA,SAAAC,EACA,MAAAC,CAAA,EACA,CACJ,CAGO,SAASC,EAAWF,EAA0B,CACnD,GAAI,EAAEA,KAAYH,GAChB,MAAM,IAAI,MAAM,6BAA6BG,CAAQ,EAAE,EAGzD,OAAOH,EAAwBG,CAAQ,CACzC"}
package/dist/sdk-docs.js CHANGED
@@ -1,4 +1,4 @@
1
- const o = [
1
+ const a = [
2
2
  {
3
3
  key: "shared.readme",
4
4
  filePath: "sdk-docs/README.md",
@@ -123,9 +123,9 @@ For humans:
123
123
 
124
124
  For LLMs:
125
125
 
126
- - First inspect the target catalog with \`get_components()\`, \`get_component()\`, \`get_actions()\`, and \`get_action()\`.
126
+ - First inspect the target catalog with \`get_components()\`, \`get_component()\`, \`get_actions()\`, \`get_action()\`, and \`get_computed_functions()\`.
127
127
  - Generate a small component tree before adding dynamic behavior.
128
- - Never invent component names, prop names, event names, or action names.
128
+ - Never invent component names, prop names, event names, action names, or computed function names.
129
129
  - Run \`validate(spec)\` and repair from the returned error messages.
130
130
  - Prefer SDK code generation over raw JSON because the SDK handles IDs, refs, and serialization.
131
131
  `,
@@ -138,7 +138,7 @@ This guide explains how an LLM should use the SDK and catalog metadata to produc
138
138
  Prefer this loop:
139
139
 
140
140
  1. **Identify target platform and catalog.** Example: web + \`AiChatCatalogV1\`.
141
- 2. **Inspect catalog capabilities.** Use \`get_components()\`, \`get_component()\`, \`get_actions()\`, and \`get_action()\`.
141
+ 2. **Inspect catalog capabilities.** Use \`get_components()\`, \`get_component()\`, \`get_actions()\`, \`get_action()\`, and \`get_computed_functions()\`.
142
142
  3. **Plan a small tree.** Pick the root and children. Confirm each component supports children before nesting.
143
143
  4. **Generate SDK code, not raw JSON.** SDK code gives better type hints and automatic serialization.
144
144
  5. **Render.** Call the catalog \`render(root, state)\`.
@@ -175,6 +175,7 @@ Rules:
175
175
  - Include all required props.
176
176
  - Use only events listed by the component definition.
177
177
  - Use only actions returned by get_actions().
178
+ - Use only computed functions returned by get_computed_functions().
178
179
  - Prefer generated SDK code over hand-written JSON.
179
180
  - Call render(root, state) and then validate(spec).
180
181
  - If validate returns errors, fix the code and validate again.
@@ -230,6 +231,7 @@ Repair strategy:
230
231
  - Missing required prop: add the prop with a safe value or state ref.
231
232
  - Unknown event: use one of the component's listed events.
232
233
  - Unknown action: use one from \`get_actions()\`.
234
+ - Unknown computed function: use one from \`get_computed_functions()\`.
233
235
  - Children not accepted: remove children or choose a container component.
234
236
  - Root missing: render the actual root returned by the tree.
235
237
 
@@ -318,6 +320,9 @@ Generated catalog modules export:
318
320
  - \`get_component(name)\`
319
321
  - \`get_actions()\`
320
322
  - \`get_action(name)\`
323
+ - \`get_functions()\`
324
+ - \`get_function(name)\`
325
+ - \`get_computed_functions()\`
321
326
  - \`render(root, state=None)\`
322
327
  - \`validate(spec)\`
323
328
 
@@ -365,12 +370,34 @@ print(submit["description"])
365
370
  print(submit.get("paramsSchema"))
366
371
  \`\`\`
367
372
 
373
+ ## Computed function discovery
374
+
375
+ Use \`get_functions()\` for a compact computed-function list:
376
+
377
+ \`\`\`python
378
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import get_functions
379
+
380
+ print(get_functions())
381
+ \`\`\`
382
+
383
+ Use \`get_computed_functions()\` or \`get_function(name)\` for params, return schemas, and docs:
384
+
385
+ \`\`\`python
386
+ from pebble_sdui_web.catalogs.AiChatCatalogV1 import get_computed_functions, get_function
387
+
388
+ functions = get_computed_functions()
389
+ definition = get_function("dateTime_format")
390
+ print(functions)
391
+ print(definition.get("paramsSchema"))
392
+ print(definition.get("returnsSchema"))
393
+ \`\`\`
394
+
368
395
  ## How humans should use catalogs
369
396
 
370
397
  1. Start with the catalog for the target surface.
371
398
  2. Use component docstrings and generated types in your editor.
372
399
  3. Read \`get_component()\` when a prop's runtime meaning is unclear.
373
- 4. Prefer generated action creators over raw dictionaries.
400
+ 4. Prefer generated action creators and computed-function helpers over raw dictionaries.
374
401
  5. Validate rendered specs in tests or at service boundaries.
375
402
 
376
403
  ## How LLMs should use catalogs
@@ -380,9 +407,10 @@ LLMs should treat the catalog as hard constraints:
380
407
  1. Call or inspect \`get_components()\` to choose candidates.
381
408
  2. Call or inspect \`get_component(name)\` for exact prop names, required props, events, and child support.
382
409
  3. Call or inspect \`get_actions()\` and \`get_action(name)\` for allowed action names and params.
383
- 4. Generate SDK code using only exported component and action symbols.
384
- 5. Render the tree.
385
- 6. Validate and repair any errors.
410
+ 4. Call or inspect \`get_computed_functions()\` before using computed values.
411
+ 5. Generate SDK code using only exported component, action, and computed-function symbols.
412
+ 6. Render the tree.
413
+ 7. Validate and repair any errors.
386
414
 
387
415
  LLMs must not invent:
388
416
 
@@ -390,6 +418,7 @@ LLMs must not invent:
390
418
  - prop names
391
419
  - event names
392
420
  - action names
421
+ - computed function names
393
422
  - enum/literal values
394
423
  - child support on leaf components
395
424
 
@@ -981,6 +1010,7 @@ Generated catalogs export compact and detailed introspection helpers:
981
1010
  import {
982
1011
  getActions,
983
1012
  getAction,
1013
+ getComputedFunctions,
984
1014
  getComponents,
985
1015
  getComponent,
986
1016
  } from '@rippling/pebble-sdui-web/catalogs/custom-apps';
@@ -989,6 +1019,7 @@ console.log(getComponents());
989
1019
  console.log(getComponent('Button'));
990
1020
  console.log(getActions());
991
1021
  console.log(getAction('showNotification'));
1022
+ console.log(getComputedFunctions());
992
1023
  \`\`\`
993
1024
 
994
1025
  LLMs should call or inspect these helpers before generating SDK code.
@@ -1163,10 +1194,10 @@ Use the core helper only in low-level tests or core-only tooling.
1163
1194
  `
1164
1195
  };
1165
1196
  function s() {
1166
- return o.map(({ key: e, filePath: t, title: a }) => ({
1197
+ return a.map(({ key: e, filePath: t, title: o }) => ({
1167
1198
  key: e,
1168
1199
  filePath: t,
1169
- title: a
1200
+ title: o
1170
1201
  }));
1171
1202
  }
1172
1203
  function r(e) {