@liustack/pptfast 0.1.0 → 0.4.0

package/dist/chunk-4W2YZPJJ.js

@@ -0,0 +1,564 @@
+import {
+  AssetsSchema,
+  BrandSchema,
+  CAPACITY,
+  COMPONENT_TYPES,
+  LAYOUT_REGISTRY,
+  MetaSchema,
+  NarrativeProfileInputSchema,
+  PptfastError,
+  PptxIRSchema,
+  STRATEGY_DEFINITIONS,
+  SlideSchema,
+  ThemeSchema,
+  getInstalledThemeIds,
+  resolveEffectiveLayoutId,
+  resolveNarrative
+} from "./chunk-7N4HGSMW.js";
+
+// src/version.ts
+var VERSION = "0.4.0";
+
+// src/ir/legacy-v3.ts
+import { z } from "zod";
+var PptxIRV3Schema = z.object({
+  version: z.literal("3").default("3"),
+  filename: z.string().default("presentation"),
+  // Pre-rename field name and axis vocabulary (mode/delivery/audience) —
+  // frozen as of the 0.3.0 release, spec §9.3. Same open-schema/closed-
+  // semantic split `NarrativeProfileInputSchema` documents: the actual
+  // mode/delivery/audience enum closure happened at `resolveScenario`
+  // runtime, not here, even before this rename.
+  scenario: z.union([z.string(), NarrativeProfileInputSchema]).optional(),
+  theme: ThemeSchema.default({ id: "consulting" }),
+  meta: MetaSchema.default({}),
+  assets: AssetsSchema.default({ images: {} }),
+  brand: BrandSchema.optional(),
+  seed: z.number().int().optional(),
+  slides: z.array(SlideSchema)
+}).strict();
+
+// src/ir/migrate.ts
+var STRATEGY_VALUE_MIGRATION = { narrative: "storytelling" };
+var PACING_VALUE_MIGRATION = { text: "dense", presentation: "spacious" };
+function migrateNarrativeInput(scenario) {
+  if (scenario === void 0 || typeof scenario === "string") return scenario;
+  const narrative = {};
+  for (const [key, value] of Object.entries(scenario)) {
+    if (key === "mode") {
+      narrative.strategy = typeof value === "string" ? STRATEGY_VALUE_MIGRATION[value] ?? value : value;
+    } else if (key === "delivery") {
+      narrative.pacing = typeof value === "string" ? PACING_VALUE_MIGRATION[value] ?? value : value;
+    } else if (key === "audience") {
+      narrative.audience = value;
+    } else {
+      narrative[key] = value;
+    }
+  }
+  return narrative;
+}
+function migrateIrV3ToV4(v3) {
+  const narrative = migrateNarrativeInput(v3.scenario);
+  return {
+    version: "4",
+    filename: v3.filename,
+    ...narrative !== void 0 ? { narrative } : {},
+    theme: v3.theme,
+    meta: v3.meta,
+    assets: v3.assets,
+    ...v3.brand !== void 0 ? { brand: v3.brand } : {},
+    ...v3.seed !== void 0 ? { seed: v3.seed } : {},
+    slides: v3.slides
+  };
+}
+
+// src/plan/index.ts
+import { z as z2 } from "zod";
+var PAGE_TYPES = ["cover", "chapter", "content", "ending"];
+var BEAT_VALUES = ["anchor", "dense", "breathing"];
+var PageSpecSchema = z2.object({
+  id: z2.string(),
+  type: z2.enum(PAGE_TYPES),
+  heading: z2.string(),
+  /** One of the three beat values, or omitted entirely — an omitted
+   *  beat is never a hard-gate violation on its own (see
+   *  {@link checkBeatRotation}'s policy functions below). It gets
+   *  auto-alternated at assemble time (W5 task 3, not this task). Renamed
+   *  from `rhythm` (vocabulary-v4 rename, spec §4.3/§6/§8.1) — same
+   *  three values, same semantics, page-level term only, distinct from
+   *  the deck-level `pacing` axis. */
+  beat: z2.enum(BEAT_VALUES).optional(),
+  /** Optional authoring hint pointing fill/select at a preferred
+   *  component type or layout id — see {@link checkFocusVocabulary}. */
+  focus: z2.string().optional(),
+  /** Free-text content anchor, "for the fill step's own reading only" (spec §5) — read by a later
+   *  fill step, never validated or interpreted here. */
+  summary: z2.string().optional()
+}).strict();
+var DeckSpecSchema = z2.object({
+  version: z2.literal("1").default("1"),
+  // Same open-schema/closed-semantic split as PptxIRSchema's `narrative`
+  // field — see `NarrativeProfileInputSchema`'s doc comment in `ir/index.ts`
+  // for the full rationale (reused verbatim here, not redefined, so the
+  // two can't drift apart). Field renamed from `scenario` to `narrative`
+  // this task (spec §8.1's `DeckPlan`→`DeckSpec` rename, task 2) — its
+  // *value* was already in the new strategy/pacing vocabulary as of task 1
+  // (vocabulary-v4 rename) — `resolveNarrative` below is what actually
+  // enforces that.
+  narrative: z2.union([z2.string(), NarrativeProfileInputSchema]).optional(),
+  theme: z2.string().optional(),
+  filename: z2.string().optional(),
+  seed: z2.number().int().optional(),
+  meta: MetaSchema.default({}),
+  /** Deck logo placement — reused verbatim from the IR's own `brand` field
+   *  (`BrandSchema`, `../ir`) so the deck spec and IR can't drift apart on
+   *  shape, same pattern as `meta` just above. Unlike `meta`, no
+   *  `.default({})`: IR's own `brand` field is a bare `.optional()` with no
+   *  default either (`undefined` means "no brand", not "an empty brand
+   *  object") — consumed by `BrandChrome` (`src/svg/BrandChrome.tsx`) for
+   *  the deck's logo image and corner position. */
+  brand: BrandSchema.optional(),
+  pages: z2.array(PageSpecSchema)
+}).strict();
+function specJsonSchema() {
+  return z2.toJSONSchema(DeckSpecSchema);
+}
+function formatSpecIssues(errors) {
+  return errors.map((e) => e.pageId ? `page "${e.pageId}" \u2014 ${e.path}: ${e.message}` : `${e.path}: ${e.message}`).join("\n");
+}
+function formatInvalidSpecError(errors) {
+  return `invalid spec (${errors.length} issue${errors.length === 1 ? "" : "s"}):
+${formatSpecIssues(errors)}`;
+}
+function resolveSpecThemeId(spec) {
+  return spec.theme ?? "consulting";
+}
+function checkPagesNonEmpty(spec) {
+  if (spec.pages.length > 0) return [];
+  return [{ path: "pages", message: "spec has no pages \u2014 a spec needs at least a cover page and an ending page" }];
+}
+function checkBoundaryTypes(spec) {
+  const { pages } = spec;
+  const errors = [];
+  const first = pages[0];
+  const last = pages[pages.length - 1];
+  if (first.type !== "cover") {
+    errors.push({
+      path: "pages.0.type",
+      pageId: first.id,
+      message: `first page must be type "cover" (got "${first.type}") \u2014 a spec must open with a cover page`
+    });
+  }
+  if (last.type !== "ending") {
+    errors.push({
+      path: `pages.${pages.length - 1}.type`,
+      pageId: last.id,
+      message: `last page must be type "ending" (got "${last.type}") \u2014 a spec must close with an ending page`
+    });
+  }
+  for (let i = 1; i < pages.length - 1; i++) {
+    const page = pages[i];
+    if (page.type === "cover" || page.type === "ending") {
+      errors.push({
+        path: `pages.${i}.type`,
+        pageId: page.id,
+        message: `page "${page.id}" is type "${page.type}", only allowed as the first (cover) or last (ending) page \u2014 use "content" or "chapter" for interior pages`
+      });
+    }
+  }
+  return errors;
+}
+function isUnsafePageId(id) {
+  return id.includes("/") || id.includes("\\") || id === "..";
+}
+function checkPageIds(spec) {
+  const errors = [];
+  const seen = /* @__PURE__ */ new Map();
+  spec.pages.forEach((page, i) => {
+    if (page.id.trim() === "") {
+      errors.push({ path: `pages.${i}.id`, message: `page ${i + 1} has an empty id \u2014 every page needs a non-empty, unique id` });
+      return;
+    }
+    if (isUnsafePageId(page.id)) {
+      errors.push({
+        path: `pages.${i}.id`,
+        pageId: page.id,
+        message: `page id "${page.id}" is not a safe file name \u2014 ids used as page/asset file names must not contain path separators or ".."`
+      });
+      return;
+    }
+    const indices = seen.get(page.id);
+    if (indices) indices.push(i);
+    else seen.set(page.id, [i]);
+  });
+  for (const [id, indices] of seen) {
+    if (indices.length < 2) continue;
+    errors.push({
+      path: "pages",
+      pageId: id,
+      message: `duplicate page id "${id}" used by ${indices.length} pages (positions ${indices.map((i) => i + 1).join(", ")}) \u2014 page ids must be unique within a spec`
+    });
+  }
+  return errors;
+}
+var HEADING_MAX_CHARS = CAPACITY.headingMaxChars;
+function specHeadingLength(heading) {
+  return heading.length;
+}
+function checkHeadings(spec) {
+  const errors = [];
+  spec.pages.forEach((page, i) => {
+    if (page.heading.trim() === "") {
+      errors.push({ path: `pages.${i}.heading`, pageId: page.id, message: `page "${page.id}" is missing a required heading` });
+      return;
+    }
+    const length = specHeadingLength(page.heading);
+    if (length > HEADING_MAX_CHARS) {
+      errors.push({
+        path: `pages.${i}.heading`,
+        pageId: page.id,
+        message: `page "${page.id}" heading is ${length} characters, exceeds the ${HEADING_MAX_CHARS}-character limit \u2014 tighten it into a short, assertive phrase`
+      });
+    }
+  });
+  return errors;
+}
+function checkTheme(spec) {
+  const themeId = resolveSpecThemeId(spec);
+  const installed = getInstalledThemeIds();
+  if (installed.includes(themeId)) return [];
+  return [{ path: "theme", message: `unknown theme "${themeId}" \u2014 available: ${installed.join(", ")} (see \`pptfast themes\`)` }];
+}
+var LAYOUT_IDS = Object.keys(LAYOUT_REGISTRY);
+function checkFocusVocabulary(spec, strategy) {
+  const tendencies = STRATEGY_DEFINITIONS[strategy].tendencies;
+  const errors = [];
+  spec.pages.forEach((page, i) => {
+    if (page.focus === void 0) return;
+    if (tendencies.includes(page.focus) || COMPONENT_TYPES.includes(page.focus) || LAYOUT_IDS.includes(page.focus)) {
+      return;
+    }
+    errors.push({
+      path: `pages.${i}.focus`,
+      pageId: page.id,
+      message: `unknown focus "${page.focus}" for strategy "${strategy}" \u2014 expected one of this strategy's tendencies (${tendencies.join(", ")}), a component type (${COMPONENT_TYPES.join(", ")}), or a layout id (${LAYOUT_IDS.join(", ")})`
+    });
+  });
+  return errors;
+}
+function declaredBeatContentPages(spec) {
+  const result = [];
+  spec.pages.forEach((page, index) => {
+    if (page.type === "content" && page.beat !== void 0) {
+      result.push({ index, id: page.id, beat: page.beat });
+    }
+  });
+  return result;
+}
+function checkAlternatePolicy(spec, strategy) {
+  const seq = declaredBeatContentPages(spec);
+  const errors = [];
+  let i = 0;
+  while (i < seq.length) {
+    let j = i + 1;
+    while (j < seq.length && seq[j].beat === seq[i].beat) j++;
+    const runLength = j - i;
+    if (runLength >= 3) {
+      const members = seq.slice(i, j);
+      errors.push({
+        path: "pages",
+        pageId: members[0].id,
+        message: `${runLength} consecutive content pages declare beat "${seq[i].beat}" (${members.map((m) => m.id).join(", ")}) \u2014 strategy "${strategy}" requires beat to alternate, vary at least one of them`
+      });
+    }
+    i = j;
+  }
+  return errors;
+}
+function checkAnchorOpenPolicy(spec, strategy) {
+  const firstContentIndex = spec.pages.findIndex((page) => page.type === "content");
+  if (firstContentIndex === -1) return [];
+  const firstContent = spec.pages[firstContentIndex];
+  if (firstContent.beat === void 0 || firstContent.beat === "anchor") return [];
+  return [
+    {
+      path: `pages.${firstContentIndex}.beat`,
+      pageId: firstContent.id,
+      message: `first content page declares beat "${firstContent.beat}" \u2014 strategy "${strategy}" requires the deck to open its first content page on "anchor" beat when a beat is declared`
+    }
+  ];
+}
+function checkAnchorSparsePolicy(spec, strategy) {
+  const declared = declaredBeatContentPages(spec);
+  if (declared.length === 0) return [];
+  const anchorPages = declared.filter((page) => page.beat === "anchor");
+  if (anchorPages.length / declared.length <= 0.5) return [];
+  const pct = Math.round(anchorPages.length / declared.length * 100);
+  return [
+    {
+      path: "pages",
+      // First offending anchor page, same "representative pageId" shape
+      // checkAlternatePolicy's own issue carries (members[0]!.id there) —
+      // this gate's violation is deck-wide (a ratio, not one page), but a
+      // representative id still gives a CLI/agent caller something to jump
+      // to rather than only a bare "pages" path.
+      pageId: anchorPages[0].id,
+      message: `${anchorPages.length} of ${declared.length} content pages with a declared beat are "anchor" (${pct}%: ${anchorPages.map((page) => page.id).join(", ")}) \u2014 strategy "${strategy}" requires "anchor" to stay a minority of declared beats, vary some to "dense" or "breathing"`
+    }
+  ];
+}
+function checkBeatRotation(spec, strategy) {
+  const policy = STRATEGY_DEFINITIONS[strategy].beatPolicy;
+  switch (policy) {
+    case "uniform-dense":
+    case "repetition-ok":
+      return [];
+    case "alternate":
+      return checkAlternatePolicy(spec, strategy);
+    case "anchor-open":
+      return checkAnchorOpenPolicy(spec, strategy);
+    case "anchor-sparse":
+      return checkAnchorSparsePolicy(spec, strategy);
+    default: {
+      const exhaustive = policy;
+      throw new Error(`unhandled beat policy: ${String(exhaustive)}`);
+    }
+  }
+}
+var SPEC_PAGE_COUNT_RANGE = {
+  dense: { min: 8, max: 30 },
+  balanced: { min: 6, max: 24 },
+  spacious: { min: 4, max: 16 }
+};
+function checkPageCount(spec, pacing) {
+  const { min, max } = SPEC_PAGE_COUNT_RANGE[pacing];
+  const n = spec.pages.length;
+  if (n >= min && n <= max) return [];
+  return [
+    {
+      path: "pages",
+      message: `spec has ${n} pages \u2014 "${pacing}" pacing expects ${min}-${max} pages, change pacing or add/remove pages`
+    }
+  ];
+}
+function pageIdFromRawInput(input, index) {
+  if (typeof input !== "object" || input === null) return void 0;
+  const pages = input.pages;
+  if (!Array.isArray(pages)) return void 0;
+  const page = pages[index];
+  if (typeof page !== "object" || page === null) return void 0;
+  const id = page.id;
+  return typeof id === "string" ? id : void 0;
+}
+function validateSpec(input) {
+  const r = DeckSpecSchema.safeParse(input);
+  if (!r.success) {
+    const errors = r.error.issues.map((issue) => {
+      const path = issue.path.join(".");
+      const m = /^pages\.(\d+)/.exec(path);
+      return { path, message: issue.message, pageId: m ? pageIdFromRawInput(input, Number(m[1])) : void 0 };
+    });
+    return { ok: false, errors };
+  }
+  const spec = r.data;
+  const emptyErrors = checkPagesNonEmpty(spec);
+  if (emptyErrors.length > 0) return { ok: false, errors: emptyErrors };
+  const boundaryErrors = checkBoundaryTypes(spec);
+  if (boundaryErrors.length > 0) return { ok: false, errors: boundaryErrors };
+  const idErrors = checkPageIds(spec);
+  if (idErrors.length > 0) return { ok: false, errors: idErrors };
+  const headingErrors = checkHeadings(spec);
+  if (headingErrors.length > 0) return { ok: false, errors: headingErrors };
+  const themeErrors = checkTheme(spec);
+  if (themeErrors.length > 0) return { ok: false, errors: themeErrors };
+  let resolvedAxes;
+  try {
+    resolvedAxes = resolveNarrative(spec.narrative);
+  } catch (err) {
+    if (!(err instanceof PptfastError)) throw err;
+    return { ok: false, errors: [{ path: "narrative", message: err.message }] };
+  }
+  const beatErrors = checkBeatRotation(spec, resolvedAxes.strategy);
+  if (beatErrors.length > 0) return { ok: false, errors: beatErrors };
+  const focusErrors = checkFocusVocabulary(spec, resolvedAxes.strategy);
+  if (focusErrors.length > 0) return { ok: false, errors: focusErrors };
+  const pageCountErrors = checkPageCount(spec, resolvedAxes.pacing);
+  if (pageCountErrors.length > 0) return { ok: false, errors: pageCountErrors };
+  return { ok: true, spec, errors: [] };
+}
+
+// src/plan/assemble.ts
+function stableHash(s) {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) h = (h << 5) + h + s.charCodeAt(i) | 0;
+  return Math.abs(h);
+}
+function generateSeed(filename, pageIds) {
+  return stableHash([filename ?? "", ...pageIds].join("\n"));
+}
+var LOCKED_KEYS = ["type", "heading"];
+function assembleDeck(spec, pages) {
+  const validated = validateSpec(spec);
+  if (!validated.ok) {
+    throw new PptfastError(formatInvalidSpecError(validated.errors));
+  }
+  const deckSpec = validated.spec;
+  for (const page of deckSpec.pages) {
+    const raw = pages[page.id];
+    if (raw === void 0) continue;
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      throw new PptfastError(`page "${page.id}": page content must be an object`);
+    }
+    for (const key of LOCKED_KEYS) {
+      if (Object.hasOwn(raw, key)) {
+        throw new PptfastError(`page "${page.id}": "${key}" is locked by the spec \u2014 remove it from the page file`);
+      }
+    }
+  }
+  const specIds = new Set(deckSpec.pages.map((page) => page.id));
+  const orphanIds = Object.keys(pages).filter((id) => !specIds.has(id));
+  if (orphanIds.length > 0) {
+    throw new PptfastError(
+      `orphan page id${orphanIds.length === 1 ? "" : "s"} ${orphanIds.map((id) => `"${id}"`).join(", ")} \u2014 not in the spec, delete the page file or add the page to the spec`
+    );
+  }
+  const slides = deckSpec.pages.map((page) => buildSlide(page, pages[page.id]));
+  const generatedSeed = deckSpec.seed === void 0 ? generateSeed(deckSpec.filename, deckSpec.pages.map((page) => page.id)) : void 0;
+  const seed = deckSpec.seed ?? generatedSeed;
+  const rawIr = {
+    version: "4",
+    ...deckSpec.narrative !== void 0 ? { narrative: deckSpec.narrative } : {},
+    ...deckSpec.theme !== void 0 ? { theme: { id: deckSpec.theme } } : {},
+    ...deckSpec.filename !== void 0 ? { filename: deckSpec.filename } : {},
+    ...deckSpec.brand !== void 0 ? { brand: deckSpec.brand } : {},
+    meta: deckSpec.meta,
+    seed,
+    slides
+  };
+  const parsed = PptxIRSchema.safeParse(rawIr);
+  if (!parsed.success) {
+    const detail = parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
+    throw new PptfastError(`assembled deck did not produce valid IR:
+${detail}`);
+  }
+  const { ir, materializedCount } = materializeEffectiveLayouts(parsed.data);
+  return {
+    ir,
+    ...generatedSeed !== void 0 ? { generatedSeed } : {},
+    ...materializedCount > 0 ? { materializedLayoutCount: materializedCount } : {}
+  };
+}
+function materializeEffectiveLayouts(ir) {
+  let materializedCount = 0;
+  const slides = ir.slides.map((slide, index) => {
+    if (slide.layout !== void 0) return slide;
+    const effectiveLayoutId = resolveEffectiveLayoutId(ir, slide, index);
+    if (effectiveLayoutId === null) return slide;
+    materializedCount++;
+    return { ...slide, layout: effectiveLayoutId };
+  });
+  return materializedCount === 0 ? { ir, materializedCount } : { ir: { ...ir, slides }, materializedCount };
+}
+function buildSlide(page, raw) {
+  if (raw === void 0) {
+    return {
+      id: page.id,
+      type: page.type,
+      heading: page.heading,
+      placeholder: true,
+      ...page.summary !== void 0 ? { subheading: page.summary } : {}
+    };
+  }
+  return {
+    id: page.id,
+    type: page.type,
+    heading: page.heading,
+    ...raw.components !== void 0 ? { components: raw.components } : {},
+    ...raw.layout !== void 0 ? { layout: raw.layout } : {},
+    ...raw.arrangement !== void 0 ? { arrangement: raw.arrangement } : {},
+    ...raw.background !== void 0 ? { background: raw.background } : {},
+    ...raw.image_side !== void 0 ? { image_side: raw.image_side } : {},
+    ...raw.footnote !== void 0 ? { footnote: raw.footnote } : {},
+    ...raw.notes !== void 0 ? { notes: raw.notes } : {}
+  };
+}
+var UNTITLED_HEADING = "Untitled";
+function disassembleDeck(ir) {
+  const pages = {};
+  const pageSpecs = ir.slides.map((slide, index) => {
+    const id = slide.id ?? `p-${index + 1}-${slide.type}`;
+    const heading = slide.heading !== void 0 && slide.heading.trim() !== "" ? slide.heading : UNTITLED_HEADING;
+    const pageSpec = {
+      id,
+      type: slide.type,
+      heading,
+      ...slide.placeholder === true && slide.subheading !== void 0 ? { summary: slide.subheading } : {}
+    };
+    if (slide.placeholder !== true) pages[id] = extractPageContent(slide);
+    return pageSpec;
+  });
+  const spec = {
+    version: "1",
+    // `ir.narrative` (v4 field, vocabulary-v4 rename) carries straight into
+    // the deck spec's own `narrative` field — its value is
+    // already in the new strategy/pacing vocabulary, no remapping needed.
+    ...ir.narrative !== void 0 ? { narrative: ir.narrative } : {},
+    theme: ir.theme.id,
+    filename: ir.filename,
+    ...ir.seed !== void 0 ? { seed: ir.seed } : {},
+    ...ir.brand !== void 0 ? { brand: ir.brand } : {},
+    meta: ir.meta,
+    pages: pageSpecs
+  };
+  return { spec, pages };
+}
+function extractPageContent(slide) {
+  const content = {};
+  if (slide.components.length > 0) content.components = slide.components;
+  if (slide.layout !== void 0) content.layout = slide.layout;
+  if (slide.arrangement !== void 0) content.arrangement = slide.arrangement;
+  if (slide.background !== void 0) content.background = slide.background;
+  if (slide.image_side !== void 0) content.image_side = slide.image_side;
+  if (slide.footnote !== void 0) content.footnote = slide.footnote;
+  if (slide.notes !== void 0) content.notes = slide.notes;
+  return content;
+}
+
+// src/plan/migrate.ts
+function migrateDeckPlanToSpec(raw) {
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) return raw;
+  const { scenario, pages, ...rest } = raw;
+  const result = { ...rest };
+  if (scenario !== void 0) result.narrative = scenario;
+  if (Array.isArray(pages)) {
+    result.pages = pages.map(migratePageRhythmToBeat);
+  } else if (pages !== void 0) {
+    result.pages = pages;
+  }
+  return result;
+}
+function migratePageRhythmToBeat(page) {
+  if (typeof page !== "object" || page === null || Array.isArray(page)) return page;
+  const { rhythm, ...rest } = page;
+  const next = { ...rest };
+  if (rhythm !== void 0) next.beat = rhythm;
+  return next;
+}
+
+export {
+  VERSION,
+  PptxIRV3Schema,
+  migrateIrV3ToV4,
+  PageSpecSchema,
+  DeckSpecSchema,
+  specJsonSchema,
+  formatSpecIssues,
+  formatInvalidSpecError,
+  resolveSpecThemeId,
+  SPEC_PAGE_COUNT_RANGE,
+  validateSpec,
+  assembleDeck,
+  disassembleDeck,
+  migrateDeckPlanToSpec
+};
+//# sourceMappingURL=chunk-4W2YZPJJ.js.map