mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/concept-custom-element-black-box.md

@@ -0,0 +1,56 @@
+---
+id: concept-custom-element-black-box
+title: Custom element black-box contract
+kind: concept
+sources: [docs/consumer/ai-context-custom-elements.md#black-box-contract]
+---
+
+# Custom element black-box contract
+
+Strict boundary between consumer and author scope.
+
+## Boundary
+
+| Scope | Owns |
+|---|---|
+| **Consumer** | Instance-level `animations`, `hover`, `active`, `focus`, `motion`, `style`, `visible`, `key` — apply to the **outer primitive** of the render tree only |
+| **Author** | All inner primitives. Consumer cannot reach them directly |
+
+## Identity cascade reaches inside
+
+`tokens.identity.animations` (cascade level 1) propagates to inner
+primitives. Consumer cannot block this via instance-level declarations.
+
+## No future leakage
+
+A future `::part()`-style API would layer on top without breaking this
+contract.
+
+## Animation cascade inside custom elements
+
+Inner primitives participate in the full 5-level cascade:
+
+```
+identity → variant → elementDef → template → element
+```
+
+For inner primitives:
+- **identity** (level 1): global, reaches inside.
+- **variant** (level 2): the inner primitive's own variant if any.
+- **elementDef** (level 3): the author's `animations` declaration on that
+  inner node — only present inside custom-element expansions.
+- **template** (level 4): if the inner uses a template.
+- **element** (level 5): NOT the consumer's declaration — that stays on
+  the outer. Inner has no level 5 unless author wires one via `$prop`.
+
+## Related concepts
+
+- [[@concept-animation-cascade]]
+- [[@concept-custom-element-prop-cascade]]
+- [[@concept-custom-elements]]
+- [[@concept-element-render-node]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-custom-elements.md § Black-Box Contract` + § Animation Cascade
+- `docs/consumer/reference-doc.md § rule 230`

package/docs/wiki/compiled/concept-custom-element-cache.md

@@ -0,0 +1,39 @@
+---
+id: concept-custom-element-cache
+title: Custom element cache invalidation
+kind: concept
+sources: [docs/consumer/reference-doc.md#rule-233]
+---
+
+# Custom element cache invalidation
+
+Cache dep scanner tracks `$prop` references as `/__prop/<name>` sentinel
+paths. At custom-element dispatch time, an `instancePropsCache` diffs
+current vs previous `mergedProps`; changed keys are injected into the
+active changed-paths set (scoped to the expansion render via `try/finally`)
+so inner primitives that declared those prop refs correctly invalidate.
+
+## Behavior
+
+- `$prop: "label"` is registered as a dependency on `/__prop/label`.
+- When consumer prop `label` changes, the sentinel path is added to the
+  changed-paths set during the next expansion.
+- Inner primitives that scan-deps include `/__prop/label` re-render.
+
+## Limitations
+
+**Shallow reference equality** — object/array props sourced from `$state`
+(which produces new references each render) over-invalidate every render
+even when contents are equal. Deep-equality diff deferred pending profiling
+(see `engine.ts` docstring).
+
+## Related concepts
+
+- [[@concept-custom-elements]]
+- [[@concept-custom-element-prop-cascade]]
+- [[@expression-prop]]
+- [[@concept-mythik-renderer]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rule 233`

package/docs/wiki/compiled/concept-custom-element-error-boundary.md

@@ -0,0 +1,33 @@
+---
+id: concept-custom-element-error-boundary
+title: Custom element error boundary
+kind: concept
+sources: [docs/consumer/reference-doc.md#rule-234]
+---
+
+# Custom element error boundary
+
+Errors anywhere inside a custom element's expansion (missing primitive,
+resolver throw, etc.) surface as an `_error` `RenderNode` — caught by the
+`renderElement` `try/catch` wrapper.
+
+## Behavior
+
+- Per-instance isolation — a broken custom element does NOT crash sibling
+  renders.
+- Consumer error handling does NOT need to know the author's internal
+  structure — errors are isolated.
+
+## Use case
+
+A misbehaving custom element shows its own error indicator while the rest
+of the page continues to render normally.
+
+## Related concepts
+
+- [[@concept-custom-elements]]
+- [[@concept-where-to-look]] — for source-level debugging
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rule 234`

package/docs/wiki/compiled/concept-custom-element-prop-cascade.md

@@ -0,0 +1,60 @@
+---
+id: concept-custom-element-prop-cascade
+title: `$prop` cascade in nested custom elements
+kind: concept
+sources: [docs/consumer/ai-context-custom-elements.md, docs/consumer/reference-doc.md#rule-231]
+---
+
+# `$prop` cascade in nested custom elements
+
+Inside a custom element's expanded tree, `$prop` references resolve
+against THAT custom element's `mergedProps`. **Nesting a custom element
+pushes a new `propContext` — outer's is shadowed, NOT merged.**
+
+## Behavior
+
+- Nearest-enclosing custom element wins.
+- Outer custom-element props are not visible to inner custom-element render trees.
+- Matches CSS custom-property scoping semantics.
+
+## Workaround for nested access
+
+Thread values via explicit prop passthrough when nested access is needed:
+
+```json
+"render": {
+  "type": "stack",
+  "children": [
+    {
+      "type": "inner-custom-element",
+      "props": {
+        "outerLabel": { "$prop": "label" }
+      }
+    }
+  ]
+}
+```
+
+The outer element passes its `label` prop down explicitly. The inner
+element reads it as `$prop: "outerLabel"`.
+
+## Implementation
+
+Cache dep scanner (`scanDeps` in `deps.ts`) tracks `$prop` references as
+`/__prop/<name>` sentinel paths. At custom-element dispatch time, an
+`instancePropsCache` diffs current vs previous `mergedProps`; changed
+keys are injected into the active changed-paths set (scoped to the
+expansion render via `try/finally`) so inner primitives that declared
+those prop refs correctly invalidate. See [[@concept-custom-element-cache]].
+
+## Related concepts
+
+- [[@concept-prop-cascade]]
+- [[@concept-custom-elements]]
+- [[@expression-prop]]
+- [[@concept-custom-element-cache]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-custom-elements.md` (full)
+- `docs/consumer/reference-doc.md § rule 231`

package/docs/wiki/compiled/concept-custom-element-repeat.md

@@ -0,0 +1,53 @@
+---
+id: concept-custom-element-repeat
+title: Custom elements under `repeat`
+kind: concept
+sources: [docs/consumer/reference-doc.md#rule-235]
+---
+
+# Custom elements under `repeat`
+
+Custom elements dispatched under `element.repeat` (count / statePath /
+source) render N instances as expected, same as primitives.
+
+## Architectural fix (Task 17)
+
+The `repeat` handling block was moved BEFORE the custom-element dispatch
+so the repeat gate (`element.repeat && itemContext === undefined`) fires
+for all element types uniformly. Prior to the fix, custom elements with
+`repeat` rendered once instead of N times because the custom-element
+dispatch returned early.
+
+## `$index` / `$item` threading
+
+Iteration context threads through consumer props into the expansion's
+`propContext` so inner primitives see the correct iteration values.
+
+## Example
+
+```json
+"my-list": {
+  "type": "stack",
+  "repeat": { "statePath": "/items", "key": "id" },
+  "children": ["row-card"]
+},
+"row-card": {
+  "type": "stat-card",
+  "props": {
+    "label": { "$item": "name" },
+    "value": { "$item": "count" }
+  }
+}
+```
+
+Each item produces one `stat-card` instance with its own merged props.
+
+## Related concepts
+
+- [[@concept-custom-elements]]
+- [[@concept-repeat]]
+- [[@expression-item-index]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rule 235`

package/docs/wiki/compiled/concept-custom-elements.md

@@ -0,0 +1,71 @@
+---
+id: concept-custom-elements
+title: Custom elements (Layer 3)
+kind: concept
+sources: [docs/consumer/ai-context-custom-elements.md, docs/consumer/reference-doc.md#layer-3-custom-elements-plan-custom-element-cascade]
+---
+
+# Custom elements (Layer 3)
+
+Authors register reusable components via `plugins.registerElement`. They
+participate in the full render contract as **first-class primitives** —
+consumers use them with identical syntax to built-ins (`type`, `props`,
+`animations`, `hover`, `visible`, `key`, etc.).
+
+## Author registers via plugin
+
+```ts
+plugins.registerElement(elementDefinition);
+```
+
+`PluginLoader.registerElement(def)` stages the definition; `factory.applyPlugins()`
+calls `elements.register(def)` for each, skipping entries already present
+(idempotent with `config.elements`). `count()` includes element definitions
+(rule 237).
+
+## Consumer uses like a primitive
+
+```json
+{
+  "type": "rating-stars",
+  "props": { "max": 5, "value": { "$bindState": "/form/rating" }, "variant": "compact" },
+  "animations": { "mount": { "recipe": "scale-in" } },
+  "hover": { "scale": 1.02 },
+  "children": ["label"]
+}
+```
+
+Instance-level `animations` / `hover` / `style` apply to the OUTER
+primitive — see [[@concept-custom-element-black-box]].
+
+## What's documented separately
+
+- [[@concept-element-definition]] — `ElementDefinition` shape
+- [[@concept-element-render-node]] — render tree
+- [[@concept-element-variants]] — author + theme variants
+- [[@concept-element-prop-definition]] — `PropDefinition`
+- [[@concept-element-children-slot]] — `"$children"` marker
+- [[@concept-custom-element-action-props]] — action-chain props via `$prop`
+- [[@concept-custom-element-black-box]] — consumer/author boundary
+- [[@concept-custom-element-prop-cascade]] — `$prop` scope
+- [[@concept-custom-element-repeat]]
+- [[@concept-custom-element-cache]]
+- [[@concept-custom-element-error-boundary]]
+
+## Validator awareness
+
+`validateSpec` accepts `elementRegistry` in `ValidationContext` — a
+non-primitive `el.type` no longer flagged as "unknown" when the registry
+knows it. Suggestion candidates merge keys from primitive and element
+registries (rule 238).
+
+## Related concepts
+
+- [[@concept-templates]] — simpler reuse mechanism
+- [[@concept-templates-vs-variants]]
+- [[@concept-animation-cascade]] — 5-level cascade (with elementDef level)
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-custom-elements.md` (full)
+- `docs/consumer/reference-doc.md § Layer 3 Custom Elements` (rules 226-240)

package/docs/wiki/compiled/concept-custom-jwt-provider.md

@@ -0,0 +1,63 @@
+---
+id: concept-custom-jwt-provider
+title: Custom JWT provider response mapping
+kind: concept
+sources: [docs/consumer/ai-context.md#auth-config, docs/consumer/reference-doc.md#rule-68]
+---
+
+# Custom JWT provider response mapping
+
+The Custom JWT provider maps login and refresh responses with explicit dot
+paths.
+
+## Token and user paths
+
+`tokenPath`, `refreshTokenPath`, and `userPath` are dot paths against the
+full login/refresh response.
+
+## Role paths
+
+`rolePath` and `rolesPath` use a compat dual contract:
+
+- Plain keys such as `"role"` or `"roles"` resolve inside the extracted
+  `userPath` object.
+- Dotted paths such as `"user.role"` or `"data.user.role"` resolve against
+  the full response.
+
+If no role or roles are found, Mythik uses `defaultRole` (`"user"` by
+default) and warns in development.
+
+## Example
+
+```ts
+createCustomJWTProvider({
+  tokenPath: "token",
+  refreshTokenPath: "refreshToken",
+  userPath: "data.user",
+  rolePath: "role",
+  rolesPath: "roles",
+  defaultRole: "user",
+});
+```
+
+For a response where the role lives outside `data.user`, use the full
+dotted path:
+
+```ts
+createCustomJWTProvider({
+  userPath: "data.user",
+  rolePath: "data.authorization.role",
+});
+```
+
+## Related concepts
+
+- [[@concept-auth-config]]
+- [[@concept-auth-security]]
+- [[@action-login]]
+- [[@concept-role-access]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md` - Auth Config
+- `docs/consumer/reference-doc.md` - rule 68

package/docs/wiki/compiled/concept-customize-action.md

@@ -0,0 +1,33 @@
+---
+id: concept-customize-action
+title: Customize — write a custom action
+kind: concept
+sources: [docs/consumer/WHERE-TO-LOOK.md]
+---
+
+# Customize — write a custom action
+
+Write a custom action callable from spec via
+`{ action: 'myAction', params: {...} }`.
+
+## Read order
+
+1. **`packages/core/src/actions/dispatcher.ts`** — built-in actions
+   registry + dispatch flow + action-context shape.
+2. Spec's `customActions` config in `ai-context.md § Actions`.
+
+## Why this works
+
+Custom actions register through the **same dispatcher** used by
+built-ins. Reading the built-in implementations (`setState`, `fetch`,
+`navigate`) gives the canonical pattern.
+
+## Related concepts
+
+- [[@concept-where-to-look]]
+- [[@concept-action-middleware]] — alternative for cross-cutting concerns
+- [[@concept-customize-plugin]]
+
+## Sources (raw)
+
+- `docs/consumer/WHERE-TO-LOOK.md § Section 1 → custom action`

package/docs/wiki/compiled/concept-customize-cli-lint-rule.md

@@ -0,0 +1,30 @@
+---
+id: concept-customize-cli-lint-rule
+title: Customize — custom CLI lint rule (NOT extensible in v0.1)
+kind: concept
+sources: [docs/consumer/WHERE-TO-LOOK.md]
+---
+
+# Customize — custom CLI lint rule
+
+**NOT officially extensible in v0.1.** Reading these files is for
+understanding rule shape, contributing upstream, or forking.
+
+## Source files
+
+| Concern | File |
+|---|---|
+| `spec-row-literal` (spec rule) | `packages/core/src/security/spec-validator.ts` |
+| `spec-crud-id-collision`, `spec-auth-domains-port` (spec rules) | `packages/core/src/security/api-spec-validator.ts` |
+| `code-store-save-bypass` (code rule) | `packages/cli/src/lint/code-rules.ts` |
+| Lint orchestrator | `packages/cli/src/lint/orchestrator.ts` |
+| Shared types | `packages/cli/src/lint/types.ts` |
+
+## Related concepts
+
+- [[@cli-lint]]
+- [[@concept-customize-validator-rule]]
+
+## Sources (raw)
+
+- `docs/consumer/WHERE-TO-LOOK.md § Section 1 → custom CLI lint rule`

package/docs/wiki/compiled/concept-customize-expression-handler.md

@@ -0,0 +1,30 @@
+---
+id: concept-customize-expression-handler
+title: Customize — custom expression handler (NOT extensible in v0.1)
+kind: concept
+sources: [docs/consumer/WHERE-TO-LOOK.md]
+---
+
+# Customize — custom expression handler
+
+**NOT officially extensible in v0.1.** Expression-handler extensibility
+is a v0.2+ candidate.
+
+## What to do instead
+
+Use **`customActions`** if your need is action-shaped (write to state,
+trigger fetch, etc.). See [[@concept-customize-action]].
+
+## Source (for fork/upstream contribution)
+
+`packages/core/src/expressions/handlers/` — shows the existing handler
+shape. Each `$name` is one file.
+
+## Related concepts
+
+- [[@concept-customize-action]]
+- [[@concept-where-to-look]]
+
+## Sources (raw)
+
+- `docs/consumer/WHERE-TO-LOOK.md § Section 1 → custom expression handler`

package/docs/wiki/compiled/concept-customize-plugin.md

@@ -0,0 +1,43 @@
+---
+id: concept-customize-plugin
+title: Customize — custom plugin (auth-style)
+kind: concept
+sources: [docs/consumer/WHERE-TO-LOOK.md]
+---
+
+# Customize — custom plugin
+
+For auth-style cross-cutting features.
+
+## Read order
+
+1. **`packages/core/src/plugins/loader.ts`** — `PluginLoader` shape +
+   plugin registration.
+2. **`packages/core/src/auth/engine.ts`** + `auth/refresh-engine.ts` +
+   `auth/persistence.ts` + `auth/cross-tab.ts` — auth as the canonical
+   plugin example.
+3. **`packages/react/src/MythikApp.tsx`** — `onPlugins` integration point.
+
+## Why auth is the canonical example
+
+Auth registers actions, exposes context, and can wrap fetch — all the
+plugin extension points exercised end-to-end.
+
+## Caveat — auth internals are not stable contract
+
+The auth subsystem is the canonical plugin example, but its **internals**
+(`engine.ts`, `refresh-engine.ts`, `persistence.ts`, `cross-tab.ts`) can
+change between framework versions. Treat as reference for the **shape**
+of a plugin, NOT as stable extension contract for the auth-plugin's own
+internals (rule from "Section 4").
+
+## Related concepts
+
+- [[@concept-action-middleware]]
+- [[@concept-customize-action]]
+- [[@concept-where-to-look]]
+- [[@concept-source-reading-misleading]]
+
+## Sources (raw)
+
+- `docs/consumer/WHERE-TO-LOOK.md § Section 1 → custom plugin`, § Section 4

package/docs/wiki/compiled/concept-customize-server-middleware.md

@@ -0,0 +1,36 @@
+---
+id: concept-customize-server-middleware
+title: Customize — custom server middleware (`mythik-server`)
+kind: concept
+sources: [docs/consumer/WHERE-TO-LOOK.md]
+---
+
+# Customize — custom server middleware
+
+Server middleware uses the standard Express `(req, res, next)` shape;
+`server.ts` is where the chain is assembled.
+
+## Read order
+
+1. **`packages/server/src/server.ts`** — `createServer` (full Express
+   middleware chain composition: CORS, body parser, auth, error handler;
+   plus per-endpoint registration in `registerEndpoint`).
+2. **`packages/server/src/middleware/cors.ts`** +
+   `middleware/error-handler.ts` — existing chain-level middleware.
+3. **`packages/server/src/auth/middleware.ts`** — canonical
+   request-gating middleware shape.
+
+## Pattern
+
+Insert your middleware into the chain composition in `server.ts`, or
+expose it via a config option for `createServer`.
+
+## Related concepts
+
+- [[@concept-where-to-look]]
+- [[@concept-api-spec]]
+- [[@concept-api-handler-endpoint]]
+
+## Sources (raw)
+
+- `docs/consumer/WHERE-TO-LOOK.md § Section 1 → custom server middleware`

package/docs/wiki/compiled/concept-customize-spec-store.md

@@ -0,0 +1,42 @@
+---
+id: concept-customize-spec-store
+title: Customize — write a custom `SpecStore`
+kind: concept
+sources: [docs/consumer/WHERE-TO-LOOK.md]
+---
+
+# Customize — write a custom `SpecStore`
+
+For e.g. MongoDB, DynamoDB, etc.
+
+## Read order
+
+1. **`packages/core/src/spec-engine/types.ts`** — `SpecStore` interface
+   (`load`, `save`, `list`, `delete`).
+2. **`packages/core/src/spec-stores/memory.ts`** — simplest reference.
+3. **`packages/core/src/spec-stores/sqlserver.ts`** + `supabase.ts` —
+   production references (connection pooling, identifier safety, JSON
+   handling).
+
+## What to do
+
+The interface is 4 methods. Memory store is the readable canonical
+implementation. SQL Server / Supabase show production patterns.
+
+## Identifier safety
+
+If your store interpolates identifiers into raw strings (table names,
+column names), reuse the framework's `assertValidIdentifier` —
+`packages/core/src/security/identifier-guard.ts`. Regex
+`/^[a-zA-Z_][a-zA-Z0-9_.]*$/`, max 128 chars.
+
+## Related concepts
+
+- [[@concept-spec-store-interface]]
+- [[@concept-spec-stores-catalog]]
+- [[@concept-customize-versioned-store]]
+- [[@concept-where-to-look]]
+
+## Sources (raw)
+
+- `docs/consumer/WHERE-TO-LOOK.md § Section 1 → custom SpecStore`

package/docs/wiki/compiled/concept-customize-validator-rule.md

@@ -0,0 +1,35 @@
+---
+id: concept-customize-validator-rule
+title: Customize — custom validator rule (NOT extensible in v0.1)
+kind: concept
+sources: [docs/consumer/WHERE-TO-LOOK.md]
+---
+
+# Customize — custom validator rule
+
+**NOT officially extensible in v0.1.** These files are the canonical
+implementations if you need to fork or contribute upstream.
+
+## Source files
+
+- `packages/core/src/security/spec-validator.ts` — spec-level rules
+- `packages/core/src/security/api-spec-validator.ts` — ApiSpec rules
+- `packages/core/src/security/app-spec-validator.ts` — AppSpec rules
+
+## What to do
+
+- For project-specific rules, prefer `mythik lint` extensibility (see
+  [[@concept-customize-cli-lint-rule]] — also not officially extensible
+  in v0.1, but easier surface).
+- For framework-upstream contributions, fork and follow the existing
+  patterns.
+
+## Related concepts
+
+- [[@concept-customize-cli-lint-rule]]
+- [[@cli-validate]]
+- [[@cli-lint]]
+
+## Sources (raw)
+
+- `docs/consumer/WHERE-TO-LOOK.md § Section 1 → custom validator rule`

package/docs/wiki/compiled/concept-customize-versioned-store.md

@@ -0,0 +1,37 @@
+---
+id: concept-customize-versioned-store
+title: Customize — custom `VersionedSpecStore`
+kind: concept
+sources: [docs/consumer/WHERE-TO-LOOK.md]
+---
+
+# Customize — custom `VersionedSpecStore`
+
+For custom DBs with version history.
+
+## Read order
+
+1. **`packages/core/src/versioning/types.ts`** — `VersionedSpecStore`,
+   `EnvironmentStore` interfaces.
+2. **`packages/core/src/spec-stores/memory-versioned.ts`** — simplest.
+3. **`packages/core/src/spec-stores/sqlserver-versioned.ts`** +
+   `supabase-versioned.ts` — production.
+4. **`docs/consumer/ai-context.md § Storage Setup`** — the schema your DB
+   needs.
+
+## Reusable internals
+
+Versioned stores extend a base store. Snapshot/patch logic lives in
+`versioning/compute-patches.ts` + `streaming/patch.ts` and is **reusable**;
+only the I/O is per-adapter.
+
+## Related concepts
+
+- [[@concept-versioned-store]]
+- [[@concept-versioning-snapshots-patches]]
+- [[@concept-storage-table-versions]]
+- [[@concept-customize-spec-store]]
+
+## Sources (raw)
+
+- `docs/consumer/WHERE-TO-LOOK.md § Section 1 → custom VersionedSpecStore`