mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/concept-token-system.md

@@ -0,0 +1,61 @@
+---
+id: concept-token-system
+title: Token system — three-layer resolution
+kind: concept
+sources: [docs/consumer/ai-context.md#deep-design-token-system, docs/consumer/reference-doc.md#deep-design-token-system]
+---
+
+# Token system — three-layer resolution
+
+```
+Layer 1: Framework DEFAULTS (always present — app looks good out of the box)
+Layer 2: DNA derivation (OKLCH color science — 8 seeds generate full identity)
+Layer 3: Manual overrides (explicit values always win)
+```
+
+## Three control levels
+
+**Level 1 — Just a color**: `"dna": { "primary": "#0D9488" }` → full
+coherent identity.
+
+**Level 2 — Personality**: `"dna": { "primary": "#0D9488", "roundness": 0.7,
+"motion": "fluid" }` → unique identity from 5 values.
+
+**Level 3 — Override specific tokens**: DNA generates base, explicit values
+win:
+```json
+{ "tokens": {
+  "dna": { "primary": "#0D9488" },
+  "colors": { "error": "#DC2626" },
+  "shape": { "radius": { "md": 24 } }
+}}
+```
+
+## Resolution order
+
+For any token reference (`$token: "colors.primary"`):
+1. Manual override in `tokens.colors.primary`?
+2. DNA-derived value?
+3. Framework default.
+
+## Reactive runtime updates
+
+`updateTokens` action hot-swaps tokens at runtime — see
+[[@action-update-tokens]]. Persists raw input to `/tokens/raw` and resolved
+output to `/tokens/resolved`.
+
+## Related concepts
+
+- [[@concept-dna-seeds]]
+- [[@concept-token-categories]]
+- [[@expression-token]]
+- [[@concept-component-variants]]
+- [[@concept-auto-dark-mode]]
+- [[@action-update-tokens]]
+- [[@path-tokens]]
+- [[@concept-identity-overview]] — identity controls categorical dimensions
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Deep Design Token System`
+- `docs/consumer/reference-doc.md § Deep Design Token System`

package/docs/wiki/compiled/concept-transaction-phase-timing.md

@@ -0,0 +1,47 @@
+---
+id: concept-transaction-phase-timing
+title: Transaction phase timing
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#16-transaction-phase-timing]
+---
+
+# Transaction phase timing
+
+Transaction bindings fire phases at distinct moments — knowing exactly when
+each phase runs is the difference between safe rollback and broken state.
+
+## Phase timing
+
+| Phase | Timing | Context |
+|---|---|---|
+| `before` | Eager at dispatch start | Pre-network. Side-effects that must NOT roll back (closeModal, navigate). |
+| `optimistic` | Eager at dispatch | State changes applied synchronously. UI reflects immediately. Rolled back on `onError`. |
+| `confirm` | Network call | Determines success/failure. Writes to `/tx/result` via target. |
+| `onSuccess` | Eager at network resolve | Response available in resolver context. UPDATE transactions typically omit (re-fetch causes flash). |
+| `onError` | Eager at network reject | Optimistic state reverted via snapshot BEFORE this phase runs. Error available in resolver context. |
+
+## Internal phase (not consumer-visible)
+
+A `snapshot` phase captures the state immediately before `optimistic`,
+enabling rollback. Consumers never invoke `snapshot` directly.
+
+## Examples
+
+When state is read inside each phase:
+```json
+"before":     [{ "action": "closeModal", "params": { "id": "edit" } }],
+"optimistic": [{ "action": "setState", "params": { "statePath": "/items", "value": { "$array": "append", ... } } }],
+"confirm":    [{ "action": "fetch", "params": { "target": "/tx/result", ... } }],
+"onSuccess":  [{ "action": "showNotification", "params": { "message": { "$template": "Created ${ /tx/result/id }" } } }],
+"onError":    [{ "action": "showNotification", "params": { "type": "error", "message": "Could not save." } }]
+```
+
+## Related concepts
+
+- [[@concept-transactions]]
+- [[@concept-transaction-rollback]]
+- [[@concept-transaction-snapshot]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 1.6` + § 5.5

package/docs/wiki/compiled/concept-transaction-rollback.md

@@ -0,0 +1,38 @@
+---
+id: concept-transaction-rollback
+title: Transaction rollback semantics
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#55-transaction-rollback-mechanics]
+---
+
+# Transaction rollback semantics
+
+At dispatch start, the engine captures `store.getSnapshot()` immediately
+before `optimistic`. If `confirm` rejects, the snapshot is restored before
+`onError` runs.
+
+## Phase rollback table
+
+| Phase | Rolled back on error? | Runs if network fails? |
+|---|---|---|
+| `before` | **No** — side-effects persist (closeModal, navigate) | Yes — runs first |
+| `optimistic` | **Yes** — state snapshot restored | Yes — applied, then potentially reverted |
+| `onSuccess` | No — only runs if network succeeded | No — skipped |
+| `onError` | No — runs AFTER rollback | Yes — sees restored state |
+
+## Implications
+
+- **Don't put data mutations in `before`** — they persist through rollback.
+- **Don't put navigation in `optimistic`** — rollback does NOT un-navigate.
+- **`onError` sees the pre-optimistic state** — rollback has already
+  happened by the time `onError` runs.
+
+## Related concepts
+
+- [[@concept-transactions]]
+- [[@concept-transaction-phase-timing]]
+- [[@concept-transaction-snapshot]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 5.5`

package/docs/wiki/compiled/concept-transaction-snapshot.md

@@ -0,0 +1,37 @@
+---
+id: concept-transaction-snapshot
+title: Transaction snapshot — internal mechanism
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#16-transaction-phase-timing, docs/consumer/ai-context-runtime-semantics.md#55-transaction-rollback-mechanics]
+---
+
+# Transaction snapshot — internal mechanism
+
+The transaction engine captures a store snapshot via `store.getSnapshot()`
+immediately before the `optimistic` phase runs. If `confirm` rejects, the
+snapshot is restored before `onError` actions execute.
+
+This is internal — consumers never invoke `snapshot` directly, but
+understanding it explains why phases behave as they do.
+
+## Implementation
+
+`packages/core/src/actions/transaction-engine.ts`:
+- `before` at line 47-50
+- snapshot at line 52-53
+- `optimistic` at line 55-58
+- `onSuccess` at line 79-81
+- `onError` at line 94-99
+
+(See `docs/consumer/ai-context-runtime-semantics.md § 5.5`.)
+
+## Related concepts
+
+- [[@concept-transactions]]
+- [[@concept-transaction-phase-timing]]
+- [[@concept-transaction-rollback]]
+- [[@concept-where-to-look]] — for source-level debugging
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 1.6` + § 5.5

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

@@ -0,0 +1,72 @@
+---
+id: concept-transactions
+title: Transactions — optimistic CRUD with rollback
+kind: concept
+sources: [docs/consumer/ai-context.md#transactions-optimistic-updates, docs/consumer/reference-doc.md#transactions-optimistic-updates]
+---
+
+# Transactions — optimistic CRUD with rollback
+
+Use `transaction` for CRUD operations that need instant UI feedback. The
+framework takes a state snapshot before `optimistic`, applies your changes
+instantly, then confirms with the server. **On failure, it rolls back
+automatically.**
+
+## Shape / Signature
+
+```json
+"on": { "press": { "transaction": {
+  "before": [/* UI transitions — NOT rolled back */],
+  "optimistic": [/* Data changes — ROLLED BACK on error */],
+  "confirm": [/* Network — determines success/failure */],
+  "onSuccess"?: [/* Post-success sync */],
+  "onError"?: [/* User notification (after rollback) */],
+  "timeout"?: 30000
+}}}
+```
+
+## Decision rule
+
+- **"Would I undo this if the server says no?"** → `optimistic`
+- **"Should this happen regardless?"** → `before`
+
+| Action | Phase | Why |
+|---|---|---|
+| `closeModal` | `before` | Don't reopen on error |
+| `setState` (data) | `optimistic` | Rollback if server rejects |
+| `setState` (form reset) | `optimistic` | Restore form so user can retry |
+| `navigate` | `before` | Stay on page, show error there |
+
+## Confirm result access
+
+`fetch` in `confirm` writes to `/tx/result` via `target`. `onSuccess` reads
+it via `{ "$state": "/tx/result" }`. On error, `/tx/error` contains
+`{ message }`. Both are cleaned up automatically.
+
+## Timeout
+
+Default 10 seconds. Override:
+```json
+"transaction": { "timeout": 30000, ... }
+```
+
+## Constraints / Anti-patterns
+
+- **`submitForm` in `confirm` is NOT recommended.** It has its own validation
+  gate that conflicts with the transaction engine. Use `fetch` in `confirm`
+  instead. See [[@antipattern-submit-form-in-tx-confirm]].
+- **UPDATE transactions don't need `onSuccess`** — re-fetch causes flash.
+  See [[@pattern-tx-update]].
+
+## Related concepts
+
+- [[@concept-transaction-phase-timing]]
+- [[@concept-transaction-rollback]]
+- [[@concept-transaction-snapshot]]
+- [[@pattern-tx-create]] / [[@pattern-tx-update]] / [[@pattern-tx-delete]] / [[@pattern-tx-toggle]]
+- [[@path-tx-result-error]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Transactions (Optimistic Updates)`
+- `docs/consumer/reference-doc.md § Transactions (Optimistic Updates)`

package/docs/wiki/compiled/concept-validation-checks.md

@@ -0,0 +1,63 @@
+---
+id: concept-validation-checks
+title: Inline validation `checks`
+kind: concept
+sources: [docs/consumer/ai-context.md#validation, docs/consumer/reference-doc.md#validation]
+---
+
+# Inline validation `checks`
+
+Per-input validators declared on the input element. Use for standalone
+fields without form coordination. For multi-field forms with `isValid`
+gating, prefer [[@concept-forms]].
+
+## Shape / Signature
+
+```json
+{ "type": "input", "props": {
+  "value": { "$bindState": "/form/email" },
+  "checks": [
+    { "type": "required", "message": "Required" },
+    { "type": "email", "message": "Invalid email" }
+  ],
+  "validateOn": "blur"
+}}
+```
+
+## `validateOn`
+
+`"blur"` (default for forms) — validates when field loses focus.
+`"change"` — validates on every keystroke.
+
+## Examples
+
+Simple required field:
+```json
+{ "type": "input", "props": {
+  "value": { "$bindState": "/form/title" },
+  "checks": [{ "type": "required" }]
+}}
+```
+
+Multiple rules:
+```json
+{ "type": "input", "props": {
+  "value": { "$bindState": "/form/email" },
+  "checks": [
+    { "type": "required", "message": "Email required" },
+    { "type": "email", "message": "Invalid email" }
+  ],
+  "validateOn": "blur"
+}}
+```
+
+## Related concepts
+
+- [[@concept-validators-catalog]] — full validator list
+- [[@concept-forms]] — coordinated form-level validation
+- [[@expression-bindstate]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Validation`
+- `docs/consumer/reference-doc.md § Validation`

package/docs/wiki/compiled/concept-validators-catalog.md

@@ -0,0 +1,76 @@
+---
+id: concept-validators-catalog
+title: Validators catalog
+kind: concept
+sources: [docs/consumer/ai-context.md#validation, docs/consumer/reference-doc.md#validation]
+---
+
+# Validators catalog
+
+Built-in validator types for `checks` on inputs and `rules` in forms.
+
+| Validator | Args | Purpose |
+|---|---|---|
+| `required` | — | Non-empty value |
+| `email` | — | Email format |
+| `minLength` | `{ min }` | Minimum string length |
+| `maxLength` | `{ max }` | Maximum string length |
+| `pattern` | `{ pattern }` | Regex match |
+| `min` | `{ min }` | Minimum number |
+| `max` | `{ max }` | Maximum number |
+| `numeric` | — | Must be a number |
+| `url` | — | Valid URL |
+| `matches` / `equalTo` | `{ other }` | Must equal another field |
+| `greaterThan` / `lessThan` | `{ other }` | Compare to another field |
+| `requiredIf` | `{ field }` | Required when `field` value is truthy. **Truthy check only** — no `eq` operator |
+
+## `requiredIf` trap
+
+`requiredIf` is **truthy-only**. To require based on a specific value (not
+just truthy), compute a boolean via `derive` first, then `requiredIf` on
+that derived path. See [[@antipattern-required-if-equals]] +
+[[@pattern-form-validation-cross-field]].
+
+## Cross-field validators
+
+`matches`, `equalTo`, `greaterThan`, `lessThan`, `requiredIf` all reference
+another field via `args.other` or `args.field`. The `other`/`field` value
+is itself an expression — typically `{ "$state": "/form/<other-field>" }`.
+
+## Examples
+
+Cross-field validation in `forms`:
+```json
+"maxPrice": { "statePath": "/form/maxPrice", "rules": [
+  { "type": "greaterThan", "args": { "other": { "$state": "/form/minPrice" } }, "message": "Max must exceed min" }
+]}
+```
+
+Conditional required via derived boolean:
+```json
+"derive": {
+  "/ui/isEngineering": { "$cond": { "$state": "/form/department", "eq": "Engineering" }, "$then": true, "$else": false }
+},
+"forms": {
+  "employee-form": {
+    "fields": {
+      "salary": { "statePath": "/form/salary", "rules": [
+        { "type": "requiredIf", "args": { "field": { "$state": "/ui/isEngineering" } }, "message": "Salary required for Engineering" }
+      ]}
+    }
+  }
+}
+```
+
+## Related concepts
+
+- [[@concept-validation-checks]] — inline use
+- [[@concept-forms]] — coordinated use
+- [[@antipattern-required-if-equals]]
+- [[@pattern-form-validation-cross-field]]
+- [[@concept-derive]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Validation`
+- `docs/consumer/reference-doc.md § Validation`

package/docs/wiki/compiled/concept-versioned-store.md

@@ -0,0 +1,65 @@
+---
+id: concept-versioned-store
+title: VersionedSpecStore — snapshots + patch chain
+kind: concept
+sources: [docs/consumer/reference-doc.md#rules-82-89]
+---
+
+# VersionedSpecStore
+
+Extends `SpecStore` with versioning. **Backward compatible** — `load(id)`
+still returns the current spec; `save(id, doc)` still works.
+
+## Added methods
+
+```ts
+saveVersion(id, doc, meta): Promise<void>
+loadVersion(id, version): Promise<unknown>
+listVersions(id, limit?): Promise<VersionMeta[]>
+currentVersion(id): Promise<number>
+```
+
+## Activation
+
+`mythik push --author <name>` and `mythik patch --author <name>` activate
+versioning automatically. Without `--author`, commands work as before
+(no versioning).
+
+## Snapshots + patch chain
+
+- v1 stores the **full spec**.
+- Subsequent versions store **RFC 6902 patches**.
+- Every N versions (configurable, default 10) a full snapshot is stored.
+- Reconstructing version X = nearest snapshot + apply patches.
+- `computePatches(before, after)` generates patches; `applyPatches`
+  applies them.
+
+## Lazy bootstrap
+
+First versioned save on an existing spec with no history automatically
+creates v1 (snapshot of current spec), then saves the change as v2. **No
+migration script needed.**
+
+## Implementations
+
+- `MemoryVersionedSpecStore` — in-memory
+- `SqlServerVersionedSpecStore` — `mythik/server`
+- `SupabaseVersionedSpecStore` — `mythik` (PostgREST)
+
+## Custom implementation
+
+See `concept-customize-versioned-store.md` for the recipe.
+
+## Related concepts
+
+- [[@concept-storage-table-versions]]
+- [[@concept-versioning-snapshots-patches]]
+- [[@cli-versioning-author]]
+- [[@cli-history]]
+- [[@concept-rollback]]
+- [[@concept-environment-store]]
+- [[@concept-customize-versioned-store]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rules 82-89`

package/docs/wiki/compiled/concept-versioning-snapshots-patches.md

@@ -0,0 +1,61 @@
+---
+id: concept-versioning-snapshots-patches
+title: Versioning — snapshots + patch chain
+kind: concept
+sources: [docs/consumer/reference-doc.md#rule-83]
+---
+
+# Versioning — snapshots + patch chain
+
+How `VersionedSpecStore` reconstructs an arbitrary version efficiently.
+
+## Strategy
+
+- v1 stores the **full spec** (snapshot).
+- Subsequent versions store **RFC 6902 patches** (delta from previous).
+- Every N versions (configurable, default 10), a fresh snapshot is stored
+  to bound replay cost.
+
+Reconstructing version X:
+1. Find the **nearest snapshot at or before X**.
+2. Apply patches sequentially up to X.
+
+## Internals
+
+`computePatches(before, after)` — generates RFC 6902 patches between two
+docs. Used at `saveVersion` time when previous version is a snapshot or
+patch row.
+
+`applyPatches` — applies a patch array to a doc.
+
+Source files: `packages/core/src/streaming/patch.ts` +
+`packages/core/src/versioning/compute-patches.ts`.
+
+## Structural diff (semantic)
+
+`computeStructuralDiff(before, after)` produces `StructuralChange[]` with
+kinds: `element-added`, `element-removed`, `prop-changed`, `action-changed`,
+`section-changed`. **Type-aware**: screen specs diff elements/props, api
+specs diff endpoints/catalogs at item level, app specs diff
+navigation/tokens. Shows actual values:
+
+```
+prop content: "Send" → "Submit"
+orderBy: added "anio DESC"
+orderBy: removed (was "anio DESC")
+```
+
+Summary: `+2 elements, ~3 changes, -1 element`.
+
+Used by `mythik history` for inline diffs. See [[@cli-history]].
+
+## Related concepts
+
+- [[@concept-versioned-store]]
+- [[@cli-history]]
+- [[@concept-rollback]]
+- [[@cli-patch]] — RFC 6902 patches
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rules 83, 85`

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

@@ -0,0 +1,55 @@
+---
+id: concept-visibility
+title: `visible` — show/hide condition
+kind: concept
+sources: [docs/consumer/ai-context.md#visibility, docs/consumer/reference-doc.md#visibility-conditions]
+---
+
+# `visible` — show/hide condition
+
+`visible` is an expression that controls whether an element renders.
+Returns a boolean — when truthy, the element renders; when falsy, it's
+omitted from the DOM/render tree.
+
+## Shape / Signature
+
+```json
+"visible": <expression>
+```
+
+## Examples
+
+Role check:
+```json
+"visible": { "$state": "/user/role", "eq": "admin" }
+"visible": { "$auth": "role", "eq": "admin" }
+```
+
+Compound conditions:
+```json
+"visible": { "$and": [{ "$state": "/form/isValid" }, { "$state": "/form/hasChanges" }] }
+"visible": { "$or": [{ "$state": "/user/isVIP" }, { "$state": "/cart/total", "gt": 200 }] }
+```
+
+Negation:
+```json
+"visible": { "$not": { "$state": "/ui/loading" } }
+```
+
+## Constraints / Anti-patterns
+
+- **Don't add `visible` on `modal` / `drawer`** — engine manages those.
+  See [[@antipattern-modal-drawer-visible]].
+- For loading/content/empty states, use [[@pattern-loading-content-empty]].
+
+## Related concepts
+
+- [[@expression-state]] — typical condition source
+- [[@expression-cond]] / [[@expression-and-or-not]]
+- [[@expression-auth]]
+- [[@pattern-loading-content-empty]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Visibility`
+- `docs/consumer/reference-doc.md § Visibility Conditions`

package/docs/wiki/compiled/concept-web-only-recipes.md

@@ -0,0 +1,37 @@
+---
+id: concept-web-only-recipes
+title: `WEB_ONLY_RECIPES`
+kind: concept
+sources: [docs/consumer/reference-doc.md#animation-system--infrastructure-plan-2-2026-04-18]
+---
+
+# `WEB_ONLY_RECIPES`
+
+`WEB_ONLY_RECIPES: ReadonlySet<string>` — recipes with no RN mapping
+until per-platform shadow / filter parsing lands. **Currently `{ 'glow' }`.**
+
+## Behavior
+
+- Web: renders correctly.
+- RN: silent no-op (the trigger fires but no visual change).
+- `validateAnimationCaps` walks each trigger's AnimationRefs and emits a
+  warning when a web-only recipe is referenced, calling out the silent RN
+  no-op.
+
+## Why glow is web-only
+
+`glow` migrated from backgroundColor tint to `boxShadow` halo (rule 197).
+RN doesn't have a 1:1 mapping for animated `boxShadow` strings. Deferred
+to a dedicated Plan 4 "RN Motion Parity" milestone — iOS shadow props +
+Android elevation are semantically incompatible and merit separate
+investigation.
+
+## Related concepts
+
+- [[@concept-animation-recipes]]
+- [[@concept-animation-caps]]
+- [[@concept-animation-build-rn]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rule 198`