SCENEGOD/scenegod/web/render.js

// render.js — draft + final video capture (Lane C, PLAN §4.3 / C-server §C5).
// Talks to Stage/Timeline through their public APIs only. No three.js import.
//
//   draftRecord(stage, timeline)       -> Promise<Blob>  quick webm via MediaRecorder
//   finalRender(stage, timeline, opts) -> Promise<url>   deterministic PNG->ffmpeg mp4
//
// The pieces finalRender is built from are exported too — web/film.js drives the
// same loop once per shot of a multi-shot sequence (M8-C), so the frame-post path
// exists exactly once.
// All URLs are RELATIVE: the app serves at / locally and /scenegod/ in prod.

const sleep = ms => new Promise(r => setTimeout(r, ms));

// --- draft: record the live canvas while the timeline plays, once through ----
export function draftRecord(stage, timeline, { fps = 30, mimeType = 'video/webm' } = {}) {
  const stream = stage.renderer.domElement.captureStream(fps);
  const rec = new MediaRecorder(stream, MediaRecorder.isTypeSupported(mimeType) ? { mimeType } : {});
  const chunks = [];
  rec.ondataavailable = e => e.data.size && chunks.push(e.data);
  return new Promise((resolve, reject) => {
    rec.onstop = () => resolve(new Blob(chunks, { type: rec.mimeType || 'video/webm' }));
    rec.onerror = reject;
    rec.start();
    timeline.seek(0);
    timeline.play();
    const stop = timeline.onTick(t => {
      if (t >= timeline.duration) { timeline.pause(); rec.stop(); if (typeof stop === 'function') stop(); }
    });
  });
}

// --- render-session primitives (shared with film.js) -------------------------

// Render at exactly width x height, then put the viewport back however fn ends.
// canvas.width/height are DEVICE pixels (CSS size x devicePixelRatio) but setSize
// multiplies by the ratio AGAIN — restoring those grew the viewport buffer by dpr
// per render on a retina Mac (4x the pixels after one film, 16x after two, until a
// window resize). Snapshot the CSS size instead; clientWidth is 0 while the panel
// is hidden, so fall back to device/dpr. (No three import here — header rule.)
export async function withRenderSize(stage, width, height, fn) {
  const canvas = stage.renderer.domElement;
  const dpr = stage.renderer.getPixelRatio() || 1;
  const prev = { w: canvas.clientWidth || Math.round(canvas.width / dpr),
                 h: canvas.clientHeight || Math.round(canvas.height / dpr), dpr };
  stage.renderer.setPixelRatio(1);
  stage.renderer.setSize(width, height, false);   // false = don't touch CSS size
  try { return await fn(); }
  finally {
    stage.renderer.setPixelRatio(prev.dpr);
    stage.renderer.setSize(prev.w, prev.h, false);
  }
}

// Supersample factor: render 2x the deliverable and let ffmpeg's lanczos resolve
// it (server vf_args). MSAA only cleans geometry edges — shading and texture
// aliasing (fences, foliage, hair cards, specular sparkle) crawl frame to frame
// without this. Forced off above 1080p: a 4K x2 buffer blows past sane texture
// limits and pushes PNG frames at the body cap.
export function ssFactor(width, height, ss = 2) {
  return (width > 1920 || height > 1080) ? 1 : Math.max(1, ss | 0);
}

export async function beginRender({ name = 'scene', fps = 30, width = 1920, height = 1080 } = {}) {
  return postJSON('render/begin', { name, fps, width, height });
}

// Stage._chrome(true) re-shows editor chrome after every PAUSED frame by forcing
// visible = true on the TransformControls object — including when detach() had
// just set it to false. three r160's TransformControls is a scene-added Object3D
// (index.html pins three@0.160.0; stage.js does scene.add(tc)) whose attach/detach
// drive `.visible` directly, and stage.select() detaches whenever nothing is
// selected OR a frustum-fitted plate is. So a render started from those states used
// to END with a ghost gizmo floating at the last object's position, inert until the
// next click — the exact class of bug pause() was added to kill.
// Re-running select() with the id Stage already holds re-runs attach/detach and puts
// the gizmo back where the selection says it should be. Cheap and idempotent.
// The real fix is stage.js saving/restoring visibility instead of forcing it (Lane A
// owns that file — logged as a REQUEST); this is the render-side guarantee that our
// pause() cannot leave the editor damaged. Skipped when the Stage has no `_selected`
// field: unknown shape, don't guess a selection.
function restoreSelectionChrome(stage) {
  if (typeof stage.select !== 'function' || !('_selected' in stage)) return;
  const id = stage._selected ?? null;
  // film.js swaps the whole scene between shots, so the remembered id can be gone
  // by now — re-selecting it would point Stage at an entity that no longer exists.
  const alive = id != null && (typeof stage.getEntity !== 'function' || !!stage.getEntity(id));
  stage.select(alive ? id : null);
}

// Step [from, to) on the timeline and post those frames as 0..n-1 of renderId.
// Deterministic: timeline.step() is seek+evaluate, never wall-clock.
// stage.pause() is the ONLY thing that sets Stage._paused, and _render hides editor
// chrome (gizmo arrows, the 60x60 grid across the backdrop, the other cameras' cyan
// cones) only while paused — SYNC7's _chrome() was dead code because nobody pulled
// this trigger, so every frame of every mp4 carried them. It also stops the rAF
// director loop competing for the GPU at render size. Idempotent (_paused is a plain
// boolean), so film.js calling this once per shot is fine; try/finally so a failed
// frame POST can never leave the editor frozen.
// pause/resume are REQUIRED, not optional-chained: the picture is wrong without them
// and a `?.` no-op would put the gizmo back in every mp4 with every test still green.
// They are not in PLAN §4.2's Stage list, so scripts/test_render_client.mjs reads the
// real web/stage.js and fails if either one stops existing.
export async function captureFrames(stage, timeline, { renderId, from = 0, to, onProgress } = {}) {
  const canvas = stage.renderer.domElement;
  const total = Math.max(0, to - from);
  const inflight = new Set();
  // A POST that fails while nobody happens to be awaiting it used to VANISH: the
  // .finally() pulls it out of `inflight`, so neither the race nor the final
  // Promise.all ever sees the rejection. Measured: with only frame 3 failing,
  // captureFrames RESOLVED with 29/30 frames stored (plus an unhandled rejection),
  // ffmpeg's %06d demuxer then stops dead at the gap and you get a short mp4 with
  // state=done. Catch every rejection into `failure` and re-throw it — the render
  // fails loudly, at the frame that broke.
  let failure = null;
  if (typeof stage.pause !== 'function' || typeof stage.resume !== 'function')
    throw new Error('render: Stage must implement pause()/resume() — without them the gizmo, ' +
                    'grid and camera cones bake into every frame');
  stage.pause();
  try {
    for (let f = from; f < to; f++) {
      timeline.step(f);
      if (stage.syncVideos) await stage.syncVideos(timeline.time);  // M6 video plates: seek + wait 'seeked'
      stage.renderActiveCamera(null);   // draw active cam (or director cam) to main canvas
      const blob = await new Promise(res => canvas.toBlob(res, 'image/png'));
      while (inflight.size >= 4) await Promise.race(inflight);      // backpressure: <=4 in flight
      const n = f - from;
      const p = fetch(`render/${renderId}/frame/${n}`, { method: 'POST', body: blob })
        .then(r => { if (!r.ok) throw new Error(`frame ${n}: ${r.status}`); })
        .catch(e => { failure = failure || e; })   // remembered, so it can't be lost...
        .finally(() => inflight.delete(p));
      inflight.add(p);
      if (failure) throw failure;                  // ...and fail fast, not 200 frames later
      onProgress?.(n + 1, total);
    }
    await Promise.all(inflight);
    if (failure) throw failure;
  } finally {
    stage.resume();                 // resume() swallows the paused clock gap: mixers don't jump
    restoreSelectionChrome(stage);  // _chrome(true) forced the detached gizmo visible
  }
  return total;
}

// extra: {intermediate:true} from film.js — a shot mp4 is re-encoded by the concat,
// so the server gives it a finer crf (one lossy generation that matters, not two).
export async function endRender(renderId, audio = [], extra = {}) {
  return postJSON(`render/${renderId}/end`, { audio, ...extra });   // scene audio[] muxed by ffmpeg
}

export async function pollRender(renderId, every = 500) {
  let st;
  do { await sleep(every); st = await getJSON(`render/${renderId}/status`); }
  while (st.state === 'queued' || st.state === 'encoding');
  if (st.state !== 'done') throw new Error('encode failed: ' + (st.log || st.state));
  return `render/${renderId}/out.mp4`;
}

// --- final: step frame-by-frame (deterministic), upload PNGs, ffmpeg encode ---
export async function finalRender(stage, timeline, opts = {}) {
  const { fps = 30, width = 1920, height = 1080, name = 'scene', audio = [], onProgress } = opts;
  // render big, deliver at width x height: begin/meta.json still describes the
  // DELIVERABLE, and the server downscales the frames (vf_args). A uniform
  // scale doesn't change aspect, and stage._render only refits backdrops when the
  // aspect changes — framing is untouched.
  const ss = ssFactor(width, height, opts.ss);
  return withRenderSize(stage, width * ss, height * ss, async () => {
    const total = Math.max(1, Math.round(timeline.duration * fps));
    const { renderId } = await beginRender({ name, fps, width, height });
    await captureFrames(stage, timeline, { renderId, from: 0, to: total, onProgress });
    await endRender(renderId, audio);
    return pollRender(renderId);
  });
}

// trigger a browser download of a blob or url (draft webm / final mp4)
export function download(blobOrUrl, filename) {
  const a = document.createElement('a');
  a.href = typeof blobOrUrl === 'string' ? blobOrUrl : URL.createObjectURL(blobOrUrl);
  a.download = filename;
  a.click();
  if (typeof blobOrUrl !== 'string') setTimeout(() => URL.revokeObjectURL(a.href), 1000);
}

export async function postJSON(url, body) {
  const r = await fetch(url, { method: 'POST', headers: { 'Content-Type': 'application/json' },
                               body: JSON.stringify(body) });
  if (!r.ok) throw new Error(`${url}: ${r.status} ${await r.text().catch(() => '')}`.trim());
  return r.json();
}

export async function getJSON(url) {
  const r = await fetch(url);
  if (!r.ok) throw new Error(`${url}: ${r.status}`);
  return r.json();
}