@liustack/pptwise 0.22.0

package/dist/cli.js

@@ -0,0 +1,4753 @@
+#!/usr/bin/env node
+import {
+  PptxIRV3Schema,
+  VERSION,
+  assembleDeck,
+  buildAssetBrief,
+  disassembleDeck,
+  extractBrandTheme,
+  formatInvalidSpecError,
+  migrateBannerHeadingToTwoColumn,
+  migrateBloomToClassroom,
+  migrateChromeToBranding,
+  migrateDeckPlanToSpec,
+  migrateIrV3ToV4,
+  migrateLogoWallToImageGrid,
+  parseBrandThemeFile,
+  registerBrandThemeFile,
+  resolveSpecThemeId,
+  slugify,
+  specJsonSchema,
+  validateSpec
+} from "./chunk-M35M4QUC.js";
+import {
+  installNodePlatform,
+  isMissingModuleError,
+  proxyFetch
+} from "./chunk-3ZUKISTY.js";
+import {
+  AUDIENCE_VALUES,
+  CANONICAL_THEME_IDS,
+  CANVAS_H_PX,
+  CANVAS_W_PX,
+  FORMAT_BY_MIME,
+  MIME_BY_SNIFFED_FORMAT,
+  NARRATIVE_PRESETS,
+  PACING_BUDGETS,
+  PptwiseError,
+  STRATEGY_DEFINITIONS,
+  StyleOverrideSchema,
+  assertContrastFloor,
+  auditDeck,
+  formatIssues,
+  formatWarnings,
+  generatePptx,
+  getInstalledThemeIds,
+  irJsonSchema,
+  listThemes,
+  renderSlideSvg,
+  resolveNarrative,
+  sniffImageFormat,
+  styleJsonSchema,
+  validateIr
+} from "./chunk-WL5KWYKS.js";
+import {
+  getPlatform
+} from "./chunk-VUOLBHD7.js";
+
+// src/cli.ts
+import { Command } from "commander";
+
+// src/cli/commands.ts
+import { mkdir as mkdir4, readdir as readdir3, readFile as readFile6, rm, writeFile as writeFile3 } from "fs/promises";
+import { basename as basename4, dirname as dirname3, join as join5, relative as relative2, resolve as resolve6 } from "path";
+
+// src/cli/config.ts
+import { readFile as readFile2 } from "fs/promises";
+import { dirname, join as join2, resolve as resolve2 } from "path";
+import { z as z2 } from "zod";
+
+// src/cli/home.ts
+import { cpSync, existsSync, realpathSync, renameSync, rmSync } from "fs";
+import { homedir as osHomedir } from "os";
+import { join, resolve } from "path";
+
+// src/cli/product-env.ts
+var PRODUCT_ENV_PREFIX = "PPTWISE_";
+var LEGACY_ENV_PREFIXES = ["PPTPRESS_", "PPTFAST_"];
+var warnedLegacyKeys = /* @__PURE__ */ new Set();
+function productEnvName(suffix) {
+  return `${PRODUCT_ENV_PREFIX}${suffix}`;
+}
+function legacyEnvNames(suffix) {
+  return LEGACY_ENV_PREFIXES.map((prefix) => `${prefix}${suffix}`);
+}
+function nonempty(value) {
+  return value === void 0 || value === "" ? void 0 : value;
+}
+function warnLegacy(legacyKey, currentKey) {
+  if (warnedLegacyKeys.has(legacyKey)) return;
+  warnedLegacyKeys.add(legacyKey);
+  process.stderr.write(`${legacyKey} is deprecated. Use ${currentKey} instead.
+`);
+}
+function resolveProductEnv(suffix, env = process.env) {
+  const currentKey = productEnvName(suffix);
+  const current = nonempty(env[currentKey]);
+  if (current !== void 0) return current;
+  for (const legacyKey of legacyEnvNames(suffix)) {
+    const legacy = nonempty(env[legacyKey]);
+    if (legacy !== void 0) {
+      warnLegacy(legacyKey, currentKey);
+      return legacy;
+    }
+  }
+  return void 0;
+}
+
+// src/cli/home.ts
+var HOME_DIRNAME = ".pptwise";
+var LEGACY_HOME_DIRNAMES = [".pptpress", ".pptfast"];
+function pptwiseHome(opts = {}) {
+  const env = opts.env ?? process.env;
+  const fromEnv = resolveProductEnv("HOME", env);
+  if (fromEnv !== void 0) return fromEnv;
+  const home = (opts.homedir ?? osHomedir)();
+  const next = join(home, HOME_DIRNAME);
+  migrateLegacyHomes(home, next);
+  return next;
+}
+function migrateLegacyHomes(home, nextDir) {
+  if (existsSync(nextDir)) return;
+  for (const dirname5 of LEGACY_HOME_DIRNAMES) {
+    const legacy = join(home, dirname5);
+    if (existsSync(legacy)) {
+      copyLegacyHome(legacy, nextDir);
+      return;
+    }
+  }
+}
+function copyLegacyHome(legacyDir, nextDir) {
+  const source = realpathSync(legacyDir);
+  const tmpDir = `${nextDir}.migrating`;
+  rmSync(tmpDir, { recursive: true, force: true });
+  try {
+    cpSync(source, tmpDir, { recursive: true });
+    renameSync(tmpDir, nextDir);
+  } catch (error) {
+    try {
+      rmSync(tmpDir, { recursive: true, force: true });
+    } catch {
+    }
+    throw error;
+  }
+}
+function decksRoot(config2, opts) {
+  return resolve(pptwiseHome(opts), config2?.decksDir ?? "decks");
+}
+function userConfigPath(opts) {
+  return join(pptwiseHome(opts), "config.json");
+}
+
+// src/cli/image-config.ts
+import { chmodSync, lstatSync } from "fs";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { z } from "zod";
+var ImageProviderConfigSchema = z.object({
+  apiKey: z.string().optional()
+}).strict();
+var OpenverseConfigSchema = z.object({
+  clientId: z.string().optional(),
+  clientSecret: z.string().optional()
+}).strict();
+var GENERATOR_IDS = ["grok", "codex", "antigravity"];
+var DEFAULT_GENERATOR_ORDER = ["grok", "codex", "antigravity"];
+var DEFAULT_GENERATOR_TIMEOUT_MS = 18e4;
+var GeneratorFlagsSchema = z.object({ enabled: z.boolean().optional() }).strict();
+var GeneratorsConfigSchema = z.object({
+  grok: GeneratorFlagsSchema.optional(),
+  codex: GeneratorFlagsSchema.optional(),
+  antigravity: GeneratorFlagsSchema.optional(),
+  order: z.array(z.enum(GENERATOR_IDS)).optional(),
+  timeoutMs: z.number().int().positive().optional()
+}).strict();
+var ImagesConfigSchema = z.object({
+  pexels: ImageProviderConfigSchema.optional(),
+  pixabay: ImageProviderConfigSchema.optional(),
+  openverse: OpenverseConfigSchema.optional(),
+  generators: GeneratorsConfigSchema.optional()
+}).strict();
+var API_KEY_PROVIDERS = ["pexels", "pixabay"];
+var ENV_SUFFIX_BY_PROVIDER = {
+  pexels: "PEXELS_API_KEY",
+  pixabay: "PIXABAY_API_KEY"
+};
+var FORBIDDEN_SEGMENTS = /* @__PURE__ */ new Set(["__proto__", "constructor", "prototype"]);
+var CLI_KEYS = {
+  "pexels.apiKey": {
+    cliKey: "pexels.apiKey",
+    path: ["images", "pexels", "apiKey"],
+    omitValue: true,
+    secret: true,
+    kind: "string"
+  },
+  "pixabay.apiKey": {
+    cliKey: "pixabay.apiKey",
+    path: ["images", "pixabay", "apiKey"],
+    omitValue: true,
+    secret: true,
+    kind: "string"
+  },
+  "openverse.clientId": {
+    cliKey: "openverse.clientId",
+    path: ["images", "openverse", "clientId"],
+    omitValue: false,
+    secret: true,
+    kind: "string"
+  },
+  "openverse.clientSecret": {
+    cliKey: "openverse.clientSecret",
+    path: ["images", "openverse", "clientSecret"],
+    omitValue: true,
+    secret: true,
+    kind: "string"
+  },
+  "images.generators.grok.enabled": {
+    cliKey: "images.generators.grok.enabled",
+    path: ["images", "generators", "grok", "enabled"],
+    omitValue: false,
+    secret: false,
+    kind: "boolean"
+  },
+  "images.generators.codex.enabled": {
+    cliKey: "images.generators.codex.enabled",
+    path: ["images", "generators", "codex", "enabled"],
+    omitValue: false,
+    secret: false,
+    kind: "boolean"
+  },
+  "images.generators.antigravity.enabled": {
+    cliKey: "images.generators.antigravity.enabled",
+    path: ["images", "generators", "antigravity", "enabled"],
+    omitValue: false,
+    secret: false,
+    kind: "boolean"
+  },
+  "images.generators.order": {
+    cliKey: "images.generators.order",
+    path: ["images", "generators", "order"],
+    omitValue: false,
+    secret: false,
+    kind: "order"
+  },
+  "images.generators.timeoutMs": {
+    cliKey: "images.generators.timeoutMs",
+    path: ["images", "generators", "timeoutMs"],
+    omitValue: false,
+    secret: false,
+    kind: "timeoutMs"
+  }
+};
+function maskKey(value) {
+  if (value.length <= 8) return "****";
+  return `${value.slice(0, 6)}...${value.slice(-2)}`;
+}
+function assertSafeConfigKeyPath(key) {
+  for (const segment of key.split(".")) {
+    if (FORBIDDEN_SEGMENTS.has(segment)) {
+      throw new PptwiseError(`refusing to set "${key}": "${segment}" is not a valid config key`);
+    }
+  }
+}
+function parseCliConfigKey(key) {
+  assertSafeConfigKeyPath(key);
+  const hit = CLI_KEYS[key];
+  if (!hit) {
+    throw new PptwiseError(
+      `unknown config key "${key}" \u2014 expected pexels.apiKey, pixabay.apiKey, openverse.clientId, openverse.clientSecret, or images.generators.*`
+    );
+  }
+  return hit;
+}
+function providerNamedInFile(file, provider) {
+  return file?.images?.[provider] !== void 0;
+}
+function nonempty2(value) {
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
+function resolveOne(file, env, provider) {
+  const namedInFile = providerNamedInFile(file, provider);
+  if (namedInFile) {
+    const apiKey2 = nonempty2(file?.images?.[provider]?.apiKey);
+    return { apiKey: apiKey2, source: apiKey2 ? "file" : null, namedInFile: true };
+  }
+  const apiKey = nonempty2(resolveProductEnv(ENV_SUFFIX_BY_PROVIDER[provider], env));
+  return { apiKey, source: apiKey ? "env" : null, namedInFile: false };
+}
+function resolveOpenverse(file, env) {
+  const namedInFile = providerNamedInFile(file, "openverse");
+  if (namedInFile) {
+    const clientId2 = nonempty2(file?.images?.openverse?.clientId);
+    const clientSecret2 = nonempty2(file?.images?.openverse?.clientSecret);
+    const ready2 = Boolean(clientId2 && clientSecret2);
+    return { clientId: clientId2, clientSecret: clientSecret2, source: ready2 ? "file" : null, namedInFile: true, ready: ready2 };
+  }
+  const clientId = nonempty2(resolveProductEnv("OPENVERSE_CLIENT_ID", env));
+  const clientSecret = nonempty2(resolveProductEnv("OPENVERSE_CLIENT_SECRET", env));
+  const ready = Boolean(clientId && clientSecret);
+  return { clientId, clientSecret, source: ready ? "env" : null, namedInFile: false, ready };
+}
+function resolveImageKeys(opts = {}) {
+  const file = opts.file ?? null;
+  const env = opts.env ?? process.env;
+  return {
+    pexels: resolveOne(file, env, "pexels"),
+    pixabay: resolveOne(file, env, "pixabay"),
+    openverse: resolveOpenverse(file, env)
+  };
+}
+function resolveGenerators(opts = {}) {
+  const g = opts.file?.images?.generators;
+  const order = g?.order && g.order.length > 0 ? g.order : DEFAULT_GENERATOR_ORDER;
+  return {
+    enabled: {
+      grok: g?.grok?.enabled === true,
+      codex: g?.codex?.enabled === true,
+      antigravity: g?.antigravity?.enabled === true
+    },
+    order,
+    timeoutMs: typeof g?.timeoutMs === "number" && g.timeoutMs > 0 ? g.timeoutMs : DEFAULT_GENERATOR_TIMEOUT_MS
+  };
+}
+function parseCliConfigValue(parsed, raw) {
+  if (parsed.kind === "boolean") {
+    const v = raw.trim().toLowerCase();
+    if (v !== "true" && v !== "false") {
+      throw new PptwiseError(`${parsed.cliKey} must be true or false`);
+    }
+    return v === "true";
+  }
+  if (parsed.kind === "order") {
+    const names = raw.split(",").map((s) => s.trim()).filter((s) => s !== "");
+    const unknown = names.find((n) => !GENERATOR_IDS.includes(n));
+    if (unknown) {
+      throw new PptwiseError(`unknown generator "${unknown}" \u2014 expected grok, codex, or antigravity`);
+    }
+    if (names.length === 0) {
+      throw new PptwiseError("images.generators.order must not be empty");
+    }
+    return names;
+  }
+  if (parsed.kind === "timeoutMs") {
+    if (!/^[0-9]+$/.test(raw.trim()) || Number(raw) <= 0) {
+      throw new PptwiseError(`${parsed.cliKey} must be a positive integer`);
+    }
+    return Number(raw);
+  }
+  return raw;
+}
+function knownSecretsFrom(keys) {
+  const secrets = [];
+  for (const provider of API_KEY_PROVIDERS) {
+    const apiKey = keys[provider].apiKey;
+    if (apiKey && apiKey.length >= 6) secrets.push(apiKey);
+  }
+  const { clientId, clientSecret } = keys.openverse;
+  if (clientSecret && clientSecret.length >= 6) secrets.push(clientSecret);
+  if (clientId && clientId.length >= 6) secrets.push(clientId);
+  return secrets;
+}
+function assertNotSymlink(path2) {
+  let st;
+  try {
+    st = lstatSync(path2);
+  } catch (e) {
+    if (e.code === "ENOENT") return;
+    throw e;
+  }
+  if (st.isSymbolicLink()) {
+    throw new PptwiseError(`refusing to write ${path2}: it is a symlink`);
+  }
+}
+function asPlainObject(value) {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return { ...value };
+  }
+  return {};
+}
+async function readRawUserConfig() {
+  const path2 = userConfigPath();
+  let text;
+  try {
+    text = await readFile(path2, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return {};
+    throw e;
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    throw new PptwiseError(`${path2} is not valid JSON: ${e.message}`);
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    throw new PptwiseError(`${path2} must be a JSON object`);
+  }
+  return raw;
+}
+async function persistUserConfigValue(path2, value) {
+  for (const segment of path2) {
+    if (FORBIDDEN_SEGMENTS.has(segment) || segment === "") {
+      throw new PptwiseError(`refusing to set "${path2.join(".")}": "${segment}" is not a valid config key`);
+    }
+  }
+  if (path2.length === 0) {
+    throw new PptwiseError("refusing to set an empty config path");
+  }
+  const filePath = userConfigPath();
+  assertNotSymlink(filePath);
+  const raw = await readRawUserConfig();
+  let cursor = raw;
+  for (let i = 0; i < path2.length - 1; i++) {
+    const segment = path2[i];
+    const next = asPlainObject(cursor[segment]);
+    cursor[segment] = next;
+    cursor = next;
+  }
+  const leaf = path2[path2.length - 1];
+  if (value === "") {
+    delete cursor[leaf];
+  } else {
+    cursor[leaf] = value;
+  }
+  await mkdir(pptwiseHome(), { recursive: true });
+  const text = JSON.stringify(raw, null, 2) + "\n";
+  await writeFile(filePath, text, { encoding: "utf8", mode: 384 });
+  try {
+    chmodSync(filePath, 384);
+  } catch {
+  }
+  return filePath;
+}
+function pexelsApplyUrl() {
+  return "https://www.pexels.com/api/";
+}
+function pixabayApplyUrl() {
+  return "https://pixabay.com/api/docs/";
+}
+function missingKeysError(kind) {
+  if (kind === "pixabay") {
+    return new PptwiseError(
+      `Pixabay is not configured. Apply at ${pixabayApplyUrl()}, then run \`pptwise config set pixabay.apiKey\`.`
+    );
+  }
+  return new PptwiseError(
+    `Pexels is not configured. Apply at ${pexelsApplyUrl()}, then run \`pptwise config set pexels.apiKey\`.`
+  );
+}
+
+// src/cli/config.ts
+var ConfigSchema = z2.object({
+  theme: z2.string().optional(),
+  style: StyleOverrideSchema.optional(),
+  decksDir: z2.string().optional(),
+  outDir: z2.string().optional()
+}).strict();
+var UserConfigSchema = z2.object({
+  theme: z2.string().optional(),
+  style: StyleOverrideSchema.optional(),
+  decksDir: z2.string().optional(),
+  images: ImagesConfigSchema.optional()
+}).strict();
+var CONFIG_FILENAME = "pptwise.config.json";
+var LEGACY_CONFIG_FILENAMES = ["pptpress.config.json", "pptfast.config.json"];
+async function readConfigFile(path2, schema) {
+  let text;
+  try {
+    text = await readFile2(path2, "utf8");
+  } catch {
+    return null;
+  }
+  let raw;
+  try {
+    raw = JSON.parse(text);
+  } catch (e) {
+    throw new PptwiseError(`${path2} is not valid JSON: ${e.message}`);
+  }
+  const r = schema.safeParse(raw);
+  if (!r.success) {
+    const detail = r.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new PptwiseError(`invalid ${path2}:
+${detail}`);
+  }
+  return { path: path2, config: r.data };
+}
+async function findConfig(startDir) {
+  let dir = resolve2(startDir);
+  for (; ; ) {
+    const hit = await readConfigFile(join2(dir, CONFIG_FILENAME), ConfigSchema);
+    if (hit) return hit;
+    for (const name of LEGACY_CONFIG_FILENAMES) {
+      const legacy = await readConfigFile(join2(dir, name), ConfigSchema);
+      if (legacy) return legacy;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+async function findUserConfig() {
+  return readConfigFile(userConfigPath(), UserConfigSchema);
+}
+
+// src/cli/deck-dir.ts
+import { copyFile, mkdir as mkdir2, readFile as readFile4, readdir, stat, writeFile as writeFile2 } from "fs/promises";
+import { basename as basename2, extname as extname2, isAbsolute as isAbsolute2, join as join3, relative, resolve as resolve4 } from "path";
+
+// src/cli/load-ir.ts
+import { readFile as readFile3 } from "fs/promises";
+import { basename, extname, isAbsolute, resolve as resolve3 } from "path";
+import { fileURLToPath } from "url";
+var MIME_BY_EXT = {
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif"
+};
+var EXT_BY_MIME = {
+  "image/png": ".png",
+  "image/jpeg": ".jpg",
+  "image/gif": ".gif",
+  "image/webp": ".webp"
+};
+function unwrapFileSrc(src, platform = process.platform) {
+  if (platform === "win32") {
+    const url = new URL(src);
+    let pathname = decodeURIComponent(url.pathname.replace(/\//g, "\\"));
+    if (url.hostname) return `\\\\${url.hostname}${pathname}`;
+    if (pathname.startsWith("\\") && pathname.length >= 3 && pathname[2] === ":") {
+      return pathname.slice(1);
+    }
+    return pathname;
+  }
+  return fileURLToPath(src);
+}
+async function loadIrFile(irPath, kind = "IR") {
+  let text;
+  try {
+    text = await readFile3(irPath, "utf8");
+  } catch {
+    throw new PptwiseError(`cannot read ${kind} file: ${irPath}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new PptwiseError(`${kind} file ${irPath} is not valid JSON: ${e.message}`);
+  }
+}
+async function readFromWorkspace(src, workspaceAssetsDir) {
+  const candidates = [resolve3(workspaceAssetsDir, src), resolve3(workspaceAssetsDir, basename(src))];
+  const seen = /* @__PURE__ */ new Set();
+  for (const candidate of candidates) {
+    if (seen.has(candidate)) continue;
+    seen.add(candidate);
+    try {
+      return await readFile3(candidate);
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+async function resolveLocalAssets(ir, baseDir, workspaceAssetsDir) {
+  for (const [name, asset] of Object.entries(ir.assets.images)) {
+    const src = asset.src;
+    if (src.startsWith("data:") || /^https?:\/\//.test(src)) continue;
+    const abs = src.startsWith("file:") ? unwrapFileSrc(src) : isAbsolute(src) ? src : resolve3(baseDir, src);
+    let bytes;
+    try {
+      bytes = await readFile3(abs);
+    } catch {
+      const fallback = workspaceAssetsDir && !isAbsolute(src) ? await readFromWorkspace(src, workspaceAssetsDir) : null;
+      if (!fallback) {
+        throw new PptwiseError(`asset "${name}": cannot read image file ${abs} (from src "${src}")`);
+      }
+      bytes = fallback;
+    }
+    if (bytes.length === 0) {
+      throw new PptwiseError(`asset "${name}": image file ${abs} is zero bytes \u2014 re-export or re-select the file`);
+    }
+    const ext = extname(abs).toLowerCase();
+    const mime = MIME_BY_EXT[ext];
+    if (mime) {
+      const sniffed = sniffImageFormat(bytes);
+      if (sniffed === null) {
+        throw new PptwiseError(
+          `asset "${name}": image file ${abs} has a corrupt or unrecognized header (extension claims ${mime}) \u2014 re-export or re-select the file`
+        );
+      }
+      const expected = FORMAT_BY_MIME[mime];
+      if (expected && sniffed !== expected) {
+        throw new PptwiseError(
+          `asset "${name}": image file ${abs} is named "${ext}" but its bytes are actually ${MIME_BY_SNIFFED_FORMAT[sniffed]} \u2014 rename the file to match its real format, or re-export/re-save it as a genuine ${mime}`
+        );
+      }
+      asset.src = `data:${mime};base64,${bytes.toString("base64")}`;
+      continue;
+    }
+    const recode = getPlatform().recodeImageToPng;
+    if (!recode) {
+      throw new PptwiseError(
+        `asset "${name}": unsupported image format "${extname(abs)}" \u2014 install sharp or convert to png/jpeg/gif`
+      );
+    }
+    asset.src = await recode(`data:application/octet-stream;base64,${bytes.toString("base64")}`);
+  }
+}
+
+// src/cli/deck-dir.ts
+var PLAN_FILENAME = "deck.plan.json";
+var SPEC_FILENAME = "deck.spec.json";
+var PAGES_DIRNAME = "pages";
+var ASSETS_DIRNAME = "assets";
+var THEME_FILENAME = "theme.json";
+function assertSafeFileSegment(id, context) {
+  const safeBase = resolve4("/pptwise-safe-base");
+  const rel = relative(safeBase, resolve4(safeBase, id));
+  const safe = !isAbsolute2(id) && !id.includes("/") && !id.includes("\\") && id !== ".." && !rel.startsWith("..") && !isAbsolute2(rel);
+  if (!safe) {
+    throw new PptwiseError(
+      `${context} "${id}" is not a safe file name \u2014 ids used as page/asset file names must not contain path separators or ".."`
+    );
+  }
+}
+async function isDeckDirectory(path2) {
+  try {
+    return (await stat(path2)).isDirectory();
+  } catch (e) {
+    if (e.code === "ENOENT") return false;
+    throw new PptwiseError(`cannot check ${path2}: ${e.message}`);
+  }
+}
+async function pathExists(path2) {
+  try {
+    await stat(path2);
+    return true;
+  } catch (e) {
+    if (e.code === "ENOENT") return false;
+    throw new PptwiseError(`cannot check path ${path2}: ${e.message}`);
+  }
+}
+async function resolveDeckTarget(arg, config2, cwd = process.cwd()) {
+  if (arg.trim() === "") throw new PptwiseError("deck target must not be empty");
+  if (arg.includes("/") || arg.includes("\\")) return resolve4(cwd, arg);
+  const local = resolve4(cwd, arg);
+  if (await pathExists(local)) return local;
+  const fallback = join3(decksRoot(config2), arg);
+  return await pathExists(fallback) ? fallback : local;
+}
+function expectedLayoutHint() {
+  const rows = [
+    [SPEC_FILENAME, "the locked spec (see `pptwise spec validate`)"],
+    [`${PAGES_DIRNAME}/<page-id>.json`, "one file per filled page (missing pages become placeholders)"],
+    [`${ASSETS_DIRNAME}/`, "optional local images"]
+  ];
+  const width = Math.max(...rows.map(([name]) => name.length)) + 2;
+  return rows.map(([name, desc]) => `  ${name.padEnd(width)}${desc}`).join("\n");
+}
+async function readSpecFile(dir) {
+  const specPath = join3(dir, SPEC_FILENAME);
+  const planPath = join3(dir, PLAN_FILENAME);
+  const [specExists, planExists] = await Promise.all([pathExists(specPath), pathExists(planPath)]);
+  if (specExists && planExists) {
+    throw new PptwiseError(
+      `both ${SPEC_FILENAME} and ${PLAN_FILENAME} exist in ${dir} \u2014 ambiguous, refusing to guess which one wins. Delete ${PLAN_FILENAME} once you have confirmed ${SPEC_FILENAME} is correct (\`pptwise migrate\` never deletes the source file it read)`
+    );
+  }
+  if (!specExists && planExists) {
+    throw new PptwiseError(
+      `${dir} has ${PLAN_FILENAME} but no ${SPEC_FILENAME} \u2014 deck project directories now use ${SPEC_FILENAME}. Run \`pptwise migrate ${dir} -o ${dir}\` to convert it`
+    );
+  }
+  let text;
+  try {
+    text = await readFile4(specPath, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") {
+      throw new PptwiseError(
+        `no ${SPEC_FILENAME} in ${dir} \u2014 expected a deck project directory:
+${expectedLayoutHint()}`
+      );
+    }
+    throw new PptwiseError(`cannot read spec file: ${specPath}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new PptwiseError(`spec file ${specPath} is not valid JSON: ${e.message}`);
+  }
+}
+async function readPages(dir) {
+  const pagesDir = join3(dir, PAGES_DIRNAME);
+  let entries;
+  try {
+    entries = (await readdir(pagesDir, { withFileTypes: true })).filter((entry) => entry.isFile() && extname2(entry.name) === ".json").map((entry) => entry.name);
+  } catch (e) {
+    if (e.code === "ENOENT") return {};
+    throw new PptwiseError(`cannot read ${PAGES_DIRNAME}/ directory ${pagesDir}: ${e.message}`);
+  }
+  const pages = {};
+  await Promise.all(
+    entries.map(async (entry) => {
+      const id = basename2(entry, ".json");
+      pages[id] = await loadIrFile(join3(pagesDir, entry), `page "${id}"`);
+    })
+  );
+  return pages;
+}
+async function scanAssets(dir) {
+  const assetsDir = join3(dir, ASSETS_DIRNAME);
+  let entries;
+  try {
+    entries = (await readdir(assetsDir, { withFileTypes: true })).filter((entry) => entry.isFile() && !entry.name.startsWith(".")).map((entry) => entry.name);
+  } catch (e) {
+    if (e.code === "ENOENT") return {};
+    throw new PptwiseError(`cannot read ${ASSETS_DIRNAME}/ directory ${assetsDir}: ${e.message}`);
+  }
+  const images2 = {};
+  const sourceFile = /* @__PURE__ */ new Map();
+  for (const entry of entries) {
+    const id = basename2(entry, extname2(entry));
+    const previous = sourceFile.get(id);
+    if (previous !== void 0) {
+      throw new PptwiseError(
+        `${ASSETS_DIRNAME}/${previous} and ${ASSETS_DIRNAME}/${entry} both register image id "${id}" \u2014 rename one of the files`
+      );
+    }
+    sourceFile.set(id, entry);
+    images2[id] = { src: `${ASSETS_DIRNAME}/${entry}` };
+  }
+  return images2;
+}
+async function readDeckDir(dir) {
+  const deckDir = resolve4(dir);
+  const spec2 = await readSpecFile(deckDir);
+  const pages = await readPages(deckDir);
+  const { ir, generatedSeed, materializedLayoutCount } = assembleDeck(spec2, pages);
+  const images2 = await scanAssets(deckDir);
+  const merged = { ...ir, assets: { images: { ...ir.assets.images, ...images2 } } };
+  return { ir: merged, generatedSeed, materializedLayoutCount, deckDir };
+}
+async function writeDeckAssets(images2, outDir, sourceBaseDir) {
+  const entries = Object.entries(images2);
+  const assetsDir = join3(outDir, ASSETS_DIRNAME);
+  if (entries.length === 0) return { count: 0, assetsDir };
+  await mkdir2(assetsDir, { recursive: true });
+  await Promise.all(entries.map(([id, asset]) => writeOneAsset(id, asset.src, assetsDir, sourceBaseDir)));
+  return { count: entries.length, assetsDir };
+}
+var DATA_URI_RE = /^data:([^;,]+);base64,(.*)$/s;
+async function writeOneAsset(id, src, assetsDir, sourceBaseDir) {
+  assertSafeFileSegment(id, "asset id");
+  if (src.startsWith("data:")) {
+    const match = DATA_URI_RE.exec(src);
+    if (!match) {
+      throw new PptwiseError(`asset "${id}": only base64-encoded data URIs can be disassembled (malformed data URI)`);
+    }
+    const mime = match[1];
+    const payload = match[2];
+    const ext = EXT_BY_MIME[mime];
+    if (!ext) {
+      throw new PptwiseError(
+        `asset "${id}": cannot disassemble a data URI with mime "${mime}" \u2014 expected one of ${Object.keys(EXT_BY_MIME).join(", ")}`
+      );
+    }
+    await writeFile2(join3(assetsDir, `${id}${ext}`), Buffer.from(payload, "base64"));
+    return;
+  }
+  if (/^https?:\/\//.test(src)) {
+    throw new PptwiseError(
+      `asset "${id}": URL assets cannot be disassembled into a deck directory \u2014 inline it as a data URI or download it first`
+    );
+  }
+  const abs = isAbsolute2(src) ? src : resolve4(sourceBaseDir, src);
+  try {
+    await copyFile(abs, join3(assetsDir, `${id}${extname2(abs)}`));
+  } catch {
+    throw new PptwiseError(`asset "${id}": cannot read source image ${abs} (from src "${src}") \u2014 cannot disassemble`);
+  }
+}
+
+// src/lib/slide-edge.ts
+var TAG = /<(\/?)(g|rect)\b([^>]*?)(\/?)>/g;
+var ATTR_CACHE = /* @__PURE__ */ new Map();
+function attr(attrs, name) {
+  let re = ATTR_CACHE.get(name);
+  if (!re) {
+    re = new RegExp(`\\b${name}="([^"]*)"`);
+    ATTR_CACHE.set(name, re);
+  }
+  const m = re.exec(attrs);
+  return m ? m[1] : void 0;
+}
+function num(attrs, name, fallback) {
+  const raw = attr(attrs, name);
+  if (raw === void 0) return fallback;
+  const n = Number(raw);
+  return Number.isFinite(n) ? n : fallback;
+}
+function isOpaque(attrs) {
+  for (const name of ["opacity", "fill-opacity"]) {
+    const raw = attr(attrs, name);
+    if (raw !== void 0 && Number(raw) < 1) return false;
+  }
+  return true;
+}
+var HEX = /^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/;
+function slideEdgeFill(svg) {
+  const rows = new Array(CANVAS_H_PX);
+  let moved = 0;
+  const open = [];
+  let painted = false;
+  TAG.lastIndex = 0;
+  for (let m = TAG.exec(svg); m; m = TAG.exec(svg)) {
+    const [, closing, tag, attrs, selfClosing] = m;
+    if (tag === "g") {
+      if (closing) {
+        if (open.pop()) moved--;
+        continue;
+      }
+      const movesChildren = /\btransform="/.test(attrs);
+      if (selfClosing) continue;
+      open.push(movesChildren);
+      if (movesChildren) moved++;
+      continue;
+    }
+    if (closing || moved > 0) continue;
+    const fill = attr(attrs, "fill");
+    if (!fill || !HEX.test(fill) || !isOpaque(attrs)) continue;
+    const x = num(attrs, "x", 0);
+    const width = num(attrs, "width", 0);
+    if (x > 0 || x + width < CANVAS_W_PX) continue;
+    const y = num(attrs, "y", 0);
+    const height = num(attrs, "height", 0);
+    const top = Math.max(0, Math.round(y));
+    const bottom = Math.min(CANVAS_H_PX, Math.round(y + height));
+    for (let r = top; r < bottom; r++) rows[r] = fill;
+    if (bottom > top) painted = true;
+  }
+  if (!painted) return null;
+  let last;
+  for (let r = 0; r < CANVAS_H_PX; r++) {
+    if (rows[r]) last = rows[r];
+    else rows[r] = last;
+  }
+  for (let r = CANVAS_H_PX - 1; r >= 0; r--) {
+    if (rows[r]) last = rows[r];
+    else rows[r] = last;
+  }
+  const stops = [];
+  for (let r = 0; r < CANVAS_H_PX; r++) {
+    const fill = rows[r];
+    const run = stops[stops.length - 1];
+    if (run && run.fill === fill) run.bottom = r + 1;
+    else stops.push({ fill, top: r, bottom: r + 1 });
+  }
+  if (stops.length === 1) return stops[0].fill;
+  const pct = (row) => `${(row / CANVAS_H_PX * 100).toFixed(3).replace(/\.?0+$/, "")}%`;
+  const body = stops.map((s) => `${s.fill} ${pct(s.top)} ${pct(s.bottom)}`).join(",");
+  return `linear-gradient(180deg,${body})`;
+}
+
+// src/lib/svg-ids.ts
+function namespaceSvgIds(svg, prefix) {
+  if (!prefix) return svg;
+  return svg.replace(/\bid="([^"]*)"/g, (_m, id) => `id="${prefix}${id}"`).replace(/url\(#([^)"']*)\)/g, (_m, id) => `url(#${prefix}${id})`).replace(/\b(xlink:href|href)="#([^"]*)"/g, (_m, attr2, id) => `${attr2}="#${prefix}${id}"`);
+}
+function svgIdPrefix(index) {
+  return `s${index}-`;
+}
+
+// src/cli/preview-html.ts
+function escapeHtml(s) {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function embedJson(value) {
+  return JSON.stringify(value).replace(/</g, "\\u003c");
+}
+function findingBadge(count, className) {
+  if (count === 0) return "";
+  return `<div class="${className}" aria-hidden="true">${count}</div>`;
+}
+function slideNode(slide, findingCount) {
+  const idAttr = slide.id !== void 0 ? ` data-id="${escapeHtml(slide.id)}"` : "";
+  const badge = slide.placeholder ? `<div class="pf-badge" aria-hidden="true">unfilled</div>` : "";
+  const fBadge = findingBadge(findingCount, "pf-finding-badge");
+  const svg = namespaceSvgIds(slide.svg, svgIdPrefix(slide.index));
+  const edgeAttr = edgeAttribute(slide, "data-edge");
+  return `<div class="pf-slide" id="pf-slide-${slide.index}" data-index="${slide.index}"${idAttr}${edgeAttr}>${badge}${fBadge}${svg}</div>`;
+}
+function edgeAttribute(slide, name) {
+  const edge = slideEdgeFill(slide.svg);
+  if (!edge) return "";
+  return ` ${name}="${escapeHtml(name === "style" ? `background:${edge}` : edge)}"`;
+}
+function thumbDescription(slide) {
+  const parts = [`slide ${slide.index + 1}`, slide.type];
+  if (slide.id !== void 0) parts.push(slide.id);
+  if (slide.placeholder) parts.push("unfilled");
+  return escapeHtml(parts.join(" \xB7 "));
+}
+function positionLabel(slide) {
+  const idPart = slide.id !== void 0 ? ` \xB7 ${slide.id}` : "";
+  return escapeHtml(`${slide.index + 1}${idPart}`);
+}
+function counterText(slide, total) {
+  const idPart = slide.id !== void 0 ? ` \xB7 ${slide.id}` : "";
+  return escapeHtml(`${slide.index + 1} / ${total}${idPart}`);
+}
+function thumbButton(slide, isActive, slotContent, findingCount) {
+  const description = thumbDescription(slide);
+  const badge = slide.placeholder ? `<span class="pf-thumb-badge" aria-hidden="true">unfilled</span>` : "";
+  const fBadge = findingBadge(findingCount, "pf-thumb-finding-badge");
+  return `<button type="button" class="pf-thumb${isActive ? " pf-thumb-active" : ""}" id="pf-thumb-${slide.index}" data-index="${slide.index}" title="${description}" aria-label="${description}"><span class="pf-thumb-slot" id="pf-slot-${slide.index}"${edgeAttribute(slide, "style")}>${slotContent}</span><span class="pf-thumb-label">${positionLabel(slide)}</span>${badge}${fBadge}</button>`;
+}
+function findingPanelEntry(f) {
+  const idPart = f.slideId !== void 0 ? ` \xB7 ${escapeHtml(f.slideId)}` : "";
+  return `<button type="button" class="pf-finding" data-page-index="${f.page - 1}"><span class="pf-finding-loc">page ${f.page}${idPart}</span><span class="pf-finding-code">[${escapeHtml(f.code)}]</span> <span class="pf-finding-msg">${escapeHtml(f.message)}</span></button>`;
+}
+var CSS = `
+:root{
+  --bg:#f4f4f2;--panel:#fff;--line:#d9d9d4;--ink:#1b1b19;--ink-dim:#6d6d66;
+  --stage:#e8e8e4;--warn:#9a6b16;--bad:#a8342d;--radius:10px;
+  color-scheme:light
+}
+body[data-surround="dark"]{
+  --bg:#17181a;--panel:#1f2124;--line:#34373c;--ink:#e9eaec;--ink-dim:#9195a0;--stage:#101113;
+  color-scheme:dark
+}
+*{box-sizing:border-box}
+html,body{height:100%;margin:0}
+body{display:flex;flex-direction:column;background:var(--bg);color:var(--ink);
+  font:14px/1.55 -apple-system,BlinkMacSystemFont,"Segoe UI","PingFang SC","Hiragino Sans GB",sans-serif;
+  -webkit-font-smoothing:antialiased}
+
+header{display:flex;align-items:center;gap:14px;padding:11px 18px;background:var(--panel);
+  border-bottom:1px solid var(--line);flex:0 0 auto}
+#pf-title{font-weight:650;letter-spacing:-.01em;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}
+#pf-counter{font-variant-numeric:tabular-nums;color:var(--ink-dim);white-space:nowrap;font-size:13px}
+.pf-spacer{flex:1 1 auto}
+#pf-audit-note{color:var(--warn);font-size:12px;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;max-width:46ch}
+#pf-audit-checks{color:var(--ink-dim);font-size:12px;white-space:nowrap}
+
+.pf-seg{display:inline-flex;border:1px solid var(--line);border-radius:8px;overflow:hidden;flex:0 0 auto}
+.pf-seg button{appearance:none;border:0;border-right:1px solid var(--line);background:transparent;color:var(--ink);
+  font:inherit;font-size:13px;padding:4px 10px;cursor:pointer}
+.pf-seg button:last-child{border-right:0}
+.pf-seg button[aria-pressed="true"]{background:var(--ink);color:var(--panel)}
+.pf-seg button:hover:not([aria-pressed="true"]){background:var(--stage)}
+
+/* container-type:size so the stage below can ask this box how tall it is
+   instead of guessing. Legal here because the box's own size never depends on
+   its contents: it is a flex item stretched to the body's width and given the
+   leftover height by flex:1 1 auto. */
+#pf-stage-wrap{container-type:size;flex:1 1 auto;min-height:0;display:flex;align-items:center;
+  justify-content:center;gap:16px;padding:18px}
+/* The stage has to fit both ways: as wide as its height allows, never wider
+   than the room left beside the findings panel. Sizing it off its height and
+   capping the width is the only arrangement that holds in both directions.
+   Measured, not reasoned about: height-driven rules (height:100%) overflow
+   when width is the tighter axis, and width-driven ones
+   (width:100%;max-height:100%) stop being 16:9 when height is.
+   100cqh is the wrap's real content height. It used to be 100vh - 210px, a
+   guess at what the header and filmstrip take. Guess high and the slide comes
+   out smaller than the window allows; guess low and the box comes out wider
+   than 16:9, which aspect-ratio cannot correct once both width and max-height
+   are set -- the slide then letterboxes inside its own stage and paints a grey
+   bar down each side. The first declaration is that old guess, left in as the
+   fallback a browser without container query units will land on. */
+#pf-stage{position:relative;background:var(--stage);box-shadow:0 10px 40px rgba(0,0,0,.18);
+  aspect-ratio:16/9;max-height:100%;
+  width:min(100%,calc((100vh - 210px) * 16 / 9));
+  width:min(100%,calc(100cqh * 16 / 9))}
+#pf-stage,.pf-thumb-slot{position:relative}
+.pf-slide{position:absolute;inset:0}
+.pf-slide svg{display:block;width:100%;height:100%}
+
+#pf-side{flex:0 0 250px;align-self:stretch;overflow-y:auto;background:var(--panel);
+  border:1px solid var(--line);border-radius:var(--radius);padding:12px 13px;font-size:13px}
+#pf-side h2{margin:0 0 8px;font-size:11px;text-transform:uppercase;letter-spacing:.06em;color:var(--ink-dim)}
+.pf-finding{display:block;width:100%;text-align:left;background:transparent;border:1px solid var(--line);
+  border-radius:8px;padding:7px 9px;margin-bottom:7px;cursor:pointer;font:inherit;color:var(--ink)}
+.pf-finding:hover{background:var(--stage)}
+.pf-finding-loc{display:block;font-size:11px;color:var(--ink-dim)}
+.pf-finding-code{display:inline-block;font-size:11px;font-weight:700;color:var(--bad)}
+.pf-finding-msg{display:block;font-size:12px;color:var(--ink-dim);margin-top:2px}
+
+/* The strip is cut off by its own right edge when it scrolls, which reads as
+   a clipping bug rather than as "there is more this way" -- the last thumbnail
+   is simply sliced, and inside an embedder's rounded frame it is sliced on a
+   curve. The two widths are driven from script (see fadeStrip) and are 0 until
+   there is really something hidden on that side, so a strip that fits is
+   untouched: at 0 the gradient is opaque from edge to edge. */
+#pf-filmstrip{display:flex;gap:10px;padding:11px 18px;overflow-x:auto;background:var(--panel);
+  border-top:1px solid var(--line);flex:0 0 auto;--pf-fade-l:0px;--pf-fade-r:0px;
+  -webkit-mask-image:linear-gradient(to right,transparent 0,#000 var(--pf-fade-l),
+    #000 calc(100% - var(--pf-fade-r)),transparent 100%);
+  mask-image:linear-gradient(to right,transparent 0,#000 var(--pf-fade-l),
+    #000 calc(100% - var(--pf-fade-r)),transparent 100%)}
+.pf-thumb{flex:0 0 auto;width:154px;padding:0;margin:0;border:1px solid var(--line);background:var(--panel);
+  cursor:pointer;border-radius:8px;overflow:hidden;position:relative;font:inherit;text-align:left}
+.pf-thumb:hover{border-color:var(--ink-dim)}
+.pf-thumb-active,.pf-thumb-active:hover{border-color:var(--ink);box-shadow:0 0 0 1px var(--ink)}
+.pf-thumb-slot{display:block;width:100%;aspect-ratio:16/9;background:var(--stage)}
+/* The active slide's SVG lives in the stage, not here \u2014 one node per slide,
+   moved between the two homes. Without this the vacated slot reads as a
+   broken empty box, so it states what it is instead. */
+.pf-thumb-active .pf-thumb-slot::after{content:"on stage";position:absolute;inset:0;display:flex;
+  align-items:center;justify-content:center;font-size:10px;letter-spacing:.08em;text-transform:uppercase;
+  color:var(--ink-dim)}
+.pf-thumb-label{display:block;font-size:11px;line-height:1.5;padding:4px 7px;color:var(--ink-dim);
+  white-space:nowrap;overflow:hidden;text-overflow:ellipsis}
+.pf-badge,.pf-thumb-badge{position:absolute;top:5px;right:5px;background:var(--warn);color:#fff;font-size:10px;
+  font-weight:700;letter-spacing:.03em;padding:2px 6px;border-radius:999px;text-transform:uppercase;z-index:2;pointer-events:none}
+.pf-finding-badge,.pf-thumb-finding-badge{position:absolute;top:5px;left:5px;background:var(--bad);color:#fff;
+  font-size:10px;font-weight:700;padding:2px 6px;border-radius:999px;z-index:2;pointer-events:none}
+`.trim();
+var JS = `
+(function () {
+  var stage = document.getElementById('pf-stage')
+  var counter = document.getElementById('pf-counter')
+  var thumbs = Array.prototype.slice.call(document.querySelectorAll('.pf-thumb'))
+  var total = thumbs.length
+  if (total === 0) return
+  var current = parseInt(thumbs[0].getAttribute('data-index'), 10)
+
+  function slideEl(i) { return document.getElementById('pf-slide-' + i) }
+  function slotEl(i) { return document.getElementById('pf-slot-' + i) }
+  function thumbEl(i) { return document.getElementById('pf-thumb-' + i) }
+  function thumbPos(i) {
+    for (var t = 0; t < thumbs.length; t++) {
+      if (parseInt(thumbs[t].getAttribute('data-index'), 10) === i) return t
+    }
+    return -1
+  }
+
+  function updateCounter(i) {
+    var el = slideEl(i)
+    if (!el) return
+    var text = (thumbPos(i) + 1) + ' / ' + total
+    var id = el.getAttribute('data-id')
+    if (id) text += ' \xB7 ' + id
+    counter.textContent = text
+  }
+
+  function activate(i) {
+    if (i === current) return
+    var nextSlide = slideEl(i)
+    var nextThumb = thumbEl(i)
+    if (!nextSlide || !nextThumb) return
+    var prevSlide = slideEl(current)
+    var prevSlot = slotEl(current)
+    if (prevSlide && prevSlot) prevSlot.appendChild(prevSlide)
+    var prevThumb = thumbEl(current)
+    if (prevThumb) prevThumb.classList.remove('pf-thumb-active')
+    stage.appendChild(nextSlide)
+    stage.style.background = nextSlide.getAttribute('data-edge') || ''
+    nextThumb.classList.add('pf-thumb-active')
+    nextThumb.scrollIntoView({ block: 'nearest', inline: 'nearest' })
+    current = i
+    updateCounter(i)
+  }
+
+  thumbs.forEach(function (t) {
+    t.addEventListener('click', function () {
+      activate(parseInt(t.getAttribute('data-index'), 10))
+    })
+  })
+
+  document.addEventListener('keydown', function (e) {
+    var pos = thumbPos(current)
+    if (e.key === 'ArrowRight' && pos < total - 1) {
+      activate(parseInt(thumbs[pos + 1].getAttribute('data-index'), 10))
+    } else if (e.key === 'ArrowLeft' && pos > 0) {
+      activate(parseInt(thumbs[pos - 1].getAttribute('data-index'), 10))
+    }
+  })
+
+  // Click a finding, jump to its page \u2014 the same activate() a thumbnail uses.
+  Array.prototype.slice.call(document.querySelectorAll('.pf-finding')).forEach(function (b) {
+    b.addEventListener('click', function () {
+      activate(parseInt(b.getAttribute('data-page-index'), 10))
+    })
+  })
+
+  // Fade whichever end of the strip has more thumbnails behind it. Driven
+  // from here rather than left to CSS because no CSS rule can ask whether a
+  // box currently overflows. See the #pf-filmstrip rule for why it matters.
+  var strip = document.getElementById('pf-filmstrip')
+  function fadeStrip() {
+    if (!strip || thumbs.length === 0) return
+    // Measured off the thumbnails, not off scrollWidth. The strip's own
+    // 18px of padding counts as scrollable width, so scrollWidth says there
+    // is more to the right while a reader is already looking at the last
+    // thumbnail \u2014 and activate()'s scrollIntoView stops exactly there,
+    // leaving the padding unscrolled. The fade would then claim there is
+    // more to see and dim the selected thumbnail's own ring to do it. Asking
+    // whether a thumbnail is actually cut off is what the fade means anyway.
+    var box = strip.getBoundingClientRect()
+    var hiddenLeft = box.left - thumbs[0].getBoundingClientRect().left
+    var hiddenRight = thumbs[thumbs.length - 1].getBoundingClientRect().right - box.right
+    // A pixel of slack: sub-pixel layout leaves a fraction of overflow on
+    // strips that visibly fit, and fading those is the bug in reverse.
+    strip.style.setProperty('--pf-fade-l', (hiddenLeft > 1 ? 28 : 0) + 'px')
+    strip.style.setProperty('--pf-fade-r', (hiddenRight > 1 ? 28 : 0) + 'px')
+  }
+  if (strip) {
+    fadeStrip()
+    strip.addEventListener('scroll', fadeStrip, { passive: true })
+    // The strip also stops and starts overflowing as the window changes width,
+    // and scrollIntoView moves it without a resize.
+    window.addEventListener('resize', fadeStrip)
+    if (window.ResizeObserver) new ResizeObserver(fadeStrip).observe(strip)
+  }
+
+  // Open on a given page: #page=3 is the third thumbnail, not slide index 3.
+  // A reader who clicks page 3 in a harness that embeds this file expects to
+  // land on page 3, and the embedder has no other way to say so \u2014 it holds a
+  // URL, not a handle on this script. Reading the position rather than the
+  // index keeps that promise honest for a deck whose slides are not numbered
+  // 0..n-1. Silently ignored when it names a page this deck does not have.
+  function fromHash() {
+    var m = /(?:^|[#&])page=(\\d+)/.exec(location.hash || '')
+    if (!m) return
+    var pos = parseInt(m[1], 10) - 1
+    // >= 0, not > 0. Page 1 is a no-op on first load, but not afterwards: a
+    // reader who pages forward and then hits Back gets #page=1 in the URL,
+    // and skipping it leaves the address bar and the deck disagreeing.
+    // activate() already returns early when it is handed the current page.
+    if (pos >= 0 && pos < total) activate(parseInt(thumbs[pos].getAttribute('data-index'), 10))
+  }
+  fromHash()
+  window.addEventListener('hashchange', fromHash)
+
+  // Light/dark surround. A deck is judged on color and weight, and the
+  // surround it sits on changes both \u2014 a dark theme reads muddy on a light
+  // page and vice versa, so the reviewer picks rather than the page deciding.
+  var seg = document.getElementById('pf-surround')
+  if (seg) {
+    seg.addEventListener('click', function (e) {
+      var btn = e.target.closest('button')
+      if (!btn) return
+      document.body.setAttribute('data-surround', btn.getAttribute('data-surround'))
+      Array.prototype.slice.call(seg.children).forEach(function (b) {
+        b.setAttribute('aria-pressed', String(b === btn))
+      })
+    })
+  }
+})()
+`.trim();
+function buildPreviewHtml(input) {
+  const { title, slides, findings = [], auditNote, checks } = input;
+  const total = slides.length;
+  const escapedTitle = escapeHtml(title);
+  const findingsByPage = /* @__PURE__ */ new Map();
+  for (const f of findings) {
+    const list = findingsByPage.get(f.page);
+    if (list) list.push(f);
+    else findingsByPage.set(f.page, [f]);
+  }
+  const countFor = (slide) => findingsByPage.get(slide.index + 1)?.length ?? 0;
+  const stageSlide = total > 0 ? slideNode(slides[0], countFor(slides[0])) : "";
+  const stageEdge = total > 0 ? edgeAttribute(slides[0], "style") : "";
+  const thumbs = slides.map((s, i) => thumbButton(s, i === 0, i === 0 ? "" : slideNode(s, countFor(s)), countFor(s))).join("");
+  const initialCounter = total > 0 ? counterText(slides[0], total) : "0 / 0";
+  const auditPanel = findings.length > 0 ? `<section id="pf-audit-panel"><h2>Audit findings (${findings.length})</h2><div id="pf-audit-list">${findings.map(findingPanelEntry).join("")}</div></section>` : "";
+  const findingsDataScript = findings.length > 0 ? `<script type="application/json" id="pf-audit-findings">${embedJson(findings)}</script>` : "";
+  const auditNoteHtml = auditNote !== void 0 ? `<span id="pf-audit-note">${escapeHtml(auditNote)}</span>` : "";
+  const checksLine = checks !== void 0 ? `<span id="pf-audit-checks">audit: svg ${checks.svg} \xB7 pixels ${checks.pixels}</span>` : "";
+  const sideHtml = auditPanel ? `<aside id="pf-side">${auditPanel}</aside>` : "";
+  return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapedTitle} \u2014 pptwise preview</title>
+<style>${CSS}</style>
+</head>
+<body data-surround="light">
+<header>
+<span id="pf-title">${escapedTitle}</span>
+<span id="pf-counter">${initialCounter}</span>
+<span class="pf-spacer"></span>
+${auditNoteHtml}
+${checksLine}
+<div class="pf-seg" id="pf-surround" role="group" aria-label="surround">
+<button type="button" data-surround="light" aria-pressed="true">Light</button>
+<button type="button" data-surround="dark" aria-pressed="false">Dark</button>
+</div>
+</header>
+<div id="pf-stage-wrap"><div id="pf-stage"${stageEdge}>${stageSlide}</div>${sideHtml}</div>
+<nav id="pf-filmstrip" aria-label="slides">${thumbs}</nav>
+${findingsDataScript}
+<script>${JS}</script>
+</body>
+</html>
+`;
+}
+
+// src/cli/preview-manifest.ts
+var PREVIEW_MANIFEST_VERSION = 1;
+function pageSlug(slide) {
+  const raw = slide.id?.trim();
+  if (raw) {
+    const safe = raw.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "");
+    if (safe) return safe;
+  }
+  return `page-${String(slide.index + 1).padStart(3, "0")}`;
+}
+function pageIds(slides) {
+  const taken = /* @__PURE__ */ new Set();
+  const claim = (candidate) => {
+    if (!taken.has(candidate)) {
+      taken.add(candidate);
+      return candidate;
+    }
+    for (let n = 2; ; n++) {
+      const suffixed = `${candidate}-${n}`;
+      if (!taken.has(suffixed)) {
+        taken.add(suffixed);
+        return suffixed;
+      }
+    }
+  };
+  return slides.map((slide) => {
+    const slug = pageSlug(slide);
+    if (!taken.has(slug)) return claim(slug);
+    return claim(`page-${String(slide.index + 1).padStart(3, "0")}`);
+  });
+}
+function buildPreviewManifest(input) {
+  const byPage = /* @__PURE__ */ new Map();
+  for (const f of input.findings ?? []) {
+    const list = byPage.get(f.page) ?? [];
+    list.push({ code: f.code, message: f.message });
+    byPage.set(f.page, list);
+  }
+  const ids = pageIds(input.slides);
+  const pages = input.slides.map((slide, i) => {
+    const findings = byPage.get(slide.index + 1) ?? [];
+    return {
+      id: ids[i],
+      page: slide.index + 1,
+      type: slide.type,
+      file: slide.file,
+      ...slide.id !== void 0 ? { slideId: slide.id } : {},
+      ...slide.placeholder ? { placeholder: true } : {},
+      ...findings.length > 0 ? { findings } : {}
+    };
+  });
+  return {
+    manifestVersion: PREVIEW_MANIFEST_VERSION,
+    generator: "pptwise preview",
+    pptwiseVersion: input.pptwiseVersion,
+    title: input.title,
+    slide: { width: input.width, height: input.height },
+    ...input.checks !== void 0 ? { checks: input.checks } : {},
+    ...input.auditNote !== void 0 ? { auditNote: input.auditNote } : {},
+    pages
+  };
+}
+
+// src/cli/workspace.ts
+import { existsSync as existsSync2 } from "fs";
+import { appendFile, mkdir as mkdir3, readFile as readFile5, readdir as readdir2, stat as stat2, unlink } from "fs/promises";
+import { basename as basename3, dirname as dirname2, extname as extname3, join as join4, resolve as resolve5 } from "path";
+
+// src/cli/child.ts
+import {
+  execFile,
+  spawn
+} from "child_process";
+
+// src/cli/win-exec.ts
+import * as fs from "fs";
+import * as path from "path";
+
+// src/cli/path-lookup.ts
+import { constants } from "fs";
+import { access as fsAccess } from "fs/promises";
+import { delimiter as defaultDelimiter, join as defaultJoin } from "path";
+var DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+function envValue(env, name) {
+  const upper = name.toUpperCase();
+  for (const [key, value] of Object.entries(env)) {
+    if (key.toUpperCase() === upper) return value;
+  }
+  return void 0;
+}
+async function findOnPath(bin, env, deps = {}) {
+  const platform = deps.platform ?? process.platform;
+  const join10 = deps.join ?? defaultJoin;
+  const delimiter = deps.delimiter ?? defaultDelimiter;
+  const tryAccess = deps.access ?? ((target, mode) => fsAccess(target, mode));
+  const dirs = (envValue(env, "PATH") ?? "").split(delimiter).filter(Boolean);
+  const suffixes = platform === "win32" ? [...(envValue(env, "PATHEXT") ?? DEFAULT_PATHEXT).split(";").map((ext) => ext.trim()).filter(Boolean), ""] : [""];
+  for (const dir of dirs) {
+    for (const suffix of suffixes) {
+      const full = join10(dir, `${bin}${suffix}`);
+      try {
+        await tryAccess(full, constants.X_OK);
+        return full;
+      } catch {
+      }
+    }
+  }
+  return null;
+}
+
+// src/cli/win-exec.ts
+function existenceOf(target) {
+  try {
+    return fs.statSync(target).isDirectory() ? "directory" : "present";
+  } catch (error) {
+    return error.code === "ENOENT" ? "absent" : "unknown";
+  }
+}
+var REAL_DEPS = {
+  platform: process.platform,
+  readFileSync: (p) => fs.readFileSync(p, "utf8"),
+  resolveOnPath: (bin, env) => findOnPath(bin, env),
+  existence: existenceOf
+};
+var UnrecognizedBatchShimError = class extends Error {
+  constructor(command) {
+    super(
+      `Cannot spawn "${command}" as a Windows batch file without a shell. Node refuses to run .cmd/.bat files without a shell (EINVAL after CVE-2024-27980), and wrapping the call in cmd.exe would truncate multi-line arguments at the first newline. Use a recognised npm/pnpm shim, or spawn the real executable.`
+    );
+    this.name = "UnrecognizedBatchShimError";
+  }
+};
+var PATHEXT_EDIT = /^@?SET PATHEXT=%PATHEXT:;\.([A-Z]+);=;%$/;
+var FLAG = /^--?[A-Za-z0-9][-A-Za-z0-9._]*(?:=[-A-Za-z0-9._/\\:]+)?$/;
+function withWindowsEnvAssignment(env, name, value) {
+  const upper = name.toUpperCase();
+  const next = {};
+  let replaced = false;
+  for (const [key, val] of Object.entries(env)) {
+    if (key.toUpperCase() === upper) {
+      next[key] = value;
+      replaced = true;
+    } else {
+      next[key] = val;
+    }
+  }
+  if (!replaced) next[name] = value;
+  return next;
+}
+function withoutWindowsEnvVariable(env, name) {
+  const upper = name.toUpperCase();
+  const next = {};
+  for (const [key, val] of Object.entries(env)) {
+    if (key.toUpperCase() !== upper) next[key] = val;
+  }
+  return next;
+}
+function withPathextEdit(env, removed) {
+  const current = envValue(env, "PATHEXT") ?? "";
+  const edited = current.replace(new RegExp(`;\\.${removed};`, "gi"), ";");
+  if (edited === "") return withoutWindowsEnvVariable(env, "PATHEXT");
+  return withWindowsEnvAssignment(env, "PATHEXT", edited);
+}
+function isFullyQualifiedLocalPath(target) {
+  return /^[A-Za-z]:[\\/]/.test(target);
+}
+function templatePath(text, shimDir) {
+  const rooted = /^%(?:dp0%|~dp0)\\?(.*)$/i.exec(text);
+  if (!rooted) {
+    return isFullyQualifiedLocalPath(text) && !text.includes("%") ? text : null;
+  }
+  const rest = rooted[1] ?? "";
+  if (rest.includes("%") || rest === "") return null;
+  return path.win32.normalize(path.win32.join(shimDir, rest));
+}
+function interpreterTail(middle, shimDir) {
+  const tokens = middle.trim().split(/\s+/).filter((token) => token !== "");
+  if (tokens.length === 0) return null;
+  const quoted = /^"([^"]*)"$/.exec(tokens[tokens.length - 1] ?? "");
+  if (!quoted) return null;
+  const entry = templatePath(quoted[1], shimDir);
+  if (entry === null) return null;
+  const flags = tokens.slice(0, -1);
+  return flags.every((flag) => FLAG.test(flag)) ? [...flags, entry] : null;
+}
+async function nodeRecipe(shimDir, tail, effective, env, deps) {
+  const local = path.win32.join(shimDir, "node.exe");
+  const found = deps.existence(local);
+  if (found === "unknown") return null;
+  if (found === "present" || found === "directory") {
+    return {
+      command: local,
+      args: tail,
+      ...effective.present === env ? {} : { env: effective.present }
+    };
+  }
+  const resolved = await deps.resolveOnPath("node", effective.absent);
+  return resolved === null ? null : {
+    command: resolved,
+    args: tail,
+    ...effective.absent === env ? {} : { env: effective.absent }
+  };
+}
+var NPM_PROLOGUE = [
+  "@ECHO off",
+  "GOTO start",
+  ":find_dp0",
+  "SET dp0=%~dp0",
+  "EXIT /b",
+  ":start",
+  "SETLOCAL",
+  "CALL :find_dp0"
+];
+var NPM_PREFIX = "endLocal & goto #_undefined_# 2>NUL || title %COMSPEC% & ";
+var NPM_EXEC_LEGACY = /^"%_prog%"(.*)\s%\*$/;
+var NPM_EXEC_CURRENT = /^set PATHEXT=%PATHEXT:;\.([A-Z]+);=;% & "%_prog%"(.*)\s%\*$/;
+var NPM_NATIVE_EXEC = /^"([^"]*)"\s+%\*$/;
+var PNPM_NODE_PATH_IF = /^@IF NOT DEFINED NODE_PATH \($/;
+var PNPM_NODE_PATH_SET = /^@SET "NODE_PATH=([^"%]+)"$/;
+var PNPM_NODE_PATH_PREPEND = /^@SET "NODE_PATH=([^"%]+);%NODE_PATH%"$/;
+var PNPM_IF = /^@IF EXIST "([^"]*)" \($/;
+var PNPM_ARM = /^"([^"]*)"(.*)\s%\*$/;
+var PNPM_BARE_ARM = /^node(.*)\s%\*$/;
+var PNPM_ONELINE = /^@"([^"]*)"(.*)\s%\*$/;
+function normalizeLines(content) {
+  const lines = content.split(/\r?\n/).map((line) => line.trim());
+  while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
+  return lines;
+}
+async function matchNpm(lines, shimDir, env, deps) {
+  if (lines.length < NPM_PROLOGUE.length) return null;
+  if (!NPM_PROLOGUE.every((expected, index) => lines[index] === expected)) return null;
+  const body = lines.slice(NPM_PROLOGUE.length).filter((line) => line !== "");
+  if (body.length === 1) {
+    const native = NPM_NATIVE_EXEC.exec(body[0] ?? "");
+    if (!native) return null;
+    const target = templatePath(native[1], shimDir);
+    if (target === null || !/\.exe$/i.test(target)) return null;
+    const normalizedDir = path.win32.normalize(shimDir);
+    const dp0 = normalizedDir.endsWith("\\") ? normalizedDir : `${normalizedDir}\\`;
+    return { command: target, args: [], env: withWindowsEnvAssignment(env, "dp0", dp0) };
+  }
+  if (body[0] !== 'IF EXIST "%dp0%\\node.exe" (') return null;
+  if (body[1] !== 'SET "_prog=%dp0%\\node.exe"') return null;
+  if (body[2] !== ") ELSE (") return null;
+  if (body[3] !== 'SET "_prog=node"') return null;
+  if (body.length === 7) {
+    if (!PATHEXT_EDIT.test(body[4] ?? "")) return null;
+    if (body[5] !== ")") return null;
+    if (!(body[6] ?? "").startsWith(NPM_PREFIX)) return null;
+    const exec = NPM_EXEC_LEGACY.exec((body[6] ?? "").slice(NPM_PREFIX.length));
+    if (!exec) return null;
+    const tail = interpreterTail(exec[1] ?? "", shimDir);
+    return tail === null ? null : nodeRecipe(shimDir, tail, { present: env, absent: env }, env, deps);
+  }
+  if (body.length === 6) {
+    if (body[4] !== ")") return null;
+    if (!(body[5] ?? "").startsWith(NPM_PREFIX)) return null;
+    const exec = NPM_EXEC_CURRENT.exec((body[5] ?? "").slice(NPM_PREFIX.length));
+    if (!exec) return null;
+    const tail = interpreterTail(exec[2] ?? "", shimDir);
+    if (tail === null) return null;
+    const edited = withPathextEdit(env, exec[1] ?? "JS");
+    return nodeRecipe(shimDir, tail, { present: edited, absent: edited }, env, deps);
+  }
+  return null;
+}
+async function matchPnpm(lines, shimDir, env, deps) {
+  if (lines[0] !== "@SETLOCAL") return null;
+  let body = lines.slice(1).filter((line) => line !== "");
+  let baseEnv = env;
+  if (body.length > 0 && PNPM_NODE_PATH_IF.test(body[0] ?? "")) {
+    if (body.length < 5) return null;
+    const set = PNPM_NODE_PATH_SET.exec(body[1] ?? "");
+    const prepend = PNPM_NODE_PATH_PREPEND.exec(body[3] ?? "");
+    if (!set || body[2] !== ") ELSE (" || !prepend || body[4] !== ")") return null;
+    if (set[1] !== prepend[1]) return null;
+    const currentValue = envValue(env, "NODE_PATH");
+    const defined = currentValue !== void 0 && currentValue !== "";
+    baseEnv = withWindowsEnvAssignment(env, "NODE_PATH", defined ? `${set[1]};${currentValue}` : set[1]);
+    body = body.slice(5);
+  }
+  if (body.length === 1) {
+    const one = PNPM_ONELINE.exec(body[0] ?? "");
+    if (!one) return null;
+    const program2 = templatePath(one[1], shimDir);
+    if (program2 === null) return null;
+    const onelineEnv = baseEnv === env ? {} : { env: baseEnv };
+    if ((one[2] ?? "").trim() === "") {
+      return /\.exe$/i.test(program2) ? { command: program2, args: [], ...onelineEnv } : null;
+    }
+    const tail2 = interpreterTail(one[2] ?? "", shimDir);
+    return tail2 === null || /\.(cmd|bat)$/i.test(program2) ? null : { command: program2, args: tail2, ...onelineEnv };
+  }
+  if (body.length !== 6) return null;
+  const opened = PNPM_IF.exec(body[0] ?? "");
+  if (!opened) return null;
+  const local = path.win32.join(shimDir, "node.exe");
+  const candidate = templatePath(opened[1], shimDir);
+  if (candidate === null || candidate.toLowerCase() !== local.toLowerCase()) return null;
+  const present = PNPM_ARM.exec(body[1] ?? "");
+  if (!present) return null;
+  const presentProgram = templatePath(present[1], shimDir);
+  if (presentProgram === null || presentProgram.toLowerCase() !== local.toLowerCase()) return null;
+  if (body[2] !== ") ELSE (") return null;
+  const edit = PATHEXT_EDIT.exec(body[3] ?? "");
+  if (!edit) return null;
+  const absent = PNPM_BARE_ARM.exec(body[4] ?? "");
+  if (!absent) return null;
+  if (body[5] !== ")") return null;
+  const tail = interpreterTail(present[2] ?? "", shimDir);
+  const otherTail = interpreterTail(absent[1] ?? "", shimDir);
+  if (tail === null || otherTail === null || tail.join(" ") !== otherTail.join(" ")) return null;
+  const removed = edit[1] ?? "JS";
+  return nodeRecipe(
+    shimDir,
+    tail,
+    { present: baseEnv, absent: withPathextEdit(baseEnv, removed) },
+    env,
+    deps
+  );
+}
+async function recognizeShim(cmdPath, content, env, deps = REAL_DEPS) {
+  if (!isFullyQualifiedLocalPath(cmdPath)) return null;
+  const shimDir = path.win32.dirname(cmdPath);
+  const lines = normalizeLines(content);
+  if (lines.length === 0) return null;
+  return await matchNpm(lines, shimDir, env, deps) ?? await matchPnpm(lines, shimDir, env, deps);
+}
+async function resolveSpawnPlan(command, args, env = process.env, _cwd, deps = REAL_DEPS) {
+  if (deps.platform !== "win32") return { command, args: [...args] };
+  let resolved = command;
+  if (!command.includes("/") && !command.includes("\\")) {
+    resolved = await deps.resolveOnPath(command, env) ?? command;
+  }
+  if (!/\.(cmd|bat)$/i.test(path.win32.basename(resolved))) {
+    return { command: resolved, args: [...args] };
+  }
+  if (!isFullyQualifiedLocalPath(resolved)) {
+    throw new UnrecognizedBatchShimError(command);
+  }
+  let content;
+  try {
+    content = deps.readFileSync(resolved);
+  } catch {
+    throw new UnrecognizedBatchShimError(command);
+  }
+  const recipe = await recognizeShim(resolved, content, env, deps);
+  if (recipe === null) throw new UnrecognizedBatchShimError(command);
+  return {
+    command: recipe.command,
+    args: [...recipe.args, ...args],
+    ...recipe.env ? { env: recipe.env } : {}
+  };
+}
+
+// src/cli/child.ts
+var DRAIN_GRACE_MS = 500;
+function spawnHidden(command, args = [], options = {}) {
+  return spawn(command, args, { ...options, windowsHide: true });
+}
+var ChildTimeoutError = class extends Error {
+  timedOut = true;
+  constructor(timeoutMs) {
+    super(`child process timed out after ${timeoutMs}ms`);
+    this.name = "ChildTimeoutError";
+  }
+};
+async function runChild(command, args = [], options = {}) {
+  const { timeoutMs, signal, ...spawnOptions } = options;
+  const cwd = typeof spawnOptions.cwd === "string" ? spawnOptions.cwd : void 0;
+  const plan2 = await resolveSpawnPlan(command, args, spawnOptions.env ?? process.env, cwd);
+  return new Promise((resolve8, reject) => {
+    const child = spawnHidden(plan2.command, plan2.args, {
+      ...spawnOptions,
+      env: plan2.env ?? spawnOptions.env,
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+    let drainTimer;
+    let timeoutTimer;
+    let exitCode = null;
+    let exited = false;
+    let timedOut = false;
+    const settle = (code) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      if (drainTimer) clearTimeout(drainTimer);
+      child.stdout?.destroy();
+      child.stderr?.destroy();
+      child.unref();
+      signal?.removeEventListener("abort", onAbort);
+      if (timedOut) {
+        reject(new ChildTimeoutError(timeoutMs ?? 0));
+        return;
+      }
+      resolve8({ code: code ?? 0, stdout, stderr });
+    };
+    const restartDrain = () => {
+      if (!exited || settled) return;
+      if (drainTimer) clearTimeout(drainTimer);
+      drainTimer = setTimeout(() => settle(exitCode), DRAIN_GRACE_MS);
+    };
+    child.stdout?.on("data", (chunk) => {
+      stdout += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      restartDrain();
+    });
+    child.stderr?.on("data", (chunk) => {
+      stderr += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+      restartDrain();
+    });
+    child.on("error", (error) => {
+      if (settled) return;
+      settled = true;
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+      if (drainTimer) clearTimeout(drainTimer);
+      signal?.removeEventListener("abort", onAbort);
+      reject(error);
+    });
+    child.on("exit", (code) => {
+      exitCode = code;
+      exited = true;
+      restartDrain();
+    });
+    child.on("close", (code) => settle(code));
+    if (timeoutMs !== void 0) {
+      timeoutTimer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+        settle(null);
+      }, timeoutMs);
+    }
+    const onAbort = () => child.kill();
+    if (signal) {
+      if (signal.aborted) onAbort();
+      else signal.addEventListener("abort", onAbort, { once: true });
+    }
+  });
+}
+
+// src/cli/workspace.ts
+var WORKSPACE_DIRNAME = ".pptwise";
+var LEGACY_WORKSPACE_DIRNAMES = [".pptpress", ".pptfast"];
+var WORKSPACE_IGNORE_ENTRY = `${WORKSPACE_DIRNAME}/`;
+function defaultWorkspaceDirname(anchor) {
+  if (existsSync2(join4(anchor, WORKSPACE_DIRNAME))) return WORKSPACE_DIRNAME;
+  for (const name of LEGACY_WORKSPACE_DIRNAMES) {
+    if (existsSync2(join4(anchor, name))) return name;
+  }
+  return WORKSPACE_DIRNAME;
+}
+function ignoreEntryFor(dirname5) {
+  return `${dirname5}/`;
+}
+var RENDERED_SVG_PATTERN = /^\d{3}-[a-z-]+\.svg$/;
+function deckSlug(target, isDir) {
+  const base = basename3(target);
+  const name = isDir ? base : base.slice(0, base.length - extname3(base).length);
+  const slug = slugify(name, "deck");
+  assertSafeFileSegment(slug, "deck slug");
+  return slug;
+}
+function resolveWorkspaceRoot(opts) {
+  const anchor = opts.projectConfigPath ? dirname2(resolve5(opts.projectConfigPath)) : resolve5(opts.cwd);
+  const configured = opts.outDir !== void 0;
+  const root = opts.outDir !== void 0 ? resolve5(anchor, opts.outDir) : join4(anchor, defaultWorkspaceDirname(anchor));
+  return { anchor, root, configured };
+}
+function resolveWorkspaceLocation(opts) {
+  const { anchor, root, configured } = resolveWorkspaceRoot(opts);
+  const slug = deckSlug(opts.target, opts.isDir);
+  return { anchor, root, dir: join4(root, slug), slug, configured };
+}
+var runGitDefault = async (args, cwd) => {
+  try {
+    const { code, stdout } = await runChild("git", args, { cwd });
+    return { code, stdout };
+  } catch (error) {
+    const code = error.code;
+    if (typeof code !== "number") return null;
+    throw error;
+  }
+};
+async function gitIgnoreStatus(dir, entry, runGit = runGitDefault) {
+  const check = await runGit(["check-ignore", "-q", "--", entry], dir);
+  if (check === null) return "not-a-repo";
+  if (check.code === 0) return "ignored";
+  if (check.code === 1) return "not-ignored";
+  return "not-a-repo";
+}
+async function inspectWorkspace(opts) {
+  const { anchor, root, configured } = resolveWorkspaceRoot(opts);
+  if (configured) return { anchor, root, configured, ignore: "skipped" };
+  const ignore = await gitIgnoreStatus(anchor, ignoreEntryFor(basename3(root)), opts.runGit);
+  return { anchor, root, configured, ignore };
+}
+async function ensureGitIgnored(dir, entry, runGit = runGitDefault) {
+  const status = await gitIgnoreStatus(dir, entry, runGit);
+  if (status === "ignored") return { kind: "already-ignored" };
+  if (status === "not-a-repo") return { kind: "no-repo" };
+  const common = await runGit(["rev-parse", "--git-common-dir"], dir);
+  if (common === null || common.code !== 0 || common.stdout.trim() === "") return { kind: "no-repo" };
+  const excludePath = join4(resolve5(dir, common.stdout.trim()), "info", "exclude");
+  try {
+    await mkdir3(dirname2(excludePath), { recursive: true });
+    let existing = "";
+    try {
+      existing = await readFile5(excludePath, "utf8");
+    } catch {
+      existing = "";
+    }
+    const lead = existing === "" || existing.endsWith("\n") ? "" : "\n";
+    await appendFile(excludePath, `${lead}${entry}
+`);
+    return { kind: "appended", path: excludePath };
+  } catch (e) {
+    return { kind: "failed", path: excludePath, reason: e.message };
+  }
+}
+async function exists(path2) {
+  try {
+    await stat2(path2);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function prepareWorkspaceDir(location, opts = {}) {
+  const rootExisted = await exists(location.root);
+  try {
+    await mkdir3(location.dir, { recursive: true });
+  } catch (e) {
+    throw new PptwiseError(
+      `cannot create the output directory ${location.dir}: ${e.message}
+  pass -o <path> to write somewhere writable, set "outDir" in pptwise.config.json, or run from a writable workspace`
+    );
+  }
+  if (rootExisted || location.configured || opts.gitIgnore === false) return [];
+  const ignoreEntry = ignoreEntryFor(basename3(location.root));
+  const outcome = await ensureGitIgnored(location.anchor, ignoreEntry, opts.runGit);
+  if (outcome.kind === "appended") {
+    return [
+      `note: added ${ignoreEntry} to ${outcome.path} \u2014 a local ignore, your shared .gitignore is untouched`
+    ];
+  }
+  if (outcome.kind === "failed") {
+    return [
+      `note: could not write ${outcome.path} (${outcome.reason}) \u2014 add ${ignoreEntry} to your ignore rules yourself`
+    ];
+  }
+  return [];
+}
+async function pruneRenderedSvgs(dir) {
+  let entries;
+  try {
+    entries = await readdir2(dir);
+  } catch {
+    return 0;
+  }
+  const stale = entries.filter((name) => RENDERED_SVG_PATTERN.test(name));
+  await Promise.all(stale.map((name) => unlink(join4(dir, name))));
+  return stale.length;
+}
+var WORKSPACE_IMAGE_EXTS = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".gif", ".webp"]);
+async function scanWorkspaceAssets(assetsDir) {
+  let names;
+  try {
+    names = (await readdir2(assetsDir, { withFileTypes: true })).filter((entry) => entry.isFile() && !entry.name.startsWith(".")).map((entry) => entry.name);
+  } catch (e) {
+    if (e.code === "ENOENT") return {};
+    throw new PptwiseError(`cannot read workspace assets directory ${assetsDir}: ${e.message}`);
+  }
+  const images2 = {};
+  const sourceFile = /* @__PURE__ */ new Map();
+  for (const name of names) {
+    const ext = extname3(name).toLowerCase();
+    if (ext === ".json" || !WORKSPACE_IMAGE_EXTS.has(ext)) continue;
+    const id = basename3(name, extname3(name));
+    const previous = sourceFile.get(id);
+    if (previous !== void 0) {
+      throw new PptwiseError(
+        `workspace ${ASSETS_DIRNAME}/${previous} and ${ASSETS_DIRNAME}/${name} both register image id "${id}" \u2014 rename one of the files`
+      );
+    }
+    sourceFile.set(id, name);
+    images2[id] = { src: join4(assetsDir, name) };
+  }
+  return images2;
+}
+
+// src/cli/commands.ts
+async function loadStyleFile(path2) {
+  const raw = await loadIrFile(path2);
+  const r = StyleOverrideSchema.safeParse(raw);
+  if (!r.success) {
+    const detail = r.error.issues.map((i) => `${i.path.join(".") || "(root)"}: ${i.message}`).join("\n");
+    throw new PptwiseError(`invalid style file ${path2}:
+${detail}`);
+  }
+  return r.data;
+}
+async function loadThemeFile(path2) {
+  const raw = await loadIrFile(path2, "theme");
+  return registerBrandThemeFile(parseBrandThemeFile(raw, path2));
+}
+async function registerDeckThemeFile(deckDir) {
+  const themePath = join5(deckDir, THEME_FILENAME);
+  if (await pathExists(themePath)) await loadThemeFile(themePath);
+}
+function describeThemeSource(opts, projectHit, userHit) {
+  if (opts.theme !== void 0) return "--theme";
+  if (projectHit?.config.theme !== void 0) return projectHit.path;
+  if (userHit?.config.theme !== void 0) return userHit.path;
+  return "the deck's own theme";
+}
+function resolveDecksDirSource(projectHit, userHit) {
+  if (projectHit?.config.decksDir !== void 0) {
+    return { decksDir: resolve6(dirname3(projectHit.path), projectHit.config.decksDir) };
+  }
+  return userHit?.config;
+}
+async function applyDeckConfig(raw, opts) {
+  if (typeof raw !== "object" || raw === null) return;
+  const deck = raw;
+  const irTheme = typeof deck.theme === "object" && deck.theme !== null ? deck.theme : {};
+  const themeFileId = opts.themeFilePath !== void 0 ? await loadThemeFile(opts.themeFilePath) : void 0;
+  const [projectHit, userHit] = await Promise.all([
+    opts.projectHit !== void 0 ? Promise.resolve(opts.projectHit) : findConfig(opts.cwd),
+    opts.userHit !== void 0 ? Promise.resolve(opts.userHit) : findUserConfig()
+  ]);
+  const theme = opts.theme ?? themeFileId ?? projectHit?.config.theme ?? userHit?.config.theme ?? irTheme.id;
+  const style = opts.stylePath ? await loadStyleFile(opts.stylePath) : projectHit?.config.style ?? userHit?.config.style ?? irTheme.style;
+  if (theme !== void 0) {
+    const installedThemeIds = getInstalledThemeIds();
+    if (!installedThemeIds.includes(theme)) {
+      throw new PptwiseError(
+        `unknown theme "${theme}" (from ${describeThemeSource(opts, projectHit, userHit)}) \u2014 available: ${installedThemeIds.join(", ")} (see \`pptwise themes\`)`
+      );
+    }
+  }
+  if (theme === void 0 && style === void 0) return;
+  deck.theme = { ...irTheme, id: theme, ...style !== void 0 ? { style } : {} };
+}
+function mergeWorkspaceImages(raw, extras) {
+  if (typeof raw !== "object" || raw === null) return raw;
+  const deck = raw;
+  const existing = deck.assets?.images ?? {};
+  return { ...deck, assets: { images: { ...extras, ...existing } } };
+}
+async function loadWorkspaceStock(cwd, projectHit, resolvedTarget, isDir) {
+  const location = resolveWorkspaceLocation({
+    cwd,
+    projectConfigPath: projectHit?.path,
+    outDir: projectHit?.config.outDir,
+    target: resolvedTarget,
+    isDir
+  });
+  const workspaceAssetsDir = join5(location.dir, ASSETS_DIRNAME);
+  const images2 = await scanWorkspaceAssets(workspaceAssetsDir);
+  return { workspaceAssetsDir, images: images2 };
+}
+async function loadDeckTarget(arg, cwd, projectHit, userHit) {
+  const target = await resolveDeckTarget(arg, resolveDecksDirSource(projectHit, userHit), cwd);
+  if (await isDeckDirectory(target)) {
+    await registerDeckThemeFile(target);
+    const { ir, deckDir } = await readDeckDir(target);
+    const stock2 = await loadWorkspaceStock(cwd, projectHit, deckDir, true);
+    return {
+      raw: mergeWorkspaceImages(ir, stock2.images),
+      baseDir: deckDir,
+      isDir: true,
+      resolvedTarget: deckDir,
+      workspaceAssetsDir: stock2.workspaceAssetsDir
+    };
+  }
+  const raw = await loadIrFile(target);
+  const resolvedFile = resolve6(target);
+  const stock = await loadWorkspaceStock(cwd, projectHit, resolvedFile, false);
+  return {
+    raw: mergeWorkspaceImages(raw, stock.images),
+    baseDir: dirname3(resolvedFile),
+    isDir: false,
+    resolvedTarget: resolvedFile,
+    workspaceAssetsDir: stock.workspaceAssetsDir
+  };
+}
+async function loadValidatedDeckIr(target, cwd) {
+  const [projectHit, userHit] = await Promise.all([findConfig(cwd), findUserConfig()]);
+  const { raw, baseDir, workspaceAssetsDir } = await loadDeckTarget(target, cwd, projectHit, userHit);
+  await applyDeckConfig(raw, { cwd, projectHit, userHit });
+  const v = validateIr(raw);
+  if (!v.ok) {
+    throw new PptwiseError(
+      `invalid IR (${v.errors.length} issue${v.errors.length === 1 ? "" : "s"}):
+${formatIssues(v.errors)}`
+    );
+  }
+  await resolveLocalAssets(v.ir, baseDir, workspaceAssetsDir);
+  return v.ir;
+}
+async function runRender(irPath, opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const [projectHit, userHit] = await Promise.all([findConfig(cwd), findUserConfig()]);
+  const { raw, baseDir, isDir, resolvedTarget, workspaceAssetsDir } = await loadDeckTarget(irPath, cwd, projectHit, userHit);
+  await applyDeckConfig(raw, {
+    theme: opts.theme,
+    themeFilePath: opts.themeFilePath,
+    stylePath: opts.stylePath,
+    cwd,
+    projectHit,
+    userHit
+  });
+  const v = validateIr(raw);
+  if (!v.ok) throw new PptwiseError(`invalid IR:
+${formatIssues(v.errors)}`);
+  await resolveLocalAssets(v.ir, baseDir, workspaceAssetsDir);
+  const bytes = await generatePptx(v.ir, {
+    draft: opts.draft,
+    allowDroppedContent: opts.allowDroppedContent
+  });
+  const extraNotes = [];
+  let output;
+  if (opts.output !== void 0) {
+    output = resolve6(cwd, opts.output);
+    await mkdir4(dirname3(output), { recursive: true });
+  } else {
+    const location = resolveWorkspaceLocation({
+      cwd,
+      projectConfigPath: projectHit?.path,
+      outDir: projectHit?.config.outDir,
+      target: resolvedTarget,
+      isDir
+    });
+    extraNotes.push(...await prepareWorkspaceDir(location, { gitIgnore: opts.gitIgnore, runGit: opts.runGit }));
+    output = join5(location.dir, `${location.slug}.pptx`);
+  }
+  await writeFile3(output, bytes);
+  const ok = `wrote ${output} (${v.ir.slides.length} slides, ${bytes.length} bytes)`;
+  const notes = [...extraNotes, warningsNote(v.warnings), normalizedNote(v.normalized)].filter(
+    (n) => n !== void 0
+  );
+  return notes.length > 0 ? `${ok}
+${notes.join("\n")}` : ok;
+}
+function normalizedNote(normalized) {
+  if (!normalized || normalized.length === 0) return void 0;
+  const n = normalized.length;
+  return `note: ${n} field alias${n === 1 ? "" : "es"} normalized
+${normalized.map((line) => `  ${line}`).join("\n")}`;
+}
+function warningsNote(warnings) {
+  if (!warnings || warnings.length === 0) return void 0;
+  return formatWarnings(warnings);
+}
+function placeholderNote(ir) {
+  const placeholders = ir.slides.map((slide, i) => ({ slide, page: i + 1 })).filter(({ slide }) => slide.placeholder);
+  if (placeholders.length === 0) return void 0;
+  const refs = placeholders.map(({ slide, page }) => slide.id ? `${slide.id} (page ${page})` : `page ${page}`).join(", ");
+  return `note: ${placeholders.length} unfilled placeholder page${placeholders.length === 1 ? "" : "s"}: ${refs}`;
+}
+async function runValidate(irPath, cwd = process.cwd(), opts = {}) {
+  const [projectHit, userHit] = await Promise.all([findConfig(cwd), findUserConfig()]);
+  const { raw, baseDir, isDir, workspaceAssetsDir } = await loadDeckTarget(irPath, cwd, projectHit, userHit);
+  await applyDeckConfig(raw, { themeFilePath: opts.themeFilePath, cwd, projectHit, userHit });
+  const v = validateIr(raw);
+  if (!v.ok)
+    throw new PptwiseError(
+      `invalid IR (${v.errors.length} issue${v.errors.length === 1 ? "" : "s"}):
+${formatIssues(v.errors)}`
+    );
+  await resolveLocalAssets(v.ir, baseDir, workspaceAssetsDir);
+  const ok = `OK \u2014 ${v.ir.slides.length} slides, theme "${v.ir.theme.id}"`;
+  const notes = [];
+  const warnNote = warningsNote(v.warnings);
+  if (warnNote) notes.push(warnNote);
+  const aliasNote = normalizedNote(v.normalized);
+  if (aliasNote) notes.push(aliasNote);
+  if (isDir) {
+    const note = placeholderNote(v.ir);
+    if (note) notes.push(note);
+  }
+  return notes.length > 0 ? `${ok}
+${notes.join("\n")}` : ok;
+}
+function formatAuditFinding(f) {
+  const idSuffix = f.slideId !== void 0 ? ` (${f.slideId})` : "";
+  return `page ${f.page}${idSuffix}: [${f.code}] ${f.message}`;
+}
+function formatAuditReport(report, ir) {
+  const lines = report.findings.map(formatAuditFinding);
+  lines.push(
+    `audited ${report.pagesAudited} page${report.pagesAudited === 1 ? "" : "s"}, ${report.pagesSkipped} skipped, ${report.findings.length} finding${report.findings.length === 1 ? "" : "s"}`
+  );
+  if (report.checks.pixels === "completed") {
+    lines.push("pixel-contrast check: completed");
+  }
+  const note = placeholderNote(ir);
+  if (note) lines.push(note);
+  return lines.join("\n");
+}
+async function runAudit(target, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const [projectHit, userHit] = await Promise.all([findConfig(cwd), findUserConfig()]);
+  const { raw, baseDir, workspaceAssetsDir } = await loadDeckTarget(target, cwd, projectHit, userHit);
+  await applyDeckConfig(raw, { themeFilePath: opts.themeFilePath, cwd, projectHit, userHit });
+  const v = validateIr(raw);
+  if (!v.ok) {
+    throw new PptwiseError(
+      `invalid IR (${v.errors.length} issue${v.errors.length === 1 ? "" : "s"}):
+${formatIssues(v.errors)}`
+    );
+  }
+  await resolveLocalAssets(v.ir, baseDir, workspaceAssetsDir);
+  const report = opts.pixels ? await auditDeck(v.ir, { pixels: true }) : auditDeck(v.ir);
+  const hasFindings = report.findings.length > 0;
+  const output = opts.json ? JSON.stringify(report, null, 2) : formatAuditReport(report, v.ir);
+  return { output, hasFindings };
+}
+function formatAssetBriefItem(item) {
+  const idSuffix = item.page.id !== void 0 ? `, ${item.page.id}` : "";
+  const sharedSuffix = item.shared ? ` (shared by ${item.occurrenceCount} image slots, frame not attributable to one)` : "";
+  const header = `page ${item.page.index + 1} (${item.page.type}${idSuffix}) \u2014 ${item.asset_id}${item.missing ? " (missing)" : ""}${item.rendered ? "" : " (not rendered under the selected layout)"}${sharedSuffix}`;
+  const lines = [header];
+  if (item.frame && item.suggested_pixels) {
+    lines.push(
+      `  frame: ${item.frame.w}x${item.frame.h} @ (${item.frame.x},${item.frame.y}), aspect ${item.frame.aspect}, ${item.fit.mode}`
+    );
+    lines.push(`  suggested pixels: ${item.suggested_pixels.w}x${item.suggested_pixels.h}`);
+  }
+  lines.push(`  fit: ${item.fit.note}`);
+  lines.push(`  palette: primary ${item.palette.primary}, accent ${item.palette.accent} (${item.palette.hexes.join(", ")})`);
+  lines.push(`  mood: ${item.mood.description}`);
+  lines.push(`  prompt: ${item.suggested_prompt}`);
+  return lines.join("\n");
+}
+function formatAssetBriefReport(brief) {
+  if (brief.items.length === 0) return `no image components found for theme "${brief.theme}"`;
+  const missingCount = brief.items.filter((i) => i.missing).length;
+  const notRenderedCount = brief.items.filter((i) => !i.rendered).length;
+  const lines = brief.items.map(formatAssetBriefItem);
+  lines.push(
+    `${brief.items.length} image slot${brief.items.length === 1 ? "" : "s"}, ${missingCount} to generate, ${notRenderedCount} not rendered under their selected layout`
+  );
+  return lines.join("\n\n");
+}
+async function runAssetBrief(target, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const [projectHit, userHit] = await Promise.all([findConfig(cwd), findUserConfig()]);
+  const { raw, baseDir, workspaceAssetsDir } = await loadDeckTarget(target, cwd, projectHit, userHit);
+  await applyDeckConfig(raw, { cwd, projectHit, userHit });
+  const v = validateIr(raw);
+  if (!v.ok) {
+    throw new PptwiseError(
+      `invalid IR (${v.errors.length} issue${v.errors.length === 1 ? "" : "s"}):
+${formatIssues(v.errors)}`
+    );
+  }
+  await resolveLocalAssets(v.ir, baseDir, workspaceAssetsDir);
+  const brief = buildAssetBrief(v.ir);
+  return opts.json ? JSON.stringify(brief, null, 2) : formatAssetBriefReport(brief);
+}
+async function runSpecValidate(specPath) {
+  const raw = await loadIrFile(specPath, "spec");
+  await registerDeckThemeFile(dirname3(resolve6(specPath)));
+  const v = validateSpec(raw);
+  if (!v.ok) {
+    throw new PptwiseError(formatInvalidSpecError(v.errors));
+  }
+  const spec2 = v.spec;
+  const axes = resolveNarrative(spec2.narrative);
+  const ok = `OK \u2014 ${spec2.pages.length} pages, narrative ${axes.strategy}/${axes.pacing}/${axes.audience}, theme "${resolveSpecThemeId(spec2)}"`;
+  const aliasNote = normalizedNote(v.normalized);
+  return aliasNote ? `${ok}
+${aliasNote}` : ok;
+}
+function runSchema(mode) {
+  const schema = mode === "style" ? styleJsonSchema() : mode === "spec" ? specJsonSchema() : irJsonSchema();
+  return JSON.stringify(schema, null, 2);
+}
+function runThemes(asJson) {
+  const themes = listThemes();
+  if (asJson) return JSON.stringify(themes, null, 2);
+  return themes.map((t) => `${t.id.padEnd(12)} ${t.label}`).join("\n");
+}
+function defaultThemeIdFor(output) {
+  return slugify(basename4(output).replace(/\.theme\.json$|\.json$/i, ""));
+}
+async function runBrandExtract(file, opts) {
+  let bytes;
+  try {
+    bytes = await readFile6(file);
+  } catch {
+    throw new PptwiseError(`cannot read template file: ${file}`);
+  }
+  const id = opts.id ?? defaultThemeIdFor(opts.output);
+  if (CANONICAL_THEME_IDS.includes(id)) {
+    throw new PptwiseError(
+      `theme id "${id}" collides with a built-in pptwise theme \u2014 pick a different id with --id (or a different output filename)`
+    );
+  }
+  const theme = await extractBrandTheme(bytes, { id, label: opts.label });
+  const outPath = resolve6(opts.output);
+  await mkdir4(dirname3(outPath), { recursive: true });
+  await writeFile3(outPath, JSON.stringify(theme, null, 2) + "\n");
+  const c = theme.style.colors;
+  const lines = [
+    `wrote ${opts.output} (theme "${theme.id}", label "${theme.label}")`,
+    `  colors: bg ${c.bg}, text ${c.text}, primary ${c.primary}, accent ${c.accent}, muted ${c.muted} (derived), ${c.chartPalette.length} chart colors`,
+    `  fonts: heading "${theme.style.fonts.heading[0]}", body "${theme.style.fonts.body[0]}"`,
+    `use it: pptwise render <deck> --theme-file ${opts.output} \u2014 or drop it into a deck project directory as ${THEME_FILENAME} and reference "${theme.id}" as the deck's theme`
+  ];
+  try {
+    assertContrastFloor(theme.id, theme.style);
+  } catch (e) {
+    lines.push(
+      `warning: this theme will be refused at load time \u2014 ${e instanceof Error ? e.message : String(e)}. Edit the written file's colors (darker text, or a lighter bg) before using it`
+    );
+  }
+  return lines.join("\n");
+}
+function runNarratives(asJson) {
+  if (asJson) {
+    return JSON.stringify(
+      {
+        presets: NARRATIVE_PRESETS,
+        strategies: STRATEGY_DEFINITIONS,
+        pacings: PACING_BUDGETS,
+        audiences: AUDIENCE_VALUES
+      },
+      null,
+      2
+    );
+  }
+  const rows = Object.values(NARRATIVE_PRESETS).map((p) => ({
+    id: p.id,
+    axes: `${p.axes.strategy}/${p.axes.pacing}/${p.axes.audience}`,
+    themes: p.themeRecommendations.join(", ")
+  }));
+  const idWidth = Math.max(...rows.map((r) => r.id.length));
+  const axesWidth = Math.max(...rows.map((r) => r.axes.length));
+  return rows.map((r) => `${r.id.padEnd(idWidth + 2)}${r.axes.padEnd(axesWidth + 2)}${r.themes}`).join("\n");
+}
+var CONFIG_TEMPLATE = {
+  theme: "consulting",
+  style: {
+    colors: { primary: "#0B5FFF", accent: "#FF6A00" }
+  }
+};
+async function runInit(cwd = process.cwd()) {
+  const target = join5(cwd, CONFIG_FILENAME);
+  try {
+    await writeFile3(target, JSON.stringify(CONFIG_TEMPLATE, null, 2) + "\n", { flag: "wx" });
+  } catch (e) {
+    if (e.code === "EEXIST") {
+      throw new PptwiseError(`${target} already exists \u2014 edit it instead`);
+    }
+    throw e;
+  }
+  return `wrote ${target} \u2014 themes: \`pptwise themes\`, style schema: \`pptwise schema --style\``;
+}
+async function renderDeckSlides(target, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const [projectHit, userHit] = await Promise.all([findConfig(cwd), findUserConfig()]);
+  const { raw, baseDir, isDir, resolvedTarget, workspaceAssetsDir } = await loadDeckTarget(target, cwd, projectHit, userHit);
+  await applyDeckConfig(raw, { themeFilePath: opts.themeFilePath, cwd, projectHit, userHit });
+  const v = validateIr(raw);
+  if (!v.ok) throw new PptwiseError(`invalid IR:
+${formatIssues(v.errors)}`);
+  await resolveLocalAssets(v.ir, baseDir, workspaceAssetsDir);
+  const ir = v.ir;
+  const svgs = ir.slides.map((_, i) => renderSlideSvg(ir, i));
+  return { ir, svgs, resolvedTarget, isDir, normalized: v.normalized };
+}
+function buildDeckAuditAndHtml(ir, svgs) {
+  const hasPlaceholder = ir.slides.some((slide) => slide.placeholder);
+  const auditReport = hasPlaceholder ? void 0 : auditDeck(ir);
+  const findings = auditReport?.findings ?? [];
+  const html = buildPreviewHtml({
+    title: ir.filename,
+    slides: ir.slides.map((slide, i) => ({
+      index: i,
+      id: slide.id,
+      type: slide.type,
+      svg: svgs[i],
+      placeholder: slide.placeholder
+    })),
+    findings: findings.map((f) => ({ page: f.page, slideId: f.slideId, code: f.code, message: f.message })),
+    auditNote: hasPlaceholder ? "audit overlay skipped \u2014 deck has unfilled placeholder pages; fill every page and re-run `pptwise preview --html` to see audit findings" : void 0,
+    checks: auditReport?.checks
+  });
+  return { html, findings, checks: auditReport?.checks };
+}
+async function buildDeckPreview(target, opts = {}) {
+  const rendered = await renderDeckSlides(target, opts);
+  const { html, findings, checks } = buildDeckAuditAndHtml(rendered.ir, rendered.svgs);
+  return { ...rendered, html, findings, checks };
+}
+async function runPreview(irPath, outDir, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const { ir, svgs, normalized, isDir, resolvedTarget } = await renderDeckSlides(irPath, {
+    cwd,
+    themeFilePath: opts.themeFilePath
+  });
+  const extraNotes = [];
+  let resolvedOut;
+  if (outDir !== void 0) {
+    resolvedOut = resolve6(cwd, outDir);
+    await mkdir4(resolvedOut, { recursive: true });
+  } else {
+    const projectHit = await findConfig(cwd);
+    const location = resolveWorkspaceLocation({
+      cwd,
+      projectConfigPath: projectHit?.path,
+      outDir: projectHit?.config.outDir,
+      target: resolvedTarget,
+      isDir
+    });
+    extraNotes.push(...await prepareWorkspaceDir(location, { gitIgnore: opts.gitIgnore, runGit: opts.runGit }));
+    await pruneRenderedSvgs(location.dir);
+    resolvedOut = location.dir;
+  }
+  const svgNames = [];
+  for (let i = 0; i < ir.slides.length; i++) {
+    const name = `${String(i + 1).padStart(3, "0")}-${ir.slides[i].type}.svg`;
+    svgNames.push(name);
+    await writeFile3(join5(resolvedOut, name), svgs[i]);
+  }
+  const ok = `wrote ${ir.slides.length} SVG files to ${resolvedOut}`;
+  const notes = [...extraNotes];
+  const aliasNote = normalizedNote(normalized);
+  if (aliasNote) notes.push(aliasNote);
+  if (opts.htmlOut) {
+    const { html, findings, checks } = buildDeckAuditAndHtml(ir, svgs);
+    const htmlPath = join5(resolvedOut, "preview.html");
+    await writeFile3(htmlPath, html);
+    const hasPlaceholder = ir.slides.some((s) => s.placeholder);
+    const manifest = buildPreviewManifest({
+      title: ir.filename,
+      pptwiseVersion: VERSION,
+      width: CANVAS_W_PX,
+      height: CANVAS_H_PX,
+      slides: ir.slides.map((slide, i) => ({
+        index: i,
+        type: slide.type ?? "content",
+        id: slide.id,
+        placeholder: slide.placeholder,
+        file: svgNames[i]
+      })),
+      findings: findings.map((f) => ({ page: f.page, code: f.code, message: f.message })),
+      checks,
+      auditNote: hasPlaceholder ? "audit skipped \u2014 deck has unfilled placeholder pages" : void 0
+    });
+    const manifestPath = join5(resolvedOut, "manifest.json");
+    await writeFile3(manifestPath, `${JSON.stringify(manifest, null, 2)}
+`);
+    notes.push(`note: wrote self-contained preview to ${htmlPath}`);
+    notes.push(`note: wrote machine-readable page manifest to ${manifestPath}`);
+    if (findings.length > 0) {
+      notes.push(`note: audit found ${findings.length} finding${findings.length === 1 ? "" : "s"} \u2014 see preview.html`);
+    }
+  }
+  return notes.length > 0 ? `${ok}
+${notes.join("\n")}` : ok;
+}
+function withRewrittenAssetPaths(ir, deckDir, outDir) {
+  const images2 = Object.fromEntries(
+    Object.entries(ir.assets.images).map(([id, asset]) => {
+      if (asset.src.startsWith("data:") || /^https?:\/\//.test(asset.src)) return [id, asset];
+      return [id, { ...asset, src: relative2(outDir, join5(deckDir, asset.src)) }];
+    })
+  );
+  return { ...ir, assets: { images: images2 } };
+}
+async function runAssemble(target, opts = {}) {
+  const cwd = opts.cwd ?? process.cwd();
+  const [projectHit, userHit] = await Promise.all([findConfig(cwd), findUserConfig()]);
+  const dir = await resolveDeckTarget(target, resolveDecksDirSource(projectHit, userHit), cwd);
+  if (await pathExists(dir) && !await isDeckDirectory(dir)) {
+    throw new PptwiseError(`expected a deck project directory: ${dir}`);
+  }
+  if (await isDeckDirectory(dir)) await registerDeckThemeFile(dir);
+  const { ir, generatedSeed, materializedLayoutCount, deckDir } = await readDeckDir(dir);
+  const outPath = opts.output ? resolve6(cwd, opts.output) : join5(deckDir, "deck.json");
+  const outDir = dirname3(outPath);
+  const outIr = outDir === deckDir ? ir : withRewrittenAssetPaths(ir, deckDir, outDir);
+  await mkdir4(outDir, { recursive: true });
+  await writeFile3(outPath, JSON.stringify(outIr, null, 2) + "\n");
+  const placeholderCount = outIr.slides.filter((s) => s.placeholder).length;
+  const summary = `wrote ${outPath} (${outIr.slides.length} slides, ${placeholderCount} placeholder${placeholderCount === 1 ? "" : "s"})`;
+  const notes = [];
+  if (generatedSeed !== void 0) {
+    notes.push(`note: generated seed ${generatedSeed} \u2014 add "seed": ${generatedSeed} to deck.spec.json for revision stability`);
+  }
+  if (materializedLayoutCount !== void 0) {
+    notes.push(
+      `note: ${materializedLayoutCount} layout${materializedLayoutCount === 1 ? "" : "s"} auto-selected into deck.json \u2014 pin "layout" in a page file to lock one`
+    );
+  }
+  return [summary, ...notes].join("\n");
+}
+async function runDisassemble(irPath, outDir) {
+  const raw = await loadIrFile(irPath);
+  const v = validateIr(raw);
+  if (!v.ok) throw new PptwiseError(`invalid IR:
+${formatIssues(v.errors)}`);
+  const { spec: spec2, pages } = disassembleDeck(v.ir);
+  const ids = Object.keys(pages);
+  for (const id of ids) assertSafeFileSegment(id, "slide id");
+  const specPath = join5(outDir, "deck.spec.json");
+  await mkdir4(outDir, { recursive: true });
+  try {
+    await writeFile3(specPath, JSON.stringify(spec2, null, 2) + "\n", { flag: "wx" });
+  } catch (e) {
+    if (e.code === "EEXIST") {
+      throw new PptwiseError(`${specPath} already exists \u2014 refusing to overwrite an existing deck project`);
+    }
+    throw e;
+  }
+  const pagesDir = join5(outDir, "pages");
+  try {
+    if (ids.length > 0) {
+      await mkdir4(pagesDir, { recursive: true });
+      await Promise.all(
+        ids.map((id) => {
+          const content = pages[id];
+          return writeFile3(join5(pagesDir, `${id}.json`), JSON.stringify(content, null, 2) + "\n");
+        })
+      );
+    }
+    const { count: assetCount, assetsDir } = await writeDeckAssets(
+      v.ir.assets.images,
+      outDir,
+      dirname3(resolve6(irPath))
+    );
+    const pagesNote = ids.length > 0 ? `${ids.length} page file${ids.length === 1 ? "" : "s"} to ${pagesDir}` : "no pages (every slide was a placeholder)";
+    const assetsNote = assetCount > 0 ? `, and ${assetCount} asset file${assetCount === 1 ? "" : "s"} to ${assetsDir}` : "";
+    return `wrote ${specPath}, ${pagesNote}${assetsNote}`;
+  } catch (e) {
+    await rm(specPath, { force: true }).catch(() => {
+    });
+    throw e;
+  }
+}
+async function runMigrate(input, output, cwd = process.cwd()) {
+  const resolvedInput = resolve6(cwd, input);
+  if (await isDeckDirectory(resolvedInput)) {
+    return runMigrateDeckDir(resolvedInput, output, cwd);
+  }
+  return runMigrateIrFile(resolvedInput, output, cwd);
+}
+function isPlainRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function needsChromeRewrite(raw) {
+  return Object.hasOwn(raw, "chrome");
+}
+function needsBloomRewrite(raw) {
+  const theme = raw.theme;
+  if (theme === "bloom") return true;
+  return isPlainRecord(theme) && theme.id === "bloom";
+}
+function componentListHasLogoWall(components) {
+  return Array.isArray(components) && components.some((component) => isPlainRecord(component) && component.type === "logo_wall");
+}
+function needsLogoWallRewrite(raw) {
+  if (componentListHasLogoWall(raw.components)) return true;
+  if (!Array.isArray(raw.slides)) return false;
+  return raw.slides.some((slide) => isPlainRecord(slide) && componentListHasLogoWall(slide.components));
+}
+function recordHasBannerHeadingPin(obj) {
+  return obj.layout === "banner-heading" || obj.focus === "banner-heading";
+}
+function needsBannerHeadingRewrite(raw) {
+  if (recordHasBannerHeadingPin(raw)) return true;
+  if (Array.isArray(raw.slides) && raw.slides.some((slide) => isPlainRecord(slide) && recordHasBannerHeadingPin(slide))) {
+    return true;
+  }
+  if (Array.isArray(raw.pages) && raw.pages.some((page) => isPlainRecord(page) && recordHasBannerHeadingPin(page))) {
+    return true;
+  }
+  return false;
+}
+function migrateRewriteNote(chrome, bloom, logoWall = false, bannerHeading = false) {
+  const parts = [];
+  if (chrome) parts.push("renamed chrome \u2192 branding");
+  if (bloom) parts.push("relocated bloom \u2192 classroom");
+  if (logoWall) parts.push("rewrote logo_wall \u2192 image_grid");
+  if (bannerHeading) parts.push("rewrote banner-heading \u2192 two-column");
+  return parts.join(", ");
+}
+function applyV4LeftoverRewrites(raw) {
+  return migrateBannerHeadingToTwoColumn(
+    migrateLogoWallToImageGrid(migrateBloomToClassroom(migrateChromeToBranding(raw)))
+  );
+}
+async function listPageJsonNames(dir) {
+  const pagesDir = join5(dir, PAGES_DIRNAME);
+  try {
+    const entries = await readdir3(pagesDir);
+    return entries.filter((name) => name.endsWith(".json")).sort();
+  } catch (e) {
+    if (e.code === "ENOENT") return [];
+    throw e;
+  }
+}
+async function rewriteLeftoverPages(dir, outDir) {
+  const names = await listPageJsonNames(dir);
+  const written = [];
+  let logoWall = false;
+  let bannerHeading = false;
+  for (const name of names) {
+    const src = join5(dir, PAGES_DIRNAME, name);
+    const raw = await loadIrFile(src, "page");
+    if (!isPlainRecord(raw)) continue;
+    const hasLogo = needsLogoWallRewrite(raw);
+    const hasBanner = needsBannerHeadingRewrite(raw);
+    if (!hasLogo && !hasBanner) continue;
+    if (hasLogo) logoWall = true;
+    if (hasBanner) bannerHeading = true;
+    const dest = join5(outDir, PAGES_DIRNAME, name);
+    await writeMigratedJson(dest, migrateBannerHeadingToTwoColumn(migrateLogoWallToImageGrid(raw)));
+    written.push(dest);
+  }
+  return { paths: written, logoWall, bannerHeading };
+}
+async function writeMigratedJson(outPath, data) {
+  await mkdir4(dirname3(outPath), { recursive: true });
+  try {
+    await writeFile3(outPath, JSON.stringify(data, null, 2) + "\n", { flag: "wx" });
+  } catch (e) {
+    if (e.code === "EEXIST") {
+      throw new PptwiseError(`${outPath} already exists \u2014 refusing to overwrite, delete it first or choose a different -o`);
+    }
+    throw e;
+  }
+}
+async function runMigrateDeckDir(dir, output, cwd) {
+  const planPath = join5(dir, PLAN_FILENAME);
+  const sourceSpecPath = join5(dir, SPEC_FILENAME);
+  const outDir = resolve6(cwd, output);
+  const specPath = join5(outDir, SPEC_FILENAME);
+  if (!await pathExists(planPath) && await pathExists(sourceSpecPath)) {
+    const raw2 = await loadIrFile(sourceSpecPath, "spec");
+    const specNeeds = isPlainRecord(raw2) && (needsChromeRewrite(raw2) || needsBloomRewrite(raw2) || needsBannerHeadingRewrite(raw2));
+    const pages2 = await rewriteLeftoverPages(dir, outDir);
+    if (specNeeds && isPlainRecord(raw2)) {
+      const chrome = needsChromeRewrite(raw2);
+      const bloom = needsBloomRewrite(raw2);
+      const bannerHeading = needsBannerHeadingRewrite(raw2);
+      const migrated2 = applyV4LeftoverRewrites(raw2);
+      await writeMigratedJson(specPath, migrated2);
+      const specNote2 = `wrote ${specPath} (${migrateRewriteNote(chrome, bloom, false, bannerHeading)})`;
+      if (pages2.paths.length === 0) return specNote2;
+      return `${specNote2}, wrote ${pages2.paths.length === 1 ? pages2.paths[0] : join5(outDir, PAGES_DIRNAME)} (${migrateRewriteNote(false, false, pages2.logoWall, pages2.bannerHeading)})`;
+    }
+    if (pages2.paths.length > 0) {
+      const target = pages2.paths.length === 1 ? pages2.paths[0] : join5(outDir, PAGES_DIRNAME);
+      return `wrote ${target} (${migrateRewriteNote(false, false, pages2.logoWall, pages2.bannerHeading)})`;
+    }
+    throw new PptwiseError(
+      `${dir} has ${SPEC_FILENAME} but no ${PLAN_FILENAME} \u2014 this deck project is already migrated, nothing to do`
+    );
+  }
+  const raw = await loadIrFile(planPath, "plan");
+  const migrated = migrateDeckPlanToSpec(raw);
+  await writeMigratedJson(specPath, migrated);
+  const pages = await rewriteLeftoverPages(dir, outDir);
+  const specNote = `wrote ${specPath} \u2014 run \`pptwise spec validate ${specPath}\` to confirm it, then delete ${planPath} (a directory with both files present is rejected)`;
+  if (pages.paths.length === 0) return specNote;
+  return `${specNote}, wrote ${pages.paths.length === 1 ? pages.paths[0] : join5(outDir, PAGES_DIRNAME)} (${migrateRewriteNote(false, false, pages.logoWall, pages.bannerHeading)})`;
+}
+async function runMigrateIrFile(filePath, output, cwd) {
+  const raw = await loadIrFile(filePath);
+  const version = typeof raw === "object" && raw !== null ? raw.version : void 0;
+  if (version === "2") {
+    throw new PptwiseError(
+      "pptwise migrate does not support IR v2 (spec \xA715.3: v2 has no real users) \u2014 run `pptwise validate` on the v2 file to see the full v2\u2192v4 combined field mapping and rewrite it by hand"
+    );
+  }
+  const outPath = resolve6(cwd, output);
+  if (version === "3") {
+    const pre = isPlainRecord(raw) ? migrateLogoWallToImageGrid(raw) : raw;
+    const parsed = PptxIRV3Schema.safeParse(pre);
+    if (!parsed.success) {
+      const detail = parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
+      throw new PptwiseError(`invalid IR v3 file ${filePath}:
+${detail}`);
+    }
+    const migrated = migrateIrV3ToV4(parsed.data);
+    await writeMigratedJson(outPath, migrated);
+    return `wrote ${outPath} (migrated IR v3 \u2192 v4)`;
+  }
+  if (isPlainRecord(raw) && (needsChromeRewrite(raw) || needsBloomRewrite(raw) || needsLogoWallRewrite(raw) || needsBannerHeadingRewrite(raw))) {
+    const chrome = needsChromeRewrite(raw);
+    const bloom = needsBloomRewrite(raw);
+    const logoWall = needsLogoWallRewrite(raw);
+    const bannerHeading = needsBannerHeadingRewrite(raw);
+    const migrated = applyV4LeftoverRewrites(raw);
+    await writeMigratedJson(outPath, migrated);
+    return `wrote ${outPath} (${migrateRewriteNote(chrome, bloom, logoWall, bannerHeading)})`;
+  }
+  throw new PptwiseError(
+    `pptwise migrate converts an IR v3 file (version: "3"), a v4 IR or deck spec still carrying the old chrome field (renamed to branding), the removed bloom theme id (relocated to classroom), a leftover logo_wall component (rewritten to image_grid), or a leftover banner-heading layout pin (rewritten to two-column), or a deck project directory containing ${PLAN_FILENAME} \u2014 got version ${JSON.stringify(version)} in ${filePath} with nothing to migrate`
+  );
+}
+
+// src/cli/secret-input.ts
+import readline from "readline";
+async function readSecret(prompt, io = { stdin: process.stdin, stderr: process.stderr }) {
+  const { stdin, stderr } = io;
+  const isTTY = Boolean(stdin.isTTY);
+  if (!isTTY) {
+    const line = await readFirstLine(stdin);
+    if (line === "") throw new PptwiseError("API key cannot be empty");
+    return line;
+  }
+  return await readHiddenTty(prompt, stdin, stderr);
+}
+function readFirstLine(stdin) {
+  return new Promise((resolve8, reject) => {
+    const encoding = stdin.readableEncoding ?? "utf8";
+    let buf = "";
+    const onData = (chunk) => {
+      buf += typeof chunk === "string" ? chunk : chunk.toString(encoding);
+      const nl = buf.indexOf("\n");
+      if (nl === -1) return;
+      cleanup();
+      resolve8(buf.slice(0, nl).replace(/\r$/, "").trim());
+    };
+    const onEnd = () => {
+      cleanup();
+      resolve8(buf.replace(/\r$/, "").trim());
+    };
+    const onError = (e) => {
+      cleanup();
+      reject(e);
+    };
+    const cleanup = () => {
+      stdin.off("data", onData);
+      stdin.off("end", onEnd);
+      stdin.off("error", onError);
+    };
+    stdin.on("data", onData);
+    stdin.on("end", onEnd);
+    stdin.on("error", onError);
+  });
+}
+function readHiddenTty(prompt, stdin, stderr) {
+  return new Promise((resolve8, reject) => {
+    const rl = readline.createInterface({ input: stdin, output: stderr, terminal: true });
+    const mutable = rl;
+    mutable._writeToOutput = () => {
+    };
+    stderr.write(prompt);
+    let settled = false;
+    const finish = (fn) => {
+      if (settled) return;
+      settled = true;
+      fn();
+    };
+    rl.question("", (answer) => {
+      finish(() => {
+        rl.close();
+        stderr.write("\n");
+        const value = answer.trim();
+        if (value === "") reject(new PptwiseError("API key cannot be empty"));
+        else resolve8(value);
+      });
+    });
+    rl.on("SIGINT", () => {
+      finish(() => {
+        rl.close();
+        stderr.write("\n");
+        reject(new PptwiseError("cancelled"));
+      });
+    });
+    rl.on("close", () => {
+      finish(() => reject(new PptwiseError("cancelled")));
+    });
+  });
+}
+
+// src/cli/config-cmd.ts
+function canOmitValue(key) {
+  return key.endsWith(".apiKey") || key.endsWith(".clientSecret");
+}
+async function runConfigSet(key, value, opts = {}) {
+  if (value === void 0 && !canOmitValue(key)) {
+    throw new PptwiseError(`${key} needs a value: pptwise config set ${key} <value>`);
+  }
+  const parsed = parseCliConfigKey(key);
+  let resolved = value;
+  if (resolved === void 0) {
+    const read = opts.readSecret ?? readSecret;
+    resolved = await read(`${key} (input hidden): `, opts.io);
+  }
+  const stored = parseCliConfigValue(parsed, resolved);
+  const path2 = await persistUserConfigValue(parsed.path, stored);
+  return `Saved ${key} to ${path2}`;
+}
+async function runConfigShow(opts = {}) {
+  const path2 = userConfigPath();
+  const hit = await findUserConfig();
+  const file = hit?.config ?? null;
+  const keys = resolveImageKeys({ file, env: opts.env ?? process.env });
+  const lines = [`User config: ${path2}`, ""];
+  for (const provider of ["pexels", "pixabay"]) {
+    const label = `${provider}.apiKey`;
+    const entry = keys[provider];
+    if (!entry.apiKey) {
+      lines.push(`${label}  missing`);
+      continue;
+    }
+    const src = entry.source === null ? "" : ` (${entry.source})`;
+    lines.push(`${label}  ${maskKey(entry.apiKey)}${src}`);
+  }
+  const ov = keys.openverse;
+  const ovSrc = ov.source === null ? "" : ` (${ov.source})`;
+  if (ov.clientId) lines.push(`openverse.clientId  ${maskKey(ov.clientId)}${ovSrc}`);
+  else lines.push("openverse.clientId  missing");
+  if (ov.clientSecret) lines.push(`openverse.clientSecret  ${maskKey(ov.clientSecret)}${ovSrc}`);
+  else lines.push("openverse.clientSecret  missing");
+  const gens = resolveGenerators({ file });
+  lines.push("");
+  for (const id of GENERATOR_IDS) {
+    lines.push(`images.generators.${id}.enabled  ${gens.enabled[id] ? "true" : "false"}`);
+  }
+  const rawGens = file?.images?.generators;
+  if (rawGens?.order) lines.push(`images.generators.order  ${rawGens.order.join(",")}`);
+  if (rawGens?.timeoutMs !== void 0) lines.push(`images.generators.timeoutMs  ${rawGens.timeoutMs}`);
+  return lines.join("\n");
+}
+
+// src/cli/doctor.ts
+import { lstatSync as lstatSync2 } from "fs";
+import { access, readFile as readFile7, readdir as readdir5 } from "fs/promises";
+import { homedir } from "os";
+import { basename as basename5, join as join7 } from "path";
+
+// src/cli/image-generators.ts
+import { copyFile as copyFile2, readdir as readdir4, stat as stat3 } from "fs/promises";
+import { join as join6 } from "path";
+var GENERATOR_PROBE_TIMEOUT_MS = 2e3;
+var BIN_NAMES = {
+  grok: ["grok"],
+  codex: ["codex"],
+  antigravity: ["antigravity", "agy"]
+};
+async function locateGeneratorBin(id, env) {
+  for (const name of BIN_NAMES[id]) {
+    const found = await findOnPath(name, env);
+    if (found) return found;
+  }
+  return null;
+}
+function parseGeneratorVersion(stdout) {
+  const line = stdout.trim().split("\n")[0] ?? "";
+  const m = /(\d+\.\d+\.\d+\S*)/.exec(line);
+  return m?.[1] ?? line;
+}
+async function defaultProcessRunner(req) {
+  try {
+    return await runChild(req.command, req.args, {
+      cwd: req.cwd,
+      env: req.env,
+      timeoutMs: req.timeoutMs
+    });
+  } catch (error) {
+    if (error instanceof ChildTimeoutError) {
+      throw new PptwiseError(`image generator timed out after ${req.timeoutMs}ms`);
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    return { code: 1, stdout: "", stderr: message };
+  }
+}
+async function probeGenerators(opts) {
+  const env = opts.env ?? process.env;
+  const run = opts.run ?? defaultProcessRunner;
+  const probes = [];
+  for (const id of GENERATOR_IDS) {
+    const bin = await locateGeneratorBin(id, env);
+    let version = null;
+    if (bin) {
+      try {
+        const result = await run({ command: bin, args: ["--version"], cwd: void 0, timeoutMs: GENERATOR_PROBE_TIMEOUT_MS, env });
+        if (result.code === 0) version = parseGeneratorVersion(result.stdout);
+      } catch {
+        version = null;
+      }
+    }
+    probes.push({ id, found: bin !== null, bin, version, enabled: opts.enabled[id] === true });
+  }
+  return probes;
+}
+function destContractPrompt(userPrompt, destAbs, toolName) {
+  return [
+    `Generate exactly one image with the ${toolName} tool using this prompt:`,
+    userPrompt,
+    `Then copy or move the saved file to ${destAbs} so that path exists as a real image file.`,
+    "Print DONE when that path exists. Edit no other files."
+  ].join("\n");
+}
+async function isSniffedImage(path2) {
+  try {
+    const { readFile: readFile9 } = await import("fs/promises");
+    const bytes = await readFile9(path2);
+    return sniffImageFormat(bytes) !== null;
+  } catch {
+    return false;
+  }
+}
+async function collectFiles(dir, acc) {
+  let entries;
+  try {
+    entries = await readdir4(dir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const full = join6(dir, entry.name);
+    if (entry.isDirectory()) {
+      await collectFiles(full, acc);
+    } else if (entry.isFile()) {
+      try {
+        const st = await stat3(full);
+        acc.push({ path: full, mtime: st.mtimeMs });
+      } catch {
+      }
+    }
+  }
+}
+async function harvestNewestImage(workdir, dest) {
+  const files = [];
+  await collectFiles(workdir, files);
+  const images2 = [];
+  for (const file of files) {
+    if (file.path === dest) continue;
+    if (await isSniffedImage(file.path)) images2.push(file);
+  }
+  images2.sort((a, b) => b.mtime - a.mtime);
+  const newest = images2[0];
+  if (!newest) return false;
+  await copyFile2(newest.path, dest);
+  return isSniffedImage(dest);
+}
+async function settleDest(req, result) {
+  if (await isSniffedImage(req.dest)) return;
+  if (await harvestNewestImage(req.workdir, req.dest)) return;
+  const detail = (result.stderr || result.stdout).trim().slice(0, 400);
+  throw new PptwiseError(
+    result.code === 0 ? `produced no image file at ${req.dest}${detail ? `: ${detail}` : ""}` : `exited ${result.code}${detail ? `: ${detail}` : ""}`
+  );
+}
+async function runGrokAdapter(req) {
+  const result = await req.run({
+    command: req.bin,
+    args: [
+      "-p",
+      destContractPrompt(req.prompt, req.dest, "image_gen"),
+      "--cwd",
+      req.workdir,
+      "--permission-mode",
+      "bypassPermissions",
+      "--max-turns",
+      "12"
+    ],
+    cwd: req.workdir,
+    timeoutMs: req.timeoutMs
+  });
+  await settleDest(req, result);
+}
+async function runCodexAdapter(req) {
+  const result = await req.run({
+    command: req.bin,
+    args: [
+      "exec",
+      "--dangerously-bypass-approvals-and-sandbox",
+      "--skip-git-repo-check",
+      "--ephemeral",
+      "-C",
+      req.workdir,
+      destContractPrompt(req.prompt, req.dest, "image_gen__imagegen")
+    ],
+    cwd: req.workdir,
+    timeoutMs: req.timeoutMs
+  });
+  await settleDest(req, result);
+}
+async function runAntigravityAdapter(req) {
+  const seconds = Math.max(1, Math.ceil(req.timeoutMs / 1e3));
+  const result = await req.run({
+    command: req.bin,
+    args: [
+      "-p",
+      destContractPrompt(req.prompt, req.dest, "generate_image"),
+      "--dangerously-skip-permissions",
+      "--print-timeout",
+      `${seconds}s`
+    ],
+    cwd: req.workdir,
+    timeoutMs: req.timeoutMs
+  });
+  await settleDest(req, result);
+}
+var GENERATOR_ADAPTERS = {
+  grok: runGrokAdapter,
+  codex: runCodexAdapter,
+  antigravity: runAntigravityAdapter
+};
+
+// src/cli/update.ts
+var PACKAGE_NAME = "@liustack/pptwise";
+function normalizeVersion(version) {
+  const normalized = version.trim().replace(/^v/i, "").split("-")[0];
+  if (!normalized) throw new Error(`invalid version: ${version}`);
+  return normalized;
+}
+function parseVersion(version) {
+  return normalizeVersion(version).split(".").map((segment) => {
+    const value = Number.parseInt(segment, 10);
+    if (!Number.isFinite(value)) throw new Error(`invalid version segment: ${segment}`);
+    return value;
+  });
+}
+function compareVersions(left, right) {
+  const l = parseVersion(left);
+  const r = parseVersion(right);
+  for (let i = 0; i < Math.max(l.length, r.length); i++) {
+    const a = l[i] ?? 0;
+    const b = r[i] ?? 0;
+    if (a !== b) return a < b ? -1 : 1;
+  }
+  return 0;
+}
+var runCommand = async (command, args) => {
+  const { code, stdout, stderr } = await runChild(command, args);
+  if (code !== 0) throw new Error(stderr.trim() || `exited ${code}`);
+  return stdout.trim();
+};
+async function checkForUpdate({
+  currentVersion,
+  packageName = PACKAGE_NAME,
+  run = runCommand
+}) {
+  const current = normalizeVersion(currentVersion);
+  try {
+    const latest = normalizeVersion(await run("npm", ["view", packageName, "version"]));
+    return {
+      packageName,
+      currentVersion: current,
+      latestVersion: latest,
+      updateAvailable: compareVersions(current, latest) < 0,
+      checked: true
+    };
+  } catch (error) {
+    return {
+      packageName,
+      currentVersion: current,
+      latestVersion: null,
+      updateAvailable: false,
+      checked: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+function createSelfUpdater(run = runCommand) {
+  return async ({
+    currentVersion,
+    packageName = PACKAGE_NAME
+  }) => {
+    const info = await checkForUpdate({ currentVersion, packageName, run });
+    if (!info.checked) throw new Error(`unable to check for updates: ${info.error ?? "unknown error"}`);
+    if (!info.updateAvailable) return { ...info, updated: false };
+    await run("npm", ["install", "-g", `${packageName}@latest`]);
+    return { ...info, updated: true };
+  };
+}
+
+// src/cli/doctor.ts
+var MIN_NODE = "22.19";
+var SKILL_DIR_NAME = "pptwise";
+var LEGACY_SKILL_DIR_NAMES = ["pptpress", "pptfast"];
+var SKILL_COPY_FILES = [
+  "SKILL.md",
+  "SKILL.zh-CN.md",
+  "scripts/run.sh",
+  "scripts/run.ps1",
+  "references/spec.md",
+  "references/spec.zh-CN.md",
+  "references/layouts.md",
+  "references/layouts.zh-CN.md",
+  "references/components.md",
+  "references/components.zh-CN.md",
+  "references/density.md",
+  "references/density.zh-CN.md",
+  "references/branding.md",
+  "references/branding.zh-CN.md",
+  "references/images.md",
+  "references/images.zh-CN.md",
+  "references/validate.md",
+  "references/validate.zh-CN.md"
+];
+var SKILL_ROOTS = [
+  { harness: "Claude Code", relative: join7(".claude", "skills") },
+  { harness: "Codex", relative: join7(".codex", "skills") },
+  { harness: "Pi, OpenCode", relative: join7(".agents", "skills") }
+];
+var SELF_TEST_DECK = {
+  version: "4",
+  filename: "pptwise-doctor-self-test.pptx",
+  theme: { id: "consulting" },
+  slides: [
+    { type: "cover", heading: "pptwise doctor", subheading: "self-test render" },
+    {
+      type: "content",
+      heading: "Core chain",
+      components: [{ type: "bullets", items: ["validate the IR", "render a slide to SVG", "generate the .pptx bytes"] }]
+    }
+  ]
+};
+function readPinnedVersion(launcher) {
+  return /^PINNED="([^"]+)"/m.exec(launcher)?.[1] ?? null;
+}
+function isOlder(version, current) {
+  try {
+    return compareVersions(version, current) < 0;
+  } catch {
+    return false;
+  }
+}
+async function pathExists2(target) {
+  try {
+    await access(target);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function scanSkillCopies(home, currentVersion) {
+  const scanned = [];
+  const copies = [];
+  for (const { harness, relative: relative3 } of SKILL_ROOTS) {
+    const root = join7(home, relative3);
+    scanned.push(root);
+    for (const { dirName, legacy } of [
+      { dirName: SKILL_DIR_NAME, legacy: false },
+      ...LEGACY_SKILL_DIR_NAMES.map((dirName2) => ({ dirName: dirName2, legacy: true }))
+    ]) {
+      const copyDir = join7(root, dirName);
+      if (!await pathExists2(copyDir)) continue;
+      const launcherPath = join7(copyDir, "scripts", "run.sh");
+      let pinned = null;
+      let launcher = null;
+      try {
+        pinned = readPinnedVersion(await readFile7(launcherPath, "utf8"));
+        launcher = launcherPath;
+      } catch {
+      }
+      const missing = [];
+      for (const rel of SKILL_COPY_FILES) {
+        if (!await pathExists2(join7(copyDir, rel))) missing.push(rel);
+      }
+      copies.push({
+        harness,
+        root,
+        path: copyDir,
+        launcher,
+        pinned,
+        stale: legacy || pinned !== null && isOlder(pinned, currentVersion),
+        missing,
+        legacy
+      });
+    }
+  }
+  return { scanned, copies };
+}
+async function readInstalledPluginVersion(profileDir) {
+  const pkgPath = join7(profileDir, "node_modules", ...PACKAGE_NAME.split("/"), "package.json");
+  try {
+    const pkg = JSON.parse(await readFile7(pkgPath, "utf8"));
+    return typeof pkg.version === "string" ? pkg.version : null;
+  } catch {
+    return null;
+  }
+}
+async function inspectDsh(home, currentVersion) {
+  const dshHome = join7(home, ".dsh");
+  if (!await pathExists2(dshHome)) return { applicable: false, home: dshHome, profiles: [] };
+  const profilesDir = join7(dshHome, "profiles");
+  let entries;
+  try {
+    const dirents = await readdir5(profilesDir, { withFileTypes: true });
+    entries = dirents.filter((d) => d.isDirectory() && d.name !== "node_modules").map((d) => d.name);
+  } catch {
+    return { applicable: true, home: dshHome, profiles: [] };
+  }
+  const profiles = [];
+  for (const name of entries.sort()) {
+    const profileDir = join7(profilesDir, name);
+    let declared;
+    try {
+      const pkg = JSON.parse(await readFile7(join7(profileDir, "package.json"), "utf8"));
+      declared = pkg.dependencies?.[PACKAGE_NAME];
+    } catch {
+      continue;
+    }
+    const installedVersion = await readInstalledPluginVersion(profileDir);
+    const declaredVersion = typeof declared === "string" && /^\d+\.\d+\.\d+/.test(declared) ? declared.match(/^\d+\.\d+\.\d+/)[0] : null;
+    const version = installedVersion ?? declaredVersion;
+    const installed = installedVersion !== null || declared !== void 0;
+    profiles.push({
+      name,
+      path: profileDir,
+      installed,
+      version,
+      source: installedVersion !== null ? "node_modules" : declaredVersion !== null ? "package.json" : null,
+      stale: installed && version !== null && isOlder(version, currentVersion)
+    });
+  }
+  return { applicable: true, home: dshHome, profiles };
+}
+function dshInstallCommand(profile, version) {
+  return `npx -y @deepseek-ai/dsh plugin --profile ${profile} add ${PACKAGE_NAME}@${version}`;
+}
+async function inspectCapabilities(env) {
+  const capabilities = [];
+  let sharpAvailable = false;
+  let sharpError = null;
+  try {
+    await import("sharp");
+    sharpAvailable = true;
+  } catch (e) {
+    sharpError = isMissingModuleError(e) ? "not installed" : e instanceof Error ? e.message : String(e);
+  }
+  capabilities.push({
+    name: "sharp",
+    available: sharpAvailable,
+    detail: sharpAvailable ? "importable \u2014 preview rasterization and `audit --pixels` are available" : `${sharpError} \u2014 preview rasterization and \`audit --pixels\` are unavailable. Plain SVG preview and .pptx rendering are unaffected`,
+    fix: sharpAvailable ? void 0 : "npm i sharp (optional dependency \u2014 install it only if you want the pixel checks)"
+  });
+  const soffice = await findOnPath("soffice", env);
+  capabilities.push({
+    name: "soffice",
+    available: soffice !== null,
+    detail: soffice !== null ? `found at ${soffice} \u2014 the PDF export path is available` : "not on PATH \u2014 the PDF export path is unavailable. Rendering and validating .pptx files are unaffected",
+    fix: soffice !== null ? void 0 : "install LibreOffice (https://libreoffice.org) and make sure `soffice` is on PATH"
+  });
+  return capabilities;
+}
+function posixBitsApply() {
+  return typeof process.getuid === "function";
+}
+async function inspectImages(env) {
+  const configPath = userConfigPath();
+  let configExists = false;
+  let groupOrOtherReadable = false;
+  try {
+    const st = lstatSync2(configPath);
+    configExists = true;
+    if (posixBitsApply() && !st.isSymbolicLink()) {
+      groupOrOtherReadable = (st.mode & 63) !== 0;
+    }
+  } catch {
+    configExists = false;
+  }
+  let file = null;
+  try {
+    file = await findUserConfig();
+  } catch {
+    file = null;
+  }
+  const keys = resolveImageKeys({ file: file?.config ?? null, env });
+  const providers = ["pexels", "pixabay"].map((provider) => ({
+    provider,
+    present: Boolean(keys[provider].apiKey),
+    source: keys[provider].source
+  }));
+  providers.push({
+    provider: "openverse",
+    present: keys.openverse.ready,
+    source: keys.openverse.ready ? keys.openverse.source : null
+  });
+  return { configPath, configExists, groupOrOtherReadable, providers };
+}
+async function inspectGenerators(env, run) {
+  let file = null;
+  try {
+    file = await findUserConfig();
+  } catch {
+    file = null;
+  }
+  const flags = resolveGenerators({ file: file?.config ?? null });
+  return probeGenerators({ env, run, enabled: flags.enabled });
+}
+async function runSelfTest() {
+  const started = performance.now();
+  const elapsed = () => Math.round(performance.now() - started);
+  try {
+    const v = validateIr(SELF_TEST_DECK);
+    if (!v.ok) throw new Error(`the built-in self-test deck failed validation:
+${formatIssues(v.errors)}`);
+    const svg = renderSlideSvg(v.ir, 0);
+    if (!svg.includes("<svg")) throw new Error("the SVG renderer produced no <svg> element");
+    const bytes = await generatePptx(v.ir);
+    if (bytes.length === 0) throw new Error("the PPTX generator produced zero bytes");
+    return { ok: true, elapsedMs: elapsed(), slides: v.ir.slides.length, bytes: bytes.length };
+  } catch (e) {
+    return {
+      ok: false,
+      elapsedMs: elapsed(),
+      slides: SELF_TEST_DECK.slides.length,
+      bytes: null,
+      error: e instanceof Error ? e.message : String(e)
+    };
+  }
+}
+function skillRefreshCommand(copyDir) {
+  return `rm -rf /tmp/pptwise-src && git clone --depth 1 https://github.com/liustack/pptwise.git /tmp/pptwise-src && cp -R /tmp/pptwise-src/skills/${SKILL_DIR_NAME}/. ${copyDir}/`;
+}
+async function buildDoctorReport(input = {}) {
+  const version = input.version ?? VERSION;
+  const home = input.home ?? homedir();
+  const env = input.env ?? process.env;
+  const nodeVersion = input.nodeVersion ?? process.version;
+  const cwd = input.cwd ?? process.cwd();
+  const [skills, dsh, capabilities, selfTest, projectHit, images2, generators] = await Promise.all([
+    scanSkillCopies(home, version),
+    inspectDsh(home, version),
+    inspectCapabilities(env),
+    runSelfTest(),
+    findConfig(cwd),
+    inspectImages(env),
+    inspectGenerators(env, input.runProcess)
+  ]);
+  const workspace = await inspectWorkspace({
+    cwd,
+    projectConfigPath: projectHit?.path,
+    outDir: projectHit?.config.outDir,
+    runGit: input.runGit
+  });
+  let meetsMinimum = true;
+  try {
+    meetsMinimum = compareVersions(nodeVersion, MIN_NODE) >= 0;
+  } catch {
+    meetsMinimum = true;
+  }
+  const runtime = {
+    node: nodeVersion,
+    bun: process.versions.bun ?? null,
+    minimum: MIN_NODE,
+    meetsMinimum
+  };
+  const errors = [];
+  const warnings = [];
+  if (!runtime.meetsMinimum) {
+    errors.push({
+      check: "runtime",
+      message: `Node ${runtime.node} is below the ${MIN_NODE} floor pptwise needs`,
+      fix: `install Node ${MIN_NODE}+ from https://nodejs.org (or \`nvm install 22\`), open a new shell, then re-run \`pptwise doctor\``
+    });
+  }
+  if (!selfTest.ok) {
+    errors.push({
+      check: "self-test",
+      message: `the self-test render failed: ${selfTest.error}`,
+      fix: `reinstall the CLI: npm install -g ${PACKAGE_NAME}`
+    });
+  }
+  for (const copy of skills.copies) {
+    if (copy.legacy) {
+      warnings.push({
+        check: "skill copy",
+        message: `${copy.path} is a leftover ${basename5(copy.path)} skill copy`,
+        fix: `remove it and install the pptwise skill in ${join7(copy.root, SKILL_DIR_NAME)}`
+      });
+    } else if (copy.stale) {
+      warnings.push({
+        check: "skill copy",
+        message: `${copy.path} pins ${copy.pinned}, behind this CLI's ${version}`,
+        fix: `re-run the install to overwrite the copy in place: ${skillRefreshCommand(copy.path)}`
+      });
+    } else if (copy.pinned === null) {
+      warnings.push({
+        check: "skill copy",
+        message: `${copy.path} has ${copy.launcher === null ? "no scripts/run.sh" : "a scripts/run.sh with no PINNED line"} \u2014 version unknown, so drift cannot be ruled out`,
+        fix: `re-run the install to restore a complete copy: ${skillRefreshCommand(copy.path)}`
+      });
+    }
+    if (copy.missing.length > 0) {
+      warnings.push({
+        check: "skill copy",
+        message: `${copy.path} is missing ${copy.missing.join(", ")}`,
+        fix: `re-run the install to restore a complete copy: ${skillRefreshCommand(copy.path)}`
+      });
+    }
+  }
+  for (const profile of dsh.profiles) {
+    if (profile.stale) {
+      warnings.push({
+        check: "dsh plugin",
+        message: `profile "${profile.name}" has ${PACKAGE_NAME} ${profile.version}, behind this CLI's ${version}`,
+        fix: dshInstallCommand(profile.name, version)
+      });
+    }
+  }
+  for (const capability of capabilities) {
+    if (!capability.available) {
+      warnings.push({ check: "capability", message: `${capability.name}: ${capability.detail}`, fix: capability.fix });
+    }
+  }
+  if (images2.groupOrOtherReadable) {
+    warnings.push({
+      check: "images",
+      message: `${images2.configPath} is group/other-readable \u2014 API keys should be mode 0600`,
+      fix: `chmod 600 ${images2.configPath}`
+    });
+  }
+  return { version, runtime, skills, dsh, capabilities, selfTest, workspace, images: images2, generators, errors, warnings };
+}
+function mark(state) {
+  return state === "ok" ? "[ok]" : state === "warn" ? "[!]" : state === "fail" ? "[!!]" : "[-]";
+}
+function renderDoctorReport(report) {
+  const lines = [];
+  lines.push(`pptwise doctor \u2014 CLI ${report.version}`);
+  lines.push("(local diagnostics only: nothing is written, no network call is made)");
+  lines.push("");
+  lines.push("Installed skill copies (a copy keeps its install-time version forever)");
+  if (report.skills.copies.length === 0) {
+    lines.push("  [-] no installed skill copy found \u2014 the CLI runs fine on its own, and dsh ships the");
+    lines.push("      skill inside the plugin instead");
+    lines.push(`      looked in: ${report.skills.scanned.join(", ")}`);
+  } else {
+    for (const copy of report.skills.copies) {
+      const state = copy.legacy || copy.stale || copy.pinned === null || copy.missing.length > 0 ? "warn" : "ok";
+      const pin = copy.legacy ? `leftover ${basename5(copy.path)} copy` : copy.pinned === null ? "version unknown" : `pins ${copy.pinned}`;
+      lines.push(`  ${mark(state)} ${copy.harness}: ${copy.path} \u2014 ${pin}${copy.stale && !copy.legacy ? " (stale)" : ""}`);
+      if (copy.legacy) {
+        lines.push(`      fix: remove it and install the pptwise skill in ${join7(copy.root, SKILL_DIR_NAME)}`);
+      } else if (copy.stale) {
+        lines.push(`      fix: ${skillRefreshCommand(copy.path)}`);
+      } else if (copy.pinned === null) {
+        lines.push(`      ${copy.launcher === null ? "no scripts/run.sh in this copy" : "scripts/run.sh carries no PINNED line"}`);
+        lines.push(`      fix: ${skillRefreshCommand(copy.path)}`);
+      }
+      if (copy.missing.length > 0) {
+        lines.push(`      missing: ${copy.missing.join(", ")}`);
+        lines.push(`      fix: ${skillRefreshCommand(copy.path)}`);
+      }
+    }
+  }
+  lines.push("");
+  lines.push("DSH plugin");
+  if (!report.dsh.applicable) {
+    lines.push(`  ${mark("n/a")} no ${report.dsh.home} \u2014 not a dsh machine, this check does not apply`);
+  } else if (report.dsh.profiles.length === 0) {
+    lines.push(`  ${mark("n/a")} ${report.dsh.home} exists but has no profiles to inspect`);
+  } else {
+    for (const profile of report.dsh.profiles) {
+      if (!profile.installed) {
+        lines.push(`  ${mark("n/a")} ${profile.name}: ${PACKAGE_NAME} not installed in this profile`);
+        continue;
+      }
+      const version = profile.version ?? "version unknown";
+      lines.push(`  ${mark(profile.stale ? "warn" : "ok")} ${profile.name}: ${version}${profile.source ? ` (via ${profile.source})` : ""}${profile.stale ? " (behind this CLI)" : ""}`);
+      if (profile.stale) {
+        lines.push(`      fix: ${dshInstallCommand(profile.name, report.version)}`);
+      }
+    }
+  }
+  lines.push("");
+  lines.push("Runtime");
+  lines.push(`  ${mark(report.runtime.meetsMinimum ? "ok" : "fail")} Node ${report.runtime.node} (minimum ${report.runtime.minimum})`);
+  if (report.runtime.bun !== null) {
+    lines.push(`  ${mark("ok")} running under Bun ${report.runtime.bun}`);
+  }
+  lines.push("");
+  lines.push("Optional capabilities (neither is needed by the main flow)");
+  for (const capability of report.capabilities) {
+    lines.push(`  ${mark(capability.available ? "ok" : "warn")} ${capability.name}: ${capability.detail}`);
+    if (capability.fix) lines.push(`      fix: ${capability.fix}`);
+  }
+  lines.push("");
+  lines.push("Self-test render (a built-in deck through the real pipeline, in memory)");
+  lines.push(
+    report.selfTest.ok ? `  ${mark("ok")} ${report.selfTest.slides} slides validated, rendered, and packed into ${report.selfTest.bytes} bytes in ${report.selfTest.elapsedMs}ms` : `  ${mark("fail")} failed after ${report.selfTest.elapsedMs}ms: ${report.selfTest.error}`
+  );
+  lines.push("");
+  lines.push("Workspace artifacts (where render/preview write when -o is omitted)");
+  lines.push(`  ${mark("ok")} anchor ${report.workspace.anchor}`);
+  lines.push(
+    report.workspace.configured ? `  ${mark("ok")} output ${report.workspace.root} (from pptwise.config.json outDir)` : `  ${mark("ok")} output ${report.workspace.root}`
+  );
+  if (report.workspace.ignore === "ignored") {
+    lines.push(`  ${mark("ok")} git-ignored`);
+  } else if (report.workspace.ignore === "not-ignored") {
+    lines.push(`  ${mark("n/a")} not git-ignored \u2014 the first render will add a local exclude line`);
+  } else if (report.workspace.ignore === "skipped") {
+    lines.push(`  ${mark("n/a")} git-ignore skipped (outDir is set in pptwise.config.json)`);
+  } else {
+    lines.push(`  ${mark("n/a")} not a git repository`);
+  }
+  lines.push("");
+  lines.push("Images (optional stock-photo search \u2014 rendering PPTX still needs no credentials)");
+  lines.push(`  ${mark("ok")} config ${report.images.configPath}${report.images.configExists ? "" : " (missing)"}`);
+  if (report.images.groupOrOtherReadable) {
+    lines.push(`  ${mark("warn")} file is group/other-readable \u2014 chmod 600`);
+  }
+  for (const provider of report.images.providers) {
+    if (provider.present) {
+      lines.push(`  ${mark("ok")} ${provider.provider}: present (${provider.source})`);
+    } else if (provider.provider === "openverse") {
+      lines.push(`  ${mark("n/a")} openverse: missing \u2014 pptwise config set openverse.clientId`);
+    } else {
+      lines.push(`  ${mark("n/a")} ${provider.provider}: missing \u2014 pptwise config set ${provider.provider}.apiKey`);
+    }
+  }
+  lines.push("");
+  lines.push("Image generators (optional, off until enabled)");
+  for (const gen of report.generators) {
+    if (!gen.found) {
+      lines.push(`  ${mark("n/a")} ${gen.id}: not found`);
+      continue;
+    }
+    const ver = gen.version ? `, ${gen.version}` : "";
+    const state = gen.enabled ? "enabled" : "disabled";
+    const hint = gen.enabled ? "" : ` \u2014 pptwise config set images.generators.${gen.id}.enabled true`;
+    lines.push(`  ${mark("ok")} ${gen.id}: found (${gen.bin}${ver}) ${state}${hint}`);
+  }
+  lines.push("");
+  lines.push(
+    `${report.errors.length} error${report.errors.length === 1 ? "" : "s"}, ${report.warnings.length} warning${report.warnings.length === 1 ? "" : "s"}`
+  );
+  for (const error of report.errors) {
+    lines.push(`  [!!] ${error.check}: ${error.message}`);
+    if (error.fix) lines.push(`       fix: ${error.fix}`);
+  }
+  for (const warning of report.warnings) {
+    lines.push(`  [!] ${warning.check}: ${warning.message}`);
+  }
+  if (report.errors.length === 0) {
+    lines.push(report.warnings.length === 0 ? "pptwise is healthy on this machine" : "nothing blocking \u2014 the warnings above are worth fixing when convenient");
+  }
+  return lines.join("\n");
+}
+async function runDoctor(opts = {}) {
+  const report = await buildDoctorReport(opts);
+  return {
+    output: opts.json ? JSON.stringify(report, null, 2) : renderDoctorReport(report),
+    hasErrors: report.errors.length > 0
+  };
+}
+
+// src/cli/images.ts
+import { mkdir as mkdir5, mkdtemp, readFile as readFile8, readdir as readdir6, rename, rm as rm2, unlink as unlink2, writeFile as writeFile4 } from "fs/promises";
+import { tmpdir } from "os";
+import { dirname as dirname4, join as join8, resolve as resolve7 } from "path";
+
+// src/cli/redact.ts
+var KEY_QUERY = /([?&](?:api_)?key=)[^&\s"'<>]*/gi;
+var CLIENT_SECRET_QUERY = /(client_secret=)[^&\s"'<>]*/gi;
+function redactSecrets(text, knownSecrets = []) {
+  let out = text;
+  const secrets = knownSecrets.filter((s) => s.length >= 6).sort((a, b) => b.length - a.length);
+  for (const secret of secrets) {
+    out = out.split(secret).join("[redacted]");
+  }
+  out = out.replace(KEY_QUERY, "$1[redacted]");
+  out = out.replace(CLIENT_SECRET_QUERY, "$1[redacted]");
+  return out;
+}
+
+// src/cli/image-openverse.ts
+var OPENVERSE_SEARCH_URL = "https://api.openverse.org/v1/images/";
+var OPENVERSE_TOKEN_URL = "https://api.openverse.org/v1/auth_tokens/token/";
+var OPENVERSE_PAGE_SIZE = 8;
+var TOKEN_SKEW_MS = 3e4;
+var defaultSleep = (ms) => new Promise((resolve8) => setTimeout(resolve8, ms));
+var tokenCache = /* @__PURE__ */ new Map();
+function userAgent() {
+  return `pptwise/${VERSION} (+https://pptwise.com)`;
+}
+function asRecord(value) {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value;
+  }
+  return null;
+}
+function asString(value) {
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
+function asNumber(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function isCc0OrPdm(license) {
+  const token = (license ?? "").toLowerCase();
+  return token === "cc0" || token === "pdm";
+}
+function retryDelayMs(res, attempt) {
+  const raw = res.headers.get("Retry-After");
+  if (raw !== null && raw !== "") {
+    const seconds = Number(raw);
+    if (Number.isFinite(seconds) && seconds >= 0) return Math.round(seconds * 1e3);
+  }
+  return attempt === 0 ? 500 : 1500;
+}
+async function fetchOpenverseJson(url, init, fetchImpl, secrets, sleep) {
+  let attempt = 0;
+  while (true) {
+    let res;
+    try {
+      res = await fetchImpl(url, init);
+    } catch (e) {
+      throw new PptwiseError(
+        redactSecrets(`stock image request failed: ${e instanceof Error ? e.message : String(e)}`, secrets)
+      );
+    }
+    const text = await res.text();
+    if (res.status === 429) {
+      if (attempt >= 2) {
+        throw new PptwiseError(
+          `stock image API rate-limited (HTTP 429): ${redactSecrets(text.slice(0, 800), secrets)}`
+        );
+      }
+      await sleep(retryDelayMs(res, attempt));
+      attempt += 1;
+      continue;
+    }
+    if (!res.ok) {
+      throw new PptwiseError(`stock image API HTTP ${res.status}: ${redactSecrets(text.slice(0, 800), secrets)}`);
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new PptwiseError(`stock image API returned non-JSON (HTTP ${res.status})`);
+    }
+  }
+}
+async function getOpenverseAccessToken(clientId, clientSecret, fetchImpl, secrets, sleep, now = Date.now) {
+  const cached = tokenCache.get(clientId);
+  if (cached && now() < cached.expiresAt - TOKEN_SKEW_MS) return cached.accessToken;
+  const body = new URLSearchParams({
+    grant_type: "client_credentials",
+    client_id: clientId,
+    client_secret: clientSecret
+  }).toString();
+  const json = await fetchOpenverseJson(
+    OPENVERSE_TOKEN_URL,
+    {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+        "User-Agent": userAgent()
+      },
+      body
+    },
+    fetchImpl,
+    secrets,
+    sleep
+  );
+  const rec = asRecord(json);
+  const accessToken = asString(rec?.access_token);
+  const expiresIn = asNumber(rec?.expires_in) ?? 3600;
+  if (!accessToken) throw new PptwiseError("Openverse token response was missing access_token");
+  tokenCache.set(clientId, { accessToken, expiresAt: now() + expiresIn * 1e3 });
+  return accessToken;
+}
+async function authHeaders(creds, fetchImpl, secrets, sleep) {
+  const headers = { "User-Agent": userAgent() };
+  if (creds.clientId && creds.clientSecret) {
+    const token = await getOpenverseAccessToken(creds.clientId, creds.clientSecret, fetchImpl, secrets, sleep);
+    headers.Authorization = `Bearer ${token}`;
+  }
+  return headers;
+}
+function parseHit(raw) {
+  const photo = asRecord(raw);
+  if (!photo) return null;
+  const id = asString(photo.id);
+  const url = asString(photo.url);
+  if (!id || !url) return null;
+  const license = (asString(photo.license) ?? "").toLowerCase();
+  if (!isCc0OrPdm(license)) return null;
+  const source = asString(photo.source) ?? asString(photo.provider) ?? "openverse";
+  return {
+    id,
+    url,
+    foreignLandingUrl: asString(photo.foreign_landing_url) ?? "",
+    creator: asString(photo.creator) ?? "unknown",
+    license,
+    attribution: asString(photo.attribution) ?? "",
+    source,
+    width: asNumber(photo.width) ?? 0,
+    height: asNumber(photo.height) ?? 0,
+    thumbnail: asString(photo.thumbnail) ?? ""
+  };
+}
+function matchesOrientation(hit, orientation) {
+  if (!orientation) return true;
+  if (orientation === "landscape") return hit.width > hit.height;
+  if (orientation === "portrait") return hit.height > hit.width;
+  return hit.width === hit.height;
+}
+async function searchOpenverse(opts) {
+  const url = new URL(OPENVERSE_SEARCH_URL);
+  url.searchParams.set("q", opts.query);
+  url.searchParams.set("license_type", "commercial");
+  url.searchParams.set("license", "cc0,pdm");
+  url.searchParams.set("page_size", String(OPENVERSE_PAGE_SIZE));
+  const headers = await authHeaders(
+    { clientId: opts.clientId, clientSecret: opts.clientSecret },
+    opts.fetch,
+    opts.secrets,
+    opts.sleep
+  );
+  const json = await fetchOpenverseJson(url.toString(), { headers }, opts.fetch, opts.secrets, opts.sleep);
+  const root = asRecord(json);
+  const list = Array.isArray(root?.results) ? root.results : [];
+  const hits = [];
+  for (const raw of list) {
+    const hit = parseHit(raw);
+    if (!hit) continue;
+    if (opts.minWidth !== void 0 && hit.width < opts.minWidth) continue;
+    if (opts.minHeight !== void 0 && hit.height < opts.minHeight) continue;
+    if (!matchesOrientation(hit, opts.orientation)) continue;
+    hits.push(hit);
+    if (hits.length >= OPENVERSE_PAGE_SIZE) break;
+  }
+  return hits;
+}
+async function loadOpenverseDetail(id, creds, fetchImpl, secrets, sleep) {
+  const url = `${OPENVERSE_SEARCH_URL}${encodeURIComponent(id)}/`;
+  const headers = await authHeaders(creds, fetchImpl, secrets, sleep);
+  const json = await fetchOpenverseJson(url, { headers }, fetchImpl, secrets, sleep);
+  const license = asString(asRecord(json)?.license);
+  if (!isCc0OrPdm(license)) {
+    throw new PptwiseError(
+      `Openverse photo ${id} is licensed "${license ?? "unknown"}", not cc0/pdm \u2014 refusing to download`
+    );
+  }
+  const hit = parseHit(json);
+  if (!hit) throw new PptwiseError(`Openverse photo ${id} was not found`);
+  return hit;
+}
+
+// src/cli/ssrf.ts
+import { lookup as dnsLookup } from "dns/promises";
+import { isIP } from "net";
+import { Agent, fetch as undiciFetch } from "undici";
+async function defaultDnsLookup(hostname) {
+  return dnsLookup(hostname, { all: true, verbatim: true });
+}
+var BLOCKED_HOSTNAMES = /* @__PURE__ */ new Set([
+  "localhost",
+  "localhost.localdomain",
+  "metadata.google.internal",
+  "metadata.amazonaws.com",
+  "metadata.azure.internal"
+]);
+function isBlockedHostname(hostname) {
+  const normalized = hostname.trim().toLowerCase();
+  if (!normalized) return true;
+  if (BLOCKED_HOSTNAMES.has(normalized)) return true;
+  if (normalized.endsWith(".localhost")) return true;
+  return false;
+}
+function isPrivateIpAddress(ipAddress) {
+  const normalized = ipAddress.trim().toLowerCase();
+  const family = isIP(normalized);
+  if (family === 4) return isPrivateIPv4(normalized);
+  if (family === 6) return isPrivateIPv6(normalized);
+  return true;
+}
+async function assertSafeRemoteTarget(url, lookup) {
+  if (isBlockedHostname(url.hostname)) {
+    throw new Error(blockedMessage(url.hostname));
+  }
+  const hostname = stripIpv6Brackets(url.hostname);
+  const ipFamily = isIP(hostname);
+  if (ipFamily > 0) {
+    if (isPrivateIpAddress(hostname)) throw new Error(blockedMessage(hostname));
+    return { hostname, address: hostname, family: ipFamily };
+  }
+  if (!lookup) return { hostname, address: hostname, family: 0 };
+  let resolved;
+  try {
+    resolved = await lookup(hostname);
+  } catch (error) {
+    throw new Error(
+      `DNS lookup failed for host ${hostname}: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+  if (resolved.length === 0) {
+    throw new Error(`Host ${hostname} did not resolve to any IP address.`);
+  }
+  const blocked = resolved.find((record) => isPrivateIpAddress(record.address));
+  if (blocked) throw new Error(blockedMessage(`${hostname} -> ${blocked.address}`));
+  const [chosen] = resolved;
+  return { hostname, address: chosen.address, family: chosen.family };
+}
+async function pinnedFetch(url, pin, init) {
+  const dispatcher = new Agent({
+    connect: {
+      lookup: (_hostname, options, callback) => {
+        const record = { address: pin.address, family: pin.family };
+        if (options?.all) callback(null, [record]);
+        else callback(null, pin.address, pin.family);
+      }
+    }
+  });
+  try {
+    const response = await undiciFetch(url, {
+      ...init,
+      dispatcher
+    });
+    const buffered = Buffer.from(await response.arrayBuffer());
+    await dispatcher.close();
+    return new Response(buffered, {
+      status: response.status,
+      statusText: response.statusText,
+      headers: response.headers
+    });
+  } catch (error) {
+    await dispatcher.close().catch(() => {
+    });
+    throw error;
+  }
+}
+function blockedMessage(target) {
+  return `Blocked private or reserved download target: ${target}. pptwise does not download from private addresses.`;
+}
+function stripIpv6Brackets(hostname) {
+  if (hostname.startsWith("[") && hostname.endsWith("]")) return hostname.slice(1, -1);
+  return hostname;
+}
+function isPrivateIPv4(ipAddress) {
+  const octets = ipAddress.split(".").map((part) => Number.parseInt(part, 10));
+  if (octets.length !== 4 || octets.some((value2) => !Number.isFinite(value2) || value2 < 0 || value2 > 255)) {
+    return true;
+  }
+  const value = octets[0] * 256 ** 3 + octets[1] * 256 ** 2 + octets[2] * 256 + octets[3];
+  return inRange(value, "0.0.0.0", "0.255.255.255") || inRange(value, "10.0.0.0", "10.255.255.255") || inRange(value, "100.64.0.0", "100.127.255.255") || inRange(value, "127.0.0.0", "127.255.255.255") || inRange(value, "169.254.0.0", "169.254.255.255") || inRange(value, "172.16.0.0", "172.31.255.255") || inRange(value, "192.0.0.0", "192.0.0.255") || inRange(value, "192.168.0.0", "192.168.255.255") || inRange(value, "198.18.0.0", "198.19.255.255") || inRange(value, "224.0.0.0", "255.255.255.255");
+}
+function inRange(value, start, end) {
+  return value >= ipv4ToNumber(start) && value <= ipv4ToNumber(end);
+}
+function ipv4ToNumber(ipAddress) {
+  const octets = ipAddress.split(".").map((part) => Number.parseInt(part, 10));
+  return octets[0] * 256 ** 3 + octets[1] * 256 ** 2 + octets[2] * 256 + octets[3];
+}
+function isPrivateIPv6(ipAddress) {
+  const groups = expandIpv6(ipAddress);
+  if (groups !== null && hasMappedV4Prefix(groups)) {
+    const mapped2 = [groups[6] >> 8, groups[6] & 255, groups[7] >> 8, groups[7] & 255].join(".");
+    return isPrivateIPv4(mapped2);
+  }
+  const normalized = ipAddress.split("%")[0];
+  const mapped = extractMappedIpv4(normalized);
+  if (mapped && isPrivateIPv4(mapped)) return true;
+  const value = ipv6ToBigInt(normalized);
+  if (value === null) return true;
+  return inIpv6Range(value, "::", 128) || inIpv6Range(value, "::1", 128) || inIpv6Range(value, "fc00::", 7) || inIpv6Range(value, "fe80::", 10) || inIpv6Range(value, "ff00::", 8) || inIpv6Range(value, "2001:db8::", 32);
+}
+function hasMappedV4Prefix(groups) {
+  return groups.slice(0, 5).every((group) => group === 0) && groups[5] === 65535;
+}
+function extractMappedIpv4(ipAddress) {
+  const lower = ipAddress.toLowerCase();
+  const marker = "::ffff:";
+  if (!lower.startsWith(marker)) return null;
+  const candidate = lower.slice(marker.length);
+  return isIP(candidate) === 4 ? candidate : null;
+}
+function inIpv6Range(value, start, prefixLength) {
+  const startValue = ipv6ToBigInt(start);
+  if (startValue === null) return false;
+  const mask = prefixLength === 0 ? 0n : (1n << BigInt(prefixLength)) - 1n << BigInt(128 - prefixLength);
+  return (value & mask) === (startValue & mask);
+}
+function ipv6ToBigInt(ipAddress) {
+  const expanded = expandIpv6(ipAddress);
+  if (!expanded) return null;
+  return expanded.reduce((acc, group) => (acc << 16n) + BigInt(group), 0n);
+}
+function expandIpv6(ipAddress) {
+  const value = ipAddress.toLowerCase();
+  if (value.includes("::")) {
+    const [left, right] = value.split("::");
+    const leftGroups = left ? left.split(":").filter(Boolean) : [];
+    const rightGroups = right ? right.split(":").filter(Boolean) : [];
+    if (leftGroups.length + rightGroups.length > 8) return null;
+    const middle = new Array(8 - leftGroups.length - rightGroups.length).fill("0");
+    return parseIpv6Groups([...leftGroups, ...middle, ...rightGroups]);
+  }
+  return parseIpv6Groups(value.split(":"));
+}
+function parseIpv6Groups(groups) {
+  if (groups.length !== 8) return null;
+  const parsed = groups.map((group) => Number.parseInt(group || "0", 16));
+  if (parsed.some((value) => !Number.isFinite(value) || value < 0 || value > 65535)) return null;
+  return parsed;
+}
+
+// src/cli/images.ts
+var BYTE_CAP = 15 * 1024 * 1024;
+var MAX_LONG_EDGE = 1920;
+var PER_PAGE = 8;
+function userAgent2() {
+  return `pptwise/${VERSION} (+https://pptwise.com)`;
+}
+function asRecord2(value) {
+  if (typeof value === "object" && value !== null && !Array.isArray(value)) {
+    return value;
+  }
+  return null;
+}
+function asString2(value) {
+  return typeof value === "string" && value !== "" ? value : void 0;
+}
+function asNumber2(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+async function loadKeys(env) {
+  const hit = await findUserConfig();
+  return resolveImageKeys({ file: hit?.config ?? null, env });
+}
+async function fetchJson(url, init, fetchImpl, secrets) {
+  let res;
+  try {
+    res = await fetchImpl(url, init);
+  } catch (e) {
+    throw new PptwiseError(
+      redactSecrets(`stock image request failed: ${e instanceof Error ? e.message : String(e)}`, secrets)
+    );
+  }
+  const text = await res.text();
+  const redacted = redactSecrets(text.slice(0, 800), secrets);
+  if (!res.ok) {
+    if (res.status === 429) {
+      throw new PptwiseError(`stock image API rate-limited (HTTP 429): ${redacted}`);
+    }
+    throw new PptwiseError(`stock image API HTTP ${res.status}: ${redacted}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new PptwiseError(`stock image API returned non-JSON (HTTP ${res.status})`);
+  }
+}
+function pexelsHeaders(apiKey) {
+  return { Authorization: apiKey, "User-Agent": userAgent2() };
+}
+var ORIENTATIONS = /* @__PURE__ */ new Set(["landscape", "portrait", "square"]);
+function parseOrientation(raw) {
+  if (raw === void 0 || raw === "") return void 0;
+  if (!ORIENTATIONS.has(raw)) {
+    throw new PptwiseError(`invalid --orientation "${raw}" \u2014 expected landscape, portrait, or square`);
+  }
+  return raw;
+}
+function clientFilter(hits, minWidth, minHeight) {
+  return hits.filter((hit) => {
+    if (minWidth !== void 0 && hit.width < minWidth) return false;
+    if (minHeight !== void 0 && hit.height < minHeight) return false;
+    return true;
+  });
+}
+function parsePexelsPhotos(json) {
+  const root = asRecord2(json);
+  const photos = Array.isArray(root?.photos) ? root.photos : [];
+  const hits = [];
+  for (const raw of photos) {
+    const photo = asRecord2(raw);
+    if (!photo) continue;
+    const id = photo.id;
+    const photoId = typeof id === "number" || typeof id === "string" ? String(id) : "";
+    if (!photoId) continue;
+    const src = asRecord2(photo.src) ?? {};
+    const author = asString2(photo.photographer) ?? "unknown";
+    const pageUrl = asString2(photo.url) ?? `https://www.pexels.com/photo/${photoId}/`;
+    hits.push({
+      id: `pexels:${photoId}`,
+      provider: "pexels",
+      photoId,
+      thumb: asString2(src.medium) ?? asString2(src.tiny) ?? "",
+      width: asNumber2(photo.width) ?? 0,
+      height: asNumber2(photo.height) ?? 0,
+      author,
+      license: "Pexels License",
+      pageUrl,
+      attribution: `Photo by ${author} on Pexels`
+    });
+  }
+  return hits.slice(0, PER_PAGE);
+}
+function parsePixabayHits(json) {
+  const root = asRecord2(json);
+  const list = Array.isArray(root?.hits) ? root.hits : [];
+  const hits = [];
+  for (const raw of list) {
+    const photo = asRecord2(raw);
+    if (!photo) continue;
+    const photoId = photo.id !== void 0 ? String(photo.id) : "";
+    if (!photoId) continue;
+    const author = asString2(photo.user) ?? "unknown";
+    const pageUrl = asString2(photo.pageURL) ?? `https://pixabay.com/photos/${photoId}/`;
+    hits.push({
+      id: `pixabay:${photoId}`,
+      provider: "pixabay",
+      photoId,
+      thumb: asString2(photo.previewURL) ?? "",
+      width: asNumber2(photo.imageWidth) ?? 0,
+      height: asNumber2(photo.imageHeight) ?? 0,
+      author,
+      license: "Pixabay License",
+      pageUrl,
+      attribution: `Photo by ${author} on Pixabay`
+    });
+  }
+  return hits.slice(0, PER_PAGE);
+}
+async function searchPexels(query, apiKey, opts, fetchImpl, secrets) {
+  const url = new URL("https://api.pexels.com/v1/search");
+  url.searchParams.set("query", query);
+  url.searchParams.set("locale", "zh-CN");
+  url.searchParams.set("per_page", String(PER_PAGE));
+  const orientation = parseOrientation(opts.orientation);
+  if (orientation) url.searchParams.set("orientation", orientation);
+  if (opts.color) url.searchParams.set("color", opts.color);
+  const json = await fetchJson(url.toString(), { headers: pexelsHeaders(apiKey) }, fetchImpl, secrets);
+  return clientFilter(parsePexelsPhotos(json), opts.minWidth, opts.minHeight);
+}
+function pixabayOrientation(orientation) {
+  if (orientation === "landscape") return "horizontal";
+  if (orientation === "portrait") return "vertical";
+  return void 0;
+}
+async function searchPixabay(query, apiKey, opts, fetchImpl, secrets) {
+  const url = new URL("https://pixabay.com/api/");
+  url.searchParams.set("key", apiKey);
+  url.searchParams.set("q", query.slice(0, 100));
+  url.searchParams.set("lang", "zh");
+  url.searchParams.set("per_page", String(PER_PAGE));
+  url.searchParams.set("safesearch", "true");
+  const mapped = pixabayOrientation(parseOrientation(opts.orientation));
+  if (mapped) url.searchParams.set("orientation", mapped);
+  if (opts.color) url.searchParams.set("colors", opts.color);
+  if (opts.minWidth !== void 0) url.searchParams.set("min_width", String(opts.minWidth));
+  if (opts.minHeight !== void 0) url.searchParams.set("min_height", String(opts.minHeight));
+  const json = await fetchJson(url.toString(), { headers: { "User-Agent": userAgent2() } }, fetchImpl, secrets);
+  return parsePixabayHits(json);
+}
+function formatHits(hits) {
+  return hits.map((hit) => {
+    const thumb = hit.thumb ? `
+  ${hit.thumb}` : "";
+    const source = hit.source ? `  ${hit.source}` : "";
+    return `${hit.id}  ${hit.width}x${hit.height}  ${hit.author}  ${hit.license}${source}${thumb}
+  ${hit.attribution}
+  ${hit.pageUrl}`;
+  }).join("\n");
+}
+function openverseNotes(anonymous, pixabaySkipped) {
+  const lines = ["Openverse does not verify individual licenses. Results are filtered to cc0/pdm."];
+  if (anonymous) {
+    lines.push(
+      "Anonymous Openverse quota is very low. Set credentials with `pptwise config set openverse.clientId` and `pptwise config set openverse.clientSecret`."
+    );
+  }
+  if (pixabaySkipped) {
+    lines.push("Pixabay is unconfigured \u2014 pptwise config set pixabay.apiKey");
+  }
+  return lines;
+}
+async function runImagesSearch(query, opts = {}) {
+  const q = query.trim();
+  if (q === "") throw new PptwiseError("search query must not be empty");
+  const env = opts.env ?? process.env;
+  const keys = await loadKeys(env);
+  const secrets = knownSecretsFrom(keys);
+  const fetchImpl = opts.fetch ?? proxyFetch;
+  const sleep = opts.sleep ?? defaultSleep;
+  if (keys.pexels.apiKey) {
+    const pexelsHits = await searchPexels(q, keys.pexels.apiKey, opts, fetchImpl, secrets);
+    if (pexelsHits.length > 0) return formatHits(pexelsHits);
+  }
+  if (keys.pixabay.apiKey) {
+    const pixabayHits = await searchPixabay(q, keys.pixabay.apiKey, opts, fetchImpl, secrets);
+    if (pixabayHits.length > 0) return formatHits(pixabayHits);
+  }
+  const orientation = parseOrientation(opts.orientation);
+  const ovHits = await searchOpenverse({
+    query: q,
+    orientation,
+    minWidth: opts.minWidth,
+    minHeight: opts.minHeight,
+    clientId: keys.openverse.ready ? keys.openverse.clientId : void 0,
+    clientSecret: keys.openverse.ready ? keys.openverse.clientSecret : void 0,
+    fetch: fetchImpl,
+    secrets,
+    sleep
+  });
+  const notes = openverseNotes(!keys.openverse.ready, !keys.pixabay.apiKey);
+  if (ovHits.length === 0) {
+    return ["No photos found.", ...notes].join("\n");
+  }
+  const hits = ovHits.map((hit) => ({
+    id: `openverse:${hit.id}`,
+    provider: "openverse",
+    photoId: hit.id,
+    thumb: hit.thumbnail,
+    width: hit.width,
+    height: hit.height,
+    author: hit.creator,
+    license: hit.license,
+    pageUrl: hit.foreignLandingUrl,
+    attribution: hit.attribution,
+    source: hit.source
+  }));
+  return [...notes, formatHits(hits)].join("\n");
+}
+function parsePhotoRef(ref) {
+  const m = /^(pexels|pixabay|openverse):(.+)$/.exec(ref.trim());
+  if (!m) {
+    throw new PptwiseError(`invalid photo ref "${ref}" \u2014 expected pexels:<id>, pixabay:<id>, or openverse:<id>`);
+  }
+  const photoId = m[2].trim();
+  if (photoId === "" || photoId.includes("/") || photoId.includes("\\") || photoId.includes("..")) {
+    throw new PptwiseError(`invalid photo id in "${ref}"`);
+  }
+  return { provider: m[1], photoId };
+}
+async function resolveDeckWorkspace(deckArg, cwd) {
+  const [projectHit, userHit] = await Promise.all([findConfig(cwd), findUserConfig()]);
+  const decksDirSource = projectHit?.config.decksDir !== void 0 ? { decksDir: resolve7(dirname4(projectHit.path), projectHit.config.decksDir) } : userHit?.config;
+  const target = await resolveDeckTarget(deckArg, decksDirSource, cwd);
+  const isDir = await isDeckDirectory(target);
+  const location = resolveWorkspaceLocation({
+    cwd,
+    projectConfigPath: projectHit?.path,
+    outDir: projectHit?.config.outDir,
+    target,
+    isDir
+  });
+  return { location, assetsDir: join8(location.dir, ASSETS_DIRNAME) };
+}
+function assertSafeDownloadUrl(url) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new PptwiseError("invalid download URL");
+  }
+  if (parsed.protocol !== "https:") {
+    throw new PptwiseError("refusing non-HTTPS download URL");
+  }
+  if (parsed.username !== "" || parsed.password !== "") {
+    throw new PptwiseError("refusing download URL with embedded userinfo");
+  }
+  return parsed;
+}
+async function downloadBytes(url, fetchImpl, secrets, lookup) {
+  const parsed = assertSafeDownloadUrl(url);
+  let pin;
+  try {
+    pin = await assertSafeRemoteTarget(parsed, lookup);
+  } catch (e) {
+    throw new PptwiseError(redactSecrets(e instanceof Error ? e.message : String(e), secrets));
+  }
+  let res;
+  try {
+    const init = { headers: { "User-Agent": userAgent2() } };
+    res = fetchImpl ? await fetchImpl(parsed.toString(), init) : await pinnedFetch(parsed, pin, init);
+  } catch (e) {
+    throw new PptwiseError(
+      redactSecrets(`download failed: ${e instanceof Error ? e.message : String(e)}`, secrets)
+    );
+  }
+  if (!res.ok) {
+    throw new PptwiseError(`download HTTP ${res.status}`);
+  }
+  const declared = Number(res.headers.get("content-length") ?? "0");
+  if (declared > BYTE_CAP) {
+    throw new PptwiseError(`download exceeds the ${BYTE_CAP} byte cap`);
+  }
+  const buf = Buffer.from(await res.arrayBuffer());
+  if (buf.byteLength > BYTE_CAP) {
+    throw new PptwiseError(`download exceeds the ${BYTE_CAP} byte cap`);
+  }
+  return buf;
+}
+async function defaultResizeToJpeg(bytes, maxLongEdge) {
+  let sharpMod;
+  try {
+    sharpMod = (await import("sharp")).default;
+  } catch (e) {
+    if (isMissingModuleError(e)) {
+      throw new PptwiseError(`Resizing stock photos requires the optional dependency "sharp" (npm i sharp)`);
+    }
+    throw e;
+  }
+  const image = sharpMod(bytes);
+  const meta = await image.metadata();
+  const width = meta.width ?? 0;
+  const height = meta.height ?? 0;
+  const long = Math.max(width, height);
+  const pipeline = long > maxLongEdge ? width >= height ? image.resize({ width: maxLongEdge }) : image.resize({ height: maxLongEdge }) : image;
+  return pipeline.jpeg({ quality: 85 }).toBuffer();
+}
+async function toJpeg(bytes, apiLongEdge, resize) {
+  const format = sniffImageFormat(bytes);
+  if (format === null) {
+    throw new PptwiseError("downloaded bytes are not a recognized image (png/jpeg/gif/webp)");
+  }
+  if (format === "jpeg" && apiLongEdge !== void 0 && apiLongEdge <= MAX_LONG_EDGE) {
+    return bytes;
+  }
+  return resize(bytes, MAX_LONG_EDGE);
+}
+async function loadPexelsPhoto(photoId, apiKey, fetchImpl, secrets) {
+  const url = `https://api.pexels.com/v1/photos/${encodeURIComponent(photoId)}`;
+  const json = await fetchJson(url, { headers: pexelsHeaders(apiKey) }, fetchImpl, secrets);
+  const photo = asRecord2(json);
+  if (!photo) throw new PptwiseError(`Pexels photo ${photoId} was not found`);
+  const src = asRecord2(photo.src) ?? {};
+  const original = asString2(src.original);
+  const large2x = asString2(src.large2x);
+  const downloadUrl = original ?? large2x;
+  if (!downloadUrl) throw new PptwiseError(`Pexels photo ${photoId} has no download URL`);
+  const author = asString2(photo.photographer) ?? "unknown";
+  return {
+    author,
+    pageUrl: asString2(photo.url) ?? `https://www.pexels.com/photo/${photoId}/`,
+    license: "Pexels License",
+    downloadUrl,
+    fallbackUrl: original ? large2x : void 0,
+    width: asNumber2(photo.width),
+    height: asNumber2(photo.height)
+  };
+}
+async function loadPixabayPhoto(photoId, apiKey, fetchImpl, secrets) {
+  const url = new URL("https://pixabay.com/api/");
+  url.searchParams.set("key", apiKey);
+  url.searchParams.set("id", photoId);
+  const json = await fetchJson(url.toString(), { headers: { "User-Agent": userAgent2() } }, fetchImpl, secrets);
+  const hits = parsePixabayHits(json);
+  const hit = hits[0];
+  const root = asRecord2(json);
+  const rawHits = Array.isArray(root?.hits) ? root.hits : [];
+  const raw = asRecord2(rawHits[0]);
+  const downloadUrl = asString2(raw?.largeImageURL);
+  if (!hit || !downloadUrl) throw new PptwiseError(`Pixabay photo ${photoId} was not found`);
+  return {
+    author: hit.author,
+    pageUrl: hit.pageUrl,
+    license: "Pixabay License",
+    downloadUrl,
+    width: hit.width,
+    height: hit.height
+  };
+}
+async function readSidecar(path2) {
+  try {
+    const raw = JSON.parse(await readFile8(path2, "utf8"));
+    const rec = asRecord2(raw);
+    if (!rec) return null;
+    const provider = asString2(rec.provider);
+    const known = provider === "pexels" || provider === "pixabay" || provider === "openverse" || provider === "grok" || provider === "codex" || provider === "antigravity";
+    if (!known || !provider) return null;
+    const photoId = asString2(rec.photo_id);
+    if ((provider === "pexels" || provider === "pixabay") && !photoId) return null;
+    return {
+      provider,
+      photo_id: photoId,
+      license: asString2(rec.license) ?? "",
+      author: asString2(rec.author),
+      page_url: asString2(rec.page_url),
+      attribution: asString2(rec.attribution),
+      source: asString2(rec.source),
+      query: asString2(rec.query),
+      prompt: asString2(rec.prompt),
+      downloaded_at: asString2(rec.downloaded_at),
+      generated_at: asString2(rec.generated_at)
+    };
+  } catch {
+    return null;
+  }
+}
+async function runImagesFetch(ref, opts) {
+  const { provider, photoId } = parsePhotoRef(ref);
+  assertSafeFileSegment(opts.as, "asset id");
+  const cwd = opts.cwd ?? process.cwd();
+  const env = opts.env ?? process.env;
+  const keys = await loadKeys(env);
+  const secrets = knownSecretsFrom(keys);
+  if (provider !== "openverse") {
+    const apiKey = keys[provider].apiKey;
+    if (!apiKey) throw missingKeysError(provider);
+  }
+  const { assetsDir } = await resolveDeckWorkspace(opts.deck, cwd);
+  const jpgPath = join8(assetsDir, `${opts.as}.jpg`);
+  const jsonPath = join8(assetsDir, `${opts.as}.json`);
+  if (await pathExists(jpgPath) && await pathExists(jsonPath)) {
+    const existing = await readSidecar(jsonPath);
+    if (existing && existing.photo_id === photoId && existing.provider === provider) {
+      return `already pinned ${provider}:${photoId} as ${opts.as} \u2014 skipped`;
+    }
+  }
+  const fetchImpl = opts.fetch ?? proxyFetch;
+  const sleep = opts.sleep ?? defaultSleep;
+  const downloadFetch = opts.fetch;
+  const lookup = opts.lookup ?? (opts.fetch ? void 0 : defaultDnsLookup);
+  let meta;
+  if (provider === "openverse") {
+    const hit = await loadOpenverseDetail(
+      photoId,
+      {
+        clientId: keys.openverse.ready ? keys.openverse.clientId : void 0,
+        clientSecret: keys.openverse.ready ? keys.openverse.clientSecret : void 0
+      },
+      fetchImpl,
+      secrets,
+      sleep
+    );
+    meta = {
+      author: hit.creator,
+      pageUrl: hit.foreignLandingUrl,
+      license: hit.license,
+      downloadUrl: hit.url,
+      width: hit.width,
+      height: hit.height,
+      attribution: hit.attribution,
+      source: hit.source
+    };
+  } else {
+    const apiKey = keys[provider].apiKey;
+    meta = provider === "pexels" ? await loadPexelsPhoto(photoId, apiKey, fetchImpl, secrets) : await loadPixabayPhoto(photoId, apiKey, fetchImpl, secrets);
+  }
+  let bytes;
+  try {
+    bytes = await downloadBytes(meta.downloadUrl, downloadFetch, secrets, lookup);
+  } catch (e) {
+    if (meta.fallbackUrl) {
+      bytes = await downloadBytes(meta.fallbackUrl, downloadFetch, secrets, lookup);
+    } else {
+      throw e;
+    }
+  }
+  const apiLong = meta.width !== void 0 && meta.height !== void 0 ? Math.max(meta.width, meta.height) : void 0;
+  const resize = opts.resizeToJpeg ?? defaultResizeToJpeg;
+  const jpeg = await toJpeg(bytes, apiLong, resize);
+  await mkdir5(assetsDir, { recursive: true });
+  await writeFile4(jpgPath, jpeg);
+  const sidecar = {
+    provider,
+    photo_id: photoId,
+    license: meta.license,
+    author: meta.author,
+    page_url: meta.pageUrl,
+    downloaded_at: (opts.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+  };
+  if (opts.query) sidecar.query = opts.query;
+  if (meta.attribution) sidecar.attribution = meta.attribution;
+  if (meta.source) sidecar.source = meta.source;
+  const json = JSON.stringify(sidecar, null, 2) + "\n";
+  if (/"apiKey"\s*:/.test(json) || /"key"\s*:/.test(json) || /"clientSecret"\s*:/.test(json)) {
+    throw new PptwiseError("internal error: sidecar would have contained a key field");
+  }
+  await writeFile4(jsonPath, json);
+  return `pinned ${provider}:${photoId} as ${opts.as} \u2192 ${jpgPath}`;
+}
+async function runImagesList(opts) {
+  const cwd = opts.cwd ?? process.cwd();
+  const { assetsDir } = await resolveDeckWorkspace(opts.deck, cwd);
+  let names;
+  try {
+    names = (await readdir6(assetsDir)).filter((n) => n.endsWith(".json") && !n.startsWith(".")).sort();
+  } catch (e) {
+    if (e.code === "ENOENT") return "No pinned stock photos.";
+    throw e;
+  }
+  const lines = [];
+  for (const name of names) {
+    const sidecar = await readSidecar(join8(assetsDir, name));
+    if (!sidecar) continue;
+    const assetId = name.slice(0, -".json".length);
+    const id = sidecar.photo_id ? `${sidecar.provider}:${sidecar.photo_id}` : sidecar.provider;
+    const rest = [sidecar.author, sidecar.license, sidecar.page_url ?? sidecar.generated_at].filter(Boolean);
+    lines.push(`${assetId}  ${id}  ${rest.join("  ")}`);
+  }
+  return lines.length === 0 ? "No pinned stock photos." : lines.join("\n");
+}
+async function writePinnedAsset(assetsDir, assetId, jpeg, sidecar) {
+  await mkdir5(assetsDir, { recursive: true });
+  const jpgPath = join8(assetsDir, `${assetId}.jpg`);
+  const jsonPath = join8(assetsDir, `${assetId}.json`);
+  const tmpJpg = join8(assetsDir, `.${assetId}.jpg.tmp`);
+  const tmpJson = join8(assetsDir, `.${assetId}.json.tmp`);
+  const json = JSON.stringify(sidecar, null, 2) + "\n";
+  if (/"apiKey"\s*:/.test(json) || /"key"\s*:/.test(json) || /"clientSecret"\s*:/.test(json)) {
+    throw new PptwiseError("internal error: sidecar would have contained a key field");
+  }
+  try {
+    await writeFile4(tmpJpg, jpeg);
+    await writeFile4(tmpJson, json);
+    await rename(tmpJpg, jpgPath);
+    await rename(tmpJson, jsonPath);
+  } catch (e) {
+    await unlink2(tmpJpg).catch(() => void 0);
+    await unlink2(tmpJson).catch(() => void 0);
+    await unlink2(jpgPath).catch(() => void 0);
+    throw e;
+  }
+  return jpgPath;
+}
+async function defaultResolvePrompt(opts) {
+  const ir = await loadValidatedDeckIr(opts.deck, opts.cwd);
+  const brief = buildAssetBrief(ir);
+  const item = brief.items.find((entry) => entry.asset_id === opts.as && entry.suggested_prompt.trim() !== "");
+  return item?.suggested_prompt;
+}
+async function runImagesGenerate(opts) {
+  assertSafeFileSegment(opts.as, "asset id");
+  const cwd = opts.cwd ?? process.cwd();
+  const env = opts.env ?? process.env;
+  const hit = await findUserConfig();
+  const gens = resolveGenerators({ file: hit?.config ?? null });
+  const fromFlag = opts.prompt?.trim();
+  const prompt = fromFlag && fromFlag !== "" ? fromFlag : await (opts.resolvePrompt ?? defaultResolvePrompt)({ deck: opts.deck, as: opts.as, cwd });
+  if (!prompt) {
+    throw new PptwiseError(`no prompt for asset "${opts.as}" \u2014 pass --prompt`);
+  }
+  const bins = {};
+  for (const id of GENERATOR_IDS) {
+    bins[id] = await locateGeneratorBin(id, env);
+  }
+  const anyEnabled = GENERATOR_IDS.some((id) => gens.enabled[id]);
+  if (!anyEnabled) {
+    const foundDisabled = GENERATOR_IDS.filter((id) => bins[id] !== null);
+    if (foundDisabled.length === 0) {
+      throw new PptwiseError(
+        "No image generator is enabled. Looked for grok, codex, antigravity. None were found on PATH."
+      );
+    }
+    const listed = foundDisabled.map((id) => `${id} \u2014 pptwise config set images.generators.${id}.enabled true`).join("; ");
+    throw new PptwiseError(`No image generator is enabled. Found but disabled: ${listed}`);
+  }
+  const { assetsDir } = await resolveDeckWorkspace(opts.deck, cwd);
+  const workdir = await mkdtemp(join8(tmpdir(), "pptwise-gen-"));
+  const dest = join8(workdir, "generated.jpg");
+  const run = opts.run ?? defaultProcessRunner;
+  const attempts = [];
+  try {
+    for (const id of gens.order) {
+      if (!gens.enabled[id]) continue;
+      const bin = bins[id];
+      if (!bin) continue;
+      try {
+        await GENERATOR_ADAPTERS[id]({
+          bin,
+          workdir,
+          dest,
+          prompt,
+          timeoutMs: gens.timeoutMs,
+          run
+        });
+        const bytes = await readFile8(dest);
+        if (sniffImageFormat(bytes) === null) {
+          throw new PptwiseError("produced bytes that are not a recognized image");
+        }
+        const resize = opts.resizeToJpeg ?? defaultResizeToJpeg;
+        const jpeg = await toJpeg(bytes, void 0, resize);
+        const sidecar = {
+          provider: id,
+          license: "user-generated",
+          prompt,
+          generated_at: (opts.now ?? (() => /* @__PURE__ */ new Date()))().toISOString()
+        };
+        const pinned = await writePinnedAsset(assetsDir, opts.as, jpeg, sidecar);
+        return `pinned ${id} as ${opts.as} \u2192 ${pinned}`;
+      } catch (e) {
+        attempts.push(`${id}: ${e instanceof Error ? e.message : String(e)}`);
+      }
+    }
+    if (attempts.length === 0) {
+      throw new PptwiseError(
+        "No enabled image generator was found on PATH. Looked for grok, codex, antigravity."
+      );
+    }
+    throw new PptwiseError(`All image generators failed: ${attempts.join("; ")}`);
+  } finally {
+    await rm2(workdir, { recursive: true, force: true });
+  }
+}
+
+// src/cli/serve.ts
+import { watch } from "fs";
+import { createServer } from "http";
+import { platform as osPlatform } from "os";
+import { join as join9 } from "path";
+var DEFAULT_PORT = 4400;
+var DEBOUNCE_MS = 200;
+var HEARTBEAT_MS = 3e4;
+function watchRoots(resolvedTarget, isDir, extra = []) {
+  const roots = isDir ? [join9(resolvedTarget, SPEC_FILENAME), join9(resolvedTarget, PAGES_DIRNAME), join9(resolvedTarget, ASSETS_DIRNAME)] : [resolvedTarget];
+  return [...roots, ...extra];
+}
+var SERVE_CLIENT_SCRIPT_ID = "pptwise-serve-client";
+var SERVE_CLIENT_JS = `
+(function () {
+  // Live reload is the whole of this client (the revision-request submit
+  // that used to sit beside it was removed on 2026-08-16 \u2014 see this
+  // module's own header). It keeps its own function and its own try/catch
+  // at the call site below: an EventSource construction that throws in some
+  // unusual embedding must degrade to a page that simply does not
+  // auto-refresh, not abort the IIFE.
+
+  function setUpLiveReload() {
+    var es = new EventSource('/events')
+    es.addEventListener('reload', function () { location.reload() })
+
+    var banner = document.createElement('div')
+    banner.id = 'pptwise-serve-error-banner'
+    banner.setAttribute('role', 'alert')
+    banner.style.cssText =
+      'display:none;position:fixed;top:0;left:0;right:0;z-index:2147483647;' +
+      'background:#dc2626;color:#fff;font:13px/1.4 -apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;' +
+      'padding:8px 16px;text-align:center'
+    document.body.appendChild(banner)
+
+    function showBanner(message) {
+      banner.textContent = 'pptwise serve: ' + message
+      banner.style.display = 'block'
+    }
+
+    es.addEventListener('error', function (e) {
+      if (!e || typeof e.data !== 'string') return // a real connection hiccup, not the server's own rebuild-failed frame
+      var message = 'rebuild failed'
+      try {
+        var parsed = JSON.parse(e.data)
+        if (parsed && typeof parsed.message === 'string') message = parsed.message
+      } catch (err) {}
+      showBanner(message)
+    })
+  }
+
+  try {
+    setUpLiveReload()
+  } catch (e) {
+    console.error('pptwise serve: failed to set up live reload', e)
+  }
+})()
+`.trim();
+function buildServeClientScriptTag() {
+  return `<script id="${SERVE_CLIENT_SCRIPT_ID}">${SERVE_CLIENT_JS}</script>`;
+}
+function injectServeClient(html) {
+  if (html.includes(SERVE_CLIENT_SCRIPT_ID)) return html;
+  return html.replace("</body>", `${buildServeClientScriptTag()}
+</body>`);
+}
+async function createServeServer(options) {
+  const cwd = options.cwd ?? process.cwd();
+  const requestedPort = options.port ?? DEFAULT_PORT;
+  if (!Number.isInteger(requestedPort) || requestedPort < 0 || requestedPort > 65535) {
+    throw new PptwiseError(`invalid port ${requestedPort} \u2014 expected an integer between 0 and 65535`);
+  }
+  const initial = await buildDeckPreview(options.target, { cwd, themeFilePath: options.themeFilePath });
+  let cachedHtml = injectServeClient(initial.html);
+  const sseClients = /* @__PURE__ */ new Set();
+  function writeToAll(chunk) {
+    for (const res of sseClients) {
+      try {
+        res.write(chunk);
+      } catch {
+      }
+    }
+  }
+  function broadcast(event, data) {
+    writeToAll(`event: ${event}
+data: ${JSON.stringify(data)}
+
+`);
+  }
+  async function rebuild() {
+    try {
+      const result = await buildDeckPreview(options.target, { cwd, themeFilePath: options.themeFilePath });
+      cachedHtml = injectServeClient(result.html);
+      broadcast("reload", {});
+    } catch (e) {
+      broadcast("error", { message: e instanceof Error ? e.message : String(e) });
+    }
+  }
+  const server = createServer((req, res) => {
+    const pathname = (req.url ?? "/").split("?")[0];
+    if (req.method === "GET" && pathname === "/") {
+      res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+      res.end(cachedHtml);
+      return;
+    }
+    if (req.method === "GET" && pathname === "/events") {
+      res.writeHead(200, {
+        "Content-Type": "text/event-stream",
+        "Cache-Control": "no-cache, no-transform",
+        Connection: "keep-alive"
+      });
+      res.write("retry: 2000\n\n");
+      sseClients.add(res);
+      res.on("close", () => sseClients.delete(res));
+      res.on("error", () => sseClients.delete(res));
+      return;
+    }
+    res.writeHead(404, { "Content-Type": "text/plain; charset=utf-8" });
+    res.end("not found");
+  });
+  const heartbeat = setInterval(() => writeToAll(": heartbeat\n\n"), HEARTBEAT_MS);
+  let debounceTimer;
+  function scheduleRebuild() {
+    if (debounceTimer) clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+      debounceTimer = void 0;
+      void rebuild();
+    }, DEBOUNCE_MS);
+  }
+  const projectHit = await findConfig(cwd);
+  const workspaceAssets = join9(
+    resolveWorkspaceLocation({
+      cwd,
+      projectConfigPath: projectHit?.path,
+      outDir: projectHit?.config.outDir,
+      target: initial.resolvedTarget,
+      isDir: initial.isDir
+    }).dir,
+    ASSETS_DIRNAME
+  );
+  const watchers = [];
+  for (const path2 of watchRoots(initial.resolvedTarget, initial.isDir, [workspaceAssets])) {
+    try {
+      watchers.push(watch(path2, () => scheduleRebuild()));
+    } catch (e) {
+      if (e.code !== "ENOENT") throw e;
+    }
+  }
+  function teardownWatchersAndTimers() {
+    clearInterval(heartbeat);
+    if (debounceTimer) clearTimeout(debounceTimer);
+    for (const w of watchers) w.close();
+  }
+  try {
+    await new Promise((resolveListen, rejectListen) => {
+      const onError = (err) => {
+        server.removeListener("listening", onListening);
+        rejectListen(err);
+      };
+      const onListening = () => {
+        server.removeListener("error", onError);
+        resolveListen();
+      };
+      server.once("error", onError);
+      server.once("listening", onListening);
+      server.listen(requestedPort, "127.0.0.1");
+    });
+  } catch (e) {
+    teardownWatchersAndTimers();
+    if (e.code === "EADDRINUSE") {
+      throw new PptwiseError(`port ${requestedPort} is already in use \u2014 pick a different one with --port`);
+    }
+    throw e;
+  }
+  const address = server.address();
+  const actualPort = typeof address === "object" && address !== null ? address.port : requestedPort;
+  let closed = false;
+  async function close() {
+    if (closed) return;
+    closed = true;
+    teardownWatchersAndTimers();
+    for (const res of sseClients) res.end();
+    sseClients.clear();
+    if (typeof server.closeIdleConnections === "function") server.closeIdleConnections();
+    if (typeof server.closeAllConnections === "function") server.closeAllConnections();
+    await new Promise((resolveClose, rejectClose) => {
+      server.close((err) => err ? rejectClose(err) : resolveClose());
+    });
+  }
+  return { server, rebuild, close, url: `http://127.0.0.1:${actualPort}`, port: actualPort };
+}
+function openBrowser(url) {
+  const command = osPlatform() === "darwin" ? "open" : "xdg-open";
+  try {
+    const child = spawnHidden(command, [url], { stdio: "ignore", detached: true });
+    child.on("error", () => {
+    });
+    child.unref();
+  } catch {
+  }
+}
+async function runServe(target, opts = {}) {
+  const handle = await createServeServer({ target, port: opts.port, cwd: opts.cwd, themeFilePath: opts.themeFilePath });
+  console.log(`pptwise serve: ${handle.url} (Ctrl+C to stop)`);
+  if (opts.open !== false) openBrowser(handle.url);
+  process.on("SIGINT", () => {
+    void handle.close().then(
+      () => process.exit(0),
+      () => process.exit(1)
+    );
+  });
+}
+
+// src/cli.ts
+installNodePlatform();
+var program = new Command();
+program.name("pptwise").description("Stable, editable PPTX generation for AI agents \u2014 semantic IR in, native DrawingML out").version(VERSION);
+function fail(e) {
+  console.error(e instanceof Error ? e.message : String(e));
+  process.exit(1);
+}
+program.command("render").description("Render an IR JSON file, deck project directory, or bare deck name to a .pptx").argument("<target>", "IR JSON file, deck project directory, or bare name under ~/.pptwise/decks").option("-o, --output <file>", "output .pptx path (default: .pptwise/<deck>/<deck>.pptx under the project root)").option("--theme <id>", "override the deck theme (see `pptwise themes`)").option("--theme-file <path>", "load a custom theme file (see `pptwise brand extract`) and render with it").option("--style <path>", "style overrides JSON re-coloring the theme (see `pptwise schema --style`)").option("--draft", "allow unfilled placeholder pages (skip the draft gate)").option(
+  "--allow-dropped-content",
+  "export anyway when a page holds more than fits and the layout drops blocks (skip the content-drop gate)"
+).option("--no-git-ignore", "do not add .pptwise/ to this repository's local exclude file").action(
+  async (target, opts) => {
+    try {
+      console.log(
+        await runRender(target, {
+          output: opts.output,
+          theme: opts.theme,
+          themeFilePath: opts.themeFile,
+          stylePath: opts.style,
+          draft: opts.draft,
+          allowDroppedContent: opts.allowDroppedContent,
+          gitIgnore: opts.gitIgnore,
+          cwd: process.cwd()
+        })
+      );
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
+program.command("validate").description("Validate an IR JSON file, deck project directory, or bare deck name against the schema").argument("<target>", "IR JSON file, deck project directory, or bare name under ~/.pptwise/decks").option("--theme-file <path>", "load a custom theme file (see `pptwise brand extract`) before validating").action(async (target, opts) => {
+  try {
+    console.log(await runValidate(target, process.cwd(), { themeFilePath: opts.themeFile }));
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("audit").description(
+  "Deterministic geometry audit (overflow, out-of-bounds, low-contrast, overlap, content-truncated, content-dropped), plus an optional --pixels contrast pass \u2014 exits 1 when it finds anything"
+).argument("<target>", "IR JSON file, deck project directory, or bare name under ~/.pptwise/decks").option("--json", "machine-readable output (the full AuditReport)").option("--pixels", "also run the optional pixel-contrast pass over image-backed text (requires sharp)").option("--theme-file <path>", "load a custom theme file (see `pptwise brand extract`) and audit with it").action(async (target, opts) => {
+  try {
+    const { output, hasFindings } = await runAudit(target, {
+      json: opts.json,
+      pixels: opts.pixels,
+      themeFilePath: opts.themeFile
+    });
+    console.log(output);
+    if (hasFindings) process.exit(1);
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("asset-brief").description(
+  "Image-generation brief for every image slot in a deck: the real rendered frame, fit/crop mode, suggested pixel size, theme palette/mood, and a paste-ready prompt"
+).argument("<target>", "IR JSON file, deck project directory, or bare name under ~/.pptwise/decks").option("--json", "machine-readable output (the full AssetBrief)").action(async (target, opts) => {
+  try {
+    console.log(await runAssetBrief(target, { json: opts.json }));
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("schema").description("Print the IR JSON Schema (feed this to a model before it writes IR)").option("--style", "print the style-override schema instead").option("--spec", "print the deck spec schema instead").option("--plan", "removed \u2014 use --spec instead").action((opts) => {
+  if (opts.plan) {
+    fail(new Error("`pptwise schema --plan` has been renamed to `pptwise schema --spec` \u2014 run `pptwise schema --spec` instead"));
+  }
+  console.log(runSchema(opts.spec ? "spec" : opts.style ? "style" : void 0));
+});
+var plan = program.command("plan").description("Removed \u2014 use `pptwise spec` instead");
+plan.command("validate").description("Removed \u2014 use `pptwise spec validate` instead").argument("<file>").action(() => {
+  fail(new Error("`pptwise plan validate` has been renamed to `pptwise spec validate` \u2014 run `pptwise spec validate <file>` instead"));
+});
+var spec = program.command("spec").description("Deck spec commands (spec \xA76)");
+spec.command("validate").description("Validate a deck spec JSON file against the schema and strategy-aware hard gates").argument("<spec.json>").action(async (specPath) => {
+  try {
+    console.log(await runSpecValidate(specPath));
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("assemble").description("Assemble a deck project directory (deck.spec.json + pages/ + assets/) into an IR JSON file").argument("<dir|name>", "deck project directory, or bare name under ~/.pptwise/decks").option("-o, --output <file>", "output IR JSON path (default: <dir>/deck.json)").action(async (target, opts) => {
+  try {
+    console.log(await runAssemble(target, { output: opts.output }));
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("disassemble").description("Split an IR JSON file into a deck project directory (deck.spec.json + pages/)").argument("<ir.json>", "path to the IR file").requiredOption("-o, --output <dir>", "output deck project directory").action(async (irPath, opts) => {
+  try {
+    console.log(await runDisassemble(irPath, opts.output));
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("migrate").description("Convert a v3 IR file to v4, rewrite chrome \u2192 branding, bloom \u2192 classroom, logo_wall \u2192 image_grid, or banner-heading \u2192 two-column on a v4 IR or deck spec, or convert a deck.plan.json project directory to deck.spec.json \u2014 deterministic, no model").argument("<input>", "IR v3 JSON file, a v4 IR or deck spec still carrying chrome, bloom, logo_wall, or banner-heading, or a deck project directory containing deck.plan.json").requiredOption("-o, --output <output>", "output path \u2014 an IR JSON file for a file input, a directory for a deck-project-directory input").action(async (input, opts) => {
+  try {
+    console.log(await runMigrate(input, opts.output));
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("themes").description("List built-in themes").option("--json", "machine-readable output").action((opts) => console.log(runThemes(Boolean(opts.json))));
+var brand = program.command("brand").description("Brand asset commands \u2014 extract your company's colors/fonts from an Office template");
+brand.command("extract").description(
+  "Extract brand colors and fonts from a .thmx/.potx/.pptx file into a pptwise theme file \u2014 runs entirely locally, the file never leaves your machine"
+).argument("<file>", "a .thmx theme, .potx template, or .pptx presentation").requiredOption("-o, --output <file>", "output theme JSON path (e.g. my-brand.theme.json)").option("--id <id>", "theme id to register under (default: slug of the output filename)").option("--label <label>", "human-readable theme label (default: the source theme's color-scheme name)").action(async (file, opts) => {
+  try {
+    console.log(await runBrandExtract(file, { output: opts.output, id: opts.id, label: opts.label }));
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("narratives").description("List named narrative presets (strategy/pacing/audience axes + theme recommendations)").option("--json", "machine-readable output").action((opts) => console.log(runNarratives(Boolean(opts.json))));
+program.command("scenarios").description("Removed \u2014 use `pptwise narratives` instead").action(() => {
+  fail(new Error("`pptwise scenarios` has been renamed to `pptwise narratives` \u2014 run `pptwise narratives` instead"));
+});
+var config = program.command("config").description("User-level settings (API keys for optional stock-photo search)");
+config.command("set <key> [value]").description("Set a user config value. Omit the value for an apiKey or clientSecret to enter it at a hidden prompt").action(async (key, value) => {
+  try {
+    console.log(await runConfigSet(key, value));
+  } catch (e) {
+    fail(e);
+  }
+});
+config.command("show").description("Show the effective user config (API keys masked)").action(async () => {
+  try {
+    console.log(await runConfigShow());
+  } catch (e) {
+    fail(e);
+  }
+});
+function parsePositiveInt(raw, flag) {
+  if (!/^[0-9]+$/.test(raw)) {
+    fail(new Error(`invalid ${flag} "${raw}" \u2014 expected a positive integer`));
+  }
+  return Number(raw);
+}
+var images = program.command("images").description("Search and pin stock photos into workspace assets");
+images.command("search <query>").description("Search Pexels, then Pixabay, then Openverse (cc0/pdm) and print attribution lines").option("--orientation <orientation>", "landscape, portrait, or square").option("--color <color>", "color name or hex for the search API").option("--min-width <px>", "client-side minimum width in pixels").option("--min-height <px>", "client-side minimum height in pixels").action(
+  async (query, opts) => {
+    try {
+      console.log(
+        await runImagesSearch(query, {
+          orientation: opts.orientation,
+          color: opts.color,
+          minWidth: opts.minWidth !== void 0 ? parsePositiveInt(opts.minWidth, "--min-width") : void 0,
+          minHeight: opts.minHeight !== void 0 ? parsePositiveInt(opts.minHeight, "--min-height") : void 0
+        })
+      );
+    } catch (e) {
+      fail(e);
+    }
+  }
+);
+images.command("fetch <ref>").description("Download a photo (pexels:<id>, pixabay:<id>, or openverse:<id>) into .pptwise/<deck>/assets/").requiredOption("--deck <dir>", "deck project directory, path, or bare name").requiredOption("--as <asset_id>", "local asset id (filename without extension)").option("--query <text>", "search query that produced this pick (stored in the sidecar)").action(async (ref, opts) => {
+  try {
+    console.log(
+      await runImagesFetch(ref, { deck: opts.deck, as: opts.as, query: opts.query, cwd: process.cwd() })
+    );
+  } catch (e) {
+    fail(e);
+  }
+});
+images.command("list").description("List pinned stock photos for a deck").requiredOption("--deck <dir>", "deck project directory, path, or bare name").action(async (opts) => {
+  try {
+    console.log(await runImagesList({ deck: opts.deck, cwd: process.cwd() }));
+  } catch (e) {
+    fail(e);
+  }
+});
+images.command("generate").description("Generate an image with a local CLI (grok, codex, or antigravity) and pin it").requiredOption("--deck <dir>", "deck project directory, path, or bare name").requiredOption("--as <asset_id>", "local asset id (filename without extension)").option("--prompt <text>", "image prompt (otherwise taken from asset-brief)").action(async (opts) => {
+  try {
+    console.log(
+      await runImagesGenerate({ deck: opts.deck, as: opts.as, prompt: opts.prompt, cwd: process.cwd() })
+    );
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("init").description("Scaffold a pptwise.config.json in the current directory").action(async () => {
+  try {
+    console.log(await runInit());
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("preview").description("Render each slide to an SVG file for visual self-check").argument("<target>", "IR JSON file, deck project directory, or bare name under ~/.pptwise/decks").option("-o, --output <dir>", "output directory (default: .pptwise/<deck>/ under the project root)").option("--html", "also write a self-contained preview.html (all slides inlined \u2014 thumbnail strip, keyboard navigation) for human review").option("--theme-file <path>", "load a custom theme file (see `pptwise brand extract`) and preview with it").option("--no-git-ignore", "do not add .pptwise/ to this repository's local exclude file").action(async (target, opts) => {
+  try {
+    console.log(
+      await runPreview(target, opts.output, {
+        htmlOut: opts.html,
+        themeFilePath: opts.themeFile,
+        gitIgnore: opts.gitIgnore,
+        cwd: process.cwd()
+      })
+    );
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("serve").description("Serve a live-reloading HTML preview of an IR JSON file, deck project directory, or bare deck name over HTTP").argument("<target>", "IR JSON file, deck project directory, or bare name under ~/.pptwise/decks").option("--port <number>", `port to listen on (default ${DEFAULT_PORT})`).option("--no-open", "do not open the URL in a browser after starting").option("--theme-file <path>", "load a custom theme file (see `pptwise brand extract`) and serve with it").action(async (target, opts) => {
+  try {
+    let port;
+    if (opts.port !== void 0) {
+      port = Number(opts.port);
+      if (!Number.isInteger(port)) {
+        fail(new Error(`invalid --port value "${opts.port}" \u2014 expected an integer`));
+      }
+    }
+    await runServe(target, { port, open: opts.open, themeFilePath: opts.themeFile });
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("doctor").description(
+  "Diagnose this machine's install: installed skill copies and what each pins, dsh plugin status, Node/Bun against the engines floor, the optional sharp/soffice capabilities, and a self-test render \u2014 exits 1 only on a hard failure"
+).option("--json", "machine-readable output (the full DoctorReport)").action(async (opts) => {
+  try {
+    const { output, hasErrors } = await runDoctor({ json: opts.json });
+    console.log(output);
+    if (hasErrors) process.exit(1);
+  } catch (e) {
+    fail(e);
+  }
+});
+program.command("check-update").description("Check npm for a newer pptwise release").action(async () => {
+  const info = await checkForUpdate({ currentVersion: VERSION });
+  if (!info.checked) fail(new Error(`update check failed: ${info.error}`));
+  console.log(
+    info.updateAvailable ? `update available: ${info.currentVersion} \u2192 ${info.latestVersion} (run \`pptwise self-update\`)` : `pptwise ${info.currentVersion} is up to date`
+  );
+});
+program.command("self-update").description("Update the global pptwise install to the latest release").action(async () => {
+  try {
+    const result = await createSelfUpdater()({ currentVersion: VERSION });
+    console.log(
+      result.updated ? `updated: ${result.currentVersion} \u2192 ${result.latestVersion}` : `already at the latest version (${result.currentVersion})`
+    );
+  } catch (e) {
+    fail(e);
+  }
+});
+program.parseAsync(process.argv, { from: "node" }).catch(fail);
+//# sourceMappingURL=cli.js.map