@salsita-ai/sdk 0.50.0-develop.f101f4c3c9 → 0.50.0-develop.f354d3576d

package/dist/application-spec/generate-application/code/templates/skills/features/index.d.ts

@@ -0,0 +1 @@
+export * from './features.js';

package/dist/application-spec/generate-application/code/templates/skills/features/index.js

@@ -0,0 +1 @@
+export*from"./features.js";

package/dist/application-spec/generate-application/code/templates/skills/features/inspection.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../guide.js';
+export declare const generatePhoenixInspectionFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/inspection.js

@@ -0,0 +1 @@
+import{createPhoenixFeatureGuide as e}from"../guide.js";import{sdkGuidanceSections as n}from"../sdk-content.js";export const generatePhoenixInspectionFeature=()=>e({path:"features/inspection.md",title:"Inspection",summary:"Asset and live runtime inspection commands; read when checking models, scene, state, data or rendered output.",whenToUse:"Read when checking imported assets or investigating the running configurator. Runtime inspection needs dev running and the preview open in a browser.",capabilities:[n.assetInspection,n.screenshotCli,n.inspectState,n.inspectData,n.inspectScene,n.playwrightMcpSetup].join("\n\n"),example:"After changing a material, run `pnpm phoenix inspect:scene` to inspect the assigned material, then `pnpm phoenix screenshot -o ./render.png` to compare the rendered result. A canvas screenshot does not cover the surrounding interface.",documentation:"Read `docs/phoenix/phoenix-cli.mdx` with `pnpm phoenix docs -r docs/phoenix/phoenix-cli.mdx` for command flags and output contracts. Use the [review index](../processes/review/index.md) when deciding which evidence the change needs.",phxMembers:[]});

package/dist/application-spec/generate-application/code/templates/skills/features/localization.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../guide.js';
+/** The guide to languages: enabling them, translatable texts, the language switch, webhook locale and catalogs. */
+export declare const generatePhoenixLocalizationFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/localization.js

@@ -0,0 +1,87 @@
+import{createPhoenixFeatureGuide as e}from"../guide.js";let a=`Read when the configurator needs several languages, when adding user-facing text to such a project, or when a PDF or email must follow the configurator user's language.
+
+Enable localization when the client sells in several languages; take them from the product definition, and ask when it names none. With one language and none planned, plain strings are fine. When more are likely, make every text translatable from the start: converting later touches every label, message and template.`,t=`A table sold in English and German: option labels in the spec, an invariant message and a picker in a custom layout.
+
+\`\`\`yaml
+# spec/application.yaml
+availableLocales: [en, de]
+textLanguages: [en, de]
+
+# spec/table.yaml
+invariants:
+  Table:
+    glassLength:
+      types: [glassTooLong]
+components:
+  Table:
+    applicationConfig:
+      main:
+        availableLocales: [en, de] # what users can pick; add it to an existing instance
+    attributeSelection:
+      finish:
+        value:
+          $bind: finish
+        options:
+          - value: oak
+            label:
+              $msg: Oak
+          - value: glass
+            label:
+              $msg: Glass
+\`\`\`
+
+\`\`\`ts
+// src/invariants/table.ts
+import { msg } from '@lingui/core/macro'
+
+const MAX_GLASS_LENGTH = 2000
+
+export default phx.domain.implementCustomInvariants({
+  Table: {
+    glassLength: table =>
+      table.finish === 'glass' && table.length > MAX_GLASS_LENGTH
+        ? [
+            {
+              type: 'glassTooLong',
+              severity: 'fatal',
+              message: msg\`Glass tops are available up to \${MAX_GLASS_LENGTH} mm.\`,
+            },
+          ]
+        : [],
+  },
+})
+\`\`\`
+
+\`\`\`tsx
+// src/elements/_shared/LanguagePicker.tsx, rendered by the project's ConfiguratorLayout
+import { msg } from '@lingui/core/macro'
+import { MenuItem, TextField } from '@mui/material'
+
+const LANGUAGE = msg\`Language\`
+
+export const LanguagePicker = () => {
+  const label = phx.frontend.useLocalizable(LANGUAGE)
+  const { locales, locale, setLocale, available } = phx.frontend.useLocaleSwitch()
+
+  if (!available) {
+    return null
+  }
+
+  return (
+    <TextField select size="small" label={label} value={locale} onChange={event => setLocale(event.target.value)}>
+      {locales.map(option => (
+        <MenuItem key={option.locale} value={option.locale}>
+          {option.displayName}
+        </MenuItem>
+      ))}
+    </TextField>
+  )
+}
+\`\`\`
+
+After \`pnpm phoenix sync\`, translate the texts in \`src/locales/de/messages.po\`, keeping the placeholder:
+
+\`\`\`po
+msgid "Glass tops are available up to {MAX_GLASS_LENGTH} mm."
+msgstr "Glasplatten gibt es bis {MAX_GLASS_LENGTH} mm L\xe4nge."
+\`\`\``;export const generatePhoenixLocalizationFeature=()=>e({path:"features/localization.md",title:"Localization",summary:"Languages, translatable spec and TypeScript texts, the language switch, the webhook's language, catalogs and formatting; read when the configurator must work in more than one language or a text must be translatable.",whenToUse:a,capabilities:"### Enable languages\n\nThree lists, each with its own job:\n\n- **`availableLocales`** in `spec/application.yaml` (default `[en]`) — the languages with a project catalog, `src/locales/<locale>/messages.po`.\n- **`availableLocales` of the root entity's `applicationConfig`** — the languages users can pick. Without it the switch offers English only and the default toolbar has no language button. Keep it within the top-level list.\n- **`textLanguages`** in `spec/application.yaml` — the languages Admin edits multilingual texts in, and the fallback order of `$lang` values.\n\nThe configurator starts in the embedding page's `locale` attribute or property (English when unset), not the first listed locale. A page locale outside `availableLocales` still activates when the SDK ships it (cs, da, de, de-AT, en, en-AU, en-GB, es, fr, hu, it, nl, pl, pt, ro, sk, tr), but project texts then have no translation and production shows their message ids. List every locale the site sets, regional ones included: their empty entries compile from the base language. In a language the SDK lacks, built-in texts stay English.\n\n### Spec texts: `$msg` or `$lang`\n\n- **`$msg`** — UI text authored in the spec: titles, labels, hints, static invariant messages, constants. The text is its own id, so rewording drops its translations; add a stable `$msgId: 'finish.title'` to texts likely to change.\n- **`$lang`** — data carrying its own translations: Admin content, published data, imports. Inline `$lang` in the spec suits data the client supplies translated.\n- A plain string shows unchanged in every language.\n- An expression holding `$msg` or `$lang` declares `$ref: phx:Localizable`; for `$msg`, `type: string` reports `EXPRESSION_VALUE_TYPE_MISMATCH`.\n- `$lang` resolves to the active locale, then each `textLanguages` entry, then `en`, else an empty string. List every market language there, primary first.\n\n### TypeScript texts\n\n- `msg` from `@lingui/core/macro` creates a message descriptor: use it for invariant messages, expression results the UI shows and labels passed to components. `` msg`Up to ${max} mm` `` keeps a placeholder for translators, `msg({ id, message })` fixes the id, `plural` handles counts.\n- Expressions, invariants and transformers run without a locale, on the server too: return descriptors or `$lang`, never translated strings or formatted numbers. [Violations](state/violations.md) covers hint texts formatted per change.\n- In React, render content with `<Trans>` from `@lingui/react/macro`. Where a string is needed (an attribute, a string-only prop, a spec text, a descriptor):\n  - `phx.frontend.useLocalizable(text)` returns one text in the active language;\n  - `phx.frontend.useResolveLocalizable()` returns `resolve(text)` for lists, loops and conditional texts.\n- Both accept a string, a descriptor or `$lang`, apply the `textLanguages` fallback and re-render on a language change. Resolve inside components, never at module scope.\n\n### Language switch\n\n- The default toolbar shows a language button, and a menu action on phones, when the `applicationConfig` list has several locales. A configured `toolbar` lists `languageToolbarButton` and `languageMenuAction` itself; [Toolbar actions](custom-layout/toolbar-actions.md) covers toolbars a layout renders.\n- `phx.frontend.useLocaleSwitch()` returns `{ locales, locale, setLocale, available }`: the `applicationConfig` locales as `{ locale, displayName }`, each named in its own language; the active locale; a setter; and whether there is a choice. Use it for your own picker and wherever code needs the active locale.\n\n### Webhooks\n\n- The language reaches the webhook only if the finalize handler sends it: `apiClient.finalize(configurationId, finalizationUuid, finalizeData, locale, frontendData)`, with `locale` from `phx.frontend.useLocaleSwitch()`. Without it, PDFs and emails come out in English. [Finalization](../processes/finalization.md) owns the handler.\n- Tasks get `ctx.resolveLocalizable(text)`, bound to that locale and `textLanguages`, and `ctx.i18n`. The PDF and email builders resolve every localizable input; templates use `<Trans>`, and `HtmlHelpers.Localized` from `@salsita-ai/sdk/webhook` for domain texts.\n- `.withLocale('de')` renders one PDF or email in another language. Plain payloads (CSV, HTTP) need `ctx.resolveLocalizable` on each text.\n\n### Catalogs and translation\n\n- `pnpm phoenix sync` and `pnpm phoenix build` extract every `msg`, `<Trans>` and `$msg` into the PO files and compile the TypeScript catalogs.\n- `pnpm phoenix dev` only creates missing catalogs at startup; with `--withLingui` (or `WITH_LINGUI=true`) it extracts and compiles on every change. Without it a new text stays English until the next sync. Restart dev after changing `availableLocales`.\n- Translate in the `msgstr` entries of `src/locales/<locale>/messages.po`, keeping placeholders such as `{max}`. Never edit the compiled `messages.ts` ([CLI core](../core/cli.md)).\n- An empty `msgstr` compiles from the fallback chain (`de-AT` → `de` → `en`): the text shows English, without an error. Before a handover, search for empty `msgstr \"\"` entries after the header.\n- When you translate yourself, tell the client which languages need a native speaker's review and record them as provisional.\n\n### Numbers and currency\n\n- `phx.frontend.useRootEntityPrice()` formats the root's `price` component for the active locale in its `currency` (`USD` when unset), and returns `null` while the root has none; choose the currency per market in the spec.\n- Format other numbers, dates and lists with `Intl` and the active locale: `useLocaleSwitch().locale` in React, `ctx.i18n.locale` in webhooks.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/phoenix/localization.mdx` — enabling languages, choosing the language, `$msg`, `$msgId`, `$lang` and its sources, the hooks and server-side translation.\n- `docs/phoenix/webhooks.mdx` — localized PDF and email builders and `.withLocale`.\n- `docs/other-features/violation-messages.mdx` — translated violation hints with nested labels.\n- `docs/other-features/currency.mdx` — the currency chosen from session data, one price component per currency filtered with `active`.\n- `docs/integrations/webcomponent-api/basics.mdx` — the page's `locale` property.",phxMembers:["frontend.useResolveLocalizable","frontend.useLocalizable","frontend.useLocaleSwitch","frontend.useRootEntityPrice"]});

package/dist/application-spec/generate-application/code/templates/skills/features/scene-objects.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../guide.js';
+/** Scene objects built in code: scene elements, custom entities and attached three.js objects, rebuilding and disposal. */
+export declare const generatePhoenixSceneObjectsFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/scene-objects.js

@@ -0,0 +1,43 @@
+import{createPhoenixFeatureGuide as e}from"../guide.js";let t=`A worktop with a cut-out per basin, as a scene element. The geometry is rebuilt only when the length or the cut-outs change; React Three Fiber releases the old one.
+
+\`\`\`yaml
+# spec/domain.yaml, components of Washtable
+sceneEntityObject:
+  worktop:
+    name: 'Worktop'
+sceneEntityObjectProperties:
+  worktop:
+    offsetY: 850
+\`\`\`
+
+\`\`\`tsx
+// src/elements/Worktop.tsx
+import { useMemo } from 'react'
+import { Path, Shape } from 'three'
+
+const NO_CUT_OUTS: readonly number[] = []
+
+export default phx.frontend.createCustomPhoenixEntityElement('Worktop', ({ entityId }) => {
+  const entity = phx.frontend.useCommittedState().entities.find(e => e.id === entityId)
+  const washtable = entity?.type === 'Washtable' ? entity : undefined
+  const length = washtable?.length ?? 1200
+  const cutOuts = washtable?.basinPositions ?? NO_CUT_OUTS
+
+  const shape = useMemo(() => {
+    const top = new Shape().moveTo(0, 0).lineTo(length, 0).lineTo(length, 460).lineTo(0, 460).closePath()
+    for (const x of cutOuts) {
+      top.holes.push(new Path().absellipse(x, 230, 180, 140, 0, Math.PI * 2, false, 0))
+    }
+    return top
+  }, [length, cutOuts])
+
+  return (
+    <mesh rotation-x={-Math.PI / 2} castShadow receiveShadow>
+      <extrudeGeometry args={[shape, { depth: 12, bevelEnabled: false }]} />
+      <meshPhysicalMaterial color="#f1ede4" roughness={0.35} clearcoat={0.3} />
+    </mesh>
+  )
+})
+\`\`\`
+
+A new finish changes only the material's color; dragging a basin changes \`basinPositions\`, which a cut-out needs, so that rebuild is real.`;export const generatePhoenixSceneObjectsFeature=()=>e({path:"features/scene-objects.md",title:"Scene objects built in code",summary:"Geometry built in code instead of loaded from a model, and keeping its rebuilds cheap; read when part of the product or its setting is generated.",whenToUse:"Read when part of the product or its setting is built in code instead of loaded from a model: geometry that follows the configuration, such as a worktop with cut-outs where the basins sit, a shelf that grows with its width or a room whose walls follow the plan.\n\nPrefer a model when one exists: `sceneEntityRemoteObject` loads a GLB, and `sceneEntityObjectProperties` positions it and binds its transforms to state. Build in code what a model cannot express.",capabilities:"### Three ways to build it\n\n- **A scene element** — usually the best fit. Name an element in an entity's `sceneEntityObject` instance, `name: 'Worktop'`, and register it in `src/elements/` with `phx.frontend.createCustomPhoenixEntityElement('Worktop', ({ entityId }) => …)`; [Custom controls](domain-controls/custom-controls.md) has the registration rules. It returns React Three Fiber JSX, meshes with their geometries and materials, and reads state through the hooks like any entity element. React Three Fiber releases what it created when the element unmounts or a geometry's `args` change.\n- **A whole custom entity** — `customSceneEntity` with `name` replaces the entity's entire representation by the element. The entity's remote objects, object properties, materials, decals and clips are then ignored; child entities still render.\n- **A three.js object** — attach `sceneEntityObjectComponent` from `@salsita-ai/sdk/domain` with `phx.domain.attachComponent` in `src/components/`, its state `{ object }` built in `memoEval`. The SDK renders the object as given and never disposes it.\n\nFor the first and third, `sceneEntityObjectProperties` of the same instance still positions, hides and highlights the object.\n\n### Rebuild only when the shape changes\n\nA rebuild costs geometry, triangulation and an upload to the GPU, and a slider or a drag can ask for one every frame.\n\n- Rebuild when an input that changes the shape changes, such as a length or a cut-out, and nothing else: memoize the geometry on those inputs, `useMemo` in an element or the `memoEval` dependencies of an attached object.\n- Move, rotate or recolor the existing object for a position or a finish, through `sceneEntityObjectProperties` bindings or the material, instead of rebuilding it.\n- A three.js object you replace keeps its GPU memory until you call `dispose()` on its geometries, materials and textures, so dispose what a rebuild replaces. Reuse a texture across rebuilds rather than cloning it and setting `needsUpdate` each time, which uploads it again.\n\n### Shadows and effects\n\n- On a three.js object, `sceneEntityObjectProperties` sets `castShadow` and `receiveShadow` on every child from the spec, `false` when unset, so flags set in code are overwritten: set them in the spec. A scene element sets them on its own meshes.\n- Soft shadows on large surfaces, outlines and other effects cost every frame; keep those whose result the client sees.",example:t,documentation:"Read with `pnpm phoenix docs -r <path>`:\n\n- `docs/3d-scene/rendering/basic.mdx` — loaded models, object properties and three.js objects attached in code.\n- `docs/3d-scene/rendering/scene-entity-object.mdx` — the `sceneEntityObject` component and its forms.\n- `docs/3d-scene/rendering/custom-entity.mdx` — `customSceneEntity` and a complete React Three Fiber element.\n- `docs/3d-scene/rendering/soft-shadows.mdx` — the canvas, object and light settings shadows need.\n- The **Performance** category — what costs per frame and per change.",phxMembers:[]});

package/dist/application-spec/generate-application/code/templates/skills/features/state/index.d.ts

@@ -0,0 +1 @@
+export * from './state.js';

package/dist/application-spec/generate-application/code/templates/skills/features/state/index.js

@@ -0,0 +1 @@
+export*from"./state.js";

package/dist/application-spec/generate-application/code/templates/skills/features/state/slices.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The store's three slices, which UI reads which, and the hooks that read them without needless re-renders. */
+export declare const generatePhoenixStateSlicesFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/state/slices.js

@@ -0,0 +1,48 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A cabinet label follows a drag frame by frame, while the order summary ignores previews and rejected changes. The label returns a tuple of numbers, so it re-renders only when one changes; returning \`cabinet.$shelves\` would re-render it on every pointer move.
+
+\`\`\`tsx
+// src/elements/CabinetWidthLabel.tsx
+import { Trans } from '@lingui/react/macro'
+import { Typography } from '@mui/material'
+
+export default phx.frontend.createCustomPhoenixEntityElement('CabinetWidthLabel', ({ entityId }) => {
+  if (!phx.domain.model.Cabinet.isId(entityId)) {
+    throw new Error('CabinetWidthLabel is attached to a Cabinet only.')
+  }
+
+  const [width, shelves] = phx.frontend.useRenderedEntitySelector(
+    entityId,
+    cabinet => [cabinet.width, cabinet.$shelves.length] as const,
+    []
+  )
+
+  return (
+    <Typography variant="caption">
+      <Trans>
+        {width} mm, {shelves} shelves
+      </Trans>
+    </Typography>
+  )
+})
+\`\`\`
+
+\`\`\`tsx
+// src/_shared/OrderSummary.tsx: committed only, so a dragged-across position never shows a price
+import { Trans } from '@lingui/react/macro'
+import { Typography } from '@mui/material'
+
+export const OrderSummary = () => {
+  const [cabinets, total] = phx.frontend.useRootEntitySelector(
+    kitchen => [kitchen.$cabinets.length, kitchen.$totalPrice] as const,
+    []
+  )
+
+  return (
+    <Typography>
+      <Trans>
+        {cabinets} cabinets, {total}
+      </Trans>
+    </Typography>
+  )
+}
+\`\`\``;export const generatePhoenixStateSlicesFeature=()=>e({path:"features/state/slices.md",title:"State slices",summary:"The rendered, committed and potentially invalid slices and the hooks that read them; read when UI shows configuration state, such as a live label during a drag or a price summary.",whenToUse:"Read when UI shows configuration state: choosing between a live preview and the committed configuration, picking a reading hook, or keeping an element from re-rendering on every drag frame. Writing changes belongs to [Updates and dry runs](updates.md).",capabilities:"### The three slices\n\nThe store keeps three slices. Each emits a state emission `{ kind, state, validity }`; an update emission adds `previousState` and `updates`.\n\n- **`rendered`** — every valid state, committed or staged: gesture previews and hover included. The scene renders from it. An invalid staged state is not emitted, so the preview stays at the last valid one.\n- **`committed`** — every valid committed state: what is saved, what undo records and what finalizing checks.\n- **`potentiallyInvalid`** — every attempted commit, rejected ones included. No reading hook targets it; configurator messages report its rejections ([Messages](../custom-layout/messages.md)).\n\n`state` is `{ rootEntityId, rootEntityType, entities, ephemeralRecords }`:\n\n- `entities` are raw entities: own fields only, no `$` expressions or relations. Read the `$` entity through the entity hooks below.\n- `ephemeralRecords` hold navigation, view, tool, selection, hover and drag state. They are never saved, and a commit that changes only them makes no undo step. Read them with the hooks of [Application states](../application-states/index.md), not by scanning records.\n\n### Choose a slice\n\n- **Rendered** — what must follow a gesture while it happens: a dimension label during a drag, an in-scene overlay, a live preview of the value being changed.\n- **Committed** — what must not flicker with previews or show a state nobody accepted: price, summaries, step completion, enabling Next or Finalize, analytics, data sent to a server.\n- Never mix them in one value: a price computed from rendered state shows prices of positions a drag only passed through.\n\n### Reading hooks\n\nEach pair reads the committed slice first, the rendered slice second:\n\n- `phx.frontend.useStoreSelector(select, deps)` \xb7 `phx.frontend.useRenderedSelector(select, deps)` — `select(emission)` returns any value. An optional third argument `false` pauses updates, for hidden UI.\n- `phx.frontend.useEntitySelector(id, select, deps)` \xb7 `phx.frontend.useRenderedEntitySelector(id, select, deps)` — `select($entity, emission)` for one entity.\n- `phx.frontend.useRootEntitySelector(select, deps)` \xb7 `phx.frontend.useRenderedRootEntitySelector(select, deps)` — the same for the root entity.\n- `phx.frontend.useEntityState(id)` — the committed `$` entity. It takes the id only and has no rendered twin on `phx.frontend`; use `useRenderedEntitySelector`.\n- `phx.frontend.useRootEntityState()` \xb7 `phx.frontend.useRootEntityRenderedState()` — the root `$` entity.\n- `phx.frontend.useRootEntityId()` \xb7 `phx.frontend.useRootEntityRenderedId()` — the root entity's id.\n- `phx.frontend.useCommittedState()` \xb7 `phx.frontend.useRenderedState()` — the whole `state`.\n- `phx.frontend.useCommittedSlice()` \xb7 `phx.frontend.useRenderedSlice()` — the whole emission, `validity` included. Neither takes an argument.\n- `phx.frontend.useStoreSelector$(select, deps)` \xb7 `phx.frontend.useRenderedSelector$(select, deps)` — an RxJS observable of the selected value, for work outside rendering such as a debounced request in an effect. It replays the current value and emits for every emission, equal or not: add `distinctUntilChanged()`.\n\nThe entity hooks throw for an id the state does not contain: take ids from the slice you read, and drop an id once its entity is deleted. In event handlers and async flows, read `storeSystem.stateSlices.committed.value.state` from `phx.frontend.useDomain()` when the code runs; a value captured during render may be stale by then.\n\n### Keep re-renders narrow\n\n- A selector runs for every emission of its slice; the component re-renders only when the result changes. Results compare shallowly: a primitive by value, an object or array member by member, each member by reference.\n- Return primitives, ids, counts or tuples of them. A relation such as `$shelves`, and anything built from it, is a new array on every state, so returning it re-renders every time: return its `length` or its ids.\n- The whole-object hooks (`useEntityState`, `useRootEntityState`, `useRootEntityRenderedState`, the state and slice hooks) return a new object for every state. Their component re-renders on every commit, and on every drag frame for the rendered ones. Keep them for small panels; use a selector in elements mounted per entity or shown during gestures.\n- List in `deps` every component value the selector reads, as for `useMemo`; the entity selectors add the id themselves. A missing dependency keeps a stale selector.\n- Treat every returned value as immutable. Move expensive derivations into [expressions](../domain-model/expressions.md), which are cached per state, rather than computing them in selectors.",example:t,documentation:'Read each with `pnpm phoenix docs -r <path>`:\n\n- `docs/performance/render-isolation.mdx` — rendered entity selectors that keep a large scene smooth while dragging, and why their results must compare equal.\n- `docs/phoenix/state-management.mdx` — slices, the emission lifecycle, validity results and the selector hooks.\n- `docs/phoenix/configurator-interface.mdx` — "Core Hooks": the slice, selector and entity hooks with a sample call each.',phxMembers:["frontend.useStoreSelector","frontend.useRenderedSelector","frontend.useStoreSelector$","frontend.useRenderedSelector$","frontend.useEntitySelector","frontend.useRenderedEntitySelector","frontend.useRootEntitySelector","frontend.useRenderedRootEntitySelector","frontend.useEntityState","frontend.useRootEntityState","frontend.useRootEntityRenderedState","frontend.useRootEntityId","frontend.useRootEntityRenderedId","frontend.useCommittedState","frontend.useRenderedState","frontend.useCommittedSlice","frontend.useRenderedSlice"]});

package/dist/application-spec/generate-application/code/templates/skills/features/state/state.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** The state index followed by its guides: reading the store, writing it, and how violations surface. */
+export declare const generatePhoenixStateGuides: () => readonly PhoenixGuide[];

package/dist/application-spec/generate-application/code/templates/skills/features/state/state.js

@@ -0,0 +1 @@
+import{createPhoenixIndexGuide as t}from"../../guide.js";import{generatePhoenixStateSlicesFeature as e}from"./slices.js";import{generatePhoenixUpdatesFeature as o}from"./updates.js";import{generatePhoenixViolationsFeature as a}from"./violations.js";export const generatePhoenixStateGuides=()=>{let n=[e(),o(),a()];return[t({path:"features/state/index.md",title:"State",summary:"Reading and writing the configuration at runtime and how violations surface; read when UI or a handler reads or changes the configuration, or must reflect what a change breaks.",intro:"The configurator keeps the configuration in a store. The slices hold the states UI can read; updates stage and commit changes, and dry runs test them first; the violations of those states disable control options, become hints and block finalizing. Read only the guide for the task. Declaring invariants belongs to [Validation and repair](../domain-model/validation-and-repair.md), transformers to [Transformers](../domain-model/transformers.md), and the controls that write for you to [Domain controls](../domain-controls/index.md).",guides:n,notes:[]}),...n]};

package/dist/application-spec/generate-application/code/templates/skills/features/state/updates.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** Writing the configuration: update kinds, the stage and commit cycle, dry runs, undo steps and update guards. */
+export declare const generatePhoenixUpdatesFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/state/updates.js

@@ -0,0 +1,39 @@
+import{createPhoenixFeatureGuide as e}from"../../guide.js";let t=`A width scrubber no configured control covers: every position is previewed, the release commits once, and the drag is one undo step. A width that breaks an invariant is not previewed, so the cabinet stays at the last valid width; a rejected release reverts the preview and becomes a message.
+
+\`\`\`tsx
+// src/_shared/WidthScrubber.tsx
+import { Slider } from '@mui/material'
+
+export const WidthScrubber = ({ cabinetId }: { readonly cabinetId: Cabinet['id'] }) => {
+  const { storeSystem } = phx.frontend.useDomain()
+  const width = phx.frontend.useRenderedEntitySelector(cabinetId, cabinet => cabinet.width, [])
+
+  const preview = (value: number | number[]) => {
+    if (typeof value !== 'number') {
+      return
+    }
+
+    // Replaces the previous preview: the whole change from the committed state
+    storeSystem.stage([
+      phx.frontend.updates.DomainEntityModification({
+        entityId: cabinetId,
+        stateDelta: { width: value },
+        updateTag: 'cabinet.scrubWidth',
+      }),
+    ])
+  }
+
+  return (
+    <Slider
+      value={width}
+      min={400}
+      max={1200}
+      step={10}
+      onChange={(_event, value) => preview(value)}
+      onChangeCommitted={() => storeSystem.commit()}
+    />
+  )
+}
+\`\`\`
+
+A discrete action is one call, such as \`storeSystem.stageAndCommit([phx.frontend.updates.EntityDeletion({ entityId, updateTag: 'cabinet.remove' })])\`. When configurator users pick it among options, a control with a dry run is the better home.`;export const generatePhoenixUpdatesFeature=()=>e({path:"features/state/updates.md",title:"Updates and dry runs",summary:"Update kinds, the stage, commit and rollback cycle, dry runs and undo steps; read when code writes the configuration or a transformer must stay cheap.",whenToUse:"Read when code writes the configuration outside a configured control, previews a change during a gesture, dry-runs a change to decide whether to offer it, needs ids for new entities, or narrows updates in a transformer.",capabilities:"### Choose the write path\n\n- Write through the control hooks of [Custom controls](../domain-controls/custom-controls.md) first: they build updates, dry-run options, stage gestures and commit. `phx.frontend.useUpdateControl(fixableViolations)` returns `prepare(updates)`, which dry-runs any updates and returns `{ disabled, hints, update, stage, trace }`.\n- Use the store system only when no control hook fits: a gesture you drive yourself, a write from a toolbar action, dialog or handler, a confirmation before a commit, or work that waits for a gesture to end.\n- `phx.frontend.useDomain()` returns the stable domain systems (`storeSystem`, `domain`, `undoSystem`, `navigationSystem`, `componentReader`, the projections), safe in dependency arrays. Navigation and selection changes belong to [Application states](../application-states/index.md).\n- Transformers return update arrays and never write to the store ([Transformers](../domain-model/transformers.md)).\n\n### Build updates\n\nEach `phx.frontend.updates` factory takes one object with an `updateTag` naming the change, such as `'cabinet.scrubWidth'`; `withTag` filters, the guards below and analytics read it. An optional localizable `hint` reaches configurator users as a side-effect message on commit: set it when a transformer changes something they did not touch.\n\n- `DomainEntityModification({ entityId, stateDelta, updateTag })` — sets some of the entity's own fields, never `id` or `type`.\n- `DomainEntityCreation({ entity, parentId, updateTag })` — adds a complete entity, optionally to the reference component instance named by `collection`. Build it with `phx.domain.createRecipe({ type, … })`, which fills the spec defaults, and replace its placeholder id. For children from recipes, prefer `phx.frontend.useCookRecipes`, which assigns ids.\n- `DomainEntityReplacement({ entityId, replacementEntity, keepChildren, updateTag })` — swaps in a new entity with a new id; `keepChildren: false` deletes its composed children.\n- `EntityDeletion({ entityId, updateTag })` — removes an entity; built-in transformers delete its composed children and prune references to it.\n- `ComponentModification({ componentInstance, writableState, updateTag })` — writes a component's writable state, as built-in controls do; it throws for a state the component rejects.\n\n`phx.frontend.getIdSequence(entities, pendingUpdates)` returns `{ nextId(type) }`, above every existing id and every id created or replaced in `pendingUpdates`. Draw a batch's ids from one sequence: two sequences from one state return the same id. In a transformer, use the context's `getIdSequence()`.\n\n### Stage, commit and roll back\n\n- `storeSystem.stage(updates)` runs transformers and invariants against the committed state and previews a valid result in the rendered slice; an invalid stage previews nothing. Each call replaces the staged updates: stage the whole change from the committed state, never a delta.\n- `storeSystem.commit()` prepares the staged updates again, runs the `onBeforeCommit` hooks and commits a valid result. A rejected commit keeps the committed state, resets the preview and reaches configurator messages through the potentially invalid slice.\n- `storeSystem.rollback()` drops the staged updates and their preview.\n- `storeSystem.stageAndCommit(updates)` writes a discrete action in one step: a click, a toggle, an add.\n- `storeSystem.hasStagedUpdates` is `true` while a staged change is pending; a hover stages nothing. It is a getter, not a subscription: check it before snapshotting the committed state, such as for an export.\n- `storeSystem.onBeforeCommit((emission, emit) => …)` runs before every commit and returns its unregister function; register it in an effect. Returning `false` holds the commit, such as to confirm a destructive change: the preview rolls back, and `emit()` commits that emission later. The hooks run again then, so let it through.\n- Leave `storeSystem.commitPrepared` to the SDK's own operations.\n\n### Dry runs\n\n- `storeSystem.prepareStateEmission(updates, storeSystem.stateSlices.committed.value.state, 'committed')` returns the emission a commit would produce, `{ state, validity, updates, … }`, without emitting it. Controls dry-run every option this way ([Violations](violations.md)).\n- Transformers and invariants run in a dry run exactly as in a commit, with the kind `'committed'`, so a transformer cannot tell them apart: `onEmissionsOfKind(['committed'])` skips staged previews but not dry runs.\n- Every mounted control dry-runs each option after every commit: ten options run the transformer pipeline and every invariant ten times per change. Staging runs them on every frame of a gesture.\n- Keep transformers pure and cheap: no requests, storage, analytics or React state.\n\n### Undo steps\n\n- One commit that changes entities is one undo step, transformer updates included, so a transformer's repair undoes with the change that caused it.\n- A commit that changes only navigation, view, tool or selection state makes no step.\n- Staged frames make no steps, but `stageAndCommit` on every keystroke or slider tick makes one each: stage while the value changes and commit once, on release or blur. [Toolbar actions](../custom-layout/toolbar-actions.md) covers the undo and redo buttons.\n\n### Update guards\n\nNarrow updates in a transformer (`ctx.updates`, `overrideAllUpdates`) or in an `onBeforeCommit` emission:\n\n- `phx.frontend.isCreateEntityUpdate(update, types)`, `phx.frontend.isReplaceEntityUpdate(update, types)` and `phx.frontend.isDeleteEntityUpdate(update, types)` — an entity of `types` added or replaced from a recipe, or removed by a built-in delete control. They check the SDK's own tags, so your own `EntityDeletion` does not match.\n- `(update, types, instanceName)` guards — the write of one built-in control on one component instance: `phx.frontend.isAttributeSelectionUpdate`, `phx.frontend.isAttributeSwitchUpdate`, `phx.frontend.isTextValueUpdate`, `phx.frontend.isSwatchSelectionUpdate`, `phx.frontend.isGenericDimensionUpdate`, `phx.frontend.isDistanceDimensionUpdate`, `phx.frontend.isAngleDimensionUpdate`.\n- A built-in step at priority `Infinity` turns component writes into entity modifications. Transformers default to that priority and run after it, and `onBeforeCommit` sees its result, so the control guards never match there. Give such a transformer a finite `priority` in its `transformers:` entry, or filter with `when.entity([...]).modified({ atFields })`.",example:t,documentation:'Read each with `pnpm phoenix docs -r <path>`:\n\n- `docs/other-features/transformers.mdx` — the transformer guide, including a component trigger registered with a finite priority.\n- `docs/complex-use-cases/navigation-guard.mdx` — an `onBeforeCommit` hook that holds a commit until configurator users confirm.\n- `docs/phoenix/state-management.mdx` — the stage, commit and rollback cycle and the emission kinds.\n- `docs/phoenix/configurator-interface.mdx` — "Updates Factory" and "Update Type Guards": every factory member, a control that dry-runs its updates, and the guards.',phxMembers:["frontend.updates","frontend.getIdSequence","frontend.useDomain","frontend.isCreateEntityUpdate","frontend.isReplaceEntityUpdate","frontend.isDeleteEntityUpdate","frontend.isAngleDimensionUpdate","frontend.isDistanceDimensionUpdate","frontend.isGenericDimensionUpdate","frontend.isAttributeSelectionUpdate","frontend.isAttributeSwitchUpdate","frontend.isTextValueUpdate","frontend.isSwatchSelectionUpdate"]});

package/dist/application-spec/generate-application/code/templates/skills/features/state/violations.d.ts

@@ -0,0 +1,3 @@
+import { type PhoenixGuide } from '../../guide.js';
+/** How violations disable control options, become hint text and gate Next and Finalize at runtime. */
+export declare const generatePhoenixViolationsFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/state/violations.js

@@ -0,0 +1,36 @@
+import{createPhoenixFeatureGuide as t}from"../../guide.js";let e=`A missing purpose is a \`warning\`: the change stays, the purpose step's Next waits for it, and finalizing waits for it like for every other warning. Its priority puts its text alone in the finalize hint while lower-ranked warnings also hold.
+
+\`\`\`yaml
+# spec/invariants.yaml
+invariants:
+  KitchenRange:
+    purposeRequired:
+      type: purpose-required
+      severity: warning
+      message:
+        $msg: Choose a purpose before continuing
+      controlViolationPriority: 10
+\`\`\`
+
+\`\`\`tsx
+// src/_shared/PurposeNextButton.tsx
+import { Trans } from '@lingui/react/macro'
+import { Button, Tooltip } from '@mui/material'
+
+export const PurposeNextButton = () => {
+  const { canGoNext, next } = phx.frontend.useStepNavigation()
+  const { violations } = phx.frontend.useFinalizeViolations()
+  const resolve = phx.frontend.useResolveLocalizable()
+  const missing = violations?.find(({ violation }) => violation.type === 'purpose-required')
+
+  return (
+    <Tooltip title={missing ? resolve(missing.violation.message ?? missing.violation.type) : ''}>
+      <span>
+        <Button variant="contained" disabled={!canGoNext || missing !== undefined} onClick={() => next()}>
+          <Trans>Next</Trans>
+        </Button>
+      </span>
+    </Tooltip>
+  )
+}
+\`\`\``;export const generatePhoenixViolationsFeature=()=>t({path:"features/state/violations.md",title:"Violations",summary:"How violations disable control options, become hints and gate finalizing; read when a control or button must reflect what a change would break or what still blocks the configuration.",whenToUse:"Read when a control must show what an option would break, when hint text needs ranking or custom wording, or when Next or Finalize must wait for the configuration's problems. Declaring invariants, choosing a severity and repairing with transformers belong to [Validation and repair](../domain-model/validation-and-repair.md).",capabilities:"### Where violations surface\n\n- **Controls** — every option is dry-run ([Updates and dry runs](updates.md#dry-runs)). An option is `disabled` when its dry run, after transformers, still has a `fatal` or `fixable` violation or an invariant throws; its hint is the text of those violations. A `warning` or `notice` never disables an option.\n- **Messages** — a rejected commit reaches the potentially invalid slice, and its violations become configurator messages. They include every violation of that state, notices and warnings too, so check `violation.severity`. [Messages](../custom-layout/messages.md) owns showing them.\n- **Finalizing** — reads the committed state: a `warning` or a failed save blocks it, a `notice` only adds text.\n\n### Control violations\n\n`phx.frontend.useControlViolations(ignoredTypes)` returns a function from a prepared emission to `{ disabled, hints, violations }`:\n\n- no violation — enabled, no hint;\n- `notice` or `warning` — enabled, no hint, `violations` listed;\n- `fatal` or `fixable` — disabled, `hints` from those violations, `violations` all of them;\n- an invariant that throws — disabled, no hint. A transformer that throws is not caught: the control's render throws.\n\nPrefer `phx.frontend.useUpdateControl` from [Custom controls](../domain-controls/custom-controls.md), which prepares the emission and applies this mapping. Call `useControlViolations` yourself only for an emission you prepared, such as a dialog listing from `violations` what an option would break.\n\n`fixableViolations`, an argument of every control hook and of both update hooks, only removes those violation types from the hint text: the option stays disabled. List a type when another part of the UI explains it. To keep an option enabled, repair the violation in a transformer, so its dry run ends valid.\n\n### Hint text\n\n- Hints keep only the violations with the highest `controlViolationPriority` (default 0), drop duplicates and join several as sentences. Rank a root cause above its consequences, such as size above color.\n- The highest priority is found before ignored types are removed, so ignoring the top-ranked violation leaves no hint rather than the next one.\n- Set `controlViolationPriority` on a YAML invariant or on a violation returned from TypeScript. The finalize hint applies the same ranking.\n- A TypeScript violation may add `formatControlViolationMessage(emission, { i18n })`: a hint naming the attempted value, or `null` to drop this hint, such as for all but one of identical violations. Messages keep using `message`.\n- `message` is optional on a TypeScript violation, and messages fall back to its type. In YAML it is a string or `$msg`; [Localization](../localization.md) covers the catalogs.\n- `phx.frontend.useMapViolationHints(ignoreTypes?)` returns `(violations, emission) => string`, the hint text these rules make from any violations. For the committed state, take the emission from `phx.frontend.useCommittedSlice()`.\n\n### Finalize and step gating\n\n`phx.frontend.useFinalizeViolations()` returns `{ disabled, hints, violations }` for the committed state:\n\n- `disabled` while a `warning` holds or the last save failed; `hints` then says why, and `violations` is `undefined` for a failed save;\n- a `notice` leaves it enabled, with its text in `hints`;\n- `violations` lists the committed state's violations, `undefined` when there are none.\n\n`phx.frontend.useStateValidity()` returns the validity of the last committed emission: `{ valid: true, severity: null }`, or `{ valid: true, severity: 'warning' | 'notice', entityViolations }`. A `fatal` or `fixable` violation is never committed, so a `warning` is the problem the committed state can still have. Its type also lists the rejected results: narrow on `severity` before reading `entityViolations`.\n\n- Gate Finalize with `disabled` and show `hints` beside it; `useFinalizeActions` already returns both ([Finalization actions](../custom-layout/finalization-actions.md)).\n- Next enforces nothing by itself ([Tabs and steps](../custom-layout/tabs-and-steps.md)). Gate it with `disabled` and show `hints`. `useStateValidity().severity === 'warning'` holds it for the configuration alone, ignoring a failed save, and gives no text.\n- When a step waits only for its own problems, filter `violations` by their types and word them with `useMapViolationHints`.",example:e,documentation:'Read each with `pnpm phoenix docs -r <path>`:\n\n- `docs/other-features/violation-messages.mdx` — `controlViolationPriority` and `formatControlViolationMessage` worked through four ranked violations, with localized hint text.\n- `docs/other-features/violation-severity.mdx` — what each severity does to controls and finalizing; [Validation and repair](../domain-model/validation-and-repair.md) owns choosing one.\n- `docs/complex-use-cases/filtered-controls-with-fix-dialog.mdx` — controls ordered so transformers repair lower choices, with `fixableViolations` shortening each hint.\n- `docs/phoenix/configurator-interface.mdx` — "Violations" lists the violation hooks with what each returns.',phxMembers:["frontend.useControlViolations","frontend.useFinalizeViolations","frontend.useStateValidity","frontend.useMapViolationHints"]});

package/dist/application-spec/generate-application/code/templates/skills/features/variants.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../guide.js';
+export declare const generatePhoenixVariantsFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/variants.js

@@ -0,0 +1 @@
+import{createPhoenixFeatureGuide as e}from"../guide.js";export const generatePhoenixVariantsFeature=()=>e({path:"features/variants.md",title:"Variants",summary:"Supported alternative types, preview constraints and usage; read when preparing a comparison in the live preview and applying the choice.",whenToUse:"Read when preparing a visual or interaction comparison in the running preview. The [workflow](../core/workflow.md#visual-choices) owns whether alternatives would help; this guide covers the supported options and how to collect and apply a choice.",capabilities:'### Option types\n\n- Use `<id>.variant.js` to edit real frontend project files on top of one captured baseline. Use `<id>.html` for a standalone branding, layout or flow proposal rendered in an iframe.\n- Use the same mechanism for controls, layout, brand, lights, visuals, materials, positions, components, elements and transformers.\n- Keep the model, schemas, data, assistant server settings, webhooks and code shared with them, dependencies, environment and uploaded assets unchanged. The preview rejects changes needing server preparation.\n- Options reuse the already loaded configurator, one at a time. Variant transactions bypass the file-watcher debounce; hot reload still takes time to apply, without a special wait for rendering to settle.\n\n### Design the comparison\n\n- One decision per set, one set open at a time. Vary the decision being compared and keep unrelated details identical.\n- Make the difference visible in the UI or the scene; similar materials in flat light may not distinguish the alternatives.\n- Choose the number of options that clarifies the decision; no fixed count is required.\n- Name options in the client\'s product language and explain what changes in one line.\n\n### Write the options\n\n- One folder per set: `.phoenix/variants/<name>/`, one script or HTML file per option. HTML and scripts can share a set, but option ids must be unique. Keep HTML self-contained. This folder survives rebuilds and is never committed.\n- For HTML, set `<title>` and `<meta name="description" content="...">`; choosing a page changes no source files.\n- For scripts, export `title` and `description` as plain string literals, and a default function `({ read, write, remove }) => {}`; it may be async.\n- `read(path)` returns the original baseline file contents. `write(path, contents)` replaces or creates a file; `remove(path)` deletes it. Paths are relative to the project root.\n- Scripts run once per selection in the browser and collect edits. Phoenix validates and writes the whole batch locally and owns backups and undo. Do not perform your own filesystem or network operations.\n- Supported edits are YAML in `spec/` outside `spec/admin/`, and TypeScript under `src/components`, `transformers`, `handlers`, `elements` and `_`-prefixed shared folders. Expressions, actions and invariants run on the server too, so they cannot be edited.\n- Every option starts from the same baseline. Original restores it; switching restores the files only the previous option changed.\n- Keep the working tree untouched while comparing. Phoenix never overwrites an edit made outside the preview: it refuses to switch options over one, and when the comparison ends it leaves that file as it is and warns in the dev log.\n\n### Run it and wait\n\n```bash\npnpm phoenix variants .phoenix/variants/<name> --title \'<the question>\' --description \'<what differs between the options>\'\n```\n\n- `pnpm phoenix dev` must be running with the preview open in a browser. Tell the client the options are open there.\n- Put the title and the description in single quotes, so the shell passes backticks, `$` and double quotes through unchanged. In bash or zsh, write a single quote inside them as `\'\\\'\'`; in PowerShell, double it instead.\n- The command waits for the answer, 540 seconds unless `--timeout <seconds>` says otherwise, so give it a command timeout longer than that. It prints JSON:\n  - `"status": "chosen"` with `choice` (the option id, or `null` for Original) and `label`;\n  - `"status": "waiting"` when the wait ran out. The options stay open: run the same command again, or end the turn and run it when the client is back. An answer given in between is returned by the next run;\n  - `"status": "closed"` when the preview was closed without an answer.\n- `pnpm phoenix variants --close` closes the open set when the comparison is abandoned.\n- `--port <port>` names the editor WebSocket port when `phoenix dev` does not use 3020.\n- The live configurator keeps its current configuration. Interactions still change it; restoring source files does not undo configuration changes.\n\n### Use the answer\n\n- **Chosen** — a script\'s exact file edits remain in the project. For an HTML choice, implement the selected proposal using the SDK and compare the result with the page. With `choice: null`, the client chose Original and the baseline remains. Verify the result with `pnpm phoenix inspect:scene` and `pnpm phoenix screenshot`, and tell the client anything that came out differently.\n- Record the decision and its reason in the [project record](../core/workflow.md#records).\n- The client confirms Original or another option; Escape and the backdrop do not close the comparison. `--close` restores the baseline source files without an answer. The folder is removed once the client answers; pass `--keep` while its files are still needed to build from, and remove the folder afterwards.',example:"Compare warm and neutral lighting with two variant scripts while keeping the product and camera unchanged. Use HTML proposals instead when comparing standalone pages, such as branding sheets, then implement the selected proposal in the project. Original remains available as the captured baseline.",documentation:"Read `docs/phoenix/phoenix-cli.mdx` with `pnpm phoenix docs -r docs/phoenix/phoenix-cli.mdx` for the CLI contract. Use the [review index](../processes/review/index.md) to select evidence for the applied result.",phxMembers:[]});

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../guide.js';
+export declare const generatePhoenixWebhooksFeature: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/features/webhooks.js

@@ -0,0 +1 @@
+import{createPhoenixFeatureGuide as e}from"../guide.js";import{sdkGuidanceSections as o}from"../sdk-content.js";export const generatePhoenixWebhooksFeature=()=>e({path:"features/webhooks.md",title:"Webhooks",summary:"Frontend and server inclusion and import boundaries; read when adding handlers, assistant setup or shared webhook code.",whenToUse:"Read when deciding which handlers and shared modules belong in the webhook, including authentication, publication and assistant setup.",capabilities:o.webhookMembership,example:"When a pricing helper is shared by the browser and a quote webhook, keep its module server-safe. A handler that also imports a React layout cannot be included; split the shared calculation from the browser presentation.",documentation:"Read `docs/phoenix/webhook-membership.mdx` for inclusion rules and `docs/phoenix/webhooks.mdx` for worked handler and task examples, using `pnpm phoenix docs -r <path>`. The [SDK core](../core/sdk.md#webhooks-and-finalization) maps the available hooks and tasks.",phxMembers:["domain.createAssistantSetupHandler"]});

package/dist/application-spec/generate-application/code/templates/skills/guide.d.ts

@@ -0,0 +1,68 @@
+/**
+ * A Markdown document of the Phoenix skill, shipped beside its `SKILL.md`.
+ *
+ * Every document opens with its title as the only H1, and its parent index lists it by `title` and `summary`, so an
+ * agent decides from the index alone whether to read it. The factories below render the shared document shapes, so
+ * a guide follows the structure the skills architecture prescribes by construction rather than by review.
+ */
+export interface PhoenixGuide {
+    /** Path inside the skill folder, `/`-separated, such as `processes/review/code.md`. */
+    readonly path: string;
+    /** The document's name: its H1 and its entry in the parent index. */
+    readonly title: string;
+    /** What the document covers and when to read it, as one cell of the parent index. */
+    readonly summary: string;
+    readonly content: string;
+    /** The `phx` members this document is the home of; only feature guides teach members, every other document none. */
+    readonly phxMembers: readonly PhxMemberName[];
+}
+/**
+ * A member of the `phx` global a generated project declares, named by its namespace and member, such as
+ * `frontend.useTabNavigation` or `domain.implementActions`.
+ *
+ * The `phx` global is the public interface the guidance teaches. Every member has exactly one feature guide as its
+ * home, which teaches it as `phx.<namespace>.<member>`, or a recorded reason why no guide teaches it yet.
+ */
+export type PhxMemberName = `${PhxNamespace}.${string}`;
+/** The namespaces of the `phx` global. */
+export type PhxNamespace = 'frontend' | 'domain' | 'webhooks' | 'applicationTypes';
+interface PhoenixGuideHeader {
+    readonly path: string;
+    readonly title: string;
+    readonly summary: string;
+}
+/** A document organized by topic, such as a required core guide. */
+export interface PhoenixTopicGuideProps extends PhoenixGuideHeader {
+    /** Markdown sections after the H1, each usually opening with an H2. */
+    readonly sections: readonly string[];
+}
+/** A reusable procedure: its trigger, its steps, its completion boundary and one focused example. */
+export interface PhoenixProcessGuideProps extends PhoenixGuideHeader {
+    readonly whenToUse: string;
+    /** The procedure itself; topic subsections use H3. */
+    readonly steps: string;
+    readonly doneWhen: string;
+    readonly example: string;
+}
+/** What a Phoenix capability supports, when it fits, one focused example and its canonical documentation. */
+export interface PhoenixFeatureGuideProps extends PhoenixGuideHeader {
+    readonly whenToUse: string;
+    /** Supported usage and limits; topic subsections use H3. */
+    readonly capabilities: string;
+    readonly example: string;
+    readonly documentation: string;
+    /** The `phx` members this guide is the home of; its content teaches each as `phx.<namespace>.<member>`. */
+    readonly phxMembers: readonly PhxMemberName[];
+}
+/** A routing document: a short introduction and a table of its children with their summaries. */
+export interface PhoenixIndexGuideProps extends PhoenixGuideHeader {
+    readonly intro: string;
+    readonly guides: readonly PhoenixGuide[];
+    /** Markdown after the table, such as rules shared by every child or a topic map; empty when there is none. */
+    readonly notes: readonly string[];
+}
+export declare const createPhoenixTopicGuide: (props: PhoenixTopicGuideProps) => PhoenixGuide;
+export declare const createPhoenixProcessGuide: (props: PhoenixProcessGuideProps) => PhoenixGuide;
+export declare const createPhoenixFeatureGuide: (props: PhoenixFeatureGuideProps) => PhoenixGuide;
+export declare const createPhoenixIndexGuide: (props: PhoenixIndexGuideProps) => PhoenixGuide;
+export {};

package/dist/application-spec/generate-application/code/templates/skills/guide.js

@@ -0,0 +1,18 @@
+let e=(e,t)=>`${[`# ${e}`,...t.map(e=>e.trim())].join("\n\n")}
+`;export const createPhoenixTopicGuide=t=>{let{path:n,title:r,summary:i,sections:o}=t;return{path:n,title:r,summary:i,content:e(r,o),phxMembers:[]}};export const createPhoenixProcessGuide=t=>{let{path:n,title:r,summary:i,whenToUse:o,steps:s,doneWhen:a,example:c}=t;return{path:n,title:r,summary:i,phxMembers:[],content:e(r,[`## When to use
+
+${o.trim()}`,`## Steps
+
+${s.trim()}`,`## Done when
+
+${a.trim()}`,`## Example
+
+${c.trim()}`])}};export const createPhoenixFeatureGuide=t=>{let{path:n,title:r,summary:i,whenToUse:o,capabilities:s,example:a,documentation:c,phxMembers:m}=t;return{path:n,title:r,summary:i,phxMembers:m,content:e(r,[`## When to use
+
+${o.trim()}`,`## Capabilities and constraints
+
+${s.trim()}`,`## Example
+
+${a.trim()}`,`## Documentation
+
+${c.trim()}`])}};export const createPhoenixIndexGuide=t=>{let{path:n,title:r,summary:i,intro:o,guides:s,notes:a}=t,c=s.map(e=>`| [${e.title}](${((e,t)=>{let n=e.split("/").slice(0,-1),r=t.split("/"),i=0;for(;i<n.length&&i<r.length-1&&n[i]===r[i];)i+=1;return`${"../".repeat(n.length-i)}${r.slice(i).join("/")}`})(n,e.path)}) | ${e.summary} |`);return{path:n,title:r,summary:i,phxMembers:[],content:e(r,[o,["| Document | What it covers and when to read it |","| --- | --- |",...c].join("\n"),...a])}};

package/dist/application-spec/generate-application/code/templates/skills/phoenix-skill-bundle.d.ts

@@ -0,0 +1,10 @@
+import { type AgentSkillReference } from './agent-skill.js';
+import { type PhoenixSkillOptions } from './processes/index.js';
+/** The discoverable entry point and the documents it ships beside it. */
+interface PhoenixSkillBundle {
+    readonly content: string;
+    readonly references: readonly AgentSkillReference[];
+}
+/** Composes the required core, the processes and the feature guides into one discoverable Phoenix skill. */
+export declare const generatePhoenixSkillBundle: (options: PhoenixSkillOptions) => PhoenixSkillBundle;
+export {};

package/dist/application-spec/generate-application/code/templates/skills/phoenix-skill-bundle.js

@@ -0,0 +1,14 @@
+import{renderAgentSkill as e}from"./agent-skill.js";import{generatePhoenixCliCore as o,generatePhoenixSdkCore as t,generatePhoenixWorkflowCore as r}from"./core/index.js";import{generatePhoenixFeatureGuides as n}from"./features/index.js";import{createPhoenixIndexGuide as s}from"./guide.js";import{generatePhoenixAssetConversion as i,generatePhoenixBeta as a,generatePhoenixFeedbackGuides as d,generatePhoenixFinalization as c,generatePhoenixFirstDraftGuides as h,generatePhoenixModelMigration as l,generatePhoenixReviewGuides as u,generatePhoenixSpecificationGuides as p}from"./processes/index.js";export const generatePhoenixSkillBundle=m=>{let f=[r(),t(),o()],w=[h(),p(),[c()],[i()],[l()],u(),d(),[a(m)]],g=s({path:"processes/index.md",title:"Processes",summary:"Procedures summarized by outcome and when to use them.",intro:"Read the procedure or section whose outcome the task needs. The [workflow](../core/workflow.md) owns strategy, preferences and effort; processes supply the execution.",guides:w.flatMap(e=>e.slice(0,1)),notes:[]}),x=n();return{content:e({name:"phoenix",description:"Build, change, inspect, deploy or review a Phoenix configurator project. Use for all Phoenix project work, including a first draft of a new project, visual alternatives and platform feedback.",sections:[`# Phoenix
+
+Use the required core to choose how to work, then load task details only when they apply.`,`## Required reading
+
+Before Phoenix work, read these three core guides in order:
+
+${f.map((e,o)=>`${o+1}. [${e.title}](${e.path}) — ${e.summary}.`).join("\n")}
+
+The core governs every task; reading the workflow does not mean executing every stage. Reuse the core while it remains in context and unchanged, and read it again when context is lost or sync or an SDK update changes it.`,`## Optional guidance
+
+- [Processes](processes/index.md) — procedures summarized by outcome and when to use them.
+- [Features](features/index.md) — what Phoenix capabilities support, their constraints and canonical SDK documentation.
+
+Follow only the destinations the task needs; a link does not require reading its whole subtree.`]}),references:[...f,g,...w.flat(),...x].map(({path:e,content:o})=>({path:e,content:o}))}};

package/dist/application-spec/generate-application/code/templates/skills/phx-members-without-guide.d.ts

@@ -0,0 +1,9 @@
+import { type PhxMemberName } from './guide.js';
+/**
+ * The `phx` members no feature guide teaches yet, each with the reason.
+ *
+ * Every other member that is not deprecated has exactly one feature guide as its home, which declares it in its
+ * `phxMembers`; deprecated members are never mentioned. The list only shrinks: a new member gets a home or an entry
+ * here with its reason, and a guide that starts teaching a member removes its entry.
+ */
+export declare const phxMembersWithoutGuide: Readonly<Partial<Record<PhxMemberName, string>>>;

package/dist/application-spec/generate-application/code/templates/skills/phx-members-without-guide.js

@@ -0,0 +1 @@
+let e="Planned guide: lifecycle providers, handlers and runtime services.",n="Planned guide: integration modes and embedding.",t="Planned guide: theming and icon sets.",a="Planned guide: Admin.",i="Planned guide: webhook builders and finalization tasks; the SDK core lists them meanwhile.",o="Planned guide: data sources and finalization data types.";export const phxMembersWithoutGuide={"frontend.usePropertyPageStack":"Not taught: guidance renders controls from the project layout, not YAML property pages.","frontend.usePropertyPageState":"Not taught: guidance renders controls from the project layout, not YAML property pages.","frontend.useSessionService":"Internal: the session service for initialization code.","frontend.createOnApplicationStartProvider":e,"frontend.createOnSessionReadyProvider":e,"frontend.createOnPublishedDataReadyProvider":e,"frontend.createOnFrontendDataReadyProvider":e,"frontend.createOnBackendDataReadyProvider":e,"frontend.createOnRoutingReadyProvider":e,"frontend.createOnConfiguratorReadyProvider":`${e} Navigation states mentions it for mounting listeners.`,"frontend.createCollectFrontendDataHandler":e,"frontend.createFilterPublishedChunksHandler":e,"frontend.createGetTextureProcessingMapHandler":e,"frontend.useAnalytics":e,"frontend.useAuthenticatedClient":e,"frontend.useAuthorizedClient":`${e} Finalization actions mentions its finalize call.`,"frontend.useCreateAuthorizedClient":e,"frontend.useSession":`${e} Presets mentions it for reading the session role.`,"frontend.useDomainApplication":`${e} Presets mentions it for saving before leaving.`,"frontend.useConfigurator":e,"frontend.useDomainApplicationProps":e,"frontend.createGetWebComponentOptionsHandler":n,"frontend.useIntegrationService":n,"frontend.useIntegrationState":n,"frontend.useRecipeEmbeddedState":n,"frontend.usePresetEmbeddedState":n,"frontend.createGetThemeHandler":t,"frontend.createPhoenixIconSet":t,"frontend.useEntityPrice":"Planned guides: specific component kinds, such as the price component.","frontend.admin":a,"domain.admin":a,"webhooks.authHandlerBuilder":i,"webhooks.webhookBuilder":i,"webhooks.taskFactory":i,"webhooks.finalizeHandlerBuilder":i,"webhooks.callbackBuilder":i,"webhooks.prefetchBuilder":i,"webhooks.dynamicResourcesFactory":i,"applicationTypes.ApplicationVersion":o,"applicationTypes.PublishedDataHash":o,"applicationTypes.PublishedData":o,"applicationTypes.SessionData":o,"applicationTypes.FrontendData":o,"applicationTypes.BackendData":o,"applicationTypes.FinalizeData":o,"applicationTypes.PrefetchedFinalizeData":o,"applicationTypes.FinalizeResult":o,"applicationTypes.CallbackData":o,"applicationTypes.ExportState":"Planned guide: the 3D scene and image export.","applicationTypes.AdminNavigationState":a};

package/dist/application-spec/generate-application/code/templates/skills/processes/asset-conversion.d.ts

@@ -0,0 +1,2 @@
+import { type PhoenixGuide } from '../guide.js';
+export declare const generatePhoenixAssetConversion: () => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/processes/asset-conversion.js

@@ -0,0 +1,23 @@
+import{createPhoenixProcessGuide as e}from"../guide.js";let t=`Conversion is part of the product's appearance, not a preliminary chore: a converted model that is misplaced, incomplete or stripped of its detail is a visible defect, and the client sees it before anything else.
+
+### Write a script, not a sequence of one-off fixes
+
+Convert every model with one re-runnable script, committed to the project and parameterized per model. Do not repair a file by hand. A correction discovered on the first model must be in the script before the next model is converted, or it is lost: repairs made interactively do not survive the batch that follows. Record in the project record which tool chain the script uses and what each step does, so the conversion can be rerun when a source file changes.
+
+### What a converted model must satisfy
+
+- **Ground contact** — the model's lowest geometry is where the product touches the floor, and it sits at the scene's floor height without a hand-computed vertical offset. A constant that has to agree with a separately placed floor eventually disagrees with it.
+- **Completeness** — every sub-assembly that belongs to the product is present, and nothing else is: no detached fragments, no parts protruding through an outer surface, no leftover rig or construction geometry.
+- **Assembly** — parts that belong together are positioned together. Source files often store sub-assemblies at their own offsets; re-seat them against the part they attach to, not against the file's origin.
+- **Scale and orientation** — dimensions match the published figures for that product, and the model faces the same way as every other model in the set. Report any divergence from the published figures rather than silently adopting the model's.
+- **Separable materials** — parts users can configure independently carry their own materials, so a control can reach them.
+- **Material class** — a part the project gives a clearcoat needs one in the converted model already. Phoenix's clearcoat overrides act on \`MeshPhysicalMaterial\`, and three.js creates that class only when the glTF declares \`KHR_materials_clearcoat\`; on a plain \`MeshStandardMaterial\` the overrides are accepted and silently do nothing. Export painted and lacquered parts with a clearcoat value, however small, so the extension is present for the override to act on.
+
+### Detail budget
+
+Reduce geometry per part, never uniformly across a model. A single ratio removes almost nothing from large flat panels and destroys small curved parts, which are usually the ones nearest the camera. Keep full detail on parts that are small, curved and always visible, such as castors, handles, pulls and hinges, and spend the budget on large simple surfaces instead. After reducing, look at the affected parts at the default camera distance, not only at a distance that flatters them.
+
+### Verify every model, not the first one
+
+Inspect each converted model with the [asset inspection](../features/inspection.md) tooling, and check every requirement above for every model in the set. A batch that reuses a script verified on one file still needs each result looked at: source files in one delivery frequently differ in origin, scale and structure.`,r=`- Every model in scope is converted by the committed script and inspected against each requirement.
+- Divergences from published figures are reported to the client, not silently adopted.`;export const generatePhoenixAssetConversion=()=>e({path:"processes/asset-conversion.md",title:"Asset conversion",summary:"Convert and verify supplied 3D models with a reproducible script; read when supplied models need conversion or repair before configuration.",whenToUse:"When supplied models need conversion or repair before they can be configured. A [first draft](first-draft/direction.md) converts only its representative model, or builds a labeled stand-in when no model is supplied.",steps:t,doneWhen:r,example:"For a set of chairs, parameterize the conversion for the source units, the ground contact and separately configurable upholstery and frame materials. Run the same script for every supplied chair and inspect each output; a valid first model does not validate the rest."});

package/dist/application-spec/generate-application/code/templates/skills/{phoenix-skill.d.ts → processes/beta.d.ts}

@@ -1,3 +1,4 @@
+import { type PhoenixGuide } from '../guide.js';
 export interface PhoenixSkillOptions {
     readonly checkLatestCanary: boolean;
 }
@@ -10,4 +11,4 @@ export declare const followsCanaryBuilds: (project: {
     readonly useWorkspace: boolean;
     readonly sdkVersion: string;
 }) => boolean;
-export declare const generatePhoenixSkill: ({ checkLatestCanary }: PhoenixSkillOptions) => string;
+export declare const generatePhoenixBeta: ({ checkLatestCanary }: PhoenixSkillOptions) => PhoenixGuide;

package/dist/application-spec/generate-application/code/templates/skills/processes/beta.js

@@ -0,0 +1,4 @@
+import{createPhoenixProcessGuide as e}from"../guide.js";let t=`### Ask for the run evaluation
+
+The Phoenix team relies on clients' evaluations during the beta. When a deploy reports the configurator live and the client has nothing more to build, ask whether they will rate the run, and follow [Evaluate the run](feedback/evaluate.md) when they agree. Ask once per conversation, not after a deploy that failed and not while the client wants to continue; a later deploy in the same conversation does not ask again.`;export const followsCanaryBuilds=e=>!e.useWorkspace&&e.sdkVersion.includes("-develop.");export const generatePhoenixBeta=({checkLatestCanary:n})=>e({path:"processes/beta.md",title:"Beta",summary:`What the internal beta adds: ${n?"keeping this canary project on the newest SDK build, ":""}the conversation log that goes with each deploy and asking for the run evaluation; read ${n?"once per conversation before changing anything, ":""}before each deploy and when a deploy goes live.`,whenToUse:`Phoenix is in an internal beta, so this applies to every project: ${n?"once per conversation before changing anything, ":""}before each \`phoenix deploy\` and when a deploy goes live. Everything here ends with the beta.`,steps:[...n?["### Stay on the latest canary\n\nThis project uses the `canary` build of the SDK, which is published from every change to the platform. Once per conversation, before changing anything, compare the installed version, the `version` in `node_modules/@salsita-ai/sdk/package.json`, with the newest canary:\n\n```bash\nnpm view @salsita-ai/sdk@canary version\n```\n\nWhen they differ, tell the client which version the project moves to, then install that exact version, bring the packages it needs in line and regenerate the project files:\n\n```bash\npnpm add @salsita-ai/sdk@<version> && pnpm phoenix deps && pnpm install && pnpm phoenix sync\n```\n\nInstall the version npm reported rather than the `@canary` tag: a package manager's cached registry data can keep the old build while reporting success. Sync rewrites the Phoenix skills, so read the guides in use again afterwards. When the client runs a globally installed `phoenix`, update it too with `npm install -g @salsita-ai/sdk@<version>`. When the project no longer builds after the update, tell the client and report it with [Feedback](feedback/index.md)."]:[],"### Share the conversation log\n\nDuring the beta each deploy carries the conversation, so the Phoenix team can learn from the run. Immediately before running `pnpm phoenix deploy`, refresh `conversation.log` in the project root with the current conversation. Prefer the agent application's native session export when available; do not invent an export command or scan unrelated sessions. Otherwise write the messages still available in context and label the log `reconstructed; incomplete`. Never present a compaction summary as verbatim earlier messages.\n\nUse UTF-8 text with a header naming the agent, export time, source (native export or reconstructed), covered session and known omissions. Preserve the client's and the agent's messages in chronological order, plus tool names, arguments and results when available; label text the agent application injected, such as loaded skills or task notifications, as what it is rather than as the client's. Keep each tool result to at most 16 KiB of text and mark truncation explicitly; describe image attachments by reference rather than embedding binary or base64 data. Exclude internal instructions, hidden reasoning, credentials and unrelated sensitive content; mark redactions without repeating the removed content. Refresh the current session's log rather than appending duplicate copies or carrying over a previous session.\n\nShow the client the exact file to review or redact, and get their approval to include it before the deploy that sends it. A log refreshed for a later deploy is a new file and needs a new yes; showing only what was added since the approved version keeps that quick. When they decline, move it out of the project root before deploying so it cannot be collected, and keep it out for the rest of the conversation unless they change their mind. Deploy includes the file in the build's private source archive, downloadable by those authorized to download that build's sources, and leaves it out of build inputs. A missing log warns but does not block deployment.",t].join("\n\n"),doneWhen:`${n?"- The project is on the newest canary build, or the client knows why it is not.\n":""}- Each deploy carried a conversation log the client approved in that version, or none.
+- After a live deploy with nothing more to build, the client was asked once for the run evaluation.`,example:'Before the first deploy, refresh `conversation.log` and show it to the client: "This log of our conversation goes with the build, visible only to people who can download its sources. Shall I include it?" After the deploy goes live and the client says they are done for now, ask whether they will rate the run.'});