mythik 0.0.1 → 0.1.0

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

@@ -0,0 +1,77 @@
+---
+id: concept-motion-field
+title: `motion` field (legacy Framer-Motion)
+kind: concept
+sources: [docs/consumer/ai-context.md#mountexit-animations, docs/consumer/reference-doc.md#animations]
+---
+
+# `motion` field (legacy)
+
+Legacy Framer-Motion-style mount/exit animation field. Still supported but
+**prefer `animations`** ([[@concept-animations-engine]]) for new specs —
+cross-platform, reduced-motion aware, integrates with the 5-level cascade.
+
+## Shape / Signature
+
+```json
+"motion": {
+  "initial": { "opacity": 0, "y": 20 },
+  "animate": { "opacity": 1, "y": 0 },
+  "transition": { "duration": 0.3, "ease": "easeOut" }
+}
+```
+
+## Examples
+
+Mount fade-up:
+```json
+"card": { "type": "box",
+  "motion": {
+    "initial": { "opacity": 0, "y": 20 },
+    "animate": { "opacity": 1, "y": 0 },
+    "transition": { "duration": 0.3 }
+  }
+}
+```
+
+Exit:
+```json
+"motion": {
+  "initial": { "opacity": 0 },
+  "animate": { "opacity": 1 },
+  "exit": { "opacity": 0, "y": -10 }
+}
+```
+
+Staggered children — parent defines stagger, children animate in sequence:
+```json
+"list": {
+  "type": "stack",
+  "motion": { "animate": {}, "transition": { "staggerChildren": 0.05 } },
+  "children": ["card-1", "card-2", "card-3"]
+}
+```
+
+Each child should have its own `motion.initial` / `motion.animate`.
+
+## `_motion.whileTap` / `_motion.whileHover`
+
+`_motion.whileTap` and `_motion.whileHover` forward to Framer Motion. Use
+`"Infinity"` (string) for `repeat` in JSON — renderer converts to JS
+`Infinity` (rule 78).
+
+## Migration
+
+`identity.motionEntrance` and `identity.motionHover` were REMOVED in
+plan 2 — see [[@antipattern-motion-entrance-token]] for the mapping.
+
+## Related concepts
+
+- [[@concept-animations-engine]] — preferred for new specs
+- [[@concept-animation-recipes]]
+- [[@antipattern-motion-entrance-token]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Mount/Exit Animations`
+- `docs/consumer/reference-doc.md § Animations → Motion design tokens`

package/docs/wiki/compiled/concept-mount-spec-runtime.md

@@ -0,0 +1,47 @@
+---
+id: concept-mount-spec-runtime
+title: `mountSpecRuntime` — internal mount helper
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#9-derive-and-datasources-lifecycle-v010--item-e]
+---
+
+# `mountSpecRuntime` — internal helper
+
+Internal helper (re-exported from `mythik` with `@internal` JSDoc)
+that wires `derive` + `dataSources` engines per spec mount. Called from
+`MythikRenderer` (web + RN).
+
+## Mount/unmount scope
+
+Per `MythikRenderer` instance via `useEffect` with deps `[spec, dispatcher,
+svc, fetcher]`. Spec change → unmount old runtime, mount new. Same spec
+reference → no remount.
+
+## Internal mount order
+
+1. `DeriveEngine.mount()` — sync evaluation in topological order; writes
+   derive paths to store.
+2. Subscribe `derive.onStateChange` to store.
+3. `protectionRegistry.contribute(derivePaths)` — derive paths now
+   blocked from setState.
+4. `dispatcher.registerAction(dataSources.getActionDefinition())` —
+   `refreshDataSource` available.
+5. `DataSourcesEngine.mount()` — initial fetches with skip-on-undefined-URL.
+
+## Why `@internal`
+
+Marked `@internal` in JSDoc — not for application-level use. The export
+exists so `MythikRenderer` (in `mythik-react`) can call it. **App code
+should NOT call `mountSpecRuntime` directly** — use `MythikRenderer`.
+
+## Related concepts
+
+- [[@concept-derive-datasources-mount-order]]
+- [[@concept-mythik-renderer]]
+- [[@concept-derive]]
+- [[@concept-data-sources]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 9`
+- ` § Item E`

package/docs/wiki/compiled/concept-mythik-renderer.md

@@ -0,0 +1,76 @@
+---
+id: concept-mythik-renderer
+title: `MythikRenderer` - root mount
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#9-derive-and-datasources-lifecycle-v010--item-e, docs/consumer/reference-doc.md#rules-220-224, docs/consumer/reference-doc.md#render-error-visibility]
+---
+
+# `MythikRenderer` - root mount
+
+The React entry point. Mounts the spec runtime + state subscription, owns
+the v2 `<BackgroundStack>` mount when `tokens.identity.background` is a
+`LayerBackground`, and catches thrown primitive/component render errors.
+
+## Effect ordering (load-bearing)
+
+The state-subscription `useEffect` is declared **BEFORE** the
+`mountSpecRuntime` `useEffect`. React fires effects in declaration order,
+so:
+
+1. State subscription attaches.
+2. `mountSpecRuntime` runs `deriveEngine.mount()`, which writes synchronously.
+3. The subscription captures those writes -> first-paint re-render.
+
+If you fork or reimplement `MythikRenderer`, **preserve this ordering**.
+
+## Table row dispatcher
+
+`MythikRenderer` wires table row interactions through
+`packages/react/src/runtime/row-dispatcher.ts`. The shared
+`createRowDispatcher` helper writes the clicked row to `/ui/selectedRow`
+BEFORE dispatching column actions or direct `onRowClick` ActionBinding(s).
+See [[@path-ui-selected-row]].
+
+## Render error boundary
+
+`MythikRenderer` catches thrown primitive/component render exceptions with a
+renderer-level error boundary. In development with
+`security.exposeErrors !== false`, it shows a visible overlay with the
+message and component stack. In production, or with
+`security.exposeErrors: false`, it renders a neutral placeholder without
+details. The boundary resets when the `spec` prop changes. See
+[[@concept-render-error-visibility]].
+
+## v2 LayerBackground mount
+
+When `tokens.identity.background` `isLayerBackground`, the renderer wraps
+the rendered tree in a positioned container with `<BackgroundStack>` as
+a sibling INSIDE a stacking context (`isolation: isolate`). Reads from
+`/tokens/resolved` so preset swaps + playground updates trigger fresh
+reads. See [[@concept-background-stack]].
+
+## Props
+
+- `spec` - the spec to render
+- `instance` - `createMythik` instance
+- `autoSkeleton={false}` - disable auto-skeleton entirely
+- `autoDeviceContext={false}` - disable device-context auto-tracking
+- `storage={...}` - StorageAdapter
+- `storageConfig={...}` - global allowedTypes / maxSize
+- `exportAdapters={{ xlsx, pdf }}` - register custom export formats
+
+## Related concepts
+
+- [[@concept-mount-spec-runtime]]
+- [[@concept-derive-datasources-mount-order]]
+- [[@concept-background-stack]]
+- [[@path-ui-selected-row]]
+- [[@concept-render-error-visibility]]
+- [[@concept-skeleton-auto]]
+- [[@path-ui-device]]
+- [[@concept-storage-adapter]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md` - section 9
+- `docs/consumer/reference-doc.md` - rules 220, 224, 251

package/docs/wiki/compiled/concept-navigation-dirty-guard.md

@@ -0,0 +1,23 @@
+---
+id: concept-navigation-dirty-guard
+title: Navigation dirty guard
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md, docs/consumer/reference-doc.md]
+---
+
+# Navigation dirty guard
+
+`navigation.editorSessionGuard` protects dirty editor sessions during app navigation.
+
+When navigation would leave a dirty editor session, the app engine writes pending guard state under `/ui/navigationGuard/pending` by default. Consumer JSON renders the confirmation UI from that state.
+
+Canonical actions:
+
+- `navigationGuardCancel` - clear pending guard state and stay on the current screen.
+- `navigationGuardSaveAndProceed` - save pending dirty sessions, then resume navigation only if they become clean.
+- `navigationGuardProceed` - low-level retry after sessions are already clean; it does not save or discard.
+- `navigationGuardDiscardAndProceed` - discard pending dirty sessions through the mounted editor engine, then resume.
+
+Custom `pendingPath` values must stay under non-reserved `/ui/<segment>` paths.
+
+Related: [[@concept-editor-sessions]], [[@concept-editor-save]].

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

@@ -0,0 +1,75 @@
+---
+id: concept-navigation
+title: Navigation config
+kind: concept
+sources: [docs/consumer/ai-context.md#appspec--navigation, docs/consumer/reference-doc.md#app-spec--screen-outlet]
+---
+
+# Navigation config
+
+The `navigation` block in AppSpec defines navigation type, initial screen,
+breadcrumb mode, sidebar menu order, and auth.
+
+## Shape / Signature
+
+```json
+"navigation": {
+  "type": "sidebar",
+  "initialScreen": "dashboard",
+  "breadcrumb": "history",
+  "menu": ["dashboard", "reports", "settings"],
+  "auth": { ... }
+}
+```
+
+## Properties
+
+| Property | Type | Required | Purpose |
+|---|---|---|---|
+| `type` | `"sidebar"` | yes | Navigation style |
+| `initialScreen` | string | yes | Default screen on app load |
+| `breadcrumb` | string | no | `"history"` (nav stack), `"hierarchy"` (parent chain), `"none"` |
+| `menu` | string[] | no | Sidebar screen order. Omit to show all. Login always excluded |
+| `auth` | object | no | Auth config (loginScreen, protectedScreens, roleAccess, etc.) |
+
+## Breadcrumb modes
+
+| Mode | Behavior |
+|---|---|
+| `"history"` | Follows navigation stack |
+| `"hierarchy"` | Follows `parent` chain from current screen to root |
+| `"none"` | No auto-computed breadcrumb |
+
+## Sidebar nav
+
+Built from `/app/screens` (auto-generated, filtered by role). Use a
+`repeat` on `/app/screens` to render nav items — each has `id`, `label`,
+`icon`.
+
+```json
+"nav-menu": {
+  "type": "stack",
+  "repeat": { "statePath": "/app/screens", "key": "id" },
+  "children": ["nav-item"]
+},
+"nav-item": {
+  "type": "touchable",
+  "on": { "press": { "action": "navigateScreen", "params": { "screen": { "$item": "id" } } } },
+  "children": ["nav-icon", "nav-label"]
+}
+```
+
+## Related concepts
+
+- [[@concept-app-spec]]
+- [[@concept-screen-definition]]
+- [[@concept-app-auto-state-paths]] — `/app/screens`, `/navigation/*`
+- [[@concept-role-access]]
+- [[@action-navigate]]
+- [[@concept-auth-config]]
+- [[@path-app-screens]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § AppSpec & Navigation → Navigation Properties`
+- `docs/consumer/reference-doc.md § App Spec & Screen Outlet`

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

@@ -0,0 +1,35 @@
+---
+id: concept-package-layout
+title: Package layout
+kind: concept
+sources: [docs/consumer/ai-context.md, docs/consumer/WHERE-TO-LOOK.md]
+---
+
+# Package layout
+
+## Public packages
+
+| Package | Purpose |
+|---|---|
+| `mythik` | Browser-safe core. State, expressions, validation, renderer engine, design, auth, data, security, and browser-safe spec stores |
+| `mythik/server` | Node-only spec stores: `FileSpecStore`, `SqlServerSpecStore`, and versioned/environment variants |
+| `mythik-react` | React host, renderer, and web primitives |
+| `mythik-cli` | CLI package; installs the `mythik` command |
+| `mythik-cli/api` | Programmatic CLI API: `runPush`, `runPatch`, `runLint`, `parsePatchInput`, and types |
+| `mythik-server` | Express server runtime for ApiSpecs |
+
+React Native work lives in the repository as a preview track and is not part of the initial npm publish surface.
+
+## Browser vs server core entries
+
+The default `mythik` entry is browser-safe by construction. Node-only stores live behind the `mythik/server` subpath so browser bundles do not pull `fs`, `mssql`, or other Node-only dependencies.
+
+## Programmatic CLI API
+
+Use `mythik-cli/api` instead of deep imports from `dist`. This keeps CLI automation on the same validated path as the binary.
+
+## Published artifacts
+
+Packages ship compiled `dist/` output and type declarations. Use `.d.ts` for type-shape questions. For behavior questions, read source from the GitHub repo or an unpacked tarball.
+
+Related: [[@concept-public-package-names]], [[@concept-spec-stores-catalog]], [[@cli-programmatic-api]], [[@concept-where-to-look]].

package/docs/wiki/compiled/concept-path-references.md

@@ -0,0 +1,53 @@
+---
+id: concept-path-references
+title: `$path` references inside variants
+kind: concept
+sources: [docs/consumer/reference-doc.md#path-token-references]
+---
+
+# `$path` references inside variants
+
+Inside variant style definitions and `ResolvedVariant.animations`, string
+values starting with `$` reference tokens. Resolved against the active
+token tree (with dark mode + identity already applied).
+
+## Examples
+
+```json
+"$colors.primary"           // → "#0D9488"
+"$shape.radius.md"          // → 12
+"$elevation.lg"             // → CSS boxShadow string
+"$typography.weight.bold"   // → 700
+"$spacing.scale.md"         // → 16
+```
+
+## Legacy paths
+
+`$radius.md`, `$shadow.lg` still work for backward compat.
+
+## Why this works for dark mode
+
+When dark mode changes `colors.surface` to `#1E293B`, any variant using
+`$colors.surface` gets the dark value automatically — no separate dark
+variant needed. The `$path` resolution happens after token tree merge.
+
+## Resolution scope (`ResolvedVariant.animations`)
+
+`resolveTokenRefs` is **one-level-deep** for animations: nested structures
+(`mount: { recipe: '$recipes.X' }`) pass through unchanged — downstream
+animation runtime layers handle deeper resolution. Only top-level trigger
+values resolve `$path` references (e.g., `animations: '$animations.interactive'`).
+
+Expression-system scope: only `$path` (token-tree) lookups are recognized
+here. `$prop`, `$state`, `$cond` are template-layer concepts.
+
+## Related concepts
+
+- [[@concept-component-variants]]
+- [[@concept-token-system]]
+- [[@expression-token]] — distinct mechanism (spec-level)
+- [[@concept-auto-dark-mode]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § $path Token References` + rule 215

package/docs/wiki/compiled/concept-pattern-primitives.md

@@ -0,0 +1,54 @@
+---
+id: concept-pattern-primitives
+title: Pattern primitives (background `pattern` kind)
+kind: concept
+sources: [docs/consumer/reference-doc.md#rules-174-179]
+---
+
+# Pattern primitives
+
+6 curated pattern kinds + `custom-svg` escape hatch. Each emits an
+`<pattern>` SVG fragment for `BackgroundLayer`.
+
+## Curated kinds
+
+`grid`, `dots`, `diagonal`, `iso`, `crosshatch`, `chevron`.
+
+## Common params
+
+| Param | Used by | Description |
+|---|---|---|
+| `spacing` | all | Distance between repeats |
+| `thickness` | all | Line/dot thickness |
+| `color` | all | Pattern color |
+| `angle` | diagonal, iso, crosshatch | Rotation degrees |
+| `dotRadius` | dots only | Dot radius |
+
+## Custom-svg escape hatch
+
+```json
+{ "kind": "custom-svg", "shapes": "<circle cx=\"5\" cy=\"5\" r=\"2\"/>", "tileSize": 10 }
+```
+
+`sanitizeSVGShapes` uses regex pre-strip + DOMPurify allowlist:
+- **Allowed**: circle, rect, path, line, polygon, polyline, ellipse,
+  g, defs, gradients + geometric attrs.
+- **Rejected**: `<script>`, `<foreignObject>`, `<use href>`, `on*` events,
+  `javascript:` URLs.
+
+Cross-platform safe (isomorphic-dompurify).
+
+## Example
+
+```json
+{ "type": "pattern", "kind": "grid", "spacing": 24, "thickness": 1, "color": "rgba(0,0,0,0.05)" }
+```
+
+## Related concepts
+
+- [[@concept-background-layer-kinds]]
+- [[@concept-layer-background]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rules 174, 179`

package/docs/wiki/compiled/concept-preset-dropdown-pattern.md

@@ -0,0 +1,52 @@
+---
+id: concept-preset-dropdown-pattern
+title: Preset dropdown pattern (`$bindState` + `$state`)
+kind: concept
+sources: [docs/consumer/ai-context.md#rule-62, docs/consumer/reference-doc.md#rule-169]
+---
+
+# Preset dropdown pattern
+
+Pattern for letting users pick a preset from a select. **Use `$bindState`
+on `value` and `$state` in the action params** — `$event` does NOT
+exist as an expression.
+
+## Pattern
+
+```json
+{ "type": "select",
+  "props": {
+    "options": { "$state": "/presets/available" },
+    "value": { "$bindState": "/ui/currentPreset" }
+  },
+  "on": { "change": [
+    { "action": "applyPreset", "params": { "preset": { "$state": "/ui/currentPreset" } } }
+  ]}
+}
+```
+
+## Why this works
+
+`$bindState` writes the new value to `/ui/currentPreset` BEFORE the
+`on.change` chain runs. The action then reads the just-written value via
+`$state`. No `$event` needed.
+
+## Constraints / Anti-patterns
+
+- **`$event` is NOT a valid expression.** Do NOT use
+  `{ "$event": "value" }` in action params. See
+  [[@antipattern-event-expression]].
+
+## Related concepts
+
+- [[@expression-bindstate]]
+- [[@action-apply-preset]]
+- [[@concept-presets]]
+- [[@concept-custom-detection-pattern]]
+- [[@antipattern-event-expression]]
+- [[@path-presets-available]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § rule 62`
+- `docs/consumer/reference-doc.md § rules 61, 169`

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

@@ -0,0 +1,49 @@
+---
+id: concept-presets
+title: Presets — `PresetDefinition`
+kind: concept
+sources: [docs/consumer/ai-context.md#presets-system, docs/consumer/reference-doc.md#presets-system]
+---
+
+# Presets — `PresetDefinition`
+
+Curated DNA + Identity snapshots that transform the entire look of an app
+with a single action. The framework provides the **tools** (contract,
+registration, application); preset definitions live **outside core** (in
+the app, a file, or a future API like mythik.dev).
+
+## Interface
+
+```ts
+interface PresetDefinition {
+  id: string;           // 'startup-saas'
+  name: string;         // 'Startup SaaS'
+  description: string;  // 'Clean, professional, outlined'
+  tags?: string[];      // ['professional', 'minimal']
+  tokens: {
+    dna: DnaSeed;
+    identity: IdentityConfig;
+  };
+}
+```
+
+## Architectural principle
+
+The framework provides tools, not opinions. Presets live in
+consumer/application code; framework supplies registration + activation
+infrastructure.
+
+## Related concepts
+
+- [[@concept-register-presets]]
+- [[@action-apply-preset]]
+- [[@concept-preset-dropdown-pattern]]
+- [[@concept-custom-detection-pattern]]
+- [[@concept-dna-seeds]]
+- [[@concept-identity-overview]]
+- [[@path-presets-available]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Presets System`
+- `docs/consumer/reference-doc.md § Presets System` + rule 167

package/docs/wiki/compiled/concept-primitive-prop-schemas.md

@@ -0,0 +1,53 @@
+---
+id: concept-primitive-prop-schemas
+title: `PRIMITIVE_PROP_SCHEMAS` — primitive metadata
+kind: concept
+sources: [, docs/consumer/ai-context-runtime-semantics.md#13-column-actions-lazy-resolution-at-press-time]
+---
+
+# `PRIMITIVE_PROP_SCHEMAS`
+
+Self-describing primitive metadata exported from `mythik`. Each
+primitive declares its valid prop names AND prop subtrees that hold action
+bindings (resolved at press time, not render time).
+
+## Shape (v0.1+)
+
+```ts
+import { PRIMITIVE_PROP_SCHEMAS, type PrimitiveSchema } from 'mythik';
+
+PRIMITIVE_PROP_SCHEMAS.table
+// → { validProps: ['data', 'columns', 'style', ...], lazyActionPaths: ['columns[].actions[].onPress', 'onRowClick'] }
+```
+
+## Use cases
+
+- **Spec validation** — `mythik validate` checks prop names against
+  `validProps` (Levenshtein "did you mean?" suggestions for typos).
+- **Lazy action paths** — engine consults `lazyActionPaths` to keep
+  matched subtrees raw at render; the row dispatcher resolves them at
+  press/click time with `/ui/selectedRow` context. Table covers both
+  `columns[].actions[].onPress` and `onRowClick`. See
+  [[@concept-expression-timing]].
+
+## Migration from pre-v0.1
+
+The shape changed from `string[]` to `{ validProps, lazyActionPaths }`:
+
+```ts
+// Before
+const validProps = PRIMITIVE_PROP_SCHEMAS.table; // ['data', 'columns', ...]
+
+// After
+const validProps = PRIMITIVE_PROP_SCHEMAS.table.validProps;
+```
+
+## Related concepts
+
+- [[@concept-expression-timing]]
+- [[@cli-validate]] — uses this for prop validation
+
+## Sources (raw)
+
+- `` — § Breaking: `PRIMITIVE_PROP_SCHEMAS` shape
+- `docs/consumer/ai-context-runtime-semantics.md § 1.3` — lazy mechanism

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

@@ -0,0 +1,49 @@
+---
+id: concept-primitives-overview
+title: Primitives — overview
+kind: concept
+sources: [docs/consumer/ai-context.md#primitives, docs/consumer/ai-context-primitives.md]
+---
+
+# Primitives — overview
+
+37 built-in visual building blocks. Each accepts the standard set of
+common props (`style`, `visible`, `permission`) plus per-type-specific
+props.
+
+## Categories
+
+| Category | Primitives |
+|---|---|
+| Layout | [[@primitive-box]], [[@primitive-text]], [[@primitive-image]], [[@primitive-icon]], [[@primitive-stack]], [[@primitive-grid]], [[@primitive-scroll]], [[@primitive-divider]], [[@primitive-spacer]] |
+| Form | [[@primitive-input]], [[@primitive-textarea]], [[@primitive-select]], [[@primitive-checkbox]], [[@primitive-toggle]], [[@primitive-slider]] |
+| Interaction | [[@primitive-button]], [[@primitive-touchable]], [[@primitive-list]] |
+| Overlays | [[@primitive-modal]], [[@primitive-drawer]], [[@primitive-tabs]], [[@primitive-accordion]], [[@primitive-wizard]], [[@primitive-screen]], [[@primitive-screen-outlet]] |
+| Charts | [[@primitive-bar-chart]], [[@primitive-line-chart]], [[@primitive-pie-chart]], [[@primitive-area-chart]], [[@primitive-table]], [[@primitive-kanban-board]] |
+| Special | [[@primitive-file-upload]], [[@primitive-camera]], [[@primitive-signature]], [[@primitive-audio-player]], [[@primitive-skeleton]], [[@primitive-toast-container]] |
+
+## Common props (all primitives)
+
+- `style` — CSS object
+- `visible` — boolean expression
+- `permission` — `{ visible, editable, readonly }` per role
+
+## Tokens are project-defined
+
+No framework defaults for design tokens. If no tokens are declared, use
+direct CSS values. See [[@concept-token-system]].
+
+## Spatial primitive
+
+- [[@primitive-spatial-map]] - generic SVG/data-first map for spatial layouts and editors.
+
+## Related concepts
+
+- [[@concept-element-properties]]
+- [[@concept-primitive-prop-schemas]] — `PRIMITIVE_PROP_SCHEMAS`
+- [[@concept-token-system]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Primitives`
+- `docs/consumer/ai-context-primitives.md` (full)