@classic-homes/slides 0.2.0 → 0.2.1

package/README.md

@@ -91,10 +91,12 @@ flags errors and crowded slides.
 ## With an AI agent (MCP)
 
 The package ships an MCP server that edits deck files slide by slide and
-validates before every save, so an agent cannot leave a deck broken.
+validates before every save, so an agent cannot leave a deck broken. It needs
+`@modelcontextprotocol/sdk` (an optional peer, so apps that only render decks
+don't install it).
 
 ```bash
-claude mcp add classic-slides -- npx -y @classic-homes/slides mcp --root ./decks
+claude mcp add classic-slides -- npx -y -p @classic-homes/slides -p @modelcontextprotocol/sdk classic-slides mcp --root ./decks
 ```
 
 Then ask: _"Build a 10-slide deck in closing-day.yaml for first-time buyers

package/dist/{chunk-TXNQKBWJ.js → chunk-33EPZMT6.js}

@@ -3,7 +3,7 @@ import {
   LAYOUTS,
   baseSlide,
   getLayout
-} from "./chunk-TM3TNVHB.js";
+} from "./chunk-7FROOJCY.js";
 
 // src/catalog.ts
 import { z } from "zod";
@@ -66,4 +66,4 @@ export {
   deckJsonSchema,
   AUTHORING_GUIDE
 };
-//# sourceMappingURL=chunk-TXNQKBWJ.js.map
+//# sourceMappingURL=chunk-33EPZMT6.js.map

package/dist/{chunk-TM3TNVHB.js → chunk-7FROOJCY.js}

@@ -881,102 +881,158 @@ function getLayout(name) {
   return byName.get(name);
 }
 
-// src/schema/deck.ts
+// src/editor.ts
 import { z as z4 } from "zod";
-var slideSchemas = LAYOUTS.map(
-  (layout) => z4.object({ layout: z4.literal(layout.name), ...baseSlide, ...layout.shape }).strict().describe(`${layout.description} Use for: ${layout.whenToUse}`)
-);
-var SlideSchema = z4.discriminatedUnion("layout", slideSchemas);
-var DeckSchema = z4.object({
-  title: z4.string().min(1).describe("Deck title (browser tab, file name, gallery)."),
-  description: z4.string().optional().describe("One sentence: who the deck is for and what it covers."),
-  author: z4.string().optional(),
-  date: z4.string().optional(),
-  lang: z4.string().default("en"),
-  journey: z4.object({
-    steps: z4.array(Text).min(2).max(10).describe("Short names of each step, in order."),
-    label: z4.string().default("STEP").describe("Word on the vertical step rail.")
-  }).optional().describe(
-    'Optional numbered journey (agenda). Enables the journey layout, step rails and "you are here" strips.'
-  ),
-  slides: z4.array(SlideSchema).min(1)
-}).strict();
-
-// src/validate.ts
-function fromZod(issue) {
-  let message = issue.message;
-  if (issue.code === "invalid_union_discriminator") {
-    message = `Unknown layout. Use one of: ${issue.options.join(", ")}.`;
-  } else if (issue.code === "unrecognized_keys") {
-    message = `Unknown field(s) ${issue.keys.map((k) => `"${k}"`).join(", ")} for this layout.`;
+var MULTILINE = /* @__PURE__ */ new Set(["lead", "body", "text", "quote", "footnote", "sub", "notes", "caption"]);
+var LABELS = {
+  eyebrowSub: "Eyebrow subtitle",
+  showJourney: "Show journey strip",
+  stepDone: "Step completed",
+  mediaSide: "Photo side",
+  imageAspect: "Photo shape",
+  numberFrom: "First badge number",
+  url: "URL",
+  id: "Slide id"
+};
+function labelFor(key) {
+  if (LABELS[key]) return LABELS[key];
+  const words = key.replace(/([A-Z])/g, " $1").toLowerCase();
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+function unwrap(schema) {
+  let s = schema;
+  let required = true;
+  let dflt;
+  let description = schema.description;
+  for (; ; ) {
+    description ??= s.description;
+    if (s instanceof z4.ZodOptional || s instanceof z4.ZodNullable) {
+      required = false;
+      s = s.unwrap();
+    } else if (s instanceof z4.ZodDefault) {
+      required = false;
+      dflt = s._def.defaultValue();
+      s = s._def.innerType;
+    } else break;
   }
-  return { level: "error", path: issue.path, message };
+  return { inner: s, required, default: dflt, description };
 }
-function validateDeck(input) {
-  const parsed = DeckSchema.safeParse(input);
-  if (!parsed.success) {
-    return { ok: false, issues: parsed.error.issues.map(fromZod) };
+function isText(s) {
+  return s === Text || s instanceof z4.ZodString && s.description === Text.description;
+}
+function describeField(key, schema) {
+  const { inner, required, default: dflt, description } = unwrap(schema);
+  const base = {
+    key,
+    label: labelFor(key),
+    required,
+    ...description ? { description } : {},
+    ...dflt !== void 0 ? { default: dflt } : {},
+    ...MULTILINE.has(key) ? { multiline: true } : {}
+  };
+  if (inner === Image) return { ...base, kind: "image" };
+  if (inner === Item) return { ...base, kind: "item" };
+  if (isText(inner)) return { ...base, kind: "inline" };
+  if (inner instanceof z4.ZodString) return { ...base, kind: "string" };
+  if (inner instanceof z4.ZodBoolean) return { ...base, kind: "boolean" };
+  if (inner instanceof z4.ZodEnum) return { ...base, kind: "enum", options: [...inner.options] };
+  if (inner instanceof z4.ZodLiteral) return { ...base, kind: "enum", options: [inner.value] };
+  if (inner instanceof z4.ZodNumber) {
+    return {
+      ...base,
+      kind: "number",
+      integer: inner.isInt,
+      ...inner.minValue !== null ? { min: inner.minValue } : {},
+      ...inner.maxValue !== null ? { max: inner.maxValue } : {}
+    };
   }
-  const deck = parsed.data;
-  const issues = [];
-  const steps = deck.journey?.steps.length ?? 0;
-  const seen = /* @__PURE__ */ new Set();
-  deck.slides.forEach((slide, i) => {
-    const layout = getLayout(slide.layout);
-    for (const issue of layout.lint?.(slide) ?? []) {
-      issues.push({ ...issue, path: ["slides", i, ...issue.path] });
-    }
-    if (slide.id) {
-      if (seen.has(slide.id))
-        issues.push({
-          level: "error",
-          path: ["slides", i, "id"],
-          message: `Duplicate slide id "${slide.id}".`
-        });
-      seen.add(slide.id);
-    }
-    if ((slide.step || slide.showJourney || slide.layout === "journey") && !steps) {
-      issues.push({
-        level: "error",
-        path: ["slides", i, slide.step ? "step" : "layout"],
-        message: "This slide uses the journey, but the deck has no journey.steps defined."
-      });
-    }
-    if (slide.step && steps && slide.step > steps) {
-      issues.push({
-        level: "error",
-        path: ["slides", i, "step"],
-        message: `Step ${slide.step} is past the last journey step (${steps}).`
-      });
+  if (inner instanceof z4.ZodUnion) {
+    const opts = inner.options;
+    if (opts.every((o) => o instanceof z4.ZodLiteral)) {
+      return {
+        ...base,
+        kind: "enum",
+        options: opts.map((o) => o.value)
+      };
     }
-  });
-  if (deck.slides[0]?.layout !== "title") {
-    issues.push({
-      level: "warning",
-      path: ["slides", 0, "layout"],
-      message: 'Decks usually open with a "title" slide.'
-    });
+    return { ...base, kind: "string" };
   }
-  return { ok: !issues.some((i) => i.level === "error"), deck, issues };
+  if (inner instanceof z4.ZodArray) {
+    const el = inner.element;
+    return {
+      ...base,
+      kind: "list",
+      of: { ...describeField("", el), label: labelFor(key.replace(/s$/, "")) },
+      ...inner._def.minLength ? { min: inner._def.minLength.value } : {},
+      ...inner._def.maxLength ? { max: inner._def.maxLength.value } : {}
+    };
+  }
+  if (inner instanceof z4.ZodObject) {
+    return {
+      ...base,
+      kind: "group",
+      fields: Object.entries(inner.shape).map(
+        ([k, v]) => describeField(k, v)
+      )
+    };
+  }
+  return { ...base, kind: "string" };
 }
-function formatPath(path) {
-  if (!path.length) return "deck";
-  return path.map(
-    (p, i) => typeof p === "number" ? path[i - 1] === "slides" ? `slide ${p + 1}` : String(p + 1) : p
-  ).filter((p) => p !== "slides").join(" \u203A ");
+function commonSlideFields() {
+  return Object.entries(baseSlide).map(([k, v]) => describeField(k, v));
 }
-function formatIssues(issues) {
-  return issues.map((i) => `${i.level === "error" ? "\u2716" : "\u26A0"} ${formatPath(i.path)}: ${i.message}`).join("\n");
+function layoutEditorInfo(name) {
+  const layout = getLayout(name);
+  if (!layout) return void 0;
+  return {
+    name: layout.name,
+    description: layout.description,
+    whenToUse: layout.whenToUse,
+    defaults: layout.defaults ?? {},
+    fields: Object.entries(layout.shape).map(
+      ([k, v]) => describeField(k, v)
+    ),
+    example: layout.example
+  };
 }
-var DeckError = class extends Error {
-  constructor(issues) {
-    super(`Deck is not valid:
-${formatIssues(issues.filter((i) => i.level === "error"))}`);
-    this.issues = issues;
-    this.name = "DeckError";
-  }
-  issues;
-};
+function allLayoutEditorInfo() {
+  return LAYOUTS.map((l) => layoutEditorInfo(l.name));
+}
+var PLACEHOLDER_IMAGE = "data:image/svg+xml;base64," + btoa(
+  '<svg xmlns="http://www.w3.org/2000/svg" width="1600" height="1000" viewBox="0 0 1600 1000"><rect width="1600" height="1000" fill="#ecebe6"/><rect x="24" y="24" width="1552" height="952" fill="none" stroke="#b9bcb4" stroke-width="6" stroke-dasharray="28 20"/><text x="800" y="520" text-anchor="middle" font-family="Figtree,Arial,sans-serif" font-size="64" fill="#7a7a7a">Add a photo</text></svg>'
+);
+function isPlaceholderImage(src) {
+  return src === PLACEHOLDER_IMAGE;
+}
+function blankSlide(name) {
+  const layout = getLayout(name);
+  if (!layout) return void 0;
+  return JSON.parse(
+    JSON.stringify(layout.example),
+    (key, value) => key === "src" && typeof value === "string" && !/^(https?:|data:)/.test(value) ? PLACEHOLDER_IMAGE : value
+  );
+}
+
+// src/schema/deck.ts
+import { z as z5 } from "zod";
+var slideSchemas = LAYOUTS.map(
+  (layout) => z5.object({ layout: z5.literal(layout.name), ...baseSlide, ...layout.shape }).strict().describe(`${layout.description} Use for: ${layout.whenToUse}`)
+);
+var SlideSchema = z5.discriminatedUnion("layout", slideSchemas);
+var DeckSchema = z5.object({
+  title: z5.string().min(1).describe("Deck title (browser tab, file name, gallery)."),
+  description: z5.string().optional().describe("One sentence: who the deck is for and what it covers."),
+  author: z5.string().optional(),
+  date: z5.string().optional(),
+  lang: z5.string().default("en"),
+  journey: z5.object({
+    steps: z5.array(Text).min(2).max(10).describe("Short names of each step, in order."),
+    label: z5.string().default("STEP").describe("Word on the vertical step rail.")
+  }).optional().describe(
+    'Optional numbered journey (agenda). Enables the journey layout, step rails and "you are here" strips.'
+  ),
+  slides: z5.array(SlideSchema).min(1)
+}).strict();
 
 // src/render.ts
 import QRCode from "qrcode";
@@ -1015,7 +1071,11 @@ var RUNTIME_JS = String.raw`
       notesBody.innerHTML = n.html || '<p><i>No notes for this slide.</i></p>';
       notesTime.textContent = n.time || '';
     }
-    if (location.hash !== '#slide-' + (i + 1)) history.replaceState(null, '', '#slide-' + (i + 1));
+    // Sandboxed or srcdoc frames may refuse history access; the deep link is optional.
+    try {
+      if (location.hash !== '#slide-' + (i + 1)) history.replaceState(null, '', '#slide-' + (i + 1));
+    } catch (_) {}
+    if (window.parent !== window) window.parent.postMessage({ type: 'classic-slides:slide', index: i, count: slides.length }, '*');
   }
 
   // Current slide comes from the scroll position, the single source of truth.
@@ -1038,7 +1098,20 @@ var RUNTIME_JS = String.raw`
     });
   }, { passive: true });
 
-  function go(n) { const t = clamp(n); slides[t].scrollIntoView(); setActive(t); }
+  // Scroll the deck element itself; scrolling the slide into view would also move an embedding page.
+  function go(n, instant) {
+    const t = clamp(n);
+    deck.scrollTo({ top: t * deck.clientHeight, behavior: instant ? 'auto' : 'smooth' });
+    setActive(t);
+  }
+
+  // Embedders (editors, previews) can drive the deck: postMessage({ type: 'classic-slides:go', index }).
+  window.addEventListener('message', (e) => {
+    const d = e.data;
+    if (!d || typeof d !== 'object') return;
+    if (d.type === 'classic-slides:go' && Number.isInteger(d.index)) go(d.index, true);
+    else if (d.type === 'classic-slides:notes') { if (notes.classList.contains('open') !== !!d.open) toggleNotes(); }
+  });
 
   document.addEventListener('keydown', (e) => {
     if (e.metaKey || e.ctrlKey || e.altKey) return;
@@ -1058,7 +1131,8 @@ var RUNTIME_JS = String.raw`
   }
 
   const m = /^#slide-(\d+)$/.exec(location.hash);
-  if (m) requestAnimationFrame(() => go(Number(m[1]) - 1));
+  const initial = m ? Number(m[1]) - 1 : Number(document.body.dataset.initialSlide || 0);
+  if (initial > 0) requestAnimationFrame(() => go(initial, true));
   else setActive(0);
 })();
 `;
@@ -1374,6 +1448,7 @@ img.natural,.media img.natural,.photo-grid img.natural{width:auto;max-width:min(
 `;
 
 // src/render.ts
+var PREVIEW_SIZE = { width: 1280, height: 720 };
 var passThrough = (src) => {
   if (/^(data:|https?:)/.test(src)) return src;
   throw new Error(
@@ -1422,12 +1497,14 @@ async function renderDeck(input, options = {}) {
   };
   const sections = [];
   const notes = [];
+  const slideMap = [];
   deck.slides.forEach((slide, i) => {
     const layout = getLayout(slide.layout);
     const rendered = layout.render(slide, ctx);
     const list = Array.isArray(rendered) ? rendered : [rendered];
     const track = slide.track ?? layout.defaults?.track ?? "value";
     const bg = slide.background ?? layout.defaults?.background ?? "paper";
+    slideMap.push(list.map((_, j) => sections.length + j));
     list.forEach((r, j) => {
       const classes = ["slide", `layout-${layout.name}`, ...r.classes ?? []];
       if (bg !== "paper") classes.push("solid", `bg-${bg}`);
@@ -1459,7 +1536,7 @@ ${deck.description ? `<meta name="description" content="${escapeAttr(deck.descri
 <style id="brand-fonts">${fontsCss()}</style>
 <style>${tokensCss()}${DECK_CSS}</style>
 </head>
-<body>
+<body${options.initialSlide ? ` data-initial-slide="${Math.max(0, Math.floor(options.initialSlide))}"` : ""}>
 <div class="rail" id="rail"></div>
 <main class="deck" id="deck">
 ${sections.join("\n")}
@@ -1473,13 +1550,96 @@ ${source}<script>${RUNTIME_JS}</script>
 </body>
 </html>
 `;
-  return { html, deck, slideCount: sections.length, warnings: result.issues };
+  return { html, deck, slideCount: sections.length, slideMap, warnings: result.issues };
 }
 function extractDeckSource(html) {
   const m = /<script type="application\/json" id="deck-source">([\s\S]*?)<\/script>/.exec(html);
   return m ? JSON.parse(m[1]) : void 0;
 }
 
+// src/validate.ts
+function fromZod(issue) {
+  let message = issue.message;
+  if (issue.code === "invalid_union_discriminator") {
+    message = `Unknown layout. Use one of: ${issue.options.join(", ")}.`;
+  } else if (issue.code === "unrecognized_keys") {
+    message = `Unknown field(s) ${issue.keys.map((k) => `"${k}"`).join(", ")} for this layout.`;
+  }
+  return { level: "error", path: issue.path, message };
+}
+function validateDeck(input) {
+  const parsed = DeckSchema.safeParse(input);
+  if (!parsed.success) {
+    return { ok: false, issues: parsed.error.issues.map(fromZod) };
+  }
+  const deck = parsed.data;
+  const issues = [];
+  const steps = deck.journey?.steps.length ?? 0;
+  const seen = /* @__PURE__ */ new Set();
+  deck.slides.forEach((slide, i) => {
+    const layout = getLayout(slide.layout);
+    for (const issue of layout.lint?.(slide) ?? []) {
+      issues.push({ ...issue, path: ["slides", i, ...issue.path] });
+    }
+    if (collectImageSources(slide).has(PLACEHOLDER_IMAGE)) {
+      issues.push({
+        level: "warning",
+        path: ["slides", i],
+        message: "Replace the placeholder photo before presenting."
+      });
+    }
+    if (slide.id) {
+      if (seen.has(slide.id))
+        issues.push({
+          level: "error",
+          path: ["slides", i, "id"],
+          message: `Duplicate slide id "${slide.id}".`
+        });
+      seen.add(slide.id);
+    }
+    if ((slide.step || slide.showJourney || slide.layout === "journey") && !steps) {
+      issues.push({
+        level: "error",
+        path: ["slides", i, slide.step ? "step" : "layout"],
+        message: "This slide uses the journey, but the deck has no journey.steps defined."
+      });
+    }
+    if (slide.step && steps && slide.step > steps) {
+      issues.push({
+        level: "error",
+        path: ["slides", i, "step"],
+        message: `Step ${slide.step} is past the last journey step (${steps}).`
+      });
+    }
+  });
+  if (deck.slides[0]?.layout !== "title") {
+    issues.push({
+      level: "warning",
+      path: ["slides", 0, "layout"],
+      message: 'Decks usually open with a "title" slide.'
+    });
+  }
+  return { ok: !issues.some((i) => i.level === "error"), deck, issues };
+}
+function formatPath(path) {
+  if (!path.length) return "deck";
+  return path.map(
+    (p, i) => typeof p === "number" ? path[i - 1] === "slides" ? `slide ${p + 1}` : String(p + 1) : p
+  ).filter((p) => p !== "slides").join(" \u203A ");
+}
+function formatIssues(issues) {
+  return issues.map((i) => `${i.level === "error" ? "\u2716" : "\u26A0"} ${formatPath(i.path)}: ${i.message}`).join("\n");
+}
+var DeckError = class extends Error {
+  constructor(issues) {
+    super(`Deck is not valid:
+${formatIssues(issues.filter((i) => i.level === "error"))}`);
+    this.issues = issues;
+    this.name = "DeckError";
+  }
+  issues;
+};
+
 // src/parse.ts
 import YAML from "yaml";
 function parseDeckSource(text) {
@@ -1497,24 +1657,28 @@ export {
   escapeHtml,
   inline,
   prose,
-  Text,
-  Image,
-  Item,
   baseSlide,
   PALETTE,
   LOGO_SVG,
   LAYOUTS,
   getLayout,
+  commonSlideFields,
+  layoutEditorInfo,
+  allLayoutEditorInfo,
+  PLACEHOLDER_IMAGE,
+  isPlaceholderImage,
+  blankSlide,
   SlideSchema,
   DeckSchema,
   validateDeck,
   formatPath,
   formatIssues,
   DeckError,
+  PREVIEW_SIZE,
   collectImageSources,
   renderDeck,
   extractDeckSource,
   parseDeckSource,
   stringifyDeck
 };
-//# sourceMappingURL=chunk-TM3TNVHB.js.map
+//# sourceMappingURL=chunk-7FROOJCY.js.map