diffing 0.18.2 → 0.18.3

package/dist/{cli-agent-Cpusc3Fl.mjs → cli-agent-DV5ZhMX1.mjs}

@@ -1,6 +1,6 @@
 import { f as getProjectStorageDir, h as getRepoRoot } from "./git-BGj31GX-.mjs";
 import { i as loadSettings, n as formatModeLabel, s as saveSettings } from "./settings-DIa-3C8o.mjs";
-import { f as slugifyScreenId, r as formatPlanReview, t as formatMockupReview } from "./mockup-format-Dzc3e_10.mjs";
+import { a as formatPlanReview, m as slugifyScreenId, r as formatMockupReview, t as formatSubmitHints } from "./mockup-lint-BRjhxXSw.mjs";
 import { t as formatComments } from "./comment-format-DS1wOWj_.mjs";
 import { u as resolveActiveServerLock, x as SESSION_TOKEN_HEADER } from "./server-lock-ACw2cKDI.mjs";
 import { i as reviewSessionUrl, t as appendSessionToken } from "./session-url-CyBpcLAH.mjs";
@@ -1146,6 +1146,13 @@ function warnMockupPathsInRepo(paths) {
 		if (abs === root || abs.startsWith(rootPrefix)) console.error(`Warning: ${abs} is inside the consumer repo. Never write diffing mockups into the working tree. Submit HTML via stdin or MCP submit_mockup({ html }), or stage files under ${storage}/mockup-sources/.`);
 	}
 }
+function printMockupHints(payload) {
+	if (!payload || typeof payload !== "object") return;
+	const hints = payload.hints;
+	if (!hints?.length) return;
+	const text = formatSubmitHints(hints).trim();
+	if (text) console.error(text);
+}
 async function mockupSubmit(args) {
 	const { values, positionals } = parseArgs({
 		args,
@@ -1218,6 +1225,7 @@ async function mockupSubmit(args) {
 	const mockup = await submitRes.json();
 	console.error(`Submitted mockup ${mockup.id} (v${mockup.version}) — review at ${appendSessionToken(`${base}/mockup/${mockup.id}`, activeAuthToken)}`);
 	if (mockup.sourcePath) console.error(`Source path: ${mockup.sourcePath}`);
+	printMockupHints(mockup);
 	if (!values.wait) {
 		console.error(CLI_MOCKUP_SUBMIT_PARK_HINT);
 		process.stdout.write(mockup.id + "\n");
@@ -1579,6 +1587,7 @@ One-screen revision. Version bumps on success; an --expected-version guard abort
 		}
 		const mockup = await res.json();
 		console.error(`Upserted screen ${screenId} on ${mockupId} → v${mockup.version} (${mockup.screens.length} screens).`);
+		printMockupHints(mockup);
 		return EXIT_OK;
 	}
 	if (action === "remove") {
@@ -1616,6 +1625,7 @@ One-screen revision. Version bumps on success; an --expected-version guard abort
 		}
 		const data = await res.json();
 		console.error(`Replaced region "${region}" on ${screenId} (${data.occurrences} match(es)) → v${data.mockup.version}.`);
+		printMockupHints(data.mockup);
 		return EXIT_OK;
 	}
 	const text = values.text;
@@ -1640,6 +1650,7 @@ One-screen revision. Version bumps on success; an --expected-version guard abort
 	}
 	const data = await res.json();
 	console.error(`Patched ${screenId} on ${mockupId} (${data.occurrences} exact match(es)) → v${data.mockup.version}.`);
+	printMockupHints(data.mockup);
 	return EXIT_OK;
 }
 async function mockupThreadsCmd(args) {
@@ -1792,6 +1803,7 @@ Staging files, if needed, go under ~/.diffing/<repo>/mockup-sources/ only.
 One state per screen: never tabs/accordions/toggles/modals/JS content-swapping — each variant is a separate screen.
 
   submit [-] [--title T] [--screen id=path]... [--id ID] [--model M] [--wait]
+         [--mode fragment|document] [--system ID] [--plan-id ID]
          # or a path already under ~/.diffing/.../mockup-sources/
   await [--timeout N]
   list [--json]

package/dist/cli.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { c as parseDiffOptions, i as validateEnvironment, l as printHelp, o as buildTuiGitDiffArgs, r as runTerminalDiff, s as intoShowMode, t as startServer } from "./server-BqCIWbuc.mjs";
+import { a as buildTuiGitDiffArgs, c as printHelp, n as runTerminalDiff, o as intoShowMode, r as validateEnvironment, s as parseDiffOptions, t as startServer } from "./server-CH-UPGFR.mjs";
 import { h as getRepoRoot, r as getBranchName } from "./git-BGj31GX-.mjs";
 import { i as loadSettings } from "./settings-DIa-3C8o.mjs";
 import { _ as generateSessionToken, b as isWildcardBindHost, c as removeServerLockIfOwned, p as writeServerLock, r as diffScopeKey, t as acquireServerStartupLease, u as resolveActiveServerLock } from "./server-lock-ACw2cKDI.mjs";
@@ -563,11 +563,11 @@ See docs/cli.md §5 (MCP) for the full tool table.`);
 			console.error("diffing mcp: --repo must be an absolute path");
 			process.exit(5);
 		}
-		const { startMcpServer } = await import("./mcp-ClEsxza5.mjs");
+		const { startMcpServer } = await import("./mcp-45VPdWIr.mjs");
 		await startMcpServer({ repoPath });
 		await new Promise(() => {});
 	}
-	const { runSubcommand } = await import("./cli-agent-Cpusc3Fl.mjs");
+	const { runSubcommand } = await import("./cli-agent-DV5ZhMX1.mjs");
 	const code = await runSubcommand(args[0], args.slice(1));
 	process.exit(code);
 }

package/dist/{mcp-ClEsxza5.mjs → mcp-45VPdWIr.mjs}

@@ -1,5 +1,5 @@
-import { a as buildGitDiffArgs, c as parseDiffOptions, n as formatSubmitHints, t as startServer } from "./server-BqCIWbuc.mjs";
-import { r as formatPlanReview, t as formatMockupReview } from "./mockup-format-Dzc3e_10.mjs";
+import { i as buildGitDiffArgs, s as parseDiffOptions, t as startServer } from "./server-CH-UPGFR.mjs";
+import { a as formatPlanReview, r as formatMockupReview, t as formatSubmitHints } from "./mockup-lint-BRjhxXSw.mjs";
 import { t as formatComments } from "./comment-format-DS1wOWj_.mjs";
 import { _ as generateSessionToken, c as removeServerLockIfOwned, i as isLockAlive, p as writeServerLock, r as diffScopeKey, s as removeServerLock, t as acquireServerStartupLease, u as resolveActiveServerLock, x as SESSION_TOKEN_HEADER, y as isLoopbackHost } from "./server-lock-ACw2cKDI.mjs";
 import { i as reviewSessionUrl, n as joinSessionApiUrl, r as reviewSessionBaseUrl, t as appendSessionToken } from "./session-url-CyBpcLAH.mjs";

package/dist/{mockup-format-Dzc3e_10.mjs → mockup-lint-BRjhxXSw.mjs}

@@ -326,4 +326,155 @@ function formatComment(comment, fallbackVersion, includeContext) {
 	return parts.join("\n");
 }
 //#endregion
-export { MOCKUP_MAX_SCREEN_BYTES as a, defaultScreenLabel as c, normalizeSubmitScreens as d, slugifyScreenId as f, sectionTitleForLine as i, isMockupViewport as l, extractPlanLines as n, MOCKUP_SCREEN_ID_RE as o, formatPlanReview as r, commentViewport as s, formatMockupReview as t, normalizeMockupViewport as u };
+//#region src/lib/mockup-lint.ts
+const RULES = [
+	{
+		label: "tabs",
+		re: /role\s*=\s*["']tab(list|panel)?["']/i
+	},
+	{
+		label: "tabs",
+		re: /aria-selected\s*=/i
+	},
+	{
+		label: "tabs",
+		re: /data-(?:bs-)?toggle\s*=\s*["'](?:tab|pill)["']/i
+	},
+	{
+		label: "tabs",
+		re: /\bdata-tabs?\s*=/i
+	},
+	{
+		label: "accordion",
+		re: /<details[\s>]/i
+	},
+	{
+		label: "accordion",
+		re: /data-(?:bs-)?toggle\s*=\s*["']collapse["']/i
+	},
+	{
+		label: "accordion",
+		re: /class\s*=\s*["'][^"']*\baccordion\b/i
+	},
+	{
+		label: "modal",
+		re: /role\s*=\s*["'](?:alert)?dialog["']/i
+	},
+	{
+		label: "modal",
+		re: /data-(?:bs-)?toggle\s*=\s*["']modal["']/i
+	},
+	{
+		label: "modal",
+		re: /class\s*=\s*["'][^"']*\bmodal\b/i
+	},
+	{
+		label: "dropdown",
+		re: /role\s*=\s*["']menu(?:bar)?["']/i
+	},
+	{
+		label: "dropdown",
+		re: /data-(?:bs-)?toggle\s*=\s*["']dropdown["']/i
+	},
+	{
+		label: "dropdown",
+		re: /class\s*=\s*["'][^"']*\bdropdown\b/i
+	},
+	{
+		label: "toggle",
+		re: /role\s*=\s*["']switch["']/i
+	},
+	{
+		label: "toggle",
+		re: /class\s*=\s*["'][^"']*\b(?:toggle|switch)\b/i
+	}
+];
+const ORDERED_LABELS = [
+	"tabs",
+	"accordion",
+	"modal",
+	"dropdown",
+	"toggle"
+];
+/** Find the in-page state UI patterns present in one screen's HTML. */
+function detectInPageState(html) {
+	const found = /* @__PURE__ */ new Set();
+	for (const rule of RULES) {
+		if (found.has(rule.label)) continue;
+		if (rule.re.test(html)) found.add(rule.label);
+	}
+	return ORDERED_LABELS.filter((label) => found.has(label));
+}
+const STYLE_RULES = [
+	{
+		label: "tailwind-cdn",
+		re: /cdn\.tailwindcss\.com/i
+	},
+	{
+		label: "tailwind-cdn",
+		re: /(?:unpkg\.com|cdn\.jsdelivr\.net|esm\.sh)\/(?:npm\/)?tailwindcss/i
+	},
+	{
+		label: "google-fonts",
+		re: /fonts\.googleapis\.com/i
+	},
+	{
+		label: "google-fonts",
+		re: /fonts\.gstatic\.com/i
+	}
+];
+const GENERIC_FONT_RE = /font-family\s*:\s*[^;{]*\bInter\b/i;
+const GENERIC_INDIGO_RE = /#(?:4f46e5|4338ca|6366f1|818cf8|7c3aed|8b5cf6|a78bfa)\b|\b(?:indigo|violet)-(?:[4-9]00|950)\b/i;
+/** Off-brand / generic-AI styling that should not ship as the product look. */
+function detectGenericStyle(html) {
+	const found = /* @__PURE__ */ new Set();
+	for (const rule of STYLE_RULES) {
+		if (found.has(rule.label)) continue;
+		if (rule.re.test(html)) found.add(rule.label);
+	}
+	if (GENERIC_FONT_RE.test(html) && GENERIC_INDIGO_RE.test(html)) found.add("generic-palette");
+	return [
+		"tailwind-cdn",
+		"google-fonts",
+		"generic-palette"
+	].filter((label) => found.has(label));
+}
+/** Build submit-time hints for a set of screens (empty when all clean). */
+function lintMockupScreens(screens) {
+	const hints = [];
+	for (const screen of screens) {
+		const state = detectInPageState(screen.html);
+		if (state.length > 0) hints.push({
+			screenId: screen.id,
+			kind: "state",
+			patterns: state,
+			message: `Screen "${screen.id}" contains in-page state UI (${state.join(", ")}). Split each state into its own screen instead.`
+		});
+		const style = detectGenericStyle(screen.html);
+		if (style.length > 0) hints.push({
+			screenId: screen.id,
+			kind: "style",
+			patterns: style,
+			message: `Screen "${screen.id}" looks generic (${style.join(", ")}). Drop CDN Tailwind / Google Fonts and do not invent Inter + indigo — match the product.`
+		});
+	}
+	return hints;
+}
+/** Compact submit/revise warning for CLI and MCP. */
+function formatSubmitHints(hints) {
+	if (hints.length === 0) return "";
+	const state = hints.filter((h) => h.kind !== "style");
+	const style = hints.filter((h) => h.kind === "style");
+	const lines = [];
+	if (state.length > 0) {
+		lines.push("⚠️ In-page state UI detected — split each state into its own screen:");
+		for (const hint of state) lines.push(`  • ${hint.screenId}: ${hint.patterns.join(", ")}`);
+	}
+	if (style.length > 0) {
+		lines.push("⚠️ Generic styling — match the product (no CDN Tailwind, Google Fonts, or Inter+indigo):");
+		for (const hint of style) lines.push(`  • ${hint.screenId}: ${hint.patterns.join(", ")}`);
+	}
+	return `\n${lines.join("\n")}`;
+}
+//#endregion
+export { formatPlanReview as a, MOCKUP_SCREEN_ID_RE as c, isMockupViewport as d, normalizeMockupViewport as f, extractPlanLines as i, commentViewport as l, slugifyScreenId as m, lintMockupScreens as n, sectionTitleForLine as o, normalizeSubmitScreens as p, formatMockupReview as r, MOCKUP_MAX_SCREEN_BYTES as s, formatSubmitHints as t, defaultScreenLabel as u };

package/dist/{server-BqCIWbuc.mjs → server-CH-UPGFR.mjs}

@@ -1,7 +1,7 @@
 import { C as listRepoFiles, D as toSafeRelativePath, E as isSafePath, S as isGitRepo, T as revertHunk, _ as getShowDiff, a as getCommitSeriesSummary, b as getUntrackedFilePathsAsync, d as getMergeStatus, f as getProjectStorageDir, h as getRepoRoot, l as getGitDiffAsync, m as getRepoMetadataAsync, o as getCustomGitDiffAsync, s as getFileContent, u as getHunkHistory, x as gitAddFile, y as getTabSizeForFilesAsync } from "./git-BGj31GX-.mjs";
 import { a as searchFiles, i as searchContent, o as searchSymbols, r as searchAll, s as trackSelection, t as getSearchStatus } from "./search-3R2E5xxr.mjs";
 import { c as writeJsonAtomically, i as loadSettings, s as saveSettings } from "./settings-DIa-3C8o.mjs";
-import { a as MOCKUP_MAX_SCREEN_BYTES, c as defaultScreenLabel, d as normalizeSubmitScreens, i as sectionTitleForLine, l as isMockupViewport, n as extractPlanLines, o as MOCKUP_SCREEN_ID_RE, r as formatPlanReview, s as commentViewport, t as formatMockupReview, u as normalizeMockupViewport } from "./mockup-format-Dzc3e_10.mjs";
+import { a as formatPlanReview, c as MOCKUP_SCREEN_ID_RE, d as isMockupViewport, f as normalizeMockupViewport, i as extractPlanLines, l as commentViewport, n as lintMockupScreens, o as sectionTitleForLine, p as normalizeSubmitScreens, r as formatMockupReview, s as MOCKUP_MAX_SCREEN_BYTES, u as defaultScreenLabel } from "./mockup-lint-BRjhxXSw.mjs";
 import { a as slugifyDesignId, i as emptyTokens, o as snapshotRevision, r as cloneTokens, s as tokensToCss, t as DEFAULT_DESIGN_SYSTEM_ID } from "./design-system-types-uiP9W2uj.mjs";
 import { t as formatComments } from "./comment-format-DS1wOWj_.mjs";
 import { g as createServerAuthMiddleware, h as buildSessionTokenSetCookieValue, v as injectSessionTokenIntoHtml } from "./server-lock-ACw2cKDI.mjs";
@@ -3006,157 +3006,6 @@ function injectMockupProbe(html, opts = {}) {
 	return script + html;
 }
 //#endregion
-//#region src/lib/mockup-lint.ts
-const RULES$1 = [
-	{
-		label: "tabs",
-		re: /role\s*=\s*["']tab(list|panel)?["']/i
-	},
-	{
-		label: "tabs",
-		re: /aria-selected\s*=/i
-	},
-	{
-		label: "tabs",
-		re: /data-(?:bs-)?toggle\s*=\s*["'](?:tab|pill)["']/i
-	},
-	{
-		label: "tabs",
-		re: /\bdata-tabs?\s*=/i
-	},
-	{
-		label: "accordion",
-		re: /<details[\s>]/i
-	},
-	{
-		label: "accordion",
-		re: /data-(?:bs-)?toggle\s*=\s*["']collapse["']/i
-	},
-	{
-		label: "accordion",
-		re: /class\s*=\s*["'][^"']*\baccordion\b/i
-	},
-	{
-		label: "modal",
-		re: /role\s*=\s*["'](?:alert)?dialog["']/i
-	},
-	{
-		label: "modal",
-		re: /data-(?:bs-)?toggle\s*=\s*["']modal["']/i
-	},
-	{
-		label: "modal",
-		re: /class\s*=\s*["'][^"']*\bmodal\b/i
-	},
-	{
-		label: "dropdown",
-		re: /role\s*=\s*["']menu(?:bar)?["']/i
-	},
-	{
-		label: "dropdown",
-		re: /data-(?:bs-)?toggle\s*=\s*["']dropdown["']/i
-	},
-	{
-		label: "dropdown",
-		re: /class\s*=\s*["'][^"']*\bdropdown\b/i
-	},
-	{
-		label: "toggle",
-		re: /role\s*=\s*["']switch["']/i
-	},
-	{
-		label: "toggle",
-		re: /class\s*=\s*["'][^"']*\b(?:toggle|switch)\b/i
-	}
-];
-const ORDERED_LABELS = [
-	"tabs",
-	"accordion",
-	"modal",
-	"dropdown",
-	"toggle"
-];
-/** Find the in-page state UI patterns present in one screen's HTML. */
-function detectInPageState(html) {
-	const found = /* @__PURE__ */ new Set();
-	for (const rule of RULES$1) {
-		if (found.has(rule.label)) continue;
-		if (rule.re.test(html)) found.add(rule.label);
-	}
-	return ORDERED_LABELS.filter((label) => found.has(label));
-}
-const STYLE_RULES = [
-	{
-		label: "tailwind-cdn",
-		re: /cdn\.tailwindcss\.com/i
-	},
-	{
-		label: "tailwind-cdn",
-		re: /(?:unpkg\.com|cdn\.jsdelivr\.net|esm\.sh)\/(?:npm\/)?tailwindcss/i
-	},
-	{
-		label: "google-fonts",
-		re: /fonts\.googleapis\.com/i
-	},
-	{
-		label: "google-fonts",
-		re: /fonts\.gstatic\.com/i
-	}
-];
-const GENERIC_FONT_RE = /font-family\s*:\s*[^;{]*\bInter\b/i;
-const GENERIC_INDIGO_RE = /#(?:4f46e5|4338ca|6366f1|818cf8|7c3aed|8b5cf6|a78bfa)\b|\b(?:indigo|violet)-(?:[4-9]00|950)\b/i;
-/** Off-brand / generic-AI styling that should not ship as the product look. */
-function detectGenericStyle(html) {
-	const found = /* @__PURE__ */ new Set();
-	for (const rule of STYLE_RULES) {
-		if (found.has(rule.label)) continue;
-		if (rule.re.test(html)) found.add(rule.label);
-	}
-	if (GENERIC_FONT_RE.test(html) && GENERIC_INDIGO_RE.test(html)) found.add("generic-palette");
-	return [
-		"tailwind-cdn",
-		"google-fonts",
-		"generic-palette"
-	].filter((label) => found.has(label));
-}
-/** Build submit-time hints for a set of screens (empty when all clean). */
-function lintMockupScreens(screens) {
-	const hints = [];
-	for (const screen of screens) {
-		const state = detectInPageState(screen.html);
-		if (state.length > 0) hints.push({
-			screenId: screen.id,
-			kind: "state",
-			patterns: state,
-			message: `Screen "${screen.id}" contains in-page state UI (${state.join(", ")}). Split each state into its own screen instead.`
-		});
-		const style = detectGenericStyle(screen.html);
-		if (style.length > 0) hints.push({
-			screenId: screen.id,
-			kind: "style",
-			patterns: style,
-			message: `Screen "${screen.id}" looks generic (${style.join(", ")}). Drop CDN Tailwind / Google Fonts and do not invent Inter + indigo — match the product.`
-		});
-	}
-	return hints;
-}
-/** Compact submit/revise warning for CLI and MCP. */
-function formatSubmitHints(hints) {
-	if (hints.length === 0) return "";
-	const state = hints.filter((h) => h.kind !== "style");
-	const style = hints.filter((h) => h.kind === "style");
-	const lines = [];
-	if (state.length > 0) {
-		lines.push("⚠️ In-page state UI detected — split each state into its own screen:");
-		for (const hint of state) lines.push(`  • ${hint.screenId}: ${hint.patterns.join(", ")}`);
-	}
-	if (style.length > 0) {
-		lines.push("⚠️ Generic styling — match the product (no CDN Tailwind, Google Fonts, or Inter+indigo):");
-		for (const hint of style) lines.push(`  • ${hint.screenId}: ${hint.patterns.join(", ")}`);
-	}
-	return `\n${lines.join("\n")}`;
-}
-//#endregion
 //#region src/lib/design-system.ts
 function newId() {
 	return crypto.randomUUID();
@@ -7769,4 +7618,4 @@ async function startServer(options) {
 	});
 }
 //#endregion
-export { buildGitDiffArgs as a, parseDiffOptions as c, validateEnvironment as i, printHelp as l, formatSubmitHints as n, buildTuiGitDiffArgs as o, runTerminalDiff as r, intoShowMode as s, startServer as t };
+export { buildTuiGitDiffArgs as a, printHelp as c, buildGitDiffArgs as i, runTerminalDiff as n, intoShowMode as o, validateEnvironment as r, parseDiffOptions as s, startServer as t };

package/extensions/pi/index.ts

@@ -3,8 +3,8 @@
  *
  * Bridges the local-first diffing review loop into pi:
  *  - Structured LLM tools mirroring the diffing MCP surface (status, review
- *    start, comments, reply/resolve, plan loop, mockup loop, progress,
- *    sessions, GH PR).
+ *    start, comments, reply/resolve, plan loop, mockup loop, design system,
+ *    progress, sessions, GH PR).
  *  - `/diffing` command to open/reuse the review UI for the current repo.
  *  - Footer status showing the active review session.
  *  - Skill self-heal: keeps `~/.agents/skills/diffing*` as symlinks to the
@@ -20,12 +20,9 @@
 import { spawn } from "node:child_process";
 import {
 	existsSync,
-	lstatSync,
 	mkdtempSync,
 	readFileSync,
-	realpathSync,
 	rmSync,
-	symlinkSync,
 	writeFileSync,
 } from "node:fs";
 import { homedir, tmpdir } from "node:os";
@@ -37,30 +34,19 @@ import type {
 	ExtensionContext,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import {
+	selfHealSkillLinks,
+	SKILLS_REL,
+} from "./skill-heal.ts";
 
 // ────────────────────────────────────────────────────────────────────────────
 // Constants
 // ────────────────────────────────────────────────────────────────────────────
 
-const SKILL_NAMES = [
-	"diffing",
-	"diffing-finish-review",
-	"diffing-mockup-author",
-	"diffing-mockup-review",
-	"diffing-plan-review",
-	"diffing-pr-address",
-	"diffing-pr-read",
-	"diffing-release",
-	"diffing-review",
-	"diffing-start-review",
-] as const;
-
 const MAX_OUTPUT_BYTES = 48 * 1024;
 const REVIEW_START_TIMEOUT_MS = 15_000;
 const REVIEW_START_POLL_MS = 400;
 
-const SKILLS_REL = join(".agents", "skills");
-
 // ────────────────────────────────────────────────────────────────────────────
 // CLI runner
 // ────────────────────────────────────────────────────────────────────────────
@@ -248,35 +234,6 @@ function findCanonicalRoot(cwd: string): string | null {
 	return null;
 }
 
-/**
- * Keep the `~/.agents/skills/diffing*` entries as symlinks to the canonical
- * checkout's `.agents/skills`. pi dedupes skills by canonical realpath, so
- * symlinked home entries merge silently with the repo's project skills and no
- * `[Skill conflicts]` banner appears. Repairs stale real copies left behind by
- * `diffing setup skills` / `npx skills add --copy`. Only touches the known
- * names in SKILL_NAMES; never deletes anything else.
- */
-function selfHealSkillLinks(canonical: string): void {
-	const homeSkills = join(homedir(), ".agents", "skills");
-	if (!existsSync(homeSkills)) return;
-	for (const name of SKILL_NAMES) {
-		const target = join(canonical, SKILLS_REL, name);
-		if (!existsSync(target)) continue;
-		const link = join(homeSkills, name);
-		try {
-			if (existsSync(link) || lstatSync(link)) {
-				if (lstatSync(link).isSymbolicLink()) {
-					const real = realpathSync(link);
-					if (real === realpathSync(target)) continue; // already correct
-				}
-				rmSync(link, { recursive: true, force: true });
-			}
-			symlinkSync(target, link, "dir");
-		} catch {
-			// best-effort; a failed heal must not break the session
-		}
-	}
-}
 
 // ────────────────────────────────────────────────────────────────────────────
 // Detached review server start
@@ -340,7 +297,9 @@ export default function (pi: ExtensionAPI) {
 	// Keep the home skill links canonical for every session (idempotent).
 	pi.on("session_start", async (_event, ctx) => {
 		const canonical = findCanonicalRoot(ctx.cwd);
-		if (canonical) selfHealSkillLinks(canonical);
+		if (canonical) {
+			selfHealSkillLinks(canonical, join(homedir(), ".agents", "skills"));
+		}
 		await refreshStatus(ctx);
 	});
 
@@ -825,7 +784,7 @@ export default function (pi: ExtensionAPI) {
 		name: "diffing_mockup_submit",
 		label: "Diffing Mockup Submit",
 		description:
-			"Submit HTML mockup screen(s) for visual review. Pass a single html body, a file/dir path, or an inline screens array [{id, html}]. Share the URL and park unless asked to wait. Resubmit with mockupId to bump the version and reset the verdict.",
+			"Submit HTML mockup screen(s) for visual review. HARD RULE — one state per screen: never tabs/accordions/toggles/modals/JS swaps. Pass html, a file/dir already under ~/.diffing/…/mockup-sources/, or screens [{id, html}]. Call diffing_design show first. Share the URL and park unless asked to wait. Resubmit with mockupId to bump the version. Fix any in-page-state or generic-style hints before parking.",
 		parameters: Type.Object({
 			html: Type.Optional(
 				Type.String({ description: "Single-screen HTML body." }),
@@ -854,6 +813,23 @@ export default function (pi: ExtensionAPI) {
 			),
 			model: Type.Optional(Type.String()),
 			source: Type.Optional(Type.String()),
+			mode: Type.Optional(
+				StringEnum(["fragment", "document"] as const, {
+					description:
+						"fragment = body contents wrapped by the published design-system shell. document = full HTML, no wrap. Default: server default.",
+				}),
+			),
+			designSystem: Type.Optional(
+				Type.String({
+					description:
+						"Design-system id to bind (default system if omitted).",
+				}),
+			),
+			planId: Type.Optional(
+				Type.String({
+					description: "Optional plan id this mockup illustrates.",
+				}),
+			),
 		}),
 		async execute(_id, params, _signal, _onUpdate, ctx) {
 			const args = ["mockup", "submit"];
@@ -896,6 +872,9 @@ export default function (pi: ExtensionAPI) {
 			if (params.mockupId) args.push("--id", params.mockupId);
 			if (params.model) args.push("--model", params.model);
 			if (params.source) args.push("--source", params.source);
+			if (params.mode) args.push("--mode", params.mode);
+			if (params.designSystem) args.push("--system", params.designSystem);
+			if (params.planId) args.push("--plan-id", params.planId);
 			try {
 				const result = await runDiffing(args, ctx.cwd, { stdin });
 				const stdout = result.stdout.trim();
@@ -1079,12 +1058,15 @@ export default function (pi: ExtensionAPI) {
 		name: "diffing_mockup_inspect",
 		label: "Diffing Mockup Inspect",
 		description:
-			"Read compact, bounded mockup data without transferring screen HTML. view=summary (headline stats), comments (paged comment list), comment (one thread), screen (screen source). Filter by comment scope: status, screenId, viewport (desktop|tablet|mobile), version. context=none|anchor|source controls anchor detail. Prefer this over diffing_mockup_show.",
+			"Read compact, bounded mockup data without transferring screen HTML. view=summary (headline stats), comments (paged comment list), comment (one thread), screen (screen source), preview (rendered preview metadata). Filter by comment scope: status, screenId, viewport (desktop|tablet|mobile), version. context=none|anchor|source controls anchor detail. Prefer this over diffing_mockup_show.",
 		parameters: Type.Object({
-			view: StringEnum(["summary", "comments", "comment", "screen"] as const, {
-				description: "What to read. Default: summary.",
-				default: "summary",
-			}),
+			view: StringEnum(
+				["summary", "comments", "comment", "screen", "preview"] as const,
+				{
+					description: "What to read. Default: summary.",
+					default: "summary",
+				},
+			),
 			mockupId: Type.Optional(
 				Type.String({ description: "Mockup id. Default: latest." }),
 			),
@@ -1152,11 +1134,12 @@ export default function (pi: ExtensionAPI) {
 		name: "diffing_mockup_screen",
 		label: "Diffing Mockup Screen",
 		description:
-			"One-screen revision of an HTML mockup. action=upsert adds/replaces a screen (html or file), remove deletes a screen, patch replaces the first exact occurrence of text with replacement. Every success bumps the mockup version; pass expectedVersion to guard racing edits (409 version-mismatch, nothing applied). For multi-screen revisions, resubmit via diffing_mockup_submit with the same mockupId.",
+			"One-screen revision of an HTML mockup. action=upsert adds/replaces a screen (html or file), remove deletes a screen, patch replaces the first exact occurrence of text with replacement, replace-region replaces the inner HTML of the first [data-diffing=region] element (prefer this when the comment has a data-diffing target). Every success bumps the mockup version; pass expectedVersion to guard racing edits (409 version-mismatch, nothing applied). For multi-screen revisions, resubmit via diffing_mockup_submit with the same mockupId.",
 		parameters: Type.Object({
-			action: StringEnum(["upsert", "remove", "patch"] as const, {
-				description: "Revision op.",
-			}),
+			action: StringEnum(
+				["upsert", "remove", "patch", "replace-region"] as const,
+				{ description: "Revision op." },
+			),
 			mockupId: Type.String({ description: "Mockup id." }),
 			screenId: Type.String({ description: "Screen id." }),
 			html: Type.Optional(
@@ -1177,8 +1160,17 @@ export default function (pi: ExtensionAPI) {
 					description: "For patch: exact text to replace (first occurrence).",
 				}),
 			),
+			region: Type.Optional(
+				Type.String({
+					description:
+						"For replace-region: data-diffing attribute value of the block to replace.",
+				}),
+			),
 			replacement: Type.Optional(
-				Type.String({ description: "For patch: replacement text." }),
+				Type.String({
+					description:
+						"For patch: replacement text. For replace-region: new inner HTML.",
+				}),
 			),
 			expectedVersion: Type.Optional(
 				Type.Number({
@@ -1202,6 +1194,10 @@ export default function (pi: ExtensionAPI) {
 					stdin = params.html;
 				}
 				if (params.label) args.push("--label", params.label);
+			} else if (params.action === "replace-region") {
+				if (params.region) args.push("--region", params.region);
+				if (params.replacement !== undefined)
+					args.push("--replacement", params.replacement);
 			} else if (params.action === "patch") {
 				if (params.text !== undefined) args.push("--text", params.text);
 				if (params.replacement !== undefined)
@@ -1264,6 +1260,77 @@ export default function (pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerTool({
+		name: "diffing_mockup_handoff",
+		label: "Diffing Mockup Handoff",
+		description:
+			"Compact implementation handoff after a mockup is approved: tokens, screens with intent, components used, leftover nits. Prefer this over dumping every screen's HTML. Call after decision=approved, before writing product UI.",
+		parameters: Type.Object({
+			mockupId: Type.Optional(
+				Type.String({ description: "Mockup id. Default: latest." }),
+			),
+			json: Type.Optional(
+				Type.Boolean({ description: "Emit raw JSON. Default: XML handoff." }),
+			),
+		}),
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const args = ["mockup", "handoff"];
+			if (params.mockupId) args.push(params.mockupId);
+			if (params.json) args.push("--json");
+			const result = await runDiffing(args, ctx.cwd);
+			return textResult(describe(result, "diffing mockup handoff"), {
+				exitCode: result.exitCode,
+				stderr: result.stderr.trim() || undefined,
+			});
+		},
+	});
+
+	pi.registerTool({
+		name: "diffing_design",
+		label: "Diffing Design System",
+		description:
+			"Per-repo design system used before authoring mockup HTML. show/list: read tokens, guidelines, components. extract: scan the consumer repo and write a draft (does not publish). propose: update the draft. publish: human action only — do not publish unless the human asked. Omit id for the default system.",
+		parameters: Type.Object({
+			action: StringEnum(
+				["show", "list", "extract", "propose", "publish"] as const,
+				{ description: "Design-system op. Default: show." },
+			),
+			id: Type.Optional(
+				Type.String({ description: "System id. Default: default." }),
+			),
+			json: Type.Optional(
+				Type.Boolean({ description: "Emit raw JSON. Default: false." }),
+			),
+			from: Type.Optional(
+				StringEnum(["css", "text"] as const, {
+					description: "For extract: scan source. Default: css.",
+				}),
+			),
+			title: Type.Optional(
+				Type.String({ description: "For extract/propose: system title." }),
+			),
+			guidelines: Type.Optional(
+				Type.String({
+					description: "For propose: markdown guidelines to write on the draft.",
+				}),
+			),
+		}),
+		async execute(_id, params, _signal, _onUpdate, ctx) {
+			const action = params.action ?? "show";
+			const args = ["design", action];
+			if (params.id) args.push(params.id);
+			if (params.json) args.push("--json");
+			if (params.from) args.push("--from", params.from);
+			if (params.title) args.push("--title", params.title);
+			if (params.guidelines) args.push("--guidelines", params.guidelines);
+			const result = await runDiffing(args, ctx.cwd);
+			return textResult(describe(result, `diffing design ${action}`), {
+				exitCode: result.exitCode,
+				stderr: result.stderr.trim() || undefined,
+			});
+		},
+	});
+
 	pi.registerTool({
 		name: "diffing_url",
 		label: "Diffing URL",

package/extensions/pi/skill-heal.ts

@@ -0,0 +1,73 @@
+import {
+	existsSync,
+	lstatSync,
+	realpathSync,
+	rmSync,
+	symlinkSync,
+} from "node:fs";
+import { join } from "node:path";
+
+export const DIFFING_SKILL_NAMES = [
+	"diffing",
+	"diffing-finish-review",
+	"diffing-mockup-author",
+	"diffing-mockup-review",
+	"diffing-plan-review",
+	"diffing-pr-address",
+	"diffing-pr-read",
+	"diffing-release",
+	"diffing-review",
+	"diffing-start-review",
+] as const;
+
+export const SKILLS_REL = join(".agents", "skills");
+
+/**
+ * Point `link` at `target`. Creates a missing link, repairs a stale/dangling
+ * one, and leaves a correct symlink alone. `existsSync` is false for both
+ * missing paths and dangling symlinks, so this uses `lstat` and treats ENOENT
+ * as "create".
+ */
+export function healSkillLink(
+	link: string,
+	target: string,
+): "ok" | "created" | "repaired" {
+	if (!existsSync(target)) return "ok";
+	let st: ReturnType<typeof lstatSync> | null = null;
+	try {
+		st = lstatSync(link);
+	} catch {
+		st = null;
+	}
+	if (st) {
+		if (st.isSymbolicLink()) {
+			try {
+				if (realpathSync(link) === realpathSync(target)) return "ok";
+			} catch {
+				// dangling or unreadable — fall through and replace
+			}
+		}
+		rmSync(link, { recursive: true, force: true });
+		symlinkSync(target, link, "dir");
+		return "repaired";
+	}
+	symlinkSync(target, link, "dir");
+	return "created";
+}
+
+/** Keep `~/.agents/skills/diffing*` as symlinks to the canonical checkout. */
+export function selfHealSkillLinks(
+	canonical: string,
+	homeSkills: string,
+): void {
+	if (!existsSync(homeSkills)) return;
+	for (const name of DIFFING_SKILL_NAMES) {
+		const target = join(canonical, SKILLS_REL, name);
+		if (!existsSync(target)) continue;
+		try {
+			healSkillLink(join(homeSkills, name), target);
+		} catch {
+			// best-effort; a failed heal must not break the session
+		}
+	}
+}

package/extensions/pi/tsconfig.json

@@ -5,10 +5,11 @@
     "moduleResolution": "bundler",
     "strict": true,
     "noEmit": true,
+    "allowImportingTsExtensions": true,
     "skipLibCheck": true,
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "types": ["node"]
   },
-  "include": ["index.ts", "pi-modules.d.ts"]
+  "include": ["index.ts", "skill-heal.ts", "pi-modules.d.ts"]
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "diffing",
-  "version": "0.18.2",
+  "version": "0.18.3",
   "description": "local-first CLI for reviewing, navigating, and discussing git diffs with AI",
   "type": "module",
   "license": "MIT",