feat(studio-server): support png-sequence from the Studio render route (#5553) - #5578

Status: implementation, two rounds of review feedback addressed, CI gates green after the rebase, ready for re-review. This
carries out the design recorded in plans/issue-5553-png-sequence-route.md, with the five
decisions the maintainer called in plans/feedback/2026-10-14-issue-5553-png-sequence-route.md.
The branch is rebased onto current main at 273672ab1, which brings in the upstream render
route changes that landed in between (streaming downloads with HEAD support, nextFreeRenderJobId,
the shared finished-job sweep and the async cancel); none of them is reverted here. The seven
commits are the feature plus one commit per review ask.

What

Studio's render route now accepts format: "png-sequence" and hands the producer a directory
rather than a single file, the way the producer and the CLI have always treated that format. A
finished PNG-sequence render shows up as a directory row in the render panel: a PNG badge and a
frame count instead of a video thumbnail, "Download as ZIP" instead of "Download", and no
"open in a new tab" control, because there is no single playable file. Downloading streams the
directory as an archive, so nothing is written twice.

Why

Before this change every part of the route was single-file-shaped, while the producer's
directory writer was already the source of truth:

• Request validation accepted only mp4, webm and mov, and the output path was built as
  renders/<jobId>.mp4 with the extension swapped per format.
• DELETE's artifact whitelist was *.mp4 | *.webm | *.mov | *.meta.json, and both adapter hosts
  derived the meta sidecar by replacing that extension.
• The listing endpoint filtered readdirSync to those three extensions, so a directory render had
  no row at all.
• StudioApiAdapter.startRender's format union in packages/studio-server/src/types.ts was the
  same three-member shape, so an adapter could not be asked for the format in the first place.

Asking for format: "png-sequence" therefore produced an invisible render, a download endpoint
that 404s, and a DELETE that tried to unlink a path that never existed.

Related work

• Fixes Studio render route: support PNG-sequence output #5553
• Design record: plans/issue-5553-png-sequence-route.md
• Maintainer feedback this resolves: plans/feedback/2026-10-14-issue-5553-png-sequence-route.md,
  checked against main at 9b996059. The comment did not include a Studio PNG-sequence render run.
• Producer directory publish: packages/producer/src/services/renderOrchestrator.ts selects the
  directory transaction, and packages/producer/src/services/render/stages/encodeStage.ts writes
  frame_NNNNNN.png plus the optional audio.m4a.
• CLI directory output is the precedent for the listing and delivery shape:
  packages/cli/src/commands/render.ts.
• Path safety reuses the existing helpers: resolveWithinProject and isPrivateProjectFile in
  packages/studio-server/src/helpers/safePath.ts.

Decisions

1. Storage — renders/<jobId>/. The route and both adapter hosts branch on the artifact
   kind, not on format === "png-sequence", so directory handling stays format-agnostic and
   usable by a future directory-producing format.
2. Listing — file rows unchanged. Directory rows alone add kind: "directory", frameCount
   and audioSidecar, and keep size numeric as a summed directory footprint. Entries come from
   disk, dot-prefixed producer staging names are skipped, and symlinked directories are rejected.
   Directory facts are cached in the meta sidecar, with a directory scan as the fallback when the
   sidecar is missing or incomplete.
3. Download — STORE ZIP64 streamed on demand. No archive is written at render completion;
   Content-Length is computed from the known entries and PNG bytes are stored, not re-deflated.
   In-memory adm-zip is not used for render frames. /render/:jobId/view returns 404 for a
   directory and Studio hides the preview control; individual frames are served as image/png.
4. DELETE — 409 while the render is active. The producer stages directory output in a hidden
   sibling and only publishes at commit, so the final path does not exist during the render; a
   DELETE that reported success there would see the render reappear in history. Cancelled and
   failed renders still delete with 200, removing a validated real directory recursively.
5. Sidecar — additive, no version field. frameCount, size and audioSidecar are new
   optional keys, and the sidecar path is built from the renders directory and job id instead of
   replacing an extension on the output path.

Type decisions carried from the design record: RenderJobState gains an optional
kind?: "file" | "directory", set at render start; existing file listing rows keep their shape.

What landed

• Route (packages/studio-server/src/routes/render.ts): format validation and a FORMAT_KIND
  map, kind-aware artifact resolution (the bare job-id directory candidate is considered only for
  directory renders), lstat-guarded recursive removal, an empty and dot-only job-id guard on
  delete, directory download, listing rows for directories, and a disk-derived artifact kind for a
  job id the server has no record of (see "Review feedback addressed").
• Docs (docs/studio/export.mdx): the Format row lists PNG sequence, the Quality row notes it
  is hidden for the lossless format, and the render-queue section describes the frames folder, the
  PNG badge with frame count, "Download as ZIP" and what Delete removes.
• Helpers: renderArtifactFs.ts (artifact discovery, metadata path, removal),
  renderDirectoryStats.ts (frame count and summed footprint, exported as the
  render-directory-stats subpath), renderZipStream.ts (STORE ZIP64 on-demand stream), and
  contentDisposition.ts (the header pair the route and download share).
• Adapters: packages/cli/src/server/studioServer.ts and packages/studio/vite.adapter.ts
  accept the format, widen cancel cleanup to a directory plus its sidecar, and record the
  directory facts in the sidecar. Render telemetry accepts the fifth format (GIF landed in
  between and is preserved).
• Studio UI: renderSettings.ts widens the persisted format union, RenderQueue.tsx adds the
  PNG sequence option (fixed-quality, like MOV), and RenderQueueItem.tsx renders the directory
  row and the ZIP download.
• Tests: new suites for the ZIP stream, directory stats, artifact filesystem helpers and the
  directory route (packages/studio-server/src/helpers/*.test.ts,
  packages/studio-server/src/routes/renderDirectory.test.ts, which also carries the same-stem
  delete-scope and dot-id regressions), plus Studio rows (RenderQueueItem.test.tsx,
  useRenderQueueDirectory.test.tsx) and the CLI adapter test.

Review feedback addressed

• Rebase and CI (James, Miguel): the branch was behind main and fork workflows wait for a
  maintainer. It is now rebased onto main at 273672ab1. The upstream route changes that landed
  in between are kept as-is: the streaming renderFileResponse with HEAD support (fix(studio-server): download exports larger than 2 GiB #6602),
  nextFreeRenderJobId (fix(studio-server): two exports in the same second get separate jobs #7053, now also checked against the artifact map so an id with a recorded
  artifact is never reused), the shared forgetJobsFinishedLongerThan sweep (fix(studio-server): a render that ran over 5 minutes can still be read after it finishes #7087) and the async cancel (fix(studio-server): the cancel route replies once the adapter's stop has settled #7221).
  This push carries the suite run from that base.
• Deleting a file render could remove a same-named directory (Miguel):
  resolveRenderArtifacts is kind-aware — the bare <jobId> directory candidate is considered
  only for directory renders, and the suffixed file candidates only for file renders. The delete
  route reads the kind from the job record, and an unknown id defaults to "file", so an unknown
  render can never trigger recursive removal. Two same-stem regression tests cover a file render
  next to a directory render, in both directions.
• Reject . and .. job ids on delete, and never remove the renders folder itself (James):
  the DELETE handler refuses empty, . and .. ids — raw, router-normalized and percent-decoded
  forms — and resolveRenderArtifacts also refuses any candidate that names "", . or ...
  The regression test drives all three forms.
• DELETE after progress expires (jrusso1020): artifact kind and validated output path now live
  separately from the expiring job records, so DELETE still targets completed PNG-sequence output
  after the finished-job sweep drops the progress entry. Listing hydration restores the identity,
  and successful deletion clears it. Regression tests drive the real sweep (TTL_MS 300 s, swept
  every 60 s, so the job is gone by 420 s) and cover posted and listed file/directory renders,
  same-stem artifacts, and symlink protections after expiry.
• DELETE with no in-memory record at all (second-round review): a server restart, or a DELETE
  before any listing, left the route with no kind to look up and the "unknown id is a file" default
  stranded the directory on disk. renderKindOnDisk now derives the kind the same way the listing
  does: a file render of the same stem wins, a dot-prefixed id is always a file, and a real
  (non-symlink) renders/<jobId> directory counts as a directory render only when it carries a
  sidecar or at least one frame. Five tests cover the restart case, a frames-only folder, a folder
  that is not render-shaped, an unrecorded same-stem pair and an unrecorded symlink at the job id.
• Archive entry timestamps (second-round review): ZIP entries used to be stamped 1980-01-01.
  Local and central headers now carry each frame's mtime (dosDateTime, clamped to the DOS epoch
  for older files), the entry order is a plain code-point sort, and a stream that fails mid-body
  logs a warning instead of closing silently. Verified with unzip -t, unzip -l (real dates) and a
  byte-identical ditto extraction.
• Vite host coverage (second-round review): vite.adapter.render.test.ts gains a PNG-sequence
  suite (directory kind and sidecar facts, cancel cleanup of the folder and sidecar), and the
  optimizeDeps: { noDiscovery: true, include: [] } setting there is now explained in a comment:
  without it Vite's background dependency scan races the server close() and logs errors.
• Docs (second-round review): docs/studio/export.mdx previously described only the delete
  fix. It now documents the PNG sequence export itself (see "What landed").

CI fixes after the rebase

The rebase onto 273672ab1 brought in four gates that did not exist when this PR was written.
Each is satisfied without weakening the gate:

• check:package-subpaths (Preflight, Lint): packages/studio-server/package-subpaths.json
  is now the source of the export map (fix(producer): local renders bring in only media, font, CSS and JS from outside the project #7647). The ./render-directory-stats export, which
  packages/cli/src/commands/render.ts imports, is registered there with
  environments: ["bun", "node"]; the regenerated package.json is unchanged. This also clears the
  Windows and preview jobs that wait on Preflight, and the packed-consumer Vite build, which treated
  the unregistered subpath as browser-safe and tried to bundle node:fs.

• Package size budget (Build): @hyperframes/studio-server goes from 168,500 / 654,000 to
  182,300 / 708,700 bytes (packed / unpacked). The ZIP64 stream, the artifact helpers,
  renderDirectoryStats, contentDisposition and their declarations add about 2% to the tarball,
  and the previous budget had under 1% of headroom. The new figures are the measured size at this
  head (173,603 / 670,116 with pnpm pack) times the verifier's own 1.05 headroom; @hyperframes/cli
  and @hyperframes/studio stay inside their existing budgets.

• Comment ratchet (Comments): the comments this PR added are condensed so each changed file stays
  at or under its comment share on main and the new helpers open under the package's share. The
  containment and symlink invariants are still stated, one line each. No behavior change.

• render-selects e2e (Studio: timeline viewport gate): the test picks each select's last option
  and then expects Quality to still be on screen, which PNG sequence hides. PNG sequence now sits
  beside MOV (ProRes), the other fixed-quality format, and GIF stays last as on main. The unit tests
  that arrow through the list follow the new order.

• Open the archive in the system tools (Miguel): the ZIP was opened and expanded with macOS
  Archive Utility and extracted with CLI tools, byte-identical to the source frames in both.
  Windows Explorer steps are in Testing below for a reviewer on Windows.

• Scope (Miguel, James): the planning notes and the unrelated engine test changes are out of
  the diff, and the commits are signed.

Testing

• Manual end-to-end run against a real Studio server (hyperframes preview), rendering a
  two-frame PNG sequence: the listing reported kind: "directory" with frameCount: 2 and a
  summed size; renders/<jobId>/ held frame_000001.png and frame_000002.png;
  /render/:jobId/view returned 404; /render/:jobId/download streamed application/zip with a
  computed Content-Length that unzip -t accepted as a valid archive; and DELETE while the
  render was still active returned 409.
• Archive verification: a 5-frame sequence with audio, downloaded through the real route,
  has the expected entries (frame_000001.png … frame_000005.png plus audio.m4a), passes
  unzip -t, and expands byte-identically to the source both via unzip and via macOS Archive
  Utility.
• bun run --cwd packages/studio-server test — 109 files, 1,919 passed, 4 skipped, 1 failed.
  The one failure is src/helpers/undecodableAudioTrack.test.ts, which this diff does not touch:
  it fails identically on main at 273672ab1 on this machine, which runs FFmpeg 9.0.2 (the test
  shells out to ffmpeg, so the result depends on the local build).
• bun run --cwd packages/cli test src/server/studioServer.test.ts — 57 passed.
• bun run --cwd packages/studio test src/components/renders vite.adapter.render.test.ts —
  10 files, 60 passed, including the new PNG-sequence suite for the Vite host.
• packages/core, packages/engine and packages/producer are untouched by this diff (their
  trees are identical to main).
• tsc --noEmit in studio-server, cli and studio, oxlint and oxfmt --check on every changed
  file, and bunx fallow audit --base origin/main --fail-on-issues are clean.

Testing on Windows

The archive is a STORE ZIP64 stream (frame_000001.png … plus audio.m4a when the composition
has audio), so verify it with the tools Windows ships:

1. Start Studio (npx hyperframes preview) and render a composition with format
   PNG sequence — once with audio in the composition, once without.

2. In the render history row, use Download as ZIP; the file saves as <jobId>.zip.

3. Double-click the archive: Windows Explorer should open it and list the frames flat (no nested
   folder), with audio.m4a present only for the audio render.

4. Use Extract All, then confirm the extraction (the archive is STORE, so bytes are identical
   to the source frames):

   Expand-Archive .\<jobId>.zip -DestinationPath .\out
   (Get-ChildItem .\out).Count            # frame count, +1 with audio.m4a
   Get-FileHash .\out\frame_000001.png    # matches the source frame

5. Optionally list without extracting: tar -tf .\<jobId>.zip (Windows 10+ ships bsdtar, which
   reads the ZIP64 central directory the same way unzip -t does on macOS).

Before

The render panel on main: the format selector offers MP4, MOV (ProRes) and WebM only, and every
queue row resolves to a single file. (Captured before the GIF format landed upstream; the selector
on current main also offers GIF.)

After

The same panel with PNG sequence available and selected. The quality selector disappears, since
PNG is lossless and fixed-quality like MOV. (The GIF option also appears on current main; it is
unrelated to this diff. The capture predates the CI fix that moved PNG sequence next to MOV (ProRes);
the shipped order is MP4, MOV (ProRes), PNG sequence, WebM, GIF.)

And a finished PNG-sequence render in the queue: a PNG badge and a frame count instead of a video
thumbnail, with the download control reading "Download as ZIP".

Notes for review

• The ZIP64 path is covered by arithmetic tests for sizes and offsets past 4 GiB; no real >4 GiB
  archive is generated in the suite.
• Deleting a render that is still in flight returns 409 and logs nothing; the UI needs a retry for
  that case, which is a follow-up rather than part of this change.
• The cancel cleanup is shared by both adapter hosts and both now have adapter-level cancel tests
  (studioServer.test.ts and vite.adapter.render.test.ts).
• renderArtifacts (job id → kind and output path) is never evicted on purpose: it holds one small
  entry per render started in this process, and it is what lets DELETE and the listing agree after
  the progress record is swept. The comment in render.ts records this.
• The browser round trip has no automated suite. It was verified by hand against a real Studio
  server (see Testing), the archive was additionally opened in macOS Archive Utility and
  extracted byte-identically, and the Windows steps above cover the Explorer side.