mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/concept-identity-images.md

@@ -0,0 +1,36 @@
+---
+id: concept-identity-images
+title: `identity.images` — image defaults
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#rule-144]
+---
+
+# `identity.images`
+
+Default corner-radius, overlay, and border for `image` primitives.
+
+## Fields
+
+| Field | Type | Effect |
+|---|---|---|
+| `corners` | string | Default `borderRadius`: `'match-card'` (uses card radius), `'circle'` (50%), `'square'` (0), `'rounded'` (8px). Spec `style.borderRadius` overrides |
+| `overlay` | string | `'gradient-bottom'`, `'color-tint'`, or `'none'`. Spec `overlay="none"` suppresses |
+| `border` | boolean | 1px border |
+
+## Example
+
+```json
+"tokens": { "identity": {
+  "images": { "corners": "match-card", "overlay": "gradient-bottom", "border": true }
+}}
+```
+
+## Related concepts
+
+- [[@primitive-image]]
+- [[@concept-identity-overview]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Identity System (Forge) → Identity images`
+- `docs/consumer/reference-doc.md § rule 144`

package/docs/wiki/compiled/concept-identity-label-style.md

@@ -0,0 +1,36 @@
+---
+id: concept-identity-label-style
+title: `identity.labelStyle` — form label formatting
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#rule-121]
+---
+
+# `identity.labelStyle`
+
+3 modes for form labels — applied to labels inside `input`, `textarea`,
+`select`, `checkbox` (not just `<Text variant="label">`).
+
+| Value | Effect |
+|---|---|
+| `normal` | (default) |
+| `uppercase` | textTransform + letterSpacing 0.08em |
+| `accent-colored` | Label text in accent color |
+
+## Example
+
+```json
+"tokens": { "identity": { "labelStyle": "uppercase" } }
+```
+
+## Related concepts
+
+- [[@primitive-input]]
+- [[@primitive-textarea]]
+- [[@primitive-select]]
+- [[@primitive-checkbox]]
+- [[@concept-identity-overview]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Identity System (Forge) → Label Style`
+- `docs/consumer/reference-doc.md § rule 121`

package/docs/wiki/compiled/concept-identity-overview.md

@@ -0,0 +1,72 @@
+---
+id: concept-identity-overview
+title: Identity system - overview
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#identity-system--tokensidentity-controls-visual-identity-beyond-dna]
+---
+
+# Identity system - overview
+
+DNA controls continuous/color values. **Identity** controls **categorical**
+visual dimensions that make apps look genuinely different. Set via
+`tokens.identity` (or runtime via `updateTokens`).
+
+## Validation
+
+Identity values are validated deeply from both AppSpec and screen Spec
+`tokens.identity`. Use documented enum values exactly. For example,
+`identity.colorScheme` is `"light-surface"`, `"dark-surface"`, or
+`"colored-surface"`; `"light"` and `"dark"` are invalid.
+
+## Categorical dimensions
+
+| Dimension | Article |
+|---|---|
+| `surface` (how containers render) | [[@concept-identity-surface]] |
+| `radiusPattern` (corner shape) | [[@concept-identity-radius-pattern]] |
+| `typographyHierarchy` (heading scale) | [[@concept-identity-typography-hierarchy]] |
+| `labelStyle` (form-label formatting) | [[@concept-identity-label-style]] |
+| `textDecoration` (heading effects, multi-select) | [[@concept-identity-text-decoration]] |
+| `colorScheme` (light/dark/colored polarity) | [[@concept-identity-color-scheme]] |
+| `colorWeight` (where color appears) | [[@concept-identity-color-weight]] |
+| `accentApplication` (where accent appears) | [[@concept-identity-accent-application]] |
+| `icons` (weight + container defaults) | [[@concept-identity-icons]] |
+| `images` (corners + overlay + border) | [[@concept-identity-images]] |
+| `gradients` (text + buttons) | [[@concept-identity-gradients]] |
+| `headingColor` (heading text color) | [[@concept-identity-heading-color]] |
+| `borderWidth` / `elevationStyle` overrides | [[@concept-identity-border-elevation-override]] |
+| `animations` (cascade level 1) | [[@concept-identity-animations]] |
+| `background` (LayerBackground) | [[@concept-layer-background]] |
+
+## Continuous dimensions
+
+| Dimension | Meaning |
+|---|---|
+| `depth` (0-1) | Shadow intensity |
+| `shadowAngle` (0-360 degrees) | Shadow direction |
+
+## Example
+
+```json
+"tokens": {
+  "dna": { "primary": "#0D9488", "roundness": 0.7 },
+  "identity": {
+    "surface": "outlined",
+    "radiusPattern": "diagonal",
+    "typographyHierarchy": "editorial",
+    "labelStyle": "uppercase",
+    "textDecoration": ["underline-accent", "shadow"]
+  }
+}
+```
+
+## Related concepts
+
+- [[@concept-dna-seeds]] - continuous side
+- [[@concept-token-system]]
+- [[@concept-identity-helpers]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md` - Identity System (Forge)
+- `docs/consumer/reference-doc.md` - Identity System + rule 111

package/docs/wiki/compiled/concept-identity-radius-pattern.md

@@ -0,0 +1,39 @@
+---
+id: concept-identity-radius-pattern
+title: `identity.radiusPattern` — 11 corner options
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#rule-119]
+---
+
+# `identity.radiusPattern`
+
+11 asymmetric corner-shape options. Applied via `t.radius(baseValue)` in
+all primitives.
+
+## Catalog
+
+`all` (default), `top`, `bottom`, `left`, `right`, `diagonal` (TL+BR),
+`inverse-diagonal` (TR+BL), `single` (TL only), `single-tr`, `single-bl`,
+`single-br`.
+
+## Example
+
+```json
+"tokens": { "identity": { "radiusPattern": "diagonal" } }
+```
+
+## Mechanism
+
+`resolveRadiusPattern()` converts to a CSS `border-radius` string. For
+example, `diagonal` produces `"<r> 0 <r> 0"` (TL and BR rounded, TR and
+BL square).
+
+## Related concepts
+
+- [[@concept-identity-overview]]
+- [[@concept-token-categories]] — `shape.radius.*`
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Identity System (Forge) → Radius Pattern`
+- `docs/consumer/reference-doc.md § rule 119`

package/docs/wiki/compiled/concept-identity-surface.md

@@ -0,0 +1,62 @@
+---
+id: concept-identity-surface
+title: `identity.surface` — 6 surface types
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#surface-treatment--6-types-transform-all-containers]
+---
+
+# `identity.surface` — 6 surface types
+
+Transforms all containers, inputs, buttons, modals, cards, accordions,
+selects, textareas, checkboxes, tables. Set via `tokens.identity.surface`.
+
+## Catalog
+
+| Value | Feel | Effect |
+|---|---|---|
+| `elevated` | Material, floating (default) | boxShadow + border + solid bg |
+| `flat` | Minimal, Notion-like | Color blocks only, no borders/shadows |
+| `outlined` | Technical, Linear-like | 1px borders, transparent bg |
+| `glass` | Premium, Apple-like | backdrop-filter blur, semi-transparent (needs dark/colored bg) |
+| `bold` | Brutalist, confident | 2-3px solid borders, no shadows |
+| `neo` | Soft 3D, tangible | Neumorphic inset+outset shadows, no borders |
+
+## Examples
+
+```json
+"tokens": { "identity": { "surface": "outlined" } }
+```
+
+## Behavior notes
+
+- **Surface styles are explicit** — every property set, no implicit values.
+  All 6 types define `border` and `boxShadow` explicitly per component
+  category. Properties are `'none'` when not used (rule 113).
+- **Surface-aware focus per type** (rule 115): elevated/outlined = 1px
+  primary border + ring; flat = no border, ring only; bold = 2px primary
+  border + ring; neo = primary-tinted inset + ring; glass = semi-transparent
+  primary border + ring.
+- **`inputFocus` never includes `backgroundColor`** (rule 140) — would
+  overwrite checkbox primary bg when checked+focused.
+- **`Select` listbox uses `surface.modal`, NOT `surface.card`** (rule 117)
+  — needs opaque bg. See [[@primitive-select]].
+- **Flat inputs** differentiate by background color, not borders — use
+  `colors.background` instead of `colors.surface` (rule 118).
+
+## React Native — glass support
+
+When `surface === 'glass'`, RN primitives wrap content in `<BlurView>`.
+See [[@concept-identity-glass-rn]].
+
+## Related concepts
+
+- [[@primitive-box]] — `surface="card"` / `surface="modal"` props
+- [[@concept-identity-overview]]
+- [[@concept-identity-helpers]]
+- [[@concept-identity-glass-rn]]
+- [[@concept-identity-border-elevation-override]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Identity System (Forge) → Surface Treatment`
+- `docs/consumer/reference-doc.md § rule 112-118, 140`

package/docs/wiki/compiled/concept-identity-text-decoration.md

@@ -0,0 +1,48 @@
+---
+id: concept-identity-text-decoration
+title: `identity.textDecoration` — heading effects (multi-select)
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#rule-122]
+---
+
+# `identity.textDecoration`
+
+6 heading effects. **Supports array for multi-select** — combinations are
+merged.
+
+## Catalog
+
+| Value | Effect |
+|---|---|
+| `stroke` | webkit-text-stroke |
+| `underline-accent` | 3px bottom border, accent color |
+| `highlight` | accent bg tint behind text |
+| `overline` | 3px top border |
+| `shadow` | text-shadow with accent |
+
+## Examples
+
+Single:
+```json
+"tokens": { "identity": { "textDecoration": "underline-accent" } }
+```
+
+Multi-select array:
+```json
+"tokens": { "identity": { "textDecoration": ["underline-accent", "shadow"] } }
+```
+
+## Mechanism
+
+`resolveTextDecorations()` merges styles from all selected decorations.
+
+## Related concepts
+
+- [[@concept-identity-typography-hierarchy]]
+- [[@concept-identity-gradients]]
+- [[@concept-identity-heading-color]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Identity System (Forge) → Text Decoration`
+- `docs/consumer/reference-doc.md § rule 122`

package/docs/wiki/compiled/concept-identity-typography-hierarchy.md

@@ -0,0 +1,40 @@
+---
+id: concept-identity-typography-hierarchy
+title: `identity.typographyHierarchy` — 6 heading scales
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#rule-120]
+---
+
+# `identity.typographyHierarchy`
+
+6 heading-scale options, applied to `<Text variant="heading">`.
+
+## Catalog
+
+| Value | Feel | Effect |
+|---|---|---|
+| `dramatic` | Strong | 3×, 800w |
+| `uniform` | Notion-like | 1.3×, 600w |
+| `editorial` | Elegant | 2.2×, 700w, -0.02em tracking |
+| `display` | Magazine hero | 4×, 900w, -0.03em |
+| `mono` | Mono-spaced | 1.5×, monospace font |
+| `contrast` | Luxury / Apple | 2.5×, 300w ultra-thin |
+
+## Example
+
+```json
+"tokens": { "identity": { "typographyHierarchy": "editorial" } }
+```
+
+## Related concepts
+
+- [[@primitive-text]]
+- [[@concept-identity-overview]]
+- [[@concept-identity-text-decoration]]
+- [[@concept-identity-heading-color]]
+- [[@concept-identity-gradients]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Identity System (Forge) → Typography Hierarchy`
+- `docs/consumer/reference-doc.md § rule 120`

package/docs/wiki/compiled/concept-initial-actions.md

@@ -0,0 +1,82 @@
+---
+id: concept-initial-actions
+title: `initialActions` — mount-time actions
+kind: concept
+sources: [docs/consumer/ai-context.md#spec-structure, docs/consumer/ai-context-runtime-semantics.md#1-expression-resolution-timing]
+---
+
+# `initialActions` — mount-time actions
+
+`initialActions` is a top-level array of ActionBindings that fire once when
+the spec mounts. Use it to load initial data (typically `fetch`), set initial
+state, or trigger any one-shot setup. Params are eagerly resolved at mount
+context — state then stabilizes for subsequent renders.
+
+## Shape / Signature
+
+```json
+{
+  "root": "...",
+  "initialActions": [
+    { "action": "fetch", "params": { "url": "/api/data", "target": "/items" } },
+    { "action": "setState", "params": { "statePath": "/ui/ready", "value": true } }
+  ],
+  "elements": { ... }
+}
+```
+
+## Resolution timing
+
+| Surface | Timing |
+|---|---|
+| `initialActions[]` params | **Eager** at spec mount, mount context |
+
+Subsequent state changes do NOT re-fire `initialActions`. For reactive
+fetching, use [[@concept-data-sources]].
+
+## Examples
+
+Initial data load with auth headers:
+```json
+"initialActions": [
+  { "action": "fetch", "params": {
+    "url": "/api/items",
+    "headers": { "$state": "/config/headers" },
+    "target": "/items"
+  }}
+]
+```
+
+Multiple actions run sequentially:
+```json
+"initialActions": [
+  { "action": "fetch", "params": { "url": "/api/config", "target": "/config" } },
+  { "action": "fetch", "params": { "url": "/api/items", "target": "/items" } }
+]
+```
+
+## Constraints / Anti-patterns
+
+- **Don't mix `initialActions + fetch` and `dataSources` for the same data
+  target.** Each writes to different loading-state paths (`/ui/loading` vs
+  `/{target}Loading`). Pick one pattern per data source — see
+  [[@antipattern-mix-fetch-and-datasources]] and
+  [[@pattern-fetch-vs-datasources]].
+- Engines with `dataSources` self-coordinate via reactive subscriptions —
+  no ordering dependency on `initialActions`. URL templates depending on
+  `initialActions` output use skip-on-undefined-URL-deps to defer the
+  initial fetch until deps resolve.
+
+## Related concepts
+
+- [[@action-fetch]] — most common initialAction
+- [[@concept-data-sources]] — reactive alternative
+- [[@concept-data-sources-lifecycle]] — mount ordering
+- [[@concept-skeleton-auto]] — auto-skeleton activates when `initialActions`
+  has `fetch`
+- [[@pattern-loading-content-empty]] — visibility pattern paired with `fetch`
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Spec Structure → Top-Level Properties`
+- `docs/consumer/ai-context-runtime-semantics.md § 1.1` (timing matrix), § 9 (mount runtime)

package/docs/wiki/compiled/concept-interactive-states.md

@@ -0,0 +1,72 @@
+---
+id: concept-interactive-states
+title: Interactive states — hover / active / focus / transition
+kind: concept
+sources: [docs/consumer/ai-context.md#interactive-states--animations, docs/consumer/reference-doc.md#interactive-states]
+---
+
+# Interactive states — hover / active / focus / transition
+
+Add visual feedback to elements. Zero overhead for elements without
+interactions.
+
+## Shape / Signature
+
+```json
+"hover": { "scale": 1.03, "backgroundColor": "#F1F5F9" },
+"active": { "scale": 0.97 },
+"focus": { "boxShadow": "0 0 0 3px rgba(13,148,136,0.3)" },
+"transition": { "duration": 150, "ease": "easeOut" }
+```
+
+## CSS vs Motion (auto-detection)
+
+| Property | Path |
+|---|---|
+| `scale`, `scaleX`, `scaleY`, `rotate`, `x`, `y` | Motion wrapper |
+| Everything else (color, opacity, shadow…) | CSS pseudo-classes (no extra DOM) |
+
+## Transform shorthand
+
+| Property | Effect |
+|---|---|
+| `scale` | Scale up/down |
+| `x` | Move horizontally |
+| `y` | Move vertically |
+| `rotate` | Degrees |
+| `scaleX` / `scaleY` | Axis-specific |
+
+## Examples
+
+Save button with full state set:
+```json
+"save-btn": {
+  "type": "button", "props": { "label": "Save Changes" },
+  "style": { "backgroundColor": { "$token": "colors.primary" }, "color": "#fff", "padding": "10px 20px", "borderRadius": 10 },
+  "hover": { "scale": 1.03, "y": -1 },
+  "active": { "scale": 0.97 },
+  "focus": { "boxShadow": "0 0 0 3px rgba(13,148,136,0.3)" },
+  "transition": { "duration": 150, "ease": "easeOut" }
+}
+```
+
+## Constraints / Anti-patterns
+
+- **CSS hover only works on**: `box`, `text`, `stack`, `grid`, `scroll`,
+  `button`, `touchable`, `table`. Other types silently ignore. `mythik
+  validate` catches this (rule 14, 34).
+- **Don't use `overflow: hidden` with `box-shadow` hover** — overflow
+  clips the shadow. See [[@antipattern-overflow-hidden-with-shadow]].
+- **Buttons / touchables have built-in CSS transitions** — only add
+  `hover`/`active` for custom behavior beyond defaults (rule 22).
+
+## Related concepts
+
+- [[@concept-css-vs-motion]]
+- [[@concept-animations-engine]] — `animations` is preferred for new specs
+- [[@concept-component-variants]] — variants can supply default states
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Interactive States & Animations → Hover/Active/Focus`
+- `docs/consumer/reference-doc.md § Interactive States`

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

@@ -0,0 +1,52 @@
+---
+id: concept-keyframe-snapshot
+title: `KeyframeSnapshot` schema
+kind: concept
+sources: [docs/consumer/reference-doc.md#animation-system--infrastructure-plan-2-2026-04-18]
+---
+
+# `KeyframeSnapshot` schema
+
+Inline animations are arrays of `KeyframeSnapshot`.
+
+## Shape / Signature
+
+```ts
+{
+  at: string,                    // percent format '0%' to '100%'
+  opacity?: number,
+  transform?: TransformValue,    // translateX/Y, scale (number or {x,y}), rotate, skewX/Y
+  backgroundColor?: string,
+  borderColor?: string,
+  borderRadius?: string,
+  borderWidth?: number,
+  color?: string,
+  filter?: FilterValue,
+  boxShadow?: string             // web-only — RN omitted (filter same policy)
+}
+```
+
+## Constraints
+
+- `at` must be percent format `'0%'` to `'100%'` (out-of-range throws).
+- Keyframes must be **monotonically non-decreasing** by `at`.
+- A ref containing both `recipe` AND `keyframes` throws as malformed.
+
+## Example — `glow` recipe (boxShadow keyframe)
+
+The `glow` recipe uses `boxShadow: 'none'` → `'0 0 20px 4px rgba(99,102,241,0.45)'` for a colored shadow halo (canonical glow per Linear/Stripe).
+
+## Web vs RN
+
+- **Web** — `buildCSSKeyframes(spec)` returns `{ name, keyframesText, animationCSS }`. `name` is `svka-${djb2(fingerprint)}` — deterministic hash for dedup.
+- **RN** — `buildReanimatedSpec(spec)` returns plain data; runner wires shared values + `useAnimatedStyle`. Numeric rotate/skew stored as `rotateDeg`/`skewXDeg`/`skewYDeg`. **Percentage `borderRadius` throws on RN** (cannot animate natively). **`boxShadow` and `filter` omitted on RN.**
+
+## Related concepts
+
+- [[@concept-animation-build-css]]
+- [[@concept-animation-build-rn]]
+- [[@concept-web-only-recipes]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rules 182, 185, 186, 197`

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

@@ -0,0 +1,80 @@
+---
+id: concept-layer-background
+title: `tokens.identity.background` — LayerBackground v2
+kind: concept
+sources: [docs/consumer/ai-context.md#identity-system-forge, docs/consumer/reference-doc.md#rules-147-152-220]
+---
+
+# `tokens.identity.background` — LayerBackground v2
+
+App-level background. The legacy `BackgroundConfig` (`{ style: 'solid' |
+'gradient' | 'mesh' | 'blobs' }`) was not part of the current public contract — current shape is
+`LayerBackground` with `color?` + ordered `layers[]`.
+
+## Shape / Signature
+
+```json
+"tokens": {
+  "identity": {
+    "background": {
+      "color": "#0a0a0a",
+      "layers": [
+        { "type": "gradient", "kind": "radial", "stops": [...] },
+        { "type": "grain", "intensity": 0.04 }
+      ]
+    }
+  }
+}
+```
+
+## Layer kinds
+
+`'solid'`, `'gradient'`, `'pattern'`, `'grain'`, `'image'`, `'blobs'` —
+each carries `LayerCommonProps` (`opacity?`, `blendMode?`, `zIndex?`).
+
+See [[@concept-background-layer-kinds]].
+
+## Recipes
+
+8 curated recipes shipped in `tokens.backgrounds.*`:
+`linear-aura` (Linear-like), `stripe-ribbons` (Stripe-like),
+`vercel-center`, `arc-organic`, `grid-subtle`, `notion-warm`,
+`raycast-mono`, `comic-pop`.
+
+Use a recipe by name string instead of declaring layers — see
+[[@concept-background-recipes]].
+
+## Mounting
+
+`<BackgroundStack>` mounts at the root of `MythikRenderer` when
+`tokens.identity.background` is a `LayerBackground`. `isLayerBackground`
+returns true for objects carrying `color` or `layers` (rejects empty `{}`,
+arrays, and objects with a `style` field — defense against legacy
+holdovers).
+
+`/tokens/resolved` is the source — preset swaps + playground updates
+trigger re-resolution and remount.
+
+## Constraints / Anti-patterns
+
+- **`$token: "backgroundCSS"` removed.** See
+  [[@antipattern-background-css-token]].
+- **Box `backgroundBlobs` prop removed.** App-level background lives
+  exclusively at `tokens.identity.background`. See
+  [[@antipattern-background-blobs-prop]].
+
+## Related concepts
+
+- [[@concept-background-stack]]
+- [[@concept-background-layer-kinds]]
+- [[@concept-blob-layer]]
+- [[@concept-background-recipes]]
+- [[@concept-pattern-primitives]]
+- [[@concept-background-caps]]
+- [[@concept-identity-overview]]
+- [[@path-tokens]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Identity System (Forge)`
+- `docs/consumer/reference-doc.md § rules 147, 152, 220, 222`