mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/cli-validate.md

@@ -0,0 +1,52 @@
+---
+id: cli-validate
+title: `mythik validate`
+kind: concept
+sources: [docs/consumer/ai-context.md#cli-workflow]
+---
+
+# `mythik validate`
+
+Validates a spec against framework rules. Per-doctype validation:
+
+| Doctype | Validates |
+|---|---|
+| Screen | Element tree, expressions, prop names (with Levenshtein "did you mean?") |
+| AppSpec | Cross-references (screen existence, roleAccess consistency) |
+| ApiSpec | Catalogs, endpoints, auth, audit |
+
+## Usage
+
+```bash
+mythik validate task-manager
+mythik validate app-demo
+mythik validate ejecucion-api
+```
+
+## Lint integration
+
+Three new spec validator checks ALSO run during `mythik validate` and
+`mythik push` (defense-in-depth — see [[@cli-lint]]):
+
+- `spec-row-literal` (warning)
+- `spec-crud-id-collision` (error)
+- `spec-auth-domains-port` (warning)
+
+`mythik validate <id>` shows both errors AND `lintWarnings`.
+
+## CLI warnings on unknown props
+
+Unknown prop names get warnings (not errors) with Levenshtein
+suggestions: `⚠ unknown prop "inputType" for type "input" — did you
+mean "type"?` (rule 64).
+
+## Related concepts
+
+- [[@cli-lint]]
+- [[@cli-push]]
+- [[@cli-overview]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § CLI Workflow`
+- `docs/consumer/reference-doc.md § rule 64`

package/docs/wiki/compiled/cli-versioning-author.md

@@ -0,0 +1,58 @@
+---
+id: cli-versioning-author
+title: `--author` flag — activates versioning
+kind: concept
+sources: [docs/consumer/reference-doc.md#rules-92-110]
+---
+
+# `--author` flag
+
+`mythik push` and `mythik patch` **without `--author`** write directly to
+the `screens` table with NO version history. **With `--author <name>`**,
+they use `VersionedSpecStore` which writes to BOTH `screens` AND
+`screen_versions`, enabling `history`, `diff`, and `rollback` commands.
+
+## Usage
+
+```bash
+mythik push my-screen --author alice --description "Initial layout"
+mythik patch screen-id --from-file patch.json --author alice --description "Fixed layout"
+```
+
+The version row includes:
+- `author` — provided via `--author`
+- `source_type` — `push` or `patch`
+- `description` — optional, via `--description`
+
+**Always use `--author` during development** (rule 110).
+
+## Without `--author`
+
+Commands work as before (no versioning). Useful for git-backed workflows
+where `git log` IS the audit trail.
+
+## Patch output metadata
+
+`runPatch` records history in text, JSON, and TOON modes. JSON/TOON
+success output includes `versioned: boolean` and `version?: number`.
+
+## Auto-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.
+
+## Related concepts
+
+- [[@cli-history]]
+- [[@cli-push]]
+- [[@cli-patch]]
+- [[@concept-versioned-store]]
+- [[@concept-storage-table-versions]]
+- [[@concept-rollback]]
+- [[@concept-promote-gate]]
+- [[@pattern-git-vs-db-versioning]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rules 92, 110`

package/docs/wiki/compiled/concept-action-chains.md

@@ -0,0 +1,65 @@
+---
+id: concept-action-chains
+title: Action chains — sequential execution
+kind: concept
+sources: [docs/consumer/ai-context.md#actions, docs/consumer/ai-context-patterns.md, docs/consumer/reference-doc.md#multiple-actions-sequential]
+---
+
+# Action chains — sequential execution
+
+Wire multiple actions to one event by passing an array. **Each action
+completes before the next starts** — sequential dispatch with state commit
+between steps.
+
+## Shape / Signature
+
+```json
+{ "on": { "press": [<action>, <action>, <action>] } }
+```
+
+## Examples
+
+Save then close + refresh:
+```json
+"press": [
+  { "action": "fetch", "params": { "url": "/api/save", "method": "POST", "body": {...} } },
+  { "action": "closeModal", "params": { "id": "edit-modal" } },
+  { "action": "fetch", "params": { "url": "/api/items", "target": "/items" } }
+]
+```
+
+Set state then navigate (the navigated screen sees the new state):
+```json
+"press": [
+  { "action": "setState", "params": { "statePath": "/draft", "value": { "$state": "/form" } } },
+  { "action": "navigateScreen", "params": { "screen": "review" } }
+]
+```
+
+## Commit semantics
+
+Each action in a sequential chain commits state before the next runs.
+`[setState, navigateScreen]` works — the navigated screen sees the state
+written by `setState`.
+
+## Constraints / Anti-patterns
+
+- **Chains do NOT stop on failure.** `validateForm` marks errors but does
+  NOT halt subsequent actions. Use `submitForm` with `formId` instead. See
+  [[@antipattern-action-chain-no-stop]].
+- For background dispatch (next action immediately), use
+  [[@concept-fire-and-forget]].
+- For optimistic CRUD UX, prefer [[@concept-transactions]] over plain chains.
+
+## Related concepts
+
+- [[@concept-fire-and-forget]] — async dispatch
+- [[@concept-transactions]] — optimistic + auto-rollback
+- [[@action-submit-form]] — gating pattern
+- [[@action-set-state]] — typical chain step
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Actions`
+- `docs/consumer/ai-context-patterns.md § Action chains commit state between steps`
+- `docs/consumer/reference-doc.md § Multiple Actions (Sequential)`

package/docs/wiki/compiled/concept-action-middleware.md

@@ -0,0 +1,55 @@
+---
+id: concept-action-middleware
+title: Action middleware
+kind: concept
+sources: [docs/consumer/reference-doc.md#action-middleware]
+---
+
+# Action middleware
+
+Pre/post/onError hooks that run on EVERY dispatcher action (not just
+`fetch`). Configured at the host-app level via `MythikApp` props.
+
+## Host-app config
+
+```tsx
+<MythikApp
+  auth={{
+    provider: createSupabaseAuthProvider(client),
+    middleware: [myLoggingMiddleware, myAnalyticsMiddleware],
+  }}
+/>
+```
+
+## Middleware shape
+
+```ts
+{
+  name: "my-middleware",
+  before: (ctx) => { /* runs before action; ctx.action, ctx.params, ctx.getState(), ctx.setParam() */ },
+  after: (ctx, result) => { /* after successful action */ },
+  onError: (ctx, error) => { /* on action failure (isolated per handler) */ }
+}
+```
+
+## Behavior
+
+- Executes in registration order.
+- `before` can modify params via `ctx.setParam()`.
+- `onError` handlers are isolated — one failing handler doesn't prevent
+  others from running.
+
+## Separation of concerns
+
+- **Fetch interceptors** = networking (headers, retry, timeout). See
+  [[@concept-fetch-interceptors]].
+- **Action middleware** = business logic (logging, analytics, auth lifecycle).
+
+## Related concepts
+
+- [[@concept-fetch-interceptors]]
+- [[@concept-customize-plugin]] — for cross-cutting framework features
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § Action Middleware`

package/docs/wiki/compiled/concept-animation-build-css.md

@@ -0,0 +1,43 @@
+---
+id: concept-animation-build-css
+title: `buildCSSKeyframes` — web output
+kind: concept
+sources: [docs/consumer/reference-doc.md#animation-system--infrastructure-plan-2-2026-04-18]
+---
+
+# `buildCSSKeyframes` — web output
+
+Web animation builder. Returns `{ name, keyframesText, animationCSS }`.
+
+## Output
+
+- `name` — `svka-${djb2(fingerprint)}`. Deterministic hash of content for
+  Constructable StyleSheets dedup.
+- `keyframesText` — derived `at` from normalized fraction (not raw input)
+  for whitespace-clean output.
+- `animationCSS` — CSS shorthand: `name duration easing delay iter
+  direction fillMode`.
+
+## Mounting (web)
+
+`packages/react/src/animation/stylesheet-singleton.ts` — Constructable
+StyleSheets singleton + `<style>.insertRule` fallback. `registerKeyframes(name,
+text)` is idempotent dedup by name. Feature-detected with iterability
+probe (jsdom defines `adoptedStyleSheets` non-iterably — fallback path
+activates). SSR-safe (`canUseDOM()` guards). **Zero `dangerouslySetInnerHTML`
+in either path** — CSSOM only.
+
+## Useful for
+
+- Custom animation libraries reading the framework's resolved AnimationSpec.
+- Debugging unexpected animation rendering.
+
+## Related concepts
+
+- [[@concept-animation-build-rn]] — RN parallel
+- [[@concept-keyframe-snapshot]]
+- [[@concept-shape-animations]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rules 185, 190`

package/docs/wiki/compiled/concept-animation-build-rn.md

@@ -0,0 +1,44 @@
+---
+id: concept-animation-build-rn
+title: `buildReanimatedSpec` — RN output
+kind: concept
+sources: [docs/consumer/reference-doc.md#animation-system--infrastructure-plan-2-2026-04-18]
+---
+
+# `buildReanimatedSpec` — RN output
+
+RN animation builder. Returns `{ animatedProps, inputRange, outputRanges,
+animatedColorProps, timing }`. Emits **plain data** — no React, no
+Reanimated imports. Runner wires shared values + `useAnimatedStyle` separately.
+
+## Mechanism
+
+- Nearest-neighbor fill for missing property values at keyframe stops.
+- Numeric rotate / skew stored as `rotateDeg` / `skewXDeg` / `skewYDeg`
+  for correct `interpolate()` input.
+- Non-deg rotate strings (`0.25turn`, `3.14rad`) skipped on RN (web-only).
+- **Percentage `borderRadius` throws on RN** (cannot animate natively).
+
+## Hooks
+
+- `useElementAnimations(animations, options)` returns `{ animatedStyle, triggerUnmount }`.
+- `useShapeAnimations(animations, options)` for SVG-shape children.
+
+Pure RN-style composition via `composeRNStyle` — scalars last-wins,
+transforms merge-by-key (not concat).
+
+## Web-only fields stripped
+
+`boxShadow` and `filter` keyframe fields are omitted on RN (no 1:1
+platform mapping yet — deferred to Plan 4 RN motion parity milestone).
+
+## Related concepts
+
+- [[@concept-animation-build-css]]
+- [[@concept-keyframe-snapshot]]
+- [[@concept-web-only-recipes]]
+- [[@concept-shape-animations]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rules 186, 192`

package/docs/wiki/compiled/concept-animation-caps.md

@@ -0,0 +1,38 @@
+---
+id: concept-animation-caps
+title: Animation performance caps
+kind: concept
+sources: [docs/consumer/reference-doc.md#animation-system--infrastructure-plan-2-2026-04-18]
+---
+
+# Animation performance caps
+
+`validateAnimationCaps(animations)` returns `{ warnings, errors }` based on
+soft/hard caps.
+
+## Caps
+
+| Scope | Soft (warn) | Hard (error) |
+|---|---|---|
+| Animations per trigger | 3 | 6 |
+| Triggers per element with animations | 5 | 7 |
+
+`null` triggers are excluded from the count.
+
+## Web-only recipes
+
+`WEB_ONLY_RECIPES: ReadonlySet<string>` — currently `{ 'glow' }`. The
+validator emits a warning when a web-only recipe is referenced, calling out
+the silent RN no-op until per-platform shadow parsing lands.
+
+See [[@concept-web-only-recipes]].
+
+## Related concepts
+
+- [[@concept-animations-engine]]
+- [[@concept-animation-triggers]]
+- [[@concept-web-only-recipes]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rule 188, 198`

package/docs/wiki/compiled/concept-animation-cascade.md

@@ -0,0 +1,89 @@
+---
+id: concept-animation-cascade
+title: 5-level animation cascade
+kind: concept
+sources: [docs/consumer/ai-context.md#interactive-states--animations, docs/consumer/reference-doc.md#layer-3-custom-elements-plan-custom-element-cascade]
+---
+
+# 5-level animation cascade
+
+Animations cascade across **identity → variant → elementDef → template →
+element**, per-trigger. Later levels override earlier. Non-overlapping
+triggers from different levels combine.
+
+## Levels
+
+| # | Level | Source | Scope |
+|---|---|---|---|
+| 1 | **identity** | `tokens.identity.animations` | App-wide default. Reaches **inside** custom-element expansions |
+| 2 | **variant** | `tokens.components.<type>.<variantName>.animations` OR `ElementDefinition.variants[name].animations` | Per-variant override |
+| 3 | **elementDef** | Author's declaration on a primitive inside a custom element's render tree | Present **only** inside custom element expansions; undefined elsewhere |
+| 4 | **template** | `spec.templates.<name>.animations` | Per-template override; supports `$prop`/`$state`/`$cond` |
+| 5 | **element** | `element.animations` | Per-instance. For custom-element instances, applies to OUTER primitive only (black-box) |
+
+## Variant resolution order
+
+1. `ElementDefinition.variants[name]` — author's built-in (checked first)
+2. `tokens.components[type].variants[name]` — theme-level fallback
+
+## Merge semantics
+
+Per-trigger, later wins. Non-overlapping triggers combine — identity's
+`mount: fade-up` + variant's `ambient: pulse-primary` + element's
+`hover: lift` all apply together.
+
+`$state` / `$cond` / `$token` / `$prop` resolve inside any level before
+merging.
+
+## Inside custom elements
+
+For inner primitives:
+- **identity** (level 1): reaches inside the box — consumer cannot block.
+- **variant** (level 2): the inner primitive's own variant if it has one.
+- **elementDef** (level 3): the author's `animations` on that inner node —
+  only present inside custom-element expansions.
+- **template** (level 4): if the inner node uses a template.
+- **element** (level 5): NOT the consumer's declaration — that stays on the
+  outer primitive (black-box). Inner has no level-5 unless author wires
+  one via `$prop`.
+
+## Example
+
+```json
+{
+  "tokens": {
+    "identity": { "animations": { "mount": { "recipe": "fade-up" } } },
+    "components": {
+      "button": { "cta": { "animations": { "ambient": { "recipe": "pulse-primary" } } } }
+    }
+  },
+  "templates": {
+    "hero-card": {
+      "type": "box",
+      "animations": { "mount": { "recipe": "scale-in" }, "hover": { "recipe": "lift" } }
+    }
+  },
+  "elements": {
+    "my-card": { "type": "hero-card", "animations": { "hover": null } }
+  }
+}
+```
+
+`my-card` resolves: `mount: scale-in` (template wins over identity), `hover`
+disabled (element null wins over template's lift).
+
+## Related concepts
+
+- [[@concept-animations-engine]]
+- [[@concept-animation-null-semantics]]
+- [[@concept-component-variants]]
+- [[@concept-templates]]
+- [[@concept-custom-elements]]
+- [[@concept-custom-element-black-box]]
+- [[@concept-identity-animations]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Interactive States & Animations → Cascade`
+- `docs/consumer/ai-context-custom-elements.md § Animation Cascade Inside Custom Elements`
+- `docs/consumer/reference-doc.md § rule 201-204, 229`

package/docs/wiki/compiled/concept-animation-null-semantics.md

@@ -0,0 +1,55 @@
+---
+id: concept-animation-null-semantics
+title: Animation null semantics
+kind: concept
+sources: [docs/consumer/ai-context.md#interactive-states--animations, docs/consumer/reference-doc.md#null-semantics-decision-table-frozen]
+---
+
+# Animation null semantics
+
+Three distinct meanings for absence/null in the cascade. **The distinction
+is load-bearing — whole-field null vs per-trigger null have different
+semantics and must NOT be conflated.**
+
+## Decision table
+
+| Form | Meaning |
+|---|---|
+| `undefined` / omitted | **Inherit** from earlier cascade level |
+| Whole-field `null` (e.g. `variant.animations: null`) | **Inheritance-neutral** — that level contributes nothing, but earlier levels still apply. Equivalent to omitting |
+| Per-trigger `null` (e.g. `element.animations: { hover: null }`) | **Disable** that trigger AND block inheritance |
+
+Output strips nulls — callers see only defined triggers.
+
+## Examples
+
+Disable hover globally on one element:
+```json
+"element": { "animations": { "hover": null } }
+```
+
+Cascade-neutral — variant declares no animations but doesn't block prior:
+```json
+"variant": { "animations": null }
+```
+
+## Why the distinction matters
+
+If you set `variant.animations: null` thinking it disables the trigger, the
+identity-level `mount: fade-up` still applies. To actually block inherited
+animations, use per-trigger null:
+
+```json
+"variant": { "animations": { "mount": null } }
+```
+
+## Related concepts
+
+- [[@concept-animation-cascade]]
+- [[@concept-animations-engine]]
+- [[@concept-animation-triggers]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Interactive States & Animations → Null semantics`
+- `docs/consumer/reference-doc.md § rule 203`

package/docs/wiki/compiled/concept-animation-recipes.md

@@ -0,0 +1,67 @@
+---
+id: concept-animation-recipes
+title: 15 animation recipes
+kind: concept
+sources: [docs/consumer/ai-context.md#interactive-states--animations, docs/consumer/reference-doc.md#animation-system--infrastructure-plan-2-2026-04-18]
+---
+
+# 15 animation recipes
+
+Curated set in `ANIMATION_RECIPES`. Mechanical naming (not emotional) for
+AI consistency.
+
+## Catalog
+
+| Recipe | Use |
+|---|---|
+| `fade` | Simple opacity fade |
+| `fade-up` | Fade + slide up |
+| `fade-down` | Fade + slide down |
+| `scale-in` | Scale 0.9 → 1.0 |
+| `slide-left` | Slide from right |
+| `slide-right` | Slide from left |
+| `lift` | Subtle Y-translate (typical hover) |
+| `glow` | **WEB-ONLY** — colored boxShadow halo (no RN mapping) |
+| `pulse-primary` | Pulse with primary color |
+| `breathe-subtle` | Slow scale 1 ↔ 1.025 (perpetual) |
+| `shimmer` | Skeleton-style sweep |
+| `float` | Slow Y-translate (perpetual) |
+| `pop` | Quick scale-up on press |
+| `shake` | Error indicator |
+| `spin` | 360° rotate (perpetual / loading) |
+
+## Known limitations (per recipe)
+
+- **`glow`** — invisible on light-mode surfaces; web-only (RN
+  parity deferred to Plan 4).
+- **`pulse-primary`** — currently scale-only (missing color-ring per
+  master spec).
+- **`shimmer`** — opacity-proxy (spec calls for gradient-position shift).
+
+## Use
+
+```json
+"animations": { "mount": { "recipe": "fade-up" } }
+"animations": { "mount": { "recipe": "fade-up", "duration": 600, "delay": 200 } }
+```
+
+## Defining custom
+
+Inline animation with explicit keyframes:
+```json
+"animations": { "mount": { "keyframes": [...] } }
+```
+
+See [[@concept-keyframe-snapshot]].
+
+## Related concepts
+
+- [[@concept-animations-engine]]
+- [[@concept-animation-triggers]]
+- [[@concept-keyframe-snapshot]]
+- [[@concept-web-only-recipes]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Interactive States & Animations`
+- `docs/consumer/reference-doc.md § rule 184, 199`

package/docs/wiki/compiled/concept-animation-triggers.md

@@ -0,0 +1,54 @@
+---
+id: concept-animation-triggers
+title: Animation triggers — 7 triggers
+kind: concept
+sources: [docs/consumer/reference-doc.md#animation-system--infrastructure-plan-2-2026-04-18]
+---
+
+# Animation triggers
+
+`ElementAnimations` supports 7 triggers. Each accepts `AnimationRef |
+AnimationRef[] | null`.
+
+| Trigger | Fires when |
+|---|---|
+| `mount` | Element first appears |
+| `unmount` | Element removed (returns Promise) |
+| `hover` | Pointer enters |
+| `focus` | Keyboard focus |
+| `active` | Pressed |
+| `ambient` | Always-running (decorative) |
+| `stateChange` | Specified state path changes (see [[@concept-state-change-animation]]) |
+
+## AnimationRef
+
+```json
+{ "recipe": "fade-up" }
+{ "recipe": "fade-up", "duration": 400, "easing": "ease-out", "delay": 100, "iterations": 1, "stagger": 0, "essential": false }
+```
+
+## Inline animation alternative
+
+```json
+{ "keyframes": [<KeyframeSnapshot>, <KeyframeSnapshot>] }
+```
+
+See [[@concept-keyframe-snapshot]].
+
+## Constraints
+
+- A ref containing both `recipe` AND `keyframes` throws as malformed.
+- `essential: true` bypasses reduced-motion policy — see [[@concept-reduced-motion]].
+
+## Related concepts
+
+- [[@concept-animations-engine]]
+- [[@concept-animation-recipes]]
+- [[@concept-keyframe-snapshot]]
+- [[@concept-state-change-animation]]
+- [[@concept-reduced-motion]]
+- [[@concept-animation-caps]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rules 180-181, 188`