mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/path-tokens.md

@@ -0,0 +1,56 @@
+---
+id: path-tokens
+title: `/tokens/raw` and `/tokens/resolved`
+kind: concept
+sources: [docs/consumer/reference-doc.md#rules-158-224]
+---
+
+# `/tokens/raw` and `/tokens/resolved`
+
+Two state paths that hold token state. Useful for export, debugging,
+preset re-resolution.
+
+## Paths
+
+| Path | Content |
+|---|---|
+| `/tokens/raw` | Accumulated raw input from `updateTokens` (pre-normalization). Useful for exporting current DNA+Identity config |
+| `/tokens/resolved` | Fully-resolved token tree (DNA-derived colors, DEFAULT-merged identity, everything downstream consumers need) |
+
+## When written
+
+- `/tokens/raw` — after every `updateTokens` call (rule 158).
+- `/tokens/resolved` — at `createMythik` initialization AND after every
+  `updateTokens` call (rule 224).
+
+## Why both
+
+`MythikRenderer`'s v2 `LayerBackground` root mount reads from
+`/tokens/resolved` so preset swaps + playground control changes (dropdown
+writes via `$bindState` + onChange `updateTokens`) trigger fresh reads
+and remount the `BackgroundStack` with the new layers. Avoids the trap
+where reading static `spec.tokens` froze the renderer at initial values
+(rule 224).
+
+## Read patterns
+
+Export current tokens:
+```json
+{ "action": "copyToClipboard", "params": { "value": { "$state": "/tokens/raw" } } }
+```
+
+Read resolved value (rare in specs — `$token` typically suffices):
+```json
+{ "$state": "/tokens/resolved/colors/primary" }
+```
+
+## Related concepts
+
+- [[@action-update-tokens]]
+- [[@concept-token-system]]
+- [[@concept-mythik-renderer]]
+- [[@concept-layer-background]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rules 158, 224`

package/docs/wiki/compiled/path-tx-result-error.md

@@ -0,0 +1,56 @@
+---
+id: path-tx-result-error
+title: `/tx/result` and `/tx/error` — transaction state
+kind: concept
+sources: [docs/consumer/ai-context.md#transactions-optimistic-updates]
+---
+
+# `/tx/result` and `/tx/error`
+
+Auto-managed transaction state for accessing `confirm` results and error
+messages.
+
+## Paths
+
+| Path | Content |
+|---|---|
+| `/tx/result` | Server response when `confirm` writes via `target: "/tx/result"`. Read in `onSuccess` |
+| `/tx/error` | `{ message }` on transaction error. Read in `onError` |
+
+Both are cleaned up automatically after the transaction completes.
+
+## Use
+
+In `confirm` phase, write to `/tx/result`:
+```json
+"confirm": [{ "action": "fetch", "params": {
+  "method": "POST", "url": "/api/items",
+  "body": {...},
+  "target": "/tx/result"
+}}]
+```
+
+In `onSuccess`, read it:
+```json
+"onSuccess": [{ "action": "showNotification", "params": {
+  "message": { "$template": "Created item ${ /tx/result/id }" }
+}}]
+```
+
+In `onError`:
+```json
+"onError": [{ "action": "showNotification", "params": {
+  "type": "error",
+  "message": { "$state": "/tx/error/message" }
+}}]
+```
+
+## Related concepts
+
+- [[@concept-transactions]]
+- [[@concept-transaction-phase-timing]]
+- [[@action-fetch]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Transactions (Optimistic Updates) → Confirm result access`

package/docs/wiki/compiled/path-ui-device.md

@@ -0,0 +1,53 @@
+---
+id: path-ui-device
+title: `/ui/device/*` — auto-tracked device context
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#22-uidevice]
+---
+
+# `/ui/device/*`
+
+Framework auto-tracks device context — viewport, platform, orientation,
+OS color scheme. Updated in real-time.
+
+## Paths
+
+| Path | Type | Updated on |
+|---|---|---|
+| `/ui/device/viewportWidth` | number | Resize |
+| `/ui/device/viewportHeight` | number | Resize |
+| `/ui/device/platform` | `"web"` / `"ios"` / `"android"` | Mount |
+| `/ui/device/orientation` | `"portrait"` / `"landscape"` | Orientation change |
+| `/ui/device/colorScheme` | `"light"` / `"dark"` | OS preference change |
+
+## Read patterns
+
+**Prefer `$breakpoint` and `$platform`** for typical use — they abstract
+over the paths and handle defaults. Use direct `$state` reads for
+detection beyond what the expressions cover (orientation, OS scheme).
+
+```json
+{ "$breakpoint": { "sm": 1, "md": 2, "lg": 3 } }                         // viewport
+{ "$platform": { "web": "blur(24px)", "native": null } }                  // platform
+{ "$cond": { "$state": "/ui/device/orientation", "eq": "portrait" }, "$then": "vertical", "$else": "horizontal" }
+```
+
+## Opt-out
+
+`autoDeviceContext={false}` on `MythikRenderer` disables auto-tracking
+(host app must populate manually).
+
+## Legacy compat
+
+`$breakpoint` reads `/ui/device/viewportWidth` first, falls back to
+`/ui/viewportWidth` for existing apps that wrote there manually.
+
+## Related concepts
+
+- [[@expression-breakpoint]]
+- [[@expression-platform]]
+- [[@concept-state-protection]] — framework-managed paths
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 2.2`

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

@@ -0,0 +1,40 @@
+---
+id: path-ui-loading-error
+title: `/ui/loading` and `/ui/lastError`
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#24-uiloading-uilasterror-and-datasources-loadingerror-paths]
+---
+
+# `/ui/loading` and `/ui/lastError`
+
+Auto-managed by `fetch` action.
+
+## Paths
+
+| Path | Type | Behavior |
+|---|---|---|
+| `/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. |
+
+## Use in visibility
+
+```json
+"loading": { "visible": { "$state": "/ui/loading" } }
+"error":   { "visible": { "$state": "/ui/lastError" } }
+```
+
+## Fine-grained tracking
+
+For per-target loading state, use `dataSources` (which writes
+`/{target}Loading` / `/{target}Error`) — see [[@path-data-source-paths]].
+Or use per-target writes in your own action chains.
+
+## Related concepts
+
+- [[@action-fetch]]
+- [[@path-data-source-paths]]
+- [[@pattern-loading-content-empty]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 2.4`

package/docs/wiki/compiled/path-ui-modals-drawers.md

@@ -0,0 +1,46 @@
+---
+id: path-ui-modals-drawers
+title: `/ui/modals/{id}` and `/ui/drawers/{id}`
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#23-uimodalsid-and-uidrawersid]
+---
+
+# `/ui/modals/{id}` and `/ui/drawers/{id}`
+
+Framework-managed visibility paths for modals and drawers.
+
+## Behavior
+
+- `openModal` writes `true` to `/ui/modals/<id>`.
+- `closeModal` writes `false`.
+- Same pattern for drawers at `/ui/drawers/<id>`.
+- The renderer reads these paths to determine visibility.
+
+## Consumer contract
+
+**Do NOT set `visible` on `modal` or `drawer` elements** — engine manages
+visibility automatically. See [[@antipattern-modal-drawer-visible]].
+
+## Examples
+
+Open a modal:
+```json
+{ "action": "openModal", "params": { "id": "edit-modal" } }
+```
+
+Read modal state (typically not needed — the engine reads it):
+```json
+{ "$state": "/ui/modals/edit-modal" }
+```
+
+## Related concepts
+
+- [[@primitive-modal]]
+- [[@primitive-drawer]]
+- [[@action-modal]]
+- [[@action-drawer]]
+- [[@antipattern-modal-drawer-visible]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 2.3`

package/docs/wiki/compiled/path-ui-selected-row.md

@@ -0,0 +1,92 @@
+---
+id: path-ui-selected-row
+title: `/ui/selectedRow` — table row magic path
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#21-uiselectedrow--blocker-1]
+---
+
+# `/ui/selectedRow` — magic path
+
+Framework writes the clicked row's data to `/ui/selectedRow`
+**immediately before** dispatching table row interactions: column actions
+and direct `onRowClick` ActionBinding(s). Read it from downstream elements
+(modal content, detail panels), action params, or subsequent actions in the
+same chain.
+
+## Write owner
+
+`packages/react/src/runtime/row-dispatcher.ts` owns the row-write-then-dispatch
+contract. `MythikRenderer` uses this helper for table column actions and
+`onRowClick` ActionBinding(s):
+
+```ts
+export function createRowDispatcher(store, dispatchAction, rowPath = RESERVED_PATHS.SELECTED_ROW) {
+  return (binding, row) => {
+    if (row) store.set(rowPath, row);
+    if (!binding) return;
+    if (Array.isArray(binding)) {
+      for (const b of binding) dispatchAction(b);
+    } else {
+      dispatchAction(binding);
+    }
+  };
+};
+```
+
+## Lifetime
+
+Persists until the next row interaction dispatch. **No auto-clear** on
+modal close, screen navigate, or tab switch. A stale `/ui/selectedRow`
+from a previous click is normal state.
+
+## Scope
+
+Singleton per screen. Two tables on the same screen share the path —
+the most recently clicked row wins. Framework does not namespace per-table.
+
+## Read patterns
+
+In a downstream modal content:
+```json
+{ "type": "text", "props": { "content": { "$template": "Editing: ${ /ui/selectedRow/name }" } } }
+```
+
+In the action's own params or a subsequent action's params:
+```json
+{ "action": "fetch", "params": {
+  "url": { "$template": "/api/items/${ /ui/selectedRow/id }" }
+}}
+```
+
+In column-action params (resolves at press time via `lazyActionPaths`):
+```json
+"onPress": [{
+  "action": "openModal",
+  "params": { "id": "edit-modal", "itemId": { "$state": "/ui/selectedRow/id" } }
+}]
+```
+
+In `onRowClick` params (same lazy contract):
+```json
+"onRowClick": [{
+  "action": "openDrawer",
+  "params": { "id": "detail", "itemId": { "$state": "/ui/selectedRow/id" } }
+}]
+```
+
+## Constraints / Anti-patterns
+
+- **`$row` does NOT exist.** See [[@antipattern-row-literal]].
+- **Multi-table caveat**: if two tables on one screen, both write here —
+  last write wins. No per-table isolation today.
+
+## Related concepts
+
+- [[@concept-expression-timing]] § 1.3 — column actions lazy
+- [[@primitive-table]]
+- [[@pattern-cross-screen-data-flow]]
+- [[@antipattern-row-literal]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 2.1` + § 5.1

package/docs/wiki/compiled/path-uploads.md

@@ -0,0 +1,32 @@
+---
+id: path-uploads
+title: `/ui/uploads/*` — internal upload state
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#27-upload-state-paths]
+---
+
+# `/ui/uploads/*`
+
+Per-upload state paths reserved for upload lifecycle (active upload ID,
+progress, error, result). **Internal — don't read directly from specs.**
+
+## Internal shape (informational)
+
+For an upload element with id `<elementId>`:
+- `/ui/uploads/{elementId}/files` — `[{ name, size, type, progress, status, previewUrl, error }]`
+
+## Why not read directly
+
+The primitive reads `/ui/uploads/*` automatically. The spec author should
+read the **`target` path** of `uploadFile` for the final URL(s). Reading
+internal state paths breaks future-compatibility.
+
+## Related concepts
+
+- [[@action-upload-file]]
+- [[@primitive-file-upload]]
+- [[@concept-storage-adapter]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 2.7`

package/docs/wiki/compiled/pattern-cross-screen-data-flow.md

@@ -0,0 +1,83 @@
+---
+id: pattern-cross-screen-data-flow
+title: Pattern — Cross-screen data flow
+kind: pattern
+sources: [docs/consumer/ai-context.md#cross-screen-data-flow]
+---
+
+# Pattern — Cross-screen data flow
+
+Two channels for passing data between screens:
+
+1. **`/ui/selectedRow`** — framework-reserved magic path. Auto-written
+   when a table row is clicked. Persists across navigation, drawer,
+   modal until next row interaction dispatch.
+2. **`/navigation/params`** — extra params on `navigateScreen`. **Reset
+   on each navigation** — for one-shot context.
+
+## Master → Detail (via `/ui/selectedRow`)
+
+```json
+// List screen: row click (framework auto-writes row to /ui/selectedRow) + navigate
+"onRowClick": [
+  { "action": "navigateScreen", "params": { "screen": "item-detail" } }
+]
+
+// Detail screen: reads /ui/selectedRow directly
+"props": { "content": { "$state": "/ui/selectedRow/name" } }
+```
+
+The framework writes the clicked row to `/ui/selectedRow` BEFORE
+dispatching the action chain. `onRowClick` params resolve lazily at click
+time, so they can read `/ui/selectedRow/<key>` directly. No explicit
+`setState` needed.
+
+**Do NOT use `"$row"` literal** — there is no `$row` expression. See
+[[@antipattern-row-literal]].
+
+## Navigation with params
+
+```json
+// Source
+{ "action": "navigateScreen", "params": { "screen": "profile", "employeeId": 42 } }
+
+// Target
+"props": { "content": { "$state": "/navigation/params/employeeId" } }
+```
+
+`/navigation/params` is reset on each navigation — for data that persists
+across back-navigation, use `/ui/selected*`.
+
+## Column action buttons follow the same pattern
+
+When a button in `columns[].actions[]` is clicked, the framework writes
+the row to `/ui/selectedRow` BEFORE dispatching. Action params resolve
+at press time (lazy, not render-time):
+
+```json
+"columns": [{
+  "id": "actions-col",
+  "actions": [{
+    "icon": "pencil-simple",
+    "onPress": [{
+      "action": "openModal",
+      "params": { "id": "edit-modal", "itemId": { "$state": "/ui/selectedRow/id" } }
+    }]
+  }]
+}]
+```
+
+Direct `onRowClick` ActionBinding(s) use the same lazy row-context contract.
+
+## Related concepts
+
+- [[@path-ui-selected-row]]
+- [[@path-navigation]]
+- [[@action-navigate]]
+- [[@primitive-table]]
+- [[@antipattern-row-literal]]
+- [[@concept-expression-timing]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Cross-Screen Data Flow`

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

@@ -0,0 +1,63 @@
+---
+id: pattern-fetch-vs-datasources
+title: Pattern — `fetch` vs `dataSources` decision
+kind: pattern
+sources: [docs/consumer/ai-context.md#when-to-use-fetch-vs-datasources, docs/consumer/reference-doc.md]
+---
+
+# Pattern — `fetch` vs `dataSources` decision
+
+Both load data into state. Pick **one pattern per data target**.
+
+## Comparison
+
+| | `initialActions + fetch` | `dataSources` |
+|---|---|---|
+| **Purpose** | One-shot load on mount, CRUD in transactions | Reactive data that re-fetches when params change |
+| **Loading state** | `/ui/loading` (boolean) | `/{target}Loading` (boolean) — auto-generated |
+| **Error state** | `/ui/lastError` (object) | `/{target}Error` (object) — auto-generated |
+| **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 |
+
+## Rule
+
+**Don't mix both for the same data target.** They write to different
+loading-state paths — using both creates conflicting state. See
+[[@antipattern-mix-fetch-and-datasources]].
+
+## Examples — same screen with both, correctly separated
+
+`dataSources` for the reactive list, `fetch` (in transactions) for
+mutations:
+
+```json
+{
+  "dataSources": {
+    "items": { "url": "/api/items", "params": { "status": { "$state": "/filter" } }, "target": "/items" }
+  },
+  "elements": {
+    "create-btn": {
+      "type": "button",
+      "on": { "press": { "transaction": {
+        "before": [{ "action": "closeModal", "params": { "id": "create-modal" } }],
+        "optimistic": [{ "action": "setState", "params": { "statePath": "/items", "value": { "$array": "append", ... } } }],
+        "confirm": [{ "action": "fetch", "params": { "url": "/api/items", "method": "POST", "body": {...}, "target": "/tx/result" } }],
+        "onSuccess": [{ "action": "refreshDataSource", "params": { "id": "items" } }]
+      }}}
+    }
+  }
+}
+```
+
+## Related concepts
+
+- [[@action-fetch]]
+- [[@concept-data-sources]]
+- [[@concept-initial-actions]]
+- [[@antipattern-mix-fetch-and-datasources]]
+- [[@pattern-loading-content-empty]]
+- [[@concept-transactions]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § When to Use fetch vs dataSources`

package/docs/wiki/compiled/pattern-file-upload-auto.md

@@ -0,0 +1,61 @@
+---
+id: pattern-file-upload-auto
+title: Pattern — Auto-upload (autoUpload: true)
+kind: pattern
+sources: [docs/consumer/ai-context-primitives.md#file-upload]
+---
+
+# Pattern — Auto-upload
+
+`autoUpload: true` (default) — file uploaded immediately on selection.
+Use for simple cases like avatar uploads.
+
+## Skeleton
+
+```json
+{
+  "type": "file-upload",
+  "props": { "accept": "image/*", "maxSize": 5242880, "autoUpload": true },
+  "on": {
+    "upload": {
+      "action": "uploadFile",
+      "params": { "bucket": "avatars", "target": "/form/avatarUrl" }
+    }
+  }
+}
+```
+
+## With `path` template
+
+```json
+{ "type": "file-upload",
+  "props": { "accept": "image/*", "maxSize": 5242880, "autoUpload": true },
+  "on": { "upload": {
+    "action": "uploadFile",
+    "params": {
+      "bucket": "avatars",
+      "path": { "$template": "users/${/auth/user/id}/${filename}" },
+      "target": "/form/avatarUrl"
+    }
+  }}
+}
+```
+
+`${filename}` is replaced with original filename.
+
+## Use case
+
+User selects an avatar → upload completes → `/form/avatarUrl` holds the
+URL → display via `<image src={ "$state": "/form/avatarUrl" } />`.
+
+## Related concepts
+
+- [[@pattern-file-upload-manual]] — alternative for multi-field forms
+- [[@primitive-file-upload]]
+- [[@action-upload-file]]
+- [[@concept-file-upload-overview]]
+- [[@concept-storage-adapter]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § file-upload → Auto upload pattern`

package/docs/wiki/compiled/pattern-file-upload-manual.md

@@ -0,0 +1,59 @@
+---
+id: pattern-file-upload-manual
+title: Pattern — Manual upload (autoUpload: false)
+kind: pattern
+sources: [docs/consumer/ai-context-primitives.md#file-upload]
+---
+
+# Pattern — Manual upload
+
+`autoUpload: false` — files selected and previewed but NOT uploaded until
+triggered by a button action chain. Use for multi-field forms where the
+upload should happen alongside the form submit.
+
+## Skeleton
+
+File-upload element:
+```json
+{
+  "type": "file-upload",
+  "props": { "accept": ".pdf,.docx,.xlsx", "multiple": true, "maxFiles": 5, "autoUpload": false, "label": "Attach documents" }
+}
+```
+
+Submit chain — upload first, then submit:
+```json
+"on": { "press": [
+  { "action": "uploadFile", "params": { "bucket": "docs", "target": "/form/attachmentUrl" } },
+  { "action": "submitForm", "params": {
+    "formId": "my-form",
+    "url": "...",
+    "method": "POST",
+    "body": { "attachment": { "$state": "/form/attachmentUrl" } }
+  }},
+  { "action": "showNotification", "params": { "type": "success", "message": "Sent!" } }
+]}
+```
+
+## Why this works
+
+Action chains commit state between steps — by the time `submitForm` runs,
+`/form/attachmentUrl` holds the just-uploaded URL.
+
+## Use case
+
+Document submission form — user picks files first (sees previews), fills
+out other fields, clicks Submit → upload + form submission happen in one
+chain.
+
+## Related concepts
+
+- [[@pattern-file-upload-auto]] — simpler alternative
+- [[@primitive-file-upload]]
+- [[@action-upload-file]]
+- [[@action-submit-form]]
+- [[@concept-action-chains]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § file-upload → Manual upload pattern`