dsh-claude-design 2.6.0 → 2.7.0

package/lib/index.js

@@ -1,16 +1,189 @@
-// dsh-claude-design 2.6.0: built from baoyu-design.
+// dsh-claude-design 2.7.0: built from baoyu-design.
 var define_PLUGIN_default = { name: "claude-design", provider: "dsh-claude-design", skills: [{ name: "claude-design", description: "Make and revise designs in the Design (canvas) artifact format (project/canvas.json plus one .dc.html Design Component file per artboard) as local files, then open them in a local canvas editor where the user can view the artboards side by side, retype copy and adjust tweaks. Use when the user asks for an editable canvas of artboards in this format, names claude-design or the Design (canvas) type, or wants to revise a folder that holds project/canvas.json. A one-off HTML prototype or design exploration outside this format is baoyu-design's.", comments: true }] };
-import { spawn } from "node:child_process";
+
+import { spawn as spawn2 } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { statSync } from "node:fs";
 import { readFile } from "node:fs/promises";
-import { delimiter, dirname, isAbsolute, join, sep } from "node:path";
+import { delimiter, dirname, isAbsolute, join as join2, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-const PLUGIN = define_PLUGIN_default;
-const name = PLUGIN.name;
-const inject = ["skills"];
-const BUNDLED_SKILL_RANK = 600;
-const packageRoot = fileURLToPath(new URL("../", import.meta.url));
+
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+
+var listPath = (skill) => `/api/baoyu-design.${skill}.artifacts`;
+var openPath = (skill) => `/api/baoyu-design.${skill}.artifacts.open`;
+
+var TITLES = {
+  "claude-slides": ["project/deck.json", "title"],
+  "claude-design": ["project/canvas.json", "title"],
+  "claude-design-system": ["project/design-system.json", "title"],
+  "claude-dashboard": ["db/dash/meta.json", "title"],
+  "claude-docs": ["doc.json", "name"],
+  "claude-motion": ["db/film/meta.json", "title"]
+};
+var OPEN_TIMEOUT_MS = 3e4;
+function dshHome() {
+  const set = process.env.DSH_HOME?.trim();
+  return set ? set : join(homedir(), ".dsh");
+}
+function artifactsDir() {
+  return join(dshHome(), "baoyu-design", "artifacts");
+}
+function recordFile(root) {
+  return join(artifactsDir(), `${createHash("sha256").update(root).digest("hex").slice(0, 24)}.json`);
+}
+function artifactTitle(skill, root) {
+  const at = TITLES[skill];
+  if (at === void 0) return null;
+  try {
+    const value = JSON.parse(readFileSync(join(root, at[0]), "utf8"))[at[1]];
+    const title = typeof value === "string" ? value.trim() : "";
+    if (title && title !== "project") return title;
+  } catch {
+  }
+  return basename(root);
+}
+function isRecord(value) {
+  const r = value;
+  return typeof r === "object" && r !== null && r.v === 1 && typeof r.root === "string" && typeof r.skill === "string" && typeof r.plugin === "string" && typeof r.sessionId === "string" && typeof r.title === "string" && typeof r.openedAt === "string";
+}
+function readRecord(file) {
+  try {
+    const value = JSON.parse(readFileSync(file, "utf8"));
+    return isRecord(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+function recordOpened(skill, plugin, sessionId, root, now = /* @__PURE__ */ new Date()) {
+  const file = recordFile(root);
+  const before = readRecord(file);
+  const record = {
+    v: 1,
+    root,
+    skill,
+    plugin,
+    sessionId,
+    title: artifactTitle(skill, root) ?? before?.title ?? basename(root),
+    openedAt: now.toISOString(),
+    firstOpenedAt: before?.root === root ? before.firstOpenedAt ?? before.openedAt : now.toISOString()
+  };
+  mkdirSync(artifactsDir(), { recursive: true });
+  const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+  writeFileSync(tmp, `${JSON.stringify(record, null, 2)}
+`);
+  renameSync(tmp, file);
+  return record;
+}
+function listArtifacts() {
+  let names;
+  try {
+    names = readdirSync(artifactsDir());
+  } catch {
+    return [];
+  }
+  const views = [];
+  for (const name2 of names) {
+    if (!name2.endsWith(".json")) continue;
+    const record = readRecord(join(artifactsDir(), name2));
+    if (record === null || !existsSync(record.root)) continue;
+    views.push({
+      root: record.root,
+      skill: record.skill,
+      plugin: record.plugin,
+      sessionId: record.sessionId,
+      title: artifactTitle(record.skill, record.root) ?? record.title,
+      openedAt: record.openedAt
+    });
+  }
+  return views.sort((a, b) => a.openedAt < b.openedAt ? 1 : a.openedAt > b.openedAt ? -1 : 0);
+}
+function findArtifact(root) {
+  const record = readRecord(recordFile(root));
+  return record?.root === root ? record : null;
+}
+function scriptEnv(node) {
+  const env = { ...process.env };
+  if (node.env) {
+    const [name2, value] = node.env.split("=");
+    if (name2) env[name2] = value ?? "";
+  }
+  return env;
+}
+function runOpen(node, script, root) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(node.path, [script, "open", root], { env: scriptEnv(node), stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    let stdout = "";
+    let stderr = "";
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(new Error("the editor did not start in time"));
+    }, OPEN_TIMEOUT_MS);
+    child.stdout?.setEncoding("utf8").on("data", (chunk) => stdout += chunk);
+    child.stderr?.setEncoding("utf8").on("data", (chunk) => stderr += chunk);
+    child.on("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      const out = firstJson(stdout);
+      if (code === 0 && typeof out?.url === "string") return resolve({ url: out.url, reused: out.reused === true });
+      const failure = firstJson(stderr);
+      const message = typeof failure?.message === "string" ? failure.message : stderr.trim() || `open exited with ${code ?? "a signal"}`;
+      reject(new Error(message));
+    });
+  });
+}
+function firstJson(text) {
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  if (start < 0 || end <= start) return null;
+  try {
+    const value = JSON.parse(text.slice(start, end + 1));
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+var json = (body, status = 200) => Response.json(body, { status, headers: { "cache-control": "no-store" } });
+function registerRoutes(routes, skill, opened) {
+  routes.register({
+    path: listPath(skill.name),
+    methods: ["GET"],
+    requestBody: "buffered",
+    fetch: () => Promise.resolve(json({ artifacts: listArtifacts() }))
+  });
+  routes.register({
+    path: openPath(skill.name),
+    methods: ["POST"],
+    requestBody: "buffered",
+    fetch: async (request) => {
+      const root = new URL(request.url).searchParams.get("root") ?? "";
+      const record = root ? findArtifact(root) : null;
+      if (record === null || record.skill !== skill.name) return json({ error: "not a recorded artifact of this skill" }, 404);
+      if (!existsSync(root)) return json({ error: "the folder is gone" }, 404);
+      try {
+        const { url, reused } = await runOpen(skill.node, skill.script, root);
+        const again = recordOpened(skill.name, skill.plugin, record.sessionId, root);
+        opened(again);
+        return json({ url, reused, sessionId: again.sessionId, title: again.title });
+      } catch (error) {
+        return json({ error: error.message }, 500);
+      }
+    }
+  });
+}
+
+var PLUGIN = define_PLUGIN_default;
+var name = PLUGIN.name;
+var inject = ["skills"];
+var BUNDLED_SKILL_RANK = 600;
+var packageRoot = fileURLToPath(new URL("../", import.meta.url));
 function isFile(path) {
   try {
     return statSync(path).isFile();
@@ -33,18 +206,18 @@ function resolveNode(config = {}) {
   if (typeof resourcesPath === "string") roots.push(resourcesPath);
   let dir = dirname(process.execPath);
   for (let i = 0; i < 6; i++) {
-    roots.push(join(dir, "Resources"), join(dir, "resources"));
+    roots.push(join2(dir, "Resources"), join2(dir, "resources"));
     const parent = dirname(dir);
     if (parent === dir) break;
     dir = parent;
   }
   for (const root of roots) {
-    const candidate = join(root, ...runtime);
+    const candidate = join2(root, ...runtime);
     if (isFile(candidate)) return { path: candidate, from: "desktop runtime" };
   }
   for (const entry of (process.env.PATH ?? "").split(delimiter)) {
     if (entry === "" || !isAbsolute(entry)) continue;
-    const candidate = join(entry, exe);
+    const candidate = join2(entry, exe);
     if (isFile(candidate)) return { path: candidate, from: "PATH" };
   }
   return { path: process.execPath, env: "ELECTRON_RUN_AS_NODE=1", from: "electron" };
@@ -53,7 +226,7 @@ function shellQuote(path) {
   return `"${path.replace(/(["\\$`])/g, "\\$1")}"`;
 }
 function runtimeSection(skill, skillDir, node) {
-  const script = join(skillDir, "scripts", "artifact.mjs");
+  const script = join2(skillDir, "scripts", "artifact.mjs");
   const run = (...args) => [node.env, shellQuote(node.path), shellQuote(script), ...args].filter(Boolean).join(" ");
   const written = skill.scriptAlias === void 0 ? "`node <this skill's folder>/scripts/artifact.mjs <command>`" : `\`node $${skill.scriptAlias} <command>\` (\`${skill.scriptAlias}\` being \`<this skill's folder>/scripts/artifact.mjs\`)`;
   const lines = [
@@ -97,14 +270,15 @@ function runtimeSection(skill, skillDir, node) {
   }
   return lines.join("\n");
 }
-const COMMENT_SOURCE = "baoyu-design-comment";
-const SUMMARY_MAX = 120;
-const SESSION_CHECK_MS = 6e4;
-const RETRY_MS = 5e3;
-const MAX_QUICK_FAILURES = 3;
-const IDLE_CHECK_MS = 500;
-const TURN_START_MS = 3e3;
-const TURN_MAX_MS = 30 * 6e4;
+var COMMENT_SOURCE = "baoyu-design-comment";
+var SUMMARY_MAX = 120;
+var SESSION_CHECK_MS = 6e4;
+var RETRY_MS = 5e3;
+var MAX_QUICK_FAILURES = 3;
+var IDLE_CHECK_MS = 500;
+var AGENT_GRACE_MS = 3e4;
+var TURN_START_MS = 3e3;
+var TURN_MAX_MS = 30 * 6e4;
 function jsonObject(text) {
   const trimmed = text.trim();
   const starts = [0];
@@ -122,6 +296,40 @@ function jsonObject(text) {
   }
   return null;
 }
+function jsonEnd(text, start) {
+  let depth = 0;
+  let inString = false;
+  for (let i = start; i < text.length; i++) {
+    const c = text[i];
+    if (inString) {
+      if (c === "\\") i++;
+      else if (c === '"') inString = false;
+    } else if (c === '"') inString = true;
+    else if (c === "{" || c === "[") depth++;
+    else if ((c === "}" || c === "]") && --depth === 0) return i;
+  }
+  return -1;
+}
+function jsonObjects(text) {
+  const found = [];
+  const starts = text.startsWith("{") ? [0] : [];
+  for (let i = text.indexOf("\n{"); i >= 0; i = text.indexOf("\n{", i + 1)) starts.push(i + 1);
+  let after = 0;
+  for (const start of starts) {
+    if (start < after) continue;
+    const end = jsonEnd(text, start);
+    if (end < 0) continue;
+    try {
+      const value = JSON.parse(text.slice(start, end + 1));
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        found.push(value);
+        after = end + 1;
+      }
+    } catch {
+    }
+  }
+  return found;
+}
 function bashStdout(result) {
   const value = result.value;
   if (typeof value === "string") return value;
@@ -132,7 +340,19 @@ function bashStdout(result) {
   const text = result.content.map((block) => block.type === "text" ? block.text ?? "" : "").join("\n");
   return text || null;
 }
-const bound = (text) => text.length <= SUMMARY_MAX ? text : `${text.slice(0, SUMMARY_MAX - 1)}…`;
+function openedEditor(script, exec, result) {
+  if (exec.name !== "bash" || exec.agent === void 0 || result.isError) return null;
+  const args = exec.arguments;
+  const command = args?.command;
+  if (typeof command !== "string" || args?.run_in_background === true) return null;
+  const at = command.indexOf(script);
+  if (at < 0 || !/(?:^|[\s"'])open(?:[\s"']|$)/.test(command.slice(at + script.length))) return null;
+  const stdout = bashStdout(result);
+  const opened = stdout === null ? void 0 : jsonObjects(stdout).findLast((o) => typeof o.root === "string" && typeof o.url === "string");
+  if (typeof opened?.root !== "string" || typeof opened.url !== "string") return null;
+  return { session: String(exec.agent.id), root: opened.root, url: opened.url };
+}
+var bound = (text) => text.length <= SUMMARY_MAX ? text : `${text.slice(0, SUMMARY_MAX - 1)}…`;
 function commentMessage(skill, plugin, out, root) {
   const title = typeof out.title === "string" && out.title ? out.title : root.split(/[\\/]/).pop() || root;
   const url = typeof out.url === "string" ? out.url : "";
@@ -183,7 +403,7 @@ function commentMessage(skill, plugin, out, root) {
   };
   return Object.freeze(message);
 }
-class CommentWatcher {
+var CommentWatcher = class {
   watches = /* @__PURE__ */ new Map();
   check;
   ctx;
@@ -204,23 +424,10 @@ class CommentWatcher {
   agent(session) {
     return this.ctx.get("agents")?.get(session);
   }
-  /** The agent ran this skill's `open`: see whether its output names an editor, and wait for its comments. */
-  observe(exec, result) {
-    if (exec.name !== "bash" || exec.agent === void 0 || result.isError) return;
-    const args = exec.arguments;
-    const command = args?.command;
-    if (typeof command !== "string" || args?.run_in_background === true) return;
-    const at = command.indexOf(this.script);
-    if (at < 0 || !/(?:^|[\s"'])open(?:[\s"']|$)/.test(command.slice(at + this.script.length))) return;
-    const stdout = bashStdout(result);
-    const opened = stdout === null ? null : jsonObject(stdout);
-    if (typeof opened?.root !== "string" || typeof opened.url !== "string") return;
-    this.watch(String(exec.agent.id), opened.root);
-  }
   watch(session, root) {
     const key = `${session}\0${root}`;
     if (this.watches.has(key)) return;
-    const watch = { child: null, stopped: false, quickFailures: 0 };
+    const watch = { child: null, stopped: false, quickFailures: 0, graceUntil: Date.now() + AGENT_GRACE_MS };
     this.watches.set(key, watch);
     this.log("info", `waiting for comments on ${root}`);
     this.run(key, session, root, watch);
@@ -235,15 +442,15 @@ class CommentWatcher {
     this.log("info", `stopped waiting for comments (${why})`);
   }
   run(key, session, root, watch) {
+    watch.retry = void 0;
     if (watch.stopped) return;
-    if (this.agent(session) === void 0) return this.stop(key, watch, "the session is gone");
-    const env = { ...process.env };
-    if (this.node.env) {
-      const [name2, value] = this.node.env.split("=");
-      if (name2) env[name2] = value ?? "";
+    if (this.agent(session) === void 0) {
+      if (Date.now() >= watch.graceUntil) return this.stop(key, watch, "the session is gone");
+      watch.retry = setTimeout(() => this.run(key, session, root, watch), IDLE_CHECK_MS);
+      return;
     }
     const started = Date.now();
-    const child = spawn(this.node.path, [this.script, "comments", root, "--wait"], { env, stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+    const child = spawn2(this.node.path, [this.script, "comments", root, "--wait"], { env: scriptEnv(this.node), stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
     watch.child = child;
     let stdout = "";
     let stderr = "";
@@ -302,14 +509,14 @@ class CommentWatcher {
   dropGoneSessions() {
     for (const [key, watch] of [...this.watches]) {
       const session = key.slice(0, key.indexOf("\0"));
-      if (this.agent(session) === void 0) this.stop(key, watch, "the session is gone");
+      if (this.agent(session) === void 0 && Date.now() >= watch.graceUntil) this.stop(key, watch, "the session is gone");
     }
   }
   dispose() {
     clearInterval(this.check);
     for (const [key, watch] of [...this.watches]) this.stop(key, watch, "the plugin stopped");
   }
-}
+};
 function skillBody(raw, path) {
   const frontmatter = /^---\r?\n[\s\S]*?\r?\n---(?:\r?\n|$)/u.exec(raw);
   if (frontmatter === null) throw new Error(`${PLUGIN.name}: ${path} has no YAML frontmatter`);
@@ -319,8 +526,8 @@ function apply(ctx, config = {}) {
   const node = resolveNode(config ?? {});
   const skills = new Map(PLUGIN.skills.map((skill) => [skill.name, skill]));
   const candidates = PLUGIN.skills.map(({ name: skillName, description }) => {
-    const directory = join(packageRoot, "skills", skillName);
-    const path = join(directory, "SKILL.md");
+    const directory = join2(packageRoot, "skills", skillName);
+    const path = join2(directory, "SKILL.md");
     if (!isFile(path)) throw new Error(`${PLUGIN.name}: ${path} is missing`);
     return {
       name: skillName,
@@ -347,11 +554,24 @@ function apply(ctx, config = {}) {
   };
   ctx.skills.registerProvider(() => provider);
   for (const skill of PLUGIN.skills) {
-    if (!skill.comments) continue;
-    const script = join(packageRoot, "skills", skill.name, "scripts", "artifact.mjs");
-    const watcher = new CommentWatcher(ctx, skill, script, node);
-    ctx.on("tools/result", (exec, result) => watcher.observe(exec, result));
-    ctx.effect(() => () => watcher.dispose(), `${PLUGIN.name}: comment waits`);
+    const script = join2(packageRoot, "skills", skill.name, "scripts", "artifact.mjs");
+    const watcher = skill.comments ? new CommentWatcher(ctx, skill, script, node) : null;
+    if (watcher) ctx.effect(() => () => watcher.dispose(), `${PLUGIN.name}: comment waits`);
+    ctx.on("tools/result", (exec, result) => {
+      const opened = openedEditor(script, exec, result);
+      if (opened === null) return;
+      watcher?.watch(opened.session, opened.root);
+      try {
+        recordOpened(skill.name, PLUGIN.provider, opened.session, opened.root);
+      } catch (error) {
+        ctx.logger?.warn?.(`${PLUGIN.name}: could not note ${opened.root} for the Artifacts page: ${error.message}`);
+      }
+    });
+    ctx.inject?.(["connection"], (sub) => {
+      registerRoutes(sub.connection.fetch, { name: skill.name, plugin: PLUGIN.provider, script, node }, (record) => {
+        watcher?.watch(record.sessionId, record.root);
+      });
+    });
   }
 }
 export {
@@ -360,7 +580,9 @@ export {
   commentMessage,
   inject,
   jsonObject,
+  jsonObjects,
   name,
+  openedEditor,
   resolveNode,
   runtimeSection
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-claude-design",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "description": "DeepSeek Harness plugin: the claude-design skill from baoyu-design. The agent writes canvases of artboards as files and opens them in a local canvas editor.",
   "keywords": [
     "dsh",
@@ -51,11 +51,17 @@
     "client": {
       "platform": "web",
       "inject": [
+        "@deepseek-ai/dsh-api-session-controller",
+        "@deepseek-ai/dsh-api-workspace-controller",
+        "@deepseek-ai/dsh-client-connection",
         "@deepseek-ai/dsh-client-locale",
         "@deepseek-ai/dsh-client-ui-chat",
         "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-layout",
         "@deepseek-ai/dsh-client-ui-renderer",
-        "@deepseek-ai/dsh-client-ui-sidebar-right"
+        "@deepseek-ai/dsh-client-ui-sidebar",
+        "@deepseek-ai/dsh-client-ui-sidebar-right",
+        "@deepseek-ai/dsh-client-ui-workspace"
       ]
     }
   }

package/skills/claude-design/SKILL.md

@@ -63,6 +63,8 @@ leave alone stays as it is, and removing an artboard's file is deleting it. The
 - `check <root>` → `problems` (0: done); when any, `issues`, each a `file` under `project/` and its fix; `designSystemNotes` when an install looks incomplete; it exits 1 while problems remain. It reads the files only: whether scripts run and how the layout looks is not checked.
 - `open <root>` → `{url, pid, stop, …}`: starts the editor page on this machine in the background (once; later calls reuse it, `reused: true`) and prints its address, 127.0.0.1:4720 (the next free port up when 4720 is taken; `--port n` starts from n, `--port 0` takes any). `stop <root>` ends it (`serve <root>` runs it in the foreground instead). The page saves the user's edits into the same files, and shows yours as soon as you write them. `.artifact-server.json` and `.artifact-server.log` beside `project/` are its own: leave them; so is `comments.json` (the comments, see Comments), which only the comment commands below change.
 - `share <root>` (or `open <root> --lan`): opens the page to the local network and prints a link per role (Sharing, below).
+- `archive <root> [--out file.zip|dir]` → `{file, files, bytes, open}`: the whole folder, history and comments too, as one zip beside it (`--out`: another file or folder), to back it up, move it to another computer or send it to someone; unzipped anywhere, `open` carries on. The owner's Download folder button in the page (between History and Share) does the same. The server's own files and the share links stay out.
+- The Theme tab links to a read-only page of the system in use, `<editor>/__ds/<folder>/`: the copy under `project/ds/<folder>/` as this canvas carries it (its tokens, its components with their `README.md` and types, its `README.md`). Anyone who can open the canvas can open it, and it changes only when the copy does.
 
 ## One artboard: the skeleton
 
@@ -173,7 +175,7 @@ People comment in the open editor: Comment (or C), then a click on anything on a
 - `share <root> --disable <role>` / `--enable <role>` turns a link off or on (`<role>`: one, `editor,viewer`, or `all`); off, it holds everyone who came by it until it is on again. `--reset <role>` gives the role a new link: the old one stops working and the people who came by it are out. `--role <guest>=<role>` gives someone who joined another role (`<guest>`: an id from the `guests` it prints). `--off` stops sharing on the network.
 - Who is here: while someone else has the canvas open, their avatars sit before History; each one's card says which artboard they are working in and whether they are editing, and the canvas shows their cursors and selections. Someone editing an artboard you have in view gets you a short note; nothing is locked (two people on one artboard: see History). After you change a file you show there as Agent for about 20 s.
 - Only the owner's page sends to you (Send to Agent); what guests comment is saved for you to read with `comments <root>`.
-- The links and the people who joined are in `<root>/.sharing.json`: leave it. It is plain http on the local network: anyone there with a link gets in.
+- The links and the people who joined are in `<root>/.sharing.json`: leave it. It is plain http on the local network: anyone there can read what passes, and a link is the permission: whoever has one gets its role, so send each only to the people meant to have it, and `--reset` a role's link that went further (the Share panel says so too). When this computer has a Tailscale address (100.64.0.0/10), `share` also prints `tailscale`: the same links at that address, for people on the owner's tailnet from any network (the Share panel: Copy Tailscale link in a link's More menu). Nothing else reaches past the local network; there is no tunnel.
 
 ## History
 
@@ -185,6 +187,24 @@ The server keeps the canvas's versions in `<root>/history/` (leave it): who chan
 - Two people on one artboard: when the page has unsaved edits on an artboard someone else just saved, the two are merged element by element: changes to different elements both stay, and where both changed the same thing the page's change wins ("Yours was kept") and the other person gets a notice. When the merge cannot work it out (an element added, removed or moved on one side while the other edited, both changed its script or head, or the artboard was deleted), a bar names who and which artboard, and nothing is saved until the person picks Use theirs (the page's edits on it go; for a deleted artboard, it is deleted here too), Keep mine (saved over theirs) or Keep both (the artboard takes theirs; the page's version becomes a new artboard beside it, `<name>-my-copy.dc.html`). A version saved over someone's change records whose change it replaced, and that person gets a notice on the page (Compare, Bring back, Dismiss). Compare shows only what that save replaced, and Bring back puts only that back: the other person's changes elsewhere on the artboard stay, and History says "Partly restored". It goes line by line in the file, so two changes on one line come back together. When that drops a change of theirs, the other person gets "Put my change back", which saves over it and counts as replacing a change again (their notice then brings back only what that replaced). Your changes on disk count too: they go through the same merge, and someone editing that artboard may get the bar with "Agent" and keep theirs, so check the file (or History) when it matters.
 - Asked who changed something, read `<root>/history/index.json`: `versions`, oldest first, each `{n, at, by, user: {name}, changes}` (`by`: `"human"`, `"agent"` for you, `"system"` for the first; `changes`: path → sha256, null for a delete; paths like `project/<name>.dc.html`, `project/canvas.json`), with `restoredFrom` or `overwrote` when it brought a version back or replaced someone's change; a content is `<root>/history/objects/<sha256>`, the file's bytes. To put something back, point the person to History (it records who did it), or write the old content yourself, which makes a version of yours.
 
+## Keeping it in git
+
+`open` writes `<root>/.gitignore` when the folder has none. It leaves out what only this computer's server needs:
+`.artifact-server.json`, `.artifact-server.log`, `.sharing.json` (the share links), `history/` (the versions; git
+keeps its own), save temp files and `.DS_Store`. Everything else, `project/` and `comments.json` included, is the
+canvas and goes in git. A `.gitignore` already there is the person's: leave it. Moving or backing up the canvas is
+copying or cloning the folder (`archive` puts it,
+history included, in one zip); `open` there starts it again.
+
+Commit, push or set up git only when asked. Asked to check the canvas before each commit: write
+`.git/hooks/pre-commit` (and `chmod +x` it) in the repository that holds `<root>`, with this skill's folder as an
+absolute path and `<root>` relative to the repository's top (a hook already there: add the line to it):
+
+```sh
+#!/bin/sh
+node "<this skill's folder>/scripts/artifact.mjs" check "<root>" > /dev/null || { echo "The canvas has problems: run artifact.mjs check <root> to see them." >&2; exit 1; }
+```
+
 ## The references
 
 Under `artifact-type/reference/` in this skill's folder: `format.md` (before a first artboard), `craft.md`, `diagrams.md` (FIRST for diagrams), `print.md` (FIRST for print), `questions.md`, `view-state.md` (before

package/skills/claude-design/artifact-type/reference/print.md

@@ -62,13 +62,19 @@ canvas made from the type, the same keys of its `boards` entry in `project/canva
   there, not on an inner box.
 - Breaks are placed by the exporter, not by CSS: it cuts BETWEEN text
   lines and never through an `<img>`/`<svg>` (place photos as `<img>`,
-  never `background-image` — those get cut); nothing else is kept whole —
-  a bordered box, table or card can split between two of its lines.
-  `break-before/inside`, `orphans`/`widows`, `@page` and a repeating
-  `<thead>` do nothing here, and you cannot force a new page. Keep each
-  figure + caption well under a page; a caption can still land on the next
-  page, and an image taller than ≈950px is cut where the page ends. Where
-  a split or a forced page start matters, make a Fixed series instead.
+  never `background-image` — those get cut). A heading (h1–h6) is kept
+  whole and on the same page as the first line after it, along with a
+  short line just above it such as a section number, and a table's
+  `<caption>` and `<thead>` row stay with the row they label, except
+  where that would leave more than a quarter of a page empty. Nothing
+  else is kept whole — a bordered box, table or card can split between two of
+  its lines. `break-before/inside`, `orphans`/`widows` and `@page` do
+  nothing here, a `<thead>` is not repeated on later pages, and you
+  cannot force a new page. A `<figcaption>` above its image stays with
+  it; one below an image taller than ≈230px can land alone on the next
+  page, so caption tall images from above. An image taller than ≈950px
+  is cut where the page ends. Where a split or a forced page start
+  matters, make a Fixed series instead.
 - ONE column of running text: CSS `columns` and side-by-side text columns
   run the whole document's height and are sliced across pages — use them
   only inside a block shorter than a page.