@norskvideo/ctl-dev-kit 0.1.38 → 0.1.40

package/conventions/publish-docs.yml

@@ -136,6 +136,21 @@ jobs:
             # the Artifact fragment index.html — ctl hosts it directly as a page.
             man="docs/generated/manual/manual.html"
             [ -s "$man" ] || { echo "::error::manual was not generated at $man"; exit 1; }
+            # This asset is published ALONE, so it must carry its own images.
+            # A manual referencing sidecars renders as a page of broken images
+            # on the ctl docs site, and the only symptom is a release
+            # link-check going red days later -- fail here, where the cause is
+            # visible. Every <img> chunk must carry a data: URI; the leading
+            # dot matches the attribute quote so no escaping is needed here.
+            # Counted rather than tested with grep -qv, whose empty-input exit
+            # status differs between GNU and BSD grep.
+            imgs="$(grep -oE "<img[^>]*src=[^>]*" "$man" || true)"
+            external="$(printf %s "$imgs" | grep -cv "src=.data:" || true)"
+            if [ -n "$imgs" ] && [ "${external:-0}" -gt 0 ]; then
+              echo "::error::manual.html references external images -- publish the self-contained standalone (buildManual standaloneHtml), not the sidecar variant"
+              printf %s "$imgs" | grep -v "src=.data:" | head -5
+              exit 1
+            fi
             cp "$man" "$RUNNER_TEMP/manual.html"
             if ! gh release view docs-latest >/dev/null 2>&1; then
               gh release create docs-latest --title "Docs (latest)" --prerelease \

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

@@ -46,8 +46,13 @@ export interface ManualSpec {
 export interface BuildManualResult {
     /** Artifact-ready fragment (no doctype/head/body). */
     indexHtml: string;
-    /** Complete standalone document wrapping the fragment. */
+    /** Complete standalone document wrapping the fragment. Always self-contained,
+     *  whether or not sidecars were asked for — this is the shape that survives
+     *  being published on its own. */
     standaloneHtml: string;
+    /** The same document referencing the sidecar files instead of inlining them.
+     *  Only present when `assets` is set, and only useful alongside `assets.dir`. */
+    standaloneAssetHtml?: string;
     /** `<slug>/<file>` of every referenced capture not found on disk. */
     missing: string[];
 }

package/doc-guide/build-manual.js

@@ -12,10 +12,13 @@
 //
 // 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.
+// thing that renders there. The STANDALONE is self-contained too, ALWAYS: it is
+// the one file publish-docs uploads on its own, so anything it references by
+// relative href would 404 wherever it lands. Pass `opts.assets` to ADDITIONALLY
+// get `standaloneAssetHtml` plus the captures written as sidecar files — the
+// shape marketing hosts and zips, where individual images must be liftable
+// rather than buried in base64. Both renders share one resize cache, so asking
+// for sidecars costs no extra ImageMagick work.
 //
 // Product-specific content — the page arrays, the overview copy, the brand — is
 // supplied by the caller in `ManualSpec`; everything structural (layout, CSS,
@@ -209,15 +212,7 @@ ${ALL.map(pageHtml).join("\n")}
 </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>
+    const document = (body) => `<!doctype html>
 <html lang="en">
 <head>
 <meta charset="utf-8" />
@@ -225,8 +220,15 @@ ${ALL.map(pageHtml).join("\n")}
 <title>${esc(spec.title)}</title>
 </head>
 <body>
-${standaloneBody}
+${body}
 </body>
 </html>`;
-    return { indexHtml, standaloneHtml, missing };
+    // Fragment and standalone are both inlined (Artifact CSP; publishable on its
+    // own). Sidecars are an EXTRA output, never a substitution.
+    const indexHtml = render(inline);
+    const standaloneHtml = document(indexHtml);
+    if (!assets)
+        return { indexHtml, standaloneHtml, missing };
+    mkdirSync(assets.dir, { recursive: true });
+    return { indexHtml, standaloneHtml, standaloneAssetHtml: document(render(external)), missing };
 }

package/package.json

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