openplanr 3.2.0 → 3.4.0

package/lib/host-packages/claude/openplanr/runtime/design/scripts/design.mjs

@@ -9,9 +9,18 @@ import {
   stopArtifactReviewServer
 } from "./design-review.mjs";
 import {
+  ARTIFACT_REVIEW_MAX_STATE_BYTES,
+  createReviewLedger,
+  decodeArtifactReviewSources,
+  mergeReviewLedger,
+  normalizeArtifactReview,
+  readArtifactReviewState,
   readDesignFeedback,
   readDesignHandoff,
-  updateDesignHandoff
+  resolveArtifactReviewDestination,
+  updateDesignHandoff,
+  withArtifactReviewLock,
+  writeArtifactReviewState
 } from "./design-handoff.mjs";
 import {
   inspectDesignDocument,
@@ -21,58 +30,44 @@ import {
   renderDesignDocument,
   standaloneDesignHtml
 } from "./design-document.mjs";
+import {
+  listDesignRevisions,
+  readDesignRevision
+} from "./design-shared-artifact-support-dependencies-design-support-protocol-contracts-d707e49b.mjs";
+import "./design-review-state-store.mjs";
+import "./design-parse5-parser.mjs";
+import "./design-parse5-tokenizer.mjs";
+import "./design-entities.mjs";
 import "./design-artifact-shell.mjs";
+import {
+  ARTIFACT_ERROR_CODES,
+  PipelineError,
+  digestArtifactEnvelope
+} from "./design-shared-artifact-support-protocol-contracts-9f6918b0.mjs";
 import "./design-sandbox-guards.mjs";
 import {
-  ARTIFACT_REVIEW_MAX_STATE_BYTES,
-  createReviewLedger,
-  decodeArtifactReviewSources,
   exportDesignShareRecovery,
   importDesignShareRecovery,
   manageDesignShare,
-  mergeReviewLedger,
-  normalizeArtifactReview,
   publishDesignShare,
-  readArtifactReviewState,
-  resolveArtifactReviewDestination,
   shareDesign,
-  syncDesignShare,
-  withArtifactReviewLock,
-  writeArtifactReviewState
-} from "./design-share.mjs";
+  syncDesignShare
+} from "./design-share-cli-bridge.mjs";
 import {
   atomicJson,
   currentDesign,
   hash,
-  listDesignRevisions,
-  readDesignRevision,
   readJson
-} from "./design-shared-artifact-support-dependencies-design-support-protocol-contracts-3d9b1a86.mjs";
-import "./design-encrypted-workspace-client.mjs";
-import "./design-upload-spool.mjs";
-import "./design-chunked-workspace-client.mjs";
-import "./design-resource-pack.mjs";
-import "./design-compression.mjs";
-import "./design-owner-custody.mjs";
+} from "./design-shared-design-support-0bac378d.mjs";
 import "./design-runtime-home.mjs";
 import {
   acquireStartLock
 } from "./design-loopback-server.mjs";
-import "./design-parse5-parser.mjs";
-import "./design-parse5-tokenizer.mjs";
-import "./design-entities.mjs";
-import {
-  ARTIFACT_ERROR_CODES,
-  PipelineError,
-  digestArtifactEnvelope
-} from "./design-shared-artifact-support-protocol-contracts-ea2cd15e.mjs";
-import "./design-shared-protocol-contracts-b5f28f94.mjs";
-import "./design-shared-protocol-contracts-75a938cc.mjs";
 
 // packages/design/lib/design/utility.mjs
 import { spawn } from "node:child_process";
-import { existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from "node:fs";
-import { dirname, join as join3, resolve as resolve2 } from "node:path";
+import { existsSync as existsSync2, mkdirSync as mkdirSync2, readFileSync, realpathSync, writeFileSync as writeFileSync2 } from "node:fs";
+import { dirname as dirname2, join as join4, resolve as resolve3 } from "node:path";
 import { fileURLToPath } from "node:url";
 
 // packages/design/lib/design/feedback-import.mjs
@@ -339,8 +334,272 @@ async function importDesignFeedback(file, { input, revision, allowStale = false,
   }
 }
 
+// packages/design/lib/design/font-fetch.mjs
+import {
+  chmodSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  readdirSync,
+  renameSync,
+  rmdirSync,
+  rmSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
+import { basename, dirname, join as join2, resolve as resolve2 } from "node:path";
+var MAX_FAMILIES = 2;
+var MAX_WEIGHTS = 3;
+var TIMEOUT_MS = 2e4;
+var MAX_FILE_BYTES = 15e5;
+var MAX_TOTAL_BYTES = 5e6;
+var STAGING_MAX_AGE_MS = 10 * 6e4;
+var STAGING_PREFIX = ".fonts-fetch-";
+var CSS_ENDPOINT = "https://fonts.googleapis.com/css2";
+var FONT_ORIGIN = "https://fonts.gstatic.com/";
+var CATALOG_ROOT = "https://raw.githubusercontent.com/google/fonts/main";
+var USER_AGENT = "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36";
+var LICENSES = Object.freeze([
+  {
+    directory: "ofl",
+    metadata: "OFL",
+    file: "OFL.txt",
+    id: "OFL-1.1",
+    text: /SIL Open Font License,?\s+Version 1\.1/iu
+  },
+  {
+    directory: "apache",
+    metadata: "APACHE2",
+    file: "LICENSE.txt",
+    id: "Apache-2.0",
+    text: /Apache License\s+Version 2\.0/iu
+  }
+]);
+var FAMILY_SPEC = /^([A-Za-z0-9](?:[A-Za-z0-9 ]*[A-Za-z0-9])?):(\d{3}(?:,\d{3})*)$/u;
+function parseFontFamily(spec) {
+  const match = typeof spec === "string" ? FAMILY_SPEC.exec(spec.trim()) : null;
+  if (!match)
+    throw new Error(
+      `--family ${JSON.stringify(spec ?? "")} must look like "Inter:400,600" (a name, a colon, comma-separated weights).`
+    );
+  const weights = [...new Set(match[2].split(",").map(Number))].sort((a, b) => a - b);
+  const invalid2 = weights.find((weight) => weight < 100 || weight > 900 || weight % 100 !== 0);
+  if (invalid2 !== void 0)
+    throw new Error(`--family "${spec}" has weight ${invalid2}; use 100 to 900 in steps of 100.`);
+  if (weights.length > MAX_WEIGHTS)
+    throw new Error(
+      `--family "${spec}" has ${weights.length} weights; at most ${MAX_WEIGHTS} per family.`
+    );
+  return { family: match[1], weights };
+}
+function latinFontFaces(css, family) {
+  const faces = [];
+  for (const [, subset, body] of css.matchAll(
+    /\/\*\s*([\w-]+)\s*\*\/\s*@font-face\s*\{([^}]*)\}/gu
+  )) {
+    const value = (name) => new RegExp(`(?:^|;)\\s*${name}\\s*:\\s*([^;]+)`, "iu").exec(body)?.[1].trim();
+    if (subset !== "latin" || !/^U\+0000-00FF\b/iu.test(value("unicode-range") ?? "")) continue;
+    const source = /^url\(([^)\s]+)\)\s*format\(['"]woff2['"]\)$/u.exec(value("src") ?? "");
+    if (!source?.[1].startsWith(FONT_ORIGIN))
+      throw new Error(
+        `"${family}" Latin face is not a woff2 file on ${FONT_ORIGIN}: ${value("src")}`
+      );
+    faces.push({ weight: Number(value("font-weight")), url: source[1] });
+  }
+  return faces;
+}
+async function request(fetchImpl, url, { headers, allowMissing = false, redirect } = {}) {
+  let response;
+  try {
+    response = await fetchImpl(url, {
+      headers,
+      redirect,
+      signal: AbortSignal.timeout(TIMEOUT_MS)
+    });
+  } catch (error) {
+    const reason = error?.name === "TimeoutError" ? `no response within ${TIMEOUT_MS / 1e3} s` : error?.message;
+    throw new Error(`Font fetch failed: ${url}: ${reason}`);
+  }
+  if (allowMissing && response.status === 404) return null;
+  if (!response.ok) throw new Error(`Font fetch failed: ${url}: HTTP ${response.status}`);
+  return response;
+}
+async function verifiedLicense(fetchImpl, family) {
+  const slug = family.toLowerCase().replace(/[^a-z0-9]/gu, "");
+  const tried = [];
+  for (const license of LICENSES) {
+    const base = `${CATALOG_ROOT}/${license.directory}/${slug}`;
+    tried.push(`${base}/METADATA.pb`);
+    const metadata = await request(fetchImpl, `${base}/METADATA.pb`, { allowMissing: true });
+    if (!metadata) continue;
+    const text = await metadata.text();
+    const name = /^name:\s*"([^"]*)"/mu.exec(text)?.[1];
+    const declared = /^license:\s*"([^"]*)"/mu.exec(text)?.[1];
+    if (name !== family && name?.toLowerCase() === family.toLowerCase())
+      throw new Error(`"${family}" is listed as "${name}"; use the catalog name "${name}".`);
+    if (name !== family || declared !== license.metadata)
+      throw new Error(
+        `"${family}" is not verified as ${license.id}: ${base}/METADATA.pb names ${JSON.stringify(name)} with license ${JSON.stringify(declared)}. Use the system stack.`
+      );
+    const body = Buffer.from(
+      await (await request(fetchImpl, `${base}/${license.file}`, { redirect: "error" })).arrayBuffer()
+    );
+    if (!license.text.test(body.toString("utf8")))
+      throw new Error(
+        `"${family}" is not verified as ${license.id}: ${base}/${license.file} does not contain the license text. Use the system stack.`
+      );
+    return { slug, license, body };
+  }
+  throw new Error(
+    `"${family}" is not an OFL or Apache licensed Google Fonts family (checked ${tried.join(", ")}). Use the system stack.`
+  );
+}
+async function download(fetchImpl, url) {
+  const bytes = Buffer.from(
+    await (await request(fetchImpl, url, { redirect: "error" })).arrayBuffer()
+  );
+  if (bytes.length > MAX_FILE_BYTES)
+    throw new Error(`Font file is ${bytes.length} bytes, over the ${MAX_FILE_BYTES} limit: ${url}`);
+  if (bytes.toString("latin1", 0, 4) !== "wOF2") throw new Error(`Font file is not woff2: ${url}`);
+  return bytes;
+}
+function assertWritableDestination(dest) {
+  if (!existsSync(dest)) return;
+  if (!statSync(dest).isDirectory() || readdirSync(dest).length > 0)
+    throw new Error(
+      `Font destination already exists and is not empty: ${dest}. Choose a new --dest or remove it.`
+    );
+}
+function faceRule(family, weights, file) {
+  const weight = weights.length > 1 ? `${weights[0]} ${weights.at(-1)}` : `${weights[0]}`;
+  return `@font-face {
+  font-family: "${family}";
+  font-style: normal;
+  font-weight: ${weight};
+  font-display: swap;
+  src: url("${file}") format("woff2");
+}
+`;
+}
+async function fetchDesignFonts({ families, dest, fetchImpl = fetch }) {
+  if (!dest) throw new Error("fonts fetch requires --dest <design>/source/assets/fonts.");
+  const specs = (families ?? []).map(parseFontFamily);
+  if (specs.length === 0)
+    throw new Error('fonts fetch requires at least one --family "<Name>:<weights>".');
+  if (specs.length > MAX_FAMILIES)
+    throw new Error(
+      `${specs.length} families requested (${specs.map(({ family }) => family).join(", ")}); at most ${MAX_FAMILIES}.`
+    );
+  const names = specs.map(({ family }) => family.toLowerCase());
+  if (new Set(names).size !== names.length)
+    throw new Error(
+      `--family names a family twice: ${specs.map(({ family }) => family).join(", ")}.`
+    );
+  const target = resolve2(dest);
+  if (basename(target).startsWith(STAGING_PREFIX))
+    throw new Error(
+      `Font destination uses the reserved staging prefix ${STAGING_PREFIX}: ${target}`
+    );
+  assertWritableDestination(target);
+  const files = /* @__PURE__ */ new Map();
+  const rules = [];
+  const summaries = [];
+  let totalBytes = 0;
+  const add = (path, bytes) => {
+    totalBytes += bytes.length;
+    if (totalBytes > MAX_TOTAL_BYTES)
+      throw new Error(`Font snapshot exceeds ${MAX_TOTAL_BYTES} bytes at ${path}.`);
+    files.set(path, bytes);
+  };
+  for (const { family, weights } of specs) {
+    const { slug, license, body } = await verifiedLicense(fetchImpl, family);
+    const source = `${CSS_ENDPOINT}?family=${encodeURIComponent(family).replaceAll("%20", "+")}:wght@${weights.join(";")}&display=swap`;
+    const css = await (await request(fetchImpl, source, { headers: { "user-agent": USER_AGENT } })).text();
+    const faces = latinFontFaces(css, family);
+    const byUrl = /* @__PURE__ */ new Map();
+    for (const weight of weights) {
+      const face = faces.find((item) => item.weight === weight);
+      if (!face)
+        throw new Error(`"${family}" has no Latin woff2 face for weight ${weight} in ${source}`);
+      byUrl.set(face.url, [...byUrl.get(face.url) ?? [], weight]);
+    }
+    rules.push(`/* ${family} (${license.id}, ${slug}/${license.file}): ${source} */
+`);
+    for (const [url, covered] of byUrl) {
+      const range = covered.length > 1 ? `${covered[0]}-${covered.at(-1)}` : `${covered[0]}`;
+      const file = `${slug}/${slug}-${range}-latin.woff2`;
+      add(file, await download(fetchImpl, url));
+      rules.push(faceRule(family, covered, file));
+    }
+    add(`${slug}/${license.file}`, body);
+    summaries.push({
+      family,
+      license: license.id,
+      weights,
+      source,
+      licenseFile: `${slug}/${license.file}`
+    });
+  }
+  add("fonts.css", Buffer.from(rules.join("")));
+  const parent = dirname(target);
+  const missingParents = [];
+  for (let directory = parent; !existsSync(directory); directory = dirname(directory))
+    missingParents.push(directory);
+  const createdParents = [];
+  let staging;
+  try {
+    for (const directory of missingParents.reverse()) {
+      mkdirSync(directory);
+      createdParents.push(directory);
+    }
+    const staleBefore = Date.now() - STAGING_MAX_AGE_MS;
+    for (const entry of readdirSync(parent, { withFileTypes: true })) {
+      if (!entry.isDirectory() || !entry.name.startsWith(STAGING_PREFIX)) continue;
+      const path = join2(parent, entry.name);
+      try {
+        if (statSync(path).mtimeMs < staleBefore) rmSync(path, { recursive: true });
+      } catch (error) {
+        if (error.code === "ENOENT") continue;
+        throw new Error(`Could not remove stale staging folder ${path}: ${error.message}`);
+      }
+    }
+    staging = mkdtempSync(join2(parent, STAGING_PREFIX));
+    for (const [path, bytes] of files) {
+      mkdirSync(dirname(join2(staging, path)), { recursive: true });
+      writeFileSync(join2(staging, path), bytes, { flag: "wx" });
+    }
+    assertWritableDestination(target);
+    if (existsSync(target)) rmdirSync(target);
+    chmodSync(staging, 493);
+    renameSync(staging, target);
+  } catch (error) {
+    const cleanupErrors = [];
+    for (const directory of [...staging ? [staging] : [], ...createdParents.reverse()]) {
+      try {
+        if (directory === staging) rmSync(directory, { recursive: true, force: true });
+        else if (readdirSync(directory).length === 0) rmdirSync(directory);
+      } catch (cleanupError) {
+        cleanupErrors.push({ path: directory, message: cleanupError.message });
+      }
+    }
+    if (cleanupErrors.length > 0) {
+      error.cleanupErrors = cleanupErrors;
+      error.message += cleanupErrors.map(({ path, message }) => ` (cleanup also failed for ${path}: ${message})`).join("");
+    }
+    throw error;
+  }
+  return {
+    ok: true,
+    dest: target,
+    css: join2(target, "fonts.css"),
+    families: summaries,
+    files: [...files].map(([path, bytes]) => ({ path, bytes: bytes.length })),
+    totalBytes
+  };
+}
+
 // packages/design/lib/design/studio-lifecycle.mjs
-import { join as join2 } from "node:path";
+import { join as join3 } from "node:path";
 function localUrl(value, service, path) {
   if (typeof value !== "string") return null;
   try {
@@ -359,7 +618,7 @@ async function manageDesignStudio(file, { action = "status", instanceId, env = p
   const services = (await listArtifactReviewServers({ env, fetchImpl })).filter(
     (service2) => service2.kind === "design" && service2.projectRoot === current.root
   );
-  const launcher = readJson(join2(current.root, ".design/server.json"), null);
+  const launcher = readJson(join3(current.root, ".design/server.json"), null);
   let service = services.find((value) => value.instanceId === (instanceId ?? launcher?.instanceId));
   if (instanceId !== void 0 && !service)
     throw new Error(
@@ -643,7 +902,7 @@ async function attachedArtifactFrame(page, artifactId, warn) {
     { state: "attached", timeout: 5e3 }
   );
   try {
-    return await new Promise((resolve3, reject) => {
+    return await new Promise((resolve4, reject) => {
       let settled = false;
       const finish = (error, frame) => {
         if (settled) return;
@@ -652,7 +911,7 @@ async function attachedArtifactFrame(page, artifactId, warn) {
         page.off("frameattached", inspect);
         page.off("framenavigated", inspect);
         if (error) reject(error);
-        else resolve3(frame);
+        else resolve4(frame);
       };
       const inspect = async (frame) => {
         if (settled || frame === page.mainFrame?.()) return;
@@ -896,7 +1155,7 @@ function verifyDesignDocument(file, report) {
   const images = (Array.isArray(report.screenshots) ? report.screenshots : []).filter((item) => {
     const path = typeof item === "string" ? item : item?.path;
     try {
-      return typeof path === "string" && isPng(readFileSync(resolve2(path)));
+      return typeof path === "string" && isPng(readFileSync(resolve3(path)));
     } catch {
       return false;
     }
@@ -920,9 +1179,37 @@ function verifyDesignDocument(file, report) {
     screenshotCount: images.length,
     primaryJourneysChecked: Boolean(journeys)
   };
-  atomicJson(join3(current.root, ".design/verification", `${current.revision}.json`), saved);
+  atomicJson(join4(current.root, ".design/verification", `${current.revision}.json`), saved);
   return saved;
 }
+var HELP_FLAGS = /* @__PURE__ */ new Set(["--help", "-h"]);
+var COMMAND_SUMMARIES = Object.freeze({
+  inspect: "Report the design document and its current render.",
+  validate: "Validate the design document without rendering.",
+  render: "Render the design document into its review revision.",
+  open: "Open the local review studio.",
+  studio: "Report or stop a running local studio (--action status|stop).",
+  "view-context": "Report what the studio is showing.",
+  export: "Export the design as html, json, or markdown.",
+  feedback: "Inspect, export, or import review feedback.",
+  verify: "Record a browser verification report.",
+  share: "Create a hosted review of the current revision.",
+  publish: "Publish the current revision to the existing hosted review.",
+  sync: "Retrieve hosted review feedback.",
+  manage: "Manage a hosted review (--action rotate|pause|resume|revoke|delete|recovery|restore).",
+  handoff: "Inspect or update the review handoff.",
+  fonts: "Download open-license fonts (fonts fetch --family ... --dest ...)."
+});
+function commandHelp(command) {
+  if (!Object.hasOwn(COMMAND_SUMMARIES, command))
+    throw new Error(`Unknown command: ${command}. Run design.mjs --help for the command list.`);
+  return {
+    command,
+    usage: command === "fonts" ? 'design.mjs fonts fetch --family "<Name>:<weights>" [--family ...] --dest <dir>' : `design.mjs ${command} <design-document.json> [options]`,
+    summary: COMMAND_SUMMARIES[command],
+    note: "Run design.mjs --help for every option. A help request never reads, renders, or sends anything."
+  };
+}
 async function designUtility(argv, {
   stdout = (value) => process.stdout.write(`${JSON.stringify(value)}
 `),
@@ -930,9 +1217,9 @@ async function designUtility(argv, {
   env = process.env,
   fetchImpl = fetch
 } = {}) {
-  if (argv.length === 0 || argv[0] === "--help" || argv[0] === "help") {
+  if (argv.length === 0 || ["--help", "-h", "help"].includes(argv[0])) {
     const help = {
-      usage: "design.mjs inspect|validate|render|open|studio|view-context|export|feedback|verify|share|publish|sync|manage|handoff <design-document.json>",
+      usage: 'design.mjs inspect|validate|render|open|studio|view-context|export|feedback|verify|share|publish|sync|manage|handoff <design-document.json> | design.mjs fonts fetch --family "<Name>:<weights>" [--family ...] --dest <dir>',
       flags: [
         "--json",
         "--no-open",
@@ -949,14 +1236,23 @@ async function designUtility(argv, {
         "--allow-stale",
         "--variant <id>",
         "--pins <id,id>",
-        "--summary <text>"
+        "--summary <text>",
+        "--family <Name>:<weight,weight> (fonts fetch; at most 2 families, 3 weights each)",
+        "--dest <design>/source/assets/fonts (fonts fetch)"
       ],
-      note: "The host authors design sources. This utility only validates, renders, reviews and exports them."
+      note: "The host authors design sources. This utility only validates, renders, reviews and exports them; fonts fetch downloads open-license fonts only when run."
     };
     stdout(help);
     return help;
   }
   const [command, input, ...args] = argv;
+  if (argv.some((value) => HELP_FLAGS.has(value))) {
+    const help = commandHelp(command);
+    stdout(help);
+    return help;
+  }
+  if (typeof input === "string" && input.startsWith("-"))
+    throw new Error(`${input} must be a design document path, not an option.`);
   if (![
     "inspect",
     "validate",
@@ -971,10 +1267,11 @@ async function designUtility(argv, {
     "publish",
     "sync",
     "manage",
-    "handoff"
+    "handoff",
+    "fonts"
   ].includes(command) || !input)
     throw new Error(
-      "Usage: design.mjs inspect|validate|render|open|studio|view-context|export|feedback|verify|share|publish|sync|manage|handoff <design-document.json> [--json] [--no-open] [--view canvas|prototype|walkthrough]"
+      'Usage: design.mjs inspect|validate|render|open|studio|view-context|export|feedback|verify|share|publish|sync|manage|handoff <design-document.json> [--json] [--no-open] [--view canvas|prototype|walkthrough] | design.mjs fonts fetch --family "<Name>:<weights>" [--family ...] --dest <dir>'
     );
   const flags = {};
   for (let i = 0; i < args.length; i++) {
@@ -997,14 +1294,28 @@ async function designUtility(argv, {
       "scope",
       "revision",
       "request-time",
-      "allow-stale"
+      "allow-stale",
+      "family",
+      "dest"
     ].includes(key))
       throw new Error(`Unknown option: ${args[i]}`);
-    flags[key] = ["json", "no-open", "allow-stale"].includes(key) ? true : args[++i];
+    if (["family", "dest"].includes(key) && command !== "fonts")
+      throw new Error(`Unknown option for ${command}: ${args[i]}`);
+    if (key === "family") flags.family = [...flags.family ?? [], args[++i]];
+    else flags[key] = ["json", "no-open", "allow-stale"].includes(key) ? true : args[++i];
   }
   if (flags.view && !["canvas", "prototype", "walkthrough"].includes(flags.view))
     throw new Error("View must be canvas, prototype, or walkthrough.");
-  const file = resolve2(input);
+  if (command === "fonts") {
+    if (input !== "fetch")
+      throw new Error(
+        'Usage: design.mjs fonts fetch --family "<Name>:<weights>" [--family ...] --dest <dir>'
+      );
+    const result2 = await fetchDesignFonts({ families: flags.family, dest: flags.dest, fetchImpl });
+    stdout(result2);
+    return result2;
+  }
+  const file = resolve3(input);
   let result;
   if (command === "view-context")
     result = readDesignViewContext(file, { requestTime: flags["request-time"] });
@@ -1020,7 +1331,7 @@ async function designUtility(argv, {
     if (action === "inspect") result = readDesignHandoff(file);
     else {
       const snapshot = readDesignHandoff(file);
-      const input2 = flags.input ? readJson(resolve2(flags.input)) : {};
+      const input2 = flags.input ? readJson(resolve3(flags.input)) : {};
       result = await updateDesignHandoff(file, {
         ...input2,
         action,
@@ -1074,25 +1385,25 @@ async function designUtility(argv, {
   }
   if (command === "export") {
     const current = currentDesign(file), view = flags.view ?? current.document.defaultView;
-    const state = readJson(join3(current.root, ".design/studio-state.json"), { state: {} }).state;
+    const state = readJson(join4(current.root, ".design/studio-state.json"), { state: {} }).state;
     if (flags.format && flags.format !== "html")
       throw new Error(
         "Portable export supports HTML. Use the studio PNG action for browser-rendered captures."
       );
-    const output = resolve2(flags.output ?? join3(current.root, `${view}-export.html`));
-    if (existsSync(output))
+    const output = resolve3(flags.output ?? join4(current.root, `${view}-export.html`));
+    if (existsSync2(output))
       throw new Error(`Export already exists: ${output}. Choose a new --output path.`);
-    mkdirSync(dirname(output), { recursive: true });
-    writeFileSync(output, standaloneDesignHtml({ ...current, state }, view), { flag: "wx" });
+    mkdirSync2(dirname2(output), { recursive: true });
+    writeFileSync2(output, standaloneDesignHtml({ ...current, state }, view), { flag: "wx" });
     result = { ok: true, output, view, revision: current.revision };
   }
   if (command === "verify") {
     if (!flags.report) throw new Error("verify requires --report <browser-report.json>.");
-    result = verifyDesignDocument(file, readJson(resolve2(flags.report)));
+    result = verifyDesignDocument(file, readJson(resolve3(flags.report)));
   }
   if (command === "feedback") {
     const action = flags.action ?? "inspect";
-    if (action !== "import") await syncDesignShare(file, { env, fetchImpl });
+    const synced = action === "import" ? void 0 : await syncDesignShare(file, { env, fetchImpl, unavailable: "skip" });
     if (action === "import")
       result = await importDesignFeedback(file, {
         input: flags.input,
@@ -1108,12 +1419,12 @@ async function designUtility(argv, {
       if (!["current", "all"].includes(scope))
         throw new Error("Feedback export scope must be current or all.");
       if (!flags.output) throw new Error("Feedback export requires --output <path>.");
-      const output = resolve2(flags.output);
-      if (existsSync(output))
+      const output = resolve3(flags.output);
+      if (existsSync2(output))
         throw new Error("Feedback export already exists. Choose a new --output path.");
       const snapshot = exportDesignReview(file, { scope, env });
-      mkdirSync(dirname(output), { recursive: true });
-      writeFileSync(output, serializeDesignReviewExport(snapshot, format), {
+      mkdirSync2(dirname2(output), { recursive: true });
+      writeFileSync2(output, serializeDesignReviewExport(snapshot, format), {
         flag: "wx",
         mode: 384
       });
@@ -1132,7 +1443,7 @@ async function designUtility(argv, {
         env
       });
     else if (action === "select") {
-      const current = currentDesign(file), saved = readJson(join3(current.root, ".design/studio-state.json"), {
+      const current = currentDesign(file), saved = readJson(join4(current.root, ".design/studio-state.json"), {
         state: {},
         stateVersion: 0
       });
@@ -1152,6 +1463,8 @@ async function designUtility(argv, {
         revision: current.revision
       };
     } else throw new Error("Feedback action must be inspect, export, import, select, or resolve.");
+    if (synced?.skipped)
+      result = { ...result, sync: { skipped: synced.skipped, reason: synced.reason } };
   }
   stdout(result);
   return result;