@kaydash9999/banker-plugins 0.15.1 → 0.16.0

package/skills/3d-intro-build/references/assemble.mjs

@@ -2,32 +2,45 @@
 /*
  * First-party assembler for the 3d-intro-build skill.
  *
- * Takes a project directory that already holds the generated stills + forward-chained clips
- * (+ an intro.json manifest describing them) and produces a self-contained preview site:
+ * Takes a project directory that already holds the generated stills + clips (+ an intro.json
+ * manifest describing them) and produces the intro page:
  *   <outDir>/
- *     index.html            (written from index-template.html, wired to the manifest)
+ *     index.html            (head of index-template.html; no inline script or style)
  *     scrub-engine.js       (copied verbatim from references/)
+ *     scrub-engine.css      (the CSS the engine injects, taken from scrub-engine.js unchanged)
+ *     scrub-engine.LICENSE.txt (scroll-world's MIT notice, which ships with the engine files)
+ *     theme.css             (the template's --sw-* tokens, set from the manifest theme)
+ *     intro-fixes.css       (layout, button text and overflow fixes for the engine, every page)
+ *     intro.js              (the mountScrollWorld config and call)
+ *     panel-glass.css       (only with "panel": "glass")
+ *     step-nav.js/.css      (only with "stepNav": scene-by-scene navigation)
  *     assets/<id>.<ext>     (scene posters/stills)
- *     assets/vid/<id>.mp4   (per-scene dive clips)
- *     assets/vid/connN.mp4  (optional connectors)
- * Serve <outDir> with serve.mjs to preview.
+ *     assets/vid/<id>.mp4   (per-scene clips: dives, or the short holds of the hold-and-flight mode)
+ *     assets/vid/connN.mp4  (optional connectors: the flights between scenes)
+ * Nothing inline, so the page runs under a strict Content-Security-Policy (no 'unsafe-inline';
+ * media-src needs blob:). The engine still tries to inject its <style>: a site with a CSP adds the
+ * reported `styleHash` to style-src to keep that refusal out of the console (scrub-engine.css
+ * carries the same rules either way). Serve <outDir> with serve.mjs (--csp to check under a policy).
  *
- * Runtime: Node >=18 builtins ONLY (node:fs / node:path / node:url). No external deps,
- * no shell — cross-platform (path.join / path.sep; asset URLs are always posix '/').
+ * Runtime: Node >=18 builtins ONLY (node:fs / node:path / node:url / node:crypto). No external
+ * deps, no shell; cross-platform (path.join / path.sep; asset URLs are always posix '/').
  *
  * The manifest (intro.json) mirrors the mountScrollWorld config, but its `still` / `clip` /
  * `connectors` values are paths to SOURCE files relative to projectDir; this assembler copies
  * them into assets/ and rewrites the config to the copied relative URLs. Shape:
  *
  *   {
- *     "pageTitle": "BRAND — the world of SUBJECT",   // optional (else derived)
+ *     "pageTitle": "BRAND - the world of SUBJECT",    // optional (else derived)
  *     "pageDescription": "Scroll to fly through ...", // optional (else derived)
+ *     "lang": "ko",                                     // optional <html lang> (template: en)
  *     "brand": { "name": "BRAND", "href": "#top" },   // optional
  *     "cta":   { "label": "Order now", "href": "#finale" }, // optional top-bar CTA
  *     "hint":  "scroll to fly in",                     // optional
  *     "theme": { "bg":"#F5EDE0","ink":"#241d2b","inkSoft":"#6a6072","accent":"#9B7EBD" }, // optional
  *     "diveScroll": 1.3, "connScroll": 0.9, "crossfade": 0.12, // optional
  *     "nav": true, "atmosphere": true,                 // optional (only false is emitted)
+ *     "panel": "glass",                                 // optional frosted-glass copy panel
+ *     "stepNav": { "end": "#main", ... },              // optional, see step-nav.js for the options
  *     "sections": [                                     // required, >= 1, in order
  *       { "id":"sceneA", "label":"Scene A",
  *         "still":"still-1.png",  "clip":"dive-1.mp4",       // required (relative to projectDir)
@@ -47,6 +60,7 @@
  *     outDir       output site dir (default: <projectDir>/site)
  *     --manifest   manifest path (default: <projectDir>/intro.json)
  */
+import crypto from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -73,6 +87,53 @@ const extOf = (p) => path.extname(String(p)).toLowerCase();
 
 // ---- config build -----------------------------------------------------------
 
+// The copy and pacing fields a section carries over to the engine as they are.
+const SECTION_FIELDS = ['accent', 'eyebrow', 'title', 'body', 'scroll', 'linger', 'cta'];
+// Where each media field of a section is copied (the source extension is kept).
+const MEDIA = [
+  ['still', (id, src) => `assets/${id}${extOf(src)}`],
+  ['stillMobile', (id, src) => `assets/${id}-m${extOf(src)}`],
+  ['clip', (id, src) => `assets/vid/${id}${extOf(src) || '.mp4'}`],
+  ['clipMobile', (id, src) => `assets/vid/${id}-m${extOf(src) || '.mp4'}`],
+];
+
+function requireFields(s, i) {
+  if (!s || !s.id) throw new Error(`assemble: section[${i}] missing "id"`);
+  for (const k of ['still', 'clip']) if (!s[k]) throw new Error(`assemble: section[${i}] (${s.id}) missing "${k}"`);
+}
+
+// One section of the engine config, its still and clips copied into assets/.
+function sectionOut(s, i, copy) {
+  requireFields(s, i);
+  const out = { id: s.id, label: s.label || s.id };
+  for (const [k, dest] of MEDIA) if (s[k]) out[k] = copy(s[k], dest(s.id, s[k]));
+  for (const k of SECTION_FIELDS) if (s[k] != null && s[k] !== '') out[k] = s[k];
+  if (Array.isArray(s.tags) && s.tags.length) out.tags = s.tags;
+  return out;
+}
+
+// Connectors: one per gap between sections, in order; a null entry means "crossfade directly".
+function connectorsOut(list, n, suffix, copy) {
+  const src = Array.isArray(list) ? list : [];
+  return Array.from({ length: Math.max(0, n - 1) }, (_, i) => (src[i]
+    ? copy(src[i], `assets/vid/conn${i + 1}${suffix}${extOf(src[i]) || '.mp4'}`) : null));
+}
+
+// The config in the shape mountScrollWorld reads (see scrub-engine.js).
+function engineConfig(m, sections, connectors, connectorsMobile) {
+  const config = {};
+  for (const k of ['brand', 'cta']) if (m[k]) config[k] = m[k];
+  config.hint = m.hint || 'scroll to fly in';
+  config.diveScroll = m.diveScroll ?? 1.3;
+  config.connScroll = m.connScroll ?? 0.9;
+  if (m.crossfade != null) config.crossfade = m.crossfade;
+  for (const k of ['nav', 'atmosphere']) if (m[k] === false) config[k] = false;
+  config.sections = sections;
+  config.connectors = connectors;
+  if (connectorsMobile.some(Boolean)) config.connectorsMobile = connectorsMobile;
+  return config;
+}
+
 /**
  * Build the exact mountScrollWorld config object from a manifest, copying every referenced
  * asset into outDir/assets. Returns { config, copied:[destPosix,...] }.
@@ -80,120 +141,118 @@ const extOf = (p) => path.extname(String(p)).toLowerCase();
 function buildConfig(manifest, projectDir, outDir) {
   const sections = Array.isArray(manifest.sections) ? manifest.sections : [];
   if (sections.length === 0) throw new Error('assemble: manifest.sections must have at least one section');
-
   const copied = [];
-  const track = (destPosix) => { copied.push(destPosix); return destPosix; };
-
-  const sectionsOut = sections.map((s, i) => {
-    if (!s || !s.id) throw new Error(`assemble: section[${i}] missing "id"`);
-    if (!s.still) throw new Error(`assemble: section[${i}] (${s.id}) missing "still"`);
-    if (!s.clip) throw new Error(`assemble: section[${i}] (${s.id}) missing "clip"`);
-
-    const out = { id: s.id, label: s.label || s.id };
-
-    // poster still (keep source extension so png/webp/jpg all work)
-    out.still = track(copyAsset(projectDir, outDir, s.still, `assets/${s.id}${extOf(s.still)}`));
-    if (s.stillMobile) {
-      out.stillMobile = track(copyAsset(projectDir, outDir, s.stillMobile, `assets/${s.id}-m${extOf(s.stillMobile)}`));
-    }
-
-    // dive clip
-    out.clip = track(copyAsset(projectDir, outDir, s.clip, `assets/vid/${s.id}${extOf(s.clip) || '.mp4'}`));
-    if (s.clipMobile) {
-      out.clipMobile = track(copyAsset(projectDir, outDir, s.clipMobile, `assets/vid/${s.id}-m${extOf(s.clipMobile) || '.mp4'}`));
-    }
-
-    if (s.accent) out.accent = s.accent;
-    if (s.eyebrow) out.eyebrow = s.eyebrow;
-    if (s.title) out.title = s.title;
-    if (s.body) out.body = s.body;
-    if (Array.isArray(s.tags) && s.tags.length) out.tags = s.tags;
-    if (s.scroll != null) out.scroll = s.scroll;
-    if (s.linger != null) out.linger = s.linger;
-    if (s.cta) out.cta = s.cta; // last section only (engine renders it wherever present)
-    return out;
-  });
-
-  // connectors: length === sections.length - 1; null entries mean "crossfade directly".
-  const srcConn = Array.isArray(manifest.connectors) ? manifest.connectors : [];
-  const srcConnM = Array.isArray(manifest.connectorsMobile) ? manifest.connectorsMobile : [];
-  const connectorsOut = [];
-  const connectorsMobileOut = [];
-  for (let i = 0; i < sectionsOut.length - 1; i++) {
-    const c = srcConn[i];
-    connectorsOut.push(c ? track(copyAsset(projectDir, outDir, c, `assets/vid/conn${i + 1}${extOf(c) || '.mp4'}`)) : null);
-    const cm = srcConnM[i];
-    connectorsMobileOut.push(cm ? track(copyAsset(projectDir, outDir, cm, `assets/vid/conn${i + 1}-m${extOf(cm) || '.mp4'}`)) : null);
-  }
-
-  // Assemble in the shape mountScrollWorld reads (see scrub-engine.js).
-  const config = {};
-  if (manifest.brand) config.brand = manifest.brand;
-  if (manifest.cta) config.cta = manifest.cta;
-  config.hint = manifest.hint || 'scroll to fly in';
-  config.diveScroll = manifest.diveScroll != null ? manifest.diveScroll : 1.3;
-  config.connScroll = manifest.connScroll != null ? manifest.connScroll : 0.9;
-  if (manifest.crossfade != null) config.crossfade = manifest.crossfade;
-  if (manifest.nav === false) config.nav = false;
-  if (manifest.atmosphere === false) config.atmosphere = false;
-  config.sections = sectionsOut;
-  config.connectors = connectorsOut;
-  if (connectorsMobileOut.some(Boolean)) config.connectorsMobile = connectorsMobileOut;
-
-  return { config, copied };
+  const copy = (src, dest) => { copied.push(copyAsset(projectDir, outDir, src, dest)); return dest; };
+  const sectionsOut = sections.map((s, i) => sectionOut(s, i, copy));
+  const connectors = connectorsOut(manifest.connectors, sectionsOut.length, '', copy);
+  const connectorsMobile = connectorsOut(manifest.connectorsMobile, sectionsOut.length, '-m', copy);
+  return { config: engineConfig(manifest, sectionsOut, connectors, connectorsMobile), copied };
 }
 
-// ---- index.html generation --------------------------------------------------
+// ---- page generation -------------------------------------------------------
+
+const PANELS = { glass: 'panel-glass.css' };
+
+/**
+ * The CSS the engine injects into <head>, exactly: the `css` template literal wrapped in @layer sw.
+ * A template literal turns CRLF and CR into LF, so a checkout with CRLF line ends (git on Windows)
+ * is read the same way and gives the same hash.
+ */
+export function engineCss(rawSource) {
+  const engineSource = String(rawSource).replace(/\r\n?/g, '\n');
+  const open = engineSource.indexOf('const css = `');
+  const close = open === -1 ? -1 : engineSource.indexOf('`;', open + 13);
+  if (close === -1) throw new Error('assemble: scrub-engine.js no longer holds `const css = `...``');
+  const css = engineSource.slice(open + 13, close);
+  if (/\\|\$\{/.test(css)) throw new Error('assemble: the engine CSS has escapes or substitutions; copy it by hand');
+  return '@layer sw {\n' + css + '\n}';
+}
 
-// Replace the value of a --sw-* custom property in the template's :root block, keeping comments.
-function setToken(html, name, value) {
-  if (!value) return html;
+// Replace the value of a --sw-* custom property, keeping comments.
+function setToken(css, name, value) {
+  if (!value) return css;
   const re = new RegExp(`(--${name}\\s*:\\s*)[^;]+;`);
-  return html.replace(re, `$1${value};`);
+  return css.replace(re, `$1${value};`);
+}
+
+// The template's inline theme block, with the manifest's colours, as a stylesheet.
+function themeCss(styleInner, theme = {}) {
+  let css = setToken(styleInner, 'sw-bg', theme.bg);
+  css = setToken(css, 'sw-ink', theme.ink);
+  css = setToken(css, 'sw-ink-soft', theme.inkSoft);
+  css = setToken(css, 'sw-accent', theme.accent);
+  return css.replace(/^\n+/, '').replace(/\s*$/, '\n');
+}
+
+function stylesheets(manifest) {
+  return ['scrub-engine.css', 'theme.css', 'intro-fixes.css', manifest.panel ? PANELS[manifest.panel] : null,
+    manifest.stepNav ? 'step-nav.css' : null].filter(Boolean);
 }
 
-/** Render index.html from index-template.html for the given config + manifest metadata. */
-function renderIndexHtml(template, config, manifest) {
+/** index.html from the template's head: title, description and lang set, its inline style replaced by links. */
+function renderIndexHtml(template, manifest) {
   const brandName = manifest.brand?.name || 'BRAND';
   const subject = manifest.subject || 'SUBJECT';
-  const title = manifest.pageTitle || `${brandName} — the world of ${subject}`;
+  const title = manifest.pageTitle || `${brandName} - the world of ${subject}`;
   const desc = manifest.pageDescription || `Scroll to fly through the world of ${brandName.replace(/\.+$/, '')}.`;
-
-  // Everything up to the engine <script> tag is the head+body-open; regenerate the tail.
   const marker = '<script src="scrub-engine.js">';
   const idx = template.indexOf(marker);
   if (idx === -1) throw new Error('assemble: index-template.html missing the scrub-engine.js script tag');
   let head = template.slice(0, idx).replace(/\s*$/, '\n');
-
   head = head.replace(/<title>[^<]*<\/title>/, `<title>${escHtml(title)}</title>`);
   head = head.replace(/(<meta name="description" content=")[^"]*(")/, `$1${escAttr(desc)}$2`);
-  const t = manifest.theme || {};
-  head = setToken(head, 'sw-bg', t.bg);
-  head = setToken(head, 'sw-ink', t.ink);
-  head = setToken(head, 'sw-ink-soft', t.inkSoft);
-  head = setToken(head, 'sw-accent', t.accent);
-
-  const configJson = JSON.stringify(config, null, 2).replace(/\n/g, '\n    ');
-  const tail =
-`  <script src="scrub-engine.js"></script>
-  <script>
-    mountScrollWorld(document.getElementById('world'), ${configJson});
-  </script>
-</body>
-</html>
+  if (manifest.lang) head = head.replace(/<html lang="[^"]*">/, `<html lang="${escAttr(manifest.lang)}">`);
+  const links = stylesheets(manifest).map((f) => `  <link rel="stylesheet" href="${f}" />`).join('\n');
+  head = head.replace(/[ \t]*<style>[\s\S]*?<\/style>\n?/, `${links}\n`);
+  const scripts = ['scrub-engine.js', manifest.stepNav ? 'step-nav.js' : null, 'intro.js'].filter(Boolean)
+    .map((f) => `  <script src="${f}"></script>`).join('\n');
+  return `${head}${scripts}\n</body>\n</html>\n`;
+}
+
+// The config and the mount, out of the page so no inline script is needed.
+function introJs(config, nav) {
+  const json = (v) => JSON.stringify(v, null, 2).replace(/\n/g, '\n  ');
+  const lines = nav
+    ? [`var nav = ${json(nav === true ? {} : nav)};`, 'if (window.IntroStepNav) window.IntroStepNav.prefetch(config, nav);',
+      'mountScrollWorld(world, config);', 'if (window.IntroStepNav) window.IntroStepNav.attach(world, config, nav);']
+    : ['mountScrollWorld(world, config);'];
+  return `// Generated by assemble.mjs from intro.json. Kept out of index.html so the page runs under a
+// Content-Security-Policy without 'unsafe-inline'.
+(function () {
+  var world = document.getElementById('world');
+  var config = ${json(config)};
+${lines.map((l) => `  ${l}`).join('\n')}
+})();
 `;
-  return head + tail;
 }
 
 const escHtml = (s) => String(s).replace(/[&<>]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;' }[c]));
 const escAttr = (s) => String(s).replace(/[&<>"]/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;' }[c]));
 
+// Heads the copied engine rules: they are scroll-world's (MIT), whose notice ships beside them.
+const ENGINE_NOTICE = '/* scroll-world (https://github.com/oso95/scroll-world), MIT License, (c) 2026 cyw.\n'
+  + '   The rules scrub-engine.js injects, copied unchanged. Notice: scrub-engine.LICENSE.txt */\n';
+
+function writeStatic(out, manifest, template) {
+  const engineSource = fs.readFileSync(path.join(HERE, 'scrub-engine.js'), 'utf8');
+  fs.copyFileSync(path.join(HERE, 'scrub-engine.js'), path.join(out, 'scrub-engine.js'));
+  fs.copyFileSync(path.join(HERE, 'LICENSE'), path.join(out, 'scrub-engine.LICENSE.txt'));
+  const css = engineCss(engineSource);
+  fs.writeFileSync(path.join(out, 'scrub-engine.css'), ENGINE_NOTICE + css);
+  const style = /<style>([\s\S]*?)<\/style>/.exec(template);
+  fs.writeFileSync(path.join(out, 'theme.css'), themeCss(style ? style[1] : '', manifest.theme));
+  const copies = ['intro-fixes.css', manifest.panel ? PANELS[manifest.panel] : null,
+    manifest.stepNav ? 'step-nav.css' : null, manifest.stepNav ? 'step-nav.js' : null].filter(Boolean);
+  for (const f of copies) fs.copyFileSync(path.join(HERE, f), path.join(out, f));
+  return `'sha256-${crypto.createHash('sha256').update(css).digest('base64')}'`;
+}
+
 // ---- public API -------------------------------------------------------------
 
 /**
- * Assemble a preview site. Copies scrub-engine.js + all referenced assets into outDir and
- * writes index.html wired to the exact mountScrollWorld config.
- * @returns {{ outDir:string, index:string, engine:string, assets:string[] }}
+ * Assemble the intro page. Copies the engine, its fixes and all referenced assets into outDir and
+ * writes index.html, intro.js and the stylesheets (see the header).
+ * @returns {{ outDir:string, index:string, engine:string, assets:string[], styleHash:string }}
  */
 export function assemble({ projectDir, outDir, manifestPath } = {}) {
   if (!projectDir) throw new Error('assemble: projectDir is required');
@@ -205,21 +264,17 @@ export function assemble({ projectDir, outDir, manifestPath } = {}) {
       'Write an intro.json in the project dir (see the header of assemble.mjs for its shape).');
   }
   const manifest = JSON.parse(fs.readFileSync(mPath, 'utf8'));
+  if (manifest.panel && !PANELS[manifest.panel]) throw new Error(`assemble: unknown panel "${manifest.panel}" (known: ${Object.keys(PANELS).join(', ')})`);
 
   fs.mkdirSync(out, { recursive: true });
   const { config, copied } = buildConfig(manifest, proj, out);
-
-  // Vendored engine sits next to this script; copy it beside index.html.
-  const engineSrc = path.join(HERE, 'scrub-engine.js');
-  if (!fs.existsSync(engineSrc)) throw new Error(`assemble: scrub-engine.js not found at ${engineSrc}`);
-  fs.copyFileSync(engineSrc, path.join(out, 'scrub-engine.js'));
-
   const template = fs.readFileSync(path.join(HERE, 'index-template.html'), 'utf8');
-  const html = renderIndexHtml(template, config, manifest);
+  const styleHash = writeStatic(out, manifest, template);
+  fs.writeFileSync(path.join(out, 'intro.js'), introJs(config, manifest.stepNav));
   const indexPath = path.join(out, 'index.html');
-  fs.writeFileSync(indexPath, html);
+  fs.writeFileSync(indexPath, renderIndexHtml(template, manifest));
 
-  return { outDir: out, index: indexPath, engine: path.join(out, 'scrub-engine.js'), assets: copied };
+  return { outDir: out, index: indexPath, engine: path.join(out, 'scrub-engine.js'), assets: copied, styleHash };
 }
 
 // ---- CLI --------------------------------------------------------------------
@@ -244,7 +299,8 @@ if (invokedDirectly) {
     console.log(`assembled ${r.assets.length} asset(s) -> ${r.outDir}`);
     console.log(`index:  ${r.index}`);
     console.log(`engine: ${r.engine}`);
-    console.log(`\npreview:  node ${path.join(HERE, 'serve.mjs')} ${r.outDir}`);
+    console.log(`CSP: the engine injects one <style>; to allow it add ${r.styleHash} to style-src (scrub-engine.css carries the same rules)`);
+    console.log(`\npreview:  node ${path.join(HERE, 'serve.mjs')} ${r.outDir} [--csp strict]`);
   } catch (e) {
     console.error(String(e.message || e));
     process.exit(1);

package/skills/3d-intro-build/references/azure-adapter.mjs

@@ -101,17 +101,31 @@ export function parseConsoleSample(text) {
   return out;
 }
 
-/** Parse a KEY=VALUE .env body into a plain object (strips surrounding quotes, skips comments). */
+/**
+ * Parse a KEY=VALUE .env body into a plain object, skipping comment lines. A quoted value keeps
+ * everything inside its quotes. In an unquoted value, a # that follows whitespace starts a comment
+ * (also right after `=`), so a note after a value never becomes part of an endpoint or a key.
+ */
 export function parseEnvFile(text) {
   const env = {};
   for (const line of String(text || '').split(/\r?\n/)) {
     if (line.trimStart().startsWith('#')) continue;
-    const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*?)\s*$/);
-    if (m) env[m[1]] = m[2].replace(/^["']|["']$/g, '');
+    const m = line.match(/^\s*([A-Za-z_][A-Za-z0-9_]*)\s*=([^\n]*)$/);
+    if (m) env[m[1]] = envValue(m[2]);
   }
   return env;
 }
 
+// `raw` is everything after `=`, so the whitespace before a leading # is still there. A stray
+// trailing \r (a \r\r\n line end) is whitespace too.
+function envValue(raw) {
+  const v = raw.trim();
+  const q = v[0];
+  const end = q === '"' || q === "'" ? v.indexOf(q, 1) : -1;
+  if (end > 0) return v.slice(1, end);
+  return raw.trimEnd().replace(/\s+#.*$/, '').trim().replace(/^["']|["']$/g, '');
+}
+
 /**
  * Load creds from `.env.3d-intro.local` in projectDir, else `~/.config/banker/3d-intro/env`.
  * Returns the parsed KEY=VALUE map plus `_source` (the file used, or null if none found).
@@ -135,7 +149,7 @@ export function persistCreds(creds, { target } = {}) {
   const lines = [];
   for (const [k, v] of Object.entries(creds || {})) {
     if (k.startsWith('_') || v == null) continue;
-    lines.push(`${k}=${String(v)}`);
+    lines.push(`${k}=${envLiteral(String(v))}`);
   }
   const body = lines.length ? `${lines.join('\n')}\n` : '';
   fs.mkdirSync(path.dirname(target), { recursive: true });
@@ -144,6 +158,12 @@ export function persistCreds(creds, { target } = {}) {
   return target;
 }
 
+// Quote a value that parseEnvFile would otherwise cut at " #", trim, or strip of its quotes.
+function envLiteral(v) {
+  if (!/\s#|^["'\s]|["'\s]$/.test(v)) return v;
+  return v.includes('"') ? `'${v}'` : `"${v}"`;
+}
+
 /** Redact a secret to `abcd…wxyz(len)`; short (<=8) secrets are fully masked; falsy -> "(missing)". */
 export function redact(s) {
   if (!s) return '(missing)';
@@ -156,10 +176,23 @@ export function redact(s) {
 // HTTP
 // ---------------------------------------------------------------------------
 
+// Retry-After / retry-after-ms response header -> milliseconds (null when absent or unparsable).
+function retryAfterMsOf(headers) {
+  const ms = Number(headers.get('retry-after-ms'));
+  if (headers.get('retry-after-ms') && Number.isFinite(ms)) return Math.max(0, ms);
+  const h = headers.get('retry-after');
+  if (!h) return null;
+  const sec = Number(h);
+  if (Number.isFinite(sec)) return Math.max(0, sec * 1000);
+  const at = Date.parse(h);
+  return Number.isFinite(at) ? Math.max(0, at - Date.now()) : null;
+}
+
 /**
  * Fetch an Azure URL trying the `api-key` header first and, on 401/403, retrying with
  * `Authorization: Bearer`. Never throws on HTTP status; a network error yields {status:0}.
- * @returns {Promise<{status:number, ok:boolean, ct:string, body:any, authStyle:string|null, error?:Error}>}
+ * `retryAfterMs` carries the server's Retry-After hint (null when absent).
+ * @returns {Promise<{status:number, ok:boolean, ct:string, body:any, authStyle:string|null, retryAfterMs:number|null, error?:Error}>}
  */
 export async function azFetch(url, { key, binary = false, headers = {}, method = 'GET', body } = {}) {
   const styles = key ? [{ 'api-key': key }, { Authorization: `Bearer ${key}` }] : [{}];
@@ -179,7 +212,7 @@ export async function azFetch(url, { key, binary = false, headers = {}, method =
     if (binary) parsed = Buffer.from(await r.arrayBuffer());
     else if (ct.includes('json')) parsed = await r.json().catch(() => null);
     else parsed = await r.text().catch(() => null);
-    last = { status: r.status, ok: r.ok, ct, body: parsed, authStyle: Object.keys(auth)[0] || null };
+    last = { status: r.status, ok: r.ok, ct, body: parsed, authStyle: Object.keys(auth)[0] || null, retryAfterMs: retryAfterMsOf(r.headers) };
     if (r.status !== 401 && r.status !== 403) return last; // accepted (or a non-auth error)
     // else: this auth style was rejected — fall through and try the next
   }
@@ -190,26 +223,40 @@ export async function azFetch(url, { key, binary = false, headers = {}, method =
 // Images
 // ---------------------------------------------------------------------------
 
+// POST JSON, retrying HTTP 429 up to `retries` times. Waits the server's Retry-After when given,
+// else 10s, 20s, 40s…; either way at most 60s per wait. Low-tier (S0) image deployments hit this.
+async function postJsonWith429Retry(url, { key, body, retries, onNote }) {
+  for (let i = 0; ; i++) {
+    const r = await azFetch(url, { key, method: 'POST', headers: { 'Content-Type': 'application/json' }, body });
+    if (r.status !== 429 || i >= retries) return r;
+    const ms = Math.min(60000, r.retryAfterMs ?? 10000 * 2 ** i);
+    if (typeof onNote === 'function') onNote(`HTTP 429; retry ${i + 1}/${retries} in ${ms} ms`);
+    await sleep(ms);
+  }
+}
+
 /**
  * Generate a still via the v1 images path; on failure fall back to the classic
  * `deployments/<dep>` path @2025-04-01-preview (discrete size). Returns a PNG Buffer.
- * `onNote(msg)` (optional) is invoked when the classic fallback is taken.
+ * HTTP 429 is retried on the same path first (`retry429` times) — the classic path shares the
+ * deployment's rate limit, so falling back on 429 would only fail again.
+ * `onNote(msg)` (optional) is invoked on 429 waits and when the classic fallback is taken.
  */
 export async function generateImage({
   endpoint, key, deployment, apiVersion = 'preview',
-  prompt, size = '720x1280', quality = 'low', n = 1, onNote,
+  prompt, size = '720x1280', quality = 'low', n = 1, onNote, retry429 = 3,
 } = {}) {
   const genBody = { model: deployment, prompt, size, quality, n };
-  let r = await azFetch(`${endpoint}/openai/v1/images/generations?api-version=${apiVersion}`, {
-    key, method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(genBody),
+  let r = await postJsonWith429Retry(`${endpoint}/openai/v1/images/generations?api-version=${apiVersion}`, {
+    key, body: JSON.stringify(genBody), retries: retry429, onNote,
   });
   let note = 'v1';
-  if (!(r.ok && r.body?.data?.[0]?.b64_json)) {
+  // no classic retry on 429 (shared limit) or on a lost connection (the v1 call may have billed)
+  if (!(r.ok && r.body?.data?.[0]?.b64_json) && r.status !== 429 && r.status !== 0) {
     note = 'classic-fallback(2025-04-01-preview)';
     if (typeof onNote === 'function') onNote(`generateImage: v1 path failed (HTTP ${r.status}); trying ${note}`);
-    r = await azFetch(`${endpoint}/openai/deployments/${deployment}/images/generations?api-version=2025-04-01-preview`, {
-      key, method: 'POST', headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ ...genBody, size: classicSize(size) }),
+    r = await postJsonWith429Retry(`${endpoint}/openai/deployments/${deployment}/images/generations?api-version=2025-04-01-preview`, {
+      key, body: JSON.stringify({ ...genBody, size: classicSize(size) }), retries: retry429, onNote,
     });
   }
   const b64 = r.body?.data?.[0]?.b64_json;
@@ -273,30 +320,49 @@ export async function createVideo({
     fd.append('input_reference', new Blob([inputReferencePng], { type: 'image/png' }), 'input_reference.png');
   }
   const r = await azFetch(`${endpoint}/openai/v1/videos?api-version=${apiVersion}`, { key, method: 'POST', body: fd });
-  if (!(r.ok && r.body?.id)) throw new Error(`createVideo failed: HTTP ${r.status} ${truncate(r.body)}`);
+  if (!(r.ok && r.body?.id)) {
+    // status 0 = network error; errno tells a refused connection (nothing sent) from a lost one
+    const err = new Error(`createVideo failed: HTTP ${r.status} ${truncate(r.body)}`);
+    err.status = r.status;
+    err.errno = r.error?.cause?.code || r.error?.code || null;
+    throw err;
+  }
   return r.body;
 }
 
+const POLL_DEFAULTS = { apiVersion: 'preview', intervalMs: 5000, maxTicks: 180 };
+const POLL_RETRY_4XX = new Set([408, 429]);
+const withoutUndefined = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
+
 /**
  * Poll a Sora job until a terminal status (or maxTicks). Polls first, then sleeps, so a job
- * that is already terminal returns without waiting. `onTick(status, i)` is optional.
+ * that is already terminal returns without waiting. `onTick(status, i)` is optional; `sleep`
+ * replaces the wait between polls. 408, 429, 5xx and network errors keep polling. Any other
+ * 4xx throws at once with `err.status` and `err.code`: a job the server no longer knows, or a
+ * key it refuses, never turns terminal.
  * @returns the last status object seen.
  */
-export async function pollVideo({
-  endpoint, key, id, onTick, apiVersion = 'preview', intervalMs = 5000, maxTicks = 180,
-} = {}) {
-  const url = `${endpoint}/openai/v1/videos/${id}?api-version=${apiVersion}`;
+export async function pollVideo(opts = {}) {
+  const o = { ...POLL_DEFAULTS, sleep, ...withoutUndefined(opts) };
+  const url = `${o.endpoint}/openai/v1/videos/${o.id}?api-version=${o.apiVersion}`;
   let st = null;
-  for (let i = 0; i < maxTicks; i++) {
-    const r = await azFetch(url, { key, method: 'GET' });
-    st = r.body || st;
-    if (typeof onTick === 'function') onTick(st, i);
+  for (let i = 0; i < o.maxTicks; i++) {
+    const r = await azFetch(url, { key: o.key, method: 'GET' });
+    throwIfRefused(r, o.id);
+    if (r.ok) st = r.body || st;
+    if (typeof o.onTick === 'function') o.onTick(st, i);
     if (st && TERMINAL_STATUS.has(st.status)) break;
-    await sleep(intervalMs);
+    await o.sleep(o.intervalMs);
   }
   return st;
 }
 
+function throwIfRefused(r, id) {
+  if (r.status < 400 || r.status >= 500 || POLL_RETRY_4XX.has(r.status)) return;
+  const code = r.body?.error?.code || null;
+  throw Object.assign(new Error(`pollVideo: job ${id} answered HTTP ${r.status}${code ? ` ${code}` : ''}`), { status: r.status, code });
+}
+
 /** Download finished video bytes. Returns an mp4 Buffer; throws on non-200 / empty body. */
 export async function downloadVideo({ endpoint, key, id, apiVersion = 'preview' } = {}) {
   const r = await azFetch(`${endpoint}/openai/v1/videos/${id}/content?api-version=${apiVersion}`, {
@@ -397,6 +463,22 @@ export async function extractLastFrame(mp4, out, { ffmpeg } = {}) {
   return out;
 }
 
+/**
+ * A still as a short clip: the hold of the hold-and-flight mode. The PNG repeats for `seconds`,
+ * encoded as the scrub engine wants (H.264 yuv420p, a keyframe every 8 frames, faststart, no
+ * audio). No generation call, so no cost. Every frame is the still, so a flight whose first or last
+ * frame is this still meets the hold exactly. `size` ('720x1280') scales; even sizes only. Returns out.
+ */
+export async function stillToClip(png, out, { ffmpeg, seconds = 1, fps = 24, size } = {}) {
+  const bin = ffmpeg || await resolveFfmpeg();
+  fs.rmSync(out, { force: true }); // a file from an earlier run must not pass for this one
+  const vf = `${size ? `scale=${String(size).replace('x', ':')},` : ''}format=yuv420p`;
+  const r = runFf(bin, ['-y', '-loop', '1', '-i', png, '-t', String(seconds), '-r', String(fps), '-vf', vf,
+    '-c:v', 'libx264', '-crf', '20', '-g', '8', '-movflags', '+faststart', '-an', out]);
+  if (r.code !== 0 && !fs.existsSync(out)) throw new Error(`stillToClip failed: ${tail(r.stderr)}`);
+  return out;
+}
+
 /** Extract the FIRST frame of an mp4 to a PNG. Returns out. */
 export async function extractFirstFrame(mp4, out, { ffmpeg } = {}) {
   const bin = ffmpeg || await resolveFfmpeg();
@@ -481,15 +563,19 @@ const VIDEO_USD_PER_SEC = 0.10;
 const IMAGE_USD_EACH = 0.02;
 
 /**
- * Rough budget for an intro of `nScenes` scenes. Video billed at $0.10/sec/clip; one image gen
- * per scene (two per scene in two-image mode). Returns per-category USD sub-costs and the total.
+ * Rough budget for an intro of `nScenes` scenes. Video billed at $0.10/sec/clip (the Sora rate:
+ * WAN rates cannot be read through an API); one image gen per scene (two per scene in two-image
+ * mode). mode 'chain' (default) makes one clip of `seconds` per scene; 'holdFlight' makes one
+ * flight of `flightSeconds` between each pair of scenes, the holds being encoded stills (free).
+ * Returns per-category USD sub-costs and the total.
  * @returns {{images:number, videos:number, usd:number}}
  */
-export function estimateCost({ nScenes, seconds = 4, twoImage = false } = {}) {
+export function estimateCost({ nScenes, seconds = 4, twoImage = false, mode = 'chain', flightSeconds = 5 } = {}) {
   const n = Number(nScenes) || 0;
   const imageCount = twoImage ? n * 2 : n;
   const images = round2(imageCount * IMAGE_USD_EACH);
-  const videos = round2(n * seconds * VIDEO_USD_PER_SEC);
+  const clipSeconds = mode === 'holdFlight' ? Math.max(0, n - 1) * flightSeconds : n * seconds;
+  const videos = round2(clipSeconds * VIDEO_USD_PER_SEC);
   const usd = round2(images + videos);
   return { images, videos, usd };
 }