@classic-homes/slides 0.2.0

package/README.md

@@ -0,0 +1,129 @@
+# @classic-homes/slides
+
+Branded Classic Homes presentations from a simple deck file. Pick a layout per
+slide, fill in the words and photos, and get one self-contained HTML file that
+opens in any browser: brand fonts, colours and presenter tools included, no
+internet needed.
+
+Decks are data, layouts own the styling. There is no way to set colours, fonts
+or sizes on a slide, which is what keeps every deck on-brand whether a person
+or an AI agent wrote it.
+
+## Quick start
+
+```bash
+npx classic-slides new decks/closing-day.yaml            # basic starter
+npx classic-slides new decks/orientation.yaml --starter journey
+npx classic-slides dev decks/closing-day.yaml            # live preview, reloads on save
+npx classic-slides build decks/closing-day.yaml          # → decks/closing-day.html
+```
+
+Present: open the HTML, use arrow keys or Space. **N** shows speaker notes,
+**F** goes fullscreen, `#slide-7` in the URL jumps to a slide. Print to PDF
+gives one 16:9 page per slide.
+
+## A deck file
+
+```yaml
+title: Closing Day
+description: What to bring and expect at your closing appointment.
+
+slides:
+  - layout: title
+    kicker: New Homeowner
+    title: Closing day, *simplified*
+    lead: Everything you need for a smooth signing.
+
+  - layout: bullets
+    title: Bring these with you
+    marker: check
+    items:
+      - Photo ID for everyone on the loan
+      - text: Certified funds
+        sub: Never wire money based on an email — call to confirm
+    notes: |
+      Stress wire fraud. Title companies never change wiring instructions by email.
+
+  - layout: split
+    title: Where to go
+    groups:
+      - items: [Arrive 10 minutes early, Plan for about an hour]
+    images:
+      - { src: images/title-office.jpg, alt: Title company front entrance }
+```
+
+Images are paths relative to the deck file (or https URLs); they are inlined
+at build time. Keep photos around 2000px wide — `build` warns about large ones.
+
+Inline text supports `**bold**`, `*highlight*` (brand accent), `` `code` `` and
+`[links](https://…)`. HTML is always escaped.
+
+## Layouts
+
+Run `classic-slides layouts` for the list, `classic-slides layouts <name>` for
+every field plus an example.
+
+| Layout        | Use for                                               |
+| ------------- | ----------------------------------------------------- |
+| `title`       | First slide                                           |
+| `section`     | Chapter divider on a solid colour, optional photo row |
+| `statement`   | One big idea, a transition, a closing line            |
+| `bullets`     | Short checklist, one or two columns                   |
+| `split`       | Text beside 1–4 photos, optional callout badge        |
+| `cards`       | 3–8 peers: services, options, people                  |
+| `stats`       | 2–6 numbers worth remembering                         |
+| `comparison`  | 2–3 columns side by side                              |
+| `journey`     | Numbered agenda map (uses `journey.steps`)            |
+| `photos`      | A grid of photos: team, products, homes               |
+| `image`       | One big image or diagram                              |
+| `walkthrough` | Ordered stages, one slide each with a progress rail   |
+| `quote`       | A testimonial or pull quote                           |
+| `qr`          | Send people to a URL with a scannable code            |
+| `contacts`    | Who to call                                           |
+
+Every slide also accepts `track` (value/red, build/teal, neutral/navy),
+`background` (paper or a solid brand colour), `notes`, `time`, `id`, and — in
+decks with `journey.steps` — `step`, `stepDone` and `showJourney`.
+
+`classic-slides guide` prints the writing rules; `classic-slides validate`
+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.
+
+```bash
+claude mcp add classic-slides -- npx -y @classic-homes/slides mcp --root ./decks
+```
+
+Then ask: _"Build a 10-slide deck in closing-day.yaml for first-time buyers
+about closing day, then build it."_
+
+Tools: `list_layouts`, `get_layout`, `get_authoring_guide`, `create_deck`,
+`read_deck`, `update_deck`, `add_slide`, `add_slides`, `update_slide`,
+`move_slide`, `delete_slide`, `validate_deck`, `build_deck`. Prompt:
+`build_deck_from_outline`. File access is confined to `--root` (default: the
+working directory).
+
+## As a library
+
+```ts
+import { renderDeck, validateDeck, listLayouts } from '@classic-homes/slides';
+import { buildDeckFile, fileImageResolver } from '@classic-homes/slides/node';
+
+const { html } = await renderDeck(deck, { resolveImage: (src) => lookUp(src) });
+```
+
+The core entry has no Node dependencies (it runs in Workers); `/node` adds
+file-based image loading and `buildDeckFile`.
+
+Rendered HTML embeds the deck source (minus image data), so
+`extractDeckSource(html)` recovers the editable deck.
+
+## Brand
+
+Colours come from `@classic-homes/theme-tokens`. Fonts (Figtree, Spectral) are
+embedded from `assets/fonts`. Styling lives in `src/styles.ts`; add a layout in
+`src/layouts/` and register it in `src/layouts/index.ts` — its example is
+tested automatically.

package/dist/chunk-CKVKX2ZD.js

@@ -0,0 +1,76 @@
+import {
+  parseDeckSource,
+  renderDeck,
+  stringifyDeck
+} from "./chunk-TM3TNVHB.js";
+
+// src/node/index.ts
+import { readFile, stat, writeFile } from "fs/promises";
+import { dirname, extname, isAbsolute, join, resolve } from "path";
+var MIME = {
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".png": "image/png",
+  ".webp": "image/webp",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".avif": "image/avif"
+};
+var IMAGE_WARN_BYTES = 800 * 1024;
+function fileImageResolver(baseDir, options = {}) {
+  const warn = options.onWarning ?? (() => {
+  });
+  return async (src) => {
+    if (src.startsWith("data:")) return src;
+    if (/^https?:/.test(src)) {
+      if (options.inlineRemote === false) return src;
+      const res = await fetch(src);
+      if (!res.ok) throw new Error(`Image ${src} returned HTTP ${res.status}`);
+      const type2 = res.headers.get("content-type") ?? "application/octet-stream";
+      const buf2 = Buffer.from(await res.arrayBuffer());
+      if (buf2.length > IMAGE_WARN_BYTES)
+        warn(`${src} is ${(buf2.length / 1024).toFixed(0)} KB; consider a smaller copy.`);
+      return `data:${type2};base64,${buf2.toString("base64")}`;
+    }
+    const path = isAbsolute(src) ? src : join(baseDir, src);
+    const type = MIME[extname(path).toLowerCase()];
+    if (!type)
+      throw new Error(`Unsupported image type for "${src}". Use jpg, png, webp, gif, svg or avif.`);
+    let buf;
+    try {
+      buf = await readFile(path);
+    } catch {
+      throw new Error(`Image not found: "${src}" (looked in ${path})`);
+    }
+    if (buf.length > IMAGE_WARN_BYTES)
+      warn(`${src} is ${(buf.length / 1024).toFixed(0)} KB; consider resizing to ~2000px wide.`);
+    return `data:${type};base64,${buf.toString("base64")}`;
+  };
+}
+async function loadDeckFile(path) {
+  return parseDeckSource(await readFile(path, "utf8"));
+}
+async function saveDeckFile(path, deck) {
+  const text = path.endsWith(".json") ? JSON.stringify(deck, null, 2) + "\n" : stringifyDeck(deck);
+  await writeFile(path, text);
+}
+async function buildDeckFile(path, options = {}) {
+  const abs = resolve(path);
+  const deck = await loadDeckFile(abs);
+  const result = await renderDeck(deck, {
+    ...options,
+    resolveImage: fileImageResolver(dirname(abs), options)
+  });
+  const out = options.out ? resolve(options.out) : abs.replace(/\.(ya?ml|json)$/i, "") + ".html";
+  await writeFile(out, result.html);
+  return { ...result, out, bytes: (await stat(out)).size };
+}
+
+export {
+  IMAGE_WARN_BYTES,
+  fileImageResolver,
+  loadDeckFile,
+  saveDeckFile,
+  buildDeckFile
+};
+//# sourceMappingURL=chunk-CKVKX2ZD.js.map

package/dist/chunk-CKVKX2ZD.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/node/index.ts"],"sourcesContent":["/** Node-only helpers: read deck files, inline local images, write HTML. */\nimport { readFile, stat, writeFile } from 'node:fs/promises';\nimport { dirname, extname, isAbsolute, join, resolve } from 'node:path';\nimport { parseDeckSource, stringifyDeck } from '../parse.js';\nimport {\n  renderDeck,\n  type ImageResolver,\n  type RenderOptions,\n  type RenderResult,\n} from '../render.js';\n\nconst MIME: Record<string, string> = {\n  '.jpg': 'image/jpeg',\n  '.jpeg': 'image/jpeg',\n  '.png': 'image/png',\n  '.webp': 'image/webp',\n  '.gif': 'image/gif',\n  '.svg': 'image/svg+xml',\n  '.avif': 'image/avif',\n};\n\n/** Largest single image we inline without warning. Big photos bloat the deck file. */\nexport const IMAGE_WARN_BYTES = 800 * 1024;\n\nexport interface FileResolverOptions {\n  /** Fetch https images and inline them so the deck works offline. Default true. */\n  inlineRemote?: boolean;\n  onWarning?: (message: string) => void;\n}\n\n/** Resolves image paths relative to the deck file and inlines them as data URIs. */\nexport function fileImageResolver(\n  baseDir: string,\n  options: FileResolverOptions = {}\n): ImageResolver {\n  const warn = options.onWarning ?? (() => {});\n  return async (src) => {\n    if (src.startsWith('data:')) return src;\n    if (/^https?:/.test(src)) {\n      if (options.inlineRemote === false) return src;\n      const res = await fetch(src);\n      if (!res.ok) throw new Error(`Image ${src} returned HTTP ${res.status}`);\n      const type = res.headers.get('content-type') ?? 'application/octet-stream';\n      const buf = Buffer.from(await res.arrayBuffer());\n      if (buf.length > IMAGE_WARN_BYTES)\n        warn(`${src} is ${(buf.length / 1024).toFixed(0)} KB; consider a smaller copy.`);\n      return `data:${type};base64,${buf.toString('base64')}`;\n    }\n    const path = isAbsolute(src) ? src : join(baseDir, src);\n    const type = MIME[extname(path).toLowerCase()];\n    if (!type)\n      throw new Error(`Unsupported image type for \"${src}\". Use jpg, png, webp, gif, svg or avif.`);\n    let buf: Buffer;\n    try {\n      buf = await readFile(path);\n    } catch {\n      throw new Error(`Image not found: \"${src}\" (looked in ${path})`);\n    }\n    if (buf.length > IMAGE_WARN_BYTES)\n      warn(`${src} is ${(buf.length / 1024).toFixed(0)} KB; consider resizing to ~2000px wide.`);\n    return `data:${type};base64,${buf.toString('base64')}`;\n  };\n}\n\nexport async function loadDeckFile(path: string): Promise<unknown> {\n  return parseDeckSource(await readFile(path, 'utf8'));\n}\n\nexport async function saveDeckFile(path: string, deck: unknown): Promise<void> {\n  const text = path.endsWith('.json') ? JSON.stringify(deck, null, 2) + '\\n' : stringifyDeck(deck);\n  await writeFile(path, text);\n}\n\nexport interface BuildOptions extends Omit<RenderOptions, 'resolveImage'>, FileResolverOptions {\n  out?: string;\n}\n\n/** Renders a deck file to a self-contained HTML file next to it (or at `out`). */\nexport async function buildDeckFile(\n  path: string,\n  options: BuildOptions = {}\n): Promise<RenderResult & { out: string; bytes: number }> {\n  const abs = resolve(path);\n  const deck = await loadDeckFile(abs);\n  const result = await renderDeck(deck, {\n    ...options,\n    resolveImage: fileImageResolver(dirname(abs), options),\n  });\n  const out = options.out ? resolve(options.out) : abs.replace(/\\.(ya?ml|json)$/i, '') + '.html';\n  await writeFile(out, result.html);\n  return { ...result, out, bytes: (await stat(out)).size };\n}\n\nexport { renderDeck };\n"],"mappings":";;;;;;;AACA,SAAS,UAAU,MAAM,iBAAiB;AAC1C,SAAS,SAAS,SAAS,YAAY,MAAM,eAAe;AAS5D,IAAM,OAA+B;AAAA,EACnC,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,QAAQ;AAAA,EACR,SAAS;AAAA,EACT,QAAQ;AAAA,EACR,QAAQ;AAAA,EACR,SAAS;AACX;AAGO,IAAM,mBAAmB,MAAM;AAS/B,SAAS,kBACd,SACA,UAA+B,CAAC,GACjB;AACf,QAAM,OAAO,QAAQ,cAAc,MAAM;AAAA,EAAC;AAC1C,SAAO,OAAO,QAAQ;AACpB,QAAI,IAAI,WAAW,OAAO,EAAG,QAAO;AACpC,QAAI,WAAW,KAAK,GAAG,GAAG;AACxB,UAAI,QAAQ,iBAAiB,MAAO,QAAO;AAC3C,YAAM,MAAM,MAAM,MAAM,GAAG;AAC3B,UAAI,CAAC,IAAI,GAAI,OAAM,IAAI,MAAM,SAAS,GAAG,kBAAkB,IAAI,MAAM,EAAE;AACvE,YAAMA,QAAO,IAAI,QAAQ,IAAI,cAAc,KAAK;AAChD,YAAMC,OAAM,OAAO,KAAK,MAAM,IAAI,YAAY,CAAC;AAC/C,UAAIA,KAAI,SAAS;AACf,aAAK,GAAG,GAAG,QAAQA,KAAI,SAAS,MAAM,QAAQ,CAAC,CAAC,+BAA+B;AACjF,aAAO,QAAQD,KAAI,WAAWC,KAAI,SAAS,QAAQ,CAAC;AAAA,IACtD;AACA,UAAM,OAAO,WAAW,GAAG,IAAI,MAAM,KAAK,SAAS,GAAG;AACtD,UAAM,OAAO,KAAK,QAAQ,IAAI,EAAE,YAAY,CAAC;AAC7C,QAAI,CAAC;AACH,YAAM,IAAI,MAAM,+BAA+B,GAAG,0CAA0C;AAC9F,QAAI;AACJ,QAAI;AACF,YAAM,MAAM,SAAS,IAAI;AAAA,IAC3B,QAAQ;AACN,YAAM,IAAI,MAAM,qBAAqB,GAAG,gBAAgB,IAAI,GAAG;AAAA,IACjE;AACA,QAAI,IAAI,SAAS;AACf,WAAK,GAAG,GAAG,QAAQ,IAAI,SAAS,MAAM,QAAQ,CAAC,CAAC,yCAAyC;AAC3F,WAAO,QAAQ,IAAI,WAAW,IAAI,SAAS,QAAQ,CAAC;AAAA,EACtD;AACF;AAEA,eAAsB,aAAa,MAAgC;AACjE,SAAO,gBAAgB,MAAM,SAAS,MAAM,MAAM,CAAC;AACrD;AAEA,eAAsB,aAAa,MAAc,MAA8B;AAC7E,QAAM,OAAO,KAAK,SAAS,OAAO,IAAI,KAAK,UAAU,MAAM,MAAM,CAAC,IAAI,OAAO,cAAc,IAAI;AAC/F,QAAM,UAAU,MAAM,IAAI;AAC5B;AAOA,eAAsB,cACpB,MACA,UAAwB,CAAC,GAC+B;AACxD,QAAM,MAAM,QAAQ,IAAI;AACxB,QAAM,OAAO,MAAM,aAAa,GAAG;AACnC,QAAM,SAAS,MAAM,WAAW,MAAM;AAAA,IACpC,GAAG;AAAA,IACH,cAAc,kBAAkB,QAAQ,GAAG,GAAG,OAAO;AAAA,EACvD,CAAC;AACD,QAAM,MAAM,QAAQ,MAAM,QAAQ,QAAQ,GAAG,IAAI,IAAI,QAAQ,oBAAoB,EAAE,IAAI;AACvF,QAAM,UAAU,KAAK,OAAO,IAAI;AAChC,SAAO,EAAE,GAAG,QAAQ,KAAK,QAAQ,MAAM,KAAK,GAAG,GAAG,KAAK;AACzD;","names":["type","buf"]}