mythik 0.1.3 → 0.1.5

package/docs/consumer/ai-context.md

@@ -24,14 +24,17 @@ Use `npm install mythik mythik-react` for a React app, `npm install -D mythik-cl
 
 Server-side SQL helpers, SQL drivers, and SQL-backed spec stores are imported from `mythik/server`, not from the browser-safe `mythik` entry. Supported SQL dialects are `sqlserver`, `postgres`, `mysql`, and `sqlite`.
 
-Database runtime dependencies: SQL adapters (`mssql`, `pg`, `mysql2`, and `better-sqlite3`) are optional dependencies of `mythik` and install by default with npm/pnpm unless optional dependencies are omitted. If the host installs with optional dependencies disabled, add only the adapter you use:
+Database runtime dependencies: SQL adapters (`mssql`, `pg`, `mysql2`, and `better-sqlite3`) are optional peer dependencies. Browser-only installs do not need them. SQL-backed stores and servers must install exactly the adapter for the selected database:
 
 ```bash
+npm install mssql           # SQL Server
 npm install pg              # PostgreSQL
 npm install mysql2          # MySQL
 npm install better-sqlite3  # SQLite
 ```
 
+SQLite uses the native `better-sqlite3` adapter. npm warnings from that adapter's transitive native-build helpers are adapter-level install noise, not a Mythik runtime failure. Missing SQL adapter errors include the package name and exact install command for the selected dialect.
+
 MySQL support targets MySQL 8.0.19+ for generated upsert SQL. Older MySQL deployments need an explicit custom SQL path or another supported dialect.
 
 ## Spec Structure
@@ -268,18 +271,26 @@ Resolves by current platform. `"native"` alias matches ios and android. Specific
 - `$breakpoint`: Layout adaptation (columns, gaps, padding, direction) — same component, different sizing
 - `$platform`: Platform-specific techniques (CSS blur vs native BlurView, hover vs press, web sidebar vs native tabs) — different implementation, same feature
 
-**Root-level `$platform`** — for fundamentally different platform layouts:
+**Keep `root` stable.** The top-level `root` value is a string element id. Do not put `$platform` directly in `root`. For platform differences, branch at localized props/children/style points, or create separate screen specs when the platform experience is fundamentally different:
 ```json
 {
-  "root": { "$platform": { "web": "layout-web", "native": "layout-native" } },
+  "root": "layout",
   "elements": {
-    "layout-web": { "type": "stack", "style": { "backdropFilter": "blur(24px)" } },
-    "layout-native": { "type": "screen", "props": { "title": "Dashboard" } },
+    "layout": {
+      "type": "stack",
+      "props": {
+        "direction": { "$platform": { "web": "horizontal", "native": "vertical" } }
+      },
+      "style": {
+        "backdropFilter": { "$platform": { "web": "blur(24px)", "native": null } }
+      },
+      "children": ["shared-form"]
+    },
     "shared-form": { "type": "stack", "children": ["..."] }
   }
 }
 ```
-State, initialActions, and forms are shared — only presentation branches per platform.
+State, initialActions, and forms stay shared while only the presentation technique branches per platform.
 
 ### Math & Data
 
@@ -342,19 +353,19 @@ Extended: `locale`, `notation` (compact/scientific), `signDisplay` (always/excep
 
 ### Named Bindings
 
-`$let` / `$ref` — define once, use many times:
-```json
-{ "$let": { "total": { "$array": "count", "source": { "$state": "/items" } } }, "$in": { "$ref": "total" } }
-```
-`$ref` may also read nested values from an object binding with dot notation:
-```json
-{ "$let": { "user": { "$state": "/auth/user" } }, "$in": { "$ref": "user.name" } }
-```
-Inside the same `$let`, `$template` placeholders can read the same dotted binding paths, for example `${user.name}`.
-**JSONB array format** (when stored in DB, order matters):
-```json
-{ "$let": [["filtered", { "$array": "filter", "source": { "$state": "/items" }, "where": { "field": "status", "eq": "active" } }], ["count", { "$array": "count", "source": { "$ref": "filtered" } }]], "$in": { "$ref": "count" } }
-```
+`$let` / `$ref` — define once, use many times:
+```json
+{ "$let": { "total": { "$array": "count", "source": { "$state": "/items" } } }, "$in": { "$ref": "total" } }
+```
+`$ref` may also read nested values from an object binding with dot notation:
+```json
+{ "$let": { "user": { "$state": "/auth/user" } }, "$in": { "$ref": "user.name" } }
+```
+Inside the same `$let`, `$template` placeholders can read the same dotted binding paths, for example `${user.name}`.
+**JSONB array format** (when stored in DB, order matters):
+```json
+{ "$let": [["filtered", { "$array": "filter", "source": { "$state": "/items" }, "where": { "field": "status", "eq": "active" } }], ["count", { "$array": "count", "source": { "$ref": "filtered" } }]], "$in": { "$ref": "count" } }
+```
 
 ### Group & Selection (inside repeat)
 
@@ -391,15 +402,15 @@ All primitives accept `style`, `visible`, and `permission`. Tokens are project-d
 
 Wire to events with `on`: `{ "on": { "press": { "action": "...", "params": {...} } } }`
 
-Arrays execute sequentially: `"press": [action1, action2, action3]`. Arrays may mix normal action bindings and transaction bindings; each entry runs in order and transactions are awaited before the next entry.
+Arrays execute sequentially: `"press": [action1, action2, action3]`. Arrays may mix normal action bindings and transaction bindings; each entry runs in order and transactions are awaited before the next entry.
 
 **Trap:** Action chains don't stop on failure — `validateForm` marks errors but does NOT halt the chain. Use `submitForm` with `formId` instead (validates + blocks if invalid). See [ai-context-patterns.md](ai-context-patterns.md).
 
-Add `"fireAndForget": true` to dispatch without waiting (background re-fetch after closing modal).
-
-Any action binding may include `params.skipIf`. Mythik resolves `skipIf` at dispatch time before resolving the rest of the params; when truthy, that action is skipped and the surrounding action chain continues.
-
-### Action Reference
+Add `"fireAndForget": true` to dispatch without waiting (background re-fetch after closing modal).
+
+Any action binding may include `params.skipIf`. Mythik resolves `skipIf` at dispatch time before resolving the rest of the params; when truthy, that action is skipped and the surrounding action chain continues.
+
+### Action Reference
 
 | Action | Params | Purpose |
 |--------|--------|---------|
@@ -438,6 +449,7 @@ Any action binding may include `params.skipIf`. Mythik resolves `skipIf` at disp
 - Empty strings in body → `null` (prevents DB errors)
 - Sets `/ui/loading` while in flight
 - On error: sets `/ui/lastError` with status and message
+- Optional `errorTarget` writes the same structured error to a screen-owned path and clears that path on success. Use it for critical screen-load fetches instead of relying only on global `/ui/lastError`
 - Auth headers auto-injected for `authDomains` URLs
 
 ### Transactions (Optimistic Updates)
@@ -591,14 +603,16 @@ Inside: `{ "$selection": "selected" }` (boolean), `{ "$selection": "count" }`. T
 
 **Rule:** Don't mix both for the same data target. Pick one pattern per data source.
 
+For critical `initialActions` fetches, set `params.errorTarget` to a screen-owned path (for example `/ui/loadErrors/orderForm`) and render a visible error state from that path. `/ui/lastError` is global and can be overwritten by unrelated fetches.
+
 ### Loading/Content/Empty Pattern
 
-**With `initialActions` fetch** (uses `/ui/loading` and `/ui/lastError`):
+**With `initialActions` fetch** (uses `/ui/loading`; critical loads should set `errorTarget`):
 ```json
 "loading": { "visible": { "$and": [{ "$state": "/ui/loading" }, { "$not": { "$array": "count", "source": { "$state": "/items" } } }] } },
 "content": { "visible": { "$array": "count", "source": { "$state": "/items" } } },
 "empty":   { "visible": { "$and": [{ "$not": { "$state": "/ui/loading" } }, { "$not": { "$array": "count", "source": { "$state": "/items" } } }] } },
-"error":   { "visible": { "$state": "/ui/lastError" } }
+"error":   { "visible": { "$state": "/ui/loadErrors/items" } }
 ```
 
 **With `dataSources`** (uses auto-generated `/{target}Loading` and `/{target}Error`):
@@ -1347,7 +1361,7 @@ If a consumer overrides any name, AI applies the same schema under the consumer-
 
 ### Canonical reference
 
-The canonical SQL store DDL ships in the installed package. Use `mythik init-store --dialect <sqlserver|postgres|mysql|sqlite> --dry-run` or `getSqlStoreDdl(dialect)` from `mythik/server` to inspect it. Do not copy DDL from unrelated local artifacts.
+The canonical SQL store DDL ships in the installed package. Use `mythik init-store --dialect <sqlserver|postgres|mysql|sqlite> --dry-run` or `getSqlStoreDdl(dialect)` from `mythik/server` to inspect it. Do not copy DDL from unrelated local artifacts.
 
 ### Schema evolution
 
@@ -1445,9 +1459,14 @@ When the framework changes the schema in a future version, this section will gai
 85. For existing spec edits, the required AI loop is `mythik manifest` -> `mythik elements` -> `mythik patch --from-file` -> verify. Manifest tells you the structure; elements gives the exact JSON you are changing; patch is the validated write path. Do not skip directly to full-spec `pull`/rewrite/push for a local change, do not mutate DB rows manually, and do not call `SpecStore.save()` from app code. Use `push` for new specs or intentional full replacement only.
 86. Mythik's AI documentation ships with the `mythik` npm package. Before generating or modifying specs, locate it with `mythik docs path` and start from `docs/llms.txt`, `docs/consumer/ai-context.md`, and `docs/wiki/compiled/README.md`. Use `mythik docs copy ./mythik-docs` when a project-local copy is easier to hand to an AI agent.
 87. DNA numeric seeds (`roundness`, `density`, `depth`, `formality`) are canonical `0–1` values. Generate `0.7`, not `70`. The runtime tolerates legacy `0–100` values by normalizing any numeric seed greater than `1` with `/100` during DNA derivation, including initial AppSpec load and runtime `updateTokens`.
-88. API query endpoints can combine `pagination: "offset"` with `scopeFilter`. For generated counts, Mythik applies the scope filter to the source query before `COUNT(*)`, so paginated totals remain tenant-scoped. Prefer generated counts. If a custom `endpoint.count` is truly needed with `scopeFilter`, include `{{scopeWhere[:alias]}}` or `{{scopeAnd[:alias]}}`; Mythik expands the macro to the correct scope predicate and removes it for bypass roles. Other custom count SQL is left verbatim. Use `:alias` for JOIN/subquery counts, and do not reference internal scope params directly.
-89. Transaction `confirm` failures from `fetch` preserve backend error details for `onError`. Read `/tx/error/message` for the best available message; when the backend returns `{ error: { code, message } }`, Mythik keeps that message, `code`, HTTP `status`, and raw `data` after rollback. Do not parse `/ui/lastError` from transaction specs.
-90. For SQL-backed stores and servers, use the generic `mythik/server` SQL boundary. Initialize tables with `mythik init-store --dialect <sqlserver|postgres|mysql|sqlite>` or inspect DDL with `--dry-run`; configure the CLI with `--store`, `--url`/`--filename`/SQL Server flags, or `MYTHIK_*` environment variables; and keep spec edits on the required `manifest -> elements -> patch --from-file -> validate` loop. Write custom API SQL in the selected dialect with Mythik named params (`@name`); Mythik does not translate custom SQL between dialects.
-91. Event arrays may mix normal actions and transaction bindings. Mythik executes them sequentially and awaits each transaction before continuing. Use this when a flow needs a small action before or after an optimistic transaction; do not wrap a transaction inside another transaction phase.
-92. `$ref` and `$template` placeholders can read nested values from `$let` object bindings with dot notation, for example `{ "$ref": "user.name" }` or `${user.name}`. If a dotted `$ref` segment is missing, runtime throws an unknown `$ref` error rather than silently returning undefined.
-93. Use `params.skipIf` for a dispatch-time action guard when an action should be skipped but the surrounding action chain should continue. `skipIf` is resolved before other params and is removed before the action handler runs. Do not use `skipIf` as a substitute for form validation or transaction rollback.
+88. API query endpoints can combine `pagination: "offset"` with `scopeFilter`. For generated counts, Mythik applies the scope filter to the source query before `COUNT(*)`, so paginated totals remain tenant-scoped. Prefer generated counts. If a custom `endpoint.count` is truly needed with `scopeFilter`, include `{{scopeWhere[:alias]}}` or `{{scopeAnd[:alias]}}`; Mythik expands the macro to the correct scope predicate and removes it for bypass roles. Other custom count SQL is left verbatim. Use `:alias` for JOIN/subquery counts, and do not reference internal scope params directly.
+89. Transaction `confirm` failures from `fetch` preserve backend error details for `onError`. Read `/tx/error/message` for the best available message; when the backend returns `{ error: { code, message } }`, Mythik keeps that message, `code`, HTTP `status`, and raw `data` after rollback. Do not parse `/ui/lastError` from transaction specs.
+90. For SQL-backed stores and servers, use the generic `mythik/server` SQL boundary. Initialize tables with `mythik init-store --dialect <sqlserver|postgres|mysql|sqlite>` or inspect DDL with `--dry-run`; configure the CLI with `--store`, `--url`/`--filename`/SQL Server flags, or `MYTHIK_*` environment variables; and keep spec edits on the required `manifest -> elements -> patch --from-file -> validate` loop. Write custom API SQL in the selected dialect with Mythik named params (`@name`); Mythik does not translate custom SQL between dialects.
+91. Event arrays may mix normal actions and transaction bindings. Mythik executes them sequentially and awaits each transaction before continuing. Use this when a flow needs a small action before or after an optimistic transaction; do not wrap a transaction inside another transaction phase.
+92. `$ref` and `$template` placeholders can read nested values from `$let` object bindings with dot notation, for example `{ "$ref": "user.name" }` or `${user.name}`. If a dotted `$ref` segment is missing, runtime throws an unknown `$ref` error rather than silently returning undefined.
+93. Use `params.skipIf` for a dispatch-time action guard when an action should be skipped but the surrounding action chain should continue. `skipIf` is resolved before other params and is removed before the action handler runs. Do not use `skipIf` as a substitute for form validation or transaction rollback.
+94. For critical direct `fetch` actions, especially `initialActions` screen loads, set `params.errorTarget` to a screen-owned `/ui/...` path and render that path visibly. The fetch action still writes global `/ui/lastError`, but `/ui/lastError` is shared and can be overwritten by unrelated fetches. On success, Mythik clears the provided `errorTarget`.
+95. `select.options` accepts strings, `{ label, value }` objects, or catalog-shaped objects when `labelKey` and `valueKey` are provided. Example: `{ "options": { "$state": "/cat/services/data" }, "labelKey": "name", "valueKey": "id" }`. Values are emitted as strings from `on.change`; malformed option data renders disabled diagnostics instead of blank clickable rows or crashes.
+96. SQL adapters are optional peer dependencies, not installed-by-default runtime payload. Browser-only apps install `mythik mythik-react` without database drivers. SQL-backed stores/servers must install exactly one selected adapter: `mssql`, `pg`, `mysql2`, or `better-sqlite3`. SQLite uses native `better-sqlite3`; native-build helper warnings from that adapter are not Mythik runtime failures.
+97. Missing SQL adapter errors are actionable. The thrown `SqlDriverError` includes `packageName`, `installCommand`, and a message with the exact `npm install ...` command for the selected dialect.
+98. For native Expo apps, install renderer peer packages with `npx expo install react-native-svg react-native-reanimated react-native-worklets ...` before installing `mythik mythik-react-native`, so Expo selects native module versions that match the app SDK. Keep `react-native-reanimated/plugin` last in the app Babel config. Keep `root` as a stable string element id; use `$platform` only inside localized props, style, children, or values. `$platform` matches exact platform keys first, then falls back from `ios`/`android` to `native`; it has no `default` key. Before using a primitive in native specs, check `REACT_NATIVE_PRIMITIVE_SUPPORT` or `getReactNativePrimitiveSupport` from `mythik-react-native`; native-milestone primitives should fail visibly instead of being treated as supported.

package/docs/consumer/reference-doc.md

@@ -309,9 +309,9 @@ Nested conditionals for multi-branch logic:
 ```json
 { "$template": "Hello, ${/user/name}! You have ${/inbox/count} messages." }
 ```
-Interpolates values into a string. Supports two reference types:
-- State paths: `${/user/name}` — reads from application state
-- `$let` bindings: `${age}` or `${user.name}` — reads from a named binding defined with `$let`
+Interpolates values into a string. Supports two reference types:
+- State paths: `${/user/name}` — reads from application state
+- `$let` bindings: `${age}` or `${user.name}` — reads from a named binding defined with `$let`
 
 ### `$computed` — Registered function
 ```json
@@ -326,20 +326,20 @@ Calls a registered function with resolved arguments. **Prefer `$math`, `$array`,
   "$in": { "$ref": "bmi" }
 }
 ```
-Define a named value once, reference it multiple times. Avoids repetition.
-
-`$ref` can read nested values from an object binding with dot notation:
-```json
-{
-  "$let": { "user": { "$state": "/auth/user" } },
-  "$in": { "$ref": "user.name" }
-}
-```
-The same dotted binding lookup is available inside `$template` placeholders, for example `${user.name}`.
-
-**Later bindings can reference earlier ones:**
-```json
-{
+Define a named value once, reference it multiple times. Avoids repetition.
+
+`$ref` can read nested values from an object binding with dot notation:
+```json
+{
+  "$let": { "user": { "$state": "/auth/user" } },
+  "$in": { "$ref": "user.name" }
+}
+```
+The same dotted binding lookup is available inside `$template` placeholders, for example `${user.name}`.
+
+**Later bindings can reference earlier ones:**
+```json
+{
   "$let": {
     "total": { "$array": "count", "source": { "$state": "/items" } },
     "label": { "$template": "${total} items" }
@@ -386,6 +386,7 @@ Resolves to different values based on the current platform (`web`, `ios`, `andro
 { "$platform": { "web": "layout-web", "native": "layout-native" } }
 { "$platform": { "web": "hover-card", "ios": "ios-card", "android": "android-card" } }
 ```
+If no key matches, `$platform` resolves to `undefined`; it does not support a `default` key. Keep top-level `root` as a stable string element id and use `$platform` only in localized props, style, children, or values.
 
 **Use with `$breakpoint`** — `$breakpoint` handles responsive layout (viewport width), `$platform` handles platform-specific techniques (CSS vs native components). They are complementary, not alternatives.
 
@@ -862,9 +863,9 @@ Wire actions to events with the `on` property:
 }
 ```
 
-### Multiple Actions (Sequential)
-
-Actions in an array execute sequentially — each async action (like `fetch`) completes before the next one starts:
+### Multiple Actions (Sequential)
+
+Actions in an array execute sequentially — each async action (like `fetch`) completes before the next one starts:
 ```json
 {
   "on": {
@@ -931,6 +932,7 @@ The `fetch` action supports:
 - **Empty string sanitization:** Empty strings in body are automatically converted to `null` (prevents database errors for typed columns)
 - **Loading state:** Sets `/ui/loading` to true while in flight, false when done
 - **Error handling:** On failure, sets `/ui/lastError` with status and message
+- **Screen-owned errors:** Optional `errorTarget` receives the same structured error and is cleared on success; use it for critical `initialActions` loads
 
 ```json
 {
@@ -946,14 +948,14 @@ The `fetch` action supports:
     },
     "target": "/lastResult"
   }
-}
-```
-
-Action arrays may also mix normal action bindings and transaction bindings. Mythik runs each entry in order and waits for a transaction to finish before dispatching the next entry.
-
-Any action binding can include `params.skipIf`. Mythik resolves `skipIf` at dispatch time before the rest of the params; if it is truthy, that action is skipped and the surrounding action chain continues.
-
-### Transactions (Optimistic Updates)
+}
+```
+
+Action arrays may also mix normal action bindings and transaction bindings. Mythik runs each entry in order and waits for a transaction to finish before dispatching the next entry.
+
+Any action binding can include `params.skipIf`. Mythik resolves `skipIf` at dispatch time before the rest of the params; if it is truthy, that action is skipped and the surrounding action chain continues.
+
+### Transactions (Optimistic Updates)
 
 Use `transaction` for CRUD operations that need instant UI feedback. The framework takes a state snapshot, applies your changes instantly, then confirms with the server. On failure, it rolls back automatically.
 
@@ -2972,7 +2974,7 @@ Mythik backgrounds use a structured `LayerBackground` model. Apps declare `token
 
 178. **`BackgroundLayer` + `BackgroundStack` components shipped for web and RN** — Web: `packages/react/src/background/` using CSS for solid/gradient/image + inline SVG for pattern/grain. RN: `packages/react-native/src/background/` using `react-native-svg` `SvgXml` for all layers + View for solid + Image for image. Accepts `LayerBackground` config OR recipe string name
 
-179. **`custom-svg` sanitized escape hatch** — When built-in patterns aren't enough, consumers pass SVG shape fragments via `{ kind: 'custom-svg', shapes: '<circle.../>', tileSize: 20 }`. `sanitizeSVGShapes` uses regex pre-strip + DOMPurify allowlist. Only circle/rect/path/line/polygon/polyline/ellipse/g/defs/gradients + geometric attrs survive. Cross-platform safe (isomorphic-dompurify)
+179. **`custom-svg` sanitized escape hatch** — When built-in patterns aren't enough, consumers pass SVG shape fragments via `{ kind: 'custom-svg', shapes: '<circle.../>', tileSize: 20 }`. `sanitizeSVGShapes` uses a platform-safe regex pre-strip plus a strict SVG tag/attribute allowlist, without DOM-only sanitizer dependencies. Only circle/rect/path/line/polygon/polyline/ellipse/g/defs/gradients plus geometric attrs survive.
 
 ---
 
@@ -3056,7 +3058,7 @@ The current background and motion stack combines app-level `LayerBackground`, an
 
 211. **`useShapeAnimations(ref, animations, options)` — Layer 3 web runner** — Exported from `mythik-react` via `packages/react/src/animation/useShapeAnimations.ts`. React hook for SVG-child animations (`<path>`/`<circle>`/`<rect>`/`<g>`…). Consumes the same `ElementAnimations` contract as `useElementAnimations` but narrowed to the `ambient` trigger ONLY; shape children have no hover/focus/active contract and no distinct mount ceremony. Attaches CSS animations via `el.style.animation` (surgical, preserves other inline styles); keyframes register once through the CSSOM singleton (zero `dangerouslySetInnerHTML`) and dedupe by hash so multiple shape instances with the same recipe share one CSS rule. Dev mode warns when non-ambient triggers are passed. Production silently ignores them. `options.recipes` SHOULD be stable for useMemo performance.
 
-212. **`useShapeAnimations(animations, options)` — Layer 3 RN runner** — Repository-preview implementation in `packages/react-native/src/animation/useShapeAnimations.ts`; it is not part of the supported npm publish surface yet. Reanimated parity of rule 211: returns `{ animatedProps }` that the consumer spreads onto `Animated.createAnimatedComponent(Path)` from `react-native-svg`. Uses the `HARD_PER_TRIGGER` (=6) fixed-pool `useSharedValue` pattern (`useSharedValueArray` helper, also exported) so React Hook count stays stable. Reuses `composeRNStyle(contributions, interpolate, interpolateColor)` shared with `useElementAnimations` — single composition pipeline for View-style and animated SVG props. Relies on `react-native-svg` v13+ auto-translating the transform array into SVG `transform="..."` strings. Same dev-mode non-ambient-trigger warning as the web hook.
+212. **`useShapeAnimations(animations, options)` — Layer 3 RN runner** — Published through `mythik-react-native` from `packages/react-native/src/animation/useShapeAnimations.ts`. Reanimated parity of rule 211: returns `{ animatedProps }` that the consumer spreads onto `Animated.createAnimatedComponent(Path)` from `react-native-svg`. Uses the `HARD_PER_TRIGGER` (=6) fixed-pool `useSharedValue` pattern (`useSharedValueArray` helper, also exported) so React Hook count stays stable. Reuses `composeRNStyle(contributions, interpolate, interpolateColor)` shared with `useElementAnimations` — single composition pipeline for View-style and animated SVG props. Relies on `react-native-svg` v13+ auto-translating the transform array into SVG `transform="..."` strings. Same dev-mode non-ambient-trigger warning as the web hook.
 
 213. **Cross-platform Layer 3 parity pins** — `buildCSSKeyframes` (web) and `buildReanimatedSpec` (RN) interpret the same resolved `AnimationSpec` identically on load-bearing invariants: duration agreement (ms count matches regardless of input form `'28s'`/`'28000'`), keyframe stop count (web `%` markers match RN `inputRange` length), direction semantic (`'alternate'` token ⇔ `timing.reverse=true`), iterations `'infinite'`/numeric count, animated-prop enumeration (`translateX/Y`/`rotateDeg`/`scale`).
 
@@ -3215,9 +3217,14 @@ See `ai-context.md` for spec-gen anti-patterns the AI must NOT generate.
 282. **Existing spec edits must use the CLI inspection-then-patch loop** - For an existing screen/app/api spec, AI agents should run `mythik manifest <id>` first, inspect only the target nodes with `mythik elements <id> <ids>`, apply a small RFC 6902 patch with `mythik patch <id> --from-file patch.json`, and verify with `manifest` or `elements`. This keeps edits surgical, validated, versionable, and reviewable. `pull` is for backup, migration, review, or full-document work; `push` is for new specs or intentional full replacement. Direct database edits and direct `SpecStore.save()` calls bypass validation and are not approved spec-write paths.
 283. **Bundled AI docs are part of the install surface** - The `mythik` package includes `docs/llms.txt`, `docs/consumer/*`, and `docs/wiki/compiled/*`. Agents should run `mythik docs path` before spec generation and read the bundled docs rather than guessing from package source. Use `mythik docs copy ./mythik-docs` to create a project-local copy when the host workflow needs explicit files.
 284. **DNA numeric seeds are canonical `0–1`, with legacy `0–100` normalization** - Generate `tokens.dna.roundness`, `density`, `depth`, and `formality` as `0–1` numbers (`0.7`, not `70`). The runtime normalizes numeric seed values greater than `1` by dividing by `100` inside DNA derivation, so initial AppSpec load and runtime `updateTokens` share the same backward-compatible behavior.
-285. **Scoped pagination counts filter before aggregation** - Query endpoints may combine `pagination: "offset"` with `scopeFilter`. For generated counts, the server applies the scope filter to the query source first and then counts the scoped source, so the response `total` matches the same tenant/role slice as `data`. Prefer generated counts. If custom `endpoint.count` is truly needed with `scopeFilter`, it must include `{{scopeWhere[:alias]}}` or `{{scopeAnd[:alias]}}`; Mythik expands the macro to the correct scope predicate and removes it for bypass roles. Other custom count SQL is left verbatim. Specs should use `:alias` for JOIN/subquery counts and should not reference internal scope parameter names directly.
-286. **Transaction fetch failures preserve backend error details** - When a transaction `confirm` uses `fetch` and the backend returns an HTTP error payload such as `{ error: { code, message } }`, `/tx/error` is written after rollback with the best backend message plus `code`, HTTP `status`, and raw `data`. `onError` should read `/tx/error/message`; transaction specs should not read global `/ui/lastError`.
-287. **SQL-backed stores and servers use one dialect-aware `mythik/server` boundary** - Import `createSqlDriver`, `SqlSpecStore`, `SqlVersionedSpecStore`, `SqlEnvironmentStore`, and `getSqlStoreDdl` from `mythik/server` for Node-side SQL work. Supported dialects are `sqlserver`, `postgres`, `mysql`, and `sqlite`. Initialize store tables with `mythik init-store --dialect <dialect>` for reachable SQL stores, `--target` for SQLite, or `--dry-run` for review/apply through a deployment process. SQL Server `init-store` accepts explicit `--server`, `--database`, `--user`, `--password`, `--encrypt`, and `--trust-server-certificate` flags. CLI commands share the same store flags/env vars and must keep existing-spec edits on the `manifest -> elements -> patch --from-file -> validate` loop. ApiSpec `dialect` controls generated CRUD/catalog/pagination/scope SQL; custom SQL remains dialect-native with Mythik named params (`@name`) and is not translated between dialects.
-288. **Event arrays may mix actions and transactions** - Event bindings can be a single action, a single transaction, or an array containing both normal action bindings and transaction bindings. Mythik executes the array sequentially and awaits each transaction before continuing. Transaction phases cannot contain nested transactions.
-289. **`$let` dotted references read nested binding values** - A `$ref` may target an object binding path such as `{ "$ref": "user.name" }`, and `$template` placeholders may read the same path as `${user.name}`. Use this for object values produced by `$let`; missing dotted `$ref` segments are invalid references and should be fixed instead of treated as optional data.
-290. **`params.skipIf` is a dispatch-time action guard** - Any action binding may include `params.skipIf`. Mythik resolves it before resolving the rest of the params; when truthy, the action is skipped and the action chain continues. The action handler never receives `skipIf`.
+285. **Scoped pagination counts filter before aggregation** - Query endpoints may combine `pagination: "offset"` with `scopeFilter`. For generated counts, the server applies the scope filter to the query source first and then counts the scoped source, so the response `total` matches the same tenant/role slice as `data`. Prefer generated counts. If custom `endpoint.count` is truly needed with `scopeFilter`, it must include `{{scopeWhere[:alias]}}` or `{{scopeAnd[:alias]}}`; Mythik expands the macro to the correct scope predicate and removes it for bypass roles. Other custom count SQL is left verbatim. Specs should use `:alias` for JOIN/subquery counts and should not reference internal scope parameter names directly.
+286. **Transaction fetch failures preserve backend error details** - When a transaction `confirm` uses `fetch` and the backend returns an HTTP error payload such as `{ error: { code, message } }`, `/tx/error` is written after rollback with the best backend message plus `code`, HTTP `status`, and raw `data`. `onError` should read `/tx/error/message`; transaction specs should not read global `/ui/lastError`.
+287. **SQL-backed stores and servers use one dialect-aware `mythik/server` boundary** - Import `createSqlDriver`, `SqlSpecStore`, `SqlVersionedSpecStore`, `SqlEnvironmentStore`, and `getSqlStoreDdl` from `mythik/server` for Node-side SQL work. Supported dialects are `sqlserver`, `postgres`, `mysql`, and `sqlite`. Initialize store tables with `mythik init-store --dialect <dialect>` for reachable SQL stores, `--target` for SQLite, or `--dry-run` for review/apply through a deployment process. SQL Server `init-store` accepts explicit `--server`, `--database`, `--user`, `--password`, `--encrypt`, and `--trust-server-certificate` flags. CLI commands share the same store flags/env vars and must keep existing-spec edits on the `manifest -> elements -> patch --from-file -> validate` loop. ApiSpec `dialect` controls generated CRUD/catalog/pagination/scope SQL; custom SQL remains dialect-native with Mythik named params (`@name`) and is not translated between dialects.
+288. **Event arrays may mix actions and transactions** - Event bindings can be a single action, a single transaction, or an array containing both normal action bindings and transaction bindings. Mythik executes the array sequentially and awaits each transaction before continuing. Transaction phases cannot contain nested transactions.
+289. **`$let` dotted references read nested binding values** - A `$ref` may target an object binding path such as `{ "$ref": "user.name" }`, and `$template` placeholders may read the same path as `${user.name}`. Use this for object values produced by `$let`; missing dotted `$ref` segments are invalid references and should be fixed instead of treated as optional data.
+290. **`params.skipIf` is a dispatch-time action guard** - Any action binding may include `params.skipIf`. Mythik resolves it before resolving the rest of the params; when truthy, the action is skipped and the action chain continues. The action handler never receives `skipIf`.
+291. **Direct `fetch` supports `errorTarget` for visible screen-load failures** - `fetch.params.errorTarget` writes HTTP/network errors to a consumer-owned state path and clears it on success. Use it for critical `initialActions` loads so the screen can render a local banner/empty state; `/ui/lastError` remains global compatibility state and can be overwritten by unrelated fetches.
+292. **`select` supports catalog keys and invalid-option diagnostics** - `select.options` may be strings, `{ label, value }`, or catalog-shaped objects when `labelKey`/`valueKey` are provided. Values emitted from the primitive are strings. Malformed option data renders as disabled diagnostics instead of blank clickable options or crashes, so AI-generated catalog bindings fail visibly.
+293. **SQL adapters are optional peer dependencies** - `mythik` does not install SQL drivers by default. Browser-only apps install `mythik mythik-react`. SQL-backed stores/servers must install exactly the selected adapter (`mssql`, `pg`, `mysql2`, or `better-sqlite3`). SQLite uses native `better-sqlite3`; warnings from its transitive native-build helpers are adapter-level install warnings, not Mythik runtime failures.
+294. **Missing SQL adapter errors are actionable** - If a SQL-backed store or server uses a dialect whose adapter package is not installed, Mythik throws `SqlDriverError` with `code: "SQL_DRIVER_DEPENDENCY_MISSING"`, `packageName`, `installCommand`, and a message containing the exact `npm install ...` command.
+295. **`mythik-react-native` publishes an explicit native support contract** - Expo apps should install React Native/Expo peer packages with `npx expo install ...`, including `react-native-reanimated` and its Expo-matched `react-native-worklets` peer, before installing `mythik mythik-react-native`, so Expo selects native module versions that match the app SDK. Keep `react-native-reanimated/plugin` last in the app Babel config. The package exports `REACT_NATIVE_PRIMITIVE_SUPPORT` and `getReactNativePrimitiveSupport(name)`. Supported native primitives are `box`, `stack`, `grid`, `scroll`, `divider`, `spacer`, `text`, `image`, `icon`, `input`, `textarea`, `select`, `checkbox`, `toggle`, `slider`, `button`, `touchable`, `list`, `modal`, `drawer`, `tabs`, `accordion`, `wizard`, `screen`, `screen-outlet`, `toast-container`, and `skeleton`. Native-milestone primitives are `bar-chart`, `line-chart`, `pie-chart`, `area-chart`, `table`, `kanban-board`, `spatial-map`, `file-upload`, `camera`, `signature`, and `audio-player`; they should surface diagnostics instead of silently rendering broken UI. Keep `root` as a stable string and use `$platform` only in localized props/style/children/value branches.

package/docs/wiki/compiled/README.md

@@ -12,12 +12,12 @@ Compiled from `docs/consumer/` into **327 atomic articles**. The wiki is optimiz
 6. [cli-existing-spec-edit-loop](cli-existing-spec-edit-loop.md) - required loop for modifying existing persisted specs.
 7. [cli-docs](cli-docs.md) - locate or copy the bundled AI documentation after `npm install`.
 
-## Publish notes
-
-- Public package names are unscoped: `mythik`, `mythik-react`, `mythik-cli`, `mythik-server`.
-- React Native work is a repository preview track, not part of the supported npm publish surface yet.
-- The wiki metadata folder is not publish content.
-- `docs/consumer` remains the canonical source.
+## Publish notes
+
+- Public package names are unscoped: `mythik`, `mythik-react`, `mythik-cli`, `mythik-server`, `mythik-react-native`.
+- `mythik-react-native` is a public preview release line with an explicit support matrix.
+- The wiki metadata folder is not publish content.
+- `docs/consumer` remains the canonical source.
 
 ## Catalog
 

package/docs/wiki/compiled/action-fetch.md

@@ -20,7 +20,8 @@ transactions, `GET` in `initialActions`). For reactive GETs, prefer
   "method"?: "GET" | "POST" | "PUT" | "PATCH" | "DELETE",
   "headers"?: <object-or-$state>,
   "body"?: <object-with-expressions>,
-  "target"?: "/state/path"
+  "target"?: "/state/path",
+  "errorTarget"?: "/ui/screen-owned-error-path"
 }}
 ```
 
@@ -30,6 +31,9 @@ transactions, `GET` in `initialActions`). For reactive GETs, prefer
 - **Empty strings in body → `null`** (prevents DB errors on typed columns).
 - Sets `/ui/loading` to `true` while in flight; `false` when done.
 - On error: writes `/ui/lastError` with status and message.
+- If `errorTarget` is provided, writes the same structured error there and
+  clears it on success. Use this for critical `initialActions` screen loads
+  instead of relying only on global `/ui/lastError`.
 - **Auth headers auto-injected** for URLs whose hostname matches
   `auth.authDomains` — see [[@concept-auth-domains]].
 
@@ -50,7 +54,8 @@ POST with body:
     "title": { "$state": "/form/title" },
     "description": { "$state": "/form/description" }
   },
-  "target": "/lastResult"
+  "target": "/lastResult",
+  "errorTarget": "/ui/loadErrors/taskCreate"
 }}
 ```
 

package/docs/wiki/compiled/concept-background-layer-kinds.md

@@ -62,7 +62,7 @@ desaturated grain).
 { "kind": "custom-svg", "shapes": "<circle.../>", "tileSize": 20 }
 ```
 
-`sanitizeSVGShapes` uses regex pre-strip + DOMPurify allowlist. Only
+`sanitizeSVGShapes` uses platform-safe regex pre-strip plus a strict SVG tag and attribute allowlist. Only
 circle/rect/path/line/polygon/polyline/ellipse/g/defs/gradients +
 geometric attrs survive. Rejects `<script>`, `<foreignObject>`,
 `<use href>`, `on*` events, `javascript:` URLs.

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

@@ -11,20 +11,20 @@ sources: [docs/consumer/ai-context.md, docs/consumer/WHERE-TO-LOOK.md]
 
 | Package | Purpose |
 |---|---|
-| `mythik` | Browser-safe core. State, expressions, validation, renderer engine, design, auth, data, security, and browser-safe spec stores |
-| `mythik/server` | Node-only spec stores, SQL drivers, and SQL DDL helpers: `FileSpecStore`, `SqlSpecStore`, `SqlVersionedSpecStore`, `SqlEnvironmentStore`, `createSqlDriver`, `getSqlStoreDdl`, and SQL Server compatibility stores |
-| `mythik-react` | React host, renderer, and web primitives |
-| `mythik-cli` | CLI package; installs the `mythik` command |
-| `mythik-cli/api` | Programmatic CLI API: `runPush`, `runPatch`, `runLint`, `parsePatchInput`, and types |
-| `mythik-server` | Express server runtime for ApiSpecs |
-
-React Native work lives in the repository as a preview track and is not part of the supported npm publish surface yet.
+| `mythik` | Browser-safe core. State, expressions, validation, renderer engine, design, auth, data, security, and browser-safe spec stores |
+| `mythik/server` | Node-only spec stores, SQL drivers, and SQL DDL helpers: `FileSpecStore`, `SqlSpecStore`, `SqlVersionedSpecStore`, `SqlEnvironmentStore`, `createSqlDriver`, `getSqlStoreDdl`, and SQL Server compatibility stores |
+| `mythik-react` | React host, renderer, and web primitives |
+| `mythik-cli` | CLI package; installs the `mythik` command |
+| `mythik-cli/api` | Programmatic CLI API: `runPush`, `runPatch`, `runLint`, `parsePatchInput`, and types |
+| `mythik-server` | Express server runtime for ApiSpecs |
+
+React Native work lives in the repository as a preview track and is not part of the supported npm publish surface yet.
 
 ## Browser vs server core entries
 
-The default `mythik` entry is browser-safe by construction. Node-only stores and SQL drivers live behind the `mythik/server` subpath so browser bundles do not pull `fs`, SQL adapters, or other Node-only dependencies.
-
-SQL adapters (`mssql`, `pg`, `mysql2`, `better-sqlite3`) are optional dependencies of `mythik`. npm/pnpm install optional dependencies by default; if optional dependencies are omitted, install the adapter for the database in use.
+The default `mythik` entry is browser-safe by construction. Node-only stores and SQL drivers live behind the `mythik/server` subpath so browser bundles do not pull `fs`, SQL adapters, or other Node-only dependencies.
+
+SQL adapters (`mssql`, `pg`, `mysql2`, `better-sqlite3`) are optional peer dependencies. Browser-only apps do not install database drivers by default; SQL-backed stores and servers must install exactly the adapter for the selected database. SQLite uses native `better-sqlite3`, so warnings from its transitive native-build helpers belong to that adapter install path. Missing SQL adapter errors include the package name and exact install command.
 
 ## Programmatic CLI API
 

package/docs/wiki/compiled/concept-pattern-primitives.md

@@ -30,13 +30,13 @@ sources: [docs/consumer/reference-doc.md#rules-174-179]
 { "kind": "custom-svg", "shapes": "<circle cx=\"5\" cy=\"5\" r=\"2\"/>", "tileSize": 10 }
 ```
 
-`sanitizeSVGShapes` uses regex pre-strip + DOMPurify allowlist:
+`sanitizeSVGShapes` uses platform-safe regex pre-strip plus a strict SVG tag and attribute allowlist:
 - **Allowed**: circle, rect, path, line, polygon, polyline, ellipse,
   g, defs, gradients + geometric attrs.
 - **Rejected**: `<script>`, `<foreignObject>`, `<use href>`, `on*` events,
   `javascript:` URLs.
 
-Cross-platform safe (isomorphic-dompurify).
+Cross-platform safe without DOM-only sanitizer dependencies.
 
 ## Example
 

package/docs/wiki/compiled/concept-public-package-names.md

@@ -7,29 +7,38 @@ sources: [docs/consumer/ai-context.md, docs/consumer/WHERE-TO-LOOK.md]
 
 # Public package names
 
-Mythik publishes unscoped npm packages. Do not generate scoped package imports for public npm consumers.
+Mythik publishes unscoped npm packages. Do not generate scoped package imports for public npm consumers.
 
 | Public package | Use |
 |---|---|
 | `mythik` | Browser-safe core runtime, state, expressions, validation, browser-safe stores |
-| `mythik/server` | Node-only stores, SQL drivers, and SQL DDL helpers exported from the core package subpath |
-| `mythik-react` | React host, renderer, and web primitives |
-| `mythik-cli` | CLI package; installs the `mythik` binary |
-| `mythik-cli/api` | Programmatic CLI API: `runPush`, `runPatch`, `runLint`, and related types |
-| `mythik-server` | Express server runtime for ApiSpecs |
-
-The `mythik` package also ships the AI documentation under `node_modules/mythik/docs`.
-Use [[@cli-docs]] to locate or copy it after install.
-
-Typical React install:
+| `mythik/server` | Node-only stores, SQL drivers, and SQL DDL helpers exported from the core package subpath |
+| `mythik-react` | React host, renderer, and web primitives |
+| `mythik-cli` | CLI package; installs the `mythik` binary |
+| `mythik-cli/api` | Programmatic CLI API: `runPush`, `runPatch`, `runLint`, and related types |
+| `mythik-server` | Express server runtime for ApiSpecs |
+
+The `mythik` package also ships the AI documentation under `node_modules/mythik/docs`.
+Use [[@cli-docs]] to locate or copy it after install.
+
+Typical React install:
 
 ```bash
 npm install mythik mythik-react
 npm install -D mythik-cli
 ```
 
-Add `mythik-server` only when building a Mythik-backed Node server. React Native work is a repository preview track, not part of the supported npm publish surface yet.
-
-SQL adapters (`mssql`, `pg`, `mysql2`, `better-sqlite3`) are optional dependencies of `mythik`. They install by default with npm/pnpm unless optional dependencies are omitted.
+Add `mythik-server` only when building a Mythik-backed Node server. React Native work is a repository preview track, not part of the supported npm publish surface yet.
+
+SQL adapters (`mssql`, `pg`, `mysql2`, `better-sqlite3`) are optional peer dependencies. Install only the selected database adapter:
+
+```bash
+npm install pg              # PostgreSQL
+npm install mysql2          # MySQL
+npm install mssql           # SQL Server
+npm install better-sqlite3  # SQLite
+```
+
+SQLite uses native `better-sqlite3`; warnings from its transitive native-build helpers are adapter-level install warnings, not Mythik runtime failures. Missing SQL adapter errors include the package name and exact install command for the selected dialect.
 
-Related: [[@cli-docs]], [[@cli-programmatic-api]], [[@concept-spec-stores-catalog]], [[@concept-where-to-look]].
+Related: [[@cli-docs]], [[@cli-programmatic-api]], [[@concept-spec-stores-catalog]], [[@concept-where-to-look]].

package/docs/wiki/compiled/expression-platform.md

@@ -25,13 +25,21 @@ Platform-specific styling:
 "style": { "backdropFilter": { "$platform": { "web": "blur(24px)", "native": null } } }
 ```
 
-Different layouts per platform (root-level):
+Localized platform-specific presentation:
 ```json
 {
-  "root": { "$platform": { "web": "layout-web", "native": "layout-native" } },
+  "root": "layout",
   "elements": {
-    "layout-web": { "type": "stack", "style": { "backdropFilter": "blur(24px)" } },
-    "layout-native": { "type": "screen", "props": { "title": "Dashboard" } },
+    "layout": {
+      "type": "stack",
+      "props": {
+        "direction": { "$platform": { "web": "horizontal", "native": "vertical" } }
+      },
+      "style": {
+        "backdropFilter": { "$platform": { "web": "blur(24px)", "native": null } }
+      },
+      "children": ["shared-form"]
+    },
     "shared-form": { "type": "stack", "children": ["..."] }
   }
 }
@@ -53,8 +61,8 @@ Platform-specific overrides for ios:
 
 - **If no key matches, resolves to `undefined`.** Always provide keys for
   all target platforms (or include `native` as fallback).
-- Root-level `$platform` enables platform-divergent layouts while
-  state/initialActions/forms remain shared — only presentation branches.
+- Keep top-level `root` as a stable string element id. Do not put `$platform`
+  directly in `root`; branch at localized props, styles, children, or values.
 
 ## Related concepts
 

package/docs/wiki/compiled/path-ui-loading-error.md

@@ -16,6 +16,11 @@ Auto-managed by `fetch` action.
 | `/ui/loading` | boolean | Set `true` at request start, `false` at resolve. **Shared across all fetch actions.** |
 | `/ui/lastError` | object | Error message on failure; cleared on next successful fetch. |
 
+`/ui/lastError` is global compatibility state. For critical screen loads,
+set `fetch.params.errorTarget` to a screen-owned `/ui/...` path and render
+that path visibly; `fetch` writes the same structured error there and clears
+it on success.
+
 ## Use in visibility
 
 ```json

package/docs/wiki/compiled/pattern-fetch-vs-datasources.md

@@ -19,6 +19,11 @@ Both load data into state. Pick **one pattern per data target**.
 | **Re-fetch** | Manual (call fetch again) | Automatic on param change, or `refreshDataSource` |
 | **Use for** | Static initial data, POST/PUT/DELETE | Lists with filters, search, pagination |
 
+For critical `initialActions + fetch` screen loads, set `errorTarget` to a
+screen-owned path (for example `/ui/loadErrors/orderForm`) and render that
+path visibly. `/ui/lastError` is shared global state and can be overwritten
+by unrelated fetches.
+
 ## Rule
 
 **Don't mix both for the same data target.** They write to different

package/docs/wiki/compiled/pattern-loading-content-empty.md

@@ -12,7 +12,8 @@ state paths differ between `initialActions + fetch` vs `dataSources`.
 
 ## With `initialActions + fetch`
 
-Uses `/ui/loading` and `/ui/lastError`:
+Uses `/ui/loading`; critical loads should set `errorTarget` and render the
+screen-owned error path:
 
 ```json
 "loading": { "visible": { "$and": [
@@ -24,7 +25,7 @@ Uses `/ui/loading` and `/ui/lastError`:
   { "$not": { "$state": "/ui/loading" } },
   { "$not": { "$array": "count", "source": { "$state": "/items" } } }
 ]}},
-"error":   { "visible": { "$state": "/ui/lastError" } }
+"error":   { "visible": { "$state": "/ui/loadErrors/items" } }
 ```
 
 ## With `dataSources`

package/docs/wiki/compiled/primitive-screen.md

@@ -22,12 +22,18 @@ chrome (title bar, navigation integration).
 { "type": "screen", "props": { "title": "Dashboard" }, "children": [...] }
 ```
 
-Used as a platform-specific root:
+Used from a stable root:
 ```json
 {
-  "root": { "$platform": { "web": "layout-web", "native": "layout-native" } },
+  "root": "layout",
   "elements": {
-    "layout-native": { "type": "screen", "props": { "title": "Dashboard" }, "children": [...] }
+    "layout": {
+      "type": "screen",
+      "props": {
+        "title": { "$platform": { "web": "Dashboard", "native": "Mobile dashboard" } }
+      },
+      "children": [...]
+    }
   }
 }
 ```