@kaydash9999/banker-plugins 0.21.0 → 0.23.0

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

@@ -5,7 +5,7 @@
  * 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            (head of index-template.html; no inline script or style)
+ *     index.html            (head of index-template.html; no inline script or style; preloads the first posters)
  *     scrub-engine.js       (copied verbatim from references/)
  *     scrub-engine.css      (the CSS the engine injects, taken from scrub-engine.js unchanged)
  *     scrub-engine.LICENSE.md (scroll-world's MIT notice, which ships with the engine files)
@@ -13,10 +13,11 @@
  *     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)
+ *     step-nav.js/.css      (scene-by-scene navigation; on unless "stepNav": false)
  *     assets/<id>.<ext>     (scene posters/stills)
  *     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)
+ *     assets/vid/connN.mp4  (optional connectors: the flights between scenes, or dive mode's exits)
+ *     assets/connN-poster.<ext> (optional connectorStills: a connector's own first frame as its poster)
  * 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
@@ -40,7 +41,8 @@
  *     "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
+ *     "panelAlpha": 0.7,                                // optional glass alpha; default: panelAlpha() below
+ *     "stepNav": { "end": "#main", ... },              // optional, default on ({}); false turns it off; options in step-nav.js
  *     "sections": [                                     // required, >= 1, in order
  *       { "id":"sceneA", "label":"Scene A",
  *         "still":"still-1.png",  "clip":"dive-1.mp4",       // required (relative to projectDir)
@@ -51,7 +53,10 @@
  *         "cta": { "primary":{"label":"","href":""}, "secondary":{"label":"","href":""} } } // last only
  *     ],
  *     "connectors": ["conn-1.mp4", null, ...],          // optional, len = sections.length-1
- *     "connectorsMobile": ["conn-1-m.mp4", ...]         // optional, same length
+ *     "connectorsMobile": ["conn-1-m.mp4", ...],        // optional, same length
+ *     "connectorStills": ["conn-1-first.png", ...]      // optional, same length: each connector's poster,
+ *                                                       // its clip's actual first frame (dive mode's exits).
+ *                                                       // Without it the engine shows the next scene's still.
  *   }
  *
  * Usage:
@@ -73,10 +78,17 @@ const HERE = path.dirname(fileURLToPath(import.meta.url));
 const osPath = (base, posixRel) => path.join(base, ...posixRel.split('/'));
 
 // Copy one source asset (path relative to projectDir) to a posix dest URL under outDir.
+// Only files inside the project folder (after links) go into assets/: a manifest naming ../ or a link
+// out of the folder would otherwise publish any readable file with the page.
 function copyAsset(projectDir, outDir, srcRel, destPosix) {
   const src = path.join(projectDir, ...String(srcRel).split(/[\\/]/));
   if (!fs.existsSync(src)) throw new Error(`assemble: asset not found: ${srcRel} (looked at ${src})`);
+  const root = fs.realpathSync(projectDir);
+  const real = fs.realpathSync(src);
+  if (real !== root && !real.startsWith(root + path.sep)) throw Object.assign(new Error(`assemble: asset outside the project folder: ${srcRel} (resolves to ${real}); copy it into ${root} first`), { code: 'EOUTSIDE' });
   const dest = osPath(outDir, destPosix);
+  const out = path.resolve(outDir);
+  if (!path.resolve(dest).startsWith(out + path.sep)) throw Object.assign(new Error(`assemble: asset would be written outside the output folder: ${destPosix}`), { code: 'EOUTSIDE' });
   fs.mkdirSync(path.dirname(dest), { recursive: true });
   fs.copyFileSync(src, dest);
   return destPosix;
@@ -97,8 +109,12 @@ const MEDIA = [
   ['clipMobile', (id, src) => `assets/vid/${id}-m${extOf(src) || '.mp4'}`],
 ];
 
+// A section id becomes a file name under assets/, so it is letters, digits, '-' and '_' only (no ../ or a separator).
+const SECTION_ID_RE = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+
 function requireFields(s, i) {
   if (!s || !s.id) throw new Error(`assemble: section[${i}] missing "id"`);
+  if (!SECTION_ID_RE.test(String(s.id))) throw new Error(`assemble: section[${i}] id ${JSON.stringify(String(s.id)).slice(0, 80)} must be letters, digits, '-' or '_' (it names files under assets/)`);
   for (const k of ['still', 'clip']) if (!s[k]) throw new Error(`assemble: section[${i}] (${s.id}) missing "${k}"`);
 }
 
@@ -114,13 +130,17 @@ function sectionOut(s, i, copy) {
 
 // Connectors: one per gap between sections, in order; a null entry means "crossfade directly".
 function connectorsOut(list, n, suffix, copy) {
+  return gapsOut(list, n, copy, (i, src) => `assets/vid/conn${i + 1}${suffix}${extOf(src) || '.mp4'}`);
+}
+
+// One copied file (or null) per gap between sections.
+function gapsOut(list, n, copy, dest) {
   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));
+  return Array.from({ length: Math.max(0, n - 1) }, (_, i) => (src[i] ? copy(src[i], dest(i, src[i])) : null));
 }
 
 // The config in the shape mountScrollWorld reads (see scrub-engine.js).
-function engineConfig(m, sections, connectors, connectorsMobile) {
+function engineConfig(m, sections, { connectors, connectorsMobile, connectorStills }) {
   const config = {};
   for (const k of ['brand', 'cta']) if (m[k]) config[k] = m[k];
   config.hint = m.hint || 'scroll to fly in';
@@ -130,10 +150,13 @@ function engineConfig(m, sections, connectors, connectorsMobile) {
   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;
+  return Object.assign(config, setLists({ connectorsMobile, connectorStills }));
 }
 
+// The per-gap lists that hold at least one file. connectorStills is the engine's opt-in connector
+// poster (see the banker line in scrub-engine.js and NOTICE.md).
+const setLists = (lists) => Object.fromEntries(Object.entries(lists).filter(([, list]) => list.some(Boolean)));
+
 /**
  * Build the exact mountScrollWorld config object from a manifest, copying every referenced
  * asset into outDir/assets. Returns { config, copied:[destPosix,...] }.
@@ -144,15 +167,53 @@ function buildConfig(manifest, projectDir, outDir) {
   const 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 };
+  const gaps = {
+    connectors: connectorsOut(manifest.connectors, sectionsOut.length, '', copy),
+    connectorsMobile: connectorsOut(manifest.connectorsMobile, sectionsOut.length, '-m', copy),
+    connectorStills: gapsOut(manifest.connectorStills, sectionsOut.length, copy, (i, src) => `assets/conn${i + 1}-poster${extOf(src)}`),
+  };
+  return { config: engineConfig(manifest, sectionsOut, gaps), copied };
 }
 
 // ---- page generation -------------------------------------------------------
 
 const PANELS = { glass: 'panel-glass.css' };
 
+/** The step navigation options: on by default ({}), off only with "stepNav": false. */
+export const navOf = (manifest) => (manifest.stepNav === false ? null : (manifest.stepNav && typeof manifest.stepNav === 'object' ? manifest.stepNav : {}));
+
+// ---- glass panel alpha ---------------------------------------------------------
+
+const lin = (c) => { const s = c / 255; return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4; };
+const lum = ([r, g, b]) => 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+const ratio = (a, b) => (Math.max(lum(a), lum(b)) + 0.05) / (Math.min(lum(a), lum(b)) + 0.05);
+const hexRgb = (h) => { const m = /^#?([\da-f]{6})$/i.exec(String(h || '').trim()); return m ? [0, 2, 4].map((k) => parseInt(m[1].slice(k, k + 2), 16)) : null; };
+// The glass panel's colours (panel-glass.css): its shade, and its text (title, body, number); the
+// label line mixes 30% of the accent into white.
+export const GLASS = { panel: [11, 18, 32], text: ['#ffffff', '#F1F5F9', '#E2E8F0'].map(hexRgb), alpha: 0.36 };
+
+/**
+ * The lowest glass alpha (0.01 steps) at which every panel text colour keeps `min` contrast even over a
+ * white pixel (the worst a scene can put behind the panel), the label colour from each accent included.
+ */
+export function panelAlpha(accents = [], { min = 4.5, panel = GLASS.panel } = {}) {
+  const labels = accents.map(hexRgb).filter(Boolean).map((a) => a.map((c) => 0.3 * c + 0.7 * 255));
+  const texts = [...GLASS.text, ...labels];
+  for (let k = 0; k <= 100; k++) {
+    const bg = panel.map((c) => (k / 100) * c + (1 - k / 100) * 255);
+    if (texts.every((t) => ratio(t, bg) >= min)) return k / 100;
+  }
+  return 1;
+}
+
+// The alpha the page gets: the manifest's panelAlpha (a person's choice) wins, else panelAlpha().
+function glassAlpha(manifest) {
+  const given = Number(manifest.panelAlpha);
+  if (manifest.panelAlpha != null && given >= 0 && given <= 1) return { alpha: given, from: 'manifest' };
+  const accents = [manifest.theme?.accent, ...(manifest.sections || []).map((s) => s.accent)];
+  return { alpha: panelAlpha(accents), from: 'computed' };
+}
+
 /**
  * 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)
@@ -186,11 +247,25 @@ function themeCss(styleInner, theme = {}) {
 
 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);
+    navOf(manifest) ? 'step-nav.css' : null].filter(Boolean);
+}
+
+/**
+ * The posters of the first `n` segments in scroll order (scene still, then the connector's own poster
+ * when it has one): the engine makes its posters loading=lazy, so on a fast first scroll the first
+ * seams could show a poster not yet loaded. A preload link fetches them with the page.
+ */
+export function firstPosters(config, n = 3) {
+  const out = [];
+  (config.sections || []).forEach((s, i) => {
+    out.push(s.still);
+    if (config.connectors?.[i] && config.connectorStills?.[i]) out.push(config.connectorStills[i]);
+  });
+  return [...new Set(out.filter(Boolean))].slice(0, n);
 }
 
 /** index.html from the template's head: title, description and lang set, its inline style replaced by links. */
-function renderIndexHtml(template, manifest) {
+function renderIndexHtml(template, manifest, config = {}) {
   const brandName = manifest.brand?.name || 'BRAND';
   const subject = manifest.subject || 'SUBJECT';
   const title = manifest.pageTitle || `${brandName} - the world of ${subject}`;
@@ -202,13 +277,23 @@ function renderIndexHtml(template, manifest) {
   head = head.replace(/<title>[^<]*<\/title>/, `<title>${escHtml(title)}</title>`);
   head = head.replace(/(<meta name="description" content=")[^"]*(")/, `$1${escAttr(desc)}$2`);
   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');
+  const links = [...stylesheets(manifest).map((f) => `  <link rel="stylesheet" href="${f}" />`),
+    ...firstPosters(config).map((f) => `  <link rel="preload" as="image" href="${escAttr(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)
+  const scripts = ['scrub-engine.js', navOf(manifest) ? 'step-nav.js' : null, 'intro.js'].filter(Boolean)
     .map((f) => `  <script src="${f}"></script>`).join('\n');
   return `${head}${scripts}\n</body>\n</html>\n`;
 }
 
+// A scene a jump shows (an anchor, a route dot under reduced motion, a scrollbar drag) paints nothing until
+// its poster is decoded, and the engine decodes posters async: a jump showed an empty background for
+// 0.1-0.35 s. The page decodes every poster at load and again once scrolling stops.
+const WARM = [
+  "var warm = function () { [].forEach.call(world.querySelectorAll('.sw-scene__still'), function (i) { if (i.decode) i.decode().catch(function () {}); }); };",
+  "warm(); window.addEventListener('load', warm);",
+  "var warmT = 0; window.addEventListener('scroll', function () { clearTimeout(warmT); warmT = setTimeout(warm, 400); }, { passive: true });",
+];
+
 // 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  ');
@@ -216,6 +301,7 @@ function introJs(config, 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);'];
+  lines.push(...WARM);
   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 () {
@@ -242,8 +328,12 @@ function writeStatic(out, manifest, template) {
   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);
+    navOf(manifest) ? 'step-nav.css' : null, navOf(manifest) ? 'step-nav.js' : null].filter(Boolean);
   for (const f of copies) fs.copyFileSync(path.join(HERE, f), path.join(out, f));
+  if (manifest.panel === 'glass') {
+    const css = path.join(out, PANELS.glass);
+    fs.writeFileSync(css, fs.readFileSync(css, 'utf8').replace(/(--intro-panel-alpha:\s*)[\d.]+;/, `$1${glassAlpha(manifest).alpha};`));
+  }
   return `'sha256-${crypto.createHash('sha256').update(css).digest('base64')}'`;
 }
 
@@ -252,7 +342,7 @@ function writeStatic(out, manifest, template) {
 /**
  * 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 }}
+ * @returns {{ outDir:string, index:string, engine:string, assets:string[], styleHash:string, panelAlpha?:{alpha,from} }}
  */
 export function assemble({ projectDir, outDir, manifestPath } = {}) {
   if (!projectDir) throw new Error('assemble: projectDir is required');
@@ -270,11 +360,11 @@ export function assemble({ projectDir, outDir, manifestPath } = {}) {
   const { config, copied } = buildConfig(manifest, proj, out);
   const template = fs.readFileSync(path.join(HERE, 'index-template.html'), 'utf8');
   const styleHash = writeStatic(out, manifest, template);
-  fs.writeFileSync(path.join(out, 'intro.js'), introJs(config, manifest.stepNav));
+  fs.writeFileSync(path.join(out, 'intro.js'), introJs(config, navOf(manifest)));
   const indexPath = path.join(out, 'index.html');
-  fs.writeFileSync(indexPath, renderIndexHtml(template, manifest));
+  fs.writeFileSync(indexPath, renderIndexHtml(template, manifest, config));
 
-  return { outDir: out, index: indexPath, engine: path.join(out, 'scrub-engine.js'), assets: copied, styleHash };
+  return { outDir: out, index: indexPath, engine: path.join(out, 'scrub-engine.js'), assets: copied, styleHash, ...(manifest.panel === 'glass' ? { panelAlpha: glassAlpha(manifest) } : {}) };
 }
 
 // ---- CLI --------------------------------------------------------------------
@@ -307,6 +397,7 @@ if (invokedDirectly()) {
     console.log(`assembled ${r.assets.length} asset(s) -> ${r.outDir}`);
     console.log(`index:  ${r.index}`);
     console.log(`engine: ${r.engine}`);
+    if (r.panelAlpha) console.log(`glass panel alpha: ${r.panelAlpha.alpha} (${r.panelAlpha.from === 'manifest' ? 'the manifest\'s panelAlpha' : 'computed: contrast 4.5 even over white'})`);
     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) {

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

@@ -173,6 +173,9 @@ const MACHINE_ONLY = ['FFMPEG_PATH'];
  * 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). From a
  * project file, FFMPEG_PATH is left out and returned under `_ignored` so the caller can say why.
+ * A project file git tracks gives no value at all: only `_source`, `_tracked: true` and `_names`
+ * (the names it sets). It may have come with the repository, so its endpoint would receive the
+ * prompts, the frames and the key; the calls refuse creds without an endpoint and a key.
  */
 export function resolveCreds({ projectDir } = {}) {
   const home = homeCredsPath();
@@ -183,7 +186,14 @@ export function resolveCreds({ projectDir } = {}) {
   if (!p) return { _source: null };
   const creds = { ...parseEnvFile(fs.readFileSync(p, 'utf8')), _source: p };
   if (p === home) return creds;
-  return trackedByGit(p) ? { ...withoutMachineOnly(creds), _tracked: true } : withoutMachineOnly(creds);
+  if (trackedByGit(p)) return { _source: p, _tracked: true, _names: Object.keys(creds).filter((k) => k !== '_source') };
+  return withoutMachineOnly(creds);
+}
+
+// The paid and listing calls need both; resolveCreds gives neither from a project key file git tracks.
+function requireConn(fn, endpoint, key) {
+  if (endpoint && key) return;
+  throw new Error(`${fn}: endpoint and key are required; nothing was sent (resolveCreds gives no value from a project key file git tracks: untrack it with git rm --cached, or use the home key file)`);
 }
 
 function withoutMachineOnly(creds) {
@@ -615,6 +625,7 @@ export async function generateImage({
   endpoint, key, deployment, apiVersion = 'preview',
   prompt, size = '720x1280', quality = 'low', n = 1, onNote, retry429 = 3,
 } = {}) {
+  requireConn('generateImage', endpoint, key);
   const genBody = { model: deployment, prompt, size, quality, n };
   const post = (url, body) => postJsonWith429Retry(url, { key, body: JSON.stringify(body), retries: retry429, onNote });
   let r = await post(`${endpoint}/openai/v1/images/generations?api-version=${apiVersion}`, genBody);
@@ -641,6 +652,7 @@ function pngFrom(r, b64, failed) {
 export async function editImage({
   endpoint, key, deployment, apiVersion = 'preview', prompt, imageBuf, maskBuf, size,
 } = {}) {
+  requireConn('editImage', endpoint, key);
   const r = await azFetch(`${endpoint}/openai/v1/images/edits?api-version=${apiVersion}`, {
     key, method: 'POST', body: editForm({ deployment, prompt, imageBuf, maskBuf, size }), timeoutMs: IMAGE_TIMEOUT_MS,
   });
@@ -659,6 +671,7 @@ function editForm({ deployment, prompt, imageBuf, maskBuf, size }) {
 
 /** Generate a still via the Black Forest Labs FLUX provider path. Returns a PNG Buffer. */
 export async function generateImageFlux({ endpoint, key, prompt, width, height, apiVersion = 'preview' } = {}) {
+  requireConn('generateImageFlux', endpoint, key);
   const r = await azFetch(`${endpoint}/providers/blackforestlabs/v1/flux-2-pro?api-version=${apiVersion}`, {
     key, method: 'POST', headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ prompt, width, height }), timeoutMs: IMAGE_TIMEOUT_MS,
@@ -684,6 +697,7 @@ export async function listVideos({ endpoint, key, apiVersion = 'preview' } = {})
 export async function createVideo({
   endpoint, key, model = 'sora-2', prompt, size = '720x1280', seconds = 4, inputReferencePng, apiVersion = 'preview',
 } = {}) {
+  requireConn('createVideo', endpoint, key);
   const body = videoForm({ model, prompt, size, seconds, inputReferencePng });
   const r = await azFetch(`${endpoint}/openai/v1/videos?api-version=${apiVersion}`, { key, method: 'POST', body });
   if (!(r.ok && r.body?.id)) throw createVideoError(r);
@@ -704,11 +718,14 @@ function videoForm({ model, prompt, size, seconds, inputReferencePng }) {
 
 // status 0 = network error; errno tells a refused connection (nothing sent) from a lost one.
 // retryAfterMs is the server's wait for a 429.
+// code is the answer's error.code (DeploymentNotFound and the like), for a 404 or 410 the caller reads.
 function createVideoError(r) {
   const err = new Error(`createVideo failed: HTTP ${r.status}${why(r)} ${truncate(r.body)}`);
-  return Object.assign(err, { status: r.status, errno: r.errno || null, retryAfterMs: r.retryAfterMs ?? null });
+  return Object.assign(err, { status: r.status, errno: r.errno || null, retryAfterMs: r.retryAfterMs ?? null, code: errorCodeOf(r) });
 }
 
+const errorCodeOf = (r) => (typeof r.body?.error?.code === 'string' ? r.body.error.code : null);
+
 const POLL_DEFAULTS = { apiVersion: 'preview', intervalMs: 5000, maxTicks: 180, now: Date.now };
 const POLL_RETRY_4XX = new Set([408, 429]);
 const withoutUndefined = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
@@ -758,15 +775,87 @@ function throwIfRefused(r, id) {
   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. */
+/** Download finished video bytes. Returns an mp4 Buffer; throws on non-200 / empty body, with err.status. */
 export async function downloadVideo({ endpoint, key, id, apiVersion = 'preview' } = {}) {
   const r = await azFetch(`${endpoint}/openai/v1/videos/${id}/content?api-version=${apiVersion}`, {
     key, method: 'GET', binary: true,
   });
-  if (!(r.status === 200 && r.body?.length)) throw new Error(`downloadVideo failed: HTTP ${r.status}${why(r)}`);
+  if (!(r.status === 200 && r.body?.length)) throw Object.assign(new Error(`downloadVideo failed: HTTP ${r.status}${why(r)}`), { status: r.status });
   return r.body;
 }
 
+// ---------------------------------------------------------------------------
+// Sora deployment probe (FREE: two GETs, nothing is generated)
+// ---------------------------------------------------------------------------
+
+const DEPLOYMENT_API_VERSION = '2022-12-01';
+/** A retirement date this many days away or nearer is reported (`soon`). */
+export const RETIRE_SOON_DAYS = 14;
+const DAY_MS = 86_400_000;
+const RETIRED_LIFECYCLE = new Set(['retired', 'removed']);
+
+/**
+ * FREE check of a Sora deployment that makes no job. POST /openai/v1/videos checks every parameter
+ * before it looks the deployment up (a deployment that does not exist answers the same 400 as one
+ * that does, measured 2026-10-29), and a POST that passes the checks is a paid generation. So the
+ * check is two GETs:
+ *   GET /openai/deployments/<name>?api-version=2022-12-01   200 {model, status}, or 404 when there is none
+ *   GET /openai/v1/models?api-version=preview                 the model's lifecycle_status and deprecation.inference
+ * state: deployed | no_deployment | retired | auth | unreachable | unknown | unset (no endpoint or key: nothing sent). `retired` means the
+ * deployment answered 410, the model list calls the model retired, or its inference retirement date
+ * has passed. `retiresAt` (ms) and `daysLeft` come from the model list; when the deployment names the
+ * model without its version, the newest dated version is taken (`versionInferred`). `soon` is true
+ * within RETIRE_SOON_DAYS. The result holds no key and no URL.
+ */
+export async function probeSoraDeployment({ endpoint, key, deployment = 'sora-2', now = Date.now } = {}) {
+  // no endpoint or key (unset, or creds from a key file git tracks, which give no values): nothing is sent
+  if (!endpoint || !key) return { deployment, status: null, code: null, errno: null, state: 'unset' };
+  const d = await azFetch(`${endpoint}/openai/deployments/${encodeURIComponent(deployment)}?api-version=${DEPLOYMENT_API_VERSION}`, { key, method: 'GET' });
+  const base = { deployment, status: d.status, code: errorCodeOf(d), errno: d.errno || null };
+  if (d.status !== 200) return { ...base, state: deploymentState(d.status) };
+  const { model, deploymentStatus } = deploymentOf(d.body);
+  const life = model ? await modelLifecycle(endpoint, key, model) : {};
+  return withSchedule({ ...base, deploymentStatus, model, ...life }, now());
+}
+
+const deploymentOf = (b) => ({ model: typeof b?.model === 'string' ? b.model : null, deploymentStatus: b?.status ?? null });
+
+const DEPLOYMENT_STATE = new Map([[404, 'no_deployment'], [410, 'retired'], [401, 'auth'], [403, 'auth'], [0, 'unreachable']]);
+const deploymentState = (status) => DEPLOYMENT_STATE.get(status) || 'unknown';
+
+// The model's entry in the resource's model list: its lifecycle and inference retirement date.
+async function modelLifecycle(endpoint, key, model) {
+  const r = await azFetch(`${endpoint}/openai/v1/models?api-version=preview`, { key, method: 'GET' });
+  const m = r.ok ? modelEntry(r.body?.data, model) : null;
+  if (!m) return { modelVersion: null, lifecycle: null, retiresAt: null };
+  return { modelVersion: m.entry.id, versionInferred: m.inferred, lifecycle: m.entry.lifecycle_status ?? null, retiresAt: msOf(m.entry.deprecation?.inference) };
+}
+
+// The entry named exactly `model`, else the newest `<model>-YYYY-MM-DD` one (a deployment names only the model).
+function modelEntry(list, model) {
+  if (!Array.isArray(list)) return null;
+  const exact = list.find((x) => x?.id === model);
+  if (exact) return { entry: exact, inferred: false };
+  const dated = (id) => typeof id === 'string' && id.startsWith(`${model}-`) && /^\d{4}-\d{2}-\d{2}$/.test(id.slice(model.length + 1));
+  const versions = list.filter((x) => dated(x?.id)).sort((a, b) => b.id.localeCompare(a.id));
+  return versions.length ? { entry: versions[0], inferred: true } : null;
+}
+
+// deprecation.inference is unix seconds; an ISO date is read too.
+function msOf(v) {
+  if (typeof v === 'number' && Number.isFinite(v)) return v * 1000;
+  const t = typeof v === 'string' ? Date.parse(v) : NaN;
+  return Number.isFinite(t) ? t : null;
+}
+
+function withSchedule(r, t) {
+  const daysLeft = r.retiresAt == null ? null : Math.ceil((r.retiresAt - t) / DAY_MS);
+  const gone = (r.retiresAt != null && r.retiresAt <= t) || RETIRED_LIFECYCLE.has(r.lifecycle);
+  const ready = !r.deploymentStatus || r.deploymentStatus === 'succeeded';
+  const state = gone ? 'retired' : ready ? 'deployed' : 'unknown';
+  return { ...r, state, daysLeft, soon: !gone && daysLeft != null && daysLeft <= RETIRE_SOON_DAYS };
+}
+
 /**
  * Probe whether the legacy two-image jobs API is available. Never throws.
  * @returns {Promise<boolean>} true when the legacy jobs endpoint exists and is authorized.
@@ -792,6 +881,7 @@ export async function detectTwoImageSupport({ endpoint, key, apiVersion = 'previ
 export async function createVideoTwoImage({
   endpoint, key, model = 'sora-2', prompt = '', firstPng, lastPng, size = '720x1280', seconds = 4, apiVersion = 'preview',
 } = {}) {
+  requireConn('createVideoTwoImage', endpoint, key);
   const r = await azFetch(`${endpoint}/openai/v1/video/generations/jobs?api-version=${apiVersion}`, {
     key, method: 'POST', body: twoImageForm({ model, prompt, firstPng, lastPng, size, seconds }),
   });
@@ -900,21 +990,6 @@ export async function extractFirstFrame(mp4, out, { ffmpeg } = {}) {
   return out;
 }
 
-/**
- * Tone/color continuity pass on srcPng. Stock ffmpeg has no true "match A's histogram to B"
- * filter, so this uses histeq — per-channel histogram equalization — the simplest robust
- * histogram normalization, which keeps a chained clip's first frame from drifting in
- * contrast/tone. refPng is accepted for API symmetry and a future CLUT-based exact match; it
- * is not fed to ffmpeg today (an unmapped extra input would make ffmpeg error). Returns out.
- */
-export async function colorMatch(srcPng, refPng, out, { ffmpeg } = {}) {
-  const bin = ffmpeg || await resolveFfmpeg();
-  void refPng; // reserved (see doc comment)
-  const r = runFf(bin, ['-y', '-i', srcPng, '-vf', 'format=rgb24,histeq', '-frames:v', '1', out]);
-  if (r.code !== 0 && !fs.existsSync(out)) throw new Error(`colorMatch failed: ${tail(r.stderr)}`);
-  return out;
-}
-
 /**
  * Crossfade clip A into clip B with an `xfade` transition of `sec` seconds. `offset` (opts) is
  * where the fade starts in A; when omitted it is derived from A's probed duration (dur - sec).
@@ -988,15 +1063,26 @@ const IMAGE_USD_EACH = 0.02;
  * 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).
+ * flight of `flightSeconds` between each pair of scenes, the holds being encoded stills (free);
+ * 'dive' makes one clip of `diveSeconds` per scene (the dives and the finale) and, with `exit`, one
+ * exit of `exitSeconds` between each pair of scenes (6 scenes: $4.8 without, the default, $6.8 with `exit: true`).
  * Returns per-category USD sub-costs and the total.
  * @returns {{images:number, videos:number, usd:number}}
  */
-export function estimateCost({ nScenes, seconds = 4, twoImage = false, mode = 'chain', flightSeconds = 5 } = {}) {
-  const n = Number(nScenes) || 0;
-  const imageCount = twoImage ? n * 2 : n;
+const COST_DEFAULTS = { seconds: 4, twoImage: false, mode: 'chain', flightSeconds: 5, diveSeconds: 8, exitSeconds: 4, exit: false };
+// The clip seconds an intro bills, by mode.
+const CLIP_SECONDS = {
+  chain: (n, o) => n * o.seconds,
+  holdFlight: (n, o) => Math.max(0, n - 1) * o.flightSeconds,
+  dive: (n, o) => n * o.diveSeconds + (o.exit ? Math.max(0, n - 1) * o.exitSeconds : 0),
+};
+
+export function estimateCost(opts = {}) {
+  const o = { ...COST_DEFAULTS, ...Object.fromEntries(Object.entries(opts).filter(([, v]) => v !== undefined)) };
+  const n = Number(o.nScenes) || 0;
+  const imageCount = o.twoImage ? n * 2 : n;
   const images = round2(imageCount * IMAGE_USD_EACH);
-  const clipSeconds = mode === 'holdFlight' ? Math.max(0, n - 1) * flightSeconds : n * seconds;
+  const clipSeconds = (CLIP_SECONDS[o.mode] || CLIP_SECONDS.chain)(n, o);
   const videos = round2(clipSeconds * VIDEO_USD_PER_SEC);
   const usd = round2(images + videos);
   return { images, videos, usd };