mockpit 0.0.0-stage → 1.0.0

package/dist/server/icons.js

@@ -0,0 +1,225 @@
+// Icons by name: an agent writes `<i icon="lucide:check"></i>` and the server
+// inlines the SVG from an Iconify JSON set at render time, so an icon costs the
+// agent its name and the frame needs no fetch. Runtime-agnostic (no node
+// imports): it runs inside renderHtmlPage on the Worker too.
+// Served with the server rather than installed per project: lucide (ISC) is
+// what agents reach for by default, mage (Apache-2.0) is what `mockpit init`
+// used to upload as a sprite, so mocks written against it keep rendering.
+export const BUNDLED_ICON_PREFIXES = ["lucide", "mage"];
+const NAME_RE = /^[a-z0-9][a-z0-9-]*$/;
+export const isIconName = (s) => typeof s === "string" && NAME_RE.test(s);
+/** A parsed set, or null when `raw` is not a usable Iconify JSON set. */
+export function parseIconSet(raw) {
+    let data = raw;
+    if (typeof data === "string") {
+        try {
+            data = JSON.parse(data);
+        }
+        catch {
+            return null;
+        }
+    }
+    if (!data || typeof data !== "object")
+        return null;
+    const set = data;
+    if (!isIconName(set.prefix) || !set.icons || typeof set.icons !== "object")
+        return null;
+    return set;
+}
+/** Icons a listing should show: hidden ones exist only so old names keep resolving. */
+export const iconCount = (set) => Object.values(set.icons).filter((i) => !i.hidden).length;
+// Bundled sets are imported on first use, not at module load: they are ~600 KB
+// of JSON each, and a workspace that never renders an icon never pays for it.
+let bundled;
+export function bundledIconSets() {
+    bundled ??= (async () => {
+        const out = new Map();
+        const loaders = {
+            lucide: () => import("@iconify-json/lucide/icons.json", { with: { type: "json" } }),
+            mage: () => import("@iconify-json/mage/icons.json", { with: { type: "json" } }),
+        };
+        for (const prefix of BUNDLED_ICON_PREFIXES) {
+            try {
+                const mod = (await loaders[prefix]());
+                const set = parseIconSet(mod.default);
+                if (set)
+                    out.set(prefix, set);
+            }
+            catch (err) {
+                // A missing package costs that set's icons, never the render.
+                console.warn(`[mockpit] bundled icon set ${prefix} unavailable`, err);
+            }
+        }
+        return out;
+    })();
+    return bundled;
+}
+const MAX_ALIAS_DEPTH = 8;
+/** Resolve `name` in `set`, following aliases and applying their transforms. */
+export function iconFromSet(set, name) {
+    // Aliases stack: the outermost alias's box wins, flips toggle, rotations add.
+    let box = {};
+    let rotate = 0;
+    let hFlip = false;
+    let vFlip = false;
+    let current = name;
+    for (let depth = 0; depth <= MAX_ALIAS_DEPTH; depth++) {
+        const icon = Object.hasOwn(set.icons, current) ? set.icons[current] : undefined;
+        const alias = !icon && set.aliases && Object.hasOwn(set.aliases, current)
+            ? set.aliases[current]
+            : undefined;
+        const props = icon ?? alias;
+        if (!props)
+            return null;
+        box = { width: props.width, height: props.height, left: props.left, top: props.top, ...box };
+        for (const k of ["width", "height", "left", "top"]) {
+            if (box[k] === undefined)
+                delete box[k];
+        }
+        rotate += props.rotate ?? 0;
+        if (props.hFlip)
+            hFlip = !hFlip;
+        if (props.vFlip)
+            vFlip = !vFlip;
+        if (icon) {
+            const width = box.width ?? set.width ?? 16;
+            const height = box.height ?? set.height ?? 16;
+            const left = box.left ?? set.left ?? 0;
+            const top = box.top ?? set.top ?? 0;
+            return transform({ body: icon.body, left, top, width, height }, rotate % 4, hFlip, vFlip);
+        }
+        current = alias.parent;
+    }
+    return null;
+}
+function transform(icon, rotate, hFlip, vFlip) {
+    let { body, left, top, width, height } = icon;
+    const flips = [
+        hFlip ? `translate(${2 * left + width} 0) scale(-1 1)` : "",
+        vFlip ? `translate(0 ${2 * top + height}) scale(1 -1)` : "",
+    ].filter(Boolean);
+    if (flips.length)
+        body = `<g transform="${flips.join(" ")}">${body}</g>`;
+    if (rotate) {
+        const cx = left + width / 2;
+        const cy = top + height / 2;
+        body = `<g transform="rotate(${rotate * 90} ${cx} ${cy})">${body}</g>`;
+        // A quarter turn swaps the box's sides around its center.
+        if (rotate % 2 === 1) {
+            [width, height] = [height, width];
+            left = cx - width / 2;
+            top = cy - height / 2;
+        }
+    }
+    return { body, left, top, width, height };
+}
+/** A resolver over in-memory sets; earlier sets win a prefix. */
+export function resolverFor(sets) {
+    const byPrefix = new Map();
+    for (const set of sets)
+        if (!byPrefix.has(set.prefix))
+            byPrefix.set(set.prefix, set);
+    return (prefix, name) => {
+        const set = byPrefix.get(prefix);
+        return set ? iconFromSet(set, name) : null;
+    };
+}
+// --- expansion -------------------------------------------------------------
+// Script, style and comment bodies are not markup: an icon attribute inside a
+// JS string must stay a string, or the inlined quotes would break the script.
+const OPAQUE_RE = /<script\b[\s\S]*?<\/script\s*>|<style\b[\s\S]*?<\/style\s*>|<!--[\s\S]*?-->/gi;
+const ATTRS = `((?:[^>"']|"[^"]*"|'[^']*')*?)`;
+const TAG_RE = new RegExp(`<([a-zA-Z][\\w-]*)(?:\\s${ATTRS})?(\\/?)>`, "g");
+// The pre-expansion form `mockpit init` taught: a sprite reference.
+const SPRITE_RE = new RegExp(`<svg\\b${ATTRS}>\\s*<use\\b${ATTRS}\\/?>\\s*(?:<\\/use>\\s*)?<\\/svg\\s*>`, "gi");
+const ATTR_RE = /([^\s"'>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+function parseAttrs(text) {
+    const out = [];
+    for (const m of text.matchAll(ATTR_RE)) {
+        out.push({ name: m[1].toLowerCase(), raw: m[0], value: m[2] ?? m[3] ?? m[4] ?? null });
+    }
+    return out;
+}
+const fmt = (n) => String(Math.round(n * 1000) / 1000);
+const viewBox = (i) => `${fmt(i.left)} ${fmt(i.top)} ${fmt(i.width)} ${fmt(i.height)}`;
+// The element's own attributes survive (data-part, style, title…); `class`
+// gains `icon` for the 1em sizing, and a decorative icon is hidden from
+// assistive tech unless the author labelled it.
+function svgFor(attrs, icon) {
+    const kept = attrs.filter((a) => a.name !== "icon" && a.name !== "class");
+    const cls = attrs.find((a) => a.name === "class")?.value?.trim();
+    const has = (n) => attrs.some((a) => a.name === n);
+    const extra = [
+        `class="${!cls ? "icon" : cls.split(/\s+/).includes("icon") ? cls : `icon ${cls}`}"`,
+        ...kept.map((a) => a.raw),
+        has("viewbox") ? "" : `viewBox="${icon ? viewBox(icon) : "0 0 24 24"}"`,
+        has("aria-hidden") || has("role")
+            ? ""
+            : has("aria-label") || has("aria-labelledby")
+                ? 'role="img"'
+                : 'aria-hidden="true"',
+    ].filter(Boolean);
+    return `<svg ${extra.join(" ")}>${icon?.body ?? ""}</svg>`;
+}
+function expandSegment(html, resolve, unknown) {
+    const lookup = (prefix, name) => {
+        const icon = resolve(prefix, name);
+        if (!icon)
+            unknown.add(`${prefix}:${name}`);
+        return icon;
+    };
+    const sprites = html.replace(SPRITE_RE, (whole, svgAttrs, useAttrs) => {
+        const href = parseAttrs(useAttrs).find((a) => a.name === "href" || a.name === "xlink:href");
+        const m = href?.value?.match(/^#mage-(.+)$/);
+        if (!m || !isIconName(m[1]))
+            return whole;
+        const icon = lookup("mage", m[1]);
+        return icon ? svgFor(parseAttrs(svgAttrs), icon) : whole;
+    });
+    let out = "";
+    let last = 0;
+    for (const m of sprites.matchAll(TAG_RE)) {
+        const attrs = m[2] ? parseAttrs(m[2]) : [];
+        const spec = attrs.find((a) => a.name === "icon")?.value;
+        const colon = spec?.indexOf(":") ?? -1;
+        if (!spec || colon < 0)
+            continue;
+        const prefix = spec.slice(0, colon);
+        const name = spec.slice(colon + 1);
+        if (!isIconName(prefix) || !isIconName(name))
+            continue;
+        let end = m.index + m[0].length;
+        // Only an empty element is an icon; one with content is left alone so
+        // nothing the author wrote is dropped.
+        if (!m[3]) {
+            const close = new RegExp(`^\\s*<\\/${m[1]}\\s*>`, "i").exec(sprites.slice(end));
+            if (!close)
+                continue;
+            end += close[0].length;
+        }
+        out += sprites.slice(last, m.index) + svgFor(attrs, lookup(prefix, name));
+        last = end;
+    }
+    return out + sprites.slice(last);
+}
+/**
+ * Inline every `icon="prefix:name"` element (and the older
+ * `<svg><use href="#mage-name"/></svg>` sprite form) as an `<svg>`. Names the
+ * resolver does not know render as an empty 1em box and are listed in
+ * `unknown`, in first-seen order.
+ */
+// Cheap pre-check so html without icons never loads a set.
+export const mayHaveIcons = (html) => html.includes("icon=") || html.includes("#mage-");
+export function expandIcons(html, resolve) {
+    if (!mayHaveIcons(html))
+        return { html, unknown: [] };
+    const unknown = new Set();
+    let out = "";
+    let last = 0;
+    for (const m of html.matchAll(OPAQUE_RE)) {
+        out += expandSegment(html.slice(last, m.index), resolve, unknown) + m[0];
+        last = m.index + m[0].length;
+    }
+    out += expandSegment(html.slice(last), resolve, unknown);
+    return { html: out, unknown: [...unknown] };
+}

package/dist/server/index.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/server/index.js

@@ -0,0 +1,64 @@
+import { serve } from "@hono/node-server";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { basename, dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { createApp } from "./app.js";
+import { createNodeExecutor } from "./codeRunner.js";
+import { GUIDE_TOPICS } from "./designGuide.js";
+import { SqlStore } from "./sqlStore.js";
+import { createSqliteStorage } from "./sqliteStorage.js";
+// Source layout puts this file at server/index.ts; the published package runs
+// the compiled copy at dist/server/index.js. viewer/ and guide/ live at the
+// package root either way.
+let root = join(dirname(fileURLToPath(import.meta.url)), "..");
+if (basename(root) === "dist")
+    root = join(root, "..");
+const [viewerHtml, setupText, topicTexts, pkgJson] = await Promise.all([
+    readFile(join(root, "viewer", "dist", "index.html"), "utf8").catch(() => {
+        console.error("viewer build missing — run `npm run build:viewer` first");
+        return process.exit(1);
+    }),
+    readFile(join(root, "guide", "AGENT_SETUP.md"), "utf8"),
+    Promise.all(GUIDE_TOPICS.map((id) => readFile(join(root, "guide", "topics", `${id}.md`), "utf8"))),
+    readFile(join(root, "package.json"), "utf8"),
+]);
+const topics = Object.fromEntries(GUIDE_TOPICS.map((id, i) => [id, topicTexts[i]]));
+const pr = process.env.MOCKPIT_PUBLIC_READ;
+const publicRead = pr === "session" || pr === "full" ? pr : undefined;
+// Storage: SQLite via node:sqlite, the same SqlStore the Cloudflare Durable
+// Object runs, so local mirrors the deploy. MOCKPIT_DB names the file; the
+// default lives in ~/.mockpit/, a user-owned dir that survives reinstalls and
+// is writable however the package was installed.
+const dbPath = process.env.MOCKPIT_DB ?? join(homedir(), ".mockpit", "mockpit.db");
+const store = new SqlStore(createSqliteStorage(dbPath));
+console.log(`mockpit store: SQLite at ${dbPath}`);
+const app = createApp({
+    store,
+    viewerHtml,
+    setupText,
+    topics,
+    authToken: process.env.MOCKPIT_TOKEN,
+    publicRead,
+    // MOCKPIT_VERSION fakes the running version (manual testing of the
+    // notice); set it to the empty string to disable the update check
+    version: process.env.MOCKPIT_VERSION ?? JSON.parse(pkgJson).version,
+    upgradeCommand: "npm install -g mockpit",
+    // `run` scripts execute in QuickJS inside a worker thread per run.
+    executor: createNodeExecutor(),
+});
+const port = Number(process.env.PORT ?? 8228);
+// MOCKPIT_HOST (or `serve --host`) restricts the listener to one address.
+// Unset keeps the previous behaviour — node's default, every interface — because
+// that is what a container or a LAN-shared instance needs. Set it to 127.0.0.1
+// when the server shares a host with anything you don't want reaching it; that
+// is stronger than the token, which is a single shared secret by design.
+const hostname = process.env.MOCKPIT_HOST || undefined;
+serve({ fetch: app.fetch, port, hostname }, (info) => {
+    // Report the address actually bound. Printing "localhost" unconditionally hid
+    // the fact that the default listens on every interface.
+    const shown = hostname ?? "localhost";
+    const authority = shown.includes(":") ? `[${shown}]` : shown;
+    console.log(`mockpit listening on http://${authority}:${info.port}` +
+        (hostname ? "" : " (all interfaces — set MOCKPIT_HOST to restrict)"));
+});

package/dist/server/kits.d.ts

@@ -0,0 +1,36 @@
+import type { ProjectKit } from "./types.ts";
+export interface Kit {
+    id: string;
+    label: string;
+    summary: string;
+    classes: string;
+    css: string;
+    js?: string;
+    href?: string;
+    script?: string;
+}
+export declare const CORE_CSS = "\n.stack{display:flex;flex-direction:column;gap:8px}.stack.sm{gap:4px}.stack.lg{gap:16px}\n.row{display:flex;align-items:center;gap:8px;flex-wrap:wrap}.row.sm{gap:4px}\n.between{display:flex;align-items:center;justify-content:space-between;gap:12px}\n.grow{flex:1;min-width:0}\n.title{font:500 15px/1.35 var(--font-sans);color:var(--color-text-primary)}\n.dim{color:var(--color-text-secondary)}.faint{color:var(--color-text-tertiary)}\n.mono{font-family:var(--font-mono)}.num{font-variant-numeric:tabular-nums}\n.hr{height:1px;border:0;margin:2px 0;background:var(--color-border-secondary)}\n.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)}\n";
+export declare const KITS: Kit[];
+export declare const isKnownKit: (id: unknown) => id is string;
+export declare const KIT_IDS: string[];
+export declare const kitSummaries: (projectKits?: readonly ProjectKit[]) => ({
+    href?: string | undefined;
+    id: string;
+    source: "bundled";
+    label: string;
+    summary: string;
+    classes: string;
+} | {
+    source: "project";
+    id: string;
+    href: string;
+    script?: string;
+    doc: string;
+})[];
+export declare const RESERVED_KIT_IDS: string[];
+export declare const PROJECT_KIT_DOC_MAX = 1200;
+export declare function checkProjectKit(raw: unknown): ProjectKit | string;
+export declare function kitAssets(ids: readonly string[] | undefined): {
+    css: string;
+    js: string;
+};

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;