mythik

The Mythik contract runtime: types, validation, expressions, actions, spec stores, versioning, editor sessions, and Reveal context contracts. This is the foundation every Mythik consumer imports. It also ships the canonical AI documentation bundled inside the npm tarball, so the docs an agent reads always match the installed version of the framework.

See the framework README on GitHub for the full Mythik architecture and design philosophy. This file documents what mythik gives you and how to use it.

What Mythik is, briefly

Mythik is an AI-first JSON-native app framework. 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 validates the shape, references, actions, state paths, and cross-contract assumptions before the change reaches runtime. This package is the runtime that makes that contract work.

Install

npm install mythik

mythik has no peer dependency. It's the foundation.

When to install this

You install mythik whenever you're building anything Mythik-related:

| You want to... | Install | |---|---| | Render specs as a React app | mythik + mythik-react | | Render specs in React Native or Expo | mythik + mythik-react-native | | Build a REST API from an ApiSpec | mythik + mythik-server | | Author or patch specs from the command line | mythik + mythik-cli (dev) | | Validate or query specs from a Node script | mythik alone |

What you get

• Strict TypeScript types for Spec, AppSpec, ApiSpec, primitives, expressions, actions, and validation results.

• The validation gate — validateSpec() and validateApiSpec() are the atomic checks that run on every push and promote. Call them directly to validate offline, in CI, or in a test.

• Spec stores — load and save specs through a swappable backend interface:

  • Browser-safe entry: MemorySpecStore, SupabaseSpecStore
  • Node-only entry (mythik/server): FileSpecStore, SqlSpecStore, SqlVersionedSpecStore, SqlEnvironmentStore, and SQL Server compatibility stores
  • Versioned variants (SupabaseVersionedSpecStore, SupabaseEnvironmentStore, SqlVersionedSpecStore, SqlEnvironmentStore) add snapshot+patch-chain history, structural diffs, and atomic promote gates

• Expression and action engines — the runtime that resolves $token, $state, $template, and dispatches action chains, transactions, forms, auth, derive, dataSources, uploads, and exports. Specs reference these by name; this package implements the resolution.

• App engine — navigation, auth integration, and screen lifecycle. Most consumers reach the app engine through <MythikApp> in mythik-react, but the runtime lives here and can be used directly for non-React shells or custom integrations.

• Mythik Reveal contracts — typed runtime context, redaction, truncation, event recorder, and protocol shapes used by the React, React Native, and CLI Reveal integrations. Reveal lets a running app expose its live contract, selected state, events, diagnostics, and environment as structured context for AI agents.

Browser-safe vs Node-only entries

// Browser-safe (works in any runtime)
import { MemorySpecStore, SupabaseSpecStore } from 'mythik';

// Node-only (file system and SQL drivers)
import { FileSpecStore, SqlSpecStore, createSqlDriver } from 'mythik/server';

Bundlers like Vite or Webpack should always import from mythik (the main entry). The mythik/server subpath is for Node scripts and server processes only. It uses Node APIs and dynamically loads the SQL driver package you installed for the selected database.

SQL adapters are optional peer dependencies. Install only the adapter you use:

npm install pg              # PostgreSQL
npm install mysql2          # MySQL
npm install mssql           # SQL Server
npm install better-sqlite3  # SQLite

SQLite uses the native better-sqlite3 adapter. If npm prints warnings from that adapter's transitive native-build helpers, the warning belongs to the SQLite adapter install path, not to Mythik's browser/runtime install. Missing SQL adapter errors include the package name and install command for the selected dialect.

SQL-backed stores use one dialect-aware driver boundary:

import { SqlSpecStore, createSqlDriver } from 'mythik/server';

const driver = createSqlDriver({
  dialect: 'postgres', // 'sqlserver' | 'postgres' | 'mysql' | 'sqlite'
  connection: process.env.DATABASE_URL!,
});

const store = new SqlSpecStore({ driver });

Initialize the required tables with the CLI:

npx mythik init-store --dialect sqlite --target ./mythik.db
npx mythik init-store --dialect postgres --dry-run

MySQL generated upsert SQL targets MySQL 8.0.19+.

Minimal example

Validate a spec in-process:

import { validateSpec, MemorySpecStore, type Spec } from 'mythik';

const homeSpec: Spec = {
  root: 'root',
  elements: {
    root: {
      type: 'box',
      props: { style: { padding: 24 } },
      children: ['title'],
    },
    title: {
      type: 'text',
      props: { content: 'Hello, world', variant: 'heading' },
    },
  },
};

const result = validateSpec(homeSpec);

if (!result.valid) {
  for (const err of result.errors) {
    console.error(`[${err.ruleId}] ${err.path}: ${err.message}`);
  }
  process.exit(1);
}

const store = new MemorySpecStore({ home: homeSpec });
const loaded = await store.load('home');
console.log('Loaded spec for screen:', loaded?.root);

validateSpec() is the same function the CLI calls when it runs mythik validate <spec-id> and the same gate that mythik patch enforces atomically. Same machine, three surfaces.

For rendering specs as a React UI, see mythik-react. For an AI agent surface to read, validate, patch, and promote specs from the command line, see mythik-cli.

AI documentation, bundled

This package ships the canonical AI documentation inside the npm tarball — so the docs travel with the framework (no external doc fetching, no version drift between docs and runtime):

node_modules/mythik/docs/
├── consumer/
│   ├── ai-context.md                    # spec-generation primer
│   ├── ai-context-primitives.md         # every primitive's props
│   ├── ai-context-runtime-semantics.md  # render-time behavior
│   ├── ai-context-custom-elements.md    # custom expressions/actions
│   ├── reference-doc.md                 # full rule catalog
│   └── WHERE-TO-LOOK.md                 # navigation guide
├── wiki/compiled/                       # atomic per-concept articles
└── llms.txt                             # index for LLM tooling

mythik-cli adds a small helper to locate or copy these into your project:

$ npx mythik docs path
/your-project/node_modules/mythik/docs

$ npx mythik docs copy ./mythik-docs

Point your AI agent at the printed path before asking it to author or modify specs.

For runtime debugging, pair these docs with Mythik Reveal:

npx mythik reveal start
npx mythik reveal apps --json
npx mythik reveal context --app <app-name>

Docs explain the contract; Reveal shows what the running app actually mounted.

For fresh AI agents, install the local operating protocol before asking for spec changes. agent init currently supports codex, claude, and all. codex creates/updates AGENTS.md, claude creates/updates CLAUDE.md, and all updates both. Existing agent files are preserved outside the Mythik-managed block delimited by <!-- mythik-agent-protocol:start --> and <!-- mythik-agent-protocol:end -->.

The adapters point the agent to shared .mythik/agent/* instructions:

npx mythik agent init codex
npx mythik agent context --app <app-id> --include-screens --out .mythik/agent/context.md

The generated protocol names the active Mythik store as the source of truth and keeps existing spec edits on manifest -> elements -> patch --from-file --author -> validate -> verify.

Related packages

• mythik-react — render the specs as a React app
• mythik-cli — Agent Protocol, patch workflow, validation, versioning, environments, and Reveal commands
• mythik-server — declarative REST server from an ApiSpec
• mythik-react-native — render supported Mythik primitives in Expo and React Native

Status

Public release line. APIs are documented for real-world feedback as the framework evolves.

Releases

Release notes and patch details are published in the CHANGELOG and on GitHub Releases.

License

Apache-2.0.