Most of your app lives as validated JSON specs loaded at runtime from your database, not source code that must be regenerated and redeployed for every change. AI agents compose those specs from a documented vocabulary; Mythik teaches them the workflow, reveals what the running app actually mounted, and validates every persisted change before the runtime accepts it.
Help without limits. Freedom without chaos.
npm install mythik mythik-react
npm install -D mythik-cli
Mythik teaches agents the workflow. Reveal shows runtime truth.
This is a live Mythik render: JSON fetched from a Supabase row at page load, no rebuild, no deploy. Drag the sliders, change the surface, swap a preset; every control writes to state, every state path is read by primitives below. The same vocabulary lets agents compose app JSON instead of editing React files.
Auth, fetch, loading state, error handling, and skeletons are driven by the spec. Wrong shape, invalid expressions, and broken cross-references are rejected with diagnostics — they never become runtime crashes.
Agents edit JSON the framework can validate. Reviewers see which element, prop, action, or data path changed instead of a code rewrite that might touch ten unrelated things.
{ "root": "screen", "elements": { "screen": { "type": "screen", "children": ["heading", "list"] }, "heading": { "type": "text", "props": { "content": "Tasks" } }, "list": { "type": "list", "repeat": { "source": { "$state": "/tasks" } }, "children": ["task-row"] } }, "dataSources": { "tasks": { "url": "/api/tasks", "target": "/tasks" } } }
With code generation, every product request can become an architectural negotiation: which files should change, where state should live, how errors should flow, and what the agent touched by accident.
Files multiplyComponents, hooks, state stores, API clients, forms, and styles become possible edit targets.
Architecture driftsEach request can invent a new pattern unless the reviewer catches it.
Review gets widerThe diff may be correct locally while touching surfaces unrelated to the request.
Specs stay narrowThe change is an RFC 6902 patch against a documented vocabulary.
The framework owns behaviorRenderer, actions, validators, version store, and server runtime keep the architecture consistent.
Review gets smallerYou inspect the element, prop, action, or data path that changed.
A passing build is not proof of correctness. Codegen can compile while the intent, data path, or action contract is wrong. Mythik checks the spec deeper: shape, references, primitives, actions, and state paths must all be valid before the runtime accepts the change.
A 5-screen app and a 500-screen app have the same shell. Adding features grows the spec store, not the host. The host file only changes when the project genuinely needs a cross-cutting integration — an icon pack, a custom auth provider, an action middleware, a storage adapter.
import { MythikApp } from 'mythik-react'; import { MemorySpecStore } from 'mythik'; const specStore = new MemorySpecStore({ home: homeSpec }); export default function App() { return <MythikApp appSpec={appSpec} specStore={specStore} />; }
import { createServer } from 'mythik-server'; createServer({ spec: './api-spec.json' }).start(3010);
No router setup
No state-store wiring
No form library config
No JWT middleware glue
One vocabulary. The same validation gate, the same lint rules, the same versioning, the same audit trail apply whether the change touches a screen, an API endpoint, a transaction, or a patch.
Elements, props, style, transactions, derive, and dataSources live in a flat document the renderer interprets.
Four declarative phases describe optimistic behavior. The engine owns snapshot, rollback, and commit.
JSON Pointer paths say exactly what changes. The framework validates the patch before it reaches the store.
Think of it like a grammar.
Finite rules. Infinite sentences. The rules don't shrink what you can say — they make it possible to say anything and be understood.
Every spec change passes through SpecEngine.patch()
before reaching the store. Apply the patch, run document-handler
validation, short-circuit on error, then persist. The previous
valid version stays current when validation fails.
Agent emits an RFC 6902 patch against the current spec.
Patch is applied to a candidate spec in memory only.
Every rule, expression, ref and protected path is checked.
If invalid: typed ValidationError with ruleId. Store unchanged.
Only validated specs reach the store. Previous version stays live until then.
The agent edits a JSON contract, not implementation details. The validator knows the contract.
Every ValidationError carries a ruleId that maps to a rule in the reference doc. No error-string parsing.
StateGuard blocks setState to /auth/*, /tx/*, all derive paths, and framework-reserved paths — at validation time and runtime.
The card below runs the framework's validateSpec against any JSON you paste. Same engine that gates every spec store write — wrong shape, unknown primitives, broken references all surface here with typed paths.
Most stacks check types between client and server. Mythik checks four dimensions at once — fetches, fields, query params, and role permissions — across every screen × every endpoint × every role, because both sides are JSON specs in the same vocabulary. Drift surfaces at push time, never in production.
# Cross-checking 14 screens against api-spec.json… ✗ screen "task-detail" reads field "assignee.avatar" from "GET /api/tasks/:id" → API returns assignee.avatarUrl (did you mean this?) ✗ screen "admin-panel" visible to role "user" contains action calling "DELETE /api/users/:id" → endpoint policy: "admin", role drift ⚠ screen "task-list" sends query param "filter" → endpoint declares: ["status", "priority"], did you mean "status"? 3 contract violations. Push aborted.
Every fetch in every screen spec must point at an endpoint the API actually exposes.
Every $state binding for fetched data must match the field names the API spec declares it returns.
Params sent in fetch URLs must be in the endpoint's params map. Typos surface with Levenshtein-suggested corrections.
If a screen is visible to role X and contains an action calling endpoint Y, role X must satisfy Y's policy.
The check is mechanical. No type-generation step,
no contract test suite, no client/server schema sync. Both
artifacts are JSON in a shared vocabulary — and the check runs
as part of mythik push, before any pointer moves.
A product request becomes a narrow JSON workflow. The agent reads the app structure, inspects only the elements that need to change, applies an RFC 6902 patch, and Mythik validates the spec before it reaches runtime.
Add a due date field to the task manager. Show it in the list and add it to the new task form. Do not edit React files.
$ npx mythik manifest task-manager --toon
task-manager
task-list
task-table
new-task-form
title-input
priority-select
submit-button
$ npx mythik elements task-manager task-table,new-task-form --json
reads 2 elements, not the codebase
$ npx mythik patch task-manager --from-file add-due-date.patch.json --author agent
Patch applied. version: 12
$ npx mythik validate task-manager
Validation passed.
[
{
"op": "add",
"path": "/elements/task-table/props/columns/-",
"value": { "key": "dueDate", "label": "Due date", "format": "date" }
},
{
"op": "add",
"path": "/elements/due-date-input",
"value": {
"type": "input",
"props": {
"type": "date",
"label": "Due date",
"value": { "$bindState": "/draft/dueDate" }
}
}
},
{
"op": "add",
"path": "/elements/new-task-form/children/-",
"value": "due-date-input"
}
]The agent reads a manifest and two target elements instead of scanning the full app.
JSON Pointer paths name exactly what changes. Everything else stays untouched.
Invalid shape, unknown primitives, and broken refs are rejected before runtime.
Modifying one screen cannot affect another. They are separate documents in the spec store.
Fresh agents should not need a human Mythik expert beside them.
mythik agent init installs project-local operating
instructions for Codex, Claude, or both, then keeps the Mythik
block managed while preserving the rest of the file.
This is not generic prompt boilerplate. It teaches the mandatory
workflow, the active-store source of truth, and the rule that
routine edits stay on manifest → elements → patch
→ validate → verify instead of pull/edit/push.
$ npx mythik agent init codex
writes or updates AGENTS.md
$ npx mythik agent init claude
writes or updates CLAUDE.md
$ npx mythik agent init all
keeps both adapters aligned
Existing project guidance stays intact. Mythik owns only its block: workflow, source-of-truth rules, strict write intent, and verification discipline.
The canonical app is the resolved Mythik store. Local JSON files are drafts, migrations, fixtures, or backups unless the project intentionally uses a file store.
The agent reads structure and target elements instead of scanning a codebase or rewriting full specs from stale files.
Persisted writes require --author; full replacements require --replace; unversioned writes must be explicit.
Documentation explains the contract. Reveal shows what the running app actually mounted, resolved, emitted, and rejected. Agents fix with runtime evidence instead of guessing from files.
$ npx mythik reveal start --port 17373
MYTHIK_REVEAL_URL=http://127.0.0.1:17373
MYTHIK_REVEAL_TOKEN=<generated-token>
$ npx mythik reveal context --app task-manager
$ npx mythik reveal element save-button --app task-managerMounted spec summary, renderer/platform, selected screen, element context, resolved public props, and dependency paths.
State paths, actions, transactions, dataSources, navigation, lifecycle events, diagnostics, warnings, and render errors.
Reveal is development tooling. It connects through a local bridge, uses generated tokens, and redacts sensitive keys by default.
Add --author to any push or patch, and the change is
recorded in screen_versions as part of a snapshot-plus-patch
chain. Inspect with mythik history; reverse with
always-forward rollback; promote across environments by atomic
pointer move.
v3 (claude, 2026-04-25, patch) "Reorder priority field" ~ element "priority-select" prop position: "after-title" → "before-status" v2 (alice, 2026-04-24, push) "Add priority field" + element "priority-select" added ~ element "submit-btn" prop content: "Send" → "Submit" v1 (system, 2026-04-23, push)
v1 stores the full spec. Subsequent versions store RFC 6902 patches. Every N versions a fresh snapshot bounds replay cost.
computeStructuralDiff produces typed records with actual values — "Send" → "Submit", not byte deltas.
executeRollback creates a new forward version with the target version's content. History never gets rewritten.
Promoting dev → staging → prod validates structure, cross-screen consistency, and the frontend↔backend contract before any pointer moves.
In a traditional app, a small product change can still require a full release cycle. In Mythik, most app changes are validated specs: checked before storage, versioned for rollback, and loaded by the runtime without redeploying the bundle.
mythik patch writes the new spec to the store. Active screens pick up the next valid version on the next fetch — no host-app remount.
Dev, staging, and prod are environment pointers in screen_environments. Promotion validates atomically; rollback moves the pointer back.
Different customers can receive different screen specs while the application binary remains identical. Multi-tenant variation is rows, not separate deploys.
Every iteration of read manifest → propose patch → push → observe runs at network round-trip speed. Self-correction loops become real loops.
The boundary is honest. This applies to spec changes.
The host file (App.tsx, server.ts) and
custom plugin code still ship through the standard npm build pipeline —
but those rarely change, because a 5-screen app and a 500-screen app
have the same host file.
Two retrieval-optimized knowledge bases ship with the framework. Agents consult them before producing JSON, eliminating the hallucinated-primitive class of failures that plague codegen tools.
One concept per file (~30–80 lines each), cross-linked by
[[@<id>]] wikilinks. _index.md lists
every article in a flat searchable format the agent reads to
decide which file to load.
An agent answering "how do I write an UPDATE transaction?" loads pattern-tx-update.md (~40 lines) and follows wikilinks. No full-corpus scan.
Module-by-module loadable for broader context. Frontend tasks load primitives + patterns. Server tasks load API + custom-elements. Debugging tasks load runtime semantics.
| ai-context.md | 1,331 |
| ai-context-runtime-semantics.md | 940 |
| ai-context-primitives.md | 629 |
| ai-context-patterns.md | 254 |
| ai-context-custom-elements.md | 249 |
| ai-context-api.md | 195 |
| reference-doc.md | 3,156 |
The wiki is generated, linted, and gap-tracked by tooling. It is not documentation that happens to also be readable by AI — it is a retrieval system that happens to also be readable by humans.
Pattern credit: this approach follows the LLM wiki pattern Andrej Karpathy popularized — atomic markdown articles cross-linked for agent traversal, with a separate schema doc telling the LLM how to maintain it.
The table below is the framework's table primitive on real data fetched from this very framework checkout. sorting, pagination, and stickyHeader are flags on the same JSON spec — 5 declarative props on a single primitive. No table component, no row renderer, no pagination logic.
A failure in one spec is contained to that spec. Per-screen storage,
validation gate, lint defense-in-depth, StateGuard,
screen-scoped re-mount, render error boundary, and per-instance
custom element isolation all keep the blast radius bounded.
Malformed patches are rejected before persistence. Store unchanged.
Protected paths and derived state cannot be overwritten — at validation and runtime.
Screens are separate documents. Patching one cannot affect another.
Runtime errors write diagnostics to /ui/renderErrors. Sibling elements keep rendering.
[ { "elementId": "priority-select", "message": "$state path /tasks/priority not found", "type": "select" } ]
Five stages, four of them framework work. Only the first costs LLM tokens — the rest are the framework catching mistakes, surfacing them, and resetting boundaries on the next valid spec.
The only stage that costs LLM tokens. The framework owns everything that follows.
mythik lint + SpecEngine.patch() + StateGuard reject malformed patches synchronously. Most errors stop here.
If a validator-passing spec fails at render, the boundary scopes the failure to the offending element.
Errors are written to /ui/renderErrors as a typed array. The agent reads them like any other state path.
Agent generates the next patch. Boundary auto-resets on spec change. Loop closes.
The boundary is honest. The loop closes for technical spec errors — invalid expressions, unknown primitives, missing state paths, anti-pattern violations. It does not close for semantic errors (a spec where every expression resolves but the user-facing behavior is wrong). Semantic correctness still requires test suites, human reviewers, or verification hooks.
Mythik gives agents declarative power while the framework enforces schemas, validators, permissions, rollback, design coherence, and cross-platform runtime behavior.
A brand color and a handful of personality sliders derive colors, typography, spacing, elevation, dark mode, and motion timing.
Surface, corners, typography, gradients, color schemes, backgrounds, and motion live in one validated identity block.
Snapshot state, apply optimistic UI, confirm over the network, and roll back atomically if the server rejects.
Computed paths update in topological order, are write-protected by StateGuard, and never need manual memoization.
22 handlers cover filtering, sorting, formatting, conditional logic, branching, i18n, auth-safe reads, and 16 array operations.
Add a fetch and the renderer replaces data-dependent elements with correctly-shaped shimmer skeletons during loading.
updateTokens and applyPreset swap the brand, dark mode, gradients, or entire visual preset at runtime.
mythik-react-native follows the same 0.2.1 version line and is available while native primitive parity and smoke coverage continue to expand.
$i18n with expression-valued args; setLocale at runtime; locale-aware $format and $date.
The card below is a Mythik spec with initialActions firing a fetch. While /items is empty during loading, the renderer auto-substitutes shape-matching shimmer skeletons for each text and icon. Reload to see it again.
Every interaction is a transaction with five named phases — before, snapshot, optimistic, confirm, resolve. The engine snapshots state before your optimistic update lands. When the API call fails, the snapshot wins back atomically. You never write rollback code — the contract lives in the spec.
navigation.auth owns the lifecycle.Authentication is part of the framework, not a problem to solve. A developer enables it with a JSON block — no auth context provider, no protected-route HOC, no session restoration logic, no token refresh loop, no cross-tab coordination, no rate limiting.
"navigation": { "auth": { "provider": "supabase", "loginScreen": "login", "protectedScreens": ["*"], "roleAccess": { "admin": ["*"], "user": ["dashboard", "profile"] }, "persistence": "local", "tokenRefresh": true, "authDomains": ["api.example.com"] } }
local survives browser close. session ends with the tab. memory requires re-login on every refresh.
Login, logout, refresh, and session expiry propagate across tabs via BroadcastChannel with localStorage fallback.
Access tokens never enter the state store. $auth whitelists block token reads. StateGuard blocks writes on /auth/*.
authDomains ensures Bearer tokens attach only to allowed hostnames. Tokens never leak to third-party APIs.
When the framework doesn't ship what you need, you don't fork it —
you register it. MythikApp.onPlugins exposes a single
PluginLoader that lets you add capabilities at every
layer of the engine. Every extension passes through the same
dispatcher, validator, and error boundary as the built-ins.
registerActionNew action handlers callable from spec.
registerExpressionNew $<name> handlers in any expression context.
registerPrimitiveNew primitive types or replacements for built-ins.
registerElementFirst-class Layer-3 custom elements with variants and animations.
registerValidatorNew validator types for forms and inline checks.
registerSourceProviderNew data-source providers for dataSources.
registerPresetsDNA + Identity preset bundles for runtime theme switching.
setIconRendererHost-app icon renderer (Phosphor / Lucide / custom).
Structure that enables. Not structure that restricts.
Every extension point is a contract — a place where the AI can compose freely, with the framework guaranteeing safety, validation, and isolation around what gets composed. The framework owns the contracts; you and the AI own what fills them.
mythik-server turns an API spec into a REST server.Auth, RBAC, row-level security, CRUD with field-injection defense, audit fields, and catalogs are declared in JSON. A real workload with 48,763 records, 35 endpoints, 170 tenant scopes, and 3 user roles was rebuilt in 192 total lines.
Point Mythik at an API spec and it mounts typed REST endpoints from declarative JSON.
Policies and tenant boundaries are enforced uniformly on reads, updates, and deletes.
Insertable and updatable allowlists drop injected fields before database writes.
Server-side audit values are un-spoofable. Live-data tests prove the contract works across roles.
crud block generates three routes.
POST, PUT/:id, and DELETE/:id
ship from one declaration — with field-injection defense and
server-side audit built in. SCOPE_IDENTITY() +
SELECT instead of OUTPUT INSERTED.* means
CRUD is safe against tables with database triggers.
"tasks": { "path": "/api/tasks", "policy": "authenticated", "crud": { "table": "tasks", "primaryKey": "id", "insertable": ["title", "priority"], "updatable": ["title", "priority", "status"] } }
/api/tasks
Insert. Body filtered to insertable fields. Injected fields like isAdmin are silently dropped.
/api/tasks/:id
Update by primary key. Body filtered to updatable fields.
/api/tasks/:id
Delete by primary key. Scoped by scopeFilter if configured.
Fields not in insertable or updatable are silently dropped. A client cannot inject isAdmin: true.
Audit values are written server-side after field filtering. Clients cannot forge them.
INSERT uses SCOPE_IDENTITY() + SELECT. Compatible with tables that have triggers.
scopeFilter once. Every query, update, and delete is scoped.One JSON block enforces per-user data boundaries across SELECT, UPDATE, and DELETE — uniformly. The same mechanism works for tenants, clinics, branches, departments, or any partitioning column.
"scopeFilter": { "claim": "tenants", "column": "tenantId", "bypassRoles": ["admin"], "mode": "all" }
Injects WHERE column IN (:scope_array). The user sees data from every scope assigned to them.
Injects WHERE column = @activeScope via header. The user picks one active scope at a time.
SELECT, UPDATE, and DELETE all enforce the filter. A user cannot modify rows outside their scope.
bypassRoles for admins
One config line lets specific roles skip the filter entirely.
Custom SQL templates override the global config when needed.
scopeFilter not institutionFilter — same pattern for any partitioning column.
One createServer call wires it all up. The spec stays
secret-free; secrets and connection strings come from the
environment at boot.
import { createServer } from 'mythik-server'; createServer({ spec: './api-spec.json' }).start(3010);
Every framework decision shown above is made once, at the framework level — and every AI agent that touches the codebase inherits the same answer. Two agents working on the same codebase, six months apart, produce structurally identical decisions because the decisions are not theirs to make.
scopeFilter on the endpoint
Owns SQL injection across read/write/delete
--author on the patch
Owns version chain, structural diffs, rollback
The framework was designed around one question: can an LLM generate this correctly without first breaking it? The answer shaped every surface — the wiki, the rule IDs, the JSON shape of extensions, the error boundaries, the build-free spec pipeline.
mythik agent init writes project-local operating instructions so fresh Codex and Claude sessions inherit the canonical Mythik workflow.
When a running app misbehaves, agents inspect mounted specs, resolved props, selected state, diagnostics, and render errors before patching.
Agent docs, TOON reads, manifests, element queries, and Reveal context keep the working set narrow instead of forcing full-corpus scans.
mythik-cli/api exposes runPush, runPatch, and runLint with typed JSON output, so agents do not parse terminal text.
Spec iterations run at network round-trip speed. read → patch → observe → correct is a real loop because there is no build pipeline blocking the cycle.
The worst-case outcome of an AI mistake is contained to one spec — caught by validation gate or render boundary. Agents can iterate freely.
The mythik npm package bundles the AI corpus under node_modules/mythik/docs. After installing the CLI, run npx mythik docs path and point your agent at the directory — no external download, no API key.
I've been building with AI for a while. It's incredible how much it helps. Until it isn't — until you ask for one small change and it touches three things you didn't want it to touch.
I kept thinking there had to be a way to keep the help without the surprise. Some way to give the AI room to work without giving it permission to break things you weren't watching.
Eventually I tried something simple. I stopped letting the AI write code, and started letting it write JSON. Just data — a description of what the UI should be. A renderer I'd already built and tested would take care of the rest.
Mythik 0.2.1 pushes that bet further: the framework now teaches agents how to work, reveals the runtime truth of a mounted app, and keeps every persisted change behind a validation gate.
Version 0.2.1 keeps hardening the operating layer around the JSON-native app: Agent Protocol teaches the workflow, Reveal exposes runtime truth, and the validation gate protects every persisted change.
npm install mythik mythik-react
npm install -D mythik-cli
npm install mythik mythik-react-native
Expo projects install native peers with npx expo install so versions match the active SDK.
npm install mythik-server
Help without limits. Freedom without chaos.