mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/concept-data-sources-lifecycle.md

@@ -0,0 +1,61 @@
+---
+id: concept-data-sources-lifecycle
+title: DataSources lifecycle (mount, deps, skip-on-undefined)
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#52-datasources-lifecycle, docs/consumer/ai-context-runtime-semantics.md#9-derive-and-datasources-lifecycle-v010--item-e]
+---
+
+# DataSources lifecycle
+
+Status: **SHIPPED v0.1.0 Item E.** Wired via internal `mountSpecRuntime`
+helper called from `MythikRenderer` (web + RN) per spec mount.
+
+## Mount
+
+1. At spec mount, framework instantiates `DataSourcesEngine` with the
+   spec's `dataSources` config + state store + resolver.
+2. Engine runs `scanDeps` on each dataSource's `url`, `params`, `headers`
+   to extract referenced state paths. These become the dataSource's deps.
+3. Initial fetch fires (when `initialFetch: true` — default).
+
+## Skip-on-undefined-URL-deps
+
+If a dataSource's URL `$template` references state that's undefined / null /
+empty at mount time, the initial fetch is **skipped** and
+`/{target}Deferred: true` is set. The reactive subscription resumes the
+fetch when deps resolve. Makes engines self-sufficient — no coordination
+with `initialActions` needed.
+
+## Auto re-fetch
+
+When the store fires a write to any declared dep, the engine re-fetches
+(debounced to coalesce rapid writes when `debounce` is configured).
+
+## `emptyWhileLoading`
+
+- `false` (default) — old data stays visible during fetch.
+- `true` — target state path cleared to `null` at fetch start.
+
+## Manual refresh
+
+```json
+{ "action": "refreshDataSource", "params": { "id": "rooms" } }
+```
+
+Auto-registered for any spec with dataSources.
+
+## Re-mount safety (navigation)
+
+`dispatcher.registerAction` uses `Map.set` (silent overwrite) — re-mounting
+a spec with the same dataSources on the same dispatcher does not throw.
+DataSourcesEngine's `refresh()` early-returns if the engine has been unmounted.
+
+## Related concepts
+
+- [[@concept-data-sources]]
+- [[@concept-derive-datasources-mount-order]] — mount-time ordering with derive
+- [[@action-refresh-data-source]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 5.2` + § 9

package/docs/wiki/compiled/concept-data-sources.md

@@ -0,0 +1,96 @@
+---
+id: concept-data-sources
+title: `dataSources` — reactive GET fetching
+kind: concept
+sources: [docs/consumer/ai-context.md#datasources, docs/consumer/reference-doc.md#data-sources-datasources, docs/consumer/ai-context-runtime-semantics.md#52-datasources-lifecycle]
+---
+
+# `dataSources` — reactive GET fetching
+
+Declarative reactive data fetching. Makes specs self-contained. Fetches
+re-fire automatically when declared parameter dependencies change. **For
+one-shot operations (POST/PATCH/DELETE), use [[@action-fetch]] inside
+transactions.**
+
+## Shape / Signature
+
+```json
+"dataSources": {
+  "tasks": {
+    "url": { "$template": "${/config/apiUrl}/rest/v1/tasks?select=*" },
+    "method": "GET",
+    "headers": { "$state": "/config/headers" },
+    "params": {
+      "status": { "$state": "/filter/status" },
+      "page": { "$state": "/pagination/page" },
+      "search": { "$state": "/filter/search" }
+    },
+    "target": "/tasks",
+    "trigger": "auto",
+    "debounce": 300,
+    "initialFetch": true,
+    "emptyWhileLoading": false
+  }
+}
+```
+
+## Properties
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `url` | Expression | — | Request URL (supports `$template`, `$state`) |
+| `method` | string | `"GET"` | HTTP method |
+| `headers` | Expression | — | From state, NOT from spec (no keys in DB) |
+| `params` | `Record<string, Expression>` | — | Reactive params — changes trigger re-fetch |
+| `target` | string | — | State path where response is written |
+| `trigger` | `"auto"` \| `"manual"` | `"auto"` | `auto`: re-fetch on param change. `manual`: only via `refreshDataSource` |
+| `debounce` | number | `0` | Debounce ms for auto-trigger |
+| `initialFetch` | boolean | `true` | Fetch on spec mount |
+| `emptyWhileLoading` | boolean | `false` | If true, clear target while loading |
+
+## Auto-generated state paths
+
+For a dataSource with `target: "/tasks"`:
+- `/tasks` — response data
+- `/tasksLoading` — boolean
+- `/tasksError` — error or null
+- `/{target}Deferred: true` — set when initial fetch is skipped because URL
+  template deps are unresolved (Item E). Render "waiting for prerequisite"
+  UI distinct from `/{target}Loading`.
+
+## Param filtering
+
+Values `null`, `undefined`, `""`, or `"all"` are omitted from the query
+string (inactive filter).
+
+## Constraints / Anti-patterns
+
+- **URL templating requires `$template`.** Plain strings with `${...}`
+  are LITERAL — validator catches this (see
+- **Don't mix `fetch` and `dataSources` for same target.** See
+  [[@antipattern-mix-fetch-and-datasources]] +
+  [[@pattern-fetch-vs-datasources]].
+- **Headers from state, not from spec.** API keys must NOT live in DB —
+  inject via host-app `initialState` / `sharedState`.
+
+## Force re-fetch
+
+```json
+{ "action": "refreshDataSource", "params": { "id": "tasks" } }
+```
+
+## Related concepts
+
+- [[@action-fetch]] — non-reactive alternative
+- [[@action-refresh-data-source]]
+- [[@concept-data-sources-lifecycle]]
+- [[@concept-derive-datasources-mount-order]]
+- [[@concept-derive]]
+- [[@path-data-source-paths]]
+- [[@concept-template-interpolation]] — URL template gotcha
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § DataSources`
+- `docs/consumer/reference-doc.md § Data Sources (dataSources)`
+- `docs/consumer/ai-context-runtime-semantics.md § 5.2`

package/docs/wiki/compiled/concept-debugging-runtime-pointers.md

@@ -0,0 +1,45 @@
+---
+id: concept-debugging-runtime-pointers
+title: Debugging runtime — source-file pointers
+kind: concept
+sources: [docs/consumer/WHERE-TO-LOOK.md]
+---
+
+# Debugging runtime — source pointers
+
+For "why is X happening?" questions, the following entry points trace
+where the behavior originates. **Read the relevant
+`ai-context-runtime-semantics.md` section first** — these source pointers
+are the fallback.
+
+## Common scenarios
+
+| You see... | Trace through |
+|---|---|
+| Expression re-evaluates more than expected | `expressions/resolver.ts` → `state/store.ts` (subscriptions) → `derive/evaluator.ts` (if in derive) → `data/data-sources.ts` (if in dataSource) |
+| Action runs in different order than dispatched | `actions/dispatcher.ts` (queue + tx orchestration) → `actions/transaction-engine.ts` → `actions/middleware.ts` |
+| `fetch` action behaves unexpectedly (auth header, retry, error) | `fetch/framework-fetch.ts` (interceptor chain) → `fetch/interceptors/` (auth, retry, timeout, logging) |
+| dataSource refresh fires/skips at surprising moment | `data/data-sources.ts` → `derive/evaluator.ts` (coordination) → `actions/dispatcher.ts` (`refreshDataSource`) |
+| Form state diverges from spec | `forms/engine.ts` (lifecycle) + `forms/types.ts` (shape) → `state/store.ts` (form paths) |
+| Renderer re-renders too eagerly/lazily | `MythikRenderer.tsx` → `renderer/engine.ts` + `renderer/deps.ts` + `renderer/lazy-paths.ts` → `primitives/<primitive>.tsx` |
+| Server endpoint returns different envelope | `server/src/server.ts` — `createServer` (line 53), `registerEndpoint` (line 373), envelope (line 497-511) |
+| Auth flow rejecting token | Server: `server.ts` (login/refresh routes 104-130) → `auth/db-auth-provider.ts` + `auth/jwt-strategy.ts` + `auth/middleware.ts`. Client: `auth/engine.ts` + `refresh-engine.ts`. Wire: `fetch/interceptors/auth.ts` |
+| CRUD auto-route 404 / collision | `server.ts:373` (registerEndpoint) → `server.ts:549-686` (CRUD block) → `handler-loader.ts` → `crud-builder.ts` |
+| Optimistic update flickers / rollbacks | `actions/transaction-engine.ts` → `streaming/patch.ts` → `streaming/compiler.ts` |
+| `mythik push` reports wrong element count | `cli/commands/push.ts` → `cli/api.ts` → `spec-engine/handlers/<doctype>-handler.ts` (per-doctype `countElements`) |
+
+## Doc-side first
+
+For ANY of these — read the corresponding `ai-context-runtime-semantics.md`
+section first. Source pointers are for cases where the docs leave a gap.
+
+## Related concepts
+
+- [[@concept-where-to-look]]
+- [[@concept-expression-timing]]
+- [[@concept-source-of-truth-references]]
+- [[@concept-source-reading-misleading]]
+
+## Sources (raw)
+
+- `docs/consumer/WHERE-TO-LOOK.md § Section 2`

package/docs/wiki/compiled/concept-derive-datasources-mount-order.md

@@ -0,0 +1,72 @@
+---
+id: concept-derive-datasources-mount-order
+title: Derive + DataSources mount ordering
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#9-derive-and-datasources-lifecycle-v010--item-e]
+---
+
+# Derive + DataSources mount ordering
+
+Both engines execute at runtime per spec mount via internal
+`mountSpecRuntime` helper called from `MythikRenderer` (web + RN). Order
+inside `mountSpecRuntime`:
+
+1. **`DeriveEngine.mount()`** — sync evaluation in topological order;
+   writes derive paths to store.
+2. Subscribe `derive.onStateChange` to store — reactive recompute on
+   state changes.
+3. `protectionRegistry.contribute(derivePaths)` — derive paths now
+   blocked from `setState`.
+4. `dispatcher.registerAction(dataSources.getActionDefinition())` —
+   `refreshDataSource` action becomes available.
+5. **`DataSourcesEngine.mount()`** — initial fetches with
+   skip-on-undefined-URL-deps.
+
+## Renderer useEffect order
+
+The state-subscription `useEffect` is declared **before** the
+`mountSpecRuntime` `useEffect`. React fires effects in declaration order,
+so the subscription is attached first; deriveEngine.mount()'s synchronous
+writes are then captured by that listener and trigger initial-paint
+re-render.
+
+If you fork or reimplement `MythikRenderer`, preserve this ordering —
+otherwise initial paint misses derive writes.
+
+## Re-entrant safety
+
+Derive recompute writes fire the store subscription, which calls
+`onStateChange` recursively. **Intentional** — chained derives need to
+cascade (B depending on A's output sees A's write and recomputes).
+Infinite loops prevented structurally:
+- Topo-sort at mount throws on circular deps.
+- A derive's own write doesn't make itself dirty (its deps don't include
+  its own path).
+
+## State protection
+
+Derive paths are contributed via RAII handle to `protectionRegistry`;
+`stateGuard` reads via lazy callback. Validator catches
+`setState → derive path` at load time (8 derive/dataSources checks);
+dispatcher catches at runtime via `stateGuard.assertCanWrite`. Defense in
+depth.
+
+## Error degradation
+
+`DeriveEngine.evaluatePath` wraps each evaluation in try/catch. On error:
+`console.error` with the path name, leave path unwritten (consumer reads
+undefined), continue with other derives. Reactive recompute on subsequent
+state changes can recover.
+
+## Related concepts
+
+- [[@concept-derive]]
+- [[@concept-data-sources]]
+- [[@concept-data-sources-lifecycle]]
+- [[@concept-state-protection]]
+- [[@concept-mount-spec-runtime]]
+- [[@concept-mythik-renderer]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 9`

package/docs/wiki/compiled/concept-derive.md

@@ -0,0 +1,67 @@
+---
+id: concept-derive
+title: `derive` — derived state
+kind: concept
+sources: [docs/consumer/ai-context.md#derived-state, docs/consumer/reference-doc.md#derived-state-derive, docs/consumer/ai-context-runtime-semantics.md#53-derive-evaluation-order]
+---
+
+# `derive` — derived state
+
+Auto-computed reactive state. Declared at spec level. **Read-only** —
+StateGuard blocks `setState` writes to derive paths. Dependency-tracked —
+only re-evaluates when a dependency changes.
+
+## Shape / Signature
+
+```json
+{
+  "derive": {
+    "/stats/total": { "$array": "count", "source": { "$state": "/items" } },
+    "/stats/avg": { "$math": "divide", "args": [
+      { "$array": "sum", "source": { "$state": "/items" }, "field": "price" },
+      { "$array": "count", "source": { "$state": "/items" } }
+    ]}
+  }
+}
+```
+
+## How it works
+
+1. On spec mount: all derive expressions are evaluated in dependency order
+   (topological sort).
+2. On state change: only derives whose deps changed re-evaluate.
+3. Derive paths are **read-only** — `setState` to a derive path is blocked
+   by StateGuard.
+4. Circular dependencies are detected at mount time (throws error).
+5. Derive A can reference Derive B (no cycles).
+
+## Constraints / Anti-patterns
+
+- **Derive sees only data in state.** With server-side pagination, state
+  holds the current page — derive sums/counts reflect the page, not the
+  full dataset. For full-dataset totals, use the API's `totals` response.
+  See [[@antipattern-derive-server-pagination]].
+- **`$auth` not available in derive.** Use `$state: "/auth/*"` instead.
+  See [[@concept-expression-contexts]].
+- **Empty/cyclic/protected paths fail at validation** — see
+- **DeriveEngine degrades gracefully**: one bad expression doesn't break
+  others. Errors logged via `console.error`; affected path stays
+  unwritten or holds last-good value.
+
+## Lifecycle (post-Item-E)
+
+DeriveEngine mounts first, populates derive paths from current state, then
+subscribes for reactive recompute. See [[@concept-derive-datasources-mount-order]].
+
+## Related concepts
+
+- [[@concept-data-sources]]
+- [[@concept-derive-datasources-mount-order]]
+- [[@concept-state-protection]]
+- [[@concept-expression-contexts]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Derived State`
+- `docs/consumer/reference-doc.md § Derived State (derive)`
+- `docs/consumer/ai-context-runtime-semantics.md § 5.3`

package/docs/wiki/compiled/concept-dna-seeds.md

@@ -0,0 +1,79 @@
+---
+id: concept-dna-seeds
+title: DNA seeds — 8 inputs that derive everything
+kind: concept
+sources: [docs/consumer/ai-context.md#deep-design-token-system, docs/consumer/reference-doc.md#dna-seeds]
+---
+
+# DNA seeds
+
+Define 1-8 seeds in `tokens.dna`. The framework derives ALL token
+categories automatically — colors via OKLCH tonal palette, shape, typography,
+spacing, elevation, motion, opacity, plus auto dark mode.
+
+## Catalog
+
+| Seed | Type | Default | Controls |
+|---|---|---|---|
+| `primary` | hex | (required) | Base color → 13-stop OKLCH tonal palette |
+| `harmony` | enum | `complementary` | How accent relates to primary: `complementary` (180°), `analogous` (50°), `triadic` (120°), `split-complementary` (150°) |
+| `accent` | hex (optional) | derived | Explicit accent (skips harmony) |
+| `neutral` | enum | `natural` | `warm` (amber 55°), `cool` (blue 250°), `natural` (primary hue). Chroma 0.025 (natural) / 0.035 (warm/cool) |
+| `roundness` | 0–1 | 0.5 | Shape: 0=sharp/brutalist → 1=pill/playful |
+| `density` | 0–1 | 0.5 | Spacing: 0=airy → 1=compact |
+| `depth` | 0–1 | 0.5 | Shadows: 0=flat → 1=elevated |
+| `motion` | enum | `gentle` | `fluid`, `snappy`, `gentle`, `energetic` — animation personality |
+| `formality` | 0–1 | 0.5 | Typography (5 font tiers + continuous letterSpacing/lineHeight/bold weight) |
+
+## Examples
+
+Minimal:
+```json
+"tokens": { "dna": { "primary": "#0D9488" } }
+```
+
+Full personality:
+```json
+"tokens": { "dna": {
+  "primary": "#0D9488",
+  "harmony": "analogous",
+  "roundness": 0.7,
+  "density": 0.5,
+  "depth": 0.6,
+  "motion": "fluid",
+  "formality": 0.3
+}}
+```
+
+## Formality drives 5 font tiers
+
+| Range | Body | Heading |
+|---|---|---|
+| 0.0 | Inter | Inter |
+| 0.25 | Space Grotesk | Space Grotesk |
+| 0.5 | Source Sans 3 | DM Sans |
+| 0.75 | Lora | Lora |
+| 1.0 | Merriweather | Playfair Display |
+
+Plus continuous: `letterSpacing` (0 → 0.03em), `headingLetterSpacing`
+(0 → -0.02em), `lineHeight` ratio (1.45 → 1.6), bold weight (700 → 800).
+
+## Primary preserved as-is
+
+`deriveDna` uses `seed.primary` directly as `colors.primary` (the exact
+hex). Variants derived via relative OKLCH lightness: `primaryLight` =
+L+15%, `primaryDark` = L-20%. Tonal palette still generated for dark mode
++ neutrals (rule 164).
+
+## Related concepts
+
+- [[@concept-token-system]]
+- [[@concept-token-categories]]
+- [[@concept-auto-dark-mode]]
+- [[@action-update-tokens]] — runtime DNA changes
+- [[@concept-cli-tokens-inspect]] — `mythik tokens` CLI
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Deep Design Token System → DNA Seed`
+- `docs/consumer/reference-doc.md § DNA Seeds`

package/docs/wiki/compiled/concept-editor-commit.md

@@ -0,0 +1,37 @@
+---
+id: concept-editor-commit
+title: editorCommit action
+kind: action
+sources: [docs/consumer/ai-context-runtime-semantics.md, docs/consumer/reference-doc.md]
+---
+
+# editorCommit action
+
+`editorCommit` applies atomic tracked-path edits through an editor session and pushes one undo entry.
+
+Use it when an edit should be recoverable:
+
+```json
+{
+  "action": "editorCommit",
+  "params": {
+    "session": "floor-layout",
+    "label": "Move item",
+    "changes": [
+      {
+        "path": "/layout/items",
+        "value": {
+          "$array": "replace",
+          "source": { "$state": "/layout/items" },
+          "where": { "field": "id", "eq": { "$state": "/ui/spatialItemChange/itemId" } },
+          "value": { "$state": "/ui/spatialItemChange/nextItem" }
+        }
+      }
+    ]
+  }
+}
+```
+
+No-op commits do not push history. Dirty state is computed against the saved snapshot, not guessed from the last action.
+
+Related: [[@concept-editor-sessions]], [[@concept-spatial-map-editor]].

package/docs/wiki/compiled/concept-editor-save.md

@@ -0,0 +1,18 @@
+---
+id: concept-editor-save
+title: editorSave action
+kind: action
+sources: [docs/consumer/ai-context-runtime-semantics.md, docs/consumer/reference-doc.md]
+---
+
+# editorSave action
+
+`editorSave` is the recommended save action for editor sessions.
+
+It captures the in-flight tracked-path snapshot, persists that snapshot through the host fetcher, and marks only that sent snapshot as saved after success. If the user edits while save is in flight, the current document remains dirty.
+
+Save failures never mark the session clean. Status, error, and attempt metadata live under `/ui/editorSessions/<id>`.
+
+Do not hand-compose `transaction` plus `editorMarkSaved` for normal editor save flows. `editorMarkSaved` is a low-level escape hatch.
+
+Related: [[@concept-editor-sessions]], [[@concept-navigation-dirty-guard]].

package/docs/wiki/compiled/concept-editor-sessions.md

@@ -0,0 +1,23 @@
+---
+id: concept-editor-sessions
+title: Editor sessions
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md, docs/consumer/reference-doc.md]
+---
+
+# Editor sessions
+
+Editor sessions provide document-style editing over tracked state paths.
+
+They manage:
+
+- undo and redo,
+- dirty tracking,
+- discard to saved snapshot,
+- validation metadata,
+- save status and save errors,
+- integration with navigation dirty guards.
+
+Use `editorCommit` to group one or more tracked-path changes into a semantic editor operation. The action lazily resolves `changes[].value` at dispatch time, so it composes with spatial edit contexts such as `/ui/spatialItemChange/nextItem` and `/ui/spatialZoneChange/nextZone`.
+
+Related: [[@concept-editor-commit]], [[@concept-editor-save]], [[@concept-navigation-dirty-guard]].

package/docs/wiki/compiled/concept-element-children-slot.md

@@ -0,0 +1,54 @@
+---
+id: concept-element-children-slot
+title: `"$children"` slot in custom element render trees
+kind: concept
+sources: [docs/consumer/ai-context-custom-elements.md#elementrendernode]
+---
+
+# `"$children"` slot in custom element render trees
+
+Authors mark slot positions for consumer children with the **string
+literal** `"$children"` in `render.children` (or any nested
+`children` array).
+
+## Syntax
+
+```json
+"render": {
+  "type": "stack",
+  "children": [
+    { "type": "icon", "props": { "name": "star" }, "repeat": { "count": { "$prop": "max" } } },
+    "$children"
+  ]
+}
+```
+
+`"$children"` is replaced with the consumer's `children` array at
+expansion time.
+
+## Multiple markers
+
+Multiple markers each splice the full consumer children list. Authors can
+position the slot anywhere in the render tree.
+
+## Constraints / Anti-patterns
+
+- **`"$children"` is a string literal** — write the bare string as an
+  item in `children`, NOT `{ "$children": true }`. The expression-object
+  form is silently ignored.
+
+## Identity
+
+Same slot semantics as spec templates ([[@concept-template-children-marker]]).
+Consumer children retain their enclosing element IDs and render via the
+unified dispatch.
+
+## Related concepts
+
+- [[@concept-element-render-node]]
+- [[@concept-template-children-marker]] — spec-template equivalent
+- [[@concept-custom-elements]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-custom-elements.md § ElementRenderNode → "$children" slot`

package/docs/wiki/compiled/concept-element-definition.md

@@ -0,0 +1,60 @@
+---
+id: concept-element-definition
+title: `ElementDefinition` shape
+kind: concept
+sources: [docs/consumer/ai-context-custom-elements.md#elementdefinition-shape]
+---
+
+# `ElementDefinition` shape
+
+Argument to `plugins.registerElement`.
+
+## Shape
+
+```json
+{
+  "type": "rating-stars",
+  "props": {
+    "max": { "type": "number", "default": 5 },
+    "value": { "type": "number", "bindable": true },
+    "label": { "type": "string", "default": "" }
+  },
+  "variants": {
+    "compact": { "props": { "max": 3 }, "style": { "gap": 2 } },
+    "large":   { "style": { "gap": 8 }, "animations": { "mount": { "recipe": "scale-in" } } }
+  },
+  "render": {
+    "type": "stack",
+    "props": { "direction": "horizontal", "gap": { "$prop": "gap" } },
+    "children": [
+      {
+        "type": "icon",
+        "props": { "name": "star" },
+        "repeat": { "count": { "$prop": "max" } },
+        "animations": { "hover": { "recipe": "lift" } }
+      },
+      { "type": "text", "props": { "content": { "$prop": "label" } } }
+    ]
+  }
+}
+```
+
+## Fields
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `type` | string | yes | Public type name consumers use in specs |
+| `props` | `Record<name, PropDefinition>` | no | Declared accepted props |
+| `variants` | `Record<name, ElementVariantSpec>` | no | Author-shipped variants |
+| `render` | `ElementRenderNode` | yes | Render tree built from primitives (and nested custom elements + templates) |
+
+## Related concepts
+
+- [[@concept-element-prop-definition]] — `PropDefinition` fields
+- [[@concept-element-render-node]] — render tree contract
+- [[@concept-element-variants]] — `ElementVariantSpec`
+- [[@concept-custom-elements]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-custom-elements.md § ElementDefinition Shape`

package/docs/wiki/compiled/concept-element-key.md

@@ -0,0 +1,56 @@
+---
+id: concept-element-key
+title: Element `key` — forced remount
+kind: concept
+sources: [docs/consumer/ai-context.md#rules, docs/consumer/reference-doc.md#element-properties]
+---
+
+# Element `key` — forced remount
+
+`Element.key` is a dynamic React key. When the resolved value changes, React
+unmounts and remounts the element, re-triggering mount animations and
+resetting any internal state. Use `key` whenever you need to force-restart
+visual transitions on a state change (e.g., re-animate a preview after the
+user applies new settings).
+
+## Shape / Signature
+
+```json
+{ "type": "...", "key": "<expression>", "props": { ... } }
+```
+
+The expression supports `$template`, `$state`, and other expressions that
+resolve to a string.
+
+## Examples
+
+Re-animate a preview when DNA tokens are applied:
+```json
+{
+  "type": "box",
+  "key": { "$template": "preview-${/internal/tokenVersion}" },
+  "animations": { "mount": { "recipe": "fade-up" } },
+  "children": ["preview-content"]
+}
+```
+
+Each time `/internal/tokenVersion` changes, the box remounts and
+`mount: fade-up` re-fires.
+
+## Constraints / Anti-patterns
+
+- Use sparingly — every `key` change is a real unmount/remount. Internal
+  state (form fields inside, scroll position) is lost.
+- Prefer `animations.stateChange` (see
+  [[@concept-state-change-animation]]) when you only want to react to a
+  state change, not full remount.
+
+## Related concepts
+
+- [[@concept-animations-engine]] — `animations.mount` recipes
+- [[@concept-state-change-animation]] — softer alternative for state-driven motion
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Rules → rule 45`
+- `docs/consumer/reference-doc.md § Element Properties (key row)` + rule 107