mythik 0.0.1 → 0.1.0

package/docs/wiki/compiled/concept-api-scope-filter.md

@@ -0,0 +1,59 @@
+---
+id: concept-api-scope-filter
+title: `scopeFilter` — row-level security
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#34-scopefilter--bypassroles, docs/consumer/ai-context-api.md#auth]
+---
+
+# `scopeFilter` — row-level security
+
+A SQL `WHERE` clause template injected server-side on **query, update,
+and delete** operations, resolved against JWT claims. **Prevents
+cross-tenant row access.**
+
+## Shape
+
+In `auth.scopeFilter`:
+```json
+"scopeFilter": {
+  "claim": "institutions",
+  "type": "int",
+  "column": "institution_id",
+  "bypassRoles": ["ADMIN"]
+}
+```
+
+Or per-endpoint (boolean / per-endpoint config):
+```json
+"endpoints": {
+  "rooms": {
+    "scopeFilter": "tenant_id = :jwt.tenant_id",
+    "bypassRoles": ["admin"]
+  }
+}
+```
+
+## Behavior
+
+- For roles in `bypassRoles`, the filter is NOT applied (admin sees all).
+- All other roles see only rows matching their JWT claim.
+- **Applies to UPDATE and DELETE**, not just SELECT — defense in depth.
+
+## Security invariant
+
+A user cannot UPDATE or DELETE rows outside their scope — the filter is
+appended to the WHERE clause of those queries. Combined with audit fields
+(see [[@concept-api-audit]]), this gives a strong defense-in-depth posture
+for multi-tenant apps.
+
+## Related concepts
+
+- [[@concept-api-auth]]
+- [[@concept-api-audit]]
+- [[@concept-api-spec]]
+- [[@concept-role-access]] — frontend equivalent
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 3.4`
+- `docs/consumer/ai-context-api.md § Auth → scopeFilter`

package/docs/wiki/compiled/concept-api-spec.md

@@ -0,0 +1,70 @@
+---
+id: concept-api-spec
+title: ApiSpec — declarative backend
+kind: concept
+sources: [docs/consumer/ai-context-api.md, docs/consumer/ai-context.md#apispec-server]
+---
+
+# ApiSpec — declarative backend
+
+`type: "api"` document defines a backend API declaratively — endpoints,
+catalogs, auth, audit. **No connection strings or secrets in the spec**
+(those go in `createServer` config).
+
+## Shape / Signature
+
+```json
+{
+  "type": "api",
+  "name": "My API",
+  "auth": { ... },
+  "catalogs": { ... },
+  "endpoints": { ... }
+}
+```
+
+## Sub-concepts
+
+- [[@concept-api-catalogs]] — dropdown data sources
+- [[@concept-api-endpoints-overview]] — 4 endpoint patterns
+- [[@concept-api-query-endpoint]]
+- [[@concept-api-handler-endpoint]]
+- [[@concept-api-crud-endpoint]] — 1 declaration → 3 routes
+- [[@concept-api-public-endpoint]]
+- [[@concept-api-endpoint-properties]]
+- [[@concept-api-param-properties]]
+- [[@concept-api-auth]]
+- [[@concept-api-scope-filter]] — row-level filtering
+- [[@concept-api-audit]] — un-spoofable audit fields
+- [[@concept-query-envelope]] — `{ data, total, page, pageSize, totals }`
+- [[@concept-api-login-body-contract]] — `{ username, password }`
+
+## Rules
+
+- ApiSpec is **pure declarative** — no connection strings, no secrets
+  (those go in `createServer` config).
+- Api-specs use `type: "api"` — **never served to the browser** (404 on
+  `GET /api/screens/:id` for type "api").
+- `query` and `handler` are mutually exclusive — use `query` for simple
+  SQL, `handler` for complex logic.
+- CRUD `insertable` / `updatable` define which fields can be written —
+  fields not listed are rejected.
+- Audit values override client-sent values — prevents spoofing.
+- `policy: "public"` skips auth — use for health checks and public
+  endpoints only.
+- ScopeFilter `bypassRoles` lets admin roles see all data.
+- Provider queries use `@username` parameter and must return `val` column.
+- Param `source` defaults to auto-detect: path first, body for non-GET,
+  query as fallback.
+
+## Related concepts
+
+- [[@concept-spec-types]]
+- [[@cli-contract]]
+- [[@pattern-fullstack-coherence]]
+- [[@concept-spec-stores-catalog]] — separate `api_specs` table per rule 71
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-api.md` (full)
+- `docs/consumer/ai-context.md § ApiSpec (Server)`

package/docs/wiki/compiled/concept-app-auto-state-paths.md

@@ -0,0 +1,59 @@
+---
+id: concept-app-auto-state-paths
+title: AppSpec auto-state paths
+kind: concept
+sources: [docs/consumer/ai-context.md#auto-generated-state, docs/consumer/reference-doc.md#auto-generated-state]
+---
+
+# AppSpec auto-state paths
+
+Paths the framework writes when AppSpec is mounted.
+
+## Paths
+
+| Path | Content |
+|---|---|
+| `/navigation/currentScreen` | Active screen ID |
+| `/navigation/history` | Visited screen IDs (array) |
+| `/navigation/breadcrumb` | Enriched array with `label`, `icon` |
+| `/navigation/params` | Extra params passed to `navigateScreen` (reset on each navigation) |
+| `/app/screens` | Accessible screens (filtered by role; loginScreen excluded) |
+| `/auth/isAuthenticated` | (auth) |
+| `/auth/user/*` | (auth — see [[@concept-auth-state-paths]]) |
+
+## Sidebar auto-refresh
+
+`MythikApp` automatically re-computes `/app/screens` when auth state
+changes (`/auth/user/*` or `/auth/isAuthenticated`). No manual call needed
+— login, logout, session restore, cross-tab sync, and role changes all
+trigger sidebar refresh.
+
+## Use patterns
+
+Read current screen:
+```json
+{ "$state": "/navigation/currentScreen" }
+```
+
+Render sidebar items via repeat:
+```json
+{ "type": "stack", "repeat": { "statePath": "/app/screens", "key": "id" }, "children": [...] }
+```
+
+Read navigation params on target screen:
+```json
+{ "$state": "/navigation/params/employeeId" }
+```
+
+## Related concepts
+
+- [[@concept-navigation]]
+- [[@concept-app-spec]]
+- [[@path-navigation]]
+- [[@path-app-screens]]
+- [[@action-navigate]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § AppSpec & Navigation → Auto-Generated State`
+- `docs/consumer/reference-doc.md § Auto-Generated State`

package/docs/wiki/compiled/concept-app-spec.md

@@ -0,0 +1,89 @@
+---
+id: concept-app-spec
+title: AppSpec — multi-screen app
+kind: concept
+sources: [docs/consumer/ai-context.md#appspec--navigation, docs/consumer/reference-doc.md#app-spec--screen-outlet]
+---
+
+# AppSpec — multi-screen app
+
+Top-level document with `type: "app"`. Defines navigation, screens, shared
+state, tokens, templates, and the layout that wraps every screen via
+`screen-outlet`. **100% opt-in** — without AppSpec, screen specs work
+standalone.
+
+## Shape / Signature
+
+```json
+{
+  "type": "app",
+  "name": "my-app",
+  "navigation": {
+    "type": "sidebar",
+    "initialScreen": "dashboard",
+    "menu": ["dashboard", "reports", "settings"],
+    "auth": { ... }
+  },
+  "screens": {
+    "dashboard": { "label": "Dashboard", "icon": "chart-bar", "statePolicy": "preserve" },
+    "new-item": { "label": "New", "icon": "plus", "statePolicy": "reset", "parent": "dashboard" }
+  },
+  "tokens": { "dna": { "primary": "#0D9488" } },
+  "sharedState": { "preferences": { "theme": "light" } },
+  "templates": { ... },
+  "translations": { "en": { ... }, "es": { ... } },
+  "layout": {
+    "root": "shell",
+    "elements": {
+      "shell": { "type": "stack", "props": { "direction": "horizontal" }, "children": ["sidebar", "screen-outlet"] },
+      "sidebar": { "type": "box", "children": ["nav"] },
+      "screen-outlet": { "type": "screen-outlet", "style": { "flex": 1 } }
+    }
+  }
+}
+```
+
+## Top-level properties
+
+| Property | Type | Required | Purpose |
+|---|---|---|---|
+| `type` | `"app"` | yes | Identifies as AppSpec |
+| `name` | string | no | App display name |
+| `navigation` | object | yes | Navigation config |
+| `screens` | object | yes | `{ id: { label, icon, statePolicy, parent?, roles? } }` |
+| `tokens` | object | no | Design tokens |
+| `sharedState` | object | no | Initial shared state |
+| `templates` | object | no | Shared templates |
+| `translations` | object | no | i18n translations |
+| `layout` | object | yes | `{ root, elements }` — sidebar + screen-outlet |
+
+## Inheritance
+
+Screens inherit from AppSpec:
+- **Tokens**: deep merge (screen overrides app)
+- **Translations**: merged (screen extends app)
+- **Templates**: screen overrides app with same name
+
+## Constraints / Anti-patterns
+
+- **AppSpec patches use `/layout/elements/`**, not `/elements/`. See
+  [[@cli-app-spec]].
+- **AppSpec is filtered without Bearer token** — `GET /api/app/:id` strips
+  `roleAccess` and `protectedScreens` when no valid Bearer is present
+  (rule 63). Prevents disclosure of authorization model.
+
+## Related concepts
+
+- [[@concept-navigation]]
+- [[@concept-screen-definition]]
+- [[@concept-state-policies]]
+- [[@concept-role-access]]
+- [[@primitive-screen-outlet]]
+- [[@concept-auth-config]]
+- [[@cli-app-spec]]
+- [[@concept-spec-types]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § AppSpec & Navigation`
+- `docs/consumer/reference-doc.md § App Spec & Screen Outlet`

package/docs/wiki/compiled/concept-auth-config.md

@@ -0,0 +1,71 @@
+---
+id: concept-auth-config
+title: AppSpec auth config
+kind: concept
+sources: [docs/consumer/ai-context.md#auth-config, docs/consumer/reference-doc.md#authentication]
+---
+
+# AppSpec auth config
+
+Auth configuration lives at `navigation.auth` in AppSpec.
+
+## Shape / Signature
+
+```json
+"navigation": {
+  "auth": {
+    "provider": "supabase",
+    "loginScreen": "login",
+    "protectedScreens": ["*"],
+    "roleAccess": { "admin": ["*"], "user": ["dashboard", "profile"] },
+    "persistence": "local",
+    "tokenRefresh": true,
+    "authDomains": ["myproject.supabase.co"],
+    "sessionExpiredMessage": "Session expired, please sign in again",
+    "loginBody": { "username": { "$state": "/login/email" }, "password": { "$state": "/login/password" } },
+    "interceptors": { "logging": true, "timeout": { "ms": 15000 } }
+  }
+}
+```
+
+## Properties
+
+| Property | Description |
+|---|---|
+| `provider` | Auth provider key (`"supabase"`, `"jwt"`, etc.) |
+| `loginScreen` | Screen ID for login |
+| `protectedScreens` | Array of screen IDs requiring auth (`["*"]` = all) |
+| `roleAccess` | Centralized access map (preferred) - see [[@concept-role-access]] |
+| `persistence` | `"local"`, `"session"`, `"memory"` - see [[@concept-session-persistence]] |
+| `tokenRefresh` | Enable proactive token refresh |
+| `authDomains` | Hostnames that auto-receive Bearer token - see [[@concept-auth-domains]] |
+| `sessionExpiredMessage` | Shown on session expiry |
+| `loginBody` | Server-side body shape mapping (e.g., email to username) - see [[@pattern-login-body-template]] |
+| `interceptors` | Fetch interceptor config - see [[@concept-fetch-interceptors]] |
+
+## Custom JWT provider response mapping
+
+For custom JWT auth, response paths are explicit. `tokenPath`,
+`refreshTokenPath`, and `userPath` are dot paths against the full response.
+`rolePath` and `rolesPath` use a compat dual contract: plain keys such as
+`"role"` / `"roles"` resolve inside the extracted `userPath` object, while
+dotted paths such as `"user.role"` or `"data.user.role"` resolve against
+the full response. See [[@concept-custom-jwt-provider]].
+
+## Related concepts
+
+- [[@concept-auth-state-paths]]
+- [[@concept-auth-security]]
+- [[@concept-custom-jwt-provider]]
+- [[@concept-auth-domains]]
+- [[@concept-session-persistence]]
+- [[@concept-cross-tab-sync]]
+- [[@concept-fetch-interceptors]]
+- [[@concept-role-access]]
+- [[@pattern-login-screen]]
+- [[@pattern-login-body-template]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md` - AppSpec & Navigation / Auth Config
+- `docs/consumer/reference-doc.md` - Authentication / AppSpec Auth Config

package/docs/wiki/compiled/concept-auth-domains.md

@@ -0,0 +1,55 @@
+---
+id: concept-auth-domains
+title: `authDomains` — hostname matcher
+kind: concept
+sources: [docs/consumer/ai-context-runtime-semantics.md#41-authdomains-hostname-only--blocker-5, docs/consumer/reference-doc.md#authentication]
+---
+
+# `authDomains` — hostname matcher
+
+Auth headers (Bearer tokens) are auto-injected on fetch/submitForm requests
+when the URL's hostname matches any entry in `authDomains`.
+
+## Matching contract
+
+**Port is stripped — hostname only.** Comparison uses `new URL(fetchUrl).hostname`.
+
+| Entry | Matches | Does NOT match |
+|---|---|---|
+| `"api.example.com"` | `https://api.example.com/...` (any port) | `https://notapi.example.com`, `https://example.com` |
+| `"example.com"` | `https://example.com`, `https://api.example.com`, `https://foo.example.com` (subdomain) | `https://notexample.com` |
+| `"localhost"` | `http://localhost:5173/...`, `http://localhost:3010/...` | `http://127.0.0.1` |
+| `"localhost:5173"` | **nothing** (port is stripped from URL hostname) | everything |
+
+## Subdomain matching
+
+An entry `"example.com"` matches any URL whose hostname **ends with** `.example.com` (note the leading dot — prevents `"api.com"` from matching `"notapi.com"`).
+
+## URL scheme filter
+
+Only `http://` and `https://` URLs are considered. Relative paths
+(`/api/rooms`), `file:`, `data:`, etc. return `false` before matching —
+auth headers are not injected on those requests.
+
+## Dev-mode guidance
+
+Configure `authDomains: ["localhost"]` (no port). Tokens inject on any
+localhost port during dev.
+
+## Constraints / Anti-patterns
+
+- **Never include `:port`** in `authDomains[]` entries — port is silently
+  stripped, leading to apparent matches that don't match. See
+  [[@antipattern-auth-domains-port]] (also a `mythik lint` rule).
+
+## Related concepts
+
+- [[@concept-auth-config]]
+- [[@concept-fetch-interceptors]]
+- [[@antipattern-auth-domains-port]]
+- [[@cli-lint]] — `spec-auth-domains-port` rule
+
+## Sources (raw)
+
+- `docs/consumer/ai-context-runtime-semantics.md § 4.1`
+- `docs/consumer/reference-doc.md § Authentication → authDomains matcher behavior` + rule 71

package/docs/wiki/compiled/concept-auth-security.md

@@ -0,0 +1,58 @@
+---
+id: concept-auth-security
+title: Auth security guarantees
+kind: concept
+sources: [docs/consumer/ai-context.md#auth-config, docs/consumer/reference-doc.md#security-guarantees]
+---
+
+# Auth security guarantees
+
+Architectural guarantees from the auth subsystem. Most are enforced at the
+type/runtime level, not by convention.
+
+## Guarantees
+
+- **Tokens NEVER exist in the state store**: only in engine closure.
+- **`$auth` blocks token/password fields** via whitelist.
+- **Auth headers only injected for `authDomains` URLs.**
+- **Credentials cleared from state after login** (success AND failure).
+- **Custom JWT role mapping is explicit**: plain `rolePath` / `rolesPath`
+  keys resolve inside the extracted user object; dotted paths resolve
+  against the full response. See [[@concept-custom-jwt-provider]].
+- **Refresh mutex**: max 1 concurrent refresh (anti-stampede).
+- **Login rate limit**: 5 attempts/min with exponential backoff.
+- **Cross-tab sync**: logout in one tab = logout in all tabs.
+- **StateGuard blocks spec writes to `/auth/*`.**
+- **XSS-resistant by architecture**: JSON to primitives to React escaping.
+
+## Blocked `$auth` fields
+
+Always return `undefined`:
+`token`, `accessToken`, `access_token`, `refreshToken`, `refresh_token`,
+`password`, `secret`, `session`, `metadata.token`, `metadata.password`.
+
+## Production behavior
+
+- **Auth errors silent in production**: `login`, `logout`, `refreshSession`
+  errors logged to console only when `NODE_ENV !== 'production'`. In
+  production, suppressed to prevent stack-trace leakage to attackers.
+  Errors still appear in UI via `/auth/error`.
+
+## Never trust client auth as security
+
+`AppAuthConfig` is UX routing (hide screens by role), not server-side
+security. Always validate tokens on the backend (rule 42).
+
+## Related concepts
+
+- [[@concept-auth-config]]
+- [[@concept-custom-jwt-provider]]
+- [[@expression-auth]]
+- [[@concept-auth-domains]]
+- [[@concept-state-protection]]
+- [[@concept-cross-tab-sync]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md` - AppSpec & Navigation / Auth Config (Security)
+- `docs/consumer/reference-doc.md` - Security Guarantees

package/docs/wiki/compiled/concept-auth-state-paths.md

@@ -0,0 +1,48 @@
+---
+id: concept-auth-state-paths
+title: Auth state paths — `/auth/*`
+kind: concept
+sources: [docs/consumer/ai-context.md#login-screen, docs/consumer/reference-doc.md#auth-state-paths-read-only-auto-managed]
+---
+
+# Auth state paths — `/auth/*`
+
+Auth state paths are **read-only** and auto-managed by the auth engine.
+StateGuard blocks spec writes to `/auth/*`.
+
+## Paths
+
+| Path | Type |
+|---|---|
+| `/auth/isAuthenticated` | boolean |
+| `/auth/loading` | boolean |
+| `/auth/error` | string \| null |
+| `/auth/user/id` | string |
+| `/auth/user/email` | string |
+| `/auth/user/name` | string \| null |
+| `/auth/user/avatar` | string \| null |
+| `/auth/user/role` | string (primary) |
+| `/auth/user/roles` | string[] (all roles) |
+| `/auth/user/metadata` | object \| null |
+
+## Read patterns
+
+Prefer [[@expression-auth]] over `$state: "/auth/user/..."` — `$auth` is
+whitelisted (blocks tokens/passwords).
+
+## Tokens NEVER live in state
+
+Tokens (access, refresh) live in engine closure only — never written to
+the state store. See [[@concept-auth-security]].
+
+## Related concepts
+
+- [[@expression-auth]]
+- [[@concept-auth-security]]
+- [[@concept-state-protection]]
+- [[@action-login]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § AppSpec & Navigation → Login Screen`
+- `docs/consumer/reference-doc.md § Auth State Paths`

package/docs/wiki/compiled/concept-auto-dark-mode.md

@@ -0,0 +1,55 @@
+---
+id: concept-auto-dark-mode
+title: Auto dark mode
+kind: concept
+sources: [docs/consumer/ai-context.md#deep-design-token-system, docs/consumer/reference-doc.md#auto-dark-mode]
+---
+
+# Auto dark mode
+
+DNA automatically generates `modes.dark` by inverting tonal palette stops.
+**No manual dark theme needed.** Override with explicit `modes.dark`
+values if desired.
+
+## Behavior
+
+- DNA is the source — palette stops invert in OKLCH lightness for
+  dark mode.
+- `toggleTheme` action toggles `/preferences/theme`.
+- `$token` automatically reads `/preferences/theme` and resolves with
+  the dark mode overrides when active.
+- All primitives re-render automatically.
+
+## Override
+
+If the auto-derived dark mode isn't what you want:
+```json
+"tokens": {
+  "dna": { "primary": "#0D9488" },
+  "modes": {
+    "dark": {
+      "colors": { "background": "#0a0a0a", "surface": "#1a1a1a" }
+    }
+  }
+}
+```
+
+## With variants
+
+`$path` references in variants resolve against the active token tree
+(dark already applied) — see [[@concept-path-references]]. No separate
+dark variant definitions needed unless the dark change isn't just a token
+swap.
+
+## Related concepts
+
+- [[@expression-token]]
+- [[@action-toggle-theme]]
+- [[@concept-component-variants]]
+- [[@concept-path-references]]
+- [[@concept-identity-color-scheme]]
+
+## Sources (raw)
+
+- `docs/consumer/ai-context.md § Deep Design Token System → Auto dark mode`
+- `docs/consumer/reference-doc.md § Auto Dark Mode`

package/docs/wiki/compiled/concept-background-caps.md

@@ -0,0 +1,42 @@
+---
+id: concept-background-caps
+title: `validateBackgroundCaps` — performance caps
+kind: concept
+sources: [docs/consumer/reference-doc.md#rule-210]
+---
+
+# `validateBackgroundCaps` — performance caps
+
+Performance validator for backgrounds. Returns
+`{ warnings: string[], errors: string[] }` (shared
+`AnimationValidationResult` type with `validateAnimationCaps`).
+
+## Caps
+
+| Scope | Soft (warn) | Hard (error) |
+|---|---|---|
+| Blobs per background | 8 | 16 |
+| Layers per background | 6 | 10 |
+| Custom-svg path length | 500 chars | 2000 chars |
+| Motion dimensions per blob | 2 | 3 |
+
+## Threshold semantics
+
+**Strictly-over** (`>`) — differs from `validateAnimationCaps`'s `>=`
+convention. Each function literal per its own design spec table
+(documented in source).
+
+## Constraints
+
+- `custom-svg` path length cap only applies when `shape === 'custom-svg'`
+  AND `path` is a string.
+
+## Related concepts
+
+- [[@concept-blob-layer]]
+- [[@concept-background-layer-kinds]]
+- [[@concept-animation-caps]] — animation parallel
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rule 210`

package/docs/wiki/compiled/concept-background-layer-kinds.md

@@ -0,0 +1,80 @@
+---
+id: concept-background-layer-kinds
+title: Background layer kinds
+kind: concept
+sources: [docs/consumer/reference-doc.md#rules-171-176-217]
+---
+
+# Background layer kinds
+
+`LayerConfig` union has 6 variants. Each carries `LayerCommonProps`
+(`opacity?`, `blendMode?`, `zIndex?`).
+
+## Kinds
+
+| Kind | Use |
+|---|---|
+| `solid` | Single color |
+| `gradient` | Linear / radial / conic. See below. |
+| `pattern` | Grid / dots / diagonal / iso / crosshatch / chevron / custom-svg. See [[@concept-pattern-primitives]] |
+| `grain` | SVG `feTurbulence` noise overlay |
+| `image` | Bitmap / vector image |
+| `blobs` | Curated organic shapes — see [[@concept-blob-layer]] |
+
+## Composition
+
+Any mix composed as ordered stack. Each layer supports:
+- `opacity` (0–1)
+- `blendMode` (`normal` / `multiply` / `screen` / `overlay` / `soft-light`
+  / `hard-light` / `color-dodge` / `color-burn`)
+- `zIndex` (defaults to array index)
+
+## Gradient primitive
+
+```json
+{ "type": "gradient", "kind": "radial", "shape": "circle", "size": "500px", "position": "0% 20%", "stops": [
+  { "color": "#0D9488", "opacity": 0.8, "at": 0 },
+  { "color": "#0D9488", "opacity": 0, "at": 70 }
+]}
+```
+
+Linear / radial / conic with custom `stops[]` (each `{ color, opacity, at }`).
+Opacity → rgba conversion automatic.
+
+## Grain primitive
+
+```json
+{ "type": "grain", "intensity": 0.05, "scale": 0.9, "monochrome": true }
+```
+
+Defaults: `intensity: 0.05`, `scale: 0.9`, `monochrome: true` (premium
+desaturated grain).
+
+## RN limitations
+
+- **Blob `blur` not rendered** until Plan 4 filter parity.
+- **Non-`normal` blendMode** triggers dev-warn on RN — no `mixBlendMode`
+  equivalent.
+
+## Custom-svg escape hatch
+
+```json
+{ "kind": "custom-svg", "shapes": "<circle.../>", "tileSize": 20 }
+```
+
+`sanitizeSVGShapes` uses regex pre-strip + DOMPurify allowlist. Only
+circle/rect/path/line/polygon/polyline/ellipse/g/defs/gradients +
+geometric attrs survive. Rejects `<script>`, `<foreignObject>`,
+`<use href>`, `on*` events, `javascript:` URLs.
+
+## Related concepts
+
+- [[@concept-layer-background]]
+- [[@concept-background-stack]]
+- [[@concept-pattern-primitives]]
+- [[@concept-blob-layer]]
+- [[@concept-background-caps]]
+
+## Sources (raw)
+
+- `docs/consumer/reference-doc.md § rules 171-176, 217`