@norskvideo/ctl-dev-kit 0.1.37 → 0.1.38

package/doc-guide/build-manual.d.ts

@@ -51,6 +51,14 @@ export interface BuildManualResult {
     /** `<slug>/<file>` of every referenced capture not found on disk. */
     missing: string[];
 }
+/** Where to write de-inlined captures for the standalone manual. `dir` is the
+ *  filesystem directory; `href` (default "images") is the relative URL prefix
+ *  the manual references them by — so `dir` sits at `<manual>/<href>`. */
+export interface ManualAssets {
+    dir: string;
+    href?: string;
+}
 export declare function buildManual(spec: ManualSpec, opts: {
     docsRoot: string;
+    assets?: ManualAssets;
 }): BuildManualResult;

package/doc-guide/build-manual.js

@@ -4,28 +4,37 @@
 //
 // Every screenshot is a real capture a doc-guide wrote under
 // <docsRoot>/<slug>/<slug>-00N.png. This assembler reads those PNGs, resizes each
-// with ImageMagick, inlines it as a data URI, and returns both the Artifact
-// FRAGMENT (index.html — the Artifact tool supplies the doctype/head/body) and a
-// complete STANDALONE document (manual.html — for hosting the manual directly as
-// a page). A referenced shot that hasn't been generated yet renders as a labelled
-// gap rather than crashing the build; every gap is reported in `missing`.
+// with ImageMagick, and returns both the Artifact FRAGMENT (index.html — the
+// Artifact tool supplies the doctype/head/body) and a complete STANDALONE document
+// (manual.html — for hosting the manual directly as a page). A referenced shot that
+// hasn't been generated yet renders as a labelled gap rather than crashing the
+// build; every gap is reported in `missing`.
+//
+// The FRAGMENT always inlines each image as a data URI — Artifacts serve under a
+// CSP that blocks external image hosts, so a self-contained fragment is the only
+// thing that renders there. The STANDALONE inlines too by default, but pass
+// `opts.assets` to write each capture as a sidecar file and reference it by a
+// relative href instead — the shape marketing hosts and zips, where individual
+// images must be liftable rather than buried in base64.
 //
 // Product-specific content — the page arrays, the overview copy, the brand — is
 // supplied by the caller in `ManualSpec`; everything structural (layout, CSS,
 // routing) lives here so every product's manual looks and behaves the same.
 import { spawnSync } from "node:child_process";
-import { existsSync } from "node:fs";
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 const esc = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
-/** Resize a captured PNG to <=1100px wide JPEG and return a data URI. Missing
- *  captures become a labelled placeholder so the manual still builds. */
-function makeUri(docsRoot, slug, file, missing) {
+/** Resize a captured PNG to <=1100px wide JPEG. A missing capture becomes a
+ *  labelled placeholder so the manual still builds, and is recorded in `missing`. */
+function loadAsset(docsRoot, slug, file, missing) {
     const path = join(docsRoot, slug, file);
     if (!existsSync(path)) {
         missing.push(`${slug}/${file}`);
         const label = esc(`missing: ${slug}/${file}`);
-        const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="880" height="200"><rect width="100%" height="100%" fill="#1a2230"/><text x="50%" y="50%" fill="#6b7787" font-family="monospace" font-size="15" text-anchor="middle" dominant-baseline="middle">${label}</text></svg>`;
-        return `data:image/svg+xml;base64,${Buffer.from(svg).toString("base64")}`;
+        return {
+            kind: "svg",
+            text: `<svg xmlns="http://www.w3.org/2000/svg" width="880" height="200"><rect width="100%" height="100%" fill="#1a2230"/><text x="50%" y="50%" fill="#6b7787" font-family="monospace" font-size="15" text-anchor="middle" dominant-baseline="middle">${label}</text></svg>`,
+        };
     }
     const r = spawnSync("magick", [path, "-resize", "1100x>", "-quality", "82", "jpg:-"], {
         maxBuffer: 64 * 1024 * 1024,
@@ -33,43 +42,73 @@ function makeUri(docsRoot, slug, file, missing) {
     if (r.status !== 0 || !r.stdout?.length) {
         throw new Error(`magick failed for ${path}: ${r.stderr?.toString() ?? "no output"}`);
     }
-    return `data:image/jpeg;base64,${r.stdout.toString("base64")}`;
+    return { kind: "jpeg", bytes: r.stdout };
+}
+/** Inline the asset as a data URI (fragment path — always self-contained). */
+function inlineUri(a) {
+    return a.kind === "svg"
+        ? `data:image/svg+xml;base64,${Buffer.from(a.text).toString("base64")}`
+        : `data:image/jpeg;base64,${a.bytes.toString("base64")}`;
+}
+/** Write the asset as a sidecar file under `assets.dir` and return its relative
+ *  href (standalone path). The capture filename convention `<slug>-00N.png` is
+ *  already unique, so the basename (extension swapped for the encoded format) is
+ *  a safe sidecar name. */
+function fileUri(a, file, assets) {
+    const ext = a.kind === "svg" ? "svg" : "jpg";
+    const name = `${file.replace(/\.[^.]+$/, "")}.${ext}`;
+    writeFileSync(join(assets.dir, name), a.kind === "svg" ? Buffer.from(a.text) : a.bytes);
+    return `${assets.href ?? "images"}/${name}`;
 }
 export function buildManual(spec, opts) {
-    const { docsRoot } = opts;
+    const { docsRoot, assets } = opts;
     const missing = [];
-    const uri = (slug, file) => makeUri(docsRoot, slug, file, missing);
+    // Each shot is loaded (resized) at most once, then rendered inline for the
+    // fragment and — when `assets` is set — as a sidecar file for the standalone.
+    const cache = new Map();
+    const load = (slug, file) => {
+        const key = `${slug}/${file}`;
+        let a = cache.get(key);
+        if (!a) {
+            a = loadAsset(docsRoot, slug, file, missing);
+            cache.set(key, a);
+        }
+        return a;
+    };
+    const inline = (slug, file) => inlineUri(load(slug, file));
+    const external = (slug, file) => fileUri(load(slug, file), file, assets);
     const FN = spec.functionality;
     const EX = spec.examples;
     const ALL = [...FN, ...EX];
     const byId = new Map(ALL.map((p) => [p.id, p]));
-    function pageHtml(p) {
-        const steps = p.steps
-            .map((s, i) => `<li class="step">
+    const render = (uri) => {
+        function pageHtml(p) {
+            const steps = p.steps
+                .map((s, i) => `<li class="step">
       <div class="stinfo"><span class="stnum">${String(i + 1).padStart(2, "0")}</span><div><h3>${esc(s.head)}</h3><p>${esc(s.desc)}</p></div></div>
       <div class="shot"><img loading="lazy" src="${uri(s.slug, s.file)}" alt="${esc(s.head)}"></div>
     </li>`)
-            .join("\n");
-        const links = p.links.length
-            ? `<div class="xlinks"><span class="xlab">${p.kind === "fn" ? "Seen in" : "Uses"}</span>${p.links
-                .map((id) => {
-                const t = byId.get(id);
-                return t ? `<a href="#${id}" class="chip">${esc(t.nav)}</a>` : "";
-            })
-                .join("")}</div>`
-            : "";
-        const thin = p.thin
-            ? `<p class="thin">More of this walkthrough is coming — this deployment shape has one screen captured so far.</p>`
-            : "";
-        return `<article class="page" id="${p.id}">
+                .join("\n");
+            const links = p.links.length
+                ? `<div class="xlinks"><span class="xlab">${p.kind === "fn" ? "Seen in" : "Uses"}</span>${p.links
+                    .map((id) => {
+                    const t = byId.get(id);
+                    return t ? `<a href="#${id}" class="chip">${esc(t.nav)}</a>` : "";
+                })
+                    .join("")}</div>`
+                : "";
+            const thin = p.thin
+                ? `<p class="thin">More of this walkthrough is coming — this deployment shape has one screen captured so far.</p>`
+                : "";
+            return `<article class="page" id="${p.id}">
     <div class="phead"><span class="kind ${p.kind}">${p.kind === "fn" ? "Functionality" : "Example deployment"}</span><h1>${esc(p.title)}</h1>${p.tag ? `<div class="ptag mono">${esc(p.tag)}</div>` : ""}</div>
     <p class="lead">${esc(p.intro)}</p>
     <ol class="steps">${steps}</ol>
     ${thin}${links}
   </article>`;
-    }
-    const ov = spec.overview;
-    const overview = `<article class="page" id="overview">
+        }
+        const ov = spec.overview;
+        const overview = `<article class="page" id="overview">
   <div class="phead"><span class="kind ov">Overview</span><h1>${esc(ov.headline)}</h1></div>
   <p class="lead">${esc(ov.lead)}</p>
   <div class="heroshot"><div class="shot"><img src="${uri(ov.hero.slug, ov.hero.file)}" alt="${esc(ov.hero.alt)}"></div><p class="hcap">${esc(ov.hero.caption)}</p></div>
@@ -78,11 +117,11 @@ export function buildManual(spec, opts) {
     <div><h2>${esc(ov.byExampleHeading ?? "By example")}</h2><p class="mini">${esc(ov.byExampleIntro)}</p><div class="linklist">${EX.map((p) => `<a href="#${p.id}">${esc(p.nav)}</a>`).join("")}</div></div>
   </div>
 </article>`;
-    const nav = `
+        const nav = `
   <a href="#overview" data-nav class="ovlink">Overview</a>
   <div class="ngroup"><div class="ghead">Functionality</div>${FN.map((p) => `<a href="#${p.id}" data-nav>${esc(p.nav)}</a>`).join("")}</div>
   <div class="ngroup"><div class="ghead">Examples <span class="ct">${EX.length}</span></div>${EX.map((p) => `<a href="#${p.id}" data-nav>${esc(p.nav)}</a>`).join("")}</div>`;
-    const html = `<title>${esc(spec.title)}</title>
+        const html = `<title>${esc(spec.title)}</title>
 <style>
 :root{--bg:#0a0d12;--bg2:#0c1118;--surf:#131923;--ink:#eaeff5;--dim:#939dab;--faint:#5f6a79;
   --line:#212a36;--accent:#54d6cf;--measure:64ch}
@@ -168,6 +207,16 @@ ${ALL.map(pageHtml).join("\n")}
   window.addEventListener('hashchange',show);show();
 })();
 </script>`;
+        return html;
+    };
+    // Fragment: always inlined (Artifact CSP). Standalone: de-inlined sidecar files
+    // when `assets` is set, otherwise the same inlined body wrapped in a document.
+    const indexHtml = render(inline);
+    let standaloneBody = indexHtml;
+    if (assets) {
+        mkdirSync(assets.dir, { recursive: true });
+        standaloneBody = render(external);
+    }
     const standaloneHtml = `<!doctype html>
 <html lang="en">
 <head>
@@ -176,8 +225,8 @@ ${ALL.map(pageHtml).join("\n")}
 <title>${esc(spec.title)}</title>
 </head>
 <body>
-${html}
+${standaloneBody}
 </body>
 </html>`;
-    return { indexHtml: html, standaloneHtml, missing };
+    return { indexHtml, standaloneHtml, missing };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@norskvideo/ctl-dev-kit",
-  "version": "0.1.37",
+  "version": "0.1.38",
   "type": "module",
   "exports": {
     "./package.json": "./package.json",