uidl-runtime 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Doni Wicaksono
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,175 @@
+# uidl-runtime
+
+A schema-driven React runtime that renders validated JSON documents into real application
+surfaces — lists, forms, reports, dashboards and settings — without putting business
+workflows inside page components.
+
+A **UIDL document** is JSON describing layout, state, queries, bindings, events and actions.
+`uidl-runtime` validates it against a Zod schema and renders it through a component registry.
+Nothing in a document names a data source, an HTTP client or a database: reads go through a
+single `DataAdapter` seam and writes go through a host-supplied mutation handler, so the same
+document runs in memory, against a mock API, or against a real backend.
+
+It was built for three callers: AI agents that generate interfaces from structured
+instructions, ERP-style products whose screens are defined by metadata rather than code, and
+low-code systems that need a validated document model instead of generated page files.
+
+```tsx
+import { DocumentSchema, UIDocumentRenderer, meridianLightTheme } from "uidl-runtime";
+import "uidl-runtime/style.css";
+
+const document = DocumentSchema.parse(rawDocument);
+
+export function App() {
+  return (
+    <UIDocumentRenderer
+      document={document}
+      theme={meridianLightTheme}
+      onRouteChange={(path) => navigate(path)}
+    />
+  );
+}
+```
+
+## Status
+
+The runtime and its reference suite are functional and covered by tests. **This is not a
+production-ready product.** The reference applications are executable blueprints, not
+certified systems — read the maturity table below before treating any of them as finished.
+
+- 131 test files, 1176 tests, one typecheck, one lint pass
+- 11 industry reference consoles plus a full double-entry accounting reference
+- Every financial posting satisfies `sum(debit) === sum(credit)`, checked by an audit gate
+
+## Quick start
+
+Node.js LTS and npm.
+
+```bash
+npm install
+npm run dev
+```
+
+To exercise the HTTP adapter instead of the in-memory one, run two terminals:
+
+```bash
+npm run mock:api            # mock API on port 8787
+npm run dev:reference:http
+```
+
+## Commands
+
+| Command | Purpose |
+|---|---|
+| `npm run dev` | Start the reference application suite in memory |
+| `npm run dev:reference:http` | Start the suite with `VITE_DATA_MODE=http` |
+| `npm run mock:api` | Start the local mock API on port 8787 |
+| `npm run typecheck` | Type-check all workspaces |
+| `npm run lint` | Run ESLint |
+| `npm test` | Run Vitest unit and integration tests |
+| `npm run build` | Build the public library and JSON schemas |
+| `npm run build:reference` | Build the reference application suite |
+| `npm run audit:reference` | Architecture, maturity and balanced-GL gates |
+| `npm run test:reference` | Playwright acceptance tests, in memory |
+| `npm run test:reference:http` | Playwright acceptance tests over HTTP |
+| `npm run smoke:package` | Pack and consume the public npm artifact |
+| `npm run validate:examples` | Validate the example UIDL documents |
+
+## How it works
+
+Reads flow one way, from metadata to rendered surface:
+
+```text
+DoctypeMeta / ModuleSpec
+        -> page generator
+        -> UIDLDocument            (validated by DocumentSchema)
+        -> UIDocumentRenderer
+        -> DataAdapter
+```
+
+Writes never take that path. They cross an explicit boundary instead:
+
+```text
+UIDL mutate action
+        -> host mutationHandler
+        -> document or domain service
+        -> DataAdapter
+```
+
+The data mode is chosen in exactly one file, `packages/templates/src/config/data.config.ts`.
+Documents and generators must not import a concrete adapter.
+
+### Core concepts
+
+- `$bind` reads reactive state or query results.
+- `$query` delegates a read to the `DataAdapter`.
+- `$expr` evaluates the supported declarative expressions, including aggregates.
+- `mutate` delegates a write to the host and **fails closed** when no permitted handler exists.
+- Generic list, form, workspace, settings, dashboard and report surfaces are generated UIDL.
+- A composite transaction may use a thin React component when UIDL cannot express the
+  interaction — but the business rules stay in services.
+
+## Repository structure
+
+```text
+uidl-runtime/
+├── packages/
+│   ├── core/          # Schemas, renderer, state, actions, themes, registry, adapters
+│   └── templates/     # Page generators, verticals, domain services, mock data
+├── apps/reference/    # Executable references, playground, gallery, POS, regression harness
+├── e2e/               # Browser acceptance and visual-regression tests
+├── scripts/           # Audit, mock API, packaging and validation tools
+└── docs/product/      # Background product notes, not a status authority
+```
+
+`packages/core`, `packages/templates` and `apps/reference` are private workspaces. The
+published artifact is `uidl-runtime`, including its required `style.css`.
+
+## Reference suite
+
+**Meridian** is the core reference: a complete double-entry accounting desk — chart of
+accounts, sales and purchase cycles, journal entries, payments, stock ledger, POS shifts,
+General Ledger, Trial Balance, Profit and Loss and Balance Sheet. Every report is *derived*
+from postings rather than hand-written, so the books balance by construction.
+
+Eleven industry consoles sit beside it: shoe retail POS, school finance, manufacturing, food
+roasting, EPC contracting, CRM, cooperative/BMT, hospital, medical device, omnichannel
+distribution and helpdesk. Several model Indonesian business documents directly — Faktur
+Pajak, e-Faktur DJP, Surat Jalan, Akad Murabahah — and the interface runs bilingually in
+Indonesian and English.
+
+Maturity is stated per reference rather than claimed for the suite:
+
+| Level | Meaning |
+|---|---|
+| Concept Reference | Architecture or workflow direction, no complete user journey |
+| UI Reference | Reusable interface pattern, no complete business execution |
+| Functional Reference | Executable workflow with deterministic data and acceptance evidence |
+| Domain-Verified Reference | Functional, plus proven domain invariants and reconciliation |
+| Production-Ready | Operations, security, accessibility, performance and support proven |
+
+Most verticals are Functional References. School dunning, koperasi murabahah collectibility,
+hospital claim reconciliation and helpdesk SLA are Domain-Verified. **None is
+Production-Ready.** A workflow counts as proven only when a browser test drives its UI;
+calling a service directly counts as setup, not evidence.
+
+## Implementation rules
+
+- Presentation in components, reusable behaviour in hooks, pure functions in utilities,
+  workflows and integrations in services.
+- Validate every generated document with `DocumentSchema` before rendering.
+- Keep one `DataAdapter` seam; never import a concrete adapter from a document, generator or
+  UI component.
+- Require `sum(debit) === sum(credit)` for every financial posting.
+- Keep API-backed actions fail-closed and explicitly allowlisted.
+- Use the shared design tokens and vector icons; respect `prefers-reduced-motion`.
+- Do not introduce a second primary runtime model alongside `UIDLDocument`.
+
+## Credits
+
+Outline icons are from [Heroicons](https://heroicons.com) (MIT). The interface type is
+[Inter](https://rsms.me/inter/) (SIL Open Font License).
+
+## License
+
+MIT — see [LICENSE](LICENSE).

package/bin/validate.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { DocumentSchema } from "../dist/uidl-runtime.js";
+
+const args = process.argv.slice(2);
+if (args.length === 0) {
+  console.error("Usage: uidl-validate <file.json> [<file2.json> ...]");
+  process.exit(1);
+}
+
+let hasError = false;
+for (const filePath of args) {
+  let raw;
+  try {
+    raw = readFileSync(filePath, "utf-8");
+  } catch (err) {
+    console.error(`✗ ${filePath}: cannot read file (${err.message})`);
+    hasError = true;
+    continue;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (err) {
+    console.error(`✗ ${filePath}: invalid JSON (${err.message})`);
+    hasError = true;
+    continue;
+  }
+
+  const result = DocumentSchema.safeParse(parsed);
+  if (result.success) {
+    console.log(`✓ ${filePath}`);
+  } else {
+    console.error(`✗ ${filePath}`);
+    for (const issue of result.error.issues) {
+      const issuePath = issue.path.join(".") || "(root)";
+      console.error(`  - ${issuePath}: ${issue.message}`);
+    }
+    hasError = true;
+  }
+}
+
+process.exit(hasError ? 1 : 0);

package/dist/actions/eventBus.d.ts

@@ -0,0 +1,7 @@
+export type EventBusListener = (payload: unknown) => void;
+export interface EventBus {
+    on: (topic: string, listener: EventBusListener) => () => void;
+    emit: (topic: string, payload: unknown) => void;
+    off: (topic: string, listener: EventBusListener) => void;
+}
+export declare function createEventBus(): EventBus;

package/dist/actions/index.d.ts

@@ -0,0 +1,5 @@
+export { createEventBus } from './eventBus';
+export type { EventBus, EventBusListener } from './eventBus';
+export { ActionInterpreter } from './interpreter';
+export type { ActionContext, ApiAllowlist } from './interpreter';
+export type { CommandHandler, CommandRequest, CommandResponse, MutationHandler, MutationRequest, MutationResponse, } from '../types/actions';

package/dist/actions/interpreter.d.ts

@@ -0,0 +1,54 @@
+import { Action, CommandHandler, MutationHandler } from '../types/actions';
+import { DocumentStateStore } from '../state/createDocumentState';
+import { createEventBus } from './eventBus';
+/**
+ * A list of allowed hostnames (exact match, or `*.example.com` for subdomains), or a predicate
+ * for more advanced matching. `api` actions refuse to run unless this is provided — see
+ * `ActionInterpreter`'s `apiAllowlist` handling for why the default is fail-closed, not open.
+ */
+export type ApiAllowlist = string[] | ((url: URL) => boolean);
+export interface ActionContext {
+    stateStore?: DocumentStateStore;
+    session?: Record<string, unknown>;
+    route?: Record<string, unknown>;
+    data?: Record<string, unknown>;
+    eventBus?: ReturnType<typeof createEventBus>;
+    mutationHandler?: MutationHandler;
+    commandHandler?: CommandHandler;
+    apiAllowlist?: ApiAllowlist;
+    /** Max `api` response body size in bytes before the request is aborted. Default 5MB. */
+    apiMaxResponseBytes?: number;
+    /**
+     * Max number of `api` actions this interpreter runs concurrently; further calls fail fast
+     * instead of queueing, so a document that fires many `api` actions at once (e.g. one per row
+     * of a `repeat`) can't hammer an allowlisted host or exhaust client connections. Default 6.
+     */
+    apiMaxConcurrentCalls?: number;
+}
+export declare class ActionInterpreter {
+    private stateStore?;
+    private route;
+    private session;
+    private data;
+    private eventBus;
+    private mutationHandler?;
+    private commandHandler?;
+    private apiAllowlist?;
+    private apiMaxResponseBytes;
+    private apiMaxConcurrentCalls;
+    private inFlightApiCalls;
+    constructor(context?: ActionContext);
+    getEventBus(): ReturnType<typeof createEventBus>;
+    execute(action: Action, eventValue?: unknown): void;
+    private executeAction;
+    private executeMutation;
+    private runMutation;
+    private buildMutationRequest;
+    private executeCommand;
+    private runCommand;
+    private buildCommandRequest;
+    private executeApi;
+    private fetchApi;
+    private isApiUrlAllowed;
+    private buildScope;
+}

package/dist/compiler/dashboard.d.ts

@@ -0,0 +1,10 @@
+import { UIDLDocument, UIDLNode } from '../types';
+import { DashboardPageMeta, HostCapabilities, RoutePolicy, UiPolicy } from './types.js';
+export interface CompileDashboardOptions {
+    hostCapabilities: HostCapabilities;
+    uiPolicy?: UiPolicy;
+    routePolicy?: RoutePolicy;
+    docId?: string;
+    extraHeaderActions?: UIDLNode[];
+}
+export declare function compileDashboardPage(meta: DashboardPageMeta, options: CompileDashboardOptions): UIDLDocument;

package/dist/compiler/form.d.ts

@@ -0,0 +1,22 @@
+import { UIDLDocument, UIDLNode } from '../types';
+import { FormPageMeta, HostCapabilities, RoutePolicy, UiPolicy } from './types.js';
+export interface CompileFormOptions {
+    hostCapabilities: HostCapabilities;
+    uiPolicy?: UiPolicy;
+    routePolicy?: RoutePolicy;
+    docId?: string;
+    listRoute?: string;
+    initialData?: Record<string, unknown>;
+    initialVersion?: number;
+    extraHeaderActions?: UIDLNode[];
+    extraFormActions?: UIDLNode[];
+    useFullWidth?: boolean;
+}
+/**
+ * TwoColumnForm prints a field's label in the row's start column, so the control must not
+ * print it again — but a control with no name of its own reaches assistive tech as an unnamed
+ * input, which is what axe reports as `label` / `select-name`. Naming it the way the static
+ * Meridian documents do (`aria-label`, see templates' `formControlNode`) satisfies both.
+ */
+export declare function nameControl(control: UIDLNode, label: string): UIDLNode;
+export declare function compileFormPage(meta: FormPageMeta, recordId: string, options: CompileFormOptions): UIDLDocument;

package/dist/compiler/index.d.ts

@@ -0,0 +1,16 @@
+export { PAGE_RECIPES, isPageRecipe, validateHostCapabilities, semanticNodeId, semanticListNodeIds, } from './types.js';
+export { compileListPage, parseListQueryParams, serializeListQueryParams, } from './list.js';
+export type { CompileListOptions } from './list.js';
+export { compileFormPage } from './form.js';
+export type { CompileFormOptions } from './form.js';
+export { compileReportPage } from './report.js';
+export type { CompileReportOptions } from './report.js';
+export { compileDashboardPage } from './dashboard.js';
+export type { CompileDashboardOptions } from './dashboard.js';
+export { compileSettingsPage } from './settings.js';
+export type { CompileSettingsOptions } from './settings.js';
+export { compileTreePage } from './tree.js';
+export type { CompileTreeOptions } from './tree.js';
+export { compileWizardPage } from './wizard.js';
+export type { CompileWizardOptions } from './wizard.js';
+export type { PageRecipe, LocalizedText, FieldWidget, FieldOption, FieldMeta, ListColumn, ListFilter, ListSummary, ListPageMeta, StateTransition, DocumentStates, ChildTableRef, FormPageMeta, ReportColumn, ReportFilter, ReportPageMeta, DashboardKpi, DashboardChart, DashboardShortcut, DashboardPageMeta, SettingsField, SettingsSection, SettingsPageMeta, TreeNode, TreePageMeta, WizardStep, WizardPageMeta, RecipeMetaMap, HostCapabilities, UiPolicy, RoutePolicy, ResponsivePolicy, CompilePageInput, CompilePageInputFor, CompilePageResult, PageCompiler, CapabilityIssue, } from './types.js';

package/dist/compiler/list.d.ts

@@ -0,0 +1,20 @@
+import { UIDLDocument, UIDLNode } from '../types';
+import { HostCapabilities, ListPageMeta, RoutePolicy, UiPolicy } from './types.js';
+export interface CompileListOptions {
+    hostCapabilities: HostCapabilities;
+    uiPolicy?: UiPolicy;
+    routePolicy?: RoutePolicy;
+    docId?: string;
+    initialState?: Record<string, unknown>;
+    rowActions?: Array<{
+        label: string;
+        event?: string;
+    }>;
+    createNewActions?: Array<Record<string, unknown>>;
+    rowOpenActions?: Array<Record<string, unknown>>;
+    extraHeaderActions?: UIDLNode[];
+    extraFilterActions?: UIDLNode[];
+}
+export declare function compileListPage(meta: ListPageMeta, options: CompileListOptions): UIDLDocument;
+export declare function parseListQueryParams(searchParams: URLSearchParams | string, meta: ListPageMeta): Record<string, unknown>;
+export declare function serializeListQueryParams(state: Record<string, unknown>, meta: ListPageMeta): URLSearchParams;

package/dist/compiler/report.d.ts

@@ -0,0 +1,10 @@
+import { UIDLDocument, UIDLNode } from '../types';
+import { HostCapabilities, ReportPageMeta, RoutePolicy, UiPolicy } from './types.js';
+export interface CompileReportOptions {
+    hostCapabilities: HostCapabilities;
+    uiPolicy?: UiPolicy;
+    routePolicy?: RoutePolicy;
+    docId?: string;
+    extraHeaderActions?: UIDLNode[];
+}
+export declare function compileReportPage(meta: ReportPageMeta, options: CompileReportOptions): UIDLDocument;

package/dist/compiler/settings.d.ts

@@ -0,0 +1,10 @@
+import { UIDLDocument, UIDLNode } from '../types';
+import { HostCapabilities, RoutePolicy, SettingsPageMeta, UiPolicy } from './types.js';
+export interface CompileSettingsOptions {
+    hostCapabilities: HostCapabilities;
+    uiPolicy?: UiPolicy;
+    routePolicy?: RoutePolicy;
+    docId?: string;
+    extraHeaderActions?: UIDLNode[];
+}
+export declare function compileSettingsPage(meta: SettingsPageMeta, options: CompileSettingsOptions): UIDLDocument;

package/dist/compiler/tree.d.ts

@@ -0,0 +1,10 @@
+import { UIDLDocument, UIDLNode } from '../types';
+import { HostCapabilities, RoutePolicy, TreePageMeta, UiPolicy } from './types.js';
+export interface CompileTreeOptions {
+    hostCapabilities: HostCapabilities;
+    uiPolicy?: UiPolicy;
+    routePolicy?: RoutePolicy;
+    docId?: string;
+    extraHeaderActions?: UIDLNode[];
+}
+export declare function compileTreePage(meta: TreePageMeta, options: CompileTreeOptions): UIDLDocument;