@hienlh/ppm 0.22.10 → 0.23.0

package/src/services/design/design-snapshot-history.ts

@@ -0,0 +1,159 @@
+import { randomBytes } from "node:crypto";
+import { readdir, readFile, rm } from "node:fs/promises";
+import { join } from "node:path";
+import {
+  DESIGN_SNAPSHOT_REASONS, isSnapshotId, type DesignSnapshotInfo, type DesignSnapshotReason,
+} from "../../shared/design-types.ts";
+import { dotDesignDir, lstatOrNull } from "./design-paths.ts";
+import { ensureDotDesign, mkdirIfMissing } from "./design-fs.ts";
+
+/**
+ * On-disk layout of a design's snapshot history:
+ *
+ *   designs/<slug>/.design/history/<id>/meta.json
+ *   designs/<slug>/.design/history/<id>/files/<the design's files>
+ *
+ * A snapshot is written under `history/.tmp-<id>/` and renamed into place when complete,
+ * so a listed snapshot is always whole; a crash leaves only a `.tmp-` directory, which
+ * pruning removes.
+ */
+
+export const HISTORY_DIR = "history";
+export const SNAPSHOT_META = "meta.json";
+export const SNAPSHOT_FILES = "files";
+
+/** Newest `turn`, `pre-restore` and `manual` snapshots kept, together. */
+export const SNAPSHOT_CAP = 100;
+/** Newest `before-edit` snapshots kept, in a pool of their own so they cannot evict real history. */
+export const EDIT_SNAPSHOT_CAP = 30;
+
+const MAX_META_BYTES = 64 * 1024;
+
+export function historyDir(designDir: string): string {
+  return join(dotDesignDir(designDir), HISTORY_DIR);
+}
+
+export function snapshotDir(designDir: string, id: string): string {
+  return join(historyDir(designDir), id);
+}
+
+export function snapshotFilesDir(designDir: string, id: string): string {
+  return join(snapshotDir(designDir, id), SNAPSHOT_FILES);
+}
+
+function isReason(value: unknown): value is DesignSnapshotReason {
+  return typeof value === "string" && (DESIGN_SNAPSHOT_REASONS as readonly string[]).includes(value);
+}
+
+/** Parse a meta.json, refusing anything that does not describe the directory it sits in. */
+function parseMeta(raw: string, id: string): DesignSnapshotInfo | null {
+  let data: Record<string, unknown>;
+  try {
+    data = JSON.parse(raw) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+  if (!data || typeof data !== "object" || data.id !== id || !isReason(data.reason)) return null;
+  if (typeof data.createdAt !== "string" || Number.isNaN(Date.parse(data.createdAt))) return null;
+  if (typeof data.fileCount !== "number" || typeof data.bytes !== "number") return null;
+  if (typeof data.treeHash !== "string" || !/^[0-9a-f]{64}$/.test(data.treeHash)) return null;
+  return {
+    id,
+    reason: data.reason,
+    createdAt: data.createdAt,
+    ...(typeof data.sessionId === "string" ? { sessionId: data.sessionId } : {}),
+    ...(isSnapshotId(data.restoreOf) ? { restoreOf: data.restoreOf } : {}),
+    fileCount: data.fileCount,
+    bytes: data.bytes,
+    treeHash: data.treeHash,
+  };
+}
+
+async function readMeta(designDir: string, id: string): Promise<DesignSnapshotInfo | null> {
+  // `.design/` is inside a folder the agent writes to. A snapshot directory that is a
+  // symlink is not one this module made, and restoring "from" it would read elsewhere.
+  const dirSt = await lstatOrNull(snapshotDir(designDir, id));
+  if (!dirSt || dirSt.isSymbolicLink() || !dirSt.isDirectory()) return null;
+  const path = join(snapshotDir(designDir, id), SNAPSHOT_META);
+  const st = await lstatOrNull(path);
+  if (!st || !st.isFile() || st.size > MAX_META_BYTES) return null;
+  return parseMeta(await readFile(path, "utf8"), id);
+}
+
+/** Every complete snapshot, newest first. Unreadable entries are left out, never guessed at. */
+export async function readSnapshotHistory(designDir: string): Promise<DesignSnapshotInfo[]> {
+  const st = await lstatOrNull(historyDir(designDir));
+  if (!st || st.isSymbolicLink() || !st.isDirectory()) return [];
+  let names: string[];
+  try {
+    names = await readdir(historyDir(designDir));
+  } catch (e) {
+    if ((e as { code?: string }).code === "ENOENT") return [];
+    throw e;
+  }
+  const infos = await Promise.all(names.filter(isSnapshotId).map((id) => readMeta(designDir, id)));
+  return infos
+    .filter((info): info is DesignSnapshotInfo => info !== null)
+    .sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt) || (a.id < b.id ? 1 : -1));
+}
+
+export async function readSnapshotInfo(designDir: string, id: string): Promise<DesignSnapshotInfo | null> {
+  return isSnapshotId(id) ? readMeta(designDir, id) : null;
+}
+
+/** `history/`, created (with `.design/` and its `.gitignore`) when missing; never a symlink. */
+export async function ensureHistoryDir(designDir: string): Promise<string> {
+  await ensureDotDesign(designDir);
+  const dir = historyDir(designDir);
+  await mkdirIfMissing(dir);
+  const st = await lstatOrNull(dir);
+  if (!st || st.isSymbolicLink() || !st.isDirectory()) {
+    throw Object.assign(new Error(".design/history must be a real directory"), { status: 403, code: "EDESIGNPATH" });
+  }
+  return dir;
+}
+
+function pad(n: number): string {
+  return String(n).padStart(2, "0");
+}
+
+/** A fresh `YYYYMMDD-HHMMSS-xxxx` id (UTC) that names nothing in `history/` yet. */
+export async function newSnapshotId(designDir: string, now = new Date()): Promise<string> {
+  const stamp = `${now.getUTCFullYear()}${pad(now.getUTCMonth() + 1)}${pad(now.getUTCDate())}-`
+    + `${pad(now.getUTCHours())}${pad(now.getUTCMinutes())}${pad(now.getUTCSeconds())}`;
+  for (let attempt = 0; attempt < 64; attempt++) {
+    const id = `${stamp}-${randomBytes(2).toString("hex")}`;
+    const taken = (await lstatOrNull(snapshotDir(designDir, id)))
+      || (await lstatOrNull(join(historyDir(designDir), `.tmp-${id}`)));
+    if (!taken) return id;
+  }
+  throw new Error("Could not allocate a snapshot id");
+}
+
+/**
+ * Apply retention to a newest-first history: keep the newest {@link SNAPSHOT_CAP} protected
+ * snapshots and the newest {@link EDIT_SNAPSHOT_CAP} `before-edit` ones, each pool counted
+ * on its own. Ids in `keep` survive regardless (a restore protects its own target while it
+ * snapshots the current state). Also clears half-written `.tmp-` directories, which only
+ * exist after a crash because every caller holds the design lock. Returns the removed ids.
+ */
+export async function pruneSnapshotHistory(
+  designDir: string,
+  history: DesignSnapshotInfo[],
+  keep: ReadonlySet<string> = new Set(),
+): Promise<string[]> {
+  const removed: string[] = [];
+  let edits = 0;
+  let others = 0;
+  for (const info of history) {
+    const overCap = info.reason === "before-edit" ? ++edits > EDIT_SNAPSHOT_CAP : ++others > SNAPSHOT_CAP;
+    if (!overCap || keep.has(info.id)) continue;
+    await rm(snapshotDir(designDir, info.id), { recursive: true, force: true });
+    removed.push(info.id);
+  }
+  const names = await readdir(historyDir(designDir)).catch(() => [] as string[]);
+  for (const name of names) {
+    if (name.startsWith(".tmp-")) await rm(join(historyDir(designDir), name), { recursive: true, force: true });
+  }
+  return removed;
+}

package/src/services/design/design-snapshots.service.ts

@@ -0,0 +1,161 @@
+import { createHash } from "node:crypto";
+import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import {
+  DESIGN_SNAPSHOT_REASONS, type DesignSnapshotInfo, type DesignSnapshotReason,
+} from "../../shared/design-types.ts";
+import { resolveDesignDir } from "./design-paths.ts";
+import { readDesignFileSafe, safeWalkDesignTree, type SafeWalkEntry } from "./design-safe-walk.ts";
+import {
+  ensureHistoryDir, newSnapshotId, pruneSnapshotHistory, readSnapshotHistory,
+  SNAPSHOT_FILES, SNAPSHOT_META,
+} from "./design-snapshot-history.ts";
+import { withRecoveredDesign } from "./design-restore-journal.ts";
+import { emitDesignEvent } from "./design-events.ts";
+import { DesignError, isDesignError } from "./design-error.ts";
+
+/**
+ * Snapshots are plain file copies of a design folder (minus `.design/`) kept in
+ * `.design/history/`, not git commits: the user does not want a commit per AI turn.
+ *
+ * A snapshot identical to the newest one is not taken (tree-hash dedupe), a design over
+ * {@link SNAPSHOT_MAX_BYTES} is skipped with a warning rather than copied every turn, and
+ * retention runs per reason (see `pruneSnapshotHistory`).
+ */
+
+export const SNAPSHOT_MAX_BYTES = 50 * 1024 * 1024;
+export const SNAPSHOT_MAX_FILES = 5000;
+
+export type SnapshotResult =
+  | { id: string }
+  | { skipped: "unchanged"; sameAs: string }
+  | { skipped: "too-large" | "missing" };
+
+export interface SnapshotMeta {
+  sessionId?: string;
+  restoreOf?: string;
+}
+
+interface ReadTree {
+  files: { rel: string; data: Buffer }[];
+  bytes: number;
+  treeHash: string;
+}
+
+/** Walk and read a tree, or null when it is over the size or file-count budget. */
+export async function readDesignTree(root: string, opts: { skipDotDesign?: boolean } = {}): Promise<ReadTree | null> {
+  const entries: SafeWalkEntry[] = [];
+  let listed = 0;
+  for await (const entry of safeWalkDesignTree(root, opts)) {
+    listed += entry.size;
+    entries.push(entry);
+    if (listed > SNAPSHOT_MAX_BYTES || entries.length > SNAPSHOT_MAX_FILES) return null;
+  }
+  const tree = createHash("sha256");
+  const files: ReadTree["files"] = [];
+  let bytes = 0;
+  for (const entry of entries) {
+    const data = await readDesignFileSafe(entry.abs, SNAPSHOT_MAX_BYTES);
+    bytes += data.length;
+    // A file can grow between the walk and the read; the budget is on what was read.
+    if (bytes > SNAPSHOT_MAX_BYTES) return null;
+    const fileHash = createHash("sha256").update(data).digest("hex");
+    tree.update(`${entry.rel}\0${data.length}\0${fileHash}\n`);
+    files.push({ rel: entry.rel, data });
+  }
+  return { files, bytes, treeHash: tree.digest("hex") };
+}
+
+/** Write already-read files under `destRoot`, creating directories as needed. */
+export async function writeTreeFiles(destRoot: string, files: ReadTree["files"]): Promise<void> {
+  for (const file of files) {
+    const dest = join(destRoot, ...file.rel.split("/"));
+    await mkdir(dirname(dest), { recursive: true });
+    await writeFile(dest, file.data);
+  }
+}
+
+/**
+ * Take a snapshot of a design whose lock the caller already holds (restore takes its
+ * `pre-restore` this way). `keep` protects ids from this snapshot's pruning.
+ *
+ * Dedupe compares against the newest snapshot, except that a protected snapshot never
+ * dedupes against a `before-edit` one: that pool is evictable, and the state it holds
+ * would then survive only as long as the next thirty canvas edits allow.
+ */
+export async function takeSnapshotLocked(
+  designDir: string,
+  reason: DesignSnapshotReason,
+  meta: SnapshotMeta = {},
+  keep: ReadonlySet<string> = new Set(),
+): Promise<SnapshotResult> {
+  const tree = await readDesignTree(designDir);
+  if (!tree) {
+    console.warn(`[design] not snapshotting ${designDir}: over ${SNAPSHOT_MAX_BYTES / 1024 / 1024} MB or ${SNAPSHOT_MAX_FILES} files`);
+    return { skipped: "too-large" };
+  }
+  const history = await readSnapshotHistory(designDir);
+  const newest = history[0];
+  if (newest && newest.treeHash === tree.treeHash && (newest.reason !== "before-edit" || reason === "before-edit")) {
+    return { skipped: "unchanged", sameAs: newest.id };
+  }
+
+  const historyRoot = await ensureHistoryDir(designDir);
+  // Strictly after the newest one, so two snapshots within a millisecond still have an order.
+  const createdMs = Math.max(Date.now(), newest ? Date.parse(newest.createdAt) + 1 : 0);
+  const id = await newSnapshotId(designDir, new Date(createdMs));
+  const staging = join(historyRoot, `.tmp-${id}`);
+  const info: DesignSnapshotInfo = {
+    id,
+    reason,
+    createdAt: new Date(createdMs).toISOString(),
+    ...(meta.sessionId ? { sessionId: meta.sessionId } : {}),
+    ...(meta.restoreOf ? { restoreOf: meta.restoreOf } : {}),
+    fileCount: tree.files.length,
+    bytes: tree.bytes,
+    treeHash: tree.treeHash,
+  };
+  try {
+    await mkdir(join(staging, SNAPSHOT_FILES), { recursive: true });
+    await writeTreeFiles(join(staging, SNAPSHOT_FILES), tree.files);
+    await writeFile(join(staging, SNAPSHOT_META), `${JSON.stringify(info, null, 2)}\n`);
+    // Published by one rename, so a listed snapshot is always complete.
+    await rename(staging, join(historyRoot, id));
+  } catch (e) {
+    await rm(staging, { recursive: true, force: true });
+    throw e;
+  }
+  await pruneSnapshotHistory(designDir, [info, ...history], keep);
+  return { id };
+}
+
+/**
+ * Snapshot a design (`turn` after an AI turn, `before-edit` ahead of a canvas write-back,
+ * `manual` on request). Announces the change with one `history_changed` event when a
+ * snapshot was actually taken. A design that does not exist is reported as skipped, since
+ * a turn can end in a session whose design was deleted.
+ */
+export async function snapshotDesign(
+  projectPath: string,
+  slug: string,
+  reason: DesignSnapshotReason,
+  meta: SnapshotMeta = {},
+): Promise<SnapshotResult> {
+  if (!(DESIGN_SNAPSHOT_REASONS as readonly string[]).includes(reason)) {
+    throw new DesignError(400, "EBADREASON", `Unknown snapshot reason: ${reason}`);
+  }
+  let result: SnapshotResult;
+  try {
+    result = await withRecoveredDesign(projectPath, slug, (dir) => takeSnapshotLocked(dir, reason, meta));
+  } catch (e) {
+    if (isDesignError(e) && e.status === 404) return { skipped: "missing" };
+    throw e;
+  }
+  if ("id" in result) emitDesignEvent("history_changed", { projectPath: resolve(projectPath), slug });
+  return result;
+}
+
+/** Snapshots of one design, newest first. */
+export async function listSnapshots(projectPath: string, slug: string): Promise<DesignSnapshotInfo[]> {
+  return readSnapshotHistory(await resolveDesignDir(projectPath, slug));
+}

package/src/services/design/design-starter-template.ts

@@ -0,0 +1,100 @@
+import type { DesignKind } from "../../shared/design-types.ts";
+
+/**
+ * The `index.html` a new design starts with: enough structure for the canvas to render
+ * something and for the agent to extend, following the same conventions its instructions
+ * describe (a `:root` block for tweakable values, `../tokens.css` when the project has one,
+ * `<section class="slide">` at 1280x720 for decks).
+ */
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&#39;");
+}
+
+const PAGE_STYLE = `    :root {
+      --accent: #4f46e5;
+      --radius: 12px;
+      --space: 24px;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+      color: #111827;
+      background: #f9fafb;
+    }
+    main {
+      max-width: 960px;
+      margin: 0 auto;
+      padding: calc(var(--space) * 3) var(--space);
+    }
+    h1 { margin: 0 0 var(--space); font-size: 2.5rem; }
+    p { color: #4b5563; line-height: 1.6; }
+    .button {
+      display: inline-block;
+      padding: 12px 20px;
+      border-radius: var(--radius);
+      background: var(--accent);
+      color: #fff;
+      text-decoration: none;
+    }`;
+
+const SLIDES_STYLE = `    :root {
+      --accent: #4f46e5;
+      --space: 64px;
+    }
+    * { box-sizing: border-box; }
+    body {
+      margin: 0;
+      font-family: system-ui, -apple-system, "Segoe UI", sans-serif;
+      background: #e5e7eb;
+    }
+    .slide {
+      width: 1280px;
+      height: 720px;
+      margin: 0 auto 24px;
+      padding: var(--space);
+      background: #fff;
+      overflow: hidden;
+      display: flex;
+      flex-direction: column;
+      justify-content: center;
+    }
+    .slide h1 { margin: 0 0 24px; font-size: 64px; color: var(--accent); }
+    .slide p { margin: 0; font-size: 28px; color: #4b5563; }`;
+
+export function starterHtml(kind: DesignKind, title: string, hasTokens: boolean): string {
+  const safeTitle = escapeHtml(title);
+  const tokensLink = hasTokens ? `  <link rel="stylesheet" href="../tokens.css">\n` : "";
+  const body =
+    kind === "slides"
+      ? `  <section class="slide">
+    <h1>${safeTitle}</h1>
+    <p>Describe the deck in the chat and the slides will appear here.</p>
+  </section>`
+      : `  <main>
+    <h1>${safeTitle}</h1>
+    <p>Describe what you want in the chat and the design will appear here.</p>
+    <a class="button" href="#">Get started</a>
+  </main>`;
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${safeTitle}</title>
+${tokensLink}  <style>
+${kind === "slides" ? SLIDES_STYLE : PAGE_STYLE}
+  </style>
+</head>
+<body>
+${body}
+</body>
+</html>
+`;
+}

package/src/services/design/design-store.service.ts

@@ -0,0 +1,156 @@
+import { mkdir, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import type { Stats } from "node:fs";
+import {
+  isDesignKind, type DesignKind, type DesignSummary, type DesignSystemStatus,
+} from "../../shared/design-types.ts";
+import { isValidDesignSlug, slugFromTitle } from "./design-slug.ts";
+import { lstatOrNull, resolveDesignDir, resolveDesignsRoot } from "./design-paths.ts";
+import { ensureDotDesign, writeFileAtomic } from "./design-fs.ts";
+import {
+  DEFAULT_ENTRY, MANIFEST_FILE, normalizeTitle, parseManifest, serializeManifest, type DesignManifest,
+} from "./design-manifest.ts";
+import { starterHtml } from "./design-starter-template.ts";
+import { DesignError } from "./design-error.ts";
+import { designLockKey, withDesignLock } from "./design-lock.ts";
+import { withRecoveredDesign } from "./design-restore-journal.ts";
+
+/** Designs listed per project, newest first. */
+export const MAX_LISTED_DESIGNS = 200;
+const MAX_MANIFEST_BYTES = 256 * 1024;
+const MAX_SLUG_SUFFIX = 999;
+
+async function readManifestRaw(designDir: string): Promise<string | null> {
+  const path = join(designDir, MANIFEST_FILE);
+  const st = await lstatOrNull(path);
+  if (!st || !st.isFile() || st.size > MAX_MANIFEST_BYTES) return null;
+  return readFile(path, "utf8");
+}
+
+async function regularFileStat(path: string): Promise<Stats | null> {
+  const st = await lstatOrNull(path);
+  return st?.isFile() ? st : null;
+}
+
+async function summarize(designDir: string, slug: string, manifest: DesignManifest): Promise<DesignSummary> {
+  const entry = await regularFileStat(join(designDir, ...manifest.entry.split("/")));
+  const updated = Math.max(Date.parse(manifest.updatedAt), entry?.mtimeMs ?? 0);
+  const { title, kind, createdAt } = manifest;
+  return { slug, title, kind, entry: manifest.entry, createdAt, updatedAt: new Date(updated).toISOString() };
+}
+
+async function loadManifest(designDir: string, slug: string): Promise<{ manifest: DesignManifest; valid: boolean; raw: string | null }> {
+  const dirSt = await lstatOrNull(designDir);
+  // A manifest without timestamps falls back to the folder's own age, not "now", so a
+  // hand-made design does not jump to the top of the list on every read.
+  const now = new Date(dirSt?.birthtimeMs || dirSt?.mtimeMs || Date.now()).toISOString();
+  const raw = await readManifestRaw(designDir);
+  return { ...parseManifest(raw, { slug, now }), raw };
+}
+
+export async function getDesign(projectPath: string, slug: string): Promise<DesignSummary> {
+  const dir = await resolveDesignDir(projectPath, slug);
+  return summarize(dir, slug, (await loadManifest(dir, slug)).manifest);
+}
+
+/**
+ * Every design folder under `designs/`, newest first, at most {@link MAX_LISTED_DESIGNS}.
+ * A folder counts as a design when its name is a valid slug and it holds a manifest or an
+ * entry page; symlinked folders are never listed.
+ */
+export async function listDesigns(projectPath: string): Promise<DesignSummary[]> {
+  const root = await resolveDesignsRoot(projectPath);
+  if (!root) return [];
+  const out: DesignSummary[] = [];
+  for (const name of await readdir(root)) {
+    if (!isValidDesignSlug(name)) continue;
+    const dir = join(root, name);
+    const st = await lstatOrNull(dir);
+    if (!st || st.isSymbolicLink() || !st.isDirectory()) continue;
+    const hasManifest = await regularFileStat(join(dir, MANIFEST_FILE));
+    if (!hasManifest && !(await regularFileStat(join(dir, DEFAULT_ENTRY)))) continue;
+    try {
+      out.push(await summarize(dir, name, (await loadManifest(dir, name)).manifest));
+    } catch (e) {
+      console.warn(`[design] skipping ${dir}: ${(e as Error).message}`);
+    }
+  }
+  return out.sort((a, b) => Date.parse(b.updatedAt) - Date.parse(a.updatedAt)).slice(0, MAX_LISTED_DESIGNS);
+}
+
+function candidateSlug(base: string, n: number): string {
+  if (n === 1) return base;
+  const suffix = `-${n}`;
+  return `${base.slice(0, 63 - suffix.length).replace(/-+$/, "")}${suffix}`;
+}
+
+/**
+ * Create `designs/<slug>/` with a starter page, the manifest and `.design/.gitignore`.
+ * The slug comes from the title; a taken slug gets `-2`, `-3`… The folder is claimed with a
+ * non-recursive mkdir, which fails if it already exists, so two creates racing for one
+ * title end up in two folders rather than one overwriting the other.
+ */
+export async function createDesign(projectPath: string, input: { title: unknown; kind: unknown }): Promise<DesignSummary> {
+  const title = normalizeTitle(input.title);
+  if (!title) throw new DesignError(400, "EBADTITLE", "A design needs a title");
+  if (input.kind !== undefined && !isDesignKind(input.kind)) throw new DesignError(400, "EBADKIND", "Unknown design kind");
+  const kind: DesignKind = isDesignKind(input.kind) ? input.kind : "page";
+  const root = await resolveDesignsRoot(projectPath, { create: true });
+  if (!root) throw new DesignError(500, "EDESIGNROOT", "Could not create designs/");
+  const base = slugFromTitle(title) || "design";
+
+  for (let n = 1; n <= MAX_SLUG_SUFFIX; n++) {
+    const slug = candidateSlug(base, n);
+    const dir = join(root, slug);
+    try {
+      await mkdir(dir);
+    } catch (e) {
+      if ((e as { code?: string }).code === "EEXIST") continue;
+      throw e;
+    }
+    try {
+      const now = new Date().toISOString();
+      const manifest: DesignManifest = { title, kind, entry: DEFAULT_ENTRY, createdAt: now, updatedAt: now, extra: { tweaks: [] } };
+      const hasTokens = !!(await regularFileStat(join(root, "tokens.css")));
+      await ensureDotDesign(dir);
+      await writeFile(join(dir, DEFAULT_ENTRY), starterHtml(kind, title, hasTokens));
+      await writeFile(join(dir, MANIFEST_FILE), serializeManifest(manifest));
+      return await summarize(dir, slug, manifest);
+    } catch (e) {
+      await rm(dir, { recursive: true, force: true });
+      throw e;
+    }
+  }
+  throw new DesignError(409, "EEXIST", "Too many designs share this title");
+}
+
+/** Change the title only: the slug is fixed because design sessions carry it in their instructions. */
+export async function renameDesign(projectPath: string, slug: string, rawTitle: unknown): Promise<DesignSummary> {
+  const title = normalizeTitle(rawTitle);
+  if (!title) throw new DesignError(400, "EBADTITLE", "A design needs a title");
+  return withRecoveredDesign(projectPath, slug, async (dir) => {
+    const { manifest, valid, raw } = await loadManifest(dir, slug);
+    // Rewriting an unreadable manifest would replace whatever the agent put there with defaults.
+    if (raw !== null && !valid) throw new DesignError(409, "EBADMANIFEST", `${MANIFEST_FILE} is not a valid JSON object`);
+    const next: DesignManifest = { ...manifest, title, updatedAt: new Date().toISOString() };
+    await writeFileAtomic(join(dir, MANIFEST_FILE), serializeManifest(next));
+    return summarize(dir, slug, next);
+  });
+}
+
+/** Delete a design folder, `.design/` and its history included. */
+export async function deleteDesign(projectPath: string, slug: string): Promise<void> {
+  await withDesignLock(designLockKey(projectPath, slug), async () => {
+    const dir = await resolveDesignDir(projectPath, slug);
+    // rm never follows a symlink inside the tree; the folder itself was checked not to be one.
+    await rm(dir, { recursive: true, force: false });
+  });
+}
+
+/** Whether the project design system exists yet (`designs/DESIGN.md`, `designs/tokens.css`). */
+export async function designSystemStatus(projectPath: string): Promise<DesignSystemStatus> {
+  const root = await resolveDesignsRoot(projectPath);
+  if (!root) return { designMd: false, tokensCss: false };
+  const [md, css] = await Promise.all([regularFileStat(join(root, "DESIGN.md")), regularFileStat(join(root, "tokens.css"))]);
+  return { designMd: !!md, tokensCss: !!css };
+}

package/src/services/design/design-style-patch.service.ts

@@ -0,0 +1,83 @@
+import { DESIGN_GEN_RE } from "../../shared/design-types.ts";
+import { ELEMENT_TAG_RE, parsePpmId } from "../../shared/design-comment-types.ts";
+import { parseTransformProps, type TransformProps } from "../../shared/design-bridge-messages-transform.ts";
+import { withRecoveredDesign } from "./design-restore-journal.ts";
+import { isSafeEntry } from "./design-manifest.ts";
+import { snapshotDesign } from "./design-snapshots.service.ts";
+import { DesignError } from "./design-error.ts";
+import { takeDesignWrite } from "./design-write-rate-limit.ts";
+import { changedSpan, recordEdit } from "./design-edit-undo-journal.ts";
+import { resolveScopedPath } from "./preview/design-preview-scope.ts";
+import { INSTRUMENT_MAX_BYTES } from "./preview/design-preview-html.ts";
+import { readDesignSource, writeDesignSource } from "./source/design-source-file.ts";
+import { patchStartTagStyle } from "./source/inline-style-patch.ts";
+
+/**
+ * A move or resize from the canvas, written into the element's inline `style`.
+ *
+ * The request names the element the way the canvas knows it — file, the gen the canvas
+ * loaded, `data-ppm-id`, tag — and carries only `translate`/`width`/`height` px values
+ * ({@link parseTransformProps}). Under the design's lock the server re-reads the file and
+ * refuses with a 409 when its gen moved on (`stale`) or the tag at that offset is not the
+ * expected one (`element-moved`), so a canvas behind an agent's edit can never write into
+ * the wrong element. Only then does the write count against the rate limit, take a
+ * `before-edit` snapshot, patch the style attribute and go to disk atomically, and the patch
+ * is journaled so Undo can reverse exactly it.
+ */
+
+export interface StylePatchInput {
+  file: string;
+  gen: string;
+  ppmId: number;
+  tag: string;
+  props: TransformProps;
+}
+
+export interface StylePatchResult {
+  gen: string;
+  /** Null when the edit was too large to journal; History still has the snapshot. */
+  undoId: string | null;
+}
+
+/** A 409 carrying why, so the canvas can say whether to reload or reselect. */
+export class StyleConflictError extends DesignError {
+  constructor(reason: "stale" | "element-moved", message: string, readonly currentGen: string) {
+    super(409, reason, message);
+  }
+}
+
+const bad = (message: string): DesignError => new DesignError(400, "EBADSTYLE", message);
+
+export function parseStylePatchInput(input: unknown): StylePatchInput {
+  if (!input || typeof input !== "object" || Array.isArray(input)) throw bad("Expected a JSON object");
+  const raw = input as Record<string, unknown>;
+  if (!isSafeEntry(raw.file)) throw bad("file must be an HTML file of the design");
+  if (typeof raw.gen !== "string" || !DESIGN_GEN_RE.test(raw.gen)) throw bad("Invalid gen");
+  const ppmId = parsePpmId(raw.ppmId);
+  if (typeof ppmId !== "number") throw bad("Invalid element id");
+  const tag = typeof raw.tag === "string" ? raw.tag.toLowerCase() : "";
+  if (!ELEMENT_TAG_RE.test(tag)) throw bad("Invalid tag");
+  const props = parseTransformProps(raw.props);
+  if (!props) throw bad("props may only set translate, width and height to px values");
+  return { file: raw.file, gen: raw.gen, ppmId, tag, props };
+}
+
+export async function commitStylePatch(projectPath: string, slug: string, raw: unknown): Promise<StylePatchResult> {
+  const input = parseStylePatchInput(raw);
+  return withRecoveredDesign(projectPath, slug, async () => {
+    const abs = (await resolveScopedPath({ projectPath, slug }, `${slug}/${input.file}`)).abs;
+    // Files above this size are served without ids, so no canvas can address one of their elements.
+    const source = await readDesignSource(abs, { maxBytes: INSTRUMENT_MAX_BYTES });
+    if (source.gen !== input.gen) {
+      throw new StyleConflictError("stale", `${input.file} changed since the canvas loaded it`, source.gen);
+    }
+    const patched = patchStartTagStyle(source.text, input.ppmId, input.tag, input.props);
+    if ("error" in patched) throw new StyleConflictError("element-moved", patched.message, source.gen);
+    takeDesignWrite(projectPath, slug);
+    await snapshotDesign(projectPath, slug, "before-edit");
+    const gen = await writeDesignSource(abs, patched.text, { bom: source.bom });
+    const span = changedSpan(input.file, source.text, patched.text);
+    const undoId = span ? recordEdit(projectPath, slug, [span], { [input.file]: gen }) : null;
+    return { gen, undoId };
+  });
+}