mythik 0.0.1 → 0.1.0

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

@@ -0,0 +1,58 @@
+---
+id: expression-selection
+title: `$selection` — selection state (inside repeat.selection)
+kind: expression
+sources: [docs/consumer/ai-context.md#group--selection-inside-repeat, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$selection` — selection state
+
+Inside a `repeat` with a `selection` config, `$selection` reads selection
+state for the current item.
+
+## Shape / Signature
+
+```json
+{ "$selection": "selected" }
+{ "$selection": "count" }
+```
+
+| Op | Returns | Description |
+|---|---|---|
+| `selected` | boolean | Whether the current item's key is in the selection array |
+| `count` | number | Total selected items |
+
+## Examples
+
+Per-row checkbox bound to selection:
+```json
+"select-checkbox": {
+  "type": "checkbox",
+  "props": { "checked": { "$selection": "selected" } },
+  "on": { "change": { "action": "toggleSelection", "params": { "statePath": "/selectedIds", "value": { "$item": "id" } } } }
+}
+```
+
+Count badge in header:
+```json
+"selection-count": {
+  "type": "text",
+  "props": { "content": { "$template": "${count} selected", "args": {} } }
+}
+```
+
+## Constraints / Anti-patterns
+
+- **Only valid inside `repeat` with `selection` config.** Throws an error
+  if used outside.
+
+## Related concepts
+
+- [[@concept-repeat-selection]] — selection config
+- [[@action-selection]] — `toggleSelection` / `selectAll` / `selectNone`
+- [[@expression-item-index]] — current row id for toggle action
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Group & Selection`
+- `docs/consumer/reference-doc.md § Expression Types → $selection`

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

@@ -0,0 +1,70 @@
+---
+id: expression-state
+title: `$state` — read from state
+kind: expression
+sources: [docs/consumer/ai-context.md#expressions, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$state` — read from state
+
+`$state` reads a value from the application state store at the given JSON
+Pointer path. It is the most common expression and works in nearly every
+context (props, visible, style, derive, repeat.source, $template, transaction).
+
+## Shape / Signature
+
+```json
+{ "$state": "/path/to/value" }
+```
+
+Can carry an `eq` operator (boolean shortcut) when used in `visible`:
+```json
+{ "$state": "/user/role", "eq": "admin" }
+```
+
+## Examples
+
+Read a value:
+```json
+{ "type": "text", "props": { "content": { "$state": "/user/name" } } }
+```
+
+Boolean check in `visible`:
+```json
+"visible": { "$state": "/user/role", "eq": "admin" }
+```
+
+Use inside `$template`:
+```json
+{ "$template": "Hello, ${/user/name}!" }
+```
+
+Inside `$array` source:
+```json
+{ "$array": "count", "source": { "$state": "/items" } }
+```
+
+## Constraints / Anti-patterns
+
+- **Trap:** `$state` with `eq` only works as a boolean condition in `visible`.
+  For `disabled` / other props that need a strict boolean, wrap in `$cond`:
+  ```json
+  { "$cond": { "$state": "/x", "eq": 0 }, "$then": true, "$else": false }
+  ```
+- For auth user data, prefer [[@expression-auth]] — `$auth` is whitelisted and
+  blocks tokens/passwords; `$state: "/auth/user/email"` works but is less safe.
+- Some paths are framework-managed (read-only). Writing to them via `setState`
+  triggers StateGuard rejection — see [[@concept-state-protection]].
+
+## Related concepts
+
+- [[@expression-bindstate]] — two-way binding equivalent
+- [[@expression-template]] — `$state` interpolation in strings
+- [[@expression-cond]] — wrap `$state` for non-boolean contexts
+- [[@concept-expression-timing]] — when `$state` resolves
+- [[@concept-state-protection]] — read-only paths
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → State & Binding`
+- `docs/consumer/reference-doc.md § Expression Types → $state`

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

@@ -0,0 +1,68 @@
+---
+id: expression-switch
+title: `$switch` — multi-branch conditional
+kind: expression
+sources: [docs/consumer/ai-context.md#conditionals--logic, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$switch` — multi-branch conditional
+
+`$switch` evaluates an expression, converts the result to string, looks up in
+`cases`, and returns the matched value (or `default` if no match). Use for
+3+ branches instead of nested `$cond`. **`default` is required** — prevents
+silent `undefined`.
+
+## Shape / Signature
+
+```json
+{
+  "$switch": <expression>,
+  "cases": { "<key>": <value>, "...": "..." },
+  "default": <value>
+}
+```
+
+Cases are looked up by string match against the resolved expression.
+
+## Examples
+
+Categorize by numeric type:
+```json
+{
+  "$switch": { "$state": "/filter/type" },
+  "cases": {
+    "1": "Current Expenses",
+    "2": "Capital Expenses",
+    "3": { "$token": "colors.warning" }
+  },
+  "default": "Other"
+}
+```
+
+Drive variant dynamically (consumer of [[@concept-custom-elements]]):
+```json
+"variant": {
+  "$switch": { "$state": "/filter/tipoEjecucion" },
+  "cases": { "1": "active" },
+  "default": "inactive"
+}
+```
+
+## Constraints / Anti-patterns
+
+- **`default` is required.** Omitting it produces silent `undefined` at
+  runtime if no case matches.
+- Cases match the **stringified** evaluation. Numbers, booleans, and
+  enums all match string keys.
+- Only the matching case is resolved (lazy evaluation). Other case
+  expressions are not evaluated.
+
+## Related concepts
+
+- [[@expression-cond]] — 2-branch alternative
+- [[@expression-and-or-not]] — boolean composition
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Conditionals & Logic → $switch`
+- `docs/consumer/reference-doc.md § Expression Types → $switch`

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

@@ -0,0 +1,71 @@
+---
+id: expression-template
+title: `$template` — string interpolation
+kind: expression
+sources: [docs/consumer/ai-context.md#values--formatting, docs/consumer/ai-context-runtime-semantics.md#15-template-interpolation]
+---
+
+# `$template` — string interpolation
+
+`$template` interpolates values into a string. Two reference forms:
+`${/state/path}` reads from state, `${name}` reads from a `$let` binding.
+Resolves at the consumption site — at render in element props, at dispatch in
+action params.
+
+## Shape / Signature
+
+```json
+{ "$template": "literal text ${/state/path} and ${letBindingName}" }
+```
+
+## Examples
+
+State interpolation:
+```json
+{ "$template": "Hello, ${/user/name}! You have ${/inbox/count} messages." }
+```
+
+URL with state:
+```json
+{ "$template": "${/config/apiUrl}/rest/v1/items?id=eq.${/form/editId}" }
+```
+
+Combined with `$let` (when `$item` is needed inside `$template`):
+```json
+{
+  "$let": { "x": { "$item": "name" } },
+  "$in": { "$template": "Editing: ${x}" }
+}
+```
+
+## Constraints / Anti-patterns
+
+- **`$template` does NOT resolve `$item` directly.** `$item` is a JSON
+  expression, not a string token. Capture in `$let` first (see example
+  above) — see also [[@concept-expression-contexts]].
+- **`$template` does NOT resolve in transaction phases.** Capture row data
+  via `setState` before the transaction fires.
+- **Plain strings containing `${...}` are LITERAL** in `DataSourceConfig.url`.
+  Wrap in `$template` to enable templating — the validator catches plain
+  strings with `${...}` and points to the fix. See
+
+## Resolution timing
+
+| Surface | Timing |
+|---|---|
+| Element prop | Eager at render |
+| Action param | Lazy at dispatch |
+
+## Related concepts
+
+- [[@concept-template-interpolation]] — full timing contract
+- [[@expression-let-ref]] — capture values for use in `$template`
+- [[@expression-state]] — `${/path}` form
+- [[@concept-expression-contexts]] — where `$template` works
+- [[@concept-data-sources]] — URL template gotcha
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Expressions → Values & Formatting → $template`
+- `docs/consumer/ai-context-runtime-semantics.md § 1.5`
+- `docs/consumer/reference-doc.md § Expression Types → $template`

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

@@ -0,0 +1,67 @@
+---
+id: expression-token
+title: `$token` — design system reference
+kind: expression
+sources: [docs/consumer/ai-context.md#deep-design-token-system, docs/consumer/reference-doc.md#expression-types]
+---
+
+# `$token` — design system reference
+
+`$token` resolves a value from the active design tokens (colors, shape,
+typography, spacing, elevation, motion, opacity). Use dot notation to address
+the token tree. Auto-respects `/preferences/theme` for dark mode — no manual
+switching required.
+
+## Shape / Signature
+
+```json
+{ "$token": "colors.primary" }
+{ "$token": "spacing.unit", "multiply": 3 }
+```
+
+`multiply` scales numeric tokens (e.g., `spacing.unit * 3`).
+
+## Examples
+
+Visual values from tokens:
+```json
+{ "type": "box", "style": {
+  "backgroundColor": { "$token": "colors.surface" },
+  "borderRadius": { "$token": "shape.radius.lg" },
+  "padding": { "$token": "spacing.scale.md" }
+}}
+```
+
+Elevation auto-converts to CSS `boxShadow` string on web:
+```json
+"style": { "boxShadow": { "$token": "elevation.lg" } }
+```
+
+Scheme-aware values in identity-driven previews:
+```json
+{ "$token": "schemeColors.text" }
+{ "$token": "colorWeight.navBg" }
+```
+
+## Constraints / Anti-patterns
+
+- **Tokens are project-defined.** No framework defaults — if no tokens are
+  declared, use direct CSS values.
+- **Use `$token` for ALL visual values** (rule 5/2) — never hardcode colors,
+  spacing, or fonts. Hardcoded values break dark mode and identity changes.
+- `$token: "backgroundCSS"` was REMOVED in the current LayerBackground contract. Use
+  `tokens.identity.background` as a `LayerBackground` instead — see
+  [[@antipattern-background-css-token]].
+
+## Related concepts
+
+- [[@concept-token-system]] — three-layer resolution (defaults → DNA → manual)
+- [[@concept-token-categories]] — full path catalogue
+- [[@concept-dna-seeds]] — DNA-driven token generation
+- [[@concept-component-variants]] — `$path` references inside variants
+- [[@concept-auto-dark-mode]] — `$token` and dark mode
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Deep Design Token System`
+- `docs/consumer/reference-doc.md § Expression Types → $token` + § Deep Design Token System

package/docs/wiki/compiled/path-app-screens.md

@@ -0,0 +1,55 @@
+---
+id: path-app-screens
+title: `/app/screens` — accessible screens
+kind: concept
+sources: [docs/consumer/ai-context.md#auto-generated-state]
+---
+
+# `/app/screens`
+
+Auto-generated array of accessible screen definitions, **filtered by
+role**, with the loginScreen excluded. Source for the sidebar menu.
+
+## Shape
+
+```json
+[
+  { "id": "dashboard", "label": "Dashboard", "icon": "chart-bar" },
+  { "id": "reports",   "label": "Reports",   "icon": "file-text" }
+]
+```
+
+## Sidebar nav pattern
+
+```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"]
+}
+```
+
+## Auto-refresh on auth changes
+
+`MythikApp` subscribes to `/auth/user/*` and `/auth/isAuthenticated` and
+re-computes `/app/screens` automatically. No manual call needed after
+login, logout, session restore, cross-tab sync, or role changes.
+
+If building a custom host app without `MythikApp`, call
+`appEngine.refreshScreenList()` after auth state changes.
+
+## Related concepts
+
+- [[@concept-navigation]]
+- [[@concept-role-access]]
+- [[@concept-app-auto-state-paths]]
+- [[@expression-auth]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Auto-Generated State`

package/docs/wiki/compiled/path-data-source-paths.md

@@ -0,0 +1,44 @@
+---
+id: path-data-source-paths
+title: DataSources auto-paths — `/{target}Loading`, `/{target}Error`, `/{target}Deferred`
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#24-uiloading-uilasterror-and-datasources-loadingerror-paths, docs/consumer/ai-context-runtime-semantics.md#9-derive-and-datasources-lifecycle-v010--item-e]
+---
+
+# DataSources auto-paths
+
+For a dataSource with `target: "/tasks"`, the framework writes
+auto-managed paths.
+
+| Path | Type | When |
+|---|---|---|
+| `/tasks` | response data | Fetch resolves |
+| `/tasksLoading` | boolean | `true` during in-flight, `false` after resolve/reject |
+| `/tasksError` | object \| null | Error message on failure, `null` on success |
+| `/tasksDeferred` | boolean | `true` when initial fetch is skipped because URL template deps are unresolved (Item E). Render "waiting for prerequisite" UI distinct from loading |
+
+## `Deferred` use case
+
+Render a "waiting for X" placeholder when the URL depends on data that
+hasn't loaded yet — distinct from "loading" (request in flight) and
+"empty" (loaded but no rows):
+
+```json
+"waiting": { "visible": { "$state": "/tasksDeferred" } }
+```
+
+## Implementation
+
+`packages/core/src/data/data-sources.ts:76-86` (loadingPath / errorPath
+derivation + write on fetch start).
+
+## Related concepts
+
+- [[@concept-data-sources]]
+- [[@concept-data-sources-lifecycle]]
+- [[@path-ui-loading-error]]
+- [[@pattern-loading-content-empty]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 2.4` + § 9

package/docs/wiki/compiled/path-forms.md

@@ -0,0 +1,38 @@
+---
+id: path-forms
+title: `/ui/forms/{id}/*` — declarative form state
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#26-forms-state-paths-formid]
+---
+
+# `/ui/forms/{id}/*`
+
+When a form is declared in `spec.forms`, the framework reserves the
+`/ui/forms/{formId}/*` subtree for form state. Internal keys (`__valid`,
+`__touched`, `__errors`) are framework-owned.
+
+## Paths
+
+See [[@concept-form-state-paths]] for the full table:
+- `/ui/forms/{id}/isValid`
+- `/ui/forms/{id}/errorCount`
+- `/ui/forms/{id}/isDirty`
+- `/ui/forms/{id}/fields/{field}/errors`
+- `/ui/forms/{id}/fields/{field}/touched`
+- `/ui/forms/{id}/fields/{field}/dirty`
+
+## Read patterns
+
+Prefer `$formValid` / `$formField` expressions where they exist —
+abstract over internal flag paths and future-proof against framework
+changes.
+
+## Related concepts
+
+- [[@concept-forms]]
+- [[@concept-form-state-paths]]
+- [[@concept-state-protection]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 2.6`

package/docs/wiki/compiled/path-login.md

@@ -0,0 +1,57 @@
+---
+id: path-login
+title: `/screens/login/*` and `/login/*`
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#25-login]
+---
+
+# `/screens/login/*` and `/login/*`
+
+Two conventions for login form state — pick one and use consistently.
+
+## `/screens/login/*` (canonical for AppSpec)
+
+```json
+"value": { "$bindState": "/screens/login/email" }
+"value": { "$bindState": "/screens/login/password" }
+```
+
+Combined with `statePolicy: "reset"` on the login screen, AppEngine
+clears `/screens/login` when navigating to the login screen — credentials
+auto-clear on logout.
+
+## `/login/*` (framework convention for runtime-semantics)
+
+The runtime-semantics doc and `login` action use `/login/username` /
+`/login/password` paths in some examples:
+
+```json
+{ "action": "login", "params": {
+  "username": { "$state": "/login/username" },
+  "password": { "$state": "/login/password" }
+}}
+```
+
+These are auto-cleared on logout (rule 47).
+
+## Pick one
+
+**For AppSpec apps**: use `/screens/login/*` + `statePolicy: "reset"`.
+**For email-convention apps**: use `loginBody` template to map at the spec
+level — see [[@pattern-login-body-template]].
+
+## Constraints
+
+- **Don't use `/form/*` for login fields** — root-level paths persist
+  across logouts (rule 30).
+
+## Related concepts
+
+- [[@action-login]]
+- [[@pattern-login-screen]]
+- [[@pattern-login-body-template]]
+- [[@concept-state-policies]] — `reset` policy
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 2.5`

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

@@ -0,0 +1,62 @@
+---
+id: path-navigation
+title: `/navigation/*` — navigation state
+kind: concept
+sources: [docs/consumer/ai-context.md#auto-generated-state]
+---
+
+# `/navigation/*`
+
+Navigation state auto-managed by AppEngine.
+
+## Paths
+
+| Path | Type | Content |
+|---|---|---|
+| `/navigation/currentScreen` | string | Active screen ID |
+| `/navigation/history` | string[] | Visited screen IDs (in order) |
+| `/navigation/breadcrumb` | array | Enriched array with `label`, `icon` per entry |
+| `/navigation/params` | object | Extra params from `navigateScreen` (reset on each navigation) |
+
+## Breadcrumb modes
+
+The shape of `/navigation/breadcrumb` depends on `navigation.breadcrumb`:
+
+| Mode | Behavior |
+|---|---|
+| `"history"` | Follows nav stack |
+| `"hierarchy"` | Follows `parent` chain |
+| `"none"` | Empty / not computed |
+
+## Read patterns
+
+Active screen:
+```json
+{ "$state": "/navigation/currentScreen" }
+```
+
+Render breadcrumb:
+```json
+{ "type": "stack", "repeat": { "statePath": "/navigation/breadcrumb", "key": "id" }, "children": ["crumb"] }
+```
+
+Read navigation params on target screen:
+```json
+{ "$state": "/navigation/params/employeeId" }
+```
+
+## `/navigation/params` is reset on each navigation
+
+For data that persists across back-navigation, use `/ui/selected*` (e.g.,
+`/ui/selectedRow`) instead.
+
+## Related concepts
+
+- [[@concept-navigation]]
+- [[@action-navigate]]
+- [[@concept-app-auto-state-paths]]
+- [[@pattern-cross-screen-data-flow]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Auto-Generated State`

package/docs/wiki/compiled/path-presets-available.md

@@ -0,0 +1,44 @@
+---
+id: path-presets-available
+title: `/presets/available` — registered presets
+kind: concept
+sources: [docs/consumer/reference-doc.md#presets-system]
+---
+
+# `/presets/available`
+
+State path written by `plugins.registerPresets`. Holds an array of
+`{ value, label }` for use as `select.options` in preset-dropdown patterns.
+
+## Shape
+
+```json
+[
+  { "value": "startup-saas", "label": "Startup SaaS" },
+  { "value": "neumorphic-ios", "label": "Neumorphic iOS" }
+]
+```
+
+## Use in specs
+
+```json
+{ "type": "select",
+  "props": {
+    "options": { "$state": "/presets/available" },
+    "value": { "$bindState": "/ui/currentPreset" }
+  }
+}
+```
+
+See [[@concept-preset-dropdown-pattern]] for the full pattern.
+
+## Related concepts
+
+- [[@concept-presets]]
+- [[@concept-register-presets]]
+- [[@concept-preset-dropdown-pattern]]
+- [[@action-apply-preset]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § Presets System`