mythik 0.0.1 → 0.1.0

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

@@ -0,0 +1,53 @@
+---
+id: concept-background-recipes
+title: 8 curated background recipes
+kind: concept
+sources: [docs/consumer/reference-doc.md#rule-173]
+---
+
+# 8 curated background recipes
+
+Shipped in `tokens.backgrounds.*`. Use by recipe-name string OR expand
+and modify for custom variants.
+
+## Catalog
+
+| Recipe | Inspiration |
+|---|---|
+| `linear-aura` | Linear |
+| `stripe-ribbons` | Stripe |
+| `vercel-center` | Vercel |
+| `arc-organic` | Arc browser |
+| `grid-subtle` | Subtle grid (technical) |
+| `notion-warm` | Notion |
+| `raycast-mono` | Raycast |
+| `comic-pop` | Pop-art / comic |
+
+Exported as `BACKGROUND_RECIPES` constant.
+
+## Use
+
+Recipe name as background:
+```json
+"tokens": { "identity": { "background": "linear-aura" } }
+```
+
+Or expand a recipe and tweak:
+```json
+"tokens": { "identity": {
+  "background": {
+    "color": "#0a0a0a",
+    "layers": [...]
+  }
+}}
+```
+
+## Related concepts
+
+- [[@concept-layer-background]]
+- [[@concept-background-layer-kinds]]
+- [[@concept-presets]] — preset-level snapshots
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rule 173`

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

@@ -0,0 +1,55 @@
+---
+id: concept-background-stack
+title: `BackgroundStack` — root mount
+kind: concept
+sources: [docs/consumer/reference-doc.md#rules-178-218-220]
+---
+
+# `BackgroundStack` — root mount
+
+Component that consumes `LayerBackground` config OR a recipe-name string
+and renders the layered background.
+
+## Mounting
+
+When `tokens.identity.background` is a `LayerBackground` (object with
+`color` or `layers`), `MythikRenderer` wraps the rendered tree in a
+positioned container with `<BackgroundStack>` as a sibling **inside a
+stacking context** (`isolation: isolate`).
+
+The isolation context prevents per-layer `zIndex` values (which
+`resolveCommon` defaults to array-index, reaching 3+ on multi-layer
+stacks) from leaking out to occlude the content wrapper.
+
+## Palette threading
+
+`BackgroundStack` accepts `palette?: { primary: string; accent: string }`
+prop. Required for blob layers — without a palette, a dev-mode warning
+fires per render.
+
+`MythikRenderer` threads palette from `tokens.colors.{primary, accent}`;
+missing/malformed colors fire a diagnostic dev-warn at the renderer seam.
+
+## Per-platform implementation
+
+- **Web** (`packages/react/src/background/`) — CSS for solid / gradient /
+  image + inline SVG for pattern / grain.
+- **RN** (`packages/react-native/src/background/`) — `react-native-svg`
+  `SvgXml` for all layers + `View` for solid + `Image` for image.
+
+## Test markers
+
+Root wrappers carry `data-sv-renderer-root="v2"` (web) and
+`testID="sv-renderer-root-v2"` (RN) markers.
+
+## Related concepts
+
+- [[@concept-layer-background]]
+- [[@concept-background-layer-kinds]]
+- [[@concept-blob-layer]]
+- [[@concept-mythik-renderer]]
+- [[@path-tokens]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rules 178, 217-220`

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

@@ -0,0 +1,92 @@
+---
+id: concept-blob-layer
+title: Blob layer v2 — preset + explicit
+kind: concept
+sources: [docs/consumer/ai-context.md#rule-53, docs/consumer/reference-doc.md#rules-205-209-219-220]
+---
+
+# Blob layer v2
+
+Two mutually-exclusive forms for blob backgrounds — preset (curated) or
+explicit (per-instance configuration).
+
+## Preset form
+
+```json
+{
+  "type": "blobs",
+  "preset": "organic-duo",
+  "palette": ["primary", "accent"],
+  "motion": "drift-gentle",
+  "blobOpacity": 0.4
+}
+```
+
+| Field | Values |
+|---|---|
+| `preset` | `'organic-duo'` / `'organic-trio'` / `'circle-pair'` |
+| `palette` | Array of `'primary'` / `'accent'` / hex strings |
+| `motion` | `'drift-gentle'` / `'drift-fluid'` / `'drift-snappy'` / `'static'` |
+| `blobOpacity` | Per-blob fill opacity default |
+
+Hydrates curated compositions from `PRESET_SEEDS`.
+
+## Explicit form
+
+```json
+{
+  "type": "blobs",
+  "blobs": [
+    {
+      "shape": "organic-1",
+      "position": { "x": 0, "y": 0 },
+      "size": { "width": 400, "height": 400 },
+      "color": "primary",
+      "opacity": 0.3,
+      "blur": 20,
+      "motion": { "drift": { ... }, "rotate": { ... }, "scale": { ... } }
+    }
+  ]
+}
+```
+
+`shape` is one of 6 catalog entries (`organic-1..5`, `circle`) OR
+`'custom-svg'` with `path` + `viewBox`.
+
+See [[@concept-blob-shapes-catalog]] + [[@concept-blob-motion]].
+
+## Layer-level vs per-blob opacity
+
+**Two distinct opacity axes**:
+- `BlobsLayerConfig.opacity` (`LayerCommonProps`) = layer-container
+  wrapper alpha.
+- `blobOpacity` (renamed from `BlobV2Config.opacity`) = per-blob fill
+  default.
+
+If both were named `opacity` at the same nesting level, they'd compose
+multiplicatively (user writes `opacity: 0.4`, sees 0.16). Rename
+prevents this.
+
+## Custom-svg requirements
+
+`shape: 'custom-svg'` requires non-empty `path` + `viewBox`. Dev: throws
+with field-specific message. Prod: skips malformed blob + `console.warn`,
+preserves app stability.
+
+## Ambiguous config
+
+`{ preset, blobs }` both set — prefers preset + dev-warn. Empty `palette: []`
+falls back to `['primary']` + dev-warn.
+
+## Related concepts
+
+- [[@concept-blob-shapes-catalog]]
+- [[@concept-blob-motion]]
+- [[@concept-background-layer-kinds]]
+- [[@concept-layer-background]]
+- [[@concept-shape-animations]] — drives blob motion
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § rule 53`
+- `docs/consumer/reference-doc.md § rules 205-209, 219-220`

package/docs/wiki/compiled/concept-blob-motion.md

@@ -0,0 +1,58 @@
+---
+id: concept-blob-motion
+title: Blob motion — drift / rotate / scale
+kind: concept
+sources: [docs/consumer/reference-doc.md#rules-208-209]
+---
+
+# Blob motion — drift / rotate / scale
+
+Each `BlobMotion` dimension becomes one `InlineAnimation` on the `ambient`
+trigger.
+
+## Dimension catalog
+
+| Dim | Keyframes | Direction |
+|---|---|---|
+| `drift` | 3 (`0%` → origin, `50%` → (range.x, range.y), `100%` → origin) | translate |
+| `rotate` | 2 (`from` → `to`) | rotate |
+| `scale` | 2 (`from` → `to`) | scale |
+
+All use `direction: 'alternate'` + `iterations: 'infinite'`. Emission
+order: drift → rotate → scale.
+
+## Single vs multi-dimension
+
+- Single dimension → returns scalar `AnimationRef`.
+- Multi-dimension → returns array — both valid per `AnimationRef |
+  AnimationRef[]` union.
+
+## Perceived cycle duration
+
+- Drift = 1× `duration` (symmetric trajectory).
+- Rotate / scale = 2× `duration` (forward + reverse iteration).
+
+## Motion presets
+
+| Preset | Effect |
+|---|---|
+| `drift-gentle` | 28s / small / ease-in-out |
+| `drift-fluid` | 20s / wide / ease-in-out |
+| `drift-snappy` | 14s / medium / linear |
+| `static` | No motion |
+
+## Runtime
+
+`useShapeAnimations` (web: CSSOM keyframes singleton; RN: Reanimated
+`useAnimatedProps` + `HARD_PER_TRIGGER` SV pool) drives them at render time.
+
+## Related concepts
+
+- [[@concept-blob-layer]]
+- [[@concept-shape-animations]]
+- [[@concept-animation-recipes]]
+- [[@concept-keyframe-snapshot]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rules 208-209`

package/docs/wiki/compiled/concept-blob-shapes-catalog.md

@@ -0,0 +1,45 @@
+---
+id: concept-blob-shapes-catalog
+title: `BLOB_CATALOG` — 6 curated shapes
+kind: concept
+sources: [docs/consumer/reference-doc.md#rule-205]
+---
+
+# `BLOB_CATALOG`
+
+Exported from `mythik`. `Record<CuratedBlobName, BlobShapeDef>` with
+6 hand-curated entries.
+
+## Shapes
+
+| Name | Aesthetic |
+|---|---|
+| `organic-1` | Balanced rounded |
+| `organic-2` | Elongated diagonal |
+| `organic-3` | Asymmetric multi-lobe (all-cubic — no T-reflection cusps) |
+| `organic-4` | Horizontal flowing ribbon |
+| `organic-5` | Sharply asymmetric |
+| `circle` | Geometric circle |
+
+Each entry has `name`, `viewBox: '0 0 W H'`, and a valid SVG `path` closed
+with `Z`.
+
+## Custom user shapes
+
+Use `shape: 'custom-svg'` (sentinel — NOT in the catalog map). Requires
+`path` + `viewBox` per [[@concept-blob-layer]].
+
+## Type surface
+
+`BlobShapeName`, `CuratedBlobName`, `BlobShapeDef`, `BlobPreset`,
+`BlobMotionPreset`, `BlobMotion`, `BlobInstance`, `BlobV2Config`,
+`BlobRenderStyle`, `BlobSpec` — all exported from `mythik`.
+
+## Related concepts
+
+- [[@concept-blob-layer]]
+- [[@concept-blob-motion]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rules 205-206`

package/docs/wiki/compiled/concept-cli-tokens-inspect.md

@@ -0,0 +1,38 @@
+---
+id: concept-cli-tokens-inspect
+title: `mythik tokens` — CLI inspection
+kind: concept
+sources: [docs/consumer/ai-context.md#deep-design-token-system, docs/consumer/reference-doc.md#cli-token-inspection]
+---
+
+# `mythik tokens` — CLI inspection
+
+Shows the full resolved token set for debugging and verifying what DNA
+generates before applying to a spec.
+
+## Usage
+
+```bash
+mythik tokens --dna '{"primary":"#0D9488","roundness":0.7}' --json
+```
+
+## Output
+
+JSON tree of all resolved tokens (colors, shape, typography, spacing,
+elevation, motion, opacity, identity). Useful for:
+
+- Verifying what DNA generates before applying.
+- Debugging unexpected resolved values.
+- Comparing two DNA settings side by side.
+
+## Related concepts
+
+- [[@concept-dna-seeds]]
+- [[@concept-token-system]]
+- [[@cli-overview]]
+- [[@cli-tokens]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Deep Design Token System → CLI inspection`
+- `docs/consumer/reference-doc.md § CLI Token Inspection`

package/docs/wiki/compiled/concept-component-variants.md

@@ -0,0 +1,89 @@
+---
+id: concept-component-variants
+title: Component variants — `tokens.components.{type}.{variant}`
+kind: concept
+sources: [docs/consumer/ai-context.md#component-variants, docs/consumer/reference-doc.md#component-variants]
+---
+
+# Component variants
+
+Token-driven component styling. Define variant definitions in
+`tokens.components.{primitiveType}.{variantName}`. The engine applies
+style, hover, active, focus, transition, animations automatically.
+
+## Defining
+
+```json
+"tokens": {
+  "components": {
+    "button": {
+      "primary": {
+        "style": { "backgroundColor": "$colors.primary", "color": "#FFF", "borderRadius": "$shape.radius.md", "padding": "10px 22px", "fontWeight": 700 },
+        "hover": { "scale": 1.05, "y": -1 },
+        "active": { "scale": 0.95 },
+        "transition": { "duration": 0.15 }
+      },
+      "danger": {
+        "style": { "backgroundColor": "$colors.error", "color": "#FFF" },
+        "hover": { "scale": 1.03 }
+      }
+    },
+    "box": {
+      "card": {
+        "style": { "backgroundColor": "$colors.surface", "borderRadius": "$shape.radius.lg", "padding": 16, "boxShadow": "$shadow.md" },
+        "hover": { "boxShadow": "$shadow.lg", "y": -2 }
+      }
+    }
+  }
+}
+```
+
+## Using
+
+```json
+{ "type": "button", "props": { "label": "Save", "variant": "primary" } }
+{ "type": "button", "props": { "label": "Delete", "variant": "danger" } }
+{ "type": "box", "props": { "variant": "card" } }
+```
+
+`variant` is **universal** — any primitive can use it when defined in
+`tokens.components`.
+
+## Supported variant fields
+
+`style`, `hover`, `active`, `focus`, `transition`, `animations`.
+
+## `$path` references
+
+String values starting with `$` reference tokens. Resolved against the
+**active** token tree (with dark mode applied):
+
+- `"$colors.primary"` → `"#0D9488"`
+- `"$shape.radius.md"` → `12`
+- `"$elevation.lg"` → CSS boxShadow string
+
+Legacy paths (`$radius.md`, `$shadow.lg`) still work for backward compat.
+
+## Merge precedence
+
+Variant is base, element-level overrides — same as CSS class + inline
+override. Hover merges per-key (variant's `scale: 1.05` + element's
+`rotate: 5` both apply).
+
+## Constraints / Anti-patterns
+
+- **Place `variant` in `props`**, not as a top-level field. Top-level is
+  silently ignored. See [[@antipattern-element-variant-top-level]].
+
+## Related concepts
+
+- [[@concept-token-system]]
+- [[@concept-templates]]
+- [[@concept-templates-vs-variants]]
+- [[@concept-path-references]]
+- [[@concept-animation-cascade]] — variant level
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Component Variants`
+- `docs/consumer/reference-doc.md § Component Variants` + rule 97

package/docs/wiki/compiled/concept-cross-tab-sync.md

@@ -0,0 +1,35 @@
+---
+id: concept-cross-tab-sync
+title: Cross-tab synchronization
+kind: concept
+sources: [docs/consumer/reference-doc.md#cross-tab-synchronization]
+---
+
+# Cross-tab synchronization
+
+Auth events are automatically synchronized across browser tabs. **No
+configuration needed** — automatic when auth is configured.
+
+## Events
+
+| Event | Trigger | Effect on other tabs |
+|---|---|---|
+| `SIGNED_IN` | Login completes | Other tabs can restore session from persistence |
+| `SIGNED_OUT` | Logout | All tabs clear session and redirect to loginScreen |
+| `TOKEN_REFRESHED` | Token refresh completes | Other tabs pick up new refresh token |
+| `SESSION_EXPIRED` | Refresh fails | All tabs clear session |
+
+## Mechanism
+
+- **Primary**: BroadcastChannel API (97%+ browser support).
+- **Fallback**: localStorage `storage` events for legacy browsers.
+
+## Related concepts
+
+- [[@concept-auth-config]]
+- [[@concept-session-persistence]]
+- [[@action-login]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § Cross-Tab Synchronization`

package/docs/wiki/compiled/concept-css-vs-motion.md

@@ -0,0 +1,46 @@
+---
+id: concept-css-vs-motion
+title: CSS vs Motion — auto-detection
+kind: concept
+sources: [docs/consumer/ai-context.md#interactive-states--animations, docs/consumer/reference-doc.md#interactive-states]
+---
+
+# CSS vs Motion — auto-detection
+
+The framework chooses CSS pseudo-classes or Motion wrapper based on
+prop names automatically. No manual choice needed.
+
+## Rule
+
+If `hover` / `active` / `focus` contains any of these **6 transform
+properties** → Motion wrapper:
+
+`scale`, `scaleX`, `scaleY`, `rotate`, `x`, `y`
+
+Everything else (color, backgroundColor, boxShadow, opacity, etc.) → CSS
+`:hover` / `:active` / `:focus-visible` pseudo-classes (no wrapper, no
+extra DOM node).
+
+## CSS hover only works on
+
+`box`, `text`, `stack`, `grid`, `scroll`, `button`, `touchable`, `table`.
+Other types silently ignore CSS hover. `mythik validate` catches this
+(rule 14).
+
+## Why this matters
+
+CSS pseudo-classes are zero-overhead — no React state, no DOM wrapping.
+Motion-driven transforms need a wrapper component to interpolate.
+Mixing both works fine — properties that match Motion go through the
+wrapper; the rest are CSS.
+
+## Related concepts
+
+- [[@concept-interactive-states]]
+- [[@concept-animations-engine]] — animation engine alternative
+- [[@antipattern-overflow-hidden-with-shadow]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Interactive States & Animations`
+- `docs/consumer/reference-doc.md § Interactive States → CSS vs Motion`

package/docs/wiki/compiled/concept-custom-detection-pattern.md

@@ -0,0 +1,49 @@
+---
+id: concept-custom-detection-pattern
+title: Custom-detection pattern (preset → "custom" on edit)
+kind: concept
+sources: [docs/consumer/reference-doc.md#rule-170]
+---
+
+# Custom-detection pattern
+
+When the user modifies any token-related control individually, the preset
+dropdown should switch back to "Custom" so they know they've left the
+preset.
+
+## Pattern
+
+Every control that modifies tokens should include in its `on:change` array:
+
+```json
+{ "action": "setState", "params": { "statePath": "/ui/currentPreset", "value": "custom" } }
+```
+
+## Example — DNA roundness slider
+
+```json
+{ "type": "slider",
+  "props": { "value": { "$bindState": "/dna/roundness" }, "min": 0, "max": 100 },
+  "on": { "change": [
+    { "action": "updateTokens", "params": { "dna": { "roundness": { "$state": "/dna/roundness" } } } },
+    { "action": "setState", "params": { "statePath": "/ui/currentPreset", "value": "custom" } }
+  ]}
+}
+```
+
+## Why `applyPreset 'custom'` is a no-op
+
+`applyPreset` with `preset: 'custom'` is a silent no-op (not a real
+preset). This means clicking "Custom" in the dropdown doesn't fire any
+token change — only the dropdown indicator updates.
+
+## Related concepts
+
+- [[@concept-preset-dropdown-pattern]]
+- [[@action-apply-preset]]
+- [[@action-update-tokens]]
+- [[@concept-presets]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rule 170`

package/docs/wiki/compiled/concept-custom-element-action-props.md

@@ -0,0 +1,81 @@
+---
+id: concept-custom-element-action-props
+title: Action-chain props (consumer-supplied event handlers)
+kind: concept
+sources: [docs/consumer/ai-context-custom-elements.md#consumer-supplied-event-handlers-action-chain-props]
+---
+
+# Action-chain props (consumer-supplied event handlers)
+
+Authors often want consumers to own the action chain fired on a user
+gesture (tabs, menu items, list rows). Declare the prop as `array`, then
+reference it in the render tree's `on.<event>` as `{ "$prop": "..." }`.
+
+## Author
+
+```json
+{
+  "type": "tab-button",
+  "props": {
+    "label": { "type": "string" },
+    "onSelect": { "type": "array" }
+  },
+  "render": {
+    "type": "touchable",
+    "props": { "style": { ... } },
+    "on": { "press": { "$prop": "onSelect" } },
+    "children": [
+      { "type": "text", "props": { "content": { "$prop": "label" } } }
+    ]
+  }
+}
+```
+
+## Consumer
+
+```json
+{ "type": "tab-button",
+  "props": {
+    "label": "Egresos SAFI",
+    "onSelect": [
+      { "action": "setState", "params": { "statePath": "/filter/tipoEjecucion", "value": "1" } },
+      { "action": "setState", "params": { "statePath": "/pagination/page", "value": 0 } },
+      { "action": "fetch", "params": { "url": { "$template": "..." }, "method": "GET", "target": "/response" } }
+    ]
+  }
+}
+```
+
+## Resolution timing
+
+The renderer resolves `$prop` at the binding level **at render time**;
+inner `$state` / `$template` / `$item` inside the action chain stay
+**lazy** — they evaluate at press time with the current state.
+
+This is the correct shape for inputs, switches, tabs, and any element
+where the consumer owns "what happens on interaction".
+
+## Implementation
+
+The renderer detects the `$prop` shape at binding level and calls
+`resolveDeep` to substitute the consumer's supplied value (typically an
+action array). Any other binding shape (plain object, array of actions,
+`TransactionBinding`) is passed through verbatim — inner `$state` /
+`$template` inside binding params stay lazy so the action dispatcher
+resolves them at press time (rule 239).
+
+Eager param resolution only activates inside a `repeat` where `$item`
+binding is required for correctness.
+
+## Related concepts
+
+- [[@expression-prop]]
+- [[@concept-prop-cascade]]
+- [[@concept-element-definition]]
+- [[@concept-element-prop-definition]]
+- [[@concept-expression-timing]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-custom-elements.md § Consumer-Supplied Event Handlers`
+- `docs/consumer/reference-doc.md § rule 239`