@kaydash9999/banker-plugins 0.22.0 → 0.23.2

package/skills/3d-intro-build/references/dive-mode.mjs

@@ -0,0 +1,299 @@
+/*
+ * dive mode for 3d-intro-build (CLIP_MODE = dive): the default on every provider, without exits. Measured on
+ * sora-2 (2025-12-08, one scene set): each scene shows, arc turns little, the finale lands only through
+ * landOnStill. dive on WAN is not measured.
+ *
+ * Every scene but the last gets a dive that starts from that scene's approved still (so each scene
+ * is entered from outside, with a MOVE: push-in, arc or crane). An optional exit clip leaves the
+ * scene from the dive's last frame. The last scene is the finale: a clip that pulls back from the
+ * closing still, played reversed, so it ends on that still. The seam to the next scene does not
+ * rely on the model: when the next clip's actual first frame has a background border (at least
+ * `bgShare` of its border band within `bgTolerance` of the band's most common colour, so a roof or a
+ * plume touching the edge does not count), the seam side (the exit, or the dive without one) lands on
+ * a plate of that background colour (clip-post landOnStill). One frame decides and gives the colour.
+ *
+ *   planDiveLegs   the legs in order (pure)
+ *   runDiveLegs    makes them with generateClip (injectable), post-processes, writes intro.json;
+ *                  { only: 'first' } makes scene 1's dive (and its exit only with exit: true, choice c) and
+ *                  stops at the first pair gate: the dive landed, and with an exit both versions to compare
+ *
+ * A generated clip is kept as <name>.raw.mp4 beside <name>.raw.json, the fingerprint of what made it
+ * (prompt, seed frame, seconds, size, MOVE, provider order). A run after the gate (or after a stop) reuses
+ * it only when that fingerprint is the same, so it does not pay for a leg twice; a changed leg (a new MOVE,
+ * length or seed) is made again ('stale' event). A raw clip with no record stops with kind 'reuse_unknown'.
+ * The clip is written to a temporary name and renamed, so a cut-off write leaves no raw clip.
+ * Events go to onEvent; none carries a key.
+ * Runtime: Node >=18 builtins and ffmpeg.
+ */
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { estimateCost, extractFirstFrame, extractLastFrame, probeDims, resolveFfmpeg } from './azure-adapter.mjs';
+import { generateClip, parseProviderOrder } from './video-pool.mjs';
+import { borderColour, cameraMotion, postClip, resizePng, seamSsim, solidPlate } from './clip-post.mjs';
+
+export const DIVE_DEFAULTS = { diveSeconds: 8, exitSeconds: 4, finaleSeconds: 8, border: 0.04, bgShare: 0.85, bgTolerance: 12, landSec: 0.6, finaleLandSec: 0.4 };
+export const MOVES = ['push-in', 'arc', 'crane'];
+
+function moveOf(scene, i) {
+  const m = scene?.move || 'push-in';
+  if (!MOVES.includes(m)) throw new Error(`planDiveLegs: scene ${i + 1} MOVE "${m}" is not one of ${MOVES.join(', ')}`);
+  return m;
+}
+
+/**
+ * The legs of a dive-mode intro, in the order they are made. `scenes` are the manifest sections
+ * (with an optional `move`); `exit` adds one exit after each dive. Seeds: a dive and the finale start
+ * from their scene's still, an exit from its dive's last frame.
+ */
+export function planDiveLegs({ scenes, exit = false, diveSeconds = DIVE_DEFAULTS.diveSeconds, exitSeconds = DIVE_DEFAULTS.exitSeconds, finaleSeconds = DIVE_DEFAULTS.finaleSeconds } = {}) {
+  const n = Array.isArray(scenes) ? scenes.length : 0;
+  if (n < 2) throw new Error('planDiveLegs: dive mode needs two scenes or more (dives, then the finale)');
+  const legs = [];
+  for (let i = 0; i < n - 1; i++) {
+    legs.push({ kind: 'dive', scene: i, name: `dive-${i + 1}`, seed: { from: 'still', scene: i }, move: moveOf(scenes[i], i), seconds: diveSeconds });
+    if (exit) legs.push({ kind: 'exit', scene: i, name: `exit-${i + 1}`, seed: { from: 'last-frame', leg: `dive-${i + 1}` }, seconds: exitSeconds });
+  }
+  legs.push({ kind: 'finale', scene: n - 1, name: 'finale', seed: { from: 'still', scene: n - 1 }, seconds: finaleSeconds, reverse: true });
+  return legs;
+}
+
+/**
+ * Whether a frame has a background border to land a seam on: at least `bgShare` of the band along its
+ * edges (`border` of each side) within `bgTolerance` of the band's most common colour. `rgb` is that
+ * background colour (the plate's). Returns the measured share either way.
+ */
+export async function judgeBackground(png, { border = DIVE_DEFAULTS.border, bgShare = DIVE_DEFAULTS.bgShare, bgTolerance = DIVE_DEFAULTS.bgTolerance, ffmpeg } = {}) {
+  const m = await borderColour(png, { border, tolerance: bgTolerance, ffmpeg });
+  const share = Math.round(m.share * 1000) / 1000;
+  return { on: m.share >= bgShare, share, rgb: m.rgb.map((x) => Math.round(x * 10) / 10), threshold: bgShare, tolerance: bgTolerance };
+}
+
+// ---------------------------------------------------------------------------
+// runDiveLegs
+// ---------------------------------------------------------------------------
+
+/**
+ * Make the dive-mode clips and write intro.json.
+ *   projectDir   the project folder (stills are paths relative to it, as in intro.json)
+ *   manifest     the intro.json to fill: sections (still, copy, optional move and zoom) and the rest
+ *   size         ORIENTATION ('720x1280'); a still of another size is scaled before it seeds a clip
+ *   promptFor(leg, section)   the prompt of each leg (prompts.md: dive, exit, finale)
+ *   exit         make exit clips (connectors); default false (dive without exits is the default mode)
+ *   only         'first': scene 1's dive, and its exit only when exit is true (no exit is paid for in choice b), then stop
+ *   generate     the clip maker (default generateClip); creds and clipOptions are passed on
+ *   bgShare, bgTolerance, border, landSec, finaleLandSec, diveSeconds, exitSeconds, finaleSeconds, reuse (default true), ffmpeg, onEvent
+ * Returns { stage: 'first-pair', ... } at the gate, else { stage: 'done', manifest, file, seams } (seams: each gap's judgeBackground).
+ */
+export async function runDiveLegs(opts = {}) {
+  const o = { ...DIVE_DEFAULTS, exit: false, reuse: true, generate: generateClip, clipsDir: 'clips', ...opts };
+  if (!o.projectDir || !o.manifest || !o.size || typeof o.promptFor !== 'function') throw new Error('runDiveLegs: projectDir, manifest, size and promptFor are required');
+  const ctx = await prepare(o);
+  const first = o.only === 'first';
+  const legs = planDiveLegs({ scenes: o.manifest.sections, exit: o.exit, diveSeconds: o.diveSeconds, exitSeconds: o.exitSeconds, finaleSeconds: o.finaleSeconds });
+  for (const leg of first ? legs.filter((l) => l.scene === 0 && l.kind !== 'finale') : legs) await makeLeg(ctx, leg);
+  if (first) return firstPair(ctx);
+  await finish(ctx);
+  return writeManifest(ctx);
+}
+
+async function prepare(o) {
+  const emit = (e) => { if (typeof o.onEvent === 'function') o.onEvent(e); };
+  const dir = path.join(o.projectDir, o.clipsDir);
+  fs.mkdirSync(dir, { recursive: true });
+  const bin = o.ffmpeg || await resolveFfmpeg();
+  const ctx = { o, emit, dir, bin, n: o.manifest.sections.length, seeds: [], seams: [], raw: {}, shown: {} };
+  for (let i = 0; i < ctx.n; i++) ctx.seeds.push(await sizedStill(ctx, i));
+  return ctx;
+}
+
+const abs = (ctx, rel) => path.join(ctx.o.projectDir, ...String(rel).split(/[\\/]/));
+const relOf = (ctx, file) => path.relative(ctx.o.projectDir, file).split(path.sep).join('/');
+const sizeOf = (size) => String(size).split('x').map(Number);
+
+// The scene's still as a seed: as it is when its size is ORIENTATION, else scaled (the classic image path gives 1024x1536).
+async function sizedStill(ctx, i) {
+  const still = abs(ctx, ctx.o.manifest.sections[i].still);
+  const { width, height } = probeDims(still);
+  const [w, h] = sizeOf(ctx.o.size);
+  if (width === w && height === h) return still;
+  ctx.emit({ type: 'resize', scene: i + 1, from: `${width}x${height}`, to: ctx.o.size });
+  return resizePng(still, ctx.o.size, path.join(ctx.dir, `still-${i + 1}.sized.png`), { ffmpeg: ctx.bin });
+}
+
+// Judge gap i on `png` (the frame the seam meets) and keep the result; `what` names that frame in the events.
+async function seamPlan(ctx, i, png, what) {
+  const j = await judgeBackground(png, { border: ctx.o.border, bgShare: ctx.o.bgShare, bgTolerance: ctx.o.bgTolerance, ffmpeg: ctx.bin });
+  ctx.emit({ type: 'seam', gap: i + 1, background: j.on, share: j.share, threshold: j.threshold, frame: what });
+  if (!j.on) {
+    ctx.emit({ type: 'note', gap: i + 1, message: `${what} has no background border (${j.share} of the band near its most common colour, under ${j.threshold}): this seam is the engine's dissolve, no background plate` });
+  }
+  ctx.seams[i] = { gap: i + 1, frame: what, ...j };
+  return ctx.seams[i];
+}
+
+// Generate one leg unless its raw clip is already there (reuse), then keep the version the next leg sees.
+async function makeLeg(ctx, leg) {
+  const raw = path.join(ctx.dir, `${leg.name}.raw.mp4`);
+  ctx.raw[leg.name] = raw;
+  const prompt = ctx.o.promptFor(leg, ctx.o.manifest.sections[leg.scene]);
+  const seed = fs.readFileSync(await seedFor(ctx, leg));
+  const fp = legPrint(ctx, leg, prompt, seed);
+  if (ctx.o.reuse && reusable(ctx, leg, raw, fp)) ctx.emit({ type: 'leg', name: leg.name, kind: leg.kind, reused: true });
+  else {
+    const r = await ctx.o.generate({ creds: ctx.o.creds, prompt, size: ctx.o.size, seconds: leg.seconds, firstFramePng: seed, onEvent: ctx.emit, ...ctx.o.clipOptions });
+    writeAtomic(raw, r.mp4);
+    writeAtomic(`${raw.slice(0, -4)}.json`, `${JSON.stringify(fp, null, 2)}\n`);
+    ctx.emit({ type: 'leg', name: leg.name, kind: leg.kind, move: leg.move, provider: r.provider, label: r.label, seconds: r.seconds });
+  }
+  if (leg.kind === 'dive') await keepShown(ctx, leg);
+}
+
+const sha = (b) => crypto.createHash('sha256').update(b).digest('hex');
+
+// What makes a leg's clip: no key, the prompt and the seed as hashes.
+function legPrint(ctx, leg, prompt, seed) {
+  const order = ctx.o.clipOptions?.order || parseProviderOrder(ctx.o.creds?.VIDEO_PROVIDER_ORDER);
+  return { prompt: sha(String(prompt)), seed: sha(seed), seconds: leg.seconds, size: ctx.o.size, move: leg.move || null, order };
+}
+
+// A raw clip is reused only when its record matches; a changed leg is made again, an unrecorded clip stops.
+function reusable(ctx, leg, raw, fp) {
+  if (!fs.existsSync(raw)) return false;
+  const rec = `${raw.slice(0, -4)}.json`;
+  if (!fs.existsSync(rec)) {
+    throw Object.assign(new Error(`runDiveLegs: ${path.basename(raw)} has no record (${path.basename(rec)}) of what made it, so it is not known to fit this leg; delete it to make the leg again, or pass reuse: false`), { kind: 'reuse_unknown', leg: leg.name });
+  }
+  let was = null;
+  try { was = JSON.parse(fs.readFileSync(rec, 'utf8')); } catch { /* unreadable: made again */ }
+  const changed = Object.keys(fp).filter((k) => JSON.stringify(was?.[k]) !== JSON.stringify(fp[k]));
+  if (changed.length) ctx.emit({ type: 'stale', name: leg.name, changed, message: `${leg.name}: ${changed.join(', ')} changed since the clip was made; making it again` });
+  return !changed.length;
+}
+
+// Write to a fresh temporary name, then rename: a write cut off leaves no file under the final name.
+function writeAtomic(file, data) {
+  const tmp = `${file}.${crypto.randomBytes(6).toString('hex')}.tmp`;
+  try {
+    fs.writeFileSync(tmp, data, { flag: 'wx' });
+    fs.renameSync(tmp, file);
+  } catch (e) {
+    fs.rmSync(tmp, { force: true });
+    throw e;
+  }
+}
+
+// A dive or the finale starts from its still; an exit from its dive's last frame, taken from what
+// shows (the zoomed dive when zoomBoost is on, else the dive as generated), before any landing.
+async function seedFor(ctx, leg) {
+  if (leg.seed.from === 'still') return ctx.seeds[leg.scene];
+  const png = path.join(ctx.dir, `seed-${leg.name}.png`);
+  await extractLastFrame(ctx.shown[leg.seed.leg], png, { ffmpeg: ctx.bin });
+  return png;
+}
+
+async function keepShown(ctx, leg) {
+  const to = ctx.o.manifest.sections[leg.scene].zoom;
+  if (!to) { ctx.shown[leg.name] = ctx.raw[leg.name]; return; }
+  const out = path.join(ctx.dir, `${leg.name}.zoom.mp4`);
+  report(ctx, leg.name, await postClip(ctx.raw[leg.name], out, { zoom: { to } }, { ffmpeg: ctx.bin }));
+  ctx.shown[leg.name] = out;
+}
+
+function report(ctx, name, r) {
+  ctx.emit({ type: 'post', clip: name, fn: r.steps, encoded: r.encoded });
+  return r;
+}
+
+// ---------------------------------------------------------------------------
+// After every leg: finale, seams, connector posters
+// ---------------------------------------------------------------------------
+
+async function finish(ctx) {
+  const finale = path.join(ctx.dir, 'finale.mp4');
+  report(ctx, 'finale', await postClip(ctx.raw.finale, finale, { reverse: true, land: { png: ctx.seeds[ctx.n - 1], sec: ctx.o.finaleLandSec } }, { ffmpeg: ctx.bin }));
+  ctx.finale = finale;
+  for (let i = 0; i < ctx.n - 1; i++) await finishGap(ctx, i);
+}
+
+// The clip after gap i, as it plays: the next dive, or the finale.
+const nextClip = (ctx, i) => (i + 1 < ctx.n - 1 ? ctx.shown[`dive-${i + 2}`] : ctx.finale);
+
+async function finishGap(ctx, i) {
+  const land = await plateLanding(ctx, i, nextClip(ctx, i));
+  const dive = path.join(ctx.dir, `dive-${i + 1}.mp4`);
+  if (!ctx.o.exit) { await placeOrPost(ctx, `dive-${i + 1}`, ctx.shown[`dive-${i + 1}`], dive, land ? { land } : {}); return; }
+  fs.copyFileSync(ctx.shown[`dive-${i + 1}`], dive);
+  const exit = path.join(ctx.dir, `exit-${i + 1}.mp4`);
+  await placeOrPost(ctx, `exit-${i + 1}`, ctx.raw[`exit-${i + 1}`], exit, land ? { land } : {});
+  await extractFirstFrame(exit, path.join(ctx.dir, `exit-${i + 1}-first.png`), { ffmpeg: ctx.bin });
+}
+
+async function placeOrPost(ctx, name, src, out, steps) {
+  if (!Object.keys(steps).length) { fs.copyFileSync(src, out); return; }
+  report(ctx, name, await postClip(src, out, steps, { ffmpeg: ctx.bin }));
+}
+
+// The next clip's actual first frame decides the seam and gives the plate colour; null when it has no background border.
+async function plateLanding(ctx, i, next) {
+  const first = await extractFirstFrame(next, path.join(ctx.dir, `next-${i + 1}-first.png`), { ffmpeg: ctx.bin });
+  return plateFrom(ctx, i, first, `the first frame of ${relOf(ctx, next)}`);
+}
+
+async function plateFrom(ctx, i, png, what) {
+  const j = await seamPlan(ctx, i, png, what);
+  if (!j.on) return null;
+  const plate = await solidPlate(j.rgb, ctx.o.size, path.join(ctx.dir, `plate-${i + 1}.png`), { ffmpeg: ctx.bin });
+  ctx.emit({ type: 'plate', gap: i + 1, rgb: j.rgb.map(Math.round) });
+  return { png: plate, sec: ctx.o.landSec };
+}
+
+function writeManifest(ctx) {
+  const m = ctx.o.manifest;
+  const last = ctx.n - 1;
+  const finaleFirst = path.join(ctx.dir, 'finale-first.png');
+  return extractFirstFrame(ctx.finale, finaleFirst, { ffmpeg: ctx.bin }).then(() => {
+    const sections = m.sections.map((s, i) => ({ ...s, clip: relOf(ctx, path.join(ctx.dir, i === last ? 'finale.mp4' : `dive-${i + 1}.mp4`)), ...(i === last ? { still: relOf(ctx, finaleFirst) } : {}) }));
+    const gaps = Array.from({ length: last }, (_, i) => i + 1);
+    const manifest = { ...m, sections, connectors: gaps.map((g) => (ctx.o.exit ? relOf(ctx, path.join(ctx.dir, `exit-${g}.mp4`)) : null)) };
+    if (ctx.o.exit) manifest.connectorStills = gaps.map((g) => relOf(ctx, path.join(ctx.dir, `exit-${g}-first.png`)));
+    const file = path.join(ctx.o.projectDir, ctx.o.manifestOut || 'intro.json');
+    fs.writeFileSync(file, `${JSON.stringify(manifest, null, 2)}\n`);
+    return { stage: 'done', manifest, file, seams: ctx.seams };
+  });
+}
+
+// ---------------------------------------------------------------------------
+// First pair gate: scene 1 without the exit and with it, side by side
+// ---------------------------------------------------------------------------
+
+async function firstPair(ctx) {
+  const gate = path.join(ctx.dir, 'gate');
+  fs.mkdirSync(gate, { recursive: true });
+  // the next clip does not exist yet: the next still decides and gives the colour (the next dive starts from that still)
+  const land = await plateFrom(ctx, 0, ctx.seeds[1], 'the next scene\'s still');
+  const noExit = path.join(gate, 'dive-1.noexit.mp4');
+  await placeOrPost(ctx, 'dive-1', ctx.shown['dive-1'], noExit, land ? { land } : {});
+  const motion = await cameraMotion(ctx.shown['dive-1'], { ffmpeg: ctx.bin });
+  const base = { stage: 'first-pair', seam: ctx.seams[0], withoutExit: [relOf(ctx, noExit)], motion: { rollDeg: motion.rollDeg, zoom: motion.zoom, method: motion.method } };
+  // choice b: no exit was made; what turning to c would add (exits between every pair of scenes), to approve first
+  if (!ctx.o.exit) return { ...base, withExit: null, switchToExitUsd: switchCost(ctx) };
+  const dive = path.join(gate, 'dive-1.mp4');
+  fs.copyFileSync(ctx.shown['dive-1'], dive);
+  const exit = path.join(gate, 'exit-1.mp4');
+  await placeOrPost(ctx, 'exit-1', ctx.raw['exit-1'], exit, land ? { land } : {});
+  return { ...base, exitEnd: await exitEnd(ctx), withExit: [relOf(ctx, dive), relOf(ctx, exit)], diveExitSsim: await seamSsim(dive, exit, { ffmpeg: ctx.bin }) };
+}
+
+// What exits between every pair of scenes add to the estimate (Sora rate, as Step 2 approved it).
+function switchCost(ctx) {
+  const at = (exit) => estimateCost({ nScenes: ctx.n, mode: 'dive', diveSeconds: ctx.o.diveSeconds, exitSeconds: ctx.o.exitSeconds, exit }).videos;
+  return Math.round((at(true) - at(false)) * 100) / 100;
+}
+
+// Whether the exit as generated reached the background by its end (the same measure), for the gate to show.
+async function exitEnd(ctx) {
+  const end = await extractLastFrame(ctx.raw['exit-1'], path.join(ctx.dir, 'gate', 'exit-1-end.png'), { ffmpeg: ctx.bin });
+  const j = await judgeBackground(end, { border: ctx.o.border, bgShare: ctx.o.bgShare, bgTolerance: ctx.o.bgTolerance, ffmpeg: ctx.bin });
+  return { reached: j.on, share: j.share, threshold: j.threshold };
+}

package/skills/3d-intro-build/references/intro-fixes.css

@@ -50,6 +50,17 @@
   .sw-route__label { display: none; }
 }
 
+/* Before a clip is ready the engine shows the scene's poster with a small zoom and shift of its own
+   (an inline transform on the img); the clip itself has none. When the clip appears the picture
+   jumps by that zoom (seen on a slow network at the first seams). The poster stays as still as the
+   clip's first frame: the inline style loses to !important, the engine file stays as shipped. */
+.sw-scene__still { transform: none !important; }
+
+/* The engine hides the poster the moment a clip has seeked, before the clip's frame is on screen: on
+   a slow network that left one or two frames with no picture at all. The poster stays under the clip
+   for 0.15 s more (the clip is on top from the start, so nothing fades; reduced motion loads no clip). */
+.sw-scene.has-clip .sw-scene__still { transition: opacity 0s linear .15s; }
+
 /* The engine draws its primary buttons in white on the theme's ink colour, which a dark theme
    (light ink) turns into white on a light pill. The theme's background colour reads on the ink in
    any theme, as the body text reads on the background. */

package/skills/3d-intro-build/references/prompts.md

@@ -28,12 +28,12 @@ Higgsfield·Monid 같은 외부 CLI 플래그는 쓰지 않는다 — 크기·
 - `PALETTE` — 4~6개 명명 hex. 예: `taro #9B7EBD, cream #F5EDE0, caramel #C88A5A, matcha #8FB98A, plum #3A2E48`. 하나를 씬 **배경색**(보통 가장 밝은 색), 하나를 기본 **accent** 로 고른다. 이 배경색을 페이지 테마(`--sw-bg`)에도 그대로 쓴다.
 - `TONE` — 한두 단어(cozy/premium, playful, industrial…).
 - `STYLE` — 아트디렉션(기본은 아래 clay diorama).
-- `CAMERA_FEEL` — fly-through(디오라마를 내려다보다 안으로 급강하) | walkthrough(한 번에 쭉 전진) | locked-iso(고정 아이소메트릭 활공). 느낌으로 제시하고 트레이드오프 한 줄씩 곁들인다.
+- `CAMERA_FEEL` — 기본은 `CLIP_MODE` 를 따른다. dive 면 "장면마다 바깥에서 들어감"(장면별 MOVE: push-in, arc, crane. 8절), chain 이나 holdFlight 면 fly-through(디오라마를 내려다보다 안으로 급강하) | walkthrough(한 번에 쭉 전진) | locked-iso(고정 아이소메트릭 활공). 느낌으로 제시하고 트레이드오프 한 줄씩 곁들인다.
 - `MOBILE` — yes/no. yes 면 세로 9:16 렌더를 별도로 만들어 `clipMobile`/`stillMobile` 로 배선한다(대략 2배 비용, 승인 게이트에 반영).
 - `STILLS_SOURCE` — 기본 `gpt-image-2`(`generateImage`). 씬 간 코히전을 더 강하게 원하면 `FLUX.2-pro`(`generateImageFlux`) 옵트인.
-- `CLIP_MODE` — `chain`(기본, 검증된 경로) 또는 `holdFlight`(장면마다 정지 클립, 장면 사이 첫과 끝 프레임을 지정한 비행 클립. WAN 필요, 이 스킬에서 미검증).
+- `CLIP_MODE` — 세 가지를 보이고 고르게 한다(SKILL Step 1): a `chain`(4절), b `dive` 나가기 없음(기본, 8절), c `dive` 나가기 있음. provider 와 관계없이 기본은 b 다(sora-2 비교 페이지에서 사용자가 고름). 영상이 WAN 으로 돌면 고를 때 "WAN 에서 dive 는 미측정" 을 알린다. `holdFlight`(장면마다 정지 클립, 장면 사이 첫과 끝 프레임을 지정한 비행 클립. WAN 필요, 이 스킬에서 미검증)는 원할 때만.
 - `SITE` — 단독 인트로 페이지 또는 기존 사이트 위에 붙임. 붙이면 그 사이트의 CSP, 본문 시작 선택자, 고정 헤더 선택자, 지원 언어를 받는다.
-- `STEP_NAV` — yes 면 휠 1칸, 키, 스와이프가 정확히 한 장면을 이동한다. 스크롤 동작을 가로채므로 사이트 성격을 보고 고른다.
+- `STEP_NAV` — 기본 yes. 장면 시작점에 멈추는 장면 단위 이동이다(휠 1칸과 방향키 1번은 절반, 2번이면 한 장면, PageDown 과 Space 는 한 장면). 스크롤 동작을 가로채므로 원하지 않으면 no(매니페스트 `"stepNav": false`).
 - `PANEL` — `glass` 면 흐린 유리 문구 패널. 기본값은 어두운 장면용이다. 밝은 장면이 많으면 대비 기준(4.5)을 지키도록 패널을 덜 투명하게(`--intro-panel-alpha` .6 이상) 한다.
 
 ---
@@ -110,7 +110,7 @@ in, the roof and upper structure gently lift and open away to reveal the warm in
 여닫을 건물이 없는 씬(들판·광장·도로)이면 지붕 절을 "the camera flies low across [the scene] toward [focal point]." 로 바꾼다.
 
 **Leg i (i ≥ 1) — 체이닝된 프레임에서 다음 씬으로:**
-`firstFramePng = extractLastFrame(clip[i-1])` (직전 클립의 **raw** 마지막 프레임. 톤 정합을 걸면 연속성이 나빠진다: 실측 raw SSIM ~0.59, histeq 0.46).
+`firstFramePng = extractLastFrame(clip[i-1])` (직전 클립의 **raw** 마지막 프레임. 시드에 톤 정합을 걸면 연속성이 나빠진다: 실측 raw SSIM ~0.59, histeq 0.46. 클립 쪽 톤 맞춤도 하지 않는다: sora-2 실측에서 새 클립 첫 프레임이 시드와 채널 평균 2.6/255 안이었다).
 
 ```
 Single continuous cinematic camera move, no cuts. Continue the same continuous camera flight
@@ -192,3 +192,50 @@ no captions.
 - 일이 일어나는 자리가 맞아야 한다. 예: 막는 장면은 이미 뚫린 안쪽이 아니라 바깥 경계에서 막는 모습으로.
 - 화면 속 글자는 깨지기 쉽다. 프롬프트 끝의 "No text, no captions." 를 지키고, 글자가 깨진 결과는 재생성한다.
 - 사물이 엉뚱한 위치에 뜨거나, 강조색이 유리나 다른 물체로 번지면 그 결과만 재생성한다.
+
+---
+
+## 8. dive 모드 프롬프트 (`CLIP_MODE = dive`, 기본 b 는 나가기 없음)
+
+장면마다 그 장면의 승인 스틸에서 시작한다(`firstFramePng = 장면 i 스틸`). 장면 사이 이음매는 Sora 가 배경까지 물러나는지에 기대지 않는다. 다음 장면 스틸의 테두리가 한 색이면 이음매 쪽 끝 0.6초를 그 색의 판으로 착지시킨다(`landOnStill`, 무료). 실행 순서와 첫 쌍 게이트는 SKILL Step 4C.
+chain 프롬프트(4절)는 바꾸지 않았다. 아래는 dive 모드에만 쓴다.
+
+**dive 모드의 스틸(선택, 미검증):** dive 모드에서만 스타일 서문 바로 뒤에 `Generous empty margin of plain background on every side; nothing touches the frame edges.` 를 붙일 수 있다. 가장자리에 닿는 지붕이나 연기를 줄여 배경 이음매가 켜질 몫을 늘리려는 문장이다. 효과는 재지 않았고, chain 과 holdFlight 의 스틸에는 붙이지 않는다(스타일 서문은 모든 장면에 글자 그대로 같아야 한다).
+
+**dive (장면 i, 마지막 장면 제외, 8초):**
+
+```
+Aerial wide shot, slight downward angle, 35 mm virtual lens, of the whole [SCENE i subject]
+as a small island on a plain solid [BG_HEX] background. One continuous camera move, no cuts.
+0-1s: hold the aerial wide shot. 1-7s: [MOVE]. Final second: arrive at a close view of
+[FOCAL POINT]. Only the camera moves. [STYLE tail + PALETTE]. No text, no captions.
+```
+
+| MOVE | 문구 | 쓰는 곳 |
+|---|---|---|
+| `push-in` (기본) | "one steady push-in and descent toward [FOCAL POINT], [the roof and upper structure lift away to reveal the interior / flying low across the scene]" | 대부분의 장면 |
+| `arc` (회전, 순응 낮음) | "a slow arc in around [FOCAL POINT], about a quarter turn, descending as it circles, keeping [FOCAL POINT] centered" | 제품, 랜드마크, 결론 앞 장면. 실측 3개 가운데 눈으로 돈 것은 1개라 첫 쌍 게이트에서 눈으로 확인 |
+| `crane` | "a crane down from high above, descending straight toward [FOCAL POINT] as the scene grows to fill the frame" | 넓은 공간, 광장 |
+
+**exit (선택 c 에서만, 장면 i 와 i+1 사이, 4초, dive 의 마지막 프레임에서):**
+
+```
+One continuous camera move, no cuts. The camera pulls straight up and back away from
+[FOCAL POINT], rising out of [SCENE i] until the whole island is small, then keeps receding
+toward the plain solid [BG_HEX] background. Only the camera moves. No text, no captions.
+```
+
+**finale (마지막 장면, 8초, 결론 스틸에서 멀어지게 만든 뒤 뒤집음):**
+
+```
+One continuous camera move, no cuts. Starting from this view of [PRODUCT], the camera pulls
+straight back and slightly up, [PRODUCT] shrinking toward the center of the plain solid
+[BG_HEX] background until it is small. 0-0.5s: hold still. Static: figures hold still,
+no smoke, no water flow, only the camera moves. No text, no captions.
+```
+
+- "figures hold still" 은 finale 에만 둔다. 뒤집으면 사람과 연기의 움직임도 거꾸로 보이기 때문이다.
+- finale 는 `reverseClip` 으로 뒤집고 끝 0.4초를 결론 스틸에 착지시킨다. 그래서 마지막 화면이 결론 스틸 그대로다.
+- arc 의 회전량은 공식 어휘가 "slow arc in" 까지라 결과를 장담하지 못한다. sora-2 실측에서 roll 근사 누적은 3개 모두 10도 아래였고, 눈으로는 1개만 4분의 1 바퀴에 가깝게 돌았다. roll 근사는 궤도 회전을 재지 못하므로 눈 검토(`verify.md`)가 주 판정이다.
+- 나가기는 선택 c 에서만 만든다(기본 b 는 없음). sora-2 실측에서 나가기 6개 가운데 4개가 끝에서 배경에 닿았고, 원본 이음매 SSIM 이 나가기 없음 0.43~0.60 에서 0.59~0.81 로 올랐다.
+- WAN 으로 돌면(`VIDEO_PROVIDER_ORDER` 기본 `wan,sora`) 같은 프롬프트를 쓰되 그 경로는 미검증이다. WAN 은 exit 에 `lastFramePng = 배경 판` 을 줄 수 있으나 설계만 했고 유료로 확인하지 않았다.

package/skills/3d-intro-build/references/scrub-engine.js

@@ -97,6 +97,7 @@ function mountScrollWorld(container, config) {
       SEGMENTS.push({ kind: 'conn', si: i, clip: CONNECTORS[i], clipM: CONNECTORS_M[i],
                       still: SECTIONS[i + 1].still, stillM: SECTIONS[i + 1].stillMobile,
                       accent: SECTIONS[i + 1].accent, w: CONN_W });
+      if ((config.connectorStills || [])[i]) Object.assign(SEGMENTS[SEGMENTS.length - 1], { still: config.connectorStills[i], stillM: null }); // banker: opt-in connector poster, see NOTICE.md
     }
   });
   const NSEG = SEGMENTS.length;

package/skills/3d-intro-build/references/step-nav.css

@@ -57,3 +57,32 @@ html.isn-ready .isn-main { display: inline-flex; }
 /* The last scene keeps the main button alone; the body shows none of these. */
 html.isn-last .isn-hint, html.isn-last .sw-hint, html.isn-last .isn-skip,
 html.isn-body .isn-hint, html.isn-body .sw-hint, html.isn-body .isn-skip, html.isn-body .isn-main { display: none !important; }
+
+/* At a stop or a half point step-nav.js marks the copy of the scene in view (isn-copy): it shows over the
+   engine's own fade, which leaves a middle scene's copy hidden at its start. When a move starts the mark
+   goes and the engine's fade takes over; both ways the opacity eases, at once under reduced motion. */
+.isn-on .sw-copy { transition: opacity .35s ease; }
+.isn-on .sw-copy.isn-copy { opacity: 1 !important; pointer-events: auto !important; }
+@media (prefers-reduced-motion: reduce) {
+  .isn-on .sw-copy { transition: none; }
+}
+/* An instant move (Home, End, a route dot) swaps the copy at once. */
+.isn-on.isn-instant .sw-copy { transition: none; }
+
+/* The loading mark of a poster wait longer than loadingDelayMs (step-nav.js): small, mid-screen, above the
+   scenes, taking no input. A status region, so its text reaches a screen reader; it never takes the focus. */
+.isn-loading {
+  position: fixed; left: 50%; top: 50%; z-index: 300; transform: translate(-50%, -50%);
+  display: none; align-items: center; gap: 10px; padding: 10px 16px; border-radius: 999px;
+  background: color-mix(in srgb, var(--sw-bg, #000) 78%, transparent); color: var(--sw-ink, #fff);
+  font-size: .82rem; letter-spacing: .04em; pointer-events: none;
+}
+.isn-loading.is-on { display: flex; }
+.isn-loading__spin {
+  width: 16px; height: 16px; border-radius: 50%; border: 2px solid currentColor; border-right-color: transparent;
+  animation: isn-spin .8s linear infinite;
+}
+@keyframes isn-spin { to { transform: rotate(360deg); } }
+@media (prefers-reduced-motion: reduce) {
+  .isn-loading__spin { animation: none; border-right-color: currentColor; opacity: .6; }
+}