mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/antipattern-auth-domains-port.md

@@ -0,0 +1,47 @@
+---
+id: antipattern-auth-domains-port
+title: Anti-pattern — `:port` in `authDomains`
+kind: pattern
+sources: [docs/consumer/ai-context-runtime-semantics.md#41-authdomains-hostname-only--blocker-5, docs/consumer/reference-doc.md#rule-71]
+---
+
+# Anti-pattern — `:port` in `authDomains`
+
+The `authDomains` matcher uses `URL.hostname` for comparison — **port is
+silently stripped**. An entry containing `:port` literally never matches
+any URL's hostname.
+
+## Wrong
+
+```json
+"authDomains": ["localhost:5173"]
+```
+
+The matcher compares `URL.hostname` (just `"localhost"`) against the
+entry (`"localhost:5173"` — contains `:5173`). Never matches → tokens
+never inject in dev → "auth works in prod but not dev with localhost:5173"
+symptom.
+
+## Right
+
+```json
+"authDomains": ["localhost"]
+```
+
+Matches all localhost ports (5173, 3010, etc.).
+
+## Detection
+
+`mythik lint` rule **`spec-auth-domains-port`** (severity: warning).
+Also runs during `mythik push` and `mythik validate`. See [[@cli-lint]].
+
+## Related concepts
+
+- [[@concept-auth-domains]]
+- [[@concept-fetch-interceptors]]
+- [[@cli-lint]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 4.1` + § 7.4
+- `docs/consumer/reference-doc.md § rules 71, 249`

package/docs/wiki/compiled/antipattern-background-blobs-prop.md

@@ -0,0 +1,62 @@
+---
+id: antipattern-background-blobs-prop
+title: Anti-pattern — `Box.backgroundBlobs` prop
+kind: pattern
+sources: [docs/consumer/ai-context.md#rule-56, docs/consumer/reference-doc.md#rules-154-222]
+---
+
+# Anti-pattern — `Box.backgroundBlobs` prop
+
+The `Box` `backgroundBlobs` prop was **REMOVED** in the current LayerBackground contract along
+with legacy per-element blob rendering. Setting it has no effect.
+
+## Wrong
+
+```json
+{ "type": "box", "props": { "backgroundBlobs": true } }
+```
+
+Silently ignored.
+
+## Right — use `tokens.identity.background`
+
+App-level background lives exclusively at `tokens.identity.background`
+(see [[@concept-layer-background]]) and mounts at `MythikRenderer` via
+`<BackgroundStack>`.
+
+```json
+"tokens": {
+  "identity": {
+    "background": {
+      "color": "#0a0a0a",
+      "layers": [
+        {
+          "type": "blobs",
+          "preset": "organic-duo",
+          "palette": ["primary", "accent"],
+          "motion": "drift-gentle"
+        }
+      ]
+    }
+  }
+}
+```
+
+## Why removed
+
+Box is now a pure surface-styled wrapper. Removed the
+`dangerouslySetInnerHTML` keyframe-injection path (previously at
+`box.tsx:127`) — zero `dangerouslySetInnerHTML` in
+`packages/react/src/primitives/*` (rule 154).
+
+## Related concepts
+
+- [[@concept-layer-background]]
+- [[@concept-blob-layer]]
+- [[@primitive-box]]
+- [[@antipattern-background-css-token]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § rule 56`
+- `docs/consumer/reference-doc.md § rules 154, 222`

package/docs/wiki/compiled/antipattern-background-css-token.md

@@ -0,0 +1,53 @@
+---
+id: antipattern-background-css-token
+title: Anti-pattern — `$token: "backgroundCSS"`
+kind: pattern
+sources: [docs/consumer/ai-context.md#rule-57, docs/consumer/reference-doc.md#rule-155]
+---
+
+# Anti-pattern — `$token: "backgroundCSS"`
+
+`$token: "backgroundCSS"` was REMOVED in the current LayerBackground contract. The field was
+deleted from `injectColorTokens` and no longer resolves.
+
+## Wrong
+
+```json
+"style": { "background": { "$token": "backgroundCSS" } }
+```
+
+Returns `undefined` at render → element has no background.
+
+## Right — use `tokens.identity.background` (LayerBackground)
+
+```json
+"tokens": {
+  "identity": {
+    "background": {
+      "color": "#0a0a0a",
+      "layers": [...]
+    }
+  }
+}
+```
+
+`MythikRenderer` mounts a root `<BackgroundStack>` that reads from
+`/tokens/resolved` and re-renders on preset switches. See
+[[@concept-layer-background]].
+
+## Why removed
+
+For preset-aware app backgrounds, presets update
+`tokens.identity.background` directly so the root `<BackgroundStack>`
+re-resolves on preset switch — no token alias indirection needed.
+
+## Related concepts
+
+- [[@concept-layer-background]]
+- [[@concept-background-stack]]
+- [[@antipattern-background-blobs-prop]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § rule 57`
+- `docs/consumer/reference-doc.md § rule 155, 222`

package/docs/wiki/compiled/antipattern-checkbox-toggle-value.md

@@ -0,0 +1,42 @@
+---
+id: antipattern-checkbox-toggle-value
+title: Anti-pattern — `value` on checkbox/toggle
+kind: pattern
+sources: [docs/consumer/ai-context-primitives.md#checkbox, docs/consumer/ai-context-primitives.md#toggle]
+---
+
+# Anti-pattern — `value` on checkbox/toggle
+
+`checkbox` and `toggle` use the **`checked`** prop, NOT `value`. Using
+`value` is silently ignored — element appears un-bound.
+
+## Wrong
+
+```json
+{ "type": "checkbox", "props": { "value": { "$bindState": "/form/agreed" } } }
+{ "type": "toggle",   "props": { "value": { "$bindState": "/preferences/darkMode" } } }
+```
+
+## Right
+
+```json
+{ "type": "checkbox", "props": { "checked": { "$bindState": "/form/agreed" } } }
+{ "type": "toggle",   "props": { "checked": { "$bindState": "/preferences/darkMode" } } }
+```
+
+## Why
+
+`checkbox` is rendered as a custom div+SVG (NOT native browser checkbox).
+The framework standardized on `checked` to clarify the boolean semantics
+— surface-aware adapt to identity (bold = thick border, neo = inset
+shadow, flat = no border).
+
+## Related concepts
+
+- [[@primitive-checkbox]]
+- [[@primitive-toggle]]
+- [[@expression-bindstate]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § checkbox, toggle`

package/docs/wiki/compiled/antipattern-crud-id-collision.md

@@ -0,0 +1,66 @@
+---
+id: antipattern-crud-id-collision
+title: Anti-pattern — CRUD `:id` collision
+kind: pattern
+sources: [docs/consumer/ai-context-api.md#endpoints, docs/consumer/ai-context-runtime-semantics.md#31-crud--one-endpoint-three-routes--blocker-3, docs/consumer/reference-doc.md#rule-70]
+---
+
+# Anti-pattern — CRUD `:id` collision
+
+`crud: {}` automatically generates `POST <path>`, `PUT <path>/:id`, and
+`DELETE <path>/:id` from a single endpoint declaration. **Combining
+`crud: {}` with `endpoint.path` ending `/:id` produces broken
+`/path/:id/:id` routes.**
+
+## Wrong
+
+```json
+"endpoints": {
+  "room-create": { "path": "/api/rooms",     "method": "POST",   "crud": { } },
+  "room-update": { "path": "/api/rooms/:id", "method": "PUT",    "crud": { } },
+  "room-delete": { "path": "/api/rooms/:id", "method": "DELETE", "crud": { } }
+}
+```
+
+Each `crud:{}` is processed independently:
+- `room-update` at `/api/rooms/:id` + auto-append `/:id` → `PUT /api/rooms/:id/:id` (broken).
+- Every CRUD endpoint also registers POST at `<path>` — collisions compound.
+- Consumer-facing symptom: routes clash in Express; requests return 404 or match wrong handler.
+
+## Right
+
+ONE endpoint at the base path with `crud: {}`:
+
+```json
+"rooms": {
+  "path": "/api/rooms",
+  "policy": "admin",
+  "crud": {
+    "table": "Rooms",
+    "primaryKey": "id",
+    "insertable": ["name", "capacity", "location"],
+    "updatable": ["name", "capacity", "location"]
+  }
+}
+```
+
+Framework synthesizes `POST /api/rooms`, `PUT /api/rooms/:id`,
+`DELETE /api/rooms/:id` automatically.
+
+## Detection
+
+`mythik lint` rule **`spec-crud-id-collision`** (severity: **error**)
+catches `endpoint.path` ending `/:id` combined with `crud: {}`. Also
+runs during `mythik validate` and `mythik push`. See [[@cli-lint]].
+
+## Related concepts
+
+- [[@concept-api-crud-endpoint]]
+- [[@concept-api-endpoints-overview]]
+- [[@cli-lint]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-api.md § Anti-pattern`
+- `docs/consumer/ai-context-runtime-semantics.md § 3.1`
+- `docs/consumer/reference-doc.md § rules 70, 249`

package/docs/wiki/compiled/antipattern-derive-server-pagination.md

@@ -0,0 +1,58 @@
+---
+id: antipattern-derive-server-pagination
+title: Anti-pattern — `derive` over server-paginated state
+kind: pattern
+sources: [docs/consumer/ai-context-patterns.md#derive-only-sees-current-page-data, docs/consumer/ai-context.md#derived-state]
+---
+
+# Anti-pattern — `derive` over server-paginated state
+
+`derive` operates on data **in state only**. With server-side pagination,
+state holds the current page — derive sums/counts reflect the page, NOT
+the full dataset.
+
+## Wrong
+
+```json
+{
+  "dataSources": {
+    "items": { "url": "/api/items", "params": { "page": { "$state": "/page" } }, "target": "/items" }
+  },
+  "derive": {
+    "/stats/totalAmount": { "$array": "sum", "source": { "$state": "/items/data" }, "field": "amount" }
+  }
+}
+```
+
+`/stats/totalAmount` is the sum of the **current page only** — typically
+not what the user expected.
+
+## Right — use API totals
+
+For full-dataset totals with server pagination, fetch totals from the API
+via the endpoint's `totals` config:
+
+```json
+"item-list": {
+  "path": "/api/items",
+  "query": "SELECT id, name, amount FROM Items",
+  "pagination": "offset",
+  "totals": ["SUM:amount", "COUNT:*"]
+}
+```
+
+The query response envelope includes `totals` — see
+[[@concept-query-envelope]].
+
+## Related concepts
+
+- [[@concept-derive]]
+- [[@concept-data-sources]]
+- [[@concept-api-query-endpoint]]
+- [[@concept-query-envelope]]
+- [[@expression-array]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-patterns.md § Derive only sees current page data`
+- `docs/consumer/ai-context.md § Derived State (warning paragraph)`

package/docs/wiki/compiled/antipattern-element-variant-top-level.md

@@ -0,0 +1,57 @@
+---
+id: antipattern-element-variant-top-level
+title: Anti-pattern — top-level `variant` field
+kind: pattern
+sources: [docs/consumer/ai-context.md#rule-67, docs/consumer/reference-doc.md#rule-240]
+---
+
+# Anti-pattern — top-level `variant` field
+
+`variant` is a **prop**. Place it inside `props`, NEVER as a top-level
+element field. Top-level `variant` is **silently ignored** by the
+renderer (reads `props.variant` only).
+
+## Wrong
+
+```json
+{ "type": "stat-card", "variant": "primary", "props": { ... } }
+```
+
+`variant: "primary"` is silently ignored.
+
+## Right
+
+```json
+{ "type": "stat-card", "props": { "variant": "primary", ... } }
+```
+
+## Applies to
+
+- Built-in primitives with `tokens.components` variants (button, box, etc.)
+- Layer 3 custom elements with `ElementDefinition.variants`
+
+## Dynamic variant
+
+Consumer may drive variant dynamically via expression:
+
+```json
+"props": {
+  "variant": {
+    "$switch": { "$state": "/filter/tipoEjecucion" },
+    "cases": { "1": "active" },
+    "default": "inactive"
+  }
+}
+```
+
+## Related concepts
+
+- [[@concept-component-variants]]
+- [[@concept-element-variants]]
+- [[@concept-element-properties]]
+- [[@expression-switch]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § rule 67`
+- `docs/consumer/reference-doc.md § rule 240`

package/docs/wiki/compiled/antipattern-event-expression.md

@@ -0,0 +1,55 @@
+---
+id: antipattern-event-expression
+title: Anti-pattern — `$event` expression
+kind: pattern
+sources: [docs/consumer/ai-context.md#rule-61, docs/consumer/reference-doc.md#rules-61-169]
+---
+
+# Anti-pattern — `$event`
+
+**`$event` is NOT a valid expression handler.** Do NOT use
+`{ "$event": "value" }` in action params. The literal string `"$event"`
+is treated as a value.
+
+## Wrong
+
+```json
+{ "type": "select",
+  "on": { "change": [{ "action": "applyPreset", "params": { "preset": { "$event": "value" } } }] }
+}
+```
+
+## Right — `$bindState` + `$state` pattern
+
+For select / control `on:change`, use `$bindState` on the value prop for
+two-way binding, then read the value via `$state` in the action:
+
+```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`. Action chains commit state between steps.
+
+## Related concepts
+
+- [[@expression-bindstate]]
+- [[@expression-state]]
+- [[@concept-action-chains]]
+- [[@concept-preset-dropdown-pattern]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § rule 61`
+- `docs/consumer/reference-doc.md § rules 61, 169`

package/docs/wiki/compiled/antipattern-input-type-name.md

@@ -0,0 +1,43 @@
+---
+id: antipattern-input-type-name
+title: Anti-pattern — `inputType` instead of `type`
+kind: pattern
+sources: [docs/consumer/ai-context-primitives.md#input, docs/consumer/reference-doc.md#rule-50]
+---
+
+# Anti-pattern — `inputType`
+
+The `input` primitive uses **`type`**, NOT `inputType`. Using `inputType`
+is silently ignored — input falls back to default `"text"` type.
+
+## Wrong
+
+```json
+{ "type": "input", "props": { "inputType": "password", "value": ... } }
+```
+
+## Right
+
+```json
+{ "type": "input", "props": { "type": "password", "value": ... } }
+```
+
+## Detection
+
+The CLI validates prop names and warns on unknown props with "did you
+mean?" suggestions (Levenshtein matching) — see [[@cli-validate]] (rule
+50, 64). The output looks like:
+
+```
+⚠ unknown prop "inputType" for type "input" — did you mean "type"?
+```
+
+## Related concepts
+
+- [[@primitive-input]]
+- [[@cli-validate]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § input` (Wrong/Right examples)
+- `docs/consumer/reference-doc.md § rules 50, 64`

package/docs/wiki/compiled/antipattern-mix-fetch-and-datasources.md

@@ -0,0 +1,48 @@
+---
+id: antipattern-mix-fetch-and-datasources
+title: Anti-pattern — mixing `fetch` + `dataSources` for same target
+kind: pattern
+sources: [docs/consumer/ai-context-patterns.md#dont-mix-fetch-and-datasources-for-the-same-target]
+---
+
+# Anti-pattern — mixing `fetch` + `dataSources` for same target
+
+`initialActions` `fetch` and `dataSources` write to **different
+loading-state paths** (`/ui/loading` vs `/{target}Loading`). Using both
+for the same data target creates conflicting state.
+
+## Wrong
+
+```json
+{
+  "initialActions": [{ "action": "fetch", "params": { "url": "/api/items", "target": "/items" } }],
+  "dataSources": {
+    "items": { "url": "/api/items", "target": "/items" }   // SAME target!
+  }
+}
+```
+
+Both populate `/items`; loading states use different paths; mutations
+race.
+
+## Right — pick one pattern per data source
+
+For reactive lists (filters, search, pagination): use `dataSources`.
+
+For one-shot CRUD (POST/PATCH/DELETE in transactions): use `fetch` action.
+
+When you need both for the SAME data source — e.g. a reactive list AND
+mutations — use `dataSources` for the GET and trigger a `refreshDataSource`
+after the mutation succeeds. See [[@pattern-fetch-vs-datasources]].
+
+## Related concepts
+
+- [[@pattern-fetch-vs-datasources]]
+- [[@action-fetch]]
+- [[@concept-data-sources]]
+- [[@concept-initial-actions]]
+- [[@action-refresh-data-source]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-patterns.md § Don't mix fetch and dataSources for the same target`

package/docs/wiki/compiled/antipattern-modal-drawer-visible.md

@@ -0,0 +1,57 @@
+---
+id: antipattern-modal-drawer-visible
+title: Anti-pattern — `visible` on modal/drawer
+kind: pattern
+sources: [docs/consumer/ai-context-primitives.md#modal, docs/consumer/reference-doc.md#modal--drawer-auto-visibility]
+---
+
+# Anti-pattern — `visible` on modal/drawer
+
+The engine **automatically manages visibility** of modal and drawer
+elements via `/ui/modals/{id}` and `/ui/drawers/{id}`. Adding a
+`visible` condition is redundant and may conflict with engine logic.
+
+## Wrong
+
+```json
+"my-modal": {
+  "type": "modal",
+  "visible": { "$state": "/ui/showEdit" },           // BAD
+  "props": { "title": "Edit" }
+}
+```
+
+## Right
+
+Don't set `visible`. Use `openModal` / `closeModal` actions to toggle:
+
+```json
+"my-modal": {
+  "type": "modal",
+  "props": { "title": "Edit" },
+  "children": ["edit-form"]
+}
+```
+
+Open from a button:
+```json
+"on": { "press": { "action": "openModal", "params": { "id": "my-modal" } } }
+```
+
+## Behind the scenes
+
+Engine binds `type:"modal"` to `/ui/modals/{elementId}` automatically.
+Same for drawers via `/ui/drawers/{id}`.
+
+## Related concepts
+
+- [[@primitive-modal]]
+- [[@primitive-drawer]]
+- [[@action-modal]]
+- [[@action-drawer]]
+- [[@path-ui-modals-drawers]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-primitives.md § modal, drawer (Wrong/Right notes)`
+- `docs/consumer/reference-doc.md § Modal & Drawer Auto-Visibility`

package/docs/wiki/compiled/antipattern-motion-entrance-token.md

@@ -0,0 +1,53 @@
+---
+id: antipattern-motion-entrance-token
+title: Anti-pattern — `identity.motionEntrance` / `motionHover`
+kind: pattern
+sources: [docs/consumer/ai-context.md#rule-54, docs/consumer/reference-doc.md#rule-149]
+---
+
+# Anti-pattern — `identity.motionEntrance` and `motionHover`
+
+`identity.motionEntrance` and `identity.motionHover` were **REMOVED** in
+plan 2 Task 22. Setting them has no effect — the legacy
+`resolveMotionEntrance` function and `MotionEntrance`/`MotionHover` types
+are deleted from the framework.
+
+## Wrong
+
+```json
+"tokens": { "identity": { "motionEntrance": "fade", "motionHover": "lift" } }
+```
+
+## Right — per-element animations via the engine
+
+```json
+{ "type": "card", "animations": { "mount": { "recipe": "fade-up" }, "hover": { "recipe": "lift" } } }
+```
+
+Or set app-wide defaults via `identity.animations` (cascade level 1):
+```json
+"tokens": { "identity": { "animations": { "mount": { "recipe": "fade-up" } } } }
+```
+
+## Old → new mapping
+
+| Old `motionEntrance` | New `animations.mount.recipe` |
+|---|---|
+| `'fade'` | `'fade'` |
+| `'slide-up'` | `'fade-up'` |
+| `'scale'` | `'scale-in'` |
+| `'slide-left'` | `'slide-right'` |
+
+Hover similarly maps to `animations.hover` (e.g. `'lift'` recipe).
+
+## Related concepts
+
+- [[@concept-animations-engine]]
+- [[@concept-animation-recipes]]
+- [[@concept-animation-cascade]]
+- [[@concept-identity-animations]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § rule 54`
+- `docs/consumer/reference-doc.md § rule 149, 200`