@volter/world-ui 0.1.37 → 1.0.1

package/dist/client/kit.css

@@ -1,55 +0,0 @@
-/* The twin UI kit's base: layout and pieces. A pack's own stylesheet is its skin: it sets the
-   variables below (and anything else of the vendor's look) and is loaded after this one. Unskinned,
-   the kit wears the Volter brand's roles (company decision 0018): the shell links the brand's tokens
-   (assets/brand/tokens.css, fetched at build) before this sheet, and the pre-commit hook refuses a
-   literal colour here. */
-:root {
-  --tw-accent: var(--volter-action-default);
-  --tw-bg: var(--volter-surface-page);
-  --tw-nav-bg: var(--volter-surface-subtle);
-  --tw-text: var(--volter-text-primary);
-  --tw-muted: var(--volter-text-muted);
-  --tw-border: var(--volter-border-default);
-  --tw-ok: var(--volter-status-healthy-text);
-  --tw-warn: var(--volter-status-attention-text);
-  --tw-bad: var(--volter-status-danger-text);
-  --tw-font: var(--volter-font-ui);
-}
-* { box-sizing: border-box; }
-body { margin: 0; font-family: var(--tw-font); color: var(--tw-text); background: var(--tw-bg); }
-button { font: inherit; }
-.tw-app { display: grid; grid-template-columns: 240px 1fr; min-height: 100vh; }
-.tw-nav { background: var(--tw-nav-bg); border-right: 1px solid var(--tw-border); padding: 12px 8px; display: flex; flex-direction: column; gap: 2px; overflow-y: auto; }
-.tw-nav button { text-align: left; background: none; border: 0; padding: 6px 10px; border-radius: 6px; color: var(--tw-text); cursor: pointer; display: flex; justify-content: space-between; }
-.tw-nav button:hover { background: var(--volter-overlay-hover); }
-.tw-nav .tw-on, .tw-nav .tw-on:hover { background: var(--tw-accent); color: var(--volter-text-on-strong); }
-.tw-brand { font-weight: 700; font-size: 16px; margin-bottom: 8px; flex-direction: column; }
-.tw-brand small { font-weight: 400; color: var(--tw-muted); font-size: 12px; }
-.tw-count { color: var(--tw-muted); font-size: 12px; margin-left: 8px; }
-.tw-main { padding: 20px 28px; overflow: auto; }
-.tw-main h1 { font-size: 20px; display: flex; align-items: center; gap: 8px; }
-.tw-list { list-style: none; padding: 0; margin: 0; border: 1px solid var(--tw-border); border-radius: 6px; }
-.tw-list li + li { border-top: 1px solid var(--tw-border); }
-.tw-list button { width: 100%; background: none; border: 0; padding: 10px 14px; display: grid; grid-template-columns: 1fr 1fr auto; gap: 12px; text-align: left; cursor: pointer; }
-.tw-list button:hover { background: var(--tw-nav-bg); }
-.tw-list span { color: var(--tw-muted); }
-.tw-empty { padding: 12px 14px; color: var(--tw-muted); }
-.tw-pill { font-size: 12px; padding: 1px 8px; border-radius: 10px; border: 1px solid currentColor; white-space: nowrap; }
-.tw-pill-ok { color: var(--tw-ok); }
-.tw-pill-warn { color: var(--tw-warn); }
-.tw-pill-bad { color: var(--tw-bad); }
-.tw-pill-muted { color: var(--tw-muted); }
-.tw-ref { font: inherit; font-size: 13px; background: none; border: 1px solid var(--tw-border); border-radius: 4px; padding: 0 6px; color: var(--tw-accent); cursor: pointer; }
-.tw-fields { margin: 12px 0; }
-.tw-field { display: grid; grid-template-columns: 220px 1fr; gap: 12px; padding: 3px 0; border-bottom: 1px dashed var(--tw-border); }
-.tw-field dt { color: var(--tw-muted); }
-.tw-field dd { margin: 0; word-break: break-all; }
-.tw-actions { display: flex; gap: 8px; flex-wrap: wrap; margin: 8px 0; }
-.tw-actions button, .tw-create button { background: var(--tw-accent); color: var(--volter-text-on-strong); border: 0; border-radius: 6px; padding: 6px 12px; cursor: pointer; text-transform: capitalize; }
-.tw-create { display: flex; gap: 8px; flex-wrap: wrap; align-items: end; margin-bottom: 12px; }
-.tw-create label { display: flex; flex-direction: column; font-size: 12px; color: var(--tw-muted); }
-.tw-create input { border: 1px solid var(--tw-border); border-radius: 6px; padding: 5px 8px; font: inherit; }
-.tw-back { background: none; border: 0; color: var(--tw-accent); cursor: pointer; padding: 0; }
-.tw-error { color: var(--tw-bad); width: 100%; }
-.tw-home ul { list-style: none; padding: 0; display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 8px; }
-.tw-home button { width: 100%; text-align: left; background: var(--tw-nav-bg); border: 1px solid var(--tw-border); border-radius: 6px; padding: 12px; cursor: pointer; }

package/dist/client/kit.d.ts

@@ -1,101 +0,0 @@
-import React, { type ReactNode } from 'react';
-export type Row = Record<string, any>;
-export type UiAction = {
-    operation: string;
-    method: string;
-    path: string;
-    field: string;
-    from: string[] | '*';
-    to?: string;
-};
-export type UiResource = {
-    list?: string;
-    retrieve?: string;
-    create?: {
-        path: string;
-        encoding: string;
-        body: Array<{
-            name: string;
-            type: string;
-            required: boolean;
-        }>;
-    };
-    actions: UiAction[];
-    states: Record<string, string[]>;
-    embeds: Record<string, string>;
-};
-export type UiData = {
-    resources: Record<string, UiResource>;
-};
-/** One entry of the navigation: a resource's list, titled the vendor's way. */
-export type Section = {
-    resource: string;
-    label: string;
-    /** where it is listed, when not the resource's own list (a sub-collection) */
-    list?: string;
-    title?: (row: Row) => string;
-    subtitle?: (row: Row) => string;
-    /** what the vendor's detail page shows beyond the fields (a balance panel, an error banner) */
-    extras?: (row: Row) => ReactNode;
-};
-/** A screen of the vendor's UI that is not a resource view (a chat, a board, a canvas). */
-export type Screen = {
-    key: string;
-    label: string;
-    render: (api: Api) => ReactNode;
-};
-export type TwinUiConfig = {
-    skin: {
-        name: string;
-        product?: string;
-    };
-    ui: UiData;
-    sections: Section[];
-    screens?: Screen[];
-    /** headers every call carries (the fake credential the vendor's API asks for) */
-    headers?: Record<string, string>;
-    /** how the vendor's lists hold their rows: `data` (Stripe, OpenAI), the whole body (GitHub), or a key */
-    rowsAt?: (body: any, resource: string) => Row[];
-    /** a value's tone for its status pill */
-    tone?: (value: string) => 'ok' | 'warn' | 'bad' | 'muted';
-};
-export type Api = {
-    get: (path: string) => Promise<any>;
-    send: (method: string, path: string, body?: Record<string, unknown>, encoding?: string) => Promise<{
-        status: number;
-        body: any;
-    }>;
-};
-export declare function makeApi(headers?: Record<string, string>): Api;
-export declare function StatusPill({ value, tone }: {
-    value: unknown;
-    tone?: TwinUiConfig['tone'];
-}): React.JSX.Element | null;
-export declare function RefChip({ label, onJump }: {
-    label: string;
-    onJump: () => void;
-}): React.JSX.Element;
-/** An object as the vendor's detail page lists it: one line per field, nested objects indented, references as chips. */
-export declare function Fields({ row, embeds, onJump }: {
-    row: Row;
-    embeds: Record<string, string>;
-    onJump: (resource: string, id: string) => void;
-}): React.JSX.Element;
-/** The moves the resource's machine allows from where this row stands, as buttons. */
-export declare function Actions({ resource, row, api, onDone }: {
-    resource: UiResource;
-    row: Row;
-    api: Api;
-    onDone: () => void;
-}): React.JSX.Element | null;
-/** A form for the resource's create operation: its required parameters, and any others the caller fills. */
-export declare function CreateForm({ resource, api, onCreated }: {
-    resource: UiResource;
-    api: Api;
-    onCreated: (row: Row) => void;
-}): React.JSX.Element | null;
-export declare function TwinUi({ config }: {
-    config: TwinUiConfig;
-}): React.JSX.Element;
-/** Mount a pack's UI into the shell's #root. */
-export declare function mountTwinUi(config: TwinUiConfig): void;

package/dist/client/kit.js

@@ -1,160 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-// THE TWIN UI KIT — shared pieces for a derived pack's screens (docs/contributing/architecture.md,
-// "Screens"): the shell and navigation, lists and details, references, state pills, the moves a machine
-// allows from a row's state, and create forms, all through the vendor's own API. A pack builds the
-// screens people work in from these under its skin. It is not a vendor's UI on its own: TwinUi's
-// generic resource browser renders any declared resource and so answers what a World holds, which a
-// vendor's screens never pose as.
-import { useCallback, useEffect, useMemo, useState } from 'react';
-import { createRoot } from 'react-dom/client';
-// ── talking to the vendor's API ────────────────────────────────────────────────────────────
-const BASE = typeof document === 'undefined' || document.querySelector('base[href]') === null ? '' : new URL('.', document.baseURI).pathname.replace(/\/$/, '');
-function formEncode(value, prefix, out) {
-    if (value === undefined || value === '')
-        return;
-    if (value && typeof value === 'object') {
-        for (const [k, v] of Object.entries(value))
-            formEncode(v, prefix ? `${prefix}[${k}]` : k, out);
-    }
-    else
-        out.append(prefix, String(value));
-}
-export function makeApi(headers = {}) {
-    return {
-        get: (path) => fetch(`${BASE}${path}`, { headers }).then((r) => r.json()),
-        send: async (method, path, body, encoding = 'json') => {
-            const init = { method, headers: { ...headers } };
-            if (body && Object.keys(body).length) {
-                if (encoding === 'form') {
-                    const p = new URLSearchParams();
-                    formEncode(body, '', p);
-                    init.body = p.toString();
-                    init.headers['content-type'] = 'application/x-www-form-urlencoded';
-                }
-                else {
-                    init.body = JSON.stringify(body);
-                    init.headers['content-type'] = 'application/json';
-                }
-            }
-            const r = await fetch(`${BASE}${path}`, init);
-            const text = await r.text();
-            let parsed = text;
-            try {
-                parsed = text ? JSON.parse(text) : null;
-            }
-            catch { /* a non-JSON answer stays text */ }
-            return { status: r.status, body: parsed };
-        },
-    };
-}
-const fill = (path, id) => path.replace(/\{[^}]+\}/, encodeURIComponent(id));
-const defaultRows = (body) => (Array.isArray(body) ? body : Array.isArray(body?.data) ? body.data : []);
-// ── pieces ───────────────────────────────────────────────────────────────────────────────
-export function StatusPill({ value, tone }) {
-    if (value === undefined || value === null || value === '')
-        return null;
-    const t = tone?.(String(value)) ?? (/(succeeded|paid|active|open|completed|ok|true)/.test(String(value)) ? 'ok' : /(fail|canceled|cancelled|void|closed|expired|error|false)/.test(String(value)) ? 'bad' : 'muted');
-    return _jsx("span", { className: `tw-pill tw-pill-${t}`, children: String(value) });
-}
-export function RefChip({ label, onJump }) {
-    return (_jsx("button", { type: "button", className: "tw-ref", onClick: onJump, children: label }));
-}
-/** An object as the vendor's detail page lists it: one line per field, nested objects indented, references as chips. */
-export function Fields({ row, embeds, onJump }) {
-    const lines = [];
-    const walk = (obj, depth, prefix) => {
-        for (const [k, v] of Object.entries(obj)) {
-            const key = prefix ? `${prefix}.${k}` : k;
-            if (v && typeof v === 'object' && !Array.isArray(v)) {
-                lines.push({ key, depth, value: '' });
-                walk(v, depth + 1, key);
-            }
-            else if (depth === 0 && embeds[k] && typeof v === 'string') {
-                lines.push({ key, depth, value: _jsx(RefChip, { label: v, onJump: () => onJump(embeds[k], v) }) });
-            }
-            else
-                lines.push({ key, depth, value: Array.isArray(v) ? JSON.stringify(v) : String(v) });
-        }
-    };
-    walk(row, 0, '');
-    return (_jsx("dl", { className: "tw-fields", children: lines.map((l) => (_jsxs("div", { className: "tw-field", style: { paddingLeft: `${l.depth * 16}px` }, children: [_jsx("dt", { children: l.key.split('.').at(-1) }), _jsx("dd", { children: l.value })] }, l.key))) }));
-}
-/** The moves the resource's machine allows from where this row stands, as buttons. */
-export function Actions({ resource, row, api, onDone }) {
-    const [error, setError] = useState(null);
-    const legal = resource.actions.filter((a) => a.from === '*' || a.from.includes(String(row[a.field])));
-    const seen = new Set();
-    const unique = legal.filter((a) => (seen.has(a.operation) ? false : (seen.add(a.operation), true)));
-    if (!unique.length)
-        return null;
-    return (_jsxs("div", { className: "tw-actions", children: [unique.map((a) => (_jsx("button", { type: "button", onClick: async () => {
-                    setError(null);
-                    const r = await api.send(a.method, fill(a.path, String(row.id)), undefined, resource.create?.encoding);
-                    if (r.status >= 400)
-                        setError(r.body?.error?.message ?? r.body?.message ?? r.body?.error ?? `HTTP ${r.status}`);
-                    onDone();
-                }, children: a.path.split('/').at(-1).replace(/[_-]/g, ' ') }, a.operation))), error ? _jsx("p", { className: "tw-error", children: String(error) }) : null] }));
-}
-/** A form for the resource's create operation: its required parameters, and any others the caller fills. */
-export function CreateForm({ resource, api, onCreated }) {
-    const create = resource.create;
-    const [values, setValues] = useState({});
-    const [error, setError] = useState(null);
-    if (!create)
-        return null;
-    const fields = create.body.filter((b) => b.required || ['name', 'email', 'description', 'title', 'amount', 'currency'].includes(b.name));
-    return (_jsxs("form", { className: "tw-create", onSubmit: async (e) => {
-            e.preventDefault();
-            setError(null);
-            const r = await api.send('POST', create.path, values, create.encoding);
-            if (r.status >= 400)
-                setError(r.body?.error?.message ?? r.body?.message ?? `HTTP ${r.status}`);
-            else
-                onCreated(r.body);
-        }, children: [fields.map((f) => (_jsxs("label", { children: [f.name, f.required ? ' *' : '', _jsx("input", { value: values[f.name] ?? '', onChange: (e) => setValues({ ...values, [f.name]: e.target.value }) })] }, f.name))), _jsx("button", { type: "submit", children: "Create" }), error ? _jsx("p", { className: "tw-error", children: String(error) }) : null] }));
-}
-export function TwinUi({ config }) {
-    const api = useMemo(() => makeApi(config.headers), [config.headers]);
-    const [route, setRoute] = useState({ kind: 'home' });
-    const [rows, setRows] = useState([]);
-    const [detail, setDetail] = useState(null);
-    const [counts, setCounts] = useState({});
-    const [tick, setTick] = useState(0);
-    const rowsOf = config.rowsAt ?? defaultRows;
-    const listPath = (s) => s.list ?? config.ui.resources[s.resource]?.list;
-    const bySection = (resource) => config.sections.find((s) => s.resource === resource);
-    useEffect(() => {
-        for (const s of config.sections) {
-            const p = listPath(s);
-            if (p && !p.includes('{'))
-                api.get(p).then((b) => setCounts((c) => ({ ...c, [s.label]: rowsOf(b, s.resource).length }))).catch(() => undefined);
-        }
-    }, [tick]);
-    useEffect(() => {
-        if (route.kind === 'list') {
-            const p = listPath(route.section);
-            if (p)
-                api.get(p).then((b) => setRows(rowsOf(b, route.section.resource))).catch(() => setRows([]));
-        }
-        if (route.kind === 'detail') {
-            const r = config.ui.resources[route.section.resource];
-            const fromList = rows.find((x) => String(x.id) === route.id) ?? null;
-            if (r?.retrieve && (r.retrieve.match(/\{/g) ?? []).length === 1)
-                api.get(fill(r.retrieve, route.id)).then(setDetail).catch(() => setDetail(fromList));
-            else
-                setDetail(fromList);
-        }
-    }, [route, tick]);
-    const jump = useCallback((resource, id) => {
-        const s = bySection(resource);
-        if (s)
-            setRoute({ kind: 'detail', section: s, id });
-    }, []);
-    return (_jsxs("div", { className: "tw-app", children: [_jsxs("nav", { className: "tw-nav", children: [_jsxs("button", { type: "button", className: "tw-brand", onClick: () => setRoute({ kind: 'home' }), children: [config.skin.name, config.skin.product ? _jsx("small", { children: config.skin.product }) : null] }), (config.screens ?? []).map((s) => (_jsx("button", { type: "button", className: route.kind === 'screen' && route.screen.key === s.key ? 'tw-on' : '', onClick: () => setRoute({ kind: 'screen', screen: s }), children: s.label }, s.key))), config.sections.map((s) => (_jsxs("button", { type: "button", className: route.kind !== 'home' && route.kind !== 'screen' && route.section.label === s.label ? 'tw-on' : '', onClick: () => setRoute({ kind: 'list', section: s }), children: [s.label, counts[s.label] !== undefined ? _jsx("span", { className: "tw-count", children: counts[s.label] }) : null] }, s.label)))] }), _jsxs("main", { className: "tw-main", children: [route.kind === 'home' ? (_jsxs("section", { className: "tw-home", children: [_jsx("h1", { children: config.skin.name }), _jsx("ul", { children: config.sections.map((s) => (_jsx("li", { children: _jsxs("button", { type: "button", onClick: () => setRoute({ kind: 'list', section: s }), children: [s.label, " ", _jsx("span", { className: "tw-count", children: counts[s.label] ?? '…' })] }) }, s.label))) })] })) : null, route.kind === 'screen' ? route.screen.render(api) : null, route.kind === 'list' ? (_jsxs("section", { children: [_jsx("h1", { children: route.section.label }), config.ui.resources[route.section.resource] ? _jsx(CreateForm, { resource: config.ui.resources[route.section.resource], api: api, onCreated: () => setTick((t) => t + 1) }) : null, _jsxs("ul", { className: "tw-list", children: [rows.map((r) => (_jsx("li", { children: _jsxs("button", { type: "button", onClick: () => setRoute({ kind: 'detail', section: route.section, id: String(r.id) }), children: [_jsx("strong", { children: route.section.title?.(r) ?? String(r.name ?? r.title ?? r.id) }), _jsx("span", { children: route.section.subtitle?.(r) ?? String(r.id) }), _jsx(StatusPill, { value: r.status ?? r.state, tone: config.tone })] }) }, String(r.id)))), rows.length === 0 ? _jsx("li", { className: "tw-empty", children: "None yet." }) : null] })] })) : null, route.kind === 'detail' && detail ? (_jsxs("section", { children: [_jsxs("button", { type: "button", className: "tw-back", onClick: () => setRoute({ kind: 'list', section: route.section }), children: ["\u2190 ", route.section.label] }), _jsxs("h1", { children: [route.section.title?.(detail) ?? String(detail.name ?? detail.title ?? detail.id), " ", _jsx(StatusPill, { value: detail.status ?? detail.state, tone: config.tone })] }), route.section.extras?.(detail), config.ui.resources[route.section.resource] ? _jsx(Actions, { resource: config.ui.resources[route.section.resource], row: detail, api: api, onDone: () => setTick((t) => t + 1) }) : null, _jsx(Fields, { row: detail, embeds: config.ui.resources[route.section.resource]?.embeds ?? {}, onJump: jump })] })) : null] })] }));
-}
-/** Mount a pack's UI into the shell's #root. */
-export function mountTwinUi(config) {
-    if (typeof document === 'undefined')
-        return;
-    createRoot(document.getElementById('root')).render(_jsx(TwinUi, { config: config }));
-}

package/dist/client/kit.tsx

@@ -1,312 +0,0 @@
-// THE TWIN UI KIT — shared pieces for a derived pack's screens (docs/contributing/architecture.md,
-// "Screens"): the shell and navigation, lists and details, references, state pills, the moves a machine
-// allows from a row's state, and create forms, all through the vendor's own API. A pack builds the
-// screens people work in from these under its skin. It is not a vendor's UI on its own: TwinUi's
-// generic resource browser renders any declared resource and so answers what a World holds, which a
-// vendor's screens never pose as.
-import React, { useCallback, useEffect, useMemo, useState, type ReactNode } from 'react';
-import { createRoot } from 'react-dom/client';
-
-export type Row = Record<string, any>;
-
-export type UiAction = { operation: string; method: string; path: string; field: string; from: string[] | '*'; to?: string };
-export type UiResource = {
-  list?: string;
-  retrieve?: string;
-  create?: { path: string; encoding: string; body: Array<{ name: string; type: string; required: boolean }> };
-  actions: UiAction[];
-  states: Record<string, string[]>;
-  embeds: Record<string, string>;
-};
-export type UiData = { resources: Record<string, UiResource> };
-
-/** One entry of the navigation: a resource's list, titled the vendor's way. */
-export type Section = {
-  resource: string;
-  label: string;
-  /** where it is listed, when not the resource's own list (a sub-collection) */
-  list?: string;
-  title?: (row: Row) => string;
-  subtitle?: (row: Row) => string;
-  /** what the vendor's detail page shows beyond the fields (a balance panel, an error banner) */
-  extras?: (row: Row) => ReactNode;
-};
-
-/** A screen of the vendor's UI that is not a resource view (a chat, a board, a canvas). */
-export type Screen = { key: string; label: string; render: (api: Api) => ReactNode };
-
-export type TwinUiConfig = {
-  skin: { name: string; product?: string };
-  ui: UiData;
-  sections: Section[];
-  screens?: Screen[];
-  /** headers every call carries (the fake credential the vendor's API asks for) */
-  headers?: Record<string, string>;
-  /** how the vendor's lists hold their rows: `data` (Stripe, OpenAI), the whole body (GitHub), or a key */
-  rowsAt?: (body: any, resource: string) => Row[];
-  /** a value's tone for its status pill */
-  tone?: (value: string) => 'ok' | 'warn' | 'bad' | 'muted';
-};
-
-// ── talking to the vendor's API ────────────────────────────────────────────────────────────
-
-const BASE = typeof document === 'undefined' || document.querySelector('base[href]') === null ? '' : new URL('.', document.baseURI).pathname.replace(/\/$/, '');
-
-export type Api = {
-  get: (path: string) => Promise<any>;
-  send: (method: string, path: string, body?: Record<string, unknown>, encoding?: string) => Promise<{ status: number; body: any }>;
-};
-
-function formEncode(value: unknown, prefix: string, out: URLSearchParams): void {
-  if (value === undefined || value === '') return;
-  if (value && typeof value === 'object') {
-    for (const [k, v] of Object.entries(value as Record<string, unknown>)) formEncode(v, prefix ? `${prefix}[${k}]` : k, out);
-  } else out.append(prefix, String(value));
-}
-
-export function makeApi(headers: Record<string, string> = {}): Api {
-  return {
-    get: (path) => fetch(`${BASE}${path}`, { headers }).then((r) => r.json()),
-    send: async (method, path, body, encoding = 'json') => {
-      const init: RequestInit = { method, headers: { ...headers } };
-      if (body && Object.keys(body).length) {
-        if (encoding === 'form') {
-          const p = new URLSearchParams();
-          formEncode(body, '', p);
-          init.body = p.toString();
-          (init.headers as Record<string, string>)['content-type'] = 'application/x-www-form-urlencoded';
-        } else {
-          init.body = JSON.stringify(body);
-          (init.headers as Record<string, string>)['content-type'] = 'application/json';
-        }
-      }
-      const r = await fetch(`${BASE}${path}`, init);
-      const text = await r.text();
-      let parsed: any = text;
-      try { parsed = text ? JSON.parse(text) : null; } catch { /* a non-JSON answer stays text */ }
-      return { status: r.status, body: parsed };
-    },
-  };
-}
-
-const fill = (path: string, id: string): string => path.replace(/\{[^}]+\}/, encodeURIComponent(id));
-const defaultRows = (body: any): Row[] => (Array.isArray(body) ? body : Array.isArray(body?.data) ? body.data : []);
-
-// ── pieces ───────────────────────────────────────────────────────────────────────────────
-
-export function StatusPill({ value, tone }: { value: unknown; tone?: TwinUiConfig['tone'] }) {
-  if (value === undefined || value === null || value === '') return null;
-  const t = tone?.(String(value)) ?? (/(succeeded|paid|active|open|completed|ok|true)/.test(String(value)) ? 'ok' : /(fail|canceled|cancelled|void|closed|expired|error|false)/.test(String(value)) ? 'bad' : 'muted');
-  return <span className={`tw-pill tw-pill-${t}`}>{String(value)}</span>;
-}
-
-export function RefChip({ label, onJump }: { label: string; onJump: () => void }) {
-  return (
-    <button type="button" className="tw-ref" onClick={onJump}>
-      {label}
-    </button>
-  );
-}
-
-/** An object as the vendor's detail page lists it: one line per field, nested objects indented, references as chips. */
-export function Fields({ row, embeds, onJump }: { row: Row; embeds: Record<string, string>; onJump: (resource: string, id: string) => void }) {
-  const lines: Array<{ key: string; depth: number; value: ReactNode }> = [];
-  const walk = (obj: Row, depth: number, prefix: string) => {
-    for (const [k, v] of Object.entries(obj)) {
-      const key = prefix ? `${prefix}.${k}` : k;
-      if (v && typeof v === 'object' && !Array.isArray(v)) {
-        lines.push({ key, depth, value: '' });
-        walk(v, depth + 1, key);
-      } else if (depth === 0 && embeds[k] && typeof v === 'string') {
-        lines.push({ key, depth, value: <RefChip label={v} onJump={() => onJump(embeds[k]!, v)} /> });
-      } else lines.push({ key, depth, value: Array.isArray(v) ? JSON.stringify(v) : String(v) });
-    }
-  };
-  walk(row, 0, '');
-  return (
-    <dl className="tw-fields">
-      {lines.map((l) => (
-        <div key={l.key} className="tw-field" style={{ paddingLeft: `${l.depth * 16}px` }}>
-          <dt>{l.key.split('.').at(-1)}</dt>
-          <dd>{l.value}</dd>
-        </div>
-      ))}
-    </dl>
-  );
-}
-
-/** The moves the resource's machine allows from where this row stands, as buttons. */
-export function Actions({ resource, row, api, onDone }: { resource: UiResource; row: Row; api: Api; onDone: () => void }) {
-  const [error, setError] = useState<string | null>(null);
-  const legal = resource.actions.filter((a) => a.from === '*' || a.from.includes(String(row[a.field])));
-  const seen = new Set<string>();
-  const unique = legal.filter((a) => (seen.has(a.operation) ? false : (seen.add(a.operation), true)));
-  if (!unique.length) return null;
-  return (
-    <div className="tw-actions">
-      {unique.map((a) => (
-        <button
-          key={a.operation}
-          type="button"
-          onClick={async () => {
-            setError(null);
-            const r = await api.send(a.method, fill(a.path, String(row.id)), undefined, resource.create?.encoding);
-            if (r.status >= 400) setError(r.body?.error?.message ?? r.body?.message ?? r.body?.error ?? `HTTP ${r.status}`);
-            onDone();
-          }}
-        >
-          {a.path.split('/').at(-1)!.replace(/[_-]/g, ' ')}
-        </button>
-      ))}
-      {error ? <p className="tw-error">{String(error)}</p> : null}
-    </div>
-  );
-}
-
-/** A form for the resource's create operation: its required parameters, and any others the caller fills. */
-export function CreateForm({ resource, api, onCreated }: { resource: UiResource; api: Api; onCreated: (row: Row) => void }) {
-  const create = resource.create;
-  const [values, setValues] = useState<Record<string, string>>({});
-  const [error, setError] = useState<string | null>(null);
-  if (!create) return null;
-  const fields = create.body.filter((b) => b.required || ['name', 'email', 'description', 'title', 'amount', 'currency'].includes(b.name));
-  return (
-    <form
-      className="tw-create"
-      onSubmit={async (e) => {
-        e.preventDefault();
-        setError(null);
-        const r = await api.send('POST', create.path, values, create.encoding);
-        if (r.status >= 400) setError(r.body?.error?.message ?? r.body?.message ?? `HTTP ${r.status}`);
-        else onCreated(r.body);
-      }}
-    >
-      {fields.map((f) => (
-        <label key={f.name}>
-          {f.name}
-          {f.required ? ' *' : ''}
-          <input value={values[f.name] ?? ''} onChange={(e) => setValues({ ...values, [f.name]: e.target.value })} />
-        </label>
-      ))}
-      <button type="submit">Create</button>
-      {error ? <p className="tw-error">{String(error)}</p> : null}
-    </form>
-  );
-}
-
-// ── the app ──────────────────────────────────────────────────────────────────────────────
-
-type Route = { kind: 'home' } | { kind: 'list'; section: Section } | { kind: 'detail'; section: Section; id: string } | { kind: 'screen'; screen: Screen };
-
-export function TwinUi({ config }: { config: TwinUiConfig }) {
-  const api = useMemo(() => makeApi(config.headers), [config.headers]);
-  const [route, setRoute] = useState<Route>({ kind: 'home' });
-  const [rows, setRows] = useState<Row[]>([]);
-  const [detail, setDetail] = useState<Row | null>(null);
-  const [counts, setCounts] = useState<Record<string, number>>({});
-  const [tick, setTick] = useState(0);
-  const rowsOf = config.rowsAt ?? defaultRows;
-  const listPath = (s: Section) => s.list ?? config.ui.resources[s.resource]?.list;
-  const bySection = (resource: string) => config.sections.find((s) => s.resource === resource);
-
-  useEffect(() => {
-    for (const s of config.sections) {
-      const p = listPath(s);
-      if (p && !p.includes('{')) api.get(p).then((b) => setCounts((c) => ({ ...c, [s.label]: rowsOf(b, s.resource).length }))).catch(() => undefined);
-    }
-  }, [tick]);
-
-  useEffect(() => {
-    if (route.kind === 'list') {
-      const p = listPath(route.section);
-      if (p) api.get(p).then((b) => setRows(rowsOf(b, route.section.resource))).catch(() => setRows([]));
-    }
-    if (route.kind === 'detail') {
-      const r = config.ui.resources[route.section.resource];
-      const fromList = rows.find((x) => String(x.id) === route.id) ?? null;
-      if (r?.retrieve && (r.retrieve.match(/\{/g) ?? []).length === 1) api.get(fill(r.retrieve, route.id)).then(setDetail).catch(() => setDetail(fromList));
-      else setDetail(fromList);
-    }
-  }, [route, tick]);
-
-  const jump = useCallback((resource: string, id: string) => {
-    const s = bySection(resource);
-    if (s) setRoute({ kind: 'detail', section: s, id });
-  }, []);
-
-  return (
-    <div className="tw-app">
-      <nav className="tw-nav">
-        <button type="button" className="tw-brand" onClick={() => setRoute({ kind: 'home' })}>
-          {config.skin.name}
-          {config.skin.product ? <small>{config.skin.product}</small> : null}
-        </button>
-        {(config.screens ?? []).map((s) => (
-          <button key={s.key} type="button" className={route.kind === 'screen' && route.screen.key === s.key ? 'tw-on' : ''} onClick={() => setRoute({ kind: 'screen', screen: s })}>
-            {s.label}
-          </button>
-        ))}
-        {config.sections.map((s) => (
-          <button key={s.label} type="button" className={route.kind !== 'home' && route.kind !== 'screen' && route.section.label === s.label ? 'tw-on' : ''} onClick={() => setRoute({ kind: 'list', section: s })}>
-            {s.label}
-            {counts[s.label] !== undefined ? <span className="tw-count">{counts[s.label]}</span> : null}
-          </button>
-        ))}
-      </nav>
-      <main className="tw-main">
-        {route.kind === 'home' ? (
-          <section className="tw-home">
-            <h1>{config.skin.name}</h1>
-            <ul>
-              {config.sections.map((s) => (
-                <li key={s.label}>
-                  <button type="button" onClick={() => setRoute({ kind: 'list', section: s })}>
-                    {s.label} <span className="tw-count">{counts[s.label] ?? '…'}</span>
-                  </button>
-                </li>
-              ))}
-            </ul>
-          </section>
-        ) : null}
-        {route.kind === 'screen' ? route.screen.render(api) : null}
-        {route.kind === 'list' ? (
-          <section>
-            <h1>{route.section.label}</h1>
-            {config.ui.resources[route.section.resource] ? <CreateForm resource={config.ui.resources[route.section.resource]!} api={api} onCreated={() => setTick((t) => t + 1)} /> : null}
-            <ul className="tw-list">
-              {rows.map((r) => (
-                <li key={String(r.id)}>
-                  <button type="button" onClick={() => setRoute({ kind: 'detail', section: route.section, id: String(r.id) })}>
-                    <strong>{route.section.title?.(r) ?? String(r.name ?? r.title ?? r.id)}</strong>
-                    <span>{route.section.subtitle?.(r) ?? String(r.id)}</span>
-                    <StatusPill value={r.status ?? r.state} tone={config.tone} />
-                  </button>
-                </li>
-              ))}
-              {rows.length === 0 ? <li className="tw-empty">None yet.</li> : null}
-            </ul>
-          </section>
-        ) : null}
-        {route.kind === 'detail' && detail ? (
-          <section>
-            <button type="button" className="tw-back" onClick={() => setRoute({ kind: 'list', section: route.section })}>
-              ← {route.section.label}
-            </button>
-            <h1>
-              {route.section.title?.(detail) ?? String(detail.name ?? detail.title ?? detail.id)} <StatusPill value={detail.status ?? detail.state} tone={config.tone} />
-            </h1>
-            {route.section.extras?.(detail)}
-            {config.ui.resources[route.section.resource] ? <Actions resource={config.ui.resources[route.section.resource]!} row={detail} api={api} onDone={() => setTick((t) => t + 1)} /> : null}
-            <Fields row={detail} embeds={config.ui.resources[route.section.resource]?.embeds ?? {}} onJump={jump} />
-          </section>
-        ) : null}
-      </main>
-    </div>
-  );
-}
-
-/** Mount a pack's UI into the shell's #root. */
-export function mountTwinUi(config: TwinUiConfig): void {
-  if (typeof document === 'undefined') return;
-  createRoot(document.getElementById('root')!).render(<TwinUi config={config} />);
-}