mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/pattern-form-validation-cross-field.md

@@ -0,0 +1,58 @@
+---
+id: pattern-form-validation-cross-field
+title: Pattern — Cross-field validation (`derive` + `requiredIf`)
+kind: pattern
+sources: [docs/consumer/ai-context-patterns.md#requiredif-is-truthy-only]
+---
+
+# Pattern — Cross-field validation
+
+`requiredIf` is **truthy-only** — does NOT support `eq`. To require based
+on a specific value, derive a boolean first, then `requiredIf` on that
+derived path.
+
+## Pattern
+
+```json
+{
+  "derive": {
+    "/ui/isEngineering": {
+      "$cond": { "$state": "/form/department", "eq": "Engineering" },
+      "$then": true,
+      "$else": false
+    }
+  },
+  "forms": {
+    "employee-form": {
+      "fields": {
+        "salary": {
+          "statePath": "/form/salary",
+          "rules": [
+            { "type": "required" },
+            { "type": "requiredIf", "args": { "field": { "$state": "/ui/isEngineering" } }, "message": "Salary required for Engineering" },
+            { "type": "greaterThan", "args": { "other": { "$state": "/form/minSalary" } }, "message": "Must exceed minimum" }
+          ]
+        }
+      }
+    }
+  }
+}
+```
+
+## Why this works
+
+- `derive` computes `/ui/isEngineering` as a boolean reactively.
+- `requiredIf` reads the boolean — works because the `field` arg is now
+  truthy/falsy (not a value comparison).
+
+## Related concepts
+
+- [[@concept-validators-catalog]]
+- [[@concept-derive]]
+- [[@concept-forms]]
+- [[@expression-cond]]
+- [[@antipattern-required-if-equals]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-patterns.md § requiredIf is truthy-only` + Cross-field conditional pattern

package/docs/wiki/compiled/pattern-form-validation.md

@@ -0,0 +1,58 @@
+---
+id: pattern-form-validation
+title: Pattern — Form validation overview
+kind: pattern
+sources: [docs/consumer/ai-context.md#forms]
+---
+
+# Pattern — Form validation overview
+
+Two layers of validation in Mythik:
+
+1. **Inline `checks`** on individual inputs — for standalone fields.
+2. **Declarative `forms` block** — for coordinated multi-field forms with
+   `isValid`, cross-field rules, and `submitForm` gating.
+
+## When to pick which
+
+| Need | Pick |
+|---|---|
+| Single field, no cross-references | Inline `checks` |
+| Disable submit until form is valid | `forms` + `submitForm` |
+| Cross-field rule (`greaterThan`, `requiredIf`) | `forms` |
+| Conditional rule based on another field's value | `forms` + `derive` (see [[@pattern-form-validation-cross-field]]) |
+
+## Skeleton
+
+```json
+{
+  "forms": {
+    "my-form": {
+      "fields": {
+        "title": { "statePath": "/form/title", "rules": [{ "type": "required" }] }
+      },
+      "validateOn": "blur"
+    }
+  },
+  "elements": {
+    "submit-btn": {
+      "type": "button",
+      "props": { "label": "Save", "disabled": { "$not": { "$state": "/ui/forms/my-form/isValid" } } },
+      "on": { "press": { "action": "submitForm", "params": { "formId": "my-form", "url": "...", "method": "POST", "body": {...} } } }
+    }
+  }
+}
+```
+
+## Related concepts
+
+- [[@concept-forms]]
+- [[@concept-validation-checks]]
+- [[@concept-validators-catalog]]
+- [[@pattern-form-validation-cross-field]]
+- [[@action-submit-form]]
+- [[@antipattern-action-chain-no-stop]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Forms`

package/docs/wiki/compiled/pattern-fullstack-coherence.md

@@ -0,0 +1,49 @@
+---
+id: pattern-fullstack-coherence
+title: Pattern — Fullstack coherence (API + Frontend)
+kind: pattern
+sources: [docs/consumer/ai-context.md#fullstack-coherence-api--frontend]
+---
+
+# Pattern — Fullstack coherence
+
+When generating both API spec and frontend screens, keep them in lockstep
+to avoid runtime mismatches.
+
+## Coherence rules
+
+- **Frontend `fetch` URLs must match API `endpoint.path` values.**
+- **Frontend filter dropdown options must match API `catalogs` static values.**
+- **Frontend CRUD transaction methods (POST/PUT/DELETE) must match API
+  endpoint methods.**
+- **API `policies` role lists should align with AppSpec `roleAccess`.**
+- **API `scopeFilter.bypassRoles` should include the same admin roles
+  as AppSpec.**
+
+## Cross-validation tool
+
+Use `mythik contract` to cross-validate before deploy:
+
+```bash
+mythik contract --app app-demo --api ejecucion-api
+```
+
+It checks 4 rules:
+- `endpoints-exist` (error)
+- `fields-valid` (error)
+- `params-match` (warning)
+- `permissions-consistent` (warning)
+
+See [[@cli-contract]] for full details.
+
+## Related concepts
+
+- [[@cli-contract]]
+- [[@concept-api-spec]]
+- [[@concept-app-spec]]
+- [[@concept-role-access]]
+- [[@concept-api-scope-filter]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Fullstack Coherence (API + Frontend)`

package/docs/wiki/compiled/pattern-git-vs-db-versioning.md

@@ -0,0 +1,55 @@
+---
+id: pattern-git-vs-db-versioning
+title: Pattern — Git-backed vs DB-versioned history
+kind: pattern
+sources: [docs/consumer/ai-context-runtime-semantics.md#62-git-backed-vs-db-versioned-history]
+---
+
+# Pattern — Git-backed vs DB-versioned history
+
+Two history models — pick one per project.
+
+## Git-backed history
+
+- Specs in repo, `git log` + `git blame` serve as audit trail.
+- No `--author` flag needed on push/patch.
+- CLI writes via `store.save` (unversioned path).
+- **Best for**: single-env apps, dev-loop iteration, specs-as-code.
+
+## DB-versioned history
+
+- `--author` flag on push/patch activates `store.saveVersion`.
+- Writes a row to `screen_versions` table.
+- Enables: `mythik diff`, `mythik rollback`, `mythik promote`,
+  `mythik bisect`.
+- Audit trail queryable in SQL (who changed what, when).
+- **Best for**: multi-env deployments, runtime admin UI, compliance.
+
+## When to enable DB versioning
+
+| Signal | Recommendation |
+|---|---|
+| Single dev env, specs in git | Skip. Git is enough |
+| Separate dev + staging + prod DBs | Enable. Use `mythik promote` |
+| Admin UI that edits specs at runtime | Enable. Git can't capture runtime edits |
+| Compliance (SOX, HIPAA, etc.) — "who changed screen X on date Y" | Enable. Native SQL audit query beats git log |
+
+## Storage dependency
+
+DB versioning requires `screen_versions` + `screen_environments` tables.
+Mythik does not auto-create them; apply the declarative schema from
+[[@concept-storage-overview]] in the consumer database before using
+versioned stores.
+
+## Related concepts
+
+- [[@cli-versioning-author]]
+- [[@concept-versioned-store]]
+- [[@concept-environment-store]]
+- [[@concept-promote-gate]]
+- [[@cli-history]]
+- [[@pattern-push-vs-patch]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 6.2`

package/docs/wiki/compiled/pattern-identity-aware-spec.md

@@ -0,0 +1,70 @@
+---
+id: pattern-identity-aware-spec
+title: Pattern — Identity-aware spec
+kind: pattern
+sources: [docs/consumer/ai-context-patterns.md#identity-aware-spec-pattern]
+---
+
+# Pattern — Identity-aware spec
+
+Generic recipe for specs that adapt to identity tokens (surface, scheme,
+gradient, etc.) without breaking under preset switches.
+
+## Always
+
+1. Set page layout `bg` to `{ "$token": "colors.background" }` (NOT white).
+2. Use `surface="card"` on card-like boxes (stat cards, form cards,
+   content panels).
+3. Set `tokens.identity` for app personality — at minimum `surface` +
+   `typographyHierarchy`.
+4. Use `$token` for ALL visual values — identity controls borders,
+   shadows, radius through tokens.
+5. For colored-surface schemes, set `coloredSurfaceLayers` to control
+   tonal separation (default 25/45/65).
+6. Use `$token: "schemeColors.text"` for scheme-aware text in
+   previews / themed content.
+7. Use `$token: "colorWeight.navBg"` for layout elements that respond
+   to color weight.
+
+## Skeleton
+
+```json
+{
+  "tokens": {
+    "dna": { "primary": "#0D9488", "harmony": "analogous", "formality": 0.3 },
+    "identity": {
+      "surface": "outlined",
+      "typographyHierarchy": "editorial",
+      "labelStyle": "uppercase",
+      "radiusPattern": "all"
+    }
+  },
+  "root": "layout",
+  "elements": {
+    "layout": { "type": "box", "style": { "backgroundColor": { "$token": "colors.background" }, "minHeight": "100vh" }, "children": ["card"] },
+    "card":   { "type": "box", "props": { "surface": "card" }, "style": { "padding": 24 }, "children": ["title", "form"] },
+    "title":  { "type": "text", "props": { "content": "Settings", "variant": "heading" } }
+  }
+}
+```
+
+## Anti-patterns
+
+- **Card-like boxes WITHOUT `surface="card"`** — they ignore identity
+  surface treatment and look inconsistent.
+- **Hardcoding text color** instead of letting surface containers set
+  `color: c.text` via CSS inheritance — child primitives use
+  `color: 'inherit'` automatically.
+
+## Related concepts
+
+- [[@concept-identity-overview]]
+- [[@concept-identity-surface]]
+- [[@concept-identity-color-scheme]]
+- [[@concept-identity-color-weight]]
+- [[@primitive-box]] — `surface` prop
+- [[@expression-token]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-patterns.md § Identity-Aware Spec Pattern`

package/docs/wiki/compiled/pattern-loading-content-empty.md

@@ -0,0 +1,66 @@
+---
+id: pattern-loading-content-empty
+title: Pattern — Loading / Content / Empty / Error
+kind: pattern
+sources: [docs/consumer/ai-context.md#loadingcontentempty-pattern, docs/consumer/reference-doc.md#loadingcontentempty-pattern]
+---
+
+# Pattern — Loading / Content / Empty / Error
+
+Standard four-state visibility pattern for data-driven screens. The exact
+state paths differ between `initialActions + fetch` vs `dataSources`.
+
+## With `initialActions + fetch`
+
+Uses `/ui/loading` and `/ui/lastError`:
+
+```json
+"loading": { "visible": { "$and": [
+  { "$state": "/ui/loading" },
+  { "$not": { "$array": "count", "source": { "$state": "/items" } } }
+]}},
+"content": { "visible": { "$array": "count", "source": { "$state": "/items" } } },
+"empty":   { "visible": { "$and": [
+  { "$not": { "$state": "/ui/loading" } },
+  { "$not": { "$array": "count", "source": { "$state": "/items" } } }
+]}},
+"error":   { "visible": { "$state": "/ui/lastError" } }
+```
+
+## With `dataSources`
+
+Uses auto-generated `/{target}Loading` and `/{target}Error`:
+
+```json
+"loading": { "visible": { "$and": [
+  { "$state": "/itemsLoading" },
+  { "$not": { "$array": "count", "source": { "$state": "/items" } } }
+]}},
+"content": { "visible": { "$array": "count", "source": { "$state": "/items" } } },
+"empty":   { "visible": { "$and": [
+  { "$not": { "$state": "/itemsLoading" } },
+  { "$not": { "$array": "count", "source": { "$state": "/items" } } }
+]}},
+"error":   { "visible": { "$state": "/itemsError" } }
+```
+
+## Key rule
+
+Loading skeleton shows ONLY on **initial load** (loading AND no data).
+Content stays visible during background re-fetches (data exists,
+regardless of loading state). This avoids the flicker pattern of
+"data → empty → data".
+
+## Related concepts
+
+- [[@concept-visibility]]
+- [[@action-fetch]] — sets `/ui/loading`, `/ui/lastError`
+- [[@concept-data-sources]] — sets `/{target}Loading`, `/{target}Error`
+- [[@path-ui-loading-error]]
+- [[@path-data-source-paths]]
+- [[@concept-skeleton-auto]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Loading/Content/Empty Pattern`
+- `docs/consumer/reference-doc.md § Loading/Content/Empty Pattern`

package/docs/wiki/compiled/pattern-login-body-template.md

@@ -0,0 +1,47 @@
+---
+id: pattern-login-body-template
+title: Pattern — `loginBody` (email→username mapping)
+kind: pattern
+sources: [docs/consumer/ai-context-runtime-semantics.md#32-apiauthlogin-body-contract]
+---
+
+# Pattern — `loginBody` (email→username mapping)
+
+The framework's `/api/auth/login` expects `{ username, password }` —
+**not `email`**. For email-convention apps, map at the spec level via
+`loginBody`.
+
+## Why `username` and not `email`
+
+The framework supports non-email username auth (employee ID, LDAP username,
+etc.). The server validates against `usernameColumn` from the auth
+provider, which can be an email column.
+
+## Pattern
+
+```json
+{
+  "auth": {
+    "loginBody": {
+      "username": { "$state": "/login/email" },
+      "password": { "$state": "/login/password" }
+    }
+  }
+}
+```
+
+The `loginBody` template is resolved at login dispatch — consumer's email
+field value becomes the server's `username` field value. Server sees
+`{ username: <email-string>, password: <pw> }` and validates against the
+users table's `usernameColumn`.
+
+## Related concepts
+
+- [[@concept-api-login-body-contract]]
+- [[@concept-auth-config]]
+- [[@action-login]]
+- [[@pattern-login-screen]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 3.2`

package/docs/wiki/compiled/pattern-login-screen.md

@@ -0,0 +1,83 @@
+---
+id: pattern-login-screen
+title: Pattern — Login screen
+kind: pattern
+sources: [docs/consumer/ai-context.md#login-screen, docs/consumer/reference-doc.md#login-screen-example]
+---
+
+# Pattern — Login screen
+
+Use **`/screens/login/...` paths** for form fields (NOT `/form/...`).
+Combined with `statePolicy: "reset"` on the login screen, credentials
+auto-clear on logout.
+
+## Skeleton
+
+```json
+{
+  "root": "login-page",
+  "elements": {
+    "login-page": { "type": "box", "style": { "display": "flex", "alignItems": "center", "justifyContent": "center", "minHeight": "100vh" }, "children": ["card"] },
+    "card": { "type": "box", "props": { "surface": "card" }, "style": { "width": 400, "padding": 32, "borderRadius": 16 }, "children": ["email", "pass", "error", "btn"] },
+    "email": { "type": "input", "props": { "placeholder": "Email", "value": { "$bindState": "/screens/login/email" } } },
+    "pass": { "type": "input", "props": { "placeholder": "Password", "type": "password", "value": { "$bindState": "/screens/login/password" } } },
+    "error": { "type": "text", "visible": { "$auth": "error" }, "props": { "content": { "$auth": "error" } }, "style": { "color": "#EF4444" } },
+    "btn": {
+      "type": "button",
+      "props": {
+        "label": { "$cond": { "$auth": "loading" }, "$then": "Signing in...", "$else": "Login" },
+        "disabled": { "$auth": "loading" }
+      },
+      "on": { "press": { "action": "login", "params": {
+        "email": { "$state": "/screens/login/email" },
+        "password": { "$state": "/screens/login/password" }
+      }}}
+    }
+  }
+}
+```
+
+## AppSpec screen definition
+
+```json
+"login": { "label": "Login", "icon": "sign-in", "statePolicy": "reset" }
+```
+
+`statePolicy: "reset"` clears `/screens/login` on every navigation to the
+login screen. Without it, credentials persist after logout.
+
+## Why `/screens/login/*` not `/form/*`
+
+Combined with `statePolicy: "reset"`, the AppEngine clears `/screens/login`
+when navigating to the login screen with reset policy. Root-level paths
+like `/form/email` would persist across logouts (rule 30).
+
+## Login renders fullscreen
+
+`MythikApp` automatically renders the login screen WITHOUT the AppSpec
+layout (no sidebar, no header) when the user is not authenticated. After
+login, the full layout appears reactively. No `visible` conditions needed
+on the sidebar (rule 46).
+
+## Submit on Enter
+
+Add `on.submit` to a password input:
+```json
+{ "type": "input", "props": { "type": "password", ... },
+  "on": { "submit": { "action": "login", "params": { ... } } }
+}
+```
+
+## Related concepts
+
+- [[@action-login]]
+- [[@expression-auth]]
+- [[@concept-state-policies]]
+- [[@concept-screen-outlet]]
+- [[@pattern-login-body-template]]
+- [[@path-login]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § AppSpec & Navigation → Login Screen`
+- `docs/consumer/reference-doc.md § Login Screen Example`

package/docs/wiki/compiled/pattern-push-vs-patch.md

@@ -0,0 +1,54 @@
+---
+id: pattern-push-vs-patch
+title: Pattern - Push vs Patch (file-first vs DB-first)
+kind: pattern
+sources: [docs/consumer/ai-context-runtime-semantics.md#61-push-vs-patch--file-first-vs-db-first]
+---
+
+# Pattern - Push vs Patch
+
+Two paradigms for modifying specs. Pick one per project; mixing creates
+issues.
+
+## Push paradigm (file-first)
+
+- Specs live in git under `specs/*.json`.
+- Modify locally, then run `mythik push <id>`.
+- Diff-reviewable in CI through normal JSON file diffs.
+- Full-spec bandwidth cost per write.
+
+## Patch paradigm (DB-first)
+
+- Specs live in the DB; local files are optional working snapshots.
+- Modify via `mythik patch <id> --from-file patch.json` for shell-safe
+  surgical writes.
+- Requires `mythik pull <id>` to refresh any local `specs/*.json` snapshot
+  after a DB patch.
+
+## Decision table
+
+| Use case | Recommended | Rationale |
+|---|---|---|
+| Specs committed to git, CI gating | Push | Git log is the source of truth |
+| Single-spec surgical edit | Patch | Surgical change |
+| Runtime admin UI editing specs | Patch (DB-first) | DB is the source of truth |
+| Multi-environment deploy | Push + DB versioning | Git for dev, versioned promote for env move |
+| Large refactor across many specs | Push | Bulk easier; patch chains get fragile |
+
+## Mixing warning
+
+Do not `patch` and later `push` from stale `specs/*.json`. In DB-first
+workflows, the DB is source of truth; local files are bootstrap/snapshot
+artifacts until refreshed from `mythik pull <id>`.
+
+## Related concepts
+
+- [[@cli-push]]
+- [[@cli-patch]]
+- [[@cli-pull]]
+- [[@pattern-git-vs-db-versioning]]
+- [[@cli-versioning-author]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md` 6.1

package/docs/wiki/compiled/pattern-reusable-components.md

@@ -0,0 +1,67 @@
+---
+id: pattern-reusable-components
+title: Pattern — Reusable components (templates + variants)
+kind: pattern
+sources: [docs/consumer/ai-context-patterns.md#reusable-components--templates--variants]
+---
+
+# Pattern — Reusable components
+
+Two underused reuse mechanisms in Mythik. **Use them before duplicating
+style blocks.**
+
+## Decision
+
+| Need | Pick |
+|---|---|
+| Same primitive type, different style set | `tokens.components.{type}.{variant}` |
+| Composite (custom type wrapping primitive + children slot) | `appSpec.templates` |
+| Style varies by state (hover/active/focus) | Variants (built-in state slots) |
+| Parametrized via props + children | Templates (with `$prop` + `$children`) |
+
+See [[@concept-templates-vs-variants]] for the full decision walk-through.
+
+## Anti-pattern — duplicate style blocks
+
+```json
+// screen-a.json
+{ "type": "button", "style": { "background": "linear-gradient(...)", "animation": "pulse 2s ...", ...20 lines } }
+
+// screen-b.json
+{ "type": "button", "style": { "background": "linear-gradient(...)", "animation": "pulse 2s ...", ...20 lines } }
+```
+
+If the same rich style object appears in 2+ specs (or 2+ places in same
+spec), extract to a template or variant. Duplication inflates DB storage,
+breaks DRY, makes updates O(N).
+
+See [[@antipattern-style-block-duplication]].
+
+## Right approach — extract once
+
+```json
+// appSpec.templates once
+{ "templates": { "button-pulse-cta": { ...full definition... } } }
+
+// both screens
+{ "type": "button-pulse-cta", "props": { "label": "..." } }
+```
+
+## Animations cascade across BOTH mechanisms
+
+`animations` declared at any of these levels merges via the cascade —
+identity → variant → template → element — with per-trigger null semantics.
+Templates and variants are NOT animation islands. See
+[[@concept-animation-cascade]].
+
+## Related concepts
+
+- [[@concept-templates]]
+- [[@concept-component-variants]]
+- [[@concept-templates-vs-variants]]
+- [[@concept-animation-cascade]]
+- [[@antipattern-style-block-duplication]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-patterns.md § Reusable Components — Templates + Variants`

package/docs/wiki/compiled/pattern-tx-create.md

@@ -0,0 +1,76 @@
+---
+id: pattern-tx-create
+title: Pattern — CREATE transaction
+kind: pattern
+sources: [docs/consumer/ai-context.md#transactions-optimistic-updates, docs/consumer/reference-doc.md#create--add-item-to-list]
+---
+
+# Pattern — CREATE transaction
+
+Append a new item with optimistic UX. Re-fetch in `onSuccess` to replace
+temporary id with the server-assigned real id.
+
+## Template
+
+```json
+{
+  "transaction": {
+    "before": [
+      { "action": "closeModal", "params": { "id": "{{MODAL_ID}}" } }
+    ],
+    "optimistic": [
+      { "action": "setState", "params": {
+        "statePath": "{{ARRAY_PATH}}",
+        "value": { "$array": "append", "source": { "$state": "{{ARRAY_PATH}}" }, "value": {
+          "id": { "$template": "temp-${/form/title}" },
+          "{{FIELD_1}}": { "$state": "/form/{{FIELD_1}}" },
+          "{{FIELD_2}}": { "$state": "/form/{{FIELD_2}}" }
+        }}
+      }}
+    ],
+    "confirm": [
+      { "action": "fetch", "params": {
+        "method": "POST",
+        "url": "{{API_URL}}",
+        "headers": { "Prefer": "return=representation" },
+        "body": {
+          "{{FIELD_1}}": { "$state": "/form/{{FIELD_1}}" },
+          "{{FIELD_2}}": { "$state": "/form/{{FIELD_2}}" }
+        },
+        "target": "/tx/result"
+      }}
+    ],
+    "onSuccess": [
+      { "action": "fetch", "params": {
+        "method": "GET",
+        "url": "{{API_URL}}?select=*&order=created_at.desc",
+        "target": "{{ARRAY_PATH}}"
+      }}
+    ],
+    "onError": [
+      { "action": "showNotification", "params": { "type": "error", "message": "Could not create {{ENTITY}}." } }
+    ]
+  }
+}
+```
+
+## Notes
+
+- `before`: close the modal so it stays closed even on rollback.
+- `optimistic`: append with a temporary id (e.g., `temp-<title>`) — UI
+  shows the row immediately.
+- `confirm`: POST. Server returns the real row.
+- `onSuccess`: re-fetch full list to replace temp id with real id.
+
+## Related concepts
+
+- [[@concept-transactions]]
+- [[@pattern-tx-update]]
+- [[@pattern-tx-delete]]
+- [[@expression-array]] — `append`
+- [[@action-fetch]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Transactions → CRUD variations`
+- `docs/consumer/reference-doc.md § Transaction Templates → CREATE`