mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/concept-where-to-look.md

@@ -0,0 +1,78 @@
+---
+id: concept-where-to-look
+title: Where-to-Look — source navigation map (overview)
+kind: concept
+sources: [docs/consumer/WHERE-TO-LOOK.md]
+---
+
+# Where-to-Look — source navigation map
+
+Fallback for cases the rest of `docs/consumer/` does not fully cover.
+**Use it when**:
+
+1. You've checked the relevant `ai-context-*.md` and `reference-doc.md`
+   and the answer is not there.
+2. You're doing **deep customization beyond documented extension points**
+   (custom actions / `SpecStore`s are first-class; custom plugins follow
+   the auth pattern but reach into framework internals; custom server
+   middleware is plain Express + the framework's chain shape).
+3. You're **debugging runtime behavior** that the docs describe at the
+   surface but you need the underlying mechanism.
+
+**Do NOT use it for**:
+
+- Spec syntax, expressions, primitives, actions catalog → use
+  ai-context.md + companions.
+- Rule lookup → [[@concept-rules-catalog]].
+- ApiSpec / server contract surface → [[@concept-api-spec]].
+- Runtime behavior reference (timing matrix, reserved state paths, store
+  coordination) → [[@concept-expression-timing]] etc. **Read those before
+  reaching for source.**
+
+## How source paths work
+
+Paths are relative to the framework repo root.
+
+- **In framework repo / unpacked tarball**: `packages/<package>/src/<path>`
+  — TypeScript source. **Authoritative for behavior questions.**
+- **In `node_modules/<public-mythik-package>/`**: published artifact ships
+  `dist/` only (compiled `.js` + `.d.ts`). `.d.ts` is enough for type-shape
+  questions; for behavior questions, fetch `src/` from the GitHub repo or
+  unpacked tarball.
+
+When in doubt, prefer reading `src/`. `dist/` is generated and may obscure
+intent.
+
+## Customization recipes (Section 1)
+
+- [[@concept-customize-action]]
+- [[@concept-customize-spec-store]]
+- [[@concept-customize-versioned-store]]
+- [[@concept-customize-plugin]]
+- [[@concept-customize-validator-rule]]
+- [[@concept-customize-cli-lint-rule]]
+- [[@concept-customize-server-middleware]]
+- [[@concept-customize-expression-handler]]
+
+## Debugging entry points (Section 2)
+
+- [[@concept-debugging-runtime-pointers]]
+
+## Source-of-truth references (Section 3)
+
+- [[@concept-source-of-truth-references]]
+
+## When source-reading is misleading (Section 4)
+
+- [[@concept-source-reading-misleading]]
+
+## Reporting gaps
+
+If you needed to read a source file that this map did NOT anticipate,
+that's a signal that either (a) the relevant doc in `docs/consumer/`
+should cover it directly, or (b) this map needs an entry. Both are valid
+framework-feedback signals.
+
+## Sources (raw)
+
+- `docs/consumer/WHERE-TO-LOOK.md` (full)

package/docs/wiki/compiled/expression-and-or-not.md

@@ -0,0 +1,68 @@
+---
+id: expression-and-or-not
+title: `$and` / `$or` / `$not` — boolean logic
+kind: expression
+sources: [docs/consumer/ai-context.md#conditionals--logic, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$and` / `$or` / `$not`
+
+Boolean composition. Works everywhere a boolean is accepted — `visible`,
+`disabled`, conditions inside `$cond`, etc.
+
+## Shape / Signature
+
+```json
+{ "$and": [<expr>, <expr>, ...] }
+{ "$or":  [<expr>, <expr>, ...] }
+{ "$not": <expr> }
+```
+
+## Examples
+
+All conditions must be true:
+```json
+"visible": { "$and": [
+  { "$state": "/form/isValid" },
+  { "$state": "/form/hasChanges" }
+]}
+```
+
+Either of multiple roles:
+```json
+{ "$or": [{ "$state": "/user/isAdmin" }, { "$state": "/user/isModerator" }] }
+```
+
+Negation:
+```json
+{ "$not": { "$state": "/form/isValid" } }
+```
+
+Combined with array operations (loading/empty pattern):
+```json
+"visible": {
+  "$and": [
+    { "$not": { "$state": "/ui/loading" } },
+    { "$not": { "$array": "count", "source": { "$state": "/items" } } }
+  ]
+}
+```
+
+## Constraints / Anti-patterns
+
+- Truthy/falsy follows JavaScript semantics: `0`, `""`, `null`,
+  `undefined`, `false`, empty arrays/objects evaluate as falsy.
+- Use `$cond` to wrap when the surrounding prop requires a strict
+  boolean (some props are stricter than `visible`).
+
+## Related concepts
+
+- [[@expression-cond]]
+- [[@expression-switch]]
+- [[@concept-visibility]] — most common use site
+- [[@pattern-loading-content-empty]] — typical `$and` + `$not` shape
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Conditionals & Logic`
+- `docs/consumer/reference-doc.md § Expression Types → $and / $or / $not`

package/docs/wiki/compiled/expression-array.md

@@ -0,0 +1,111 @@
+---
+id: expression-array
+title: `$array` — array operations
+kind: expression
+sources: [docs/consumer/ai-context.md#math--data, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$array` — array operations
+
+Comprehensive array operations over expression sources. The most-used
+operation set in specs — count, filter, sum, search, slice, sort, append,
+replace, remove, etc.
+
+## Operations catalog
+
+| Op | Signature | Purpose |
+|---|---|---|
+| `count` | `source[, where]` | Length, optionally filtered |
+| `sum` | `source, field[, where]` | Sum of `field` |
+| `sumProduct` | `source, field1, field2` | Σ(field1 × field2) |
+| `filter` | `source, where` | Subset by predicate |
+| `search` | `source, query, fields` | Case-insensitive multi-field |
+| `sort` | `source, field, direction` | `asc`/`desc` |
+| `slice` | `source, from, to` | Range |
+| `find` | `source, where` | First match |
+| `includes` | `source, value` | Boolean membership |
+| `map` | `source, field` | Project a single field |
+| `first` | `source` | First element |
+| `last` | `source` | Last element |
+| `append` | `source, value` | Add element (mutate path) |
+| `replace` | `source, where, value` | Replace by predicate |
+| `remove` | `source, where` | Remove by predicate |
+| `toggle` | `source, value` | Add or remove (selection toggle) |
+
+## Where operators
+
+`eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `in`, `notIn`.
+
+**`where` accepts ONE field + ONE operator only** — no `$and`/`$or` inside
+`where`. For multiple conditions, chain filters.
+
+## Examples
+
+Count items:
+```json
+{ "$array": "count", "source": { "$state": "/items" } }
+```
+
+Filter active items:
+```json
+{ "$array": "filter", "source": { "$state": "/items" }, "where": { "field": "status", "eq": "active" } }
+```
+
+Multi-condition (chain filters):
+```json
+{
+  "$array": "filter",
+  "source": {
+    "$array": "filter",
+    "source": { "$state": "/items" },
+    "where": { "field": "price", "gte": 10 }
+  },
+  "where": { "field": "price", "lte": 100 }
+}
+```
+
+Search + paginate:
+```json
+{
+  "$array": "slice",
+  "source": {
+    "$array": "search",
+    "source": { "$state": "/items" },
+    "query": { "$state": "/search" },
+    "fields": ["name", "category"]
+  },
+  "from": 0,
+  "to": 20
+}
+```
+
+Mutation in transaction `optimistic`:
+```json
+{ "$array": "append", "source": { "$state": "/items" }, "value": { "name": "New" } }
+{ "$array": "replace", "source": { "$state": "/items" }, "where": { "field": "id", "eq": 1 }, "value": { "name": "Updated" } }
+{ "$array": "remove", "source": { "$state": "/items" }, "where": { "field": "id", "eq": 3 } }
+```
+
+## Constraints / Anti-patterns
+
+- **`append` and `replace` use `value`, NOT `item`.** `item` silently does
+  nothing (rule 10). See [[@antipattern-action-chain-no-stop]] for related
+  silent-fail traps.
+- **`"all"` is NOT a wildcard** — `where: { field: "status", eq: "all" }`
+  matches the literal string `"all"`. Use `$cond` to bypass — see
+  [[@antipattern-all-filter-wildcard]].
+- **`derive` over server-paginated state sees only the current page.**
+  Don't use `$array: "sum"` for full-dataset totals — use the API's
+  `totals` response instead. See [[@antipattern-derive-server-pagination]].
+
+## Related concepts
+
+- [[@concept-repeat]] — `repeat.source` consumer
+- [[@expression-math]] — pair with `$math` for averages
+- [[@concept-derive]] — typical `$array` consumer
+- [[@pattern-tx-create]] / [[@pattern-tx-update]] / [[@pattern-tx-delete]] — mutation in optimistic phases
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Math & Data → $array`
+- `docs/consumer/reference-doc.md § Expression Types → $array`

package/docs/wiki/compiled/expression-auth.md

@@ -0,0 +1,83 @@
+---
+id: expression-auth
+title: `$auth` — authenticated user data
+kind: expression
+sources: [docs/consumer/ai-context.md#login-screen, docs/consumer/reference-doc.md#expression-types, docs/consumer/reference-doc.md#authentication]
+---
+
+# `$auth` — authenticated user data
+
+Reads from the authenticated user's data with a **security whitelist**.
+Sensitive fields (token, password, secret, session, and variants) always
+return `undefined`. Prefer `$auth` over `$state: "/auth/user/..."` —
+`$auth` is whitelisted, has clear semantics, and is stable across framework
+versions.
+
+## Shape / Signature
+
+```json
+{ "$auth": "<field>" }
+```
+
+## Allowed fields
+
+| Field | Returns |
+|---|---|
+| `isAuthenticated` | boolean — false when no auth state |
+| `id`, `email`, `name`, `avatar` | User profile fields |
+| `role` | Primary role (string) |
+| `roles` | All roles (string[]) |
+| `metadata` | Full metadata object |
+| `metadata.*` | Nested metadata field (dot notation) |
+| `user` | Full user object |
+| `loading` | Auth operation in progress |
+| `error` | Last auth error message or null |
+
+## Blocked fields (always return `undefined`)
+
+`token`, `accessToken`, `access_token`, `refreshToken`, `refresh_token`,
+`password`, `secret`, `session`, `metadata.token`, `metadata.password`.
+
+## Examples
+
+Show user email:
+```json
+{ "$auth": "email" }
+```
+
+Visibility by role:
+```json
+"visible": { "$auth": "role", "eq": "admin" }
+```
+
+Login button label reflecting loading state:
+```json
+"label": { "$cond": { "$auth": "loading" }, "$then": "Signing in...", "$else": "Login" }
+```
+
+Avatar URL for the current user:
+```json
+{ "$template": "/avatars/${ /auth/user/id }.png" }
+```
+
+(Or with `$auth`: `{ "$template": "/avatars/${id}.png" }` after capturing
+via `$let`.)
+
+## Constraints / Anti-patterns
+
+- `$auth` in `derive` is NOT available — use `$state` to read from
+  `/auth/*` paths in derive expressions. See [[@concept-expression-contexts]].
+- Auth state paths (`/auth/*`) are read-only — see [[@path-app-screens]] +
+  [[@concept-state-protection]].
+
+## Related concepts
+
+- [[@path-app-screens]] — auto-managed `/auth/*` paths
+- [[@concept-auth-security]] — full guarantees + blocked-field list
+- [[@action-login]] — `login` action sets `$auth.*`
+- [[@concept-role-access]] — paired with `$auth.role`
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § AppSpec & Navigation → Login Screen`
+- `docs/consumer/reference-doc.md § Expression Types → $auth` + § Authentication

package/docs/wiki/compiled/expression-binditem.md

@@ -0,0 +1,52 @@
+---
+id: expression-binditem
+title: `$bindItem` — two-way binding to repeat item
+kind: expression
+sources: [docs/consumer/ai-context.md#expressions, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$bindItem` — two-way binding to repeat item
+
+`$bindItem` is the read+write equivalent of `$item`. Use it on input value
+props inside a `repeat` so each row's input updates that row's data.
+
+## Shape / Signature
+
+```json
+{ "$bindItem": "<fieldName>" }
+```
+
+## Examples
+
+Editable list of todos with completion checkboxes:
+```json
+"task-list": {
+  "type": "stack",
+  "repeat": { "statePath": "/tasks", "key": "id" },
+  "children": ["task-row"]
+},
+"task-row": {
+  "type": "checkbox",
+  "props": {
+    "checked": { "$bindItem": "completed" },
+    "label": { "$item": "title" }
+  }
+}
+```
+
+## Constraints / Anti-patterns
+
+- Only valid inside `repeat`. Outside, returns undefined.
+- Mutates the underlying array entry at the bound field — make sure the
+  array path is writable (not a derived path).
+
+## Related concepts
+
+- [[@expression-item-index]] — read-only equivalent
+- [[@expression-bindstate]] — non-repeat two-way binding
+- [[@concept-repeat]] — `repeat` config
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → State & Binding`
+- `docs/consumer/reference-doc.md § Expression Types → $bindItem`

package/docs/wiki/compiled/expression-bindstate.md

@@ -0,0 +1,63 @@
+---
+id: expression-bindstate
+title: `$bindState` — two-way binding
+kind: expression
+sources: [docs/consumer/ai-context.md#expressions, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$bindState` — two-way binding
+
+`$bindState` reads AND writes a state path. Use it on form-input value props
+(`input`, `textarea`, `select`, `checkbox`, `toggle`, `slider`, `tabs`) so the
+input reads its current value AND writes back to state on every change event.
+
+## Shape / Signature
+
+```json
+{ "$bindState": "/path/to/value" }
+```
+
+## Examples
+
+Text input bound to form state:
+```json
+{ "type": "input", "props": { "value": { "$bindState": "/form/email" } } }
+```
+
+Checkbox uses `checked` (NOT `value`):
+```json
+{ "type": "checkbox", "props": { "checked": { "$bindState": "/form/agreed" }, "label": "I agree" } }
+```
+
+Tabs:
+```json
+{ "type": "tabs", "props": { "value": { "$bindState": "/ui/activeTab" }, "items": [...] } }
+```
+
+## Resolution timing
+
+`$bindState` is **eager read at render** + **write on event**. There is no
+"resolve at press" semantics — the framework wires both directions at render.
+
+## Constraints / Anti-patterns
+
+- `checkbox` and `toggle` use the `checked` prop, **not `value`** — see
+  [[@antipattern-checkbox-toggle-value]].
+- Don't use `$bindState` on display-only props (`text.content`,
+  `image.src`) — there's nothing to write back. Use [[@expression-state]].
+- For dropdown patterns where consumer drives `applyPreset`, use
+  `$bindState` on `value` + `$state` in the action params (see
+  [[@concept-preset-dropdown-pattern]]). `$event` does NOT exist as an
+  expression — see [[@antipattern-event-expression]].
+
+## Related concepts
+
+- [[@expression-state]] — read-only equivalent
+- [[@expression-binditem]] — two-way binding inside `repeat`
+- [[@concept-forms]] — coordinated form state via `$bindState`
+- [[@antipattern-event-expression]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → State & Binding`
+- `docs/consumer/reference-doc.md § Expression Types → $bindState`

package/docs/wiki/compiled/expression-breakpoint.md

@@ -0,0 +1,71 @@
+---
+id: expression-breakpoint
+title: `$breakpoint` — responsive value
+kind: expression
+sources: [docs/consumer/ai-context.md#responsive--cross-platform, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$breakpoint` — responsive value
+
+`$breakpoint` resolves to different values based on viewport width. Auto-tracked
+— the renderer writes `/ui/device/viewportWidth` on mount and resize.
+Default breakpoints: `sm: 0`, `md: 768`, `lg: 1024`, `xl: 1280`. Override via
+design tokens.
+
+## Shape / Signature
+
+```json
+{ "$breakpoint": { "sm": <value>, "md": <value>, "lg": <value>, "xl": <value> } }
+```
+
+Missing breakpoints inherit from the smallest defined one below the current
+viewport.
+
+## Examples
+
+Responsive grid columns:
+```json
+{
+  "type": "grid",
+  "props": { "columns": { "$breakpoint": { "sm": 1, "md": 2, "lg": 3 } } }
+}
+```
+
+Responsive padding:
+```json
+"style": {
+  "padding": { "$breakpoint": { "sm": "16px", "md": "24px", "lg": "32px" } }
+}
+```
+
+Responsive direction (stack flips on small screens):
+```json
+"props": { "direction": { "$breakpoint": { "sm": "vertical", "md": "horizontal" } } }
+```
+
+## Recommended responsive defaults
+
+| Property | Mobile (sm) | Tablet (md) | Desktop (lg+) |
+|---|---|---|---|
+| `direction` | `"vertical"` | `"horizontal"` | `"horizontal"` |
+| `columns` | `1` | `2` | `3-4` |
+| `gap` | `12` | `16` | `24` |
+| `padding` | `"16px"` | `"24px"` | `"32px"` |
+
+## Constraints / Anti-patterns
+
+- **Always use `$breakpoint` for layout properties.** Hardcoding desktop-only
+  values produces broken mobile UX.
+- For platform-specific TECHNIQUES (CSS blur vs native BlurView), use
+  [[@expression-platform]] instead.
+
+## Related concepts
+
+- [[@expression-platform]] — cross-platform variant
+- [[@path-ui-device]] — `/ui/device/*` paths
+- [[@concept-token-categories]] — override breakpoints via tokens
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Responsive & Cross-Platform → $breakpoint`
+- `docs/consumer/reference-doc.md § Expression Types → $breakpoint`

package/docs/wiki/compiled/expression-computed.md

@@ -0,0 +1,52 @@
+---
+id: expression-computed
+title: `$computed` — registered function
+kind: expression
+sources: [docs/consumer/ai-context.md#values--formatting, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$computed` — registered function
+
+`$computed` calls a registered function with resolved arguments. **Prefer the
+built-in operators** ([[@expression-math]], [[@expression-array]],
+[[@expression-date]], [[@expression-format]]) — built-in operations cover
+90%+ of cases without registering code.
+
+## Shape / Signature
+
+```json
+{ "$computed": "<functionName>", "args": { "<argName>": <expr>, ... } }
+```
+
+## Examples
+
+```json
+{
+  "$computed": "calculateBMI",
+  "args": {
+    "weight": { "$state": "/patient/weight" },
+    "height": { "$state": "/patient/height" }
+  }
+}
+```
+
+## Constraints / Anti-patterns
+
+- **Prefer built-in expressions.** Use `$computed` only when no
+  combination of `$math` / `$array` / `$date` / `$format` covers the case.
+- The function must be registered with the engine via host-app config —
+  `$computed` references resolve only against that registry.
+- Args are resolved before the function runs.
+
+## Related concepts
+
+- [[@expression-math]] — arithmetic
+- [[@expression-array]] — array ops
+- [[@expression-date]] — date ops
+- [[@expression-format]] — value formatting
+- [[@concept-derive]] — derived state for memoizing computed values
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Values & Formatting → $computed`
+- `docs/consumer/reference-doc.md § Expression Types → $computed`

package/docs/wiki/compiled/expression-cond.md

@@ -0,0 +1,78 @@
+---
+id: expression-cond
+title: `$cond` / `$then` / `$else` — conditional value
+kind: expression
+sources: [docs/consumer/ai-context.md#conditionals--logic, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$cond` / `$then` / `$else`
+
+`$cond` evaluates a condition and returns `$then` if truthy, `$else` otherwise.
+Operators: `eq`, `neq`, `gt`, `gte`, `lt`, `lte`, `not`. Both branches can be
+arbitrary expressions.
+
+## Shape / Signature
+
+```json
+{
+  "$cond": <expression-or-condition>,
+  "$then": <value>,
+  "$else": <value>
+}
+```
+
+Truthiness check:
+```json
+{ "$cond": { "$state": "/form/isValid" }, "$then": "green", "$else": "gray" }
+```
+
+Operator form:
+```json
+{ "$cond": { "$item": "priority", "eq": "urgent" }, "$then": "#EF4444", "$else": "#22C55E" }
+```
+
+## Examples
+
+Disable button conditionally:
+```json
+"disabled": {
+  "$cond": { "$state": "/x", "eq": 0 },
+  "$then": true,
+  "$else": false
+}
+```
+
+Nested for multi-branch (prefer [[@expression-switch]] for 3+ branches):
+```json
+{
+  "$cond": { "$item": "priority", "eq": "urgent" },
+  "$then": "#EF4444",
+  "$else": {
+    "$cond": { "$item": "priority", "eq": "high" },
+    "$then": "#F97316",
+    "$else": "#22C55E"
+  }
+}
+```
+
+## Constraints / Anti-patterns
+
+- **For 3+ branches use [[@expression-switch]].** Deeply nested `$cond`
+  becomes unreadable.
+- **`$state` with `eq` only resolves to boolean in `visible`.** For
+  `disabled` and other props, wrap in `$cond` (the trap above).
+- `requiredIf` is truthy-only — does NOT support `eq`. To require
+  conditionally on a specific value, derive a boolean first via `$cond` in
+  `derive`, then `requiredIf` on that derived path. See
+  [[@antipattern-required-if-equals]] + [[@pattern-form-validation-cross-field]].
+
+## Related concepts
+
+- [[@expression-switch]] — multi-branch alternative
+- [[@expression-and-or-not]] — boolean composition
+- [[@concept-derive]] — derived booleans for conditional rules
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Conditionals & Logic`
+- `docs/consumer/reference-doc.md § Expression Types → $cond / $then / $else`