mockpit 0.0.0-stage → 1.1.0

package/dist/server/kits.js

@@ -0,0 +1,279 @@
+// Opt-in style/behavior bundles for html surfaces. An html surface may list kit ids
+// in its `kits` field; renderHtmlPage concatenates each requested kit's CSS
+// (and JS) into the sandboxed document AFTER the base KIT_CSS. A default html
+// surface (no `kits`) is untouched — the richer vocabulary only ships when asked
+// for, so kits never homogenize freeform html. Kits are a library you import
+// per surface, not a frame every surface is locked into.
+//
+// Runtime-agnostic (no node imports): imported by surfacePage (server render),
+// postSurfaces (id allowlist), and surfaced over HTTP/MCP for discovery. Every
+// class resolves against the theme `--color-*` / `--font-*` / radius tokens, so
+// kit output re-themes with the workspace like any other html surface.
+import { checkCdnUrl } from "./cdn.js";
+// Layout + text helpers shared by every kit — injected ONCE whenever any kit is
+// requested, so kit-specific css below only declares its distinctive classes.
+// Exported so surfacePage.ts can publish it as its own content-hashed
+// stylesheet instead of inlining it into every surface document.
+export const CORE_CSS = `
+.stack{display:flex;flex-direction:column;gap:8px}.stack.sm{gap:4px}.stack.lg{gap:16px}
+.row{display:flex;align-items:center;gap:8px;flex-wrap:wrap}.row.sm{gap:4px}
+.between{display:flex;align-items:center;justify-content:space-between;gap:12px}
+.grow{flex:1;min-width:0}
+.title{font:500 15px/1.35 var(--font-sans);color:var(--color-text-primary)}
+.dim{color:var(--color-text-secondary)}.faint{color:var(--color-text-tertiary)}
+.mono{font-family:var(--font-mono)}.num{font-variant-numeric:tabular-nums}
+.hr{height:1px;border:0;margin:2px 0;background:var(--color-border-secondary)}
+.kbd{font:400 12px/1 var(--font-mono);padding:2px 6px;border:1px solid var(--color-border-secondary);border-bottom-width:2px;border-radius:6px;background:var(--color-background-secondary);color:var(--color-text-secondary)}
+`;
+// issues: cards, status badges/dots, mono ref chips, rollup bars, and a nesting
+// rail (.tree → nest another .tree to indent). Composes an issue/PR/CI tree,
+// a status board, or a PR summary from generic primitives.
+const ISSUES_CSS = `
+.card{background:var(--color-background-primary);border:1px solid var(--color-border-secondary);border-radius:var(--border-radius-lg);padding:14px 16px}
+.card.soft{background:var(--color-background-secondary)}
+.badge{display:inline-flex;align-items:center;gap:5px;font:500 12px/1.4 var(--font-sans);padding:2px 9px;border-radius:999px;background:var(--color-background-secondary);color:var(--color-text-secondary)}
+.badge.ok{background:var(--color-background-success);color:var(--color-text-success)}
+.badge.info{background:var(--color-background-info);color:var(--color-text-info)}
+.badge.warn{background:var(--color-background-warning);color:var(--color-text-warning)}
+.badge.danger{background:var(--color-background-danger);color:var(--color-text-danger)}
+.chip{display:inline-flex;align-items:center;gap:4px;font:400 12px/1.4 var(--font-mono);padding:1px 7px;border-radius:var(--border-radius-md);border:1px solid var(--color-border-secondary);color:var(--color-text-secondary)}
+.dot{width:8px;height:8px;border-radius:999px;background:var(--color-text-tertiary);flex:none}
+.dot.ok{background:var(--color-text-success)}.dot.info{background:var(--color-text-info)}.dot.warn{background:var(--color-text-warning)}.dot.danger{background:var(--color-text-danger)}
+.bar{height:6px;border-radius:999px;background:var(--color-background-secondary);overflow:hidden}
+.bar>i{display:block;height:100%;border-radius:inherit;background:var(--color-text-success)}
+.tree{display:flex;flex-direction:column;gap:7px;margin:0;padding:0;list-style:none}
+.tree .tree{margin-top:7px;margin-left:9px;padding-left:14px;border-left:1px solid var(--color-border-secondary)}
+`;
+// slides: a stepped deck. Author `.deck` with `.slide` children; the JS shows
+// one at a time and injects prev/dots/counter/next controls. Arrow keys and
+// PageUp/Down navigate (plain keys only — the host owns the meta/alt combos).
+//
+// The slides are GRID-STACKED (every `.slide` in the same `1/1` cell), not
+// swapped with display:none or overlaid with position:absolute. That keeps them
+// in normal flow — so the deck (and the document) sizes to the TALLEST slide and
+// the height the surface reports stays stable — while still letting them overlap
+// so inactive slides can cross-fade under the active one. An absolute overlay
+// would grow scrollHeight without growing the measured box, and the frame's
+// ResizeObserver (which watches the box, not scrollHeight) would go blind to it
+// and clip the deck; grid-stacking avoids that trap. Inactive slides stay laid
+// out (so they keep sizing the track) but are visibility:hidden — out of the tab
+// order and the a11y tree — until they become `.on`.
+const SLIDES_CSS = `
+.deck{display:grid;min-height:140px}
+.deck>.slide{grid-area:1/1;opacity:0;visibility:hidden;pointer-events:none;transition:opacity .3s ease,visibility 0s linear .3s}
+.deck>.slide.on{opacity:1;visibility:visible;pointer-events:auto;transition:opacity .3s ease}
+@media (prefers-reduced-motion:reduce){.deck>.slide{transition:none}}
+.deck>.slide h2{font:500 22px/1.3 var(--font-sans);margin:0 0 14px}
+.deck-ctl{display:flex;align-items:center;justify-content:center;gap:14px;margin-top:18px;padding-top:14px;border-top:1px solid var(--color-border-secondary)}
+.deck-dots{display:inline-flex;gap:7px}
+.deck-dots i{width:7px;height:7px;border-radius:999px;background:var(--color-border-primary);cursor:pointer}
+.deck-dots i.on{background:var(--color-text-info)}
+.deck-num{font:400 13px/1 var(--font-mono);color:var(--color-text-tertiary);min-width:46px;text-align:center}
+`;
+const SLIDES_JS = `
+(function(){
+  var deck=document.querySelector('.deck');if(!deck)return;
+  var slides=[].slice.call(deck.querySelectorAll(':scope > .slide'));if(!slides.length)return;
+  var i=0;
+  var ctl=document.createElement('div');ctl.className='deck-ctl';
+  var prev=document.createElement('button');prev.type='button';prev.setAttribute('aria-label','Previous slide');prev.textContent='‹';
+  var next=document.createElement('button');next.type='button';next.setAttribute('aria-label','Next slide');next.textContent='›';
+  var dots=document.createElement('span');dots.className='deck-dots';
+  var num=document.createElement('span');num.className='deck-num';
+  slides.forEach(function(_,k){var d=document.createElement('i');d.setAttribute('role','button');d.addEventListener('click',function(){go(k);});dots.appendChild(d);});
+  ctl.appendChild(prev);ctl.appendChild(dots);ctl.appendChild(num);ctl.appendChild(next);
+  deck.appendChild(ctl);
+  function go(n){i=(n+slides.length)%slides.length;
+    slides.forEach(function(s,k){s.classList.toggle('on',k===i);});
+    [].forEach.call(dots.children,function(d,k){d.classList.toggle('on',k===i);});
+    num.textContent=(i+1)+' / '+slides.length;}
+  prev.addEventListener('click',function(){go(i-1);});
+  next.addEventListener('click',function(){go(i+1);});
+  document.addEventListener('keydown',function(e){
+    if(e.metaKey||e.altKey||e.ctrlKey)return;
+    if(e.key==='ArrowRight'||e.key==='PageDown'){e.preventDefault();go(i+1);}
+    else if(e.key==='ArrowLeft'||e.key==='PageUp'){e.preventDefault();go(i-1);}});
+  go(0);
+})();
+`;
+// builtin: the fallback component vocabulary `mockpit init` injects when a
+// project has no Tailwind/shadcn of its own. Class names mirror shadcn so an
+// agent that knows one writes the other without a lookup, but every rule is
+// CSS-only — no JS, no CDN — and every color comes from the `--color-*` tokens
+// the wrapper already emits, so it re-themes with the workspace and with an
+// imported project palette alike. Radius prefers the project's own `--radius`
+// (imported verbatim by init) and falls back to the mockpit token.
+//
+// It deliberately redeclares `.card`/`.badge` from the `issues` kit: surfaces
+// ask for one or the other, and renderHtmlPage appends builtin last so a
+// project's component look wins if both are somehow present.
+const BUILTIN_CSS = `
+:root{--r:var(--radius,var(--border-radius-md))}
+.btn{display:inline-flex;align-items:center;justify-content:center;gap:6px;font:500 14px/1 var(--font-sans);padding:9px 16px;border-radius:var(--r);border:1px solid var(--color-border-secondary);background:var(--color-background-primary);color:var(--color-text-primary);cursor:pointer;text-decoration:none;white-space:nowrap}
+.btn:hover{background:var(--color-background-secondary)}
+.btn:focus-visible{outline:2px solid var(--color-border-info);outline-offset:2px}
+.btn[disabled],.btn.disabled{opacity:.5;pointer-events:none}
+.btn-primary{background:var(--color-text-info);border-color:var(--color-text-info);color:var(--color-background-primary)}
+.btn-primary:hover{opacity:.9;background:var(--color-text-info)}
+.btn-secondary{background:var(--color-background-secondary);border-color:transparent}
+.btn-ghost{background:none;border-color:transparent}
+.btn-ghost:hover{background:var(--color-background-secondary)}
+.btn-destructive{background:var(--color-text-danger);border-color:var(--color-text-danger);color:var(--color-background-primary)}
+.btn-sm{font-size:13px;padding:6px 11px}
+.btn-lg{font-size:15px;padding:12px 22px}
+.card{background:var(--color-background-primary);border:1px solid var(--color-border-secondary);border-radius:calc(var(--r) + 4px);padding:20px;display:flex;flex-direction:column;gap:12px}
+.card-header{display:flex;flex-direction:column;gap:4px}
+.card-title{font:500 16px/1.3 var(--font-sans);margin:0}
+.card-desc{font-size:13px;color:var(--color-text-secondary);margin:0}
+.card-content{display:flex;flex-direction:column;gap:10px}
+.card-footer{display:flex;align-items:center;gap:8px;padding-top:4px}
+.label{font:500 13px/1.3 var(--font-sans);color:var(--color-text-primary)}
+.input,.textarea,.select{width:100%;font:14px/1.4 var(--font-sans);color:var(--color-text-primary);background:var(--color-background-primary);border:1px solid var(--color-border-secondary);border-radius:var(--r);padding:8px 11px;outline:none}
+.input:focus,.textarea:focus,.select:focus{border-color:var(--color-border-info);box-shadow:0 0 0 1px var(--color-border-info)}
+.input::placeholder,.textarea::placeholder{color:var(--color-text-tertiary)}
+.textarea{min-height:76px;resize:vertical}
+.field{display:flex;flex-direction:column;gap:6px}
+.badge{display:inline-flex;align-items:center;gap:5px;font:500 12px/1.4 var(--font-sans);padding:2px 9px;border-radius:999px;background:var(--color-text-info);color:var(--color-background-primary);border:1px solid transparent}
+.badge-secondary{background:var(--color-background-secondary);color:var(--color-text-secondary)}
+.badge-outline{background:none;border-color:var(--color-border-secondary);color:var(--color-text-secondary)}
+.badge-destructive{background:var(--color-text-danger);color:var(--color-background-primary)}
+.tabs{display:flex;flex-direction:column;gap:14px}
+.tabs-list{display:inline-flex;gap:2px;padding:3px;border-radius:var(--r);background:var(--color-background-secondary);align-self:flex-start}
+.tab{font:500 13px/1 var(--font-sans);padding:7px 13px;border:0;border-radius:calc(var(--r) - 2px);background:none;color:var(--color-text-secondary);cursor:pointer}
+.tab:hover{color:var(--color-text-primary)}
+.tab.on,.tab[aria-selected=true]{background:var(--color-background-primary);color:var(--color-text-primary)}
+.tab-panel{display:none}.tab-panel.on{display:block}
+.dialog{position:relative;margin:0 auto;max-width:440px;background:var(--color-background-primary);border:1px solid var(--color-border-secondary);border-radius:calc(var(--r) + 4px);padding:22px;display:flex;flex-direction:column;gap:14px;box-shadow:none}
+.dialog-scrim{padding:26px;border-radius:calc(var(--r) + 6px);background:var(--color-background-tertiary)}
+.dialog-header{display:flex;flex-direction:column;gap:5px}
+.dialog-title{font:500 16px/1.3 var(--font-sans);margin:0}
+.dialog-desc{font-size:13px;color:var(--color-text-secondary);margin:0}
+.dialog-footer{display:flex;justify-content:flex-end;gap:8px}
+.table{width:100%;border-collapse:collapse;font-size:14px}
+.table th{text-align:left;font-weight:500;color:var(--color-text-secondary);padding:8px 12px;border-bottom:1px solid var(--color-border-secondary)}
+.table td{padding:9px 12px;border-bottom:1px solid var(--color-border-tertiary)}
+.table tbody tr:last-child td{border-bottom:0}
+.table tbody tr:hover{background:var(--color-background-secondary)}
+.table .num{text-align:right}
+.sep{height:1px;border:0;margin:0;background:var(--color-border-secondary)}
+.muted-fg{color:var(--color-text-secondary)}
+`;
+// Basecoat reads shadcn's variable names. A project that imported its own
+// shadcn `:root` block overrides these (its vars are injected last); a project
+// with none still gets a themed Basecoat in both modes, because each name
+// resolves to a mockpit token that already flips with the mode.
+const BASECOAT_THEME_CSS = `
+:root{--radius:var(--border-radius-md);--background:var(--color-background-primary);--foreground:var(--color-text-primary);--card:var(--color-background-primary);--card-foreground:var(--color-text-primary);--popover:var(--color-background-primary);--popover-foreground:var(--color-text-primary);--primary:var(--color-text-primary);--primary-foreground:var(--color-background-primary);--secondary:var(--color-background-secondary);--secondary-foreground:var(--color-text-primary);--muted:var(--color-background-secondary);--muted-foreground:var(--color-text-secondary);--accent:var(--color-background-secondary);--accent-foreground:var(--color-text-primary);--destructive:var(--color-text-danger);--border:var(--color-border-secondary);--input:var(--color-border-secondary);--ring:var(--color-border-info)}
+`;
+// Pinned to a major so fixes arrive without a server release. 1.x moved
+// variants from `.btn-primary` classes to `data-variant`.
+const BASECOAT_CDN = "https://cdn.jsdelivr.net/npm/basecoat-css@1/dist";
+export const KITS = [
+    {
+        id: "builtin",
+        label: "Builtin",
+        summary: "shadcn-shaped components (CSS only) for projects with no design system",
+        classes: "btn · card · input · label · badge · tabs · dialog · table",
+        css: BUILTIN_CSS,
+    },
+    {
+        id: "issues",
+        label: "Issues",
+        summary: "issue / PR / CI status — trees, badges, chips, rollup bars",
+        classes: "card · tree · badge · chip · dot · bar",
+        css: ISSUES_CSS,
+    },
+    {
+        id: "slides",
+        label: "Slides",
+        summary: "a stepped, cross-fading deck with prev/next controls and a counter",
+        classes: "deck · slide (+ injected controls)",
+        css: SLIDES_CSS,
+        js: SLIDES_JS,
+    },
+    {
+        id: "basecoat",
+        label: "Basecoat",
+        summary: "shadcn's look as plain CSS classes (Basecoat UI from jsDelivr); themes from shadcn vars",
+        classes: 'btn card input label badge alert table tabs dialog kbd; data-variant="secondary|outline|ghost|destructive"',
+        css: BASECOAT_THEME_CSS,
+        href: `${BASECOAT_CDN}/basecoat.cdn.min.css`,
+        // Tabs (advertised above) switch only with Basecoat's script; the bundle
+        // also drives dropdown-menu, select and popover markup.
+        script: `${BASECOAT_CDN}/js/all.min.js`,
+    },
+];
+const KIT_BY_ID = new Map(KITS.map((k) => [k.id, k]));
+export const isKnownKit = (id) => typeof id === "string" && KIT_BY_ID.has(id);
+export const KIT_IDS = KITS.map((k) => k.id);
+// Compact descriptor for discovery (no CSS/JS payload), followed by the
+// project's own kits when given.
+export const kitSummaries = (projectKits = []) => [
+    ...KITS.map((k) => ({
+        id: k.id,
+        source: "bundled",
+        label: k.label,
+        summary: k.summary,
+        classes: k.classes,
+        ...(k.href ? { href: k.href } : {}),
+    })),
+    ...projectKits.map((k) => ({ ...k, source: "project" })),
+];
+// Ids a project kit may not take: they already mean something in design.kit.
+export const RESERVED_KIT_IDS = ["tailwind", "none", ...KIT_IDS];
+export const PROJECT_KIT_DOC_MAX = 1200;
+const PROJECT_KIT_ID = /^[a-z0-9][a-z0-9-]{0,31}$/;
+// One project kit as it arrives over the API. Its URLs become tags in the
+// sandboxed document, so they must pass the same allowlist as the CSP.
+export function checkProjectKit(raw) {
+    if (!raw || typeof raw !== "object")
+        return "a kit must be an object {id, href, doc}";
+    const k = raw;
+    if (typeof k.id !== "string" || !PROJECT_KIT_ID.test(k.id))
+        return "kit id must be lowercase letters, digits and dashes, at most 32";
+    if (RESERVED_KIT_IDS.includes(k.id))
+        return `kit id "${k.id}" is taken by a bundled kit`;
+    const href = checkCdnUrl(k.href, "kit url");
+    if ("error" in href)
+        return href.error;
+    let script;
+    if (k.script !== undefined && k.script !== null && k.script !== "") {
+        const checked = checkCdnUrl(k.script, "kit script");
+        if ("error" in checked)
+            return checked.error;
+        script = checked.url;
+    }
+    const doc = typeof k.doc === "string" ? k.doc.trim() : "";
+    if (!doc)
+        return "a kit needs a doc: the class cheat sheet the brief prints";
+    if (doc.length > PROJECT_KIT_DOC_MAX)
+        return `kit doc is ${doc.length} chars; keep it under ${PROJECT_KIT_DOC_MAX}`;
+    return { id: k.id, href: href.url, ...(script ? { script } : {}), doc };
+}
+// Resolve a list of kit ids to the CSS/JS to inject. Unknown ids are ignored;
+// duplicates collapse; CORE ships once when any known kit is present.
+export function kitAssets(ids) {
+    if (!ids || ids.length === 0)
+        return { css: "", js: "" };
+    const seen = new Set();
+    const chosen = [];
+    for (const id of ids) {
+        const kit = KIT_BY_ID.get(id);
+        if (kit && !seen.has(id)) {
+            seen.add(id);
+            chosen.push(kit);
+        }
+    }
+    if (chosen.length === 0)
+        return { css: "", js: "" };
+    // A reference kit brings its own vocabulary; CORE's `.kbd` would override
+    // the library's.
+    let css = chosen.some((k) => !k.href) ? CORE_CSS : "";
+    let js = "";
+    for (const kit of chosen) {
+        css += kit.css;
+        if (kit.js)
+            js += kit.js;
+    }
+    return { css, js };
+}

package/dist/server/knobs.d.ts

@@ -0,0 +1,15 @@
+import type { ExplicitKnob, KnobConfig, Knobs, KnobValue, Mock, Post } from "./types.ts";
+export type Checked<T> = {
+    ok: true;
+    value: T;
+} | {
+    ok: false;
+    error: string;
+};
+export declare function explicitKnob(config: KnobConfig): ExplicitKnob;
+export declare function checkKnobConfig(path: string, raw: unknown): Checked<KnobConfig>;
+export declare function checkKnobs(raw: unknown): Checked<Knobs>;
+export declare function checkKnobValue(path: string, config: KnobConfig, value: unknown): Checked<KnobValue>;
+export declare function knobFor(path: string, mock: Pick<Mock, "knobs">, posts: Pick<Post, "knobs">[]): KnobConfig | undefined;
+export declare function checkKnobValues(raw: unknown, mock: Pick<Mock, "knobs">, posts: Pick<Post, "knobs">[], what: string): Checked<Record<string, KnobValue>>;
+export declare function discreteChoices(config: KnobConfig): number | null;

package/dist/server/knobs.js

@@ -0,0 +1,333 @@
+// Knob schema and value validation (plan Q3: values are checked against the
+// declared schema before they are stored or used). Runtime-agnostic. The config
+// shape mirrors tunekit's usePane config; see the knob types in types.ts.
+const MAX_KNOBS = 100;
+const MAX_OPTIONS = 100;
+const MAX_STRING = 500;
+const MAX_TEXT_VALUE = 2000;
+// A path is "size" (global) or "<part>.<name>"; segments stay CSS/attribute-safe
+// because the bridge turns them into `--k-<path>` vars and `data-k-<path>` attrs.
+const PATH_RE = /^[A-Za-z_][\w-]{0,63}(\.[A-Za-z_][\w-]{0,63}){0,3}$/;
+// Color values end up inside CSS custom properties, so only the characters a
+// CSS color or gradient needs are allowed.
+const COLOR_RE = /^[#\w\s(),.%/+-]{1,300}$/;
+// The character class above still admits `url(//host/x)` and `image(...)`, which
+// would turn a colour var into a network fetch inside the sandbox; a colour never
+// needs either function.
+const COLOR_FETCH_RE = /\b(url|image|image-set|src)\s*\(/i;
+const isCssColor = (v) => COLOR_RE.test(v) && !COLOR_FETCH_RE.test(v);
+const COLOR_HINT = /^(#|rgba?\(|hsla?\(|hwb\(|lab\(|lch\(|oklab\(|oklch\(|color\(|(linear|radial|conic)-gradient\()/i;
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+const isStr = (v, max = MAX_STRING) => typeof v === "string" && v.length <= max;
+function checkAxis(raw, name) {
+    if (!Array.isArray(raw) || raw.length < 3 || raw.length > 4 || !raw.every(isNum)) {
+        return { ok: false, error: `${name} must be [default, min, max, step?] numbers` };
+    }
+    const [value, min, max, step] = raw;
+    if (min > max)
+        return { ok: false, error: `${name} min is above max` };
+    if (value < min || value > max)
+        return { ok: false, error: `${name} default is outside min..max` };
+    if (step !== undefined && step <= 0)
+        return { ok: false, error: `${name} step must be positive` };
+    return { ok: true, value: raw.slice() };
+}
+function checkOptions(raw, name) {
+    if (!Array.isArray(raw) || raw.length === 0 || raw.length > MAX_OPTIONS) {
+        return { ok: false, error: `${name} options must be a non-empty array` };
+    }
+    const out = [];
+    for (const o of raw) {
+        if (isStr(o))
+            out.push(o);
+        else if (o && typeof o === "object" && isStr(o.value) && isStr(o.label)) {
+            out.push({ value: o.value, label: o.label });
+        }
+        else
+            return { ok: false, error: `${name} options must be strings or {value, label}` };
+    }
+    return { ok: true, value: out };
+}
+const optionValues = (options) => (options ?? []).map((o) => (typeof o === "string" ? o : o.value));
+// Expand tunekit's shorthands into an explicit control, the same way tunekit's
+// config parser does (a string is a color when it looks like one, else text).
+export function explicitKnob(config) {
+    if (Array.isArray(config)) {
+        const [value, min, max, step] = config;
+        return { type: "slider", value, min, max, ...(step === undefined ? {} : { step }) };
+    }
+    if (typeof config === "number") {
+        if (config >= 0 && config <= 1)
+            return { type: "slider", value: config, min: 0, max: 1 };
+        if (config >= 0)
+            return { type: "slider", value: config, min: 0, max: config * 3 || 10 };
+        return { type: "slider", value: config, min: config * 3, max: -config * 3 };
+    }
+    if (typeof config === "boolean")
+        return { type: "toggle", value: config };
+    if (typeof config === "string") {
+        return COLOR_HINT.test(config)
+            ? { type: "color", value: config }
+            : { type: "text", value: config };
+    }
+    return config;
+}
+// Validate one declared knob and return a clean copy (unknown keys dropped).
+export function checkKnobConfig(path, raw) {
+    const name = `knob "${path}"`;
+    if (Array.isArray(raw))
+        return checkAxis(raw, name);
+    if (isNum(raw) || typeof raw === "boolean")
+        return { ok: true, value: raw };
+    if (typeof raw === "string") {
+        return raw.length <= MAX_STRING
+            ? { ok: true, value: raw }
+            : { ok: false, error: `${name} is too long` };
+    }
+    if (!raw || typeof raw !== "object")
+        return { ok: false, error: `${name} is not a knob` };
+    const k = raw;
+    switch (k.type) {
+        case "slider": {
+            const axis = checkAxis([k.value, k.min, k.max, ...(k.step === undefined ? [] : [k.step])], name);
+            if (!axis.ok)
+                return axis;
+            const [value, min, max, step] = axis.value;
+            return {
+                ok: true,
+                value: { type: "slider", value, min, max, ...(step === undefined ? {} : { step }) },
+            };
+        }
+        case "toggle":
+            return typeof k.value === "boolean"
+                ? { ok: true, value: { type: "toggle", value: k.value } }
+                : { ok: false, error: `${name} toggle needs a boolean value` };
+        case "select": {
+            const options = checkOptions(k.options, name);
+            if (!options.ok)
+                return options;
+            if (k.value !== undefined && !optionValues(options.value).includes(k.value)) {
+                return { ok: false, error: `${name} value is not one of its options` };
+            }
+            return {
+                ok: true,
+                value: {
+                    type: "select",
+                    options: options.value,
+                    ...(k.value === undefined ? {} : { value: k.value }),
+                },
+            };
+        }
+        case "color": {
+            if (k.value !== undefined && !(typeof k.value === "string" && isCssColor(k.value))) {
+                return { ok: false, error: `${name} color value is not a CSS color` };
+            }
+            return {
+                ok: true,
+                value: {
+                    type: "color",
+                    ...(k.value === undefined ? {} : { value: k.value }),
+                    ...(k.gradient === true ? { gradient: true } : {}),
+                    ...(isStr(k.contrast) && isCssColor(k.contrast) ? { contrast: k.contrast } : {}),
+                },
+            };
+        }
+        case "text":
+            if (k.value !== undefined && !isStr(k.value, MAX_TEXT_VALUE)) {
+                return { ok: false, error: `${name} text value must be a string` };
+            }
+            return {
+                ok: true,
+                value: {
+                    type: "text",
+                    ...(k.value === undefined ? {} : { value: k.value }),
+                    ...(isStr(k.placeholder) ? { placeholder: k.placeholder } : {}),
+                },
+            };
+        case "spring": {
+            const out = { type: "spring" };
+            for (const key of ["stiffness", "damping", "mass", "visualDuration", "bounce"]) {
+                if (k[key] === undefined)
+                    continue;
+                if (!isNum(k[key]))
+                    return { ok: false, error: `${name} ${key} must be a number` };
+                out[key] = k[key];
+            }
+            return { ok: true, value: out };
+        }
+        case "easing": {
+            if (!isNum(k.duration) || k.duration < 0) {
+                return { ok: false, error: `${name} easing needs a duration` };
+            }
+            if (!Array.isArray(k.ease) || k.ease.length !== 4 || !k.ease.every(isNum)) {
+                return { ok: false, error: `${name} ease must be four numbers` };
+            }
+            return {
+                ok: true,
+                value: {
+                    type: "easing",
+                    duration: k.duration,
+                    ease: [...k.ease],
+                },
+            };
+        }
+        case "image": {
+            let options;
+            if (k.options !== undefined) {
+                const checked = checkOptions(k.options, name);
+                if (!checked.ok)
+                    return checked;
+                options = checked.value;
+            }
+            if (k.value !== undefined && !isStr(k.value, MAX_TEXT_VALUE)) {
+                return { ok: false, error: `${name} image value must be a string` };
+            }
+            return {
+                ok: true,
+                value: {
+                    type: "image",
+                    ...(k.value === undefined ? {} : { value: k.value }),
+                    ...(options ? { options } : {}),
+                },
+            };
+        }
+        case "pad": {
+            const out = { type: "pad" };
+            for (const axis of ["x", "y"]) {
+                if (k[axis] === undefined)
+                    continue;
+                const checked = checkAxis(k[axis], `${name} ${axis}`);
+                if (!checked.ok)
+                    return checked;
+                out[axis] = checked.value;
+            }
+            if (k.labels && typeof k.labels === "object") {
+                out.labels = {
+                    ...(isStr(k.labels.x) ? { x: k.labels.x } : {}),
+                    ...(isStr(k.labels.y) ? { y: k.labels.y } : {}),
+                };
+            }
+            return { ok: true, value: out };
+        }
+        default:
+            return { ok: false, error: `${name} has unknown type "${String(k.type)}"` };
+    }
+}
+export function checkKnobs(raw) {
+    if (raw === undefined || raw === null)
+        return { ok: true, value: {} };
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, error: "knobs must be an object of path → knob" };
+    }
+    const entries = Object.entries(raw);
+    if (entries.length > MAX_KNOBS)
+        return { ok: false, error: `at most ${MAX_KNOBS} knobs` };
+    const out = {};
+    for (const [path, config] of entries) {
+        if (!PATH_RE.test(path)) {
+            return { ok: false, error: `knob path "${path}" must be "name" or "part.name"` };
+        }
+        const checked = checkKnobConfig(path, config);
+        if (!checked.ok)
+            return checked;
+        out[path] = checked.value;
+    }
+    return { ok: true, value: out };
+}
+const axisOf = (axis) => axis ? [axis[1], axis[2]] : [-1, 1];
+// Whether `value` is something the declared knob could hold.
+export function checkKnobValue(path, config, value) {
+    const knob = explicitKnob(config);
+    const bad = (what) => ({
+        ok: false,
+        error: `value for knob "${path}" ${what}`,
+    });
+    switch (knob.type) {
+        case "slider":
+            if (!isNum(value))
+                return bad("must be a number");
+            if (value < knob.min || value > knob.max)
+                return bad(`must be within ${knob.min}..${knob.max}`);
+            return { ok: true, value };
+        case "toggle":
+            return typeof value === "boolean" ? { ok: true, value } : bad("must be true or false");
+        case "select":
+            return typeof value === "string" && optionValues(knob.options).includes(value)
+                ? { ok: true, value }
+                : bad(`must be one of ${optionValues(knob.options).join(", ")}`);
+        case "color":
+            return typeof value === "string" && isCssColor(value)
+                ? { ok: true, value }
+                : bad("must be a CSS color");
+        case "text":
+            return isStr(value, MAX_TEXT_VALUE) ? { ok: true, value } : bad("must be a string");
+        case "image":
+            if (!isStr(value, MAX_TEXT_VALUE))
+                return bad("must be a string");
+            if (knob.options && !optionValues(knob.options).includes(value)) {
+                return bad(`must be one of ${optionValues(knob.options).join(", ")}`);
+            }
+            return { ok: true, value };
+        case "pad": {
+            if (!value || typeof value !== "object")
+                return bad("must be {x, y}");
+            const { x, y } = value;
+            const [xMin, xMax] = axisOf(knob.x);
+            const [yMin, yMax] = axisOf(knob.y);
+            if (!isNum(x) || !isNum(y) || x < xMin || x > xMax || y < yMin || y > yMax) {
+                return bad("must be {x, y} within the pad's range");
+            }
+            return { ok: true, value: { x, y } };
+        }
+        case "spring":
+        case "easing": {
+            // tunekit lets a transition knob switch between spring and easing modes.
+            const checked = checkKnobConfig(path, value);
+            if (!checked.ok)
+                return checked;
+            const t = checked.value;
+            return t && typeof t === "object" && (t.type === "spring" || t.type === "easing")
+                ? { ok: true, value: t }
+                : bad("must be a spring or easing");
+        }
+    }
+}
+// The declared knob for a path: the mock's own, else a variant's override.
+export function knobFor(path, mock, posts) {
+    if (Object.hasOwn(mock.knobs, path))
+        return mock.knobs[path];
+    for (const p of posts)
+        if (p.knobs && Object.hasOwn(p.knobs, path))
+            return p.knobs[path];
+    return undefined;
+}
+export function checkKnobValues(raw, mock, posts, what) {
+    if (raw === undefined || raw === null)
+        return { ok: true, value: {} };
+    if (typeof raw !== "object" || Array.isArray(raw)) {
+        return { ok: false, error: `${what} must be an object of knob path → value` };
+    }
+    const out = {};
+    for (const [path, value] of Object.entries(raw)) {
+        const config = knobFor(path, mock, posts);
+        if (config === undefined)
+            return { ok: false, error: `${what}: no knob "${path}" is declared` };
+        const checked = checkKnobValue(path, config, value);
+        if (!checked.ok)
+            return checked;
+        out[path] = checked.value;
+    }
+    return { ok: true, value: out };
+}
+// How many discrete choices a knob offers, or null when it is continuous. A knob
+// with only a handful is usually a decision dressed as a control (plan D12).
+export function discreteChoices(config) {
+    const knob = explicitKnob(config);
+    if (knob.type === "toggle")
+        return 2;
+    if (knob.type === "select")
+        return knob.options.length;
+    if (knob.type === "image" && knob.options)
+        return knob.options.length;
+    return null;
+}

package/dist/server/logFile.d.ts

@@ -0,0 +1,2 @@
+import type { LogSink } from "./eventLog.ts";
+export declare function createFileLog(path: string, maxBytes?: number): LogSink;

package/dist/server/logFile.js

@@ -0,0 +1,27 @@
+import { appendFileSync, mkdirSync, renameSync, statSync } from "node:fs";
+import { dirname } from "node:path";
+// One file plus one rotated predecessor caps the log at twice this, so leaving
+// it on by default costs a bounded slice of disk.
+const DEFAULT_MAX_BYTES = 10 * 1024 * 1024;
+// Appends JSONL to `path`, rolling it to `<path>.1` past `maxBytes`. Writes are
+// synchronous so lines never interleave and a crash loses nothing already
+// answered; the loop's call rate makes that cost negligible.
+export function createFileLog(path, maxBytes = DEFAULT_MAX_BYTES) {
+    mkdirSync(dirname(path), { recursive: true });
+    let size = 0;
+    try {
+        size = statSync(path).size;
+    }
+    catch {
+        // No file yet.
+    }
+    return (entry) => {
+        const line = `${JSON.stringify(entry)}\n`;
+        if (size > 0 && size + line.length > maxBytes) {
+            renameSync(path, `${path}.1`);
+            size = 0;
+        }
+        appendFileSync(path, line);
+        size += Buffer.byteLength(line);
+    };
+}