@classic-homes/slides 0.2.0 → 0.3.0

package/README.md

@@ -63,38 +63,82 @@ Inline text supports `**bold**`, `*highlight*` (brand accent), `` `code` `` and
 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                                           |
+| Group              | Layouts                                                                                                                                         |
+| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| Openers & dividers | `title`, `section`, `statement`, `journey`                                                                                                      |
+| Text               | `bullets`, `cards`, `comparison`, `quote`                                                                                                       |
+| Data               | `stats` (with trends + sparklines), `chart`, `table`                                                                                            |
+| Diagrams           | `flow`, `timeline`, `cycle`, `hierarchy`, `matrix`, `tiers` (funnel / pyramid)                                                                  |
+| Media              | `split`, `photos`, `image` (with numbered hotspots), `compare` (before/after), `walkthrough`, `video` (YouTube/Vimeo), `embed` (any https page) |
+| People & places    | `qr`, `contacts`                                                                                                                                |
 
 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`.
+`background` (paper or a solid brand colour), `backgroundImage` + `overlay`,
+`notes`, `time`, `id`, `hidden`, and — in decks with `journey.steps` — `step`,
+`stepDone` and `showJourney`. `bullets`, `cards`, `flow` and `timeline` take
+`build: true` to reveal one item per click.
 
-`classic-slides guide` prints the writing rules; `classic-slides validate`
-flags errors and crowded slides.
+### Charts
+
+```yaml
+- layout: chart
+  title: Closings *doubled* since spring
+  chart:
+    type: column # bar, stacked-column, stacked-bar, line, area, pie, donut, funnel, gauge, scatter, radar
+    labels: [Q1, Q2, Q3, Q4]
+    series: [{ name: Closings, values: [42, 61, 88, 94] }]
+    unit: homes
+    highlight: Q4
+  insights: [Q4 best quarter on record]
+  source: Sales ops
+```
+
+Charts are rendered to static SVG with ECharts (server-side rendering, themed
+from `@classic-homes/charts-core`), so they work offline and in print. ECharts
+is loaded only when a deck has charts.
+
+### Video and embeds
+
+`video` takes YouTube/Vimeo links (privacy-enhanced players); `embed` takes any
+https page (maps, dashboards, 3D tours, forms) in a sandboxed frame. Both load
+only while their slide is shown, and fall back to a poster/screenshot with a QR
+code offline, in print and in PDF.
+
+## Brand profiles and deck settings
+
+```yaml
+brand:
+  profile: pentrust # admin-managed profile; default classic-homes
+  name: PenTrust Lending # optional overrides: name, tagline, logo, logoOnDark, favicon, footer
+settings:
+  slideNumbers: true
+  logo: all # title | all | none
+  confidential: Internal
+  autoAdvance: 15 # kiosk mode (also ?kiosk=15 on the URL)
+  loop: true
+```
+
+Profiles (`BrandProfile`) carry name, logos, favicon, footer and an optional
+palette; `validateBrandProfile()` enforces WCAG AA contrast. Pass them to
+`renderDeck(deck, { brands })` / `validateDeck(deck, { brands })`. Authors can
+override words and images, never colours.
+
+## Presenting
+
+Arrow keys / Space advance (and step through reveals) · **N** notes · **P**
+presenter window (current + next slide, notes, timer, clock) · **O** overview ·
+**F** fullscreen · `#slide-7` deep links · `?kiosk=15` loops unattended. Print
+to PDF gives one 16:9 page per slide with media fallbacks.
 
 ## 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
@@ -115,8 +159,13 @@ 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`.
+The core entry has no Node dependencies (it runs in Workers and browsers);
+`/node` adds file-based image loading and `buildDeckFile`. For editors,
+`layoutEditorInfo()` / `deckEditorFields()` describe every field as a widget
+(with `hint`s for chart, grid, url, video-url and point pickers),
+`blankSlide(layout)` gives a valid starting slide, and `renderDeck(deck,
+{ includeHidden: true, initialSlide })` plus the `postMessage` API drive a
+live preview.
 
 Rendered HTML embeds the deck source (minus image data), so
 `extractDeckSource(html)` recovers the editable deck.

package/dist/{chunk-CKVKX2ZD.js → chunk-2IPLZ3SA.js}

@@ -2,11 +2,38 @@ import {
   parseDeckSource,
   renderDeck,
   stringifyDeck
-} from "./chunk-TM3TNVHB.js";
+} from "./chunk-GXGDPBAR.js";
 
 // src/node/index.ts
 import { readFile, stat, writeFile } from "fs/promises";
-import { dirname, extname, isAbsolute, join, resolve } from "path";
+import { dirname as dirname2, extname, isAbsolute, join, resolve as resolve2 } from "path";
+
+// src/node/paths.ts
+import { lstatSync, realpathSync } from "fs";
+import { dirname, relative, resolve, sep } from "path";
+function confinedPath(root, path) {
+  const canonicalRoot = realpathSync(root);
+  const absolute = resolve(path);
+  let ancestor = absolute;
+  for (; ; ) {
+    try {
+      const canonical = resolve(realpathSync(ancestor), relative(ancestor, absolute));
+      if (canonical !== canonicalRoot && !canonical.startsWith(canonicalRoot + sep)) {
+        throw new Error(`Path "${path}" is outside the deck root ${root}.`);
+      }
+      return canonical;
+    } catch (error) {
+      if (error.code !== "ENOENT" || ancestor === dirname(ancestor))
+        throw error;
+      if (lstatSync(ancestor, { throwIfNoEntry: false })?.isSymbolicLink()) {
+        throw new Error(`Cannot follow dangling symlink "${ancestor}".`);
+      }
+      ancestor = dirname(ancestor);
+    }
+  }
+}
+
+// src/node/index.ts
 var MIME = {
   ".jpg": "image/jpeg",
   ".jpeg": "image/jpeg",
@@ -32,7 +59,8 @@ function fileImageResolver(baseDir, options = {}) {
         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 candidate = isAbsolute(src) ? src : join(baseDir, src);
+    const path = options.rootDir ? confinedPath(options.rootDir, candidate) : candidate;
     const type = MIME[extname(path).toLowerCase()];
     if (!type)
       throw new Error(`Unsupported image type for "${src}". Use jpg, png, webp, gif, svg or avif.`);
@@ -55,22 +83,24 @@ async function saveDeckFile(path, deck) {
   await writeFile(path, text);
 }
 async function buildDeckFile(path, options = {}) {
-  const abs = resolve(path);
+  const abs = options.rootDir ? confinedPath(options.rootDir, resolve2(path)) : resolve2(path);
   const deck = await loadDeckFile(abs);
   const result = await renderDeck(deck, {
     ...options,
-    resolveImage: fileImageResolver(dirname(abs), options)
+    resolveImage: fileImageResolver(dirname2(abs), options)
   });
-  const out = options.out ? resolve(options.out) : abs.replace(/\.(ya?ml|json)$/i, "") + ".html";
+  const candidate = options.out ? resolve2(options.out) : abs.replace(/\.(ya?ml|json)$/i, "") + ".html";
+  const out = options.rootDir ? confinedPath(options.rootDir, candidate) : candidate;
   await writeFile(out, result.html);
   return { ...result, out, bytes: (await stat(out)).size };
 }
 
 export {
+  confinedPath,
   IMAGE_WARN_BYTES,
   fileImageResolver,
   loadDeckFile,
   saveDeckFile,
   buildDeckFile
 };
-//# sourceMappingURL=chunk-CKVKX2ZD.js.map
+//# sourceMappingURL=chunk-2IPLZ3SA.js.map

package/dist/chunk-2IPLZ3SA.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/node/index.ts","../src/node/paths.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 { confinedPath } from './paths.js';\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  /** Restrict local image reads and build paths to this root (used by the MCP server). */\n  rootDir?: string;\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 candidate = isAbsolute(src) ? src : join(baseDir, src);\n    const path = options.rootDir ? confinedPath(options.rootDir, candidate) : candidate;\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 = options.rootDir ? confinedPath(options.rootDir, resolve(path)) : 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 candidate = options.out\n    ? resolve(options.out)\n    : abs.replace(/\\.(ya?ml|json)$/i, '') + '.html';\n  const out = options.rootDir ? confinedPath(options.rootDir, candidate) : candidate;\n  await writeFile(out, result.html);\n  return { ...result, out, bytes: (await stat(out)).size };\n}\n\nexport { renderDeck };\n","/** Canonical containment for existing files and new output files. */\nimport { lstatSync, realpathSync } from 'node:fs';\nimport { dirname, relative, resolve, sep } from 'node:path';\n\nexport function confinedPath(root: string, path: string): string {\n  const canonicalRoot = realpathSync(root);\n  const absolute = resolve(path);\n  let ancestor = absolute;\n  for (;;) {\n    try {\n      const canonical = resolve(realpathSync(ancestor), relative(ancestor, absolute));\n      if (canonical !== canonicalRoot && !canonical.startsWith(canonicalRoot + sep)) {\n        throw new Error(`Path \"${path}\" is outside the deck root ${root}.`);\n      }\n      return canonical;\n    } catch (error) {\n      if ((error as NodeJS.ErrnoException).code !== 'ENOENT' || ancestor === dirname(ancestor))\n        throw error;\n      if (lstatSync(ancestor, { throwIfNoEntry: false })?.isSymbolicLink()) {\n        throw new Error(`Cannot follow dangling symlink \"${ancestor}\".`);\n      }\n      ancestor = dirname(ancestor);\n    }\n  }\n}\n"],"mappings":"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","names":["dirname","resolve","type","buf","resolve","dirname"]}