mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/concept-spec-stores-catalog.md

@@ -0,0 +1,66 @@
+---
+id: concept-spec-stores-catalog
+title: Spec stores catalog
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#54-specstore-layering--save-vs-saveversion-vs-cli-patch]
+---
+
+# Spec stores catalog
+
+## Browser-safe (`mythik`)
+
+| Store | Purpose |
+|---|---|
+| `MemorySpecStore` | In-memory; testing |
+| `MemoryVersionedSpecStore` | + version history |
+| `MemoryEnvironmentStore` | + env promotions |
+| `SupabaseSpecStore` | Supabase (REST API; no `@supabase/supabase-js` dep) |
+| `SupabaseVersionedSpecStore` | + version history |
+| `SupabaseEnvironmentStore` | + env promotions |
+
+## Node-only (`mythik/server`)
+
+| Store | Purpose |
+|---|---|
+| `FileSpecStore` | Local filesystem (`fs`) |
+| `SqlServerSpecStore` | SQL Server (via `mssql`) |
+| `SqlServerVersionedSpecStore` | + version history |
+| `SqlServerEnvironmentStore` | + env promotions |
+
+## Why split
+
+Pre-v0.1.0 shape pulled `mssql` (Node-only) and `fs` into any browser
+bundle that imported `mythik`. v0.1.0 structural split makes
+`mythik` browser-safe **by construction** — no bundler stubs
+
+## Imports
+
+```ts
+// Browser-safe
+import { SupabaseSpecStore, MemorySpecStore } from 'mythik';
+
+// Node-only
+import { SqlServerSpecStore, FileSpecStore } from 'mythik/server';
+```
+
+## Configurable table names
+
+Default `'screens'`. Override via constructor — see
+[[@concept-storage-custom-names]].
+
+```ts
+new SqlServerSpecStore({ ..., table: 'api_specs' })
+new SupabaseSpecStore({ ..., table: 'api_specs' })
+```
+
+## Related concepts
+
+- [[@concept-spec-store-interface]]
+- [[@concept-versioned-store]]
+- [[@concept-environment-store]]
+- [[@concept-package-layout]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 5.4` (last paragraph)
+- ` § Breaking: Node-only spec stores moved`

package/docs/wiki/compiled/concept-spec-structure.md

@@ -0,0 +1,94 @@
+---
+id: concept-spec-structure
+title: Spec Structure (Flat Tree)
+kind: concept
+sources: [docs/consumer/ai-context.md#spec-structure, docs/consumer/reference-doc.md#spec-structure-flat-tree]
+---
+
+# Spec Structure (Flat Tree)
+
+Every screen is a JSON Spec with three top-level fields: a `root` ID (string),
+a flat `elements` map (ID → element definition), and optional `initialActions`
+that fire on spec mount. Children are referenced by ID — never inlined. This
+flat shape keeps every element addressable by JSON Pointer for patching and
+makes the renderer's expansion logic mechanical.
+
+## Shape / Signature
+
+```json
+{
+  "root": "main-layout",
+  "initialActions": [
+    { "action": "fetch", "params": { "url": "/api/data", "target": "/items" } }
+  ],
+  "elements": {
+    "main-layout": {
+      "type": "stack",
+      "props": { "direction": "vertical" },
+      "children": ["header", "content"]
+    },
+    "header": {
+      "type": "text",
+      "props": { "content": "Hello", "variant": "heading" }
+    },
+    "content": {
+      "type": "box",
+      "children": ["field1"]
+    }
+  }
+}
+```
+
+## Top-Level Properties
+
+| Property | Type | Purpose |
+|---|---|---|
+| `root` | string | ID of the root element |
+| `elements` | object | Flat map of element ID → definition |
+| `initialActions` | ActionBinding[] | Actions on spec mount (e.g., fetch data) |
+| `derive` | object | Auto-computed reactive state |
+| `forms` | object | Declarative form validation |
+| `dataSources` | object | Reactive data fetching |
+| `templates` | object | Reusable element definitions |
+
+## Examples
+
+Minimal spec:
+```json
+{ "root": "page", "elements": { "page": { "type": "text", "props": { "content": "Hello" } } } }
+```
+
+Spec with mount-time data load:
+```json
+{
+  "root": "list",
+  "initialActions": [{ "action": "fetch", "params": { "url": "/api/items", "target": "/items" } }],
+  "elements": {
+    "list": { "type": "stack", "repeat": { "statePath": "/items", "key": "id" }, "children": ["row"] },
+    "row": { "type": "text", "props": { "content": { "$item": "name" } } }
+  }
+}
+```
+
+## Constraints / Anti-patterns
+
+- **Flat tree only** — children are string IDs, never inline objects. Inline
+  children break patching and break expression scope tracking.
+- **Field IDs must be unique within the spec.** Use descriptive names
+  (`patient-name`, `submit-btn`). Duplicate keys silently overwrite during
+  JSON parse.
+- **Use arrays for ordered collections** — `children` is an array, never an
+  object. Object-keyed children would lose order in JSONB storage.
+
+## Related concepts
+
+- [[@concept-element-properties]] — full element property catalogue
+- [[@concept-spec-types]] — Spec vs ApiSpec vs AppSpec discrimination
+- [[@concept-initial-actions]] — `initialActions` semantics
+- [[@concept-element-key]] — dynamic remount via `key`
+- [[@concept-templates]] — reusable element definitions
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md` — "Spec Structure" section
+- `docs/consumer/reference-doc.md` — "Spec Structure (Flat Tree)"

package/docs/wiki/compiled/concept-spec-types.md

@@ -0,0 +1,76 @@
+---
+id: concept-spec-types
+title: Spec Types — Screen vs App vs Api
+kind: concept
+sources: [docs/consumer/ai-context.md#spec-structure, docs/consumer/ai-context.md#appspec--navigation, docs/consumer/ai-context-api.md#apispec-server, docs/consumer/reference-doc.md#app-spec--screen-outlet]
+---
+
+# Spec Types — Screen vs App vs Api
+
+Mythik distinguishes three top-level document types. The framework picks the
+right handler from the document's shape: **Screen specs** (no `type` field) are
+single-screen UI; **AppSpecs** declare `type: "app"` for multi-screen apps with
+sidebar/auth/shared state; **ApiSpecs** declare `type: "api"` for declarative
+backend APIs. The CLI auto-detects which kind it's operating on.
+
+## Shape / Signature
+
+Screen spec — no `type`:
+```json
+{ "root": "...", "elements": { "...": "..." } }
+```
+
+AppSpec:
+```json
+{ "type": "app", "name": "...", "navigation": { ... }, "screens": { ... }, "layout": { ... } }
+```
+
+ApiSpec:
+```json
+{ "type": "api", "name": "...", "auth": { ... }, "catalogs": { ... }, "endpoints": { ... } }
+```
+
+## Per-type discrimination
+
+| Field | Screen | App | Api |
+|---|---|---|---|
+| `type` | absent | `"app"` | `"api"` |
+| Root layout | `root` + `elements` (top-level) | `layout.root` + `layout.elements` | n/a |
+| Children of `screens`? | n/a | yes | n/a |
+| Served to browser? | yes | yes (with auth filtering) | **never** (404) |
+| CLI detection | auto | auto | auto |
+
+## Examples
+
+Inspecting different doctypes:
+```bash
+mythik manifest task-manager      # Screen — element tree
+mythik manifest app-demo          # App — layout + screens + tokens
+mythik manifest ejecucion-api     # Api — catalogs + endpoints + auth
+```
+
+## Constraints / Anti-patterns
+
+- **Api specs are never served to the browser.** `GET /api/screens/:id` and
+  `GET /api/app/:id` return 404 for documents with `type: "api"`. This
+  prevents disclosure of table names, SQL queries, and auth config.
+- **AppSpec patches use `/layout/elements/`**, not `/elements/`.
+  Screen-spec elements live at `/elements/{id}`; AppSpec layout elements
+  live at `/layout/elements/{id}`.
+- Validation is per-doctype: AppSpec validates cross-references (screen
+  existence, roleAccess consistency); ApiSpec validates endpoints/catalogs;
+  Screen specs validate element trees + expressions.
+
+## Related concepts
+
+- [[@concept-spec-structure]] — Screen-spec details
+- [[@concept-app-spec]] — AppSpec details
+- [[@concept-api-spec]] — ApiSpec details
+- [[@cli-app-spec]] — CLI commands for AppSpecs
+- [[@concept-spec-engine]] — patch/validate/save flow
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § AppSpec & Navigation` + `§ ApiSpec`
+- `docs/consumer/ai-context-api.md § ApiSpec (Server)`
+- `docs/consumer/reference-doc.md § App Spec & Screen Outlet`

package/docs/wiki/compiled/concept-state-change-animation.md

@@ -0,0 +1,73 @@
+---
+id: concept-state-change-animation
+title: `stateChange` — state-driven animation
+kind: concept
+sources: [docs/consumer/reference-doc.md#animation-system--infrastructure-plan-2-2026-04-18]
+---
+
+# `stateChange` — state-driven animation
+
+Trigger an animation when a watched state path changes. Single-fire — for
+repeating state-driven behavior, use `ambient` with conditional enablement
+via `$cond`.
+
+## Shape / Signature
+
+```json
+"animations": {
+  "stateChange": {
+    "watch": "/cart/count",
+    "on": "increase",
+    "recipe": "pop",
+    "duration": 300
+  }
+}
+```
+
+## `on` patterns
+
+| Pattern | Triggers when |
+|---|---|
+| `"change"` | Value changes (any direction) |
+| `"increase"` | Numeric increase |
+| `"decrease"` | Numeric decrease |
+| `"truthy"` | Becomes truthy |
+| `"falsy"` | Becomes falsy |
+| `{ "equals": <value> }` | Becomes equal to specific value |
+
+## Field reference
+
+```json
+{
+  "watch": "<state-path>",
+  "on"?: "<pattern>",
+  "recipe"?: "<recipe-name>",
+  "keyframes"?: [<KeyframeSnapshot>],
+  "duration": <ms>,
+  "easing"?: "<easing>",
+  "debounce"?: <ms>
+}
+```
+
+Must supply either `recipe` or `keyframes`.
+
+## Symmetric-keyframe convention
+
+`stateChange` animations should return to baseline or the transient clear
+will cause a visible snap. Recipes are designed to return to start state
+within the duration window.
+
+## Constraints
+
+- Single-fire semantics (no `iterations` / `direction`).
+- For repeating behavior, use `ambient` with conditional enablement.
+
+## Related concepts
+
+- [[@concept-animation-triggers]]
+- [[@concept-animations-engine]]
+- [[@concept-keyframe-snapshot]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rule 189`

package/docs/wiki/compiled/concept-state-policies.md

@@ -0,0 +1,44 @@
+---
+id: concept-state-policies
+title: State policies — preserve / reset / reload
+kind: concept
+sources: [docs/consumer/ai-context.md#state-policies, docs/consumer/reference-doc.md#state-policies]
+---
+
+# State policies
+
+Per-screen state behavior on navigation. Set via `screens.<id>.statePolicy`.
+
+| Policy | On leave | On return | Use for |
+|---|---|---|---|
+| `preserve` | Keep state | Restore | Lists, dashboards |
+| `reset` | Clear | Fresh `initialState` | Create forms |
+| `reload` | Clear | Re-execute `initialActions` | Always-fresh data |
+
+## Examples
+
+Login screen with `reset` (credentials clear on every visit):
+```json
+"login": { "label": "Login", "icon": "sign-in", "statePolicy": "reset" }
+```
+
+Dashboard preserved across navigation:
+```json
+"dashboard": { "label": "Dashboard", "icon": "chart-bar", "statePolicy": "preserve" }
+```
+
+Admin report — always fresh:
+```json
+"report": { "label": "Daily Report", "icon": "file-text", "statePolicy": "reload" }
+```
+
+## Related concepts
+
+- [[@concept-screen-definition]]
+- [[@pattern-login-screen]] — typical use of `reset`
+- [[@concept-initial-actions]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § AppSpec & Navigation → State Policies`
+- `docs/consumer/reference-doc.md § State Policies`

package/docs/wiki/compiled/concept-state-protection.md

@@ -0,0 +1,51 @@
+---
+id: concept-state-protection
+title: State protection — protected paths
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#2-framework-reserved-state-paths, docs/consumer/ai-context-runtime-semantics.md#53-derive-evaluation-order]
+---
+
+# State protection — protected paths
+
+Several state paths are **read-only** to consumer specs. The `StateGuard`
+blocks `setState` writes to these paths, and the validator catches
+`setState → protected path` at load time. Defense in depth.
+
+## Protected categories
+
+- **Derive paths** — every entry in `spec.derive` is registered as
+  protected. See [[@concept-derive]] + [[@concept-derive-datasources-mount-order]].
+- **Auth paths** — `/auth/*` is owned by the auth engine. See
+  [[@concept-auth-state-paths]].
+- **Default protected patterns** — `/auth/*`, `/tx/*`, `/ui/forms/*` are
+  always protected. Derive paths matching these patterns ERROR at
+  validation.
+- **Framework-reserved paths** — `/ui/selectedRow`, `/ui/modals/*`,
+  `/ui/drawers/*`, `/ui/loading`, `/ui/lastError`, `/ui/device/*`,
+  `/{target}Loading`, `/{target}Error`, `/{target}Deferred`. Some
+  consumers can READ these but the framework owns the writes.
+
+## Implementation
+
+Derive paths are contributed via RAII handle to `protectionRegistry`;
+`stateGuard` reads via lazy callback. Validator catches
+`setState → derive path` at load time (8 new derive/dataSources checks);
+dispatcher catches at runtime via `stateGuard.assertCanWrite`.
+
+## What happens if you violate
+
+- **Validator load time**: error during `mythik validate` / `mythik push`
+  with path name.
+- **Runtime**: dispatcher throws via `stateGuard.assertCanWrite` —
+  visible only at render time if validation was bypassed.
+
+## Related concepts
+
+- [[@concept-derive]]
+- [[@concept-auth-state-paths]]
+- [[@concept-data-sources]]
+- [[@path-ui-selected-row]] / [[@path-ui-modals-drawers]] / etc.
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 2`, § 5.3

package/docs/wiki/compiled/concept-storage-adapter.md

@@ -0,0 +1,69 @@
+---
+id: concept-storage-adapter
+title: StorageAdapter (host-app)
+kind: concept
+sources: [docs/consumer/reference-doc.md#storageadapter-setup-host-app]
+---
+
+# StorageAdapter (host-app)
+
+The host app provides a StorageAdapter to enable file uploads. Two
+canonical adapters ship; consumers can write custom ones.
+
+## Supabase Storage
+
+```tsx
+import { createSupabaseStorageAdapter } from 'mythik';
+
+<MythikRenderer
+  spec={spec}
+  instance={svc}
+  storage={createSupabaseStorageAdapter({ client: supabaseClient })}
+/>
+```
+
+## Generic URL (any backend)
+
+```tsx
+import { createUrlStorageAdapter } from 'mythik';
+
+<MythikRenderer
+  spec={spec}
+  instance={svc}
+  storage={createUrlStorageAdapter({
+    uploadUrl: 'https://api.example.com/upload',
+    deleteUrl: 'https://api.example.com/files',
+    responsePath: 'data.url',
+    headers: { 'X-Api-Key': apiKey },
+  })}
+/>
+```
+
+## Global limits (optional security backstop)
+
+```tsx
+<MythikRenderer
+  spec={spec}
+  instance={svc}
+  storage={adapter}
+  storageConfig={{
+    allowedTypes: ['image/jpeg', 'image/png', 'application/pdf'],
+    maxSize: 10_485_760,
+  }}
+/>
+```
+
+`storageConfig` enforces ABOVE per-element `accept` + `maxSize` — defense
+in depth.
+
+## Related concepts
+
+- [[@primitive-file-upload]]
+- [[@action-upload-file]]
+- [[@concept-file-upload-overview]]
+- [[@pattern-file-upload-auto]]
+- [[@pattern-file-upload-manual]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § StorageAdapter Setup (Host App)`

package/docs/wiki/compiled/concept-storage-custom-names.md

@@ -0,0 +1,69 @@
+---
+id: concept-storage-custom-names
+title: Storage — custom table names + identifier safety
+kind: concept
+sources: [docs/consumer/ai-context.md#custom-table-names]
+---
+
+# Storage — custom table names + identifier safety
+
+All three table names are independently configurable; overriding one does
+not require overriding the others.
+
+## Override per store
+
+```ts
+new SqlServerSpecStore({ ..., table: 'my_screens' })
+new SqlServerVersionedSpecStore({ ..., table: 'my_screens', versionsTable: 'my_versions' })
+new SqlServerEnvironmentStore({ ..., table: 'my_envs' })
+```
+
+(`SqlServerVersionedSpecStore` accepts both `table` and `versionsTable`
+since it extends `SqlServerSpecStore`.)
+
+## AI applies custom names directly
+
+If a consumer overrides any name, AI applies the same schema under the
+chosen name.
+
+## Identifier-safety scope (SQL Server)
+
+SQL Server stores enforce `assertValidIdentifier` on every configured
+name:
+- regex `/^[a-zA-Z_][a-zA-Z0-9_.]*$/`
+- max 128 chars
+
+Source: `packages/core/src/security/identifier-guard.ts`. Validator
+invoked in constructors of `SqlServerSpecStore` (line 26),
+`SqlServerVersionedSpecStore` (line 25), `SqlServerEnvironmentStore`.
+
+This blocks SQL injection via table-name interpolation in
+`[${table}]` / `[${versionsTable}]` template literals.
+
+## Supabase does NOT validate
+
+Supabase stores do NOT validate any configured name (it flows directly
+into the REST URL via `${this.tableName}`); consumer code passing
+user-controlled table names to a Supabase store **must validate them
+upstream**.
+
+## CLI `--table` flag
+
+Overrides store table for any command:
+```bash
+mythik validate my-api --table api_specs
+```
+
+Environment and version tables are NOT affected — they always use their
+fixed names (`screen_environments`, `screen_versions`) (rule 91).
+
+## Related concepts
+
+- [[@concept-storage-overview]]
+- [[@concept-spec-stores-catalog]]
+- [[@cli-overview]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Custom table names`
+- `docs/consumer/reference-doc.md § rule 91`

package/docs/wiki/compiled/concept-storage-evolution.md

@@ -0,0 +1,32 @@
+---
+id: concept-storage-evolution
+title: Storage — schema evolution policy
+kind: concept
+sources: [docs/consumer/ai-context.md#schema-evolution]
+---
+
+# Schema evolution policy
+
+When the framework changes the schema in a future version, that version's
+release notes will gain an "Evolution from v0.X.0" subsection listing
+per-version diffs (additive columns, new indexes, etc.) with idempotent
+ALTER instructions.
+
+## Canonical evolution path
+
+AI inspects the consumer's existing schema first, then applies the
+smallest set of ALTER statements to converge on the current version.
+
+## v0.1.0 baseline
+
+No evolution diffs yet. v0.1.0 is the first public release; consumers
+running pre-v0.1.0 with manually-created tables are unaffected (schema
+unchanged from what the demo script produced).
+
+## Related concepts
+
+- [[@concept-storage-overview]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Schema evolution`

package/docs/wiki/compiled/concept-storage-idempotency.md

@@ -0,0 +1,35 @@
+---
+id: concept-storage-idempotency
+title: Storage — idempotency requirement
+kind: concept
+sources: [docs/consumer/ai-context.md#idempotency-requirement]
+---
+
+# Storage idempotency
+
+The applied DDL **MUST be idempotent** — re-running it on a database that
+already has the tables MUST NOT fail and MUST NOT recreate.
+
+## Per-dialect "if not exists"
+
+| Dialect | Form |
+|---|---|
+| SQL Server | `IF NOT EXISTS (SELECT * FROM INFORMATION_SCHEMA.TABLES WHERE TABLE_NAME = '...') CREATE TABLE ...` |
+| Postgres / Supabase | `CREATE TABLE IF NOT EXISTS ...` |
+| MySQL / MariaDB | `CREATE TABLE IF NOT EXISTS ...` |
+
+## Indexes + triggers
+
+Apply the same idempotent guard to indexes and triggers (`CREATE INDEX IF
+NOT EXISTS`, `CREATE OR REPLACE FUNCTION`, `DROP TRIGGER IF EXISTS …;
+CREATE TRIGGER …`).
+
+## Related concepts
+
+- [[@concept-storage-overview]]
+- [[@concept-storage-verification]]
+- [[@concept-storage-evolution]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Idempotency requirement`

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

@@ -0,0 +1,81 @@
+---
+id: concept-storage-overview
+title: Storage setup — three tables
+kind: concept
+sources: [docs/consumer/ai-context.md#storage-setup, docs/consumer/reference-doc.md#rule-250]
+---
+
+# Storage setup — three tables
+
+Mythik stores specs in the consumer's database. **Three tables** depending
+on which features the consumer opts into.
+
+| Table | When required |
+|---|---|
+| **`screens`** (base) | **REQUIRED for every adapter** |
+| **`screen_versions`** (opt-in) | Only when using `*VersionedSpecStore` (i.e., `mythik push --author <name>`) |
+| **`screen_environments`** (opt-in) | Only when using `*EnvironmentStore` |
+
+**The framework does NOT auto-create any of these tables.** Apply the
+schema once during initial setup, then the framework operates against the
+running tables.
+
+## Authoritative since v0.1.0
+
+Framework's INSERT/SELECT/UPDATE statements require these exact columns by
+name + semantic type. AI applying this schema MUST preserve all columns,
+constraints, and indexes; the SQL dialect is free to vary
+(NVARCHAR/VARCHAR/TEXT, BIT/BOOLEAN, DATETIME2/TIMESTAMPTZ — pick what
+the target DB supports).
+
+## Versioned stores extend the base store
+
+When `SqlServerVersionedSpecStore.saveVersion(id, doc, meta)` runs, it
+appends to `screen_versions` AND calls the inherited base `save(id, doc)`
+which writes to `screens`. **`screens` MUST exist for every consumer** —
+no "versioning-only" mode skips it.
+
+## Why no `mythik migrate` command
+
+Two paths were considered (Item G):
+1. Ship a CLI command that generates + executes DDL per adapter.
+2. Declare the schema in `ai-context.md` and let the AI apply it.
+
+**Path 2 chosen.** Rationale: Mythik is AI-first; consumer setup already
+involves an AI; CLI for AI-only task is redundant. AI faithfully translates
+a precise semantic spec across SQL dialects. Schema evolution becomes a doc
+update rather than a versioned migration runner. (`mythik migrate` may be
+revisited in v0.3+ if multi-store fan-out grows.)
+
+## Bootstrap procedure
+
+1. Configure `.mythikrc` / env vars for the target store.
+2. Open `docs/consumer/ai-context.md § Storage Setup`.
+3. Hand the schema to your AI assistant; ask it to bootstrap your DB.
+4. AI translates → applies idempotently → verifies via INFORMATION_SCHEMA
+   (and on Postgres, verifies the two triggers on `screens`).
+5. Run `mythik push my-screen --author <name>`.
+
+## Sub-articles
+
+- [[@concept-storage-table-screens]]
+- [[@concept-storage-table-versions]]
+- [[@concept-storage-table-environments]]
+- [[@concept-storage-postgres-jsonb]]
+- [[@concept-storage-postgres-triggers]]
+- [[@concept-storage-idempotency]]
+- [[@concept-storage-verification]]
+- [[@concept-storage-custom-names]]
+- [[@concept-storage-evolution]]
+
+## Related concepts
+
+- [[@concept-spec-stores-catalog]]
+- [[@concept-versioned-store]]
+- [[@concept-environment-store]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Storage Setup`
+- ` § Item G`
+- `docs/consumer/reference-doc.md § rule 250`