mockpit 3.0.0 → 3.1.0

package/dist/server/sqlStore.js

@@ -1,13 +1,9 @@
 import { collectAssetIds, collectAttachedIds, DEFAULT_PROJECT, DEFAULT_VARIANT, hashAssetId, HISTORY_LIMIT, htmlSurface, MAX_WORKSPACE_ASSET_BYTES, isDesignKind, newId, normalizeSurfaceIds, isLive, projectFromCwd, AREA_ORDER_SETTING, DECISION_EDITS_SETTING, reservedAgent, sameScreen, selectEvictions, slugify, stripNul, summarizeProjects, } from "./types.js";
 import { renameSlugRefs } from "./embeds.js";
+import { CURRENT_CONTRACT, normalizeSystem, SYSTEM_LIMITS, systemFromDesignSettings, } from "./system.js";
 import { RULES_SETTING } from "./guidance.js";
 // The settings keyed `<prefix>:<project>`, which a project rename carries.
-const PROJECT_SETTINGS = [
-    "design",
-    AREA_ORDER_SETTING,
-    RULES_SETTING,
-    DECISION_EDITS_SETTING,
-];
+const PROJECT_SETTINGS = [AREA_ORDER_SETTING, RULES_SETTING, DECISION_EDITS_SETTING];
 // An optional free-text label: blank means none.
 const label = (v) => stripNul(v ?? "").trim() || null;
 function parseJson(raw, fallback) {
@@ -59,6 +55,9 @@ const surfaceHeads = (surfaces) => JSON.stringify(surfaces.map((s) => {
         kind: s.kind,
         ...(s.poster ? { poster: s.poster } : {}),
         ...(s.poster && s.posterMode ? { posterMode: s.posterMode } : {}),
+        ...(s.poster && s.posterMode && s.posterSystem !== undefined
+            ? { posterSystem: s.posterSystem }
+            : {}),
         ...(/<mockpit-embed|data-fill/i.test(s.html) ? { marked: true } : {}),
     };
 }));
@@ -350,6 +349,14 @@ export class SqlStore {
         createdAt TEXT NOT NULL, updatedAt TEXT NOT NULL,
         PRIMARY KEY (project, name)
       );
+      CREATE TABLE IF NOT EXISTS systems (
+        project TEXT PRIMARY KEY, rev INTEGER NOT NULL, json TEXT NOT NULL
+      );
+      CREATE TABLE IF NOT EXISTS system_revisions (
+        project TEXT NOT NULL, rev INTEGER NOT NULL, json TEXT NOT NULL, at TEXT NOT NULL,
+        sessionId TEXT, summary TEXT NOT NULL DEFAULT '',
+        PRIMARY KEY (project, rev)
+      );
     `);
         this.addMissing("sessions", {
             agentSeq: "INTEGER NOT NULL DEFAULT 0",
@@ -377,7 +384,12 @@ export class SqlStore {
         });
         this.migrateSituations();
         // Before the legacy lift, whose history rows are written with every column.
-        this.addMissing("post_versions", { sessionId: "TEXT", amendedAt: "TEXT" });
+        this.addMissing("post_versions", {
+            sessionId: "TEXT",
+            amendedAt: "TEXT",
+            contract: "INTEGER",
+            system: "INTEGER",
+        });
         if (legacy)
             this.migrateLegacy();
         // After the legacy lift, which rebuilds posts from POST_COLUMNS alone.
@@ -397,6 +409,8 @@ export class SqlStore {
             archiveReason: "TEXT",
             stayedVersion: "INTEGER",
             archivedAt: "TEXT",
+            curContract: "INTEGER",
+            curSystem: "INTEGER",
         });
         // Before the pin, accepted meant "its latest": freeze that as the version in use.
         if (!pinned) {
@@ -410,6 +424,7 @@ export class SqlStore {
         }
         if (this.settingSync("sketchKind") !== "1")
             this.migrateToSketches();
+        this.migrateSystems();
         if (this.settingSync("contractTerms") !== "1")
             this.migrateToContractTerms();
         if (this.settingSync("designWords") !== "1")
@@ -753,7 +768,7 @@ export class SqlStore {
     }
     // --- rows ---
     insertVersion(postId, v) {
-        this.sql.exec("INSERT OR REPLACE INTO post_versions (postId, version, title, surfaces, head, at, fromVersion, prompt, author, sessionId, amendedAt) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", postId, v.version, v.title, JSON.stringify(v.surfaces ?? []), surfaceHeads(v.surfaces ?? []), v.at, v.from ?? null, v.prompt ?? null, v.author ?? null, v.publishedBy ?? null, v.amendedAt ?? null);
+        this.sql.exec("INSERT OR REPLACE INTO post_versions (postId, version, title, surfaces, head, at, fromVersion, prompt, author, sessionId, amendedAt, contract, system) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)", postId, v.version, v.title, JSON.stringify(v.surfaces ?? []), surfaceHeads(v.surfaces ?? []), v.at, v.from ?? null, v.prompt ?? null, v.author ?? null, v.publishedBy ?? null, v.amendedAt ?? null, v.contract ?? null, v.system ?? null);
     }
     rowToVersion(r) {
         return {
@@ -767,6 +782,8 @@ export class SqlStore {
             ...(r.author == null ? {} : { author: r.author }),
             ...(r.sessionId == null ? {} : { publishedBy: r.sessionId }),
             ...(r.amendedAt == null ? {} : { amendedAt: r.amendedAt }),
+            ...(r.contract == null ? {} : { contract: r.contract }),
+            ...(r.system == null ? {} : { system: r.system }),
         };
     }
     historiesFor(ids, weigh) {
@@ -865,6 +882,8 @@ export class SqlStore {
             ...(r.curAuthor == null ? {} : { author: r.curAuthor }),
             ...(r.curSession == null ? {} : { publishedBy: r.curSession }),
             ...(r.amendedAt == null ? {} : { amendedAt: r.amendedAt }),
+            ...(r.curContract == null ? {} : { contract: r.curContract }),
+            ...(r.curSystem == null ? {} : { system: r.curSystem }),
             ...(r.rewrites ? { rewrites: r.rewrites } : {}),
         };
     }
@@ -999,8 +1018,6 @@ export class SqlStore {
         return this.settingSync(key);
     }
     async setSetting(key, value) {
-        if (key.startsWith("design:"))
-            this.invalidateAssetRefs();
         this.sql.exec("INSERT INTO settings (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value", stripNul(key), stripNul(value));
     }
     // --- projects / designs ---
@@ -1246,12 +1263,98 @@ export class SqlStore {
                     continue;
                 this.sql.exec("INSERT OR REPLACE INTO settings (key, value) VALUES (?, ?)", `${prefix}:${target}`, value);
                 this.sql.exec("DELETE FROM settings WHERE key = ?", `${prefix}:${from}`);
-                if (prefix === "design")
-                    this.invalidateAssetRefs();
+            }
+            if (this.sql.exec("SELECT 1 FROM systems WHERE project = ?", from).toArray().length) {
+                this.sql.exec("DELETE FROM systems WHERE project = ?", target);
+                this.sql.exec("DELETE FROM system_revisions WHERE project = ?", target);
+                for (const table of ["systems", "system_revisions"]) {
+                    for (const r of this.sql
+                        .exec(`SELECT rowid AS id, json FROM ${table} WHERE project = ?`, from)
+                        .toArray()) {
+                        const moved = { ...parseJson(r.json, {}), project: target };
+                        this.sql.exec(`UPDATE ${table} SET project = ?, json = ? WHERE rowid = ?`, target, JSON.stringify(moved), r.id);
+                    }
+                }
             }
             return true;
         });
     }
+    // --- systems ---
+    async getSystem(project) {
+        const rows = this.sql.exec("SELECT json FROM systems WHERE project = ?", project).toArray();
+        return rows.length ? normalizeSystem(project, parseJson(rows[0].json, null)) : null;
+    }
+    async putSystem(system, meta) {
+        this.atomic(() => this.writeSystem(system, meta));
+        this.invalidateAssetRefs();
+        return system;
+    }
+    async commitSystemDecision(input) {
+        const tell = input.tell;
+        const comment = this.atomic(() => {
+            this.writeSystem(input.system, { sessionId: null, summary: input.summary });
+            return tell
+                ? this.insertComment({
+                    sessionId: tell.sessionId,
+                    author: "user",
+                    text: "",
+                    kind: "reply",
+                    payload: tell.payload,
+                })
+                : null;
+        });
+        this.invalidateAssetRefs();
+        return comment;
+    }
+    // Unwrapped, so a reply's transaction can carry it.
+    writeSystem(system, meta) {
+        const json = JSON.stringify(system);
+        const at = new Date().toISOString();
+        {
+            this.sql.exec("INSERT INTO systems (project, rev, json) VALUES (?, ?, ?) ON CONFLICT(project) DO UPDATE SET rev = excluded.rev, json = excluded.json", system.project, system.rev, json);
+            this.sql.exec("INSERT OR REPLACE INTO system_revisions (project, rev, json, at, sessionId, summary) VALUES (?, ?, ?, ?, ?, ?)", system.project, system.rev, json, at, meta.sessionId, stripNul(meta.summary).slice(0, SYSTEM_LIMITS.summary));
+            this.sql.exec("DELETE FROM system_revisions WHERE project = ? AND rev <= ?", system.project, system.rev - SYSTEM_LIMITS.revisions);
+        }
+    }
+    async listSystemRevisions(project) {
+        return this.sql
+            .exec("SELECT rev, at, sessionId, summary FROM system_revisions WHERE project = ? ORDER BY rev DESC", project)
+            .toArray()
+            .map((r) => ({
+            rev: r.rev,
+            at: r.at,
+            sessionId: r.sessionId ?? null,
+            summary: r.summary,
+        }));
+    }
+    async getSystemRevision(project, rev) {
+        const rows = this.sql
+            .exec("SELECT json FROM system_revisions WHERE project = ? AND rev = ?", project, rev)
+            .toArray();
+        return rows.length ? normalizeSystem(project, parseJson(rows[0].json, null)) : null;
+    }
+    // Each project's old design settings become its system, with the repo's
+    // tokens derived, and the setting goes.
+    migrateSystems() {
+        const rows = this.sql
+            .exec("SELECT key, value FROM settings WHERE key LIKE 'design:%'")
+            .toArray();
+        if (rows.length === 0)
+            return;
+        const at = new Date().toISOString();
+        for (const r of rows) {
+            const project = r.key.slice("design:".length);
+            const have = this.sql.exec("SELECT 1 FROM systems WHERE project = ?", project).toArray();
+            if (have.length === 0) {
+                const system = { ...systemFromDesignSettings(project, parseJson(r.value, null)), rev: 1 };
+                const json = JSON.stringify(system);
+                this.sql.exec("INSERT INTO systems (project, rev, json) VALUES (?, 1, ?)", project, json);
+                this.sql.exec("INSERT INTO system_revisions (project, rev, json, at, sessionId, summary) VALUES (?, 1, ?, ?, NULL, ?)", project, json, at, "from what the project stored before");
+            }
+            this.sql.exec("DELETE FROM settings WHERE key = ?", r.key);
+        }
+        this.invalidateAssetRefs();
+    }
     // --- flows ---
     flowsOf(project) {
         return this.sql
@@ -1505,8 +1608,10 @@ export class SqlStore {
             ...(input.prompt === undefined ? {} : { prompt: stripNul(input.prompt) }),
             ...(input.author === undefined ? {} : { author: stripNul(input.author) }),
             publishedBy: input.publishedBy ?? input.sessionId,
+            contract: input.contract ?? CURRENT_CONTRACT,
+            ...(input.system === undefined ? {} : { system: input.system }),
         };
-        this.writingPosts(post.design, [post.id], () => this.sql.exec("INSERT INTO posts (id, sessionId, designId, state, variant, status, title, surfaces, head, knobs, slots, createdAt, updatedAt, version, curFrom, curPrompt, curAuthor, description, forkedFrom, copiedFrom, curSession) VALUES (?, ?, ?, ?, ?, 'open', ?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?, ?, ?, ?, ?)", post.id, post.sessionId, post.design, post.state, post.variant, post.title, JSON.stringify(post.surfaces), surfaceHeads(post.surfaces), post.knobs ? JSON.stringify(post.knobs) : null, JSON.stringify(post.embeds), post.createdAt, post.updatedAt, post.from ?? null, post.prompt ?? null, post.author ?? null, post.description ?? null, post.forkedFrom ? JSON.stringify(post.forkedFrom) : null, post.copiedFrom ? JSON.stringify(post.copiedFrom) : null, post.publishedBy ?? null));
+        this.writingPosts(post.design, [post.id], () => this.sql.exec("INSERT INTO posts (id, sessionId, designId, state, variant, status, title, surfaces, head, knobs, slots, createdAt, updatedAt, version, curFrom, curPrompt, curAuthor, description, forkedFrom, copiedFrom, curSession, curContract, curSystem) VALUES (?, ?, ?, ?, ?, 'open', ?, ?, ?, ?, ?, ?, ?, 1, ?, ?, ?, ?, ?, ?, ?, ?, ?)", post.id, post.sessionId, post.design, post.state, post.variant, post.title, JSON.stringify(post.surfaces), surfaceHeads(post.surfaces), post.knobs ? JSON.stringify(post.knobs) : null, JSON.stringify(post.embeds), post.createdAt, post.updatedAt, post.from ?? null, post.prompt ?? null, post.author ?? null, post.description ?? null, post.forkedFrom ? JSON.stringify(post.forkedFrom) : null, post.copiedFrom ? JSON.stringify(post.copiedFrom) : null, post.publishedBy ?? null, post.contract ?? null, post.system ?? null));
         this.touch(input.sessionId);
         this.touchDesign(post.design, now);
         this.addAssetRefs(post.surfaces);
@@ -1529,6 +1634,8 @@ export class SqlStore {
                 ...(post.author === undefined ? {} : { author: post.author }),
                 ...(post.publishedBy === undefined ? {} : { publishedBy: post.publishedBy }),
                 ...(post.amendedAt === undefined ? {} : { amendedAt: post.amendedAt }),
+                ...(post.contract === undefined ? {} : { contract: post.contract }),
+                ...(post.system === undefined ? {} : { system: post.system }),
             };
             // The version in use is kept past the limit: export and embeds resolve to it.
             const pin = post.acceptedVersion ?? -1;
@@ -1551,8 +1658,10 @@ export class SqlStore {
             const prompt = stripNul(patch.prompt ?? "");
             const author = patch.author === undefined ? null : stripNul(patch.author);
             const publishedBy = patch.publishedBy ?? null;
+            const contract = patch.contract ?? CURRENT_CONTRACT;
+            const system = patch.system ?? null;
             const wrote = this.writingPosts(post.design, [id], () => {
-                this.sql.exec("UPDATE posts SET title = ?, surfaces = ?, head = ?, knobs = ?, description = ?, slots = ?, state = ?, updatedAt = ?, version = ?, curFrom = ?, curPrompt = ?, curAuthor = ?, curSession = ?, amendedAt = NULL WHERE id = ? AND version = ?", title, JSON.stringify(surfaces), surfaceHeads(surfaces), knobs ? JSON.stringify(knobs) : null, description ?? null, JSON.stringify(embeds), state, updatedAt, version, from, prompt, author, publishedBy, id, post.version);
+                this.sql.exec("UPDATE posts SET title = ?, surfaces = ?, head = ?, knobs = ?, description = ?, slots = ?, state = ?, updatedAt = ?, version = ?, curFrom = ?, curPrompt = ?, curAuthor = ?, curSession = ?, amendedAt = NULL, curContract = ?, curSystem = ? WHERE id = ? AND version = ?", title, JSON.stringify(surfaces), surfaceHeads(surfaces), knobs ? JSON.stringify(knobs) : null, description ?? null, JSON.stringify(embeds), state, updatedAt, version, from, prompt, author, publishedBy, contract, system, id, post.version);
                 if (this.sql.exec("SELECT changes() AS n").one().n === 0)
                     return false;
                 this.insertVersion(id, archived);
@@ -1564,9 +1673,11 @@ export class SqlStore {
                 this.touchDesign(post.design, updatedAt);
                 if (patch.surfaces !== undefined)
                     this.addAssetRefs(surfaces);
-                const { knobs: _knobs, description: _description, author: _author, publishedBy: _by, amendedAt: _amended, ...rest } = post;
+                const { knobs: _knobs, description: _description, author: _author, publishedBy: _by, amendedAt: _amended, contract: _contract, system: _system, ...rest } = post;
                 return {
                     ...rest,
+                    contract,
+                    ...(system === null ? {} : { system }),
                     title,
                     surfaces,
                     ...(knobs ? { knobs } : {}),
@@ -1601,8 +1712,10 @@ export class SqlStore {
         const author = patch.author === undefined ? post.author : stripNul(patch.author);
         const amendedAt = new Date().toISOString();
         const rewrites = (post.rewrites ?? 0) + 1;
+        const contract = patch.contract ?? CURRENT_CONTRACT;
+        const system = patch.system ?? post.system;
         const wrote = this.writingPosts(post.design, [id], () => {
-            this.sql.exec("UPDATE posts SET title = ?, surfaces = ?, head = ?, knobs = ?, description = ?, slots = ?, curFrom = ?, curPrompt = ?, curAuthor = ?, amendedAt = ?, rewrites = ? WHERE id = ? AND version = ?", title, JSON.stringify(surfaces), surfaceHeads(surfaces), knobs ? JSON.stringify(knobs) : null, description ?? null, JSON.stringify(embeds), from ?? null, prompt ?? null, author ?? null, amendedAt, rewrites, id, version);
+            this.sql.exec("UPDATE posts SET title = ?, surfaces = ?, head = ?, knobs = ?, description = ?, slots = ?, curFrom = ?, curPrompt = ?, curAuthor = ?, amendedAt = ?, rewrites = ?, curContract = ?, curSystem = ? WHERE id = ? AND version = ?", title, JSON.stringify(surfaces), surfaceHeads(surfaces), knobs ? JSON.stringify(knobs) : null, description ?? null, JSON.stringify(embeds), from ?? null, prompt ?? null, author ?? null, amendedAt, rewrites, contract, system ?? null, id, version);
             return this.sql.exec("SELECT changes() AS n").one().n > 0;
         });
         if (!wrote)
@@ -1624,17 +1737,33 @@ export class SqlStore {
             ...(author === undefined ? {} : { author }),
             amendedAt,
             rewrites,
+            contract,
+            ...(system === undefined ? {} : { system }),
         };
     }
-    async setPosterOnce(id, version, poster, mode) {
+    async setPosterOnce(id, version, poster, mode, system) {
         const post = await this.getPost(id);
         if (!post || post.version !== version)
             return false;
         const at = post.surfaces.findIndex((s) => s.kind === "html");
         const page = post.surfaces[at];
-        if (!page || page.kind !== "html" || page.poster)
+        if (!page || page.kind !== "html")
+            return false;
+        // A still mockpit took under another system revision no longer shows, so a new
+        // one may take its place; an agent's own, or a current one, stays.
+        const stale = page.posterMode !== undefined &&
+            system !== undefined &&
+            (page.posterSystem === undefined ? system > 1 : page.posterSystem !== system);
+        if (page.poster && !stale)
             return false;
-        const surfaces = post.surfaces.map((s, i) => i === at ? { ...page, poster, ...(mode ? { posterMode: mode } : {}) } : s);
+        const surfaces = post.surfaces.map((s, i) => i === at
+            ? {
+                ...page,
+                poster,
+                ...(mode ? { posterMode: mode } : {}),
+                ...(mode && system !== undefined ? { posterSystem: system } : {}),
+            }
+            : s);
         const wrote = this.writingPosts(post.design, [id], () => {
             this.sql.exec("UPDATE posts SET surfaces = ?, head = ? WHERE id = ? AND version = ?", JSON.stringify(surfaces), surfaceHeads(surfaces), id, version);
             return this.sql.exec("SELECT changes() AS n").one().n > 0;
@@ -1664,12 +1793,12 @@ export class SqlStore {
         const rewrites = (post.rewrites ?? 0) + 1;
         const hidden = (post.hiddenVersions ?? []).filter((v) => v !== version);
         this.writingPosts(post.design, [id], () => this.atomic(() => {
-            this.sql.exec("UPDATE posts SET title = ?, surfaces = ?, head = ?, slots = ?, updatedAt = ?, version = ?, curFrom = ?, curPrompt = ?, curAuthor = ?, curSession = ?, amendedAt = ?, rewrites = ?, hiddenVersions = ? WHERE id = ? AND version = ?", previous.title, JSON.stringify(previous.surfaces), surfaceHeads(previous.surfaces), JSON.stringify(embeds), previous.at, previous.version, previous.from ?? null, previous.prompt ?? null, previous.author ?? null, previous.publishedBy ?? null, previous.amendedAt ?? null, rewrites, hidden.length ? JSON.stringify(hidden) : null, id, version);
+            this.sql.exec("UPDATE posts SET title = ?, surfaces = ?, head = ?, slots = ?, updatedAt = ?, version = ?, curFrom = ?, curPrompt = ?, curAuthor = ?, curSession = ?, amendedAt = ?, rewrites = ?, hiddenVersions = ?, curContract = ?, curSystem = ? WHERE id = ? AND version = ?", previous.title, JSON.stringify(previous.surfaces), surfaceHeads(previous.surfaces), JSON.stringify(embeds), previous.at, previous.version, previous.from ?? null, previous.prompt ?? null, previous.author ?? null, previous.publishedBy ?? null, previous.amendedAt ?? null, rewrites, hidden.length ? JSON.stringify(hidden) : null, previous.contract ?? null, previous.system ?? null, id, version);
             this.sql.exec("DELETE FROM post_versions WHERE postId = ? AND version = ?", id, previous.version);
         }));
         this.touchDesign(post.design, now);
         this.invalidateAssetRefs();
-        const { from: _from, prompt: _prompt, author: _author, publishedBy: _by, amendedAt: _amended, hiddenVersions: _hidden, ...rest } = post;
+        const { from: _from, prompt: _prompt, author: _author, publishedBy: _by, amendedAt: _amended, hiddenVersions: _hidden, contract: _contract, system: _system, ...rest } = post;
         return {
             post: {
                 ...rest,
@@ -1685,6 +1814,8 @@ export class SqlStore {
                 ...(previous.publishedBy === undefined ? {} : { publishedBy: previous.publishedBy }),
                 ...(previous.amendedAt === undefined ? {} : { amendedAt: previous.amendedAt }),
                 ...(hidden.length ? { hiddenVersions: hidden } : {}),
+                ...(previous.contract === undefined ? {} : { contract: previous.contract }),
+                ...(previous.system === undefined ? {} : { system: previous.system }),
                 rewrites,
             },
         };
@@ -1809,6 +1940,8 @@ export class SqlStore {
     async listComments(query) {
         const clauses = [];
         const params = [];
+        if (query.noDesign)
+            clauses.push("designId IS NULL");
         if (query.sessionId !== undefined) {
             clauses.push("sessionId = ?");
             params.push(query.sessionId);
@@ -1916,6 +2049,12 @@ export class SqlStore {
                 postVersion: input.payload.version,
                 payload: input.payload,
             });
+            if (input.system) {
+                this.writeSystem(input.system.next, {
+                    sessionId: input.sessionId,
+                    summary: input.system.summary,
+                });
+            }
             this.sql.exec(input.keepDraft
                 ? "UPDATE designs SET asks = ? WHERE id = ?"
                 : "UPDATE designs SET asks = ?, draft = NULL WHERE id = ?", JSON.stringify(input.asks), input.designId);
@@ -1971,12 +2110,10 @@ export class SqlStore {
             .toArray()) {
             collectAttachedIds(parseJson(r.payload, null), out);
         }
-        // An installed icon set is referenced by its project's design, not by a
+        // An installed icon set is referenced by its project's system, not by a
         // surface; evicting it would blank that project's icons.
-        for (const r of this.sql
-            .exec("SELECT value FROM settings WHERE key LIKE 'design:%'")
-            .toArray()) {
-            const sets = parseJson(r.value, null)?.iconSets;
+        for (const r of this.sql.exec("SELECT json FROM systems").toArray()) {
+            const sets = parseJson(r.json, null)?.iconSets;
             for (const ref of Array.isArray(sets) ? sets : []) {
                 if (typeof ref?.assetId === "string")
                     out.add(ref.assetId);

package/dist/server/surfacePage.d.ts

@@ -1,5 +1,5 @@
 import { type IconResolver } from "./icons.ts";
-import { type DesignSystem } from "./types.ts";
+import { type System } from "./system.ts";
 import { type Mode, type Theme } from "./themes.ts";
 export declare const BRIDGE_JS = "\nwindow.sendPrompt = function (text) {\n  parent.postMessage({ __mockpit: true, type: 'send-prompt', text: String(text) }, '*');\n};\nwindow.openLink = function (url) {\n  parent.postMessage({ __mockpit: true, type: 'open-link', url: String(url) }, '*');\n};\nwindow.copyToClipboard = function (text) {\n  parent.postMessage({ __mockpit: true, type: 'copy', text: String(text) }, '*');\n};\ndocument.addEventListener('click', function (e) {\n  var a = e.target && e.target.closest ? e.target.closest('a[href]') : null;\n  if (a && /^https?:/.test(a.href)) { e.preventDefault(); window.openLink(a.href); }\n});\n// Cmd+Option+Up/Down switches sessions in the sidebar, but keydowns fire in\n// whichever document holds focus \u2014 once the user clicks into a surface, this\n// sandboxed iframe swallows them. Forward just that combo to the host.\ndocument.addEventListener('keydown', function (e) {\n  if (!e.metaKey || !e.altKey || e.ctrlKey || e.shiftKey) return;\n  if (e.key !== 'ArrowUp' && e.key !== 'ArrowDown') return;\n  e.preventDefault();\n  parent.postMessage({ __mockpit: true, type: 'switch-session', key: e.key }, '*');\n});\n// Report content height to the parent so it can size this iframe, while\n// breaking a feedback loop that can peg a CPU core.\n//\n// The loop: the parent sets the iframe's height to whatever we report, but some\n// content's height *inverts* with the frame's height \u2014 a scrollbar that appears\n// at height A reflows the content to height B, then disappears at B and reflows\n// back to A (or any 100vh / percentage-derived layout). The ResizeObserver then\n// fires on every flip, so reported heights alternate A, B, A, B... forever. With\n// a cheap surface that's a brief blip; with a heavy one (a big syntax-highlighted\n// diff/markdown surface) each relayout is expensive and the tab sits at 100% CPU\n// until the surface unmounts.\n//\n// A plain h !== __lastH guard can't stop this: in a 2-cycle every value differs\n// from the one immediately before it. So we remember the previous height too and\n// defer a return to it *if it recurs faster than a human could* (< 250ms) \u2014 that's\n// the runaway. The deferred pass keeps one trailing re-measure and reports the\n// taller height in the pair, so an ordinary font/image reflow can't leave the\n// frame permanently clipped.\nvar __lastH = 0;\nvar __prevH = 0;\nvar __lastT = 0;\nvar __seenH = 0;\nvar __trailTimer = 0;\nvar __trailH = 0;\nvar __FLIP_MS = 250;\nvar __TRAIL_MS = 350;\nfunction __now() {\n  return typeof performance !== 'undefined' && performance.now ? performance.now() : Date.now();\n}\nfunction __measureHeight() {\n  return document.body\n    ? document.body.scrollHeight\n    : document.documentElement.scrollHeight;\n}\nfunction __postHeight(h, t) {\n  __prevH = __lastH;\n  __lastH = h;\n  __lastT = t;\n  parent.postMessage({ __mockpit: true, type: 'resize', height: h }, '*');\n}\nfunction __clearTrailing() {\n  if (__trailTimer && typeof clearTimeout !== 'undefined') clearTimeout(__trailTimer);\n  __trailTimer = 0;\n  __trailH = 0;\n}\nfunction __flushTrailing() {\n  __trailTimer = 0;\n  var measured = __measureHeight();\n  if (measured > 0) __seenH = measured;\n  var target = Math.max(__trailH || 0, measured || 0);\n  __trailH = 0;\n  if (target <= 0 || target === __lastH) return;\n  __postHeight(target, __now());\n}\nfunction __scheduleTrailing(h, reset) {\n  __trailH = Math.max(__trailH || 0, h || 0, __lastH || 0);\n  if (__trailTimer) {\n    if (!reset) return;\n    if (typeof clearTimeout !== 'undefined') clearTimeout(__trailTimer);\n  }\n  __trailTimer = setTimeout(__flushTrailing, __TRAIL_MS);\n}\nfunction __report() {\n  var h = __measureHeight();\n  if (h <= 0) return; // no content yet\n  var changed = h !== __seenH;\n  __seenH = h;\n  if (h === __lastH) return; // unchanged\n  var t = __now();\n  if (h === __prevH && (__trailTimer || t - __lastT < __FLIP_MS)) {\n    __scheduleTrailing(h, true); // rapid A<->B flip: defer one settled report\n    return;\n  }\n  __clearTrailing();\n  __postHeight(h, t);\n}\nif (document.readyState === 'complete') __report();\nelse window.addEventListener('load', function () { requestAnimationFrame(__report); });\nsetTimeout(__report, 60);\nsetTimeout(__report, 350);\nsetTimeout(__report, 1500);\nsetTimeout(__report, 3000);\nsetTimeout(__report, 6000);\nsetTimeout(__report, 10000);\nif (document.fonts && document.fonts.ready && document.fonts.ready.then) {\n  document.fonts.ready.then(function () { __report(); });\n}\nif (window.ResizeObserver) {\n  window.__ssRO = new ResizeObserver(__report);\n  window.__ssRO.observe(document.documentElement);\n  if (document.body) window.__ssRO.observe(document.body);\n}\n";
 export declare const FREEZE_JS = "\n(function () {\n  if (location.hash !== '#small' || !document.getAnimations) return;\n  var QUIET_MS = 800, CAP_MS = 10000, LOAD_CAP_MS = 15000, MAX_STEP_MS = 100, RUN_MAX_MS = 30000;\n  var HELD_MAX = 32;\n  var raf = window.requestAnimationFrame.bind(window);\n  var caf = window.cancelAnimationFrame.bind(window);\n  var asked = new Map(), nextId = 0;\n  var frozen = false, loaded = false;\n  var run = 0, last = 0, settleFrom = 0, active = 0, runUntil = RUN_MAX_MS;\n  var paused = [], sweepQueued = false;\n  window.addEventListener('load', function () { loaded = true; settleFrom = run; active = run; });\n\n  function fire(id, t) {\n    var entry = asked.get(id);\n    if (!entry) return;\n    entry.native = 0;\n    if (frozen) return;\n    asked.delete(id);\n    entry.cb(t);\n  }\n  function queue(id, entry) {\n    entry.native = raf(function (t) { fire(id, t); });\n  }\n  window.requestAnimationFrame = function (cb) {\n    if (frozen && run < runUntil) thaw();\n    var id = ++nextId, entry = { cb: cb, native: 0 };\n    if (frozen && asked.size >= HELD_MAX) return id;\n    asked.set(id, entry);\n    active = run;\n    if (!frozen) queue(id, entry);\n    return id;\n  };\n  window.cancelAnimationFrame = function (id) {\n    var entry = asked.get(id);\n    if (!entry) return;\n    if (entry.native) caf(entry.native);\n    asked.delete(id);\n  };\n  if (window.webkitRequestAnimationFrame) {\n    window.webkitRequestAnimationFrame = window.requestAnimationFrame;\n    window.webkitCancelAnimationFrame = window.cancelAnimationFrame;\n  }\n\n  function own(a) { return a.timeline === document.timeline && a.effect; }\n  function ends(a) { return isFinite(a.effect.getComputedTiming().endTime); }\n  function stillDrawing() {\n    return document.getAnimations().some(function (a) {\n      return own(a) && a.playState === 'running' && ends(a);\n    });\n  }\n  function sweep() {\n    sweepQueued = false;\n    if (!frozen) return;\n    document.getAnimations().forEach(function (a) {\n      if (!own(a)) return;\n      try {\n        if (ends(a)) a.finish();\n        else if (a.playState !== 'paused') { a.pause(); a.currentTime = 0; paused.push(a); }\n      } catch (e) {}\n    });\n    Array.prototype.forEach.call(document.querySelectorAll('svg'), function (svg) {\n      if (svg.pauseAnimations) svg.pauseAnimations();\n    });\n  }\n  function queueSweep() {\n    if (frozen && !sweepQueued) { sweepQueued = true; setTimeout(sweep, 0); }\n  }\n  function freeze() { frozen = true; sweep(); }\n  function thaw() {\n    frozen = false;\n    active = settleFrom = run;\n    paused.splice(0).forEach(function (a) { try { a.play(); } catch (e) {} });\n    Array.prototype.forEach.call(document.querySelectorAll('svg'), function (svg) {\n      if (svg.unpauseAnimations) svg.unpauseAnimations();\n    });\n    asked.forEach(function (entry, id) { if (!entry.native) queue(id, entry); });\n    last = 0;\n    raf(tick);\n  }\n  function settled() {\n    return run - active >= QUIET_MS && !stillDrawing();\n  }\n  function tick(t) {\n    if (frozen) return;\n    run += last ? Math.min(t - last, MAX_STEP_MS) : 0;\n    last = t;\n    if (loaded ? settled() || run - settleFrom >= CAP_MS : run >= LOAD_CAP_MS) freeze();\n    else raf(tick);\n  }\n  new MutationObserver(function () {\n    active = run;\n    queueSweep();\n  }).observe(document, { subtree: true, childList: true, attributes: true, characterData: true });\n  document.addEventListener('animationstart', queueSweep, true);\n  document.addEventListener('transitionstart', queueSweep, true);\n  window.addEventListener('message', function (e) {\n    var d = e.data;\n    if (e.source !== window.parent || !d || d.__mockpit !== true || d.type !== 'knobs') return;\n    runUntil = run + RUN_MAX_MS;\n    if (frozen) thaw();\n  });\n  raf(tick);\n})();\n";
@@ -42,7 +42,9 @@ export declare function renderHtmlPage(doc: {
     theme?: Theme | string;
     mode?: Mode;
     kits?: string[];
-    designSystem?: DesignSystem | null;
+    system?: System | null;
+    palette?: string;
+    contract?: number;
     version?: number;
     knobs?: Record<string, unknown>;
     resolveIcon?: IconResolver;

package/dist/server/surfacePage.js

@@ -2,6 +2,7 @@ import { scanFills, slotCss } from "./fills.js";
 import { CDN_ALLOWLIST, checkCdnUrl } from "./cdn.js";
 import { CORE_CSS, KITS, kitAssets } from "./kits.js";
 import { expandIcons } from "./icons.js";
+import { CURRENT_CONTRACT, systemCss } from "./system.js";
 import { PARAGRAPH_TEXT_MAX, PARAGRAPHS_MAX } from "./types.js";
 import { schemeCss, themeById, tokenThemeCss, viewerThemeCss, } from "./themes.js";
 // The kit's two custom SVG accent ramps (teal, coral) aren't in the theme
@@ -1126,7 +1127,7 @@ export function knobAttributes(knobs) {
 const PART_HIGHLIGHT_CSS = `.mockpit-part-hl{outline:2px solid #8b7bff !important;outline-offset:2px}html.mockpit-try [data-goto]{outline:2px dashed #3fb27f !important;outline-offset:3px;cursor:pointer}`;
 // Tailwind's browser build, pinned to a major (jsdelivr is already on the CDN
 // allowlist, so this needs no CSP widening). Injected only when a project's
-// design settings say `kit: "tailwind"`, i.e. the repo itself is a Tailwind
+// system says `kit: "tailwind"`, i.e. the repo itself is a Tailwind
 // repo — so the agent writes the same classes it writes in the codebase.
 const TAILWIND_CDN = "https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4";
 // Sizing for the `<svg class="icon">` that icons.ts inlines for every
@@ -1163,6 +1164,14 @@ const PARAGRAPHS_TAG = inlineScript(PARAGRAPHS_JS);
 // The base html-surface stylesheet: static design tokens + the surface kit.
 const BASE_CSS_TAG = inlineStyle(`${TOKENS_CSS}${KIT_CSS}${PART_HIGHLIGHT_CSS}${ICON_CSS}`);
 const KIT_CORE_TAG = inlineStyle(CORE_CSS);
+const LAYER_ORDER_TAG = inlineStyle("@layer mockpit, kit, system;");
+// Tailwind's browser build declares `theme, base, components, utilities` after
+// this tag, so layers it names first would come last and preflight (`base`)
+// would undo the sheet. Naming them here keeps preflight under the sheet and
+// utilities over it, as in the repo.
+const LAYER_ORDER_TAILWIND_TAG = inlineStyle("@layer theme, base, mockpit, kit, system, components, utilities;");
+const BASE_CSS_LAYERED_TAG = inlineStyle(`@layer mockpit{${TOKENS_CSS}${KIT_CSS}${PART_HIGHLIGHT_CSS}${ICON_CSS}}`);
+const KIT_CORE_LAYERED_TAG = inlineStyle(`@layer kit{${CORE_CSS}}`);
 const versionAttr = (version) => version === undefined ? "" : ` data-mockpit-version="${version}"`;
 // The same resolution kitAssets does (known ids, first occurrence wins), but
 // yielding one stylesheet per kit instead of one concatenated string. Project
@@ -1194,33 +1203,49 @@ function resolveKits(ids, projectKits = []) {
     }
     return chosen;
 }
-// Everything a project's DesignSystem contributes to one html-surface doc.
-// Kept in one place so the ordering rule is visible: the project's own tokens
-// land AFTER mockpit's, because a repo that declares `--radius` or a brand
-// color should win inside its own project's surfaces.
-function designAssets(designSystem, mode) {
-    if (!designSystem)
-        return { css: "", kits: [], projectKits: [], headScripts: "", dark: false };
-    const tailwindCss = designSystem.kit === "tailwind" ? (designSystem.tailwindCss?.trim() ?? "") : "";
-    const raw = tailwindCss ? "" : (designSystem.cssVars?.trim() ?? "");
+// Everything a project's system contributes to one html-surface doc.
+function systemAssets(system, opts) {
+    if (!system)
+        return {
+            repoVars: "",
+            sheet: "",
+            tokens: "",
+            fonts: [],
+            kits: [],
+            projectKits: [],
+            headScripts: "",
+            tailwind: false,
+            dark: false,
+            attrs: "",
+        };
+    const repo = system.repo;
+    const tailwindCss = system.kit === "tailwind" ? (repo?.tailwindCss?.trim() ?? "") : "";
+    const raw = tailwindCss ? "" : (repo?.cssVars?.trim() ?? "");
     // `cssVars` is stored as the repo's raw block; accept either the full
     // `:root{…}` text or a bare declaration list.
     const vars = raw ? (raw.includes("{") ? raw : `:root{${raw}}`) : "";
-    const kit = designSystem.kit;
+    const kit = system.kit;
     // The browser build reads its input from the style tags present when its
     // script runs, so the stylesheet goes first. Its compiled output already
     // carries the repo's `:root` block, hence no `cssVars` beside it.
     const tailwind = kit !== "tailwind"
         ? ""
         : `${tailwindCss ? `<style type="text/tailwindcss">${tailwindCss.replace(/<\/style/gi, "<\\/style")}</style>\n` : ""}<script src="${TAILWIND_CDN}"></script>`;
+    const css = systemCss(system, opts);
     return {
-        css: vars,
+        repoVars: vars,
+        sheet: css.sheet.replace(/<\/style/gi, "<\\/style"),
+        tokens: css.tokens,
+        fonts: css.fonts,
         kits: kit && kit !== "tailwind" && kit !== "none" ? [kit] : [],
-        projectKits: Array.isArray(designSystem.projectKits) ? designSystem.projectKits : [],
+        projectKits: Array.isArray(system.projectKits) ? system.projectKits : [],
         headScripts: tailwind,
+        tailwind: kit === "tailwind",
         // Repos theme dark through a `.dark` ancestor (shadcn's `.dark {…}` block,
         // `@custom-variant dark (&:is(.dark *))`), so the frame wears the class.
-        dark: mode === "dark" && /\.dark\b/.test(tailwindCss || raw),
+        dark: (css.attrs.scheme ?? opts.mode) === "dark" && /\.dark\b/.test(tailwindCss || raw),
+        attrs: `${css.attrs.scheme ? ` data-scheme="${css.attrs.scheme}"` : ""}${css.attrs.palette ? ` data-palette="${escapeHtml(css.attrs.palette)}"` : ""}`,
+        ...(css.attrs.scheme ? { scheme: css.attrs.scheme } : {}),
     };
 }
 export const escapeHtml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
@@ -1453,29 +1478,52 @@ ${PARAGRAPHS_TAG}
 }
 export function renderHtmlPage(doc) {
     const theme = typeof doc.theme === "string" || doc.theme == null ? themeById(doc.theme) : doc.theme;
-    const designSystem = designAssets(doc.designSystem, doc.mode);
+    const contract = doc.contract ?? CURRENT_CONTRACT;
+    const project = systemAssets(doc.system, { mode: doc.mode, palette: doc.palette, contract });
     const preamble = knobPreamble(doc.version, doc.knobs);
-    const htmlTag = designSystem.dark
+    let htmlTag = project.dark
         ? preamble.htmlTag.replace("<html ", '<html class="dark" ')
         : preamble.htmlTag;
+    if (project.attrs && contract >= 2)
+        htmlTag = htmlTag.replace("<html ", `<html${project.attrs} `);
     // The project kit is appended, so with both present its components win over
     // a surface-requested kit's same-named classes.
-    const kitIds = [...(doc.kits ?? []), ...designSystem.kits];
-    const kits = resolveKits(kitIds, designSystem.projectKits);
+    const kitIds = [...(doc.kits ?? []), ...project.kits];
+    const kits = resolveKits(kitIds, project.projectKits);
     const kit = kitAssets(kitIds);
-    // Document order decides the cascade: theme tokens, base, kit accents, kit(s),
-    // then the project's own vars (which must win last).
-    const styles = [
-        `<style>${tokenThemeCss(theme, doc.mode)}</style>`,
-        BASE_CSS_TAG,
-        `<style>${kitAccentCss(doc.mode)}</style>`,
-        ...(kits.some((k) => !k.href) ? [KIT_CORE_TAG] : []),
-        ...kits.flatMap((k) => [
-            ...(k.href ? [`<link rel="stylesheet" href="${escapeHtml(k.href)}">`] : []),
-            ...(k.css ? [inlineStyle(k.css)] : []),
-        ]),
-        `<style>${designSystem.css}${colorSchemeCss(doc.mode)}</style>`,
-    ].join("\n");
+    const scheme = colorSchemeCss(project.scheme ?? doc.mode);
+    const fonts = project.fonts.map((href) => `<link rel="stylesheet" href="${escapeHtml(href)}">`);
+    const styles = contract >= 2
+        ? // Layers decide the cascade: mockpit's own styles, then kits, then the
+            // project sheet. The tokens and the page are unlayered, so they win
+            // over all three without extra specificity.
+            [
+                project.tailwind ? LAYER_ORDER_TAILWIND_TAG : LAYER_ORDER_TAG,
+                `<style>@layer mockpit{${tokenThemeCss(theme, doc.mode)}${kitAccentCss(doc.mode)}}</style>`,
+                BASE_CSS_LAYERED_TAG,
+                ...(kits.some((k) => !k.href) ? [KIT_CORE_LAYERED_TAG] : []),
+                ...kits.flatMap((k) => [
+                    ...(k.href ? [`<style>@import url("${escapeHtml(k.href)}") layer(kit);</style>`] : []),
+                    ...(k.css ? [inlineStyle(`@layer kit{${k.css}}`)] : []),
+                ]),
+                ...(project.sheet ? [`<style>@layer system{${project.sheet}}</style>`] : []),
+                `<style>${project.repoVars}${project.tokens}${scheme}</style>`,
+                ...fonts,
+            ].join("\n")
+        : // Document order decides the cascade: theme tokens, base, kit accents,
+            // kit(s), then the project's own vars (which must win last).
+            [
+                `<style>${tokenThemeCss(theme, doc.mode)}</style>`,
+                BASE_CSS_TAG,
+                `<style>${kitAccentCss(doc.mode)}</style>`,
+                ...(kits.some((k) => !k.href) ? [KIT_CORE_TAG] : []),
+                ...kits.flatMap((k) => [
+                    ...(k.href ? [`<link rel="stylesheet" href="${escapeHtml(k.href)}">`] : []),
+                    ...(k.css ? [inlineStyle(k.css)] : []),
+                ]),
+                `<style>${project.repoVars}${project.sheet}${project.tokens}${scheme}</style>`,
+                ...fonts,
+            ].join("\n");
     // Slots (fills.ts): only the chosen fill of each shows, keyed on the knob
     // attribute; with no value yet, the default fill.
     const fillCss = slotCss(scanFills(doc.html).slots);
@@ -1491,7 +1539,7 @@ ${preamble.headScript}
 ${KNOBS_TAG}
 ${styles}
 ${fillCss ? `<style>${fillCss}</style>` : ""}
-${designSystem.headScripts}
+${project.headScripts}
 ${kits.flatMap((k) => (k.script ? [`<script src="${escapeHtml(k.script)}" defer></script>`] : [])).join("\n")}
 </head>
 <body>