The open source AI video agent: turns any coding agent into a video agent, with an editor to change anything it makes.
0.2.1: the timeline's main track, smoother preview and export, projects folder, diagnostics, chat attachments and fixes (#93)
riverisbuildinga7faee013da4
diff --git a/.changeset/agent-leftovers.md b/.changeset/agent-leftovers.mdnew file mode 100644index 0000000..5698341--- /dev/null+++ b/.changeset/agent-leftovers.md@@ -0,0 +1,5 @@+---+"@openfilm/desktop": patch+---++A turn whose agent waits five minutes on its model with nothing coming (CodeBuddy, its connection hung) is stopped and says why. Why a turn failed still shows after OpenFilm restarts: the last one's above the composer, an older one's on its Interrupted. Agents are asked whether they are signed in less often, in a folder of OpenFilm's own instead of your home folder, and none is left running after OpenFilm quits.diff --git a/.changeset/agent-menu-always-model-effort.md b/.changeset/agent-menu-always-model-effort.mdnew file mode 100644index 0000000..dbc988d--- /dev/null+++ b/.changeset/agent-menu-always-model-effort.md@@ -0,0 +1,5 @@+---+"@openfilm/desktop": patch+---++The agent menu always shows Model and Effort. When an agent offers no choice of one (GitHub Copilot picks its own effort), the row shows the one value it uses, or "Default".diff --git a/.changeset/agent-model-once.md b/.changeset/agent-model-once.mdnew file mode 100644index 0000000..51d32df--- /dev/null+++ b/.changeset/agent-model-once.md@@ -0,0 +1,6 @@+---+"@openfilm/desktop": patch+"openfilm": patch+---++An agent's menu shows each choice once. GitHub Copilot lists its model "Auto" twice, and both showed, ticked.diff --git a/.changeset/agent-plan-and-empty-turns.md b/.changeset/agent-plan-and-empty-turns.mdnew file mode 100644index 0000000..9225537--- /dev/null+++ b/.changeset/agent-plan-and-empty-turns.md@@ -0,0 +1,5 @@+---+"@openfilm/desktop": patch+---++An agent refused for your plan, not your sign-in (Kimi: "403 Your current subscription does not have access to Kimi Code"), now shows its own words and stays signed in, instead of asking you to sign in again and again. A turn an agent ends without saying or doing anything (older Kimi, on a plan that does not cover it) is said so instead of left empty.diff --git a/.changeset/agent-sign-in-wait.md b/.changeset/agent-sign-in-wait.mdnew file mode 100644index 0000000..47fc7eb--- /dev/null+++ b/.changeset/agent-sign-in-wait.md@@ -0,0 +1,5 @@+---+"@openfilm/desktop": patch+---++Signing in to an agent in Terminal is waited for 15 minutes instead of 5, asking only that agent meanwhile, so a sign-in that takes a while on the maker's site is still noticed. Cursor is found when its installer named it `agent` only.diff --git a/.changeset/chat-attach-in-place.md b/.changeset/chat-attach-in-place.mdnew file mode 100644index 0000000..f831554--- /dev/null+++ b/.changeset/chat-attach-in-place.md@@ -0,0 +1,6 @@+---+"@openfilm/desktop": patch+"openfilm": patch+---++The chat takes any number of files in one message, and folders too. A file or folder dragged in from your disk stays where it is: the message gives the agent its path, and the agent copies into the project only what the film uses, so Studio's media no longer fills up with everything you dropped. A file pasted from the clipboard, which has no path of its own, is kept in the project's `.film/attachments/`. Up to 20 pictures go to the agent with a message, the pictures of what you pointed at in Studio first; the rest go by their path.diff --git a/.changeset/chat-bottom-room.md b/.changeset/chat-bottom-room.mdnew file mode 100644index 0000000..ee8dd79--- /dev/null+++ b/.changeset/chat-bottom-room.md@@ -0,0 +1,5 @@+---+"@openfilm/desktop": patch+---++The chat leaves more room under its last message, and the way back to the latest is a round down arrow above the composer.diff --git a/.changeset/codebuddy-china.md b/.changeset/codebuddy-china.mdnew file mode 100644index 0000000..5cb8964--- /dev/null+++ b/.changeset/codebuddy-china.md@@ -0,0 +1,5 @@+---+"@openfilm/desktop": patch+---++CodeBuddy works as its China edition: it is started that way unless your shell sets CODEBUDDY_INTERNET_ENVIRONMENT yourself, and its install link is the China site's. A turn an agent gives up on now shows the agent's own reason (CodeBuddy's network error, say) instead of an empty reply. Signing in in Terminal runs in a folder of OpenFilm's own, so CodeBuddy no longer warns about trusting your home folder. Two models an agent names alike (CodeBuddy's "Hy3") are told apart in the menu.diff --git a/.changeset/copies-paste-never-cut.md b/.changeset/copies-paste-never-cut.mdnew file mode 100644index 0000000..418244d--- /dev/null+++ b/.changeset/copies-paste-never-cut.md@@ -0,0 +1,5 @@+---+'openfilm': patch+---++Studio: ⌥-drag copies, paste, ⌥←/→ and a start time typed in the inspector no longer cut clips. A copy or paste lands on a new track when its spot is taken; a nudge stops against the next clip. A new track opens above a picture track and below a sound track, so the track you pointed at keeps its number.diff --git a/.changeset/cursor-signed-out.md b/.changeset/cursor-signed-out.mdnew file mode 100644index 0000000..f75ff54--- /dev/null+++ b/.changeset/cursor-signed-out.md@@ -0,0 +1,5 @@+---+"@openfilm/desktop": patch+---++A Cursor that is signed out now says so at once ("Cursor is not signed in. Sign in under Settings → Agents.") instead of waiting minutes on a sign-in page it opened in the browser by itself.diff --git a/.changeset/decode-on-every-system.md b/.changeset/decode-on-every-system.mdnew file mode 100644index 0000000..bbc4c2c--- /dev/null+++ b/.changeset/decode-on-every-system.md@@ -0,0 +1,10 @@+---+"@openfilm/desktop": patch+"openfilm": patch+---++Footage is decoded on the graphics chip on every system: VideoToolbox on a Mac, Direct3D 11 (then NVIDIA's decoder) on Windows, and VA-API (then NVIDIA's) on Linux. This covers the fast-seeking copies, the preview's proxies and the files an editing project converts. Each decoder is tried once on a moment of H.264 and used only when its frames match the processor's pixel for pixel. If it fails partway, the work is done again without it.++Footage the render's browser can't decode no longer stalls an export: ProRes, which no browser plays, and HEVC on a computer without a chip for it. Before rendering, such footage is converted to a copy the browser plays, keeping its transparency when it has one. A film with ProRes footage used to take about thirty seconds a frame and showed none of it.++`openfilm doctor` says which encoders and decoders ffmpeg uses on the chip, and which video codecs the browser decodes there.diff --git a/.changeset/diagnostic-report.md b/.changeset/diagnostic-report.mdnew file mode 100644index 0000000..f6e96a0--- /dev/null+++ b/.changeset/diagnostic-report.md@@ -0,0 +1,6 @@+---+"openfilm": patch+"@openfilm/desktop": patch+---++A diagnostic report to paste into an issue. `openfilm doctor` checks what OpenFilm needs on this computer: Node, ffmpeg, the browser films are drawn in and whether it uses the graphics chip, Studio, the data and projects folders, and npm. It also shows which agent ran the command and the last errors in Studio's log. Settings → General → Copy report copies the same report, plus what the browser Studio is open in can do. In the desktop app, it adds each agent's program, version and state. Paths in your home folder show as ~; the report has no keys, accounts or projects.diff --git a/.changeset/diagnostics-in-developer.md b/.changeset/diagnostics-in-developer.mdnew file mode 100644index 0000000..49e5f3c--- /dev/null+++ b/.changeset/diagnostics-in-developer.md@@ -0,0 +1,6 @@+---+'openfilm': patch+'@openfilm/desktop': patch+---++Diagnostics move to Settings → Developer, which Studio now shows outside the desktop app too. Studio and the desktop app keep what went wrong (an agent that did not start or answer, or whose process ended by itself; an export that failed; an error Studio did not expect) in `logs/problems.jsonl` in Studio's home: the last two weeks, at most 500, with home paths, keys, tokens and email addresses taken out. The copied report (and `openfilm doctor`) ends with the last week's problems. Export writes a diagnostic file to the exports folder: the report, the problems, the end of each log, how the failed turns went (what was said only if you ask for it), and Codex's own warnings and errors around its problems. Settings → Developer lists the recent problems. In the desktop app, a message that failed has "Copy diagnostic report" beside its error, and so does an agent with a problem in Settings → Agents.diff --git a/.changeset/drop-places-only.md b/.changeset/drop-places-only.mdnew file mode 100644index 0000000..cd15cbc--- /dev/null+++ b/.changeset/drop-places-only.md@@ -0,0 +1,5 @@+---+'openfilm': patch+---++Studio: a file dragged from the media pane onto the timeline is put down where you let go, or on a new track when that spot is taken. It never cuts, pushes or covers a clip there; hold ⌥ to overwrite.diff --git a/.changeset/export-leaves-room.md b/.changeset/export-leaves-room.mdnew file mode 100644index 0000000..0484d39--- /dev/null+++ b/.changeset/export-leaves-room.md@@ -0,0 +1,12 @@+---+"@openfilm/desktop": patch+"openfilm": patch+---++Exports leave the computer usable, and do less work twice:++- **Fewer browsers.** A render opens one browser per performance core minus one, as many as the memory free right now can hold with 2 GB to spare, and at most four. Before, a Mac with 16 GB opened five and could run out of memory. A short render opens one.+- **Lower priority.** Exports and `openfilm render` run below the apps you're using, along with every browser and encoder they start. This now holds in the desktop app too.+- **Your film's frame rate.** A platform preset exports at the film's own rate, up to the most the platform shows. A 30 fps film is no longer drawn at 60 for 哔哩哔哩 or YouTube.+- **One render for same-size presets.** Platforms that take the same picture, such as 抖音, 快手 and 视频号, are drawn once and their files cloned.+- **Faster PNG frames.** Alpha videos and editing-project exports take their PNG frames with fast compression. The pixels are the same, and the frames come two to four times sooner.diff --git a/.changeset/export-on-the-chip.md b/.changeset/export-on-the-chip.mdnew file mode 100644index 0000000..d4f5c32--- /dev/null+++ b/.changeset/export-on-the-chip.md@@ -0,0 +1,6 @@+---+"@openfilm/desktop": patch+"openfilm": patch+---++Exports leave more of the work to the Mac's media engines, so the computer stays usable while they run. ProRes exports, and the pages an editing project carries, go through the ProRes engine, about three times as fast with a quarter of the processor. `openfilm render` writes H.264 on the graphics chip, as Studio's exports already do. The copies a render makes of slow-seeking footage, and the preview's proxies of heavy footage, are decoded and encoded on the chip too. H.264 and HEVC from the chip get a key frame every two seconds instead of every twelve frames, which looks better at the same size. Where the chip can't do something, the processor does it as before.diff --git a/.changeset/file-names-any-character.md b/.changeset/file-names-any-character.mdnew file mode 100644index 0000000..7f7f47a--- /dev/null+++ b/.changeset/file-names-any-character.md@@ -0,0 +1,5 @@+---+"openfilm": patch+---++A file whose name has `#`, `?` or `%` in it now plays in a film. Before, `#` made film.html fail to read, and `?` or `%` stopped the preview with an error, or left the file out. film.html writes those three characters escaped (`%23`, `%3F`, `%25`); every other character, Chinese punctuation and spaces included, is written as it is. A src written with escapes, like `my%20file.png`, now names `my file.png` in Studio too. A film's versions also keep such files, and files with quotes in their names.diff --git a/.changeset/final-cut-pro-export.md b/.changeset/final-cut-pro-export.mdindex 06186ad..dbf238e 100644--- a/.changeset/final-cut-pro-export.md+++ b/.changeset/final-cut-pro-export.md@@ -1,6 +1,6 @@----"openfilm": minor-"@openfilm/desktop": minor+"openfilm": patch+"@openfilm/desktop": patch---Export editing projects for Final Cut Pro as FCPXML with their media, the main picture track on the primary storyline, connected overlays and separate audio clips or mixed stems. Separate audio clips retain Studio's row grouping with an audio role per row. HTML pages render as ProRes clips with alpha; subtitles are included as editable title clips above the picture tracks with a separate SRT copy.diff --git a/.changeset/folder-chip-reveal.md b/.changeset/folder-chip-reveal.mdnew file mode 100644index 0000000..a5ef558--- /dev/null+++ b/.changeset/folder-chip-reveal.md@@ -0,0 +1,5 @@+---+"@openfilm/desktop": patch+---++Files, pictures and folders attached in the chat look the same in the box you're writing in and in the message once sent: a 40px square for a picture or video, a card as tall for anything else. A folder's card says where it is, and clicking it shows it in its folder.diff --git a/.changeset/kimi-install-link.md b/.changeset/kimi-install-link.mdnew file mode 100644index 0000000..96e1e85--- /dev/null+++ b/.changeset/kimi-install-link.md@@ -0,0 +1,5 @@+---+"@openfilm/desktop": patch+---++Settings → Agents: Kimi's Install button opens the install guide of Kimi Code CLI.diff --git a/.changeset/main-track-magnet-linkage.md b/.changeset/main-track-magnet-linkage.mdnew file mode 100644index 0000000..90012e5--- /dev/null+++ b/.changeset/main-track-magnet-linkage.md@@ -0,0 +1,5 @@+---+'openfilm': patch+---++Studio's timeline: the magnet keeps the main track (the lowest picture track) closed up. A clip put on it goes in between, a deleted one closes the gap, and a trim or a new speed moves what follows. Linkage keeps the titles, overlays and sounds over a main-track clip on their moment of it, and deletes them with it; a clip that starts past the end of the main track rides on nothing. Dragging the cut between two clips trims the clip you grab. The new preview axis shows the frame under the pointer as it moves over the timeline; its switch sits in the toolbar beside the magnet, snapping and linkage. Keys: P (or ⇧N) magnet, ~ linkage, S preview axis.diff --git a/.changeset/main-track-no-badge.md b/.changeset/main-track-no-badge.mdnew file mode 100644index 0000000..49e6938--- /dev/null+++ b/.changeset/main-track-no-badge.md@@ -0,0 +1,5 @@+---+"openfilm": patch+---++The main track's head no longer carries a magnet badge, which read as a switch: the main track is told by its band and its tooltip, and the magnet itself is the switch in the timeline's toolbar.diff --git a/.changeset/media-pane-page-playback.md b/.changeset/media-pane-page-playback.mdnew file mode 100644index 0000000..74168cf--- /dev/null+++ b/.changeset/media-pane-page-playback.md@@ -0,0 +1,6 @@+---+"openfilm": patch+"@openfilm/desktop": patch+---++A web page picked in the media pane now plays as smoothly as the film in the viewer. The page draws its own frames, one per frame of the project's frame rate, instead of waiting on a message from the editor for each one, so a busy editor no longer makes it stutter. Pausing stops on the frame on screen, and the timecode and the position bar match it.diff --git a/.changeset/move-never-cuts.md b/.changeset/move-never-cuts.mdnew file mode 100644index 0000000..7b99e62--- /dev/null+++ b/.changeset/move-never-cuts.md@@ -0,0 +1,5 @@+---+'openfilm': patch+---++Studio: a clip dragged onto another clip no longer cuts it. It lands where you let go, or on a new track right above when that spot is taken. Hold ⌥ while dragging to insert.diff --git a/.changeset/pages-at-viewer-size.md b/.changeset/pages-at-viewer-size.mdnew file mode 100644index 0000000..225bdd1--- /dev/null+++ b/.changeset/pages-at-viewer-size.md@@ -0,0 +1,6 @@+---+"openfilm": patch+"@openfilm/desktop": patch+---++Studio's preview draws web pages at the size the viewer shows them. A page that sizes its canvas or 3D by the device pixel ratio, as the protocol asks, now draws only the pixels you see instead of the film's full size scaled down, so heavy pages play more smoothly and look the same. Going fullscreen loads the film again behind the picture at the new size. Turn it off under Settings → Playback → Draw pages at the viewer's size. Exports always draw at full size.diff --git a/.changeset/preview-renders.md b/.changeset/preview-renders.mdnew file mode 100644index 0000000..3baffc8--- /dev/null+++ b/.changeset/preview-renders.md@@ -0,0 +1,6 @@+---+"openfilm": patch+"@openfilm/desktop": patch+---++Studio renders what plays late. While the film plays, Studio notes where the viewer can't keep up, such as a page heavy with 3D or many videos at once. Once you stop, it renders those stretches in the background at low priority, and from then on they play smoothly from the render. Paused, scrubbed or edited, the viewer still shows the live film, and any change to the film or its files renders them again. A line under the timeline's ruler marks each stretch: red plays late, yellow is rendering, green is rendered. Turn it off under Settings → Playback → Render what plays late. Exports always draw the film itself.diff --git a/.changeset/project-cover.md b/.changeset/project-cover.mdnew file mode 100644index 0000000..e384e9a--- /dev/null+++ b/.changeset/project-cover.md@@ -0,0 +1,6 @@+---+"openfilm": patch+"@openfilm/desktop": patch+---++A project can have a cover of its own in the projects list: pick a picture from a project's "…" menu, use the frame under the playhead from the editor's "…" menu, or set one of the project's pictures from the asset pane. "Use the automatic cover" goes back to the film's own picture.diff --git a/.changeset/projects-folder.md b/.changeset/projects-folder.mdnew file mode 100644index 0000000..d1139a5--- /dev/null+++ b/.changeset/projects-folder.md@@ -0,0 +1,6 @@+---+"openfilm": patch+"@openfilm/desktop": patch+---++Projects now shows every project in your projects folder, one folder each, including the ones an agent made there or you copied in; one you delete from the folder leaves the list. Projects you opened from elsewhere stay in the list too, and a project's … menu has Reveal in Finder (Explorer on Windows) to show where its folder is. Settings → General → Storage calls it the projects folder. When you change it, or set it back to the default, Studio asks whether your projects move with it: moved, each folder goes whole (across disks it is copied, then the old one goes to the Trash); left behind, they stay where they are and in the list.diff --git a/.changeset/quiet-buttons-share.md b/.changeset/quiet-buttons-share.mddeleted file mode 100644index dc21934..0000000--- a/.changeset/quiet-buttons-share.md+++ /dev/null@@ -1,5 +0,0 @@-----'@openfilm/desktop': patch------Desktop: a folder dragged into the chat now goes into the project — every file in it, hidden ones left out — instead of "That is not a file."diff --git a/.changeset/rename-any-tab.md b/.changeset/rename-any-tab.mdnew file mode 100644index 0000000..a64238b--- /dev/null+++ b/.changeset/rename-any-tab.md@@ -0,0 +1,6 @@+---+"@openfilm/desktop": patch+"openfilm": patch+---++Any tab can rename its project, not just the one in front: right-click it and choose Rename, or double-click it. A tab's name being edited now shows its selected words plainly.diff --git a/.changeset/smooth-preview-playback.md b/.changeset/smooth-preview-playback.mdnew file mode 100644index 0000000..c7a8a38--- /dev/null+++ b/.changeset/smooth-preview-playback.md@@ -0,0 +1,6 @@+---+"openfilm": patch+"@openfilm/desktop": patch+---++Studio's preview plays smoothly and in sync. The film now draws its own frames while it plays, once per frame of the film's frame rate and timed to when each frame reaches the screen, from a clock that follows the sound as you hear it, output latency included. It no longer waits on a message from the editor for every frame, so a busy editor or a slower computer no longer stutters the picture. Videos play by themselves and are eased back into step instead of being paused and sought again and again. Footage inside a web page that seeks its video frame by frame now plays at its full frame rate while the film plays, and still lands on the exact frame when you stop. The editor does far less work while playing: the playhead moves on its own, and the timecode and subtitles update only when they change. Changing speed, soloing a track or editing during playback no longer stalls the picture. Exports are unchanged.diff --git a/.changeset/smooth-scrub.md b/.changeset/smooth-scrub.mdnew file mode 100644index 0000000..dc0ea6a--- /dev/null+++ b/.changeset/smooth-scrub.md@@ -0,0 +1,6 @@+---+"openfilm": patch+"@openfilm/desktop": patch+---++Dragging the playhead along the timeline is smoother. The picture follows every frame instead of 25 times a second, and so does the timecode under it. The playhead line moves without making the editor lay its whole page out again, and the rest of the editor updates a few times a second until you let go. Zooming the timeline no longer redraws every waveform at each step: each one is redrawn once the zoom stops, a few per frame, so a film with hundreds of sounds doesn't freeze when you zoom.diff --git a/.changeset/stills-play-any-footage.md b/.changeset/stills-play-any-footage.mdnew file mode 100644index 0000000..198c30d--- /dev/null+++ b/.changeset/stills-play-any-footage.md@@ -0,0 +1,6 @@+---+"@openfilm/desktop": patch+"openfilm": patch+---++Footage the browser can't decode now shows everywhere a film is drawn, not only in exports: `openfilm look`, posters, stills and slides, Studio's film cards, and page thumbnails. This covers ProRes, and HEVC on a computer without a chip for it. Each place draws it through the same copy an export makes. Studio's preview also plays that copy when no proxy is ready. A video exported with its subtitles burned in gets these copies too; before, its ProRes footage came out black.diff --git a/.changeset/tab-menu-agent-settings.md b/.changeset/tab-menu-agent-settings.mdnew file mode 100644index 0000000..e1250c0--- /dev/null+++ b/.changeset/tab-menu-agent-settings.md@@ -0,0 +1,6 @@+---+"@openfilm/desktop": patch+"openfilm": patch+---++Right-click a tab for its menu: rename it, show its project's folder, close it, close the other tabs or the tabs to its right. Renaming a tab now shows the selected words clearly. The chat's agent menu has a settings button at its top right that opens Settings → Agents.diff --git a/.changeset/timeline-big-film-smooth.md b/.changeset/timeline-big-film-smooth.mdnew file mode 100644index 0000000..9a87017--- /dev/null+++ b/.changeset/timeline-big-film-smooth.md@@ -0,0 +1,6 @@+---+"openfilm": patch+"@openfilm/desktop": patch+---++Zooming and scrolling the timeline of a big film stay smooth. Only the tracks near the view have their clips drawn, so a film with hundreds of sounds on dozens of tracks lays out a fraction of them. A pinch or Ctrl+wheel zoom scales what is drawn while you zoom and lays the timeline out once you stop, keeping the moment under the pointer where it is. Scrolling up and down moves the track heads with the tracks without redrawing the timeline.diff --git a/.changeset/timeline-scroll-restyle.md b/.changeset/timeline-scroll-restyle.mdnew file mode 100644index 0000000..f1d097d--- /dev/null+++ b/.changeset/timeline-scroll-restyle.md@@ -0,0 +1,5 @@+---+'openfilm': patch+---++Studio: scrolling a long timeline sideways is smoother. Keeping clip names in view no longer restyles every clip on each step.diff --git a/.changeset/windows-registry-path.md b/.changeset/windows-registry-path.mdnew file mode 100644index 0000000..40c9d24--- /dev/null+++ b/.changeset/windows-registry-path.md@@ -0,0 +1,5 @@+---+'@openfilm/desktop': patch+---++Desktop: on Windows, the app reads the PATH from the registry again, so an agent or tool installed while it runs is found without restarting it.diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.ymlindex 20ffca2..702c2ea 100644--- a/.github/ISSUE_TEMPLATE/bug_report.yml+++ b/.github/ISSUE_TEMPLATE/bug_report.yml@@ -30,6 +30,18 @@ body:- Other (say which below)validations:required: true+ - type: textarea+ id: report+ attributes:+ label: Diagnostic report+ description: |+ In Studio: Settings → Developer → Copy report (or, in the desktop app, Copy diagnostic report under the message+ that failed), then paste it here. Without Studio, paste what `npx openfilm doctor` prints. Paths in your home+ folder show as ~, and it has no keys or accounts. If neither runs, say so. For more, attach the diagnostic file+ from Settings → Developer → Export, after a look at it.+ render: text+ validations:+ required: true- type: textareaid: stepsattributes:diff --git a/.github/workflows/agents.yml b/.github/workflows/agents.ymlnew file mode 100644index 0000000..81ecc3b--- /dev/null+++ b/.github/workflows/agents.yml@@ -0,0 +1,61 @@+name: agents+# Every night, the newest release of each agent the desktop chat drives, installed the way most people install it (npm,+# global), on macOS and Windows: found where the app looks, started, and spoken to over ACP through the app's own code+# (apps/desktop/scripts/agent-check.mjs). An agent's update that breaks the chat shows here before people meet it.+# Nobody is signed in: an agent that asks for its sign-in was found, started and answered, which is what is checked.+# Cursor and Kimi are not on npm and are left out. A failed night opens an issue, or adds to the one still open.+on:+ schedule:+ - cron: '17 3 * * *'+ workflow_dispatch:+permissions:+ contents: read+concurrency:+ group: agents+ cancel-in-progress: true+jobs:+ check:+ if: github.repository == 'openfilm/openfilm'+ strategy:+ fail-fast: false+ matrix:+ os: [macos-latest, windows-latest]+ runs-on: ${{ matrix.os }}+ timeout-minutes: 30+ env:+ # the check never starts Electron: no need for its 100 MB download+ ELECTRON_SKIP_BINARY_DOWNLOAD: '1'+ steps:+ - uses: actions/checkout@v4+ - uses: pnpm/action-setup@v4+ - uses: actions/setup-node@v4+ with:+ node-version: 22+ cache: pnpm+ - run: pnpm install --frozen-lockfile+ - name: The newest agents from npm+ run: npm install -g @openai/codex@latest @anthropic-ai/claude-code@latest @github/copilot@latest opencode-ai@latest @qwen-code/qwen-code@latest @tencent-ai/codebuddy-code@latest+ - name: Found, started and spoken to+ working-directory: apps/desktop+ run: node scripts/agent-check.mjs codex claude copilot opencode qwen codebuddy++ report:+ needs: check+ if: failure() && github.event_name == 'schedule'+ runs-on: ubuntu-latest+ permissions:+ issues: write+ steps:+ - name: Open an issue, or add to the open one+ env:+ GH_TOKEN: ${{ github.token }}+ TITLE: Nightly agent check failed+ RUN: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}+ run: |+ body="An agent the desktop chat drives did not start or answer on its newest release: $RUN (each job's summary says which, and what it said)."+ number=$(gh issue list --repo "$GITHUB_REPOSITORY" --state open --search "in:title \"$TITLE\"" --json number --jq '.[0].number // empty')+ if [ -n "$number" ]; then+ gh issue comment "$number" --repo "$GITHUB_REPOSITORY" --body "$body"+ else+ gh issue create --repo "$GITHUB_REPOSITORY" --title "$TITLE" --label bug --body "$body"+ fidiff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 667b43f..ece4982 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -57,8 +57,8 @@ docs/ pictures for the README## packages/openfilm: the format, the CLI and Studio-`pnpm dev` runs Studio on port 4848, with its state, projects and exports in `packages/openfilm/.dev/`-(git-ignored), apart from an OpenFilm you have installed. It opens a sample film in your browser, rebuilds the editor+`pnpm dev` runs Studio on port 4848, with its state and exports in `packages/openfilm/.dev/` (git-ignored), beside an+OpenFilm you have installed; its projects are in the library every OpenFilm shares. It opens a sample film in your browser, rebuilds the editorwhen `studio/ui` changes (reload the page), and restarts Studio when `studio/server` or `src` change. Ctrl+C stops it.`pnpm --filter openfilm test` runs its tests and `pnpm --filter openfilm typecheck` checks the server's and the@@ -72,11 +72,13 @@ node --test --test-name-pattern="split" studio/server/film.test.mjs### Trying a change with a coding agentWhile `pnpm dev` runs, `packages/openfilm/.dev/bin/openfilm` (`openfilm.cmd` on Windows) is your checkout's command-on that Studio. Open Codex, Claude Code or any coding agent in `packages/openfilm/.dev/projects` (that Studio's library)-and ask for a film: the AGENTS.md and CLAUDE.md `pnpm dev` writes there tell it to run that command instead of the-skill's `npx -y openfilm@latest` (the release), and the manual names the same command, so it keeps using it. Elsewhere,-tell your agent to run the command. Your films appear in the Studio `pnpm dev` opened, and an installed OpenFilm, its-Studio on port 4747 and `~/.openfilm` are left alone.+on that Studio. Ask Codex, Claude Code or any coding agent for a film and tell it to run that command instead of the+skill's `npx -y openfilm@latest` (the release); the manual names the same command, so it keeps using it. Your films+appear in the Studio `pnpm dev` opened. Its state is in `packages/openfilm/.dev/` and its port is its own, so an+installed OpenFilm, its Studio on port 4747 and `~/.openfilm` are left alone; projects are the one thing they share:+every OpenFilm uses the same library, the one Studio's Settings chose (kept in `~/.openfilm/prefs.json`, which+`OPENFILM_SHARED_HOME` points it at), by default `~/Movies/OpenFilm/Projects` on macOS. A test that must stay apart+sets `OPENFILM_LIBRARY` and leaves `OPENFILM_SHARED_HOME` unset.To make your checkout the `openfilm` your agents use everywhere, `npm link` in `packages/openfilm` (`npm unlink -gopenfilm` undoes it). That one shares `~/.openfilm` and port 4747 with an installed OpenFilm; of two Studios, the@@ -99,8 +101,9 @@ pnpm --filter @openfilm/desktop typecheck```Run from source, the app is its own "OpenFilm Dev": its own name, data folder, Studio home and port, so it never-shares anything with an installed OpenFilm. Its renamed copy of Electron lives in `apps/desktop/.dev/` (git-ignored),-signed only for this machine: you need no certificate to run or change it. Its window's page imports Studio's editor+shares a window or a Studio with an installed OpenFilm. Its projects are in the same library as every OpenFilm's.+Its renamed copy of Electron lives in `apps/desktop/.dev/` (git-ignored), signed only for this machine: you need no+certificate to run or change it. Its window's page imports Studio's editorfrom `packages/openfilm` as source, so a change to Studio shows in the app at its next start.`pnpm --filter @openfilm/desktop release` builds an installable app into `apps/desktop/.release/` (git-ignored),diff --git a/README.md b/README.mdindex 187ffa2..ca23e45 100644--- a/README.md+++ b/README.md@@ -66,6 +66,7 @@ openfilm open [folder | url] # show a film in Studio: a new one, an existinopenfilm look [what] [t | a-b] # check the film, a page or a media file: a contact sheet, one frame, or a rangeopenfilm render [a-b] # the MP4; --4k, --blur (motion blur), --alpha (.webm / .mov)openfilm get [what] # voice-over, music, sound effects, transcripts, images, video, from your services+openfilm doctor # what this computer has for OpenFilm, to paste into an issue````openfilm <command> --help` lists a command's options; `openfilm get` alone lists what can be made and how to@@ -140,11 +141,12 @@ PATH, and git.```shgit clone https://github.com/openfilm/openfilm && cd openfilmpnpm install-pnpm dev # Studio from this checkout, with a sample film, apart from an installed OpenFilm+pnpm dev # Studio from this checkout, with a sample film, beside an installed OpenFilmpnpm test```-Open your coding agent in `packages/openfilm/.dev/projects` and it makes films with your checkout, in that Studio.+Tell your coding agent to run `packages/openfilm/.dev/bin/openfilm` and it makes films with your checkout, in that+Studio. Every OpenFilm, installed or from source, keeps its projects in the same library.`pnpm dev:desktop` runs the desktop app from source, and `pnpm typecheck`, `pnpm build` and `pnpm audit:public` dowhat they say.@@ -153,7 +155,8 @@ what they say.## CommunityQuestions, ideas and films you made go to [Discussions](https://github.com/openfilm/openfilm/discussions): ask in-Q&A, share your film in Show and tell. Bugs go to [Issues](https://github.com/openfilm/openfilm/issues).+Q&A, share your film in Show and tell. Bugs go to [Issues](https://github.com/openfilm/openfilm/issues), with the+report from Studio's Settings → Developer → Copy report (or `npx openfilm doctor`).## Contributingdiff --git a/README.zh-CN.md b/README.zh-CN.mdindex 3278816..3aea1d4 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -134,11 +134,12 @@ OpenFilm 把功夫花在模型容易出错的地方:检查片子。`look` 会```shgit clone https://github.com/openfilm/openfilm && cd openfilmpnpm install-pnpm dev # 用这份源码运行 Studio,带一部示例片,和你安装的 OpenFilm 互不干扰+pnpm dev # 用这份源码运行 Studio,带一部示例片,和你安装的 OpenFilm 各用各的端口pnpm test```-在 `packages/openfilm/.dev/projects` 里打开你的编程智能体,它就会用这份源码在这个 Studio 里做片子。+让你的编程智能体运行 `packages/openfilm/.dev/bin/openfilm`,它就会用这份源码在这个 Studio 里做片子。不管是安装的还是+源码运行的 OpenFilm,项目都在同一个项目库里。`pnpm dev:desktop` 从源码运行桌面版;`pnpm typecheck`、`pnpm build` 和 `pnpm audit:public` 分别是类型检查、构建和公开内容审计。各个包的详细说明见 [CONTRIBUTING.md](CONTRIBUTING.md)(英文)。diff --git a/apps/desktop/chat/src/App.tsx b/apps/desktop/chat/src/App.tsxindex 6fdf342..36d1f8d 100644--- a/apps/desktop/chat/src/App.tsx+++ b/apps/desktop/chat/src/App.tsx@@ -6,13 +6,15 @@* (lib/local-agent-run's saved turns).*/import React from 'react';-import { ArrowDown, Blocks, Coins, CornerDownLeft, LibraryBig, Loader2, Play, Plus, ShieldQuestion, Square, SquareSlash, X } from 'lucide-react';+import { ArrowDown, Blocks, Coins, CornerDownLeft, LibraryBig, Loader2, Plus, ShieldQuestion, Square, SquareSlash, X } from 'lucide-react';import { buildPromptDisplay, type Turn } from '@openfilm/shared';import { useT, useUiLocale } from '@/i18n';import { ConversationSessionBar } from '@/components/ConversationSessionBar';import { ProjectConversation, primeStoredTranscript } from '@/components/ProjectConversation';import { ProjectStarters } from '@/components/ProjectStarters';import { AttachmentPreview, type AttachmentPreviewItem } from '@/components/AttachmentPreview';+import { ATTACHMENT_CARD, ATTACHMENT_THUMB, AttachmentCardBody, PlayMark } from '@/components/AttachmentCard';+import { attachmentPlace } from '@/lib/attachment-place';import { ModelPopover } from '@/components/ModelPopover';import { AddSkillDialog, type PickedSkill } from '@/components/AddSkill';import { CardActions, CardButton, ComposerCard } from '@/components/ComposerCard';@@ -22,7 +24,7 @@ import { StickToBottomContext, useStickToBottom, useTailSpacer } from '@/componeimport { PromptEditor, PromptPill, PromptPillHoverContext, PromptPillRevealContext, activatedSkillIds, fileReferenceId, fileReferencePath, promptReferenceToken, resolvePromptReferences, skillReferenceId, skillReferencePackage, splitPromptReferenceText, type MentionProvider, type PromptEditorHandle, type PromptEditorState, type PromptPillHover, type PromptReference } from '@/components/prompt-editor';import { filesFromTransfer, transferHasFiles } from '@/lib/composer-attachments';import { attachmentIcon } from '@/lib/project-resources';-import { attachedPictures, attachedText, attachmentBlocker, formatFileSize, turnAttachments, useDesktopAttachments } from '@/lib/desktop-attachments';+import { PROMPT_PICTURES_MAX, attachedPictures, attachedText, attachmentBlocker, formatFileSize, turnAttachments, useDesktopAttachments } from '@/lib/desktop-attachments';import { deriveProjectTurns } from '@/lib/project-versions';import { makePlaceholder, mergeAssetLists } from '@/lib/asset-lists';import { isEmptyBackgroundTurn } from '@/lib/unprompted';@@ -51,11 +53,12 @@ import {type LocalAgentTurn,type LocalTranscriptStore,} from '@/lib/local-agent-run';-import type { LocalAgentId, LocalAgentTurnMeta, PromptImage } from '@/lib/desktop-bridge';+import { desktopBridge, type LocalAgentId, type LocalAgentTurnMeta, type PromptImage } from '@/lib/desktop-bridge';import { referencePictures } from '@/lib/ref-pictures';import type { TurnFileChanges } from '@/lib/file-changes';import { readBalance, type TurnBalance } from '@/lib/balance';import { BalanceNotice } from '@/components/BalanceNotice';+import { CopyDiagnostics } from '@/components/CopyDiagnostics';import { readStudioFilm } from '@/lib/studio-film';import { studioRefsFromTransfer, transferHasStudioRefs } from '@/lib/studio-transfer';import { agentModelSummary, agentOptions, currentAgent, effectivePrefs, offeredOption, useLocalAgents } from '@/state/local-agent-store';@@ -85,14 +88,6 @@ const CONTEXT_NOTICE_SHARE = 0.85;const SKILLS_CHANGED = 'openfilm:skills-changed';const MAKE_SKILL = 'openfilm:make-skill';-function PlayMark() {- return (- <span aria-hidden className="pointer-events-none absolute inset-0 m-auto flex h-4 w-4 items-center justify-center rounded-full bg-black/55">- <Play size={8} className="translate-x-[0.5px] fill-white text-white" />- </span>- );-}-export function App({ initialProject, initialSelection, initialFfmpeg }: {initialProject: Project | null;initialSelection: StudioSelection | null;@@ -244,6 +239,8 @@ function ChatPane({ project, banners, selection, assetsOpen }: { project: Projecconst opLog = React.useMemo(() => (blank ? [] : deriveProjectTurns(ordered, [], asset?.id ?? null)), [blank, ordered, asset?.id]);const localTurn = useLocalAgentTurn(asset?.id ?? null);+ /* why the last turn failed: as it happened, or, the chat opened again on it (the app restarted), as it was kept */+ const turnError = localTurn ? localTurn.state.error : asset?.status === 'error' && !(asset as Turn & TurnBalance).balance ? asset.error ?? null : null;const liveStore = localTurn?.turn.store ?? EMPTY_STORE;const activity = useLiveActivityFromStore(liveStore, localTurn?.state.thinking ?? false, false);@@ -280,7 +277,7 @@ function ChatPane({ project, banners, selection, assetsOpen }: { project: Projecconst [studioRefs, setStudioRefs] = React.useState<Map<string, StudioRef>>(() => new Map());const [queued, setQueued] = React.useState(false);const [followUpError, setFollowUpError] = React.useState<string | null>(null);- const composerFiles = useDesktopAttachments();+ const composerFiles = useDesktopAttachments(project.path);/* a file of the message being written, opened to look at */const [openedFile, setOpenedFile] = React.useState<AttachmentPreviewItem | null>(null);const attachInputRef = React.useRef<HTMLInputElement>(null);@@ -705,7 +702,7 @@ function ChatPane({ project, banners, selection, assetsOpen }: { project: Projec/* the skills it names: each one's SKILL.md follows the message, for the agent to read */const skillNames = activatedSkillIds(followUpRefs);if (!instruction) return;- const blocker = attachmentBlocker(composerFiles.files);+ const blocker = attachmentBlocker(composerFiles.files, t);if (blocker) { setFollowUpError(blocker); return; }setFollowUpError(null);const promptDisplay = buildPromptDisplay(followUp, followUpRefs);@@ -726,10 +723,11 @@ function ChatPane({ project, banners, selection, assetsOpen }: { project: Projec/* an example pointed at: its folder fetched now if it is not yet (the turn waits, as it waits for its reply) */const withFolders = Promise.all(refs.map(async (ref) => (ref.kind === 'example' && !ref.folder? { ...ref, folder: await app.exampleFolder?.(ref.id).catch(() => undefined) } : ref)));+ /* the pictures sent: the references' first, then the attached ones while there is room (the rest by their path) */const prepared = withFolders.then((ready) => Promise.all([referencePictures(ready, { project: project.path, turnId: id }), skillTexts])- .then(([{ pictures, images }, skills]) => ({+ .then(async ([{ pictures, images }, skills]) => ({text: said + studioReferencesText(ready, { stage, pictures }) + skills.map((s) => `\n\n${s.text}`).join(''),- images: [...attachedPictures(files), ...images],+ images: [...images, ...await attachedPictures(files, PROMPT_PICTURES_MAX - images.length)],})));const opened = openTurn(id, instruction, promptDisplay ?? null, turnAttachments(files));if (steer && asset) steerTurn(asset.id, opened, prepared);@@ -801,10 +799,10 @@ function ChatPane({ project, banners, selection, assetsOpen }: { project: Projec}`}>{composerFiles.files.length > 0 && (- /* whole rows: up to three show at once (a message's twelve files fit in two), only more than that scrolls */+ /* whole rows: up to three show at once, only more than that scrolls */<div className="flex max-h-[144px] flex-wrap gap-1.5 overflow-y-auto px-3.5 pt-3">{composerFiles.files.map((file) => {- const Icon = attachmentIcon({ name: file.name, mediaType: file.mediaType });+ const Icon = attachmentIcon({ name: file.name, mediaType: file.mediaType, folder: file.folder });const remove = (<spanrole="button"@@ -816,33 +814,37 @@ function ChatPane({ project, banners, selection, assetsOpen }: { project: Projec<X size={10} /></span>);- const busy = file.state === 'importing' ? <Loader2 size={12} className="absolute inset-0 m-auto animate-spin text-white drop-shadow" /> : null;+ const busy = file.state === 'pending' ? <Loader2 size={12} className="absolute inset-0 m-auto animate-spin text-white drop-shadow" /> : null;/* a picture shows itself; a video, a frame of itself with a play mark (once one is had) */const picture = file.kind === 'image' ? file.previewUrl : file.thumb;- /* clicked, it opens to look at: a picture large, a video played, a text read */- const open = file.previewUrl && !file.folder ? {+ /* clicked, it opens to look at: a picture large, a video played, a text read; a folder, shown where it is */+ const folderPath = file.folder && file.state === 'ready' ? file.path : undefined;+ const open = file.previewUrl || folderPath ? {role: 'button' as const,tabIndex: 0,- 'aria-label': t('composer.openAttachment').replace('{name}', file.name),- onClick: () => setOpenedFile({ name: file.name, kind: file.kind, url: file.previewUrl!, ...(file.mediaType ? { mediaType: file.mediaType } : {}) }),+ 'aria-label': t(folderPath ? 'composer.revealFolder' : 'composer.openAttachment').replace('{name}', file.name),+ onClick: () => (folderPath+ ? void desktopBridge()?.revealPath(folderPath)+ : setOpenedFile({ name: file.name, kind: file.kind, url: file.previewUrl!, ...(file.mediaType ? { mediaType: file.mediaType } : {}) })),onKeyDown: (event: React.KeyboardEvent) => { if (event.key === 'Enter' || event.key === ' ') { event.preventDefault(); (event.currentTarget as HTMLElement).click(); } },} : {};return picture ? (- <div key={file.id} title={file.error ?? file.name} {...open}- className={`group relative h-10 w-10 overflow-hidden rounded-[8px] border bg-[var(--surface-2)] transition ${file.previewUrl ? 'cursor-pointer' : ''} ${file.state === 'failed' ? 'border-[var(--danger)]' : 'border-[var(--border)] hover:border-[var(--border-strong)]'}`}>+ <div key={file.id} title={file.error ?? file.path ?? file.name} {...open}+ className={`group ${ATTACHMENT_THUMB} transition ${file.previewUrl ? 'cursor-pointer' : ''} ${file.state === 'failed' ? 'border-[var(--danger)]' : 'border-[var(--border)] hover:border-[var(--border-strong)]'}`}><img src={picture} alt={file.name} className={`h-full w-full object-cover transition ${file.state === 'ready' ? '' : 'opacity-45'}`} />{file.kind !== 'image' && !busy ? <PlayMark /> : null}{busy}{remove}</div>) : (- <div key={file.id} title={file.error ?? file.name} {...open}- className={`group relative flex h-10 min-w-0 max-w-[150px] items-center gap-1.5 overflow-hidden rounded-[8px] border bg-[var(--surface-2)] py-1 pl-2 pr-5 transition ${file.previewUrl && !file.folder ? 'cursor-pointer' : ''} ${file.state === 'failed' ? 'border-[var(--danger)]' : 'border-[var(--border)] hover:border-[var(--border-strong)]'}`}>- {file.state === 'importing' ? <Loader2 size={13} className="shrink-0 animate-spin text-[var(--text-muted)]" /> : <Icon size={13} className="shrink-0 text-[var(--text-muted)]" />}- <span className="flex min-w-0 flex-col">- <span className="truncate text-[11.5px] leading-tight text-[var(--text-muted)]">{file.name}</span>- <span className="truncate text-[10.5px] leading-tight text-[var(--text-faint)]">{file.state === 'failed' ? 'Not added' : file.folder ? t('composer.folder') : formatFileSize(file.size)}</span>- </span>+ <div key={file.id} title={file.error ?? file.path ?? file.name} {...open}+ className={`group ${ATTACHMENT_CARD} transition ${file.previewUrl || folderPath ? 'cursor-pointer' : ''} ${file.state === 'failed' ? 'border-[var(--danger)]' : 'border-[var(--border)] hover:border-[var(--border-strong)]'}`}>+ <AttachmentCardBody+ icon={file.state === 'pending' ? <Loader2 size={14} className="animate-spin" /> : <Icon size={14} />}+ name={file.name}+ /* a folder's size is not read: where it is says more */+ detail={file.state === 'failed' ? 'Not added' : file.folder ? (file.path ? attachmentPlace(file.path) : null) : formatFileSize(file.size)}+ />{remove}</div>);@@ -946,11 +948,12 @@ function ChatPane({ project, banners, selection, assetsOpen }: { project: Projecbusy={active}/><div className="relative flex min-h-0 min-w-0 flex-1 flex-col">- {/* the first message well below the session bar, as a chat app opens a conversation */}+ {/* the first message well below the session bar, as a chat app opens a conversation; the last well above+ the composer, room for the way back to it */}<divref={thread.viewportRef}onScroll={(event) => setScrolled(event.currentTarget.scrollTop > 2)}- className={`flex min-h-0 min-w-0 flex-1 flex-col overflow-y-auto overflow-x-hidden [overflow-anchor:none] [scrollbar-gutter:stable] px-4${blank ? ' justify-center py-3.5' : ' pt-8 pb-10'}`}+ className={`flex min-h-0 min-w-0 flex-1 flex-col overflow-y-auto overflow-x-hidden [overflow-anchor:none] [scrollbar-gutter:stable] px-4${blank ? ' justify-center py-3.5' : ' pt-8 pb-24'}`}>{blank ? (<div ref={thread.contentRef}>@@ -977,14 +980,16 @@ function ChatPane({ project, banners, selection, assetsOpen }: { project: Projec<div aria-hidden className={`pointer-events-none absolute inset-x-0 top-0 h-6 bg-gradient-to-b from-[var(--dock-pane)] to-transparent transition-opacity duration-150 ${scrolled && !blank ? 'opacity-100' : 'opacity-0'}`} /><div aria-hidden className="pointer-events-none absolute inset-x-0 bottom-0 h-8 bg-gradient-to-t from-[var(--dock-pane)] to-transparent" />{!blank && !thread.atBottom && (- <button- type="button"- onClick={() => thread.scrollToBottom({ smooth: true })}- className="absolute bottom-1.5 left-1/2 flex h-7 -translate-x-1/2 items-center gap-1 rounded-full border border-[var(--border)] bg-[var(--surface)] px-2.5 text-[11.5px] font-medium text-[var(--text-dim)] shadow-[0_2px_10px_rgba(0,0,0,0.18)] transition hover:text-[var(--text)]"- >- <ArrowDown size={12} />- {t('project.jumpToLatest')}- </button>+ <Tooltip label={t('project.jumpToLatest')}>+ <button+ type="button"+ onClick={() => thread.scrollToBottom({ smooth: true })}+ aria-label={t('project.jumpToLatest')}+ className="absolute bottom-4 left-1/2 flex h-9 w-9 -translate-x-1/2 items-center justify-center rounded-full border border-[var(--border-strong)] bg-[var(--surface)] text-[var(--text-dim)] shadow-[0_2px_10px_rgba(0,0,0,0.18)] transition hover:bg-[var(--surface-2)] hover:text-[var(--text)]"+ >+ <ArrowDown size={17} />+ </button>+ </Tooltip>)}</div></div>@@ -1032,10 +1037,15 @@ function ChatPane({ project, banners, selection, assetsOpen }: { project: Projec</CardActions></ComposerCard>) : null}- {localTurn?.state.error ? <p role="alert" className="text-xs text-[var(--err)]">{localTurn.state.error}</p> : null}+ {turnError ? (+ <p role="alert" className="text-xs text-[var(--err)]">+ {turnError}{' '}+ {/* what to send when it keeps failing */}+ <span className="text-[var(--text-muted)]"><CopyDiagnostics /></span>+ </p>+ ) : null}{localTurn?.state.balance ? <BalanceNotice balance={localTurn.state.balance} /> : null}{followUpError && <p className="text-xs text-[var(--err)]">{followUpError}</p>}- {composerFiles.notice && <p className="text-xs text-[var(--warn)]">{composerFiles.notice}</p>}{queued && active ? (<p role="status" className="flex items-center gap-2 text-[12px] text-[var(--text-muted)]"><span className="h-1.5 w-1.5 shrink-0 rounded-full bg-[var(--accent)]" />diff --git a/apps/desktop/chat/src/app-bridge.ts b/apps/desktop/chat/src/app-bridge.tsindex 092131e..09b0309 100644--- a/apps/desktop/chat/src/app-bridge.ts+++ b/apps/desktop/chat/src/app-bridge.ts@@ -50,8 +50,6 @@ interface AppBridge {onStudioHover(listener: (ref: StudioRef | null) => void): () => void;/** the project's files (Studio's listing), for the @ menu */projectFiles(): Promise<{ files: Array<{ path: string; kind: string; size: number }>; pages?: Array<{ path: string; size: number }> }>;- /** bring a file into the project (assets/upload/): from its path, or its bytes */- importFile(file: { path: string; name: string } | { bytes: ArrayBuffer; name: string }): Promise<{ ok: true; path: string; folder?: boolean } | { ok: false; error: string }>;onSelection(listener: (selection: StudioSelection) => void): () => void;setChatWidth(width: number, done?: boolean): void;setChatOpen(open: boolean): void;@@ -72,6 +70,10 @@ interface AppBridge {reveal(project: string, turnId?: string): Promise<unknown>;/** a picture a message's reference points at, kept for its agent: .film/refs/<turn>-<n>.jpg (its path in the project) */saveRefImage(project: string, turnId: string, n: number, bytes: ArrayBuffer): Promise<{ path: string }>;+ /** a file pasted into a message (it has no path of its own), kept for its agent: .film/attachments/<name> */+ saveAttachment(project: string, name: string, bytes: ArrayBuffer): Promise<{ path: string }>;+ /** what each path dragged into a message is, where it is (nothing is copied) */+ describePaths(paths: string[]): Promise<Array<{ path: string; folder: boolean; size?: number } | { path: string; error: string }>>;/** the turns with a log and no saved record (src/chat-store.mjs unsavedTurns), but those of `except` */unsaved?(project: string, except?: string[]): Promise<Array<{ turnId: string; events: TurnLog['events'] }>>;/** the project's files as a turn starts, kept by the app; then what the turn changed in them (src/file-changes.mjs) */diff --git a/apps/desktop/chat/src/chat.css b/apps/desktop/chat/src/chat.cssindex 0489173..563a835 100644--- a/apps/desktop/chat/src/chat.css+++ b/apps/desktop/chat/src/chat.css@@ -118,7 +118,7 @@--card-bg: #0b0d14;/* Docked workspace: panes sit on a backing a step darker, and the gaps are that backing showing through.- As in Unreal: a divider says "a boundary", a gap says "two separate things". */+ A divider says "a boundary", a gap says "two separate things". */--dock-shell: #f2f2f2;--dock-pane: #fcfcfc;diff --git a/apps/desktop/chat/src/components/AttachmentCard.tsx b/apps/desktop/chat/src/components/AttachmentCard.tsxnew file mode 100644index 0000000..7ddcfeb--- /dev/null+++ b/apps/desktop/chat/src/components/AttachmentCard.tsx@@ -0,0 +1,34 @@+/**+ * What a message brought, as it shows in the composer and, the same, in the sent message: a picture or a video's+ * frame as a 40px square, anything else as a card as tall: its type's icon on a small tile, its name, and under it+ * what says most about it (a folder's place, a file's size).+ */+import React from 'react';+import { Play } from 'lucide-react';++/** A picture's square; the caller adds its border color and what a click does. */+export const ATTACHMENT_THUMB = 'relative h-10 w-10 shrink-0 overflow-hidden rounded-[8px] border bg-[var(--fill-tsp)]';++/** A card's shape, left-aligned even as a button; the caller adds its border color and what a click does. */+export const ATTACHMENT_CARD = 'relative flex h-10 min-w-0 max-w-[180px] items-center gap-2 overflow-hidden rounded-[8px] border bg-[var(--fill-tsp)] pl-1.5 pr-2.5 text-left';++export function AttachmentCardBody({ icon, name, detail }: { icon: React.ReactNode; name: string; detail?: string | null }) {+ return (+ <>+ <span className="flex h-7 w-7 shrink-0 items-center justify-center rounded-[6px] bg-[var(--bg-active)] text-[var(--text-muted)]">{icon}</span>+ <span className="flex min-w-0 flex-col">+ <span className="truncate text-[11.5px] leading-tight text-[var(--text)]">{name}</span>+ {detail ? <span className="truncate text-[10.5px] leading-tight text-[var(--text-muted)]">{detail}</span> : null}+ </span>+ </>+ );+}++/** Over a video's frame: it is not a picture. */+export function PlayMark() {+ return (+ <span aria-hidden className="pointer-events-none absolute inset-0 m-auto flex h-4 w-4 items-center justify-center rounded-full bg-black/55">+ <Play size={8} className="translate-x-[0.5px] fill-white text-white" />+ </span>+ );+}diff --git a/apps/desktop/chat/src/components/CopyDiagnostics.tsx b/apps/desktop/chat/src/components/CopyDiagnostics.tsxnew file mode 100644index 0000000..ea9d72b--- /dev/null+++ b/apps/desktop/chat/src/components/CopyDiagnostics.tsx@@ -0,0 +1,24 @@+/**+ * By a turn that failed: the diagnostic report on the clipboard, to paste into an issue (the app's main.mjs makes it:+ * what OpenFilm finds on this computer, the last week's problems, the agents). Not shown by a shell that lacks it.+ */+import React from 'react';+import { useT } from '@/i18n';+import { desktopBridge } from '@/lib/desktop-bridge';++export function CopyDiagnostics() {+ const t = useT();+ const copy = desktopBridge()?.agents?.copyReport;+ const [state, setState] = React.useState<'idle' | 'making' | 'copied'>('idle');+ if (!copy) return null;+ const run = () => {+ setState('making');+ void copy().then((r) => setState(r.ok ? 'copied' : 'idle'), () => setState('idle'));+ };+ return (+ <button type="button" onClick={run} disabled={state === 'making'} title={t('composer.copyDiagnosticsHint')}+ className="underline underline-offset-2 hover:text-[var(--text)] disabled:opacity-60">+ {state === 'copied' ? t('composer.diagnosticsCopied') : t('composer.copyDiagnostics')}+ </button>+ );+}diff --git a/apps/desktop/chat/src/components/ModelPopover.tsx b/apps/desktop/chat/src/components/ModelPopover.tsxindex 750208e..3e40168 100644--- a/apps/desktop/chat/src/components/ModelPopover.tsx+++ b/apps/desktop/chat/src/components/ModelPopover.tsx@@ -2,9 +2,11 @@* The composer's agent button: which agent is thinking and with what (its model, reasoning effort and speed), and a* menu to change them.*- * The menu lists the agents switched on in Settings → Agents (none when only one is: there is nothing to choose), then- * a row for each option the agent reports, with its value; pointing at a row opens its choices in a side menu beside- * it. Choosing leaves both open (a model and an effort are often changed together); a click elsewhere closes them.+ * The menu opens on a heading with a button to Settings → Agents, then lists the agents switched on there (none when+ * only one is: there is nothing to choose, and the heading names it instead), then its model and effort, always, and+ * its speed when it has one (agent-menu-rows.ts), each with its value; pointing at a row opens its choices in a side+ * menu beside it. Choosing leaves both open (a model and an effort are often changed together); a click elsewhere+ * closes them.** The chat is a view of its own and nothing can be drawn outside it, and the two never cover each other: the side menu* takes the room beside the card (a long name wraps to fit), the card slides left to make that room, and in a narrow@@ -12,7 +14,7 @@*/import React from 'react';import { createPortal } from 'react-dom';-import { Check, ChevronRight, KeyRound } from 'lucide-react';+import { Check, ChevronRight, KeyRound, Settings } from 'lucide-react';import { keepFocus, Popover } from './Popover';import { useT } from '@/i18n';import { Tooltip } from '@/components/Tooltip';@@ -21,6 +23,7 @@ import { POPOVER_CHROME } from '@/components/ComposerCard';import { desktopBridge, type LocalAgentId, type RosterAgent } from '@/lib/desktop-bridge';import { agentModelSummary, agentOptions, currentAgent, effectivePrefs, offeredChoices, offeredOption, optionLabel, optionValue, shownAgents, useLocalAgents } from '@/state/local-agent-store';import { chatLayer } from '@/lib/chat-layer';+import { isSpeed, menuOptions, type MenuOption } from '@/lib/agent-menu-rows';/** the card, wider when it lists the agents; the side menu's least width; the gap between them; the window's margin */const CARD_W = 236;@@ -37,7 +40,13 @@ const ROW_BASE ='flex min-h-[28px] w-full items-center gap-2 rounded-[6px] px-2.5 text-[13px] font-normal tracking-normal text-left outline-none transition';const ROW = `${ROW_BASE} hover:bg-[var(--bg-hover)] focus-visible:bg-[var(--bg-hover)]`;-type Option = { id: string; name: string; category?: string; options?: Array<{ value: unknown; name: string; description?: string }> };+type Option = MenuOption;++/** A row's choices: those the agent offers there, or its one value when that is all it has (a "default" too). */+function rowChoices(agent: LocalAgentId, o: Option, chosen: unknown): NonNullable<Option['options']> {+ if (o.fixed) return o.options!.slice(0, 1);+ return offeredChoices(agent, o, chosen);+}/** Why the agent could not be started for its settings, as it said, on a few lines; none when it started and offered none. */function failureReason(error: { text: string } | undefined): string | null {@@ -45,13 +54,6 @@ function failureReason(error: { text: string } | undefined): string | null {return error.text.replace(/\s+/g, ' ').trim().slice(0, 400) || null;}-/** The options the menu offers, in this order: the model, the reasoning effort, the speed (when the model has one). */-const isSpeed = (o: Option) => o.category === 'speed' || /^(fast|fast-mode|speed)$/i.test(o.id) || /\b(fast|speed)\b/i.test(o.name);-function menuOptions(options: Option[] | undefined): Option[] {- const pick = (test: (o: Option) => boolean) => (options ?? []).find((o) => test(o) && (o.options?.length ?? 0) > 1);- return [pick((o) => o.category === 'model'), pick((o) => o.category === 'thought_level'), pick(isSpeed)].filter((o): o is Option => Boolean(o));-}-export function ChatAgentIcon({ id, size = 14 }: { id: LocalAgentId; size?: number }) {if (id === 'byok') return <KeyRound size={size} />;return <AgentIcon id={id} size={size} />;@@ -101,11 +103,12 @@ export function ModelPopover({ placement = 'bottom', align = 'start' }: { placemconst options = agentOptions(la, agent);const prefs = effectivePrefs(la.prefs, agent, la.roster, options);- const rows = menuOptions(options).filter((o) => offeredOption(agent, la.roster, o));+ const rows = options ? menuOptions(options, t('composer.optionDefault')).filter((o) => offeredOption(agent, la.roster, o)) : [];const summary = agentModelSummary(options, prefs);const triggerModel = summary.model;- const triggerEffort = rows.some((o) => o.category === 'thought_level') ? summary.effort : null;- const valueOf = (o: Option) => (o.category === 'model' ? triggerModel : null) ?? optionLabel(options, o.id, optionValue(options, prefs, o.id)) ?? '';+ const triggerEffort = rows.some((o) => o.category === 'thought_level' && !o.fixed) ? summary.effort : null;+ const valueOf = (o: Option) => (o.fixed ? (optionLabel(options, o.id, optionValue(options, prefs, o.id)) ?? o.options![0]!.name)+ : (o.category === 'model' ? triggerModel : null) ?? optionLabel(options, o.id, optionValue(options, prefs, o.id)) ?? '');const rowLabel = (o: Option) => (o.category === 'model' ? t('composer.model') : o.category === 'thought_level' ? t('composer.effort') : isSpeed(o) ? t('composer.speed') : o.name);const nameOf = (a: RosterAgent) => (a.id === 'byok' ? t('composer.agentOwnKey') : a.name);@@ -128,8 +131,9 @@ export function ModelPopover({ placement = 'bottom', align = 'start' }: { placemconst openSettings = () => { setOpen(false); desktopBridge()?.openSettings?.('agents'); };const current = shown.find((a) => a.id === agent);const choosing = side ? rows.find((o) => o.id === side) : undefined;- const chosenValue = (o: Option) => optionValue(options, prefs, o.id);- const pickChoice = (o: Option, value: unknown) => la.setPref(agent, o.id, value);+ const chosenValue = (o: Option) => (o.fixed ? o.options![0]!.value : optionValue(options, prefs, o.id));+ /* a fixed row's one value is already the one in use */+ const pickChoice = (o: Option, value: unknown) => { if (!o.fixed) la.setPref(agent, o.id, value); };/* the side menu beside its row: on the right of the card, the card sliding left when the window is too narrow forboth, and over the card's right edge only when it cannot slide far enough; measured again once it is drawn */@@ -161,8 +165,8 @@ export function ModelPopover({ placement = 'bottom', align = 'start' }: { placemconst sideMenu = open && choosing && typeof document !== 'undefined' ? createPortal(<div ref={sideRef} onMouseEnter={() => showSide(choosing.id)} onMouseLeave={hideSideSoon}style={{ ...POPOVER_CHROME, padding: 4, overflowY: 'auto', ...(sideStyle ?? { position: 'fixed', left: -9999, top: 0 }) }}>- {/* the names only: no descriptions, and the choices the menu offers (offeredChoices) */}- {offeredChoices(agent, choosing, chosenValue(choosing)).map((choice) => {+ {/* the names only: no descriptions, and the choices the menu offers (rowChoices) */}+ {rowChoices(agent, choosing, chosenValue(choosing)).map((choice) => {const selected = chosenValue(choosing) === choice.value;return (<button key={String(choice.value)} type="button" onMouseDown={keepFocus}@@ -208,9 +212,18 @@ export function ModelPopover({ placement = 'bottom', align = 'start' }: { placem</div>) : (<>+ {/* the heading, and Settings → Agents beside it (where agents are switched on, connected and signed in) */}+ <div className="flex items-center gap-2 pb-0.5 pl-2.5 pr-0.5 pt-0.5">+ <span className="min-w-0 flex-1 truncate text-[11px] text-[var(--text-faint)]">{shown.length > 1 ? t('composer.agentSection') : current ? nameOf(current) : t('composer.agentSection')}</span>+ <Tooltip label={t('composer.openSettings')}>+ <button type="button" aria-label={t('composer.openSettings')} onMouseDown={keepFocus} onMouseEnter={hideSideSoon} onClick={openSettings}+ className="flex h-6 w-6 shrink-0 items-center justify-center rounded-[6px] text-[var(--text-faint)] outline-none transition hover:bg-[var(--bg-hover)] hover:text-[var(--text)] focus-visible:bg-[var(--bg-hover)]">+ <Settings size={13} />+ </button>+ </Tooltip>+ </div>{shown.length > 1 ? (<>- <div className="px-2.5 pb-1 pt-1 text-[11px] text-[var(--text-faint)]">{t('composer.agentSection')}</div>{shown.map((a) => {const status = statusOf(a);return (@@ -230,7 +243,7 @@ export function ModelPopover({ placement = 'bottom', align = 'start' }: { placem{current ? `${nameOf(current)}: ${statusOf(current) ?? ''}` : t('composer.agentLoading')}{' '}<button type="button" onMouseDown={keepFocus} onClick={openSettings} className="text-[var(--text)] underline underline-offset-2">{t('composer.openSettings')}</button></div>- ) : rows.length === 0 && options && !la.optionsError[agent] ? null : rows.length === 0 ? (+ ) : rows.length === 0 ? (<p className="px-2.5 py-1.5 text-[12px] leading-relaxed text-[var(--text-muted)]">{la.optionsError[agent]? <>diff --git a/apps/desktop/chat/src/components/ProjectConversation.tsx b/apps/desktop/chat/src/components/ProjectConversation.tsxindex a6bfbaf..87d41f0 100644--- a/apps/desktop/chat/src/components/ProjectConversation.tsx+++ b/apps/desktop/chat/src/components/ProjectConversation.tsx@@ -2,7 +2,7 @@import React from 'react';import type { PublicProgressSnapshot, TurnAttachment } from '@openfilm/shared';-import { BellRing, Check, ChevronRight, Copy, Play } from 'lucide-react';+import { BellRing, Check, ChevronRight, Copy } from 'lucide-react';import { AgentActivityList, formatWorkDuration, StatusLine, type AgentActivityItem } from './AgentActivityRow';import { AgentIcon, hasAgentIcon } from './AgentIcons';import { BrandLogo } from './BrandLogo';@@ -28,6 +28,9 @@ import { TurnLogButton } from './TurnLog';import { FileChangesList } from './FileChangesList';import { ChatProjectContext, useDeveloperMode, useShowChanges } from '@/lib/developer';import { isVideoAttachment } from '@/lib/composer-attachments';+import { desktopBridge } from '@/lib/desktop-bridge';+import { attachmentPlace } from '@/lib/attachment-place';+import { ATTACHMENT_CARD, ATTACHMENT_THUMB, AttachmentCardBody, PlayMark } from './AttachmentCard';/** What past turns get as "no live process". One constant: a new array each time would defeat the memo. */const NO_TRANSCRIPT: TranscriptItem[] = [];@@ -404,7 +407,8 @@ const ConversationTurn = React.memo(function ConversationTurn({{/* Still running: one status line, always one line high, only its text changes (see StatusLine), and thefooter under it on hover (its Log is the turn so far). Done, the footer alone. Always there, in one placein the tree: a log opened from it stays open as the turn finishes. An interruption doesn't- show Failed here: the reason and Resume appear above the composer, as in Cursor. */}+ show Failed here: the reason and Resume appear above the composer (the last turn's, even after a+ restart); an older one's reason is on its footer's Interrupted, on hover. */}{running ? <StatusLine items={rows ?? NO_ROWS} fallback={liveActivity} ownAgent={entry.agent === 'byok'} /> : null}<TurnFooter entry={entry} items={items} running={running} /></div>@@ -475,36 +479,32 @@ function TurnAttachments({ items }: { items: TurnAttachment[] }) {: (item.thumb? { name: item.name, kind: item.kind, url: item.thumb, thumbOnly: true }: null);- /* 32px squares: a receipt, not a gallery. Enough to recognize what was sent; open one to see it. The- smaller they are, the higher the text sits, and the bubble reads as a sentence, not an attachment list. */- const shell = item.thumb- ? 'relative h-8 w-8 overflow-hidden rounded-[6px] border border-[var(--border)] bg-[var(--surface)]'- : 'flex h-8 min-w-0 max-w-[132px] items-center gap-1 overflow-hidden rounded-[6px] border border-[var(--border)] bg-[var(--surface)] px-1.5';+ /* as each was in the composer: a square for a picture, a card for anything else */+ const shell = `${item.thumb ? ATTACHMENT_THUMB : ATTACHMENT_CARD} border-[var(--border)]`;/* a video's thumbnail is a frame of it: a play mark says it is not a picture */const inner = item.thumb ? (<>{/* eslint-disable-next-line @next/next/no-img-element */}<img src={item.thumb} alt={item.name} className="h-full w-full object-cover" />- {isVideoAttachment(item) ? (- <span aria-hidden className="pointer-events-none absolute inset-0 m-auto flex h-3.5 w-3.5 items-center justify-center rounded-full bg-black/55">- <Play size={7} className="translate-x-[0.5px] fill-white text-white" />- </span>- ) : null}+ {isVideoAttachment(item) ? <PlayMark /> : null}</>) : (- <>- <AttachmentTypeIcon file={item} size={11} className="shrink-0 text-[var(--chat-hint)]" />- <span className="truncate text-[11px] text-[var(--chat-hint)]">{item.name}</span>- </>+ <AttachmentCardBody+ icon={<AttachmentTypeIcon file={item} size={14} />}+ name={item.name.replace(/\/$/, '')}+ detail={item.path ? attachmentPlace(item.path) : null}+ />);- return preview ? (+ /* a folder stays where it was on the disk: clicked, it is shown there */+ const folderPath = item.path;+ return preview || folderPath ? (<buttonkey={`${item.name}-${index}`}type="button"- title={item.name}- aria-label={t('composer.openAttachment').replace('{name}', item.name)}- onClick={() => setOpen(preview)}+ title={folderPath ?? item.name}+ aria-label={t(folderPath ? 'composer.revealFolder' : 'composer.openAttachment').replace('{name}', item.name)}+ onClick={() => (folderPath ? void desktopBridge()?.revealPath(folderPath) : setOpen(preview))}className={`${shell} transition hover:border-[var(--border-strong)]`}>{inner}@@ -698,7 +698,7 @@ function TurnFooter({ entry, items, running = false }: { entry: ProjectVersion;</span>) : when ? <span>{when}</span> : null}{outcome ? (- <span className={entry.outcome === 'stopped' ? '' : 'text-[var(--warn)]'}>+ <span className={entry.outcome === 'stopped' ? '' : 'text-[var(--warn)]'} title={entry.error}>{entry.agent || when ? '· ' : ''}{outcome}</span>) : null}diff --git a/apps/desktop/chat/src/components/project-version.ts b/apps/desktop/chat/src/components/project-version.tsindex 6b47eac..889a023 100644--- a/apps/desktop/chat/src/components/project-version.ts+++ b/apps/desktop/chat/src/components/project-version.ts@@ -25,6 +25,8 @@ export interface ProjectVersion {outcome?: 'stopped' | 'failed' | 'balance';/** outcome 'balance': which service had no balance left, and its page to top it up */balance?: Balance;+ /** outcome 'failed': why, as the turn kept it (on its footer's Interrupted, on hover) */+ error?: string;/** When it was sent / settled (ISO): hover says "N minutes ago". */createdAt?: string;settledAt?: string;diff --git a/apps/desktop/chat/src/i18n/locales/en-US.ts b/apps/desktop/chat/src/i18n/locales/en-US.tsindex 0856eaf..0cfcb9e 100644--- a/apps/desktop/chat/src/i18n/locales/en-US.ts+++ b/apps/desktop/chat/src/i18n/locales/en-US.ts@@ -139,16 +139,23 @@ export const enUS = {agentSetUp: 'Set up',agentWaiting: 'Signing in…',effort: 'Effort',- folder: 'Folder',+ filesFailed: 'Couldn\'t attach {names}: {error} Remove it to send.',+ filesPending: 'The files are still being attached.',model: 'Model',+ /* the one value of a model or an effort the agent offers no choice of */+ optionDefault: 'Default',openAttachment: 'View {name}',+ revealFolder: 'Show {name} in its folder',openSettings: 'Open Settings',queued: 'Queued — sends when this turn finishes.',queuedCancel: 'Don\'t send',+ copyDiagnostics: 'Copy diagnostic report',+ copyDiagnosticsHint: 'What OpenFilm finds on this computer and its recent problems, to paste into an issue',+ diagnosticsCopied: 'Copied',removeFile: 'Remove file',removeImage: 'Remove image',speed: 'Speed',- thumbOnly: 'A thumbnail kept with the message. The original went to the agent and lives in the project assets.',+ thumbOnly: 'A thumbnail kept with the message. The original stays where it was, or in the project if it was pasted.',},library: {removeReference: 'Remove reference',diff --git a/apps/desktop/chat/src/i18n/locales/es.ts b/apps/desktop/chat/src/i18n/locales/es.tsindex 26fcda9..e4f2c64 100644--- a/apps/desktop/chat/src/i18n/locales/es.ts+++ b/apps/desktop/chat/src/i18n/locales/es.ts@@ -140,16 +140,23 @@ export const es: Words = {agentSetUp: 'Configurar',agentWaiting: 'Iniciando sesión…',effort: 'Esfuerzo',- folder: 'Carpeta',+ filesFailed: 'No se pudo adjuntar {names}: {error} Quítalo para enviar.',+ filesPending: 'Los archivos aún se están adjuntando.',model: 'Modelo',+ /* the one value of a model or an effort the agent offers no choice of */+ optionDefault: 'Predeterminado',openAttachment: 'Ver {name}',+ revealFolder: 'Mostrar {name} en su carpeta',openSettings: 'Abrir Configuración',queued: 'En cola: se envía cuando termine este turno.',queuedCancel: 'No enviar',+ copyDiagnostics: 'Copiar informe de diagnóstico',+ copyDiagnosticsHint: 'Lo que OpenFilm encuentra en este equipo y sus problemas recientes, para pegar en un issue',+ diagnosticsCopied: 'Copiado',removeFile: 'Quitar archivo',removeImage: 'Quitar imagen',speed: 'Velocidad',- thumbOnly: 'Una miniatura guardada con el mensaje. El original se envió al agente y está en los recursos del proyecto.',+ thumbOnly: 'Una miniatura guardada con el mensaje. El original sigue donde estaba, o en el proyecto si se pegó.',},library: {removeReference: 'Quitar referencia',diff --git a/apps/desktop/chat/src/i18n/locales/ja.ts b/apps/desktop/chat/src/i18n/locales/ja.tsindex 83dd6ac..61048f3 100644--- a/apps/desktop/chat/src/i18n/locales/ja.ts+++ b/apps/desktop/chat/src/i18n/locales/ja.ts@@ -140,16 +140,23 @@ export const ja: Words = {agentSetUp: '設定',agentWaiting: 'サインイン中…',effort: '思考レベル',- folder: 'フォルダ',+ filesFailed: '{names} を追加できませんでした:{error} 削除してから送信してください。',+ filesPending: 'ファイルを追加しています。',model: 'モデル',+ /* the one value of a model or an effort the agent offers no choice of */+ optionDefault: 'デフォルト',openAttachment: '{name} を表示',+ revealFolder: '{name} をフォルダに表示',openSettings: '設定を開く',queued: '待機中 — このターンが終わると送信されます。',queuedCancel: '送信しない',+ copyDiagnostics: '診断レポートをコピー',+ copyDiagnosticsHint: 'このコンピュータで OpenFilm が見つけた状況と最近の問題。issue に貼り付けられます',+ diagnosticsCopied: 'コピーしました',removeFile: 'ファイルを削除',removeImage: '画像を削除',speed: '速度',- thumbOnly: 'メッセージにはサムネイルだけが残ります。元のファイルはエージェントに送られ、プロジェクトの素材に保存されています。',+ thumbOnly: 'メッセージにはサムネイルだけが残ります。元のファイルは元の場所にあります。貼り付けたものはプロジェクトに保存されています。',},library: {removeReference: '参照を削除',diff --git a/apps/desktop/chat/src/i18n/locales/ko.ts b/apps/desktop/chat/src/i18n/locales/ko.tsindex 2615a9a..2fe85d1 100644--- a/apps/desktop/chat/src/i18n/locales/ko.ts+++ b/apps/desktop/chat/src/i18n/locales/ko.ts@@ -140,16 +140,23 @@ export const ko: Words = {agentSetUp: '설정',agentWaiting: '로그인하는 중…',effort: '추론 강도',- folder: '폴더',+ filesFailed: '{names}을(를) 추가하지 못했습니다: {error} 제거한 뒤 보내세요.',+ filesPending: '파일을 추가하는 중입니다.',model: '모델',+ /* the one value of a model or an effort the agent offers no choice of */+ optionDefault: '기본값',openAttachment: '{name} 보기',+ revealFolder: '폴더에서 {name} 보기',openSettings: '설정 열기',queued: '대기 중 — 이번 턴이 끝나면 보냅니다.',queuedCancel: '보내지 않기',+ copyDiagnostics: '진단 보고서 복사',+ copyDiagnosticsHint: '이 컴퓨터에서 OpenFilm이 확인한 상태와 최근 문제, issue에 붙여 넣을 수 있습니다',+ diagnosticsCopied: '복사됨',removeFile: '파일 제거',removeImage: '이미지 제거',speed: '속도',- thumbOnly: '메시지에는 썸네일만 남겨 두었습니다. 원본은 에이전트에게 전달되었고 프로젝트 에셋에 있습니다.',+ thumbOnly: '메시지에는 썸네일만 남겨 두었습니다. 원본은 원래 위치에 있고, 붙여 넣은 파일은 프로젝트에 저장되어 있습니다.',},library: {removeReference: '참조 제거',diff --git a/apps/desktop/chat/src/i18n/locales/zh-CN.ts b/apps/desktop/chat/src/i18n/locales/zh-CN.tsindex 56c2eed..fb3774f 100644--- a/apps/desktop/chat/src/i18n/locales/zh-CN.ts+++ b/apps/desktop/chat/src/i18n/locales/zh-CN.ts@@ -140,16 +140,23 @@ export const zhCN: Words = {agentSetUp: '设置',agentWaiting: '正在登录…',effort: '思考强度',- folder: '文件夹',+ filesFailed: '{names} 添加失败:{error} 移除后再发送。',+ filesPending: '文件还在添加中。',model: '模型',+ /* the one value of a model or an effort the agent offers no choice of */+ optionDefault: '默认',openAttachment: '查看 {name}',+ revealFolder: '在文件夹中显示 {name}',openSettings: '打开设置',queued: '已排队,本轮结束后发送。',queuedCancel: '不发送',+ copyDiagnostics: '复制诊断信息',+ copyDiagnosticsHint: 'OpenFilm 在这台电脑上找到的情况和最近的问题,可以贴进 issue',+ diagnosticsCopied: '已复制',removeFile: '移除文件',removeImage: '移除图片',speed: '速度',- thumbOnly: '消息中只保留了缩略图。原图已发送给智能体,并保存在项目素材中。',+ thumbOnly: '消息中只保留了缩略图。原文件还在原来的位置;粘贴的文件保存在项目里。',},library: {removeReference: '移除引用',diff --git a/apps/desktop/chat/src/lib/agent-menu-rows.ts b/apps/desktop/chat/src/lib/agent-menu-rows.tsnew file mode 100644index 0000000..a697a00--- /dev/null+++ b/apps/desktop/chat/src/lib/agent-menu-rows.ts@@ -0,0 +1,41 @@+/**+ * The rows of the chat's agent menu (ModelPopover), from the config options the agent reports. Reads no React, so+ * `node --test` can use it.+ */++export type MenuOption = {+ id: string;+ name: string;+ category?: string;+ options?: Array<{ value: unknown; name: string; description?: string }>;+ /** a row the agent offers no choice of: its one value, shown and never set */+ fixed?: boolean;+};++export const isSpeed = (o: MenuOption) => o.category === 'speed' || /^(fast|fast-mode|speed)$/i.test(o.id) || /\b(fast|speed)\b/i.test(o.name);++/**+ * The rows the menu shows, in this order: the model and the reasoning effort, always, and the speed when the model has+ * one. A model or an effort the agent offers no choice of (GitHub Copilot picks its own) is a row all the same, its one+ * value `fixed`: `defaultName` when the agent names none.+ */+export function menuOptions(options: MenuOption[] | undefined, defaultName: string): MenuOption[] {+ const pick = (test: (o: MenuOption) => boolean, least: number) => {+ const found = (options ?? []).find((o) => test(o) && (o.options?.length ?? 0) >= least);+ return found ? { ...found, options: distinctNames(found.options!) } : undefined;+ };+ const always = (category: string, found: MenuOption | undefined): MenuOption => (found && found.options!.length > 1 ? found+ : { id: found?.id ?? category, name: found?.name ?? category, category, fixed: true, options: found?.options?.length ? found.options : [{ value: null, name: defaultName }] });+ const speed = pick(isSpeed, 2);+ return [always('model', pick((o) => o.category === 'model', 1)), always('thought_level', pick((o) => o.category === 'thought_level', 1)), ...(speed ? [speed] : [])];+}++/**+ * Choices with names told apart: two the agent names alike (CodeBuddy's "Hy3" is two models, hy3 and hy3-x) each get+ * their value beside the name, "Hy3 (hy3-x)", or the menu would show the same row twice.+ */+export function distinctNames<T extends { value: unknown; name: string }>(choices: T[]): T[] {+ const count = new Map<string, number>();+ for (const c of choices) count.set(c.name, (count.get(c.name) ?? 0) + 1);+ return choices.map((c) => ((count.get(c.name) ?? 0) > 1 && c.value !== null && String(c.value) !== c.name ? { ...c, name: `${c.name} (${String(c.value)})` } : c));+}diff --git a/apps/desktop/chat/src/lib/attachment-place.ts b/apps/desktop/chat/src/lib/attachment-place.tsnew file mode 100644index 0000000..1f32664--- /dev/null+++ b/apps/desktop/chat/src/lib/attachment-place.ts@@ -0,0 +1,17 @@+/**+ * Where an attached folder is, short enough for its card: the folder it sits in, the home folder written as "~", and+ * only the last two folders of a deep path ("…/Projects/2026"). Empty for a folder at the top of a disk.+ */+export function attachmentPlace(path: string): string {+ const windows = /^[A-Za-z]:[\\/]/.test(path) || path.includes('\\');+ const sep = windows ? '\\' : '/';+ const trimmed = path.replace(/[\\/]+$/, '');+ const cut = Math.max(trimmed.lastIndexOf('/'), trimmed.lastIndexOf('\\'));+ if (cut <= 0) return '';+ const parent = trimmed.slice(0, cut);+ const home = parent.match(/^(?:\/Users\/[^/]+|\/home\/[^/]+|[A-Za-z]:[\\/]Users[\\/][^\\/]+)(?=$|[\\/])/);+ const rest = (home ? parent.slice(home[0].length) : parent).split(/[\\/]/).filter(Boolean);+ if (rest.length > 2) return ['…', ...rest.slice(-2)].join(sep);+ if (home) return ['~', ...rest].join(sep);+ return `${windows ? '' : '/'}${rest.join(sep)}`;+}diff --git a/apps/desktop/chat/src/lib/desktop-attachments.ts b/apps/desktop/chat/src/lib/desktop-attachments.tsindex 428f796..9a2d684 100644--- a/apps/desktop/chat/src/lib/desktop-attachments.ts+++ b/apps/desktop/chat/src/lib/desktop-attachments.ts@@ -1,10 +1,10 @@/*** The files brought into a message (dragged in, pasted, picked with +): a row of thumbnails (a picture's own, a- * video's frame) and names above the sentence. On the desktop each goes into the project at once, through Studio's own- * import (assets/upload/): the agent works in the project folder, so that is where it can read them, and Studio's- * media shows them too. The message says where they are (attachedText), the bubble shows their names and thumbnails.- * A picture is also sent to the agent beside the text (`picture`), as one pasted in its own chat is, to an agent that- * takes pictures.+ * video's frame) and names above the sentence. Any number, and folders too. A file or folder from the disk stays where+ * it is: the message names its path, as an agent's own chat does, and the agent copies into the project what the film+ * uses. Only a pasted one, which has no path, is kept in the project (.film/attachments/). The message says where they+ * are (attachedText), the bubble shows their names and thumbnails. Pictures are also sent to the agent beside the text,+ * as one pasted in its own chat is, to an agent that takes pictures (attachedPictures).*/import React from 'react';import type { TurnAttachment } from '@openfilm/shared';@@ -20,22 +20,25 @@ export interface DesktopAttachment {kind: 'image' | 'document';mediaType: string;size: number;+ /** a folder from the disk: its path names it, nothing in it is read */+ folder?: boolean;/** the file itself, while it is in the composer: an image shows it, and any one opens it to look at (AttachmentPreview) */previewUrl?: string;/** the small picture kept with the message: an image's, or a frame of a video */thumb?: string;- state: 'importing' | 'ready' | 'failed';- /** where it landed in the project */+ state: 'pending' | 'ready' | 'failed';+ /** where it is: its own path on the disk, or where a pasted one was kept in the project */path?: string;- /** a folder brought in whole: every file in it is under `path` */- folder?: boolean;- /** a picture, as its agent is sent it beside the text */- picture?: PromptImage;+ /** the file, until the message goes: a picture is read for its agent only then, and only as many as are sent */+ file?: File;error?: string;}-/** at most this many in one message */-const MAX_FILES = 12;+/** at most this many pictures go with a message (the app sends no more: src/local-agents-ipc.mjs PROMPT_IMAGES_MAX) */+export const PROMPT_PICTURES_MAX = 20;++/** thumbnails made at once: a folder's worth of photos read all together would hold every one of them in memory */+const THUMBS_AT_ONCE = 4;const SIZE_UNITS = ['B', 'KB', 'MB', 'GB'];export function formatFileSize(bytes: number): string {@@ -45,18 +48,27 @@ export function formatFileSize(bytes: number): string {return `${unit ? value.toFixed(value < 10 ? 1 : 0) : value} ${SIZE_UNITS[unit]}`;}-export function useDesktopAttachments() {+export function useDesktopAttachments(project: string) {const [files, setFiles] = React.useState<DesktopAttachment[]>([]);- const [notice, setNotice] = React.useState<string | null>(null);const patch = (id: string, next: Partial<DesktopAttachment>) => setFiles((list) => list.map((f) => (f.id === id ? { ...f, ...next } : f)));- const count = React.useRef(0);- count.current = files.length;+ const thumbs = React.useRef<{ running: number; waiting: Array<() => Promise<void>> }>({ running: 0, waiting: [] });+ const thumbnail = React.useCallback((make: () => Promise<void>) => {+ const queue = thumbs.current;+ const next = () => {+ if (queue.running >= THUMBS_AT_ONCE) return;+ const job = queue.waiting.shift();+ if (!job) return;+ queue.running += 1;+ void job().catch(() => {}).finally(() => { queue.running -= 1; next(); });+ };+ queue.waiting.push(make);+ next();+ }, []);+const add = React.useCallback((incoming: File[]) => {- setNotice(null);- const room = Math.max(0, MAX_FILES - count.current);- if (incoming.length > room) setNotice(`Up to ${MAX_FILES} files in one message.`);- const items = incoming.slice(0, room).map((file) => {+ const bridge = (window as unknown as { openfilmDesktop?: { pathForFile?: (f: File) => string } }).openfilmDesktop;+ const items = incoming.map((file) => {const image = isImageAttachment(file);const item: DesktopAttachment = {id: `a${Date.now().toString(36)}${Math.random().toString(36).slice(2, 8)}`,@@ -65,28 +77,43 @@ export function useDesktopAttachments() {mediaType: file.type,size: file.size,previewUrl: URL.createObjectURL(file),- state: 'importing',+ state: 'pending',+ file,};- return { item, file };+ return { item, file, path: bridge?.pathForFile?.(file) ?? '' };});- count.current += items.length;setFiles((list) => [...list, ...items.map(({ item }) => item)]);for (const { item, file } of items) {if (item.kind === 'image') {- void readFileDataUrl(file).then(makeAttachmentThumb).then((thumb) => { if (thumb) patch(item.id, { thumb }); }).catch(() => {});- void attachedPicture(file).then((picture) => { if (picture) patch(item.id, { picture }); });+ thumbnail(() => readFileDataUrl(file).then(makeAttachmentThumb).then((thumb) => { if (thumb) patch(item.id, { thumb }); }));} else if (isVideoAttachment(file)) {/* a video shows a frame of itself, as a picture does: its name alone says little of what was sent */- void videoFrameDataUrl(file).then(makeAttachmentThumb).then((thumb) => { if (thumb) patch(item.id, { thumb }); }).catch(() => {});+ thumbnail(() => videoFrameDataUrl(file).then(makeAttachmentThumb).then((thumb) => { if (thumb) patch(item.id, { thumb }); }));}- /* a file from the disk goes by its path; a pasted one has none, so its bytes go */- const path = (window as unknown as { openfilmDesktop?: { pathForFile?: (f: File) => string } }).openfilmDesktop?.pathForFile?.(file) ?? '';- void (path ? Promise.resolve(null) : file.arrayBuffer())- .then((bytes) => app.importFile(path ? { path, name: item.name } : { bytes: bytes!, name: item.name }))- .then((r) => patch(item.id, r.ok ? { state: 'ready', path: r.path, ...(r.folder ? { folder: true } : {}) } : { state: 'failed', error: r.error }))+ }+ /* from the disk: its path, once the app has said whether it is a file or a folder (nothing is copied) */+ const onDisk = items.filter(({ path }) => path);+ if (onDisk.length) {+ void app.chat.describePaths(onDisk.map(({ path }) => path))+ .then((found) => onDisk.forEach(({ item }, i) => {+ const one = found[i];+ if (!one || 'error' in one) { patch(item.id, { state: 'failed', error: one?.error ?? 'That is not a file.' }); return; }+ if (one.folder) {+ URL.revokeObjectURL(item.previewUrl!);+ patch(item.id, { state: 'ready', path: one.path, folder: true, kind: 'document', previewUrl: undefined, file: undefined, thumb: undefined });+ } else patch(item.id, { state: 'ready', path: one.path, size: one.size ?? item.size });+ }))+ .catch((error: unknown) => onDisk.forEach(({ item }) => patch(item.id, { state: 'failed', error: error instanceof Error ? error.message : String(error) })));+ }+ /* pasted: no path of its own, so its bytes are kept in the project */+ for (const { item, file, path } of items) {+ if (path) continue;+ void file.arrayBuffer()+ .then((bytes) => app.chat.saveAttachment(project, item.name, bytes))+ .then((r) => patch(item.id, { state: 'ready', path: r.path })).catch((error: unknown) => patch(item.id, { state: 'failed', error: error instanceof Error ? error.message : String(error) }));}- }, []);+ }, [project, thumbnail]);const drop = React.useCallback((id: string) => {setFiles((list) => {@@ -101,37 +128,51 @@ export function useDesktopAttachments() {current.current = files;const take = React.useCallback((): DesktopAttachment[] => {const taken = current.current;- /* sent: the message keeps their thumbnails, the files are in the project */+ /* sent: the message keeps their thumbnails, the agent their paths */for (const f of taken) if (f.previewUrl) URL.revokeObjectURL(f.previewUrl);current.current = [];- count.current = 0;setFiles([]);return taken;}, []);- return { files, notice, setNotice, add, drop, take };+ return { files, add, drop, take };}-/** What still keeps the message from going: a file being imported, or one that did not import. */-export function attachmentBlocker(files: readonly DesktopAttachment[]): string | null {- if (files.some((f) => f.state === 'importing')) return 'The files are still going into the project.';+/** What still keeps the message from going: a file still on its way, or one that could not be attached. */+export function attachmentBlocker(files: readonly DesktopAttachment[], t: (path: string) => string): string | null {+ if (files.some((f) => f.state === 'pending')) return t('composer.filesPending');const failed = files.filter((f) => f.state === 'failed');- return failed.length ? `${failed.map((f) => f.name).join(', ')} did not go into the project: ${failed[0]!.error ?? 'try again'}. Remove it to send.` : null;+ return failed.length+ ? t('composer.filesFailed').replace('{names}', failed.map((f) => f.name).join(', ')).replace('{error}', failed[0]!.error ?? '')+ : null;}-/** After the message, for the agent: where the files are now. */+/** After the message, for the agent: where the files are. A folder's path ends in "/". */export function attachedText(files: readonly DesktopAttachment[]): string {const placed = files.filter((f) => f.path);if (!placed.length) return '';- return `\n\nAttached files (in this project folder):\n${placed.map((f) => `- ${f.path} (${f.folder ? 'folder: every file in it' : `${attachmentKind({ name: f.name, mediaType: f.mediaType })}, ${formatFileSize(f.size)}`})`).join('\n')}`;+ const line = (f: DesktopAttachment) => (f.folder+ ? `- ${f.path!.replace(/[\\/]+$/, '')}/ (folder)`+ : `- ${f.path} (${attachmentKind({ name: f.name, mediaType: f.mediaType })}, ${formatFileSize(f.size)})`);+ return `\n\nAttached files:\n${placed.map(line).join('\n')}`;}-/** The pictures among them, as their agent is sent them. */-export function attachedPictures(files: readonly DesktopAttachment[]): PromptImage[] {- return files.flatMap((f) => (f.picture ? [f.picture] : []));+/**+ * The pictures among them, as their agent is sent them: the first `room`, in the order they were attached (the rest go+ * by their path only). Read now, as the message goes: a folder's worth of photos would not all be sent anyway.+ */+export async function attachedPictures(files: readonly DesktopAttachment[], room: number): Promise<PromptImage[]> {+ const wanted = files.filter((f) => f.kind === 'image' && f.file).slice(0, Math.max(0, room));+ const made = await Promise.all(wanted.map((f) => attachedPicture(f.file!)));+ return made.filter((picture): picture is PromptImage => picture !== null);}-/** What the message keeps of them, to show in its bubble. */+/** What the message keeps of them, to show in its bubble (a folder's name ends in "/", and its path opens it). */export function turnAttachments(files: readonly DesktopAttachment[]): TurnAttachment[] {- return files.map((f) => ({ kind: f.kind, name: f.name, ...(f.thumb ? { thumb: f.thumb } : {}) }));+ return files.map((f) => ({+ kind: f.kind,+ name: f.folder ? `${f.name}/` : f.name,+ ...(f.thumb ? { thumb: f.thumb } : {}),+ ...(f.folder && f.path ? { path: f.path } : {}),+ }));}diff --git a/apps/desktop/chat/src/lib/desktop-bridge.ts b/apps/desktop/chat/src/lib/desktop-bridge.tsindex 0c707ad..57afd76 100644--- a/apps/desktop/chat/src/lib/desktop-bridge.ts+++ b/apps/desktop/chat/src/lib/desktop-bridge.ts@@ -180,6 +180,8 @@ export interface DesktopBridge {list(): Promise<RosterAgent[]>;connect(id: LocalAgentId): Promise<{ ok: boolean; error?: string }>;onChange(listener: (agents: RosterAgent[]) => void): () => void;+ /** The diagnostic report (the computer, the last week's problems, the agents) on the clipboard. Older shells lack it. */+ copyReport?(): Promise<{ ok: boolean }>;};/** Studio's Settings, on Agents (or Providers). */openSettings?(section?: 'agents' | 'providers'): void;diff --git a/apps/desktop/chat/src/lib/project-resources.ts b/apps/desktop/chat/src/lib/project-resources.tsindex c111ad9..dbb8501 100644--- a/apps/desktop/chat/src/lib/project-resources.ts+++ b/apps/desktop/chat/src/lib/project-resources.ts@@ -10,6 +10,7 @@ import {FileSpreadsheet,FileText,FileVideo,+ Folder,Image as ImageIcon,Subtitles,type LucideIcon,@@ -58,7 +59,8 @@ export function attachmentKind(file: { name: string; mediaType?: string }): Workreturn 'other';}-/** The icon for a file in the composer or a message. */-export function attachmentIcon(file: { name: string; mediaType?: string }): LucideIcon {+/** The icon for a file in the composer or a message; a folder's name ends in "/" (desktop-attachments turnAttachments). */+export function attachmentIcon(file: { name: string; mediaType?: string; folder?: boolean }): LucideIcon {+ if (file.folder || file.name.endsWith('/')) return Folder;return resourceIcon({ name: file.name, kind: attachmentKind(file) });}diff --git a/apps/desktop/chat/src/lib/project-versions.ts b/apps/desktop/chat/src/lib/project-versions.tsindex fdefdca..d32acca 100644--- a/apps/desktop/chat/src/lib/project-versions.ts+++ b/apps/desktop/chat/src/lib/project-versions.ts@@ -1,6 +1,6 @@import type { Turn, LibraryVideo, PromptDisplay, TurnAttachment } from '@openfilm/shared';-import { readFileChanges, type FileChange, type TurnFileChanges } from './file-changes';-import { readBalance, type Balance, type TurnBalance } from './balance';+import { readFileChanges, type FileChange, type TurnFileChanges } from './file-changes.ts';+import { readBalance, type Balance, type TurnBalance } from './balance.ts';/*** A project's conversation: each of its turns, in time order.@@ -38,6 +38,8 @@ export interface ProjectVersionEntry {outcome?: 'stopped' | 'failed' | 'balance';/** outcome 'balance': which service had no balance left, and its page */balance?: Balance;+ /** outcome 'failed': why, as the turn kept it */+ error?: string;/** When the message was sent (ISO). Hovering under the bubble says "N minutes ago". */createdAt?: string;/** When the turn settled (ISO), only for settled turns. Hovering under the reply says "N minutes ago". */@@ -51,7 +53,7 @@ export interface ProjectVersionEntry {/** Longest believable turn: anything longer most likely means a later write touched updatedAt. */const DURATION_MAX_MS = 3 * 60 * 60 * 1000;-function frameOf(asset: Turn): Pick<ProjectVersionEntry, 'agent' | 'model' | 'durationMs' | 'outcome' | 'balance' | 'createdAt' | 'settledAt'> {+function frameOf(asset: Turn): Pick<ProjectVersionEntry, 'agent' | 'model' | 'durationMs' | 'outcome' | 'balance' | 'error' | 'createdAt' | 'settledAt'> {const settled = asset.status === 'ready' || asset.status === 'error' || asset.status === 'cancelled';const ms = Date.parse(asset.updatedAt) - Date.parse(asset.createdAt);const model = asset.localAgent?.model ?? null;@@ -67,6 +69,7 @@ function frameOf(asset: Turn): Pick<ProjectVersionEntry, 'agent' | 'model' | 'du...(settled && Number.isFinite(ms) && ms > 0 && ms < DURATION_MAX_MS ? { durationMs: ms } : {}),...(outcome ? { outcome } : {}),...(balance ? { balance } : {}),+ ...(outcome === 'failed' && asset.error ? { error: asset.error } : {}),...(asset.createdAt ? { createdAt: asset.createdAt } : {}),...(settled && asset.updatedAt ? { settledAt: asset.updatedAt } : {}),};diff --git a/apps/desktop/chat/src/lib/ref-pictures.ts b/apps/desktop/chat/src/lib/ref-pictures.tsindex 6972a29..d7e6eff 100644--- a/apps/desktop/chat/src/lib/ref-pictures.ts+++ b/apps/desktop/chat/src/lib/ref-pictures.ts@@ -81,9 +81,12 @@ export async function referencePictures(refs: StudioRef[], { project, turnId }:return { pictures, images };}-/** an attached picture is sent as it is up to this size and this many pixels on its long side; larger, made smaller */+/**+ * an attached picture is sent as it is up to this size and this many pixels on its long side; larger, made smaller.+ * 2000: a request with more than 20 pictures in it (a conversation's, not only this message's) takes none larger+ */const ATTACHED_MAX_BYTES = 4 * 1024 * 1024;-const ATTACHED_MAX_SIDE = 2048;+const ATTACHED_MAX_SIDE = 2000;const AS_IS = new Set(['image/jpeg', 'image/png', 'image/webp']);/**diff --git a/apps/desktop/scripts/agent-check.mjs b/apps/desktop/scripts/agent-check.mjsnew file mode 100644index 0000000..ae79089--- /dev/null+++ b/apps/desktop/scripts/agent-check.mjs@@ -0,0 +1,89 @@+/**+ * Each of the person's own agents, as the chat would use it on this computer: found where the app looks (its login+ * shell's PATH and the usual folders), started (`--version`), and spoken to over ACP through the app's own code+ * (agents.mjs AgentSession: the same environment, adapter and command line as the chat's). The nightly `agents`+ * workflow runs it after installing the newest of each, so an agent's update that breaks the chat shows there first.+ *+ * node scripts/agent-check.mjs [agent…]+ *+ * Agents named must be found; with none named, every agent is tried and one not installed is left out. Nobody needs to+ * be signed in: an agent that asks for its sign-in, or refuses a session in its own words, was found, started and+ * spoke ACP, which is what this checks. Exit status 1 when one named is not found or does not get that far.+ * On GitHub Actions the table also goes to the job's summary.+ */+import { appendFileSync, mkdtempSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { pathToFileURL } from 'node:url';+import { AGENTS, AgentSession, checkAgentProgram, resolveAgentCli } from '../src/agents.mjs';+import { PATH_SEP, loginShellEnvironment } from '../src/environment.mjs';++const SESSION_MS = 120_000;++/**+ * How far an agent got: `found` (its program), `version` (what --version said), `acp` ('opened' a session, 'sign-in'+ * asked for, 'answered' with an error in ACP's own terms, else null) and `error` when it stopped short.+ * @param {string} id @param {string[]} pathDirs+ */+export async function checkAgent(id, pathDirs, { sessionMs = SESSION_MS } = {}) {+ const cli = resolveAgentCli(id, { pathDirs });+ if (!cli) return { id, found: null, version: null, acp: null, error: 'not found' };+ const started = await checkAgentProgram(id, cli.path);+ if (!started.ok) return { id, found: cli.path, version: null, acp: null, error: `--version: ${started.error}` };+ const cwd = mkdtempSync(join(tmpdir(), `openfilm-agent-check-${id}-`));+ const session = new AgentSession({ agent: id, cwd });+ let timer;+ try {+ await Promise.race([session.start(), new Promise((_, fail) => { timer = setTimeout(() => fail(new Error(`no session within ${sessionMs / 1000} s`)), sessionMs); })]);+ return { id, found: cli.path, version: started.version, acp: 'opened', error: null };+ } catch (e) {+ const err = /** @type {any} */ (e);+ if (err?.code === 'sign-in') return { id, found: cli.path, version: started.version, acp: 'sign-in', error: null };+ /* an error with a JSON-RPC code came from the agent over ACP: it started and spoke */+ if (typeof err?.code === 'number') return { id, found: cli.path, version: started.version, acp: 'answered', error: null, said: String(err.message) };+ const stderr = session.stderr.trim().split(/\r?\n/).slice(-8).join('\n');+ return { id, found: cli.path, version: started.version, acp: null, error: `${err?.message ?? err}${stderr ? `\n${stderr}` : ''}` };+ } finally {+ clearTimeout(timer);+ session.close();+ try { rmSync(cwd, { recursive: true, force: true }); } catch { /* a process still in it (Windows) */ }+ }+}++/** The results as a Markdown table, for the job's summary. */+export function summary(results, { platform = process.platform } = {}) {+ const cell = (text) => String(text ?? '').replace(/\\/g, '\\\\').replace(/\|/g, '\\|').replace(/\r?\n/g, '<br>');+ return [+ `### Agents on ${platform}`,+ '',+ '| Agent | Result | Version | Program | Said |',+ '| --- | --- | --- | --- | --- |',+ ...results.map((r) => `| ${AGENTS[r.id]?.label ?? r.id} | ${r.error ? `✗ ${cell(r.error.split('\n')[0])}` : `✓ ${r.acp}`} | ${cell(r.version)} | ${cell(r.found)} | ${cell(r.said ?? (r.error?.includes('\n') ? r.error.split('\n').slice(1).join('\n') : ''))} |`),+ '',+ ].join('\n');+}++async function main() {+ const named = process.argv.slice(2);+ const unknown = named.filter((id) => !Object.hasOwn(AGENTS, id));+ if (unknown.length) {+ console.error(`agent-check: no agent ${unknown.join(', ')} (there are ${Object.keys(AGENTS).join(', ')})`);+ process.exit(2);+ }+ const ids = named.length ? named : Object.keys(AGENTS);+ const pathDirs = (await loginShellEnvironment({ maxAgeMs: 0 })).PATH.split(PATH_SEP);+ const results = [];+ /* one at a time: each starts a program that may be heavy, and their outputs stay apart */+ for (const id of ids) {+ const r = await checkAgent(id, pathDirs);+ if (!named.length && r.error === 'not found') continue;+ results.push(r);+ const label = AGENTS[id].label;+ console.log(r.error ? `✗ ${label}: ${r.error}` : `✓ ${label}: ${r.version} · ${r.acp}${r.said ? ` (${r.said})` : ''} · ${r.found}`);+ }+ if (process.env.GITHUB_STEP_SUMMARY) appendFileSync(process.env.GITHUB_STEP_SUMMARY, summary(results));+ /* the adapters' children and stdio pipes would keep the process up */+ process.exit(results.some((r) => r.error) ? 1 : 0);+}++if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) await main();diff --git a/apps/desktop/scripts/agent-check.test.mjs b/apps/desktop/scripts/agent-check.test.mjsnew file mode 100644index 0000000..81cfeb6--- /dev/null+++ b/apps/desktop/scripts/agent-check.test.mjs@@ -0,0 +1,15 @@+import assert from 'node:assert/strict';+import { test } from 'node:test';+import { summary } from './agent-check.mjs';++test('the summary: a row per agent, how far it got, a failure\'s first line and what its program said', () => {+ const text = summary([+ { id: 'codex', found: 'C:\\npm\\codex.cmd', version: 'codex-cli 0.163.0', acp: 'opened', error: null },+ { id: 'copilot', found: '/usr/local/bin/copilot', version: '1.0.98', acp: 'answered', error: null, said: 'Authentication required | set a key' },+ { id: 'claude', found: '/usr/local/bin/claude', version: '2.1.302', acp: null, error: 'no session within 120 s\nTypeError: x is not a function' },+ ], { platform: 'win32' });+ assert.match(text, /^### Agents on win32/);+ assert.match(text, /\| Codex \| ✓ opened \| codex-cli 0\.163\.0 \| C:\\\\npm\\\\codex\.cmd \| \|/, 'a backslash escaped, so Markdown shows it as it is');+ assert.match(text, /\| GitHub Copilot \| ✓ answered \| .* \| Authentication required \\\| set a key \|/);+ assert.match(text, /\| Claude Code \| ✗ no session within 120 s \| .* \| TypeError: x is not a function \|/);+});diff --git a/apps/desktop/shell/bridge.ts b/apps/desktop/shell/bridge.tsindex 0e4d041..5568c04 100644--- a/apps/desktop/shell/bridge.ts+++ b/apps/desktop/shell/bridge.ts@@ -28,7 +28,6 @@ interface Native {/* the window's tabs (src/tabs.mjs) */tabs: NonNullable<StudioHost['tabs']>;localAgents: Record<string, unknown>;- importFile(request: { projectId: string; path: string; name: string }): Promise<{ ok: true; path: string; folder?: boolean } | { ok: false; error: string }>;chat: Record<string, (...args: never[]) => Promise<unknown>>;/* the composer's Skills button (src/skills-ipc.mjs) */skills: Record<string, (...args: never[]) => Promise<unknown>>;@@ -320,7 +319,6 @@ function commandFor(ref: StudioRef): StudioCommand {case 'example': return { type: 'show-examples', open: { kind: 'example', id: ref.id } };}}-const uploadName = (name: string) => name.split(/[\\/]/).pop()!.replace(/[\u0000-\u001f]+/g, '').slice(0, 200) || 'file';(window as unknown as { openfilmDesktop: unknown }).openfilmDesktop = {bridgeVersion: '1',@@ -378,19 +376,6 @@ const uploadName = (name: string) => name.split(/[\\/]/).pop()!.replace(/[\u0000if (!id) return { files: [] };try { return await (await fetch(`/api/projects/${encodeURIComponent(id)}/files`)).json(); } catch { return { files: [] }; }},- /* a file brought into the chat goes into the project (assets/upload/), through Studio's own import: a file on the- disk by its path (the app reads it), one with no path (pasted) by its bytes */- async importFile(file: { path: string; name: string } | { bytes: ArrayBuffer; name: string }) {- const id = project.get()?.id;- if (!id) return { ok: false, error: 'No project is open.' };- const name = uploadName(file.name);- if ('path' in file) return native.importFile({ projectId: id, path: file.path, name });- try {- const res = await fetch(`/api/projects/${encodeURIComponent(id)}/files?path=${encodeURIComponent(`assets/upload/${name}`)}`, { method: 'PUT', body: file.bytes });- const answer = await res.json().catch(() => ({})) as { path?: string; error?: string };- return res.ok ? { ok: true, path: answer.path } : { ok: false, error: answer.error ?? `Studio answered ${res.status}` };- } catch (error) { return { ok: false, error: (error as Error).message }; }- },setChatWidth: (width: number, done?: boolean) => setChatWidth(width, done === true),setChatOpen,assetsOpen: () => assets.open,diff --git a/apps/desktop/src/agent-installation.mjs b/apps/desktop/src/agent-installation.mjsindex b65059e..8c799de 100644--- a/apps/desktop/src/agent-installation.mjs+++ b/apps/desktop/src/agent-installation.mjs@@ -16,9 +16,9 @@ export const AGENT_DOWNLOADS = Object.freeze({copilot: 'https://github.com/features/copilot/cli',cursor: 'https://cursor.com/cli',opencode: 'https://opencode.ai/download',- codebuddy: 'https://www.workbuddy.ai/docs/cli/installation',+ codebuddy: 'https://www.codebuddy.cn/docs/cli/installation',qwen: 'https://github.com/QwenLM/qwen-code',- kimi: 'https://www.kimi.com/code',+ kimi: 'https://www.kimi.com/code/docs/en/kimi-code-cli/guides/getting-started.html',minimax: 'https://www.npmjs.com/package/@minimax-ai/code',});@@ -30,7 +30,9 @@ export const AGENT_PROGRAMS = Object.freeze({claude: { names: ['claude'] },codex: { names: ['codex'] },copilot: { names: ['copilot'] },- cursor: { names: ['cursor-agent'] },+ /* Cursor's installer names it `agent`, and `cursor-agent` as before; a program called `agent` counts only when it is+ Cursor's (its own folder is cursor-agent), as other tools are called that too */+ cursor: { names: ['cursor-agent', 'agent'], ours: (file, name) => name === 'cursor-agent' || inCursorFolder(file) },opencode: { names: ['opencode'], dirs: (home) => [join(home, '.opencode', 'bin')] },codebuddy: { names: ['codebuddy', 'cbc'] },qwen: { names: ['qwen'] },@@ -40,6 +42,13 @@ export const AGENT_PROGRAMS = Object.freeze({minimax: { names: ['mcode'], dirs: (home) => [join(home, '.minimax-code', 'bin')] },});+/** Whether a program is the one in Cursor's own folder (…/cursor-agent/…), followed through its link. */+export function inCursorFolder(file) {+ let real = file;+ try { real = realpathSync(file); } catch { /* as it is */ }+ return /[\\/]cursor-agent[\\/]/i.test(real);+}+export function executableFile(path) {try { accessSync(path, constants.X_OK); return statSync(path).isFile(); } catch { return false; }}@@ -308,7 +317,15 @@ export function detectAgentInstallation(id, { home = homedir(), env = process.enif (picked) return { installed: true, cli: picked, source: 'chosen', install };const dirs = [...pathDirs, ...(program.dirs?.(home) ?? [])];let cli = null;- for (const name of program.names) if (!cli) cli = findExecutable(name, dirs, env, { win });+ for (const name of program.names) {+ if (cli) break;+ if (!program.ours) { cli = findExecutable(name, dirs, env, { win }); continue; }+ /* each folder in turn: another program by that name earlier on the PATH does not hide the agent's */+ for (const dir of unique([...pathIn(env).split(win ? ';' : delimiter), ...dirs], win)) {+ const file = findExecutable(name, [dir], { PATH: '' }, { win });+ if (file && program.ours(file, name)) { cli = file; break; }+ }+ }if (cli) {/* Claude Code both on the PATH (an npm install that is never updated, say) and in the Claude app, which keeps itsown up to date: the later one, whose models are the current ones. One whose version can't be told stays. */diff --git a/apps/desktop/src/agent-installation.test.mjs b/apps/desktop/src/agent-installation.test.mjsindex 9c3ae28..15c0777 100644--- a/apps/desktop/src/agent-installation.test.mjs+++ b/apps/desktop/src/agent-installation.test.mjs@@ -263,3 +263,22 @@ test('Codex installed long ago beside the copy an app keeps up to date: the lateassert.equal(detectAgentInstallation('codex', { ...opts, codexVersionOf: versions({ [inApp]: '0.163.0' }) }).cli, onPath, 'one whose version can\'t be told stays');assert.equal(detectAgentInstallation('codex', { ...opts, chosen: onPath, codexVersionOf: versions({ [onPath]: '0.1.0', [inApp]: '0.163.0' }) }).cli, onPath, 'the one chosen, whatever its version');});++test("Cursor installed as `agent` alone is found; another program called `agent` is not taken for it", () => {+ if (process.platform === 'win32') return;+ const home = mkdtempSync(join(tmpdir(), 'of-home-'));+ const exe = (file) => { mkdirSync(join(file, '..'), { recursive: true }); writeFileSync(file, '', { mode: 0o755 }); return file; };+ /* some other tool's `agent` */+ const other = join(home, 'other-bin');+ exe(join(other, 'agent'));+ assert.equal(detectAgentInstallation('cursor', { home, env: { PATH: '' }, pathDirs: [other] }).cli, null);+ /* Cursor's installer: its own folder, linked as `agent` (the legacy `cursor-agent` link gone) */+ const real = exe(join(home, '.local/share/cursor-agent/versions/2026.10.16-e3cb207/cursor-agent'));+ const bin = join(home, '.local/bin');+ mkdirSync(bin, { recursive: true });+ symlinkSync(real, join(bin, 'agent'));+ assert.equal(detectAgentInstallation('cursor', { home, env: { PATH: '' }, pathDirs: [other, bin] }).cli, join(bin, 'agent'));+ /* both links, as the installer makes them now: `cursor-agent` first */+ symlinkSync(real, join(bin, 'cursor-agent'));+ assert.equal(detectAgentInstallation('cursor', { home, env: { PATH: '' }, pathDirs: [bin] }).cli, join(bin, 'cursor-agent'));+});diff --git a/apps/desktop/src/agent-menu-rows.test.mjs b/apps/desktop/src/agent-menu-rows.test.mjsnew file mode 100644index 0000000..f6cc138--- /dev/null+++ b/apps/desktop/src/agent-menu-rows.test.mjs@@ -0,0 +1,31 @@+import assert from 'node:assert/strict';+import { test } from 'node:test';+import { distinctNames, menuOptions } from '../chat/src/lib/agent-menu-rows.ts';++const rows = (options) => menuOptions(options, 'Default').map((o) => [o.category, o.fixed === true, o.options.map((c) => c.name)]);++test('the menu always has a model and an effort row, "Default" for one the agent does not offer', () => {+ /* GitHub Copilot: one model, no effort */+ assert.deepEqual(rows([{ id: 'model', name: 'Model', category: 'model', options: [{ value: 'auto', name: 'Auto' }] }, { id: 'mode', name: 'Mode', category: 'mode', options: [{ value: 'a', name: 'Agent' }, { value: 'p', name: 'Plan' }] }]),+ [['model', true, ['Auto']], ['thought_level', true, ['Default']]]);+ assert.deepEqual(rows([]), [['model', true, ['Default']], ['thought_level', true, ['Default']]]);+});++test('a model or an effort with choices is offered as it is, and the speed only when there is one to choose', () => {+ const options = [+ { id: 'model', name: 'Model', category: 'model', options: [{ value: 'a', name: 'A' }, { value: 'b', name: 'B' }] },+ { id: 'effort', name: 'Effort', category: 'thought_level', options: [{ value: 'low', name: 'Low' }, { value: 'high', name: 'High' }] },+ { id: 'fast', name: 'Fast mode', options: [{ value: 'off', name: 'Off' }] },+ ];+ assert.deepEqual(rows(options), [['model', false, ['A', 'B']], ['thought_level', false, ['Low', 'High']]]);+ options[2].options.push({ value: 'on', name: 'On' });+ assert.deepEqual(rows(options).map(([c]) => c), ['model', 'thought_level', undefined]);+});++test('two choices named alike are told apart by their values; the others keep their names', () => {+ /* CodeBuddy 2.168: "Hy3" is hy3 and hy3-x */+ assert.deepEqual(distinctNames([{ value: 'hy4', name: 'Hy4' }, { value: 'hy3', name: 'Hy3' }, { value: 'hy3-x', name: 'Hy3' }]).map((c) => c.name),+ ['Hy4', 'Hy3 (hy3)', 'Hy3 (hy3-x)']);+ const [model] = menuOptions([{ id: 'model', name: 'Model', category: 'model', options: [{ value: 'a', name: 'A' }, { value: 'b', name: 'A' }] }], 'Default');+ assert.deepEqual(model.options.map((c) => c.name), ['A (a)', 'A (b)']);+});diff --git a/apps/desktop/src/agent-roster.mjs b/apps/desktop/src/agent-roster.mjsindex 3682c87..a5cf3e9 100644--- a/apps/desktop/src/agent-roster.mjs+++ b/apps/desktop/src/agent-roster.mjs@@ -56,9 +56,12 @@ const DEFAULT_SHOWN = { codex: true, claude: true, byok: false };/* Codex is used as it is signed in on the computer from the start; Claude Code only once the person connects it, whichsigns in to their Claude subscription the first time */const DEFAULT_DISCONNECTED = Object.freeze(['claude']);-/** How long a sign-in in Terminal is waited for, asked about every few seconds. */-const SIGN_IN_WAIT_MS = 5 * 60_000;-const SIGN_IN_POLL_MS = 3000;+/**+ * How long a sign-in in Terminal is waited for, asked about every few seconds: a person may first sign in to the+ * maker's site, with a code sent to them (five minutes, as it was, was too short for Cursor's). Once it is over, the+ * window coming back into focus asks again (Settings → Agents).+ */+const SIGN_IN_WAIT = { ms: 15 * 60_000, pollMs: 3000 };/** A red 16 × 16 picture, for asking a model whether it reads pictures. */const PROBE_PNG = 'iVBORw0KGgoAAAANSUhEUgAAABAAAAAQCAIAAACQkWg2AAAAFklEQVR4nGN4pqFBEmIY1TCqYfhqAACM5TYQULtblwAAAABJRU5ErkJggg==';@@ -185,6 +188,7 @@ export async function probeModel({ format, baseUrl, key, model, fetch: fetchImpl* @param {{* dataDir: string,* localAgents: () => Promise<Array<{ id: string, cli: { path: string } | null, signedIn: boolean | null, account?: object | null, problem?: string, install: string | null, setupRequired: string | null }>>,+ * localAgent?: (id: string) => Promise<{ id: string, cli: { path: string } | null, signedIn: boolean | null, account?: object | null, problem?: string, install: string | null, setupRequired: string | null }>,* openSignIn: (id: string) => Promise<{ ok: boolean, error?: string }>,* usePaths?: (paths: Record<string, string>) => void,* pickProgram?: (id: string, words?: { title?: string, button?: string }) => Promise<string | null>,@@ -194,7 +198,9 @@ export async function probeModel({ format, baseUrl, key, model, fetch: fetchImpl* seal: (text: string) => Buffer, unseal: (data: Buffer) => string,* onChange: (list: any[]) => void,* fetch?: typeof fetch,+ * signInWait?: { ms: number, pollMs: number },* }} deps+ * `localAgent(id)`: one agent as `localAgents` has it, asked alone while its sign-in is waited for (`signInWait`).*/export function createRoster(deps) {const { dataDir } = deps;@@ -258,13 +264,23 @@ export function createRoster(deps) {return list();}+ /** The one agent signed in to, asked again: alone when it can be, not every agent every few seconds. */+ async function lookAgain(id) {+ if (!deps.localAgent) { await refresh(); return; }+ const one = await deps.localAgent(id).catch(() => null);+ if (!one) return;+ local = [...(local ?? []).filter((a) => a.id !== id), one];+ changed();+ }+async function waitForSignIn(id) {live.waiting[id] = true;changed();- const until = Date.now() + SIGN_IN_WAIT_MS;+ const wait = deps.signInWait ?? SIGN_IN_WAIT;+ const until = Date.now() + wait.ms;while (Date.now() < until && live.waiting[id]) {- await new Promise((done) => setTimeout(done, SIGN_IN_POLL_MS));- await refresh();+ await new Promise((done) => setTimeout(done, wait.pollMs));+ await lookAgain(id);if (local?.find((a) => a.id === id)?.signedIn !== false) break;}delete live.waiting[id];diff --git a/apps/desktop/src/agent-roster.test.mjs b/apps/desktop/src/agent-roster.test.mjsindex a676643..96d9ccb 100644--- a/apps/desktop/src/agent-roster.test.mjs+++ b/apps/desktop/src/agent-roster.test.mjs@@ -244,3 +244,33 @@ test('Codex is connected from the start, Claude Code once the person connects itwriteFileSync(join(dir, 'agents.json'), JSON.stringify({ disconnected: [] }));assert.deepEqual(readChoices(dir).disconnected, [], 'connected before: still connected');});++test('a sign-in in Terminal is waited for asking only that agent, until it is signed in or the wait is over', async () => {+ const dir = mkdtempSync(join(tmpdir(), 'of-roster-'));+ const cursor = (signedIn) => ({ id: 'cursor', cli: { path: '/bin/cursor-agent' }, signedIn, install: null, setupRequired: null });+ let signedIn = false;+ let all = 0;+ const asked = [];+ const r = roster(dir, undefined, {+ localAgents: async () => { all++; return [cursor(signedIn)]; },+ localAgent: async (id) => { asked.push(id); return cursor(signedIn); },+ signInWait: { ms: 2000, pollMs: 10 },+ });+ assert.deepEqual(await r.connect('cursor'), { ok: true });+ await new Promise((done) => setTimeout(done, 50));+ assert.equal(r.list().find((a) => a.id === 'cursor').status, 'waiting');+ const before = all;+ signedIn = true;+ await new Promise((done) => setTimeout(done, 50));+ assert.equal(r.list().find((a) => a.id === 'cursor').status, 'ready');+ assert.ok(asked.length > 1 && asked.every((id) => id === 'cursor'));+ assert.equal(all, before, 'the other agents are not asked while it waits');++ /* a sign-in never finished: asked about until the wait is over, then it needs its sign-in again */+ const late = roster(mkdtempSync(join(tmpdir(), 'of-roster-')), undefined, {+ localAgents: async () => [cursor(false)], localAgent: async () => cursor(false), signInWait: { ms: 40, pollMs: 10 },+ });+ await late.connect('cursor');+ await new Promise((done) => setTimeout(done, 120));+ assert.equal(late.list().find((a) => a.id === 'cursor').status, 'sign-in');+});diff --git a/apps/desktop/src/agents.mjs b/apps/desktop/src/agents.mjsindex eb0ff49..22e5536 100644--- a/apps/desktop/src/agents.mjs+++ b/apps/desktop/src/agents.mjs@@ -25,7 +25,7 @@* Reads no Electron module, so `node --test` can use it.*/import { execFile, spawn } from 'node:child_process';-import { existsSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';import { arch, homedir, release, tmpdir } from 'node:os';import { createRequire } from 'node:module';import { dirname, isAbsolute, join } from 'node:path';@@ -57,7 +57,7 @@ export const AGENTS = Object.freeze({env: (path) => ({ CLAUDE_CODE_EXECUTABLE: path }),auth: ['auth', 'status'],login: ['auth', 'login'],- /* of the shell only its PATH, proxies, config folder and locale, as 0.1.5 had it and ChatCut has it: a key or+ /* of the shell only its PATH, proxies, config folder and locale, as 0.1.5 had it: a key orgateway set there (ANTHROPIC_*) would take the place of the person's Claude subscription */fromShell: shellSubset,/* signed in to the person's Claude subscription, the way its adapter offers it (ACP terminal auth), in Terminal */@@ -75,7 +75,10 @@ export const AGENTS = Object.freeze({copilot: { label: 'GitHub Copilot', args: ['--acp', '--allow-all'], login: ['login'], approve: true },cursor: { label: 'Cursor', args: ['--force', 'acp'], auth: ['status'], login: ['login'], authenticate: 'cursor_login', approve: true },opencode: { label: 'OpenCode', args: ['acp'], login: ['auth', 'login'], approve: true },- codebuddy: { label: 'CodeBuddy', args: ['--acp', '--permission-mode', 'bypassPermissions'], login: [], approve: true },+ /* CodeBuddy is the China edition unless the person's shell says otherwise: the program itself defaults to the+ international site (www.codebuddy.ai) whichever site it was signed in on, out of reach from China */+ codebuddy: { label: 'CodeBuddy', args: ['--acp', '--permission-mode', 'bypassPermissions'], login: [], approve: true,+ defaults: { CODEBUDDY_INTERNET_ENVIRONMENT: 'internal' } },qwen: { label: 'Qwen Code', args: ['--acp', '--approval-mode', 'yolo'], login: [], approve: true },kimi: { label: 'Kimi', args: ['acp'], login: ['login'], approve: true },minimax: { label: 'MiniMax Code', args: ['acp'], login: ['login'], approve: true },@@ -83,6 +86,11 @@ export const AGENTS = Object.freeze({export const isAgentId = (id) => typeof id === 'string' && Object.hasOwn(AGENTS, id);+/** The variables an agent is started with (`defaults`) that the person's shell does not set itself. */+export function agentDefaults(id, shell = {}) {+ return Object.fromEntries(Object.entries(AGENTS[id]?.defaults ?? {}).filter(([key]) => !Object.hasOwn(shell, key)));+}+/** The app's own agent: Pi (pi-agent.mjs), on the person's own key (agent-roster.mjs). */export const HARNESS_AGENTS = Object.freeze(['byok']);export const isChatAgent = (id) => isAgentId(id) || HARNESS_AGENTS.includes(id);@@ -372,10 +380,25 @@ export function readAgentStatus(id, stdout, out) {return { signedIn: null, account: null };}-/** what a session opened only to ask found, for a while: the roster asks again every few seconds */+/**+ * What a session opened only to ask found, for a while: the roster asks again every few seconds. Signed in is kept+ * longer: each ask starts the agent (CodeBuddy leaves a stale file for each one it is stopped at once), and a sign-out+ * is learnt anyway, from a message refused for it (noteSignedOut) or when the person signs in from Settings.+ */const asked = new Map();const ASKED_FOR_MS = 15_000;-let probeDir = null;+const SIGNED_IN_FOR_MS = 10 * 60_000;++/**+ * The folder a session opened only to ask (signed in? its options?) runs in: an empty one of the app's, the same each+ * time. Not the home folder: an agent takes the folder it runs in for a project, keeping a record of it and reading+ * its instructions files.+ */+export function probeFolder() {+ const dir = join(tmpdir(), 'openfilm-agent-probe');+ mkdirSync(dir, { recursive: true });+ return dir;+}/*** Signed in, for an agent with no command that says: a session opened (in an empty folder of the app's) and closed.@@ -383,10 +406,9 @@ let probeDir = null;*/export function acpSignedIn(id) {const kept = asked.get(id);- if (kept && Date.now() - kept.at < ASKED_FOR_MS) return kept.answer;+ if (kept && Date.now() - kept.at < (kept.signedIn ? SIGNED_IN_FOR_MS : ASKED_FOR_MS)) return kept.answer;const answer = (async () => {- probeDir ??= mkdtempSync(join(tmpdir(), 'openfilm-agent-'));- const session = new AgentSession({ agent: id, cwd: probeDir });+ const session = new AgentSession({ agent: id, cwd: probeFolder() });try {await Promise.race([session.start(), new Promise((_, fail) => setTimeout(() => fail(new Error('timed out')), 30_000))]);return true;@@ -396,7 +418,9 @@ export function acpSignedIn(id) {session.close();}})();- asked.set(id, { at: Date.now(), answer });+ const entry = { at: Date.now(), answer, signedIn: false };+ asked.set(id, entry);+ void answer.then((yes) => { entry.signedIn = yes === true; });return answer;}@@ -410,9 +434,12 @@ function noteSignedOut(id) {const shq = (s) => `'${String(s).replace(/'/g, `'\\''`)}'`;-/** The AppleScript that has Terminal run one command in a new window. */-export function signInScript(cliPath, args) {- const command = [cliPath, ...args].map(shq).join(' ');+/**+ * The AppleScript that has Terminal run one command in a new window, in `cwd` when given (SIGN_IN_DIR: not the home+ * folder a new window opens in).+ */+export function signInScript(cliPath, args, { cwd } = {}) {+ const command = `${cwd ? `cd ${shq(cwd)} && ` : ''}${[cliPath, ...args].map(shq).join(' ')}`;return `tell application "Terminal"\nactivate\ndo script "${command.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"\nend tell`;}@@ -461,6 +488,13 @@ export async function agentSignInMethods(id) {}}+/**+ * Where a sign-in in Terminal runs: an empty folder of the app's own. A program whose sign-in is the program itself+ * (CodeBuddy, Qwen Code) first asks whether to trust the folder it is in, and in the home folder a new Terminal window+ * opens in, warns that it may hold sensitive files; trusted once, this folder is not asked about again.+ */+const SIGN_IN_DIR = () => join(tmpdir(), 'openfilm-sign-in');+/*** Sign in: Terminal runs the program's own sign-in, which opens the maker's own page. The app touches nothing. One* signed in the way its adapter offers (`acpSignIn`, that way's id) runs the adapter with that way's arguments, as ACP@@ -479,27 +513,34 @@ export async function openAgentSignIn(id) {const launch = adapterLaunch(id, cli.path);how = { cmd: launch.cmd, args: [...launch.args, ...way.args], env: { ...launch.env, ...way.env } };}+ /* signed in as it will be started (agentDefaults: CodeBuddy's China edition) */+ const defaults = agentDefaults(id, agentShell(id, await loginShellVariables()));+ if (!how && Object.keys(defaults).length && process.platform !== 'win32') how = { cmd: cli.path, args: spec.login, env: defaults };if (process.platform === 'win32') {- /* a PowerShell window of its own running a script, as ChatCut does: no command line for cmd.exe to unquote (a path+ /* a PowerShell window of its own running a script: no command line for cmd.exe to unquote (a pathwith a space in it), and left open so its sign-in can be read and answered (it runs a shim itself) */how ??= /\.(?:cmd|bat)$/i.test(cli.path) ? { cmd: cli.path, args: spec.login, env: {} } : starting(cli.path, spec.login);+ how = { ...how, env: { ...defaults, ...how.env } };try {- const dir = join(tmpdir(), 'openfilm-sign-in');+ const dir = SIGN_IN_DIR();mkdirSync(dir, { recursive: true });const file = join(dir, `${id}.ps1`);writeFileSync(file, powerShellScript(`${spec.label} sign-in`, how.cmd, how.args), 'utf8');const powershell = join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'WindowsPowerShell', 'v1.0', 'powershell.exe');const child = spawn(powershell, ['-NoLogo', '-NoExit', '-ExecutionPolicy', 'Bypass', '-File', file], {- detached: true, stdio: 'ignore', windowsHide: false, env: childEnvironment({ shell: agentShell(id, await loginShellVariables()), extra: how.env }),+ cwd: dir, detached: true, stdio: 'ignore', windowsHide: false, env: childEnvironment({ shell: agentShell(id, await loginShellVariables()), extra: how.env }),});await new Promise((done, fail) => { child.once('spawn', done); child.once('error', fail); });child.unref();return { ok: true };} catch (e) { return { ok: false, error: e instanceof Error ? e.message : String(e) }; }}+ const cwd = SIGN_IN_DIR();+ try { mkdirSync(cwd, { recursive: true }); } catch { /* signed in from the home folder, as before */ }+ const where = existsSync(cwd) ? { cwd } : {};const script = how- ? signInScript('/usr/bin/env', [...Object.entries(how.env).map(([k, v]) => `${k}=${v}`), how.cmd, ...how.args])- : signInScript(cli.path, spec.login);+ ? signInScript('/usr/bin/env', [...Object.entries(how.env).map(([k, v]) => `${k}=${v}`), how.cmd, ...how.args], where)+ : signInScript(cli.path, spec.login, where);const r = await run('/usr/bin/osascript', ['-e', script], 15_000);return r.ok ? { ok: true } : { ok: false, error: r.out.trim() || 'Terminal did not open.' };}@@ -520,20 +561,28 @@ export async function listAgents() {await Promise.race([slow, new Promise((done) => setTimeout(done, 3000).unref?.())]);}}- return Promise.all(Object.entries(AGENTS).map(async ([id, spec]) => {- const cli = resolveAgentCli(id, { pathDirs });- const { install } = detectAgentInstallation(id);- const claudeApp = id === 'claude' && !cli && ['/Applications', join(homedir(), 'Applications')].some((dir) => existsSync(join(dir, 'Claude.app')));- return {- id,- label: spec.label,- cli: cli ? { path: cli.path, source: cli.source } : null,- chosen: chosenPaths[id] ?? null,- ...(cli ? await agentStatus(id, cli.path) : { signedIn: null, account: null }),- install,- setupRequired: claudeApp ? 'code-tab' : null,- };- }));+ return Promise.all(Object.keys(AGENTS).map((id) => agentOnComputer(id, pathDirs)));+}++/** One agent as listAgents has it, asked alone: while the person signs in to it, only it is asked again. */+export async function localAgent(id) {+ if (!isAgentId(id)) throw new Error(`No agent ${id}`);+ return agentOnComputer(id, (await loginShellEnvironment({ maxAgeMs: 10_000 })).PATH.split(PATH_SEP));+}++async function agentOnComputer(id, pathDirs) {+ const cli = resolveAgentCli(id, { pathDirs });+ const { install } = detectAgentInstallation(id);+ const claudeApp = id === 'claude' && !cli && ['/Applications', join(homedir(), 'Applications')].some((dir) => existsSync(join(dir, 'Claude.app')));+ return {+ id,+ label: AGENTS[id].label,+ cli: cli ? { path: cli.path, source: cli.source } : null,+ chosen: chosenPaths[id] ?? null,+ ...(cli ? await agentStatus(id, cli.path) : { signedIn: null, account: null }),+ install,+ setupRequired: claudeApp ? 'code-tab' : null,+ };}/** The adapter's command line (its package's `bin`), run with Electron's own Node. */@@ -638,6 +687,25 @@ export const CLIENT_CAPABILITIES = {const CLIENT_INFO = { name: 'openfilm-desktop', title: 'OpenFilm', version: '0.1.0' };+/** How long an agent may wait on its model with nothing coming before the turn is stopped. */+const MODEL_STALL_MS = 5 * 60_000;++/** Where an agent says it is in its turn (CodeBuddy's `codebuddy.ai/agentPhase`: model_requesting, retrying…), or null. */+export function agentPhase(update) {+ const meta = update?._meta;+ if (!meta || typeof meta !== 'object') return null;+ const phase = Object.entries(meta).find(([k]) => /(?:^|[/.])agentPhase$/.test(k))?.[1]?.phase;+ return typeof phase === 'string' ? phase : null;+}++function stallError(label, ms) {+ const minutes = Math.max(1, Math.round(ms / 60_000));+ return Object.assign(new Error(`${label} heard nothing back from its model for ${minutes} minute${minutes === 1 ? '' : 's'}: its connection may be blocked. The turn was stopped; send your message again to retry.`), { code: 'agent-stalled' });+}++/** What an agent sends while it answers or works: a turn with none of these said nothing. */+const SPOKE = new Set(['agent_message_chunk', 'agent_thought_chunk', 'tool_call', 'tool_call_update', 'plan']);+/** ACP's auth_required: the agent wants its own sign-in first. */const AUTH_REQUIRED = -32000;@@ -661,10 +729,17 @@ export function codexTooOld(agent, path, e, versionOf = codexVersion) {const INTERNAL_ERROR = -32603;/**- * A session refused for the agent's sign-in, said so (`code: 'sign-in'`); any other error with its reason (errorCause).+ * A session refused for the agent's sign-in, said so (`code: 'sign-in'`). One refused in ACP's sign-in terms for the+ * person's plan instead (Kimi 2.2: "Authentication required: 403 Your current subscription does not have access to Kimi+ * Code…") is the agent's own words (`code: 'agent-error'`): signing in again would not help, and the agent is not taken+ * for signed out. Any other error with its reason (errorCause).*/export function signInError(label, e) {- if (e?.code === AUTH_REQUIRED) return Object.assign(new Error(`${label} is not signed in. Sign in under Settings → Agents.`), { code: 'sign-in' });+ if (e?.code === AUTH_REQUIRED) {+ const plan = planProblem(e?.message);+ if (plan) return Object.assign(new Error(`${label}: ${plan}`), { code: 'agent-error' });+ return Object.assign(new Error(`${label} is not signed in. Sign in under Settings → Agents.`), { code: 'sign-in' });+ }return errorCause(e);}@@ -680,6 +755,26 @@ export function errorCause(e) {return why.trim() ? Object.assign(new Error(why.trim(), { cause: e }), { code: e.code }) : e;}+/** What an agent's sign-in refusal says when it is about the person's plan, not their sign-in, or null. */+export function planProblem(message) {+ const text = String(message ?? '').replace(/^\s*Authentication required[:.]?\s*/i, '').trim();+ return /\b(?:403|subscriptions?|plans?|upgrade|quota|billing|credits?|balance)\b/i.test(text) ? text.slice(0, 1000) : null;+}++/**+ * Why a turn ended, as the agent says it beside the turn's result (`_meta`, under a key ending in `errorMessage`:+ * CodeBuddy's `codebuddy.ai/errorMessage`, itself JSON with a `message`), or null.+ */+export function turnError(result) {+ const meta = result?._meta;+ if (!meta || typeof meta !== 'object') return null;+ const raw = Object.entries(meta).find(([k, v]) => /(?:^|[/.])errorMessage$/.test(k) && typeof v === 'string' && v.trim())?.[1];+ if (!raw) return null;+ let text = raw.trim();+ try { const said = JSON.parse(text); if (typeof said?.message === 'string' && said.message.trim()) text = said.message.trim(); } catch { /* plain words */ }+ return text.slice(0, 1000);+}+/** The answer that lets it go ahead (for good, where it offers that), or null when none does. */export function allowOption(params) {const options = params?.options ?? [];@@ -700,6 +795,19 @@ export function legacyOptions(session) {return out;}+/**+ * Config options with each choice once: an agent may list the same value twice (GitHub Copilot's model list has+ * "Auto" twice), which the menu would show twice, both ticked. The first of each is kept; anything else as it was.+ */+export function distinctOptions(configOptions) {+ if (!Array.isArray(configOptions)) return configOptions;+ return configOptions.map((o) => {+ if (!Array.isArray(o?.options)) return o;+ const seen = new Set();+ return { ...o, options: o.options.filter((c) => !c || !('value' in c) || (!seen.has(c.value) && seen.add(c.value))) };+ });+}+/*** One conversation: one ACP session on one adapter process.*@@ -717,11 +825,12 @@ export class AgentSession {* onUpdate?: (update: any) => void, onPermission?: (params: any) => Promise<string | null>,* onQuestion?: (ask: { message: string, toolCallId: string | null, questions: any[] }) => Promise<Record<string, { label?: string, text?: string }> | null>,* onExit?: (info: { code: number | null, stderr: string }) => void,- * onSend?: (sent: { prompt: any[], _meta?: any }) => void }} opts+ * onSend?: (sent: { prompt: any[], _meta?: any }) => void, stallMs?: number }} opts* `onSend` hears each message as it goes to the agent, whole (the app's words before the first one's, for an agent* told them there); `opened`, once started, says what it was started and opened with.* `skills`: the session has its maker's skills and MCP servers, OpenFilm's skills, and of the person's own only those* let in (`allowed`, `mcpAllowed`), each agent told by its own switch (agent-skills.mjs); `opened.skills` says how.+ * `stallMs`: how long the agent may wait on its model with nothing coming (MODEL_STALL_MS) before the turn is stopped.* `logDir` (Developer mode): an agent whose own record lacks what its model got is started with its own logging* switch, writing under this folder (agent-logs.mjs); `opened.log` says where.*/@@ -757,6 +866,11 @@ export class AgentSession {const cli = harness ? null : resolveAgentCli(this.opts.agent, { pathDirs: shell.PATH.split(PATH_SEP) });if (!harness && !cli) throw Object.assign(new Error(`${this.spec.label} is not installed on this computer.`), { code: 'not-installed' });this.cli = cli;+ /* one whose ACP sign-in takes up its own (Cursor's `authenticate`) opens the maker's sign-in page in the browser and+ waits there when it is signed out: its own status says so first, and the person signs in from Settings */+ if (cli && this.spec.authenticate && this.spec.auth && (await agentStatus(this.opts.agent, cli.path)).signedIn === false) {+ throw signInError(this.spec.label, { code: AUTH_REQUIRED });+ }const node = nodeRuntime();const path = [this.opts.binDir, shell.PATH, this.opts.fallbackDir].filter(Boolean).join(PATH_SEP);const instructions = INSTRUCTIONS;@@ -776,7 +890,7 @@ export class AgentSession {? await logSwitches(this.opts.agent, { base: this.opts.logDir, shell, cwd: this.opts.cwd }).catch(() => null) : null;/* an agent that speaks ACP itself: its own program, started as the registry starts it */const native = cli && !this.spec.adapter ? starting(cli.path, [...this.spec.args, ...(this.logging?.args ?? []), ...(skills?.args ?? [])]) : null;- const extra = { ...this.opts.env, ...(native ? native.env : node.env), ...(cli && this.spec.env ? this.spec.env(cli.path) : {}), ...own, ...skills?.env, ...this.logging?.env };+ const extra = { ...agentDefaults(this.opts.agent, shell), ...this.opts.env, ...(native ? native.env : node.env), ...(cli && this.spec.env ? this.spec.env(cli.path) : {}), ...own, ...skills?.env, ...this.logging?.env };/* OpenCode's inline configuration carries both its skills and, in Developer mode, its logging */if (skills?.env?.OPENCODE_CONFIG_CONTENT && this.logging?.env?.OPENCODE_CONFIG_CONTENT) {extra.OPENCODE_CONFIG_CONTENT = JSON.stringify(mergeConfig(JSON.parse(skills.env.OPENCODE_CONFIG_CONTENT), JSON.parse(this.logging.env.OPENCODE_CONFIG_CONTENT)));@@ -795,7 +909,8 @@ export class AgentSession {? spawn(native.cmd, native.args, { ...native.options, cwd: this.opts.cwd, env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true }): spawn(node.command, [...(node.env.ELECTRON_RUN_AS_NODE ? [AS_NODE] : []), script], { cwd: this.opts.cwd, env, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });this.child.stderr.on('data', (d) => { this.stderr = (this.stderr + String(d)).slice(-16_000); });- this.child.once('exit', (code) => this.opts.onExit?.({ code, stderr: this.stderr }));+ LIVE.add(this);+ this.child.once('exit', (code) => { LIVE.delete(this); this.opts.onExit?.({ code, stderr: this.stderr }); });this.child.once('error', () => {});const stream = acp.ndJsonStream(Writable.toWeb(this.child.stdin), Readable.toWeb(this.child.stdout));@@ -812,7 +927,12 @@ export class AgentSession {return answers ? { action: 'accept', content: formContent(questions, answers) } : { action: 'decline' };}).onNotification(acp.methods.client.session.update, (ctx) => {- if (!this.replaying) this.opts.onUpdate?.(ctx.params.update);+ const update = ctx.params.update;+ if (SPOKE.has(update?.sessionUpdate)) this.spoke = true;+ this.heard = Date.now();+ const phase = agentPhase(update);+ if (phase) this.phase = phase;+ if (!this.replaying) this.opts.onUpdate?.(update?.configOptions ? { ...update, configOptions: distinctOptions(update.configOptions) } : update);}).connect(stream);@@ -855,7 +975,7 @@ export class AgentSession {agentInfo: init.agentInfo ?? null,models: session.models ?? null,modes: session.modes ?? null,- configOptions: session.configOptions ?? (this.legacy ? legacyOptions(session) : null),+ configOptions: distinctOptions(session.configOptions ?? (this.legacy ? legacyOptions(session) : null)),/* what a prompt may carry besides text (pictures, for one): the agent says so as it shakes hands */promptCapabilities: caps.promptCapabilities ?? null,/* a message sent while it works joins the turn it is in (steer), as in its own chat */@@ -894,7 +1014,24 @@ export class AgentSession {this.instructions = null;/* the message exactly as the agent gets it, for the turn log */this.opts.onSend?.({ prompt: [...told, ...blocks], ...meta });- const r = await this.conn.agent.request(acp.methods.agent.session.prompt, { sessionId: this.sessionId, prompt: [...told, ...blocks], ...meta })+ this.spoke = false;+ this.heard = Date.now();+ this.phase = null;+ /* a model asked and never answering (CodeBuddy, its connection hung): the turn is stopped for the person */+ let stalled = false;+ const stallMs = this.opts.stallMs ?? MODEL_STALL_MS;+ let giveUp = () => {};+ const gaveUp = new Promise((_, fail) => { giveUp = fail; });+ gaveUp.catch(() => {});+ const watch = setInterval(() => {+ if (stalled || this.phase !== 'model_requesting' || Date.now() - this.heard < stallMs) return;+ stalled = true;+ void this.cancel();+ /* one that does not stop when asked is left: the chat is not kept waiting on it */+ setTimeout(() => giveUp(stallError(this.spec.label, stallMs)), 10_000).unref?.();+ }, Math.min(15_000, Math.max(50, stallMs / 4)));+ watch.unref?.();+ const asking = this.conn.agent.request(acp.methods.agent.session.prompt, { sessionId: this.sessionId, prompt: [...told, ...blocks], ...meta }).catch((e) => {/* the app's own agent: a service with no balance left is said the same for every service, with its page */const own = this.opts.harness?.models?.find((m) => m.id === this.modelNow) ?? this.opts.harness?.models?.[0];@@ -905,6 +1042,16 @@ export class AgentSession {if (said.code === 'sign-in') noteSignedOut(this.opts.agent);throw said;});+ const r = await Promise.race([asking, gaveUp]).finally(() => clearInterval(watch));+ if (stalled && r.stopReason === 'cancelled') throw stallError(this.spec.label, stallMs);+ /* a turn the agent gave up on with its reason beside it, not in its reply (CodeBuddy: a network error): said as+ the turn's error, or the chat would show an empty reply */+ const why = r.stopReason === 'refusal' ? turnError(r) : null;+ if (why) throw Object.assign(new Error(why), { code: 'agent-error' });+ /* a turn ended with nothing said or done (Kimi 0.27 so ends one its plan does not cover): said, not an empty reply */+ if (r.stopReason === 'end_turn' && !this.spoke && isAgentId(this.opts.agent)) {+ throw Object.assign(new Error(`${this.spec.label} ended its turn without replying. If it keeps doing so, try ${this.spec.label} in its own terminal: it may need an update, or a plan that covers it.`), { code: 'empty-turn' });+ }return r.stopReason;}@@ -930,7 +1077,7 @@ export class AgentSession {if (this.legacy && configId === 'model') return this.conn.agent.request('session/set_model', { sessionId: this.sessionId, modelId: value });const r = await this.conn.agent.request(acp.methods.agent.session.setConfigOption, { sessionId: this.sessionId, configId, value });this.noteModel(r?.configOptions);- return r;+ return r?.configOptions ? { ...r, configOptions: distinctOptions(r.configOptions) } : r;}/** The model the session is on (its `model` option's value): the app's own agent names the service a failure was on by it. */@@ -944,8 +1091,22 @@ export class AgentSession {}close() {+ LIVE.delete(this);try { this.conn?.close(); } catch { /* gone already */ }if (this.child && this.child.exitCode === null) this.child.kill('SIGTERM');this.logging?.close();}}++/** Every agent process this app started and has not closed: a chat's, or one opened only to ask. */+const LIVE = new Set();++/**+ * Close every agent process, a session opened only to ask included (the chat's own are closed by their owner): the+ * app is quitting, and one left would outlive it.+ */+export function closeEverySession() {+ for (const session of [...LIVE]) session.close();+}+/* and as the process ends without quitting the usual way: none outlives it */+process.once('exit', closeEverySession);diff --git a/apps/desktop/src/agents.test.mjs b/apps/desktop/src/agents.test.mjsindex 18d906e..319eb11 100644--- a/apps/desktop/src/agents.test.mjs+++ b/apps/desktop/src/agents.test.mjs@@ -1,6 +1,6 @@import { test } from 'node:test';import assert from 'node:assert/strict';-import { CLIENT_CAPABILITIES, CODEX_UTF8_CMD, agentShell, allowOption, codexDeveloperInstructions, codexLaunchEnv, errorCause, legacyOptions, powerShellScript, readAgentStatus, signInError, codexTooOld } from './agents.mjs';+import { AgentSession, CLIENT_CAPABILITIES, agentDefaults, closeEverySession, planProblem, probeFolder, CODEX_UTF8_CMD, agentShell, allowOption, codexDeveloperInstructions, codexLaunchEnv, distinctOptions, errorCause, legacyOptions, powerShellScript, readAgentStatus, setChosenPaths, signInScript, turnError, signInError, codexTooOld } from './agents.mjs';test('an agent that asks: yes for good where it offers that, else yes this once; nothing to say yes with is null', () => {const options = [@@ -24,6 +24,17 @@ test("the protocol's older model and mode lists read as the config options the cassert.deepEqual(legacyOptions({}), []);});+test('a choice an agent lists twice shows once in the menu', () => {+ /* GitHub Copilot 1.0.98 lists its model "auto" twice */+ const [model, mode] = distinctOptions([+ { id: 'model', currentValue: 'auto', options: [{ value: 'auto', name: 'Auto' }, { value: 'auto', name: 'Auto', description: 'Auto' }, { value: 'gpt', name: 'GPT' }] },+ { id: 'mode', currentValue: 'agent', options: [{ value: 'agent', name: 'Agent' }, { value: 'plan', name: 'Plan' }] },+ ]);+ assert.deepEqual(model.options, [{ value: 'auto', name: 'Auto' }, { value: 'gpt', name: 'GPT' }]);+ assert.deepEqual(mode.options.map((o) => o.value), ['agent', 'plan']);+ assert.equal(distinctOptions(null), null);+});+test('whose sign-in it is, as each program says it, never a key', () => {const claude = JSON.stringify({ loggedIn: true, authMethod: 'claude.ai', email: '[email protected]', orgName: 'Studio', subscriptionType: 'max' });assert.deepEqual(readAgentStatus('claude', claude, claude), { signedIn: true, account: { method: 'claude.ai', email: '[email protected]', org: 'Studio', plan: 'max' } });@@ -110,6 +121,12 @@ test('the chat says it signs in in Terminal, so Claude Code offers its subscriptassert.equal(zClientCapabilities.parse(CLIENT_CAPABILITIES).auth?.terminal, true);});+test("a sign-in in Terminal runs in a folder of the app's own, not the home folder a program warns about", () => {+ const script = signInScript('/opt/homebrew/bin/codebuddy', [], { cwd: "/tmp/it's here" });+ assert.match(script, /do script "cd '\/tmp\/it'\\\\''s here' && '\/opt\/homebrew\/bin\/codebuddy'"/);+ assert.match(signInScript('/bin/copilot', ['login']), /do script "'\/bin\/copilot' 'login'"/);+});+test('a Windows sign-in is a PowerShell script: each path whole however it is spelled, read as UTF-8', () => {const script = powerShellScript('Claude Code sign-in', 'C:\\Program Files\\OpenFilm\\OpenFilm.exe',['C:\\Program Files\\OpenFilm\\app.asar\\src\\as-node.mjs', 'D:\\用户\\it\'s\\index.js', '--cli', 'auth', 'login', '--claudeai']);@@ -141,6 +158,153 @@ test('on Windows, Codex is started through a script that turns the console to UTassert.deepEqual(codexLaunchEnv(exe, { win: true, dir: join(blocked, 'launch') }), { CODEX_PATH: exe });});+test('a signed-out Cursor is said to need its sign-in at once, without the session that would open its sign-in page', async () => {+ const { mkdtempSync, writeFileSync } = await import('node:fs');+ const { tmpdir } = await import('node:os');+ const { join } = await import('node:path');+ const dir = mkdtempSync(join(tmpdir(), 'of-cursor-'));+ /* says it is signed out, and never answers over ACP (Cursor waits on its sign-in page there) */+ const program = join(dir, 'cursor-agent.mjs');+ writeFileSync(program, "if (process.argv.includes('status')) console.log('Not logged in'); else setInterval(() => {}, 1000);\n");+ setChosenPaths({ cursor: program });+ const session = new AgentSession({ agent: 'cursor', cwd: dir });+ try {+ const failed = await Promise.race([+ session.start().then(() => null, (e) => e),+ new Promise((done) => setTimeout(() => done(new Error('still waiting')), 15_000).unref()),+ ]);+ assert.equal(failed?.code, 'sign-in', failed?.message);+ } finally {+ session.close();+ setChosenPaths({});+ }+});++test("a turn an agent gave up on is said in the agent's own words, not left as an empty reply", () => {+ /* CodeBuddy 2.168, its site out of reach: stopReason "refusal", the reason beside it */+ const message = 'Network error: 502 安全连接建立失败 (target: https://www.codebuddy.ai)';+ assert.equal(turnError({ stopReason: 'refusal', _meta: { 'codebuddy.ai/requestId': 'r1', 'codebuddy.ai/errorMessage': JSON.stringify({ code: -32001, message }) } }), message);+ assert.equal(turnError({ stopReason: 'refusal', _meta: { errorMessage: 'Rate limited' } }), 'Rate limited');+ assert.equal(turnError({ stopReason: 'refusal' }), null);+ assert.equal(turnError({ stopReason: 'refusal', _meta: { 'codebuddy.ai/requestId': 'r1' } }), null);+});++test("CodeBuddy is started as its China edition, unless the person's shell says which edition themselves", () => {+ assert.deepEqual(agentDefaults('codebuddy', { PATH: '/bin' }), { CODEBUDDY_INTERNET_ENVIRONMENT: 'internal' });+ assert.deepEqual(agentDefaults('codebuddy', { CODEBUDDY_INTERNET_ENVIRONMENT: 'ioa' }), {});+ assert.deepEqual(agentDefaults('cursor', {}), {});+});++test('a refusal about the plan is the agent\'s own words; one about the sign-in is a sign-in', () => {+ /* Kimi 2.2 on an account without Kimi Code */+ assert.equal(planProblem('Authentication required: 403 Your current subscription does not have access to Kimi Code right now. Upgrade your plan to keep coding with Kimi Code: https://www.kimi.com/code/#pricing'),+ '403 Your current subscription does not have access to Kimi Code right now. Upgrade your plan to keep coding with Kimi Code: https://www.kimi.com/code/#pricing');+ assert.equal(planProblem('Authentication required: Use Qwen Code CLI to authenticate first.'), null);+ assert.equal(planProblem('Authentication required'), null);+});++test('a turn that ends with nothing said is said so; a refusal for the plan does not sign the agent out', async () => {+ const { mkdtempSync, writeFileSync } = await import('node:fs');+ const { tmpdir } = await import('node:os');+ const { join } = await import('node:path');+ const dir = mkdtempSync(join(tmpdir(), 'of-kimi-'));+ /* a Kimi that answers its first message with nothing and its second with Kimi 2.2's refusal for the plan */+ const program = join(dir, 'kimi.mjs');+ writeFileSync(program, `let turns = 0;+let buf = '';+const send = (o) => process.stdout.write(JSON.stringify(o) + '\\n');+process.stdin.on('data', (d) => {+ buf += d;+ let i;+ while ((i = buf.indexOf('\\n')) >= 0) {+ const m = JSON.parse(buf.slice(0, i)); buf = buf.slice(i + 1);+ if (m.method === 'initialize') send({ jsonrpc: '2.0', id: m.id, result: { protocolVersion: 1, agentCapabilities: {}, authMethods: [] } });+ else if (m.method === 'session/new') send({ jsonrpc: '2.0', id: m.id, result: { sessionId: 's1' } });+ else if (m.method === 'session/prompt') send(++turns === 1 ? { jsonrpc: '2.0', id: m.id, result: { stopReason: 'end_turn' } }+ : { jsonrpc: '2.0', id: m.id, error: { code: -32000, message: 'Authentication required: 403 Your current subscription does not have access to Kimi Code right now.' } });+ }+});+`);+ setChosenPaths({ kimi: program });+ const session = new AgentSession({ agent: 'kimi', cwd: dir });+ try {+ await session.start();+ const empty = await session.prompt([{ type: 'text', text: 'hi' }]).then(() => null, (e) => e);+ assert.equal(empty?.code, 'empty-turn');+ const plan = await session.prompt([{ type: 'text', text: 'hi' }]).then(() => null, (e) => e);+ assert.equal(plan?.code, 'agent-error');+ assert.match(plan.message, /^Kimi: 403 Your current subscription/);+ } finally {+ session.close();+ setChosenPaths({});+ }+});++/** A fake agent over ACP (newline-delimited JSON-RPC), as a script: `onPrompt(m, send)` answers each message. */+async function fakeAcpAgent(name, onPrompt) {+ const { mkdtempSync, writeFileSync } = await import('node:fs');+ const { tmpdir } = await import('node:os');+ const { join } = await import('node:path');+ const dir = mkdtempSync(join(tmpdir(), 'of-fake-'));+ const program = join(dir, `${name}.mjs`);+ writeFileSync(program, `let buf = '';+let asked = null;+const send = (o) => process.stdout.write(JSON.stringify(o) + '\\n');+process.stdin.on('data', (d) => {+ buf += d;+ let i;+ while ((i = buf.indexOf('\\n')) >= 0) {+ const m = JSON.parse(buf.slice(0, i)); buf = buf.slice(i + 1);+ if (m.method === 'initialize') send({ jsonrpc: '2.0', id: m.id, result: { protocolVersion: 1, agentCapabilities: {}, authMethods: [] } });+ else if (m.method === 'session/new') send({ jsonrpc: '2.0', id: m.id, result: { sessionId: 's1' } });+ else (${onPrompt})(m, send);+ }+});+setInterval(() => {}, 1000);+`);+ return { dir, program };+}++test('a turn whose agent waits on its model with nothing coming is stopped, and says why', async () => {+ /* CodeBuddy with its connection hung: model_requesting, then nothing until it is cancelled */+ const { dir, program } = await fakeAcpAgent('codebuddy', (m, send) => {+ if (m.method === 'session/prompt') {+ globalThis.asked = m.id;+ send({ jsonrpc: '2.0', method: 'session/update', params: { sessionId: 's1', update: { sessionUpdate: 'session_info_update', _meta: { 'codebuddy.ai/agentPhase': { phase: 'model_requesting' } } } } });+ } else if (m.method === 'session/cancel') {+ send({ jsonrpc: '2.0', id: globalThis.asked, result: { stopReason: 'cancelled' } });+ }+ });+ setChosenPaths({ codebuddy: program });+ const session = new AgentSession({ agent: 'codebuddy', cwd: dir, stallMs: 200 });+ try {+ await session.start();+ const failed = await session.prompt([{ type: 'text', text: 'hi' }]).then(() => null, (e) => e);+ assert.equal(failed?.code, 'agent-stalled');+ assert.match(failed.message, /^CodeBuddy heard nothing back from its model/);+ } finally {+ session.close();+ setChosenPaths({});+ }+});++test('quitting closes every agent process, one opened only to ask included; asking runs in one empty folder of the app', async () => {+ assert.equal(probeFolder(), probeFolder());+ const { dir, program } = await fakeAcpAgent('opencode', () => {});+ setChosenPaths({ opencode: program });+ const session = new AgentSession({ agent: 'opencode', cwd: dir });+ try {+ await session.start();+ const gone = new Promise((done) => session.child.once('exit', done));+ closeEverySession();+ await gone;+ assert.notEqual(session.child.exitCode ?? session.child.signalCode, null);+ } finally {+ session.close();+ setChosenPaths({});+ }+});+test('a Codex older than the ones tried, that did not start, is said to need an update; a later one, or a sign-in, as it was', () => {const failed = new Error('Pending response rejected since connection got disposed');const old = codexTooOld('codex', '/usr/local/bin/codex', failed, () => '0.104.0');diff --git a/apps/desktop/src/app-report.mjs b/apps/desktop/src/app-report.mjsnew file mode 100644index 0000000..9efc9dd--- /dev/null+++ b/apps/desktop/src/app-report.mjs@@ -0,0 +1,69 @@+/**+ * The app's part of the diagnostic report Studio's Settings → Developer copies (the rest is `openfilm doctor` and the+ * page's browser): the app, where its PATH came from, and each of the person's own agents as the roster has it, with+ * its program and the version that program says. Paths in the home folder read ~; no account, key or token.+ *+ * Reads no Electron module, so `node --test` can use it.+ */+import { homedir } from 'node:os';++/** A path as the report shows it: the home folder as ~. */+export function tidy(path, home = homedir()) {+ if (!path || !home || home.length < 2) return path;+ const starts = process.platform === 'win32' ? path.toLowerCase().startsWith(home.toLowerCase()) : path.startsWith(home);+ return starts ? `~${path.slice(home.length)}` : path;+}++/**+ * One agent's line: ✓ ready, ✗ something to fix (signed out, an error, a program that does not start), – neither (not+ * installed, disconnected here).+ * @param {{ id: string, name: string, status: string, path?: string | null, chosen?: string | null, error?: string, shown?: boolean }} agent+ * @param {{ ok: boolean, version?: string, error?: string } | null} version what `--version` said; null when not asked+ */+export function agentLine(agent, version, home = homedir()) {+ const bad = agent.status === 'sign-in' || Boolean(agent.error) || (version && !version.ok);+ const mark = agent.status === 'ready' && !bad ? '✓' : bad ? '✗' : '–';+ const where = agent.path ? ` · ${tidy(agent.path, home)}${agent.chosen ? ' (chosen)' : ''}` : '';+ const said = version ? ` · ${version.ok ? version.version || '(no version)' : `--version failed: ${oneLine(version.error)}`}` : '';+ const error = agent.error ? ` · ${oneLine(agent.error)}` : '';+ return `${mark} ${agent.name.padEnd(15)}${agent.status}${said}${where}${error}`;+}++const oneLine = (text = '') => {+ const line = String(text).replace(/\s+/g, ' ').trim();+ return line.length > 200 ? `${line.slice(0, 199)}…` : line;+};++/**+ * The report's text.+ * @param {{ version: string, flavor: string, packaged: boolean, channel?: string | null, electron: string, pathSource: string | null,+ * agents: Array<Parameters<typeof agentLine>[0]>, versions: Record<string, Parameters<typeof agentLine>[1]>, home?: string }} facts+ */+export function appReport({ version, flavor, packaged, channel = null, electron, pathSource, agents, versions, home = homedir() }) {+ const own = agents.filter((a) => a.id !== 'byok');+ const byok = agents.find((a) => a.id === 'byok');+ return [+ 'OpenFilm desktop app',+ '',+ ` App ${version} (${flavor}${packaged ? '' : ', from source'}${channel ? `, ${channel} updates` : ''}; Electron ${electron})`,+ ` PATH from ${pathSource ?? 'not read yet'}`,+ '',+ 'Agents',+ '',+ ...own.map((a) => ` ${agentLine(a, versions[a.id] ?? null, home)}`),+ ...(byok ? [` ${agentLine({ ...byok, path: null }, null, home)}`] : []),+ ].join('\n');+}++/**+ * The report, gathered now: the roster's agents, and `--version` of each one found (at once, each in its own time).+ * @param {{ list: () => Promise<any[]>, check: (id: string, path: string) => Promise<{ ok: boolean, version?: string, error?: string }> }} roster+ * @param {Omit<Parameters<typeof appReport>[0], 'agents' | 'versions'>} app+ */+export async function gatherAppReport(roster, app) {+ const agents = await roster.list();+ const found = agents.filter((a) => a.id !== 'byok' && a.path);+ const answers = await Promise.all(found.map((a) => roster.check(a.id, a.path).catch((e) => ({ ok: false, error: e?.message ?? String(e) }))));+ const versions = Object.fromEntries(found.map((a, i) => [a.id, answers[i]]));+ return appReport({ ...app, agents, versions });+}diff --git a/apps/desktop/src/app-report.test.mjs b/apps/desktop/src/app-report.test.mjsnew file mode 100644index 0000000..e9b0bed--- /dev/null+++ b/apps/desktop/src/app-report.test.mjs@@ -0,0 +1,48 @@+import assert from 'node:assert/strict';+import { test } from 'node:test';+import { agentLine, appReport, gatherAppReport } from './app-report.mjs';++const HOME = '/Volumes/Home/someone';++test('an agent\'s line: its state, version and program, paths in home as ~', () => {+ assert.equal(agentLine({ id: 'codex', name: 'Codex', status: 'ready', path: `${HOME}/.npm-global/bin/codex` }, { ok: true, version: 'codex-cli 0.163.0' }, HOME),+ '✓ Codex ready · codex-cli 0.163.0 · ~/.npm-global/bin/codex');+ assert.equal(agentLine({ id: 'cursor', name: 'Cursor', status: 'missing', path: null }, null, HOME), '– Cursor missing');+ assert.match(agentLine({ id: 'claude', name: 'Claude Code', status: 'sign-in', path: '/opt/homebrew/bin/claude' }, { ok: true, version: '2.1.302' }, HOME), /^✗ Claude Code +sign-in/);+});++test('a program that does not start, or an error the app saw, is something to fix, said on one line', () => {+ const line = agentLine({ id: 'codex', name: 'Codex', status: 'ready', path: 'D:\\Profiles\\someone\\AppData\\Roaming\\npm\\codex.cmd', chosen: 'x' },+ { ok: false, error: 'Error: spawn EINVAL\n at ChildProcess.spawn' }, 'D:\\Profiles\\someone');+ assert.match(line, /^✗ Codex/);+ assert.match(line, /--version failed: Error: spawn EINVAL at ChildProcess\.spawn/);+ assert.match(line, /~\\AppData\\Roaming\\npm\\codex\.cmd \(chosen\)/);+ assert.match(agentLine({ id: 'kimi', name: 'Kimi', status: 'ready', path: '/bin/kimi', error: 'auth_required' }, null, HOME), /^✗ Kimi .* · auth_required$/);+});++test('the report: the app, then each agent, the own-key one without a program', () => {+ const text = appReport({+ version: '0.1.8', flavor: 'release', packaged: true, channel: 'beta', electron: '44.4.0', pathSource: 'login shell', home: HOME,+ agents: [{ id: 'codex', name: 'Codex', status: 'ready', path: `${HOME}/bin/codex` }, { id: 'byok', name: 'Own key', status: 'key' }],+ versions: { codex: { ok: true, version: '0.163.0' } },+ });+ assert.match(text, /App +0\.1\.8 \(release, beta updates; Electron 44\.4\.0\)/);+ assert.match(text, /PATH from +login shell/);+ assert.match(text, /✓ Codex +ready · 0\.163\.0 · ~\/bin\/codex/);+ assert.match(text, /– Own key +key$/);+});++test('gathering asks --version of the agents found, and only those', async () => {+ const asked = [];+ const text = await gatherAppReport({+ list: async () => [+ { id: 'codex', name: 'Codex', status: 'ready', path: '/bin/codex' },+ { id: 'cursor', name: 'Cursor', status: 'missing', path: null },+ { id: 'qwen', name: 'Qwen Code', status: 'ready', path: '/bin/qwen' },+ ],+ check: async (id) => { asked.push(id); if (id === 'qwen') throw new Error('boom'); return { ok: true, version: '1.0' }; },+ }, { version: '0.1.8', flavor: 'dev', packaged: false, electron: '44.4.0', pathSource: null });+ assert.deepEqual(asked.sort(), ['codex', 'qwen']);+ assert.match(text, /from source/);+ assert.match(text, /✗ Qwen Code +ready · --version failed: boom/);+});diff --git a/apps/desktop/src/attachment-place.test.mjs b/apps/desktop/src/attachment-place.test.mjsnew file mode 100644index 0000000..f180499--- /dev/null+++ b/apps/desktop/src/attachment-place.test.mjs@@ -0,0 +1,23 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { attachmentPlace } from '../chat/src/lib/attachment-place.ts';++test('a folder is placed by the folder it sits in, the home folder as ~', () => {+ assert.equal(attachmentPlace('/Users/me/Desktop/temp'), '~/Desktop');+ assert.equal(attachmentPlace('/Users/me/Desktop/temp/'), '~/Desktop');+ assert.equal(attachmentPlace('/Users/me/temp'), '~');+ assert.equal(attachmentPlace('/home/me/films/temp'), '~/films');+ assert.equal(attachmentPlace('/Volumes/Disk/temp'), '/Volumes/Disk');+ assert.equal(attachmentPlace('C:\\Users\\me\\Desktop\\temp'), '~\\Desktop');+ assert.equal(attachmentPlace('D:\\footage\\temp'), 'D:\\footage');+});++test('a deep folder keeps only the last two folders above it', () => {+ assert.equal(attachmentPlace('/Users/me/Movies/OpenFilm/Projects/2026/temp'), '…/Projects/2026');+ assert.equal(attachmentPlace('/srv/a/b/c/temp'), '…/b/c');+});++test('a folder at the top of a disk has no place to show', () => {+ assert.equal(attachmentPlace('/temp'), '');+ assert.equal(attachmentPlace('temp'), '');+});diff --git a/apps/desktop/src/chat-ipc.mjs b/apps/desktop/src/chat-ipc.mjsindex be593a4..2db0606 100644--- a/apps/desktop/src/chat-ipc.mjs+++ b/apps/desktop/src/chat-ipc.mjs@@ -9,6 +9,8 @@* its requests read from the agent's own record (or log) as it is now (agent-records.mjs)* desktop:chat:reveal { project, turnId? } the turn's log (or the logs folder) in the file manager* desktop:chat:ref-image { project, turnId, n, bytes } → { path } a reference's picture, kept for the agent+ * desktop:chat:attachment { project, name, bytes } → { path } a file pasted into a message, kept for the agent+ * desktop:chat:paths { paths } → [{ path, folder, size? } | { path, error }] files and folders dragged in* desktop:chat:unsaved { project, except? } → [{ turnId, events }] turns with a log and no saved record* desktop:chat:snapshot { project, turnId } the project's files as a turn starts (file-changes.mjs), kept here* desktop:chat:changes { project, turnId } → { files, cut } | null what the turn changed in them since@@ -20,7 +22,7 @@import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';import { join, resolve } from 'node:path';import { RECORDED_AGENTS, agentRecordCalls, compactCalls } from './agent-records.mjs';-import { chatDir, loadChat, readLog, saveRefImage, saveSessions, saveTurn, unsavedTurns } from './chat-store.mjs';+import { chatDir, describePaths, loadChat, readLog, saveAttachment, saveRefImage, saveSessions, saveTurn, unsavedTurns } from './chat-store.mjs';import { loginShellVariables } from './environment.mjs';import { changes, snapshot } from './file-changes.mjs';@@ -82,6 +84,8 @@ export function registerChatIpc(ipcMain, { trusted, projects, dataDir, reveal, thandle('desktop:chat:sessions', async ({ project: path, sessions, last }) => { saveSessions(await project(path), { sessions, last }); return { ok: true }; });handle('desktop:chat:turn', async ({ project: path, turn, items }) => { saveTurn(await project(path), { turn, items }); return { ok: true }; });handle('desktop:chat:ref-image', async ({ project: path, turnId, n, bytes }) => saveRefImage(await project(path), turnId, n, bytes));+ handle('desktop:chat:attachment', async ({ project: path, name, bytes }) => saveAttachment(await project(path), name, bytes));+ handle('desktop:chat:paths', async ({ paths }) => describePaths(paths));handle('desktop:chat:unsaved', async ({ project: path, except }) => unsavedTurns(await project(path), {except: Array.isArray(except) ? except.filter((id) => typeof id === 'string') : [],}));diff --git a/apps/desktop/src/chat-store.mjs b/apps/desktop/src/chat-store.mjsindex 0cdd52d..7b2e221 100644--- a/apps/desktop/src/chat-store.mjs+++ b/apps/desktop/src/chat-store.mjs@@ -22,12 +22,17 @@* <turn>-<n>.jpg the picture of the message's reference [n] (a frame, or the part of it pointed at), for its* agent to look at: the message names the path*+ * the files pasted into a message, `.film/attachments/`:+ * <name> a file with no place on the disk of its own (a screenshot, a picture copied from a page),+ * kept for the agent: the message names the path. A file or folder dragged in from the disk+ * stays where it is, and the message names that path instead+ ** `.film/` is Studio's own (its projects.mjs says what else is there): a film never reads it, and nothing in it is* served. Reads no Electron module, so `node --test` can use it.*/import { createHash } from 'node:crypto';import { createWriteStream, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statSync, writeFileSync } from 'node:fs';-import { join } from 'node:path';+import { isAbsolute, join } from 'node:path';/** a turn's id (`local:…`) and the file it names (no `:`, which Windows does not allow in a name) */const ID = /^[\w:-]{1,120}$/;@@ -38,6 +43,7 @@ const LOG_READ_MAX = 32 * 1024 * 1024;export const chatDir = (project) => join(project, '.film', 'chat');export const logsDir = (project) => join(project, '.film', 'logs');export const refsDir = (project) => join(project, '.film', 'refs');+export const attachmentsDir = (project) => join(project, '.film', 'attachments');/** a reference's picture: a JPEG, of a frame at most 1280 px wide (the page makes it so) */const REF_IMAGE_MAX = 8 * 1024 * 1024;const REF_MAX = 64;@@ -102,6 +108,42 @@ export function saveRefImage(project, turnId, n, bytes) {return { path: `.film/refs/${name}` };}+/**+ * Keep a file pasted into a message; → its path in the project (`.film/attachments/<name>`). The name is cut to its last+ * part and cleaned here, so the page cannot write anywhere else; a name already there gets ` 2`, ` 3`… before its ending.+ */+export function saveAttachment(project, name, bytes) {+ const data = bytes instanceof Uint8Array ? bytes : bytes instanceof ArrayBuffer ? new Uint8Array(bytes) : null;+ if (!data || !data.length) throw new Error('the file is empty');+ const clean = String(name ?? '').split(/[/\\]/).pop().replace(/[\u0000-\u001f<>:"|?*]+/g, '').replace(/^[.\s]+/, '').trim().slice(0, 200) || 'file';+ const dot = clean.lastIndexOf('.');+ const [stem, ending] = dot > 0 ? [clean.slice(0, dot), clean.slice(dot)] : [clean, ''];+ const dir = attachmentsDir(project);+ mkdirSync(dir, { recursive: true });+ for (let n = 1; ; n++) {+ const file = n === 1 ? clean : `${stem} ${n}${ending}`;+ if (existsSync(join(dir, file))) continue;+ writeAtomic(join(dir, file), data);+ return { path: `.film/attachments/${file}` };+ }+}++/**+ * What each path dragged into a message is: a file (its size) or a folder; `error` for one that is not there or cannot+ * be read. Nothing is copied: the message names the path where it is.+ */+export function describePaths(paths) {+ return (Array.isArray(paths) ? paths : []).map((path) => {+ if (typeof path !== 'string' || !isAbsolute(path)) return { path: String(path), error: 'That is not a file.' };+ try {+ const found = statSync(path);+ return found.isDirectory() ? { path, folder: true } : { path, folder: false, size: found.size };+ } catch {+ return { path, error: 'That file is not there any more.' };+ }+ });+}+/*** A turn's events, as written: [{ t, kind, … }] (a broken line, from a crash mid-write, is left out). `unless`: the* sizes a reader already has (`size`, `callsSize` of an earlier read): when neither file has grown, `{ same: true }`diff --git a/apps/desktop/src/chat-store.test.mjs b/apps/desktop/src/chat-store.test.mjsindex 00722a6..b989156 100644--- a/apps/desktop/src/chat-store.test.mjs+++ b/apps/desktop/src/chat-store.test.mjs@@ -1,9 +1,9 @@import { test } from 'node:test';import assert from 'node:assert/strict';-import { appendFileSync, mkdtempSync, readFileSync } from 'node:fs';+import { appendFileSync, mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';-import { chatDir, loadChat, logsDir, openLog, readLog, refsDir, saveRefImage, saveSessions, saveTurn, unsavedTurns } from './chat-store.mjs';+import { attachmentsDir, chatDir, describePaths, loadChat, logsDir, openLog, readLog, refsDir, saveAttachment, saveRefImage, saveSessions, saveTurn, unsavedTurns } from './chat-store.mjs';const project = () => mkdtempSync(join(tmpdir(), 'of-chat-'));const turn = (id, createdAt) => ({ turn: { id, createdAt, sessionId: 's1', prompt: id }, items: [{ kind: 'text', text: id }] });@@ -103,6 +103,37 @@ test('a reference\'s picture is kept as .film/refs/<turn>-<n>.jpg, and nothing bassert.throws(() => saveRefImage(dir, 'local:abc', 1, 'not bytes'), /not a picture/);});+test('a pasted file is kept in .film/attachments under its own name, cleaned, and never anywhere else', () => {+ const dir = project();+ const bytes = new Uint8Array([1, 2, 3]);+ assert.deepEqual(saveAttachment(dir, 'image.png', bytes), { path: '.film/attachments/image.png' });+ assert.deepEqual([...readFileSync(join(attachmentsDir(dir), 'image.png'))], [1, 2, 3]);+ assert.equal(saveAttachment(dir, 'image.png', bytes.buffer).path, '.film/attachments/image 2.png', 'a name already there is not written over');+ assert.equal(saveAttachment(dir, 'image.png', bytes).path, '.film/attachments/image 3.png');+ assert.equal(saveAttachment(dir, '../../etc/passwd', bytes).path, '.film/attachments/passwd');+ assert.equal(saveAttachment(dir, '..\\..\\win.ini', bytes).path, '.film/attachments/win.ini');+ assert.equal(saveAttachment(dir, '.hidden', bytes).path, '.film/attachments/hidden');+ assert.equal(saveAttachment(dir, '', bytes).path, '.film/attachments/file');+ assert.throws(() => saveAttachment(dir, 'empty.txt', new Uint8Array()), /empty/);+ assert.throws(() => saveAttachment(dir, 'x.txt', 'not bytes'), /empty/);+});++test('a path dragged in is said to be a file (with its size) or a folder, where it is; one not there is said so', () => {+ const dir = project();+ const folder = join(dir, 'Footage');+ mkdirSync(folder);+ const clip = join(folder, 'a.mp4');+ writeFileSync(clip, 'abcd');+ assert.deepEqual(describePaths([clip, folder, join(dir, 'gone.mp4'), 'relative.mp4', 7]), [+ { path: clip, folder: false, size: 4 },+ { path: folder, folder: true },+ { path: join(dir, 'gone.mp4'), error: 'That file is not there any more.' },+ { path: 'relative.mp4', error: 'That is not a file.' },+ { path: '7', error: 'That is not a file.' },+ ]);+ assert.deepEqual(describePaths('not a list'), []);+});+test('a log not grown since the sizes a reader has is not read again', async () => {const dir = project();const log = openLog(dir, 't2');diff --git a/apps/desktop/src/environment.mjs b/apps/desktop/src/environment.mjsindex 1074c39..7b3d1a8 100644--- a/apps/desktop/src/environment.mjs+++ b/apps/desktop/src/environment.mjs@@ -12,7 +12,7 @@* runs, so an agent installed meanwhile is found without restarting it. Reads no Electron module, so `node --test`* can use it.*/-import { spawn } from 'node:child_process';+import { execFile, spawn } from 'node:child_process';import { homedir, userInfo } from 'node:os';import { isAbsolute, join } from 'node:path';diff --git a/apps/desktop/src/flavor.mjs b/apps/desktop/src/flavor.mjsindex 0abb656..c283c9f 100644--- a/apps/desktop/src/flavor.mjs+++ b/apps/desktop/src/flavor.mjs@@ -1,13 +1,14 @@/*** Which OpenFilm this process is. Two apps, each with its own name, bundle id, data folder and Studio home, so the- * one run from this repository never shares a window, a lock or a Studio with the installed one:+ * one run from this repository never shares a window, a lock or a Studio with the installed one. Projects are the+ * person's, so every app but the bench shares one library: the one ~/.openfilm says (`sharedHome`; by default+ * ~/Movies/OpenFilm/Projects, or OPENFILM_LIBRARY):** · release — the packaged app. Its Studio is the machine's Studio (~/.openfilm), the one `openfilm open` finds.* · preview — a packaged app built with `release --preview`, "OpenFilm Preview", to try a build in: its own data- * folder, Studio home, port and projects, so it never meets an installed OpenFilm (its package says so:+ * folder, Studio home and port, so it never meets an installed OpenFilm (its package says so:* `openfilmFlavor`).- * · dev — `pnpm --filter @openfilm/desktop start`: this repository's code, with its own Studio home and its own- * folder for new projects.+ * · dev — `pnpm --filter @openfilm/desktop start`: this repository's code, with its own Studio home.* · bench — `node bench/run.mjs`: this repository's code, everything (data, Studio home, projects) in the throwaway* folder the benchmark names in OPENFILM_BENCH_DIR, so a run never touches a person's dev or installed app.*@@ -21,21 +22,21 @@ import { fileURLToPath } from 'node:url';const packaged = Boolean(process.versions.electron) && !process.defaultApp;export const FLAVORS = Object.freeze({- release: { productName: 'OpenFilm', bundleId: 'dev.openfilm.desktop', studioPort: 4747, studioHome: null, library: null },+ release: { productName: 'OpenFilm', bundleId: 'dev.openfilm.desktop', studioPort: 4747, studioHome: null, library: null, sharedHome: null },preview: {productName: 'OpenFilm Preview', bundleId: 'dev.openfilm.desktop.preview', studioPort: 4777,- studioHome: join(homedir(), '.openfilm-preview'), library: join(homedir(), 'Movies', 'OpenFilm Preview', 'Projects'),+ studioHome: join(homedir(), '.openfilm-preview'), library: null, sharedHome: join(homedir(), '.openfilm'),},dev: {productName: 'OpenFilm Dev', bundleId: 'dev.openfilm.desktop.dev', studioPort: 4757,- studioHome: join(homedir(), '.openfilm-dev'), library: join(homedir(), 'Movies', 'OpenFilm Dev', 'Projects'),+ studioHome: join(homedir(), '.openfilm-dev'), library: null, sharedHome: join(homedir(), '.openfilm'),},});const benchDir = process.env.OPENFILM_BENCH_DIR ?? '';const BENCH = Object.freeze({productName: 'OpenFilm Bench', bundleId: 'dev.openfilm.desktop.bench', studioPort: 4767,- studioHome: join(benchDir, 'home'), library: join(benchDir, 'projects'), userData: join(benchDir, 'data'),+ studioHome: join(benchDir, 'home'), library: join(benchDir, 'projects'), sharedHome: null, userData: join(benchDir, 'data'),});/** What the app's package says it was built as (`release --preview` writes `openfilmFlavor`). */diff --git a/apps/desktop/src/flavor.test.mjs b/apps/desktop/src/flavor.test.mjsindex cc20e18..735f59f 100644--- a/apps/desktop/src/flavor.test.mjs+++ b/apps/desktop/src/flavor.test.mjs@@ -1,5 +1,7 @@import { test } from 'node:test';import assert from 'node:assert/strict';+import { homedir } from 'node:os';+import { join } from 'node:path';import { FLAVORS, flavorName } from './flavor.mjs';test('which app this is: packaged, the release unless built as the preview; from source, dev when asked', () => {@@ -17,7 +19,14 @@ test('the preview shares nothing with an installed OpenFilm or the dev app', ()assert.notEqual(preview.bundleId, other.bundleId);assert.notEqual(preview.studioPort, other.studioPort);assert.notEqual(preview.studioHome, other.studioHome);- assert.notEqual(preview.library, other.library);}assert.ok(preview.studioHome, 'its own Studio home, not the machine\'s ~/.openfilm');});++test('every app makes its projects in the person\'s one library', () => {+ for (const flavor of Object.values(FLAVORS)) {+ assert.equal(flavor.library, null);+ /* the folder the person chose for it is kept in the machine's Studio home */+ assert.equal(flavor.sharedHome ?? join(homedir(), '.openfilm'), join(homedir(), '.openfilm'));+ }+});diff --git a/apps/desktop/src/local-agents-ipc.mjs b/apps/desktop/src/local-agents-ipc.mjsindex 14e23e5..d256cd7 100644--- a/apps/desktop/src/local-agents-ipc.mjs+++ b/apps/desktop/src/local-agents-ipc.mjs@@ -45,12 +45,13 @@* into `.film/logs/<turn>.model.jsonl`, as the app's own agent writes its own.*/import { randomUUID } from 'node:crypto';-import { homedir } from 'node:os';+import { join } from 'node:path';+import { recordProblem, problemsFile } from 'openfilm/problems';import { LOG_SETTLE_MS } from './agent-logs.mjs';import { RECORDED_AGENTS, agentRecordCalls, compactCalls } from './agent-records.mjs';import { skillStore } from './agent-skills.mjs';-import { AgentSession, HARNESS_AGENTS, isAgentId, isChatAgent, listAgents, openAgentSignIn } from './agents.mjs';-import { loggedBlocks, openLog, writeModelLog } from './chat-store.mjs';+import { AGENTS, AgentSession, HARNESS_AGENTS, isAgentId, isChatAgent, listAgents, openAgentSignIn, probeFolder } from './agents.mjs';+import { loggedBlocks, logsDir, openLog, writeModelLog } from './chat-store.mjs';import { loginShellVariables } from './environment.mjs';const TURN_LOG_MAX = 5000;@@ -63,8 +64,8 @@ const IDLE_CHECK_MS = 60_000;const PROBE_COMMANDS_MS = 1500;/** how long after its turn a session whose skills changed closes: the page has settled the turn by then */const STALE_CLOSE_MS = 3000;-/** the pictures one message may carry, and how big each (base64 of a JPEG at most 1280 px wide) */-const PROMPT_IMAGES_MAX = 8;+/** the pictures one message may carry (the page's PROMPT_PICTURES_MAX), and how big each (base64, at most 2000 px a side) */+const PROMPT_IMAGES_MAX = 20;const PROMPT_IMAGE_MAX_CHARS = 8 * 1024 * 1024;const IMAGE_TYPES = new Set(['image/jpeg', 'image/png', 'image/webp']);@@ -96,6 +97,23 @@ function imageBlocks(images) {.map((image) => ({ type: 'image', data: image.data, mimeType: image.mimeType }));}+/**+ * An agent that did not start, did not answer, or whose process ended by itself, as Studio's problems keep it+ * (openfilm's problems.mjs): why, the step it stopped at, its program, the last of its stderr, and where its turn's log+ * is.+ * @param {{ agent: string, cwd: string, session?: any }} entry @param {string} step @param {any} e @param {string | null} [turnId]+ */+export function agentProblem(entry, step, e, turnId = null) {+ const failure = entry.session?.failure?.() ?? {};+ const stderr = String(failure.stderr ?? entry.session?.stderr ?? '').trim().split(/\r?\n/).slice(-5).join('\n');+ return {+ area: 'agent', agent: AGENTS[entry.agent]?.label ?? (entry.agent === 'byok' ? 'Own key' : entry.agent), agentId: entry.agent,+ what: e instanceof Error ? e.message : String(e), step: failure.step ?? e?.step ?? step, ...(e?.code != null ? { code: String(e.code) } : {}),+ project: entry.cwd, ...(turnId ? { log: join(logsDir(entry.cwd), `${turnId.replace(/:/g, '-')}.jsonl`) } : {}),+ ...(failure.program ? { program: failure.program } : {}), ...(stderr ? { stderr } : {}), ...(failure.ownLogs ? { ownLogs: failure.ownLogs } : {}),+ };+}+/*** @param {import('electron').IpcMain} ipcMain* `harness(id)` gives the app's own agent ('byok') what it runs with (agent-roster.mjs), resolved as@@ -112,6 +130,9 @@ function imageBlocks(images) {export function registerLocalAgentIpc(ipcMain, { trusted, binDir = null, fallbackDir = null, env = {}, harness = async () => null, log = () => {}, onWorking = () => {}, onAsking = () => {}, logDir = () => null, skills = null }) {const harnessFor = async (agent) => (HARNESS_AGENTS.includes(agent) ? harness(agent) : undefined);const skillRecord = skills ? skillStore(skills.dataDir) : null;+ /* what went wrong, kept in Studio's home with Studio's own problems (openfilm's problems.mjs), for its report */+ const problems = env.OPENFILM_HOME ? problemsFile(env.OPENFILM_HOME) : undefined;+ const noteProblem = (entry, step, e, turnId = null) => recordProblem(agentProblem(entry, step, e, turnId), { file: problems });/** a session's skills and MCP servers: OpenFilm's, and of the person's own those let in (agent-skills.mjs) */const skillsFor = (agent) => (skills && skillRecord ? { ...skills, allowed: skillRecord.allowed(agent), mcpAllowed: skillRecord.mcpAllowed(agent) } : null);/** @type {Map<string, { session: AgentSession, sender: import('electron').WebContents, pending: Map<string, (answer: any) => void>, agent: string, cwd: string, turn: any }>} */@@ -179,7 +200,7 @@ export function registerLocalAgentIpc(ipcMain, { trusted, binDir = null, fallbaclet commands = null;let said = () => {};const heard = new Promise((done) => { said = done; });- session = new AgentSession({ agent, cwd: homedir(), binDir, fallbackDir, env, harness: await harnessFor(agent),+ session = new AgentSession({ agent, cwd: probeFolder(), binDir, fallbackDir, env, harness: await harnessFor(agent),onUpdate: (update) => { if (update?.sessionUpdate === 'available_commands_update') { commands = update.availableCommands ?? null; said(); } } });const info = await session.start();await Promise.race([heard, new Promise((done) => setTimeout(done, PROBE_COMMANDS_MS))]);@@ -233,7 +254,13 @@ export function registerLocalAgentIpc(ipcMain, { trusted, binDir = null, fallbacsend(entry, key, { kind: 'question', requestId, ...ask });tellAsking();}),- onExit: (info) => { send(entry, key, { kind: 'exit', ...info }); sessions.delete(key); if (entry.running > 0) onWorking(working()); },+ onExit: (info) => {+ /* ended by itself (not closed here), and not well: a problem */+ if (sessions.get(key) === entry && info.code) noteProblem(entry, 'exit', new Error(`${AGENTS[agent]?.label ?? agent}'s process ended with code ${info.code}.`), entry.turn && !entry.turn.done ? entry.turn.meta?.turnId : null);+ send(entry, key, { kind: 'exit', ...info });+ sessions.delete(key);+ if (entry.running > 0) onWorking(working());+ },onSend: (sent) => {const file = entry.turn && !entry.turn.done ? entry.turn.file : entry.adopted;file?.write('sent', { ...sent, prompt: loggedBlocks(cwd, sent.prompt) });@@ -245,6 +272,8 @@ export function registerLocalAgentIpc(ipcMain, { trusted, binDir = null, fallbacentry.info = info;return { ok: true, key, info: { ...info, authMethods: [], mcp: false } };} catch (e) {+ /* one not installed, or not set up, is not a problem of the app's: the chat says what to do */+ if (e?.code !== 'not-installed' && e?.code !== 'not-ready') noteProblem(entry, 'start', e);close(key);return { ok: false, error: e instanceof Error ? e.message : String(e), ...(e?.code ? { code: String(e.code) } : {}) };}@@ -279,6 +308,7 @@ export function registerLocalAgentIpc(ipcMain, { trusted, binDir = null, fallbacresult = { ok: false, error: e instanceof Error ? e.message : String(e), ...(e?.balance ? { balance: e.balance } : {}) };const asSent = e?.cause ?? e;if (typeof asSent?.code === 'number') raw = { code: asSent.code, message: asSent.message, data: asSent.data ?? null };+ if (!e?.balance) noteProblem(entry, 'prompt', e, meta?.turnId ?? null);} finally {activePrompts--;entry.running -= 1;diff --git a/apps/desktop/src/local-agents-ipc.test.mjs b/apps/desktop/src/local-agents-ipc.test.mjsnew file mode 100644index 0000000..92fc3d3--- /dev/null+++ b/apps/desktop/src/local-agents-ipc.test.mjs@@ -0,0 +1,19 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { join } from 'node:path';+import { agentProblem } from './local-agents-ipc.mjs';++test('an agent that failed, as its problem is kept: its name, why, the step, the last of its stderr and its turn\'s log', () => {+ const session = { stderr: 'a\nb\nc\nd\ne\nError: write EPIPE\n' };+ const e = Object.assign(new Error('ACP connection closed'), { code: -32603 });+ assert.deepEqual(agentProblem({ agent: 'codex', cwd: '/p/Film', session }, 'prompt', e, 'local:abc'), {+ area: 'agent', agent: 'Codex', agentId: 'codex', what: 'ACP connection closed', step: 'prompt', code: '-32603',+ project: '/p/Film', log: join('/p/Film', '.film', 'logs', 'local-abc.jsonl'), stderr: 'b\nc\nd\ne\nError: write EPIPE',+ });+ /* a session that says how it failed (agents.mjs `failure()`): its step, program and own logs */+ const told = { failure: () => ({ step: 'session/new', program: '/x/codex', stderr: '', ownLogs: '/h/.codex' }) };+ assert.deepEqual(agentProblem({ agent: 'codex', cwd: '/p/Film', session: told }, 'start', new Error('Internal error')), {+ area: 'agent', agent: 'Codex', agentId: 'codex', what: 'Internal error', step: 'session/new', project: '/p/Film', program: '/x/codex', ownLogs: '/h/.codex',+ });+ assert.equal(agentProblem({ agent: 'byok', cwd: '/p' }, 'start', 'no models').agent, 'Own key');+});diff --git a/apps/desktop/src/main.mjs b/apps/desktop/src/main.mjsindex 5767c7d..7b818c5 100644--- a/apps/desktop/src/main.mjs+++ b/apps/desktop/src/main.mjs@@ -9,14 +9,14 @@* in the page (shell/bridge.ts); this process does what only the app can: the window, the agents, files on the disk,* ffmpeg, updates (preload.cjs). The window opens straight into the last project.*/-import { BaseWindow, Menu, WebContentsView, app, dialog, ipcMain, nativeTheme, safeStorage, screen, shell } from 'electron';-import { appendFileSync, createReadStream, existsSync, mkdirSync, statSync } from 'node:fs';-import { basename, dirname, join } from 'node:path';-import { Readable } from 'node:stream';+import { BaseWindow, Menu, WebContentsView, app, clipboard, dialog, ipcMain, nativeTheme, safeStorage, screen, shell } from 'electron';+import { appendFileSync, existsSync, mkdirSync } from 'node:fs';+import { dirname, join } from 'node:path';import { fileURLToPath } from 'node:url';import { FLAVOR, IDENTITY, PRODUCT_NAME } from './flavor.mjs';import { folderDialogOptions, programDialogOptions } from './folder-dialog.mjs';-import { childEnvironment, loginShellEnvironment } from './environment.mjs';+import { childEnvironment, lastPathSource, loginShellEnvironment } from './environment.mjs';+import { gatherAppReport } from './app-report.mjs';import { startWindowStudio } from './studio.mjs';import { CHAT_MIN, STUDIO_MIN, WINDOW_MIN, placeOnDisplays, readWindowState, writeWindowState } from './window-state.mjs';import { createPagePresentation, preparePage, revealPage } from './page-presentation.mjs';@@ -26,7 +26,7 @@ import { registerLocalAgentIpc } from './local-agents-ipc.mjs';import { readPreferences, registerChatIpc } from './chat-ipc.mjs';import { registerSkillsIpc } from './skills-ipc.mjs';import { createRoster } from './agent-roster.mjs';-import { checkAgentProgram, diagnoseAgent, listAgents, openAgentSignIn, setChosenPaths } from './agents.mjs';+import { checkAgentProgram, closeEverySession, diagnoseAgent, listAgents, localAgent, openAgentSignIn, setChosenPaths } from './agents.mjs';import { agentUsage, forgetAgentUsage } from './agent-usage.mjs';import { installOpenfilmCommand } from './openfilm-command.mjs';import { startUpdates } from './updates.mjs';@@ -351,7 +351,8 @@ async function runStudio(env) {home: env.OPENFILM_HOME,port: IDENTITY.studioPort,/* Studio serves the window's page as its editor (shell/: its editor with the chat beside it) */- env: { ...env, OPENFILM_EDITOR_DIR: here('../shell/dist/') },+ /* its diagnostic file takes the app's own logs too (Studio's diagnostics.mjs) */+ env: { ...env, OPENFILM_EDITOR_DIR: here('../shell/dist/'), OPENFILM_APP_LOGS: LOGS },log,onOpen: (url) => {/* Studio would open a browser for an address of its own: the window already shows Studio */@@ -385,6 +386,8 @@ async function start() {extra: {OPENFILM_HOME: IDENTITY.studioHome ?? process.env.OPENFILM_HOME ?? join(app.getPath('home'), '.openfilm'),...((IDENTITY.library ?? process.env.OPENFILM_LIBRARY) ? { OPENFILM_LIBRARY: IDENTITY.library ?? process.env.OPENFILM_LIBRARY } : {}),+ /* a flavour with a home of its own still shares the person's library (src/locations.mjs) */+ ...(IDENTITY.sharedHome ? { OPENFILM_SHARED_HOME: IDENTITY.sharedHome } : {}),/* the app names Studio's home, which would put exports inside it (Studio's rule for a home kept apart): theDesktop, where `openfilm` puts them, unless this is a flavour with a home of its own */...(IDENTITY.studioHome || process.env.OPENFILM_EXPORTS ? {} : { OPENFILM_EXPORTS: app.getPath('desktop') }),@@ -473,6 +476,11 @@ async function start() {tellTabs();return { ok: true };});+ /* another tab's project renamed from this page's tabs: its title, also while that tab has no page to say it */+ tabHandle('desktop:tabs:retitle', (_self, { id, title }) => {+ if (typeof title === 'string' && tabs?.report(String(id), { title: title.slice(0, 200) })) tellTabs();+ return { ok: true };+ });/* Studio's "open this project", heard by each page: settled once here */tabHandle('desktop:tabs:open', (_self, { to }) => { openInTabs(to); return { ok: true }; });/* a tab left behind long enough lets its page go; it comes back when shown */@@ -492,7 +500,11 @@ async function start() {that has none of its own: the person's own ffmpeg and browsers are what the agent's commands use */binDir: installOpenfilmCommand(DATA, { ffmpeg: ffmpegHere, env: browsers }),fallbackDir: ffmpegHere,- env: { OPENFILM_HOME: env.OPENFILM_HOME, ...(env.OPENFILM_LIBRARY ? { OPENFILM_LIBRARY: env.OPENFILM_LIBRARY } : {}) },+ env: {+ OPENFILM_HOME: env.OPENFILM_HOME,+ ...(env.OPENFILM_LIBRARY ? { OPENFILM_LIBRARY: env.OPENFILM_LIBRARY } : {}),+ ...(env.OPENFILM_SHARED_HOME ? { OPENFILM_SHARED_HOME: env.OPENFILM_SHARED_HOME } : {}),+ },harness: async (id) => roster?.harness(id) ?? null,/* Developer mode: an agent whose own record lacks what its model got logs it here (agent-logs.mjs) */logDir: () => (readPreferences(DATA).developer ? join(DATA, 'agent-logs') : null),@@ -515,6 +527,7 @@ async function start() {roster = createRoster({dataDir: DATA,localAgents: listAgents,+ localAgent,openSignIn: openAgentSignIn,/* sessions closed on connecting and disconnecting: the next look at its usage is for whichever account is used now */closeSessions: (id) => { forgetAgentUsage(id); localAgents?.closeAgent(id); },@@ -542,41 +555,27 @@ async function start() {agentHandle('desktop:agents:locate', ({ id, words }) => roster.locate(String(id), words));agentHandle('desktop:agents:automatic', ({ id }) => roster.useAutomatic(String(id)));agentHandle('desktop:agents:diagnose', ({ id }) => roster.diagnose(String(id)));+ /* the app's part of Studio's diagnostic report (app-report.mjs): the agents as found now, each one's --version */+ const appReport = () => gatherAppReport({ list: () => roster.refresh(), check: checkAgentProgram }, {+ version: app.getVersion(), flavor: FLAVOR, packaged: app.isPackaged, channel: updates?.snapshot()?.channel ?? null,+ electron: process.versions.electron, pathSource: lastPathSource(),+ });+ agentHandle('desktop:agents:report', appReport);+ /* the chat's "Copy diagnostic report" by a turn that failed: what Studio's report has (`openfilm doctor`, with the+ last week's problems) and the app's agents, on the clipboard (the chat's page may not be let write it) */+ agentHandle('desktop:diagnostics:copy', async () => {+ const [computer, own] = await Promise.all([+ studioApi('/api/doctor').then((r) => String(r.text ?? ''), () => ''),+ appReport().catch(() => ''),+ ]);+ const text = [computer, own].filter(Boolean).join('\n\n────────\n\n');+ if (!text) return { ok: false };+ clipboard.writeText(text);+ return { ok: true };+ });agentHandle('desktop:agents:shown', ({ id, shown }) => { roster.setShown(String(id), shown === true); return { ok: true }; });agentHandle('desktop:agents:own-model', ({ config }) => roster.saveOwnModel(config));agentHandle('desktop:agents:own-model-remove', ({ id }) => { roster.removeOwnModel(String(id)); return { ok: true }; });- /* a file on the disk brought into the chat goes into the project the page names, through Studio's own import (it- shows in Studio's media at once, and the import is in the project's history); one without a path the page sends- itself. A folder goes as it is, through Studio's bring (files.mjs bringIn): every file in it, copied where the disk- can clone, hidden ones left out */- ipcMain.handle('desktop:import-file', async (event, request) => {- if (!fromPage(event) || !studio) return { ok: false, error: 'Studio is not running.' };- const projectId = String(request?.projectId ?? '');- if (!/^[\w-]+$/.test(projectId)) return { ok: false, error: 'No project is open.' };- const name = basename(String(request?.name ?? '')).replace(/[\u0000-\u001f/\\]+/g, '').slice(0, 200) || 'file';- const path = typeof request?.path === 'string' ? request.path : '';- if (!path) return { ok: false, error: 'That file is not there any more.' };- let info;- try { info = statSync(path); } catch { return { ok: false, error: 'That file is not there any more.' }; }- if (info.isDirectory()) {- try {- const res = await fetch(`${studio.origin}/api/projects/${encodeURIComponent(projectId)}/files/bring`, {- method: 'POST', headers: { 'x-studio-key': studio.key, 'content-type': 'application/json' },- body: JSON.stringify({ into: 'assets/upload', mode: 'copy', paths: [path] }),- });- const answer = await res.json().catch(() => ({}));- return res.ok && answer.landed?.[0] ? { ok: true, path: answer.landed[0], folder: true } : { ok: false, error: answer.error ?? `Studio answered ${res.status}` };- } catch (error) { return { ok: false, error: error.message }; }- }- if (!info.isFile()) return { ok: false, error: 'That is not a file.' };- try {- const res = await fetch(`${studio.origin}/api/projects/${encodeURIComponent(projectId)}/files?path=${encodeURIComponent(`assets/upload/${name}`)}`, {- method: 'PUT', headers: { 'x-studio-key': studio.key }, body: Readable.toWeb(createReadStream(path)), duplex: 'half',- });- const answer = await res.json().catch(() => ({}));- return res.ok ? { ok: true, path: answer.path } : { ok: false, error: answer.error ?? `Studio answered ${res.status}` };- } catch (error) { return { ok: false, error: error.message }; }- });ipcMain.handle('desktop:reveal', (event, path) => { if (fromPage(event) && typeof path === 'string' && path) shell.showItemInFolder(path); });ipcMain.handle('desktop:pick-folder', (event, options) => (fromPage(event) ? pickFolder(options) : null));/* a picture of part of the window (the viewer, for a reference in the chat): what the person sees, as JPEG */@@ -608,6 +607,7 @@ async function start() {beforeInstall: async () => {quitting = true;localAgents?.closeAll();+ closeEverySession();for (const v of views.values()) v.webContents.on('will-prevent-unload', (event) => event.preventDefault());await studio?.quit();updates?.close();@@ -673,6 +673,7 @@ app.on('window-all-closed', () => app.quit());app.on('before-quit', (event) => {quitAfterStudio(event, {quitting, markQuitting: () => { quitting = true; }, studio,- closeAgents: () => localAgents?.closeAll(), quit: () => app.quit(),+ /* and the ones opened only to ask (signed in? its options?), which belong to no chat */+ closeAgents: () => { localAgents?.closeAll(); closeEverySession(); }, quit: () => app.quit(),});});diff --git a/apps/desktop/src/preload.cjs b/apps/desktop/src/preload.cjsindex ef64c1f..f82c79f 100644--- a/apps/desktop/src/preload.cjs+++ b/apps/desktop/src/preload.cjs@@ -35,6 +35,7 @@ contextBridge.exposeInMainWorld('openfilmNative', {open: (projectId) => ipcRenderer.invoke('desktop:tabs:new', { projectId }),move: (id, index) => ipcRenderer.invoke('desktop:tabs:move', { id, index }),report: (state) => ipcRenderer.invoke('desktop:tabs:report', state ?? {}),+ retitle: (id, title) => ipcRenderer.invoke('desktop:tabs:retitle', { id, title }),openRequest: (to) => ipcRenderer.invoke('desktop:tabs:open', { to }),onPick: on('desktop:tabs:pick'),},@@ -49,6 +50,9 @@ contextBridge.exposeInMainWorld('openfilmNative', {locate: (id, words) => ipcRenderer.invoke('desktop:agents:locate', { id, words }),useAutomatic: (id) => ipcRenderer.invoke('desktop:agents:automatic', { id }),diagnose: (id) => ipcRenderer.invoke('desktop:agents:diagnose', { id }),+ report: () => ipcRenderer.invoke('desktop:agents:report'),+ /* the whole diagnostic report on the clipboard (main.mjs): the chat's, by a turn that failed */+ copyReport: () => ipcRenderer.invoke('desktop:diagnostics:copy'),saveOwnModel: (config) => ipcRenderer.invoke('desktop:agents:own-model', { config }),removeOwnModel: (id) => ipcRenderer.invoke('desktop:agents:own-model-remove', { id }),/* the MCP servers the person added to it themselves, each let into OpenFilm or not (skills-ipc.mjs) */@@ -87,6 +91,8 @@ contextBridge.exposeInMainWorld('openfilmNative', {log: (project, turnId, unless) => ipcRenderer.invoke('desktop:chat:log', { project, turnId, unless }),reveal: (project, turnId) => ipcRenderer.invoke('desktop:chat:reveal', { project, turnId }),saveRefImage: (project, turnId, n, bytes) => ipcRenderer.invoke('desktop:chat:ref-image', { project, turnId, n, bytes }),+ saveAttachment: (project, name, bytes) => ipcRenderer.invoke('desktop:chat:attachment', { project, name, bytes }),+ describePaths: (paths) => ipcRenderer.invoke('desktop:chat:paths', { paths }),unsaved: (project, except) => ipcRenderer.invoke('desktop:chat:unsaved', { project, except }),snapshot: (project, turnId) => ipcRenderer.invoke('desktop:chat:snapshot', { project, turnId }),changes: (project, turnId) => ipcRenderer.invoke('desktop:chat:changes', { project, turnId }),@@ -109,8 +115,6 @@ contextBridge.exposeInMainWorld('openfilmNative', {set: (next) => ipcRenderer.invoke('desktop:prefs:set', next),onChange: on('desktop:prefs'),},- /* a file on the disk brought into the project (the page has no way to read it) */- importFile: (request) => ipcRenderer.invoke('desktop:import-file', request),/* the chat's column as the person left it, kept for the next launch */saveLayout: (layout) => ipcRenderer.send('desktop:layout', { chatOpen: layout?.chatOpen === true, chatWidth: Number(layout?.chatWidth) }),/* the page's theme, for the window behind it and the system's menus and dialogs */diff --git a/apps/desktop/src/project-versions.test.mjs b/apps/desktop/src/project-versions.test.mjsnew file mode 100644index 0000000..aac009c--- /dev/null+++ b/apps/desktop/src/project-versions.test.mjs@@ -0,0 +1,20 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { deriveProjectTurns } from '../chat/src/lib/project-versions.ts';++const turn = (id, status, extra = {}) => ({+ id, prompt: id, status, createdAt: `2026-10-18T10:00:0${id.length}Z`, updatedAt: `2026-10-18T10:01:0${id.length}Z`, ...extra,+});++test("a failed turn keeps why it failed, for the chat to say after a restart; one that stopped or finished has none", () => {+ const [failed, stopped, done] = deriveProjectTurns([+ turn('a', 'error', { error: 'Kimi: 403 Your current subscription does not have access to Kimi Code right now.' }),+ turn('bb', 'cancelled', { error: 'stopped' }),+ turn('ccc', 'ready'),+ ], [], null);+ assert.equal(failed.outcome, 'failed');+ assert.equal(failed.error, 'Kimi: 403 Your current subscription does not have access to Kimi Code right now.');+ assert.equal(stopped.outcome, 'stopped');+ assert.equal(stopped.error, undefined);+ assert.equal(done.error, undefined);+});diff --git a/apps/desktop/src/turn-log.test.mjs b/apps/desktop/src/turn-log.test.mjsindex 5a506d9..4992422 100644--- a/apps/desktop/src/turn-log.test.mjs+++ b/apps/desktop/src/turn-log.test.mjs@@ -17,7 +17,11 @@ import * as acp from ${JSON.stringify(import.meta.resolve('@agentclientprotocol/const connection = new acp.AgentSideConnection(() => ({async initialize() { return { protocolVersion: acp.PROTOCOL_VERSION, agentCapabilities: { promptCapabilities: { image: true } }, agentInfo: { name: 'fake', version: '1' }, authMethods: [] }; },async newSession() { return { sessionId: 'fake-session' }; },- async prompt(params) { appendFileSync(${JSON.stringify(out)}, JSON.stringify({ argv: process.argv.slice(2), prompt: params.prompt }) + '\\n'); return { stopReason: 'end_turn' }; },+ async prompt(params) {+ appendFileSync(${JSON.stringify(out)}, JSON.stringify({ argv: process.argv.slice(2), prompt: params.prompt }) + '\\n');+ await connection.sessionUpdate({ sessionId: params.sessionId, update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'Done.' } } });+ return { stopReason: 'end_turn' };+ },async cancel() {},}), acp.ndJsonStream(Writable.toWeb(process.stdout), Readable.toWeb(process.stdin)));await connection.closed;diff --git a/packages/openfilm/README.md b/packages/openfilm/README.mdindex a0d6d4a..d0f7485 100644--- a/packages/openfilm/README.md+++ b/packages/openfilm/README.md@@ -26,6 +26,7 @@ openfilm open [folder | url] # show a film in Studio (a GitHub address fetcopenfilm look [what] [t | a-b] # check the film, a page or a media fileopenfilm render [a-b] # the MP4; --4k, --blur, --alphaopenfilm get [what] # voice-over, music, sound effects, transcripts, images, video, from your services+openfilm doctor # what this computer has for OpenFilm, to paste into an issue````MANUAL.md` (in this package) is what `openfilm` tells your agent, and `SPEC.md` is the film format, for anyonediff --git a/packages/openfilm/bin/openfilm.mjs b/packages/openfilm/bin/openfilm.mjsindex 48c5807..cc8b623 100755--- a/packages/openfilm/bin/openfilm.mjs+++ b/packages/openfilm/bin/openfilm.mjs@@ -1,4 +1,5 @@#!/usr/bin/env node+import { setPriority } from 'node:os';import { parseArgs } from 'node:util';const USAGE = `openfilm — a film is a function of time: given t, it draws that moment@@ -9,6 +10,7 @@ const USAGE = `openfilm — a film is a function of time: given t, it draws thatopenfilm get [what] [--options] voice-over, music, sound effects, transcripts, images, video, from a connected serviceopenfilm skills the skills this film can be made with; \`openfilm skill <name>\` prints oneopenfilm update the newest OpenFilm; Studio starts again on it+ openfilm doctor what this computer has for OpenFilm, to paste into an issueRun with no arguments for the manual; \`openfilm <command> --help\` for one command's options; --version for the version.look, render and get work on the project around the current folder.@@ -51,6 +53,12 @@ openfilm skill remove <name>The newest OpenFilm from npm, and Studio started again on it once nothing is being exported or made; pages open onit come back on the new version. The desktop app's Studio updates with the app, a source checkout with git pull:each is said instead.`,+ doctor: `openfilm doctor++ Checks what OpenFilm needs here and prints a report to paste into an issue: OpenFilm's and Node's versions, the+ system, which agent ran the command, Studio, ffmpeg, the browser films are drawn in and its graphics, the data and+ projects folders, npm, and the last errors in Studio's log. Paths under your home folder read ~; no keys, accounts+ or projects are in it. Exit status 1 when something needs fixing; the report says what.`,look: `openfilm look [what] [t | a-b]what the project (default), a web page (.html), or a media file (video, image, sound)@@ -146,10 +154,19 @@ for (const [name, [lo, hi, whole]] of Object.entries(RANGES)) {const commands = {open: () => open(args[0] ?? null),look: () => import('../src/look.mjs').then((m) => m.look(args, opts)),- render: () => import('../src/render.mjs').then((m) => m.render(args, opts)),+ /* below the person's own apps, with every browser and encoder it starts: a render takes the computer whole only+ while nothing else wants it */+ render: () => {+ try { setPriority(10); } catch { /* not allowed here: as it is */ }+ return import('../src/render.mjs').then((m) => m.render(args, opts));+ },update: () => import('../studio/client.mjs').then((m) => m.updateOpenfilm((line) => console.error(line))),skills: () => import('../src/skills-cli.mjs').then((m) => m.skillsCommand(RUN)),skill: () => import('../src/skills-cli.mjs').then((m) => m.skillCommand(args, RUN)),+ doctor: () => import('../src/doctor.mjs').then(async (m) => {+ const report = await m.doctor({ run: RUN });+ return { ok: report.ok, lines: [report.text] };+ }),};/*** Show a project in Studio; `.film/opened` marks a project Studio has shown. A folder named is made a project when it isdiff --git a/packages/openfilm/package.json b/packages/openfilm/package.jsonindex 1e5b92c..f83bf35 100644--- a/packages/openfilm/package.json+++ b/packages/openfilm/package.json@@ -31,6 +31,7 @@"./shared": "./src/shared.mjs","./look": "./src/look.mjs","./render": "./src/render.mjs",+ "./problems": "./src/problems.mjs","./skills": "./src/skills.mjs","./skills-cli": "./src/skills-cli.mjs","./studio": "./studio/server/server.mjs",diff --git a/packages/openfilm/scripts/dev.mjs b/packages/openfilm/scripts/dev.mjsindex b584cbe..8fb6c98 100644--- a/packages/openfilm/scripts/dev.mjs+++ b/packages/openfilm/scripts/dev.mjs@@ -1,17 +1,18 @@#!/usr/bin/env node// @ts-check/**- * `npm run dev`: Studio from this checkout, apart from an installed OpenFilm. Its state, projects and exports are in- * .dev/ (git-ignored), and it listens on port 4848 (OPENFILM_STUDIO_PORT for another). The editor is rebuilt when+ * `npm run dev`: Studio from this checkout, beside an installed OpenFilm. Its state and exports are in .dev/+ * (git-ignored), its projects in the same library as every OpenFilm's (the one ~/.openfilm says, by default+ * ~/Movies/OpenFilm/Projects on macOS), and it listens on port 4848 (OPENFILM_STUDIO_PORT for another). The editor is rebuilt when* studio/ui changes (reload the page); Studio restarts when studio/server or src change. It opens a sample project in* your browser (OPENFILM_NO_BROWSER=1: it only prints the address). Ctrl+C stops it all.** It also writes .dev/bin/openfilm (and openfilm.cmd on Windows): this checkout's command on this Studio, for your own- * agent to try your changes with; and in .dev/projects (this Studio's library) an AGENTS.md and a CLAUDE.md saying so,- * so an agent opened in that folder uses it without being told.+ * agent to try your changes with.*/import { spawn } from 'node:child_process';import { chmodSync, existsSync, mkdirSync, readFileSync, rmSync, watch, writeFileSync } from 'node:fs';+import { homedir } from 'node:os';import { join } from 'node:path';import { fileURLToPath } from 'node:url';@@ -24,8 +25,9 @@ const env = {...process.env,...(existsSync(SKILLS) && !process.env.OPENFILM_OFFICIAL_SKILLS ? { OPENFILM_OFFICIAL_SKILLS: SKILLS } : {}),OPENFILM_HOME: join(DEV, 'home'),- OPENFILM_LIBRARY: join(DEV, 'projects'),OPENFILM_EXPORTS: join(DEV, 'exports'),+ /* the person's library, wherever they chose to keep it (src/locations.mjs) */+ OPENFILM_SHARED_HOME: process.env.OPENFILM_SHARED_HOME || join(homedir(), '.openfilm'),OPENFILM_STUDIO_PORT: process.env.OPENFILM_STUDIO_PORT || '4848',OPENFILM_NO_UPDATE_CHECK: '1',/* Studio itself, without the supervisor `openfilm open` gives it: this script starts it again when its code changes */@@ -52,7 +54,7 @@ process.on('exit', () => {const BIN = join(DEV, 'bin');mkdirSync(BIN, { recursive: true });const CLI = join(ROOT, 'bin', 'openfilm.mjs');-const SHARED = ['OPENFILM_HOME', 'OPENFILM_LIBRARY', 'OPENFILM_EXPORTS', 'OPENFILM_STUDIO_PORT', 'OPENFILM_NO_UPDATE_CHECK', 'OPENFILM_OFFICIAL_SKILLS'].filter((k) => env[k]);+const SHARED = ['OPENFILM_HOME', 'OPENFILM_LIBRARY', 'OPENFILM_SHARED_HOME', 'OPENFILM_EXPORTS', 'OPENFILM_STUDIO_PORT', 'OPENFILM_NO_UPDATE_CHECK', 'OPENFILM_OFFICIAL_SKILLS'].filter((k) => env[k]);const sh = join(BIN, 'openfilm');writeFileSync(sh, `#!/bin/sh\n${SHARED.map((k) => `export ${k}='${env[k]}'`).join('\n')}\nOPENFILM_RUN="${sh}" exec '${process.execPath}' '${CLI}' "$@"\n`);chmodSync(sh, 0o755);@@ -60,25 +62,10 @@ if (process.platform === 'win32') {writeFileSync(join(BIN, 'openfilm.cmd'), `@echo off\r\n${SHARED.map((k) => `set "${k}=${env[k]}"`).join('\r\n')}\r\nset "OPENFILM_RUN=%~f0"\r\n"${process.execPath}" "${CLI}" %*\r\n`);}-/* an agent opened in this Studio's library (Codex reads AGENTS.md, Claude Code CLAUDE.md) makes its films with this- checkout, on this Studio: the skill's `npx openfilm@latest` is the release, on the Studio of an installed OpenFilm */const command = process.platform === 'win32' ? join(BIN, 'openfilm.cmd') : sh;-const AGENT_NOTE = `# Films made with an OpenFilm checkout--This folder is the library of the Studio that \`pnpm dev\` runs from an OpenFilm checkout. Here OpenFilm is that-checkout: wherever a skill or the manual says \`openfilm\` or \`npx openfilm\`, run-- ${command}--and never \`npx openfilm\` (the published version, on another Studio). Run it with no arguments for the manual. Make-each film in a folder of its own here; it shows in that Studio.-`;-mkdirSync(env.OPENFILM_LIBRARY, { recursive: true });-writeFileSync(join(env.OPENFILM_LIBRARY, 'AGENTS.md'), AGENT_NOTE);-writeFileSync(join(env.OPENFILM_LIBRARY, 'CLAUDE.md'), AGENT_NOTE);/* a small film to open: one page, drawn by frame(t) */-const SAMPLE = join(DEV, 'projects', 'Sample');+const SAMPLE = join(DEV, 'sample');if (!existsSync(join(SAMPLE, 'film.html'))) {mkdirSync(SAMPLE, { recursive: true });writeFileSync(join(SAMPLE, 'film.html'), `<meta name="viewport" content="width=1920, height=1080">@@ -147,7 +134,7 @@ for (const end = Date.now() + 30_000; Date.now() < end; await new Promise((r) =>body: JSON.stringify({ path: SAMPLE, now: !quiet, fallback: 0 }),}).catch((e) => ({ ok: false, json: async () => ({ error: e.message }) }));const said = await res.json();- console.log(res.ok ? `\nStudio (dev) ${said.url}\nhome ${env.OPENFILM_HOME}\nyour agent open it in ${env.OPENFILM_LIBRARY} (its AGENTS.md and CLAUDE.md say to run ${command}): this checkout, on this Studio\n` : `\ncould not open the sample: ${said.error}\n`);+ console.log(res.ok ? `\nStudio (dev) ${said.url}\nhome ${env.OPENFILM_HOME}\nyour agent tell it to run ${command}: this checkout, on this Studio\n` : `\ncould not open the sample: ${said.error}\n`);break;}diff --git a/packages/openfilm/src/doctor.mjs b/packages/openfilm/src/doctor.mjsnew file mode 100644index 0000000..3e817fd--- /dev/null+++ b/packages/openfilm/src/doctor.mjs@@ -0,0 +1,238 @@+// @ts-check+/**+ * `openfilm doctor`: what this computer has for OpenFilm, as text a person pastes into an issue. Studio's Settings →+ * Developer copies the same report, with what the browser it is open in can do.+ *+ * Each check is a line: what it is, what was found, and when something is wrong, what to do about it. A path under the+ * home folder reads ~. No keys, accounts, projects or variables' values are in it: of the variables an agent sets, only+ * their names, which say which agent ran the command. After the checks, the problems of the last week (problems.mjs)+ * and the last errors in Studio's log.+ */+import { spawnSync } from 'node:child_process';+import { accessSync, constants, existsSync, readFileSync } from 'node:fs';+import { arch, homedir, platform, release, version as osVersion } from 'node:os';+import { join } from 'node:path';+import { freeSpace, libraryRoot, studioHomeDir } from './locations.mjs';+import { problemLines, problemsFile } from './problems.mjs';++const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version;+const FROM_SOURCE = existsSync(new URL('../studio/ui/src', import.meta.url));+const FFMPEG_HELP = 'macOS: brew install ffmpeg · Debian/Ubuntu: sudo apt install ffmpeg · Windows: winget install ffmpeg';++/** The agents a variable's name tells, by the prefix each one's variables have. */+const AGENT_PREFIXES = /** @type {const} */ ([+ ['CLAUDE', 'Claude Code'], ['CODEX', 'Codex'], ['CURSOR', 'Cursor'], ['COPILOT', 'GitHub Copilot'],+ ['OPENCODE', 'OpenCode'], ['CODEBUDDY', 'CodeBuddy'], ['QWEN', 'Qwen Code'], ['KIMI', 'Kimi'],+]);++/**+ * A path as the report shows it: the home folder as ~.+ * @param {string} path @param {string} [home]+ */+export function tidy(path, home = homedir()) {+ if (!home || home.length < 2) return path;+ const lower = platform() === 'win32';+ const starts = lower ? path.toLowerCase().startsWith(home.toLowerCase()) : path.startsWith(home);+ return starts ? `~${path.slice(home.length)}` : path;+}++/**+ * Which agents ran this, by the names of the variables they set: `{ agents, names }`. Values are never read.+ * @param {Record<string, string | undefined>} env+ */+export function agentHints(env) {+ const names = Object.keys(env).filter((name) => AGENT_PREFIXES.some(([prefix]) => name.toUpperCase().startsWith(prefix))).sort();+ const agents = AGENT_PREFIXES.filter(([prefix]) => names.some((name) => name.toUpperCase().startsWith(prefix))).map(([, label]) => label);+ return { agents, names };+}++/**+ * The lines of studio.log that say something went wrong, the last few, each cut short.+ * @param {string} text @param {number} [count]+ */+export function logTrouble(text, count = 10) {+ /** @type {{ line: string, times: number }[]} */+ const kept = [];+ for (const line of text.split(/\r?\n/)) {+ if (!/error|fail|uncaught|cannot|EACCES|EPERM|ENOENT|EADDRINUSE/i.test(line)) continue;+ const short = line.length > 300 ? `${line.slice(0, 299)}…` : line;+ /* the same line again (a retry, a stack's head) counts once, with how many times */+ if (kept.at(-1)?.line === short) kept[kept.length - 1].times += 1;+ else kept.push({ line: short, times: 1 });+ }+ return kept.slice(-count).map(({ line, times }) => (times > 1 ? `${line} (×${times})` : line));+}++/**+ * A WebGL renderer drawn without the graphics chip: every frame is slow.+ * @param {string | null} renderer+ */+export const softwareRenderer = (renderer) => Boolean(renderer && /swiftshader|llvmpipe|software|basic render/i.test(renderer));++/** @typedef {{ label: string, text: string, problem?: string }} Check */++/**+ * The report as text: one line per check, then what to fix.+ * @param {Check[]} checks @param {string[]} [extra] more lines after the checks (the log's)+ */+export function formatReport(checks, extra = []) {+ const width = Math.max(...checks.map((c) => c.label.length)) + 2;+ const problems = checks.filter((c) => c.problem);+ return [+ 'OpenFilm doctor',+ '',+ ...checks.map((c) => `${c.problem ? '✗' : '✓'} ${c.label.padEnd(width)}${c.text}`),+ ...(problems.length ? ['', 'To fix:', ...problems.map((c) => ` ${c.label}: ${c.problem}`)] : ['', 'Nothing to fix.']),+ ...(extra.length ? ['', ...extra] : []),+ ].join('\n');+}++/** The system's name and version, as a person knows it (macOS 26.6.2, Windows 11 Pro 10.0.26100). */+function systemName() {+ if (platform() === 'darwin') {+ const r = spawnSync('sw_vers', ['-productVersion'], { encoding: 'utf8' });+ const v = r.status === 0 ? r.stdout.trim() : '';+ return `macOS ${v || '(unknown)'} (darwin ${release()}, ${arch()})`;+ }+ return `${osVersion()} ${release()} (${platform()}, ${arch()})`;+}++/** @param {string} bin */+function toolVersion(bin) {+ const r = spawnSync(bin, ['-version'], { encoding: 'utf8', windowsHide: true, timeout: 10_000 });+ if (r.error || r.status !== 0) return null;+ return r.stdout.split(/\r?\n/)[0].replace(new RegExp(`^${bin} version\\s+`), '').split(' ')[0] || '(unknown)';+}++/** @param {string} folder */+function writable(folder) {+ try { accessSync(folder, constants.W_OK); return true; } catch { return false; }+}++/** @param {number | null} bytes */+const gb = (bytes) => (bytes == null ? '' : `, ${(bytes / 1e9).toFixed(bytes < 10e9 ? 1 : 0)} GB free`);++/**+ * The browser films are drawn in: its version, what draws WebGL in it, and the video codecs it decodes on the graphics+ * chip (Chromium's `powerEfficient`), which a film's footage is played with. null when it is not downloaded yet.+ * @returns {Promise<{ version: string, renderer: string | null, chipVideo: string[] } | null>}+ */+async function filmBrowser() {+ const { launch } = await import('./host.mjs');+ let browser;+ try { browser = await launch(); }+ catch (e) { if (/Executable doesn't exist/.test(String(/** @type {Error} */ (e).message))) return null; throw e; }+ try {+ const page = await browser.newPage();+ const renderer = await page.evaluate(() => {+ const gl = document.createElement('canvas').getContext('webgl');+ if (!gl) return null;+ const info = gl.getExtension('WEBGL_debug_renderer_info');+ return String(gl.getParameter(info ? info.UNMASKED_RENDERER_WEBGL : gl.RENDERER));+ });+ const chipVideo = await page.evaluate(async () => {+ const codecs = { 'H.264': 'video/mp4; codecs="avc1.640028"', HEVC: 'video/mp4; codecs="hvc1.1.6.L120.90"', VP9: 'video/webm; codecs="vp09.00.40.08"', AV1: 'video/mp4; codecs="av01.0.08M.08"' };+ const on = [];+ for (const [name, contentType] of Object.entries(codecs)) {+ try {+ const info = await navigator.mediaCapabilities.decodingInfo({ type: 'file', video: { contentType, width: 1920, height: 1080, bitrate: 8e6, framerate: 30 } });+ if (info.powerEfficient) on.push(name);+ } catch { /* not this one */ }+ }+ return on;+ }).catch(() => []);+ return { version: browser.version(), renderer, chipVideo };+ } finally {+ await browser.close().catch(() => {});+ }+}++/** What this machine's ffmpeg does on the graphics chip (encoders.mjs): the encoders that work here, and the decoding. */+async function chipText() {+ const { encoders, hardwareDecoding, hardwareEncoder } = await import('./encoders.mjs');+ const have = await encoders();+ const encoding = (await Promise.all(/** @type {const} */ (['h264', 'hevc', 'prores']).map((codec) => hardwareEncoder(codec, have)))).filter(Boolean);+ const decoding = await hardwareDecoding();+ return `ffmpeg ${encoding.length ? `encodes with ${encoding.join(', ')}` : 'encodes on the processor'}; ${decoding.length ? `decodes with ${decoding[1]}` : 'decodes on the processor'}`;+}++/**+ * Every check, run now. `studio`: the Studio asking, when it is Studio that runs this (it is not looked for then).+ * `browser: false` and `network: false` leave those checks out (tests).+ * @param {{ run?: string, env?: Record<string, string | undefined>, studio?: { origin: string, version: string, app?: boolean } | null,+ * browser?: boolean, network?: boolean, home?: string }} [options]+ */+export async function doctor({ run = 'openfilm', env = process.env, studio = null, browser = true, network = true, home = homedir() } = {}) {+ /** @type {Check[]} */+ const checks = [];+ const at = (/** @type {string} */ path) => tidy(path, home);++ const from = FROM_SOURCE ? 'a source checkout' : studio?.app ? 'the desktop app' : 'npm';+ checks.push({ label: 'OpenFilm', text: `${VERSION} (${from}; run as ${run})` });+ checks.push({ label: 'System', text: systemName() });+ const [major, minor] = process.versions.node.split('.').map(Number);+ const oldNode = major < 22 || (major === 22 && minor < 18);+ checks.push({ label: 'Node', text: `${process.version} (${at(process.execPath)})`, ...(oldNode ? { problem: 'OpenFilm needs Node 22.18 or newer: install it from nodejs.org' } : {}) });++ const { agents, names } = agentHints(env);+ const term = env.TERM_PROGRAM ? `; terminal ${env.TERM_PROGRAM}` : '';+ const shown = names.length > 4 ? `${names.slice(0, 4).join(', ')} and ${names.length - 4} more` : names.join(', ');+ checks.push({ label: 'Run by', text: agents.length ? `${agents.join(', ')} (${shown})${term}` : `no agent's variables${term}` });++ if (studio) {+ checks.push({ label: 'Studio', text: `${studio.version} at ${studio.origin}${studio.app ? ' (the desktop app\'s)' : ''}` });+ } else {+ const { running } = await import('../studio/client.mjs');+ const up = await running().catch(() => null);+ checks.push(up+ ? { label: 'Studio', text: `${up.version ?? '(unknown version)'} at ${up.origin}${up.app ? ' (the desktop app\'s)' : ''}` }+ : { label: 'Studio', text: `not running (\`${run} open\` starts it)` });+ }++ for (const bin of ['ffmpeg', 'ffprobe']) {+ const v = toolVersion(bin);+ checks.push(v ? { label: bin, text: v } : { label: bin, text: 'not found on the PATH', problem: `install ffmpeg (${FFMPEG_HELP})` });+ }+ if (toolVersion('ffmpeg')) checks.push({ label: 'Hardware', text: await chipText() });++ if (browser) {+ try {+ const b = await filmBrowser();+ if (!b) checks.push({ label: 'Browser', text: 'not downloaded yet', problem: `\`${run} open\` downloads it (about 100 MB, once)` });+ else {+ const slow = softwareRenderer(b.renderer);+ const video = b.chipVideo.length ? `video decoded on the chip: ${b.chipVideo.join(', ')}` : 'video decoded by the processor';+ checks.push({ label: 'Browser', text: `Chromium ${b.version}; WebGL ${b.renderer ?? 'unavailable'}; ${video}`,+ ...(slow ? { problem: 'films are drawn without the graphics chip, so looks and renders are slow: update the graphics driver' } : {}) });+ }+ } catch (e) {+ checks.push({ label: 'Browser', text: 'does not start', problem: String(/** @type {Error} */ (e).message).split('\n')[0].slice(0, 300) });+ }+ }++ const data = studioHomeDir();+ const projects = libraryRoot();+ const dataOk = !existsSync(data) || writable(data);+ const projectsOk = !existsSync(projects) || writable(projects);+ checks.push({ label: 'Data', text: `${at(data)}${existsSync(data) ? (dataOk ? '' : ' (not writable)') : ' (not made yet)'}`,+ ...(dataOk ? {} : { problem: `OpenFilm cannot write to ${at(data)}: give your account write access to it` }) });+ checks.push({ label: 'Projects', text: `${at(projects)}${existsSync(projects) ? (projectsOk ? '' : ' (not writable)') : ' (not made yet)'}${gb(freeSpace(projects))}`,+ ...(projectsOk ? {} : { problem: `OpenFilm cannot write to ${at(projects)}: choose another folder in Studio's Settings → General` }) });++ if (network) {+ const reached = await fetch('https://registry.npmjs.org/openfilm', { method: 'HEAD', signal: AbortSignal.timeout(5000) }).then((r) => r.ok, () => false);+ checks.push(reached ? { label: 'Network', text: 'npm reachable' }+ : { label: 'Network', text: 'npm not reachable', problem: 'npx and updates need registry.npmjs.org: check the network, a proxy, or the agent\'s sandbox' });+ }++ const log = join(data, 'logs', 'studio.log');+ const trouble = existsSync(log) ? logTrouble(readFileSync(log, 'utf8')).map((line) => (home.length > 1 ? line.replaceAll(home, '~') : line)) : [];+ const recent = problemLines({ file: problemsFile(data) });+ const extra = [+ ...recent,+ ...(recent.length && trouble.length ? [''] : []),+ ...(trouble.length ? [`Last errors in ${at(log)}:`, ...trouble.map((line) => ` ${line}`)] : []),+ ];++ return { ok: !checks.some((c) => c.problem), checks, text: formatReport(checks, extra) };+}diff --git a/packages/openfilm/src/doctor.test.mjs b/packages/openfilm/src/doctor.test.mjsnew file mode 100644index 0000000..271f010--- /dev/null+++ b/packages/openfilm/src/doctor.test.mjs@@ -0,0 +1,68 @@+import assert from 'node:assert/strict';+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { test } from 'node:test';+import { agentHints, doctor, formatReport, logTrouble, softwareRenderer, tidy } from './doctor.mjs';++test('a path under the home folder reads ~', () => {+ assert.equal(tidy('/Volumes/Home/someone/.openfilm', '/Volumes/Home/someone'), '~/.openfilm');+ assert.equal(tidy('/opt/homebrew/bin/node', '/Volumes/Home/someone'), '/opt/homebrew/bin/node');+});++test('the agent that ran it is told by its variables\' names, never their values', () => {+ const { agents, names } = agentHints({ CLAUDECODE: '1', CLAUDE_CODE_OAUTH_TOKEN: 'secret', PATH: '/bin', CODEX_SANDBOX: 'seatbelt' });+ assert.deepEqual(agents, ['Claude Code', 'Codex']);+ assert.deepEqual(names, ['CLAUDECODE', 'CLAUDE_CODE_OAUTH_TOKEN', 'CODEX_SANDBOX']);+ assert.ok(!JSON.stringify({ agents, names }).includes('secret'));+ assert.deepEqual(agentHints({ PATH: '/bin', TERM_PROGRAM: 'vscode' }).agents, []);+});++test('the log\'s errors: the last few, a repeated one once with its count', () => {+ const log = ['started', 'Error: spawn EBADF', 'Error: spawn EBADF', 'Error: spawn EBADF', 'ok', 'uncaught: boom', 'x'.repeat(400) + ' failed'].join('\n');+ const lines = logTrouble(log);+ assert.deepEqual(lines.slice(0, 2), ['Error: spawn EBADF (×3)', 'uncaught: boom']);+ assert.ok(lines[2].length <= 300 && lines[2].endsWith('…'));+ assert.equal(logTrouble(log, 1).length, 1);+});++test('a WebGL drawn in software is told apart from a graphics chip', () => {+ assert.equal(softwareRenderer('ANGLE (Google, Vulkan 1.3.0 (SwiftShader Device (Subzero)), SwiftShader driver)'), true);+ assert.equal(softwareRenderer('ANGLE (Apple, ANGLE Metal Renderer: Apple M2, Unspecified Version)'), false);+ assert.equal(softwareRenderer(null), false);+});++test('the report lists each check, then what to fix', () => {+ const text = formatReport([{ label: 'Node', text: 'v22.18.0' }, { label: 'ffmpeg', text: 'not found on the PATH', problem: 'install ffmpeg' }]);+ assert.match(text, /✓ Node {4}v22\.18\.0/);+ assert.match(text, /✗ ffmpeg {2}not found on the PATH/);+ assert.match(text, /To fix:\n {2}ffmpeg: install ffmpeg/);+ assert.match(formatReport([{ label: 'Node', text: 'v22' }]), /Nothing to fix\./);+});++test('doctor: the folders and the log, paths under home as ~', async () => {+ const home = mkdtempSync(join(tmpdir(), 'openfilm-doctor-'));+ const data = join(home, '.openfilm');+ mkdirSync(join(data, 'logs'), { recursive: true });+ writeFileSync(join(data, 'logs', 'studio.log'), `2026-10-18T00:00:00Z Error: could not read ${join(home, 'film', 'film.html')}\n`);+ const before = { home: process.env.OPENFILM_HOME, library: process.env.OPENFILM_LIBRARY };+ process.env.OPENFILM_HOME = data;+ process.env.OPENFILM_LIBRARY = join(home, 'Projects');+ try {+ const report = await doctor({ env: { CODEX_SANDBOX: 'seatbelt' }, studio: { origin: 'http://127.0.0.1:4848', version: '0.1.7' }, browser: false, network: false, home });+ assert.match(report.text, /Run by +Codex \(CODEX_SANDBOX\)/);+ assert.match(report.text, /Studio +0\.1\.7 at http:\/\/127\.0\.0\.1:4848/);+ /* what ffmpeg does on the graphics chip here, or that it does it on the processor */+ if (/ffmpeg +\d/.test(report.text)) assert.match(report.text, /Hardware +ffmpeg encodes (with [^;]+|on the processor); decodes (with \S+|on the processor)\n/);+ assert.match(report.text, /Data +~[/\\]\.openfilm/);+ assert.match(report.text, /Projects +~[/\\]Projects \(not made yet\)/);+ assert.match(report.text, /Last errors in ~.*studio\.log:\n {2}.*could not read ~[/\\]film/);+ assert.ok(!report.text.includes(home), 'no full home path');+ assert.ok(!report.text.includes('seatbelt'), 'no variable values');+ } finally {+ for (const [name, value] of [['OPENFILM_HOME', before.home], ['OPENFILM_LIBRARY', before.library]]) {+ if (value === undefined) delete process.env[name]; else process.env[name] = value;+ }+ rmSync(home, { recursive: true, force: true });+ }+});diff --git a/packages/openfilm/src/encoders.mjs b/packages/openfilm/src/encoders.mjsnew file mode 100644index 0000000..8cc70f4--- /dev/null+++ b/packages/openfilm/src/encoders.mjs@@ -0,0 +1,249 @@+// @ts-check+/**+ * The graphics chip's encoders and decoders, for everything that writes video: Studio's exports, `openfilm render`,+ * the fast-seeking copies a render makes (seekable.mjs) and the preview's proxies. Which ones this machine's ffmpeg+ * has, whether each works here (a moment of video goes through it first, once a launch), and the options each takes.+ * A caller uses the processor's own encoder when the chip has none, and when the chip's fails partway (`broken`).+ */+import { execFile, spawn } from 'node:child_process';+import { readdirSync } from 'node:fs';++/** @typedef {'h264' | 'hevc' | 'prores'} ChipCodec */++/** @type {Promise<Set<string>> | null} */+let encoderList = null;+/**+ * The encoders this machine's ffmpeg has (none when there is no ffmpeg). No ffmpeg is asked about again next time:+ * the desktop app downloads it while Studio is already running.+ * @returns {Promise<Set<string>>}+ */+export function encoders() {+ encoderList ??= new Promise((done) => {+ execFile('ffmpeg', ['-hide_banner', '-encoders'], { maxBuffer: 8 << 20, windowsHide: true }, (error, stdout) => {+ if (error) encoderList = null;+ done(new Set(error ? [] : [...String(stdout).matchAll(/^ [VAS][.A-Z]{5} (\S+)/gm)].map((m) => m[1])));+ });+ });+ return encoderList;+}++/** @type {Promise<Set<string>> | null} */+let accelList = null;+/** The hardware decoders this machine's ffmpeg has (`-hwaccels`), asked again while there is no ffmpeg. @returns {Promise<Set<string>>} */+function hwaccels() {+ accelList ??= new Promise((done) => {+ execFile('ffmpeg', ['-hide_banner', '-hwaccels'], { windowsHide: true }, (error, stdout) => {+ if (error) accelList = null;+ done(new Set(error ? [] : String(stdout).split('\n').slice(1).map((l) => l.trim()).filter(Boolean)));+ });+ });+ return accelList;+}++/**+ * The graphics chip's encoders this platform's ffmpeg may have, in the order they are tried: the Mac's own (its media+ * engine, ProRes too); on Windows NVIDIA's, Intel's, AMD's, then Windows' own (Media Foundation, through whichever chip+ * there is); NVIDIA's on Linux.+ */+const HARDWARE = /** @type {Record<string, Partial<Record<ChipCodec, string[]>>>} */ ({+ darwin: { h264: ['h264_videotoolbox'], hevc: ['hevc_videotoolbox'], prores: ['prores_videotoolbox'] },+ win32: { h264: ['h264_nvenc', 'h264_qsv', 'h264_amf', 'h264_mf'], hevc: ['hevc_nvenc', 'hevc_qsv', 'hevc_amf', 'hevc_mf'] },+ linux: { h264: ['h264_nvenc'], hevc: ['hevc_nvenc'] },+});++/**+ * A hardware H.264 or HEVC encoder's options at a bitrate (they take no quality number that means the same on every+ * chip): peaks allowed at half again, for cuts and screen text. `gop`: frames from one key frame to the next (left+ * to itself, the Mac's puts one every 12 frames, and a bitrate spent on key frames is lost to the picture).+ * @param {string} encoder @param {number} bits a second @param {{ gop?: number }} [options]+ */+export function hardwareOptions(encoder, bits, { gop } = {}) {+ const k = (/** @type {number} */ n) => `${Math.round(n / 1000)}k`;+ const rate = ['-b:v', k(bits), '-maxrate', k(bits * 1.5), '-bufsize', k(bits * 2)];+ const hevc = encoder.startsWith('hevc_');+ const tag = [...(hevc ? ['-tag:v', 'hvc1'] : []), ...(gop ? ['-g', String(Math.max(1, Math.round(gop)))] : [])];+ switch (encoder.slice(encoder.indexOf('_') + 1)) {+ case 'videotoolbox': return ['-c:v', encoder, ...(hevc ? [] : ['-profile:v', 'high']), '-b:v', k(bits), ...tag];+ case 'nvenc': return ['-c:v', encoder, '-preset', 'p5', '-rc', 'vbr', ...rate, ...tag];+ case 'qsv': return ['-c:v', encoder, '-preset', 'medium', ...rate, ...tag];+ case 'amf': return ['-c:v', encoder, '-quality', 'quality', '-rc', 'vbr_peak', ...rate, ...tag];+ /* the chip's own encoder, never Windows' software one (x264 is better at that) */+ case 'mf': return ['-c:v', encoder, '-hw_encoding', '1', '-rate_control', 'u_vbr', '-b:v', k(bits), ...tag];+ default: return ['-c:v', encoder, '-b:v', k(bits), ...tag];+ }+}++/**+ * ProRes 4444 with its alpha, or 422 HQ: through the Mac's ProRes engine (`prores_videotoolbox`, Apple's own+ * encoder), else ffmpeg's. `video`: the encoder's options; `pix`: the pixel format it takes, as a filter.+ * @param {string} encoder @param {boolean} alpha+ */+export function proresOptions(encoder, alpha) {+ if (encoder === 'prores_videotoolbox') return { video: ['-c:v', encoder, '-profile:v', alpha ? '4444' : 'hq'], pix: alpha ? 'format=bgra' : 'format=p210le' };+ return { video: ['-c:v', 'prores_ks', '-profile:v', alpha ? '4444' : '3', '-vendor', 'apl0'], pix: alpha ? 'format=yuva444p10le' : 'format=yuv422p10le' };+}++/** @type {Map<string, Promise<boolean>>} */+const tried = new Map();+/**+ * Whether a hardware encoder works on this machine: one built into ffmpeg may have no chip or driver behind it (a Mac+ * without a ProRes engine, a PC without that maker's chip), so a moment of video goes through it first (once a+ * launch; `broken` remembers one that failed after that).+ * @param {string} encoder+ */+function works(encoder) {+ if (!tried.has(encoder)) {+ const prores = encoder.startsWith('prores_') ? proresOptions(encoder, true) : null;+ const options = prores ? ['-vf', prores.pix, ...prores.video] : ['-vf', 'format=yuv420p', ...hardwareOptions(encoder, 2e6)];+ tried.set(encoder, new Promise((done) => {+ execFile('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-f', 'lavfi', '-i', 'testsrc2=size=640x360:rate=30', '-frames:v', '10',+ ...options, '-f', 'null', '-'], { timeout: 20_000, windowsHide: true }, (error) => done(!error));+ }));+ }+ return /** @type {Promise<boolean>} */ (tried.get(encoder));+}++/** A hardware encoder that failed partway: the rest of this launch uses another. @param {string} encoder */+export const broken = (encoder) => { tried.set(encoder, Promise.resolve(false)); };++/**+ * The first hardware encoder for H.264, HEVC or ProRes that works here, or null.+ * @param {ChipCodec} codec @param {Set<string>} have @param {string} [platform]+ */+export async function hardwareEncoder(codec, have, platform = process.platform) {+ for (const encoder of HARDWARE[platform]?.[codec] ?? []) if (have.has(encoder) && await works(encoder)) return encoder;+ return null;+}++/** Linux's render nodes (`/dev/dri/renderD128`…), the way to a chip's VA-API without a display. */+function renderNodes() {+ try { return readdirSync('/dev/dri').filter((n) => /^renderD\d+$/.test(n)).sort().map((n) => `/dev/dri/${n}`); } catch { return []; }+}++/**+ * The graphics chip's decoders a platform's ffmpeg may have, in the order they are tried, as the input options that+ * turn each on: the Mac's media engine; on Windows Direct3D 11's, which every maker's chip has, then NVIDIA's own; on+ * Linux VA-API's (Intel's and AMD's) through the first render node, then NVIDIA's. With no output format asked, each+ * hands its frames back to memory, where any filter and either kind of encoder takes them.+ * @param {string} [platform] @param {string[]} [nodes] Linux's render nodes+ * @returns {string[][]}+ */+export function decoderCandidates(platform = process.platform, nodes = platform === 'linux' ? renderNodes() : []) {+ if (platform === 'darwin') return [['-hwaccel', 'videotoolbox']];+ if (platform === 'win32') return [['-hwaccel', 'd3d11va'], ['-hwaccel', 'cuda']];+ if (platform === 'linux') return [...(nodes.length ? [['-hwaccel', 'vaapi', '-hwaccel_device', nodes[0]]] : []), ['-hwaccel', 'cuda']];+ return [];+}++/** A moment of H.264 (ten frames, raw), for trying decoders on; null when this ffmpeg can't make one. @returns {Promise<Buffer | null>} */+function sampleH264() {+ return new Promise((done) => {+ execFile('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-f', 'lavfi', '-i', 'testsrc2=size=640x360:rate=30', '-frames:v', '10',+ '-c:v', 'libx264', '-pix_fmt', 'yuv420p', '-f', 'h264', 'pipe:1'], { encoding: 'buffer', maxBuffer: 16 << 20, timeout: 20_000, windowsHide: true },+ (error, stdout) => done(error || !stdout.length ? null : stdout));+ });+}++/**+ * `sample` decoded with these input options, as the MD5 of its frames in 8-bit 4:2:0; null when it does not decode. A+ * decoder whose device does not open (no chip, no driver, a virtual machine) fails at once. H.264 decodes to the same+ * pixels on every correct decoder, so a chip whose frames differ from the processor's has a driver that is wrong.+ * @param {string[]} options @param {Buffer} sample @returns {Promise<string | null>}+ */+function decodedMd5(options, sample) {+ return new Promise((done) => {+ const proc = spawn('ffmpeg', ['-hide_banner', '-loglevel', 'error', ...options, '-f', 'h264', '-i', 'pipe:0', '-pix_fmt', 'yuv420p', '-f', 'md5', '-'],+ { stdio: ['pipe', 'pipe', 'ignore'], windowsHide: true });+ let out = '';+ proc.stdout.on('data', (d) => { out += d; });+ const timer = setTimeout(() => proc.kill('SIGKILL'), 20_000);+ proc.on('error', () => { clearTimeout(timer); done(null); });+ proc.on('close', (code) => { clearTimeout(timer); done(code === 0 && /^MD5=\w+$/.test(out.trim()) ? out.trim() : null); });+ proc.stdin.on('error', () => {});+ proc.stdin.end(sample);+ });+}++/** @type {Promise<string[]> | null} */+let decoding = null;+/**+ * The input options that decode footage on the graphics chip here, or none: the first of decoderCandidates this+ * ffmpeg has that decodes a moment of H.264 to the processor's very pixels (once a launch). What the chip can't take (a+ * codec, a bit depth, a size) ffmpeg decodes on the processor by itself; a chip that fails partway is left out from+ * then on (`onTheChip`).+ * @returns {Promise<string[]>}+ */+export function hardwareDecoding() {+ decoding ??= (async () => {+ const built = await hwaccels();+ const candidates = decoderCandidates().filter((options) => built.has(options[1]));+ const sample = candidates.length ? await sampleH264() : null;+ const expected = sample ? await decodedMd5([], sample) : null;+ if (sample && expected) for (const options of candidates) if (await decodedMd5(options, sample) === expected) return options;+ return [];+ })();+ return decoding;+}++/**+ * A conversion on the chip, and again without what failed: `make(encoder, decoding)` with the chip's decoding and+ * `encoder` (either may be none), then with the processor's decoding, then with the processor for both (`encoder`+ * null). What made the difference is left out for the rest of this launch: the chip's decoding when the same encoder+ * then worked, else the chip's encoder. Cancelled (`signal`), it is not tried again.+ * @template T+ * @param {string | null} encoder @param {(encoder: string | null, decoding: string[]) => Promise<T>} make+ * @param {AbortSignal} [signal] @returns {Promise<T>}+ */+export async function onTheChip(encoder, make, signal) {+ const chip = await hardwareDecoding();+ const tries = /** @type {[string | null, string[]][]} */ ([[encoder, chip], [encoder, []], [null, []]])+ .filter(([e, d], i, all) => all.findIndex(([e2, d2]) => e2 === e && d2.length === d.length) === i);+ /** @type {string | null | undefined} the encoder of the try that failed last */+ let failed;+ for (const [i, [e, d]] of tries.entries()) {+ try {+ const made = await make(e, d);+ if (failed !== undefined) {+ if (failed === e) decoding = Promise.resolve([]);+ else if (failed) broken(failed);+ }+ return made;+ } catch (error) {+ if (signal?.aborted || i === tries.length - 1) throw error;+ failed = e;+ }+ }+ throw new Error('no conversion was tried');+}++/* the codes of H.273 (what an H.264 stream says), by the names ffprobe gives */+const PRIMARIES = /** @type {Record<string, number>} */ ({ bt709: 1, bt470m: 4, bt470bg: 5, smpte170m: 6, smpte240m: 7, film: 8, bt2020: 9, smpte428: 10, smpte431: 11, smpte432: 12, 'jedec-p22': 22 });+const TRANSFERS = /** @type {Record<string, number>} */ ({ bt709: 1, gamma22: 4, gamma28: 5, smpte170m: 6, smpte240m: 7, linear: 8, log100: 9, log316: 10, 'iec61966-2-4': 11, bt1361e: 12, 'iec61966-2-1': 13, 'bt2020-10': 14, 'bt2020-12': 15, smpte2084: 16, smpte428: 17, 'arib-std-b67': 18 });+const MATRICES = /** @type {Record<string, number>} */ ({ gbr: 0, bt709: 1, fcc: 4, bt470bg: 5, smpte170m: 6, smpte240m: 7, ycgco: 8, bt2020nc: 9, bt2020c: 10, smpte2085: 11, 'chroma-derived-nc': 12, 'chroma-derived-c': 13, ictcp: 14 });++/**+ * A source's color tags written into the H.264 stream of its copy (`h264_metadata`): a chip's encoder drops the ones+ * it has no key for (the sRGB transfer screen recordings carry), and a copy must show as its source does. Empty when+ * the source says nothing.+ * @param {{ color_primaries?: string, color_transfer?: string, color_space?: string, color_range?: string }} tags+ */+export function h264ColorTags(tags) {+ const parts = [];+ const code = (/** @type {Record<string, number>} */ table, /** @type {string | undefined} */ name) => (name && Object.hasOwn(table, name) ? table[name] : null);+ const primaries = code(PRIMARIES, tags.color_primaries), transfer = code(TRANSFERS, tags.color_transfer), matrix = code(MATRICES, tags.color_space);+ if (primaries != null) parts.push(`colour_primaries=${primaries}`);+ if (transfer != null) parts.push(`transfer_characteristics=${transfer}`);+ if (matrix != null) parts.push(`matrix_coefficients=${matrix}`);+ if (tags.color_range === 'tv' || tags.color_range === 'pc') parts.push(`video_full_range_flag=${tags.color_range === 'pc' ? 1 : 0}`);+ return parts.length ? ['-bsf:v', `h264_metadata=${parts.join(':')}`] : [];+}++/** The color tags of a video's first picture stream (none when ffprobe can't say). @param {string} file */+export function colorTagsOf(file) {+ return new Promise((done) => {+ execFile('ffprobe', ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=color_primaries,color_transfer,color_space,color_range', '-of', 'json', file],+ { windowsHide: true }, (error, stdout) => {+ try { done(error ? {} : JSON.parse(String(stdout)).streams?.[0] ?? {}); } catch { done({}); }+ });+ });+}diff --git a/packages/openfilm/src/encoders.test.mjs b/packages/openfilm/src/encoders.test.mjsnew file mode 100644index 0000000..ce1f883--- /dev/null+++ b/packages/openfilm/src/encoders.test.mjs@@ -0,0 +1,129 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { execFileSync } from 'node:child_process';+import { mkdtempSync, rmSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { colorTagsOf, decoderCandidates, encoders, h264ColorTags, hardwareDecoding, hardwareEncoder, hardwareOptions, onTheChip, proresOptions } from './encoders.mjs';++const hasFfmpeg = (() => { try { execFileSync('ffmpeg', ['-version'], { stdio: 'ignore' }); return true; } catch { return false; } })();+const ffmpeg = { skip: !hasFfmpeg && 'no ffmpeg', timeout: 120_000 };++test('each graphics chip\'s encoder gets a bitrate it keeps to, a key frame interval when asked, and HEVC tagged for Apple players', () => {+ for (const encoder of ['h264_videotoolbox', 'h264_nvenc', 'h264_qsv', 'h264_amf', 'h264_mf', 'hevc_videotoolbox', 'hevc_nvenc', 'hevc_qsv', 'hevc_amf', 'hevc_mf']) {+ const options = hardwareOptions(encoder, 8e6);+ assert.deepEqual(options.slice(0, 2), ['-c:v', encoder]);+ assert.equal(options[options.indexOf('-b:v') + 1], '8000k', encoder);+ assert.equal(options.includes('hvc1'), encoder.startsWith('hevc_'), encoder);+ assert.ok(!options.includes('-g'), `${encoder}: its own interval unless asked`);+ const keyed = hardwareOptions(encoder, 8e6, { gop: 59.94 });+ assert.equal(keyed[keyed.indexOf('-g') + 1], '60', encoder);+ }+ assert.ok(hardwareOptions('h264_mf', 8e6).join(' ').includes('-hw_encoding 1'), 'never Windows\' software encoder');+});++test('ProRes: 4444 keeps its alpha and 422 HQ its ten bits, on the Mac\'s ProRes engine or with ffmpeg\'s own encoder', () => {+ assert.deepEqual(proresOptions('prores_videotoolbox', true), { video: ['-c:v', 'prores_videotoolbox', '-profile:v', '4444'], pix: 'format=bgra' });+ assert.deepEqual(proresOptions('prores_videotoolbox', false), { video: ['-c:v', 'prores_videotoolbox', '-profile:v', 'hq'], pix: 'format=p210le' });+ assert.deepEqual(proresOptions('prores_ks', true), { video: ['-c:v', 'prores_ks', '-profile:v', '4444', '-vendor', 'apl0'], pix: 'format=yuva444p10le' });+ assert.deepEqual(proresOptions('prores_ks', false), { video: ['-c:v', 'prores_ks', '-profile:v', '3', '-vendor', 'apl0'], pix: 'format=yuv422p10le' });+});++test('a hardware encoder is used only when this ffmpeg has it and it works', ffmpeg, async () => {+ assert.equal(await hardwareEncoder('h264', new Set(['libx264']), 'win32'), null, 'none built in');+ assert.equal(await hardwareEncoder('h264', new Set(['h264_nvenc']), 'darwin'), null, 'not one of this platform\'s');+ assert.equal(await hardwareEncoder('prores', new Set(['prores_videotoolbox']), 'win32'), null, 'ProRes on the chip is the Mac\'s');+ const have = await encoders();+ if (process.platform === 'darwin' && have.has('h264_videotoolbox')) {+ assert.equal(await hardwareEncoder('h264', have), 'h264_videotoolbox');+ assert.equal(await hardwareEncoder('hevc', have), have.has('hevc_videotoolbox') ? 'hevc_videotoolbox' : null);+ }+});++test('each system\'s decoders, in the order tried: the Mac\'s media engine; Direct3D 11, then NVIDIA\'s; VA-API through a render node, then NVIDIA\'s', () => {+ assert.deepEqual(decoderCandidates('darwin'), [['-hwaccel', 'videotoolbox']]);+ assert.deepEqual(decoderCandidates('win32'), [['-hwaccel', 'd3d11va'], ['-hwaccel', 'cuda']]);+ assert.deepEqual(decoderCandidates('linux', ['/dev/dri/renderD128', '/dev/dri/renderD129']), [['-hwaccel', 'vaapi', '-hwaccel_device', '/dev/dri/renderD128'], ['-hwaccel', 'cuda']]);+ assert.deepEqual(decoderCandidates('linux', []), [['-hwaccel', 'cuda']], 'no render node: no VA-API');+ assert.deepEqual(decoderCandidates('freebsd'), []);+});++test('the chip\'s decoding is one that decodes here, or none; footage decodes either way', ffmpeg, async () => {+ const decoding = await hardwareDecoding();+ assert.ok(decoding.length === 0 || decoderCandidates().some((c) => c.join(' ') === decoding.join(' ')), decoding.join(' '));+ const dir = mkdtempSync(join(tmpdir(), 'of-decoding-'));+ try {+ const src = join(dir, 'in.mp4');+ execFileSync('ffmpeg', ['-v', 'error', '-y', '-f', 'lavfi', '-i', 'testsrc2=s=320x180:r=30:d=0.5', '-c:v', 'libx264', '-pix_fmt', 'yuv420p', src]);+ const frames = execFileSync('ffmpeg', ['-v', 'error', ...decoding, '-i', src, '-vf', 'scale=160:90', '-f', 'framecrc', '-']).toString().split('\n').filter((l) => /^0,/.test(l));+ assert.equal(frames.length, 15);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test('a conversion that fails on the chip is made again without what failed', ffmpeg, async () => {+ const chip = await hardwareDecoding();+ /** @param {string | null} encoder @param {string[]} failing the tries that throw, as `encoder+decoding` */+ const run = async (encoder, failing) => {+ const seen = [];+ const result = await onTheChip(encoder, async (e, d) => {+ seen.push(`${e ?? 'cpu'}+${d.length ? 'chip' : 'cpu'}`);+ if (failing.includes(seen.at(-1))) throw new Error(`ffmpeg: ${seen.at(-1)} failed`);+ return seen.at(-1);+ });+ return { result, seen };+ };+ assert.deepEqual(await run('fake_encoder', []), { result: `fake_encoder+${chip.length ? 'chip' : 'cpu'}`, seen: [`fake_encoder+${chip.length ? 'chip' : 'cpu'}`] });+ /* the encoder fails with either decoding: the processor's encoder */+ const encoderFails = await run('fake_encoder', ['fake_encoder+chip', 'fake_encoder+cpu']);+ assert.deepEqual(encoderFails.seen, [...(chip.length ? ['fake_encoder+chip'] : []), 'fake_encoder+cpu', 'cpu+cpu']);+ assert.equal(encoderFails.result, 'cpu+cpu');+ await assert.rejects(run(null, ['cpu+chip', 'cpu+cpu']), /ffmpeg: cpu\+cpu failed/, 'what fails on the processor too is the source\'s');+ const stopped = new AbortController();+ stopped.abort();+ await assert.rejects(onTheChip('fake_encoder', async () => { throw new Error('ffmpeg: cancelled'); }, stopped.signal), /cancelled/);+ if (chip.length) {+ /* the chip's decoding fails where the processor's works with the same encoder: it is left out from then on */+ const decodingFails = await run('fake_encoder', ['fake_encoder+chip']);+ assert.deepEqual(decodingFails.seen, ['fake_encoder+chip', 'fake_encoder+cpu']);+ assert.deepEqual(await hardwareDecoding(), []);+ }+});++test('a copy keeps its source\'s color tags, by their H.273 codes', () => {+ assert.deepEqual(h264ColorTags({ color_primaries: 'bt709', color_transfer: 'iec61966-2-1', color_space: 'bt709', color_range: 'tv' }),+ ['-bsf:v', 'h264_metadata=colour_primaries=1:transfer_characteristics=13:matrix_coefficients=1:video_full_range_flag=0']);+ assert.deepEqual(h264ColorTags({ color_primaries: 'bt2020', color_transfer: 'arib-std-b67', color_space: 'bt2020nc', color_range: 'pc' }),+ ['-bsf:v', 'h264_metadata=colour_primaries=9:transfer_characteristics=18:matrix_coefficients=9:video_full_range_flag=1']);+ assert.deepEqual(h264ColorTags({ color_primaries: 'unknown', color_transfer: 'unknown', color_space: 'unknown', color_range: 'unknown' }), []);+ assert.deepEqual(h264ColorTags({}), []);+ assert.deepEqual(h264ColorTags({ color_transfer: 'constructor' }), [], 'only the names ffprobe gives');+});++test('on a Mac with a ProRes engine, ProRes keeps half alpha; the chip\'s H.264 keeps an sRGB transfer when told it', ffmpeg, async (t) => {+ const have = await encoders();+ if (process.platform !== 'darwin' || !have.has('h264_videotoolbox')) { t.skip('no VideoToolbox here'); return; }+ const dir = mkdtempSync(join(tmpdir(), 'of-encoders-'));+ try {+ const prores = await hardwareEncoder('prores', have);+ if (prores) {+ const { video, pix } = proresOptions(prores, true);+ const mov = join(dir, 'half.mov');+ execFileSync('ffmpeg', ['-v', 'error', '-y', '-f', 'lavfi', '-i', '[email protected]:s=320x180:r=30:d=0.2,format=rgba', '-vf', pix, ...video, mov]);+ const alpha = execFileSync('ffmpeg', ['-v', 'error', '-i', mov, '-frames:v', '1', '-vf', 'format=rgba', '-f', 'rawvideo', '-']).filter((_, i) => i % 4 === 3);+ assert.ok(alpha.every((a) => Math.abs(a - 128) <= 2), `alpha ${alpha[0]}`);+ }+ const src = join(dir, 'srgb.mp4');+ execFileSync('ffmpeg', ['-v', 'error', '-y', '-f', 'lavfi', '-i', 'testsrc2=s=320x180:r=30:d=0.5', '-c:v', 'libx264', '-pix_fmt', 'yuv420p',+ '-bsf:v', 'h264_metadata=colour_primaries=1:transfer_characteristics=13:matrix_coefficients=1', src]);+ const tags = await colorTagsOf(src);+ assert.equal(tags.color_transfer, 'iec61966-2-1');+ const copy = join(dir, 'copy.mp4');+ execFileSync('ffmpeg', ['-v', 'error', '-y', ...(await hardwareDecoding()), '-i', src, '-pix_fmt', 'nv12',+ ...hardwareOptions('h264_videotoolbox', 4e6, { gop: 8 }), ...h264ColorTags(tags), copy]);+ assert.equal((await colorTagsOf(copy)).color_transfer, 'iec61966-2-1');+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});diff --git a/packages/openfilm/src/film-doc.d.mts b/packages/openfilm/src/film-doc.d.mtsindex 9c92446..c75e327 100644--- a/packages/openfilm/src/film-doc.d.mts+++ b/packages/openfilm/src/film-doc.d.mts@@ -86,6 +86,8 @@ export declare const SPEED_MAX: number;export declare function isStill(src: string): boolean;export declare function isPage(src: string): boolean;+/** A clip's src as an address: its path with `%`, `#` and `?` escaped; a src with a scheme as written. */+export declare function srcHref(src: string): string;export declare function soundRole(src: string): 'voice' | 'music' | 'sfx';export declare function clipKind(src: unknown): FilmClipKind | null;export declare function hasPicture(src: unknown): boolean;diff --git a/packages/openfilm/src/film-doc.mjs b/packages/openfilm/src/film-doc.mjsindex ebf7ee1..4cda326 100644--- a/packages/openfilm/src/film-doc.mjs+++ b/packages/openfilm/src/film-doc.mjs@@ -51,6 +51,23 @@ export function soundRole(src) {return 'voice';}+/* a src with a scheme (https:, data:) is an address, kept as written; any other is the path of a file */+const ADDRESS = /^[a-z][a-z0-9+.-]*:/i;++/**+ * A clip's src as an address: its file's path with the three characters an address reads otherwise escaped (`%` an+ * escape, `#` the part of the file, `?` a query). Any other character, a space or a Chinese comma, is written as is.+ */+export function srcHref(src) {+ return ADDRESS.test(src) ? src : src.replace(/[%#?]/g, (c) => encodeURIComponent(c));+}++/** The path a src attribute names: its escapes read (`%23` is `#`), a `%` that escapes nothing kept as it is. */+function srcPath(value) {+ if (ADDRESS.test(value)) return value;+ return value.replace(/(?:%[0-9a-f]{2})+/gi, (m) => { try { return decodeURIComponent(m); } catch { return m; } });+}+/** A web page clip: an .html file that sets `window.film` (SPEC.md). */export function isPage(src) {return /\.html?$/i.test(src);@@ -494,7 +511,7 @@ const NOT_OF_KIND = {};/**- * What an agent writes from elsewhere (other editors, web pages, HyperFrames), answered with what it is here.+ * What an agent writes from elsewhere (other editors' and video formats, web pages), answered with what it is here.*/const ATTRIBUTE_HINTS = {time: 'the part of the file goes on src as a media fragment: src="a.mp4#t=2,6" (its seconds 2 to 6)',@@ -679,13 +696,13 @@ function clipOfTag(tag, where, problems) {if (name === 'id') { if (value) raw.id = value; }else if (name === 'src') {const hash = value.indexOf('#');- raw.src = hash < 0 ? value : value.slice(0, hash);+ raw.src = srcPath(hash < 0 ? value : value.slice(0, hash));if (hash >= 0) {const m = /^t=([^,]*)(?:,(.*))?$/.exec(value.slice(hash + 1));const from = m ? fragmentSeconds(m[1]) : NaN;const to = m && m[2] !== undefined ? fragmentSeconds(m[2]) : undefined;if (!m || !Number.isFinite(from) || (to !== undefined && !Number.isFinite(to))) {- problems.push(`${where}: src's fragment says which seconds of the file it plays, like src="a.mp4#t=2,6" (2 s to 6 s) or "#t=2" (2 s to the end) — "${value.slice(hash)}" is not that.`);+ problems.push(`${where}: src's fragment says which seconds of the file it plays, like src="a.mp4#t=2,6" (2 s to 6 s) or "#t=2" (2 s to the end) — "${value.slice(hash)}" is not that.${m ? '' : ' A # in the file\'s name is written %23.'}`);} else if (to !== undefined) raw.time = [from, to];else if (from > 0) raw.time = [from];}@@ -877,7 +894,7 @@ export function clipTag(clip) {const tag = TAG_OF_KIND[kind];const t = clip.time;const num = (n) => String(Number(n.toFixed(3)));- const src = clip.src + (t ? (t.length === 2 ? `#t=${num(t[0])},${num(t[1])}` : `#t=${num(t[0])}`) : '');+ const src = srcHref(clip.src) + (t ? (t.length === 2 ? `#t=${num(t[0])},${num(t[1])}` : `#t=${num(t[0])}`) : '');const parts = [];if (clip.id) parts.push(`id="${escapeAttr(clip.id)}"`);parts.push(`src="${escapeAttr(src)}"`);diff --git a/packages/openfilm/src/film-doc.test.mjs b/packages/openfilm/src/film-doc.test.mjsindex 28829c8..a04f198 100644--- a/packages/openfilm/src/film-doc.test.mjs+++ b/packages/openfilm/src/film-doc.test.mjs@@ -1,6 +1,6 @@import { test } from 'node:test';import assert from 'node:assert/strict';-import { clipFade, clipIdFor, clipKind, clipSpan, fadeGain, filmHtml, kindOf, parseFilm, pictureRect, readFilm, readFilmFile, soundRole, sourceAt } from './film-doc.mjs';+import { clipFade, clipIdFor, clipKind, clipSpan, fadeGain, filmHtml, kindOf, parseFilm, pictureRect, readFilm, readFilmFile, soundRole, sourceAt, srcHref } from './film-doc.mjs';const film = (clip) => ({ stage: { w: 1920, h: 1080 }, tracks: [{ clips: [clip] }] });const problems = (value) => readFilm(value).problems.join('\n');@@ -62,6 +62,30 @@ test('a clip written without an id gets its name written, so it stays put', () =assert.match(filmHtml(value, text), /<audio id="line" src="vo\/line.m4a"><\/audio>\n {2}<audio id="line-2" src="vo\/line.m4a" at="3"><\/audio>/);});+test('a file\'s name may hold any character: src escapes only %, # and ?, and reads back the same path', () => {+ const names = ['assets/a#b.png', 'assets/what?.png', 'assets/100%.png', 'assets/a%20b.png', 'assets/封面,标题!.png', "assets/it's (1) [v2] & co.png"];+ const value = { stage: { w: 1920, h: 1080 }, tracks: [{ clips: names.map((src, i) => ({ id: `c${i}`, src, at: i, time: [0, 1] })) }] };+ const text = filmHtml(value);+ assert.match(text, /src="assets\/a%23b\.png#t=0,1"/);+ assert.match(text, /src="assets\/what%3F\.png#t=0,1"/);+ assert.match(text, /src="assets\/100%25\.png#t=0,1"/);+ assert.match(text, /src="assets\/a%2520b\.png#t=0,1"/);+ assert.match(text, /src="assets\/封面,标题!\.png#t=0,1"/, 'written as it is');+ const { doc, problems: said } = readFilmFile(text);+ assert.deepEqual(said, []);+ assert.deepEqual(doc.tracks[0].clips.map((c) => c.src), names);+ assert.deepEqual(doc.tracks[0].clips.map((c) => c.time), names.map(() => [0, 1]));+});++test('a src written by hand: its escapes are read, a bare % is a %, an address is kept, a # in a name is told', () => {+ const srcs = (els) => readFilmFile(page([els])).doc.tracks[0].clips.map((c) => c.src);+ assert.deepEqual(srcs(['<img src="assets/my%20file.png#t=0,2">', '<img src="assets/100%.png#t=0,2" at="2">', '<img src="assets/%E5%9B%BE.png#t=0,2" at="4">']),+ ['assets/my file.png', 'assets/100%.png', 'assets/图.png']);+ assert.deepEqual(srcs(['<video src="https://x.test/a%20b.mp4"></video>']), ['https://x.test/a%20b.mp4']);+ assert.match(said(page([['<img src="assets/a#b.png#t=0,2">']])), /A # in the file's name is written %23/);+ assert.equal(srcHref('https://x.test/a.mp4?v=1#x'), 'https://x.test/a.mp4?v=1#x');+});+test('a new film is a whole page; a box at 0, 0 is written as one', () => {const out = filmHtml({ stage: { w: 1080, h: 1920 }, tracks: [{ clips: [{ src: 'a.mp4', id: 'a', box: { x: 0, y: 0 }, time: [0, 2] }] }] });assert.equal(out, '<!doctype html>\n<html>\n<head>\n<meta charset="utf-8">\n<meta name="viewport" content="width=1080, height=1920">\n</head>\n<body>\n'diff --git a/packages/openfilm/src/host.mjs b/packages/openfilm/src/host.mjsindex 6db498f..800778f 100644--- a/packages/openfilm/src/host.mjs+++ b/packages/openfilm/src/host.mjs@@ -466,7 +466,9 @@ export class FilmPage {async capture({ format = 'png', quality } = {}) {// Without a clip, headless Chromium returns CSS pixels; a clip at the device pixel ratio returns real pixels.const clip = { x: 0, y: 0, width: this.meta.width, height: this.meta.height, scale: this.scale };- const { data } = await inTime(this.cdp.send('Page.captureScreenshot', { format, quality, clip, fromSurface: true, optimizeForSpeed: format !== 'png' }),+ // Fast compression, for a PNG too: the same pixels in a larger file, two to four times sooner (a 4K frame of+ // footage: 240 ms instead of a second).+ const { data } = await inTime(this.cdp.send('Page.captureScreenshot', { format, quality, clip, fromSurface: true, optimizeForSpeed: true }),CAPTURE_MS, `the picture did not come within ${CAPTURE_MS / 1000} s`);return Buffer.from(data, 'base64');}diff --git a/packages/openfilm/src/locations.mjs b/packages/openfilm/src/locations.mjsindex 020d82d..9da9e99 100644--- a/packages/openfilm/src/locations.mjs+++ b/packages/openfilm/src/locations.mjs@@ -1,21 +1,26 @@// @ts-check/**- * Where OpenFilm keeps the person's work on this computer: the projects library (where new projects go) and the- * exports folder. The library has a default and may be moved in Studio's Settings → General: Studio's `prefs.json`- * (`projectsFolder`), read by Studio and by the `openfilm` command alike, so a project fetched from the command line- * lands where Studio's go. OPENFILM_LIBRARY sets the default (a build, or a Studio kept apart); what the person chose- * comes first. Projects made before stay where they are: the projects list knows them by their folder. Exports go to- * the folder picked when exporting (the export dialog keeps the last one), else to the exports default.+ * Where OpenFilm keeps the person's work on this computer: the projects library (one folder per project, the folders+ * Studio's Projects list shows) and the exports folder. The library has a default and may be moved in Studio's+ * Settings → General: Studio's `prefs.json` (`projectsFolder`), read by Studio and by the `openfilm` command alike, so+ * a project fetched from the command line lands where Studio's go. A Studio with a home of its own (OPENFILM_HOME, as+ * `pnpm dev` and the desktop app's dev and preview builds have) shares the person's library when OPENFILM_SHARED_HOME+ * names the home that keeps it (~/.openfilm). OPENFILM_LIBRARY sets the default (a build, or a Studio kept apart);+ * what the person chose comes first. Exports go to the folder picked when exporting (the export dialog keeps the last+ * one), else to the exports default.** Reads no Studio module, so the command can use it.*/-import { accessSync, constants, existsSync, mkdirSync, readFileSync, statfsSync } from 'node:fs';+import { accessSync, constants, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, statfsSync, writeFileSync } from 'node:fs';import { homedir } from 'node:os';import { dirname, isAbsolute, join, resolve, sep } from 'node:path';/** Studio's own home (its settings and keys, not the person's work): OPENFILM_HOME, else ~/.openfilm. */export const studioHomeDir = () => process.env.OPENFILM_HOME || join(homedir(), '.openfilm');+/** The Studio home whose prefs.json says where the library is: OPENFILM_SHARED_HOME, else Studio's own. */+const choiceHome = () => process.env.OPENFILM_SHARED_HOME || studioHomeDir();+/** Where new projects go unless the person chose: OPENFILM_LIBRARY, else ~/Movies/OpenFilm/Projects on macOS, ~/Videos/OpenFilm/Projects elsewhere. */export const libraryDefault = () => process.env.OPENFILM_LIBRARY|| join(homedir(), process.platform === 'darwin' ? 'Movies' : 'Videos', 'OpenFilm', 'Projects');@@ -42,16 +47,44 @@ export const LOCATION_KEYS = /** @type {const} */ ({ projects: 'projectsFolder'/** A folder the person chose, as kept in prefs.json: an absolute path, or null (none chosen, or not one). */export function chosenFolder(/** @type {'projectsFolder'} */ key) {try {- const value = JSON.parse(readFileSync(join(studioHomeDir(), 'prefs.json'), 'utf8'))?.[key];+ const value = JSON.parse(readFileSync(join(choiceHome(), 'prefs.json'), 'utf8'))?.[key];return typeof value === 'string' && isAbsolute(value) ? resolve(value) : null;} catch {return null;}}+/**+ * Keep a folder the person chose (null: back to the default) in the prefs.json that holds it. The file is shared with+ * every OpenFilm on this computer, older or newer: what this one does not know of it is written back as it was.+ * @param {'projectsFolder'} key @param {string | null} value+ */+export function chooseFolder(key, value) {+ const at = join(choiceHome(), 'prefs.json');+ let kept = {};+ try { const raw = JSON.parse(readFileSync(at, 'utf8')); if (raw && typeof raw === 'object' && !Array.isArray(raw)) kept = raw; } catch { /* none yet */ }+ mkdirSync(choiceHome(), { recursive: true });+ writeFileSync(`${at}.${process.pid}.tmp`, `${JSON.stringify({ ...kept, [key]: value }, null, 2)}\n`);+ renameSync(`${at}.${process.pid}.tmp`, at);+}+/** Where new projects go: the folder the person chose, else the default. */export const libraryRoot = () => chosenFolder('projectsFolder') ?? libraryDefault();+/**+ * The projects in a library, by full path: its folders that hold a film (film.html, or Studio's `.film/id` for one+ * that lost it), not hidden ones. Nothing deeper: a project is a folder of the library.+ */+export function libraryProjects(root = libraryRoot()) {+ try {+ return readdirSync(root, { withFileTypes: true })+ .filter((d) => d.isDirectory() && !d.name.startsWith('.') && (existsSync(join(root, d.name, 'film.html')) || existsSync(join(root, d.name, '.film', 'id'))))+ .map((d) => join(root, d.name));+ } catch {+ return [];+ }+}+/** Where exports go when no folder is picked. */export const exportsRoot = () => exportsDefault();@@ -68,11 +101,11 @@ export function freeSpace(/** @type {string} */ folder) {}/**- * Each folder the person can choose, for Settings: where it is now, its default, whether it was chosen, and the free- * space on its disk.+ * Each folder the person can choose, for Settings: where it is now, its default, whether it was chosen, the free+ * space on its disk, and how many projects are in it (Settings asks whether they move with it).*/export function locations() {- const one = (/** @type {string} */ path, /** @type {string} */ fallback, /** @type {boolean} */ chosen) => ({ path, default: fallback, chosen, free: freeSpace(path) });+ const one = (/** @type {string} */ path, /** @type {string} */ fallback, /** @type {boolean} */ chosen) => ({ path, default: fallback, chosen, free: freeSpace(path), count: libraryProjects(path).length });return {projects: one(libraryRoot(), libraryDefault(), chosenFolder('projectsFolder') !== null),};@@ -87,8 +120,9 @@ export function usableFolder(value) {if (typeof value !== 'string' || !isAbsolute(value)) throw new Error('Choose a folder by its full path.');const path = resolve(value);if (dirname(path) === path) throw new Error('Choose a folder on that disk, not the disk itself.');- const home = resolve(studioHomeDir());- if (path === home || path.startsWith(home + sep)) throw new Error('OpenFilm keeps its own settings there: choose another folder.');+ for (const home of new Set([resolve(studioHomeDir()), resolve(choiceHome())])) {+ if (path === home || path.startsWith(home + sep)) throw new Error('OpenFilm keeps its own settings there: choose another folder.');+ }try {mkdirSync(path, { recursive: true });accessSync(path, constants.W_OK);diff --git a/packages/openfilm/src/locations.test.mjs b/packages/openfilm/src/locations.test.mjsindex 8a6d7c7..959b948 100644--- a/packages/openfilm/src/locations.test.mjs+++ b/packages/openfilm/src/locations.test.mjs@@ -1,11 +1,11 @@import { test, beforeEach, afterEach } from 'node:test';import assert from 'node:assert/strict';-import { existsSync, mkdtempSync, writeFileSync } from 'node:fs';+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';-import { exportsRoot, libraryDefault, libraryRoot, locations, usableFolder } from './locations.mjs';+import { exportsRoot, libraryDefault, libraryProjects, libraryRoot, locations, usableFolder } from './locations.mjs';-const KEYS = ['OPENFILM_HOME', 'OPENFILM_LIBRARY', 'OPENFILM_EXPORTS'];+const KEYS = ['OPENFILM_HOME', 'OPENFILM_LIBRARY', 'OPENFILM_EXPORTS', 'OPENFILM_SHARED_HOME'];let saved;let home;beforeEach(() => {@@ -14,6 +14,7 @@ beforeEach(() => {process.env.OPENFILM_HOME = home;delete process.env.OPENFILM_LIBRARY;delete process.env.OPENFILM_EXPORTS;+ delete process.env.OPENFILM_SHARED_HOME;});afterEach(() => {for (const k of KEYS) { if (saved[k] === undefined) delete process.env[k]; else process.env[k] = saved[k]; }@@ -62,3 +63,26 @@ test('a folder offered is made and kept by its full path; a disk, Studio\'s ownassert.throws(() => usableFolder(process.platform === 'win32' ? 'C:\\' : '/'), /not the disk itself/);assert.throws(() => usableFolder(join(home, 'inside')), /own settings/);});++test('a library\'s projects are its folders that hold a film; Settings counts them', () => {+ const lib = join(home, 'lib');+ process.env.OPENFILM_LIBRARY = lib;+ for (const name of ['One', 'Two', '.hidden']) { mkdirSync(join(lib, name), { recursive: true }); writeFileSync(join(lib, name, 'film.html'), ''); }+ mkdirSync(join(lib, 'Lost its film', '.film'), { recursive: true });+ writeFileSync(join(lib, 'Lost its film', '.film', 'id'), 'abcdef');+ mkdirSync(join(lib, 'Plain'));+ writeFileSync(join(lib, 'notes.txt'), '');+ assert.deepEqual(libraryProjects().map((p) => p.slice(lib.length + 1)).sort(), ['Lost its film', 'One', 'Two']);+ assert.equal(locations().projects.count, 3);+ assert.deepEqual(libraryProjects(join(home, 'none')), [], 'a folder not there holds none');+});++test('with a shared home, the folder chosen there is the library; a folder inside either home is refused', () => {+ const shared = join(home, '..', `of-shared-${process.pid}`);+ process.env.OPENFILM_SHARED_HOME = shared;+ mkdirSync(shared, { recursive: true });+ writeFileSync(join(shared, 'prefs.json'), JSON.stringify({ projectsFolder: join(home, 'X', 'Projects') }));+ prefs({ projectsFolder: join(home, 'Own') });+ assert.equal(libraryRoot(), join(home, 'X', 'Projects'), 'the shared one, not its own');+ assert.throws(() => usableFolder(join(shared, 'inside')), /own settings/);+});diff --git a/packages/openfilm/src/look.mjs b/packages/openfilm/src/look.mjsindex 593df1e..5f555a1 100644--- a/packages/openfilm/src/look.mjs+++ b/packages/openfilm/src/look.mjs@@ -12,7 +12,8 @@ export async function look(args, opts = {}) {const { film: target, at, range } = parseTarget(args);if (MEDIA.test(target)) return lookMedia(target, at, range, opts);let s;- try { s = await open(target, { root: opts.root, offline: opts.offline, network: opts.network, transparent: true, launch: opts.launch }); }+ /* `playable`: footage the browser does not decode (ProRes; HEVC without a chip for it) is looked at through a copy it plays */+ try { s = await open(target, { root: opts.root, offline: opts.offline, network: opts.network, transparent: true, launch: opts.launch, playable: true }); }catch (e) { if (e instanceof FrameError) return { ok: false, lines: [`✗ ${e.message}`], files: [] }; throw e; }const { film, browser } = s;const m = film.meta;diff --git a/packages/openfilm/src/problems.mjs b/packages/openfilm/src/problems.mjsnew file mode 100644index 0000000..5bb51d6--- /dev/null+++ b/packages/openfilm/src/problems.mjs@@ -0,0 +1,133 @@+// @ts-check+/**+ * What went wrong lately, kept so a person can say why when something does not work: one line per problem (an agent+ * that did not start or answer, an export that failed, an error Studio did not expect) in `logs/problems.jsonl` in+ * Studio's home. Written always, not only in Developer mode, and small: the last KEEP_DAYS days, at most KEEP_MAX+ * lines. Each says what failed and why in a line, and where its details are (a turn's log, Studio's log); the details+ * stay there.+ *+ * What goes in is tidied first: the home folder reads ~, and keys, tokens and email addresses are taken out+ * (`redact`). The desktop app writes here too (OPENFILM_HOME is the same), so Studio's report has its agents'+ * problems.+ *+ * Reads no Studio module, so the command and the desktop app can use it.+ */+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';+import { homedir } from 'node:os';+import { dirname, join } from 'node:path';+import { studioHomeDir } from './locations.mjs';++/** How long a problem is kept, and how many are. */+export const KEEP_DAYS = 14;+export const KEEP_MAX = 500;+/** A line's longest field: a message, what stderr said. */+const FIELD_MAX = 2000;+/** Past this size the file is trimmed to KEEP_DAYS and KEEP_MAX as the next problem is written. */+const TRIM_AT = 256 * 1024;++/** @param {string} [home] Studio's home */+export const problemsFile = (home = studioHomeDir()) => join(home, 'logs', 'problems.jsonl');++/**+ * Text with what must not leave the computer taken out: the home folder as ~, keys (sk-…, a bearer token, a key or+ * token named in a setting or an address), and email addresses.+ * @param {string} text @param {string} [home]+ */+export function redact(text, home = homedir()) {+ let out = String(text);+ if (home && home.length > 1) out = out.split(home).join('~');+ return out+ .replace(/\b(Bearer|Basic)\s+[\w.~+/=-]{8,}/gi, '$1 (hidden)')+ .replace(/\b(sk|pk|rk|ghp|gho|ghs|xox[abp]|AKIA)[-_]?[A-Za-z0-9_-]{12,}/g, '(key hidden)')+ .replace(/((?:api[_-]?key|access[_-]?token|refresh[_-]?token|id[_-]?token|token|secret|password|authorization)["']?\s*[:=]\s*["']?)[^\s"'&,}]{6,}/gi, '$1(hidden)')+ .replace(/[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Za-z]{2,}/g, '(email)');+}++/** @param {unknown} value */+const field = (value) => {+ const text = redact(typeof value === 'string' ? value : JSON.stringify(value));+ return text.length > FIELD_MAX ? `${text.slice(0, FIELD_MAX - 1)}…` : text;+};++/**+ * @typedef {{ t: string, area: 'agent' | 'export' | 'studio' | string, what: string, agent?: string, agentId?: string,+ * version?: string, step?: string, code?: string, project?: string, log?: string, stderr?: string,+ * ownLogs?: string }} Problem+ * `what`: the message, in a line. `agent`: its name, `agentId` the app's id for it. `log`: its turn's log (in+ * `.film/logs/` of the project). `ownLogs`: where the agent keeps its own logs (Codex: ~/.codex).+ */++/**+ * Keep a problem. Never throws: a problem that cannot be kept does not become another.+ * @param {Omit<Problem, 't'> & { t?: string }} problem @param {{ file?: string, now?: Date }} [options]+ */+export function recordProblem(problem, { file = problemsFile(), now = new Date() } = {}) {+ try {+ /** @type {Record<string, string>} */+ const line = { t: problem.t ?? now.toISOString() };+ for (const [key, value] of Object.entries(problem)) {+ if (key !== 't' && value != null && value !== '') line[key] = key === 'what' ? field(value).replace(/\s+/g, ' ').trim() : field(value);+ }+ if (!line.what) return;+ mkdirSync(dirname(file), { recursive: true });+ appendFileSync(file, `${JSON.stringify(line)}\n`);+ if (statSync(file).size > TRIM_AT) trimProblems({ file, now });+ } catch { /* not kept */ }+}++/** @param {string} file @returns {Problem[]} */+function readAll(file) {+ if (!existsSync(file)) return [];+ return readFileSync(file, 'utf8').split('\n').flatMap((line) => {+ try { const p = line ? JSON.parse(line) : null; return p && typeof p.t === 'string' && typeof p.what === 'string' ? [p] : []; } catch { return []; }+ });+}++/**+ * The problems of the last `days` days, oldest first (by their time: two processes write here), the last `max` of them.+ * @param {{ file?: string, days?: number, max?: number, now?: Date }} [options]+ */+export function recentProblems({ file = problemsFile(), days = KEEP_DAYS, max = KEEP_MAX, now = new Date() } = {}) {+ const since = now.getTime() - days * 86_400_000;+ return readAll(file).filter((p) => Date.parse(p.t) >= since).sort((a, b) => Date.parse(a.t) - Date.parse(b.t)).slice(-max);+}++/**+ * The file cut to what is kept: KEEP_DAYS days, KEEP_MAX lines.+ * @param {{ file?: string, now?: Date }} [options]+ */+export function trimProblems({ file = problemsFile(), now = new Date() } = {}) {+ try {+ if (!existsSync(file)) return;+ const kept = recentProblems({ file, now });+ writeFileSync(file, kept.map((p) => JSON.stringify(p)).join('\n') + (kept.length ? '\n' : ''));+ } catch { /* as it was */ }+}++/**+ * A problem as one line of the report: when (local time, to the minute), what it was about, what it said. No project,+ * no turn: those are in the file the full report exports.+ * @param {Problem} p+ */+export function problemLine(p) {+ const at = new Date(p.t);+ const pad = (/** @type {number} */ n) => String(n).padStart(2, '0');+ const when = Number.isNaN(at.getTime()) ? p.t : `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())} ${pad(at.getHours())}:${pad(at.getMinutes())}`;+ const about = [p.agent ? `${p.agent}${p.version ? ` ${p.version}` : ''}` : p.area, p.step].filter(Boolean).join(' · ');+ const what = p.what.length > 240 ? `${p.what.slice(0, 239)}…` : p.what;+ return `${when} ${about} ${what}`;+}++/**+ * The report's lines for the problems of the last `days` days: the last `count`, newest last; none when there are none.+ * @param {{ file?: string, days?: number, count?: number, now?: Date }} [options]+ */+export function problemLines({ file = problemsFile(), days = 7, count = 10, now = new Date() } = {}) {+ const all = recentProblems({ file, days, now });+ if (!all.length) return [];+ const shown = all.slice(-count);+ return [+ `Problems in the last ${days} days (${all.length}${all.length > shown.length ? `, the last ${shown.length}` : ''}):`,+ ...shown.map((p) => ` ${problemLine(p)}`),+ ];+}diff --git a/packages/openfilm/src/problems.test.mjs b/packages/openfilm/src/problems.test.mjsnew file mode 100644index 0000000..007f7ff--- /dev/null+++ b/packages/openfilm/src/problems.test.mjs@@ -0,0 +1,64 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { mkdtempSync, readFileSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { KEEP_MAX, problemLine, problemLines, recentProblems, recordProblem, redact, trimProblems } from './problems.mjs';++const fileIn = () => join(mkdtempSync(join(tmpdir(), 'openfilm-problems-')), 'logs', 'problems.jsonl');++test('a problem is kept as a line, tidied: the home folder as ~, no keys, tokens or email addresses', () => {+ const file = fileIn();+ recordProblem({ area: 'agent', agent: 'Codex', step: 'session/prompt', what: 'Codex stopped\nwithout saying why.', project: '/home-of-someone/Projects/Film', stderr: 'Authorization: Bearer abcdefghijklmnop for [email protected]' }, { file, now: new Date('2026-10-18T13:13:15Z') });+ const [p] = recentProblems({ file, now: new Date('2026-10-18T14:00:00Z') });+ assert.equal(p.t, '2026-10-18T13:13:15.000Z');+ assert.equal(p.what, 'Codex stopped without saying why.');+ assert.equal(p.agent, 'Codex');+ assert.equal(p.step, 'session/prompt');+ assert.doesNotMatch(p.stderr, /abcdefghijklmnop|ana@example\.com/);+ assert.equal(redact('/home-of-someone/x', '/home-of-someone'), '~/x');+ assert.equal(redact('key sk-proj-abcdefghijklmnopqrstu end'), 'key (key hidden) end');+ assert.equal(redact('{"api_key": "xxxxxxxxxxxx"}'), '{"api_key": "(hidden)"}');+ assert.equal(redact('https://x.dev/?token=abcdef123456&a=1'), 'https://x.dev/?token=(hidden)&a=1');+});++test('one with nothing to say is not kept; one that cannot be written does not throw', () => {+ const file = fileIn();+ recordProblem({ area: 'agent', what: ' ' }, { file });+ assert.deepEqual(recentProblems({ file }), []);+ assert.doesNotThrow(() => recordProblem({ area: 'x', what: 'y' }, { file: '/dev/null/cannot/problems.jsonl' }));+});++test('kept: the last two weeks, at most KEEP_MAX; a broken line is left out', () => {+ const file = fileIn();+ const now = new Date('2026-10-18T12:00:00Z');+ recordProblem({ area: 'export', what: 'old' }, { file, now: new Date('2026-10-01T12:00:00Z') });+ for (let i = 0; i < KEEP_MAX + 5; i += 1) recordProblem({ area: 'export', what: `p${i}` }, { file, now: new Date(now.getTime() - (KEEP_MAX + 5 - i) * 1000) });+ writeFileSync(file, `${readFileSync(file, 'utf8')}{"t":"half`);+ trimProblems({ file, now });+ const kept = recentProblems({ file, now });+ assert.equal(kept.length, KEEP_MAX);+ assert.equal(kept[0].what, 'p5');+ assert.equal(kept.at(-1).what, `p${KEEP_MAX + 4}`);+ assert.ok(!kept.some((p) => p.what === 'old'));+});++test('read in the order they happened, whichever process wrote one first', () => {+ const file = fileIn();+ recordProblem({ area: 'agent', what: 'later' }, { file, now: new Date('2026-10-18T12:00:00Z') });+ recordProblem({ area: 'studio', what: 'earlier' }, { file, now: new Date('2026-10-18T11:00:00Z') });+ assert.deepEqual(recentProblems({ file, now: new Date('2026-10-18T13:00:00Z') }).map((p) => p.what), ['earlier', 'later']);+});++test("the report's lines: the last week's, the last few, each when, what about and what it said; none without any", () => {+ const file = fileIn();+ const now = new Date('2026-10-18T12:00:00Z');+ assert.deepEqual(problemLines({ file, now }), []);+ recordProblem({ area: 'studio', what: 'last month' }, { file, now: new Date('2026-10-05T12:00:00Z') });+ for (let i = 0; i < 12; i += 1) recordProblem({ area: 'agent', agent: 'Codex', step: 'start', what: `failed ${i}` }, { file, now: new Date(now.getTime() - (12 - i) * 60_000) });+ const lines = problemLines({ file, now, count: 3 });+ assert.equal(lines[0], 'Problems in the last 7 days (12, the last 3):');+ assert.equal(lines.length, 4);+ assert.match(lines[3], /^ {2}\d{4}-\d\d-\d\d \d\d:\d\d {2}Codex · start {2}failed 11$/);+ assert.match(problemLine({ t: 'x', area: 'export', what: 'no codec' }), /^x {2}export {2}no codec$/);+});diff --git a/packages/openfilm/src/render.mjs b/packages/openfilm/src/render.mjsindex 81b4fe9..1648d87 100644--- a/packages/openfilm/src/render.mjs+++ b/packages/openfilm/src/render.mjs@@ -1,12 +1,14 @@// film render: the deliverable. Frames are rendered in parallel page instances, averaged// over the shutter for motion blur, encoded with tagged BT.709 color, and muxed with the mix of the film's sounds.-import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs';-import { availableParallelism, totalmem } from 'node:os';+import { spawnSync } from 'node:child_process';+import { mkdirSync, rmSync, writeFileSync } from 'node:fs';+import { availableParallelism, freemem, totalmem } from 'node:os';import { basename, dirname, extname, join, resolve } from 'node:path';-import { clipKind, kindOf, readFilmFile } from './film-doc.mjs';+import { clipKind, FILM_FILE } from './film-doc.mjs';+import { broken, encoders, hardwareEncoder, hardwareOptions, proresOptions } from './encoders.mjs';import { FilmPage, launch } from './host.mjs';-import { seekableCopies } from './seekable.mjs';-import { ffmpeg, fileOf, filmSound, fmt, kill, mix, open, outDir, parseTarget, shown, UsageError, write } from './shared.mjs';+import { browserCopies, filmVideos } from './seekable.mjs';+import { ffmpeg, filmSound, fmt, kill, mix, open, outDir, parseTarget, shown, UsageError, write } from './shared.mjs';const BT709 = ['-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc', 'bt709', '-color_range', 'tv'];const TAG_709 = ['-bsf:v', 'h264_metadata=colour_primaries=1:transfer_characteristics=1:matrix_coefficients=1:video_full_range_flag=0'];@@ -18,6 +20,32 @@ const FORMATS = {'.mov': { video: ['-c:v', 'prores_ks', '-profile:v', '4444', '-vendor', 'apl0'], pix: 'format=yuva444p10le', audio: ['-c:a', 'pcm_s16le'], tag: [] },};+/** Bits per pixel per frame for the chip's H.264: Studio's "high", with room for screen text (exports.mjs). */+const CHIP_BPP = 0.165;++/**+ * The container's picture through the graphics chip, when it has an encoder that works and takes the picture's size:+ * H.264 for an MP4, a key frame every two seconds; ProRes 4444 for a MOV. Null otherwise: the container's own.+ * @param {string} ext @param {{ w: number, h: number }} size @param {number} fps+ */+async function chipFormat(ext, size, fps) {+ if (Math.min(size.w, size.h) < 64 || Math.max(size.w, size.h) > 4096) return null;+ const have = await encoders();+ if (ext === '.mp4') {+ const encoder = await hardwareEncoder('h264', have);+ const bits = Math.min(120e6, Math.max(2e6, size.w * size.h * fps * CHIP_BPP));+ return encoder ? { encoder, format: { video: [...hardwareOptions(encoder, bits, { gop: fps * 2 }), ...BT709] } } : null;+ }+ if (ext === '.mov') {+ const encoder = await hardwareEncoder('prores', have);+ return encoder ? { encoder, format: proresOptions(encoder, true) } : null;+ }+ return null;+}++/** The encoder a format's picture options name. @param {string[] | undefined} video */+const encoderOf = (video = []) => video[video.indexOf('-c:v') + 1] ?? 'ffmpeg';+export async function render(args, opts = {}) {const started = Date.now();const { film: target, at, range } = parseTarget(args);@@ -57,21 +85,23 @@ export async function render(args, opts = {}) {mkdirSync(dirname(out), { recursive: true });const container = FORMATS[extname(out).toLowerCase()];if (!container) { await probe.close(); throw new UsageError(`can't write ${extname(out)}: use .mp4, .webm or .mov`); }- /* a host may encode the container its own way (Studio's export: another codec, a quality, a frame around the film) */- const format = { ...container, ...opts.format };if (alpha && extname(out).toLowerCase() === '.mp4') { await probe.close(); throw new UsageError('mp4 has no transparency: write .webm or .mov with --alpha'); }- const workers = Math.max(1, Math.min(Number(opts.workers ?? defaultWorkers()), total));- /* a render of more than a moment: its videos seek fast (a film's video clips load only when their time comes, so- they are read from film.html; a page's own videos are the ones it asked for) */- if (total >= fps * 2 && opts.seekable !== false) {- if (isFilm) {- try {- const doc = readFilmFile(readFileSync(join(root, entry), 'utf8')).doc;- for (const track of doc?.tracks ?? []) for (const clip of track.clips) if (kindOf(clip) === 'video') videos.add(fileOf(root, entry, clip.src));- } catch { /* the pages ask for what they need */ }- }- /* only ever faster: a copy that could not be made leaves its video as it is */- if (videos.size) copies = await seekableCopies([...videos], dir, { signal: opts.signal }).catch(() => new Map());+ /* a host may encode the container its own way (Studio's export: another codec, a quality, a frame around the film),+ and gets exactly that; else the picture goes through the graphics chip when it can */+ const own = { ...container, ...opts.format };+ const size = { w: Math.round(meta.width * scale), h: Math.round(meta.height * scale) };+ const chip = opts.format || opts.hardware === false ? null : await chipFormat(extname(out).toLowerCase(), size, fps);+ let format = chip ? { ...own, ...chip.format } : own;+ let encoder = chip?.encoder ?? encoderOf(own.video);+ const workers = Math.max(1, Math.min(Number(opts.workers ?? defaultWorkers(machine(), total)), total));+ /* the videos get copies this browser plays: those it does not decode here (ProRes; HEVC without a chip for it), and+ for a render of more than a moment those that seek slowly (seekable.mjs). A film's video clips load only when+ their time comes, so they are read from film.html (a page drawn around the project's film, as a burned-in+ subtitle export is, reads the project's); a page's own videos are the ones it asked for */+ if (opts.seekable !== false) {+ const film = isFilm ? entry : opts.root ? FILM_FILE : null;+ const files = [...new Set([...videos, ...(film ? filmVideos(root, film) : [])])];+ copies = await browserCopies(browser, site.url, root, files, { signal: opts.signal, slow: total >= fps * 2 });}if (!process.stderr.isTTY && !opts.onProgress) process.stderr.write(` rendering ${total} frames with ${workers} browser${workers > 1 ? 's' : ''}…\n`);@@ -111,7 +141,35 @@ export async function render(args, opts = {}) {if (alpha && isFilm) await Promise.all(pages.map((p) => p.page.addStyleTag({ content: 'html, body { background: transparent !important; }' })));const per = Math.ceil(total / workers);const parts = pages.map((film, i) => ({ film, a: f0 + i * per, b: Math.min(f1, f0 + (i + 1) * per), file: join(work, `part-${i}${extname(out)}`) })).filter((p) => p.a < p.b);- await unlessCancelled(Promise.all(parts.map((p) => encode(p, { fps, samples, shutter, duration: end, format, onFrame: progress, still: alpha ? 'png' : 'jpeg', signal: opts.signal }))));+ /** Every part, encoded with `f`: one that fails stops the others before its error is told. @param {typeof format} f */+ const encodeAll = async (f) => {+ const stop = new AbortController();+ const quit = () => stop.abort();+ opts.signal?.addEventListener('abort', quit, { once: true });+ const runs = parts.map((p) => encode(p, { fps, samples, shutter, duration: end, format: f, onFrame: progress, still: alpha ? 'png' : 'jpeg', signal: stop.signal }));+ try {+ await unlessCancelled(Promise.all(runs));+ } catch (e) {+ stop.abort();+ await Promise.allSettled(runs);+ throw e;+ } finally {+ opts.signal?.removeEventListener('abort', quit);+ }+ };+ try {+ await encodeAll(format);+ } catch (e) {+ /* the chip's encoder gave up partway (a driver, a size it does not take): the frames again without it, and the+ rest of this launch does without it */+ if (!chip || opts.signal?.aborted || !/^ffmpeg/.test(e instanceof Error ? e.message : '')) throw e;+ broken(chip.encoder);+ format = own;+ encoder = encoderOf(own.video);+ done = 0;+ told = 0;+ await encodeAll(format);+ }if (process.stderr.isTTY && !opts.onProgress) process.stderr.write('\n');for (const p of pages) problems.push(...p.problems);@@ -137,9 +195,10 @@ export async function render(args, opts = {}) {const seconds = (Date.now() - started) / 1000;return {out,+ encoder,lines: [`→ ${shown(out)}`,- ` ${total} frames · ${fmt(to - from)} at ${fps} fps · ${Math.round(meta.width * scale)}×${Math.round(meta.height * scale)}${samples > 1 ? ` · ${samples} samples/frame` : ''}${alpha ? ' · alpha' : ''} · ${workers} worker${workers > 1 ? 's' : ''} · ${seconds.toFixed(1)} s`,+ ` ${total} frames · ${fmt(to - from)} at ${fps} fps · ${Math.round(meta.width * scale)}×${Math.round(meta.height * scale)}${samples > 1 ? ` · ${samples} samples/frame` : ''}${alpha ? ' · alpha' : ''} · ${workers} worker${workers > 1 ? 's' : ''} · ${encoder} · ${seconds.toFixed(1)} s`,...problems.map((p) => `✗ ${p.kind === 'request' ? 'request' : 'page'}: ${p.message}`),],};@@ -149,9 +208,42 @@ export async function render(args, opts = {}) {* One browser per three cores, at most four, and memory to spare (a page with its media takes 1.5 GB or more, and the* encoder and the person's own apps need theirs): a render leaves the computer usable while it runs.*/-/** A browser for every two cores (a core's two threads), with 3 GB of memory each, up to 8. */-export function defaultWorkers(threads = availableParallelism(), memory = totalmem()) {- return Math.max(1, Math.min(8, Math.floor(threads / 2), Math.floor(memory / (3 * 2 ** 30))));+/** The memory a browser drawing a film takes, with its share of the encoding (a 1080p film's page measured 1.1 GB). */+const WORKER_MEMORY = 1.5 * 2 ** 30;+/** Memory left free for the person's own apps. */+const RESERVE = 2 * 2 ** 30;+/** Frames worth a browser of their own: for fewer, starting one costs more than it saves. */+const FRAMES_PER_WORKER = 60;+/** More browsers stop drawing faster: they share one graphics chip (measured: three draw twice as fast as one;+ * past four, slower, and eight ran out of resources). */+const MAX_WORKERS = 4;++/**+ * What a render may use of this machine: its performance cores (Apple silicon's efficiency cores are slow for+ * drawing; elsewhere a core is two threads) and the memory free now. On a Mac `os.freemem()` counts only memory never+ * used, a fraction of what is free: the system's own share of free memory is read instead.+ */+export function machine() {+ const sysctl = (/** @type {string} */ name) => Number(spawnSync('sysctl', ['-n', name], { encoding: 'utf8', timeout: 2000 }).stdout?.trim());+ let cores = Math.max(1, Math.floor(availableParallelism() / 2));+ let available = freemem();+ if (process.platform === 'darwin') {+ const performance = sysctl('hw.perflevel0.physicalcpu');+ if (performance > 0) cores = performance;+ const free = sysctl('kern.memorystatus_level');+ if (free > 0 && free <= 100) available = (totalmem() * free) / 100;+ }+ return { cores, available };+}++/**+ * How many browsers draw a render: one for each performance core but one (the person keeps one), as many as the+ * memory free now holds with room left for the person's apps, and enough frames for each; at most four. The+ * computer stays usable while it renders: a render takes only memory that is free when it starts.+ * @param {{ cores: number, available: number }} [budget] @param {number} [frames]+ */+export function defaultWorkers({ cores, available } = machine(), frames = Infinity) {+ return Math.max(1, Math.min(MAX_WORKERS, cores - 1, Math.floor((available - RESERVE) / WORKER_MEMORY), Math.floor(frames / FRAMES_PER_WORKER)));}/** Frames [a, b) of one page into one file; sub-frames are averaged by ffmpeg (tmix) and every n-th kept. */diff --git a/packages/openfilm/src/render.test.mjs b/packages/openfilm/src/render.test.mjsindex 7df732f..0422a4f 100644--- a/packages/openfilm/src/render.test.mjs+++ b/packages/openfilm/src/render.test.mjs@@ -1,13 +1,38 @@import { test } from 'node:test';import assert from 'node:assert/strict';-import { execFileSync } from 'node:child_process';-import { mkdtempSync, rmSync, writeFileSync } from 'node:fs';-import { tmpdir } from 'node:os';+import { execFileSync, spawn } from 'node:child_process';+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';+import { getPriority, tmpdir, totalmem } from 'node:os';import { join } from 'node:path';-import { defaultWorkers, render } from './render.mjs';+import { fileURLToPath } from 'node:url';+import { encoders, hardwareEncoder } from './encoders.mjs';+import { filmHtml } from './film-doc.mjs';+import { defaultWorkers, machine, render } from './render.mjs';const hasFfmpeg = (() => { try { execFileSync('ffmpeg', ['-version'], { stdio: 'ignore' }); return true; } catch { return false; } })();+test('a render with no format of its own encodes on the graphics chip when it can: H.264 for an MP4, ProRes for a MOV', { skip: !hasFfmpeg && 'no ffmpeg', timeout: 120_000 }, async () => {+ const dir = mkdtempSync(join(tmpdir(), 'of-render-chip-'));+ try {+ writeFileSync(join(dir, 'index.html'), '<!doctype html><body style="margin:0"><div id="box" style="width:320px;height:180px"></div><script>'+ + 'window.film = { duration: 1, width: 320, height: 180, frame(t) { document.getElementById("box").style.background = `hsl(${t * 360}, 80%, 50%)`; } };</script>');+ const have = await encoders();+ const quiet = { workers: 1, silent: true, onProgress() {} };+ const mp4 = await render([dir, '0-0.5'], { ...quiet, out: join(dir, 'chip.mp4') });+ assert.equal(mp4.encoder, (await hardwareEncoder('h264', have)) ?? 'libx264');+ assert.match(mp4.lines[1], new RegExp(` · ${mp4.encoder} · `), 'the summary says which encoder');+ const soft = await render([dir, '0-0.5'], { ...quiet, out: join(dir, 'soft.mp4'), hardware: false });+ assert.equal(soft.encoder, 'libx264', 'hardware: false keeps the processor\'s');+ const mov = await render([dir, '0-0.5'], { ...quiet, out: join(dir, 'chip.mov'), alpha: true });+ assert.equal(mov.encoder, (await hardwareEncoder('prores', have)) ?? 'prores_ks');+ assert.equal(execFileSync('ffprobe', ['-v', 'error', '-select_streams', 'v:0', '-show_entries', 'stream=codec_name,profile', '-of', 'csv=p=0', mov.out]).toString().trim(), 'prores,4444');+ const frames = (file) => parseInt(execFileSync('ffprobe', ['-v', 'error', '-count_packets', '-select_streams', 'v:0', '-show_entries', 'stream=nb_read_packets', '-of', 'csv=p=0', file]).toString(), 10);+ assert.deepEqual([mp4.out, soft.out, mov.out].map(frames), [15, 15, 15]);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});+test('an encoder that fails to start fails the render with ffmpeg\'s error, instead of waiting forever', { skip: !hasFfmpeg && 'no ffmpeg', timeout: 60_000 }, async () => {const dir = mkdtempSync(join(tmpdir(), 'of-render-fails-'));try {@@ -23,10 +48,37 @@ test('an encoder that fails to start fails the render with ffmpeg\'s error, inst}});-test('a browser for every two threads, with 3 GB of memory each, at least one and at most eight', () => {+test('browsers: one per performance core but one, as many as the free memory holds with room to spare, enough frames each, at most four', () => {const GB = 2 ** 30;- assert.equal(defaultWorkers(10, 16 * GB), 5);- assert.equal(defaultWorkers(8, 8 * GB), 2, 'memory first');- assert.equal(defaultWorkers(32, 128 * GB), 8);- assert.equal(defaultWorkers(2, 4 * GB), 1);+ assert.equal(defaultWorkers({ cores: 4, available: 6.5 * GB }), 3, 'an M5 with 16 GB, 41% free');+ assert.equal(defaultWorkers({ cores: 4, available: 3 * GB }), 1, 'little memory free: one, never swapping');+ assert.equal(defaultWorkers({ cores: 12, available: 48 * GB }), 4, 'a big machine: four, as one graphics chip takes no more');+ assert.equal(defaultWorkers({ cores: 2, available: 16 * GB }), 1, 'two cores: one left for the person');+ assert.equal(defaultWorkers({ cores: 8, available: 32 * GB }, 100), 1, 'a short render: one browser, its start not worth more');+ assert.equal(defaultWorkers({ cores: 8, available: 32 * GB }, 240), 4);+ const { cores, available } = machine();+ assert.ok(cores >= 1 && available > 0 && available <= totalmem(), `this machine: ${cores} cores, ${available} bytes free`);+});++test('a render runs below the person\'s own apps, with every process it starts', { skip: !hasFfmpeg && 'no ffmpeg', timeout: 120_000 }, async () => {+ const dir = mkdtempSync(join(tmpdir(), 'of-render-priority-'));+ try {+ /* a project Studio has shown before (`.film/opened`), so the command goes straight to the render */+ writeFileSync(join(dir, 'p.html'), '<!doctype html><body><script>window.film = { duration: 3, width: 320, height: 180, frame() {} };</script>');+ writeFileSync(join(dir, 'film.html'), filmHtml({ stage: { w: 320, h: 180 }, tracks: [{ clips: [{ id: 'p', src: 'p.html', at: 0, time: [0, 3] }] }] }));+ mkdirSync(join(dir, '.film'));+ writeFileSync(join(dir, '.film', 'opened'), '');+ const child = spawn(process.execPath, [fileURLToPath(new URL('../bin/openfilm.mjs', import.meta.url)), 'render', '0-3', '--workers', '1', '--out', join(dir, 'out.mp4')], { cwd: dir, stdio: 'ignore' });+ const ended = new Promise((done) => child.on('exit', done));+ /* read until it is lowered: the process may start at another nice value (a CI runner's is not 0) */+ let priority = null;+ for (const end = Date.now() + 20_000; priority !== 10 && child.exitCode == null && Date.now() < end;) {+ try { priority = getPriority(/** @type {number} */ (child.pid)); } catch { break; }+ await new Promise((r) => setTimeout(r, 50));+ }+ await ended;+ assert.equal(priority, 10);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }});diff --git a/packages/openfilm/src/seekable.mjs b/packages/openfilm/src/seekable.mjsindex 8c0dd15..a6bb745 100644--- a/packages/openfilm/src/seekable.mjs+++ b/packages/openfilm/src/seekable.mjs@@ -1,12 +1,15 @@-// Videos that seek fast, for a render. A render seeks each video to every frame, and a browser decodes from the key+// Videos a render's browser plays well. A render seeks each video to every frame, and a browser decodes from the key// frame before the one asked: footage from cameras, phones and stock sites has one every 1 to 4 s, so each frame costs-// the decoding of up to a few hundred. Before rendering, such a video gets a copy with a key frame every quarter-// second, all but lossless, made once and kept in the project's cache; the render's pages are served the copy, and-// the sound is still mixed from the original.+// the decoding of up to a few hundred. And some footage the browser does not decode at all: ProRes in any browser,+// HEVC on a machine without a chip for it. Before rendering, such a video gets a copy the browser plays, with a key+// frame every quarter second, all but lossless (with its alpha, when it has one), made once and kept in the project's+// cache; the render's pages are served the copy, and the sound is still mixed from the original.import { execFile } from 'node:child_process';-import { existsSync, renameSync, rmSync, statSync } from 'node:fs';-import { join } from 'node:path';-import { ffmpeg, hash, outDir } from './shared.mjs';+import { existsSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs';+import { extname, join, relative, sep } from 'node:path';+import { colorTagsOf, encoders, h264ColorTags, hardwareEncoder, hardwareOptions, onTheChip } from './encoders.mjs';+import { kindOf, readFilmFile, srcHref } from './film-doc.mjs';+import { ffmpeg, fileOf, hash, outDir } from './shared.mjs';/** A key frame further apart than this is slow to seek to frame by frame. */const SLOW_GOP_S = 0.5;@@ -56,43 +59,168 @@ export async function slowSeeking(file) {span = first == null || last == null ? 0 : last - first;} catch { return null; }if (keys === 0 || span <= 0) return null;- return span / keys > SLOW_GOP_S ? { fps, seconds } : null;+ return span / keys > SLOW_GOP_S ? { fps, seconds, w: Number(stream.width), h: Number(stream.height) } : null;+}++/** Every Chromium decodes these by itself, with its own decoders, on any machine: no need to ask it. */+const decodedAnywhere = (/** @type {{ codec_name?: string, pix_fmt?: string }} */ s) =>+ (s.codec_name === 'h264' && ['yuv420p', 'yuvj420p'].includes(String(s.pix_fmt))) || ['vp8', 'vp9', 'av1'].includes(String(s.codec_name));++/**+ * What a render needs of a video: a copy because its browser does not decode it here (`unplayable`: ProRes in any+ * browser, HEVC without a chip for it, 10-bit H.264…, asked of the browser itself with `plays`; `alpha` when its+ * picture has one to keep), or because it seeks slowly (`slow`, slowSeeking, only when `slow` is asked for); null for+ * neither.+ * @param {string} file @param {{ plays?: (file: string) => Promise<boolean>, slow?: boolean }} [options]+ * @returns {Promise<{ why: 'unplayable' | 'slow', fps: number, w: number, h: number, alpha: boolean } | null>}+ */+export async function copyNeed(file, { plays, slow = true } = {}) {+ let info;+ try {+ info = JSON.parse(await probe(file, ['-select_streams', 'v:0', '-show_entries', 'stream=codec_name,width,height,pix_fmt,avg_frame_rate:stream_tags=alpha_mode', '-of', 'json']));+ } catch { return null; }+ const stream = info.streams?.[0];+ if (!stream || stream.width > MAX_SIDE || stream.height > MAX_SIDE) return null;+ if (plays && !decodedAnywhere(stream) && !(await plays(file))) {+ const [n, d] = String(stream.avg_frame_rate).split('/').map(Number);+ const alpha = /^(yuva|rgba|bgra|argb|abgr|gbrap|ya)/.test(String(stream.pix_fmt)) || stream.tags?.alpha_mode === '1';+ return { why: 'unplayable', fps: n > 0 && d > 0 ? n / d : 30, w: Number(stream.width), h: Number(stream.height), alpha };+ }+ const slowly = slow ? await slowSeeking(file) : null;+ return slowly ? { why: 'slow', fps: slowly.fps, w: slowly.w, h: slowly.h, alpha: false } : null;+}++/** Where `file`'s copy is kept in `root`'s cache, by the file's version: the path without its extension. */+const copyBase = (/** @type {string} */ file, /** @type {string} */ root, /** @type {import('node:fs').Stats} */ stat) =>+ join(root, '.film', 'cache', 'seek', hash(Buffer.from(`${VERSION}\0${file}\0${stat.size}\0${stat.mtimeMs}`)));++/** @type {Map<string, { copy: string | null, at: number }>} what madeCopy found, by file and version */+const found = new Map();+/**+ * The copy of `file` already made in `root`'s cache (seekableCopies), or null; nothing is made. Asked on every request+ * a playing video makes, so a copy found is remembered, and one not found is looked for again a moment later.+ * @param {string} file @param {string} root+ */+export function madeCopy(file, root) {+ let stat;+ try { stat = statSync(file); } catch { return null; }+ const key = `${root}\0${file}\0${stat.size}\0${stat.mtimeMs}`;+ const hit = found.get(key);+ if (hit && (hit.copy ? existsSync(hit.copy) : Date.now() - hit.at < 2000)) return hit.copy;+ const base = copyBase(file, root, stat);+ const copy = [`${base}.mp4`, `${base}.webm`].find((f) => existsSync(f)) ?? null;+ found.set(key, { copy, at: Date.now() });+ return copy;+}++/**+ * The files of a film's video clips: film.html at `film` (a path in `root`, as a URL says it), as a render, a look or+ * a still of it plays them.+ * @param {string} root @param {string} film+ */+export function filmVideos(root, film) {+ let doc;+ try { doc = readFilmFile(readFileSync(join(root, decodeURI(film)), 'utf8')).doc; } catch { return []; }+ const files = new Set();+ for (const track of doc?.tracks ?? []) {+ for (const clip of track.clips) {+ if (kindOf(clip) !== 'video') continue;+ try { files.add(fileOf(root, film, srcHref(clip.src))); } catch { /* a source out of the folder: not served either */ }+ }+ }+ return [...files];+}++/**+ * In a page: whether the browser shows the first frame of the video at `url`. One it does not decode (ProRes; HEVC+ * without a chip for it) fails at once, or never shows a frame.+ * @param {string} url+ */+const firstFrame = (url) => new Promise((done) => {+ const video = document.createElement('video');+ video.muted = true;+ video.preload = 'auto';+ const end = (/** @type {boolean} */ shown) => { clearTimeout(timer); video.removeAttribute('src'); video.load(); done(shown); };+ const timer = setTimeout(() => end(false), 10_000);+ video.addEventListener('loadeddata', () => end(true), { once: true });+ video.addEventListener('error', () => end(false), { once: true });+ video.src = url;+});++/**+ * The copies `browser` needs of `files` to show them (seekableCopies, kept in `root`'s cache), each file asked of the+ * browser itself through a page that loads it from the site at `origin`, which serves `root`. `slow`: slow-seeking+ * ones too. A map from a file to its copy; it never fails: a video that can't be copied stays as it is.+ * @param {import('playwright-core').Browser} browser @param {string} origin @param {string} root @param {string[]} files+ * @param {{ signal?: AbortSignal, slow?: boolean }} [options]+ */+export async function browserCopies(browser, origin, root, files, { signal, slow = false } = {}) {+ if (!files.length) return new Map();+ /** @type {Promise<import('playwright-core').Page> | null} */+ let tester = null;+ const plays = async (/** @type {string} */ file) => {+ tester ??= browser.newPage();+ const url = `${origin.replace(/\/$/, '')}/${relative(root, file).split(sep).map(encodeURIComponent).join('/')}`;+ return (await tester).evaluate(firstFrame, url).catch(() => false);+ };+ try {+ return await seekableCopies(files, root, { signal, plays, slow });+ } catch {+ return new Map();+ } finally {+ if (tester) await (await tester).close().catch(() => {});+ }}/**- * The fast-seeking copy of each of `files` that needs one, made in `root`'s cache (or found there from before): a map- * from a file to its copy. A file that is fine as it is, or whose copy fails, is not in it.- * @param {string[]} files @param {string} root @param {{ signal?: AbortSignal }} [options]+ * The copy of each of `files` that needs one (copyNeed), made in `root`'s cache (or found there from before): a map+ * from a file to its copy. A file that is fine as it is, or whose copy fails, is not in it. `plays`: whether the+ * render's browser decodes a file; `slow`: whether slow-seeking ones get a copy too (a render of more than a moment).+ * @param {string[]} files @param {string} root+ * @param {{ signal?: AbortSignal, plays?: (file: string) => Promise<boolean>, slow?: boolean }} [options]*/-export async function seekableCopies(files, root, { signal } = {}) {+export async function seekableCopies(files, root, { signal, plays, slow = true } = {}) {const copies = new Map();- const dir = outDir(root, 'seek');- /* two at a time: each one already keeps several cores busy */+ outDir(root, 'seek');+ /* two at a time: on the processor each one keeps several cores busy; on the graphics chip it leaves them free */const queue = [...new Set(files)];const worker = async () => {for (let file = queue.shift(); file; file = queue.shift()) {if (signal?.aborted) return;let stat;try { stat = statSync(file); } catch { continue; }- const out = join(dir, `${hash(Buffer.from(`${VERSION}\0${file}\0${stat.size}\0${stat.mtimeMs}`))}.mp4`);- if (existsSync(out)) { copies.set(file, out); continue; }- const slow = await slowSeeking(file);- if (!slow) continue;- const gop = String(Math.max(1, Math.round(slow.fps * COPY_GOP_S)));- const part = `${out}.part.mp4`;- /* the same frames at the same times (passthrough: no frame is added or dropped), the picture only */- const run = ffmpeg(['-i', file, '-map', '0:v:0', '-an', '-sn', '-dn', '-fps_mode', 'passthrough',- '-c:v', 'libx264', '-preset', 'superfast', '-crf', '16', '-g', gop, '-keyint_min', gop, '-pix_fmt', 'yuv420p', part]);- const stop = () => run.proc.kill('SIGKILL');- signal?.addEventListener('abort', stop, { once: true });+ const base = copyBase(file, root, stat);+ /* madeCopy finds it from now on, without waiting out a miss it remembers */+ const known = (/** @type {string} */ copy) => { copies.set(file, copy); found.set(`${root}\0${file}\0${stat.size}\0${stat.mtimeMs}`, { copy, at: Date.now() }); };+ const made = [`${base}.mp4`, `${base}.webm`].find((f) => existsSync(f));+ if (made) { known(made); continue; }+ const need = await copyNeed(file, { plays, slow });+ if (!need) continue;+ /* with an alpha to keep: VP9, which every Chromium decodes with its alpha; else H.264 */+ const out = `${base}${need.alpha ? '.webm' : '.mp4'}`;+ const gop = Math.max(1, Math.round(need.fps * COPY_GOP_S));+ const part = `${out}.part${extname(out)}`;+ /* all but lossless: about 19 Mbps at 1080p and 30 fps; the chip's encoder keeps the source's color tags only+ when told them */+ const bits = Math.min(120e6, Math.max(4e6, ((need.w * need.h) || 1920 * 1080) * need.fps * 0.3));+ /* decoded and written on the graphics chip when it can (encoders.mjs), else on the processor */+ const make = async (/** @type {string | null} */ encoder, /** @type {string[]} */ decoding) => {+ /* the same frames at the same times (passthrough: no frame is added or dropped), the picture only */+ const run = ffmpeg([...decoding, '-i', file, '-map', '0:v:0', '-an', '-sn', '-dn', '-fps_mode', 'passthrough',+ ...(need.alpha ? ['-c:v', 'libvpx-vp9', '-pix_fmt', 'yuva420p', '-b:v', '0', '-crf', '18', '-row-mt', '1', '-deadline', 'realtime', '-cpu-used', '8',+ '-g', String(gop), '-keyint_min', String(gop), '-auto-alt-ref', '0']+ : encoder ? ['-pix_fmt', 'nv12', ...hardwareOptions(encoder, bits, { gop }), ...h264ColorTags(await colorTagsOf(file))]+ : ['-c:v', 'libx264', '-preset', 'superfast', '-crf', '16', '-g', String(gop), '-keyint_min', String(gop), '-pix_fmt', 'yuv420p']), part]);+ const stop = () => run.proc.kill('SIGKILL');+ signal?.addEventListener('abort', stop, { once: true });+ try { await run.done; } finally { signal?.removeEventListener('abort', stop); }+ };try {- await run.done;+ await onTheChip(need.alpha ? null : await hardwareEncoder('h264', await encoders()), make, signal);renameSync(part, out);- copies.set(file, out);+ known(out);} catch {rmSync(part, { force: true });- } finally {- signal?.removeEventListener('abort', stop);}}};diff --git a/packages/openfilm/src/seekable.test.mjs b/packages/openfilm/src/seekable.test.mjsindex 27b7587..0de6ede 100644--- a/packages/openfilm/src/seekable.test.mjs+++ b/packages/openfilm/src/seekable.test.mjs@@ -6,7 +6,8 @@ import { tmpdir } from 'node:os';import { join } from 'node:path';import { filmHtml } from './film-doc.mjs';import { render } from './render.mjs';-import { seekableCopies, slowSeeking } from './seekable.mjs';+import { copyNeed, madeCopy, seekableCopies, slowSeeking } from './seekable.mjs';+import { look } from './look.mjs';const hasFfmpeg = (() => { try { execFileSync('ffmpeg', ['-version'], { stdio: 'ignore' }); return true; } catch { return false; } })();const ffmpeg = { skip: !hasFfmpeg && 'no ffmpeg', timeout: 120_000 };@@ -49,3 +50,74 @@ test('a render serves the film\'s slow-seeking videos as their copies', ffmpeg,rmSync(dir, { recursive: true, force: true });}});++test('footage the browser does not decode gets a copy it plays, with its alpha when it has one; footage it decodes is not asked about', ffmpeg, async () => {+ const dir = mkdtempSync(join(tmpdir(), 'of-seekable-unplayable-'));+ try {+ const make = (name, args) => execFileSync('ffmpeg', ['-v', 'error', '-y', '-f', 'lavfi', ...args, '-t', '1', join(dir, name)]);+ make('prores.mov', ['-i', 'testsrc2=size=320x180:rate=30', '-c:v', 'prores_ks', '-profile:v', '3']);+ make('alpha.mov', ['-i', '[email protected]:size=320x180:rate=30,format=rgba', '-c:v', 'prores_ks', '-profile:v', '4444', '-pix_fmt', 'yuva444p10le']);+ clip(join(dir, 'fast.mp4'), 5);+ const asked = [];+ const plays = async (file) => { asked.push(file.split(/[\\/]/).pop()); return false; };+ assert.deepEqual(await copyNeed(join(dir, 'prores.mov'), { plays }), { why: 'unplayable', fps: 30, w: 320, h: 180, alpha: false });+ assert.equal((await copyNeed(join(dir, 'alpha.mov'), { plays }))?.alpha, true);+ assert.equal(await copyNeed(join(dir, 'fast.mp4'), { plays }), null, '8-bit H.264 plays anywhere');+ assert.deepEqual(asked, ['prores.mov', 'alpha.mov']);+ assert.equal(await copyNeed(join(dir, 'prores.mov'), { plays: async () => true }), null, 'a browser that decodes it needs no copy');+ const copies = await seekableCopies(['prores.mov', 'alpha.mov', 'fast.mp4'].map((n) => join(dir, n)), dir, { plays, slow: false });+ const prores = /** @type {string} */ (copies.get(join(dir, 'prores.mov')));+ const alpha = /** @type {string} */ (copies.get(join(dir, 'alpha.mov')));+ assert.ok(prores.endsWith('.mp4') && alpha.endsWith('.webm') && !copies.has(join(dir, 'fast.mp4')));+ assert.deepEqual(times(prores), times(join(dir, 'prores.mov')), 'the same frames at the same times');+ const probe = (file, entries) => execFileSync('ffprobe', ['-v', 'error', '-select_streams', 'v:0', '-show_entries', entries, '-of', 'csv=p=0', file]).toString().trim();+ assert.match(probe(prores, 'stream=codec_name,pix_fmt'), /^h264,(yuv420p|nv12)/);+ const kept = execFileSync('ffmpeg', ['-v', 'error', '-c:v', 'libvpx-vp9', '-i', alpha, '-frames:v', '1', '-vf', 'format=rgba', '-f', 'rawvideo', '-']).filter((_, i) => i % 4 === 3);+ assert.ok(kept.every((a) => Math.abs(a - 128) <= 3), `the alpha kept: ${kept[0]}`);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test('a render shows ProRes footage, which no browser decodes, through its copy', ffmpeg, async () => {+ const dir = mkdtempSync(join(tmpdir(), 'of-seekable-prores-render-'));+ try {+ execFileSync('ffmpeg', ['-v', 'error', '-y', '-f', 'lavfi', '-i', 'color=c=0x2060c0:size=320x180:rate=30', '-t', '1', '-c:v', 'prores_ks', '-profile:v', '3', join(dir, 'a.mov')]);+ writeFileSync(join(dir, 'film.html'), filmHtml({ stage: { w: 320, h: 180 }, tracks: [{ clips: [{ id: 'v', src: 'a.mov', at: 0, time: [0, 1] }] }] }));+ const started = Date.now();+ const done = await render([dir, '0-0.5'], { out: join(dir, 'out.mp4'), workers: 1, silent: true, onProgress() {} });+ assert.ok(Date.now() - started < 60_000, 'no frame waits on a video that never shows');+ const [r, g, b] = execFileSync('ffmpeg', ['-v', 'error', '-ss', '0.2', '-i', done.out, '-frames:v', '1', '-vf', 'crop=4:4:160:90,format=rgb24', '-f', 'rawvideo', '-']);+ assert.ok(Math.abs(r - 0x20) < 16 && Math.abs(g - 0x60) < 16 && Math.abs(b - 0xc0) < 16, `the footage's colour: ${r},${g},${b}`);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test('a copy once made is found for each request after it, and none before', ffmpeg, async () => {+ const dir = mkdtempSync(join(tmpdir(), 'of-seekable-made-'));+ try {+ const file = join(dir, 'prores.mov');+ execFileSync('ffmpeg', ['-v', 'error', '-y', '-f', 'lavfi', '-i', 'testsrc2=size=320x180:rate=30', '-t', '1', '-c:v', 'prores_ks', '-profile:v', '3', file]);+ assert.equal(madeCopy(file, dir), null);+ const copies = await seekableCopies([file], dir, { plays: async () => false, slow: false });+ assert.ok(copies.get(file));+ assert.equal(madeCopy(file, dir), copies.get(file), 'at once, though a miss was just remembered');+ assert.equal(madeCopy(join(dir, 'gone.mov'), dir), null);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});++test('look shows ProRes footage, which no browser decodes, through its copy', ffmpeg, async () => {+ const dir = mkdtempSync(join(tmpdir(), 'of-seekable-prores-look-'));+ try {+ execFileSync('ffmpeg', ['-v', 'error', '-y', '-f', 'lavfi', '-i', 'color=c=0x2060c0:size=320x180:rate=30', '-t', '1', '-c:v', 'prores_ks', '-profile:v', '3', join(dir, 'a.mov')]);+ writeFileSync(join(dir, 'film.html'), filmHtml({ stage: { w: 320, h: 180 }, tracks: [{ clips: [{ id: 'v', src: 'a.mov', at: 0, time: [0, 1] }] }] }));+ const seen = await look([dir, '0.5']);+ const [r, g, b] = execFileSync('ffmpeg', ['-v', 'error', '-i', seen.files[0], '-frames:v', '1', '-vf', 'crop=4:4:160:90,format=rgb24', '-f', 'rawvideo', '-']);+ assert.ok(Math.abs(r - 0x20) < 16 && Math.abs(g - 0x60) < 16 && Math.abs(b - 0xc0) < 16, `the footage's colour: ${r},${g},${b}`);+ } finally {+ rmSync(dir, { recursive: true, force: true });+ }+});diff --git a/packages/openfilm/src/shared.d.mts b/packages/openfilm/src/shared.d.mtsindex fc839c1..416d63b 100644--- a/packages/openfilm/src/shared.d.mts+++ b/packages/openfilm/src/shared.d.mts@@ -16,7 +16,8 @@ export interface OpenFilm {site: { url: string; close(): Promise<void> };close(): Promise<void>;}-export declare function open(target: string, opts?: { root?: string }): Promise<OpenFilm>;+/** `playable`: the picture is wanted, so footage the browser does not decode is served as a copy it plays (the film's video clips, or these files). */+export declare function open(target: string, opts?: { root?: string; playable?: boolean | string[]; signal?: AbortSignal }): Promise<OpenFilm>;/** The film's sound from `from` seconds on, as clips to mix: its sound clips and its videos' own sound. */export declare function filmSound(s: OpenFilm, from: number): Promise<MixClip[]>;export declare class UsageError extends Error {}diff --git a/packages/openfilm/src/shared.mjs b/packages/openfilm/src/shared.mjsindex 7fa8408..19a65e5 100644--- a/packages/openfilm/src/shared.mjs+++ b/packages/openfilm/src/shared.mjs@@ -61,7 +61,11 @@ export function parseTarget(args) {return { film, at, range };}-/** Serve the film's folder, open it in Chromium, wait for window.film and `ready`. */+/**+ * Serve the film's folder, open it in Chromium, wait for window.film and `ready`. `playable`: its picture is wanted,+ * so footage this browser does not decode (ProRes; HEVC without a chip for it) is served as a copy it plays, made+ * before the film opens (seekable.mjs): the film's video clips (`true`), or these files.+ */export async function open(target, opts = {}) {const loc = locate(target, opts.root);/* an edit is read before anything opens: its problems, every one, at once */@@ -69,10 +73,19 @@ export async function open(target, opts = {}) {const { problems } = readFilmFile(readFileSync(join(loc.dir, FILM_FILE), 'utf8'));if (problems.length) throw new FrameError(problems.length === 1 ? problems[0] : `${FILM_FILE} has ${problems.length} problems:\n ${problems.join('\n ')}`);}- const site = await serve(loc.root, { swap: opts.swap });+ /** @type {Map<string, string>} */+ const copies = new Map();+ const site = await serve(loc.root, { swap: (file) => opts.swap?.(file) ?? copies.get(file) ?? null });let browser;try { browser = await launch(opts.launch); }catch (e) { await site.close(); throw e; }+ if (opts.playable) {+ try {+ const { browserCopies, filmVideos } = await import('./seekable.mjs');+ const files = Array.isArray(opts.playable) ? opts.playable : loc.isFilm ? filmVideos(loc.root, loc.entry) : [];+ for (const [file, copy] of await browserCopies(browser, site.url, loc.root, files, { signal: opts.signal })) copies.set(file, copy);+ } catch { /* the footage as it is */ }+ }let film;try { film = await FilmPage.open(browser, site.url, loc.entry, opts); }catch (e) { await browser.close(); await site.close(); throw e; }@@ -145,7 +158,8 @@ export async function write(stream, buf) {}/**- * Where a path the film asks for (a sound's `src`, resolved from the entry as the browser would) lives on disk. The+ * Where an address the film asks for (a sound's `src`, resolved from the entry as the browser would; a clip's src made+ * one by film-doc's srcHref) lives on disk. The* file is inside the film's folder; a link out of it is followed only to media the person linked (`readableLink`,* src/media-links.mjs), as the file server does.*/diff --git a/packages/openfilm/src/timeline.mjs b/packages/openfilm/src/timeline.mjsindex 3470802..b4ec469 100644--- a/packages/openfilm/src/timeline.mjs+++ b/packages/openfilm/src/timeline.mjs@@ -2,7 +2,7 @@// in host.mjs); the file's own elements are the clips: an <iframe> a web page, a <video>, an <img> a still, an// <audio> a sound for the mix. Where each plays and sits is what film-doc.mjs reads in the file, the same reading// Studio plays and exports by; how each looks is the file's own CSS. Track 0, the first <section>, is on top.-import { clipFade, clipSpan, clipTag, declarations, fadeGain, filmHead, fittedFade, kindOf, parseFilm, pictureRect, readFilmFile, sourceAt } from './film-doc.mjs';+import { clipFade, clipSpan, clipTag, declarations, fadeGain, filmHead, fittedFade, kindOf, parseFilm, pictureRect, readFilmFile, sourceAt, srcHref } from './film-doc.mjs';import { override, restore } from './overrides.mjs';/* the file as written (without what the host puts in it), read as every reader reads it */@@ -24,7 +24,7 @@ Object.assign(document.body.style, { width: stage.w + 'px', height: stage.h + 'pconst CLIP_TAGS = new Set(['iframe', 'video', 'img', 'audio']);const sections = [...document.body.children].filter((el) => el.localName === 'section');const elements = sections.map((s) => { s.style.display = 'contents'; return [...s.children].filter((el) => CLIP_TAGS.has(el.localName)); });-const url = (src) => new URL(src, location.href);+const url = (src) => new URL(srcHref(src), location.href);/* an editor's preview (`?film-missing=skip`) plays on past a clip whose file is not there: the clip keeps its time,but is neither loaded, drawn nor heard. Anything else (a check, an export) says the missing file and stops */const SKIP_MISSING = new URL(location.href).searchParams.get('film-missing') === 'skip';@@ -213,31 +213,31 @@ function mediaShown(page) {}/*- * While a person watches, a video plays by itself instead of being sought frame by frame (a seek decodes from the- * last key frame: on a long one each frame costs more, and playback stutters). It rolls while frames come in order at- * about the clock's pace, its own pace nudged toward the film's clock; otherwise (a still moment, a scrub) it is- * sought (see glance). A video about to come on is sought ahead and starts a moment before its cut, so it is running in- * step when it shows. When frames stop coming, every video stops; a frame asked of window.film (an export's) is always- * exact.+ * While the film plays, a video plays by itself instead of being sought frame by frame (a seek decodes from the last+ * key frame: on a long one each frame costs more, and playback stutters). It is kept on the film's clock by its pace,+ * never by seeking while it is near: further off than ROLL_STEER (two frames running) it plays ROLL_NUDGE faster or+ * slower until it is back within ROLL_SETTLE, and only further off than ROLL_SEEK is it sought. The host says the film+ * plays (watch's `play`); a still moment or a scrub seeks (see glance). A video about to come on is sought ahead and+ * starts a moment before its cut, so it is running in step when it shows. When the film stops, every video stops; a+ * frame asked of window.film (an export's) is always exact.*/-const ROLL_STEP = 0.5; // s: a frame further on than this from the last one is a jump-const ROLL_DRIFT = 0.25; // s: a playing video further off the film's clock than this is sought again-const CUE_AHEAD = 1.5; // s: how long before its clip starts a video is sought, ready-const PREROLL = 0.2; // s: how long before its clip starts a video plays, hidden, to be in step at its cut-const START_LAG = 0.08; // s: how long play() takes to get a video going-let rollStop = 0;-/** the last frame drawn while a person watches: its t and when (to tell playing, in step with the clock, from a scrub) */-let lastLive = { t: -Infinity, at: 0 };-/** Keep a playing video at `want`: sought when far off, else its pace nudged until it is in step. */-function roll(c, want) {+const ROLL_SEEK = 0.5; // s: a playing video further off the film's clock than this is sought again+const ROLL_STEER = 0.04; // s: further off than this, two frames running, its pace is nudged+const ROLL_SETTLE = 0.01; // s: back within this, it plays at its own pace again+const ROLL_NUDGE = 0.03; // how much faster or slower a nudged video plays+const CUE_AHEAD = 1.5; // s: how long before its clip starts a video is sought, ready+const PREROLL = 0.2; // s: how long before its clip starts a video plays, hidden, to be in step at its cut+const START_LAG = 0.08; // s: how long play() takes to get a video going+/** Keep a playing video at `want` as the film plays at `rate`: its pace nudged when it drifts, sought when far off. */+function roll(c, want, rate) {const v = c.el;- const speed = c.span.speed ?? 1;const drift = v.currentTime - want;- if (Math.abs(drift) > ROLL_DRIFT || v.ended) { v.currentTime = want; v.playbackRate = speed; }- else {- const rate = speed * (1 - Math.max(-0.1, Math.min(0.1, drift * 2)));- if (Math.abs(v.playbackRate - rate) > 0.005) v.playbackRate = rate;- }+ if (Math.abs(drift) > ROLL_SEEK || v.ended) { v.currentTime = want; c.steer = 0; c.off = 0; }+ else if (Math.abs(drift) > ROLL_STEER) { c.off = (c.off ?? 0) + 1; if (c.off >= 2) c.steer = drift > 0 ? -1 : 1; }+ else { c.off = 0; if (Math.abs(drift) < ROLL_SETTLE) c.steer = 0; }+ /* the pace is written only when it changes: each write is work for the media pipeline */+ const pace = (c.span.speed ?? 1) * rate * (1 + (c.steer ?? 0) * ROLL_NUDGE);+ if (Math.abs(v.playbackRate - pace) > 1e-4) v.playbackRate = pace;if (v.paused) v.play().catch((e) => { if (e?.name === 'NotAllowedError') c.held = true; });c.lastWant = want;}@@ -279,25 +279,235 @@ async function glance(c, want) {});}/**- * A video whose clip starts `lead` seconds from now: sought ahead (to PREROLL before its first frame), started a- * moment before that point comes (play() takes a moment to get going), then kept in step until its cut.+ * A video whose clip starts `lead` film seconds from now, the film playing at `rate`: sought ahead (to PREROLL before+ * its first frame), started a moment before that point comes (play() takes a moment to get going), then kept in step+ * until its cut.*/-function getReady(c, lead) {+function getReady(c, lead, rate) {const v = c.el;const speed = c.span.speed ?? 1;const first = sourceAt(c.span, 0, c.row);const cue = Math.max(0, first - PREROLL * speed);const rolling = (first - cue) / speed; // the lead at which the video is at `cue`- if (lead < rolling) { roll(c, first - lead * speed); return; }+ if (lead < rolling) { roll(c, first - lead * speed, rate); return; }if (c.cued !== cue || c.lastWant !== cue) {if (!v.paused) v.pause();v.currentTime = cue;c.cued = c.lastWant = cue;}- if (lead < rolling + START_LAG && v.paused && !v.seeking && !c.held) { v.playbackRate = speed; v.play().catch((e) => { if (e?.name === 'NotAllowedError') c.held = true; }); }+ if (lead < rolling + START_LAG * rate && v.paused && !v.seeking && !c.held) {+ v.playbackRate = speed * rate;+ v.play().catch((e) => { if (e?.name === 'NotAllowedError') c.held = true; });+ }}function stopRolling() {- for (const c of clips) if (c.kind === 'video' && !c.el.paused) c.el.pause();+ for (const c of clips) {+ if (c.kind !== 'video') continue;+ if (!c.el.paused) c.el.pause();+ c.steer = 0; c.off = 0;+ }+ stopPageFootage();+}++/*+ * A page's own footage while the film plays. A page draws a video by setting its currentTime to the frame it wants and+ * waiting for that frame (SPEC §4): exact, as an export needs, but while the film plays each of those seeks decodes+ * from the last key frame, and a page showing a few videos plays them at a few frames a second. So while the film+ * plays, a video whose wanted times move on at a steady pace is played instead, at that pace, and kept on them as the+ * film's own videos are (see roll); the page is told each seek landed at once (currentTime reads what it asked, and+ * nothing is seeking). A jump, a held frame or a reverse is sought as asked, and when the film stops each such video+ * is sought exactly where its page last asked, so a still frame is as exact as ever. The page changes nothing.+ */+/** the film playing (`rate`, `now` as in draw's `play`) at the frame being drawn (`t`), or null */+let footagePlay = null;+/** which frame a person watching is being drawn (counted), or 0 for an exact one (an export's) */+let footageFrame = 0;+let footageFrames = 0;+/** each page video asked for a time while a person watches: where, at which frame and film second it was asked last,+ its pace, whether it plays by itself */+const footage = new WeakMap();+/** the page videos playing by themselves now */+const footageRolling = new Set();+const FOOTAGE_IDLE = 0.6; // film s: a playing page video not asked for this long is stopped (its page went off)++/** A task soon (a seek's events come as tasks, after whatever the page does next in its own turn). */+const soon = (() => {+ const channel = new MessageChannel();+ const queue = [];+ channel.port1.onmessage = () => queue.shift()?.();+ return (fn) => { queue.push(fn); channel.port2.postMessage(0); };+})();+/** `seeked`s said for a seek not made, a frame: a page asking again for a frame it gave up on is not answered on and on */+const SAID_MOST = 2;++/** Take over the time a page's videos are asked for (once a page): see above. */+function steerFootage(win) {+ const proto = win.HTMLMediaElement?.prototype;+ if (!proto || Object.hasOwn(proto, '__filmFootage')) return;+ const own = Object.getOwnPropertyDescriptor(proto, 'currentTime');+ Object.defineProperty(proto, '__filmFootage', { value: true });+ Object.defineProperty(proto, 'currentTime', {+ configurable: true, enumerable: true,+ get() { const f = footage.get(this); return f?.rolling ? f.want : own.get.call(this); },+ set(value) {+ const how = footageAsked(this, Number(value), own, win);+ if (how === 'seek') { own.set.call(this, value); return; }+ if (how === 'drop') return;+ /* the page waits for its seek as for any (SPEC §4): it lands at once, said as a seek is */+ const f = footage.get(this);+ if (f.said.seq !== f.seq) f.said = { seq: f.seq, n: 0 };+ if (++f.said.n > SAID_MOST) return;+ soon(() => this.dispatchEvent(new win.Event('seeked')));+ },+ });+}++/**+ * A page asks for its video `v` at `want` (media seconds): 'seek' to seek as asked; 'play' when it plays on there by+ * itself (the page is told its seek landed); 'drop' for an ask of a frame given up on (see below), neither sought nor+ * answered. `own`: the page's own currentTime, before this one took it over.+ */+function footageAsked(v, want, own, win) {+ const play = footagePlay;+ const frame = footageFrame;+ const f = footage.get(v);+ if (!frame || !(v instanceof win.HTMLVideoElement) || !Number.isFinite(want)) { footageStop(v, false); return 'seek'; }+ if (!f) { footage.set(v, { own, want, t: play?.t ?? null, seq: frame, pace: null, rolling: false, steer: 0, off: 0, said: { seq: null, n: 0 } }); return 'seek'; }+ if (f.seq === frame) {+ /* asked again within the same frame for the same time: the page making sure */+ if (Math.abs(want - f.want) < 1e-6) return f.rolling ? 'play' : 'seek';+ /* for another time, once this frame asked: an earlier frame's wait, left when the host gave up on that frame+ (a slow seek while playing or scrubbing), asking for that frame's time when a seek of this one lands. Sought,+ it would undo this frame's, which would ask again, and so on: the first ask of a frame stands */+ return 'drop';+ }+ f.seq = frame;+ /* a later frame, still: sought as asked */+ if (!play) { f.want = want; f.t = null; f.pace = null; return 'seek'; }+ /* playing: how far on the film went since the last ask, and the video with it */+ const dt = f.t == null ? 0 : play.t - f.t;+ const pace = dt > 0 ? (want - f.want) / dt : 0;+ /* moving on at a pace a video can play at, the same as the frame before: it plays (or plays on) at that pace. A gap+ between asks is a jump, unless it went on playing meanwhile (under a render, see playRenders) */+ const steady = pace > 0.0625 && pace < 16 && (dt < 0.5 || f.rolling) && f.pace != null && Math.abs(pace - f.pace) <= 0.02 * f.pace;+ f.t = play.t;+ f.pace = pace;+ if (!steady || v.readyState < 2) { footageStop(v, false); f.want = want; return 'seek'; }+ f.want = want;+ /* where it should be this moment: the frame asked is the one on its way to the screen, a moment from now */+ const expected = Math.max(0, want - pace * (play.t - play.now));+ const drift = own.get.call(v) - expected;+ if (!f.rolling) {+ own.set.call(v, expected);+ f.rolling = true;+ f.steer = 0; f.off = 0;+ footageRolling.add(v);+ } else if (Math.abs(drift) > ROLL_SEEK || v.ended) {+ own.set.call(v, expected);+ f.steer = 0; f.off = 0;+ } else if (Math.abs(drift) > ROLL_STEER) { f.off += 1; if (f.off >= 2) f.steer = drift > 0 ? -1 : 1; }+ else { f.off = 0; if (Math.abs(drift) < ROLL_SETTLE) f.steer = 0; }+ const rate = pace * play.rate * (1 + f.steer * ROLL_NUDGE);+ if (Math.abs(v.playbackRate - rate) > 1e-4) v.playbackRate = rate;+ /* a page has no sound (SPEC: every sound is a clip): never heard */+ v.muted = true;+ if (v.paused) v.play().catch(() => footageStop(v));+ return 'play';+}++/**+ * A page video that played by itself stops, sought exactly to where its page last asked (not with `seek` false: the+ * page is seeking it itself now).+ */+function footageStop(v, seek = true) {+ const f = footage.get(v);+ if (!f?.rolling) return;+ f.rolling = false;+ f.pace = null;+ footageRolling.delete(v);+ if (!v.paused) v.pause();+ if (seek) f.own.set.call(v, f.want);+}++/** The film stopped: every page video playing by itself stops where it was asked last. */+function stopPageFootage() {+ footagePlay = null;+ for (const v of [...footageRolling]) footageStop(v);+}++/** While playing: a page video no frame asked for lately (its page went off, or stopped showing it) stops. */+function idleFootage(t) {+ for (const v of [...footageRolling]) if (t - footage.get(v).t > FOOTAGE_IDLE) footageStop(v);+}++/*+ * Renders: stretches of the film an editor had rendered into a video because they played late (Studio's preview+ * renders), given as `{ a, b, src }`. While the film plays through one, its video plays above everything, kept on the+ * film's clock as a video clip is; the clips under it are drawn only a few times a second, out of sight, and every+ * frame again just before it ends, so they are on screen as it ends. Stopped, the film is drawn as ever and the render+ * goes once that is on screen. A film exported or looked at has none.+ */+const renders = [];+const RENDER_HANDOVER = 0.5; // s: how long before a render ends the clips under it are drawn every frame again+const RENDER_WARM = 0.25; // s: before that, they are drawn this often, out of sight (see draw)+/** the film second the clips under a render were last drawn at */+let warmAt = -Infinity;+/** the render playing now, or null */+let renderOn = null;++/** The renders the film has now (each a video clip of its own, kept while it is the same stretch of the same file). */+function setRenders(list) {+ const kept = new Map(renders.map((r) => [`${r.row.src}\0${r.at}\0${r.end}`, r]));+ const next = [];+ for (const { a, b, src } of list) {+ const key = `${src}\0${a}\0${b}`;+ const had = kept.get(key);+ if (had) { kept.delete(key); next.push(had); continue; }+ const el = document.createElement('video');+ el.muted = true; el.playsInline = true; el.preload = 'none';+ Object.assign(el.style, { position: 'absolute', left: '0', top: '0', margin: '0', objectFit: 'fill', visibility: 'hidden', pointerEvents: 'none' });+ document.body.append(el);+ next.push({ kind: 'video', id: `render ${a}-${b}`, el, at: a, end: b, span: { from: 0, to: b - a, speed: 1, length: b - a }, row: { src }, awake: null });+ }+ for (const r of kept.values()) { r.el.pause(); r.el.removeAttribute('src'); r.el.load(); r.el.remove(); if (renderOn === r) renderOn = null; }+ renders.splice(0, renders.length, ...next);+}++/**+ * While playing (`play`), at frame t: the render the film is in plays and shows, one coming up gets ready. True when+ * the clips are not to be drawn this frame (a render covers them, not near its end).+ */+function playRenders(t, play) {+ const on = play ? renders.find((r) => play.now >= r.at && play.now < r.end) ?? null : null;+ for (const r of renders) {+ Object.assign(r.el.style, { width: stage.w + 'px', height: stage.h + 'px', zIndex: String(doc.tracks.length + 1) });+ if (r === on) continue;+ if (play && r.at > play.now && r.at - play.now < WAKE_AHEAD * play.rate) {+ if (!r.awake) { r.el.preload = 'auto'; r.el.src = r.row.src; r.awake = true; }+ if (r.at - play.now < CUE_AHEAD * play.rate) getReady(r, r.at - play.now, play.rate);+ continue;+ }+ if (!r.el.paused) r.el.pause();+ /* far from where the film plays: its file let go, as a video clip's (see near) */+ if (r.awake && play && (r.at - play.now > KEEP || play.now - r.end > KEEP)) { r.el.removeAttribute('src'); r.el.load(); r.awake = null; }+ }+ if (!on) { renderOn = null; return false; }+ if (!on.awake) { on.el.preload = 'auto'; on.el.src = on.row.src; on.awake = true; }+ roll(on, play.now - on.at, play.rate);+ if (on.el.readyState < 2) { renderOn = null; return false; }+ /* the clips under it are not drawn, but their videos play on, out of sight: paused, a page's many would be let go+ by the browser (it suspends paused players past a few), and at the render's end each is still in step */+ renderOn = on;+ on.el.style.visibility = 'visible';+ return t < on.end - RENDER_HANDOVER;+}+/** The renders but `keep` go from the screen (the film drawn under them is all there). */+function hideRenders(keep = null) {+ for (const r of renders) {+ if (r === keep) continue;+ if (r.el.style.visibility !== 'hidden') r.el.style.visibility = 'hidden';+ if (!r.el.paused) r.el.pause();+ }}/*@@ -384,6 +594,7 @@ function wakePage(c) {const win = el.contentWindow;await ready(win.film);if (c.waking !== mine) return;+ steerFootage(win);c.win = win;c.child = win.film;c.touched = new Map();@@ -551,6 +762,9 @@ async function load(row, track, ti, el) {if (!facts && !(await mustBeThere(row.src))) c.missing = true;c.native = facts?.duration ?? 0;} else if (kind === 'still') {+ /* its file as the film names it: a name written with a bare `?` or `%` asks the browser for another file */+ const href = url(row.src).href;+ if (el.src.replace(/#.*$/, '') !== href) el.src = href;await el.decode().catch(() => {});if (!el.naturalWidth && !(await mustBeThere(row.src))) c.missing = true;c.nw = el.naturalWidth || stage.w; c.nh = el.naturalHeight || stage.h;@@ -606,19 +820,15 @@ loading.catch(() => {});let watched = 0;/**- * Draw the film at t. `live`: a person is watching (an editor, or the film opened as a page), so videos play by- * themselves while frames come in order, and a scrub's frame does not wait for its video to be on screen; otherwise- * the frame is exact (an export's, `look`'s).+ * Draw the film at t. `live`: a person is watching (an editor, or the film opened as a page), so a scrub's frame does+ * not wait for its video to be on screen; otherwise the frame is exact (an export's, `look`'s). `play`: the film is+ * playing, `rate` film seconds a second, and is at film second `now` this moment (t is the frame on its way to the+ * screen, a moment later): videos play by themselves, kept on that clock; without it, every video stops.*/-async function draw(t, live) {+async function draw(t, live, play = null) {shownT = t;- clearTimeout(rollStop);- if (live) rollStop = setTimeout(stopRolling, 150); else stopRolling();- /* playing: this frame follows the last one at about the clock's pace (a scrub goes anywhere at any pace) */- const now = performance.now();- const pace = (t - lastLive.t) / Math.max(1e-3, (now - lastLive.at) / 1000);- const playing = live && t >= lastLive.t && t - lastLive.t < ROLL_STEP && pace > 0.5 && pace < 2;- lastLive = live ? { t, at: now } : { t: -Infinity, at: 0 };+ const playing = live && play != null;+ if (!playing) stopRolling();clearTimeout(settleNear);if (live && !playing) { near(t, { only: true }); settleNear = setTimeout(() => near(t), 250); } else near(t, { exact: !live });/* watched, a page coming on shows once its frame is drawn, and the pictures going off stay until then: shown first,@@ -626,9 +836,20 @@ async function draw(t, live) {its frame took, a flash at the cut. An exact frame is taken when all of it is drawn, so it shows each at once. */const turn = live ? ++watched : 0;const coming = [], going = [];+ /* a render of this stretch plays instead of the clips (see setRenders). Under it they are drawn a few times a+ second, out of sight: what a page loads as it goes (its footage, its pictures) comes as it would, not all at once+ as the render ends, and its footage goes on playing in step */+ if (live && playRenders(t, playing ? play : null) && Math.abs(t - warmAt) < RENDER_WARM) return;+ warmAt = t;+ /* the pages' footage plays by itself while the film does (see steerFootage) */+ footageFrame = live ? ++footageFrames : 0;+ footagePlay = playing ? { rate: play.rate, now: play.now, t } : null;try {- await Promise.all(clips.map((c) => drawClip(c, t, live, playing, turn, coming, going)));+ await Promise.all(clips.map((c) => drawClip(c, t, live, playing ? play : null, turn, coming, going)));+ if (playing) idleFootage(t);} finally {+ /* the film drawn: a render not playing now goes */+ hideRenders(playing ? renderOn : null);for (const c of coming) if (c.coming === turn) c.coming = 0;if (live && turn === watched) {for (const c of going) if (!c.shown) c.el.style.visibility = 'hidden';@@ -638,7 +859,7 @@ async function draw(t, live) {}/** One clip's part of a frame (see draw): a page coming on while watched is put in `coming`, a picture going off in `going`. */-async function drawClip(c, t, live, playing, turn, coming, going) {+async function drawClip(c, t, live, play, turn, coming, going) {if (c.kind === 'sound') return;const on = !c.hidden && !c.missing && t >= c.at && t < c.end;c.shown = on;@@ -649,14 +870,19 @@ async function drawClip(c, t, live, playing, turn, coming, going) {if (on) fadeAt(c, t);if (!on) {if (c.kind !== 'video') return;- if (playing && c.awake && c.at > t && c.at - t < CUE_AHEAD) getReady(c, c.at - t);+ if (play && c.awake && c.at > t && c.at - play.now < CUE_AHEAD * play.rate) getReady(c, c.at - play.now, play.rate);else { if (!c.el.paused) c.el.pause(); c.lastWant = c.cued = undefined; }return;}if (c.kind === 'still') return;if (c.kind === 'video') {+ if (play) {+ /* where it should be this moment (not at the frame on its way): its own clock runs on to that frame */+ const playing = sourceAt(c.span, Math.min(Math.max(0, play.now - c.at), c.span.length), c.row);+ if (c.held) step(c, playing); else roll(c, playing, play.rate);+ return;+ }const want = sourceAt(c.span, t - c.at, c.row);- if (playing) { if (c.held) step(c, want); else roll(c, want); return; }c.held = false;if (live) { await glance(c, want); return; }if (!c.el.paused) c.el.pause();@@ -901,8 +1127,8 @@ function describe(c, el) {}window.__filmEditor = {- /** Draw the film at t for a person watching it (see draw). */- watch: (t) => draw(t, true),+ /** Draw the film at t for a person watching it (see draw); `play` while it plays: `{ rate, now }`. */+ watch: (t, play = null) => draw(t, true, play),/*** For Studio's stage (studio/server/stage.js): the clips as loaded, a clip placed by a box not kept yet (null: by* its own again), `updated`, which the stage sets to hear of each update made in place, and `woke`, to hear of a page@@ -933,6 +1159,10 @@ window.__filmEditor = {changing = changing.then(() => change(value, look)).catch(() => false);return changing;},+ /** The stretches rendered for the preview, `{ a, b, src }` (see setRenders); [] none. */+ renders(list) { setRenders(Array.isArray(list) ? list.filter((r) => r && r.b > r.a && typeof r.src === 'string') : []); },+ /** Whether a render plays in the film's place now. */+ rendering: () => renderOn != null,/** Show `overrides` on a page clip instead of its own until called with null (a drag, a typed word). */preview(id, overrides) {const c = clips.find((x) => x.id === id && x.kind === 'page');@@ -960,6 +1190,10 @@ window.__filmEditor = {if (!window.filmHost) {await loading;const t0 = performance.now();- const loop = async () => { await draw(((performance.now() - t0) / 1000) % film.duration, true); requestAnimationFrame(loop); };+ const loop = async () => {+ const t = ((performance.now() - t0) / 1000) % film.duration;+ await draw(t, true, { rate: 1, now: t });+ requestAnimationFrame(loop);+ };loop();}diff --git a/packages/openfilm/src/timeline.test.mjs b/packages/openfilm/src/timeline.test.mjsindex c718b3c..1d74946 100644--- a/packages/openfilm/src/timeline.test.mjs+++ b/packages/openfilm/src/timeline.test.mjs@@ -793,3 +793,198 @@ window.seen.push(look());await new Promise((r)=>setTimeout(r,150));window.seen.pawait s.close();}});++/**+ * Play the film in its page as Studio's preview does (src/../studio/server/bridge.js): a frame each refresh, on the+ * film's frame grid, for `seconds`, from film second 0. Says how long each frame took to draw (ms).+ */+async function playFor(film, seconds, fps = 30) {+ return film.page.evaluate(async ([seconds, fps]) => {+ const clock = window.filmHost?.now ?? performance.now.bind(performance);+ const t0 = clock();+ const took = [];+ let last = -1;+ while (clock() - t0 < seconds * 1000) {+ await new Promise((r) => requestAnimationFrame(r));+ const now = (clock() - t0) / 1000;+ const t = Math.floor((now + 1 / 60) * fps + 1e-6) / fps;+ if (t === last) continue;+ last = t;+ const s = clock();+ await window.__filmEditor.watch(t, { rate: 1, now });+ took.push(clock() - s);+ }+ return took;+ }, [seconds, fps]);+}++test('playing, a video plays by itself on the film\'s clock, not sought frame by frame; a still moment stops it there', { skip: !hasFfmpeg && 'no ffmpeg', timeout: 120_000 }, async () => {+ const dir = mkdtempSync(join(tmpdir(), 'of-roll-'));+ execFileSync('ffmpeg', ['-v', 'error', '-f', 'lavfi', '-i', 'testsrc=size=320x180:rate=30:duration=4', '-pix_fmt', 'yuv420p', '-g', '15', join(dir, 'clip.mp4')]);+ writeFileSync(join(dir, 'film.html'), filmHtml({ stage: { w: 320, h: 180 }, tracks: [{ clips: [{ id: 'clip', src: 'clip.mp4' }] }] }));+ const s = await open(dir);+ try {+ await s.film.page.evaluate(() => {+ const v = document.getElementById('clip');+ window.seeks = 0;+ v.addEventListener('seeking', () => { window.seeks += 1; });+ });+ await playFor(s.film, 2);+ const playing = await s.film.page.evaluate(() => { const v = document.getElementById('clip'); return { seeks: window.seeks, paused: v.paused, time: v.currentTime }; });+ assert.ok(playing.seeks <= 2, `sought ${playing.seeks} times in two seconds of playing`);+ assert.ok(!playing.paused && playing.time > 1.5, JSON.stringify(playing));+ /* stopped: a still moment is the exact frame, the video paused there */+ const still = await s.film.page.evaluate(async () => {+ await window.__filmEditor.watch(1.25);+ const v = document.getElementById('clip');+ return { paused: v.paused, time: v.currentTime };+ });+ assert.ok(still.paused && Math.abs(still.time - 1.25) < 0.01, JSON.stringify(still));+ } finally {+ await s.close();+ }+});++test('playing, a page\'s own video asked for frame by frame plays by itself, each frame drawn at once; stopped, it is where the page asked', { skip: !hasFfmpeg && 'no ffmpeg', timeout: 120_000 }, async () => {+ const dir = mkdtempSync(join(tmpdir(), 'of-footage-'));+ execFileSync('ffmpeg', ['-v', 'error', '-f', 'lavfi', '-i', 'testsrc=size=320x180:rate=30:duration=5', '-pix_fmt', 'yuv420p', '-g', '15', join(dir, 'rec.mp4')]);+ /* a page that draws its footage as SPEC §4 says: its time set to the frame wanted, then waited for */+ writeFileSync(join(dir, 'page.html'), `<!doctype html><body style="margin:0"><video id="v" src="rec.mp4" muted playsinline preload="auto" style="width:320px;height:180px"></video>+<script>+const v = document.getElementById('v');+window.asked = [];+const seekTo = (want) => new Promise((ok) => {+ const go = () => {+ if (!v.seeking && v.readyState >= 2 && Math.abs(v.currentTime - want) < 0.002) return ok();+ v.addEventListener('seeked', go, { once: true });+ if (Math.abs(v.currentTime - want) >= 0.002) v.currentTime = want;+ };+ go();+});+window.film = {+ duration: 4, width: 320, height: 180,+ ready: new Promise((r) => (v.readyState >= 2 ? r() : v.addEventListener('loadeddata', r, { once: true }))),+ frame(t) { const want = Math.floor(t * 30 + 1e-6) / 30 + 0.5 / 30; window.asked.push(want); return seekTo(want); },+};+</script></body>`);+ writeFileSync(join(dir, 'film.html'), filmHtml({ stage: { w: 320, h: 180 }, tracks: [{ clips: [{ id: 'page', src: 'page.html' }] }] }));+ const s = await open(dir);+ try {+ await s.film.page.evaluate(() => {+ const v = document.getElementById('page').contentDocument.getElementById('v');+ window.seeks = 0;+ v.addEventListener('seeking', () => { window.seeks += 1; });+ });+ const took = await playFor(s.film, 2);+ const playing = await s.film.page.evaluate(() => {+ const page = document.getElementById('page').contentWindow;+ const v = page.document.getElementById('v');+ return { seeks: window.seeks, frames: page.asked.length, paused: v.paused, time: v.currentTime, said: v.currentTime === page.asked.at(-1) };+ });+ assert.ok(playing.frames >= 40, `${playing.frames} frames drawn`);+ assert.ok(playing.seeks <= 4, `sought ${playing.seeks} times for ${playing.frames} frames`);+ assert.ok(!playing.paused && playing.said, `it plays, and the page reads the time it asked for: ${JSON.stringify(playing)}`);+ took.sort((a, b) => a - b);+ assert.ok(took[Math.floor(took.length * 0.9)] < 20, `each frame drawn at once, not after a seek: ${took.slice(-5)}`);+ /* stopped: the still moment is exact, as an export's */+ const still = await s.film.page.evaluate(async () => {+ await window.__filmEditor.watch(1.25);+ const page = document.getElementById('page').contentWindow;+ const v = page.document.getElementById('v');+ return { paused: v.paused, time: v.currentTime, want: page.asked.at(-1) };+ });+ assert.ok(still.paused && Math.abs(still.time - still.want) < 0.002 && Math.abs(still.want - (37 / 30 + 0.5 / 30)) < 1e-6, JSON.stringify(still));+ } finally {+ await s.close();+ }+});++test('playing through a stretch rendered for the preview, its render shows, the clips under it drawn only now and then; stopped, they are', { skip: !hasFfmpeg && 'no ffmpeg', timeout: 120_000 }, async () => {+ const dir = mkdtempSync(join(tmpdir(), 'of-render-'));+ execFileSync('ffmpeg', ['-v', 'error', '-f', 'lavfi', '-i', 'color=c=red:size=320x180:rate=30:duration=2', '-pix_fmt', 'yuv420p', join(dir, 'render.mp4')]);+ /* a page that counts the frames it is asked for */+ writeFileSync(join(dir, 'p.html'), `<!doctype html><body style="margin:0;background:#00f"><script>window.drawn=[];window.film={duration:4,width:320,height:180,frame(t){window.drawn.push(t)}}</script></body>`);+ writeFileSync(join(dir, 'film.html'), filmHtml({ stage: { w: 320, h: 180 }, tracks: [{ clips: [{ id: 'p', src: 'p.html' }] }] }));+ const s = await open(dir);+ try {+ const seen = await s.film.page.evaluate(async () => {+ const page = document.getElementById('p').contentWindow;+ window.__filmEditor.renders([{ a: 0.5, b: 2.5, src: 'render.mp4' }]);+ const clock = window.filmHost?.now ?? performance.now.bind(performance);+ const t0 = clock();+ const log = [];+ let last = -1;+ while (clock() - t0 < 2700) {+ await new Promise((r) => requestAnimationFrame(r));+ const now = (clock() - t0) / 1000;+ const t = Math.floor((now + 1 / 60) * 30 + 1e-6) / 30;+ if (t === last) continue;+ last = t;+ const before = page.drawn.length;+ await window.__filmEditor.watch(t, { rate: 1, now });+ const render = [...document.querySelectorAll('body > video')].at(-1);+ log.push({ t, drew: page.drawn.length > before, render: render.style.visibility });+ }+ await window.__filmEditor.watch(1.5);+ const render = [...document.querySelectorAll('body > video')].at(-1);+ return { log, still: { drew: page.drawn.at(-1), render: render.style.visibility, paused: render.paused } };+ });+ const inside = seen.log.filter((f) => f.t >= 1 && f.t < 1.9);+ assert.ok(inside.length > 10 && inside.every((f) => f.render === 'visible'), `inside the render: ${JSON.stringify(inside.slice(0, 3))}`);+ /* under it, the clips are drawn only a few times a second, out of sight, so what they load comes as it would */+ const drew = inside.filter((f) => f.drew).length;+ assert.ok(drew >= 2 && drew <= 6, `drawn under the render ${drew} times in 0.9 s`);+ assert.ok(seen.log.filter((f) => f.t < 0.4).every((f) => f.drew && f.render === 'hidden'), 'before it: the film itself');+ assert.ok(seen.log.filter((f) => f.t >= 2.1 && f.t < 2.45).every((f) => f.drew), 'just before it ends: the clips are drawn again under it');+ assert.ok(seen.log.filter((f) => f.t >= 2.55).every((f) => f.drew && f.render === 'hidden'), 'after it: the film itself');+ assert.deepEqual(seen.still, { drew: 1.5, render: 'hidden', paused: true }, 'stopped: the film itself, exact');+ } finally {+ await s.close();+ }+});++for (const playing of [true, false]) test(`${playing ? 'playing' : 'scrubbing'}, frames asked before the last is drawn (a host giving up on a slow one) do not leave a page's footage sought back and forth`, { skip: !hasFfmpeg && 'no ffmpeg', timeout: 120_000 }, async () => {+ const dir = mkdtempSync(join(tmpdir(), 'of-giveup-'));+ /* a heavy recording, a key frame in five seconds: each seek takes a while, so frames overlap */+ execFileSync('ffmpeg', ['-v', 'error', '-f', 'lavfi', '-i', 'testsrc2=size=1920x1080:rate=30:duration=5', '-pix_fmt', 'yuv420p', '-g', '150', join(dir, 'rec.mp4')]);+ writeFileSync(join(dir, 'page.html'), `<!doctype html><body style="margin:0"><video id="v" src="rec.mp4" muted playsinline preload="auto"></video>+<script>+const v = document.getElementById('v');+const seekTo = (want) => new Promise((ok) => {+ const go = () => {+ if (!v.seeking && v.readyState >= 2 && Math.abs(v.currentTime - want) < 0.002) return ok();+ v.addEventListener('seeked', go, { once: true });+ if (Math.abs(v.currentTime - want) >= 0.002) v.currentTime = want;+ };+ go();+});+window.film = { duration: 4, width: 320, height: 180,+ ready: new Promise((r) => (v.readyState >= 2 ? r() : v.addEventListener('loadeddata', r, { once: true }))),+ frame(t) { return seekTo(Math.floor(t * 30 + 1e-6) / 30 + 0.5 / 30); } };+</script></body>`);+ writeFileSync(join(dir, 'film.html'), filmHtml({ stage: { w: 320, h: 180 }, tracks: [{ clips: [{ id: 'page', src: 'page.html' }] }] }));+ const s = await open(dir);+ try {+ const seen = await s.film.page.evaluate(async (playing) => {+ const v = document.getElementById('page').contentDocument.getElementById('v');+ let seeks = 0;+ v.addEventListener('seeking', () => { seeks += 1; });+ /* ten frames, each asked before the one before is drawn, far apart in the file (each one a real seek), as a+ host that gave up on each in turn would */+ const drawn = [];+ for (const t of [0, 2, 0.7, 3.1, 1.4, 2.6, 0.2, 1.9, 3.5, 1]) {+ drawn.push(window.__filmEditor.watch(t, playing ? { rate: 1, now: t } : null));+ await new Promise((r) => setTimeout(r, 5));+ }+ const all = await Promise.race([Promise.all(drawn.slice(-1)).then(() => true), new Promise((r) => setTimeout(() => r(false), 5000))]);+ /* left alone a moment: nothing goes on seeking by itself */+ const after = seeks;+ await new Promise((r) => setTimeout(r, 1000));+ return { all, seeks, more: seeks - after };+ }, playing);+ assert.ok(seen.all, 'the last frame drawn');+ assert.equal(seen.more, 0, `still seeking on its own: ${JSON.stringify(seen)}`);+ } finally {+ await s.close();+ }+});diff --git a/packages/openfilm/studio/client.mjs b/packages/openfilm/studio/client.mjsindex babeb98..e79e6f1 100644--- a/packages/openfilm/studio/client.mjs+++ b/packages/openfilm/studio/client.mjs@@ -32,7 +32,7 @@ async function health(/** @type {string} */ origin, ms = 1500) {* run.json was lost; it opens with the machine's key, so it can still be used).* @returns {Promise<Running | null>}*/-async function running() {+export async function running() {/** @type {Running | null} */let run = null;try { run = JSON.parse(readFileSync(join(studioHome(), 'run.json'), 'utf8')); } catch { /* none advertised */ }diff --git a/packages/openfilm/studio/server/bridge.js b/packages/openfilm/studio/server/bridge.jsindex e89768b..4acb679 100644--- a/packages/openfilm/studio/server/bridge.js+++ b/packages/openfilm/studio/server/bridge.js@@ -2,13 +2,22 @@* Studio's bridge into the film's timeline page (src/timeline.mjs), injected after the host flag and before the* page's own script. The editor, on another origin, drives the film through it:*- * editor → { source: 'openfilm-studio', type: 'seek', t, seq, behind } draw the film at t (`behind`: this load- * is not shown yet, another one is: its first picture is waited for whole)+ * editor → { source: 'openfilm-studio', type: 'seek', t, seq, behind } draw the film at t, still (`behind`: this+ * load is not shown yet, another one is: its first picture is waited for whole)+ * { type: 'play', t, at, rate, fps } play: film second t at `at` (ms on this page's clock), `rate` film+ * seconds a second; the frames are drawn here, on the film's frame grid+ * { type: 'clock', ping } what this page's clock says now (to put the editor's moments on it)* { type: 'update', film, head, seq } film.html changed: change the film in place if it can be+ * { type: 'renders', list } stretches rendered for the preview to play in their place: [{ a, b, src }]* { type: 'preview', clip, overrides } show a tweak on a page, not kept (null: stop showing)* { type: 'pick', x, y, seq } what is under this stage point- * film → { source: 'openfilm-film', type: 'ready', duration, width, height, sounds, spans }+ * film → { source: 'openfilm-film', type: 'ready', duration, width, height, sounds, spans, origin }* { type: 'seeked', t, seq } the frame at t is on screen+ * { type: 'clock', ping, now } this page's clock (performance.now) when the ping came+ * { type: 'played', frames, drawn, late, rendered, ms, spans } while playing, about once a second over+ * `ms`: the screen's refreshes, the film's frames drawn, the refreshes that got+ * no new frame, whether a render played, and per half second of film [its start,+ * refreshes, late]* { type: 'updated', seq, inPlace, duration, sounds, spans } (inPlace false: load the page again)* { type: 'picked', seq, target } (null: nothing there)* { type: 'error', message } the film or a page failed@@ -24,6 +33,8 @@const fail = (error) => post({ type: 'error', message: String(error?.message ?? error ?? 'the film failed') });window.addEventListener('error', (e) => fail(e.error ?? e.message));window.addEventListener('unhandledrejection', (e) => fail(e.reason));+ /* the page's real clock: the host holds performance.now() at a frame's t while it draws one (src/host.mjs) */+ const clock = () => (window.filmHost?.now ?? performance.now.bind(performance))();/* window.film is set by the page's module script, which runs after this one: wait for it */const film = new Promise((resolve) => {@@ -35,8 +46,9 @@/* the film once loaded, or null: one that fails to load (a clip with no length, a missing file) says why once, here,and draws and answers nothing after — a page error for each later message would only repeat it */+ let up = null;const loaded = film.then(async (f) => {- try { await f.ready; post({ type: 'ready', ...facts(f) }); return f; } catch (e) { fail(e); return null; }+ try { await f.ready; up = f; post({ type: 'ready', ...facts(f), origin: performance.timeOrigin }); return f; } catch (e) { fail(e); return null; }});/* one frame at a time: a seek that comes while one is drawing waits, and only the latest waiting one is drawn */@@ -56,9 +68,9 @@try {const f = await loaded;if (!f) { drawing = false; return; }- /* a person is watching: the timeline draws for them (videos play by themselves, a scrub does not wait for them to- be composited); a page on its own draws its frame. A frame that does not come within a moment is let go: one- stuck page or video must not stop the picture. */+ /* a person is watching: the timeline draws for them (a scrub does not wait for its videos to be composited); a+ page on its own draws its frame. A frame that does not come within a moment is let go: one stuck page or+ video must not stop the picture. */const watch = editor()?.watch;let timer;await Promise.race([watch ? watch(t) : f.frame(t), new Promise((done) => { timer = setTimeout(done, behind ? BEHIND_WAIT_MS : FRAME_WAIT_MS); })]);@@ -66,13 +78,97 @@post({ type: 'seeked', t, seq });} catch (e) { fail(e); }drawing = false;- draw();+ if (line) requestFrame(); else draw();};+ /*+ * Playing: the frames are drawn here, one each time the screen refreshes, from the line the editor gave (where the+ * film is, from its sound), not one message a frame from the editor: a busy editor does not hold the picture. Each+ * frame is the film where it will be when that frame reaches the screen (a refresh from now), on the film's frame+ * grid, so a 60 fps film on a 120 Hz screen draws each of its frames once and shows it twice. A frame still being+ * drawn when the next refresh comes is let finish; the one after it is the film where it is then (frames are dropped,+ * never queued).+ */+ let line = null;+ let raf = 0;+ /* the last frame drawn while playing, and how long the screen takes between frames (ms, measured as it plays) */+ let lastT = null;+ let refresh = 1000 / 60;+ let lastTick = 0;+ /* what the editor is told about how playing goes: frames drawn and late, and late frames per half second of film */+ let tally = { frames: 0, drawn: 0, late: 0, since: 0, rendered: false, spans: new Map() };+ const requestFrame = () => { if (!raf) raf = requestAnimationFrame(tick); };+ const lineAt = (ms) => line.t + (Math.max(0, ms - line.at) / 1000) * line.rate;+ async function tick() {+ raf = 0;+ if (!line || !up) return;+ requestFrame();+ const now = clock();+ const gap = lastTick ? now - lastTick : 0;+ lastTick = now;+ if (gap > 2 && gap < 60) refresh += (Math.min(gap, refresh * 2) - refresh) * 0.1;+ /* refreshes the screen got no new frame for (this one came more than half a frame after it was due) */+ const late = gap > refresh * 1.5 ? Math.round(gap / refresh) - 1 : 0;+ const end = Math.max(0, (up.duration ?? Infinity) - 1e-3);+ let t = Math.min(lineAt(now + refresh), end);+ if (line.fps > 0) t = Math.min(Math.floor(t * line.fps + 1e-6) / line.fps, end);+ count(t, late || (drawing && t !== lastT ? 1 : 0));+ if (drawing || t === lastT) return;+ lastT = t;+ drawing = true;+ tally.drawn += 1;+ try {+ const watch = editor()?.watch;+ const play = { rate: line.rate, now: Math.min(lineAt(now), end) };+ let timer;+ await Promise.race([watch ? watch(t, play) : up.frame(t), new Promise((done) => { timer = setTimeout(done, FRAME_WAIT_MS); })]);+ clearTimeout(timer);+ } catch (e) { fail(e); }+ drawing = false;+ /* a seek that came while this frame drew (the film stopped): drawn now */+ if (next) draw();+ }+ /** Count a refresh while playing at film second t, and tell the editor how it went about once a second. */+ function count(t, late) {+ tally.frames += 1;+ tally.late += late;+ if (editor()?.rendering?.()) tally.rendered = true;+ const half = Math.floor(t * 2) / 2;+ const span = tally.spans.get(half) ?? [0, 0];+ span[0] += 1 + late;+ span[1] += late;+ tally.spans.set(half, span);+ const now = clock();+ if (!tally.since) tally.since = now;+ if (now - tally.since >= 1000) say();+ }+ function say() {+ if (tally.frames) post({ type: 'played', frames: tally.frames, drawn: tally.drawn, late: tally.late, rendered: tally.rendered, ms: Math.round(clock() - tally.since), spans: [...tally.spans].map(([t, [frames, late]]) => [t, frames, late]) });+ tally = { frames: 0, drawn: 0, late: 0, since: 0, rendered: false, spans: new Map() };+ }+ function stop() {+ if (!line) return;+ line = null;+ lastT = null;+ lastTick = 0;+ if (raf) cancelAnimationFrame(raf);+ raf = 0;+ say();+ }+window.addEventListener('message', async (e) => {if (e.origin !== EDITOR || e.data?.source !== 'openfilm-studio') return;const m = e.data;- if (m.type === 'seek') { next = m; asked = m.t; draw(); return; }+ if (m.type === 'clock') { post({ type: 'clock', ping: m.ping, now: clock() }); return; }+ if (m.type === 'seek') { stop(); next = m; asked = m.t; draw(); return; }+ if (m.type === 'play') {+ const fps = Number(m.fps);+ line = { t: Number(m.t), at: Number(m.at), rate: Number(m.rate) || 1, fps: fps > 0 ? fps : 0 };+ next = null;+ lastT = null;+ requestFrame();+ return;+ }const f = await loaded;if (!f) return;if (m.type === 'update') {@@ -80,9 +176,12 @@try { inPlace = Boolean(await editor()?.update(m.film, m.head)); } catch { inPlace = false; }post({ type: 'updated', seq: m.seq, inPlace, ...(inPlace ? facts(f) : {}) });/* the moment asked for, drawn again as the film is now; not the last one drawn, which is older while a draw- is still going (the first one, as the film comes up): the picture went back there, the playhead stayed */- if (inPlace && !next) { next = { t: asked, seq: m.seq }; draw(); }+ is still going (the first one, as the film comes up): the picture went back there, the playhead stayed.+ Playing, the next frame draws it */+ if (inPlace && line) lastT = null;+ else if (inPlace && !next) { next = { t: asked, seq: m.seq }; draw(); }}+ if (m.type === 'renders') editor()?.renders?.(m.list);if (m.type === 'preview') editor()?.preview(m.clip, m.overrides);if (m.type === 'pick') post({ type: 'picked', seq: m.seq, target: editor()?.pick(m.x, m.y) ?? null });});diff --git a/packages/openfilm/studio/server/bridge.test.mjs b/packages/openfilm/studio/server/bridge.test.mjsindex db324a8..cab309c 100644--- a/packages/openfilm/studio/server/bridge.test.mjs+++ b/packages/openfilm/studio/server/bridge.test.mjs@@ -6,25 +6,42 @@ import { runInNewContext } from 'node:vm';const BRIDGE = readFileSync(new URL('./bridge.js', import.meta.url), 'utf8');const EDITOR = 'http://127.0.0.1:4792';-/** The bridge in a film page of its own: the film's draws held until let go, and what it says to the editor. */-function filmPage() {+/**+ * The bridge in a film page of its own: the film's draws held until let go, and what it says to the editor. Its clock+ * and its screen's refreshes are the test's: `refresh(ms)` moves the clock on and runs the frame callbacks waiting.+ * `alone`: a web page on its own (the media pane's viewer), with no timeline in it: its own frame(t) draws.+ * `duration` null: a page without one.+ */+function filmPage({ alone = false, duration = 10 } = {}) {const listeners = new Map();const said = [];const drawn = [];+ let now = 5000;+ let frames = new Map();+ let ids = 0;+ /* each draw waits until the test lets it go */+ const held = (t, play = null) => new Promise((done) => drawn.push({ t, play, done }));const window = {addEventListener: (type, fn) => listeners.set(type, fn),- film: { duration: 10, width: 320, height: 180, ready: Promise.resolve(), frame() {} },- __filmEditor: {- /* each draw waits until the test lets it go */- watch: (t) => new Promise((done) => drawn.push({ t, done })),- update: async () => true,- },+ film: { ...(duration == null ? {} : { duration }), width: 320, height: 180, ready: Promise.resolve(), frame: alone ? (t) => held(t) : () => {} },+ ...(alone ? {} : { __filmEditor: { watch: held, update: async () => true } }),};const parent = { postMessage: (m) => said.push(m) };- runInNewContext(BRIDGE.replaceAll('__EDITOR__', JSON.stringify(EDITOR)), { window, parent, location: { origin: 'http://localhost:4793' }, setTimeout, clearTimeout, Promise });+ const performance = { now: () => now, timeOrigin: 1_700_000_000_000 };+ const requestAnimationFrame = (fn) => { frames.set(++ids, fn); return ids; };+ const cancelAnimationFrame = (id) => frames.delete(id);+ runInNewContext(BRIDGE.replaceAll('__EDITOR__', JSON.stringify(EDITOR)), { window, parent, location: { origin: 'http://localhost:4793' }, setTimeout, clearTimeout, Promise, performance, requestAnimationFrame, cancelAnimationFrame });const send = (data) => listeners.get('message')({ origin: EDITOR, data: { source: 'openfilm-studio', ...data } });const settle = () => new Promise((r) => setTimeout(r, 10));- return { send, said, drawn, settle };+ /** The screen refreshes `ms` from now: the frame callbacks waiting run, then the draws they start settle. */+ const refresh = async (ms = 1000 / 60) => {+ now += ms;+ const due = [...frames.values()];+ frames = new Map();+ for (const fn of due) fn(now);+ await settle();+ };+ return { send, said, drawn, settle, refresh, clock: () => now };}test('an edit changed in place while the first moment is still drawing is drawn at that moment, not at 0 s', async () => {@@ -59,3 +76,105 @@ test('a load of the film behind the picture shown says its first moment is drawnawait new Promise((r) => setTimeout(r, 1300));assert.deepEqual(page.said.filter((m) => m.type === 'seeked').map((m) => m.t), [3, 4]);});++test('playing, the film draws its own frames from the line it was given, each frame of its rate once, a refresh ahead', async () => {+ const page = filmPage();+ await page.settle();+ /* film second 2 at the page's 5000 ms, at 1x, a 30 fps film, on a 60 Hz screen */+ page.send({ type: 'play', t: 2, at: page.clock(), rate: 1, fps: 30 });+ for (let i = 0; i < 6; i++) {+ await page.refresh();+ page.drawn.at(-1)?.done();+ }+ await page.settle();+ const ts = page.drawn.map((d) => Math.round(d.t * 30));+ assert.deepEqual(ts, [...new Set(ts)], 'no frame drawn twice');+ assert.ok(ts.every((f, i) => i === 0 || f === ts[i - 1] + 1), `one frame after another: ${ts}`);+ /* each frame is where the film will be as it reaches the screen; its videos keep to where it is now */+ const last = page.drawn.at(-1);+ assert.ok(last.play && last.play.rate === 1 && last.play.now < last.t + 1 / 30 && last.play.now > 2, JSON.stringify(last.play));+ /* a still moment stops it: no frame after it */+ page.send({ type: 'seek', t: 7, seq: 1 });+ await page.settle();+ page.drawn.at(-1).done();+ const before = page.drawn.length;+ await page.refresh();+ await page.refresh();+ assert.equal(page.drawn.length, before);+ assert.equal(page.drawn.at(-1).t, 7);+ assert.equal(page.drawn.at(-1).play, null);+});++test('playing, a frame still drawing when the screen refreshes is let finish, and the next one drawn is where the film is then', async () => {+ const page = filmPage();+ await page.settle();+ page.send({ type: 'play', t: 0, at: page.clock(), rate: 1, fps: 60 });+ await page.refresh();+ assert.equal(page.drawn.length, 1);+ /* four refreshes while the first frame draws: nothing queued behind it */+ for (let i = 0; i < 4; i++) await page.refresh();+ assert.equal(page.drawn.length, 1);+ page.drawn[0].done();+ await page.settle();+ await page.refresh();+ assert.equal(page.drawn.length, 2);+ assert.ok(page.drawn[1].t - page.drawn[0].t > 4 / 60, 'the frames between were dropped, not drawn late');+ /* the editor hears how it went: frames the screen got late */+ page.drawn[1].done();+ await page.settle();+ page.send({ type: 'seek', t: 1, seq: 1 });+ await page.settle();+ const played = page.said.filter((m) => m.type === 'played');+ assert.ok(played.length && played.reduce((n, m) => n + m.late, 0) >= 3, JSON.stringify(played));+});++test('the film\'s clock is read with a ping, and an edit while playing is drawn by the next frame, not as a still', async () => {+ const page = filmPage();+ await page.settle();+ page.send({ type: 'clock', ping: 123 });+ assert.deepEqual(page.said.filter((m) => m.type === 'clock').map((m) => ({ ...m })), [{ source: 'openfilm-film', type: 'clock', ping: 123, now: page.clock() }]);+ assert.equal(page.said.find((m) => m.type === 'ready').origin, 1_700_000_000_000, 'where its clock starts, said as it is ready');+ page.send({ type: 'play', t: 1, at: page.clock(), rate: 1, fps: 30 });+ await page.refresh();+ page.drawn[0].done();+ await page.settle();+ await page.send({ type: 'update', film: {}, seq: 2 });+ await page.settle();+ assert.ok(page.drawn.every((d) => d.play), 'no still moment drawn for it');+ await page.refresh();+ assert.equal(page.drawn.length, 2, 'the next frame is drawn, the film as it is now');+});++test('a web page on its own plays from the line too, drawn by its own frame(t): each frame of the rate once, never past its end, until a seek', async () => {+ /* 0.2 s long at 30 fps: its frames up to the last one before its end */+ const page = filmPage({ alone: true, duration: 0.2 });+ await page.settle();+ page.send({ type: 'play', t: 0, at: page.clock(), rate: 1, fps: 30 });+ for (let i = 0; i < 20; i++) {+ await page.refresh();+ page.drawn.at(-1)?.done();+ }+ await page.settle();+ assert.deepEqual(page.drawn.map((d) => Math.round(d.t * 30)), [1, 2, 3, 4, 5], 'a refresh ahead, each frame once, none past its end');+ assert.ok(page.drawn.every((d) => Math.abs(d.t * 30 - Math.round(d.t * 30)) < 1e-6), 'on the frame grid');+ /* a still moment stops it: drawn, and no frame after it */+ page.send({ type: 'seek', t: 0.1, seq: 1 });+ await page.settle();+ page.drawn.at(-1).done();+ await page.settle();+ await page.refresh();+ await page.refresh();+ assert.deepEqual(page.drawn.slice(5).map((d) => d.t), [0.1]);+ assert.deepEqual(page.said.filter((m) => m.type === 'seeked').map((m) => m.t), [0.1]);++ /* a page without a duration has no end of its own: it plays on until the viewer stops it */+ const endless = filmPage({ alone: true, duration: null });+ await endless.settle();+ endless.send({ type: 'play', t: 0, at: endless.clock(), rate: 1, fps: 30 });+ for (let i = 0; i < 20; i++) {+ await endless.refresh();+ endless.drawn.at(-1)?.done();+ }+ await endless.settle();+ assert.equal(Math.round(endless.drawn.at(-1).t * 30), 10, 'a third of a second in, a refresh ahead');+});diff --git a/packages/openfilm/studio/server/closure.mjs b/packages/openfilm/studio/server/closure.mjsindex 912913d..c15c58c 100644--- a/packages/openfilm/studio/server/closure.mjs+++ b/packages/openfilm/studio/server/closure.mjs@@ -73,6 +73,16 @@ export function projectPath(/** @type {string} */ ref, /** @type {string} */ basreturn path.replace(/\/$/, '');}+/**+ * A clip's src (its file's path from film.html, as film-doc reads it: any character a name has) made a project path;+ * null for another site, or outside the folder.+ */+export function clipFile(/** @type {string} */ src) {+ if (/^([a-z][a-z0-9+.-]*:|\/\/)/i.test(src)) return null;+ const path = posix.normalize(src.replace(/^\/+/, ''));+ return !path || path === '.' || path === '..' || path.startsWith('../') ? null : path;+}+/* ── reading files for what they name ────────────────────────────────────── *//** The strings of a script or JSON text (comments skipped): quoted ones, and template strings with `${…}` as `\0`. */@@ -293,7 +303,8 @@ export async function filmClosure(view) {for (const track of value?.tracks ?? []) {for (const clip of /** @type {{ src?: unknown, overrides?: unknown }[]} */ (track.clips ?? [])) {if (typeof clip?.src !== 'string') continue;- await ref(clip.src, [''], FILM_FILE);+ const file = clipFile(clip.src);+ if (file) await take(file, FILM_FILE);/* a picture the person put in a page's place (an override's `url()`), named from the page's folder */const dir = posix.dirname(clip.src) === '.' ? '' : posix.dirname(clip.src);for (const o of Array.isArray(clip.overrides) ? clip.overrides : []) {diff --git a/packages/openfilm/studio/server/closure.test.mjs b/packages/openfilm/studio/server/closure.test.mjsindex 7760985..6d29461 100644--- a/packages/openfilm/studio/server/closure.test.mjs+++ b/packages/openfilm/studio/server/closure.test.mjs@@ -3,6 +3,7 @@ import assert from 'node:assert/strict';import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';import { tmpdir } from 'node:os';import { dirname, join } from 'node:path';+import { filmHtml } from '../../src/film-doc.mjs';import { filmClosure, folderView, projectFiles, projectPath } from './closure.mjs';/** A folder with these files (path → text). */@@ -118,6 +119,19 @@ test('a film\'s closure: its clips, what its pages load, subtitles beside its meassert.ok(!all.has('.film/id') && all.has('render.log'), 'the folder\'s files, without Studio\'s own');});+test('a clip\'s file is the film\'s whatever its name holds: quotes, #, ?, %', async () => {+ /* Windows takes no " ? | in a file name */+ const names = process.platform === 'win32'+ ? ["assets/it's 1.png", 'assets/a#b.mp4', 'assets/100%.mp3', 'assets/{x}^`.png']+ : ["assets/it's \"1\".png", 'assets/a#b?.mp4', 'assets/100%.mp3', 'assets/{x}|^`.png'];+ const root = folder({+ 'film.html': filmHtml({ stage: { w: 640, h: 360 }, tracks: [{ clips: names.map((src, i) => ({ id: `c${i}`, src, at: i, ...(/\.png$/.test(src) ? { time: [0, 1] } : {}) })) }] }),+ ...Object.fromEntries(names.map((n) => [n, 'x'])),+ });+ const closure = await filmClosure(folderView(root));+ for (const n of names) assert.ok(closure.has(n), n);+});+test('a folder without film.html holds no film', async () => {const root = folder({ 'a.html': 'a' });assert.equal((await filmClosure(folderView(root))).size, 0);diff --git a/packages/openfilm/studio/server/cover.mjs b/packages/openfilm/studio/server/cover.mjsnew file mode 100644index 0000000..f18100c--- /dev/null+++ b/packages/openfilm/studio/server/cover.mjs@@ -0,0 +1,102 @@+// @ts-check+/**+ * A project's own cover: the picture its card shows in the projects list in place of the film's poster, chosen by the+ * person (a picture from this computer, a picture of the project, or the film at a moment). It is Studio's, kept in+ * `.film/cover.<ext>` as a copy; without one, the card shows the film's poster (pageframes.mjs filmPoster).+ */+import { statSync } from 'node:fs';+import { readFile, rename, rm, stat, writeFile } from 'node:fs/promises';+import { join } from 'node:path';++/** The kinds of picture a cover may be, by the ending its copy is kept under. */+const TYPES = { jpg: 'image/jpeg', png: 'image/png', webp: 'image/webp', gif: 'image/gif' };++/** How wide the film is drawn for a cover taken of it: as wide as a frame is drawn (pageframes.mjs), sharp on any card. */+export const COVER_FRAME_W = 960;++/** A cover is a picture for a card, never footage. */+export const COVER_MAX_BYTES = 20 << 20;++export class CoverError extends Error {+ /** @param {string} message @param {number} [status] */+ constructor(message, status = 400) {+ super(message);+ this.status = status;+ }+}++/** What kind of picture the bytes are, by their first bytes (a name or a header can say anything). */+export function pictureType(/** @type {Buffer} */ bytes) {+ if (bytes.length > 3 && bytes[0] === 0xff && bytes[1] === 0xd8 && bytes[2] === 0xff) return 'jpg';+ if (bytes.length > 8 && bytes.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return 'png';+ if (bytes.length > 12 && bytes.toString('latin1', 0, 4) === 'RIFF' && bytes.toString('latin1', 8, 12) === 'WEBP') return 'webp';+ if (bytes.length > 6 && /^GIF8[79]a$/.test(bytes.toString('latin1', 0, 6))) return 'gif';+ return null;+}++/* `.film/` (projects.mjs TOOL_DIR, not imported: projects.mjs lists each project's cover with coverAt) */+const coverPath = (/** @type {string} */ root, /** @type {string} */ ext) => join(root, '.film', `cover.${ext}`);++/** When the project's cover was set (ms), for its card to ask for the new picture; null when it has none. */+export function coverAt(/** @type {string} */ root) {+ for (const ext of Object.keys(TYPES)) {+ const info = statSync(coverPath(root, ext), { throwIfNoEntry: false });+ if (info?.isFile()) return Math.round(info.mtimeMs);+ }+ return null;+}++/**+ * The project's cover, if it has one: where it is, its media type and when it was set (ms).+ * @param {string} root+ * @returns {Promise<{ path: string, type: string, at: number } | null>}+ */+export async function readCover(root) {+ for (const [ext, type] of Object.entries(TYPES)) {+ const path = coverPath(root, ext);+ const info = await stat(path).catch(() => null);+ if (info?.isFile()) return { path, type, at: Math.round(info.mtimeMs) };+ }+ return null;+}++/**+ * Make these bytes the project's cover, in place of any it had. Written whole before it takes the old one's place: a+ * card never shows half a picture.+ * @param {string} root @param {Buffer} bytes+ */+export async function setCover(root, bytes) {+ if (bytes.length > COVER_MAX_BYTES) throw new CoverError('That picture is too large for a cover.', 413);+ const ext = pictureType(bytes);+ if (!ext) throw new CoverError('A cover has to be a JPEG, PNG, WebP or GIF picture.', 415);+ const path = coverPath(root, ext);+ await writeFile(`${path}.part`, bytes);+ await rename(`${path}.part`, path);+ for (const other of Object.keys(TYPES)) if (other !== ext) await rm(coverPath(root, other), { force: true });+ return /** @type {NonNullable<Awaited<ReturnType<typeof readCover>>>} */ (await readCover(root));+}++/** A picture of the project made its cover; `abs`, where it is (files.mjs readable). @param {string} root @param {string} abs */+export async function setCoverFromFile(root, abs) {+ const info = await stat(abs).catch(() => null);+ if (!info?.isFile()) throw new CoverError('That picture is not there any more.', 404);+ if (info.size > COVER_MAX_BYTES) throw new CoverError('That picture is too large for a cover.', 413);+ return setCover(root, await readFile(abs));+}++/** No cover of its own: the card shows the film's poster again. @param {string} root */+export async function clearCover(root) {+ for (const ext of Object.keys(TYPES)) await rm(coverPath(root, ext), { force: true });+}++/** The request's body as bytes, at most a cover's size. @param {import('node:http').IncomingMessage} req */+export async function readCoverBody(req) {+ let size = 0;+ const chunks = [];+ for await (const chunk of req) {+ size += chunk.length;+ if (size > COVER_MAX_BYTES) throw new CoverError('That picture is too large for a cover.', 413);+ chunks.push(chunk);+ }+ return Buffer.concat(chunks);+}diff --git a/packages/openfilm/studio/server/cover.test.mjs b/packages/openfilm/studio/server/cover.test.mjsnew file mode 100644index 0000000..958d995--- /dev/null+++ b/packages/openfilm/studio/server/cover.test.mjs@@ -0,0 +1,93 @@+import { test, before, after } from 'node:test';+import assert from 'node:assert/strict';+import { existsSync, mkdirSync, mkdtempSync, readdirSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { startStudio } from './server.mjs';+import { filmHtml } from '../../src/film-doc.mjs';+import { pictureType } from './cover.mjs';++let studio, scratch;+before(async () => {+ scratch = mkdtempSync(join(tmpdir(), 'of-cover-'));+ process.env.OPENFILM_HOME = join(scratch, 'home');+ process.env.OPENFILM_LIBRARY = join(scratch, 'library');+ process.env.OPENFILM_TRASH_DIR = join(scratch, 'trash');+ mkdirSync(process.env.OPENFILM_TRASH_DIR);+ studio = await startStudio({ port: 0, openBrowser: () => {} });+});+after(() => studio.close());++/** a 1×1 PNG */+const PNG = Buffer.from('iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8z8BQDwAEhQGAhKmMIQAAAABJRU5ErkJggg==', 'base64');++const api = (path, { method = 'GET', body, raw } = {}) => fetch(`${studio.origin}${path}`, {+ method,+ headers: { 'x-studio-key': studio.key, ...(body ? { 'content-type': 'application/json' } : {}), ...(raw ? { 'content-type': 'application/octet-stream' } : {}) },+ body: raw ?? (body ? JSON.stringify(body) : undefined),+});+const make = async (name) => (await (await api('/api/projects', { method: 'POST', body: { path: join(scratch, name) } })).json()).project;+const listed = async (id) => (await (await api('/api/projects')).json()).projects.find((p) => p.id === id);+const poster = async (id) => {+ const res = await api(`/api/projects/${id}/poster`);+ return { status: res.status, type: res.headers.get('content-type'), body: Buffer.from(await res.arrayBuffer()) };+};++test('a picture from this computer becomes the card, even of an empty film; taken off, the film\'s poster again', async () => {+ const project = await make('Uploaded');+ writeFileSync(join(project.path, 'film.html'), filmHtml({ tracks: [{ clips: [] }] }));+ assert.equal((await poster(project.id)).status, 404, 'an empty film has no poster');+ assert.equal((await listed(project.id)).cover, undefined);++ const set = await (await api(`/api/projects/${project.id}/cover`, { method: 'PUT', raw: PNG })).json();+ assert.equal(typeof set.cover, 'number');+ const shown = await poster(project.id);+ assert.equal(shown.status, 200);+ assert.equal(shown.type, 'image/png');+ assert.ok(shown.body.equals(PNG), 'the picture as it was given');+ assert.equal((await listed(project.id)).cover, set.cover, 'the list says when, for the card to ask again');+ assert.deepEqual(readdirSync(join(project.path, '.film')).filter((n) => n.startsWith('cover')), ['cover.png'], 'one copy, in .film');++ assert.deepEqual(await (await api(`/api/projects/${project.id}/cover`, { method: 'DELETE' })).json(), { cover: null });+ assert.equal((await poster(project.id)).status, 404, 'the film\'s own poster again');+ assert.equal((await listed(project.id)).cover, undefined);+});++test('only a picture is a cover: anything else is refused and the cover is kept', async () => {+ const project = await make('Refused');+ await api(`/api/projects/${project.id}/cover`, { method: 'PUT', raw: PNG });+ const res = await api(`/api/projects/${project.id}/cover`, { method: 'PUT', raw: Buffer.from('<svg xmlns="http://www.w3.org/2000/svg"/>') });+ assert.equal(res.status, 415);+ assert.ok((await poster(project.id)).body.equals(PNG));+ assert.equal(pictureType(Buffer.from('GIF89a......')), 'gif');+ assert.equal(pictureType(Buffer.from('not a picture')), null);+});++test('a picture of the project becomes the cover; one outside it cannot', async () => {+ const project = await make('FromAssets');+ mkdirSync(join(project.path, 'assets'), { recursive: true });+ writeFileSync(join(project.path, 'assets', 'still.png'), PNG);+ const set = await api(`/api/projects/${project.id}/cover`, { method: 'POST', body: { path: 'assets/still.png' } });+ assert.equal(set.status, 200);+ assert.ok((await poster(project.id)).body.equals(PNG));+ writeFileSync(join(scratch, 'outside.png'), PNG);+ assert.notEqual((await api(`/api/projects/${project.id}/cover`, { method: 'POST', body: { path: '../outside.png' } })).status, 200);+ assert.equal((await api(`/api/projects/${project.id}/cover`, { method: 'POST', body: { path: 'assets/gone.png' } })).status, 404);+});++test('the film at a moment becomes the cover, a JPEG, in place of a picture set before', async () => {+ const project = await make('Moment');+ writeFileSync(join(project.path, 'p.html'), `<!doctype html><body style="margin:0"><div id="b" style="width:1920px;height:1080px"></div><script>+ window.film = { duration: 2, frame(t) { document.getElementById('b').style.background = t < 1 ? '#f00' : '#00f'; } };+ </script></body>`);+ writeFileSync(join(project.path, 'film.html'), filmHtml({ tracks: [{ clips: [{ src: 'p.html' }] }] }));+ await api(`/api/projects/${project.id}/cover`, { method: 'PUT', raw: PNG });+ const set = await api(`/api/projects/${project.id}/cover`, { method: 'POST', body: { ms: 1500 } });+ assert.equal(set.status, 200);+ const shown = await poster(project.id);+ assert.equal(shown.type, 'image/jpeg');+ assert.equal(pictureType(shown.body), 'jpg');+ assert.ok(existsSync(join(project.path, '.film', 'cover.jpg')));+ assert.ok(!existsSync(join(project.path, '.film', 'cover.png')), 'the picture before is gone');+ assert.equal((await api(`/api/projects/${project.id}/cover`, { method: 'POST', body: { ms: -1 } })).status, 400);+});diff --git a/packages/openfilm/studio/server/diagnostics.mjs b/packages/openfilm/studio/server/diagnostics.mjsnew file mode 100644index 0000000..28c93dc--- /dev/null+++ b/packages/openfilm/studio/server/diagnostics.mjs@@ -0,0 +1,151 @@+// @ts-check+/**+ * Settings → Developer's diagnostic file: one zip with everything that says why something went wrong lately, for a+ * person to look at and then attach to an issue. The copied report is short; this is the rest of it:+ *+ * report.txt the report the page copies (`openfilm doctor`, the browser, the desktop app's agents)+ * problems.jsonl the problems of the last KEEP_DAYS days (src/problems.mjs)+ * logs/… the last of each log Studio and the desktop app write (OPENFILM_APP_LOGS)+ * turns/… the logs of the turns the last agent problems were in. Unless `conversations`, only how they+ * went (turnLogForFile): never a word the person or the agent wrote, a tool's title, command,+ * input or output, or anything from the person's files+ * agents/codex.txt Codex's own warnings and errors around each of its problems, from its log database+ *+ * Everything in it is redacted as problems are (the home folder as ~, no keys, tokens or email addresses).+ */+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';+import { mkdir } from 'node:fs/promises';+import { homedir } from 'node:os';+import { basename, isAbsolute, join } from 'node:path';+import { exportsDefault, studioHomeDir } from '../../src/locations.mjs';+import { KEEP_DAYS, problemsFile, recentProblems, redact } from '../../src/problems.mjs';+import { zipFiles } from './zip.mjs';++/** The most of a log that goes in: its end. */+const LOG_TAIL = 1 << 20;+/** How many of the last agent problems bring their turn's log, and how much of each. */+const TURNS_MAX = 5;+const TURN_MAX = 2 << 20;+/** Codex's log around a problem: from this long before it to this long after. */+const CODEX_BEFORE_S = 120;+const CODEX_AFTER_S = 15;++/** A path a problem wrote with the home folder as ~, back to where it is. @param {string} path */+const expand = (path) => (path.startsWith('~') ? join(homedir(), path.slice(1)) : path);++/** The end of a file, from a whole line. @param {string} file @param {number} max */+function tail(file, max) {+ const text = readFileSync(file, 'utf8');+ return text.length > max ? text.slice(text.length - max).replace(/^[^\n]*\n/, '') : text;+}++/* what a turn's log says of how it went, never what was said: kept whole */+const TURN_KINDS = new Set(['start', 'done', 'exit', 'cancel', 'set-option', 'steer-answer', 'permission-answer']);+/* the agent's own updates that say how it goes, not what it says or does */+const STATE_UPDATES = new Set(['notice', 'session_info_update', 'usage_update', 'current_mode_update', 'config_option_update', 'available_commands_update']);+/* asked of the person: that it was, and when, never what */+const ASKED = new Set(['permission', 'question', 'question-answer']);++/**+ * A turn's log as it goes in the file: whole with `conversations`; else only how it went: its start and how it ended,+ * the agent's notices and state, the prompt's agent, model and program without its words, each tool's step as its+ * kind, name, status and exit code (no title, command, input or output), and when it asked the person something.+ * @param {string} text @param {boolean} conversations+ */+export function turnLogForFile(text, conversations) {+ if (conversations) return text;+ return text.split('\n').flatMap((line) => {+ let e;+ try { e = line ? JSON.parse(line) : null; } catch { return []; }+ if (!e || typeof e !== 'object') return [];+ if (TURN_KINDS.has(e.kind)) return [line];+ if (e.kind === 'update' && STATE_UPDATES.has(e.update?.sessionUpdate)) return [line];+ if (e.kind === 'update' && (e.update?.sessionUpdate === 'tool_call' || e.update?.sessionUpdate === 'tool_call_update')) {+ const { sessionUpdate, toolCallId, name, kind, status } = e.update;+ const exitCode = e.update.rawOutput?.exit_code ?? e.update.rawOutput?.exitCode;+ return [JSON.stringify({ t: e.t, kind: 'update', update: { sessionUpdate, toolCallId, name, kind, status, ...(Number.isInteger(exitCode) ? { exitCode } : {}) } })];+ }+ if (ASKED.has(e.kind)) return [JSON.stringify({ t: e.t, kind: e.kind, words: '(left out)' })];+ if (e.kind === 'prompt') {+ const { t, kind, agent, meta, session, opened } = e;+ return [JSON.stringify({ t, kind, agent, model: meta?.model ?? null, agentInfo: session?.agentInfo ?? null,+ program: opened?.program ?? null, adapter: opened?.adapter ?? null, words: '(left out)' })];+ }+ return [];+ }).join('\n');+}++/**+ * Codex's own warnings and errors around these times (each problem's), from its log database (logs_*.sqlite in its+ * home), as text; null when there is none to read (no Codex, a Node without node:sqlite, a database it cannot open).+ * @param {string} dir Codex's home @param {number[]} times milliseconds+ */+export async function codexLogAround(dir, times) {+ if (!times.length || !existsSync(dir)) return null;+ const file = readdirSync(dir).filter((n) => /^logs_\d+\.sqlite$/.test(n)).sort().pop();+ if (!file) return null;+ let sqlite;+ try { sqlite = await import('node:sqlite'); } catch { return null; }+ let db;+ try {+ db = new sqlite.DatabaseSync(join(dir, file), { readOnly: true });+ const query = db.prepare("SELECT ts, level, target, feedback_log_body AS body FROM logs WHERE ts BETWEEN ? AND ? AND level IN ('ERROR', 'WARN') ORDER BY ts, ts_nanos LIMIT 400");+ const parts = times.map((ms) => {+ const at = Math.floor(ms / 1000);+ const rows = /** @type {{ ts: number, level: string, target: string, body: string | null }[]} */ (query.all(at - CODEX_BEFORE_S, at + CODEX_AFTER_S));+ return [`Around ${new Date(ms).toISOString()}:`, ...(rows.length ? rows.map((r) => ` ${new Date(r.ts * 1000).toISOString()} ${r.level} ${r.target} ${String(r.body ?? '').replace(/\s+/g, ' ').slice(0, 1000)}`) : [' (nothing)'])].join('\n');+ });+ return redact(parts.join('\n\n'));+ } catch {+ return null;+ } finally {+ try { db?.close(); } catch { /* closed */ }+ }+}++/** A name for the file, by the time: `OpenFilm diagnostics 2026-10-18 1013.zip`. @param {Date} now */+export function diagnosticsName(now) {+ const pad = (/** @type {number} */ n) => String(n).padStart(2, '0');+ return `OpenFilm diagnostics ${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())} ${pad(now.getHours())}${pad(now.getMinutes())}.zip`;+}++/**+ * Write the diagnostic file; → where it is.+ * @param {{ report: string, conversations?: boolean, folder?: string, home?: string, appLogs?: string | null, now?: Date }} options+ */+export async function exportDiagnostics({ report, conversations = false, folder = exportsDefault(), home = studioHomeDir(), appLogs = process.env.OPENFILM_APP_LOGS ?? null, now = new Date() }) {+ /** @type {{ name: string, data: Buffer }[]} */+ const entries = [];+ const add = (/** @type {string} */ name, /** @type {string} */ text) => entries.push({ name, data: Buffer.from(text) });++ add('report.txt', redact(report));+ const problems = recentProblems({ file: problemsFile(home), days: KEEP_DAYS, now });+ add('problems.jsonl', problems.map((p) => JSON.stringify(p)).join('\n') + (problems.length ? '\n' : ''));++ /* the logs: Studio's (its home's logs/) and the desktop app's (its own logs/), the end of each */+ for (const [under, dir] of /** @type {const} */ ([['studio', join(home, 'logs')], ['app', appLogs]])) {+ if (!dir || !isAbsolute(dir) || !existsSync(dir)) continue;+ for (const name of readdirSync(dir).filter((n) => n.endsWith('.log')).sort()) {+ try { if (statSync(join(dir, name)).isFile()) add(`logs/${under}/${name}`, redact(tail(join(dir, name), LOG_TAIL))); } catch { /* unreadable */ }+ }+ }++ /* the turns of the last agent problems, each once */+ const turns = [...new Set(problems.filter((p) => p.area === 'agent' && typeof p.log === 'string').map((p) => expand(/** @type {string} */ (p.log))))].slice(-TURNS_MAX);+ for (const file of turns) {+ try { if (existsSync(file)) add(`turns/${basename(file)}`, redact(turnLogForFile(tail(file, TURN_MAX), conversations))); } catch { /* unreadable */ }+ }++ /* Codex's own log around each of its problems */+ const codex = problems.filter((p) => p.area === 'agent' && /^codex$/i.test(String(p.agentId ?? p.agent ?? '')));+ if (codex.length) {+ const dir = expand(String(codex.at(-1)?.ownLogs ?? join('~', '.codex')));+ const text = await codexLogAround(dir, codex.slice(-TURNS_MAX).map((p) => Date.parse(p.t)).filter(Number.isFinite));+ if (text) add('agents/codex.txt', text);+ }++ await mkdir(folder, { recursive: true });+ const out = join(folder, diagnosticsName(now));+ await zipFiles(out, entries);+ return { path: out, files: entries.map((e) => e.name), conversations };+}diff --git a/packages/openfilm/studio/server/diagnostics.test.mjs b/packages/openfilm/studio/server/diagnostics.test.mjsnew file mode 100644index 0000000..f78dce1--- /dev/null+++ b/packages/openfilm/studio/server/diagnostics.test.mjs@@ -0,0 +1,78 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { mkdirSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { recordProblem, problemsFile } from '../../src/problems.mjs';+import { diagnosticsName, exportDiagnostics, turnLogForFile } from './diagnostics.mjs';++const TURN = [+ { t: 1, kind: 'prompt', agent: 'codex', text: 'make my secret film', meta: { model: '6.1 Sol' }, session: { agentInfo: { name: 'codex-acp', version: '1.13.1' } }, opened: { program: '/x/codex', adapter: '@agentclientprotocol/codex-acp' } },+ { t: 2, kind: 'sent', prompt: [{ type: 'text', text: 'make my secret film' }] },+ { t: 3, kind: 'update', update: { sessionUpdate: 'agent_message_chunk', content: { type: 'text', text: 'a reply about the secret' } } },+ { t: 4, kind: 'update', update: { sessionUpdate: 'notice', severity: 'warning', title: 'Reconnecting... 2/5' } },+ { t: 4.1, kind: 'update', update: { sessionUpdate: 'tool_call', toolCallId: 'c1', title: "List files in 'secret'", name: 'exec_command', kind: 'read', status: 'in_progress', rawInput: { command: 'ls secret' } } },+ { t: 4.2, kind: 'update', update: { sessionUpdate: 'tool_call_update', toolCallId: 'c1', status: 'failed', name: 'exec_command', rawOutput: { formatted_output: 'secret.txt', exit_code: 2 } } },+ { t: 4.3, kind: 'permission', params: { toolCall: { title: 'Delete secret' } } },+ { t: 4.4, kind: 'question', message: 'Which secret?' },+ { t: 5, kind: 'done', ok: false, error: 'Codex stopped while answering without saying why.' },+].map((e) => JSON.stringify(e)).join('\n');++test("a turn's log goes in as how it went, without what was said unless asked", () => {+ const kept = turnLogForFile(TURN, false);+ assert.doesNotMatch(kept, /secret/);+ assert.match(kept, /Reconnecting\.\.\. 2\/5/);+ assert.match(kept, /without saying why/);+ const prompt = JSON.parse(kept.split('\n')[0]);+ assert.deepEqual([prompt.kind, prompt.model, prompt.program, prompt.words], ['prompt', '6.1 Sol', '/x/codex', '(left out)']);+ const steps = kept.split('\n').map((l) => JSON.parse(l)).filter((e) => e.update?.toolCallId);+ assert.deepEqual(steps.map((e) => e.update), [+ { sessionUpdate: 'tool_call', toolCallId: 'c1', name: 'exec_command', kind: 'read', status: 'in_progress' },+ { sessionUpdate: 'tool_call_update', toolCallId: 'c1', name: 'exec_command', status: 'failed', exitCode: 2 },+ ]);+ assert.match(kept, /"kind":"permission","words":"\(left out\)"/);+ assert.equal(turnLogForFile(TURN, true), TURN);+});++test('the diagnostic file: the report, the problems, the logs, the failed turns, and Codex\'s own log around its problem', async () => {+ const root = mkdtempSync(join(tmpdir(), 'openfilm-diagnostics-'));+ const home = join(root, 'home');+ const appLogs = join(root, 'app-logs');+ const project = join(root, 'Film');+ const codexHome = join(root, 'codex');+ for (const dir of [join(home, 'logs'), appLogs, join(project, '.film', 'logs'), codexHome]) mkdirSync(dir, { recursive: true });+ writeFileSync(join(home, 'logs', 'studio.log'), 'listening\nexport failed: no codec\n');+ writeFileSync(join(appLogs, 'updates.log'), '{"status":"current"}\n');+ const log = join(project, '.film', 'logs', 'local-abc.jsonl');+ writeFileSync(log, TURN);+ const at = new Date('2026-10-18T13:13:15Z');+ recordProblem({ area: 'agent', agent: 'Codex', agentId: 'codex', step: 'session/prompt', what: 'Codex stopped while answering without saying why.', project, log, ownLogs: codexHome }, { file: problemsFile(home), now: at });++ /* Codex's log database, as Codex keeps it */+ let sqlite = null;+ try { sqlite = await import('node:sqlite'); } catch { /* a Node without it: that part is left out */ }+ if (sqlite) {+ const db = new sqlite.DatabaseSync(join(codexHome, 'logs_2.sqlite'));+ db.exec('CREATE TABLE logs (id INTEGER PRIMARY KEY, ts INTEGER, ts_nanos INTEGER, level TEXT, target TEXT, feedback_log_body TEXT)');+ const add = db.prepare('INSERT INTO logs (ts, ts_nanos, level, target, feedback_log_body) VALUES (?, 0, ?, ?, ?)');+ const s = Math.floor(at.getTime() / 1000);+ add.run(s - 10, 'ERROR', 'codex_models_manager', 'failed to refresh available models: request timed out');+ add.run(s - 5, 'INFO', 'codex_http_client', 'using system root certificates');+ add.run(s - 3600, 'ERROR', 'codex_core', 'an hour before');+ db.close();+ }++ const made = await exportDiagnostics({ report: 'OpenFilm doctor\n✓ Node', folder: join(root, 'out'), home, appLogs, now: new Date('2026-10-18T14:00:00Z') });+ assert.equal(made.path, join(root, 'out', diagnosticsName(new Date('2026-10-18T14:00:00Z'))));+ assert.deepEqual(made.files.filter((f) => f !== 'agents/codex.txt'), ['report.txt', 'problems.jsonl', 'logs/studio/studio.log', 'logs/app/updates.log', 'turns/local-abc.jsonl']);+ const zip = readFileSync(made.path).toString('utf8');+ assert.match(zip, /OpenFilm doctor/);+ assert.match(zip, /export failed: no codec/);+ assert.match(zip, /Reconnecting\.\.\. 2\/5/);+ assert.doesNotMatch(zip, /secret/, 'no words of the turn');+ if (sqlite) {+ assert.ok(made.files.includes('agents/codex.txt'));+ assert.match(zip, /request timed out/);+ assert.doesNotMatch(zip, /system root certificates|an hour before/, 'only warnings and errors, around the problem');+ }+});diff --git a/packages/openfilm/studio/server/exports.mjs b/packages/openfilm/studio/server/exports.mjsindex 60cd520..e6cf4e9 100644--- a/packages/openfilm/studio/server/exports.mjs+++ b/packages/openfilm/studio/server/exports.mjs@@ -53,11 +53,13 @@ import { execFile, fork, spawn } from 'node:child_process';import { randomBytes } from 'node:crypto';import { constants as fsConstants, existsSync, readFileSync, statSync } from 'node:fs';import { copyFile, mkdir, mkdtemp, readdir, readFile, rename, rm, rmdir, stat, writeFile } from 'node:fs/promises';-import { homedir, tmpdir } from 'node:os';-import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path';+import { homedir, setPriority, tmpdir } from 'node:os';+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } from 'node:path';import { fileURLToPath } from 'node:url';import { FilmPage, launch } from '../../src/host.mjs';+import { broken, encoders, hardwareEncoder, hardwareOptions, onTheChip, proresOptions } from '../../src/encoders.mjs';import { filmSound, kill as killProcess, mix, open } from '../../src/shared.mjs';+import { filmVideos } from '../../src/seekable.mjs';import { FILM_FILE, clipFade, filmHtml, fittedFade, kindOf, pictureRect, readFilmFile } from '../../src/film-doc.mjs';import { layerBlocks, rowBadges, trackKind } from './track-layout.mjs';import { fcpxmlDocument } from './fcpxml.mjs';@@ -70,6 +72,7 @@ import { zipFiles } from './zip.mjs';import { inProject } from './files.mjs';import { PROJECT_PARTS, TOOL_DIR } from './projects.mjs';import { exportsRoot } from '../../src/locations.mjs';+import { recordProblem } from '../../src/problems.mjs';/** The exports folder: the one chosen in Settings, else the Desktop, where a file just made is found (src/locations.mjs). */export { exportsRoot };@@ -112,22 +115,6 @@ export class ExportError extends Error {/* ── what this machine can encode ───────────────────────────────────────── */-/** @type {Promise<Set<string>> | null} */-let encoderList = null;-/**- * The encoders this machine's ffmpeg has (none when there is no ffmpeg). No ffmpeg is asked about again next time:- * the desktop app downloads it while Studio is already running.- */-function encoders() {- encoderList ??= new Promise((done) => {- execFile('ffmpeg', ['-hide_banner', '-encoders'], { maxBuffer: 8 << 20, windowsHide: true }, (error, stdout) => {- if (error) encoderList = null;- done(new Set(error ? [] : [...String(stdout).matchAll(/^ [VAS][.A-Z]{5} (\S+)/gm)].map((m) => m[1])));- });- });- return encoderList;-}-/** What the export dialog may offer: the encoders behind each choice that depends on this machine's ffmpeg. */export async function exportCapabilities() {const have = await encoders();@@ -136,7 +123,7 @@ export async function exportCapabilities() {hevc: have.has('libx265') || have.has('hevc_videotoolbox'),hevcAlpha: have.has('hevc_videotoolbox'),vp9: have.has('libvpx-vp9'),- prores: have.has('prores_ks'),+ prores: have.has('prores_ks') || have.has('prores_videotoolbox'),mp3: have.has('libmp3lame'),};}@@ -385,6 +372,14 @@ export async function projectSizes(root) {/* ── doing it ───────────────────────────────────────────────────────────── */+/**+ * Below the person's own apps: an export's processes (its renderer, and through it its browsers and encoders, which+ * start below too; its ffmpeg runs) give way to what the person is doing, and take the computer whole when it is+ * idle. Studio started by `openfilm open` runs below already (main.mjs); the desktop app's does not.+ * @param {import('node:child_process').ChildProcess} proc+ */+const below = (proc) => { try { if (proc.pid) setPriority(proc.pid, 10); } catch { /* not allowed here: as it is */ } };+/*** ffmpeg, stopped when `signal` aborts. `input`: what it reads from its standard input.* @param {string[]} args @param {AbortSignal} signal @param {Buffer} [input]@@ -393,6 +388,7 @@ function run(args, signal, input) {if (signal.aborted) return Promise.reject(new Error('cancelled'));return new Promise((done, fail) => {const proc = spawn('ffmpeg', ['-hide_banner', '-nostdin', '-loglevel', 'error', '-y', ...args], { stdio: [input ? 'pipe' : 'ignore', 'ignore', 'pipe'], windowsHide: true });+ below(proc);let err = '';proc.stderr?.on('data', (d) => { err += d; });const kill = () => killProcess(proc);@@ -546,93 +542,43 @@ const BT709 = ['-colorspace', 'bt709', '-color_primaries', 'bt709', '-color_trc'const TO_709 = 'scale=out_color_matrix=bt709:out_range=tv';/**- * The graphics chip's encoders for H.264 and HEVC that this platform's ffmpeg may have, in the order they are tried:- * the Mac's own; on Windows NVIDIA's, Intel's, AMD's, then Windows' own (Media Foundation, through whichever chip- * there is); NVIDIA's on Linux.- */-const HARDWARE = /** @type {Record<string, Record<'h264' | 'hevc', string[]>>} */ ({- darwin: { h264: ['h264_videotoolbox'], hevc: ['hevc_videotoolbox'] },- win32: { h264: ['h264_nvenc', 'h264_qsv', 'h264_amf', 'h264_mf'], hevc: ['hevc_nvenc', 'hevc_qsv', 'hevc_amf', 'hevc_mf'] },- linux: { h264: ['h264_nvenc'], hevc: ['hevc_nvenc'] },-});--/**- * A hardware encoder's options at a bitrate (they take no quality number that means the same on every chip): peaks- * allowed at half again, for cuts and screen text.- * @param {string} encoder @param {number} bits a second- */-export function hardwareOptions(encoder, bits) {- const k = (/** @type {number} */ n) => `${Math.round(n / 1000)}k`;- const rate = ['-b:v', k(bits), '-maxrate', k(bits * 1.5), '-bufsize', k(bits * 2)];- const hevc = encoder.startsWith('hevc_');- const tag = hevc ? ['-tag:v', 'hvc1'] : [];- switch (encoder.slice(encoder.indexOf('_') + 1)) {- case 'videotoolbox': return ['-c:v', encoder, ...(hevc ? [] : ['-profile:v', 'high']), '-b:v', k(bits), ...tag];- case 'nvenc': return ['-c:v', encoder, '-preset', 'p5', '-rc', 'vbr', ...rate, ...tag];- case 'qsv': return ['-c:v', encoder, '-preset', 'medium', ...rate, ...tag];- case 'amf': return ['-c:v', encoder, '-quality', 'quality', '-rc', 'vbr_peak', ...rate, ...tag];- /* the chip's own encoder, never Windows' software one (x264 is better at that) */- case 'mf': return ['-c:v', encoder, '-hw_encoding', '1', '-rate_control', 'u_vbr', '-b:v', k(bits), ...tag];- default: return ['-c:v', encoder, '-b:v', k(bits), ...tag];- }-}--/** @type {Map<string, Promise<boolean>>} */-const tried = new Map();-/**- * Whether a hardware encoder works on this machine: one built into ffmpeg may have no chip or driver behind it, so a- * moment of video goes through it first (once a launch; `broken` remembers one that failed an export after that).- * @param {string} encoder+ * The graphics chip's encoder to try for a codec, or null: H.264 and HEVC below master, as editors do (several times+ * faster, and the processor stays free for drawing the frames and for the person; master stays x264 and x265 at+ * their slowest and best), and ProRes at any quality (the Mac's ProRes engine is Apple's own encoder).+ * @param {VideoCodec} codec @param {Quality} quality*/-function works(encoder) {- if (!tried.has(encoder)) {- tried.set(encoder, new Promise((done) => {- execFile('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-f', 'lavfi', '-i', 'testsrc2=size=640x360:rate=30', '-frames:v', '10',- '-vf', 'format=yuv420p', ...hardwareOptions(encoder, 2e6), '-f', 'null', '-'], { timeout: 20_000, windowsHide: true }, (error) => done(!error));- }));- }- return /** @type {Promise<boolean>} */ (tried.get(encoder));-}-/** A hardware encoder that failed an export: the rest of this launch uses another. @param {string} encoder */-const broken = (encoder) => { tried.set(encoder, Promise.resolve(false)); };+const chipCodec = (codec, quality) => ((codec === 'h264' || codec === 'hevc') && quality !== 'master' ? codec+ : codec === 'prores422hq' || codec === 'prores4444' ? 'prores' : null);/**- * The first hardware encoder for H.264 or HEVC that works here, or null.- * @param {'h264' | 'hevc'} codec @param {Set<string>} have @param {string} [platform]- */-export async function hardwareEncoder(codec, have, platform = process.platform) {- for (const encoder of HARDWARE[platform]?.[codec] ?? []) if (have.has(encoder) && await works(encoder)) return encoder;- return null;-}--/**- * How render should encode a codec: its encoder (for the person's list), and the container format render takes. H.264- * and HEVC below master go through the graphics chip's encoder when it has one that works (`hw`, hardwareEncoder),- * as editors do: several times faster, and the processor stays free for drawing the frames and for the person; master- * stays x264 and x265 at their slowest and best.+ * How render should encode a codec: its encoder (for the person's list), and the container format render takes,+ * through the graphics chip's encoder when it has one that works (`hw`: hardwareEncoder for chipCodec).* @param {VideoCodec} codec @param {Quality} quality @param {{ w: number, h: number }} size @param {number} fps @param {Set<string>} have @param {string | null} [hw]*/function encoding(codec, quality, size, fps, have, hw = null) {const bits = (/** @type {number} */ k) => Math.min(120e6, Math.max(2e6, size.w * size.h * fps * BPP[quality] * k));const bitrate = (/** @type {number} */ k) => `${Math.round(bits(k) / 1000)}k`;+ /* a key frame every two seconds */+ const gop = Math.round(fps * 2);switch (codec) {case 'h264':/* with room for screen text: half again the dialog's scale */- if (hw && quality !== 'master') return { encoder: hw, format: { video: [...hardwareOptions(hw, bits(1.5)), ...BT709] } };+ if (hw) return { encoder: hw, format: { video: [...hardwareOptions(hw, bits(1.5), { gop }), ...BT709] } };return { encoder: 'libx264', format: { video: ['-c:v', 'libx264', '-preset', quality === 'master' ? 'slow' : 'medium', '-crf', String(H264_CRF[quality]), ...BT709] } };case 'hevc':- if (hw && quality !== 'master') return { encoder: hw, format: { video: [...hardwareOptions(hw, bits(0.8)), ...BT709], tag: ['-tag:v', 'hvc1'] } };+ if (hw) return { encoder: hw, format: { video: [...hardwareOptions(hw, bits(0.8), { gop }), ...BT709], tag: ['-tag:v', 'hvc1'] } };if (have.has('libx265')) {return { encoder: 'libx265', format: { video: ['-c:v', 'libx265', '-preset', 'medium', '-crf', String(X265_CRF[quality]), '-x265-params', 'log-level=error', '-tag:v', 'hvc1', ...BT709], tag: ['-tag:v', 'hvc1'] } };}- if (have.has('hevc_videotoolbox')) return { encoder: 'hevc_videotoolbox', format: { video: ['-c:v', 'hevc_videotoolbox', '-b:v', bitrate(0.8), '-tag:v', 'hvc1', ...BT709], tag: ['-tag:v', 'hvc1'] } };+ if (have.has('hevc_videotoolbox')) return { encoder: 'hevc_videotoolbox', format: { video: ['-c:v', 'hevc_videotoolbox', '-b:v', bitrate(0.8), '-g', String(gop), '-tag:v', 'hvc1', ...BT709], tag: ['-tag:v', 'hvc1'] } };throw new ExportError('this computer\'s ffmpeg has no HEVC encoder (libx265 or hevc_videotoolbox)');case 'vp9':return { encoder: 'libvpx-vp9', format: { video: ['-c:v', 'libvpx-vp9', '-b:v', '0', '-crf', String(VP9_CRF[quality]), '-row-mt', '1'] } };case 'prores422hq':- return { encoder: 'prores_ks', format: { video: ['-c:v', 'prores_ks', '-profile:v', '3', '-vendor', 'apl0'], pix: 'format=yuv422p10le' } };- case 'prores4444':- return { encoder: 'prores_ks', format: {} };+ case 'prores4444': {+ const encoder = hw ?? 'prores_ks';+ return { encoder, format: proresOptions(encoder, codec === 'prores4444') };+ }case 'hevc_alpha':if (!have.has('hevc_videotoolbox')) throw new ExportError('HEVC with alpha needs macOS\'s hevc_videotoolbox encoder');return { encoder: 'hevc_videotoolbox', format: { video: ['-c:v', 'hevc_videotoolbox', '-alpha_quality', '0.75', '-b:v', bitrate(0.8), '-tag:v', 'hvc1'], pix: 'format=bgra', tag: ['-tag:v', 'hvc1'] } };@@ -699,13 +645,17 @@ async function transcode(make, out, signal) {return;}const alpha = make.to === 'prores4444';- const tail = ['-map', '0:v:0', '-map', '0:a?', '-c:v', 'prores_ks', '-profile:v', alpha ? '4444' : '3', '-vendor', 'apl0',- '-pix_fmt', alpha ? 'yuva444p10le' : 'yuv422p10le', '-c:a', 'pcm_s16le', '-ar', '48000', out];- /* VP9's alpha is a side channel ffmpeg's own decoder drops: libvpx reads it */- if (alpha) {- try { await run(['-c:v', 'libvpx-vp9', '-i', make.from, ...tail], signal); return; } catch (e) { if (signal.aborted) throw e; }- }- await run(['-i', make.from, ...tail], signal);+ /* decoded on the graphics chip and written by the Mac's ProRes engine when it can, else by ffmpeg's own encoder */+ const chip = await hardwareEncoder('prores', await encoders());+ await onTheChip(chip, async (encoder, decoding) => {+ const { video, pix } = proresOptions(encoder ?? 'prores_ks', alpha);+ const tail = ['-map', '0:v:0', '-map', '0:a?', '-vf', pix, ...video, '-c:a', 'pcm_s16le', '-ar', '48000', out];+ /* VP9's alpha is a side channel ffmpeg's own decoder drops: libvpx reads it */+ if (alpha) {+ try { await run(['-c:v', 'libvpx-vp9', '-i', make.from, ...tail], signal); return; } catch (e) { if (signal.aborted) throw e; }+ }+ await run([...decoding, '-i', make.from, ...tail], signal);+ }, signal);}const IMAGE_TYPES = /** @type {Record<string, string>} */ ({ svg: 'image/svg+xml', webp: 'image/webp', avif: 'image/avif', gif: 'image/gif', png: 'image/png', jpg: 'image/jpeg', jpeg: 'image/jpeg', bmp: 'image/bmp' });@@ -741,7 +691,7 @@ async function rasterize(browser, file, w, h, out) {export function createExports({ onChange = () => {}, captions = subtitlesForExport, drafts = defaultDrafts } = {}) {/** @type {ExportJob[]} */const jobs = [];- /** @type {Map<string, { root: string, folder: string, abort: AbortController }>} */+ /** @type {Map<string, { root: string, folder: string, abort: AbortController, twin?: string }>} */const work = new Map();let running = false;@@ -821,7 +771,8 @@ export function createExports({ onChange = () => {}, captions = subtitlesForExpoconst fps = ask.fps;const quality = ask.quality ?? 'high';const have = await encoders();- const hw = ask.hardware !== false && quality !== 'master' && (codec === 'h264' || codec === 'hevc') ? await hardwareEncoder(codec, have) : null;+ const chipFor = chipCodec(codec, quality);+ const hw = ask.hardware !== false && chipFor ? await hardwareEncoder(chipFor, have) : null;/** @param {string | null} chip */const how = (chip) => {const { encoder, format } = encoding(codec, quality, size, fps ?? 30, have, chip);@@ -951,7 +902,9 @@ export function createExports({ onChange = () => {}, captions = subtitlesForExpo*/async function stillFrames(job, root, ask, ext, scratch, signal) {const burn = await burned(root, ask);- const probe = await open(burn ? burn.dir : root, burn ? { root } : {}).catch(async (e) => { await burn?.remove(); throw e; });+ /* footage the browser does not decode (ProRes; HEVC without a chip for it) drawn through a copy it plays: the film's+ video clips, the project's when the film is drawn inside a frame with its subtitles */+ const probe = await open(burn ? burn.dir : root, burn ? { root, playable: filmVideos(root, FILM_FILE) } : { playable: true }).catch(async (e) => { await burn?.remove(); throw e; });try {const meta = probe.film.meta;/* with subtitles, the frame is the page drawn */@@ -1079,7 +1032,7 @@ export function createExports({ onChange = () => {}, captions = subtitlesForExpoconst fps = nleFps(ask.fps ?? 30);const mode = ask.audio ?? 'clips';const title = safeName(job.name);- update(job, { encoder: 'prores_ks' });+ update(job, { encoder: (await hardwareEncoder('prores', await encoders())) ?? 'prores_ks' });/* the edit with every track shown: a hidden track comes over disabled, one click from back on, so it is drawn too */const doc = existsSync(join(root, FILM_FILE)) ? filmDoc(root): { stage: await stageOf(root), tracks: [{ clips: [{ src: 'index.html', id: title }] }] };@@ -1192,6 +1145,8 @@ export function createExports({ onChange = () => {}, captions = subtitlesForExpoconst totalFrames = renders.reduce((n, f) => n + (f.job.kind === 'render' ? f.job.frames : 0), 0);const tick = frames(job, 0.88);let framesBefore = 0;+ /* the chip's ProRes until one of the pages has to do without it: the rest do without it too */+ let hardware = true;for (const file of renders) {if (file.job.kind !== 'render') continue;const { clip: id, frames } = file.job;@@ -1202,10 +1157,12 @@ export function createExports({ onChange = () => {}, captions = subtitlesForExpoconst one = await clipFilm(root, id, { change: { time }, doc });const offset = framesBefore;try {- await render([one.dir], {- root, alpha: true, silent: true, fps: timeline.rate.fps, out: staged(file), signal,+ const drawn = await render([one.dir], {+ root, alpha: true, silent: true, fps: timeline.rate.fps, out: staged(file), signal, hardware,onProgress: (/** @type {number} */ done) => tick(offset + done, totalFrames),});+ if (drawn.encoder !== job.encoder) update(job, { encoder: drawn.encoder });+ if (drawn.encoder === 'prores_ks') hardware = false;} finally {await one.remove();}@@ -1310,18 +1267,42 @@ export function createExports({ onChange = () => {}, captions = subtitlesForExpo}}+ /**+ * An export the same as `made` but for its name: `made`'s files, cloned under this one's name beside them (on APFS at+ * once, taking no more room), a sidecar with its file.+ * @param {ExportJob} job @param {ExportJob} made @param {string} dir+ */+ async function cloneOf(job, made, dir) {+ const main = made.outputs[0];+ const ext = extname(main);+ const out = freeFile(dir, baseName(job.name, job.ask), ext);+ const stem = main.slice(0, main.length - ext.length);+ /** @type {string[]} */+ const outputs = [];+ for (const file of made.outputs) {+ const to = file === main ? out : `${out.slice(0, out.length - ext.length)}${file.slice(stem.length)}`;+ outputs.push(to);+ update(job, { out, outputs: [...outputs] });+ await copyFile(file, to, fsConstants.COPYFILE_FICLONE);+ }+ update(job, { encoder: made.encoder, alpha: made.alpha });+ }+async function next() {if (running) return;/* the oldest waiting: the list is newest first, and exports run in the order asked */const job = jobs.findLast((j) => j.status === 'waiting');if (!job) return;running = true;- const { root, folder, abort } = /** @type {{ root: string, folder: string, abort: AbortController }} */ (work.get(job.id));+ const { root, folder, abort, twin } = /** @type {{ root: string, folder: string, abort: AbortController, twin?: string }} */ (work.get(job.id));try {await mkdir(folder, { recursive: true });update(job, { status: 'running', phase: 'preparing', startedAt: Date.now() });const kind = job.ask.kind;- if (kind === 'video') await exportVideo(job, root, folder, abort.signal);+ /* the same export as one made just before it (asked together), but for its name: that one's files, cloned */+ const made = twin ? jobs.find((j) => j.id === twin && j.status === 'done' && j.outputs.length) : undefined;+ if (made) await cloneOf(job, made, folder);+ else if (kind === 'video') await exportVideo(job, root, folder, abort.signal);else if (kind === 'gif') await exportGif(job, root, folder, abort.signal);else if (kind === 'audio') await exportSound(job, root, folder, abort.signal);else if (kind === 'subtitles') await exportSubtitles(job, root, folder);@@ -1336,7 +1317,9 @@ export function createExports({ onChange = () => {}, captions = subtitlesForExpo/* what a cancelled or failed export left half written is not an export */for (const f of job.outputs) await rm(f, { force: true }).catch(() => {});const ended = { phase: null, etaMs: null, outputs: [], out: undefined, finishedAt: Date.now() };- update(job, abort.signal.aborted ? { ...ended, status: 'cancelled' } : { ...ended, status: 'failed', error: e instanceof Error ? e.message : String(e) });+ const error = e instanceof Error ? e.message : String(e);+ update(job, abort.signal.aborted ? { ...ended, status: 'cancelled' } : { ...ended, status: 'failed', error });+ if (!abort.signal.aborted) recordProblem({ area: 'export', step: job.ask.kind, what: error, project: root });} finally {work.delete(job.id);running = false;@@ -1345,7 +1328,8 @@ export function createExports({ onChange = () => {}, captions = subtitlesForExpo}/** @param {{ id: string, name: string, path: string }} project @param {ExportAsk} ask @param {string} folder */- function queue(project, ask, folder) {+ /** @param {{ id: string, name: string, path: string }} project @param {ExportAsk} ask @param {string} folder @param {string} [twin] */+ function queue(project, ask, folder, twin) {/** @type {ExportJob} */const job = {id: randomBytes(6).toString('hex'), project: project.id, name: project.name, label: ask.label ?? '', kind: ask.kind, ask,@@ -1353,7 +1337,7 @@ export function createExports({ onChange = () => {}, captions = subtitlesForExpooutputs: [], bytes: null, alpha: null, at: Date.now(), startedAt: null, finishedAt: null,};jobs.unshift(job);- work.set(job.id, { root: project.path, folder, abort: new AbortController() });+ work.set(job.id, { root: project.path, folder, abort: new AbortController(), ...(twin ? { twin } : {}) });onChange({ ...job, outputs: [] });return job;}@@ -1373,7 +1357,17 @@ export function createExports({ onChange = () => {}, captions = subtitlesForExpoif (!Array.isArray(body?.jobs) || !body.jobs.length || body.jobs.length > 24) throw new ExportError('jobs: a list of 1 to 24 exports');const asks = body.jobs.map((ask) => checked(/** @type {ExportAsk} */ (ask)));const folder = folderOf(body.folder);- const queued = asks.map((ask) => queue(project, ask, folder));+ /* asks the same but for their name (platforms that take the same frame, size and rate: 抖音, 快手, 视频号) are+ drawn once, and the others get that one's files */+ /** @type {Map<string, string>} */+ const first = new Map();+ const queued = asks.map((ask) => {+ const { preset, label, ...rest } = /** @type {ExportAsk & { preset?: string }} */ (ask);+ const same = ask.kind === 'video' || ask.kind === 'gif' ? JSON.stringify(rest, Object.keys(rest).sort()) : null;+ const job = queue(project, ask, folder, same ? first.get(same) : undefined);+ if (same && !first.has(same)) first.set(same, job.id);+ return job;+ });next();return queued.map((job) => ({ ...job }));},@@ -1405,13 +1399,15 @@ export function createExports({ onChange = () => {}, captions = subtitlesForExpo* render (src/render.mjs) in a process of its own (render-worker.mjs), as an editor's export runs apart from the editor:* what breaks in its browsers or encoders ends that export, said in its error, and never Studio. Same arguments and* result as render; `signal` asks it to stop, and it is ended if it has not after a few seconds.- * @param {string[]} args @param {Record<string, any>} opts @returns {Promise<{ out: string, lines: string[] }>}+ * @param {string[]} args @param {Record<string, any>} opts @returns {Promise<{ out: string, encoder: string, lines: string[] }>}*/function render(args, opts) {const { signal, onProgress, ...rest } = opts;return new Promise((done, fail) => {if (signal?.aborted) return fail(new Error('cancelled'));const child = fork(fileURLToPath(new URL('./render-worker.mjs', import.meta.url)), [], { stdio: ['ignore', 'inherit', 'pipe', 'ipc'] });+ /* before it is told what to render, so every browser and encoder it starts starts below too */+ below(child);let said = '';child.stderr?.on('data', (d) => { said = (said + d).slice(-4000); process.stderr.write(d); });let settled = false;diff --git a/packages/openfilm/studio/server/exports.test.mjs b/packages/openfilm/studio/server/exports.test.mjsindex bcd0bad..6451e80 100644--- a/packages/openfilm/studio/server/exports.test.mjs+++ b/packages/openfilm/studio/server/exports.test.mjs@@ -3,9 +3,10 @@ import assert from 'node:assert/strict';import { execFileSync, spawnSync } from 'node:child_process';import { existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';import { homedir, tmpdir } from 'node:os';-import { join } from 'node:path';+import { basename, join } from 'node:path';import { fileURLToPath } from 'node:url';-import { createExports, exportCapabilities, exportsRoot, ExportError, frameBox, dimsForShortEdge, hardwareEncoder, hardwareOptions, projectFiles, projectSizes } from './exports.mjs';+import { createExports, exportCapabilities, exportsRoot, ExportError, frameBox, dimsForShortEdge, projectFiles, projectSizes } from './exports.mjs';+import { encoders, hardwareEncoder } from '../../src/encoders.mjs';import { allocateLanes, containMotion, fadeKeyframes, frameSpan, nleRate, planNleTimeline, xmemlDocument } from './nle.mjs';import { fcpxmlDocument } from './fcpxml.mjs';import { pptxParts } from './slides.mjs';@@ -235,6 +236,8 @@ test('each codec this machine encodes, at the size asked, transparent where theassert.equal(probe(done.out, 'stream=codec_name,width,height'), `${name},160,90`, codec);if (codec === 'prores422hq') assert.equal(done.alpha, null, 'no alpha to measure');if (codec === 'prores4444' || codec === 'vp9') assert.deepEqual(done.alpha, { any: false }, `${codec}: the title paints over all of it`);+ /* ProRes on the Mac's ProRes engine when it has one, ffmpeg's own encoder otherwise */+ if (name === 'prores') assert.equal(done.encoder, (await hardwareEncoder('prores', await encoders())) ?? 'prores_ks', codec);}const hevc = can.hevc ? (await exported({ kind: 'video', codec: 'hevc', fps: 5, range: [0, 0.2] })).out : null;if (hevc) assert.equal(probe(hevc, 'stream=codec_tag_string'), 'hvc1', 'HEVC that Apple players open');@@ -966,22 +969,32 @@ test('an editing-software export of a film whose clip leads out of the project (assert.deepEqual(made.flatMap((n) => readdirSync(join(exportsRoot(), n), { recursive: true })).filter((f) => /private/.test(String(f))), []);});-test('each graphics chip\'s encoder gets a bitrate it keeps to, with HEVC tagged for Apple players', () => {- for (const encoder of ['h264_videotoolbox', 'h264_nvenc', 'h264_qsv', 'h264_amf', 'h264_mf', 'hevc_videotoolbox', 'hevc_nvenc', 'hevc_qsv', 'hevc_amf', 'hevc_mf']) {- const options = hardwareOptions(encoder, 8e6);- assert.deepEqual(options.slice(0, 2), ['-c:v', encoder]);- assert.equal(options[options.indexOf('-b:v') + 1], '8000k', encoder);- assert.equal(options.includes('hvc1'), encoder.startsWith('hevc_'), encoder);++test('a poster, and a video with its subtitles burned in, show footage no browser decodes (ProRes) through its copy', ffmpeg, async () => {+ const folder = mkdtempSync(join(tmpdir(), 'of-exports-prores-'));+ try {+ execFileSync('ffmpeg', ['-v', 'error', '-y', '-f', 'lavfi', '-i', 'color=c=0x2060c0:size=320x180:rate=30', '-t', '1', '-c:v', 'prores_ks', '-profile:v', '3', join(folder, 'a.mov')]);+ writeFileSync(join(folder, 'film.html'), filmHtml({ stage: { w: 320, h: 180 }, tracks: [{ clips: [{ id: 'v', src: 'a.mov', at: 0, time: [0, 1] }] }] }));+ const poster = await exported({ kind: 'poster', format: 'png', at: 0.5 }, 'ProRes', folder);+ assert.ok(near(firstFrame(poster.out).at(160, 90), [0x20, 0x60, 0xc0], 20), `the poster: ${firstFrame(poster.out).at(160, 90)}`);+ /* the film drawn inside a frame with its subtitles: the project's footage, copied for it too */+ const burned = await exported({ kind: 'video', fps: 10, range: [0, 0.5], burnSubtitles: true }, 'ProRes burned', folder);+ assert.ok(near(firstFrame(burned.out).at(160, 30), [0x20, 0x60, 0xc0], 24), `the burned video: ${firstFrame(burned.out).at(160, 30)}`);+ } finally {+ rmSync(folder, { recursive: true, force: true });}- assert.ok(hardwareOptions('h264_mf', 8e6).join(' ').includes('-hw_encoding 1'), 'never Windows\' software encoder');});-test('a hardware encoder is used only when this ffmpeg has it and it works', ffmpeg, async () => {- assert.equal(await hardwareEncoder('h264', new Set(['libx264']), 'win32'), null, 'none built in');- assert.equal(await hardwareEncoder('h264', new Set(['h264_nvenc']), 'darwin'), null, 'not one of this platform\'s');- const have = new Set(execFileSync('ffmpeg', ['-hide_banner', '-encoders']).toString().match(/^ V\S{5} (\S+)/gm)?.map((l) => l.trim().split(/\s+/)[1]) ?? []);- if (process.platform === 'darwin' && have.has('h264_videotoolbox')) {- assert.equal(await hardwareEncoder('h264', have), 'h264_videotoolbox');- assert.equal(await hardwareEncoder('hevc', have), have.has('hevc_videotoolbox') ? 'hevc_videotoolbox' : null);- }+test('platforms that take the same picture are drawn once, the others get its file under their own name', ffmpeg, async () => {+ const seen = [];+ const exports = createExports({ captions: subtitles, onChange: (job) => seen.push(job) });+ const same = { kind: 'video', frame: '9:16', shortEdge: 180, fps: 10, range: [0, 0.4] };+ const queued = exports.startAll(project('Feeds'), { jobs: [{ ...same, preset: '抖音' }, { ...same, preset: '快手' }, { ...same, preset: '视频号' }, { ...same, fps: 5, preset: 'Other' }] });+ const done = [];+ for (const job of queued) done.push(await ended(exports, job));+ assert.deepEqual(done.map((j) => j.status), ['done', 'done', 'done', 'done'], done.map((j) => j.error).join(' '));+ assert.deepEqual(done.map((j) => basename(j.out)), ['Feeds · 抖音 0-0.4s.mp4', 'Feeds · 快手 0-0.4s.mp4', 'Feeds · 视频号 0-0.4s.mp4', 'Feeds · Other 0-0.4s.mp4']);+ const drawn = new Set(seen.filter((j) => j.phase === 'rendering').map((j) => j.id));+ assert.deepEqual(done.map((j) => drawn.has(j.id)), [true, false, false, true], 'only the first of the same, and the one at another rate');+ assert.ok(readFileSync(done[1].out).equals(readFileSync(done[0].out)) && readFileSync(done[2].out).equals(readFileSync(done[0].out)), 'the same file');});diff --git a/packages/openfilm/studio/server/history.mjs b/packages/openfilm/studio/server/history.mjsindex 5e648fc..ddb920d 100644--- a/packages/openfilm/studio/server/history.mjs+++ b/packages/openfilm/studio/server/history.mjs@@ -27,7 +27,7 @@ import { tmpdir } from 'node:os';import { join } from 'node:path';import { promisify } from 'node:util';import { FILM_FILE, kindOf, readFilmFile } from '../../src/film-doc.mjs';-import { filmClosure, folderView, projectFiles, projectPath } from './closure.mjs';+import { clipFile, filmClosure, folderView, projectFiles } from './closure.mjs';import { FORMAT, formatOf, markFormat, migrateHistory } from './history-migrate.mjs';import {HistoryError, gitRun, keepFiles, openRepo, readBlobs, readVersion, sameAs, writeFiles, writeTree,@@ -203,7 +203,7 @@ function clipsOf(/** @type {string} */ text) {for (const track of doc?.tracks ?? []) {for (const clip of track.clips) {const src = String(clip.src);- clips.set(clip.id, { sound: kindOf(clip) === 'sound', file: projectPath(src, '') ?? src.replace(/[#?].*$/, ''), said: JSON.stringify(clip) });+ clips.set(clip.id, { sound: kindOf(clip) === 'sound', file: clipFile(src) ?? src, said: JSON.stringify(clip) });}}return { clips, stage: doc ? `${doc.stage.w}x${doc.stage.h}` : '' };diff --git a/packages/openfilm/studio/server/main.mjs b/packages/openfilm/studio/server/main.mjsindex da86373..5292b1a 100644--- a/packages/openfilm/studio/server/main.mjs+++ b/packages/openfilm/studio/server/main.mjs@@ -35,16 +35,21 @@ if (process.env.OPENFILM_STUDIO_WORKER !== '1') await supervise();const { startStudio } = await import('./server.mjs');const { closePageFrames } = await import('./pageframes.mjs');const { closeBrowsers } = await import('../../src/host.mjs');+const { recordProblem } = await import('../../src/problems.mjs');/* A browser's pipe that breaks (Playwright then throws where nothing can catch it) ends only the work on that browser:every browser is closed, so a render waiting on one fails and says so, the next one starts a new browser, and Studiokeeps serving. Anything else still ends the process, its state unknown. */process.on('uncaughtException', (e) => {console.error('uncaught:', e);+ recordProblem({ area: 'studio', step: 'uncaught', what: String(e?.message ?? e) });if (/playwright-core/.test(String(e?.stack ?? ''))) { void closePageFrames().catch(() => {}); void closeBrowsers(); return; }process.exit(1);});-process.on('unhandledRejection', (e) => { console.error('unhandled rejection:', e); });+process.on('unhandledRejection', (e) => {+ console.error('unhandled rejection:', e);+ recordProblem({ area: 'studio', step: 'unhandled rejection', what: String(/** @type {any} */ (e)?.message ?? e) });+});const given = process.env.OPENFILM_STUDIO_PORT;const port = given != null && given !== '' && Number.isInteger(Number(given)) ? Number(given) : 4747;diff --git a/packages/openfilm/studio/server/pageframes.mjs b/packages/openfilm/studio/server/pageframes.mjsindex 8bc3dd8..003151f 100644--- a/packages/openfilm/studio/server/pageframes.mjs+++ b/packages/openfilm/studio/server/pageframes.mjs@@ -12,7 +12,8 @@ import { existsSync } from 'node:fs';import { mkdir, readFile, stat } from 'node:fs/promises';import { join } from 'node:path';import { FilmPage, launch } from '../../src/host.mjs';-import { FILM_FILE } from '../../src/film-doc.mjs';+import { FILM_FILE, clipKind } from '../../src/film-doc.mjs';+import { browserCopies, filmVideos, madeCopy } from '../../src/seekable.mjs';import { TOOL_DIR } from './projects.mjs';import { writeAtomic } from './atomic.mjs';import { inProject } from './files.mjs';@@ -88,6 +89,9 @@ export async function pageFrame(root, base, rel, ms, width, overrides = null) {const pending = drawing.get(id);if (pending) return pending;const made = (async () => {+ /* the film's footage this browser does not decode (ProRes; HEVC without a chip for it) gets a copy it plays first,+ served in its place (pages.mjs): drawn without one, the film shows nothing where it is */+ if (rel === FILM_PAGE) await filmCopies(root, base, info);/* a page drawn with tweaks is one of its own: the page kept open for another clip of the same file has none */const drawn = tweaks ? `${version}:${createHash('sha256').update(tweaks).digest('hex').slice(0, 12)}` : version;const { jpeg, duration, loaded } = await draw(pageUrl(base, rel), ms, w, drawn, base, tweaks ? overrides : null).catch((e) => {@@ -115,12 +119,33 @@ export async function pageFrame(root, base, rel, ms, width, overrides = null) {return made;}-/** What `files` (project relative) are now: each one's change time and size, as one text (a file gone reads so). */+/**+ * What `files` (project relative) are now: each one's change time and size, as one text (a file gone reads so); a+ * video with a copy played in its place (seekable.mjs) says so, so a frame drawn before the copy was made is not kept.+ */async function stampOf(/** @type {string} */ root, /** @type {string[]} */ files) {- const parts = await Promise.all(files.map((f) => stat(join(root, f)).then((s) => `${f}:${s.mtimeMs}:${s.size}`, () => `${f}:-`)));+ const parts = await Promise.all(files.map((f) => stat(join(root, f)).then(+ (s) => `${f}:${s.mtimeMs}:${s.size}${clipKind(f) === 'video' && madeCopy(join(root, f), root) ? ':copy' : ''}`, () => `${f}:-`)));return createHash('sha256').update(parts.join('\n')).digest('hex').slice(0, 24);}+/** @type {Map<string, string>} the version of each project's film.html whose footage got its copies */+const copied = new Map();+/**+ * The copies the film's footage needs to be drawn by this browser (seekable.mjs), made once for each version of+ * film.html (`info`); a footage file changed since gets its own when it is drawn next with a changed film.html.+ * @param {string} root @param {string} base @param {import('node:fs').Stats} info+ */+async function filmCopies(root, base, info) {+ const version = `${info.mtimeMs}:${info.size}`;+ if (copied.get(root) === version) return;+ browser ??= launch().catch((e) => { browser = null; throw e; });+ const b = await browser.catch(() => null);+ if (!b) return;+ await browserCopies(b, base, root, filmVideos(root, FILM_FILE));+ copied.set(root, version);+}+/** The film's last poster, in `.film/cache/`: what its card shows at once while the poster of a changed film is drawn. */const FILM_POSTER = 'film-poster.jpg';/** How long a card waits for the film's current poster before it is given the last one: one drawn already is readdiff --git a/packages/openfilm/studio/server/pageframes.test.mjs b/packages/openfilm/studio/server/pageframes.test.mjsindex ccb26e6..32d25b6 100644--- a/packages/openfilm/studio/server/pageframes.test.mjs+++ b/packages/openfilm/studio/server/pageframes.test.mjs@@ -1,5 +1,6 @@import { test, before, after } from 'node:test';import assert from 'node:assert/strict';+import { execFileSync } from 'node:child_process';import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';import { tmpdir } from 'node:os';import { join } from 'node:path';@@ -134,3 +135,14 @@ test('a page\'s facts: its own size, or none (reflows: shown alone at 1920 × 10assert.deepEqual(await facts('chart.html'), { width: 480, height: 320 });assert.deepEqual(await facts('cards.html'), { duration: 5, width: 1920, height: 1080, reflows: true });});++const hasFfmpeg = (() => { try { execFileSync('ffmpeg', ['-version'], { stdio: 'ignore' }); return true; } catch { return false; } })();++test('a film whose footage no browser decodes (ProRes) has its picture on its card, through a copy', { skip: !hasFfmpeg && 'no ffmpeg', timeout: 120_000 }, async () => {+ const { project } = await (await api('/api/projects', { method: 'POST', body: { path: join(scratch, 'ProRes') } })).json();+ execFileSync('ffmpeg', ['-v', 'error', '-y', '-f', 'lavfi', '-i', 'color=c=0x2060c0:size=320x180:rate=30', '-t', '2', '-c:v', 'prores_ks', '-profile:v', '3', join(project.path, 'a.mov')]);+ writeFileSync(join(project.path, 'film.html'), filmHtml({ stage: { w: 320, h: 180 }, tracks: [{ clips: [{ id: 'v', src: 'a.mov', at: 0, time: [0, 2] }] }] }));+ const jpeg = await posterOf(project.id);+ const [r, g, b] = execFileSync('ffmpeg', ['-v', 'error', '-f', 'image2pipe', '-i', '-', '-frames:v', '1', '-vf', 'crop=4:4:iw/2:ih/2,format=rgb24', '-f', 'rawvideo', '-'], { input: jpeg });+ assert.ok(Math.abs(r - 0x20) < 20 && Math.abs(g - 0x60) < 20 && Math.abs(b - 0xc0) < 20, `the footage's colour: ${r},${g},${b}`);+});diff --git a/packages/openfilm/studio/server/pages.mjs b/packages/openfilm/studio/server/pages.mjsindex bd9f4b4..9b1013a 100644--- a/packages/openfilm/studio/server/pages.mjs+++ b/packages/openfilm/studio/server/pages.mjs@@ -29,6 +29,8 @@ import { readableLink } from '../../src/media-links.mjs';import { clipKind } from '../../src/film-doc.mjs';import { readPrefs } from './prefs.mjs';import { readyProxy } from './proxies.mjs';+import { madeCopy } from '../../src/seekable.mjs';+import { isPreviewKey, previewDir } from './preview-cache.mjs';import { soundOf } from './derived.mjs';const BRIDGE = readFileSync(new URL('./bridge.js', import.meta.url), 'utf8');@@ -70,6 +72,12 @@ async function playableCopy(root, rel) {return made;}const STAGE = readFileSync(new URL('./stage.js', import.meta.url), 'utf8');+/*+ * A page in the preview's film draws at the pixels the viewer shows it at: its devicePixelRatio is the one the editor+ * put in the film's address (`film-dpr`, editor/Preview.tsx), so a canvas sized by it (SPEC §3) is no larger than what is+ * seen. The film's own videos and pictures, and every page drawn for an export, are as the screen is.+ */+const PAGE_SCALE = `(()=>{try{if(parent===window)return;const k=Number(new URL(parent.location.href).searchParams.get('film-dpr'));if(k>0)Object.defineProperty(window,'devicePixelRatio',{configurable:true,get:()=>k})}catch{}})();`;/*** Whether a request was addressed to this machine at `port` by name (its Host): another site whose name is made to@@ -121,14 +129,15 @@ export async function startPages({ port, editorOrigin, secret, projects }) {/* the timeline page (the preview) gets the bridge and the stage; a web page gets the bridge too, so the editor canplay one on its own (the media pane's viewer) — inside the timeline it stays quiet: its parent is not the editor */const filesOf = (/** @type {string} */ root) => folderFiles(root, {- inject: `<script>${HOST_FLAG}</script>${scripts(BRIDGE)}`,+ inject: `<script>${HOST_FLAG}${PAGE_SCALE}</script>${scripts(BRIDGE)}`,timelineInject: `<script>${HOST_FLAG}</script>${scripts(BRIDGE, STAGE)}`,headers: policy(),- /* heavy footage is played from its proxy once it is made, while proxies are on (proxies.mjs): the preview only */+ /* heavy footage is played from its proxy once it is made, while proxies are on (proxies.mjs); else from a copy made+ for footage the browser does not decode, or that seeks slowly (src/seekable.mjs), when there is one */swap: (file) => {if (clipKind(file) !== 'video') return null;const { proxies } = readPrefs();- return proxies.on ? readyProxy(root, relative(root, file).split(sep).join('/'), proxies.height) : null;+ return (proxies.on ? readyProxy(root, relative(root, file).split(sep).join('/'), proxies.height) : null) ?? madeCopy(file, root);},});@@ -175,6 +184,13 @@ export async function startPages({ port, editorOrigin, secret, projects }) {if (!folderFiles(dirname(file), { headers: policy() })(req, res, `/${basename(file)}`, url.searchParams)) res.writeHead(403, headers).end();return;}+ /* a stretch of the film rendered for the preview to play in its place (preview-cache.mjs): its cache, not the+ project's files */+ const render = /^\/__film\/preview\/([0-9a-f]+)\.mp4$/.exec(plain);+ if (render && isPreviewKey(render[1])) {+ if (!folderFiles(previewDir(entry.root), { headers: policy() })(req, res, `/${render[1]}.mp4`, url.searchParams)) res.writeHead(403, headers).end();+ return;+ }if (UNPLAYABLE.test(plain)) {const copy = await playableCopy(entry.root, plain.replace(/^\/+/, ''));if (!copy) { res.writeHead(404, headers).end('not found'); return; }diff --git a/packages/openfilm/studio/server/prefs.mjs b/packages/openfilm/studio/server/prefs.mjsindex 83eda6d..e252d72 100644--- a/packages/openfilm/studio/server/prefs.mjs+++ b/packages/openfilm/studio/server/prefs.mjs@@ -5,16 +5,18 @@** proxies light copies of heavy footage for the preview (proxies.mjs): on, and how tall* seenVersion the version whose "what's new" was last shown (null: none yet, a new install shows none)- * projectsFolder where new projects go, when the person chose (null: the default; src/locations.mjs, which the- * `openfilm` command reads too)+ * projectsFolder where the projects library is, when the person chose (null: the default; src/locations.mjs,+ * which the `openfilm` command reads too). Kept in the prefs.json of the home that holds the library+ * (OPENFILM_SHARED_HOME, else this one), so every OpenFilm on the computer shares it.*/import { mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';import { isAbsolute, join, resolve } from 'node:path';import { studioHome } from './projects.mjs';+import { chooseFolder, chosenFolder } from '../../src/locations.mjs';/** @typedef {{ proxies: { on: boolean, height: 540 | 720 | 1080 }, seenVersion: string | null, projectsFolder: string | null }} Prefs */-/** Proxies as CapCut has them: on, at 720p. */+/** Proxies on by default, at 720p. */export const DEFAULT_PREFS = /** @type {Prefs} */ ({ proxies: { on: true, height: 720 }, seenVersion: null, projectsFolder: null });const VERSION = /^\d+\.\d+\.\d+(?:-[\w.]+)?$/;const HEIGHTS = [540, 720, 1080];@@ -38,7 +40,9 @@ const file = () => join(studioHome(), 'prefs.json');/** @returns {Prefs} */export function readPrefs() {- try { return prefsOf(JSON.parse(readFileSync(file(), 'utf8'))); } catch { return prefsOf(null); }+ let own = null;+ try { own = JSON.parse(readFileSync(file(), 'utf8')); } catch { /* none yet */ }+ return { ...prefsOf(own), projectsFolder: chosenFolder('projectsFolder') };}/**@@ -53,8 +57,11 @@ export function writePrefs(patch) {const at = file();let kept = {};try { const raw = JSON.parse(readFileSync(at, 'utf8')); if (raw && typeof raw === 'object' && !Array.isArray(raw)) kept = raw; } catch { /* none yet */ }+ const { projectsFolder, ...own } = next;mkdirSync(studioHome(), { recursive: true });- writeFileSync(`${at}.${process.pid}.tmp`, `${JSON.stringify({ ...kept, ...next, proxies: { ...(/** @type {{ proxies?: object }} */ (kept).proxies ?? {}), ...next.proxies } }, null, 2)}\n`);+ writeFileSync(`${at}.${process.pid}.tmp`, `${JSON.stringify({ ...kept, ...own, proxies: { ...(/** @type {{ proxies?: object }} */ (kept).proxies ?? {}), ...next.proxies } }, null, 2)}\n`);renameSync(`${at}.${process.pid}.tmp`, at);+ /* where the library is: in the home that holds it (src/locations.mjs) */+ if ('projectsFolder' in asked) chooseFolder('projectsFolder', projectsFolder);return next;}diff --git a/packages/openfilm/studio/server/preview-cache.mjs b/packages/openfilm/studio/server/preview-cache.mjsnew file mode 100644index 0000000..381b7b2--- /dev/null+++ b/packages/openfilm/studio/server/preview-cache.mjs@@ -0,0 +1,205 @@+// @ts-check+/**+ * Preview renders: stretches of a film the preview cannot draw as fast as it plays (a page heavy with 3D, many videos+ * at once), rendered in the background into a video the preview plays in their place while the film plays. The editor+ * says which stretches played late (the frames the screen got late, see bridge.js `played`); each one is rendered by+ * the film's own renderer (src/render.mjs, in a process of its own at low priority, one page), at the preview's size+ * and the film's frame rate, its picture only, into the project's cache. Paused, scrubbed or edited, the preview draws+ * the film itself; exports always do.+ *+ * A render is named by everything its picture depends on: film.html, every file of the project but its sounds, the+ * stretch, the rate and the size. Any change makes another name, so a stale render is never played; renders asked for+ * under names no longer current are let go.+ */+import { fork } from 'node:child_process';+import { createHash } from 'node:crypto';+import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync } from 'node:fs';+import { setPriority } from 'node:os';+import { extname, join } from 'node:path';+import { fileURLToPath } from 'node:url';+import { DEFAULT_STAGE, FILM_FILE, readFilmFile } from '../../src/film-doc.mjs';+import { writeAtomic } from './atomic.mjs';+import { TOOL_DIR } from './projects.mjs';++/** Changing how renders are made names them anew. */+const VERSION = 1;+/** Files whose change cannot change the picture. */+const SOUNDS = new Set(['.mp3', '.wav', '.m4a', '.aac', '.ogg', '.oga', '.opus', '.flac', '.aif', '.aiff', '.aifc', '.vtt', '.srt']);+/** Most files of a project read for its fingerprint (a folder of thousands of frames is taken as a whole beyond that). */+const MOST_FILES = 20_000;++/** Where a project's preview renders are kept. @param {string} root */+export const previewDir = (root) => join(root, TOOL_DIR, 'cache', 'preview');++/** A render's name is 20 hex digits: anything else asked for is not one. @param {string} key */+export const isPreviewKey = (key) => /^[0-9a-f]{20}$/.test(key);++/**+ * What the project's files are now, as far as a picture can tell: every file but its sounds and film.html, by path,+ * size and time changed (dot folders, the tools' own, left out).+ * @param {string} root+ */+export function projectPrint(root) {+ const hash = createHash('sha1');+ let seen = 0;+ /** @param {string} dir @param {string} rel */+ const walk = (dir, rel) => {+ let names;+ try { names = readdirSync(dir, { withFileTypes: true }); } catch { return; }+ names.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));+ for (const d of names) {+ if (d.name.startsWith('.') || seen > MOST_FILES) continue;+ const path = rel ? `${rel}/${d.name}` : d.name;+ if (d.isDirectory()) { walk(join(dir, d.name), path); continue; }+ if (path === FILM_FILE || SOUNDS.has(extname(d.name).toLowerCase())) continue;+ seen += 1;+ try { const s = statSync(join(dir, d.name)); hash.update(`${path}\0${s.size}\0${Math.round(s.mtimeMs)}\n`); } catch { /* gone meanwhile */ }+ }+ };+ walk(root, '');+ return hash.digest('hex');+}++/**+ * The name of a render of film seconds [a, b) at `fps` and `height` (its short side), for the project as it is now.+ * @param {string} root @param {number} a @param {number} b @param {number} fps @param {number} height @param {string} [print]+ */+export function previewKey(root, a, b, fps, height, print = projectPrint(root)) {+ let film = '';+ try { film = readFileSync(join(root, FILM_FILE), 'utf8'); } catch { /* none: nothing renders */ }+ return createHash('sha1').update(`${VERSION}\0${film}\0${print}\0${a}\0${b}\0${fps}\0${height}`).digest('hex').slice(0, 20);+}++/**+ * The stretches of the project known to play late, as the editor last said them (film seconds [a, b)), kept with its+ * renders so another session of the editor plays them from their renders at once, not late first.+ * @param {string} root @returns {[number, number][]}+ */+export function knownLate(root) {+ try {+ const { ranges } = JSON.parse(readFileSync(join(previewDir(root), LATE_FILE), 'utf8'));+ return Array.isArray(ranges) ? ranges.filter((r) => Array.isArray(r) && r.length === 2 && r.every(Number.isFinite) && r[1] > r[0]) : [];+ } catch { return []; }+}+const LATE_FILE = 'late.json';++/** @typedef {{ state: 'waiting' | 'making' | 'ready' | 'failed', ratio?: number }} PreviewState */+/** @typedef {PreviewState & { a: number, b: number, key: string }} PreviewRange */++/**+ * The render asked for, by its file, and what became of it.+ * @type {Map<string, PreviewState & { root: string, a: number, b: number, fps: number, height: number, abort?: AbortController }>}+ */+const jobs = new Map();+let running = false;++/**+ * Renders of `ranges` (film seconds, each put on the film's frame grid) for the project at `root`, at `fps` and+ * `height`: each one's name and state, a render asked for when there is none yet. Renders of this project asked for+ * earlier under other names (the film changed since) are let go.+ * @param {string} root @param {[number, number][]} ranges @param {number} fps @param {number} height+ * @param {(root: string, a: number, b: number, fps: number, height: number, out: string, signal: AbortSignal, progress: (ratio: number) => void) => Promise<void>} [make]+ * @returns {PreviewRange[]}+ */+export function ensurePreviews(root, ranges, fps, height, make = renderApart) {+ const print = projectPrint(root);+ const dir = previewDir(root);+ /* what is known to play late, for the next session (not kept: found again as it plays) */+ if (JSON.stringify(knownLate(root)) !== JSON.stringify(ranges)) {+ try { mkdirSync(dir, { recursive: true }); } catch { /* writeAtomic says so */ }+ void writeAtomic(join(dir, LATE_FILE), `${JSON.stringify({ ranges })}\n`).catch(() => {});+ }+ /** @type {PreviewRange[]} */+ const states = [];+ const current = new Set();+ for (const [from, to] of ranges) {+ const a = Math.floor(from * fps + 1e-6) / fps;+ const b = Math.ceil(to * fps - 1e-6) / fps;+ if (!(b > a)) continue;+ const key = previewKey(root, a, b, fps, height, print);+ const out = join(dir, `${key}.mp4`);+ current.add(out);+ if (existsSync(out)) { states.push({ a, b, key, state: 'ready' }); continue; }+ let job = jobs.get(out);+ if (!job) {+ job = { root, a, b, fps, height, state: 'waiting' };+ jobs.set(out, job);+ }+ states.push({ a, b, key, state: job.state, ...(job.state === 'making' ? { ratio: job.ratio ?? 0 } : {}) });+ }+ /* the film changed: what was asked of it before is no longer wanted */+ for (const [out, job] of jobs) {+ if (job.root !== root || current.has(out)) continue;+ job.abort?.abort();+ jobs.delete(out);+ }+ void drain(make);+ return states;+}++/** Make the renders waiting, one at a time. @param {Parameters<typeof ensurePreviews>[4] & {}} make */+async function drain(make) {+ if (running) return;+ running = true;+ try {+ for (;;) {+ const next = [...jobs.entries()].find(([, job]) => job.state === 'waiting');+ if (!next) return;+ const [out, job] = next;+ job.state = 'making';+ job.ratio = 0;+ job.abort = new AbortController();+ mkdirSync(previewDir(job.root), { recursive: true });+ const part = `${out}.part.mp4`;+ try {+ await make(job.root, job.a, job.b, job.fps, job.height, part, job.abort.signal, (ratio) => { job.ratio = ratio; });+ if (job.abort.signal.aborted) throw new Error('cancelled');+ renameSync(part, out);+ jobs.delete(out);+ } catch {+ rmSync(part, { force: true });+ /* let go (the film changed): forgotten; failed: said, and not tried again under this name */+ if (jobs.get(out) === job) job.state = 'failed';+ }+ }+ } finally { running = false; }+}++/** A number as render's range takes it: plain digits, no exponent. @param {number} n */+const num = (n) => String(Number(n.toFixed(3)));++/**+ * One stretch rendered by src/render.mjs in a process of its own (render-worker.mjs), at low priority so the editor+ * and the person's other apps come first, with one page; its picture only.+ * @type {Parameters<typeof ensurePreviews>[4] & {}}+ */+function renderApart(root, a, b, fps, height, out, signal, progress) {+ return new Promise((done, fail) => {+ if (signal.aborted) { fail(new Error('cancelled')); return; }+ const child = fork(fileURLToPath(new URL('./render-worker.mjs', import.meta.url)), [], { stdio: ['ignore', 'ignore', 'ignore', 'ipc'] });+ try { if (child.pid) setPriority(child.pid, 10); } catch { /* left as it is */ }+ const cancel = () => {+ if (child.connected) child.send({ type: 'cancel' });+ setTimeout(() => { if (child.exitCode == null && child.signalCode == null) child.kill('SIGKILL'); }, 5000).unref();+ };+ signal.addEventListener('abort', cancel, { once: true });+ let settled = false;+ /** @param {() => void} end */+ const settle = (end) => { if (settled) return; settled = true; signal.removeEventListener('abort', cancel); end(); };+ child.on('message', (/** @type {any} */ m) => {+ if (m?.type === 'progress') progress(m.total > 0 ? Math.min(0.99, m.done / m.total) : 0);+ else if (m?.type === 'done') settle(() => done(undefined));+ else if (m?.type === 'failed') settle(() => fail(new Error(m.error)));+ });+ child.on('error', (e) => settle(() => fail(e)));+ child.on('exit', (code) => settle(() => fail(new Error(`the renderer stopped (exit ${code})`))));+ const stage = filmStage(root);+ const scale = height / Math.max(1, Math.min(stage.w, stage.h));+ child.send({ args: [root, `${num(a)}-${num(b)}`], opts: { fps, scale: Math.min(1, scale), workers: 1, silent: true, out } });+ });+}++/** The film's stage, as film.html says it. @param {string} root */+function filmStage(root) {+ try { return readFilmFile(readFileSync(join(root, FILM_FILE), 'utf8')).doc?.stage ?? DEFAULT_STAGE; } catch { return DEFAULT_STAGE; }+}diff --git a/packages/openfilm/studio/server/preview-cache.test.mjs b/packages/openfilm/studio/server/preview-cache.test.mjsnew file mode 100644index 0000000..3c7480f--- /dev/null+++ b/packages/openfilm/studio/server/preview-cache.test.mjs@@ -0,0 +1,110 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { existsSync, mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';+import { tmpdir } from 'node:os';+import { join } from 'node:path';+import { filmHtml } from '../../src/film-doc.mjs';+import { ensurePreviews, isPreviewKey, previewDir, previewKey } from './preview-cache.mjs';+import { startPages } from './pages.mjs';++const page = (word) => `<!doctype html><body style="margin:0;background:#123"><p>${word}</p><script>window.film={duration:2,frame(){}}</script></body>`;++/** A project of one page clip, 320 × 180. */+function project() {+ const dir = mkdtempSync(join(tmpdir(), 'of-previews-'));+ writeFileSync(join(dir, 'a.html'), page('a'));+ writeFileSync(join(dir, 'beat.wav'), 'not really a sound');+ writeFileSync(join(dir, 'film.html'), filmHtml({ stage: { w: 320, h: 180 }, tracks: [{ clips: [{ id: 'a', src: 'a.html' }] }] }));+ return dir;+}++/** Wait until `ok()`, a moment at a time. */+async function until(ok, ms = 5000) {+ for (const end = Date.now() + ms; Date.now() < end; await new Promise((r) => setTimeout(r, 20))) if (ok()) return;+ throw new Error('waited too long');+}++test('a render is named by all its picture depends on: film.html and the pages change it, a sound does not', () => {+ const dir = project();+ const key = previewKey(dir, 0, 1, 30, 540);+ assert.ok(isPreviewKey(key));+ assert.equal(previewKey(dir, 0, 1, 30, 540), key, 'the same project, the same name');+ assert.notEqual(previewKey(dir, 0, 1.5, 30, 540), key, 'another stretch');+ assert.notEqual(previewKey(dir, 0, 1, 30, 720), key, 'another size');+ writeFileSync(join(dir, 'beat.wav'), 'another sound, the same picture');+ assert.equal(previewKey(dir, 0, 1, 30, 540), key);+ writeFileSync(join(dir, 'a.html'), page('changed'));+ const changed = previewKey(dir, 0, 1, 30, 540);+ assert.notEqual(changed, key, 'a page changed');+ writeFileSync(join(dir, 'film.html'), filmHtml({ stage: { w: 320, h: 180 }, tracks: [{ clips: [{ id: 'a', src: 'a.html', at: 0.5 }] }] }));+ assert.notEqual(previewKey(dir, 0, 1, 30, 540), changed, 'the film changed');+ /* the tools' own folder is not the picture's */+ mkdirSync(join(dir, '.film'), { recursive: true });+ writeFileSync(join(dir, '.film', 'settings.json'), '{}');+ assert.equal(previewKey(dir, 0, 1, 30, 540), previewKey(dir, 0, 1, 30, 540));+});++test('renders are made one at a time, on the frame grid; asked again under other names, the old ones are let go', async () => {+ const dir = project();+ const made = [];+ let finish = () => {};+ /* a renderer that writes its file once the test lets it */+ const make = (root, a, b, fps, height, out, signal) => new Promise((done, fail) => {+ made.push({ a, b, fps, height, signal });+ signal.addEventListener('abort', () => fail(new Error('cancelled')), { once: true });+ finish = () => { writeFileSync(out, 'video'); done(undefined); };+ });+ const [first] = ensurePreviews(dir, [[1.01, 2.02]], 30, 540, make);+ assert.equal(first.a, 1, 'its start on the frame before');+ assert.ok(Math.abs(first.b - 61 / 30) < 1e-9, 'its end on the frame after');+ await until(() => made.length === 1);+ assert.equal(ensurePreviews(dir, [[1.01, 2.02]], 30, 540, make)[0].state, 'making');+ finish();+ await until(() => existsSync(join(previewDir(dir), `${first.key}.mp4`)));+ assert.equal(ensurePreviews(dir, [[1.01, 2.02]], 30, 540, make)[0].state, 'ready');+ /* the film changes while another stretch renders: that render is let go */+ ensurePreviews(dir, [[3, 4]], 30, 540, make);+ await until(() => made.length === 2);+ writeFileSync(join(dir, 'a.html'), page('changed'));+ const [now] = ensurePreviews(dir, [[3, 4]], 30, 540, make);+ assert.ok(made[1].signal.aborted, 'the stale render stopped');+ assert.notEqual(now.state, 'ready');+ await until(() => made.length === 3);+ finish();+ await until(() => existsSync(join(previewDir(dir), `${now.key}.mp4`)));+});++test('the film\'s origin serves a render by its name from the project\'s cache, and nothing else there', async () => {+ const dir = project();+ mkdirSync(previewDir(dir), { recursive: true });+ const key = 'abcdef0123456789abcd';+ writeFileSync(join(previewDir(dir), `${key}.mp4`), 'video bytes');+ writeFileSync(join(previewDir(dir), 'notes.txt'), 'not a render');+ const pages = await startPages({ port: 0, editorOrigin: () => 'http://127.0.0.1:1', secret: 'k', projects: async () => [{ id: 'p', path: dir }] });+ try {+ const folder = pages.folderUrl({ id: 'p', path: dir });+ const got = await fetch(`${folder}__film/preview/${key}.mp4`);+ assert.equal(got.status, 200);+ assert.equal(await got.text(), 'video bytes');+ const part = await fetch(`${folder}__film/preview/${key}.mp4`, { headers: { range: 'bytes=0-4' } });+ assert.equal(part.status, 206, 'a video is read in ranges');+ for (const other of ['notes.txt', 'abc.mp4', `${key}.mp4.part.mp4`, `../${key}.mp4`]) {+ assert.notEqual((await fetch(`${folder}__film/preview/${other}`)).status, 200, other);+ }+ } finally {+ await pages.close();+ }+});++test('a stretch is rendered by the film\'s own renderer, its picture only, at the size asked', { timeout: 180_000 }, async () => {+ const dir = project();+ const [asked] = ensurePreviews(dir, [[0.5, 1.5]], 30, 90);+ const out = join(previewDir(dir), `${asked.key}.mp4`);+ await until(() => existsSync(out) || ensurePreviews(dir, [[0.5, 1.5]], 30, 90)[0].state === 'failed', 170_000);+ assert.ok(existsSync(out), 'rendered');+ const { execFileSync } = await import('node:child_process');+ const probe = JSON.parse(execFileSync('ffprobe', ['-v', 'error', '-show_entries', 'stream=codec_type,width,height,nb_frames', '-of', 'json', out], { encoding: 'utf8' }));+ assert.deepEqual(probe.streams.map((s) => s.codec_type), ['video'], 'no sound in it');+ assert.equal(probe.streams[0].height, 90);+ assert.equal(Number(probe.streams[0].nb_frames), 30, 'a second at 30 fps');+});diff --git a/packages/openfilm/studio/server/projects.mjs b/packages/openfilm/studio/server/projects.mjsindex 6433ff0..9f3e081 100644--- a/packages/openfilm/studio/server/projects.mjs+++ b/packages/openfilm/studio/server/projects.mjs@@ -1,6 +1,7 @@// @ts-check/**- * Projects: folders, and the list of the ones opened recently (~/.openfilm/studio.json). A project is its folder, and+ * Projects: folders, and the list of them (~/.openfilm/studio.json): every project in the library (src/locations.mjs,+ * one folder each, found again at each listing) and the ones opened from elsewhere. A project is its folder, and* everything about it is in the folder, so moving or copying the folder moves or copies the project:** film.html, its pages and code, assets/ the work@@ -16,13 +17,14 @@import { moveToTrash } from './trash.mjs';import { randomBytes } from 'node:crypto';import { existsSync, mkdirSync, readFileSync, realpathSync, statSync, writeFileSync } from 'node:fs';-import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';+import { cp, mkdir, readFile, rename, writeFile } from 'node:fs/promises';import { homedir } from 'node:os';import { basename, dirname, join, resolve, sep } from 'node:path';import { EMPTY_FILM } from './film.mjs';import { FILM_FILE, filmHtml } from '../../src/film-doc.mjs';import { writeAtomic } from './atomic.mjs';-import { libraryRoot } from '../../src/locations.mjs';+import { coverAt } from './cover.mjs';+import { libraryProjects, libraryRoot } from '../../src/locations.mjs';export const TOOL_DIR = '.film';@@ -175,17 +177,20 @@ function folderName(/** @type {string} */ name) {/*** A project as the API gives it: `createdAt` is when its folder was made; `duration` (s) the film's length when Studio- * has drawn the film since film.html last changed (its poster), else absent; `folderId` its folder in the list.+ * has drawn the film since film.html last changed (its poster), else absent; `folderId` its folder in the list; `cover`+ * when the person last set a cover of its own (cover.mjs), else absent.*/const describe = (/** @type {Recent} */ r) => {const created = statSync(r.path, { throwIfNoEntry: false });const duration = filmDuration(r.path);+ const cover = coverAt(r.path);return {/* `missing`: its folder is gone (one that only lost its film.html is still there, and still opens) */id: r.id, path: r.path, name: basename(r.path), openedAt: r.openedAt, missing: !created?.isDirectory(),createdAt: created ? Math.round(created.birthtimeMs || created.ctimeMs) : r.openedAt,...(duration != null ? { duration } : {}),...(r.folderId ? { folderId: r.folderId } : {}),+ ...(cover != null ? { cover } : {}),};};@@ -198,9 +203,40 @@ function filmDuration(/** @type {string} */ folder) {} catch { return null; }}-/** The projects opened recently, most recent first; one whose folder is gone says so (`missing`). */+/**+ * The list follows the library: a project folder that came into it (made by an agent, copied in, a library moved here)+ * joins the list, at the time its film last changed, or, when it is a listed project whose folder is gone (moved here+ * outside Studio), the list points at it from now on; one that left it (deleted or moved away outside Studio) leaves+ * the list. Nothing changes while the library's folder is not there (a disk not plugged in). Returns whether it changed.+ * @param {StudioState} state+ */+async function followLibrary(state) {+ const root = libraryRoot();+ if (!existsSync(root)) return false;+ const real = realpathSync(root);+ const before = state.recent.length;+ state.recent = state.recent.filter((r) => !((dirname(r.path) === real || dirname(r.path) === root) && !existsSync(r.path)));+ let changed = state.recent.length !== before;+ for (const found of libraryProjects(real)) {+ if (state.recent.some((r) => r.path === found)) continue;+ await mkdir(join(found, TOOL_DIR), { recursive: true });+ await writeFile(join(found, TOOL_DIR, '.gitignore'), '*\n');+ const id = await folderId(found, state);+ changed = true;+ /* folderId gave a copy its own id, so a listed one with this id is this project, moved */+ const moved = state.recent.find((r) => r.id === id);+ if (moved) { moved.path = found; continue; }+ const film = statSync(join(found, FILM_FILE), { throwIfNoEntry: false }) ?? statSync(found);+ state.recent.push({ id, path: found, openedAt: Math.round(film.mtimeMs) });+ }+ if (changed) state.recent.sort((a, b) => b.openedAt - a.openedAt);+ return changed;+}++/** Every project of the library and the ones opened from elsewhere, most recent first; one whose folder is gone says so (`missing`). */export async function listProjects() {const state = await readState();+ if (await followLibrary(state)) await writeState(state);const folders = new Set(state.folders.map((f) => f.id));/* a project in a folder that was deleted is back at the top level */return state.recent.map((r) => describe(r.folderId && !folders.has(r.folderId) ? { ...r, folderId: undefined } : r));@@ -360,3 +396,51 @@ export async function forgetProject(/** @type {string} */ id) {state.recent = state.recent.filter((r) => r.id !== id);await writeState(state);}++/**+ * Move the library: from now on new projects go to `to` (null: the default), and with `move`, the projects in the old+ * library go with it, each folder whole (to "Name 2" when the new library already has a "Name"). Across disks a project+ * is copied, then its old folder goes to the Trash. Anything else in the old folder stays. A project that cannot move+ * stays where it is, in the list, and is named in `failed`.+ * @param {string | null} to @param {{ move?: boolean, choose: (folder: string | null) => void }} options+ */+export async function moveLibrary(to, { move = false, choose }) {+ const from = libraryRoot();+ choose(to);+ const into = libraryRoot();+ /** @type {{ name: string, error: string }[]} */+ const failed = [];+ let moved = 0;+ if (!move || resolve(from) === resolve(into) || !existsSync(from)) return { moved, failed };+ await mkdir(into, { recursive: true });+ const state = await readState();+ const realFrom = realpathSync(from);+ for (const folder of libraryProjects(from)) {+ let target = join(into, basename(folder));+ for (let n = 2; existsSync(target); n++) target = join(into, `${basename(folder)} ${n}`);+ try {+ try {+ await rename(folder, target);+ } catch (e) {+ if (/** @type {NodeJS.ErrnoException} */ (e).code !== 'EXDEV') throw e;+ try {+ await cp(folder, target, { recursive: true, errorOnExist: true, force: false, preserveTimestamps: true });+ } catch (copying) {+ /* half a copy is no project: it goes, the original stays */+ if (existsSync(target)) await moveToTrash(target).catch(() => {});+ throw copying;+ }+ await moveToTrash(folder);+ }+ } catch (e) {+ failed.push({ name: basename(folder), error: /** @type {Error} */ (e).message });+ continue;+ }+ moved++;+ const real = realpathSync(target);+ const was = join(realFrom, basename(folder));+ for (const r of state.recent) if (r.path === folder || r.path === was) r.path = real;+ }+ await writeState(state);+ return { moved, failed };+}diff --git a/packages/openfilm/studio/server/projects.test.mjs b/packages/openfilm/studio/server/projects.test.mjsindex d19fdbb..98ab27c 100644--- a/packages/openfilm/studio/server/projects.test.mjs+++ b/packages/openfilm/studio/server/projects.test.mjs@@ -3,7 +3,8 @@ import assert from 'node:assert/strict';import { cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, symlinkSync, writeFileSync } from 'node:fs';import { homedir, tmpdir } from 'node:os';import { join } from 'node:path';-import { createProject, forgetProject, listProjects, locateProject, openProject, projectById, renameProject, ProjectError } from './projects.mjs';+import { createProject, forgetProject, listProjects, locateProject, moveLibrary, openProject, projectById, renameProject, ProjectError } from './projects.mjs';+import { chooseFolder } from '../../src/locations.mjs';import { readFilmFile } from '../../src/film-doc.mjs';let scratch;@@ -11,6 +12,7 @@ beforeEach(() => {scratch = mkdtempSync(join(tmpdir(), 'of-projects-'));process.env.OPENFILM_HOME = join(scratch, 'home');process.env.OPENFILM_LIBRARY = join(scratch, 'library');+ delete process.env.OPENFILM_SHARED_HOME;});test('opening a new folder makes it a project: an empty film, .film/ with an id, kept out of git', async () => {@@ -156,3 +158,84 @@ test('what a newer OpenFilm keeps in studio.json stays when this one writes it',assert.deepEqual(written.pinned, ['abc']);assert.equal(written.recent.length, 1);});++/** A film folder made outside Studio (by an agent, copied in), as Studio has never seen it. */+function filmFolder(/** @type {string} */ folder) {+ mkdirSync(folder, { recursive: true });+ writeFileSync(join(folder, 'film.html'), '{"stage":{"w":1920,"h":1080},"tracks":[]}');+ return folder;+}++test('the list shows every project in the library, made in Studio or not; plain folders and hidden ones are not projects', async () => {+ const made = await createProject('Made');+ filmFolder(join(scratch, 'library', 'By agent'));+ mkdirSync(join(scratch, 'library', 'Just a folder'));+ filmFolder(join(scratch, 'library', '.hidden'));+ const names = (await listProjects()).map((p) => p.name).sort();+ assert.deepEqual(names, ['By agent', 'Made']);+ const found = (await listProjects()).find((p) => p.name === 'By agent');+ assert.equal(readFileSync(join(found.path, '.film', 'id'), 'utf8').trim(), found.id, 'it has an id, the same at the next listing');+ assert.equal((await projectById(made.id)).name, 'Made');+});++test('a project deleted from the library outside Studio leaves the list; one opened from elsewhere stays, missing', async () => {+ const inside = await createProject('Inside');+ const outside = await openProject(join(scratch, 'elsewhere'));+ renameSync(inside.path, join(scratch, 'gone'));+ renameSync(outside.path, join(scratch, 'gone too'));+ const listed = await listProjects();+ assert.equal(listed.some((p) => p.id === inside.id), false);+ assert.equal(listed.find((p) => p.id === outside.id)?.missing, true);+});++test('while the library\'s folder is not there (a disk unplugged), its projects stay in the list', async () => {+ const p = await createProject('On a disk');+ renameSync(join(scratch, 'library'), join(scratch, 'unplugged'));+ assert.equal((await listProjects()).find((x) => x.id === p.id)?.missing, true);+});++test('moving the library with its projects: each folder whole, a name taken becomes "Name 2", the rest stays', async () => {+ const a = await createProject('Alpha');+ const b = await createProject('Beta');+ writeFileSync(join(scratch, 'library', 'notes.txt'), 'mine');+ const to = filmFolder(join(scratch, 'New', 'Beta'));+ const done = await moveLibrary(join(scratch, 'New'), { move: true, choose: (f) => chooseFolder('projectsFolder', f) });+ assert.deepEqual(done, { moved: 2, failed: [] });+ const listed = await listProjects();+ const real = realpathSync(join(scratch, 'New'));+ assert.equal(listed.find((p) => p.id === a.id)?.path, join(real, 'Alpha'), 'the same project, at its new folder');+ assert.equal(listed.find((p) => p.id === b.id)?.path, join(real, 'Beta 2'));+ assert.ok(existsSync(join(to, 'film.html')), 'what was there already stays');+ assert.ok(existsSync(join(scratch, 'library', 'notes.txt')), 'what is not a project stays');+ assert.ok((await createProject('Next')).path.startsWith(real), 'new projects go to the new library');+});++test('moving the library without its projects: they stay where they are, still in the list', async () => {+ const a = await createProject('Stays');+ const done = await moveLibrary(join(scratch, 'Other'), { move: false, choose: (f) => chooseFolder('projectsFolder', f) });+ assert.deepEqual(done, { moved: 0, failed: [] });+ assert.equal((await listProjects()).find((p) => p.id === a.id)?.path, a.path);+ assert.equal((await listProjects()).find((p) => p.id === a.id)?.missing, false);+});++test('a Studio with a home of its own shares the library the person chose, kept in the shared home', async () => {+ process.env.OPENFILM_SHARED_HOME = join(scratch, 'machine');+ const chosen = join(scratch, 'Chosen');+ mkdirSync(process.env.OPENFILM_SHARED_HOME, { recursive: true });+ writeFileSync(join(process.env.OPENFILM_SHARED_HOME, 'prefs.json'), JSON.stringify({ proxies: { on: false }, projectsFolder: chosen }));+ assert.ok((await createProject('Shared')).path.startsWith(realpathSync(chosen)));+ await moveLibrary(null, { move: false, choose: (f) => chooseFolder('projectsFolder', f) });+ const machine = JSON.parse(readFileSync(join(process.env.OPENFILM_SHARED_HOME, 'prefs.json'), 'utf8'));+ assert.deepEqual(machine, { proxies: { on: false }, projectsFolder: null }, 'only the folder changed, in the shared home');+ assert.equal(existsSync(join(process.env.OPENFILM_HOME, 'prefs.json')), false, 'nothing in its own');+});++test('a listed project moved into the library outside Studio is the same project at its new folder, listed once', async () => {+ const p = await openProject(join(scratch, 'elsewhere', 'Trip'));+ mkdirSync(join(scratch, 'library'), { recursive: true });+ renameSync(p.path, join(scratch, 'library', 'Trip'));+ const listed = (await listProjects()).filter((x) => x.id === p.id);+ assert.equal(listed.length, 1);+ assert.equal(listed[0].path, join(realpathSync(scratch), 'library', 'Trip'));+ assert.equal(listed[0].missing, false);+});diff --git a/packages/openfilm/studio/server/proxies.mjs b/packages/openfilm/studio/server/proxies.mjsindex 428b18d..87d65f3 100644--- a/packages/openfilm/studio/server/proxies.mjs+++ b/packages/openfilm/studio/server/proxies.mjs@@ -1,10 +1,11 @@// @ts-check/**- * Proxies: light copies of heavy footage for the preview to play, as editors make them (CapCut's, Premiere's). Footage+ * Proxies: light copies of heavy footage for the preview to play. Footage* past 1080p, or in a form slow to decode (ProRes, HEVC, 10-bit…), from a NAS most of all, stutters when played and* scrubbed; its proxy is an H.264 copy `height` px on its short side, its picture only, with the same frames at the* same times (passthrough: none added or dropped) and a key frame every half second, so a scrub lands at once. Made in- * the background, one at a time, kept in the project's cache.+ * the background, one at a time, kept in the project's cache: decoded and written on the graphics chip when it can+ * (src/encoders.mjs), so the processor stays free; by x264 otherwise.** Only the preview plays them (pages.mjs swaps a file for its proxy): the film's sound is mixed from the original, and* an export or a render reads the originals. Nothing in film.html changes.@@ -14,6 +15,7 @@ import { createHash } from 'node:crypto';import { existsSync, mkdirSync, renameSync, rmSync, statSync } from 'node:fs';import { join } from 'node:path';import { clipKind } from '../../src/film-doc.mjs';+import { colorTagsOf, encoders, h264ColorTags, hardwareEncoder, hardwareOptions, onTheChip } from '../../src/encoders.mjs';import { probe } from './derived.mjs';import { readable } from './files.mjs';import { TOOL_DIR } from './projects.mjs';@@ -110,7 +112,7 @@ export async function ensureProxies(root, rels, height) {const seconds = Number(facts.duration) > 0 ? Number(facts.duration) : 0;/** @type {ProxyState & { make?: () => Promise<void> }} */const fresh = { state: 'waiting' };- fresh.make = () => make(abs, out, size, fps, seconds, (ratio) => { fresh.ratio = ratio; });+ fresh.make = () => proxy(abs, out, size, fps, seconds, (ratio) => { fresh.ratio = ratio; });jobs.set(out, fresh);job = fresh;}@@ -121,19 +123,32 @@ export async function ensureProxies(root, rels, height) {}/**- * Make one proxy: through a hidden name, renamed once whole. ffmpeg turns a turned video upright (as it is shown),- * which is the size asked for.+ * Make one proxy, decoded and written on the graphics chip when it can, else (or when it fails) by x264.* @param {string} abs @param {string} out @param {{ w: number, h: number }} size @param {number} fps @param {number} seconds* @param {(ratio: number) => void} progress*/-function make(abs, out, size, fps, seconds, progress) {+async function proxy(abs, out, size, fps, seconds, progress) {+ const chip = await hardwareEncoder('h264', await encoders());+ await onTheChip(chip, (encoder, decoding) => make(abs, out, size, fps, seconds, progress, encoder, decoding));+}++/**+ * Make one proxy: through a hidden name, renamed once whole. ffmpeg turns a turned video upright (as it is shown),+ * which is the size asked for. `encoder`: the graphics chip's (about x264's quality at crf 23), with the source's+ * color tags, which it keeps only when told them; null for x264. `decoding`: the input options that decode on the chip.+ * @param {string} abs @param {string} out @param {{ w: number, h: number }} size @param {number} fps @param {number} seconds+ * @param {(ratio: number) => void} progress @param {string | null} encoder @param {string[]} decoding+ */+async function make(abs, out, size, fps, seconds, progress, encoder, decoding) {mkdirSync(join(out, '..'), { recursive: true });const part = `${out}.part.mp4`;- const gop = String(Math.max(1, Math.round(fps * GOP_S)));+ const gop = Math.max(1, Math.round(fps * GOP_S));+ const codec = encoder+ ? ['-pix_fmt', 'nv12', ...hardwareOptions(encoder, Math.max(2e6, size.w * size.h * fps * 0.1), { gop }), ...h264ColorTags(await colorTagsOf(abs))]+ : ['-c:v', 'libx264', '-preset', 'veryfast', '-crf', '23', '-g', String(gop), '-keyint_min', String(gop), '-pix_fmt', 'yuv420p'];return new Promise((done, fail) => {- const proc = spawn('ffmpeg', ['-hide_banner', '-nostdin', '-loglevel', 'error', '-y', '-i', abs,- '-map', '0:v:0', '-an', '-sn', '-dn', '-fps_mode', 'passthrough', '-vf', `scale=${size.w}:${size.h}`,- '-c:v', 'libx264', '-preset', 'veryfast', '-crf', '23', '-g', gop, '-keyint_min', gop, '-pix_fmt', 'yuv420p',+ const proc = spawn('ffmpeg', ['-hide_banner', '-nostdin', '-loglevel', 'error', '-y', ...decoding, '-i', abs,+ '-map', '0:v:0', '-an', '-sn', '-dn', '-fps_mode', 'passthrough', '-vf', `scale=${size.w}:${size.h}`, ...codec,'-movflags', '+faststart', '-progress', 'pipe:1', '-nostats', part], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });let err = '';proc.stderr.on('data', (d) => { err += d; });diff --git a/packages/openfilm/studio/server/server.mjs b/packages/openfilm/studio/server/server.mjsindex 9ceb338..5c0e054 100644--- a/packages/openfilm/studio/server/server.mjs+++ b/packages/openfilm/studio/server/server.mjs@@ -30,7 +30,7 @@ import { ownHost, startPages } from './pages.mjs';import { HttpError, cookie, json, readJson } from './http.mjs';import { acceptWebSocket } from './websocket.mjs';import {- ProjectError, createFolder, createProject, deleteFolder, deleteProject, libraryRoot, listFolders, listProjects, locateProject, markOpened,+ ProjectError, createFolder, createProject, deleteFolder, deleteProject, libraryRoot, listFolders, listProjects, locateProject, markOpened, moveLibrary,moveProjectToFolder, openProject, projectById, renameFolder, renameProject, studioHome, studioKey, TOOL_DIR,} from './projects.mjs';import { FetchError, createFetches, fetchFilm, parseRepoUrl } from './fetch-repo.mjs';@@ -39,12 +39,14 @@ import { exampleFile, exampleFolder, listExamples } from './examples.mjs';import { pickFiles, pickFolder } from './folder-picker.mjs';import { readPrefs, writePrefs } from './prefs.mjs';import { ensureProxies } from './proxies.mjs';+import { ensurePreviews, knownLate } from './preview-cache.mjs';import { npmOpenfilm, olderThanThis } from '../client.mjs';import { writeAtomic } from './atomic.mjs';import { createWatchers } from './watch.mjs';import { installedFonts } from './fonts.mjs';import { projectFonts, resolveIn } from './project-fonts.mjs';import { FILM_PAGE, PageFrameError, closePageFrames, filmPoster, pageFacts, pageFrame, warmFilmPoster } from './pageframes.mjs';+import { COVER_FRAME_W, CoverError, clearCover, readCover, readCoverBody, setCover, setCoverFromFile } from './cover.mjs';import { SavedError, bundlePoster, libraryPath, libraryRel, libraryRoot as savedLibrary, listLibrary, saveClip, saveFile, saveGroup, takeSaved } from './saved.mjs';import { FILM_FILE, clipKind, isPage } from '../../src/film-doc.mjs';import { listSkills, skillOrigins } from '../../src/skills.mjs';@@ -54,7 +56,10 @@ import { projectSettingsRoute } from './project-settings.mjs';import { markersRoute } from './markers.mjs';import { transitionPageRoutes } from './transition-pages.mjs';import { createAsks, getRoute, subtitleTranscriber, subtitleTranslator } from './get.mjs';-import { LOCATION_KEYS, locations, usableFolder } from '../../src/locations.mjs';+import { LOCATION_KEYS, chooseFolder, locations, usableFolder } from '../../src/locations.mjs';+import { doctor } from '../../src/doctor.mjs';+import { recentProblems } from '../../src/problems.mjs';+import { exportDiagnostics } from './diagnostics.mjs';/** @typedef {import('./http.mjs').Req} Req @typedef {import('./http.mjs').Res} Res */@@ -242,6 +247,25 @@ export async function startStudio({ port = 4747, key, openBrowser = systemBrowsereturn json(res, 200, { version: VERSION, latest, newer: Boolean(latest && olderThanThis(VERSION, latest)), checkedAt, checking: !process.env.OPENFILM_NO_UPDATE_CHECK && !FROM_SOURCE, source: FROM_SOURCE,...(updating ? { update: updating } : {}) });}+ /* Settings → Developer's diagnostic report: `openfilm doctor` (src/doctor.mjs), as this Studio sees the computer */+ if (parts[0] === 'doctor' && parts.length === 1 && req.method === 'GET') {+ const report = await doctor({ studio: { origin, version: VERSION, ...(stays ? { app: true } : {}) } });+ return json(res, 200, { ok: report.ok, text: report.text });+ }+ /* Settings → Developer: the problems of the last two weeks (src/problems.mjs), newest first */+ if (parts[0] === 'diagnostics' && parts[1] === 'problems' && parts.length === 2 && req.method === 'GET') {+ return json(res, 200, { problems: recentProblems().reverse() });+ }+ /* Settings → Developer's diagnostic file (diagnostics.mjs): the report the page made, and the rest, as a zip in the+ exports folder, shown in the file manager */+ if (parts[0] === 'diagnostics' && parts[1] === 'export' && parts.length === 2 && req.method === 'POST') {+ const { report, conversations } = /** @type {{ report?: unknown, conversations?: unknown }} */ ((await readJson(req).catch(() => null)) ?? {});+ const text = typeof report === 'string' && report.trim() ? report+ : (await doctor({ studio: { origin, version: VERSION, ...(stays ? { app: true } : {}) } })).text;+ const made = await exportDiagnostics({ report: text, conversations: conversations === true });+ reveal(made.path);+ return json(res, 200, made);+ }/* the top bar's Update (Studio run with npm, not the app's nor a checkout): the newest openfilm run in thebackground as `openfilm update` (client.mjs updateOpenfilm), which starts Studio again on it; the pages come backon the new version and reload. Not while an export runs or media is made. `/api/version` says how it goes */@@ -350,6 +374,16 @@ export async function startStudio({ port = 4747, key, openBrowser = systemBrowse/* where new projects go (src/locations.mjs): the folder, its default, and its disk's free space; a POST opens itin the system's file manager */if (parts[0] === 'locations' && parts.length === 1 && req.method === 'GET') return json(res, 200, locations());+ /* the library moved (projects.mjs moveLibrary): { path } (null: the default), and with `move` its projects go too */+ if (parts[0] === 'locations' && parts[1] === 'projects' && parts.length === 2 && req.method === 'PUT') {+ const { path: asked, move } = /** @type {{ path?: unknown, move?: unknown }} */ (await readJson(req) ?? {});+ let to = null;+ if (asked != null) {+ try { to = usableFolder(asked); } catch (e) { throw new HttpError(400, /** @type {Error} */ (e).message); }+ }+ const done = await moveLibrary(to, { move: move === true, choose: (folder) => chooseFolder('projectsFolder', folder) });+ return json(res, 200, { ...done, locations: locations() });+ }if (parts[0] === 'locations' && parts[1] === 'projects' && parts.length === 2 && req.method === 'POST') {const folder = locations()[parts[1]].path;mkdirSync(folder, { recursive: true });@@ -483,6 +517,8 @@ export async function startStudio({ port = 4747, key, openBrowser = systemBrowseconst renamed = await renameProject(project.id, String(name ?? ''));/* its address stays: the preview open on it keeps loading from the folder by its new name */pages.folderUrl(renamed);+ /* the pages showing it (renamed from another tab, or the projects list) take the new name */+ watchers.emit(project.path, { type: 'project', project: renamed });return json(res, 200, { project: renamed });}/* the project is deleted: its folder goes to the Trash (pages showing it go back to the list) */@@ -629,6 +665,19 @@ export async function startStudio({ port = 4747, key, openBrowser = systemBrowseconst videos = (await listFiles(project.path)).files.filter((f) => f.kind === 'video').map((f) => f.path);return json(res, 200, { on: true, height: proxies.height, states: await ensureProxies(project.path, videos, proxies.height) });}+ /* renders of the stretches the preview played late (preview-cache.mjs), asked for when not made yet: each one's+ name and state, at the proxies' size */+ if (rest === 'preview-cache' && (req.method === 'POST' || req.method === 'GET')) {+ /* GET: the stretches known to play late (from an earlier session) and theirs */+ const { ranges, fps } = /** @type {{ ranges?: unknown, fps?: unknown }} */ (req.method === 'GET'+ ? { ranges: knownLate(project.path), fps: url.searchParams.get('fps') }+ : await readJson(req));+ const rate = Number(fps);+ const list = Array.isArray(ranges) ? ranges.filter((r) => Array.isArray(r) && r.length === 2 && r.every(Number.isFinite) && r[1] > r[0] && r[0] >= 0).slice(0, 50) : [];+ if (!(rate > 0 && rate <= 240)) throw new HttpError(400, 'fps: a frame rate');+ const { proxies } = readPrefs();+ return json(res, 200, { late: list, ranges: list.length ? ensurePreviews(project.path, /** @type {[number, number][]} */ (list), rate, proxies.height) : [] });+ }/* what a link leads to copied into the project in its place (files.mjs collect) */if (rest === 'files/collect' && req.method === 'POST') {const { path: rel } = /** @type {{ path?: unknown }} */ (await readJson(req));@@ -768,8 +817,40 @@ export async function startStudio({ port = 4747, key, openBrowser = systemBrowseelse openFile(file);return json(res, 200, {});}- /* the film's middle frame: the project's card in the projects list */+ /* the project's own cover (cover.mjs): PUT a picture's bytes; POST `{ path }`, a picture of the project, or `{ ms }`,+ the film at that moment; DELETE, none of its own (the film's poster again). Answers when it was set (null: none) */+ if (rest === 'cover') {+ const set = (/** @type {{ at: number } | null} */ cover) => json(res, 200, { cover: cover?.at ?? null });+ try {+ if (req.method === 'PUT') return set(await setCover(project.path, await readCoverBody(req)));+ if (req.method === 'POST') {+ const { path: rel, ms } = /** @type {{ path?: unknown, ms?: unknown }} */ (await readJson(req));+ if (typeof rel === 'string' && rel) return set(await setCoverFromFile(project.path, readable(project.path, rel)));+ if (typeof ms === 'number' && Number.isFinite(ms) && ms >= 0) {+ const jpeg = await pageFrame(project.path, pages.folderUrl(project), FILM_PAGE, ms, COVER_FRAME_W).catch((e) => {+ throw new HttpError(e instanceof PageFrameError ? 404 : 422, String(e?.message ?? e));+ });+ return set(await setCover(project.path, jpeg));+ }+ throw new HttpError(400, 'a picture of the project (path) or a moment of the film (ms)');+ }+ if (req.method === 'DELETE') {+ await clearCover(project.path);+ return set(null);+ }+ } catch (e) {+ if (e instanceof CoverError) throw new HttpError(e.status, e.message);+ throw e;+ }+ }+ /* the project's card in the projects list: its own cover, else the film's middle frame */if (rest === 'poster' && req.method === 'GET') {+ const cover = await readCover(project.path);+ if (cover) {+ const picture = await readFile(cover.path);+ res.writeHead(200, { 'content-type': cover.type, 'cache-control': 'private, max-age=60', 'content-length': picture.length });+ return res.end(picture);+ }/* a film with nothing in it yet has no picture to show (its card shows its own face, not a black frame) */const { doc } = await readProjectFilm(project.path);if (!doc?.tracks.some((t) => t.clips.length)) throw new HttpError(404, 'the film is empty');diff --git a/packages/openfilm/studio/server/server.test.mjs b/packages/openfilm/studio/server/server.test.mjsindex 2964d32..417f4ad 100644--- a/packages/openfilm/studio/server/server.test.mjs+++ b/packages/openfilm/studio/server/server.test.mjs@@ -184,10 +184,13 @@ test('a film whose clips have no ids comes back with each named after its file,assert.deepEqual(film.value.tracks[0].clips.map((c) => c.id), ['title', 'title-2']);});-test('rename renames the folder; delete moves it to the Trash and off the list', async () => {+test('rename renames the folder and tells the pages showing it; delete moves it to the Trash and off the list', async () => {const { project } = await (await api('/api/projects', { method: 'POST', body: { name: 'Draft' } })).json();+ const events = collect(`/api/projects/${project.id}/events`, (e) => e.some((x) => x.type === 'project'));+ await new Promise((r) => setTimeout(r, 300));const renamed = await (await api(`/api/projects/${project.id}`, { method: 'PATCH', body: { name: 'Final' } })).json();assert.equal(renamed.project.name, 'Final');+ assert.equal((await events).find((e) => e.type === 'project').project.name, 'Final');assert.ok(existsSync(renamed.project.path));assert.equal((await api(`/api/projects/${project.id}`, { method: 'DELETE' })).status, 200);assert.equal((await api(`/api/projects/${project.id}`)).status, 404);@@ -714,3 +717,23 @@ test('a frame from a page larger than the cap closes its stream; small ones areawait closed;assert.ok(Buffer.concat(got).includes(Buffer.from([0x88, 2, 0x03, 0xf1])), 'a close saying the message was too big');});++test('Settings moves the library: how many projects it holds, then the folder and, when asked, its projects', async () => {+ const before = await (await api('/api/locations')).json();+ const { project } = await (await api('/api/projects', { method: 'POST', body: { name: 'To move' } })).json();+ assert.equal((await (await api('/api/locations')).json()).projects.count, before.projects.count + 1);+ const to = join(scratch, 'Moved library');+ const res = await api('/api/locations/projects', { method: 'PUT', body: { path: to, move: true } });+ const done = await res.json();+ assert.equal(res.status, 200);+ assert.equal(done.failed.length, 0);+ assert.equal(done.locations.projects.path, to);+ assert.equal(done.locations.projects.chosen, true);+ assert.ok(existsSync(join(to, 'To move', 'film.html')));+ const listed = (await (await api('/api/projects')).json()).projects.find((p) => p.id === project.id);+ assert.equal(listed.path, join(realpathSync(to), 'To move'), 'the same project, at its new folder');+ assert.equal((await api('/api/locations/projects', { method: 'PUT', body: { path: 'relative' } })).status, 400);+ const back = await (await api('/api/locations/projects', { method: 'PUT', body: { path: null, move: true } })).json();+ assert.equal(back.locations.projects.chosen, false);+ assert.ok(existsSync(join(back.locations.projects.path, 'To move', 'film.html')), 'and back to the default');+});diff --git a/packages/openfilm/studio/server/stage.js b/packages/openfilm/studio/server/stage.jsindex 25d8f54..9c4f541 100644--- a/packages/openfilm/studio/server/stage.js+++ b/packages/openfilm/studio/server/stage.js@@ -580,7 +580,7 @@return hits.sort((a, b) => a.area - b.area || b.order - a.order);};/**- * A box that fills its whole page is the page's backdrop, as a frame's fill in Figma: a click there takes the clip+ * A box that fills its whole page is the page's backdrop: a click there takes the clip* (moving the picture), not the box (which would only move what is inside the page). It is selected in Layers, or* with Alt, and once in hand a click on it keeps it.*/@@ -1060,7 +1060,7 @@return pinned.some((e) => e.style.position) && holds(pinned) ? pinned : null;};- /* ── a layer restyled: the others stay where they are, as in Figma, where one layer's look never moves another ── */+ /* ── a layer restyled: the others stay where they are; one layer's look never moves another ── *//** The style a hold sets (holdFor): kept apart from what the person set, so a new hold replaces the one before. */const HOLD_KEYS = ['marginTop', 'marginRight', 'marginBottom', 'marginLeft', 'width'];const SIDES = ['Top', 'Right', 'Bottom', 'Left'];@@ -1070,7 +1070,7 @@* hold's style on it (`show`, style keys to null take a kept one away). `unheld`: a hold kept before, taken away* first (it was for the change before).*- * The layer takes its new size (its box grows with a larger font or more words, as a text box in Figma does); margins+ * The layer takes its new size (its box grows with a larger font or more words); margins* give back to the page's flow the room it gained or lost, on the side the flow lays it out from, so what is beside* it, under it or lined up with its baseline stays put. Words in a block as wide as what holds it get a box that hugs* them, and stay where they were set in it (centered, at its end).@@ -1423,7 +1423,7 @@/** Stop showing what was not kept on a clip (a refused edit, a cancelled drag). */release({ clip }) { release(clip); return true; },/**- * Bring a layer to the front of what it overlaps, or send it to the back of it, as Photoshop does — whatever part+ * Bring a layer to the front of what it overlaps, or send it to the back of it — whatever part* of the page the other layer is in. A z-index orders only siblings, so for each layer it overlaps the order is* set where the two meet: on the two branches under their nearest common ancestor, the branch it is in is given a* z-index past the other's (with position: relative where it has none, which moves nothing). Sent back, a commondiff --git a/packages/openfilm/studio/server/watch.mjs b/packages/openfilm/studio/server/watch.mjsindex 11e7d5d..0f29034 100644--- a/packages/openfilm/studio/server/watch.mjs+++ b/packages/openfilm/studio/server/watch.mjs@@ -23,8 +23,9 @@ const WRITING = /(^|[/\\])([^/\\]+\.[0-9a-f-]{8,}\.tmp|\.\d+\.\d+\.importing)$/;* `ask` / `asked`: a question about spending for the person, and that it was answered; `notice`: something the person* is told, such as a provider with no balance left (get.mjs).* `history-progress`: how far a version history action is (history.mjs), `op` the action ('commit', 'checkout'…).+ * `project`: the project renamed, as it is now.* @typedef {{ type: 'film', rev: string } | { type: 'files', paths?: string[] } | { type: 'history' } | { type: 'export', job: object }- * | { type: 'history-progress', op: string, phase: string, done: number, total: number }+ * | { type: 'history-progress', op: string, phase: string, done: number, total: number } | { type: 'project', project: object }* | { type: 'ask', ask: object } | { type: 'asked', id: string } | { type: 'notice', notice: object }} FolderEvent*/diff --git a/packages/openfilm/studio/ui/src/api.ts b/packages/openfilm/studio/ui/src/api.tsindex 0df6c24..00e7ab6 100644--- a/packages/openfilm/studio/ui/src/api.ts+++ b/packages/openfilm/studio/ui/src/api.ts@@ -11,7 +11,8 @@ export interface StudioVersion { version: string; latest: string | null; newer:/** the update Studio runs from the top bar (lib/web-update), or one that failed */update?: { status: 'updating' | 'failed'; version: string; error?: string } }-export type Project = { id: string; path: string; name: string; openedAt: number; missing: boolean; working?: boolean };+/** `cover`: when the person set a cover of its own (studio/server/cover.mjs), absent when it has none. */+export type Project = { id: string; path: string; name: string; openedAt: number; missing: boolean; working?: boolean; cover?: number };export type Clip = { src: string; id: string; at?: number; time?: [number] | [number, number];box?: { x: number; y: number; w?: number; h?: number; r?: number }; volume?: number; speed?: number; overrides?: unknown[];/** a page that sets no size of its own: the px it is laid out at (the stage's without it) */@@ -78,21 +79,45 @@ const p = (id: string) => `projects/${encodeURIComponent(id)}`;/** Studio's own preferences, the same for every project (studio/server/prefs.mjs). */export interface StudioPrefs { proxies: { on: boolean; height: 540 | 720 | 1080 }; seenVersion: string | null; projectsFolder: string | null }-/** Where new projects and exports go (src/locations.mjs): the folder, its default, whether the person chose it, the free space on its disk. */-export interface StudioLocation { path: string; default: string; chosen: boolean; free: number | null }+/** Where the projects library is (src/locations.mjs): the folder, its default, whether the person chose it, the free space on its disk, how many projects are in it. */+export interface StudioLocation { path: string; default: string; chosen: boolean; free: number | null; count: number }export interface StudioLocations { projects: StudioLocation }/** Said on the window when they change, for what plays by them (the preview's proxies). */export const PREFS_EVENT = 'openfilm:prefs';+/** Said on the window when the library moved, for the Projects list. */+export const LIBRARY_EVENT = 'openfilm:library';++/** A problem as Studio keeps it (src/problems.mjs): when, what it was about, what it said. */+export interface StudioProblem {+ t: string;+ area: string;+ what: string;+ agent?: string;+ step?: string;+}export const api = {/** this Studio's version and the latest openfilm on npm; `check`: ask npm now */version: (check = false) => call<StudioVersion>(`version${check ? '?check=1' : ''}`),/** the newest openfilm, run in the background (`openfilm update`): Studio starts again on it; refused (ApiError, `body.code`) while busy */update: () => call<{ update: NonNullable<StudioVersion['update']> }>('update', { method: 'POST', json: {} }),+ /** `openfilm doctor`, run by this Studio: the report to paste into an issue (src/doctor.mjs) */+ doctor: () => call<{ ok: boolean; text: string }>('doctor'),+ /** what went wrong in the last two weeks, newest first (src/problems.mjs) */+ problems: () => call<{ problems: StudioProblem[] }>('diagnostics/problems').then((r) => r.problems),+ /** the diagnostic file (server/diagnostics.mjs): `report` and the rest, zipped into the exports folder and shown there */+ exportDiagnostics: (report: string, conversations: boolean) => call<{ path: string; files: string[]; conversations: boolean }>('diagnostics/export', { method: 'POST', json: { report, conversations } }),projects: () => call<{ projects: Project[] }>('projects').then((r) => r.projects),prefs: () => call<StudioPrefs>('prefs'),/** where new projects and exports go, and the free space there */locations: () => call<StudioLocations>('locations'),+ /** move the library to `path` (null: the default); with `move`, its projects go too (those that could not are in `failed`) */+ moveLibrary: (path: string | null, move: boolean) => call<{ moved: number; failed: { name: string; error: string }[]; locations: StudioLocations }>('locations/projects', { method: 'PUT', json: { path, move } }).then((done) => {+ window.dispatchEvent(new Event(LIBRARY_EVENT));+ return done;+ }),+ /** a project's folder, shown in the system's file manager */+ revealProject: (id: string) => call<object>(`projects/${encodeURIComponent(id)}/reveal`, { method: 'POST', json: {} }),/** one of them in the system's file manager */openLocation: (which: keyof StudioLocations) => call<{ ok: true }>(`locations/${which}`, { method: 'POST', json: {} }),setPrefs: (patch: { proxies?: Partial<StudioPrefs['proxies']>; seenVersion?: string; projectsFolder?: string | null }) => call<StudioPrefs>('prefs', { method: 'PATCH', json: patch }).then((prefs) => {@@ -127,6 +152,11 @@ export const api = {),/** a video's frame (`ms` of its own time) made a still beside it; answers its path */freezeFrame: (id: string, path: string, ms: number) => call<{ path: string }>(`${p(id)}/files/still`, { method: 'POST', json: { path, ms } }).then((r) => r.path),+ /** The project's own cover for its card (studio/server/cover.mjs): a picture from this computer, a picture of the project,+ the film at `ms`, or none (null: its film's poster again). Each answers when it was set. */+ setCover: (id: string, from: { file: Blob } | { path: string } | { ms: number }) => call<{ cover: number | null }>(`${p(id)}/cover`,+ 'file' in from ? { method: 'PUT', body: from.file, headers: { 'content-type': 'application/octet-stream' } } : { method: 'POST', json: from }).then((r) => r.cover),+ clearCover: (id: string) => call<{ cover: null }>(`${p(id)}/cover`, { method: 'DELETE' }).then(() => null),answerAsk: (askId: string, allow: boolean) => call<{ answered: boolean }>(`get/asks/${encodeURIComponent(askId)}`, { method: 'POST', json: { allow } }),/** the provider's own page for its balance, opened in the person's browser */openBilling: (providerId: string) => call<Record<string, never>>(`providers/${encodeURIComponent(providerId)}/billing`, { method: 'POST' }),@@ -158,7 +188,7 @@ export type StudioNotice = { id: string; kind: 'balance'; provider: string; provexport type FolderEvent = { type: 'film'; rev: string } | { type: 'files'; paths?: string[] } | { type: 'history' } | { type: 'export'; job: ExportJob } | { type: 'open'; to: string }| { type: 'history-progress'; op: string; phase: string; done: number; total: number }- | { type: 'ask'; ask: SpendAsk } | { type: 'asked'; id: string } | { type: 'notice'; notice: StudioNotice };+ | { type: 'ask'; ask: SpendAsk } | { type: 'asked'; id: string } | { type: 'notice'; notice: StudioNotice } | { type: 'project'; project: Project };/*** Listen to a stream of events (a WebSocket: a browser's six HTTP connections to Studio stay free for the page'sdiff --git a/packages/openfilm/studio/ui/src/components/AudioMeters.tsx b/packages/openfilm/studio/ui/src/components/AudioMeters.tsxindex 8381b13..c3659ba 100644--- a/packages/openfilm/studio/ui/src/components/AudioMeters.tsx+++ b/packages/openfilm/studio/ui/src/components/AudioMeters.tsx@@ -1,5 +1,5 @@/**- * The audio meters, as Premiere's: the film's sound as it plays, left and right, peak (the light bar, with a mark that+ * The audio meters: the film's sound as it plays, left and right, peak (the light bar, with a mark that* holds the loudest of late) and RMS (the solid bar inside it), on a dBFS scale. A channel that reached 0 dBFS lights* its clip light at the top until it is clicked.*diff --git a/packages/openfilm/studio/ui/src/components/BlockWaveform.tsx b/packages/openfilm/studio/ui/src/components/BlockWaveform.tsxindex dbe1515..35afbdb 100644--- a/packages/openfilm/studio/ui/src/components/BlockWaveform.tsx+++ b/packages/openfilm/studio/ui/src/components/BlockWaveform.tsx@@ -3,7 +3,7 @@* where it is silent — and "did this cut land mid-word" can only be seen on the waveform.** Drawn from the bottom, not mirrored: sound rows are short, and a mirrored waveform leaves half the height each way.- * A skyline still reads when low (CapCut draws it this way). On a canvas, not hundreds of divs: dozens of clips with+ * A skyline still reads when low. On a canvas, not hundreds of divs: dozens of clips with* hundreds of peaks each would be tens of thousands of nodes.** Peaks come from the server: GET media?what=wave&path= → `{ duration (s), peaks }`, 40 peaks a second, 0..1;@@ -25,6 +25,45 @@ const PEAKS_PER_SECOND = 40;/** At most this many device pixels per canvas: past the browser's limit a canvas goes blank. */const MAX_CANVAS_PX = 4096;+/** A change this soon after the last drawing is drawn once the changes stop for as long (ms). */+const BURST_MS = 150;++/*+ * Drawings waiting, done a few a frame (FRAME_BUDGET_MS of them at most): a zoom of a film with hundreds of sounds redrew+ * them all in one go, a long freeze. A newer drawing of a canvas replaces its older one; the stretched old bitmap holds+ * until it is done.+ */+const FRAME_BUDGET_MS = 6;+const waiting = new Map<HTMLCanvasElement, () => void>();+let drawing = 0;+function drawSoon(el: HTMLCanvasElement, draw: () => void) {+ waiting.set(el, draw);+ if (!drawing) drawing = requestAnimationFrame(drawSome);+}+function drawSome() {+ drawing = 0;+ const start = performance.now();+ for (const [el, draw] of waiting) {+ waiting.delete(el);+ draw();+ if (performance.now() - start > FRAME_BUDGET_MS) break;+ }+ if (waiting.size) drawing = requestAnimationFrame(drawSome);+}++/* the color a waveform is drawn in, read once per color and theme: read from each canvas, each drawing laid out the+ page's styles again */+const colors = new Map<string, string>();+function colorOf(el: HTMLCanvasElement, color: string, theme: unknown): string {+ const key = `${String(theme)}\0${color}`;+ let c = colors.get(key);+ if (!c) {+ c = getComputedStyle(el).color || color;+ if (colors.size > 64) colors.clear();+ colors.set(key, c);+ }+ return c;+}/** Waveforms already fetched: the same sound is drawn again on every drag and zoom. */const CACHE = new Map<string, Wave>();@@ -100,7 +139,9 @@ export function BlockWaveform({React.useEffect(() => {let alive = true;- void loadWave(url).then((wave) => { if (alive) setLoaded({ url, wave }); });+ /* the same wave already in hand (from the cache) renders nothing: a clip drawn as it scrolls into view is not+ drawn twice */+ void loadWave(url).then((wave) => { if (alive) setLoaded((cur) => (cur.url === url && cur.wave === wave ? cur : { url, wave })); });return () => { alive = false; };}, [url]);@@ -110,11 +151,15 @@ export function BlockWaveform({const to = Math.max(from, Math.min(width, Math.ceil(visiblePx?.to ?? width)));const sliceW = to - from;+ /* when it was last drawn: a change soon after is part of a burst (a zoom, a scroll) */+ const drawnAt = React.useRef(-Infinity);React.useEffect(() => {const el = ref.current;if (!el || !wave?.peaks.length || sliceW <= 0 || height <= 0) return undefined;- /* drawn on the next frame, so a burst of zoom steps draws once (the stretched old bitmap holds meanwhile) */- const frame = requestAnimationFrame(() => {+ /* drawn soon (see drawSoon); in a burst of zoom or scroll steps, once the burst stops (the stretched old bitmap+ holds meanwhile): redrawn at every step, the waveforms were most of what a zoom cost */+ const draw = () => {+ drawnAt.current = performance.now();/* capped in device pixels, not CSS pixels: capping CSS pixels would also drop Retina's 2×, and this layer isthin enough that blur makes it useless. Full ratio while it fits, down to 1× at the cap. */const drawW = Math.min(Math.round(sliceW), MAX_CANVAS_PX);@@ -125,7 +170,7 @@ export function BlockWaveform({if (!ctx) return;ctx.scale(dpr, dpr);ctx.clearRect(0, 0, drawW, height);- ctx.fillStyle = getComputedStyle(el).color || color;+ ctx.fillStyle = colorOf(el, color, theme);/* one column per pixel: more peaks than pixels takes the maximum (sampling would miss a drum hit and drawsilence); fewer peaks than pixels interpolates (nearest-peak steps are the sampling grid, not the sound) */@@ -140,8 +185,9 @@ export function BlockWaveform({ctx.rect(x, height - h, 1, h);}ctx.fill();- });- return () => cancelAnimationFrame(frame);+ };+ const timer = window.setTimeout(() => drawSoon(el, draw), performance.now() - drawnAt.current < BURST_MS ? BURST_MS : 0);+ return () => { window.clearTimeout(timer); waiting.delete(el); };}, [wave, width, height, color, inMs, durMs, from, sliceW, theme]);if (!wave?.peaks.length || sliceW <= 0) return null;diff --git a/packages/openfilm/studio/ui/src/components/ColorPicker.tsx b/packages/openfilm/studio/ui/src/components/ColorPicker.tsxindex ef06752..baff042 100644--- a/packages/openfilm/studio/ui/src/components/ColorPicker.tsx+++ b/packages/openfilm/studio/ui/src/components/ColorPicker.tsx@@ -1,5 +1,5 @@/**- * The color picker a swatch opens, drawn like Figma's: a saturation × brightness square, a hue strip,+ * The color picker a swatch opens: a saturation × brightness square, a hue strip,* an opacity strip, the hex and the opacity as numbers, and the colors used lately.** Dragging previews (the picture follows the pointer, nothing is written); letting go commits once.diff --git a/packages/openfilm/studio/ui/src/components/ConfirmDialog.tsx b/packages/openfilm/studio/ui/src/components/ConfirmDialog.tsxindex 9414356..434ce16 100644--- a/packages/openfilm/studio/ui/src/components/ConfirmDialog.tsx+++ b/packages/openfilm/studio/ui/src/components/ConfirmDialog.tsx@@ -11,6 +11,8 @@ export function ConfirmDialog({confirmLabel,cancelLabel,danger = false,+ altLabel,+ onAlt,onConfirm,onCancel,}: {@@ -20,6 +22,9 @@ export function ConfirmDialog({confirmLabel?: string;cancelLabel?: string;danger?: boolean;+ /** a second answer besides confirming, between Cancel and the confirm button */+ altLabel?: string;+ onAlt?: () => void;onConfirm: () => void;onCancel: () => void;}) {@@ -43,8 +48,8 @@ export function ConfirmDialog({if (e.key === 'Enter') {const target = e.target as Node | null;if (target && dialogRef.current?.contains(target)) {- // Enter on the Cancel button presses Cancel- if (target === cancelButtonRef.current) return;+ // Enter on another button (Cancel, the second answer) presses that button+ if (target instanceof HTMLButtonElement && target !== confirmButtonRef.current) return;e.preventDefault();onConfirm();}@@ -78,6 +83,7 @@ export function ConfirmDialog({<CardButton ref={cancelButtonRef} weight="quiet" onClick={onCancel}>{cancelLabel ?? t('confirm.cancel')}</CardButton>+ {altLabel && onAlt ? <CardButton onClick={onAlt}>{altLabel}</CardButton> : null}<CardButton ref={confirmButtonRef} weight={danger ? 'danger' : 'primary'} onClick={onConfirm}>{confirmLabel ?? t('confirm.ok')}</CardButton>diff --git a/packages/openfilm/studio/ui/src/components/FilmInspector.tsx b/packages/openfilm/studio/ui/src/components/FilmInspector.tsxindex 0e853b0..6d2d00c 100644--- a/packages/openfilm/studio/ui/src/components/FilmInspector.tsx+++ b/packages/openfilm/studio/ui/src/components/FilmInspector.tsx@@ -1,5 +1,5 @@/**- * The inspector: what is selected right now, read like Figma's properties panel and adjusted as in an editor.+ * The inspector: what is selected right now, read as a properties panel and adjusted as in an editor.** One property model wherever a thing is: a whole clip on the timeline (a video, a still, a page), a layer inside a* page on the picture, several of either, and the film itself when nothing is selected. The same sections in the@@ -808,7 +808,7 @@ function LayerPanel({/* the anchor below is a hook: it has to run before the early return */const geoAnchor = React.useRef<StageGeometry | null>(null);React.useEffect(() => { geoAnchor.current = null; }, [element.loc, element.override]);- /* aspect lock: on by default for text (squashed letters are never wanted), off otherwise (as in Figma) */+ /* aspect lock: on by default for text (squashed letters are never wanted), off otherwise */const [ratioLocked, setRatioLocked] = React.useState(element.kind === 'text');/* the properties a preview has painted: what a revert paints back */const previewedKeys = React.useRef(new Set<string>());@@ -853,7 +853,7 @@ function LayerPanel({});/*- * Position and size are an override. The panel shows Figma's numbers — X / Y, W / H on the stage, the angle — as+ * Position and size are an override. The panel shows X / Y, W / H on the stage and the angle as* the stage measures them (geometry); what is written is the override's offset / factors, converted back by* `unit` (the offset is in the parent's coordinates). Not measurable (not on screen) → the written offset.* With "All N copies" one override covers every copy, otherwise only the picked one.@@ -899,8 +899,8 @@ function LayerPanel({];};/**- * W / H write the override's x / y factors (both together when the aspect is locked). The top left stays put, as- * in Figma; the offset that keeps it there is added by the caller from what the stage measures.+ * W / H write the override's x / y factors (both together when the aspect is locked). The top left stays put;+ * the offset that keeps it there is added by the caller from what the stage measures.*/const sizeFor = (w: number | null, h: number | null): { s: number | [number, number] } | null => {if (!geo || !(geo.w > 0) || !(geo.h > 0)) return null;@@ -1093,7 +1093,7 @@ function LayerPanel({{...(onEditMask ? { onEditMask } : {})}/>- {/* Figma's order: appearance, fill, stroke, effects; then the picture's color adjustments */}+ {/* in this order: appearance, fill, stroke, effects; then the picture's color adjustments */}<AppearanceSection look={look} t={t} radius={kind === 'box' || kind === 'image' || textFilled} /><FillSectionlook={look}@@ -1202,7 +1202,7 @@ function TextSection({cancelled.current = false;typing.current = true;setRaw(e.target.value);- /* the picture follows the words (Figma's feel); the write still waits for blur / Enter */+ /* the picture follows the words as they are typed; the write still waits for blur / Enter */onPreviewText?.(text.loc, e.target.value);}}onBlur={save}@@ -1240,7 +1240,7 @@ function GroupPanel({ geometry, group, layers, onEditLayers, onPlace, t }: {group: NonNullable<StageGeometry['group']>;layers?: readonly StageElement[];onEditLayers?: (list: LayerEdit[]) => Promise<string | null>;- /** Their bounds typed: moved (x, y) or scaled in proportion (w, h), as Figma's fields do a selection. */+ /** Their bounds typed: moved (x, y) or scaled in proportion (w, h). */onPlace?: (to: { x?: number; y?: number; w?: number; h?: number }) => void;t: T;}) {@@ -1948,7 +1948,7 @@ function MultiClipPanel({const before = compactBox(p.value, p.own);return JSON.stringify(next) === JSON.stringify(before) ? [] : [{ loc: p.loc, prop: 'box', value: next }];});- /* their bounds, as Figma shows a selection's: typed, the X / Y move them all and the W / H scale them all, in+ /* their bounds: typed, the X / Y move them all and the W / H scale them all, inproportion, about the bounds' top left */const bounds = allPlaced?.length ? (() => {const x0 = Math.min(...allPlaced.map((p) => p.x)), y0 = Math.min(...allPlaced.map((p) => p.y));@@ -2120,7 +2120,7 @@ function TransitionPanel({ t, pick }: { t: T; pick: TransitionPick }) {/*** A clip's `box` (film.html only — a code-shaped clip has no such section), its picture's own size `own` known.*- * The fields are Figma's: X / Y, W / H in stage px, the angle, and the align row. W and H keep the picture's+ * The fields: X / Y, W / H in stage px, the angle, and the align row. W and H keep the picture's* proportions while locked (typing one sets the other, and the box is written with its width alone); unlocked, a* video or still gets a box of its own proportions (its CSS fits or crops the picture in it). A page always shows* whole, so its box keeps its proportions.diff --git a/packages/openfilm/studio/ui/src/components/FilmStageSelect.tsx b/packages/openfilm/studio/ui/src/components/FilmStageSelect.tsxindex 8ae443c..177ea27 100644--- a/packages/openfilm/studio/ui/src/components/FilmStageSelect.tsx+++ b/packages/openfilm/studio/ui/src/components/FilmStageSelect.tsx@@ -111,12 +111,12 @@ type PressEvent = Pick<PointerEvent, 'button' | 'timeStamp' | 'pointerId' | 'tar/** Controls in the viewer's picture area: a press on one is theirs. */const CONTROLS = 'button, a, input, textarea, select, [role="button"], [role="slider"], [role="menu"], [contenteditable="true"]';const regionKeyHeld = (e: { metaKey: boolean; ctrlKey: boolean }) => (MAC ? e.metaKey : e.ctrlKey);-/** ⌘A (Ctrl+A elsewhere): every layer on the picture, as Figma selects all. */+/** ⌘A (Ctrl+A elsewhere): every layer on the picture selected. */const isSelectAll = (e: KeyLike) => isSelectAllKey(e, MAC);/** Arrow keys write what they moved this long after the last one (held down they come thirty a second). */const NUDGE_WRITE_MS = 350;const NO_CROP: Crop = [0, 0, 0, 0];-/** Figma's measuring red: distances held apart from the selection's blue. */+/** The measuring red: distances held apart from the selection's blue. */const MEASURE_RED = '#f24822';/** A layer as the film's stage describes it (studio/server/stage.js `describe`); boxes in stage px. */@@ -183,7 +183,7 @@ export interface FilmStageControl {previewStyle(element: StageElement, patch: StageElementStyle | Record<string, string | number | null>): void;/*** What a layer needs besides `style` so that no other layer moves when it is kept (its place in the page held, as- * Figma keeps a restyled layer from moving the others): style to write with it, {} when nothing else moves.+ * a restyled layer never moves the others): style to write with it, {} when nothing else moves.*/holdStyle(element: StageElement, style: Record<string, string | number | null>, text?: string): Promise<Record<string, string | null>>;/** Show a layer's words before they are kept. */@@ -214,7 +214,7 @@ export interface FilmStageControl {flushPending(): void;/*** Several layers in hand: their bounds put at `x` / `y` (all moved alike), or made `w` / `h` wide (all scaled alike,- * in proportion, about the bounds' top left), as Figma's fields move and scale a selection. Stage px.+ * in proportion, about the bounds' top left), as the inspector's fields move and scale a selection. Stage px.*/placeLayers(to: { x?: number; y?: number; w?: number; h?: number }): void;}@@ -564,7 +564,7 @@ function FilmStageSelectImpl({};/*** The clips a marquee `area` goes around (stage px), by the part of each on the canvas (a part past its edge cannot- * be boxed), as Figma takes the frames a box goes around.+ * be boxed): a clip is taken when the box goes around it.*/const clipsInside = (list: readonly StageClipBox[], area: Rect): { id: string; loc: string }[] => {const onCanvas = (r: Rect): Rect => {@@ -661,7 +661,7 @@ function FilmStageSelectImpl({/* ── several layers moved together ── */type MultiDragItem = MultiItem & { base: LayerGeometry; scale: number; now: LayerGeometry };const multiDrag = React.useRef<{ x: number; y: number; moved: boolean; rect0: ClientBox; items: MultiDragItem[] } | null>(null);- /* several layers scaled or turned by their box's handles (Figma's): each one's center at the press (stage px) */+ /* several layers scaled or turned by their box's handles: each one's center at the press (stage px) */const layersPull = React.useRef<(GroupPull & { x: number; y: number; moved: boolean; box0: ClientBox; items: MultiDragItem[]; centers: { x: number; y: number }[] }) | null>(null);/** The box around several layers while they are turned: the box they had, turned as far. */const [layersTurn, setLayersTurn] = React.useState<{ box: ClientBox; turn: number } | null>(null);@@ -671,7 +671,7 @@ function FilmStageSelectImpl({/* scaling: the corner or edge pulled ('n', 'se'…) and where it was (stage px); turning: the pointer's first angle */handle: string | null; from: { x: number; y: number }; a0: number; box0: ClientBox;}) | null>(null);- /** The frame around several clips while they are turned: the frame they had, turned as far (Figma's). */+ /** The frame around several clips while they are turned: the frame they had, turned as far. */const [groupTurn, setGroupTurn] = React.useState<{ box: ClientBox; turn: number } | null>(null);/** Where the clips being dragged are drawn now (their outlines follow the hand; film.html is written at the release). */const [clipsMoved, setClipsMoved] = React.useState<readonly LinkedMark[] | null>(null);@@ -931,7 +931,7 @@ function FilmStageSelectImpl({let guides: MgGuide[] = [];let center: { x: number; y: number } | undefined;if (d.kind === 'move') {- /* Shift keeps one axis, as in Figma */+ /* Shift keeps one axis */if (mods.shift) {if (Math.abs(dx) >= Math.abs(dy)) dy = 0;else dx = 0;@@ -1137,7 +1137,7 @@ function FilmStageSelectImpl({if (!nudgeClip(e)) nudgeLayer(e);return;}- /* the shortcuts are the menu's items (Figma's): ⇧⌘H hide, ⇧⌘L lock, ] / [ to the front / back; grayed ones+ /* the shortcuts are the menu's items: ⇧⌘H hide, ⇧⌘L lock, ] / [ to the front / back; grayed onesdo nothing. A whole clip's delete / copy / paste are the timeline's keys. */const mod = e.metaKey || e.ctrlKey;const k = e.key.toLowerCase();@@ -1178,7 +1178,7 @@ function FilmStageSelectImpl({}if (e.key !== 'Escape') return;/* a number being typed in the inspector: the field gives it up itself (its own Esc runs after this one, which- listens first), then it is blurred; the selection stays (as Figma does). Blurred here at once, the field+ listens first), then it is blurred; the selection stays. Blurred here at once, the fieldwould take the blur for a commit and keep what was typed. */const focus = document.activeElement as HTMLElement | null;if (focus?.closest('[data-film-inspector]') && /^(INPUT|TEXTAREA|SELECT)$/.test(focus.tagName)) {@@ -1434,7 +1434,7 @@ function FilmStageSelectImpl({? (cur && cur.handle === found.handle && cur.clip === found.clip && sameClientRect(cur.rect, found.rect) ? cur : found): (cur ? null : cur)));}), [ask]);- /* while a marquee is drawn: what letting go would select, outlined as it goes (Figma) — the clips it goes around,+ /* while a marquee is drawn: what letting go would select, outlined as it goes — the clips it goes around,else the layers wholly inside it. The clips are asked once, at the press */const marqueeClips = React.useRef<Promise<StageClipBox[] | null> | null>(null);const [marqueeHits, setMarqueeHits] = React.useState<readonly StageOutline[]>([]);@@ -1514,7 +1514,7 @@ function FilmStageSelectImpl({next = rotateTransform(g.origin, g.box, g.start, stagePt, shift ? 15 : 0);} else if (g.kind === 'scale' && g.handle) {const f0 = shown;- /* as Figma: a corner keeps the proportions and an edge stretches its side, Shift the other way round; a page's+ /* a corner keeps the proportions and an edge stretches its side, Shift the other way round; a page'sbox is never stretched. Alt: about the center, unsnapped (it moves both sides) */const proportional = !g.stretchable || (g.handle.hx && g.handle.hy ? !shift : shift);const r = resizedFrame(f0, g.handle, { x: stagePt.x - g.start.x, y: stagePt.y - g.start.y }, { proportional, fromCenter: alt },@@ -1978,7 +1978,7 @@ function FilmStageSelectImpl({const first = doubleClickAim(pressesRef.current, e.timeStamp);const at = first ? { x: first.x, y: first.y } : { x: p.x / vs, y: p.y / vs };const inside = held && insideBox(held.rect, at.x, at.y);- /* cropping, a double-click keeps the crop (as in Figma); on the video or still in hand, it starts one */+ /* cropping, a double-click keeps the crop; on the video or still in hand, it starts one */if (cropRef.current) { finishCrop(true); return; }const outer = held?.element;const t = liveTRef.current ?? outer?.transform;@@ -2247,7 +2247,7 @@ function FilmStageSelectImpl({const p = local(e);if (gestureRef.current.pendingClick) {/* a click on the clip in hand (a drag moves it): the layer of a page under the pointer is taken in hand, as- a click in a selected frame selects what is in it (Figma); else the top clip there */+ a click in a selected frame selects what is in it; else the top clip there */const g = gestureRef.current;gestureRef.current = null;liveTRef.current = null;@@ -2295,8 +2295,8 @@ function FilmStageSelectImpl({/* the threshold is in stage px: the same gesture is a click in a small window and in full screen alike */if (box.width / vs >= MARQUEE_MIN_PX && box.height / vs >= MARQUEE_MIN_PX) {const area = { x: box.left / vs, y: box.top / vs, w: box.width / vs, h: box.height / vs };- /* clips wholly inside (a page, a video, a still, by the part on the canvas) are selected whole, as Figma takes- a frame the box goes around; Shift adds them to the clips selected */+ /* clips wholly inside (a page, a video, a still, by the part on the canvas) are selected whole, each one the+ box goes around; Shift adds them to the clips selected */const clips = onSelectClips ? await (marqueeClips.current ?? ask<StageClipBox[]>('clips')) ?? [] : [];if (token !== pressSeq.current) return;const around = clipsInside(clips, area).map((c) => c.loc);@@ -2324,7 +2324,7 @@ function FilmStageSelectImpl({/* not pulled open far enough: a click. A layer of a page is selected, else the clip; on nothing, nothing is */const layer = await ask<StageLayer>('hit', { x: p.x / vs, y: p.y / vs, cycleFrom: cycle, from, detail: true });if (token !== pressSeq.current) return;- /* Shift-click adds to / takes from the selection (Figma) */+ /* Shift-click adds to / takes from the selection */if (base && layer) {const has = base.some((b) => b.handle === layer.handle);setHover(null);@@ -2357,7 +2357,7 @@ function FilmStageSelectImpl({? { left: Math.min(draft.x1, draft.x2), top: Math.min(draft.y1, draft.y2), width: Math.abs(draft.x2 - draft.x1), height: Math.abs(draft.y2 - draft.y1) }: null;const linkedShown = linkedOutlines(linkedMarks, picked?.element?.clipLoc, dragging);- /* several clips selected: one frame around them all, as Figma draws a selection (it moves with them) */+ /* several clips selected: one frame around them all (it moves with them) */const groupMarks = clipsMoved ?? (linkedShown.length > 1 ? linkedShown : null);const groupStretch = Boolean(groupMarks?.every((m) => infoOf(m.loc)?.kind === 'video'));const groupBox = groupMarks ? unionRect(groupMarks.map((m) => clientOf(frameAabb(visibleFrame(m.t, m.box, infoOf(m.loc)?.crop ?? NO_CROP))))) : null;@@ -2489,7 +2489,7 @@ function FilmStageSelectImpl({const barLabel = barKind === 'layers' ? t('selectionBar.layers').replace('{n}', String(multi?.length ?? 0)) : undefined;/**- * A press: on the picture, or on the dark around it (a marquee starts there too, as on Figma's canvas, so what sits+ * A press: on the picture, or on the dark around it (a marquee starts there too, so what sits* at an edge can be boxed whole). The moves and the release then come to the overlay, which holds the pointer.* `outside`: in the dark, where nothing can be clicked, only a box drawn: the film plays on until the box is pulled* open (a click there only lets the selection go).@@ -2602,7 +2602,7 @@ function FilmStageSelectImpl({});return;}- /* several clips selected: a press on one of them drags them all, as Figma moves a selection (Shift: a marquee+ /* several clips selected: a press on one of them drags them all (Shift: a marqueethat adds to them instead) */const linkedNow = linkedLocs ?? [];const groupHit = target?.closest('[data-group-kind]') as HTMLElement | null;@@ -2633,7 +2633,7 @@ function FilmStageSelectImpl({return;}/* several selected: a press inside their box drags them all (Shift adds / takes away instead); its handles scale- them or turn them together, as Figma does a selection */+ them or turn them together */const many = multiRef.current;const held0 = pickedRef.current;const pullKind = groupHit?.getAttribute('data-group-kind');@@ -3201,7 +3201,7 @@ function CropOverlay({ session: s, viewScale: vs, moving, bounds, onAspect, onDo}/**- * Distances while Alt is held (Figma's): a red line across each gap with its length in stage px, dashed helpers from+ * Distances while Alt is held: a red line across each gap with its length in stage px, dashed helpers from* the other box's edge, and the other box outlined.*/function Measures({ lines, other, viewScale: vs }: { lines: readonly MeasureLine[]; other: Rect | null; viewScale: number }) {diff --git a/packages/openfilm/studio/ui/src/components/FontFamilyPicker.tsx b/packages/openfilm/studio/ui/src/components/FontFamilyPicker.tsxindex 7444045..83ef14f 100644--- a/packages/openfilm/studio/ui/src/components/FontFamilyPicker.tsx+++ b/packages/openfilm/studio/ui/src/components/FontFamilyPicker.tsx@@ -1,5 +1,5 @@/**- * Picking a font in the inspector, as in Figma.+ * Picking a font in the inspector.** The menu has "In this project" first (the families the project's pages declare with @font-face, and the ones the* page in hand names), then the recent picks, then every font installed here by script — the CJK groups first whendiff --git a/packages/openfilm/studio/ui/src/components/FramePicker.tsx b/packages/openfilm/studio/ui/src/components/FramePicker.tsxindex 7765f97..5b5416e 100644--- a/packages/openfilm/studio/ui/src/components/FramePicker.tsx+++ b/packages/openfilm/studio/ui/src/components/FramePicker.tsx@@ -1,6 +1,6 @@/*** The aspect ratio button beside the picture: the film's canvas (its stage in film.html). Picking a shape changes the- * canvas itself (`onCanvas`), as CapCut's does: the film is scaled whole into it, centered, until the agent lays it+ * canvas itself (`onCanvas`): the film is scaled whole into it, centered, until the agent lays it* out again. A delivery frame (bars or a crop around the film) is the export's. Any other size is typed in the* inspector.*/@@ -10,7 +10,7 @@ import { useT } from '@/i18n';import { customFilmFrame, filmFrameRatio, type FilmFrameId } from '@/lib/film-frame';import { Tooltip } from './Tooltip';-/** The shapes a canvas is offered in, as CapCut lists them (and 21:9): landscape, then portrait. */+/** The shapes a canvas is offered in: landscape, then portrait. */export const CANVAS_RATIOS: { group: 'wide' | 'tall'; id: FilmFrameId; phone?: true }[] = [{ group: 'wide', id: '16:9' },{ group: 'wide', id: '21:9' },diff --git a/packages/openfilm/studio/ui/src/components/LayersPanel.tsx b/packages/openfilm/studio/ui/src/components/LayersPanel.tsxindex 8a29b44..c32221a 100644--- a/packages/openfilm/studio/ui/src/components/LayersPanel.tsx+++ b/packages/openfilm/studio/ui/src/components/LayersPanel.tsx@@ -1,11 +1,11 @@/**- * The Layers panel: what is on the picture at the playhead as layers, the top one first, as Figma or Photoshop list- * them. Each picture clip shown is a row; a page clip opens into its layers, each level in the order the page draws- * it. A row selects its layer on the picture (and the picture's selection opens the rows down to it); its eye hides- * it and its lock keeps it from being moved; dragged up or down its own level, or into the level of a row around it- * (which then moves, with all it holds: CSS restacks only within a level), it is restacked (z-index overrides,- * studio/server/stage.js `restack`). Nothing is kept here: the tree is read from the pages each time they- * may have changed, and every change is an override of the page clip in film.html.+ * The Layers panel: what is on the picture at the playhead as layers, the top one first. Each picture clip shown is+ * a row; a page clip opens into its layers, each level in the order the page draws it. A row selects its layer on+ * the picture (and the picture's selection opens the rows down to it); its eye hides it and its lock keeps it from+ * being moved; dragged up or down its own level, or into the level of a row around it (which then moves, with all+ * it holds: CSS restacks only within a level), it is restacked (z-index overrides, studio/server/stage.js+ * `restack`). Nothing is kept here: the tree is read from the pages each time they may have changed, and every+ * change is an override of the page clip in film.html.*/import React from 'react';import {diff --git a/packages/openfilm/studio/ui/src/components/LiveTime.tsx b/packages/openfilm/studio/ui/src/components/LiveTime.tsxindex 4a072c8..f59f3c6 100644--- a/packages/openfilm/studio/ui/src/components/LiveTime.tsx+++ b/packages/openfilm/studio/ui/src/components/LiveTime.tsx@@ -1,14 +1,19 @@import type React from 'react';-import { useSyncExternalStore } from 'react';+import { useEffect, useLayoutEffect, useRef, useState, useSyncExternalStore } from 'react';/**- * The playing time as an external store. Keeping it in React state would re-render the whole editor ~20 times a- * second while playing; only the few leaves that follow the clock (playhead, timecode, subtitles, stage outlines)- * subscribe to it.+ * The playing time as an external store. Keeping it in React state would re-render the whole editor each frame while+ * playing; only the few leaves that follow the clock (playhead, timecode, subtitles, stage outlines) subscribe to it,+ * and each changes the page only when what it shows changes.*/export interface PlaybackClock {get(): number;subscribe(fn: () => void): () => void;+ /**+ * The line the film plays on now (film `ms` at `at` on the page's clock, `rate` film ms a ms; held at `ms` until+ * `at`), or null while still: what moves by itself (the playhead) follows it without being told each frame.+ */+ line?(): { ms: number; at: number; rate: number } | null;}const NO_SUBSCRIBE = () => () => {};@@ -19,17 +24,78 @@ export function usePlaybackTime(clock: PlaybackClock | null | undefined, fallbacreturn useSyncExternalStore(clock ? clock.subscribe : NO_SUBSCRIBE, read, read);}-/** Re-render only this small part as the clock moves: `<LiveTime clock={clock} timeMs={timeMs}>{(ms) => …}</LiveTime>`. */+/**+ * Follow a PlaybackClock, rendering again only when `step(ms)` changes (what is shown changes: another subtitle, its+ * next word), with the time it changed at; without a clock, `fallback`.+ */+export function useSteppedPlaybackTime(clock: PlaybackClock | null | undefined, fallback: number, step: (ms: number) => unknown): number {+ const [ms, setMs] = useState(fallback);+ const stepRef = useRef(step);+ stepRef.current = step;+ useEffect(() => {+ if (!clock) return undefined;+ let shown: unknown = Symbol('none');+ const tick = () => {+ const now = clock.get();+ const key = stepRef.current(now);+ if (key !== shown) { shown = key; setMs(now); }+ };+ tick();+ return clock.subscribe(tick);+ }, [clock]);+ return clock ? ms : fallback;+}++/**+ * Re-render only this small part as the clock moves: `<LiveTime clock={clock} timeMs={timeMs}>{(ms) => …}</LiveTime>`.+ * `step`: only when that says what is shown changed (see useSteppedPlaybackTime).+ */export function LiveTime({clock,timeMs,+ step,children,}: {clock: PlaybackClock | null | undefined;/** The time when there is no clock (or while stopped). */timeMs: number;+ step?: (ms: number) => unknown;children: (timeMs: number) => React.ReactNode;}) {- const live = usePlaybackTime(clock, timeMs);- return <>{children(live)}</>;+ return step ? <SteppedTime clock={clock} timeMs={timeMs} step={step}>{children}</SteppedTime> : <EveryTime clock={clock} timeMs={timeMs}>{children}</EveryTime>;+}+function EveryTime({ clock, timeMs, children }: { clock: PlaybackClock | null | undefined; timeMs: number; children: (timeMs: number) => React.ReactNode }) {+ return <>{children(usePlaybackTime(clock, timeMs))}</>;+}+function SteppedTime({ clock, timeMs, step, children }: { clock: PlaybackClock | null | undefined; timeMs: number; step: (ms: number) => unknown; children: (timeMs: number) => React.ReactNode }) {+ return <>{children(useSteppedPlaybackTime(clock, timeMs, step))}</>;+}++/**+ * Text that follows the clock (a timecode): written into the page directly, and only when it reads differently, so a+ * playing film costs the editor no rendering for it.+ */+export function LiveText({ clock, timeMs, format, className }: {+ clock: PlaybackClock | null | undefined;+ timeMs: number;+ format: (ms: number) => string;+ className?: string;+}) {+ const ref = useRef<HTMLSpanElement>(null);+ const formatRef = useRef(format);+ formatRef.current = format;+ useLayoutEffect(() => {+ const el = ref.current;+ if (!el) return undefined;+ let shown: string | null = null;+ const show = (ms: number) => {+ const text = formatRef.current(ms);+ if (text !== shown) { shown = text; el.textContent = text; }+ };+ if (!clock) { show(timeMs); return undefined; }+ const tick = () => show(clock.get());+ tick();+ return clock.subscribe(tick);+ }, [clock, timeMs, format]);+ return <span ref={ref} className={className} />;}diff --git a/packages/openfilm/studio/ui/src/components/MediaPool.tsx b/packages/openfilm/studio/ui/src/components/MediaPool.tsxindex 1bd9107..402de5a 100644--- a/packages/openfilm/studio/ui/src/components/MediaPool.tsx+++ b/packages/openfilm/studio/ui/src/components/MediaPool.tsx@@ -1,6 +1,6 @@/**- * Studio's media pane, kept the way editors keep media (CapCut's media panel, DaVinci's Media Pool): everything at- * one top level called All, folders as tiles beside the files, double-click a folder to go in.+ * Studio's media pane: everything at one top level called All, folders as tiles beside the files, double-click a+ * folder to go in.** The top level is assets/ itself plus every web page of the project (its scenes). A person can make folders and* drag files into them. Paths are not shown: Reveal in Finder and Copy path are on the right-click menu.@@ -29,6 +29,7 @@ import {FolderInput,FolderSymlink,HardDriveDownload,+ ImagePlus,Link2,Unlink,FolderOpen,@@ -145,6 +146,8 @@ export interface MediaPoolProps {onDelete: (path: string) => Promise<MediaResult>;/** A video's sound made a file of its own beside it (it shows up in the listing like any new file). */onExtractAudio?: (path: string) => Promise<MediaResult>;+ /** A picture of the project made its cover in the projects list. */+ onSetCover?: (path: string) => void;/** Make a folder (project-relative path, its name already made safe). */onNewFolder: (path: string) => Promise<MediaResult>;/** Before deleting files, take their clips off the timeline. A string is the reason it could not. */@@ -204,6 +207,7 @@ export function MediaPool({onMoveCheck,onDelete,onExtractAudio,+ onSetCover,onNewFolder,onDropClips,onReveal,@@ -571,6 +575,7 @@ export function MediaPool({id: 'extract-audio', label: t('assets.extractAudio'), icon: <AudioLines size={14} />,onSelect: () => { void onExtractAudio(file.path).then((r) => { if (r !== 'ok') setNotice(t('assets.extractAudioFailed')); }); },}] : []),+ ...(file.kind === 'image' && onSetCover ? [{ id: 'cover', label: t('projects.setAsCover'), icon: <ImagePlus size={14} />, onSelect: () => onSetCover(file.path) }] : []),/* a page of the project is named in other pages' code (not renamed here); one of Saved is its own folder */...(file.kind === 'mg' && !file.bundle ? [] : [{ id: 'rename', label: t('assets.rename'), icon: <Pencil size={14} />, onSelect: () => setRenaming(file.path) }]),moveEntry([file.path]),diff --git a/packages/openfilm/studio/ui/src/components/MenuSelect.tsx b/packages/openfilm/studio/ui/src/components/MenuSelect.tsxindex c4f310b..ecabcc3 100644--- a/packages/openfilm/studio/ui/src/components/MenuSelect.tsx+++ b/packages/openfilm/studio/ui/src/components/MenuSelect.tsx@@ -3,7 +3,7 @@* checked), in place of the browser's own list: that one is drawn by the system, light in a dark Studio, and with* the field's text color it read as if every choice were disabled. Choices may come in groups, each under a small* heading. The arrow keys move through them, Enter picks, Esc closes. With `onPreview`, the choice under the pointer (or- * the keys) is shown before it is picked, as Figma shows a font or a blend mode on the canvas; closing without a pick+ * the keys) is shown on the picture before it is picked (a font, a blend mode); closing without a pick* takes it back (`onRevert`).*/import React from 'react';diff --git a/packages/openfilm/studio/ui/src/components/PaneDivider.tsx b/packages/openfilm/studio/ui/src/components/PaneDivider.tsxindex 6782eb8..0239b29 100644--- a/packages/openfilm/studio/ui/src/components/PaneDivider.tsx+++ b/packages/openfilm/studio/ui/src/components/PaneDivider.tsx@@ -6,14 +6,14 @@* wider pane or a taller timeline when working on a long edit. A fixed ratio always* shortchanges one of them, and only the user knows the trade-off at that moment.*- * Modeled on Unreal: the gap between the panes is the seam, and the seam is the handle. Its+ * The gap between the panes is the seam, and the seam is the handle. Its* width must therefore equal the spacing between panes (DOCK_GAP); one pixel off makes it look crooked.** With a mouse the seam draws nothing. Hovering already turns the cursor into a resize arrow,* and while dragging the panes widen under the hand, which is the most direct feedback there* is. Lighting up a line would say the same thing a third time, and it would flicker whenever* the pointer merely crosses the seam (a seam between panes is on the path across the screen).- * CapCut and Unreal work this way: the cursor says where you can drag, the content says what is happening.+ * The cursor says where you can drag, the content says what is happening.** It lights up only when reached by keyboard: there is no cursor shape and no held button* then, so without a highlight a keyboard user cannot tell which seam has focus.diff --git a/packages/openfilm/studio/ui/src/components/PasteAttrsDialog.tsx b/packages/openfilm/studio/ui/src/components/PasteAttrsDialog.tsxindex 626dbb3..bfed06c 100644--- a/packages/openfilm/studio/ui/src/components/PasteAttrsDialog.tsx+++ b/packages/openfilm/studio/ui/src/components/PasteAttrsDialog.tsx@@ -5,7 +5,7 @@ import { groupsOf, type AttrGroup, type CopiedAttrs } from '@/lib/clip-attrs';import { Card, CardActions, CardButton } from './Card';/**- * Paste attributes (⌘⇧V), as CapCut's dialog: what the copied clip has, in two parts — its picture (place and size,+ * Paste attributes (⌘⇧V): what the copied clip has, in two parts — its picture (place and size,* blending) and its sound (volume, fades) — each ticked, untick what should stay. Enter pastes, Esc backs out.*/export function PasteAttrsDialog({diff --git a/packages/openfilm/studio/ui/src/components/ProjectCover.tsx b/packages/openfilm/studio/ui/src/components/ProjectCover.tsxnew file mode 100644index 0000000..c34cc30--- /dev/null+++ b/packages/openfilm/studio/ui/src/components/ProjectCover.tsx@@ -0,0 +1,60 @@+/**+ * A project's own cover, from its card in the Projects popover: a picture chosen on this computer, or back to the+ * film's poster (studio/server/cover.mjs). The popover provides the actions; each card's "…" menu offers them.+ */+import React from 'react';+import { api } from '@/api';+import type { LibraryProject } from './ProjectsView';++export interface ProjectCoverActions {+ /** Pick a picture on this computer for its cover. */+ change: (project: LibraryProject) => void;+ /** No cover of its own: the film's poster again. */+ restore: (project: LibraryProject) => void;+}++export const ProjectCoverContext = React.createContext<ProjectCoverActions | null>(null);++/** The card's picture: its own cover when it has one (asked for again once it changes), else the film's poster. */+export const posterUrl = (project: { id: string; cover?: number }) =>+ `/api/projects/${encodeURIComponent(project.id)}/poster${project.cover ? `?cover=${project.cover}` : ''}`;++/** The pictures a cover may be (cover.mjs reads what they are, not their names). */+const ACCEPT = 'image/png,image/jpeg,image/webp,image/gif';++/**+ * The actions and the file input they use. `changed` gets the project's new cover time (null: none of its own);+ * `failed` is told when Studio could not take the picture.+ */+export function useProjectCover(changed: (id: string, cover: number | null) => void, failed: () => void) {+ const input = React.useRef<HTMLInputElement>(null);+ const picking = React.useRef<string | null>(null);++ const actions = React.useMemo<ProjectCoverActions>(() => ({+ change: (project) => {+ picking.current = project.id;+ if (input.current) { input.current.value = ''; input.current.click(); }+ },+ restore: (project) => {+ void api.clearCover(project.id).then(() => changed(project.id, null), failed);+ },+ }), [changed, failed]);++ const picker = (+ <input+ ref={input}+ type="file"+ accept={ACCEPT}+ hidden+ onChange={(event) => {+ const file = event.currentTarget.files?.[0];+ const id = picking.current;+ picking.current = null;+ if (!file || !id) return;+ void api.setCover(id, { file }).then((cover) => changed(id, cover), failed);+ }}+ />+ );++ return { actions, picker };+}diff --git a/packages/openfilm/studio/ui/src/components/ProjectMenu.tsx b/packages/openfilm/studio/ui/src/components/ProjectMenu.tsxindex 5b3fce1..eb28c98 100644--- a/packages/openfilm/studio/ui/src/components/ProjectMenu.tsx+++ b/packages/openfilm/studio/ui/src/components/ProjectMenu.tsx@@ -1,5 +1,5 @@import React from 'react';-import { CheckSquare, Download, FolderInput, FolderOpen, FolderSearch, ListX, MoreHorizontal, Pencil, Trash2 } from 'lucide-react';+import { CheckSquare, Download, FolderInput, FolderOpen, FolderSearch, Image, ImageOff, ImagePlus, ListX, MoreHorizontal, Pencil, Trash2 } from 'lucide-react';import { ContextMenu, type ContextMenuEntry } from './ContextMenu';import { Tooltip } from './Tooltip';import { useT } from '@/i18n';@@ -7,8 +7,9 @@ import { useT } from '@/i18n';/*** A project's "…" menu.*- * Each item shows only when its callback is passed: the editor's top bar passes Export and Reveal in Finder; a card in- * the Projects popover passes Open / Rename / Select / Move to folder / Delete, or Locate… and Remove from list when the+ * Each item shows only when its callback is passed: the editor's top bar passes the current frame as the cover, Export+ * and Reveal in Finder; a card in the Projects popover passes Open / Rename / Select / Move to folder / Change cover /+ * Restore cover / Reveal / Delete, or Locate… and Remove from list when the* project's folder is gone. The order is fixed here, not by the props, so the same menu looks the same wherever it* appears. It is a ContextMenu hanging from the button: it flips above it near the bottom of the window, and Esc* closes only the menu.@@ -18,6 +19,9 @@ export function ProjectMenu({onRename,onSelect,onMoveToFolder,+ onChangeCover,+ onRestoreCover,+ onCoverFromFrame,onExport,onReveal,onLocate,@@ -33,6 +37,12 @@ export function ProjectMenu({onSelect?: () => void;/** Pick a folder of the Projects list to put it in. */onMoveToFolder?: () => void;+ /** Pick a picture for the project's card. */+ onChangeCover?: () => void;+ /** The project has a cover of its own: back to the film's poster. */+ onRestoreCover?: () => void;+ /** The film as the viewer shows it now made the project's cover. */+ onCoverFromFrame?: () => void;onExport?: () => void;/** Show the project's folder in Finder / Explorer. */onReveal?: () => void;@@ -63,6 +73,9 @@ export function ProjectMenu({add('rename', <Pencil size={15} />, t('projectMenu.rename'), onRename);add('select', <CheckSquare size={15} />, t('library.select'), onSelect);add('move', <FolderInput size={15} />, t('projects.moveToFolder'), onMoveToFolder);+ add('cover', <ImagePlus size={15} />, t('projects.changeCover'), onChangeCover);+ add('coverFrame', <Image size={15} />, t('projects.coverFromFrame'), onCoverFromFrame);+ add('coverReset', <ImageOff size={15} />, t('projects.restoreCover'), onRestoreCover);add('export', <Download size={15} />, t('projectMenu.export'), onExport);add('reveal', <FolderOpen size={15} />, t('projects.revealFolder'), onReveal);add('locate', <FolderSearch size={15} />, t('projects.locate'), onLocate);diff --git a/packages/openfilm/studio/ui/src/components/ProjectView.tsx b/packages/openfilm/studio/ui/src/components/ProjectView.tsxindex 1a13339..68818cd 100644--- a/packages/openfilm/studio/ui/src/components/ProjectView.tsx+++ b/packages/openfilm/studio/ui/src/components/ProjectView.tsx@@ -13,13 +13,14 @@ import { api, ApiError, PREFS_EVENT, projectEvents, type Clip, type Film, type Limport { useT } from '@/i18n';import { useFilm, type Step } from '@/editor/use-film';import { Player } from '@/editor/player';-import { Preview, type FilmInfo, type PreviewHandle } from '@/editor/Preview';+import { Preview, type FilmInfo, type PlayedReport, type PreviewHandle } from '@/editor/Preview';+import { usePreviewRenders } from '@/editor/use-preview-renders';import { filmShape, type MediaFacts } from '@/lib/film-shape';import { changesPicture } from '@/lib/picture-files';import type { ReplaceFamily } from '@/lib/clip-replace';import { layoutTracks, type TimelineBlock, type TimelineTrack } from '@/lib/timeline-layout';import { filmClipKind, filmSrcIsPage, filmSrcKind, filmTrackBadges, parseFilmDocLoc, type FilmBox, type FilmDoc, type FilmOverride } from '@/lib/film';-import { footageFps, setTimecodeFps, snapToFrame, stepFrames } from '@/lib/timecode';+import { exactRate, footageFps, setTimecodeFps, snapToFrame, stepFrames } from '@/lib/timecode';import { JUMP_FRAMES, keyCommandOf, loopBack, playStart, shuttleRate } from '@/lib/timeline-keys';import { attrsOf, pasteAttrs, type AttrGroup, type CopiedAttrs } from '@/lib/clip-attrs';import { cutPoints, namedTrack, nextCut, trackNamesOf } from '@/lib/timeline-nav';@@ -29,7 +30,7 @@ import { apartOnTracks, type ClipEdit } from '@/lib/film-clip-edits';import { mediaFetch, useMediaImages } from '@/lib/media-queue';import { clipboardItemsOf, clipboardNow, pasteEdit, type TimelineClipboardItem } from '@/lib/timeline-clipboard';import { editModelOf, freshLink, linkedIds, magnetOn, mainTrackOf, planMove, planRippleTrim, planRoom, planSpeed, soundTrackFor, type EditMode } from '@/lib/timeline-edit';-import { followOf, readTimelinePrefs } from '@/lib/timeline-prefs';+import { readTimelinePrefs, switchesOf } from '@/lib/timeline-prefs';import { fadeMsOf, type FadeMs } from '@/lib/clip-fade';import {findTransitions, planRemoveTransition, planResizeTransition, planTransition, TRANSITION_MS,@@ -61,7 +62,7 @@ import { SubtitleOverlay } from './SubtitleOverlay';import { SubtitleInspector, subtitleLineKey, type SubtitleLineAt, type SubtitleLineRefer } from './SubtitleInspector';import { useFilmSubtitles } from '@/lib/use-film-subtitles';import { speakerAt, useSubtitleEdits } from '@/lib/use-subtitle-edits';-import { cueAt, filmSubtitleStyleFor, sameFilmSubtitleLanguage } from '@/lib/subtitles';+import { cueAt, filmSubtitleStyleFor, filmSubtitleWords, sameFilmSubtitleLanguage, type SubtitleCue } from '@/lib/subtitles';import { DEFAULT_INSPECTOR, DOCK_GAP, DockPaneDivider, MIN_DOCK_H, MIN_INSPECTOR, MIN_STAGE_H, MIN_VIEWER, PaneDivider, usePaneSize } from './PaneDivider';import { PANE_BAR, PANE_BTN_ON, PANE_TOGGLE, PANE_TOGGLE_ICON } from './dock-pane-bar';import { Tooltip } from './Tooltip';@@ -109,6 +110,7 @@ import type { MaskSession } from '@/lib/stage-mask';import type { MaskShape } from '@/lib/clip-mask';import { nextOverrides, overrideOf, type OverrideGeometry } from '@/lib/film-overrides';import { compactScale, type MgTransform, type NodeOverride, type OverridePivot, type StageElement, type StageElementStyle, type StageGeometry } from '@/lib/stage-types';+import { usePreviewPrefs } from '@/lib/preview-prefs';import { isTypingTarget } from './typing-target';const PANE = 'relative flex min-h-0 min-w-0 flex-col overflow-hidden rounded-[7px]';@@ -184,6 +186,9 @@ function clipIdAt(film: Film | null, loc: string): string | null {return at ? film?.tracks[at.track]?.clips[at.clip]?.id ?? null : null;}+/** No subtitles shown (fullscreen's CC off): the same list each time, so nothing renders again for it. */+const NO_CUES: readonly SubtitleCue[] = [];+export function ProjectView({ projectId, onProject, onLeave }: {projectId: string;/** go to another project */@@ -216,6 +221,8 @@ export function ProjectView({ projectId, onProject, onLeave }: {/* a picture that could not be drawn is tried again whenever the folder changes: the missing file arrived, orthe clip that named it is gone from film.html now that the edit is written */if (previewErrorRef.current && (event.type === 'film' || event.type === 'files')) { preview.current?.reload?.(); }+ /* renamed from another tab, or the projects list */+ if (event.type === 'project') { setLoaded((l) => (l ? { ...l, project: event.project } : l)); return; }if (event.type !== 'files') return;void loadFiles();/* a page's picture depends on the files it loads (its styles, code, pictures): its thumbnails are asked again@@ -352,9 +359,13 @@ export function ProjectView({ projectId, onProject, onLeave }: {const refOfFile = React.useCallback((file: WorkspaceResource) => fileRef(file, file.kind === 'mg' ? mediaSources.pagePoster?.(file): file.kind === 'image' ? stillUrl(projectId, file.path, Math.round(file.mtimeMs)) : file.kind === 'video' ? mediaSources.poster?.(file) : undefined), [mediaSources, projectId]);- /* ── transport: the sound is the clock; the picture follows it ── */+ /* ── transport: the sound is the clock; the picture follows it, drawn in the preview from the player's line ── */const player = React.useRef(new Player());- React.useEffect(() => () => player.current.close(), []);+ React.useEffect(() => {+ const p = player.current;+ p.onAnchor = (anchor) => preview.current?.play?.(anchor);+ return () => { p.onAnchor = null; p.close(); };+ }, []);const [playing, setPlaying] = React.useState(false);const [timeMs, setTimeMs] = React.useState(0);const timeRef = React.useRef(0);@@ -371,6 +382,7 @@ export function ProjectView({ projectId, onProject, onLeave }: {const clock = React.useMemo<PlaybackClock>(() => ({get: () => player.current.time() * 1000,subscribe: (fn) => { listeners.current.add(fn); return () => listeners.current.delete(fn); },+ line: () => { const a = player.current.anchor(); return a ? { ms: a.t * 1000, at: a.at, rate: a.rate } : null; },}), []);/* the player never says 0 (it divides by its length): an empty film is 0.001 s long, here 0 */const drawnMs = (info?.duration ?? 0) > 0.001 ? Math.round(info!.duration * 1000) : 0;@@ -387,8 +399,8 @@ export function ProjectView({ projectId, onProject, onLeave }: {const back = loopRef.current ? loopBack(t * 1000, rangeNowRef.current, player.current.duration * 1000) : null;if (back != null) {stopAtRef.current = null;+ /* the player plays on from there: the preview is told its new line */player.current.seek(back / 1000);- preview.current?.seek(pictureAt(back / 1000));setTimeMs(back);for (const fn of listeners.current) fn();frame = requestAnimationFrame(tick);@@ -405,10 +417,10 @@ export function ProjectView({ projectId, onProject, onLeave }: {for (const fn of listeners.current) fn();return;}- preview.current?.seek(pictureAt(t));+ /* the picture draws itself from the player's line (Preview's play); the playhead, timecode and subtitles read the+ clock; the rest of the editor hears the time a few times a second (each time, all of it renders again) */for (const fn of listeners.current) fn();- /* the rest of the editor hears the time a few times a second; the playhead and timecode read the clock */- if (now - lastTick > 50) { lastTick = now; setTimeMs(t * 1000); }+ if (now - lastTick > 250) { lastTick = now; setTimeMs(t * 1000); }if (!player.current.playing || t >= player.current.duration - 1e-3) {player.current.pause();setPlaying(false);@@ -424,9 +436,10 @@ export function ProjectView({ projectId, onProject, onLeave }: {const seek = React.useCallback((ms: number) => {const t = Math.max(0, Math.min(ms / 1000, player.current.duration || ms / 1000));+ /* playing, it plays on from there (the preview is told the player's new line); still, the picture shows t */player.current.seek(t);setTimeMs(t * 1000);- preview.current?.seek(pictureAt(t));+ if (!player.current.playing) preview.current?.seek(pictureAt(t));for (const fn of listeners.current) fn();}, []);/* ── J / K / L: the shuttle. 1× and 2× forward are the player's own (with sound); faster, or backwards, the picture@@ -446,9 +459,12 @@ export function ProjectView({ projectId, onProject, onLeave }: {if (shuttleFrame.current) { cancelAnimationFrame(shuttleFrame.current); shuttleFrame.current = 0; shuttleRateRef.current = 0; }if (!player.current.playing) return;player.current.pause();+ /* stopped on the frame being shown: the timecode, the picture and an edit at the playhead all mean that frame */+ player.current.seek(snapToFrame(player.current.time() * 1000) / 1000);setPlaying(false);setTimeMs(player.current.time() * 1000);preview.current?.seek(pictureAt(player.current.time()));+ for (const fn of listeners.current) fn();}, []);const toggle = React.useCallback(() => {stopShuttle();@@ -512,8 +528,27 @@ export function ProjectView({ projectId, onProject, onLeave }: {return () => { window.removeEventListener('pointerdown', wake, true); window.removeEventListener('keydown', wake, true); };}, []);/* scrubbing the timeline pauses, and stays paused */- const scrubPreview = React.useCallback((ms: number) => { pause(); seek(ms); }, [pause, seek]);+ /* while scrubbing, the picture and the timecode follow each step the timeline tells (every frame); the rest of the+ editor, which renders whole each time, hears the time a few times a second, and once more as the scrub ends */+ const scrubTold = React.useRef(0);+ const scrubPreview = React.useCallback((ms: number) => {+ pause();+ const t = Math.max(0, Math.min(ms / 1000, player.current.duration || ms / 1000));+ player.current.seek(t);+ preview.current?.seek(pictureAt(t));+ for (const fn of listeners.current) fn();+ const now = performance.now();+ if (now - scrubTold.current > 100) { scrubTold.current = now; setTimeMs(t * 1000); }+ // eslint-disable-next-line react-hooks/exhaustive-deps+ }, [pause]);const scrubCommit = React.useCallback((ms: number) => { pause(); seek(ms); }, [pause, seek]);+ /* the timeline's preview axis: the picture at the moment under the pointer, the clock and the playhead staying; null:+ back to the playhead's picture. Not while playing (the picture is the film's then) */+ const hoverPreview = React.useCallback((ms: number | null) => {+ if (player.current.playing) return;+ preview.current?.seek(pictureAt(ms == null ? player.current.time() : Math.max(0, ms / 1000)));+ // eslint-disable-next-line react-hooks/exhaustive-deps+ }, []);/* a seek asked for past the film's end as it was (the end of a clip just put on): made once the film is that long */const seekWhenLonger = React.useRef<number | null>(null);@@ -569,6 +604,15 @@ export function ProjectView({ projectId, onProject, onLeave }: {...(rawListing?.files ?? []).filter((f) => f.kind === 'video').map((f) => facts.get(f.path)?.fps),]), [timelineTracks, rawListing, facts]);const projectFps = settings?.fps ?? footageRate;+ /* stretches that play late, rendered in the background to play smoothly (editor/use-preview-renders) */+ const { renders: rendersOn, stats: statsOn } = usePreviewPrefs();+ const previewRenders = usePreviewRenders({ projectId, folder, fps: exactRate(projectFps), playing, on: rendersOn, film: film.film, files: filesTick, preview });+ /* Settings → Developer: how playing goes, in the viewer's corner, said about once a second */+ const [played, setPlayed] = React.useState<PlayedReport | null>(null);+ const onPlayed = React.useCallback((report: PlayedReport) => {+ previewRenders.onPlayed(report);+ if (statsOn) setPlayed(report);+ }, [previewRenders, statsOn]);React.useEffect(() => { setTimecodeFps(projectFps); }, [projectFps]);React.useEffect(() => () => setTimecodeFps(30), []);const frameRate = React.useMemo(() => ({ fps: projectFps, fromFootage: settings?.fps == null, onChange: (fps: number) => patchSettings({ fps }) }), [projectFps, settings, patchSettings]);@@ -671,6 +715,13 @@ export function ProjectView({ projectId, onProject, onLeave }: {const subs = useFilmSubtitles(projectId);/* fullscreen's CC button (and c): only what is shown, not the film's own setting */const [captionsOn, setCaptionsOn] = React.useState(true);+ /* the subtitle over the picture renders again while playing only when another line, or another of its words, is said */+ const shownCues = captionsOn ? subs.cues : NO_CUES;+ const subtitleStep = React.useCallback((ms: number) => {+ const cue = subs.style.on ? cueAt(shownCues, ms) : null;+ if (!cue) return '';+ return `${shownCues.indexOf(cue)}:${subs.style.karaoke ? filmSubtitleWords(cue, ms).map((w) => (w.active ? 1 : 0)).join('') : ''}`;+ }, [shownCues, subs.style.on, subs.style.karaoke]);const configureSubtitles = React.useCallback(() => {setInspectorContent('subtitles');setInspectorOpen(!(inspectorOpen && inspectorContent === 'subtitles'));@@ -733,7 +784,7 @@ export function ProjectView({ projectId, onProject, onLeave }: {/** An edit the timeline planned (lib/timeline-edit), as it planned it: one write, one undo step. */const editOps = React.useCallback((ops: Op[], label: string) => edit(ops, label), [edit]);- /* ── a clip's attributes copied onto others (lib/clip-attrs, ⌘⇧C / ⌘⇧V, as CapCut's) ── */+ /* ── a clip's attributes copied onto others (lib/clip-attrs, ⌘⇧C / ⌘⇧V) ── */const [copiedAttrs, setCopiedAttrs] = React.useState<CopiedAttrs | null>(null);const [pasteAttrsOpen, setPasteAttrsOpen] = React.useState(false);const filmClipOf = React.useCallback((id: string) => filmRef.current?.tracks.flatMap((tr) => tr.clips).find((c) => c.id === id) ?? null, []);@@ -783,16 +834,15 @@ export function ProjectView({ projectId, onProject, onLeave }: {const pickedTr = filmTransitions.find((x) => x.key === pickedTransition) ?? null;/*** A transition put on a cut, made longer or shorter, or taken away (lib/transitions): planned on the timeline as it- * is, in the timeline's mode (the magnet, sync lock, linked clips), one write and one undo step. The menus put on- * fades only; other transitions are an agent's to write.+ * is (on the main track with the magnet what follows an overlap closes up, linked clips along), one write and one+ * undo step. The menus put on fades only; other transitions are an agent's to write.*/const askTransition = React.useCallback(async (ask: TransitionAsk): Promise<string | null> => {- const prefs = readTimelinePrefs();const model = editModel();- /* the magnet acts on the main track: there a transition's overlap closes up what follows */+ /* the magnet acts on the main track: there an overlap closes up what follows, no gap opens after it */const cutClip = ask.kind === 'add' ? ask.cut.a : filmTransitions.find((x) => x.key === ask.key)?.a;const cutTrack = model.find((tr) => tr.clips.some((c) => c.id === cutClip))?.index;- const opts = { ripple: magnetOn(model, cutTrack, prefs.magnet), ...followOf(prefs), linked: true, whiteSrc: WHITE_SRC };+ const opts = { ripple: magnetOn(model, cutTrack, readTimelinePrefs().magnet), linked: true, whiteSrc: WHITE_SRC };let plan: TransitionPlan;let label: string;if (ask.kind === 'add') {@@ -810,40 +860,42 @@ export function ProjectView({ projectId, onProject, onLeave }: {return plan.ops.length ? edit(plan.ops, label) : null;}, [editModel, clipFacts, filmTransitions, edit, t]);/**- * The inspector's edits (its refusals it says beside its field). A new speed goes to the clips linked to the clip too; with the magnet on (the timeline's- * switch) a speed or a length that makes the clip longer or shorter pushes or pulls what follows, as a ripple trim- * does; without, a speed too slow to fit before the next clip is refused, and the inspector says why.+ * The inspector's edits (its refusals it says beside its field). A new speed goes to the clips linked to the clip+ * too. On the main track with the magnet (the timeline's switch) a speed or a length that makes the clip longer or+ * shorter pushes or pulls what follows, as a ripple trim does; elsewhere a speed too slow to fit before the next clip+ * is refused, and the inspector says why. With linkage what rides on the main track stays on its footage.*/const editClips = React.useCallback((edits: ClipEdit[]): Promise<string | null> => {const [one] = edits;const block = one && edits.length === 1 ? blocksRef.current.find((b) => b.loc === one.loc) : undefined;- const prefs = readTimelinePrefs();if (block?.loc && lockedEdits(edits, filmRef.current).length) return Promise.resolve(t('timeline.trackLocked'));const model = editModel();+ const prefs = readTimelinePrefs();+ const switches = switchesOf(prefs);/* the magnet acts on the main track alone */const magnet = magnetOn(model, model.find((tr) => tr.clips.some((c) => c.id === block?.clipId))?.index, prefs.magnet);if (!block?.clipId || (one!.prop !== 'speed' && one!.prop !== 'at' && !(one!.prop === 'end' && magnet))) return editBlocks(edits, true);const ids = [block.clipId, ...linkedIds(model, [block.clipId]).filter((id) => id !== block.clipId)];if (one!.prop === 'at') {- /* a start typed in: the clip (and those linked to it) moves as a drag would, in the timeline's mode: with the- magnet it goes in at the insert point there and pushes what follows on; without it, it lands there and covers- what is under it. Never onto a new track */+ /* a start typed in: the clip (and those linked to it) moves as a drag would: on the main track with the magnet+ it goes in at the insert point there; elsewhere it lands there, or on a new track beside its own when that+ time is taken. Nothing there is cut */const startMs = Number(one!.value) * 1000 + (block.anchor?.parentStartMs ?? 0);if (!Number.isFinite(startMs)) return Promise.resolve(t('timeline.editFail'));- const plan = planMove(model, { ids, deltaMs: startMs - block.startMs, pointerMs: startMs, mode: magnet ? 'insert' : 'overwrite', magnet: prefs.magnet, ...followOf(prefs) });+ const plan = planMove(model, { ids, deltaMs: startMs - block.startMs, pointerMs: startMs, mode: 'place', ...switches });if (!plan) return Promise.resolve(t('timeline.trackLocked'));return plan.ops.length ? edit(plan.ops, clipStep('history.stepMoved', [block.clipId]), true) : Promise.resolve(null);}if (one!.prop === 'speed') {const speed = typeof one!.value === 'number' ? one!.value : 1;- const plan = planSpeed(model, ids, speed, { ripple: magnet, ...followOf(prefs) });+ const plan = planSpeed(model, ids, speed, { ripple: magnet, ...switches });if (plan.slowest != null) return Promise.resolve(t('inspector.speedTooSlow').replace('{n}', String(plan.slowest)));return plan.ops.length ? edit(plan.ops, `history.stepSpeed|${block.clipId}`, true) : Promise.resolve(null);}/* a new length, with the magnet: a ripple trim of the tail by the difference (source seconds over the speed) */const k = block.anchor?.trimFrom != null && block.speed ? block.speed : 1;const deltaMs = ((Number(one!.value) - Number(one!.from ?? one!.value)) * 1000) / k;- const plan = planRippleTrim(model, ids, 'end', deltaMs, followOf(prefs));+ const plan = planRippleTrim(model, ids, 'end', deltaMs, switches);return plan.ops.length ? edit(plan.ops, `history.stepRippleTrimmed|${block.clipId}`, true) : Promise.resolve(null);}, [editBlocks, editModel, edit, t]);const removeBlock = React.useCallback((block: TimelineBlock): Promise<string | null> => {@@ -879,7 +931,7 @@ export function ProjectView({ projectId, onProject, onLeave }: {taken.add(made);rightLinks.set(link, made);}- /* a selected clip's selection goes to its right half, as CapCut's: named here so it can be selected once written */+ /* a selected clip's selection goes to its right half: named here so it can be selected once written */const selected = new Set(selectedKeysRef.current);const used = new Set(clips.map((c) => c.id));const rightIds = new Map<string, string>();@@ -942,9 +994,10 @@ export function ProjectView({ projectId, onProject, onLeave }: {setClipboard(clipboardItemsOf(blocks, timelineTracks));}, [timelineTracks]);/**- * A paste (⌘V, the menu) at a time, in the timeline's mode: onto the track pointed at (`lane`) or each copy's own,- * an insert making room there with the magnet on, else an overwrite (lib/timeline-clipboard pasteEdit). Never a new- * track. A clip cut since it was copied comes back as it was copied (under a new id).+ * A paste (⌘V, the menu) at a time: onto the track pointed at (`lane`) or each copy's own, never cutting what is+ * there: a taken spot opens a track beside it, and with the magnet a copy for the main track goes right above it+ * (lib/timeline-clipboard pasteEdit). A clip cut since it was copied comes back as it was copied (under a+ * new id).*/const pasteAt = React.useCallback((lane: string | null, atMs: number): Promise<string | null> => {if (!clipboard.length) return Promise.resolve(t('timeline.menuPasteEmpty'));@@ -953,8 +1006,7 @@ export function ProjectView({ projectId, onProject, onLeave }: {if (missing > cut.length) toast.show(t('timeline.pasteGone'));const all = [...items, ...cut].sort((a, b) => a.startMs - b.startMs);if (!all.length) return Promise.resolve(null);- const prefs = readTimelinePrefs();- const ops = pasteEdit(all, timelineTracks, editModel(), atMs, lane, { magnet: prefs.magnet, ...followOf(prefs) });+ const ops = pasteEdit(all, timelineTracks, editModel(), atMs, lane, { mode: 'place', ...switchesOf(readTimelinePrefs()) });if (!ops) return Promise.resolve(t('timeline.trackLocked'));const gone = new Set(cut.map((item) => item.clipId));const written = ops.map((op): Op => {@@ -970,7 +1022,7 @@ export function ProjectView({ projectId, onProject, onLeave }: {const roomFor = React.useCallback((spans: { track: number | { insert: number } | undefined; atSec: number; durMs: number }[], mode?: EditMode): Op[] => {const onTracks = spans.flatMap((s) => (typeof s.track === 'number' ? [{ track: s.track, startMs: Math.round(s.atSec * 1000), endMs: Math.round(s.atSec * 1000) + s.durMs }] : []));if (!mode || !onTracks.length) return [];- return planRoom(editModel(), onTracks, { mode, ...followOf(readTimelinePrefs()) }).ops;+ return planRoom(editModel(), onTracks, { mode, ...switchesOf(readTimelinePrefs()) }).ops;}, [editModel]);const dropAsset = React.useCallback(async (file: ResourceDragItem, target: AssetDropTarget, atMs: number): Promise<string | null> => {const plan = assetDropInsert(file, timelineTracks, target, atMs, stageRef.current);@@ -1008,14 +1060,13 @@ export function ProjectView({ projectId, onProject, onLeave }: {dropAssetRef.current = dropAsset;/*** A media file put on the timeline without a drag (lib/media-place): the media pane's "+" and Enter (in the- * timeline's mode, at the playhead on the targeted track, else at the end of the main track), the source viewer's- * `,` and `.` (insert or overwrite the part marked, at the playhead; the playhead then goes to its end, as Premiere's).+ * playhead on the targeted track, else at the end of the lowest picture track), the source viewer's+ * `,` and `.` (insert or overwrite the part marked, at the playhead; the playhead then goes to its end).*/const addMedia = React.useCallback(async (file: WorkspaceResource, how: { mode?: EditMode; range?: SourceRange | null; atPlayhead?: boolean } = {}) => {- const prefs = readTimelinePrefs();const target = timelineCommands.current?.target() ?? null;const at = how.atPlayhead || target != null ? snapToFrame(timeRef.current) : 'end';- const plan = placeMedia(editModel(), { file, range: how.range ?? null, target, at, ...(how.mode ? { mode: how.mode } : {}), magnet: prefs.magnet, ...followOf(prefs), stage: stageRef.current });+ const plan = placeMedia(editModel(), { file, range: how.range ?? null, target, at, ...(how.mode ? { mode: how.mode } : {}), ...switchesOf(readTimelinePrefs()), stage: stageRef.current });if ('error' in plan) { toast.show(plan.error === 'locked' ? t('timeline.trackLocked') : t('timeline.dropNotClip')); return; }const failed = await edit(plan.ops, 'history.stepDrop');if (failed) { toast.show(failed); return; }@@ -1045,9 +1096,8 @@ export function ProjectView({ projectId, onProject, onLeave }: {if (failed) toast.show(failed);return;}- const prefs = readTimelinePrefs();const target = timelineCommands.current?.target() ?? null;- const plan = placeMedia(editModel(), { file, range: null, target, at: snapToFrame(timeRef.current), magnet: prefs.magnet, ...followOf(prefs), stage: stageRef.current });+ const plan = placeMedia(editModel(), { file, range: null, target, at: snapToFrame(timeRef.current), ...switchesOf(readTimelinePrefs()), stage: stageRef.current });if ('error' in plan) { toast.show(plan.error === 'locked' ? t('timeline.trackLocked') : t('timeline.dropNotClip')); return; }const clip = taken.clip;const failed = await edit(plan.ops.map((op) => (op.op === 'insert' ? { ...op, clip: clip as never } : op)), 'history.stepDrop');@@ -1232,6 +1282,7 @@ export function ProjectView({ projectId, onProject, onLeave }: {onMoveCheck={onMoveCheck}onDelete={onDelete}onExtractAudio={onExtractAudio}+ onSetCover={onSetCover}onNewFolder={onNewFolder}onDropClips={dropClipsForAssets}onReveal={reveal}@@ -1696,7 +1747,7 @@ export function ProjectView({ projectId, onProject, onLeave }: {}, [stageMenuFor, t, saveBlocks]);/** Two groups of menu entries, a line between them when both have some. */const menuGroups = (a: ContextMenuEntry[], b: ContextMenuEntry[]): ContextMenuEntry[] => (a.length && b.length ? [...a, { id: 'tools-sep', separator: true }, ...b] : [...a, ...b]);- /* copy and paste attributes, as CapCut's clip menu has them */+ /* copy and paste attributes, in the clip menu */const attrsEntries = (blocks: readonly TimelineBlock[]): ContextMenuEntry[] => [{ id: 'copy-attrs', label: t('clipAttrs.copy'), icon: <ClipboardCopy size={14} />, shortcut: shortcutHint('C', { mod: true, shift: true }), disabled: blocks.length !== 1, onSelect: () => copyAttrs(blocks) },{ id: 'paste-attrs', label: t('clipAttrs.pasteMenu'), icon: <ClipboardPaste size={14} />, shortcut: shortcutHint('V', { mod: true, shift: true }), disabled: !copiedAttrs, hint: t('clipAttrs.nothing'), onSelect: () => askPasteAttrs(blocks) },@@ -1744,15 +1795,15 @@ export function ProjectView({ projectId, onProject, onLeave }: {}, 60);}, []); // eslint-disable-line react-hooks/exhaustive-deps/**- * Duplicate (⌘D, the bar's, the picture menu's): copies right after the clips, each on its own track, in the- * timeline's mode (an insert pushes what follows on, an overwrite covers it), as a paste there is; never a new track.+ * Duplicate (⌘D, the bar's, the picture menu's): copies right after the clips, each on its own track, going in+ * between (what follows on that track moves on; with linkage, what rides on the main track along), so nothing is+ * covered; never a new track.*/const duplicateBlocks = React.useCallback(async (blocks: readonly TimelineBlock[]) => {const picked = blocks.filter((b) => b.clipId);if (!picked.length) return null;- const prefs = readTimelinePrefs();const tracks = tracksRef.current;- const ops = pasteEdit(clipboardItemsOf(picked, tracks), tracks, editModel(), Math.max(...picked.map((b) => b.endMs)), null, { magnet: prefs.magnet, ...followOf(prefs) });+ const ops = pasteEdit(clipboardItemsOf(picked, tracks), tracks, editModel(), Math.max(...picked.map((b) => b.endMs)), null, { mode: 'insert', ...switchesOf(readTimelinePrefs()) });const failed = !ops ? t('timeline.trackLocked') : ops.length ? await edit(ops, picked.length <= 2 ? clipStep('history.stepDuplicated', picked.map((b) => b.clipId!)) : 'history.stepDuplicate') : null;if (failed) toast.show(failed);return failed;@@ -2112,6 +2163,10 @@ export function ProjectView({ projectId, onProject, onLeave }: {const onExtractAudio = React.useCallback(async (path: string) => mediaResult(await fetch(`${projectApi}/files/audio`, {method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ path }),})), [projectApi]);+ /* a picture of the project: the project's card in the projects list */+ const onSetCover = React.useCallback((path: string) => {+ void api.setCover(projectId, { path }).then(() => toast.show(t('projects.coverSet')), () => toast.showError(t('projects.coverFailed')));+ }, [projectId, toast, t]);const onNewFolder = React.useCallback(async (path: string) => mediaResult(await fetch(`${projectApi}/folders`, {method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ path }),})), [projectApi]);@@ -2123,7 +2178,7 @@ export function ProjectView({ projectId, onProject, onLeave }: {const stage = film.film?.stage ?? { w: 1920, h: 1080 };stageRef.current = stage;const empty = !film.film?.tracks.some((tr) => tr.clips.length);- /* the canvas (the stage in film.html), from the viewer's ratio button or the inspector, as CapCut's: another shape+ /* the canvas (the stage in film.html), from the viewer's ratio button or the inspector: another shapekeeps the canvas's short side (canvasFor; a typed size is that size), and every picture on it is scaled by onefactor into the new canvas, centered, in the same edit (one undo). Laying the film out again for the new canvasis the agent's (the inspector gives the words) */@@ -2344,7 +2399,7 @@ export function ProjectView({ projectId, onProject, onLeave }: {/* the source viewer's keys (it takes them first while it is up) */return;case 'range-clip': {- /* ⇧X: the range is the selected clips' span (CapCut's 以片段选定区域) */+ /* ⇧X: the range is the selected clips' span */if (!selectedBlocks.length) return;take();setMarkedRange({ startMs: Math.min(...selectedBlocks.map((b) => b.startMs)), endMs: Math.max(...selectedBlocks.map((b) => b.endMs)) });@@ -2353,7 +2408,7 @@ export function ProjectView({ projectId, onProject, onLeave }: {case 'copy-attrs': if (!selectedBlocks.length) return; take(); if (once) copyAttrs(selectedBlocks); return;case 'paste-attrs': if (!selectedBlocks.length) return; take(); if (once) askPasteAttrs(selectedBlocks); return;case 'speed': {- /* ⌘R: the selected clip's speed, in the inspector (CapCut's 变速 panel) */+ /* ⌘R: the selected clip's speed, in the inspector */if (selectedBlocks.length !== 1 || !once) return;take();setInspectorContent('selection');@@ -2362,7 +2417,7 @@ export function ProjectView({ projectId, onProject, onLeave }: {return;}case 'detach-audio': {- /* ⇧⌃S: the selected video's sound on a track of its own (CapCut's 分离音频) */+ /* ⇧⌃S: the selected video's sound on a track of its own */const video = selectedBlocks.find((b) => b.kind === 'video' && b.clipId);if (!video || !once) return;take();@@ -2386,12 +2441,15 @@ export function ProjectView({ projectId, onProject, onLeave }: {case 'select-left': case 'select-right': take(); if (once) commands.selectSide(cmd === 'select-left' ? -1 : 1); return;case 'ripple-start': take(); if (once) commands.rippleTrimStart(); return;case 'ripple-end': take(); if (once) commands.rippleTrimEnd(); return;- case 'toggle-snap': case 'toggle-magnet': case 'toggle-linkage': {+ case 'toggle-snap': case 'toggle-magnet': case 'toggle-linkage': case 'toggle-preview-axis': {take();if (!once) return;- const pref = cmd === 'toggle-snap' ? 'snap' : cmd === 'toggle-magnet' ? 'magnet' : 'linkage';+ const pref = cmd === 'toggle-snap' ? 'snap' : cmd === 'toggle-magnet' ? 'magnet' : cmd === 'toggle-linkage' ? 'linkage' : 'previewAxis';const on = !readTimelinePrefs()[pref];- if (pref === 'snap') commands.toggleSnap(); else if (pref === 'magnet') commands.toggleMagnet(); else commands.toggleLinkage();+ if (pref === 'snap') commands.toggleSnap();+ else if (pref === 'magnet') commands.toggleMagnet();+ else if (pref === 'linkage') commands.toggleLinkage();+ else commands.togglePreviewAxis();toast.show(`${t(`timeline.${pref}`)} · ${t(`timeline.${pref}${on ? 'On' : 'Off'}`)}`);return;}@@ -2425,17 +2483,26 @@ export function ProjectView({ projectId, onProject, onLeave }: {/* the app's "New Tab" (its menu): the projects, to pick what the new tab shows */React.useEffect(() => studioHost?.tabs?.onPick(() => setProjectsOpen(true)), []);React.useEffect(() => { if (title) studioHost?.tabs?.report({ title }); }, [title]);- const commitTitle = async () => {+ const renameError = (e: unknown, name: string) =>+ toast.showError(e instanceof ApiError && e.status === 409 ? t('projects.renameTaken').replace('{name}', name) : t('project.renameFailed'));+ const commitTitle = async (draft = titleDraft) => {setRenaming(false);- const next = titleDraft.trim();- if (!next || next === title || !loaded) return;+ const next = draft.trim();+ if (!next || next === title || !loaded) return false;setLoaded({ ...loaded, project: { ...loaded.project, name: next } });- try { const project = await api.rename(projectId, next); setLoaded((l) => (l ? { ...l, project } : l)); }+ try { const project = await api.rename(projectId, next); setLoaded((l) => (l ? { ...l, project } : l)); return true; }catch (e) {setLoaded((l) => (l ? { ...l, project: { ...l.project, name: title } } : l));- toast.showError(e instanceof ApiError && e.status === 409 ? t('projects.renameTaken').replace('{name}', next) : t('project.renameFailed'));+ renameError(e, next);+ return false;}};+ /* a tab renamed in the tab strip: this page's project, as its title is, or another tab's (its page hears it) */+ const renameTab = async (id: string, name: string) => {+ if (id === projectId) return commitTitle(name);+ try { await api.rename(id, name); return true; }+ catch (e) { renameError(e, name); return false; }+ };const [projectsOpen, setProjectsOpen] = React.useState(false);/* the examples over the film, opened from the app's chat *//* the Community over the film: closed, open on its list (true), or on one skill's or example's page */@@ -2571,26 +2638,7 @@ export function ProjectView({ projectId, onProject, onLeave }: {</Tooltip>}</div>{inTabs ? (- <TabStrip onRename={startRename} onNew={() => setProjectsOpen(true)} editor={renaming ? (- <input- autoFocus- value={titleDraft}- onChange={(e) => setTitleDraft(e.target.value)}- onBlur={() => void commitTitle()}- onKeyDown={(e) => {- if (e.key === 'Enter') void commitTitle();- if (e.key === 'Escape') { setTitleDraft(title); setRenaming(false); }- }}- onClick={(e) => e.stopPropagation()}- /* opened by a double-click: all its words selected, to type over or to pick from */- onFocus={(e) => e.currentTarget.select()}- onMouseDown={(e) => e.stopPropagation()}- onDoubleClick={(e) => e.stopPropagation()}- placeholder={t('project.untitled')}- maxLength={TITLE_MAX_CHARS}- className="min-w-0 flex-1 bg-transparent text-[12.5px] font-medium text-[var(--text)] outline-none"- />- ) : undefined} />+ <TabStrip onRename={renameTab} onNew={() => setProjectsOpen(true)} maxLength={TITLE_MAX_CHARS} />) : <div className="min-w-0 flex-1" />}<div ref={headerOpsRef} className="pointer-events-auto flex min-w-0 items-center justify-end gap-1"><ProjectLayoutMenu className={TOP_BTN}@@ -2602,6 +2650,12 @@ export function ProjectView({ projectId, onProject, onLeave }: {hostPanel={hostPanel ? { label: hostPanel.label, open: hostPanel.open, onChange: hostPanel.setOpen } : null} /><ProjectHistoryButton open={historyOpen} onClick={openHistory} className={TOP_BTN} /><ProjectMenu className={TOP_BTN}+ /* the film at the playhead, drawn by Studio as the projects list will show it */+ onCoverFromFrame={() => {+ if (previewError || totalMs <= 0) { toast.show(t('project.filmNotReady')); return; }+ void api.setCover(projectId, { ms: Math.max(0, Math.min(totalMs - 1, timeRef.current)) })+ .then(() => toast.show(t('projects.coverSet')), () => toast.showError(t('projects.coverFailed')));+ }}onExport={() => {if (previewError) toast.showError(`${t('project.filmCannotExport')} ${previewError}`);else if (totalMs > 0) setExportOpen(true);@@ -2736,8 +2790,8 @@ export function ProjectView({ projectId, onProject, onLeave }: {width: `${(frameBox.inner.w / frameBox.w) * 100}%`,height: `${(frameBox.inner.h / frameBox.h) * 100}%`,}}>- <Preview ref={preview} folder={folder} stage={shownStage} time={() => player.current.time()}- onInfo={onInfo} onKey={previewKey} onError={setPreviewError}>+ <Preview ref={preview} folder={folder} stage={shownStage} time={() => player.current.time()} fps={exactRate(projectFps)}+ onInfo={onInfo} onKey={previewKey} onError={setPreviewError} onPlayed={onPlayed}>{!fullscreen ? (<FilmStageSelectpreviewRef={preview}@@ -2776,6 +2830,12 @@ export function ProjectView({ projectId, onProject, onLeave }: {</div>{/* a clip under the playhead whose file is gone plays as nothing (src/timeline.mjs, film-missing):said here, over the picture, with what to do */}+ {statsOn && playing && played ? (+ <div data-playback-stats="" className="pointer-events-none absolute right-2 top-2 z-10 rounded-[4px] bg-black/75 px-2 py-1 font-mono text-[11px] tabular-nums text-white">+ {t('viewer.stats').replace('{fps}', String(Math.round((played.drawn * 1000) / Math.max(1, played.ms)))).replace('{late}', String(Math.round((played.late * 1000) / Math.max(1, played.ms))))}+ {played.rendered ? ` · ${t('viewer.statsRendered')}` : ''}+ </div>+ ) : null}{missingHere && !fullscreen ? (<div data-preview-missing="" className="pointer-events-none absolute left-2 top-2 z-10 max-w-[80%] truncate rounded-[4px] bg-black/75 px-2 py-1 text-[11px] text-white">{t('project.previewMissing').replace('{file}', missingHere)}@@ -2789,9 +2849,9 @@ export function ProjectView({ projectId, onProject, onLeave }: {{fullscreen ? <div className="absolute inset-0 z-[5]" aria-hidden /> : null}{/* subtitles sit on the frame, not on the film: their place is a share of the frame, so a 9:16frame puts them on its own bottom (the bar), not pushed up with the picture */}- <LiveTime clock={playing ? clock : null} timeMs={timeMs}>{(liveMs) => (+ <LiveTime clock={playing ? clock : null} timeMs={timeMs} step={subtitleStep}>{(liveMs) => (<SubtitleOverlay- cues={captionsOn ? subs.cues : []}+ cues={shownCues}timeMs={liveMs}style={filmSubtitleStyleFor(subs.style, frameBox)}onMove={fullscreen ? undefined : subs.move}@@ -2832,7 +2892,7 @@ export function ProjectView({ projectId, onProject, onLeave }: {) : null}<ViewerBartimeMs={timeMs}- clock={playing ? clock : null}+ clock={clock}totalMs={totalMs}playing={playing}onPlayPause={toggle}@@ -2942,9 +3002,11 @@ export function ProjectView({ projectId, onProject, onLeave }: {timeMs={timeMs}clock={playing ? clock : null}playing={playing}+ previewBar={previewRenders.bar}onSeek={(ms) => seek(ms)}onScrubPreview={scrubPreview}onScrubCommit={scrubCommit}+ onHoverPreview={hoverPreview}onRemove={removeBlock}onRemoveMany={removeBlocks}onSplit={splitBlocks}@@ -2972,7 +3034,7 @@ export function ProjectView({ projectId, onProject, onLeave }: {{...tools.timeline}/></div>- {/* the audio meters, beside the timeline as Premiere's */}+ {/* the audio meters, beside the timeline */}<div className="absolute inset-y-0 right-0"><AudioMeters levels={tools.levels} playing={playing} /></div></div>) : null}diff --git a/packages/openfilm/studio/ui/src/components/ProjectsLibrary.tsx b/packages/openfilm/studio/ui/src/components/ProjectsLibrary.tsxindex 70a8bea..0be5652 100644--- a/packages/openfilm/studio/ui/src/components/ProjectsLibrary.tsx+++ b/packages/openfilm/studio/ui/src/components/ProjectsLibrary.tsx@@ -18,7 +18,7 @@import React from 'react';import { createPortal } from 'react-dom';import { Loader2 } from 'lucide-react';-import { api, ApiError } from '@/api';+import { api, ApiError, LIBRARY_EVENT } from '@/api';import { useT } from '@/i18n';import { folderApi, folderCounts, folderTrail, type ProjectFolder } from '@/lib/project-folders';import { studioHost } from '@/lib/host';@@ -27,11 +27,12 @@ import { ConfirmDialog } from './ConfirmDialog';import { ProjectsView, type LibraryProject } from './ProjectsView';import { FolderBrowserDialog, GitHubDialog } from './ProjectSources';import { ExamplesGallery, TitleSwitch } from './ExamplesGallery';+import { ProjectCoverContext, posterUrl, useProjectCover } from './ProjectCover';-/* each card's picture: the film's middle frame, drawn by Studio (cached until film.html changes); none for a project- whose folder is gone (its card shows its color) */-const posterOf = (p: LibraryProject) => (p.missing ? undefined : `/api/projects/${encodeURIComponent(p.id)}/poster`);+/* each card's picture: its own cover, else the film's middle frame, drawn by Studio (cached until film.html changes);+ none for a project whose folder is gone (its card shows its color) */+const posterOf = (p: LibraryProject) => (p.missing ? undefined : posterUrl(p));function useProjectLibrary(open: boolean) {const t = useT();@@ -64,9 +65,28 @@ function useProjectLibrary(open: boolean) {const reloadFolders = React.useCallback(() => {void folderApi.list().then(setFolders, () => {});- void api.projects().then((list) => setProjects((cur) => list.map((p) => ({ ...p, poster: cur.find((c) => c.id === p.id)?.poster ?? posterOf(p) }))), () => {});+ /* a card keeps the picture it shows, unless its cover changed meanwhile (from the editor, or another window) */+ void api.projects().then((list) => setProjects((cur) => list.map((p) => {+ const shown = cur.find((c) => c.id === p.id);+ return { ...p, poster: shown && shown.cover === p.cover ? shown.poster ?? posterOf(p) : posterOf(p) };+ })), () => {});}, []);+ /** A project's cover set or taken off (null): its card asks for its picture again. */+ const coverChanged = React.useCallback((id: string, cover: number | null) => {+ setProjects((list) => list.map((p) => {+ if (p.id !== id) return p;+ const next = { ...p, cover: cover ?? undefined };+ return { ...next, poster: posterOf(next) };+ }));+ }, []);+ /* the library moved (Settings): its projects, where they are now */+ React.useEffect(() => {+ if (!open) return undefined;+ window.addEventListener(LIBRARY_EVENT, reloadFolders);+ return () => window.removeEventListener(LIBRARY_EVENT, reloadFolders);+ }, [open, reloadFolders]);+/*** How many of `ids` an agent is working in right now, read afresh (an agent may have started or finished since the* list was read); each card's mark follows.@@ -157,7 +177,7 @@ function useProjectLibrary(open: boolean) {}}- return { projects, folders, loaded, error, flash, reload: reloadFolders, agentRunning, workingIn, deleteProjects, renameProject, createFolder, renameFolder, moveProject, deleteFolder };+ return { projects, folders, loaded, error, flash, reload: reloadFolders, agentRunning, workingIn, deleteProjects, renameProject, createFolder, renameFolder, moveProject, deleteFolder, coverChanged };}/** The launcher's two views: the person's projects, and the examples to start from (ExamplesGallery). */@@ -192,6 +212,8 @@ export function ProjectsPopover({}) {const t = useT();const lib = useProjectLibrary(open);+ const { flash } = lib;+ const cover = useProjectCover(lib.coverChanged, React.useCallback(() => flash(t('projects.coverFailed')), [flash, t]));/* each time it opens: the projects (the examples are a switch away) */const [view, setView] = React.useState<LauncherView>('projects');React.useEffect(() => { if (open) setView('projects'); }, [open]);@@ -345,6 +367,7 @@ export function ProjectsPopover({onDrop={onDrop}><div className="relative flex min-h-0 flex-1 flex-col overflow-hidden">+ {cover.picker}{view === 'examples' ? (<ExamplesGallerymode="start"@@ -353,6 +376,7 @@ export function ProjectsPopover({onStart={(example) => setGithub({ url: example.url, start: true, title: example.title })}/>) : lib.loaded ? (+ <ProjectCoverContext.Provider value={cover.actions}><ProjectsViewheading={<LauncherSwitch view={view} onView={showView} />}projects={lib.projects}@@ -382,6 +406,7 @@ export function ProjectsPopover({onMoveToFolder={lib.moveProject}onClose={onClose}/>+ </ProjectCoverContext.Provider>) : (<div className="flex flex-1 items-center justify-center text-[var(--text-muted)]"><Loader2 size={18} className="animate-spin" />diff --git a/packages/openfilm/studio/ui/src/components/ProjectsView.tsx b/packages/openfilm/studio/ui/src/components/ProjectsView.tsxindex ed3b98d..40e0350 100644--- a/packages/openfilm/studio/ui/src/components/ProjectsView.tsx+++ b/packages/openfilm/studio/ui/src/components/ProjectsView.tsx@@ -31,10 +31,11 @@ import type { Example } from '@/lib/project-sources';import { ExamplesSection } from './ProjectSources';import { useLanguage, useT, type Language } from '@/i18n';import { limitTitleWidth, TITLE_MAX_WIDTH } from '@/lib/title';-import type { Project } from '@/api';+import { api, type Project } from '@/api';import { folderCounts, folderPosters, folderTrail, parentOf, visibleProjects, type LibrarySort, type ProjectFolder } from '@/lib/project-folders';import { ContextMenu } from './ContextMenu';import { ProjectMenu } from './ProjectMenu';+import { ProjectCoverContext } from './ProjectCover';import { Tooltip } from './Tooltip';/**@@ -754,7 +755,10 @@ function MissingActions({ onLocate, onRemove, compact = false }: { onLocate: ());}-/** A card's or row's "…". A project whose folder is gone can be located or leave the list: there is nothing to open or rename. */+/**+ * A card's or row's "…", with Reveal to show where its folder is. A project whose folder is gone can be located or+ * leave the list: there is nothing to open, rename or reveal.+ */function ItemMenu({project,onOpen,@@ -765,6 +769,7 @@ function ItemMenu({onDelete,size,}: Pick<ItemProps, 'project' | 'onOpen' | 'onStartRename' | 'onStartSelect' | 'onMoveToFolder' | 'onLocate' | 'onDelete'> & { size: number }) {+ const cover = React.useContext(ProjectCoverContext);if (project.missing) return <ProjectMenu onLocate={onLocate} onRemove={onDelete} size={size} />;return (<ProjectMenu@@ -772,6 +777,9 @@ function ItemMenu({onRename={onStartRename}onSelect={onStartSelect}onMoveToFolder={onMoveToFolder}+ onChangeCover={cover ? () => cover.change(project) : undefined}+ onRestoreCover={cover && project.cover ? () => cover.restore(project) : undefined}+ onReveal={() => void api.revealProject(project.id).catch(() => {})}onDelete={onDelete}size={size}/>diff --git a/packages/openfilm/studio/ui/src/components/SourcePreview.tsx b/packages/openfilm/studio/ui/src/components/SourcePreview.tsxindex 282155c..f5fdeba 100644--- a/packages/openfilm/studio/ui/src/components/SourcePreview.tsx+++ b/packages/openfilm/studio/ui/src/components/SourcePreview.tsx@@ -1,6 +1,6 @@/*** The viewer showing one media file instead of the film: what an editor's source monitor does when a clip is picked- * in the media pane (CapCut, DaVinci). Video and sound play with their own playhead; a still is shown. The film stays+ * in the media pane. Video and sound play with their own playhead; a still is shown. The film stays* loaded behind it, so going back costs nothing: Esc, or picking anything on the timeline (the host clears it).** While it is up the keys are its own, as a source monitor's: I and O mark the part of the file to use (X lets the@@ -8,10 +8,11 @@*/import React from 'react';import { Expand } from 'lucide-react';+import { anchorTime, type Anchor } from '@/editor/player';import { useT } from '@/i18n';import { STILL_DROP_MS } from '@/lib/asset-timeline';import type { SourceRange } from '@/lib/media-place';-import { formatTimecode, snapToFrame } from '@/lib/timecode';+import { exactRate, formatTimecode, snapToFrame, useTimecodeFps } from '@/lib/timecode';import { type MediaSources, type WorkspaceResource } from '@/lib/workspace-resources';import { isTypingTarget } from './typing-target';import { KIND_ICON, MediaPreview } from './MediaPreview';@@ -277,16 +278,20 @@ function MediaPreviewPane({ file, sources, onClose, onPlace }: SourcePreviewProp);}+/** Clock readings asked of a page as it comes up: the one answered soonest says best where its clock is. */+const CLOCK_PINGS = 5;+/*** One web page on its own, the way the preview plays the film: on the film's origin (a page is its author's code; on- * the editor's origin it could reach the editor), with Studio's bridge in it, driven by messages (seek t → frame(t)).+ * the editor's origin it could reach the editor), with Studio's bridge in it, driven by messages. Still, it is told the+ * moment to draw (seek t → frame(t)); playing, the line it plays on, and it draws its own frames from it, on the+ * project's frame grid (studio/server/bridge.js `play`): no message a frame, so a busy editor does not hold the picture.*/function PagePreview({ file, sources, onClose, onPlace }: SourcePreviewProps) {const t = useT();const rootRef = React.useRef<HTMLDivElement>(null);const frameRef = React.useRef<HTMLIFrameElement>(null);const boxRef = React.useRef<HTMLDivElement>(null);- const clockRef = React.useRef({ base: 0, at: 0 });const seq = React.useRef(0);const surface = sources.pageSurface?.(file) ?? null;const origin = React.useMemo(() => {@@ -297,25 +302,60 @@ function PagePreview({ file, sources, onClose, onPlace }: SourcePreviewProps) {const [playing, setPlaying] = React.useState(false);const [time, setTime] = React.useState(0);const [scale, setScale] = React.useState(1);+ /* playing draws each frame of the project's rate, as the film would draw the page, none between */+ const fps = exactRate(useTimecodeFps());+ const fpsRef = React.useRef(fps);+ fpsRef.current = fps;- const draw = React.useCallback((at: number) => {+ const post = React.useCallback((message: object) => {if (!origin) return;- frameRef.current?.contentWindow?.postMessage({ source: 'openfilm-studio', type: 'seek', seq: ++seq.current, t: Math.max(0, at) }, origin);+ frameRef.current?.contentWindow?.postMessage({ source: 'openfilm-studio', ...message }, origin);}, [origin]);+ /* the picture at t: at the very end of a page with a duration its last frame (it draws below its duration) */+ const end = size?.duration ? size.duration - 1e-3 : Infinity;+ const draw = React.useCallback((at: number) => {+ post({ type: 'seek', seq: ++seq.current, t: Math.max(0, Math.min(at, end)) });+ }, [post, end]);+ /*+ * Playing: the line the page plays on (null while still), on this page's clock. The page's clock starts elsewhere+ * (another document, another process), so it is told the line by how far its clock is from this one, read with a+ * few pings and taken from the one answered soonest (the time a message takes is the error, a fraction of a+ * millisecond).+ */+ const line = React.useRef<Anchor | null>(null);+ const clock = React.useRef<{ offset: number; rtt: number } | null>(null);+ const tellPlay = React.useCallback(() => {+ const a = line.current;+ if (!a) return;+ post({ type: 'play', t: a.t, at: a.at + (clock.current?.offset ?? 0), rate: a.rate, fps: fpsRef.current });+ }, [post]);React.useEffect(() => {const onMessage = (event: MessageEvent) => {- const data = event.data as { source?: unknown; type?: unknown; duration?: unknown; width?: unknown; height?: unknown } | null;+ const data = event.data as {+ source?: unknown; type?: unknown; duration?: unknown; width?: unknown; height?: unknown; origin?: unknown; ping?: unknown; now?: unknown;+ } | null;if (event.source !== frameRef.current?.contentWindow || event.origin !== origin || data?.source !== 'openfilm-film') return;if (data.type === 'error') { setFailed(true); return; }+ if (data.type === 'clock') {+ const rtt = performance.now() - Number(data.ping);+ if (!(rtt >= 0) || (clock.current && clock.current.rtt <= rtt)) return;+ clock.current = { offset: Number(data.now) - (Number(data.ping) + rtt / 2), rtt };+ /* playing on it: told the line again, on its clock as now read */+ tellPlay();+ return;+ }if (data.type !== 'ready') return;const num = (v: unknown, fallback: number) => (typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : fallback);setSize({ w: num(data.width, 1920), h: num(data.height, 1080), duration: num(data.duration, 0) });+ /* where its clock is: first by where each clock started, then by pings */+ clock.current = Number(data.origin) > 0 ? { offset: performance.timeOrigin - Number(data.origin), rtt: Infinity } : null;+ for (let i = 0; i < CLOCK_PINGS; i++) setTimeout(() => post({ type: 'clock', ping: performance.now() }), 40 * i);draw(0);};window.addEventListener('message', onMessage);return () => window.removeEventListener('message', onMessage);- }, [draw, origin]);+ }, [draw, origin, post, tellPlay]);React.useEffect(() => {const box = boxRef.current;@@ -335,10 +375,22 @@ function PagePreview({ file, sources, onClose, onPlace }: SourcePreviewProps) {const play = React.useCallback(() => {if (!size) return;const from = time >= duration - 0.05 ? 0 : time;- clockRef.current = { base: from, at: performance.now() };+ line.current = { t: from, at: performance.now(), rate: 1 };+ tellPlay();setPlaying(true);- }, [time, duration, size]);- const pause = React.useCallback(() => setPlaying(false), []);+ }, [time, duration, size, tellPlay]);+ /* still at `at` (a pause, the end, a scrub): the page stops playing and draws that moment */+ const still = React.useCallback((at: number) => {+ line.current = null;+ setPlaying(false);+ setTime(at);+ draw(at);+ }, [draw]);+ /* stopped on the frame being shown: the timecode, the picture and a mark all mean that frame */+ const pause = React.useCallback(() => {+ const a = line.current;+ if (a) still(Math.min(duration, snapToFrame(anchorTime(a, performance.now()) * 1000) / 1000));+ }, [duration, still]);/* picked to be seen: it plays from the start once the page is ready (once: a pause stays a pause) */const started = React.useRef(false);React.useEffect(() => {@@ -348,20 +400,21 @@ function PagePreview({ file, sources, onClose, onPlace }: SourcePreviewProps) {}, [size, play]);const toggle = React.useCallback(() => (playing ? pause() : play()), [playing, play, pause]);+ /* the page draws itself while it plays; the timecode and the scrub line follow its line here, to its end */React.useEffect(() => {if (!playing) return;let raf = 0;const step = () => {- const now = clockRef.current.base + (performance.now() - clockRef.current.at) / 1000;- const at = Math.min(now, duration);+ const a = line.current;+ if (!a) return;+ const at = Math.min(anchorTime(a, performance.now()), duration);+ if (at >= duration) { still(duration); return; }setTime(at);- draw(at);- if (at >= duration) { setPlaying(false); return; }raf = requestAnimationFrame(step);};raf = requestAnimationFrame(step);return () => cancelAnimationFrame(raf);- }, [playing, duration, draw]);+ }, [playing, duration, still]);React.useEffect(() => {const onKey = (e: KeyboardEvent) => {@@ -395,7 +448,7 @@ function PagePreview({ file, sources, onClose, onPlace }: SourcePreviewProps) {duration={duration}playing={playing}onToggle={toggle}- onSeek={(v) => { setPlaying(false); setTime(v); draw(v); }}+ onSeek={still}disabled={!size}marks={marks}onFullscreen={() => toggleFullscreen(rootRef.current)}diff --git a/packages/openfilm/studio/ui/src/components/StageMaskOverlay.tsx b/packages/openfilm/studio/ui/src/components/StageMaskOverlay.tsxindex 70a5d46..6a3a56f 100644--- a/packages/openfilm/studio/ui/src/components/StageMaskOverlay.tsx+++ b/packages/openfilm/studio/ui/src/components/StageMaskOverlay.tsx@@ -1,6 +1,6 @@/*** A mask edited on the picture (the inspector's Mask › Edit on picture): its outline over the clip or layer in hand,- * turned with it, and CapCut's handles — a press inside moves it (anywhere in the box for a line or a band), the squares+ * turned with it, and its handles — a press inside moves it (anywhere in the box for a line or a band), the squares* resize it, the round knob above turns it, the knob below pulled outward feathers it. The geometry is lib/stage-mask's.** A drag shows on the picture as it goes (the session's preview, a frame at a time) and is written once, at thediff --git a/packages/openfilm/studio/ui/src/components/StageTransformFrame.tsx b/packages/openfilm/studio/ui/src/components/StageTransformFrame.tsxindex bc3637c..cbdbc1b 100644--- a/packages/openfilm/studio/ui/src/components/StageTransformFrame.tsx+++ b/packages/openfilm/studio/ui/src/components/StageTransformFrame.tsx@@ -1,5 +1,5 @@/**- * The frame of the thing in hand on the stage, shared by a whole clip and a layer inside one (Figma's look).+ * The frame of the thing in hand on the stage, shared by a whole clip and a layer inside one.** A 1px blue border and white corner squares with a blue edge (scale); an invisible ring outside the corners turns the* pointer into the rotate cursor; invisible strips on the edges stretch one side (a layer's override scale has x and y;@@ -41,7 +41,7 @@ const CORNER_AT: Record<FrameCorner, { x: 0 | 1; y: 0 | 1 }> = {};/*- * The rotate cursor: a quarter arc with an arrow at each end (Figma's; browsers have no such cursor). Drawn for the+ * The rotate cursor: a quarter arc with an arrow at each end (browsers have no such cursor). Drawn for the* top-right corner; other corners and turned frames turn it, cached in 15° steps.*/const ROTATE_CURSORS = new Map<number, string>();@@ -103,7 +103,7 @@ export function StageTransformFrame({const h = Math.max(frame.h, 1);/** Handles sit on a frame at least HANDLE_BOX_MIN big: on something tiny (an icon, a thin line) corner squares on its- * own edges would pile up over it. As in Figma the blue border keeps the true size and the handles go on the ring+ * own edges would pile up over it. The blue border keeps the true size and the handles go on the ring* outside, the whole middle still draggable.*/const hw = Math.max(w, HANDLE_BOX_MIN);@@ -204,7 +204,7 @@ export function StageTransformFrame({);}) : null}</div>- {/* shown while dragging too: the frame moves and its size changes, and the label follows (as in Figma) */}+ {/* shown while dragging too: the frame moves and its size changes, and the label follows */}{label ? <FrameLabel frame={{ ...frame, w: hw, h: hh }} text={label} {...(bounds ? { bounds } : {})} /> : null}</>);diff --git a/packages/openfilm/studio/ui/src/components/SubtitleRow.tsx b/packages/openfilm/studio/ui/src/components/SubtitleRow.tsxindex 7cee1e4..7d46384 100644--- a/packages/openfilm/studio/ui/src/components/SubtitleRow.tsx+++ b/packages/openfilm/studio/ui/src/components/SubtitleRow.tsx@@ -1,5 +1,5 @@/**- * The subtitle row: the film's subtitles as blocks under the ruler, timed by hand as CapCut's caption track is.+ * The subtitle row: the film's subtitles as blocks under the ruler, timed by hand.** drag a cue's edge its start or end (never over a neighbor, snapping to clip edges, cues and the playhead)* drag a cue moves it, its length kept@@ -348,64 +348,67 @@ export const SubtitleRow = React.forwardRef<SubtitleRowHandle, {onContextMenu={(e) => openMenu(e, null)}><div ref={innerRef} className="absolute inset-y-0 left-0" style={{ width, transform: `translate3d(${-scrollLeft}px,0,0)` }}>- {cues.map((cue) => {- const key = cueKey(cue);- const shown = drag?.key === key ? drag : held?.key === key ? held : { startMs: cue.startMs, endMs: cueEnd(cue) };- const left = shown.startMs * pxPerMs;- const w = Math.max(2, (shown.endMs - shown.startMs) * pxPerMs);- const picked = selected === key;- const edge = Math.min(EDGE_PX, w / 4);- return (- <div- key={key}- data-subtitle-cue={cue.startMs}- title={cue.text}- className="absolute top-[3px] bottom-[3px] cursor-grab overflow-hidden rounded-[3px] active:cursor-grabbing"- style={{- left, width: w, background: 'var(--tl-caption)',- boxShadow: picked ? '0 0 0 1.5px var(--tl-select)' : undefined,- zIndex: picked ? 2 : 1,- }}- onPointerDown={(e) => startDrag(e, cue, 'move')}- onDoubleClick={(e) => { e.stopPropagation(); setEditing({ key, text: cue.text }); }}- onContextMenu={(e) => openMenu(e, cue)}- >- <span className="pointer-events-none absolute inset-0 flex items-center truncate px-1.5 text-[10.5px] leading-none text-white/95">- {w > 14 ? cue.text : null}- </span>- <span role="presentation" data-trim="start" className="absolute inset-y-0 left-0 z-[2] cursor-ew-resize" style={{ width: edge }}- onPointerDown={(e) => startDrag(e, cue, 'start')} />- <span role="presentation" data-trim="end" className="absolute inset-y-0 right-0 z-[2] cursor-ew-resize" style={{ width: edge }}- onPointerDown={(e) => startDrag(e, cue, 'end')} />- </div>- );- })}- {editing ? (() => {- const cue = cues.find((c) => cueKey(c) === editing.key);- if (!cue) return null;- return (- <input- autoFocus- data-subtitle-edit=""- aria-label={t('subtitleRow.edit')}- value={editing.text}- onChange={(e) => setEditing({ ...editing, text: e.target.value })}- onFocus={(e) => e.currentTarget.select()}- onKeyDown={(e) => {- e.stopPropagation();- if (e.key === 'Enter') { e.preventDefault(); commitText(); }- if (e.key === 'Escape') { e.preventDefault(); setEditing(null); }- }}- onBlur={commitText}- onPointerDown={(e) => e.stopPropagation()}- className="absolute top-[3px] z-10 h-[24px] rounded-[3px] bg-[var(--bg)] px-1.5 text-[11.5px] text-[var(--text)] outline-none ring-1 ring-[var(--tl-accent)]"- style={{ left: cue.startMs * pxPerMs, width: Math.max(180, cue.durMs * pxPerMs) }}- />- );- })() : null}- {drag?.guideMs != null ? (- <div aria-hidden className="pointer-events-none absolute inset-y-0 z-[3] w-px bg-[var(--tl-accent)]" style={{ left: drag.guideMs * pxPerMs }} />- ) : null}+ {/* scaled while a zoom gesture goes on (see Timeline's zoom layers) */}+ <div data-zoom-layer="content" className="absolute inset-0">+ {cues.map((cue) => {+ const key = cueKey(cue);+ const shown = drag?.key === key ? drag : held?.key === key ? held : { startMs: cue.startMs, endMs: cueEnd(cue) };+ const left = shown.startMs * pxPerMs;+ const w = Math.max(2, (shown.endMs - shown.startMs) * pxPerMs);+ const picked = selected === key;+ const edge = Math.min(EDGE_PX, w / 4);+ return (+ <div+ key={key}+ data-subtitle-cue={cue.startMs}+ title={cue.text}+ className="absolute top-[3px] bottom-[3px] cursor-grab overflow-hidden rounded-[3px] active:cursor-grabbing"+ style={{+ left, width: w, background: 'var(--tl-caption)',+ boxShadow: picked ? '0 0 0 1.5px var(--tl-select)' : undefined,+ zIndex: picked ? 2 : 1,+ }}+ onPointerDown={(e) => startDrag(e, cue, 'move')}+ onDoubleClick={(e) => { e.stopPropagation(); setEditing({ key, text: cue.text }); }}+ onContextMenu={(e) => openMenu(e, cue)}+ >+ <span className="pointer-events-none absolute inset-0 flex items-center truncate px-1.5 text-[10.5px] leading-none text-white/95">+ {w > 14 ? cue.text : null}+ </span>+ <span role="presentation" data-trim="start" className="absolute inset-y-0 left-0 z-[2] cursor-ew-resize" style={{ width: edge }}+ onPointerDown={(e) => startDrag(e, cue, 'start')} />+ <span role="presentation" data-trim="end" className="absolute inset-y-0 right-0 z-[2] cursor-ew-resize" style={{ width: edge }}+ onPointerDown={(e) => startDrag(e, cue, 'end')} />+ </div>+ );+ })}+ {editing ? (() => {+ const cue = cues.find((c) => cueKey(c) === editing.key);+ if (!cue) return null;+ return (+ <input+ autoFocus+ data-subtitle-edit=""+ aria-label={t('subtitleRow.edit')}+ value={editing.text}+ onChange={(e) => setEditing({ ...editing, text: e.target.value })}+ onFocus={(e) => e.currentTarget.select()}+ onKeyDown={(e) => {+ e.stopPropagation();+ if (e.key === 'Enter') { e.preventDefault(); commitText(); }+ if (e.key === 'Escape') { e.preventDefault(); setEditing(null); }+ }}+ onBlur={commitText}+ onPointerDown={(e) => e.stopPropagation()}+ className="absolute top-[3px] z-10 h-[24px] rounded-[3px] bg-[var(--bg)] px-1.5 text-[11.5px] text-[var(--text)] outline-none ring-1 ring-[var(--tl-accent)]"+ style={{ left: cue.startMs * pxPerMs, width: Math.max(180, cue.durMs * pxPerMs) }}+ />+ );+ })() : null}+ {drag?.guideMs != null ? (+ <div aria-hidden className="pointer-events-none absolute inset-y-0 z-[3] w-px bg-[var(--tl-accent)]" style={{ left: drag.guideMs * pxPerMs }} />+ ) : null}+ </div></div>{menu ? <ContextMenu x={menu.x} y={menu.y} items={menu.items} onClose={() => setMenu(null)} /> : null}</div>diff --git a/packages/openfilm/studio/ui/src/components/TabStrip.tsx b/packages/openfilm/studio/ui/src/components/TabStrip.tsxindex d9e1a45..720625f 100644--- a/packages/openfilm/studio/ui/src/components/TabStrip.tsx+++ b/packages/openfilm/studio/ui/src/components/TabStrip.tsx@@ -3,17 +3,23 @@* opens the projects window to pick the project a new tab shows. Tabs are the bar's full height, square, side by side* between hairlines; the one in front takes the panes' color. A tab says what is happening in it: an agent at work (a* spinner), a question waiting for the person (a dot), an export (its percent). A tab is shown by a click, closed by- * its × or a middle click, moved by dragging; this page's own tab, double-clicked, renames its project (`onRename`),- * and shows `editor` instead of its title while that happens.+ * its × or a middle click, moved by dragging. Any tab renames its project in place (`onRename`), double-clicked or from+ * its menu: its title becomes a field, its words selected. A tab behind takes the double-click's first click to come to+ * front, so its page renames on the second. A right-click opens a tab's menu: rename it, show its project's folder,+ * close it, the others or those to its right.*/import React from 'react';import { Loader2, Plus, X } from 'lucide-react';import { api } from '@/api';import { useT } from '@/i18n';import { studioHost, type HostTab } from '@/lib/host';+import { tabsToClose } from '@/lib/tab-menu';+import { ContextMenu, type ContextMenuEntry } from './ContextMenu';import { Tooltip } from './Tooltip';const TAB_TYPE = 'application/x-openfilm-tab';+/* a second click this soon after this page's tab came to front ends a double-click begun on it while it was behind */+const DOUBLE_CLICK_MS = 500;/** The tabs as the app has them, live, and which is this page's. */export function useHostTabs() {@@ -30,7 +36,15 @@ export function useHostTabs() {return { tabs, self };}-export function TabStrip({ editor, onRename, onNew }: { editor?: React.ReactNode; onRename?: () => void; onNew?: () => void }) {+/**+ * `onRename`: a tab's project renamed (this page's own or another's); resolves whether it was. `maxLength`: a name's+ * longest.+ */+export function TabStrip({ onRename, onNew, maxLength }: {+ onRename?: (projectId: string, name: string) => Promise<boolean>;+ onNew?: () => void;+ maxLength?: number;+}) {const t = useT();const host = studioHost?.tabs;const { tabs, self } = useHostTabs();@@ -43,9 +57,49 @@ export function TabStrip({ editor, onRename, onNew }: { editor?: React.ReactNode}, [unnamed]);const [dragging, setDragging] = React.useState<string | null>(null);const [over, setOver] = React.useState<number | null>(null);+ /* the tab whose menu is open, and where */+ const [menu, setMenu] = React.useState<{ id: string; x: number; y: number } | null>(null);+ /* the tab being renamed and its words so far; a name on its way, shown until its tab says it */+ const [editing, setEditing] = React.useState<string | null>(null);+ const [draft, setDraft] = React.useState('');+ const [pending, setPending] = React.useState<{ id: string; name: string } | null>(null);+ const frontAt = React.useRef(0);+ const front = tabs.some((tab) => tab.id === self && tab.active);+ React.useEffect(() => { if (front) frontAt.current = Date.now(); }, [front]);if (!host) return null;- const titleOf = (tab: HostTab) => tab.title || names[tab.projectId] || t('project.untitled');+ const titleOf = (tab: HostTab) => (pending?.id === tab.id ? pending.name : tab.title || names[tab.projectId] || t('project.untitled'));+ const startRename = (tab: HostTab) => { if (!onRename || editing === tab.id) return; setDraft(titleOf(tab)); setEditing(tab.id); };+ const commitRename = () => {+ const tab = tabs.find((each) => each.id === editing);+ setEditing(null);+ const next = draft.trim();+ if (!tab || !onRename || !next || next === titleOf(tab)) return;+ setPending({ id: tab.id, name: next });+ void onRename(tab.projectId, next).then(async (ok) => {+ /* another tab's page may be gone (behind too long): the app is told its title, and so is this page's list */+ if (ok && tab.id !== self) {+ setNames((n) => ({ ...n, [tab.projectId]: next }));+ await host.retitle?.(tab.id, next);+ }+ setPending((p) => (p?.id === tab.id ? null : p));+ });+ };++ const menuItems = (id: string): ContextMenuEntry[] => {+ const tab = tabs.find((each) => each.id === id);+ if (!tab) return [];+ const others = tabsToClose(tabs, id, 'others');+ const right = tabsToClose(tabs, id, 'right');+ return [+ { id: 'rename', label: t('projectMenu.rename'), disabled: !onRename, onSelect: () => startRename(tab) },+ { id: 'reveal', label: t('projects.revealFolder'), onSelect: () => { void api.revealProject(tab.projectId).catch(() => {}); } },+ { id: 'sep', separator: true },+ { id: 'close', label: t('tabs.close'), onSelect: () => host.close(id) },+ { id: 'close-others', label: t('tabs.closeOthers'), disabled: others.length === 0, onSelect: () => { for (const other of others) host.close(other.id); } },+ { id: 'close-right', label: t('tabs.closeRight'), disabled: right.length === 0, onSelect: () => { for (const other of right) host.close(other.id); } },+ ];+ };return (<div role="tablist" aria-label={t('tabs.label')} className="flex h-full min-w-0 flex-1 items-stretch">@@ -53,18 +107,23 @@ export function TabStrip({ editor, onRename, onNew }: { editor?: React.ReactNode{tabs.map((tab, i) => {const mine = tab.id === self;/* being renamed: its words are selected and edited like any text, and the tab does not move */- const editing = mine && Boolean(editor);+ const renaming = editing === tab.id;return (<React.Fragment key={tab.id}><divrole="tab"aria-selected={tab.active}tabIndex={-1}- draggable={!editing}+ draggable={!renaming}title={titleOf(tab)}- onClick={() => { if (!tab.active) host.show(tab.id); }}- onDoubleClick={() => { if (mine && !editing) onRename?.(); }}+ onClick={() => {+ if (renaming) return;+ if (!tab.active) host.show(tab.id);+ else if (mine && Date.now() - frontAt.current < DOUBLE_CLICK_MS) startRename(tab);+ }}+ onDoubleClick={() => { if (tab.active) startRename(tab); }}onMouseDown={(e) => { if (e.button === 1) { e.preventDefault(); host.close(tab.id); } }}+ onContextMenu={(e) => { if (renaming) return; e.preventDefault(); setMenu({ id: tab.id, x: e.clientX, y: e.clientY }); }}onDragStart={(e) => { e.dataTransfer.setData(TAB_TYPE, tab.id); e.dataTransfer.effectAllowed = 'move'; setDragging(tab.id); }}onDragEnd={() => { setDragging(null); setOver(null); }}onDragOver={(e) => { if (e.dataTransfer.types.includes(TAB_TYPE)) { e.preventDefault(); setOver(i); } }}@@ -75,7 +134,27 @@ export function TabStrip({ editor, onRename, onNew }: { editor?: React.ReactNode>{tab.working ? <Loader2 size={11} className="shrink-0 animate-spin text-[var(--text-dim)]" /> : null}{tab.asking ? <span className="h-[6px] w-[6px] shrink-0 rounded-full bg-[#ff9f43]" /> : null}- {editing ? editor : <span className="min-w-0 flex-1 truncate font-medium">{titleOf(tab)}</span>}+ {renaming ? (+ <input+ autoFocus+ value={draft}+ onChange={(e) => setDraft(e.target.value)}+ onBlur={commitRename}+ onKeyDown={(e) => {+ if (e.key === 'Enter') commitRename();+ if (e.key === 'Escape') setEditing(null);+ }}+ /* opened by a double-click or the menu: all its words selected, to type over or to pick from */+ onFocus={(e) => e.currentTarget.select()}+ onClick={(e) => e.stopPropagation()}+ onMouseDown={(e) => e.stopPropagation()}+ onDoubleClick={(e) => e.stopPropagation()}+ aria-label={t('projectMenu.rename')}+ placeholder={t('project.untitled')}+ maxLength={maxLength}+ className="min-w-0 flex-1 bg-transparent text-[12.5px] font-medium text-[var(--text)] outline-none selection:bg-[var(--text-selection)]"+ />+ ) : <span className="min-w-0 flex-1 truncate font-medium">{titleOf(tab)}</span>}{tab.exporting != null ? <span className="shrink-0 font-mono text-[10.5px] text-[var(--text-faint)]">{Math.round(tab.exporting * 100)}%</span> : null}<buttontype="button"@@ -90,6 +169,7 @@ export function TabStrip({ editor, onRename, onNew }: { editor?: React.ReactNode);})}</div>+ {menu ? <ContextMenu x={menu.x} y={menu.y} items={menuItems(menu.id)} onClose={() => setMenu(null)} /> : null}{onNew ? (<Tooltip label={t('tabs.new')} side="bottom"><button type="button" aria-label={t('tabs.new')} onClick={onNew}diff --git a/packages/openfilm/studio/ui/src/components/Timeline.tsx b/packages/openfilm/studio/ui/src/components/Timeline.tsxindex dd22ad9..8b753dd 100644--- a/packages/openfilm/studio/ui/src/components/Timeline.tsx+++ b/packages/openfilm/studio/ui/src/components/Timeline.tsx@@ -1,5 +1,5 @@/**- * The timeline under the picture — the multi-track kind, as in CapCut and OpenCut.+ * The timeline under the picture, with as many tracks as the film has.** film.html has tracks of clips; each film.html track is a row here (overlapping clips spread into extra rows, see* layoutTracks), pictures above, sounds below.@@ -7,10 +7,12 @@* There is no play button or timecode here: the transport is under the picture (one place for one thing). The* timeline shows what the film looks like over time and is the one place to drag the playhead. Everything it changes* (move, trim, roll, slip, slide, split, delete, paste, a gap closed) is written back to film.html through the- * callbacks; what an edit does to the other clips is planned in lib/timeline-edit, by the switches in the toolbar: the- * magnet (insert and ripple, or overwrite), sync lock (ripples move every unlocked track) and linked clips.+ * callbacks; what an edit does to the other clips is planned in lib/timeline-edit: a delete or a move leaves a gap and+ * a clip put down covers what is there, unless the edit is a ripple or an insert, which moves what follows on every+ * unlocked track.*/import React from 'react';+import { flushSync } from 'react-dom';import {ClipboardPaste,Copy,@@ -47,6 +49,7 @@ import {Link2Off,Mic,SeparatorVertical,+ TextCursor,BetweenHorizontalStart,ArrowLeftToLine,ArrowRightToLine,@@ -109,7 +112,7 @@ import {} from '@/lib/timeline-edit';import { clipThumbId, indexClipThumbs, thumbIntoOrigin } from '@/lib/thumb-frame';import { THUMB_CELL_PX } from '@/lib/thumb-cache';-import { followOf, useTimelinePrefs, writeTimelinePref } from '@/lib/timeline-prefs';+import { switchesOf, useTimelinePrefs, writeTimelinePref } from '@/lib/timeline-prefs';import { STUDIO_REF_TYPE, type StudioRef } from '@/lib/host';import { orderedRange, rangeLabel, type FilmRange } from '@/lib/studio-refs';import { draftNumbersOf, sameClip, type ChatPoint, type DraftMarks } from '@/lib/chat-marks';@@ -138,11 +141,22 @@ import {type TimelineBlockKind,type TimelineTrack,} from '@/lib/timeline-layout';+import {+ rebaseZoomPreview,+ rowBand,+ rowsNear,+ zoomLayerTransform,+ zoomPreviewAt,+ zoomPreviewIsRest,+ zoomPreviewStep,+ type ZoomPreview,+} from '@/lib/timeline-view';import { OperationHistory, type SessionTimeline } from './OperationHistory';import { BlockThumbs } from './BlockThumbs';import { BlockWaveform } from './BlockWaveform';import { ContextMenu, type ContextMenuEntry } from './ContextMenu';import type { PlaybackClock } from './LiveTime';+import type { PreviewBarRange } from '@/editor/use-preview-renders';import { CaptionsIcon } from './player-controls/controls-bar';import { isTypingTarget } from './typing-target';import { Popover } from './Popover';@@ -205,10 +219,13 @@ const TRACK_H = { visual: 56, audio: 44 } as const;/** The info strip at the top of a clip (name + length). */const INFO_H = 15;/**- * While scrubbing, how often the time is told upward: every 40 ms (25 Hz). Telling it re-renders the editor and seeks- * the preview — the expensive part. The line itself follows every frame from local state.+ * While scrubbing, how often the time is told upward: each frame (the editor seeks the picture there and writes the+ * timecode, and renders the rest of itself a few times a second, see ProjectView's scrubPreview). The line itself+ * follows every frame from local state.*/-const SCRUB_TELL_MS = 40;+const SCRUB_TELL_MS = 15;+/** While scrubbing, how often the timeline renders itself for the time (ms): the line itself moves each frame. */+const SCRUB_STATE_MS = 100;/*** The audio band at the bottom of a video clip: its own sound draws its waveform here; a video without sound keeps* the band empty but still takes its height, so the preview bands of neighboring videos line up. A page or a still@@ -227,6 +244,13 @@ const LANE_EDGE_PX = 5;const TL_VPAD = 10;/** While playing, the timeline pages when the playhead gets this close to the edge. */const FOLLOW_EDGE = 24;+/** A wheel or pinch zoom is laid out once no step has come for this long (ms); until then it is drawn scaled. */+const ZOOM_SETTLE_MS = 120;+/**+ * How far a zoom gesture is drawn scaled before it is laid out on the way: beyond it the stretched text and waveforms+ * blur, and zooming out runs past the clips drawn either side of the view.+ */+const ZOOM_RELAYOUT = 1.5;/** Color by kind of clip: picture, voice, other sound. Muted tones, dark enough for white text and waveforms. */const KIND_COLOR: Record<TimelineBlockKind, string> = {@@ -469,14 +493,9 @@ function trimHit(width: number): number {return Math.min(SELECT_HIT, Math.max(2, Math.floor(width / 4)));}-/** A roll handle's grab width on the cut between clips this wide: 6 px, less where either is narrow. */-function rollHit(width: number): number {- return Math.min(6, Math.max(2, Math.floor(width / 4)));-}--/** Whether a press is on a clip, one of its edges or a cut between two (not the empty track space). */+/** Whether a press is on a clip or one of its edges (not the empty track space). */function overClip(e: React.PointerEvent): boolean {- return Boolean((e.target as Element | null)?.closest?.('[data-block-id],[data-roll]'));+ return Boolean((e.target as Element | null)?.closest?.('[data-block-id]'));}function trackKindHeight(kind: string): number {@@ -575,10 +594,18 @@ export interface TimelineProps {/** The playback clock. With it, playing does not re-render the timeline: the playhead and follow-scroll read it. */clock?: PlaybackClock | null;playing: boolean;+ /** Stretches that play late in the viewer, and their renders (editor/use-preview-renders): a line under the ruler. */+ previewBar?: readonly PreviewBarRange[];/** While dragging the playhead: move the picture, do not settle. */onScrubPreview: (ms: number) => void;/** On release, once: settle. */onScrubCommit: (ms: number) => void;+ /**+ * The preview axis (a switch in the toolbar): the picture at the moment under the pointer while it+ * moves over the tracks, the playhead staying where it is; null: back to the playhead's picture. Without it there is+ * no preview axis.+ */+ onHoverPreview?: (ms: number | null) => void;/** A single seek: the keyboard. */onSeek: (ms: number) => void;/** Delete a clip from film.html. Null = done. */@@ -712,22 +739,23 @@ export interface TimelineCommands {/** Link the selected clips, or unlink them. */link: () => void;unlink: () => void;- /** The switches (see lib/timeline-prefs). */- toggleMagnet: () => void;- toggleLinkage: () => void;/** [ / ]: every clip before / after the playhead selected (lib/timeline-nav sideTargets). */selectSide: (dir: -1 | 1) => void;+ /** The switches (see lib/timeline-prefs): the main-track magnet, snapping, linkage, the preview axis. */+ toggleMagnet: () => void;toggleSnap: () => void;+ toggleLinkage: () => void;+ togglePreviewAxis: () => void;/**- * ⌘B: split the selected clips at the playhead; with nothing selected, the clip under it on the targeted track (the- * one last pressed), else on the topmost track seen. The clips linked to them go too.+ * ⌘B: split the selected clips at the playhead; with nothing selected, the clip under it on the main track, else on+ * the targeted track (the one last pressed), else on the topmost track seen. The clips linked to them go too.*/split: () => void;/** ⇧⌘B: split every clip under the playhead, on every unlocked track. */splitAll: () => void;- /** ⌘X: copy the selected clips, then delete them (closing the gap with the magnet on, as ⌫ does). */+ /** ⌘X: copy the selected clips, then delete them (as ⌫ does: with the magnet the main track closes up). */cut: () => void;- /** ⌥← / ⌥→: move the selected clips `frames` frames, in the timeline's mode. */+ /** ⌥← / ⌥→: move the selected clips `frames` frames, stopping against a clip in the way. */nudge: (frames: number) => void;/** ⇧Z: the whole film in view. */zoomFit: () => void;@@ -797,7 +825,7 @@ function TrimHandle({className="group/trim absolute inset-y-0 z-[2] cursor-ew-resize"/* picked, the grab straddles the edge (the selection frame outside, the clip's own edge inside): a person reachesfor the clip's edge, and grabbing just inside it moved the whole clip instead (UI test, 2026-10-03). Not where- another clip touches it: outside is that clip's edge, and the cut between them a roll */+ another clip touches it: outside is that clip's own edge, which trims that clip (a press there never rolls) */style={{width: picked ? hit * 2 : hit,...(edge === 'start'@@ -921,8 +949,10 @@ export const Timeline = React.memo(function Timeline({timeMs,clock,playing,+ previewBar,onScrubPreview,onScrubCommit,+ onHoverPreview,onSeek,onRemove,onRemoveMany,@@ -985,16 +1015,29 @@ export const Timeline = React.memo(function Timeline({const toolbarRef = React.useRef<HTMLDivElement | null>(null);/* the head column and the ruler do not scroll themselves; the track area drives them (ruler horizontally, headsvertically), so clips and ticks never drift apart by a few pixels */- const headRef = React.useRef<HTMLDivElement | null>(null);+ const headShiftRef = React.useRef<HTMLDivElement | null>(null);const rulerRef = React.useRef<HTMLDivElement | null>(null);const skinsShiftRef = React.useRef<HTMLDivElement | null>(null);const padTopRef = React.useRef(0);const dragExtentRef = React.useRef(0);- /** The view: scroll position and size. Ticks drawn and rows centered by it. */- const [view, setView] = React.useState({ left: 0, top: 0, width: 0, height: 0 });+ /** The view: horizontal scroll and size. Ticks drawn and rows centered by it. */+ const [view, setView] = React.useState({ left: 0, width: 0, height: 0 });+ /*+ * The vertical scroll is not in the view: a render per step of a scroll cost more than the scroll. The heads and the+ * rows' backgrounds follow it on the compositor (onScroll); the rows whose clips are drawn follow it in steps+ * (lib/timeline-view rowBand).+ */+ const scrollTopRef = React.useRef(0);+ const [band, setBand] = React.useState(0);+ const bandRef = React.useRef(band);+ /** The rows drawn follow a scroll to `top` in a view `height` tall (a render only when the step changes). */+ const followRows = (top: number, height: number) => {+ const next = rowBand(top, height);+ if (next !== bandRef.current) { bandRef.current = next; setBand(next); }+ };const [zoom, setZoom] = React.useState(ZOOM_DEFAULT);- /* the switches: snapping, the magnet (insert and ripple), sync lock, linked clips; kept on this machine */+ /* the switches (the main-track magnet, snapping, linkage, the preview axis); kept on this machine */const prefs = useTimelinePrefs();const snap = prefs.snap;const prefsRef = React.useRef(prefs);@@ -1014,10 +1057,10 @@ export const Timeline = React.memo(function Timeline({const [notice, setNotice] = React.useState<string | null>(null);/* the tracks as an edit sees them (lib/timeline-edit): every gesture plans on it */const model = React.useMemo(() => editModelOf(tracks, links), [tracks, links]);- /** The main track's film.html index: the magnet acts there. */- const mainDoc = React.useMemo(() => mainTrackOf(model), [model]);const modelRef = React.useRef(model);modelRef.current = model;+ /** The main track's film.html index: the magnet and linkage act there. */+ const mainDoc = React.useMemo(() => mainTrackOf(model), [model]);/** Block ids → the same clips with every clip linked to them, unless `alone` (⌥). */const withLinked = React.useCallback((ids: readonly string[], alone = false): string[] => {if (alone) return [...ids];@@ -1065,6 +1108,8 @@ export const Timeline = React.memo(function Timeline({* (only the timeline re-renders); the editor and the picture are told every SCRUB_TELL_MS.*/const [scrubMs, setScrubMs] = React.useState<number | null>(null);+ /* a scrub moves the playhead itself each frame (see PlayheadTrack `moveRef`); scrubMs follows a few times a second */+ const playheadMove = React.useRef<((x: number) => void) | null>(null);/** When the time was last told upward (see SCRUB_TELL_MS). */const lastTold = React.useRef(0);/** What the selection bar is about: what was picked last (the clips, the range, a point on the ruler). */@@ -1073,43 +1118,23 @@ export const Timeline = React.memo(function Timeline({const [selectedMode, setMode] = React.useState<TimelineMode>('select');const mode = onSplit ? selectedMode : 'select';- React.useEffect(() => {+ /* measured before the first paint: until the view has a size every clip is drawn (lib/timeline-view rowsNear) */+ React.useLayoutEffect(() => {const el = scrollRef.current;if (!el || typeof ResizeObserver === 'undefined') return;const ro = new ResizeObserver(() => {setView((cur) => (cur.width === el.clientWidth && cur.height === el.clientHeight? cur: { ...cur, width: el.clientWidth, height: el.clientHeight }));+ followRows(el.scrollTop, el.clientHeight);});ro.observe(el);- setView({- left: el.scrollLeft,- top: el.scrollTop,- width: el.clientWidth,- height: el.clientHeight,- });+ scrollTopRef.current = el.scrollTop;+ setView({ left: el.scrollLeft, width: el.clientWidth, height: el.clientHeight });+ followRows(el.scrollTop, el.clientHeight);return () => ro.disconnect();}, []);- /* ruler and heads follow at once, and the view is written back at once (a frame late shows a gap at the top) */- const onScroll = React.useCallback(() => {- const el = scrollRef.current;- if (!el) return;- if (rulerRef.current) rulerRef.current.scrollLeft = el.scrollLeft;- if (headRef.current) headRef.current.scrollTop = el.scrollTop;- if (skinsShiftRef.current) {- skinsShiftRef.current.style.transform = `translate3d(0,${padTopRef.current - el.scrollTop}px,0)`;- }- const left = el.scrollLeft;- const top = el.scrollTop;- el.style.setProperty('--tl-scroll-left', `${left}px`);- setView((cur) => (- cur.left === left && cur.top === top- ? cur- : { ...cur, left, top }- ));- }, []);-/* with length 0 there may still be empty tracks (`clips: []`): they are drawn so assets can be dropped on them;playback and scrubbing still need a length */const hasLanes = tracks.length > 0;@@ -1167,51 +1192,261 @@ export const Timeline = React.memo(function Timeline({/* at least TL_VPAD even when the rows overflow, counted in padTop so every hit test uses the same number */const padTop = Math.max(TL_VPAD, Math.floor((view.height - tracksH) / 2));padTopRef.current = padTop;+ const viewHeightRef = React.useRef(view.height);+ viewHeightRef.current = view.height;+ /* the heads and the rows' backgrounds, moved with the vertical scroll (see onScroll) */+ const rowsShift = `translate3d(0,${padTop - scrollTopRef.current}px,0)`;+ /*+ * The rows whose clips (and heads) are drawn: those near the view. Every clip drawn is laid out, layerized and+ * hit-tested again on each zoom step and scroll; a film's dozens of sound rows mostly lie below the view.+ */+ const rowHeights = React.useMemo(() => tracks.map(rowH), [tracks]);+ const { first: nearFirst, last: nearLast } = rowsNear(rowHeights, { gap: GAP, padTop, band, viewH: view.height });/* in the project's frames: at 25 fps a tick every 5 frames, not every 6 as at 30 */const steps = React.useMemo(() => rulerSteps(pxPerMs, fps), [pxPerMs, fps]);/* ── Zoom around a point ──Without a fixed point, zooming jumps elsewhere: the scroll stays, the time under it changes. The point: the- pointer (wheel zoom), else the playhead if in view, else the middle of the view. */- const anchorRef = React.useRef<{ ms: number; x: number } | null>(null);- const anchorAt = React.useCallback((clientX?: number) => {+ pointer (wheel zoom), else the playhead if in view, else the middle of the view.+ A wheel or pinch gesture lays nothing out while it goes on: what is drawn in time (the clips, the ruler, the+ subtitle and marker rows, the playhead, the range; each marked data-zoom-layer) is scaled by transforms the+ compositor applies (lib/timeline-view), and laid out at the new density once it stops or has gone ZOOM_RELAYOUT+ far. Laid out on each step, a film of hundreds of clips spent most of every frame on it. */+ /** The gesture under way, against what is laid out at `px` (null: none). */+ const previewRef = React.useRef<(ZoomPreview & { px: number }) | null>(null);+ /** A gesture is drawn by transforms: the selection bar hides, the ruler draws on past the canvas. */+ const [zooming, setZooming] = React.useState(false);+ const zoomingRef = React.useRef(false);+ /** The scroll a zoom just laid out goes to, before paint (see the layout effect below). */+ const zoomScrollRef = React.useRef<number | null>(null);+ /** Waits for the gesture to stop (0: none). */+ const settleTimer = React.useRef(0);+ /** The density laid out (what the page has drawn), and the scroll taken in (read here instead of the page's, which+ would lay the page out again when a render has just changed it). */+ const laidPxRef = React.useRef(pxPerMs);+ const scrollLeftRef = React.useRef(0);+ /**+ * Clip labels kept at the view's left edge, so a clip wider than the view still says what it is. Only the labels of+ * clips that edge runs through are moved, each by its own transform: a scroll restyles a handful of labels, where a+ * CSS variable on the scroller had every clip's style worked out again on each step.+ */+ const pinnedRef = React.useRef(new Set<HTMLElement>());+ const pinLabels = React.useCallback((scrollLeft: number) => {const el = scrollRef.current;- if (!el || pxPerMs <= 0) return;- const playX = timeMsRef.current * pxPerMs - el.scrollLeft;- const raw = clientX != null- ? clientX - el.getBoundingClientRect().left- : playX >= 0 && playX <= el.clientWidth- ? playX- : el.clientWidth / 2;- const x = Math.min(el.clientWidth, Math.max(0, raw));- anchorRef.current = { ms: timeAtPx(el.scrollLeft + x, pxPerMs, canvasMs), x };- }, [pxPerMs, canvasMs]);-- const zoomBy = React.useCallback((factor: number, clientX?: number) => {- anchorAt(clientX);- setZoom((z) => Math.min(zoomMaxOf(spanMs), Math.max(zoomMinOf(spanMs), z * factor)));- }, [anchorAt, spanMs]);-- const zoomTo = React.useCallback((next: number) => {- anchorAt();- setZoom(Math.min(zoomMaxOf(spanMs), Math.max(zoomMinOf(spanMs), next)));- }, [anchorAt, spanMs]);-- /* when the density changes, put the fixed point back in place — before paint, or a frame shows the jump */- React.useLayoutEffect(() => {+ if (!el) return;+ const next = new Set<HTMLElement>();+ for (const label of el.querySelectorAll<HTMLElement>('[data-pin]')) {+ const shift = Math.max(0, Math.min(scrollLeft - Number(label.dataset.pin), Number(label.dataset.pinMax)));+ if (!(shift > 0)) continue;+ label.style.transform = `translateX(${shift}px)`;+ next.add(label);+ }+ for (const label of pinnedRef.current) if (!next.has(label)) label.style.transform = '';+ pinnedRef.current = next;+ }, []);+ /** The canvas's width at a density (set once the canvas is worked out, below): the view never goes past its end. */+ const canvasPxAtRef = React.useRef<(px: number) => number>(() => 0);+ /** Something is in hand (a clip, the playhead, a marquee…): it is placed from the layout (set below). */+ const inHandRef = React.useRef(false);+ /** What each zoom layer was last drawn with, so an unchanged one is not written again. */+ const drawnLayers = React.useRef(new WeakMap<HTMLElement, string>());++ /** Draws each zoom layer as the gesture has it, or as laid out once there is none. */+ const drawZoom = React.useCallback(() => {+ const root = rootRef.current;+ if (!root) return;+ const scroll = scrollLeftRef.current;+ const p = previewRef.current ?? zoomPreviewAt(scroll);+ for (const layer of root.querySelectorAll<HTMLElement>('[data-zoom-layer]')) {+ const kind = layer.dataset.zoomLayer === 'view' ? 'view' : 'content';+ const t = zoomLayerTransform(p, scroll, kind, Number(layer.dataset.zoomBleed) || 0);+ if ((drawnLayers.current.get(layer) ?? '') === t) continue;+ drawnLayers.current.set(layer, t);+ layer.style.transform = t;+ layer.style.transformOrigin = t ? '0 0' : '';+ }+ /* what keeps its width in a scaled layer (the playhead's knob, the range's label) */+ for (const keep of root.querySelectorAll<HTMLElement>('[data-zoom-keep]')) {+ keep.style.scale = previewRef.current && p.scale !== 1 ? `${1 / p.scale} 1` : '';+ }+ }, []);++ const endZoom = React.useCallback(() => {+ previewRef.current = null;+ window.clearTimeout(settleTimer.current);+ settleTimer.current = 0;+ drawZoom();+ if (zoomingRef.current) { zoomingRef.current = false; setZooming(false); }+ }, [drawZoom]);++ /** Lays out at a density with the view's left edge at `scroll`, before the next paint. */+ const layOut = (px: number, scroll: number) => {+ const next = zoomForPxPerMs(spanMs, laneW, px);+ zoomScrollRef.current = scroll;+ setZoom(next);+ setView((cur) => (cur.left === scroll ? cur : { ...cur, left: scroll }));+ };++ /** The furthest the view can scroll at a density. */+ const maxScrollAt = (px: number) => Math.max(0, canvasPxAtRef.current(px) - laneW);++ /** One step of a wheel or pinch gesture: `factor` around the pointer, drawn by transforms. */+ const zoomStep = (factor: number, clientX: number) => {const el = scrollRef.current;- const anchor = anchorRef.current;- anchorRef.current = null;- if (!el || !anchor || pxPerMs <= 0) return;- el.scrollLeft = Math.max(0, anchor.ms * pxPerMs - anchor.x);- setView({- left: el.scrollLeft,- top: el.scrollTop,- width: el.clientWidth,- height: el.clientHeight,+ const px = laidPxRef.current;+ if (!el || !(px > 0) || !(spanMs > 0)) return;+ const at = Math.min(laneW, Math.max(0, clientX - el.getBoundingClientRect().left));+ const now = previewRef.current ?? { ...zoomPreviewAt(scrollLeftRef.current), px };+ /* with something in hand each step is laid out, as what is in hand is placed from the layout */+ if (inHandRef.current) {+ zoomTo(zoomForPxPerMs(spanMs, laneW, now.px * now.scale * factor), { at });+ return;+ }+ const next = zoomPreviewStep(now, factor, at, {+ minScale: zoomedPxPerMs(spanMs, laneW, zoomMinOf(spanMs)) / px,+ maxScale: zoomedPxPerMs(spanMs, laneW, zoomMaxOf(spanMs)) / px,+ maxScrollAt: (scale) => maxScrollAt(px * scale),});- }, [pxPerMs]);+ previewRef.current = { ...next, px };+ if (!zoomingRef.current) { zoomingRef.current = true; setZooming(true); }+ drawZoom();+ window.clearTimeout(settleTimer.current);+ settleTimer.current = window.setTimeout(() => zoomFns.current.settleZoom(), ZOOM_SETTLE_MS);+ /* scaled much further, the stretched clips blur and the far side runs out of what is drawn: lay out now */+ if (next.scale > ZOOM_RELAYOUT || next.scale < 1 / ZOOM_RELAYOUT) layOut(px * next.scale, -next.offset);+ };++ /** The gesture stopped: laid out where it is. */+ const settleZoom = () => {+ settleTimer.current = 0;+ const p = previewRef.current;+ if (!p) return;+ if (zoomPreviewIsRest(p, scrollLeftRef.current)) { endZoom(); return; }+ layOut(p.px * p.scale, -p.offset);+ };++ /** Zoom to `next`, keeping view x `at` in place (by default the playhead if in view, else the middle); `scroll`:+ where the view's left edge goes instead. From what is drawn: a gesture under way counts. */+ const zoomTo = (next: number, place: { at?: number; scroll?: number } = {}) => {+ const el = scrollRef.current;+ const px0 = laidPxRef.current;+ if (!el || !(px0 > 0)) return;+ const p = previewRef.current ?? { ...zoomPreviewAt(scrollLeftRef.current), px: px0 };+ const drawnPx = p.px * p.scale;+ const drawnLeft = -p.offset;+ const px = zoomedPxPerMs(spanMs, laneW, Math.min(zoomMaxOf(spanMs), Math.max(zoomMinOf(spanMs), next)));+ const playX = timeMsRef.current * drawnPx - drawnLeft;+ const at = place.at ?? (playX >= 0 && playX <= laneW ? playX : laneW / 2);+ const scroll = Math.min(maxScrollAt(px), Math.max(0, place.scroll ?? ((drawnLeft + at) / drawnPx) * px - at));+ window.clearTimeout(settleTimer.current);+ settleTimer.current = 0;+ /* nothing to lay out: what is laid out is it (a gesture drawn on top of it ends) */+ if (Math.abs(px - p.px) < 1e-12 && Math.abs(scroll - scrollLeftRef.current) < 0.5) { endZoom(); return; }+ /* the gesture (if any) ends where this zoom lays out: at rest once it is, see the layout effect */+ previewRef.current = { offset: -scroll, scale: px / p.px, px: p.px };+ layOut(px, scroll);+ };+ /** Zoom by a factor of what is drawn now. */+ const zoomBy = (factor: number) => {+ const p = previewRef.current;+ const drawnPx = p ? p.px * p.scale : laidPxRef.current;+ zoomTo(zoomForPxPerMs(spanMs, laneW, drawnPx * factor));+ };+ const zoomFns = React.useRef({ zoomStep, settleZoom, zoomTo, zoomBy });+ zoomFns.current = { zoomStep, settleZoom, zoomTo, zoomBy };+ /* stable for the key handlers and buttons; they act on what is current */+ const zoomToStable = React.useCallback((next: number, place?: { at?: number; scroll?: number }) => zoomFns.current.zoomTo(next, place), []);+ const zoomByStable = React.useCallback((factor: number) => zoomFns.current.zoomBy(factor), []);++ /* after every render: a zoom laid out goes to its scroll before paint, and a gesture is redrawn against what is laid+ out now (or ends, once it has stopped and the layout shows it) */+ React.useLayoutEffect(() => {+ const el = scrollRef.current;+ if (!el) return;+ const want = zoomScrollRef.current;+ if (want != null) {+ zoomScrollRef.current = null;+ el.scrollLeft = want;+ const left = el.scrollLeft;+ /* taken in here: its scroll event moves nothing (see onScroll); where the browser rounded it, the view moved by+ that much, as with any scroll */+ scrollLeftRef.current = left;+ const before = previewRef.current;+ if (before && left !== want) previewRef.current = { ...before, offset: before.offset - (left - want) };+ if (rulerRef.current) rulerRef.current.scrollLeft = left;+ if (left !== view.left) setView((cur) => ({ ...cur, left }));+ }+ /* clips moved, or were drawn again: their labels pinned where the view is now */+ pinLabels(scrollLeftRef.current);+ const p = previewRef.current;+ if (p && p.px !== pxPerMs && pxPerMs > 0) previewRef.current = { ...rebaseZoomPreview(p, p.px, pxPerMs), px: pxPerMs };+ laidPxRef.current = pxPerMs;+ const now = previewRef.current;+ if (!now) return;+ if (!settleTimer.current && zoomPreviewIsRest(now, scrollLeftRef.current)) endZoom();+ else drawZoom();+ });++ /* a press lays a gesture out first: what the press does is worked out from the layout (times, rows, edges) */+ React.useEffect(() => {+ const onDown = () => {+ if (previewRef.current) flushSync(() => zoomFns.current.settleZoom());+ };+ window.addEventListener('pointerdown', onDown, true);+ return () => window.removeEventListener('pointerdown', onDown, true);+ }, []);++ /* ruler and heads follow at once, and the view is written back at once (a frame late shows a gap at the top); React+ hears of a scroll only when what it draws changes: the rows drawn (vertical) or the view's left edge */+ const onScroll = React.useCallback(() => {+ const el = scrollRef.current;+ if (!el) return;+ const left = el.scrollLeft;+ const top = el.scrollTop;+ if (top !== scrollTopRef.current) {+ scrollTopRef.current = top;+ /* a transform, not a scroll of their own (that one repainted the heads on each step); from here only where the+ scroll's own timeline does not move them (see below) */+ if (!rowsOnTimelineRef.current) {+ const shift = `translate3d(0,${padTopRef.current - top}px,0)`;+ if (skinsShiftRef.current) skinsShiftRef.current.style.transform = shift;+ if (headShiftRef.current) headShiftRef.current.style.transform = shift;+ }+ followRows(top, viewHeightRef.current);+ }+ if (left === scrollLeftRef.current) return;+ /* during a zoom gesture the view moves on with the scroll, its layers redrawn for it */+ const p = previewRef.current;+ if (p) previewRef.current = { ...p, offset: p.offset - (left - scrollLeftRef.current) };+ scrollLeftRef.current = left;+ if (rulerRef.current) rulerRef.current.scrollLeft = left;+ pinLabels(left);+ if (p) drawZoom();+ setView((cur) => (cur.left === left ? cur : { ...cur, left }));+ }, [drawZoom, pinLabels]);++ /*+ * Where the browser has scroll timelines, the heads and the rows' backgrounds follow the vertical scroll on the+ * compositor: an animation on the track area's scroll, so they keep step with the rows however busy the page is.+ * Moved from onScroll instead, each step of a scroll layerized the page again.+ */+ const rowsOnTimelineRef = React.useRef(false);+ React.useLayoutEffect(() => {+ const el = scrollRef.current;+ const ScrollTimeline = (globalThis as { ScrollTimeline?: new (o: { source: Element; axis: 'block' }) => AnimationTimeline }).ScrollTimeline;+ if (!el || !ScrollTimeline) return undefined;+ const max = el.scrollHeight - el.clientHeight;+ if (!(max > 0)) return undefined;+ const timeline = new ScrollTimeline({ source: el, axis: 'block' });+ const frames = [{ transform: `translate3d(0,${padTop}px,0)` }, { transform: `translate3d(0,${padTop - max}px,0)` }];+ const moving = [skinsShiftRef.current, headShiftRef.current].flatMap((layer) => (layer ? [layer.animate(frames, { timeline, fill: 'both' })] : []));+ rowsOnTimelineRef.current = true;+ return () => {+ rowsOnTimelineRef.current = false;+ for (const a of moving) a.cancel();+ };+ }, [padTop, tracksH, view.height, hasLanes]);const panViewTo = React.useCallback((fromMs: number) => {const el = scrollRef.current;@@ -1222,12 +1457,10 @@ export const Timeline = React.memo(function Timeline({/* Ctrl/⌘ + wheel (and pinch) zooms around the pointer. A native non-passive listener: React's onWheel is passive andcannot stop the browser's page zoom. Horizontal swipes and Shift+wheel scroll here too: the track area hides itshorizontal scrollbar. */- const zoomByRef = React.useRef(zoomBy);- React.useEffect(() => { zoomByRef.current = zoomBy; }, [zoomBy]);React.useEffect(() => {const el = scrollRef.current;if (!el) return;- /* one zoom per frame: a pinch sends a hundred wheel events a second, each relaying out every clip */+ /* one step per frame: a pinch sends a hundred wheel events a second */let factor = 1;let anchorX = 0;let raf = 0;@@ -1235,7 +1468,7 @@ export const Timeline = React.memo(function Timeline({raf = 0;const f = factor;factor = 1;- if (f !== 1) zoomByRef.current(f, anchorX);+ if (f !== 1) zoomFns.current.zoomStep(f, anchorX);};/* Firefox reports lines (deltaMode 1) or pages (2) */const pixels = (e: WheelEvent, d: number) => (e.deltaMode === 1 ? d * 16 : e.deltaMode === 2 ? d * 400 : d);@@ -1258,6 +1491,7 @@ export const Timeline = React.memo(function Timeline({if (raf) cancelAnimationFrame(raf);};}, []);+ React.useEffect(() => () => window.clearTimeout(settleTimer.current), []);/*** The row under the pointer. Outside the rows it says so (-1 above, tracks.length below) instead of clamping to the@@ -1337,6 +1571,16 @@ export const Timeline = React.memo(function Timeline({});/* whole pixels: a fractional width blurs every clip edge on it */const trackPx = pxPerMs > 0 ? Math.max(laneW, Math.ceil(extentMs * pxPerMs)) : laneW;+ /* the same at another density: how far a zoom gesture can take the view (see zoomStep) */+ canvasPxAtRef.current = (px: number) => {+ const ms = liveCanvasMs({+ canvasMs: canvasTimeMs(spanMs, laneW, px),+ clipEndMs,+ dragReachMs: dragExtentRef.current,+ tailMs: (drag.preview || assetHint) ? Math.max(laneW / px * 0.5, VIEW_SPAN_MIN_MS) : 0,+ });+ return Math.max(laneW, Math.ceil(ms * px));+ };const ticks = React.useMemo(() => {if (!hasLanes) return [];@@ -1344,11 +1588,12 @@ export const Timeline = React.memo(function Timeline({leftPx: view.left,widthPx: view.width,pxPerMs,- maxMs: extentMs,+ /* a zoom gesture scales the ruler: zooming out, it shows time past the canvas's end before that is laid out */+ maxMs: zooming && pxPerMs > 0 ? Math.max(extentMs, (view.left + view.width * ZOOM_RELAYOUT) / pxPerMs) : extentMs,tickMs: steps.tickMs,});return rulerMarks(fromMs, toMs, steps);- }, [hasLanes, view.left, view.width, pxPerMs, extentMs, steps]);+ }, [hasLanes, view.left, view.width, pxPerMs, extentMs, steps, zooming]);const msAtClientX = React.useCallback((clientX: number): number => {const el = scrollRef.current;@@ -1385,7 +1630,7 @@ export const Timeline = React.memo(function Timeline({/* A scrub follows the pointer from pointerdown to pointerup even outside the timeline (listeners on window). Eachframe previews, release commits: hundreds of seeks would make the sound tear. With snapping on, the line snaps to- clip edges and markers, as CapCut's. A click without dragging takes the same path, and pauses, as CapCut does. */+ clip edges and markers. A click without dragging takes the same path, and pauses. */const startScrub = React.useCallback((e: React.PointerEvent, fromRuler = false) => {if (e.button !== 0 || !playable) return;e.preventDefault();@@ -1398,7 +1643,11 @@ export const Timeline = React.memo(function Timeline({setScrubMs(at);onScrubPreview(at);lastTold.current = performance.now();+ let lastState = lastTold.current;setScrubbing(true);+ /* the line where the time is now, the scroll as it is now (an edge may be scrolling it) */+ const moveLine = () => playheadMove.current?.(at * pxPerMs - (scrollRef.current?.scrollLeft ?? 0) + PLAYHEAD_BLEED);+ moveLine();/* the scrub cursor holds for the whole drag (an !important class), or clips under the line take it */document.body.classList.add('tl-scrubbing');/* once per frame: the pointer sends far more moves than the screen draws */@@ -1407,10 +1656,11 @@ export const Timeline = React.memo(function Timeline({const flush = (): void => {raf = 0;at = timeAt(atX);- /* the line every frame (cheap: the rows are memoized without the time) */- setScrubMs(at);- /* the editor and the picture every SCRUB_TELL_MS (the expensive part) */+ /* the line every frame, outside React; what else shows the time here (the selection bar), a few times a second */+ moveLine();const now = performance.now();+ if (now - lastState >= SCRUB_STATE_MS) { lastState = now; setScrubMs(at); }+ /* the editor and the picture every SCRUB_TELL_MS */if (now - lastTold.current >= SCRUB_TELL_MS) {lastTold.current = now;onScrubPreview(at);@@ -1531,18 +1781,14 @@ export const Timeline = React.memo(function Timeline({return now && Math.abs(now.startMs - g.startMs) < TOUCH_MS && Math.abs(now.endMs - g.endMs) < TOUCH_MS ? g : null;});}, [model]);- /* the magnet turned on closes up the main track, as CapCut's: its gaps go, in one step */+ /* the magnet turned on closes up the main track: its gaps go, in one step */onMagnetOn.current = () => {- void runPlan(planCloseMainGaps(modelRef.current, followOf(prefsRef.current)), 'history.stepMainClosed');+ void runPlan(planCloseMainGaps(modelRef.current, switchesOf(prefsRef.current)), 'history.stepMainClosed');};- /**- * Close a gap: what is after it moves back (with sync lock, on every unlocked track; on its own track alone when a- * synced track has no room, and a notice says so).- */+ /** Close a gap: what is after it on its track moves back (with linkage, what rides on the main track along). */const closeGapOn = React.useCallback((g: { track: number; startMs: number; endMs: number }) => {- const plan = planCloseGap(modelRef.current, g.track, g, followOf(prefsRef.current));- void runPlan(plan, 'history.stepGapClosed', plan.alone ? t('timeline.gapClosedAlone') : undefined);- }, [runPlan, t]);+ void runPlan(planCloseGap(modelRef.current, g.track, g, switchesOf(prefsRef.current)), 'history.stepGapClosed');+ }, [runPlan]);/** Close the gap picked. */const closeGap = React.useCallback(() => {const g = gap;@@ -1741,6 +1987,39 @@ export const Timeline = React.memo(function Timeline({return out;}, [mode, tracks]);+ /* ── the preview axis: a line under the pointer, the picture there; the playhead stays ── */+ const axisRef = React.useRef<HTMLDivElement | null>(null);+ const axisAt = React.useRef<number | null>(null);+ const axisFrame = React.useRef(0);+ const hoverPreviewRef = React.useRef(onHoverPreview);+ hoverPreviewRef.current = onHoverPreview;+ /** The axis at a moment (null: gone, the picture back at the playhead). Written to the DOM, told once a frame. */+ const showAxis = React.useCallback((ms: number | null) => {+ const line = axisRef.current;+ if (line) {+ line.style.opacity = ms == null ? '0' : '1';+ if (ms != null) line.style.transform = `translateX(${Math.round(ms * laidPxRef.current - scrollLeftRef.current + PLAYHEAD_BLEED)}px)`;+ }+ if (axisAt.current === ms) return;+ axisAt.current = ms;+ if (axisFrame.current) return;+ axisFrame.current = requestAnimationFrame(() => {+ axisFrame.current = 0;+ hoverPreviewRef.current?.(axisAt.current);+ });+ }, []);+ React.useEffect(() => () => { if (axisFrame.current) cancelAnimationFrame(axisFrame.current); }, []);+ /* not while playing, nor with a button held (a drag, a scrub, a marquee): then the picture is theirs */+ const aimAxis = React.useCallback((e: React.PointerEvent) => {+ if (!prefsRef.current.previewAxis || !hoverPreviewRef.current || playing || e.buttons || inHandRef.current) {+ if (axisAt.current != null) showAxis(null);+ return;+ }+ showAxis(Math.max(0, Math.min(totalMs, msAtClientX(e.clientX))));+ }, [playing, totalMs, msAtClientX, showAxis]);+ /* turned off, or playing: the axis goes */+ React.useEffect(() => { if ((!prefs.previewAxis || playing) && axisAt.current != null) showAxis(null); }, [prefs.previewAxis, playing, showAxis]);+const bladeRef = React.useRef<HTMLDivElement | null>(null);const contentRef = React.useRef<HTMLDivElement | null>(null);const hideBlade = React.useCallback(() => {@@ -1770,10 +2049,10 @@ export const Timeline = React.memo(function Timeline({}, [msAtClientX, pxPerMs, splitSpots]);/**- * Delete clips: locked rows untouched. Planned (lib/timeline-edit) as one edit; with `ripple` the time they took- * closes (with sync lock on every unlocked track). Without onEditOps, one by one through onRemove(Many).+ * Delete clips: locked rows untouched. Planned (lib/timeline-edit) as one edit; without `ripple` they leave a gap,+ * with it the time they took closes on every unlocked track. Without onEditOps, one by one through onRemove(Many).*/- const removeMany = React.useCallback(async (blocks: readonly TimelineBlock[], ripple: boolean | 'main' = false) => {+ const removeMany = React.useCallback(async (blocks: readonly TimelineBlock[], ripple = false) => {const locked = new Set(tracks.filter((tr) => tr.locked).flatMap((tr) => tr.blocks.map((b) => b.id)),);@@ -1784,7 +2063,7 @@ export const Timeline = React.memo(function Timeline({if (onEditOps) {const ids = targets.flatMap((b) => (b.clipId ? [b.clipId] : []));const label = ids.length <= 2 ? `history.stepRemoved|${ids.join(', ')}` : 'history.stepRemove';- await runPlan(planRemove(modelRef.current, ids, { ripple, ...followOf(prefsRef.current) }), label);+ await runPlan(planRemove(modelRef.current, ids, { ripple, ...switchesOf(prefsRef.current) }), label);return;}if (onRemoveMany) {@@ -1801,38 +2080,37 @@ export const Timeline = React.memo(function Timeline({}, [onEditOps, onRemove, onRemoveMany, tracks, setSelected, runPlan]);/**- * Ripple delete (⇧Delete, the menu): what comes after closes the gap, on the clips' tracks and with sync lock every- * unlocked track, or with linkage the main track's, carrying the others. `'main'` (Delete with the magnet on): only- * the main track closes up, the others keep their gaps. One edit, one ⌘Z.+ * Ripple delete (⇧Delete, the menu): what comes after closes the gap on each of their tracks. With `ripple` false a+ * delete (⌫) that closes up only the main track, with the magnet. One edit, one ⌘Z.*/- const rippleRemove = React.useCallback(async (blocks: readonly TimelineBlock[], waited = false, how: true | 'main' = true) => {+ const rippleRemove = React.useCallback(async (blocks: readonly TimelineBlock[], waited = false, ripple = true) => {/* a track with clips not drawn yet (an undo just put them back): wait for them, or the gap closes onto them */const ids = new Set(blocks.map((b) => b.id));if (!waited && tracks.some((tr) => tr.incomplete && tr.blocks.some((b) => ids.has(b.id)))) {- const wait = { keys: blocks.map((b) => b.clipId ?? b.id), how };+ const wait = { keys: blocks.map((b) => b.clipId ?? b.id), ripple };rippleWait.current = wait;/* past the wait it goes with what is drawn: a page that never loads must not block it for good */window.setTimeout(() => { if (rippleWait.current === wait) rippleRetry.current(true); }, RIPPLE_WAIT_MS);return;}rippleWait.current = null;- await removeMany(blocks, how);+ await removeMany(blocks, ripple);}, [removeMany, tracks]);/* a waiting ripple delete goes once its tracks are whole, its clips found again by id (their places may havechanged meanwhile) */- const rippleWait = React.useRef<{ keys: readonly string[]; how: true | 'main' } | null>(null);+ const rippleWait = React.useRef<{ keys: readonly string[]; ripple: boolean } | null>(null);const rippleRetry = React.useRef((_late: boolean) => {});rippleRetry.current = (late: boolean) => {const wait = rippleWait.current;if (!wait) return;const mine = (b: TimelineBlock) => wait.keys.includes(b.clipId ?? b.id);if (!late && tracks.some((tr) => tr.incomplete && tr.blocks.some(mine))) return;- void rippleRemove(tracks.flatMap((tr) => tr.blocks).filter(mine), true, wait.how);+ void rippleRemove(tracks.flatMap((tr) => tr.blocks).filter(mine), true, wait.ripple);};React.useEffect(() => { rippleRetry.current(false); }, [tracks]);- /** Delete (⌫, ⌘X, the menu): with the magnet the main track closes up, the other tracks keep their gaps. */+ /** Delete (⌫, ⌘X, the menu): with the magnet the main track closes up; it waits as a ripple does. */const magnetRemove = React.useCallback(- (blocks: readonly TimelineBlock[]) => (prefsRef.current.magnet ? rippleRemove(blocks, false, 'main') : removeMany(blocks)),+ (blocks: readonly TimelineBlock[]) => (prefsRef.current.magnet ? rippleRemove(blocks, false, false) : removeMany(blocks)),[rippleRemove, removeMany],);@@ -1872,7 +2150,7 @@ export const Timeline = React.memo(function Timeline({}if ((!onRemove && !onRemoveMany && !onEditOps) || !picked.length) return;e.preventDefault();- /* with the magnet on a delete closes the gap it leaves, as ⇧Delete always does */+ /* ⌫ leaves a gap (with the magnet the main track closes up); ⇧⌫ closes it (a ripple delete) */void (e.shiftKey ? rippleRemove(picked) : magnetRemove(picked));return;}@@ -1881,8 +2159,8 @@ export const Timeline = React.memo(function Timeline({if (mod && !e.altKey && (e.key === '=' || e.key === '+' || e.key === '-' || e.key === '0')) {if (!playable || !scrollRef.current?.checkVisibility?.({ visibilityProperty: true })) return;e.preventDefault();- if (e.key === '0') zoomTo(ZOOM_DEFAULT);- else zoomBy(e.key === '-' ? 1 / ZOOM_STEP : ZOOM_STEP);+ if (e.key === '0') zoomToStable(ZOOM_DEFAULT);+ else zoomByStable(e.key === '-' ? 1 / ZOOM_STEP : ZOOM_STEP);return;}if (!mod || e.altKey || e.shiftKey) return;@@ -1904,7 +2182,7 @@ export const Timeline = React.memo(function Timeline({window.addEventListener('keydown', onKey);return () => window.removeEventListener('keydown', onKey);/* the playhead is read from a ref: as a dependency the listener would be swapped twenty times a second */- }, [onRemove, onRemoveMany, onEditOps, onCopy, onPaste, hasClipboard, removeMany, rippleRemove, magnetRemove, selected, tracks, setSelected, playable, zoomBy, zoomTo, gap, closeGap, pickedTransition, onTransition, onPickTransition]);+ }, [onRemove, onRemoveMany, onEditOps, onCopy, onPaste, hasClipboard, removeMany, rippleRemove, magnetRemove, selected, tracks, setSelected, playable, zoomByStable, zoomToStable, gap, closeGap, pickedTransition, onTransition, onPickTransition]);/* whether the last press was on the timeline (for ⌘A); capture phase, since presses here are often stopped */React.useEffect(() => {@@ -1947,21 +2225,22 @@ export const Timeline = React.memo(function Timeline({}, [allBlocks, pxPerMs, snap, snapPointsMs]);/**- * How a drop from the media pane goes in. On the main track with the magnet: an insert (⌥: an overwrite). Elsewhere- * with the magnet, as CapCut's: no edit, so it never covers a clip — a taken spot opens a new track (⌥: an- * overwrite). Without the magnet: an overwrite (⌥: an insert).+ * How a drop from the media pane goes in. Onto the main track with the magnet: in between two clips at the insert+ * point there, what follows on that track moving on (nothing is cut). Anywhere else it is put down where it is let+ * go, or on a new track when that spot is taken. ⌥: an overwrite.*/const dropModeAt = React.useCallback((hit: { lane: number; band: DropBand }, alt: boolean): EditMode | undefined => {+ if (alt) return 'overwrite';+ /* onto the main track with the magnet: in between, what follows moving on */const doc = hit.band === 'body' ? tracks[hit.lane]?.docIndex : undefined;- const { magnet } = prefsRef.current;- if (magnet && !magnetOn(modelRef.current, doc, magnet)) return alt ? 'overwrite' : undefined;- return magnetOn(modelRef.current, doc, magnet) !== alt ? 'insert' : 'overwrite';+ return magnetOn(modelRef.current, doc, prefsRef.current.magnet) ? 'insert' : undefined;}, [tracks]);/**- * Where a drop from the media pane lands and what it does there, for the preview and the drop alike. Onto the main- * track with the magnet (⌥: the other way): an insert at the insert point of the track (lib/timeline-edit insertPointOn),- * pushing what follows on; without: an overwrite where it was let go. The clips it pushes or cuts are drawn moved.+ * Where a drop from the media pane lands and what it does there, for the preview and the drop alike: on the main+ * track with the magnet an insert at the insert point there (lib/timeline-edit insertPointOn), what follows moving+ * on; elsewhere put down where it was let go, or on a new track when that spot is taken (dropModeAt). With ⌥, an+ * overwrite there. The clips it pushes or cuts are drawn moved.*/const assetLanding = React.useCallback((file: ResourceDragItem, clientX: number, clientY: number, altKey: boolean): AssetHint | null => {const laneHit = laneHitAtY(clientY);@@ -1975,7 +2254,7 @@ export const Timeline = React.memo(function Timeline({let startMs = preview.startMs;if (docIndex != null && !preview.error && onEditOps && editMode) {if (editMode === 'insert') startMs = insertPointOn(modelRef.current, docIndex, pointerMs, startMs);- const plan = planRoom(modelRef.current, [{ track: docIndex, startMs, endMs: startMs + preview.endMs - preview.startMs }], { mode: editMode, ...followOf(prefsRef.current) });+ const plan = planRoom(modelRef.current, [{ track: docIndex, startMs, endMs: startMs + preview.endMs - preview.startMs }], { mode: editMode, ...switchesOf(prefsRef.current) });for (const [clipId, at] of plan.placed) {const b = allBlocks.find((x) => x.clipId === clipId);if (b) ghosts.set(b.id, at ? { startMs: at.startMs, endMs: at.endMs } : null);@@ -2088,7 +2367,7 @@ export const Timeline = React.memo(function Timeline({if (!onSplit) return;if (e.altKey || e.shiftKey || e.metaKey || e.ctrlKey || e.defaultPrevented) return;const key = e.key.toLowerCase();- /* A or V selects (CapCut's key, Premiere's key), B splits */+ /* A or V selects, B splits */if (key !== 'a' && key !== 'b' && key !== 'v') return;e.preventDefault();setMode(key === 'b' ? 'split' : 'select');@@ -2298,6 +2577,11 @@ export const Timeline = React.memo(function Timeline({return lanes;}, [tracks, selected]);+ /* each head's element is kept while nothing it shows changes (as the clips' are, see clipElements): the heads drawn+ follow the scroll, and rebuilding every one of them each time rendered all their buttons and tooltips again */+ const headElements = React.useMemo(() => new Map<string, { pose: string; node: React.ReactElement }>(), [+ tracks, t, onEditBlocks, startLaneReorder, toggleTrack, openHeadMenu, trackNames, onRenameTrack, solo, onResizeTrack,+ ]);/** The head column (outside the scroller, so drawn apart from the rows). */const heads = React.useMemo(() => tracks.map((track, laneIndex) => {const h = rowH(track);@@ -2311,13 +2595,20 @@ export const Timeline = React.memo(function Timeline({const lit = selectedLanes.has(track.lane);const targeted = targetLane === track.lane;const renamingHere = renaming != null && renaming === track.docIndex && track.index === 1;+ /* far from the view, only its place (the one being renamed or dragged keeps all of it) */+ if ((laneIndex < nearFirst || laneIndex > nearLast) && !renamingHere && !liftingHead) {+ return <div key={track.lane} className="rounded-l-[3px]" style={{ marginTop: GAP, height: h, background: laneTone(track, lit) }} />;+ }/* typing a name always has its field; a name given shows when the row has room for it */const nameLine = renamingHere || (Boolean(given) && h >= HEAD_NAME_MIN_H);- /* the main track is marked by its look (its band, the magnet by its badge), not by a name that reads as one */+ /* the main track is marked by its look (its band) and its hover title, not by a name or a badge that reads as a switch */const mainHead = Boolean(track.main) && track.index === 1;/* the track a pill hovered in the app's chat points at */const chatLit = chatTrack != null && track.docIndex === chatTrack;- return (+ const pose = `${liftingHead}:${lit}:${targeted}:${renamingHere}:${chatLit}`;+ const cached = headElements.get(track.lane);+ if (cached?.pose === pose) return cached.node;+ const node = (/* each head is its own block with gaps between, matching its row one to one */<divkey={track.lane}@@ -2428,13 +2719,12 @@ export const Timeline = React.memo(function Timeline({) : nameLine && given ? (<span className="col-span-full w-full min-w-0 justify-self-stretch truncate px-1 text-[10.5px] font-medium leading-[14px]" style={{ color: TL.text }} data-track-name="">{given}</span>) : null}- {mainHead ? (- <Magnet size={10} aria-label={t('timeline.mainTrack')} className="pointer-events-none absolute bottom-1 left-1.5" style={{ color: 'var(--tl-accent)' }} />- ) : null}{onResizeTrack && track.docIndex != null ? <TrackResizeHandle height={h} onResize={(height, done) => onResizeTrack(track, height, done)} /> : null}</div>);- }), [tracks, t, laneOrder, onEditBlocks, startLaneReorder, toggleTrack, selectedLanes, openHeadMenu, chatTrack, trackNames, targetLane, renaming, onRenameTrack, solo, onResizeTrack]);+ headElements.set(track.lane, { pose, node });+ return node;+ }), [tracks, t, laneOrder, onEditBlocks, startLaneReorder, toggleTrack, selectedLanes, openHeadMenu, chatTrack, trackNames, targetLane, renaming, onRenameTrack, solo, onResizeTrack, nearFirst, nearLast, headElements]);/* row backgrounds are fixed to the view and only follow vertical scroll; the clips move horizontally above them */const laneSkins = React.useMemo(() => tracks.map((track) => (@@ -2564,9 +2854,11 @@ export const Timeline = React.memo(function Timeline({const liftingIds = drag.preview? new Set([drag.preview.id, ...drag.preview.moves.map((m) => m.id)]): null;- return tracks.map((track) => {+ return tracks.map((track, laneIndex) => {const h = rowH(track);const liftingHere = Boolean(liftingIds && track.blocks.some((b) => liftingIds.has(b.id)));+ /* a row far from the view keeps its place and its clips in hand, moving or selected (see rowsNear) */+ const near = laneIndex >= nearFirst && laneIndex <= nearLast;/* the edges another clip touches (`<id>:start` / `<id>:end`): their handles stay inside the clip */const touching = new Set(cutsOf(track.blocks).flatMap(([a, b]) => [`${a.id}:end`, `${b.id}:start`]));return (@@ -2601,10 +2893,10 @@ export const Timeline = React.memo(function Timeline({const blockW = (endMs - startMs) * pxPerMs;const winFrom = Math.max(0, Math.min(blockW, thumbWindow.from - blockLeft));const winTo = Math.max(0, Math.min(blockW, thumbWindow.to - blockLeft));- /* clips more than a screen out of view are not drawn, except those in hand, moving or selected */- if (view.width > 0 && (blockLeft + blockW < thumbWindow.from || blockLeft > thumbWindow.to) && !lifting && !live && !picked) {- return null;- }+ /* clips more than a screen out of view, or on a row far from it, are not drawn, except those in hand,+ moving or selected */+ const far = !near || (view.width > 0 && (blockLeft + blockW < thumbWindow.from || blockLeft > thumbWindow.to));+ if (far && !lifting && !live && !picked) return null;/* `length`: the clip has no length (see TimelineBlock.noLength), and the film cannot be drawn until it has */const trouble = block.noLength ? 'length' : block.src ? mediaTrouble?.get(block.src) : undefined;/* the app's chat: the clip of the pill hovered there, and this clip's numbers in the message being written */@@ -2700,17 +2992,17 @@ export const Timeline = React.memo(function Timeline({if (!inGroup) setSelected(own);if (track.locked) return;const at = msAtClientX(e.clientX);- /* ⇧: every track is cut there, as CapCut's */+ /* ⇧: every track is cut there */if (e.shiftKey) { void runSplit(splitAllTargets(tracks, at), at); return; }const cut = new Set(own);void runSplit(tracks.flatMap((tr) => tr.blocks).filter((b) => cut.has(b.id)), at);return;}- /* ⌥-drag copies (this clip alone, or the group it is in), as CapCut's; a ⌥-click picks this clip alone */+ /* ⌥-drag copies (this clip alone, or the group it is in); a ⌥-click picks this clip alone */if (e.altKey) {if (!inGroup) setSelected(withLinked([block.id]));collapseIfClick(e, block.id, true);- if (able.move) drag.start(e, block, 'move', inGroup ? current : [block.id], undefined, undefined, true);+ if (able.move) drag.start(e, block, 'move', inGroup ? current : [block.id], true);return;}if (!inGroup) setSelected(own);@@ -2742,14 +3034,9 @@ export const Timeline = React.memo(function Timeline({className="pointer-events-none absolute inset-x-0 top-0 flex items-center overflow-hidden px-1.5"style={{ height: INFO_H, background: 'rgba(0,0,0,0.3)' }}>- {/* pinned to the left of the view so a clip wider than the screen still says what it is; the scroll- position comes from a CSS variable (set in onScroll), not React, so scrolling rebuilds nothing */}- <span- className="flex min-w-0 items-center gap-1"- style={{- transform: `translateX(clamp(0px, calc(var(--tl-scroll-left, 0px) - ${left}px), ${width - 48}px))`,- }}- >+ {/* pinned to the left of the view so a clip wider than the screen still says what it is (pinLabels,+ on scroll: scrolling rebuilds nothing) */}+ <span className="flex min-w-0 items-center gap-1" data-pin={left} data-pin-max={width - 48}>{/* a voice says so before its name: it is what the subtitles are made from */}{block.kind === 'voice' ? <Mic className="h-2.5 w-2.5 shrink-0 text-white/90" aria-hidden /> : null}<span className="min-w-0 truncate text-[10px] font-medium leading-none text-white/95">@@ -2914,38 +3201,8 @@ export const Timeline = React.memo(function Timeline({clipElements.set(block.id, { pose, node });return node;})}- {/* the cuts between clips that touch: dragged, a roll (one gets longer, the other shorter); not while a move- is in hand, and not on a locked track */}- {/* a cut's roll handle: not on the main track with the magnet, where a cut's edges trim and what follows closes- up, as CapCut's (it has no roll) */}- {!track.locked && mode === 'select' && !(drag.preview?.mode === 'move' && !drag.preview.landed)- && !(prefs.magnet && track.docIndex != null && track.docIndex === mainDoc) ? cutsOf(track.blocks).map(([a, b]) => {- const pa = placedOf(a.id);- const pb = placedOf(b.id);- if (pa?.gone || pb?.gone || !drag.can(a).resize || !drag.can(b).resize) return null;- const atMs = pb?.startMs ?? b.startMs;- const w = rollHit(Math.min(((pa?.endMs ?? a.endMs) - (pa?.startMs ?? a.startMs)) * pxPerMs, ((pb?.endMs ?? b.endMs) - atMs) * pxPerMs));- return (- <span- key={`roll:${a.id}:${b.id}`}- role="presentation"- data-roll={`${a.clipId ?? a.id}|${b.clipId ?? b.id}`}- title={t('timeline.rollHint')}- className="group/roll absolute inset-y-0 z-[11] cursor-col-resize"- style={{ left: Math.round(atMs * pxPerMs) - w / 2, width: w }}- onPointerDown={(e) => {- e.stopPropagation();- if (e.button !== 0) return;- /* a drag rolls the cut (and selects the clip before it then) */- drag.start(e, a, 'roll', undefined, b, () => pickForTrim(e, a));- }}- >- <span aria-hidden className="pointer-events-none absolute inset-y-[2px] left-1/2 w-[2px] -translate-x-1/2 rounded-full bg-[var(--tl-select)] opacity-0 transition-opacity group-hover/roll:opacity-90" />- </span>- );- }) : null}{/* the transitions drawn on this row: a mark over each, picked by a click, resized by its edges */}- {(transitions ?? []).filter((tr) => track.blocks.some((b) => b.clipId === tr.on)).map((tr) => {+ {near && (transitions ?? []).filter((tr) => track.blocks.some((b) => b.clipId === tr.on)).map((tr) => {const span = transitionDrag?.key === tr.key ? transitionSpan(tr, transitionDrag.durationMs) : tr;const x = Math.round(span.startMs * pxPerMs);const w = Math.max(10, Math.round(span.endMs * pxPerMs) - x);@@ -2987,7 +3244,7 @@ export const Timeline = React.memo(function Timeline({);})}{/* the gap picked on this track (on its first row): ⌫ closes it */}- {gap && track.docIndex === gap.track && track.index === 1 ? (+ {near && gap && track.docIndex === gap.track && track.index === 1 ? (<divdata-gap=""className="pointer-events-none absolute inset-y-[2px] z-[3] rounded-[3px] border border-dashed"@@ -2999,8 +3256,8 @@ export const Timeline = React.memo(function Timeline({}}/>) : null}- {trackOverlay?.(track, pxPerMs)}- {track.locked ? (+ {near ? trackOverlay?.(track, pxPerMs) : null}+ {near && track.locked ? (<divclassName="pointer-events-none absolute inset-0 z-[20]"style={{@@ -3017,7 +3274,7 @@ export const Timeline = React.memo(function Timeline({openBlockMenu, openLaneMenu, onEditBlocks, collapseIfClick, selectOne, setSelected, clipElements, thumbWindow, view.width,chatClip, chatDraft, placedOf, pickForTrim, gap, withLinked, runSplit, trackOverlay,fadeOfBlock, fadeDrag, startFade, transitions, transitionDrag, pickedTransition, onPickTransition, onTransition, startTransitionResize,- prefs.magnet, mainDoc,+ nearFirst, nearLast,]);const tickMarks = React.useMemo(() => ticks.map(({ ms, label }) => {@@ -3088,7 +3345,11 @@ export const Timeline = React.memo(function Timeline({const home = tracks.findIndex((tr) => tr.blocks.some((b) => b.id === id));const block = allBlocks.find((b) => b.id === id);if (!block || home < 0) continue;- const at = p.laneDelta+ /* a spot that is taken: the new track the move opens above it */+ const opens = p.opens.get(id);+ const at = opens != null+ ? moveLandingLane({ action: 'insert', at: opens }, tracks, home)+ : p.laneDelta? { laneIndex: home + p.laneDelta, newTrack: false }: moveLandingLane(id === p.id ? p.drop : { action: 'stay' }, tracks, home);/* the floating clip already sits at its own row and time: a slot there would just double it */@@ -3127,24 +3388,25 @@ export const Timeline = React.memo(function Timeline({/*** Ripple trim to the playhead (Q / W): `start` takes the head of the clip off up to the playhead, `end` its tail- * from it, and what follows closes up (with sync lock on every unlocked track; with linkage, on the main track, the- * other tracks along). On the clips given, else the selected ones the playhead is inside, else the main track's- * under it, else the topmost under it; the clips linked to them go along. After Q the playhead goes to the clip's- * start, where what was under it now is, as CapCut's.+ * from it, and what follows on its track closes up (with linkage, what rides on the main track along). On the clips+ * given, else the selected ones the playhead is inside, else the main track's under it, else the one+ * under it on the targeted track, else the topmost under it; the clips linked to them go along. After Q the+ * playhead goes to the clip's start, where what was under it now is.*/const rippleTrimToPlayhead = React.useCallback((edge: 'start' | 'end', given?: readonly TimelineBlock[]) => {const atMs = timeMsRef.current;const lockedRow = (b: TimelineBlock) => tracks.some((tr) => tr.locked && tr.blocks.some((x) => x.id === b.id));const inside = (b: TimelineBlock) => Boolean(b.clipId) && !lockedRow(b) && atMs > b.startMs + TOUCH_MS && atMs < b.endMs - TOUCH_MS;const all = tracks.flatMap((tr) => tr.blocks);- const mainIndex = mainTrackOf(modelRef.current);- const onMain = tracks.filter((tr) => tr.docIndex != null && tr.docIndex === mainIndex).flatMap((tr) => tr.blocks);- const main = (given ?? all.filter((b) => selectedRef.current.includes(b.id))).find(inside) ?? onMain.find(inside) ?? all.find(inside);- if (!main?.clipId) return;- const ids = [main.clipId, ...linkedIds(modelRef.current, [main.clipId]).filter((id) => id !== main.clipId)];- const plan = planRippleTrimTo(modelRef.current, ids, edge, atMs, followOf(prefsRef.current));- void runPlan(plan, `history.stepRippleTrimmed|${main.clipId}`).then((done) => { if (done && edge === 'start') onSeek(main.startMs); });- }, [tracks, runPlan, onSeek]);+ const onMain = tracks.filter((tr) => tr.docIndex != null && tr.docIndex === mainDoc).flatMap((tr) => tr.blocks);+ const onTarget = tracks.filter((tr) => tr.lane === targetLaneRef.current).flatMap((tr) => tr.blocks);+ const lead = (given ?? all.filter((b) => selectedRef.current.includes(b.id))).find(inside)+ ?? onMain.find(inside) ?? onTarget.find(inside) ?? all.find(inside);+ if (!lead?.clipId) return;+ const ids = [lead.clipId, ...linkedIds(modelRef.current, [lead.clipId]).filter((id) => id !== lead.clipId)];+ const plan = planRippleTrimTo(modelRef.current, ids, edge, atMs, switchesOf(prefsRef.current));+ void runPlan(plan, `history.stepRippleTrimmed|${lead.clipId}`).then((done) => { if (done && edge === 'start') onSeek(lead.startMs); });+ }, [tracks, mainDoc, runPlan, onSeek]);/** Link clips (one `data-link`), or unlink them. */const linkBlocks = React.useCallback((blocks: readonly TimelineBlock[]) => {@@ -3167,10 +3429,11 @@ export const Timeline = React.memo(function Timeline({closeGap,link: () => linkBlocks(picked()),unlink: () => unlinkBlocks(picked()),- toggleMagnet: () => togglePref('magnet'),- toggleLinkage: () => togglePref('linkage'),selectSide: (dir) => { setSelected(sideTargets(tracks, timeMsRef.current, dir).map((b) => b.id)); },+ toggleMagnet: () => togglePref('magnet'),toggleSnap: () => togglePref('snap'),+ toggleLinkage: () => togglePref('linkage'),+ togglePreviewAxis: () => togglePref('previewAxis'),split: () => {const atMs = timeMsRef.current;const found = splitTargets(tracks, selectedRef.current, atMs, targetLaneRef.current);@@ -3188,18 +3451,14 @@ export const Timeline = React.memo(function Timeline({nudge: (frames) => {const ids = picked().flatMap((b) => (b.clipId ? [b.clipId] : []));if (!ids.length) return;- /* with the magnet nothing is overwritten (on the main track or off it): into free time only */- const plan = planNudge(modelRef.current, ids, frames, { mode: prefsRef.current.magnet ? 'insert' : 'overwrite', ...followOf(prefsRef.current) });+ const plan = planNudge(modelRef.current, ids, frames, switchesOf(prefsRef.current));if (plan) void runPlan(plan, 'history.stepMove');},- zoomFit: () => {- zoomTo(ZOOM_DEFAULT);- requestAnimationFrame(() => { if (scrollRef.current) scrollRef.current.scrollLeft = 0; });- },+ zoomFit: () => zoomToStable(ZOOM_DEFAULT, { scroll: 0 }),target: () => tracks.find((tr) => tr.lane === targetLaneRef.current)?.docIndex ?? null,};return () => { commandsRef.current = null; };- }, [commandsRef, tracks, rippleTrimToPlayhead, closeGap, linkBlocks, unlinkBlocks, togglePref, withLinked, runSplit, onCopy, magnetRemove, runPlan, zoomTo]);+ }, [commandsRef, tracks, rippleTrimToPlayhead, closeGap, linkBlocks, unlinkBlocks, togglePref, withLinked, runSplit, onCopy, magnetRemove, runPlan, zoomToStable]);/** A fade's entry for a clip's edge: put there at its default length, in one step. */const transitionEntries = React.useCallback((cut: CutRef, kinds: readonly TransitionKind[]): ContextMenuEntry[] => kinds.map((kind) => ({@@ -3255,7 +3514,7 @@ export const Timeline = React.memo(function Timeline({onSelect: () => closeGapOn(found),});}- /* every gap on this track at once (CapCut's 批量闭合空隙) */+ /* every gap on this track closed at once */const row = tracks.find((tr) => tr.lane === menu.lane);if (onEditOps && row?.docIndex != null && !laneLocked && gapsOf(modelRef.current, row.docIndex).length) {const doc = row.docIndex;@@ -3263,7 +3522,7 @@ export const Timeline = React.memo(function Timeline({id: 'close-gaps',label: t('timeline.menuCloseGaps'),icon: <BetweenHorizontalStart size={14} />,- onSelect: () => { void runPlan(planCloseTrackGaps(modelRef.current, doc, followOf(prefsRef.current)), 'history.stepGapsClosed'); },+ onSelect: () => { void runPlan(planCloseTrackGaps(modelRef.current, doc, switchesOf(prefsRef.current)), 'history.stepGapsClosed'); },});}return entries;@@ -3291,7 +3550,7 @@ export const Timeline = React.memo(function Timeline({onSelect: () => { void runSplit(picked); },});}- /* ripple trims to the playhead (Q / W in Premiere): off the head up to it, or off the tail from it, closing up */+ /* ripple trims to the playhead (Q / W): off the head up to it, or off the tail from it, closing up */if (one && onEditOps && one.clipId) {const under = spans(one) && !pickedLocked;out.push({@@ -3415,7 +3674,7 @@ export const Timeline = React.memo(function Timeline({disabled: pickedLocked || !picked.some((b) => b.loc),hint: pickedLocked ? t('timeline.trackLocked') : t('timeline.menuCopyNone'),shortcut: '⌫',- /* as ⌫: with the magnet on, the gap closes */+ /* as ⌫: a gap is left */onSelect: () => { void magnetRemove(picked); },});if (onEditOps) {@@ -3568,6 +3827,7 @@ export const Timeline = React.memo(function Timeline({/* just over the ruler: the toolbar row above it is the room there is */return { anchor, bounds, gap: 2 };};+ inHandRef.current = Boolean(drag.preview || assetHint || marquee || rangeDraft || referDraft || scrubbing || laneOrder || fadeDrag || transitionDrag);const barKey = !barKind ? null : barKind === 'clips' ? `clips:${selKey}` : barKind === 'range' ? `range:${rangeKey}` : 'point';return (@@ -3669,7 +3929,7 @@ export const Timeline = React.memo(function Timeline({) : null}</div>- {/* the switches (lib/timeline-prefs), in CapCut's order: the main-track magnet, snapping, linkage */}+ {/* the switches (lib/timeline-prefs), in this order: the main-track magnet, snapping, linkage, the preview axis */}{onEditOps ? <><span data-timeline-magnet={prefs.magnet ? '1' : '0'}><ToolButton onClick={() => togglePref('magnet')} active={prefs.magnet} label={t('timeline.magnet')}@@ -3690,6 +3950,14 @@ export const Timeline = React.memo(function Timeline({</ToolButton></span></> : null}+ {onHoverPreview ? (+ <span data-timeline-preview-axis={prefs.previewAxis ? '1' : '0'}>+ <ToolButton onClick={() => togglePref('previewAxis')} active={prefs.previewAxis} label={t('timeline.previewAxis')}+ hint={prefs.previewAxis ? t('timeline.previewAxisOn') : t('timeline.previewAxisOff')}>+ <TextCursor size={15} />+ </ToolButton>+ </span>+ ) : null}<ToolButtononClick={() => zoomBy(1 / ZOOM_STEP)}@@ -3753,36 +4021,34 @@ export const Timeline = React.memo(function Timeline({{subRowShown ? <SubtitleRowHead onAdd={() => subRowRef.current?.addAtPlayhead()} /> : null}{markerRowH ? <div style={{ height: markerRowH }} /> : null}<div- ref={headRef}className="relative overflow-hidden"- /* the same padding as the track area, so both scroll the same height and scrollTop stays in sync */- style={{- height: `calc(100% - ${RULER_H + subRowH + markerRowH}px - ${H_SCROLL_H}px)`,- paddingTop: padTop,- paddingBottom: TL_VPAD,- }}+ style={{ height: `calc(100% - ${RULER_H + subRowH + markerRowH}px - ${H_SCROLL_H}px)` }}>- {heads}- {laneOrder ? (() => {- const hover = laneOrder.hoverLane;- let top = padTop;- if (hover < 0) {- /* above all rows */- } else if (hover >= tracks.length) {- top += tracksH;- } else {- for (let i = 0; i < hover; i += 1) top += GAP + rowH(tracks[i]!);- if (hover > laneOrder.fromLane) top += GAP + rowH(tracks[hover]!);- else top += GAP / 2;- }- return (- <div- className="pointer-events-none absolute left-0 right-0 z-40 h-0.5"- data-lane-order-guide=""- style={{ top, background: 'var(--tl-select)' }}- />- );- })() : null}+ {/* moved with the track area's vertical scroll (onScroll), as the rows' backgrounds are; its own block+ (flow-root), so the first head's margin stays inside it and the reorder guide's top counts from it */}+ <div ref={headShiftRef} className="relative flow-root" style={{ transform: rowsShift }}>+ {heads}+ {laneOrder ? (() => {+ const hover = laneOrder.hoverLane;+ let top = 0;+ if (hover < 0) {+ /* above all rows */+ } else if (hover >= tracks.length) {+ top += tracksH;+ } else {+ for (let i = 0; i < hover; i += 1) top += GAP + rowH(tracks[i]!);+ if (hover > laneOrder.fromLane) top += GAP + rowH(tracks[hover]!);+ else top += GAP / 2;+ }+ return (+ <div+ className="pointer-events-none absolute left-0 right-0 z-40 h-0.5"+ data-lane-order-guide=""+ style={{ top, background: 'var(--tl-select)' }}+ />+ );+ })() : null}+ </div></div></div>@@ -3802,6 +4068,7 @@ export const Timeline = React.memo(function Timeline({><divref={seekRef}+ data-zoom-layer="content"role="slider"tabIndex={0}aria-label={t('timeline.seek')}@@ -3827,6 +4094,7 @@ export const Timeline = React.memo(function Timeline({style={{ width: trackPx, cursor: onReferRuler ? (rulerHoverMs == null && !referDraft ? 'col-resize' : 'pointer') : 'col-resize' }}>{tickMarks}+ {previewBar?.length ? <PreviewBar ranges={previewBar} pxPerMs={pxPerMs} /> : null}{onReferRuler ? <RulerRefer hoverMs={rulerHoverMs} draft={referDraft} pxPerMs={pxPerMs} widthPx={trackPx} /> : null}</div></div>@@ -3852,7 +4120,9 @@ export const Timeline = React.memo(function Timeline({} : undefined}><div className="absolute inset-y-0 left-0" style={{ width: trackPx, transform: `translate3d(${-view.left}px,0,0)` }}>- {markerLane.render({ pxPerMs, widthPx: trackPx, snap: snapMarker, guide: setMarkerGuide })}+ <div data-zoom-layer="content" className="absolute inset-0">+ {markerLane.render({ pxPerMs, widthPx: trackPx, snap: snapMarker, guide: setMarkerGuide })}+ </div></div></div>) : null}@@ -3865,10 +4135,7 @@ export const Timeline = React.memo(function Timeline({data-lane-skins=""className="pointer-events-none absolute inset-0 overflow-hidden">- <div- ref={skinsShiftRef}- style={{ transform: `translate3d(0,${padTop - view.top}px,0)` }}- >+ <div ref={skinsShiftRef} style={{ transform: rowsShift }}>{laneSkins}</div></div>@@ -3879,8 +4146,8 @@ export const Timeline = React.memo(function Timeline({/* capture phase: a press on the playhead line goes to the scrub before clips and marquee (grabPlayhead);move / leave only manage the cursor */onPointerDownCapture={grabPlayhead}- onPointerMove={(e) => { hotPlayhead(e); aimBlade(e); }}- onPointerLeave={() => { coldPlayhead(); hideBlade(); }}+ onPointerMove={(e) => { hotPlayhead(e); aimBlade(e); aimAxis(e); }}+ onPointerLeave={() => { coldPlayhead(); hideBlade(); showAxis(null); }}/* no rubber-band: a ruler that bounces makes people think they dragged wrong */className={`tl-scroll absolute inset-0 overflow-y-auto overflow-x-hidden overscroll-none bg-transparent${mode === 'split' ? ' tl-blade' : ''@@ -3904,6 +4171,7 @@ export const Timeline = React.memo(function Timeline({) : (<divref={contentRef}+ data-zoom-layer="content"className="relative select-none"/* full height, so the empty space below the rows can be clicked too (a seek); the centering space ispadding, not a child's margin — a margin would collapse outside this box and not take clicks */@@ -3978,26 +4246,36 @@ export const Timeline = React.memo(function Timeline({className="pointer-events-none absolute inset-y-0 z-[35]"style={{ left: headW - PLAYHEAD_BLEED, right: 0, top: TOOLBAR_H, bottom: H_SCROLL_H, overflow: 'hidden' }}>- {/* moved with transform, not left: the most frequently moving thing here, and transform skips layout */}- <PlayheadTrack- clock={clock}- animate={playing && scrubMs == null}- x={playheadX - scrollLeft + PLAYHEAD_BLEED}- pxPerMs={pxPerMs}- totalMs={totalMs}- scrollRef={scrollRef}- >- <div className="absolute inset-y-0 left-0 w-px" style={{ background: 'var(--tl-playhead)' }} />- {/* the knob; its hit area (24×20) is larger than the visible pin, people aim for the line and miss by a- few pixels. Through the rows the line takes no pointer events: grabbing there is grabPlayhead's. */}- <span- role="presentation"- onPointerDown={startScrub}- className="pointer-events-auto absolute top-0 left-1/2 flex h-[20px] w-[24px] -translate-x-1/2 cursor-col-resize items-start justify-center"+ {/* the preview axis under the pointer (showAxis moves it): a thin line, quieter than the playhead */}+ {onHoverPreview ? (+ <div ref={axisRef} data-preview-axis="" aria-hidden className="absolute inset-y-0 left-0 w-px"+ style={{ opacity: 0, background: 'var(--tl-faint)' }} />+ ) : null}+ {/* moved with transform, not left: the most frequently moving thing here, and transform skips layout; a zoom+ gesture scales its layer (the knob keeps its width) */}+ <div data-zoom-layer="view" data-zoom-bleed={PLAYHEAD_BLEED} className="absolute inset-0">+ <PlayheadTrack+ clock={clock}+ animate={playing && scrubMs == null}+ x={scrubMs == null ? playheadX - scrollLeft + PLAYHEAD_BLEED : null}+ moveRef={playheadMove}+ pxPerMs={pxPerMs}+ totalMs={totalMs}+ scrollRef={scrollRef}>- <PlayheadKnob filled={scrubbing} />- </span>- </PlayheadTrack>+ <div className="absolute inset-y-0 left-0 w-px" style={{ background: 'var(--tl-playhead)' }} />+ {/* the knob; its hit area (24×20) is larger than the visible pin, people aim for the line and miss by a+ few pixels. Through the rows the line takes no pointer events: grabbing there is grabPlayhead's. */}+ <span+ role="presentation"+ onPointerDown={startScrub}+ data-zoom-keep=""+ className="pointer-events-auto absolute top-0 left-1/2 flex h-[20px] w-[24px] -translate-x-1/2 cursor-col-resize items-start justify-center"+ >+ <PlayheadKnob filled={scrubbing} />+ </span>+ </PlayheadTrack>+ </div></div>) : null}@@ -4038,16 +4316,18 @@ export const Timeline = React.memo(function Timeline({{/* the span of a pill hovered in the app's chat (a range, a subtitle line, a moment), tinted on the ruler */}{chat?.span ? (<div className="pointer-events-none absolute z-[26] overflow-hidden" style={{ left: headW, right: 0, top: TOOLBAR_H, height: RULER_H }}>- <div- data-chat-span=""- className="absolute inset-y-0 left-0"- style={{- transform: `translate3d(${chat.span.startMs * pxPerMs - scrollLeft}px,0,0)`,- width: Math.max(2, (chat.span.endMs - chat.span.startMs) * pxPerMs),- background: 'color-mix(in srgb, var(--tl-accent) 45%, transparent)',- boxShadow: 'inset 0 -2px 0 var(--tl-accent)',- }}- />+ <div data-zoom-layer="view" className="absolute inset-0">+ <div+ data-chat-span=""+ className="absolute inset-y-0 left-0"+ style={{+ transform: `translate3d(${chat.span.startMs * pxPerMs - scrollLeft}px,0,0)`,+ width: Math.max(2, (chat.span.endMs - chat.span.startMs) * pxPerMs),+ background: 'color-mix(in srgb, var(--tl-accent) 45%, transparent)',+ boxShadow: 'inset 0 -2px 0 var(--tl-accent)',+ }}+ />+ </div></div>) : null}@@ -4060,35 +4340,40 @@ export const Timeline = React.memo(function Timeline({return (<><div className="pointer-events-none absolute z-[24] overflow-hidden" style={{ left: headW, right: 0, top: TOOLBAR_H, bottom: H_SCROLL_H }}>- <div- data-timeline-range=""- className="absolute inset-y-0 left-0 border-x"- style={{- transform: `translate3d(${fromX}px,0,0)`,- width,- borderColor: 'var(--tl-accent)',- background: 'color-mix(in srgb, var(--tl-accent) 13%, transparent)',- }}- >- <div className="absolute inset-x-0 top-0" style={{ height: RULER_H, background: 'color-mix(in srgb, var(--tl-accent) 28%, transparent)' }} />+ <div data-zoom-layer="view" className="absolute inset-0">+ <div+ data-timeline-range=""+ className="absolute inset-y-0 left-0 border-x"+ style={{+ transform: `translate3d(${fromX}px,0,0)`,+ width,+ borderColor: 'var(--tl-accent)',+ background: 'color-mix(in srgb, var(--tl-accent) 13%, transparent)',+ }}+ >+ <div className="absolute inset-x-0 top-0" style={{ height: RULER_H, background: 'color-mix(in srgb, var(--tl-accent) 28%, transparent)' }} />+ </div></div></div>{/* pinned to the view's left while the band starts before it */}{fromX + width > 0 ? (<div className="pointer-events-none absolute z-[36] overflow-hidden" style={{ left: headW, right: 0, top: TOOLBAR_H + RULER_H + 3, height: 20 }}>- <div- draggable={Boolean(rangeRef && range && !rangeDraft)}- title={rangeRef ? t('host.rangeDrag') : undefined}- onDragStart={(e) => {- if (!rangeRef || !range) return;- e.dataTransfer.setData(STUDIO_REF_TYPE, JSON.stringify([rangeRef(range)]));- e.dataTransfer.setData('text/plain', label);- e.dataTransfer.effectAllowed = 'copy';- }}- className={`absolute top-0 whitespace-nowrap rounded-[4px] px-1.5 py-[2px] text-[10.5px] font-medium leading-[15px] text-white tabular-nums shadow-[0_1px_4px_rgba(0,0,0,.25)] ${rangeRef ? 'pointer-events-auto cursor-grab active:cursor-grabbing' : ''}`}- style={{ left: Math.max(4, fromX + 4), background: 'var(--tl-accent)' }}- >- {label}+ <div data-zoom-layer="view" className="absolute inset-0">+ <div+ data-zoom-keep=""+ draggable={Boolean(rangeRef && range && !rangeDraft)}+ title={rangeRef ? t('host.rangeDrag') : undefined}+ onDragStart={(e) => {+ if (!rangeRef || !range) return;+ e.dataTransfer.setData(STUDIO_REF_TYPE, JSON.stringify([rangeRef(range)]));+ e.dataTransfer.setData('text/plain', label);+ e.dataTransfer.effectAllowed = 'copy';+ }}+ className={`absolute top-0 origin-left whitespace-nowrap rounded-[4px] px-1.5 py-[2px] text-[10.5px] font-medium leading-[15px] text-white tabular-nums shadow-[0_1px_4px_rgba(0,0,0,.25)] ${rangeRef ? 'pointer-events-auto cursor-grab active:cursor-grabbing' : ''}`}+ style={{ left: Math.max(4, fromX + 4), background: 'var(--tl-accent)' }}+ >+ {label}+ </div></div></div>) : null}@@ -4099,7 +4384,7 @@ export const Timeline = React.memo(function Timeline({<SelectionToolbarselection={barKey}measure={measureBar}- hidden={playing || scrubbing || Boolean(marquee || rangeDraft || drag.preview || laneOrder || assetHint)}+ hidden={playing || scrubbing || zooming || Boolean(marquee || rangeDraft || drag.preview || laneOrder || assetHint)}lead={barLead}{...(barLabel ? { label: barLabel } : {})}tools={barTools}@@ -4382,11 +4667,50 @@ function ModePicker({}/**- * The playhead line — while playing it follows the clock itself, outside React.- *- * The clock ticks at 20 Hz; drawn tick by tick the line jumps, zoomed in by a dozen pixels. Each frame it moves on- * from the last tick by the time since, and lines up at the next tick; when a new tick is slightly behind what was- * drawn, it waits instead of stepping back.+ * A playhead held at a place: an animation paused, its time the place in px from HELD_FROM to the left, so moving it is+ * setting its time. A transform written from script made the browser lay the whole page out again on each move (all the+ * timeline's clips); an animation's moves are the compositor's.+ */+const HELD_FROM = 100_000;+const HELD_SPAN = 10_000_000;+function holdAt(el: HTMLElement): Animation {+ const a = el.animate([{ transform: `translate3d(${-HELD_FROM}px,0,0)` }, { transform: `translate3d(${HELD_SPAN - HELD_FROM}px,0,0)` }], { duration: HELD_SPAN, fill: 'both' });+ a.pause();+ return a;+}++/** The line under the ruler's colors: plays late, rendering, rendered, could not be rendered. */+const PREVIEW_BAR: Record<PreviewBarRange['state'], string> = { late: '#e5484d', making: '#e8c547', ready: '#3dd68c', failed: '#8b8d98' };++/**+ * Under the ruler, where the viewer plays late, and its renders: red plays late (rendered once the film stops), yellow+ * is rendering, green plays from its render. Each says so when pointed at; a press goes on to the ruler.+ */+function PreviewBar({ ranges, pxPerMs }: { ranges: readonly PreviewBarRange[]; pxPerMs: number }) {+ const t = useT();+ const title = (r: PreviewBarRange) => (r.state === 'late' ? t('timeline.previewLate')+ : r.state === 'making' ? t('timeline.previewMaking').replace('{p}', String(Math.round((r.ratio ?? 0) * 100)))+ : r.state === 'ready' ? t('timeline.previewReady') : t('timeline.previewFailed'));+ return (+ <>+ {ranges.map((r) => (+ <div+ key={`${r.a}-${r.b}`}+ data-preview-bar={r.state}+ title={title(r)}+ className="absolute bottom-0"+ style={{ left: r.a * 1000 * pxPerMs, width: Math.max(2, (r.b - r.a) * 1000 * pxPerMs), height: 3, background: PREVIEW_BAR[r.state], opacity: 0.9 }}+ />+ ))}+ </>+ );+}++/**+ * The playhead line — while playing it moves by itself, outside React and off the page's main thread: an animation+ * from where the film is to its end, on the clock's line (`line`: where the film is at a moment, and how fast it goes),+ * which the compositor draws every frame. It is made again only when the line changes (a seek, a loop, another speed),+ * the timeline scrolls or zooms. Moved from script each frame instead, the editor laid out its whole page every frame.** Follow-scroll happens here too: out of view, the timeline pages (the playhead at 10% from the left) rather than* recentring every step, which would slide constantly. For a while after the user scrolls, it does not follow.@@ -4395,6 +4719,7 @@ function PlayheadTrack({clock,animate,x,+ moveRef,pxPerMs,totalMs,scrollRef,@@ -4403,8 +4728,10 @@ function PlayheadTrack({clock: PlaybackClock | null | undefined;/** Playing and not scrubbing: the line moves itself. Otherwise it is drawn at `x`. */animate: boolean;- /** Where the line is when not moving itself (scroll already taken off). */- x: number;+ /** Where the line is when not moving itself (scroll already taken off); null: moved by `moveRef` (a scrub). */+ x: number | null;+ /** Set here: moves the line to x at once, outside React (a scrub moves it each frame). */+ moveRef?: React.MutableRefObject<((x: number) => void) | null>;pxPerMs: number;totalMs: number;scrollRef: React.RefObject<HTMLDivElement | null>;@@ -4412,47 +4739,93 @@ function PlayheadTrack({}) {const ref = React.useRef<HTMLDivElement>(null);const live = Boolean(clock) && animate;+ /* still, or dragged: an animation held at the place (its time is the px), not a transform written from script,+ which laid the page out again on every step of a drag */+ const held = React.useRef<Animation | null>(null);+ const hold = React.useCallback((at: number) => {+ const el = ref.current;+ if (!el) return;+ held.current ??= holdAt(el);+ held.current.currentTime = at + HELD_FROM;+ }, []);React.useLayoutEffect(() => {- if (live || !ref.current) return;- ref.current.style.transform = `translate3d(${x}px,0,0)`;- }, [live, x]);+ if (live || x == null) return;+ hold(x);+ }, [live, x, hold]);+ React.useEffect(() => {+ if (!moveRef) return undefined;+ moveRef.current = (at) => { if (!live) hold(at); };+ return () => { moveRef.current = null; };+ }, [moveRef, live, hold]);+ React.useEffect(() => {+ if (!live) return undefined;+ /* moving by itself: the held one gives way, and is made again when it stops */+ held.current?.cancel();+ held.current = null;+ return undefined;+ }, [live]);+ React.useEffect(() => () => { held.current?.cancel(); }, []);React.useEffect(() => {- if (!live || !clock) return undefined;+ const el = ref.current;+ if (!live || !clock || !el) return undefined;const scroller = scrollRef.current;- let tick = { ms: clock.get(), at: performance.now() };- let shown = tick.ms;let userAt = -Infinity;- const off = clock.subscribe(() => { tick = { ms: clock.get(), at: performance.now() }; });- const onUser = () => { userAt = performance.now(); };- scroller?.addEventListener('wheel', onUser, { passive: true });- scroller?.addEventListener('pointerdown', onUser, { passive: true });- let raf = 0;- const frame = (now: number) => {- let ms = Math.min(tick.ms + Math.min(now - tick.at, 120), totalMs);- /* a new tick slightly behind what was drawn: wait, do not step back. Far behind (a seek, a loop): follow it. */- if (ms < shown && shown - ms < 80) ms = shown;- shown = ms;- const el = scrollRef.current;- const scrollLeft = el?.scrollLeft ?? 0;- const px = ms * pxPerMs;- if (el && now - userAt > 1500 && pxPerMs > 0) {- if (px < scrollLeft + FOLLOW_EDGE || px > scrollLeft + el.clientWidth - FOLLOW_EDGE) {- el.scrollLeft = Math.max(0, px - el.clientWidth * 0.1);- }- }- if (ref.current) {- ref.current.style.transform = `translate3d(${px - (el?.scrollLeft ?? scrollLeft) + PLAYHEAD_BLEED}px,0,0)`;+ let scroll = scroller?.scrollLeft ?? 0;+ let width = scroller?.clientWidth ?? 0;+ /* the line the animation runs on now, and the scroll it was made for */+ let made: { ms: number; at: number; rate: number; scroll: number } | null = null;+ let anim: Animation | null = null;+ const lineNow = () => clock.line?.() ?? { ms: clock.get(), at: performance.now(), rate: 1 };+ const make = () => {+ const line = lineNow();+ const from = Math.min(line.ms, totalMs);+ const place = (ms: number) => `translate3d(${ms * pxPerMs - scroll + PLAYHEAD_BLEED}px,0,0)`;+ anim?.cancel();+ anim = el.animate([{ transform: place(from) }, { transform: place(totalMs) }], {+ duration: Math.max(1, (totalMs - from) / Math.max(1e-6, line.rate)), easing: 'linear', fill: 'both',+ });+ /* on the page's clock: the document's timeline counts from the same origin as performance.now() */+ anim.startTime = line.at;+ made = { ...line, scroll };+ };+ /* a new line moves the film elsewhere than this one: within a pixel, it is the same line (the sound's small+ corrections) */+ const moved = () => {+ const line = lineNow();+ if (!made || line.rate !== made.rate || made.scroll !== scroll) return true;+ const now = performance.now();+ const at = (l: { ms: number; at: number; rate: number }) => l.ms + Math.max(0, now - l.at) * l.rate;+ return Math.abs(at(line) - at(made)) * pxPerMs > 1;+ };+ const follow = () => {+ const px = clock.get() * pxPerMs;+ if (scroller && performance.now() - userAt > 1500 && pxPerMs > 0 && (px < scroll + FOLLOW_EDGE || px > scroll + width - FOLLOW_EDGE)) {+ scroller.scrollLeft = Math.max(0, px - width * 0.1);+ scroll = scroller.scrollLeft;}- raf = requestAnimationFrame(frame);};- raf = requestAnimationFrame(frame);+ const tick = () => { follow(); if (moved()) make(); };+ make();+ tick();+ const off = clock.subscribe(tick);+ const onUser = () => { userAt = performance.now(); };+ const onScroll = () => { scroll = scroller?.scrollLeft ?? 0; if (moved()) make(); };+ const sized = new ResizeObserver(() => { width = scroller?.clientWidth ?? 0; });+ if (scroller) {+ scroller.addEventListener('wheel', onUser, { passive: true });+ scroller.addEventListener('pointerdown', onUser, { passive: true });+ scroller.addEventListener('scroll', onScroll, { passive: true });+ sized.observe(scroller);+ }return () => {- cancelAnimationFrame(raf);off();+ anim?.cancel();+ sized.disconnect();scroller?.removeEventListener('wheel', onUser);scroller?.removeEventListener('pointerdown', onUser);+ scroller?.removeEventListener('scroll', onScroll);};}, [live, clock, pxPerMs, totalMs, scrollRef]);diff --git a/packages/openfilm/studio/ui/src/components/ViewerBar.tsx b/packages/openfilm/studio/ui/src/components/ViewerBar.tsxindex 09d1b28..46ea8f4 100644--- a/packages/openfilm/studio/ui/src/components/ViewerBar.tsx+++ b/packages/openfilm/studio/ui/src/components/ViewerBar.tsx@@ -7,7 +7,7 @@ import { Expand, Pause, Play, Repeat } from 'lucide-react';import { useT } from '@/i18n';import { formatTimecode, useTimecodeFps } from '@/lib/timecode';import { PANE_BTN, PANE_ICON } from './dock-pane-bar';-import { LiveTime, type PlaybackClock } from './LiveTime';+import { LiveText, type PlaybackClock } from './LiveTime';import { Tooltip } from './Tooltip';/** The bar's buttons: the pane-bar size (22×22, icon 14) plus a keyboard focus ring (Tab must show where it is). */@@ -24,7 +24,7 @@ export function ViewerBar({loop,}: {timeMs: number;- /** While playing the time is on the clock; only the timecode subscribes to it, the rest of the bar stays still. */+ /** The time on the clock (playing, scrubbing): only the timecode follows it, the rest of the bar stays still. */clock?: PlaybackClock | null;totalMs: number;playing: boolean;@@ -49,7 +49,7 @@ export function ViewerBar({{/* where we are is read constantly: body color, 12px; the length one step fainter. One line, never wrapped:when it does not fit, the length is clipped first. No hour field for a film under an hour. */}<span className="min-w-0 overflow-hidden text-ellipsis whitespace-nowrap text-[12px] tabular-nums text-[var(--text)]">- <LiveTime clock={clock} timeMs={timeMs}>{(liveMs) => formatTimecode(liveMs, { hours })}</LiveTime>+ <LiveText clock={clock} timeMs={timeMs} format={(ms) => formatTimecode(ms, { hours })} /><span className="text-[11px] text-[var(--text-faint)]">{' / '}{formatTimecode(totalMs, { hours })}</span>diff --git a/packages/openfilm/studio/ui/src/components/export/ExportCenter.tsx b/packages/openfilm/studio/ui/src/components/export/ExportCenter.tsxindex 6c5ff75..e69be87 100644--- a/packages/openfilm/studio/ui/src/components/export/ExportCenter.tsx+++ b/packages/openfilm/studio/ui/src/components/export/ExportCenter.tsx@@ -34,6 +34,7 @@ import {exportGifDims,exportGifEstimateBytes,exportPreset,+ presetFps,rangeMarks,type ExportPresetGroup,type ExportQuality,@@ -387,7 +388,7 @@ export function ExportCenter(props: ExportCenterProps) {switch (dest) {case 'social':return s.presets.map((id) => presets.find((p) => p.id === id) ?? null).filter((p) => p !== null).map((p) => ({- kind: 'video', codec: 'h264', frame: p.frame, fill: 'contain', shortEdge: p.shortEdge, fps: p.fps,+ kind: 'video', codec: 'h264', frame: p.frame, fill: 'contain', shortEdge: p.shortEdge, fps: presetFps(p, projectFps),quality: s.socialQuality, audio: true, preset: p.name, label: p.name,...burn(s.socialSubs === 'auto' ? p.burnSubtitles : s.socialSubs === 'on'), ...ranged,}));@@ -646,7 +647,7 @@ export function ExportCenter(props: ExportCenterProps) {{on && <Check size={13} className="shrink-0 text-[var(--text)]" />}</span><span className="text-[11px] tabular-nums text-[var(--text-faint)]">- {dims.w}×{dims.h} · {p.fps}fps+ {dims.w}×{dims.h} · {presetFps(p, projectFps)}fps</span>{tooLong && (<span className="text-[10.5px] leading-snug text-[var(--warn)]">diff --git a/packages/openfilm/studio/ui/src/components/inspector-fields.tsx b/packages/openfilm/studio/ui/src/components/inspector-fields.tsxindex 61d3817..02aa77e 100644--- a/packages/openfilm/studio/ui/src/components/inspector-fields.tsx+++ b/packages/openfilm/studio/ui/src/components/inspector-fields.tsx@@ -24,7 +24,7 @@ import { MenuSelect } from './MenuSelect';/* ───────────────────────────── skin ───────────────────────────── */-/** A field: light fill, no border; a thin edge on hover, the accent ring on focus. Figma's properties panel look. */+/** A field: light fill, no border; a thin edge on hover, the accent ring on focus. */export const FIELD = 'group/field relative flex h-[26px] min-w-0 w-full items-center overflow-hidden rounded-[5px] bg-[var(--fill-tsp)] ring-1 ring-inset ring-transparent transition-[box-shadow,background-color] hover:ring-[var(--border)] focus-within:bg-[var(--bg)] focus-within:ring-[1.5px] focus-within:ring-[var(--accent)]';export const INPUT = 'h-[26px] min-w-0 flex-1 border-0 bg-transparent pr-2 text-[11px] text-[var(--text)] outline-none tabular-nums placeholder:text-[var(--text-faint)]';const PREFIX = 'flex h-[26px] w-[22px] shrink-0 select-none items-center justify-center text-[10.5px] text-[var(--text-faint)]';@@ -678,9 +678,9 @@ export function SelectField({/* ───────────────────────────── color ───────────────────────────── *//**- * A color: swatch + hex (with its opacity after it when it has one). The swatch opens our own picker (ColorPicker,- * like Figma's); the hex can be typed too (`#` optional). Gradients, `url()` and the like show as written, with a- * checkerboard swatch — that is not one color, and the picker cannot make it.+ * A color: swatch + hex (with its opacity after it when it has one). The swatch opens our own picker (ColorPicker);+ * the hex can be typed too (`#` optional). Gradients, `url()` and the like show as written, with a checkerboard+ * swatch — that is not one color, and the picker cannot make it.*/export function ColorField({label, value, onCommit, onPreview,@@ -798,7 +798,7 @@ export function useTimeUnit(): [TimeUnit, (next: TimeUnit) => void] {/* ───────────────────────────── glyphs ───────────────────────────── */-/* Figma's little marks that lucide does not have: opacity (half-filled square), radius, angle, type sizes. */+/* Little marks that lucide does not have: opacity (half-filled square), radius, angle, type sizes. */export function OpacityGlyph() {return (<svg width="11" height="11" viewBox="0 0 11 11" aria-hidden>diff --git a/packages/openfilm/studio/ui/src/components/inspector-look.tsx b/packages/openfilm/studio/ui/src/components/inspector-look.tsxindex 61222d7..622ff73 100644--- a/packages/openfilm/studio/ui/src/components/inspector-look.tsx+++ b/packages/openfilm/studio/ui/src/components/inspector-look.tsx@@ -338,7 +338,7 @@ export function MaskGlyph({ shape }: { shape: MaskShape | 'none' }) {}/**- * A mask, as CapCut's: a shape the picture shows through (or, inverted, is hidden by), placed, sized, turned and+ * A mask: a shape the picture shows through (or, inverted, is hidden by), placed, sized, turned and* feathered in % of the box. Written as `mask-image` layers (lib/clip-mask: what each shape is in CSS, and how it sits* with the faded edges, which share the property, and with the crop's clip-path). A mask written by hand is "custom":* the raw CSS (Advanced) has it.@@ -518,7 +518,7 @@ const CORNERS = ['top-left', 'top-right', 'bottom-right', 'bottom-left'] as constype Corner = (typeof CORNERS)[number];/**- * Corner radius, as Figma's: one number for all four, or (the button beside it) each corner its own. A crop cuts the+ * Corner radius: one number for all four, or (the button beside it) each corner its own. A crop cuts the* box's own corners away, so it carries the same roundness (one for all: a crop's shape rounds its corners alike).*/function RadiusField({ look, t }: { look: Look; t: T }) {@@ -587,11 +587,11 @@ function CornerGlyph({ corner }: { corner: Corner }) {/*** Opacity, corner radius (`radius`: for what has corners — a box, a picture, a line with its own fill) and blend,- * as Figma's Appearance.+ * the Appearance section.*//*** What the things in hand looked like before a menu showed something else on the picture (a hovered font, weight,- * size or blend mode, as Figma shows one on the canvas before it is picked): the stage measures a layer again after+ * size or blend mode, shown on the picture before it is picked): the stage measures a layer again after* each preview, so by then it reads as the preview. Giving up (`restore`) paints that back; a pick (`commit`) keeps it.*/function usePreviewed(look: Look) {@@ -658,7 +658,7 @@ export function AppearanceSection({ look, t, children, radius = false }: { look:/* ───────────────────────────── fill ───────────────────────────── *//**- * Fill, as Figma's: what paints the thing — a line's color, a box's background, a shape's fill. One the thing may go+ * Fill: what paints the thing — a line's color, a box's background, a shape's fill. One the thing may go* without (a box's background) has "−" to take it off, and "+" brings one back.*/export function FillSection({ look, t, fills, add }: {@@ -701,7 +701,7 @@ export function FillSection({ look, t, fills, add }: {/* ───────────────────────────── stroke ───────────────────────────── *//**- * Stroke, as Figma's: color, weight, where it lies against the edge (inside, across, outside) and its line (solid,+ * Stroke: color, weight, where it lies against the edge (inside, across, outside) and its line (solid,* dashed, dotted). Drawn as an `outline` with its offset (lib/clip-look placedStrokeOf): it adds nothing to the box,* so the layout does not move as it is added or thickened.*/@@ -804,7 +804,7 @@ const ADJUST_RANGE: Record<AdjustKey, { min: number; max: number; unit: string;* grayscale): 0 is as is, a double-click puts one back, the reset all. Filter functions without a control here* (sepia, a url) are kept as written, in their place.*/-/* the picture's color; its blur is an effect (Figma's layer blur) */+/* the picture's color; its blur is an effect (a layer blur) */const COLOR_KEYS = ADJUST_KEYS.filter((k) => k !== 'blur');export function AdjustSection({ look, t }: { look: Look; t: T }) {@@ -866,7 +866,7 @@ export function AdjustSection({ look, t }: { look: Look; t: T }) {type EffectId = 'shadow' | 'inner' | 'blur' | 'backdrop' | 'fade';/**- * Effects, as Figma's, each added with "+" and taken off with "−", none taking room unless used: a drop shadow, an+ * Effects, each added with "+" and taken off with "−", none taking room unless used: a drop shadow, an* inner shadow (`inner`: for what has a box of its own to cast it in), a layer blur, a background blur — and faded* edges, a video editor's.*@@ -1110,7 +1110,7 @@ export function EffectsSection({ look, t, inner = false }: { look: Look; t: T; i/** What a type property is when nothing sets it (what giving up a preview paints back when the layer had none). */const TYPE_NEUTRAL: Record<string, string> = { 'font-weight': '400', 'font-style': 'normal', 'line-height': 'normal', 'letter-spacing': 'normal' };-/** A family's weight menu: its own weights and italics by name, as Figma's ("Semi Bold", "Bold Italic"). */+/** A family's weight menu: its own weights and italics by name ("Semi Bold", "Bold Italic"). */function weightOptions(styles: FontStyles | null, t: T): { value: string; label: string }[] {const list = styleOptions(styles ?? { weights: NAMED_WEIGHTS });return list.map((s) => {@@ -1122,7 +1122,7 @@ function weightOptions(styles: FontStyles | null, t: T): { value: string; label:}/**- * Type, as Figma's typography panel: font (its menu shows each family on the picture as it is pointed at), weight+ * Type: font (its menu shows each family on the picture as it is pointed at), weight* (the family's own), size (with a menu of common sizes), line height, letter spacing, alignment, case* (`text-transform`) and color. Text in an SVG has no line layout and is colored by its fill.*/@@ -1286,7 +1286,7 @@ export function TypographySection({ look, t, svg, sample }: { look: Look; t: T;);}-/** The font size field's menu: the common sizes, as Figma's; the one under the pointer shown before it is picked. */+/** The font size field's menu: the common sizes; the one under the pointer shown before it is picked. */function FontSizeMenu({ t, onPick, onPreview, onRevert }: { t: T; onPick: (n: number) => void; onPreview: (n: number) => void; onRevert: () => void }) {const [open, setOpen] = React.useState(false);const previewing = React.useRef(false);diff --git a/packages/openfilm/studio/ui/src/components/settings/AgentsSection.tsx b/packages/openfilm/studio/ui/src/components/settings/AgentsSection.tsxindex c3d4f26..cd6f483 100644--- a/packages/openfilm/studio/ui/src/components/settings/AgentsSection.tsx+++ b/packages/openfilm/studio/ui/src/components/settings/AgentsSection.tsx@@ -28,6 +28,7 @@ import { ProviderMark } from './ProviderMark';import { agentMark } from '@/lib/provider-marks';import { SettingsSelect } from './SettingsSelect';import { SettingsButton, SettingsField, SettingsGroup, SettingsInset, SettingsItem, SettingsLinkButton, SettingsPage, SettingsStatus, SettingsSwitch, settingsError } from './ui';+import { ReportLink } from './DiagnosticsGroup';function useHostAgents(): HostAgent[] | null {const [agents, setAgents] = React.useState<HostAgent[] | null>(null);@@ -316,6 +317,8 @@ export function AgentsSection() {) : null}{open ? <OwnModels agent={agent} onDone={() => setKeyOpen(false)} /> : null}{said ? <p className={settingsError}>{said}</p> : null}+ {/* what to send when it keeps failing */}+ {said ? <ReportLink /> : null}</div>) : null}</SettingsItem>diff --git a/packages/openfilm/studio/ui/src/components/settings/DiagnosticsGroup.tsx b/packages/openfilm/studio/ui/src/components/settings/DiagnosticsGroup.tsxnew file mode 100644index 0000000..d4ac0c9--- /dev/null+++ b/packages/openfilm/studio/ui/src/components/settings/DiagnosticsGroup.tsx@@ -0,0 +1,202 @@+/**+ * Settings → Developer's Diagnostics, for when something does not work and a person wants to say why: the report to+ * copy (short: `openfilm doctor` with the last week's problems, this browser, the desktop app's agents; lib/diagnostics),+ * the diagnostic file to export (the rest: the logs and the failed turns, zipped; server/diagnostics.mjs), and the+ * problems of the last two weeks, newest first.+ */+import React from 'react';+import { Check, Copy, Download, Loader2 } from 'lucide-react';+import { useLanguage, useT } from '@/i18n';+import { studioHost } from '@/lib/host';+import { fullReport, pageFacts } from '@/lib/diagnostics';+import { api, type StudioProblem } from '@/api';+import { SettingsButton, SettingsGroup, SettingsInset, SettingsItem, SettingsSwitch } from './ui';++/** The report as text, made now: the computer's (with its problems), this browser's, and the app's agents. */+async function makeReport(): Promise<string> {+ const [computer, app] = await Promise.all([api.doctor(), studioHost?.agents?.report?.().catch(() => null) ?? null]);+ return fullReport(computer.text, pageFacts(), app);+}++/**+ * Copying the report: its state, and the report itself when the browser does not let the page copy (an agent's+ * preview pane may not), to select by hand.+ */+export function useReportCopy() {+ const [state, setState] = React.useState<'idle' | 'making' | 'copied' | 'failed'>('idle');+ const [shown, setShown] = React.useState<string | null>(null);+ const copy = () => {+ setState('making');+ void makeReport()+ .then((text) => navigator.clipboard.writeText(text).then(() => { setShown(null); setState('copied'); }, () => { setShown(text); setState('idle'); }))+ .catch(() => setState('failed'));+ };+ return { state, shown, copy };+}++/** The button that copies the report, as Settings → Developer and an agent with a problem (Settings → Agents) show it. */+export function CopyReportButton({ copying, variant = 'default' }: { copying: ReturnType<typeof useReportCopy>; variant?: 'default' | 'quiet' }) {+ const t = useT();+ const { state, copy } = copying;+ return (+ <SettingsButton variant={variant} disabled={state === 'making'} onClick={copy}>+ {state === 'making' ? <Loader2 size={15} className="animate-spin" aria-hidden /> : state === 'copied' ? <Check size={15} aria-hidden /> : <Copy size={15} aria-hidden />}+ {state === 'making' ? t('settings.report.making') : state === 'copied' ? t('settings.report.copied') : t('settings.report.copy')}+ </SettingsButton>+ );+}++/** The report to select, where the page could not copy it. */+export function ReportText({ text }: { text: string }) {+ const t = useT();+ return (+ <textarea readOnly value={text} rows={12} aria-label={t('settings.report.title')} onFocus={(e) => e.currentTarget.select()}+ className="mb-2 w-full resize-y rounded-md border border-[var(--border)] bg-[var(--surface-2)] p-2 font-mono text-[11.5px] leading-snug text-[var(--text)]" />+ );+}++/** The report as a link to copy it, under an agent's problem (Settings → Agents). */+export function ReportLink() {+ const t = useT();+ const copying = useReportCopy();+ return (+ <>+ <p className="text-[13.5px] leading-relaxed text-[var(--text-muted)]">+ <button type="button" onClick={copying.copy} disabled={copying.state === 'making'} title={t('settings.report.hint')}+ className="underline underline-offset-2 hover:text-[var(--text)] disabled:opacity-60">+ {copying.state === 'making' ? t('settings.report.making') : copying.state === 'copied' ? t('settings.report.copied') : t('settings.report.copy')}+ </button>+ {copying.state === 'failed' ? ` ${t('settings.report.failed')}` : null}+ </p>+ {copying.shown ? <ReportText text={copying.shown} /> : null}+ </>+ );+}++/**+ * What an exported file holds, in words, from the names of what went in (server/diagnostics.mjs): each part once, the+ * logs and the turns counted.+ */+function fileParts(files: string[], conversations: boolean, t: (key: string) => string): string[] {+ const count = (prefix: string) => files.filter((f) => f.startsWith(prefix)).length;+ const logs = count('logs/');+ const turns = count('turns/');+ return [+ ...(files.includes('report.txt') ? [t('settings.report.partReport')] : []),+ ...(files.includes('problems.jsonl') ? [t('settings.report.partProblems')] : []),+ ...(logs ? [t('settings.report.partLogs').replace('{count}', String(logs))] : []),+ ...(turns ? [t(conversations ? 'settings.report.partTurnsWords' : 'settings.report.partTurns').replace('{count}', String(turns))] : []),+ ...(files.includes('agents/codex.txt') ? [t('settings.report.partCodex')] : []),+ ];+}++/* what turning on "Include what was said" adds, said in full before it is on */+const ADDS = ['settings.report.adds1', 'settings.report.adds2', 'settings.report.adds3', 'settings.report.adds4', 'settings.report.adds5'];++/** How many problems show before "Show all". */+const PROBLEMS_SHOWN = 5;++export function DiagnosticsGroup() {+ const t = useT();+ const locale = useLanguage();+ const copying = useReportCopy();+ /* what was said in failed turns: off unless the person turns it on, and only after reading what it adds (`asking`) */+ const [conversations, setConversations] = React.useState(false);+ const [asking, setAsking] = React.useState(false);+ const [exporting, setExporting] = React.useState<{ state: 'idle' | 'making' | 'failed' } | { state: 'done'; name: string; parts: string[] }>({ state: 'idle' });+ const [problems, setProblems] = React.useState<StudioProblem[] | null>(null);+ const [all, setAll] = React.useState(false);+ React.useEffect(() => { void api.problems().then(setProblems, () => setProblems([])); }, []);++ const exportFile = () => {+ setExporting({ state: 'making' });+ void makeReport()+ .then((report) => api.exportDiagnostics(report, conversations))+ .then((made) => setExporting({ state: 'done', name: made.path.split(/[\\/]/).pop() ?? made.path, parts: fileParts(made.files, made.conversations, t) }))+ .catch(() => setExporting({ state: 'failed' }));+ };++ const when = (iso: string) => {+ const at = new Date(iso);+ return Number.isNaN(at.getTime()) ? iso : at.toLocaleString(locale, { month: 'short', day: 'numeric', hour: '2-digit', minute: '2-digit' });+ };+ const shown = problems ? (all ? problems : problems.slice(0, PROBLEMS_SHOWN)) : [];++ return (+ <SettingsGroup title={t('settings.report.group')}>+ <SettingsItem+ title={t('settings.report.title')}+ description={copying.state === 'failed' ? t('settings.report.failed') : copying.shown ? t('settings.report.select') : t('settings.report.hint')}+ control={<CopyReportButton copying={copying} />}+ >+ {copying.shown ? <ReportText text={copying.shown} /> : null}+ </SettingsItem>+ <SettingsItem+ title={t('settings.report.conversations')}+ description={conversations ? t('settings.report.conversationsOn') : t('settings.report.conversationsHint')}+ control={(+ <SettingsSwitch checked={conversations || asking} label={t('settings.report.conversations')}+ onChange={(on) => { if (on) setAsking(true); else { setAsking(false); setConversations(false); } }} />+ )}+ >+ {asking ? (+ <SettingsInset>+ <p className="text-[14px] font-medium text-[var(--text)]">{t('settings.report.addsTitle')}</p>+ <ul className="flex list-disc flex-col gap-1 pl-5 text-[13.5px] leading-relaxed text-[var(--text)]">+ {ADDS.map((key) => <li key={key}>{t(key)}</li>)}+ </ul>+ <p className="text-[13px] leading-relaxed text-[var(--text-muted)]">{t('settings.report.addsKept')}</p>+ <p className="text-[13px] leading-relaxed text-[var(--warn)]">{t('settings.report.addsWho')}</p>+ <div className="flex justify-end gap-1.5">+ <SettingsButton variant="quiet" onClick={() => setAsking(false)}>{t('settings.report.addsNo')}</SettingsButton>+ <SettingsButton onClick={() => { setAsking(false); setConversations(true); }}>{t('settings.report.addsYes')}</SettingsButton>+ </div>+ </SettingsInset>+ ) : null}+ </SettingsItem>+ <SettingsItem+ title={t('settings.report.export')}+ description={exporting.state === 'failed' ? t('settings.report.exportFailed')+ : exporting.state === 'done' ? t('settings.report.exported').replace('{name}', exporting.name)+ : t('settings.report.exportHint')}+ control={(+ <SettingsButton disabled={exporting.state === 'making' || asking} onClick={exportFile}>+ {exporting.state === 'making' ? <Loader2 size={15} className="animate-spin" aria-hidden /> : <Download size={15} aria-hidden />}+ {exporting.state === 'making' ? t('settings.report.exporting') : t('settings.report.exportButton')}+ </SettingsButton>+ )}+ >+ {exporting.state === 'done' ? (+ <div className="mb-2 text-[13px] leading-relaxed text-[var(--text-muted)]">+ <p>{t('settings.report.exportedHas')}</p>+ <ul className="list-disc pl-5">{exporting.parts.map((part) => <li key={part}>{part}</li>)}</ul>+ </div>+ ) : null}+ </SettingsItem>+ <SettingsItem+ title={t('settings.report.problems')}+ description={problems && !problems.length ? t('settings.report.noProblems') : t('settings.report.problemsHint')}+ >+ {shown.length ? (+ <ul className="mb-2 flex flex-col gap-1.5">+ {shown.map((p, i) => (+ <li key={`${p.t}:${i}`} className="min-w-0 rounded-md bg-[var(--surface-2)] px-2.5 py-1.5 text-[12.5px] leading-snug">+ <div className="flex gap-2 text-[var(--text-muted)]">+ <span className="shrink-0 tabular-nums">{when(p.t)}</span>+ <span className="truncate">{[p.agent ?? p.area, p.step].filter(Boolean).join(' · ')}</span>+ </div>+ <div className="break-words text-[var(--text)]">{p.what}</div>+ </li>+ ))}+ </ul>+ ) : null}+ {problems && problems.length > PROBLEMS_SHOWN && !all ? (+ <button type="button" onClick={() => setAll(true)}+ className="mb-2 text-[13px] text-[var(--text-muted)] underline underline-offset-2 transition hover:text-[var(--text)]">+ {t('settings.report.more').replace('{count}', String(problems.length))}+ </button>+ ) : null}+ </SettingsItem>+ </SettingsGroup>+ );+}diff --git a/packages/openfilm/studio/ui/src/components/settings/SettingsModal.tsx b/packages/openfilm/studio/ui/src/components/settings/SettingsModal.tsxindex e4f9fe1..5d1fa4d 100644--- a/packages/openfilm/studio/ui/src/components/settings/SettingsModal.tsx+++ b/packages/openfilm/studio/ui/src/components/settings/SettingsModal.tsx@@ -13,10 +13,12 @@ import { shortcutHint } from '@/lib/shortcut-hint';import { SHORTCUTS, type ShortcutKey } from '@/lib/timeline-keys';import { studioHost, type HostDeveloper, type HostUpdateState } from '@/lib/host';import { showWhatsNew } from '@/lib/whats-new';+import { usePreviewPrefs, writePreviewPref } from '@/lib/preview-prefs';import { hasNotes, newestVersion } from '../WhatsNew';import { useWebUpdate } from '../UpdateButton';import { api, type StudioPrefs, type StudioVersion } from '@/api';import { AgentsSection } from './AgentsSection';+import { DiagnosticsGroup } from './DiagnosticsGroup';import { ModelsSection } from './ModelsSection';import { ProvidersSection } from './ProvidersSection';import { SettingsSelect } from './SettingsSelect';@@ -26,11 +28,11 @@ import { StorageGroup } from './StorageGroup';export type SettingsSection = 'general' | 'agents' | 'providers' | 'models' | 'developer' | 'shortcuts';-/* the nav, in groups: what OpenFilm does, then help (Agents and Developer only inside an app with a chat:- lib/host.ts `agents`, `developer`) */+/* the nav, in groups: what OpenFilm does, then help (Agents only inside an app with a chat: lib/host.ts `agents`;+ Developer always, for its diagnostics) */const NAV: Array<{ group: 'settings' | 'help'; sections: SettingsSection[] }> = [{ group: 'settings', sections: ['general', ...(studioHost?.agents ? ['agents' as const] : []), 'providers', 'models'] },- { group: 'help', sections: ['shortcuts', ...(studioHost?.developer ? ['developer' as const] : [])] },+ { group: 'help', sections: ['shortcuts', 'developer'] },];/** where OpenFilm lives, linked at the foot of the nav */@@ -55,7 +57,7 @@ const SECTION_WORDS: Record<SettingsSection, string | string[]> = {agents: 'settings.agents',providers: 'settings.providers',models: 'settings.models',- developer: 'settings.developer',+ developer: ['settings.developer', 'settings.report'],shortcuts: 'settings.shortcuts',};@@ -247,11 +249,13 @@ function GeneralSection() {}/**- * How the preview plays heavy footage (studio/server/proxies.mjs): from a lighter copy made in the background, as- * CapCut's proxies, and how tall that copy is. Exports always read the originals.+ * How the preview plays heavy footage (studio/server/proxies.mjs): from a lighter copy made in the background (a+ * proxy), and how tall that copy is; whether pages draw at the viewer's size, and whether stretches that play+ * late are rendered to play smoothly (lib/preview-prefs). Exports always read the originals and draw at full size.*/function PlaybackGroup() {const t = useT();+ const { fitPages, renders } = usePreviewPrefs();const [prefs, setPrefs] = React.useState<StudioPrefs | null>(null);React.useEffect(() => { void api.prefs().then(setPrefs).catch(() => {}); }, []);if (!prefs) return null;@@ -280,6 +284,16 @@ function PlaybackGroup() {)}/>) : null}+ <SettingsItem+ title={t('settings.playback.fitPages')}+ description={t('settings.playback.fitPagesHint')}+ control={<SettingsSwitch checked={fitPages} onChange={(on) => writePreviewPref('fitPages', on)} label={t('settings.playback.fitPages')} />}+ />+ <SettingsItem+ title={t('settings.playback.renders')}+ description={t('settings.playback.rendersHint')}+ control={<SettingsSwitch checked={renders} onChange={(on) => writePreviewPref('renders', on)} label={t('settings.playback.renders')} />}+ /></SettingsGroup>);}@@ -428,7 +442,11 @@ function AppAboutGroup() {);}-/** What the app's chat shows of each turn: what it changed in the files, and its full log (lib/host.ts `developer`). */+/**+ * Diagnostics (DiagnosticsGroup), for when something does not work; how playing goes, in the viewer's corner+ * (lib/preview-prefs `stats`); in the app, what its chat shows of each turn: what it changed in the files, and its+ * full log (lib/host.ts `developer`).+ */function DeveloperSection() {const t = useT();const developer = studioHost?.developer;@@ -438,26 +456,36 @@ function DeveloperSection() {void developer.get().then(setPrefs);return developer.onChange(setPrefs);}, [developer]);- if (!developer) return null;const change = (next: Partial<HostDeveloper>) => {setPrefs((was) => (was ? { ...was, ...next } : was));- void developer.set(next);+ void developer?.set(next);};+ const { stats } = usePreviewPrefs();return (<SettingsPage note={t('settings.developer.intro')}>- <SettingsGroup title={t('settings.developer.group')} footnote={t('settings.developer.where')}>- {/* drawn once the app has said whether each is on: drawn off first, a switch slid on each time the page opened */}- <SettingsItem- title={t('settings.developer.changes')}- description={t('settings.developer.changesHint')}- control={prefs ? <SettingsSwitch checked={prefs.changes} label={t('settings.developer.changes')} onChange={(on) => change({ changes: on })} /> : null}- />+ <DiagnosticsGroup />+ <SettingsGroup title={t('settings.developer.playbackGroup')}><SettingsItem- title={t('settings.developer.logs')}- description={t('settings.developer.logsHint')}- control={prefs ? <SettingsSwitch checked={prefs.logs} label={t('settings.developer.logs')} onChange={(on) => change({ logs: on })} /> : null}+ title={t('settings.developer.playbackStats')}+ description={t('settings.developer.playbackStatsHint')}+ control={<SettingsSwitch checked={stats} onChange={(on) => writePreviewPref('stats', on)} label={t('settings.developer.playbackStats')} />}/></SettingsGroup>+ {developer ? (+ <SettingsGroup title={t('settings.developer.group')} footnote={t('settings.developer.where')}>+ {/* drawn once the app has said whether each is on: drawn off first, a switch slid on each time the page opened */}+ <SettingsItem+ title={t('settings.developer.changes')}+ description={t('settings.developer.changesHint')}+ control={prefs ? <SettingsSwitch checked={prefs.changes} label={t('settings.developer.changes')} onChange={(on) => change({ changes: on })} /> : null}+ />+ <SettingsItem+ title={t('settings.developer.logs')}+ description={t('settings.developer.logsHint')}+ control={prefs ? <SettingsSwitch checked={prefs.logs} label={t('settings.developer.logs')} onChange={(on) => change({ logs: on })} /> : null}+ />+ </SettingsGroup>+ ) : null}{newestVersion() ? (<SettingsGroup title={t('settings.developer.releaseGroup')}><SettingsItemdiff --git a/packages/openfilm/studio/ui/src/components/settings/StorageGroup.tsx b/packages/openfilm/studio/ui/src/components/settings/StorageGroup.tsxindex b160b58..db6faa3 100644--- a/packages/openfilm/studio/ui/src/components/settings/StorageGroup.tsx+++ b/packages/openfilm/studio/ui/src/components/settings/StorageGroup.tsx@@ -1,13 +1,15 @@/**- * Settings → General → Storage: where new projects go (studio/server's locations, src/locations.mjs). It shows its- * folder and the free space on its disk, and can be changed (the system's folder dialog), opened in the file manager,- * or set back to its default. Projects made before stay where they are. Exports have no setting: the export dialog- * picks the folder and keeps the last one.+ * Settings → General → Storage: the projects library, the folder every project is a folder of (studio/server's+ * locations, src/locations.mjs). It shows its folder and the free space on its disk, and can be changed (the system's+ * folder dialog), opened in the file manager, or set back to its default. When projects are in it, a change asks+ * whether they move too; left behind, they stay where they are, and in the list. Exports have no setting: the export+ * dialog picks the folder and keeps the last one.*/import React from 'react';import { useT } from '@/i18n';import { api, type StudioLocation, type StudioLocations } from '@/api';import { studioHost } from '@/lib/host';+import { ConfirmDialog } from '../ConfirmDialog';import { SettingsButton, SettingsField, SettingsGroup, SettingsItem, settingsError } from './ui';type Which = keyof StudioLocations;@@ -24,29 +26,40 @@ export function StorageGroup() {const [error, setError] = React.useState<{ which: Which; text: string } | null>(null);/* where no folder dialog can open (a browser on another system), the path is typed */const [typing, setTyping] = React.useState<{ which: Which; text: string } | null>(null);+ /* a new folder for a library with projects in it: whether they move too */+ const [asking, setAsking] = React.useState<{ which: Which; folder: string | null } | null>(null);+ const [note, setNote] = React.useState<{ which: Which; text: string } | null>(null);const load = React.useCallback(() => { void api.locations().then(setWhere).catch(() => {}); }, []);React.useEffect(load, [load]);if (!where) return null;- const keep = async (which: Which, folder: string | null) => {+ const apply = async (which: Which, folder: string | null, move: boolean) => {setBusy(which);setError(null);+ setNote(null);try {- await api.setPrefs({ projectsFolder: folder });+ const done = await api.moveLibrary(folder, move);setTyping(null);- load();+ setWhere(done.locations);+ if (done.failed.length) setError({ which, text: t('settings.storage.moveFailed').replace('{names}', done.failed.map((f) => f.name).join(', ')) });+ if (done.moved) setNote({ which, text: t('settings.storage.moved').replace('{count}', String(done.moved)) });} catch (e) {setError({ which, text: e instanceof Error ? e.message : String(e) });} finally {setBusy(null);}};+ const keep = (which: Which, folder: string | null) => {+ const now = where[which];+ if (now.count > 0 && (folder ?? now.default) !== now.path) setAsking({ which, folder });+ else void apply(which, folder, false);+ };const change = async (which: Which) => {const ask = { title: t(`settings.storage.${which}Pick`), button: t('settings.storage.pickButton'), at: where[which].path };try {const pick = studioHost?.folders?.pick;const picked = pick ? await pick(ask) : await api.pickFolder(ask.title, ask.at);- if (picked) await keep(which, picked);+ if (picked) keep(which, picked);} catch {setTyping({ which, text: where[which].path });}@@ -60,7 +73,7 @@ export function StorageGroup() {<><span className="block">{t(`settings.storage.${which}Hint`)}</span>{typing?.which === which ? (- <form className="mt-2 flex items-center gap-2" onSubmit={(e) => { e.preventDefault(); if (typing.text.trim()) void keep(which, typing.text.trim()); }}>+ <form className="mt-2 flex items-center gap-2" onSubmit={(e) => { e.preventDefault(); if (typing.text.trim()) keep(which, typing.text.trim()); }}><SettingsField autoFocus value={typing.text} onChange={(e) => setTyping({ which, text: e.target.value })} spellCheck={false}aria-label={t(`settings.storage.${which}`)} className="font-mono text-[13px]"onKeyDown={(e) => { if (e.key === 'Escape') { e.preventDefault(); e.stopPropagation(); setTyping(null); } }} />@@ -70,13 +83,14 @@ export function StorageGroup() {<span className="mt-1 block break-all font-mono text-[13px] text-[var(--text)]" title={place.path}>{place.path}</span>)}{place.free != null ? <span className="mt-0.5 block text-[13px]">{t('settings.storage.free').replace('{size}', size(place.free))}</span> : null}+ {note?.which === which ? <span className="mt-1 block text-[13px]" role="status">{note.text}</span> : null}{error?.which === which ? <span className={`mt-1 block ${settingsError}`} role="alert">{error.text}</span> : null}</>)}control={(<>{place.chosen ? (- <SettingsButton variant="quiet" disabled={busy === which} onClick={() => void keep(which, null)} title={place.default}>{t('settings.storage.reset')}</SettingsButton>+ <SettingsButton variant="quiet" disabled={busy === which} onClick={() => keep(which, null)} title={place.default}>{t('settings.storage.reset')}</SettingsButton>) : null}<SettingsButton variant="quiet" onClick={() => void api.openLocation(which).catch(() => {})}>{t('settings.storage.show')}</SettingsButton><SettingsButton disabled={busy === which} onClick={() => void change(which)}>{t('settings.storage.change')}</SettingsButton>@@ -88,6 +102,19 @@ export function StorageGroup() {return (<SettingsGroup title={t('settings.storage.group')}>{row('projects', where.projects)}+ <ConfirmDialog+ open={!!asking}+ title={t('settings.storage.moveTitle')}+ description={asking ? t('settings.storage.moveDesc')+ .replace('{count}', String(where[asking.which].count))+ .replace('{from}', where[asking.which].path)+ .replace('{to}', asking.folder ?? where[asking.which].default) : undefined}+ confirmLabel={t('settings.storage.moveYes')}+ altLabel={t('settings.storage.moveNo')}+ onConfirm={() => { const a = asking; setAsking(null); if (a) void apply(a.which, a.folder, true); }}+ onAlt={() => { const a = asking; setAsking(null); if (a) void apply(a.which, a.folder, false); }}+ onCancel={() => setAsking(null)}+ /></SettingsGroup>);}diff --git a/packages/openfilm/studio/ui/src/components/stage-menu.tsx b/packages/openfilm/studio/ui/src/components/stage-menu.tsxindex 0823dfa..00083d3 100644--- a/packages/openfilm/studio/ui/src/components/stage-menu.tsx+++ b/packages/openfilm/studio/ui/src/components/stage-menu.tsx@@ -1,5 +1,5 @@/**- * The stage's context menus (FilmStageSelect asks for one on a right-click): as in Figma, what was hit decides the+ * The stage's context menus (FilmStageSelect asks for one on a right-click): what was hit decides the* list. A layer inside a page, a whole clip (the same actions as its block on the timeline), several layers boxed* together; and after them on every menu, Show… / Unlock… for the layers that cannot be clicked any more. Items that* cannot run stay, grayed, with the reason.diff --git a/packages/openfilm/studio/ui/src/components/use-editor-tools.tsx b/packages/openfilm/studio/ui/src/components/use-editor-tools.tsxindex 559e428..5f52ad2 100644--- a/packages/openfilm/studio/ui/src/components/use-editor-tools.tsx+++ b/packages/openfilm/studio/ui/src/components/use-editor-tools.tsx@@ -17,11 +17,11 @@ import {} from '@/lib/markers';import type { ClipEdit } from '@/lib/film-clip-edits';import { heardClips, toggleSolo } from '@/lib/solo';-import { magnetOn, type EditMode, type EditModel } from '@/lib/timeline-edit';+import type { EditModel } from '@/lib/timeline-edit';+import { readTimelinePrefs, switchesOf } from '@/lib/timeline-prefs';import type { KeyCommand } from '@/lib/timeline-keys';import type { TimelineBlock, TimelineTrack } from '@/lib/timeline-layout';import type { MediaListing } from '@/lib/workspace-resources';-import { followOf, readTimelinePrefs } from '@/lib/timeline-prefs';import { ownTrackHeight, sizeOf, trackHeightsOf, withTrackHeight, TRACK_SIZES, type TrackSize } from '@/lib/track-heights';import type { Player } from '@/editor/player';import type { OutsideStep } from '@/editor/use-film';@@ -114,7 +114,7 @@ export function useEditorTools({const atMs = at ?? timeRef.current;const clip = on === undefined ? markerClip(tracksRef.current, selectedClipIds, atMs) : on;const { list, added } = addMarker(markersRef.current, atMs, clip);- /* one there already: M again names it, as Premiere's */+ /* one there already: M again names it */if (list.length === markersRef.current.length) { setNaming(added.id); return; }saveMarkers(list);if (added.clip && clip) toast.show(t('editorTools.markerAddedOn').replace('{clip}', clip.title));@@ -258,10 +258,9 @@ export function useEditorTools({let still: string;try { still = await api.freezeFrame(projectId, block.src, srcMs); }catch (e) { toast.showError(t('editorTools.freezeFail').replace('{reason}', (e as Error).message)); return; }- const prefs = readTimelinePrefs();- const model = editModel();- const mode: EditMode = magnetOn(model, ti, prefs.magnet) ? 'insert' : 'overwrite';- const ops = planFreeze(model, { clip, track: ti, atMs: at, still, mode, ...followOf(prefs) });+ /* the still goes in between at the playhead: what follows on that track moves on (with linkage, what+ rides on the main track along) */+ const ops = planFreeze(editModel(), { clip, track: ti, atMs: at, still, mode: 'insert', ...switchesOf(readTimelinePrefs()) });if (!ops) { toast.show(t('timeline.trackLocked')); return; }const failed = await edit(ops, `history.stepFroze|${clip.id}`);if (failed) toast.showError(failed);diff --git a/packages/openfilm/studio/ui/src/components/useBlockDrag.ts b/packages/openfilm/studio/ui/src/components/useBlockDrag.tsindex a2b01e5..d8adf47 100644--- a/packages/openfilm/studio/ui/src/components/useBlockDrag.ts+++ b/packages/openfilm/studio/ui/src/components/useBlockDrag.ts@@ -1,6 +1,6 @@/**- * Dragging on the timeline: a clip moved (or copied, ⌥), an edge trimmed, a cut rolled- * between its neighbors. Press, follow the pointer, write the result to film.html on release.+ * Dragging on the timeline: a clip moved (or copied, ⌥), an edge trimmed. Press, follow the pointer, write the result+ * to film.html on release.** Clips are a projection of the evaluated film, not data to change freely: release sends an edit and the timeline* redraws from the film that comes back. Two consequences:@@ -8,9 +8,9 @@* · after release the clips stay where they were let go until the new layout arrives, instead of jumping back* first (which looks like a failed drag).*- * What a gesture does to the other clips is planned by lib/timeline-edit (insert or overwrite, ripple, linked clips,- * sync lock), every frame, so the clips it pushes, trims or cuts are drawn where they will be before release; release- * sends that plan, one write and one undo step.+ * What a gesture does to the other clips is planned by lib/timeline-edit (the main track's magnet, linkage, linked+ * clips), every frame, so the clips it pushes or carries are drawn where they will be before release; release sends+ * that plan, one write and one undo step.** The idle / pending / dragging gesture with a 5 px threshold follows mature editors: without it, clicking a clip* would be a zero-length drag that writes the same value back.@@ -26,7 +26,6 @@ import {groupLaneShift,moveDestFor,moveEditMode,- rangeOverlaps,snapTargetsFor,SNAP_THRESHOLD_PX,trimFence,@@ -44,19 +43,18 @@ import {planEdges,planMove,planRippleTrim,- rollMoves,sourceLeftMs,- type EditMode,type EditModel,type EditPlan,+ type MoveMode,type TrackDest,} from '@/lib/timeline-edit';import { planCopies } from '@/lib/timeline-clipboard';-import { followOf, type TimelinePrefs } from '@/lib/timeline-prefs';+import { switchesOf, type TimelinePrefs } from '@/lib/timeline-prefs';import type { TimelineBlock, TimelineTrack } from '@/lib/timeline-layout';-/** What a press on the timeline does: move a clip, trim one of its edges, roll a cut. */-export type GestureMode = DragMode | 'roll';+/** What a press on the timeline does: move a clip, or trim one of its edges. */+export type GestureMode = DragMode;/*** The tracks as places to drop. `except` are the clips in hand (the dragged one and the selection moving with it):@@ -78,9 +76,9 @@ function dropLanesOf(lanes: readonly TimelineTrack[], except: readonly string[])}));}-/** What the label beside the pointer says while trimming or rolling. */+/** What the label beside the pointer says while trimming. */export interface GestureTip {- kind: 'trim' | 'ripple' | 'roll';+ kind: 'trim' | 'ripple';/** How far the edge, the cut, the content or the clip moved (film ms). */deltaMs: number;/** The clip's length now, for a trim. */@@ -124,8 +122,10 @@ export interface DragPreview {/** Released: this only holds the clips' places until the write lands (and only while the old layout is shown). */landed: boolean;mode: GestureMode;- /** A move: whether it inserts (pushing what follows) or overwrites (cutting what it lands on). */- editMode: EditMode;+ /** A move: put down (a taken spot opens a track) or inserted (pushing what follows on). */+ editMode: MoveMode;+ /** Clips in hand the move puts on a new track because their spot is taken: block id → the track's film.html place. */+ opens: ReadonlyMap<string, number>;/** An insert onto a track: where it goes in (a line is drawn there). */insertAtMs: number | null;/** Where the clips the edit pushes, trims or cuts are drawn meanwhile, by block id; null: it goes. */@@ -141,10 +141,10 @@ export interface BlockDrag {saving: boolean;error: string | null;/**- * Attached to the clip body, its edges and the cuts between clips. `selected`: the clips moving along (a move);- * `other`: the clip after the cut (a roll). ⌥ at the press (`e.altKey`) trims or rolls this clip alone.+ * Attached to the clip body and its edges. `selected`: the clips moving along (a move). ⌥ at the press (`e.altKey`)+ * trims this clip alone; for a move it copies (`copy`).*/- start: (e: React.PointerEvent, block: TimelineBlock, mode: GestureMode, selected?: readonly string[], other?: TimelineBlock, onLift?: () => void, copy?: boolean) => void;+ start: (e: React.PointerEvent, block: TimelineBlock, mode: GestureMode, selected?: readonly string[], copy?: boolean) => void;/** Whether a clip can move / be trimmed: decides handles and cursors. */can: (block: TimelineBlock) => { move: boolean; resize: boolean };dismissError: () => void;@@ -155,11 +155,23 @@ function overHostPanel(ev: PointerEvent): boolean {return Boolean(document.elementFromPoint(ev.clientX, ev.clientY)?.closest('[data-studio-host-panel]'));}+/** The clips in hand a plan puts on a new track: block id → the track's film.html place. */+function opensOf(+ plan: EditPlan | null,+ blockOfClip: ReadonlyMap<string, TimelineBlock>,+ inHand: ReadonlySet<string>,+): Map<string, number> {+ const out = new Map<string, number>();+ for (const [clipId, at] of plan?.placed ?? []) {+ const b = blockOfClip.get(clipId);+ if (b && inHand.has(b.id) && at && typeof at.track === 'object') out.set(b.id, at.track.insert);+ }+ return out;+}+/** The history label of a gesture, naming the clip (see OperationHistory's stepText). */function stepOf(mode: GestureMode, ripple: boolean, clipId: string): string {- const key = mode === 'move' ? 'history.stepMoved'- : mode === 'roll' ? 'history.stepRolled'- : ripple ? 'history.stepRippleTrimmed' : 'history.stepTrimmed';+ const key = mode === 'move' ? 'history.stepMoved' : ripple ? 'history.stepRippleTrimmed' : 'history.stepTrimmed';return `${key}|${clipId}`;}@@ -174,7 +186,7 @@ export function useBlockDrag(opts: {/** More times to snap to: the markers (ms). */snapPointsMs?: readonly number[];pxPerMs: number;- /** The timeline's switches: snapping, the magnet (insert / ripple), sync lock, linked clips. */+ /** The timeline's switch: snapping. */prefs: TimelinePrefs;/** The timeline's scroller: it scrolls by itself when a drag reaches its left or right edge. */scrollEl?: React.RefObject<HTMLElement | null>;@@ -229,16 +241,12 @@ export function useBlockDrag(opts: {block: TimelineBlock,mode: GestureMode,selected?: readonly string[],- other?: TimelineBlock,- /** Called once when the press becomes a drag (a roll selects its clip only then: a click on a cut is the cut's). */- onLift?: () => void,- /** A move that copies (⌥ at the press, as CapCut's): the clips stay, copies land where they are let go. */+ /** A move that copies (⌥ at the press): the clips stay, copies land where they are let go. */copy = false,) => {if (e.button !== 0) return;const able = can(block);if (mode === 'move' ? !able.move : !able.resize) return;- if (mode === 'roll' && (!other || !can(other).resize)) return;cancelGesture.current?.();setError(null);@@ -258,13 +266,13 @@ export function useBlockDrag(opts: {const startScrollTop = latest.current.scrollEl?.current?.scrollTop ?? 0;/* the film time under the hand at the press: an insert goes before or after the clip under it */const grabMs = block.startMs + (startX - pointerTarget.getBoundingClientRect().left) / pxPerMs;- /* ⌥ at the press: this clip alone, not the clips linked to it (a trim, a roll; for a move ⌥ copies) */- const alone = e.altKey && (mode === 'trim-start' || mode === 'trim-end' || mode === 'roll');+ /* ⌥ at the press: this clip alone, not the clips linked to it (a trim; for a move ⌥ copies) */+ const alone = e.altKey && (mode === 'trim-start' || mode === 'trim-end');const geom: Block = { id: block.id, startMs: block.startMs, endMs: block.endMs };/* a trim also leaves out where the dragged edge is now: with clips end to end the neighbor's edge sits rightthere and would hold the edge in place (see snapTargetsFor) */- const edgeMs = mode === 'trim-end' || mode === 'roll' ? block.endMs+ const edgeMs = mode === 'trim-end' ? block.endMs: mode === 'trim-start' ? block.startMs: undefined;const locked = new Set(lanes.filter((lane) => lane.locked).flatMap((lane) => lane.blocks.map((b) => b.id)));@@ -289,9 +297,9 @@ export function useBlockDrag(opts: {const singleLanes = dropLanesOf(lanes, [block.id]);const groupLanes = crowd.length ? dropLanesOf(lanes, [block.id, ...crowd.map((b) => b.id)]) : singleLanes;const snapCache = new Map<string, SnapTarget[]>();- /* without the magnet a trim stops at the neighbors on the clip's own track (every row of it) */+ /* a trim stops at the neighbors on the clip's own track (every row of it) */const fence = mode === 'trim-start' || mode === 'trim-end' ? trimFence(geom, singleLanes[homeLaneIndex]?.occupied ?? []) : undefined;- /* the magnet acts on the main track alone: a trim there ripples, elsewhere it stops at the neighbors */+ /* on the main track with the magnet a trim ripples: what follows moves with the edge */const ripple = magnetOn(model, homeLane?.docIndex, prefs.magnet) && (mode === 'trim-start' || mode === 'trim-end');let dragging = false;@@ -322,7 +330,7 @@ export function useBlockDrag(opts: {const scrolledY = (latest.current.scrollEl?.current?.scrollTop ?? startScrollTop) - startScrollTop;const deltaMs = (ev.clientX - startX + scrolled) / pxPerMs;const snapping = p.snap;- const movingIds = [block.id, ...crowd.map((b) => b.id), ...(other ? [other.id] : []), ...partners.map((b) => b.id)];+ const movingIds = [block.id, ...crowd.map((b) => b.id), ...partners.map((b) => b.id)];const snapKey = `${latest.current.playheadMs}`;if (snapping && !snapCache.has(snapKey)) {snapCache.clear();@@ -332,40 +340,29 @@ export function useBlockDrag(opts: {const base = {id: block.id, moves: [] as BlockMove[], landMoves: [] as BlockMove[], offsetY: 0, hoverLane: homeLaneIndex,band: 'body' as DropBand, drop: { action: 'stay' } as TrackDrop, laneDelta: 0, trackMoves: [], droppable: true,- landed: false, mode, editMode: 'overwrite' as EditMode, insertAtMs: null,+ landed: false, mode, editMode: 'place' as MoveMode, opens: new Map<string, number>(), insertAtMs: null,};if (mode !== 'move') {- /* trims, rolls, slips and slides: the clips stay on their rows; the plan says where every edge lands */- let plan: EditPlan & { deltaMs: number };- let snappedTo: SnapTarget | null = null;- let tip: GestureTip;- if (mode === 'trim-start' || mode === 'trim-end') {- const out = applyDrag(geom, mode, deltaMs, targets, pxPerMs, block.room, undefined, ripple ? undefined : fence);- const edge = mode === 'trim-end' ? 'end' : 'start';- const want = edge === 'end' ? out.endMs - geom.endMs : out.startMs - geom.startMs;- plan = ripple- ? planRippleTrim(m, ids, edge, want, followOf(p))- : planEdges(m, ids.map((id) => ({ id, kind: edge })), want);- if (plan.deltaMs === want) snappedTo = out.snappedTo;- const own = plan.placed.get(block.clipId!);- /* how much source is left past that edge once it moved (pulled out, the edge moves away from the clip) */- const left = (sourceLeftMs(m, block.clipId!, edge) ?? Infinity) - (edge === 'end' ? plan.deltaMs : -plan.deltaMs);- tip = {- kind: ripple ? 'ripple' : 'trim', deltaMs: plan.deltaMs, lengthMs: own ? own.endMs - own.startMs : geom.endMs - geom.startMs,- atMs: edge === 'end' || ripple ? (own?.endMs ?? geom.endMs) : (own?.startMs ?? geom.startMs), lane: homeLaneIndex,- ...(left < 1 ? { sourceEnd: true } : {}),- };- } else {- const out = applyDrag(geom, 'trim-end', deltaMs, targets, pxPerMs);- const want = out.endMs - geom.endMs;- plan = planEdges(m, rollMoves(m, block.clipId!, other!.clipId!, !alone), want);- if (plan.deltaMs === want) snappedTo = out.snappedTo;- tip = { kind: 'roll', deltaMs: plan.deltaMs, atMs: geom.endMs + plan.deltaMs, lane: homeLaneIndex };- }- lastPlan = plan;+ /* a trim: the clips stay on their rows; the plan says where every edge lands. Rippling (the main track with the+ magnet), the neighbor is no fence: it moves along */+ const out = applyDrag(geom, mode, deltaMs, targets, pxPerMs, block.room, undefined, ripple ? undefined : fence);+ const edge = mode === 'trim-end' ? 'end' : 'start';+ const want = edge === 'end' ? out.endMs - geom.endMs : out.startMs - geom.startMs;+ const plan = ripple+ ? planRippleTrim(m, ids, edge, want, switchesOf(p))+ : planEdges(m, ids.map((id) => ({ id, kind: edge })), want, switchesOf(p));+ const snappedTo = plan.deltaMs === want ? out.snappedTo : null;const own = plan.placed.get(block.clipId!);- document.body.style.cursor = mode === 'roll' ? 'col-resize' : 'ew-resize';+ /* how much source is left past that edge once it moved (pulled out, the edge moves away from the clip) */+ const left = (sourceLeftMs(m, block.clipId!, edge) ?? Infinity) - (edge === 'end' ? plan.deltaMs : -plan.deltaMs);+ const tip: GestureTip = {+ kind: ripple ? 'ripple' : 'trim', deltaMs: plan.deltaMs, lengthMs: own ? own.endMs - own.startMs : geom.endMs - geom.startMs,+ atMs: edge === 'end' || ripple ? (own?.endMs ?? geom.endMs) : (own?.startMs ?? geom.startMs), lane: homeLaneIndex,+ ...(left < 1 ? { sourceEnd: true } : {}),+ };+ lastPlan = plan;+ document.body.style.cursor = 'ew-resize';last = {...base,startMs: own?.startMs ?? geom.startMs,@@ -409,27 +406,19 @@ export function useBlockDrag(opts: {const drop = grouped ? { action: 'stay' as const } : moveDestFor(homeLane?.docIndex, singleLanes, hit.lane);/** Looks flush: make it flush. The nearest snap target is often the playhead a few ms off a neighbor's edge —- * under a pixel on screen, but an overwrite would cut those ms off the neighbor (flushShiftMs). Only with- * snapping on, for one clip, overwriting.+ * under a pixel on screen, but those ms would put it on a new track (flushShiftMs). Only with snapping on, for+ * one clip, put down.*/const destLane = drop.action === 'move' ? singleLanes.find((l) => l.docIndex === drop.trackIndex) : singleLanes[homeLaneIndex];const flush = !grouped && snapping && drop.action !== 'insert'? flushShiftMs({ startMs: out.startMs, endMs: out.endMs }, destLane?.occupied ?? [], SNAP_THRESHOLD_PX / pxPerMs): null;- /* along its own track (alone, or with its linked clips, none changing track), onto another clip: it goes in- between instead of cutting it (moveEditMode). Onto another, not one in hand: those move with it (dragged past- the gap to the next selected clip, it is not landing on that one) */- const alongOwnTrack = grouped ? shift.ok && shift.delta === 0 : drop.action === 'stay';- const wouldLand = { startMs: out.startMs + (flush?.shiftMs ?? 0), endMs: out.endMs + (flush?.shiftMs ?? 0) };- const overlaps = alongOwnTrack && rangeOverlaps(wouldLand, groupLanes[homeLaneIndex]?.occupied ?? []);- /* the track it lands on: the magnet inserts on the main track; elsewhere with the magnet it covers nothing (a clip- landing on another goes to a free track, see planMove), ⌥ inserting there */- const landsOn = groupOpens != null ? null : drop.action === 'move' ? drop.trackIndex : drop.action === 'insert' ? null : homeLane?.docIndex;- const onMain = magnetOn(m, landsOn, p.magnet);- const editMode: EditMode = p.magnet && !onMain- ? (altNow ? 'insert' : 'overwrite')- : moveEditMode({ magnet: onMain, alt: altNow, overlaps });- const settle = editMode === 'overwrite' ? flush : null;+ /* a copy (⌥ at the press, often still held) is always put down: ⌥ inserts only a move */+ const editMode: MoveMode = copy ? 'place' : moveEditMode(altNow);+ /* onto the main track with the magnet it goes in between: the insert point decides, not a snap */+ const landsOn = groupOpens != null ? null : drop.action === 'move' ? drop.trackIndex : drop.action === 'stay' ? homeLane?.docIndex : null;+ const mainInsert = !grouped && magnetOn(m, landsOn, p.magnet);+ const settle = editMode === 'place' && !mainInsert ? flush : null;const to = new Map<string, TrackDest>();if (drop.action === 'move') to.set(block.clipId!, drop.trackIndex);if (drop.action === 'insert') to.set(block.clipId!, { insert: drop.at });@@ -442,8 +431,8 @@ export function useBlockDrag(opts: {const moveBy = out.startMs + (settle?.shiftMs ?? 0) - geom.startMs;/* ⌥ at the press: copies land there, the clips stay (planCopies) */const plan = outside || drop.action === 'refuse' || !shift.ok ? null : copy- ? planCopies(m, { ids, deltaMs: moveBy, pointerMs: grabMs + deltaMs, to, magnet: p.magnet, ...followOf(p) })- : planMove(m, { ids, deltaMs: moveBy, pointerMs: grabMs + deltaMs, to, mode: editMode, magnet: p.magnet, ...followOf(p) });+ ? planCopies(m, { ids, deltaMs: moveBy, to, pointerMs: grabMs + deltaMs, ...switchesOf(p) })+ : planMove(m, { ids, deltaMs: moveBy, pointerMs: grabMs + deltaMs, to, mode: editMode, ...switchesOf(p) });lastPlan = plan;document.body.style.cursor = outside || copy ? 'copy' : 'grabbing';const landed = plan?.placed.get(block.clipId!);@@ -454,7 +443,7 @@ export function useBlockDrag(opts: {startMs: geom.startMs + deltaMs,endMs: geom.endMs + deltaMs,/* a push into contact counts as a snap too: the guide shows it landed against the neighbor */- snappedTo: plan && editMode === 'overwrite' ? (settle ? { ms: settle.edgeMs, kind: 'edge' as const } : out.snappedTo) : null,+ snappedTo: plan && editMode === 'place' && !mainInsert ? (settle ? { ms: settle.edgeMs, kind: 'edge' as const } : out.snappedTo) : null,moves: crowd.map((b) => ({ id: b.id, startMs: b.startMs + deltaMs, endMs: b.endMs + deltaMs })),landStartMs,landEndMs: landStartMs + (geom.endMs - geom.startMs),@@ -471,7 +460,8 @@ export function useBlockDrag(opts: {trackMoves: shift.ok ? shift.moves : [],droppable: Boolean(plan),editMode,- insertAtMs: plan && editMode === 'insert' && drop.action !== 'insert' ? landStartMs : null,+ opens: opensOf(plan, blockOfClip, inHand),+ insertAtMs: plan && (editMode === 'insert' || mainInsert) && drop.action !== 'insert' ? landStartMs : null,ghosts: plan ? ghostsOf(plan, inHand) : new Map(),tip: null,};@@ -535,7 +525,6 @@ export function useBlockDrag(opts: {if (!dragLifted(mode, dx, dy)) return;dragging = true;document.body.style.userSelect = 'none';- onLift?.();}lastEv = ev;if (mode === 'move') altNow = ev.altKey;diff --git a/packages/openfilm/studio/ui/src/editor/Preview.tsx b/packages/openfilm/studio/ui/src/editor/Preview.tsxindex a08c52a..73f5f69 100644--- a/packages/openfilm/studio/ui/src/editor/Preview.tsx+++ b/packages/openfilm/studio/ui/src/editor/Preview.tsx@@ -14,8 +14,9 @@ import { forwardRef, useEffect, useImperativeHandle, useLayoutEffect, useRef, usimport type { Film } from '../api';import { useT } from '@/i18n';import type { ClipSpan } from '@/lib/film-shape';-import type { Sound } from './player';-import { reloaded, shownAfter, updateKeys, type Frame } from './preview-frames';+import type { Anchor, Sound } from './player';+import { pageScaleFor, reloaded, shownAfter, updateKeys, type Frame } from './preview-frames';+import { usePreviewPrefs } from '@/lib/preview-prefs';import { chromiumBased } from '@/lib/browser';/** How far the film's frame reaches past the picture's box on each side, in px (see the `stage-frames` clip). */@@ -28,7 +29,12 @@ export type Target = {at?: string; n?: number; tag?: string; text?: string | null; style?: Record<string, string>;};export type PreviewHandle = {+ /** Show the still moment t (the film stops playing). */seek(t: number): void;+ /** Play on this line (the player's, on this page's clock): the film draws its own frames from it until `seek`. */+ play?(anchor: Anchor): void;+ /** Stretches rendered to play in place of the film while it plays (studio/server/preview-cache.mjs); [] none. */+ renders?(list: PreviewRender[]): void;update(film: Film, head?: string): void;preview(clip: string, overrides: unknown[] | null): void;pick(x: number, y: number): Promise<Target | null>;@@ -48,6 +54,15 @@ export type PreviewHandle = {reload?(): void;};+/** A stretch of the film rendered into a video (film seconds [a, b)), played in its place while the film plays. */+export type PreviewRender = { a: number; b: number; src: string };+/**+ * How playing went, about once a second over `ms` (studio/server/bridge.js `played`): refreshes the screen had while+ * playing, the film's frames drawn, how many refreshes got no new frame (`late`), whether a render played, and per half+ * second of film [its start, refreshes, late].+ */+export type PlayedReport = { frames: number; drawn: number; late: number; rendered: boolean; ms: number; spans: [number, number, number][] };+/*** What the film's stage tells on its own: the words of an in-place text edit as they are typed, the edit ended* (`commit` with the new words), a key pressed while the picture had focus (not while typing in it), or another load@@ -65,6 +80,8 @@ type Props = {stage: { w: number; h: number };/** where the film is: a loaded page draws its first frame there */time: () => number;+ /** the film's frame rate (frames a second, 29.97 as 30000/1001): playing draws each of its frames, none between */+ fps?: number;onInfo(info: FilmInfo): void;/*** A key pressed while the picture had focus (key events do not cross documents), after the stage's own listeners@@ -74,10 +91,17 @@ type Props = {onKey?(e: KeyboardEvent): void;/** The film could not be drawn (the message), or it is drawn again (null). */onError?(message: string | null): void;+ /** How playing went, about once a second while it plays. */+ onPlayed?(report: PlayedReport): void;children?: ReactNode;};-export const Preview = forwardRef<PreviewHandle, Props>(function Preview({ folder, stage, time, onInfo, onKey, onError, children }, ref) {+/** Clock readings asked of a frame as it comes up: the one answered soonest says best where its clock is. */+const CLOCK_PINGS = 5;+/** How long the viewer keeps another size before the film is loaded again for it (ms): not at each step of a drag. */+const RESCALE_MS = 600;++export const Preview = forwardRef<PreviewHandle, Props>(function Preview({ folder, stage, time, fps, onInfo, onKey, onError, onPlayed, children }, ref) {const t = useT();const origin = new URL(folder).origin;const [frames, setFrames] = useState<Frame[]>([{ key: 1, ready: false }]);@@ -90,6 +114,17 @@ export const Preview = forwardRef<PreviewHandle, Props>(function Preview({ foldeonKeyRef.current = onKey;const box = useRef<HTMLDivElement>(null);const [fit, setFit] = useState({ w: 0, h: 0, k: 1 });+ /* the viewer measured once: the film loads only then, its pages drawn for that size (see pageScale) */+ const [measured, setMeasured] = useState(false);+ /*+ * The device pixels a page draws per CSS px (its devicePixelRatio, `film-dpr` in the film's address, see+ * studio/server/pages.mjs): what the viewer shows, not the film's full size scaled down, while that switch is on;+ * null: the screen's own. A load of the film keeps the scale it was made with; another one, kept a moment, loads+ * the film again behind the picture.+ */+ const { fitPages } = usePreviewPrefs();+ const pageScale = fitPages && fit.w > 0 ? pageScaleFor(fit.k, window.devicePixelRatio || 1) : null;+ const scaleOf = useRef(new Map<number, number | null>());const framesRef = useRef(frames);framesRef.current = frames;const shown = frames.find((f) => f.ready) ?? null;@@ -101,12 +136,32 @@ export const Preview = forwardRef<PreviewHandle, Props>(function Preview({ foldefailedRef.current = failed;const onErrorRef = useRef(onError);onErrorRef.current = onError;+ const onPlayedRef = useRef(onPlayed);+ onPlayedRef.current = onPlayed;+ /* the stretches rendered to play in the film's place: told to each load of the film once it is up */+ const rendered = useRef<PreviewRender[]>([]);useEffect(() => { onErrorRef.current?.(failed); }, [failed]);const post = (key: number | undefined, message: object) => {if (key == null) return;elements.current.get(key)?.contentWindow?.postMessage({ source: 'openfilm-studio', ...message }, origin);};+ /*+ * Playing: the line the film plays on (null while still), told to the frame shown, and to a frame that comes up+ * meanwhile once it shows. The line is on this page's clock; each frame's clock starts elsewhere (another document,+ * another process), so each is told it on its own: by how far its clock is from this one, read with a few pings and+ * taken from the one answered soonest (the time a message takes is the error, a fraction of a millisecond).+ */+ const line = useRef<Anchor | null>(null);+ const fpsRef = useRef(fps);+ fpsRef.current = fps;+ const clocks = useRef(new Map<number, { offset: number; rtt: number }>());+ const tellPlay = (key: number | undefined) => {+ const a = line.current;+ if (key == null || !a) return;+ const offset = clocks.current.get(key)?.offset ?? 0;+ post(key, { type: 'play', t: a.t, at: a.at + offset, rate: a.rate, fps: fpsRef.current ?? 0 });+ };/** A frame loads film.html as the folder has it when it starts; the films given since (`update`) are kept, and a frame* that comes up after some is given the latest, so a load in progress never misses an edit.@@ -119,6 +174,20 @@ export const Preview = forwardRef<PreviewHandle, Props>(function Preview({ folde/* the frames whose film said it is ready: each is told every edit from then on, the one loading behind too (it isshown next, and must not come up without the edits made while it drew its first picture) */const up = useRef(new Set<number>());+ /* one ref callback a frame keeps for its life: a new one each render would be called with null on every render,+ and drop the clock, scale and readiness measured for a frame still on screen */+ const refs = useRef(new Map<number, (el: HTMLIFrameElement | null) => void>());+ const refOf = (key: number) => {+ let ref = refs.current.get(key);+ if (!ref) {+ ref = (el) => {+ if (el) { elements.current.set(key, el); return; }+ elements.current.delete(key); up.current.delete(key); clocks.current.delete(key); scaleOf.current.delete(key); refs.current.delete(key);+ };+ refs.current.set(key, ref);+ }+ return ref;+ };/** load the film again behind the picture (its structure changed, or the folder's film was replaced) */const reload = () => setFrames((list) => {const next = reloaded(list);@@ -128,8 +197,17 @@ export const Preview = forwardRef<PreviewHandle, Props>(function Preview({ foldeuseImperativeHandle(ref, () => ({seek(t) {+ line.current = null;post(shownRef.current?.key, { type: 'seek', t, seq: ++seq.current });},+ play(anchor) {+ line.current = { ...anchor };+ tellPlay(shownRef.current?.key);+ },+ renders(list) {+ rendered.current = list;+ for (const key of up.current) post(key, { type: 'renders', list });+ },update(film, head) {updates.current += 1;latest.current = film;@@ -202,16 +280,34 @@ export const Preview = forwardRef<PreviewHandle, Props>(function Preview({ foldeif (m.type === 'ready') {onInfo(m as FilmInfo);up.current.add(key);+ if (rendered.current.length) post(key, { type: 'renders', list: rendered.current });+ /* where its clock is: first by where each clock started, then by pings */+ if (Number(m.origin) > 0) clocks.current.set(key, { offset: performance.timeOrigin - Number(m.origin), rtt: Infinity });+ for (let i = 0; i < CLOCK_PINGS; i++) setTimeout(() => post(key, { type: 'clock', ping: performance.now() }), 40 * i);/* the film changed here while this frame was loading: it gets the latest before its first picture */if ((born.current.get(key) ?? 0) < updates.current && latest.current) post(key, { type: 'update', film: latest.current, head: latestHead.current, seq: ++seq.current });/* behind the picture shown: its first picture is waited for whole (its videos loaded), as it replaces that one */const behind = shownRef.current != null && shownRef.current.key !== key;post(key, { type: 'seek', t: time(), seq: ++seq.current, ...(behind ? { behind: true } : {}) });+ } else if (m.type === 'played') {+ if (key === shownRef.current?.key) {+ onPlayedRef.current?.({ frames: Number(m.frames), drawn: Number(m.drawn) || 0, late: Number(m.late), rendered: Boolean(m.rendered), ms: Number(m.ms), spans: Array.isArray(m.spans) ? m.spans : [] });+ }+ } else if (m.type === 'clock') {+ const back = performance.now();+ const rtt = back - Number(m.ping);+ const had = clocks.current.get(key);+ if (!(rtt >= 0) || (had && had.rtt <= rtt)) return;+ clocks.current.set(key, { offset: Number(m.now) - (Number(m.ping) + rtt / 2), rtt });+ /* playing on it: told the line again, on its clock as now read */+ if (line.current && key === shownRef.current?.key) tellPlay(key);} else if (m.type === 'seeked') {const swap = !framesRef.current.find((f) => f.key === key)?.ready;setFrames((list) => shownAfter(list, key));- /* shown now: the playhead may have moved while it drew, and seeks went to the frame shown then */- if (swap && Math.abs(time() - Number(m.t)) > 1e-6) post(key, { type: 'seek', t: time(), seq: ++seq.current });+ /* shown now: the film playing, it plays on from the line; still, the playhead may have moved while it drew,+ and seeks went to the frame shown then */+ if (swap && line.current) tellPlay(key);+ else if (swap && Math.abs(time() - Number(m.t)) > 1e-6) post(key, { type: 'seek', t: time(), seq: ++seq.current });} else if (m.type === 'updated') {if (m.inPlace) onInfo(m as FilmInfo);else reload();@@ -253,15 +349,29 @@ export const Preview = forwardRef<PreviewHandle, Props>(function Preview({ foldeuseLayoutEffect(() => {const el = box.current;if (!el) return undefined;- const observer = new ResizeObserver(([entry]) => {- const { width, height } = entry.contentRect;+ const size = (width: number, height: number) => {const k = Math.max(0.01, Math.min(width / stage.w, height / stage.h));setFit({ w: Math.floor(stage.w * k), h: Math.floor(stage.h * k), k });- });+ };+ /* measured now, before the first picture: the film loads once, for this size */+ if (el.clientWidth > 0 && el.clientHeight > 0) size(el.clientWidth, el.clientHeight);+ setMeasured(true);+ const observer = new ResizeObserver(([entry]) => size(entry.contentRect.width, entry.contentRect.height));observer.observe(el);return () => observer.disconnect();}, [stage.w, stage.h]);+ /* a load keeps the scale it was made with */+ if (measured) for (const f of frames) if (!scaleOf.current.has(f.key)) scaleOf.current.set(f.key, pageScale);+ /* the viewer kept another size (fullscreen, a pane resized), or the switch changed: the film loads again behind */+ const shownScale = shown ? scaleOf.current.get(shown.key) : undefined;+ useEffect(() => {+ if (!shown || shownScale === undefined || shownScale === pageScale || frames.some((f) => !f.ready)) return undefined;+ const timer = setTimeout(reload, RESCALE_MS);+ return () => clearTimeout(timer);+ // eslint-disable-next-line react-hooks/exhaustive-deps+ }, [pageScale, shownScale, shown?.key, frames.length]);+const error = failed;return (<div className="stage-box" ref={box}>@@ -270,13 +380,13 @@ export const Preview = forwardRef<PreviewHandle, Props>(function Preview({ foldeof a frame (a part of a device px a browser rounds its own way, a backdrop it paints under the film) isnever on screen as a line along the picture */}<div className="stage-frames">- {frames.map((f) => (+ {(measured ? frames : []).map((f) => (<iframekey={f.key}- ref={(el) => { if (el) elements.current.set(f.key, el); else { elements.current.delete(f.key); up.current.delete(f.key); } }}+ ref={refOf(f.key)}/* `film-missing=skip`: a clip whose file is not there keeps its time and plays as nothing, the rest plays on(src/timeline.mjs); the timeline marks it and offers to relink it */- src={`${folder}film.html?load=${f.key}&film-missing=skip`}+ src={`${folder}film.html?load=${f.key}&film-missing=skip${scaleOf.current.get(f.key) != null ? `&film-dpr=${scaleOf.current.get(f.key)}` : ''}`}/* the film's videos play when the person presses play here: another origin needs this to be allowed */allow="autoplay"scrolling="no"diff --git a/packages/openfilm/studio/ui/src/editor/player.test.ts b/packages/openfilm/studio/ui/src/editor/player.test.tsindex 076524c..511656d 100644--- a/packages/openfilm/studio/ui/src/editor/player.test.ts+++ b/packages/openfilm/studio/ui/src/editor/player.test.ts@@ -1,6 +1,6 @@import { test } from 'node:test';import assert from 'node:assert/strict';-import { fadeSteps } from './player.ts';+import { anchorTime, EASE_STEP, easedLead, fadeSteps, JUMP, soundsDue } from './player.ts';test('a sound\'s fades as ramps: where it is now, then each corner after it', () => {/* 4 s long, 1 s in, 2 s out */@@ -12,3 +12,30 @@ test('a sound\'s fades as ramps: where it is now, then each corner after it', ()/* only a fade out: full until it starts */assert.deepEqual(fadeSteps(0, 2, [0, 0.5]), [[0, 1], [1.5, 1], [2, 0]]);});++test('the film plays on a line: held at its second until its moment comes, then on at its rate', () => {+ const a = { t: 10, at: 1000, rate: 1 };+ assert.equal(anchorTime(a, 900), 10, 'before the sound is heard the picture waits where it starts');+ assert.equal(anchorTime(a, 1000), 10);+ assert.equal(anchorTime(a, 1500), 10.5);+ assert.equal(anchorTime({ ...a, rate: 2 }, 1500), 11);+});++test('the sound\'s lead over the page\'s clock is eased in a little at a time, taken at once when far off or new', () => {+ assert.equal(easedLead(null, 3.25), 3.25, 'the first one is taken as it is');+ assert.equal(easedLead(3.25, 3.2502), 3.2502, 'within a step: taken');+ assert.equal(easedLead(3.25, 3.26), 3.25 + EASE_STEP, 'further: one step toward it');+ assert.equal(easedLead(3.25, 3.24), 3.25 - EASE_STEP);+ assert.equal(easedLead(3.25, 3.25 + JUMP + 0.01), 3.25 + JUMP + 0.01, 'far off: another device, taken at once');+});++test('sounds are started a few seconds ahead of the film, each once, solo leaving the others out', () => {+ const s = (at: number, length: number, clip: string) => ({ src: `${clip}.wav`, at, from: 0, to: length, volume: 1, speed: 1, clip });+ const sounds = [s(0, 2, 'a'), s(1, 20, 'b'), s(9, 1, 'c'), s(30, 1, 'd')];+ assert.deepEqual(soundsDue(sounds, 1.5, 9.5, new Set(), null), [0, 1, 2], 'playing at 1.5, or starting before 9.5');+ assert.deepEqual(soundsDue(sounds, 1.5, 9.5, new Set([0, 2]), null), [1], 'not started twice');+ assert.deepEqual(soundsDue(sounds, 2.5, 9.5, new Set(), null), [1, 2], 'one that ended before is not');+ assert.deepEqual(soundsDue(sounds, 1.5, 9.5, new Set(), new Set(['b'])), [1], 'solo: only the clips heard');+ /* a sound of a faster clip lasts less on the film */+ assert.deepEqual(soundsDue([{ ...s(0, 4, 'e'), speed: 2 }], 2.5, 3, new Set(), null), []);+});diff --git a/packages/openfilm/studio/ui/src/editor/player.ts b/packages/openfilm/studio/ui/src/editor/player.tsindex 9500111..a597af0 100644--- a/packages/openfilm/studio/ui/src/editor/player.ts+++ b/packages/openfilm/studio/ui/src/editor/player.ts@@ -1,28 +1,62 @@/*** The film's sound, played with Web Audio, and the clock the picture follows. The picture is drawn in the preview- * (another origin, see Preview); every sound of the film plays here, so one clock decides where the film is:- * the audio context's while playing, a number while paused. A browser that will not start the sound yet (no click on- * the page so far, an embedding app's stricter rules) does not stop the film: the clock is then the page's own, the- * picture plays silent, and the sound joins as soon as the browser lets it start.+ * (another origin, see Preview), which runs its own frames from this clock's anchor (`anchor`, told on each change+ * through `onAnchor`): a straight line from a film second at a moment of the page's clock, at the playing rate. While+ * the sound plays, that line is where the sound is heard: the audio context says when the sample it plays now reaches+ * the ears (its output timestamp, the device's latency included), and the line follows it, eased so the picture never+ * jumps. A browser that will not start the sound yet (no click on the page so far, an embedding app's stricter rules)+ * does not stop the film: the line is then the page's clock alone, the picture plays silent, and the sound joins where+ * the film is as soon as the browser lets it start.** `sounds` is the timeline's own list (src/timeline.mjs `__filmSounds`): each sound clip's sound and each video's own,* already placed and cut to its clip, with its volume and speed. Each file's sound is fetched small (`?film-sound`, see* studio/server/pages.mjs): a video's is a copy of its sound alone, never the whole video. A sound not here yet (its- * copy still being made) is silent until it is, then joins where the film is.+ * copy still being made) is silent until it is, then joins where the film is. Sounds are started a few seconds ahead of+ * the film, not all at once: a film of hundreds of sounds starts as quickly as one of a few.** Every sound goes through one mix, metered (`levels`: the audio meters read it while the film plays, nothing reads it* paused) before the person's volume. Solo (`setHeard`) leaves the clips of the other tracks out of what plays here* only: the film and its exports are as they are.*/-/** How long play waits for the browser to start the sound before the film plays on without it. */-const RESUME_WAIT_MS = 250;/** Sounds fetched at once; the others wait, the ones nearest to where the film is first. */const FETCHES = 3;+/** How far ahead of the film sounds are started (film seconds); the rest are started as the film gets near them. */+const AHEAD = 8;+/** How often, while playing, sounds coming up are started and the line is checked against the sound (ms). */+const CHECK_MS = 250;+/** How long after now a sound can be started at the soonest (s): sooner, its start is cut. */+const LEAD = 0.03;/** `fade`: its fades in and out, film seconds, already fitted to its length (src/timeline.mjs). */export type Sound = { src: string; at: number; from: number; to: number; volume: number; speed: number; clip?: string; fade?: [number, number] };+/**+ * Where the film is while it plays: film second `t` at `at` (ms on the page's clock, performance.now()), moving on+ * `rate` film seconds a second.+ */+export type Anchor = { t: number; at: number; rate: number };++/** The film second an anchor puts at `now` (ms on the page's clock): `t` until its moment comes, then on from there. */+export function anchorTime(a: Anchor, now: number): number {+ return a.t + (Math.max(0, now - a.at) / 1000) * a.rate;+}++/** A change of the sound's lead over the page's clock eased in at most this much per check (s): 0.2% of a second. */+export const EASE_STEP = 0.0005;+/** A change larger than this is taken at once (s): another output device, a stall of the sound. */+export const JUMP = 0.05;++/**+ * How far the audio clock is ahead of the page's (s), as last taken (`current`, null before the first), moved toward+ * what the output timestamp says now (`measured`): eased by EASE_STEP a check so the picture following it never jumps,+ * at once when it is far off or nothing was taken yet.+ */+export function easedLead(current: number | null, measured: number): number {+ if (current == null || Math.abs(measured - current) > JUMP) return measured;+ return current + Math.max(-EASE_STEP, Math.min(EASE_STEP, measured - current));+}+/*** A sound's gain as its fades have it: where it is at `local` seconds into its `length`, then each corner of its ramps* after that (the ramp up's end, the ramp down's start, its end), each as [local seconds, gain]. Straight lines between,@@ -45,12 +79,28 @@ export function fadeSteps(local: number, length: number, fade: readonly [number,/** The mix's level now, by channel (left, right): its latest samples, as the audio meters read them. */export type MixSamples = [Float32Array<ArrayBuffer>, Float32Array<ArrayBuffer>];+/** A sound's length on the film (s). */+const lengthOf = (s: Sound) => (s.to - s.from) / s.speed;+/** How far film time `t` is from a sound: 0 while it plays, else until it starts; one already past after all those. */function awayFrom(s: Sound, t: number) {- const end = s.at + (s.to - s.from) / s.speed;+ const end = s.at + lengthOf(s);return t < s.at ? s.at - t : t < end ? 0 : 1e6 + t - end;}+/**+ * The sounds to start now, by their place in `sounds`: those heard between film seconds `from` and `until` (a sound+ * playing at `from` included), not started already (`started`) and not left out (`heard`: the clips heard, null all).+ */+export function soundsDue(sounds: readonly Sound[], from: number, until: number, started: ReadonlySet<number>, heard: ReadonlySet<string> | null): number[] {+ const due: number[] = [];+ sounds.forEach((s, i) => {+ if (started.has(i) || (heard && !(s.clip && heard.has(s.clip)))) return;+ if (s.at + lengthOf(s) > from && s.at < until) due.push(i);+ });+ return due;+}+export class Player {private ctx: AudioContext | null = null;/** each file's decoded sound, and the version of the file it was decoded from (undefined: not known then) */@@ -59,11 +109,15 @@ export class Player {private versionOf: (src: string) => number | undefined = () => undefined;private sounds: Sound[] = [];private playingNodes: AudioScheduledSourceNode[] = [];- private startedAt = 0;- private startT = 0;+ /** where the film is while playing, on the page's clock (see Anchor) */+ private line: Anchor = { t: 0, at: 0, rate: 1 };+ /** the same line on the audio clock while the sound plays: film second `t` is heard at audio time `at` (s); null silent */+ private heardLine: { t: number; at: number } | null = null;+ /** how far the audio clock is ahead of the page's (s), eased (see easedLead); null until taken */+ private lead: number | null = null;private pausedT = 0;- /** playing without sound: the clock is performance.now(), in seconds, from `startedAt` */- private silent = false;+ /** the sounds started this time the film plays, by their place in `sounds` */+ private started = new Set<number>();/** which call to play is the latest: an earlier one still waiting for the sound gives up */private starts = 0;private master: GainNode | null = null;@@ -75,12 +129,15 @@ export class Player {private heard: ReadonlySet<string> | null = null;private fetching = 0;private queued: { src: string; go: () => void }[] = [];+ private checks = 0;playing = false;duration = 0;/** the person's volume (0–1), muting and playback speed (the fullscreen bar's): the whole film's, not a clip's */volume = 1;muted = false;rate = 1;+ /** Told each time the line the film plays on changes (a play, a seek, another speed, the sound joining or moving). */+ onAnchor: ((a: Anchor) => void) | null = null;/** The film's sounds, fetched from `origin` (the film's origin) and decoded once each (once per version). */load(origin: string, sounds: Sound[], duration: number) {@@ -88,7 +145,7 @@ export class Player {this.sounds = sounds;this.duration = duration;this.fetchSounds();- if (this.playing) this.play(this.time());+ if (this.playing) this.restart();}/**@@ -97,7 +154,7 @@ export class Player {*/setVersions(versionOf: (src: string) => number | undefined) {this.versionOf = versionOf;- if (this.fetchSounds() && this.playing) this.play(this.time());+ if (this.fetchSounds() && this.playing) this.restart();}/** Fetches the sounds not decoded yet, or decoded from an older version; says whether there were any. */@@ -173,17 +230,30 @@ export class Player {this.analysers = [meter(0), meter(1)];/* the sound was not allowed to start when play was pressed; now it is: it joins where the film is */const ctx = this.ctx;- ctx.addEventListener('statechange', () => { if (ctx.state === 'running' && this.playing && this.silent) void this.play(this.time()); });+ ctx.addEventListener('statechange', () => { if (ctx.state === 'running' && this.playing && !this.heardLine) this.join(); });}return this.ctx;}+ /**+ * How far the audio clock is ahead of the page's now (s): the output timestamp pairs the audio time being heard with+ * the page time it is heard at. Before the device has said (its first moments), the context's own time less its+ * latencies. Null while the sound is not running.+ */+ private measuredLead(): number | null {+ const ctx = this.ctx;+ if (!ctx || ctx.state !== 'running') return null;+ const stamp = typeof ctx.getOutputTimestamp === 'function' ? ctx.getOutputTimestamp() : null;+ if (stamp && Number(stamp.contextTime) > 0 && Number(stamp.performanceTime) > 0) return stamp.contextTime! - stamp.performanceTime! / 1000;+ return ctx.currentTime - (ctx.baseLatency || 0) - (ctx.outputLatency || 0) - performance.now() / 1000;+ }+/*** The mix's latest samples (about 40 ms), left and right, or null when nothing is playing here (paused, no sound* yet): read by the meters once a frame while the film plays.*/levels(): MixSamples | null {- if (!this.analysers || !this.playing || this.silent) return null;+ if (!this.analysers || !this.playing || !this.heardLine) return null;const [l, r] = this.analysers;this.samples ??= [new Float32Array(l.fftSize), new Float32Array(r.fftSize)];l.getFloatTimeDomainData(this.samples[0]);@@ -195,7 +265,7 @@ export class Player {setHeard(clips: ReadonlySet<string> | null) {const same = clips === this.heard || (clips && this.heard && clips.size === this.heard.size && [...clips].every((c) => this.heard!.has(c)));this.heard = clips;- if (!same && this.playing) void this.play(this.time());+ if (!same && this.playing) this.restart();}/** Try to start the sound again (a click or key on the page lets a browser that refused it before). */@@ -218,66 +288,119 @@ export class Player {setRate(rate: number) {const t = this.time();this.rate = Math.max(0.25, Math.min(2, rate));- if (this.playing) void this.play(t);+ if (this.playing) this.restart(t);}/** Where the film is, in seconds. */time(): number {- if (!this.playing || !this.ctx) return this.pausedT;- /* the sound starts a moment after play (see play): until then the picture waits where it starts */- const now = this.silent ? performance.now() / 1000 : this.ctx.currentTime;- const t = this.startT + Math.max(0, now - this.startedAt) * this.rate;- return Math.min(t, this.duration);+ if (!this.playing) return this.pausedT;+ return Math.max(0, Math.min(anchorTime(this.line, performance.now()), this.duration));+ }++ /** The line the film plays on now, or null while paused. */+ anchor(): Anchor | null {+ return this.playing ? { ...this.line } : null;}/**- * Play from `t`. Sounds not decoded yet join when they are. Playing starts at once, on the page's clock: the- * sound starts when the browser lets it (resume() can take a while, or never come), and joins where the film is by- * then. Anything that waits for `playing` sees it now, not after that wait.+ * Play from `t`. The picture starts with the sound: with the sound running already, both start a moment from now+ * (as long as starting a sound takes, and the device's latency), from `t`. A browser holding the sound back does+ * not hold the film: it plays on the page's clock at once, and the sound joins where it is when it may.*/- async play(t = this.time()) {+ play(t = this.time()) {this.stopNodes();if (t >= this.duration - 1e-3) t = 0;const go = ++this.starts;this.playing = true;- this.startT = t;- this.silent = true;- this.startedAt = performance.now() / 1000;const ctx = this.context();- /* a resume the browser holds back never settles: wait a moment, then play on without the sound */- await Promise.race([ctx.resume().catch(() => {}), new Promise((done) => setTimeout(done, RESUME_WAIT_MS))]);- /* paused, sought or played again while waiting: that call decides */- if (go !== this.starts || !this.playing) return;- if (ctx.state !== 'running') return;- this.startT = this.time();- this.silent = false;- this.startedAt = ctx.currentTime + 0.05;- t = this.startT;- const startedAt = this.startedAt;- for (const s of this.sounds) {- if (this.heard && !(s.clip && this.heard.has(s.clip))) continue;- const length = (s.to - s.from) / s.speed;- const end = s.at + length;- if (end <= t) continue;+ const lead = ctx.state === 'running' ? this.measuredLead() : null;+ if (lead != null) {+ this.lead = easedLead(null, lead);+ /* heard from t at audio time `at`: the picture is at t when that is heard */+ const at = ctx.currentTime + LEAD;+ this.heardLine = { t, at };+ this.line = { t, at: (at - this.lead) * 1000, rate: this.rate };+ this.startDue();+ } else {+ this.heardLine = null;+ this.line = { t, at: performance.now(), rate: this.rate };+ void ctx.resume().catch(() => {}).then(() => { if (go === this.starts && this.playing && !this.heardLine && ctx.state === 'running') this.join(); });+ }+ this.watch();+ this.onAnchor?.(this.anchor()!);+ }++ /**+ * Playing on from where the film is, its sounds started again (another speed, a solo, the sounds changed): the+ * picture goes on without a jump, the sounds join a moment later.+ */+ private restart(t = this.time()) {+ this.stopNodes();+ this.line = { t, at: performance.now(), rate: this.rate };+ this.heardLine = null;+ if (this.ctx?.state === 'running') this.join();+ this.onAnchor?.(this.anchor()!);+ }++ /** The sound joins the film where it is (it was not running, or it is started again): the picture keeps its line. */+ private join() {+ const lead = this.measuredLead();+ if (lead == null || !this.playing) return;+ this.lead = easedLead(null, lead);+ /* where the line puts the film when a sound started now is heard */+ const at = this.ctx!.currentTime + LEAD;+ this.heardLine = { t: anchorTime(this.line, (at - this.lead) * 1000), at };+ this.started.clear();+ this.startDue();+ }++ /** While playing: start the sounds coming up, and keep the picture's line on the sound as it is heard. */+ private watch() {+ window.clearInterval(this.checks);+ this.checks = window.setInterval(() => {+ if (!this.playing) { window.clearInterval(this.checks); return; }+ if (!this.heardLine) return;+ const measured = this.measuredLead();+ if (measured != null) {+ const lead = easedLead(this.lead, measured);+ if (lead !== this.lead) {+ this.lead = lead;+ /* the picture follows the sound as heard: the same line, on the page's clock by the lead now */+ this.line = { t: this.heardLine.t, at: (this.heardLine.at - lead) * 1000, rate: this.rate };+ this.onAnchor?.(this.anchor()!);+ }+ }+ this.startDue();+ }, CHECK_MS);+ }++ /** Start the sounds heard from now to AHEAD seconds on that are not started yet. */+ private startDue() {+ const heard = this.heardLine;+ if (!heard || !this.ctx) return;+ const now = anchorTime({ t: heard.t, at: heard.at * 1000, rate: this.rate }, (this.ctx.currentTime + LEAD) * 1000);+ for (const i of soundsDue(this.sounds, now, now + AHEAD * this.rate, this.started, this.heard)) {+ this.started.add(i);+ const s = this.sounds[i];void this.buffers.get(s.src)?.buffer.then((buffer) => {- if (!buffer || !this.playing || this.startedAt !== startedAt) return;- this.schedule(buffer, s, t, end);+ if (!buffer || !this.playing || this.heardLine !== heard) return;+ this.schedule(buffer, s, heard);});}}- /** One sound from film time `t` on: its offset into the file, its speed, its volume. */- private schedule(buffer: AudioBuffer, s: Sound, t: number, end: number) {+ /** One sound, heard where `heard` puts it: from its start, or from where the film is when it starts late. */+ private schedule(buffer: AudioBuffer, s: Sound, heard: { t: number; at: number }) {const ctx = this.context();- const now = ctx.currentTime;- /* where the film is when this sound is scheduled (decoding may have taken a moment since play) */const r = this.rate;- const filmNow = Math.max(t, this.startT + (now - this.startedAt) * r);- const startFilm = Math.max(s.at, filmNow);+ /* film seconds → audio seconds: a film second lasts 1 / rate */+ const ctxAt = (filmT: number) => heard.at + (filmT - heard.t) / r;+ const end = s.at + lengthOf(s);+ /* a sound whose start has passed (decoding took a moment, or the film started inside it) starts where the film is */+ const soonest = ctx.currentTime + LEAD;+ const startFilm = Math.max(s.at, heard.t + Math.max(0, soonest - heard.at) * r);if (startFilm >= end) return;- /* film seconds → context seconds: a film second lasts 1 / rate */- const ctxAt = (filmT: number) => this.startedAt + (filmT - this.startT) / r;- const when = ctxAt(startFilm);+ const when = Math.max(soonest, ctxAt(startFilm));const offset = s.from + (startFilm - s.at) * s.speed;const source = ctx.createBufferSource();source.buffer = buffer;@@ -286,30 +409,38 @@ export class Player {if (s.fade) {/* its fades as ramps on the audio clock, sample-accurate: from where it starts, each corner at its own moment */const [[, first], ...rest] = fadeSteps(startFilm - s.at, end - s.at, s.fade);- gain.gain.setValueAtTime(s.volume * first, Math.max(now, when));- for (const [u, g] of rest) gain.gain.linearRampToValueAtTime(s.volume * g, Math.max(now, ctxAt(s.at + u)));+ gain.gain.setValueAtTime(s.volume * first, when);+ for (const [u, g] of rest) gain.gain.linearRampToValueAtTime(s.volume * g, Math.max(when, ctxAt(s.at + u)));} else gain.gain.value = s.volume;source.connect(gain).connect(this.mix ?? ctx.destination);- source.start(Math.max(now, when), offset, (end - startFilm) * s.speed);+ source.start(when, offset, (end - startFilm) * s.speed);+ source.onended = () => {+ const i = this.playingNodes.indexOf(source);+ if (i >= 0) this.playingNodes.splice(i, 1);+ };this.playingNodes.push(source);}pause() {this.pausedT = this.time();this.playing = false;+ this.starts += 1;+ window.clearInterval(this.checks);+ this.heardLine = null;this.stopNodes();}/** Move to `t`; playing goes on from there. */seek(t: number) {const clamped = Math.max(0, Math.min(t, this.duration));- if (this.playing) void this.play(clamped);+ if (this.playing) this.play(clamped);else this.pausedT = clamped;}private stopNodes() {- for (const node of this.playingNodes) { try { node.stop(); } catch { /* already stopped */ } }+ for (const node of this.playingNodes) { try { node.onended = null; node.stop(); } catch { /* already stopped */ } }this.playingNodes = [];+ this.started.clear();}close() {diff --git a/packages/openfilm/studio/ui/src/editor/preview-frames.test.ts b/packages/openfilm/studio/ui/src/editor/preview-frames.test.tsindex f18d34b..2b5342d 100644--- a/packages/openfilm/studio/ui/src/editor/preview-frames.test.ts+++ b/packages/openfilm/studio/ui/src/editor/preview-frames.test.ts@@ -1,6 +1,6 @@import { test } from 'node:test';import assert from 'node:assert/strict';-import { reloaded, shownAfter, updateKeys } from './preview-frames.ts';+import { pageScaleFor, reloaded, shownAfter, updateKeys } from './preview-frames.ts';test('a load behind the picture: the frame shown stays until the new one has drawn, and only then goes', () => {const first = [{ key: 1, ready: true }];@@ -22,3 +22,12 @@ test('an edit reaches the frame shown and the one loading behind it once its filassert.deepEqual(updateKeys(1, new Set([1, 2])), [1, 2]);assert.deepEqual(updateKeys(2, new Set([2])), [2]);});++test('a page draws at what the viewer shows of the film: in quarter steps up, never more than the screen\'s pixels', () => {+ /* a 1920 px film in a 1102 px viewer on a 2x screen: 1.15 device px a stage px, drawn at 1.25 */+ assert.equal(pageScaleFor(1102 / 1920, 2), 1.25);+ assert.equal(pageScaleFor(1, 2), 2, 'shown at full size: the screen\'s');+ assert.equal(pageScaleFor(1.5, 2), 2, 'shown larger than the film: no more than the screen has');+ assert.equal(pageScaleFor(0.5, 1), 0.5);+ assert.equal(pageScaleFor(0.05, 1), 0.25, 'a tiny viewer: a quarter at least');+});diff --git a/packages/openfilm/studio/ui/src/editor/preview-frames.ts b/packages/openfilm/studio/ui/src/editor/preview-frames.tsindex 63ce74e..fb11d0d 100644--- a/packages/openfilm/studio/ui/src/editor/preview-frames.ts+++ b/packages/openfilm/studio/ui/src/editor/preview-frames.ts@@ -24,3 +24,13 @@ export function shownAfter(list: readonly Frame[], key: number): Frame[] {export function updateKeys(shown: number, up: ReadonlySet<number>): number[] {return [shown, ...[...up].filter((key) => key !== shown)];}++/**+ * The device pixels a page draws per CSS px in the viewer (its devicePixelRatio there): what the viewer shows of the+ * film (`k`, viewer px per stage px, times the screen's `dpr`), in quarter steps rounded up, so a small resize does not+ * load the film again; never more than the screen's own, nor under a quarter.+ */+export function pageScaleFor(k: number, dpr: number): number {+ const shown = Math.max(0.25, k * dpr);+ return Math.min(dpr, Math.ceil(shown * 4 - 1e-9) / 4);+}diff --git a/packages/openfilm/studio/ui/src/editor/use-preview-renders.ts b/packages/openfilm/studio/ui/src/editor/use-preview-renders.tsnew file mode 100644index 0000000..17ee1a4--- /dev/null+++ b/packages/openfilm/studio/ui/src/editor/use-preview-renders.ts@@ -0,0 +1,98 @@+/**+ * Preview renders, the editor's side: the stretches that play late (measured as the film plays, lib/preview-renders)+ * are asked to be rendered once the film has stopped for a moment (studio/server/preview-cache.mjs, in the+ * background), followed while they are made, and told to the preview when they are, to play in the film's place.+ * Anything changed in the project (film.html, a page, a file) and those renders are not played until the server names+ * them for the project as it is now. `bar`: what the timeline's ruler shows of them.+ */+import { useCallback, useEffect, useMemo, useRef, useState, type RefObject } from 'react';+import { addHeat, joinStretches, lateStretches, sameStretches, type Heat } from '@/lib/preview-renders';+import type { PlayedReport, PreviewHandle, PreviewRender } from './Preview';++/** A stretch on the ruler: plays late (not rendered), being rendered, rendered, or one that could not be. */+export type PreviewBarRange = { a: number; b: number; state: 'late' | 'making' | 'ready' | 'failed'; ratio?: number };+type Made = { a: number; b: number; key: string; state: 'waiting' | 'making' | 'ready' | 'failed'; ratio?: number };++/** How long the film stays stopped (and unchanged) before what plays late is rendered (ms). */+const IDLE_MS = 2000;+/** How often renders being made are asked after (ms). */+const FOLLOW_MS = 1500;++export function usePreviewRenders({ projectId, folder, fps, playing, on, film, files, preview }: {+ projectId: string;+ /** the project's folder on the film's origin (the preview's address of it) */+ folder: string;+ /** the film's frame rate: renders are made at it */+ fps: number;+ playing: boolean;+ /** Settings → Playback: render what plays late */+ on: boolean;+ /** film.html as it is now, and the project's files' version: either changing makes the renders made before stale */+ film: unknown;+ files: unknown;+ preview: RefObject<PreviewHandle | null>;+}) {+ const heat = useRef<Heat>(new Map());+ /* known late before this session (the server keeps them with the renders), and found late as it plays */+ const known = useRef<[number, number][]>([]);+ const [late, setLate] = useState<[number, number][]>([]);+ const [made, setMade] = useState<Made[]>([]);+ const madeRef = useRef(made);+ madeRef.current = made;+ const lateNow = () => joinStretches([...known.current, ...lateStretches(heat.current)]);+ const onPlayed = useCallback((report: PlayedReport) => {+ /* a half second played from its render says nothing of how the film itself plays there */+ const rendered = madeRef.current.filter((r) => r.state === 'ready');+ addHeat(heat.current, report.spans.filter(([t]) => !rendered.some((r) => t + 0.5 > r.a && t < r.b)));+ const next = lateNow();+ setLate((had) => (sameStretches(had, next) ? had : next));+ // eslint-disable-next-line react-hooks/exhaustive-deps+ }, []);+ /* another project: what is known of how it plays, from the server (an earlier session's), and its renders */+ useEffect(() => {+ heat.current = new Map();+ known.current = [];+ setLate([]);+ setMade([]);+ if (!on || !(fps > 0)) return undefined;+ let alive = true;+ void fetch(`/api/projects/${encodeURIComponent(projectId)}/preview-cache?fps=${fps}`).then((r) => (r.ok ? r.json() : null), () => null)+ .then((answer: { late?: [number, number][]; ranges?: Made[] } | null) => {+ if (!alive || !answer?.late?.length) return;+ known.current = answer.late;+ setLate(lateNow());+ setMade(answer.ranges ?? []);+ });+ return () => { alive = false; };+ // eslint-disable-next-line react-hooks/exhaustive-deps+ }, [projectId, on, fps]);+ /* the project changed: what was rendered of it is not played until it is named for the project as it is now */+ useEffect(() => { setMade([]); }, [film, files]);+ useEffect(() => {+ if (!on || playing || !late.length || !(fps > 0)) return undefined;+ let alive = true;+ let timer = 0;+ const ask = async () => {+ const answer = await fetch(`/api/projects/${encodeURIComponent(projectId)}/preview-cache`, {+ method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ ranges: late, fps }),+ }).then((r) => (r.ok ? r.json() : null), () => null) as { ranges?: Made[] } | null;+ if (!alive || !answer?.ranges) return;+ setMade(answer.ranges);+ if (answer.ranges.some((r) => r.state === 'waiting' || r.state === 'making')) timer = window.setTimeout(() => { void ask(); }, FOLLOW_MS);+ };+ timer = window.setTimeout(() => { void ask(); }, IDLE_MS);+ return () => { alive = false; window.clearTimeout(timer); };+ }, [on, playing, late, fps, projectId, film, files]);+ const list = useMemo<PreviewRender[]>(() => (on+ ? made.filter((r) => r.state === 'ready').map((r) => ({ a: r.a, b: r.b, src: `${folder}__film/preview/${r.key}.mp4` }))+ : []), [on, made, folder]);+ useEffect(() => { preview.current?.renders?.(list); }, [list, preview]);+ const bar = useMemo<PreviewBarRange[]>(() => {+ if (!on) return [];+ /* the server's answer is the stretches as asked, put on the frame grid; a stretch found late since is late */+ const asked = made.map((r): PreviewBarRange => ({ a: r.a, b: r.b, state: r.state === 'waiting' ? 'making' : r.state, ...(r.state === 'making' ? { ratio: r.ratio ?? 0 } : {}) }));+ const since = late.filter(([a, b]) => !made.some((r) => r.a < b && a < r.b)).map(([a, b]): PreviewBarRange => ({ a, b, state: 'late' }));+ return [...asked, ...since].sort((x, y) => x.a - y.a);+ }, [on, late, made]);+ return { onPlayed, bar };+}diff --git a/packages/openfilm/studio/ui/src/globals.css b/packages/openfilm/studio/ui/src/globals.cssindex 49faca8..8bf778a 100644--- a/packages/openfilm/studio/ui/src/globals.css+++ b/packages/openfilm/studio/ui/src/globals.css@@ -58,6 +58,8 @@--accent: #1a1a1a;--accent-soft: rgba(26, 26, 26, 0.06);--on-accent: #ffffff;+ /* selected words being edited (a tab's name): plainly seen, as the system's text selection */+ --text-selection: rgba(26, 147, 254, 0.3);--ok: #16a34a;--warn: #d97706;@@ -137,6 +139,7 @@--accent: #1a93fe;--accent-soft: rgba(26, 147, 254, 0.12);--on-accent: #ffffff;+ --text-selection: rgba(26, 147, 254, 0.45);--ok: #5eb92d;--warn: #ffbf36;@@ -214,8 +217,11 @@ body {overscroll-behavior: none;}-::selection {- background: var(--accent-soft);+/* in the base layer, so a field's own selection color (a tab's name being edited) wins over it */+@layer base {+ ::selection {+ background: var(--accent-soft);+ }}::-webkit-scrollbar {diff --git a/packages/openfilm/studio/ui/src/i18n/en.ts b/packages/openfilm/studio/ui/src/i18n/en.tsindex eb15527..721645d 100644--- a/packages/openfilm/studio/ui/src/i18n/en.ts+++ b/packages/openfilm/studio/ui/src/i18n/en.ts@@ -11,7 +11,7 @@ export const en = {desktop: 'Desktop',},/* the app window's tabs (TabStrip), a new tab's launcher, and the examples (ExamplesGallery) */- tabs: { label: 'Tabs', new: 'Open a project', close: 'Close tab' },+ tabs: { label: 'Tabs', new: 'Open a project', close: 'Close tab', closeOthers: 'Close other tabs', closeRight: 'Close tabs to the right' },launcher: { projects: 'Projects', examples: 'Examples' },gallery: {title: 'Examples',@@ -156,6 +156,12 @@ export const en = {deleteFolderHintEmpty: 'Deletes the folder. There are no projects in it.',renameTaken: '“{name}” is taken: there is already a folder with that name. Choose another.',moveToFolder: 'Move to folder',+ changeCover: 'Change cover…',+ restoreCover: 'Use the automatic cover',+ coverFromFrame: 'Use this frame as the cover',+ setAsCover: 'Set as project cover',+ coverSet: 'Cover set',+ coverFailed: 'Couldn’t use that as the cover.',noFolder: 'No folder',folderEmpty: 'This folder is empty',creating: 'Creating project',@@ -554,11 +560,10 @@ export const en = {stepTrimmed: 'Trimmed {clip}',stepSplit: 'Split {clip}',stepDetachAudio: 'Detached the audio of {clip}',- stepRolled: 'Rolled the cut after {clip}',stepRippleTrimmed: 'Ripple trimmed {clip}',stepGapClosed: 'Closed a gap',- stepMainClosed: 'Closed up the main track',stepGapsClosed: 'Closed the gaps on a track',+ stepMainClosed: 'Closed up the main track',stepLinked: 'Linked {clip}',stepUnlinked: 'Unlinked {clip}',stepSpeed: 'Changed the speed of {clip}',@@ -855,6 +860,8 @@ export const en = {restackFailed: 'That layer couldn\'t be restacked. The picture may have changed; try again.',},viewer: {+ stats: '{fps} frames/s · {late} late',+ statsRendered: 'from a render',loopRange: "Loop the range",loopFilm: "Loop",play: 'Play',@@ -945,7 +952,7 @@ export const en = {inPoint: 'In point',inPointWhole: 'The clip plays all of its file. Shorten it to move the in point.',speed: 'Speed',- speedLimit: 'Slower than {n}× runs into the next clip. On the main track, the magnet in the timeline pushes it along.',+ speedLimit: 'Slower than {n}× runs into the next clip. On the main track, the timeline\'s magnet pushes it along.',speedTooSlow: 'Slower than {n}× runs into the next clip on its track.',sound: 'Sound',gainDb: 'Volume',@@ -1166,6 +1173,10 @@ export const en = {mediaReconnecting: 'Reconnecting to this clip… it comes back on its own.',resize: 'Resize timeline',seek: 'Drag the playhead',+ previewLate: 'Plays late here: renders when the film stops',+ previewMaking: 'Rendering to play smoothly… {p}%',+ previewReady: 'Rendered: plays smoothly here',+ previewFailed: 'Couldn’t render this stretch: it plays live',split: 'Split',subtitles: 'Subtitles',subtitlesNone: 'No subtitles yet — they appear once the film has a voice',@@ -1263,21 +1274,21 @@ export const en = {magnetOn: 'On: clips on the main track stay end to end, with no gaps',magnetOff: 'Off: clips on the main track stay where you put them',linkage: 'Linkage',- linkageOn: 'On: titles, overlays and sound move with the main-track clip under them',+ linkageOn: 'On: titles, overlays and sound move with the main-track clip under them, and go with it',linkageOff: 'Off: editing the main track moves only the main track',+ previewAxis: 'Preview axis',+ previewAxisOn: 'On: the picture follows the pointer over the timeline',+ previewAxisOff: 'Off: the picture stays at the playhead',rippleShort: "Clips on another track were in the way: {s} s left open so everything stays in sync.",- gapClosedAlone: 'Clips on other tracks were in the way, so the gap closed on this track alone.',menuCloseGap: 'Close gap',menuCloseGaps: 'Close all gaps on this track',menuRippleStart: 'Ripple trim start to playhead',menuRippleEnd: 'Ripple trim end to playhead',menuLink: 'Link',menuUnlink: 'Unlink',- rollHint: 'Drag to roll the cut: one clip gets longer, the other shorter',tip: {trim: 'Trim',ripple: 'Ripple',- roll: 'Roll',sourceEnd: 'End of the media',},trackLocked: 'Track locked',@@ -1351,7 +1362,7 @@ export const en = {replaceFromComputer: "From your computer…",replacePick: "Choose a file to replace the clip",},- /* a clip's attributes copied onto others (lib/clip-attrs, components/PasteAttrsDialog), as CapCut's */+ /* a clip's attributes copied onto others (lib/clip-attrs, components/PasteAttrsDialog) */clipAttrs: {title: 'Paste attributes',picture: 'Picture',@@ -1457,15 +1468,21 @@ export const en = {},storage: {group: 'Storage',- projects: 'New projects',- projectsHint: 'Where new projects go, with their media and cache. Projects made before stay where they are.',- projectsPick: 'Choose where new projects go',+ projects: 'Projects folder',+ projectsHint: 'Each project is a folder here, with its media and cache. Projects shows every project in this folder.',+ projectsPick: 'Choose the projects folder',pickButton: 'Choose',change: 'Change…',show: 'Show',reset: 'Use default',save: 'Save',free: '{size} free on this disk',+ moveTitle: 'Move your projects too?',+ moveDesc: '{count} projects are in {from}. Move them to {to}, or leave them where they are: they stay in Projects.',+ moveYes: 'Move projects',+ moveNo: 'Leave them',+ moved: 'Moved {count} projects.',+ moveFailed: 'These could not move and stay where they were: {names}',},playback: {group: "Playback",@@ -1473,6 +1490,10 @@ export const en = {proxiesHint: "Footage past 1080p, or slow to decode (ProRes, HEVC, 10-bit), plays from a lighter copy made in the background. Exports always use the originals.",proxySize: "Proxy size",proxySizeHint: "Smaller plays more smoothly; larger looks sharper in the viewer.",+ fitPages: "Draw pages at the viewer’s size",+ fitPagesHint: "Canvas and 3D in web pages are drawn at the size the viewer shows them, which plays more smoothly and looks the same. Off: at the film’s full size. Exports always draw at full size.",+ renders: "Render what plays late",+ rendersHint: "A stretch the viewer can’t play at full speed is rendered in the background once the film stops, and plays smoothly from then on. The timeline’s ruler marks it: red plays late, yellow is rendering, green is rendered.",},about: {group: 'About',@@ -1497,6 +1518,46 @@ export const en = {appUnavailable: 'Updates are unavailable right now. Try again later.',appFailed: 'Could not complete the update. Try again later.',},+ report: {+ title: 'Diagnostic report',+ hint: 'What OpenFilm finds on this computer and in this browser, the agents and the last week’s problems, to paste into an issue. Paths in your home folder show as ~; no keys, accounts or projects.',+ copy: 'Copy report',+ making: 'Checking…',+ copied: 'Copied',+ failed: 'Couldn’t make the report. Try again.',+ select: 'Your browser didn’t let Studio copy it: select the report below and copy it.',+ group: 'Diagnostics',+ export: 'Diagnostic file',+ exportHint: 'Everything else that says why something went wrong, as one zip in your exports folder: the report, the problems of the last two weeks, the logs, and how the failed turns went. Look at it before you attach it to an issue.',+ exportButton: 'Export',+ exporting: 'Exporting…',+ exported: 'Exported {name}, shown in its folder.',+ exportFailed: 'Couldn’t write the file. Try again.',+ conversations: 'Include what was said in failed turns',+ conversationsHint: 'Off, for each failed turn the file says only how it went: the agent and model, when each step started and ended, each tool’s kind and whether it worked, the agent’s notices and the error. Never your messages, the agent’s replies, commands, file names or anything from your files.',+ problems: 'Recent problems',+ problemsHint: 'What went wrong in the last two weeks, newest first. Kept on this computer only.',+ noProblems: 'No problems in the last two weeks.',+ more: 'Show all {count}',+ conversationsOn: 'On: the next file also has the words of the failed turns, as listed when you turned this on. Turn it off to leave them out.',+ addsTitle: 'Turning this on adds, for the last five turns that failed in the last two weeks:',+ adds1: 'Your messages, as you wrote them (pictures you attached stay out).',+ adds2: 'The agent’s replies and its thinking.',+ adds3: 'Each step’s title, command, input and output, which can hold your files’ names and contents and what commands printed.',+ adds4: 'The questions the agent asked you, and your answers.',+ adds5: 'The instructions the agent started with, including your own from its settings.',+ addsKept: 'Still taken out: your home folder (shown as ~), keys, tokens and email addresses. Nothing is sent anywhere: the file stays on this computer until you attach it.',+ addsWho: 'Anyone who can see where you attach it can read it, a public GitHub issue included. Send it only where you mean to.',+ addsYes: 'Include them',+ addsNo: 'Cancel',+ exportedHas: 'In it:',+ partReport: 'The diagnostic report',+ partProblems: 'The problems of the last two weeks',+ partLogs: 'The end of {count} logs of Studio and the app',+ partTurns: 'How {count} failed turns went, without what was said',+ partTurnsWords: '{count} failed turns, with what was said',+ partCodex: 'Codex’s own warnings and errors around its problems',+ },agents: {intro: 'The agents the chat can use. Codex, Claude Code and the others under Your agents are your own, on the account signed in on this computer: to use another account, switch accounts in the agent itself, then disconnect and connect it again here. Your own key runs on models you set up yourself, each on its own service.',byokName: 'Your own key',@@ -1591,7 +1652,10 @@ export const en = {mcpUnfiltered: '{agent} uses all {n} of your own MCP servers in OpenFilm, as in its own app.',},developer: {- intro: 'For finding out exactly what an agent did, and why: nothing here changes what the agents do.',+ playbackGroup: 'Playback',+ playbackStats: 'Show playback stats',+ playbackStatsHint: 'While the film plays, the viewer’s corner shows how many of the film’s frames it draws a second, how many times a second the screen got no new frame, and whether a stretch plays from its render.',+ intro: 'For finding out what went wrong, and exactly what an agent did and why: nothing here changes what the agents do.',group: 'Each turn',changes: 'Show what each turn changed',changesHint: 'Under each reply, the files the turn added, deleted or changed, with the lines added and removed. Click a file to see its changed lines.',@@ -1634,6 +1698,7 @@ export const en = {toggleMagnet: "Main track magnet on / off",toggleSnap: "Snapping on / off",toggleLinkage: "Linkage on / off",+ togglePreviewAxis: "Preview axis on / off",zoomFit: "Zoom to fit the film",frameStep: "Move playhead one frame",jumpStep: "Move playhead 10 frames",@@ -1664,7 +1729,7 @@ export const en = {selectMode: 'Select tool',splitMode: 'Split tool',splitModeAll: 'With the split tool, click with it held: every track is cut there',- editModeSwap: 'Hold while dropping a clip: insert instead of overwrite, or the other way round',+ editModeSwap: 'Hold while dropping a clip: it goes in between and what follows moves along',copyDrag: 'Drag a clip with it held: a copy goes where you let go, the clip stays',},providers: {diff --git a/packages/openfilm/studio/ui/src/i18n/es.ts b/packages/openfilm/studio/ui/src/i18n/es.tsindex 57eeb5a..61ea501 100644--- a/packages/openfilm/studio/ui/src/i18n/es.ts+++ b/packages/openfilm/studio/ui/src/i18n/es.ts@@ -10,7 +10,7 @@ export const es: Words = {desktop: 'Escritorio',},/* the app window's tabs (TabStrip), a new tab's launcher, and the examples (ExamplesGallery) */- tabs: { label: 'Pestañas', new: 'Abrir un proyecto', close: 'Cerrar pestaña' },+ tabs: { label: 'Pestañas', new: 'Abrir un proyecto', close: 'Cerrar pestaña', closeOthers: 'Cerrar las demás pestañas', closeRight: 'Cerrar las pestañas a la derecha' },launcher: { projects: 'Proyectos', examples: 'Ejemplos' },gallery: {title: 'Ejemplos',@@ -155,6 +155,12 @@ export const es: Words = {deleteFolderHintEmpty: 'Elimina la carpeta. No contiene ningún proyecto.',renameTaken: '“{name}” ya está en uso: ya hay una carpeta con ese nombre. Elige otro.',moveToFolder: 'Mover a carpeta',+ changeCover: 'Cambiar portada…',+ restoreCover: 'Usar la portada automática',+ coverFromFrame: 'Usar este fotograma como portada',+ setAsCover: 'Usar como portada del proyecto',+ coverSet: 'Portada establecida',+ coverFailed: 'No se pudo usar como portada.',noFolder: 'Sin carpeta',folderEmpty: 'Esta carpeta está vacía',creating: 'Creando proyecto',@@ -553,11 +559,10 @@ export const es: Words = {stepTrimmed: 'Recortado {clip}',stepSplit: 'Dividido {clip}',stepDetachAudio: 'Audio separado de {clip}',- stepRolled: 'Corte después de {clip} desplazado',stepRippleTrimmed: 'Recorte con desplazamiento de {clip}',stepGapClosed: 'Hueco cerrado',- stepMainClosed: 'Pista principal cerrada',stepGapsClosed: 'Huecos de una pista cerrados',+ stepMainClosed: 'Pista principal cerrada',stepLinked: '{clip} vinculado',stepUnlinked: '{clip} desvinculado',stepSpeed: 'Velocidad de {clip} cambiada',@@ -854,6 +859,8 @@ export const es: Words = {restackFailed: 'No se pudo reordenar esa capa. Puede que la imagen haya cambiado; inténtalo de nuevo.',},viewer: {+ stats: '{fps} fotogramas/s · {late} con retraso',+ statsRendered: 'desde un render',loopRange: "Reproducir el rango en bucle",loopFilm: "Bucle",play: 'Reproducir',@@ -1165,6 +1172,10 @@ export const es: Words = {mediaReconnecting: 'Reconectando con este clip… volverá por sí solo.',resize: 'Redimensionar línea de tiempo',seek: 'Arrastrar el cabezal de reproducción',+ previewLate: 'Aquí se reproduce con retraso: se renderiza al detener la película',+ previewMaking: 'Renderizando para reproducir con fluidez… {p}%',+ previewReady: 'Renderizado: aquí se reproduce con fluidez',+ previewFailed: 'No se pudo renderizar este tramo: se reproduce en vivo',split: 'Dividir',subtitles: 'Subtítulos',subtitlesNone: 'Aún no hay subtítulos: aparecen cuando la película tiene voz',@@ -1262,21 +1273,21 @@ export const es: Words = {magnetOn: 'Activado: los clips de la pista principal quedan seguidos, sin huecos',magnetOff: 'Desactivado: los clips de la pista principal se quedan donde los pones',linkage: 'Vinculación',- linkageOn: 'Activada: títulos, superposiciones y sonido se mueven con el clip de la pista principal que tienen debajo',- linkageOff: 'Desactivada: editar la pista principal mueve solo la pista principal',+ linkageOn: 'Activada: títulos, superposiciones y sonido se mueven con el clip de la pista principal que tienen debajo, y se van con él',+ linkageOff: 'Desactivada: editar la pista principal solo mueve la pista principal',+ previewAxis: 'Eje de vista previa',+ previewAxisOn: 'Activado: la imagen sigue al puntero sobre la línea de tiempo',+ previewAxisOff: 'Desactivado: la imagen se queda en el cabezal',rippleShort: 'Había clips en otra pista: quedan {s} s abiertos para que todo siga sincronizado.',- gapClosedAlone: 'Había clips en otras pistas, así que el hueco se cerró solo en esta pista.',menuCloseGap: 'Cerrar hueco',menuCloseGaps: 'Cerrar todos los huecos de esta pista',menuRippleStart: 'Recortar inicio hasta el cabezal y desplazar',menuRippleEnd: 'Recortar final hasta el cabezal y desplazar',menuLink: 'Vincular',menuUnlink: 'Desvincular',- rollHint: 'Arrastra para mover el corte: un clip se alarga y el otro se acorta',tip: {trim: 'Recorte',ripple: 'Desplazar',- roll: 'Corte',sourceEnd: 'Fin del medio',},trackLocked: 'Pista bloqueada',@@ -1350,7 +1361,7 @@ export const es: Words = {replaceFromComputer: "Desde tu ordenador…",replacePick: "Elige un archivo para reemplazar el clip",},- /* a clip's attributes copied onto others (lib/clip-attrs, components/PasteAttrsDialog), as CapCut's */+ /* a clip's attributes copied onto others (lib/clip-attrs, components/PasteAttrsDialog) */clipAttrs: {title: 'Pegar atributos',picture: 'Imagen',@@ -1456,15 +1467,21 @@ export const es: Words = {},storage: {group: 'Almacenamiento',- projects: 'Proyectos nuevos',- projectsHint: 'Dónde van los proyectos nuevos, con sus medios y su caché. Los proyectos anteriores se quedan donde están.',- projectsPick: 'Elige dónde van los proyectos nuevos',+ projects: 'Carpeta de proyectos',+ projectsHint: 'Cada proyecto es una carpeta aquí, con sus medios y su caché. La lista de proyectos muestra todos los de esta carpeta.',+ projectsPick: 'Elige la carpeta de proyectos',pickButton: 'Elegir',change: 'Cambiar…',show: 'Abrir',reset: 'Usar la predeterminada',save: 'Guardar',free: '{size} libres en este disco',+ moveTitle: '¿Mover también tus proyectos?',+ moveDesc: 'Hay {count} proyectos en {from}. Muévelos a {to} o déjalos donde están: seguirán en la lista de proyectos.',+ moveYes: 'Mover proyectos',+ moveNo: 'Dejarlos',+ moved: 'Se movieron {count} proyectos.',+ moveFailed: 'No se pudieron mover y siguen donde estaban: {names}',},playback: {group: "Reproducción",@@ -1472,6 +1489,10 @@ export const es: Words = {proxiesHint: "El metraje de más de 1080p, o lento de decodificar (ProRes, HEVC, 10 bits), se reproduce desde una copia ligera hecha en segundo plano. Las exportaciones siempre usan los originales.",proxySize: "Tamaño del proxy",proxySizeHint: "Más pequeño se reproduce con más fluidez; más grande se ve más nítido en el visor.",+ fitPages: "Dibujar las páginas al tamaño del visor",+ fitPagesHint: "El canvas y el 3D de las páginas web se dibujan al tamaño con que los muestra el visor: se ven igual y se reproducen con más fluidez. Desactivado: al tamaño completo de la película. Las exportaciones siempre se dibujan a tamaño completo.",+ renders: "Renderizar lo que se reproduce con retraso",+ rendersHint: "Un tramo que el visor no puede reproducir a velocidad completa se renderiza en segundo plano cuando se detiene la película, y desde entonces se reproduce con fluidez. La regla de la línea de tiempo lo marca: rojo se reproduce con retraso, amarillo se está renderizando, verde ya está renderizado.",},about: {group: 'Acerca de',@@ -1496,6 +1517,46 @@ export const es: Words = {appUnavailable: 'Las actualizaciones no están disponibles ahora. Inténtalo más tarde.',appFailed: 'No se pudo completar la actualización. Inténtalo más tarde.',},+ report: {+ title: 'Informe de diagnóstico',+ hint: 'Lo que OpenFilm encuentra en este equipo y en este navegador, los agentes y los problemas de la última semana, para pegarlo en un issue. Las rutas de tu carpeta personal aparecen como ~; sin claves, cuentas ni proyectos.',+ copy: 'Copiar informe',+ making: 'Comprobando…',+ copied: 'Copiado',+ failed: 'No se pudo crear el informe. Inténtalo de nuevo.',+ select: 'Tu navegador no dejó que Studio lo copiara: selecciona el informe de abajo y cópialo.',+ group: 'Diagnóstico',+ export: 'Archivo de diagnóstico',+ exportHint: 'Todo lo demás que explica por qué algo falló, en un zip en tu carpeta de exportaciones: el informe, los problemas de las últimas dos semanas, los registros y cómo fueron los turnos que fallaron. Revísalo antes de adjuntarlo a un issue.',+ exportButton: 'Exportar',+ exporting: 'Exportando…',+ exported: 'Se exportó {name}; se muestra en su carpeta.',+ exportFailed: 'No se pudo escribir el archivo. Inténtalo de nuevo.',+ conversations: 'Incluir lo que se dijo en los turnos fallidos',+ conversationsHint: 'Desactivado, de cada turno fallido el archivo solo dice cómo fue: el agente y el modelo, cuándo empezó y terminó cada paso, el tipo de cada herramienta y si funcionó, los avisos del agente y el error. Nunca tus mensajes, las respuestas del agente, comandos, nombres de archivo ni nada de tus archivos.',+ problems: 'Problemas recientes',+ problemsHint: 'Lo que falló en las últimas dos semanas, lo más reciente primero. Solo se guarda en este equipo.',+ noProblems: 'No hubo problemas en las últimas dos semanas.',+ more: 'Ver los {count}',+ conversationsOn: 'Activado: el próximo archivo también tendrá lo que se dijo en los turnos fallidos, lo que se listó al activarlo. Desactívalo para dejarlo fuera.',+ addsTitle: 'Al activarlo se añade, de los últimos cinco turnos que fallaron en las dos últimas semanas:',+ adds1: 'Tus mensajes, tal como los escribiste (las imágenes que adjuntaste quedan fuera).',+ adds2: 'Las respuestas del agente y su razonamiento.',+ adds3: 'El título, el comando, la entrada y la salida de cada paso, que pueden tener nombres y contenido de tus archivos y lo que imprimieron los comandos.',+ adds4: 'Las preguntas que te hizo el agente y tus respuestas.',+ adds5: 'Las instrucciones con las que empezó el agente, incluidas las tuyas de su configuración.',+ addsKept: 'Se sigue quitando: tu carpeta personal (se ve como ~), claves, tokens y direcciones de correo. No se envía nada: el archivo se queda en este equipo hasta que lo adjuntes.',+ addsWho: 'Cualquiera que vea dónde lo adjuntas puede leerlo, también en un issue público de GitHub. Envíalo solo donde quieras.',+ addsYes: 'Incluirlos',+ addsNo: 'Cancelar',+ exportedHas: 'Contiene:',+ partReport: 'El informe de diagnóstico',+ partProblems: 'Los problemas de las dos últimas semanas',+ partLogs: 'El final de {count} registros de Studio y la app',+ partTurns: 'Cómo fueron {count} turnos fallidos, sin lo que se dijo',+ partTurnsWords: '{count} turnos fallidos, con lo que se dijo',+ partCodex: 'Los avisos y errores del propio Codex en torno a sus problemas',+ },agents: {intro: 'Los agentes que puede usar el chat. Codex, Claude Code y los demás de Tus agentes son tuyos, con la cuenta iniciada en este equipo: para usar otra cuenta, cámbiala en el propio agente y luego desconéctalo y vuelve a conectarlo aquí. Tu propia clave usa modelos que configuras tú, cada uno con su propio servicio.',byokName: 'Tu propia clave',@@ -1590,7 +1651,10 @@ export const es: Words = {mcpUnfiltered: '{agent} usa tus {n} servidores MCP en OpenFilm, como en su propia app.',},developer: {- intro: 'Para saber exactamente qué hizo un agente y por qué: nada de esto cambia lo que hacen los agentes.',+ playbackGroup: 'Reproducción',+ playbackStats: 'Mostrar estadísticas de reproducción',+ playbackStatsHint: 'Mientras se reproduce la película, la esquina del visor muestra cuántos fotogramas de la película dibuja por segundo, cuántas veces por segundo la pantalla no recibió un fotograma nuevo y si un tramo se reproduce desde su render.',+ intro: 'Para saber qué falló y exactamente qué hizo un agente y por qué: nada de esto cambia lo que hacen los agentes.',group: 'Cada turno',changes: 'Mostrar lo que cambió cada turno',changesHint: 'Bajo cada respuesta, los archivos que el turno añadió, eliminó o cambió, con las líneas añadidas y quitadas. Haz clic en un archivo para ver sus líneas cambiadas.',@@ -1633,6 +1697,7 @@ export const es: Words = {toggleMagnet: "Activar / desactivar el imán de la pista principal",toggleSnap: "Activar / desactivar el ajuste",toggleLinkage: "Activar / desactivar la vinculación",+ togglePreviewAxis: "Activar / desactivar el eje de vista previa",zoomFit: "Ajustar el zoom a toda la película",frameStep: 'Mover el cabezal de reproducción un fotograma',jumpStep: "Mover el cabezal 10 fotogramas",@@ -1663,7 +1728,7 @@ export const es: Words = {selectMode: 'Herramienta de selección',splitMode: 'Herramienta de división',splitModeAll: 'Con la herramienta de corte, haz clic con ella pulsada: se cortan todas las pistas ahí',- editModeSwap: 'Mantén al soltar un clip: insertar en vez de sobrescribir, o al revés',+ editModeSwap: 'Mantén al soltar un clip: se intercala y lo que sigue se desplaza',copyDrag: 'Arrastra un clip con ella pulsada: una copia va donde lo sueltas y el clip se queda',},providers: {diff --git a/packages/openfilm/studio/ui/src/i18n/ja.ts b/packages/openfilm/studio/ui/src/i18n/ja.tsindex d8b8cea..e26217a 100644--- a/packages/openfilm/studio/ui/src/i18n/ja.ts+++ b/packages/openfilm/studio/ui/src/i18n/ja.ts@@ -10,7 +10,7 @@ export const ja: Words = {desktop: 'デスクトップ版',},/* the app window's tabs (TabStrip), a new tab's launcher, and the examples (ExamplesGallery) */- tabs: { label: 'タブ', new: 'プロジェクトを開く', close: 'タブを閉じる' },+ tabs: { label: 'タブ', new: 'プロジェクトを開く', close: 'タブを閉じる', closeOthers: '他のタブを閉じる', closeRight: '右側のタブを閉じる' },launcher: { projects: 'プロジェクト', examples: 'サンプル' },gallery: {title: 'サンプル',@@ -155,6 +155,12 @@ export const ja: Words = {deleteFolderHintEmpty: 'フォルダーを削除します。中にプロジェクトはありません。',renameTaken: '「{name}」は使用されています。同じ名前のフォルダーがすでにあります。別の名前を選んでください。',moveToFolder: 'フォルダーへ移動',+ changeCover: 'カバーを変更…',+ restoreCover: '自動のカバーに戻す',+ coverFromFrame: '現在のフレームをカバーにする',+ setAsCover: 'プロジェクトのカバーにする',+ coverSet: 'カバーを設定しました',+ coverFailed: 'カバーにできませんでした。',noFolder: 'フォルダーなし',folderEmpty: 'このフォルダーは空です',creating: 'プロジェクトを作成中',@@ -553,11 +559,10 @@ export const ja: Words = {stepTrimmed: '{clip} をトリミング',stepSplit: '{clip} を分割',stepDetachAudio: '{clip} のオーディオを切り離し',- stepRolled: '{clip} の後のカットをロール',stepRippleTrimmed: '{clip} をリップルトリム',stepGapClosed: '隙間を詰めました',- stepMainClosed: 'メイントラックを詰めました',stepGapsClosed: 'トラックの隙間を詰めました',+ stepMainClosed: 'メイントラックを詰めました',stepLinked: '{clip} をリンク',stepUnlinked: '{clip} のリンクを解除',stepSpeed: '{clip} の速度を変更',@@ -854,6 +859,8 @@ export const ja: Words = {restackFailed: 'このレイヤーの重ね順を変更できませんでした。画面が変わった可能性があります。もう一度お試しください。',},viewer: {+ stats: '{fps} フレーム/秒 · 遅延 {late}',+ statsRendered: 'レンダリングから再生',loopRange: "範囲をループ再生",loopFilm: "ループ再生",play: '再生',@@ -944,7 +951,7 @@ export const ja: Words = {inPoint: 'イン点',inPointWhole: 'クリップはファイル全体を再生しています。イン点を動かすには、先に短くしてください。',speed: '速度',- speedLimit: '{n}× より遅くすると次のクリップに重なります。メイントラックでは、タイムラインのメイントラックマグネットで後ろへ押し出せます。',+ speedLimit: '{n}× より遅くすると次のクリップに重なります。メイントラックでは、タイムラインのマグネットで後ろのクリップが送られます。',speedTooSlow: '{n}× より遅くすると同じトラックの次のクリップに重なります。',sound: 'サウンド',gainDb: '音量',@@ -1165,6 +1172,10 @@ export const ja: Words = {mediaReconnecting: 'このクリップに再接続しています… 自動的に復帰します。',resize: 'タイムラインのサイズを変更',seek: '再生ヘッドをドラッグ',+ previewLate: 'ここは再生が遅れます:再生を止めるとレンダリングします',+ previewMaking: '滑らかに再生するためレンダリング中… {p}%',+ previewReady: 'レンダリング済み:ここは滑らかに再生されます',+ previewFailed: 'この区間はレンダリングできませんでした:リアルタイムで再生します',split: '分割',subtitles: '字幕',subtitlesNone: '字幕はまだありません — 映像に音声が入ると表示されます',@@ -1258,25 +1269,25 @@ export const ja: Words = {snapOn: 'オン:クリップの端、再生ヘッド、マーカーにスナップします',snapOff: 'オフ:離した位置にそのまま置きます',mainTrack: 'メイントラック',- magnet: 'メイントラックマグネット',+ magnet: 'メイントラックのマグネット',magnetOn: 'オン:メイントラックのクリップは隙間なく並びます',magnetOff: 'オフ:メイントラックのクリップは置いた位置のままです',linkage: '連動',- linkageOn: 'オン:テロップ、オーバーレイ、音声が下のメイントラックのクリップと一緒に動きます',+ linkageOn: 'オン:テキスト、オーバーレイ、音声が下のメイントラックのクリップと一緒に動き、一緒に削除されます',linkageOff: 'オフ:メイントラックの編集はメイントラックだけを動かします',+ previewAxis: 'プレビュー軸',+ previewAxisOn: 'オン:タイムライン上のポインターに合わせて映像が動きます',+ previewAxisOff: 'オフ:映像は再生ヘッドの位置のままです',rippleShort: '他のトラックのクリップが邪魔をしています:同期を保つため {s} 秒の隙間が残りました。',- gapClosedAlone: '他のトラックのクリップが邪魔をしていたため、隙間はこのトラックだけで詰めました。',menuCloseGap: '隙間を詰める',menuCloseGaps: 'このトラックの隙間をすべて詰める',menuRippleStart: '再生ヘッドまで先頭をリップルトリム',menuRippleEnd: '再生ヘッドから末尾をリップルトリム',menuLink: 'リンク',menuUnlink: 'リンク解除',- rollHint: 'ドラッグでカットをロール:一方が長く、もう一方が短くなります',tip: {trim: 'トリム',ripple: 'リップル',- roll: 'ロール',sourceEnd: '素材の端です',},trackLocked: 'トラックはロックされています',@@ -1350,7 +1361,7 @@ export const ja: Words = {replaceFromComputer: "このコンピュータから…",replacePick: "クリップと置き換えるファイルを選択",},- /* a clip's attributes copied onto others (lib/clip-attrs, components/PasteAttrsDialog), as CapCut's */+ /* a clip's attributes copied onto others (lib/clip-attrs, components/PasteAttrsDialog) */clipAttrs: {title: '属性をペースト',picture: '映像',@@ -1456,15 +1467,21 @@ export const ja: Words = {},storage: {group: '保存場所',- projects: '新しいプロジェクト',- projectsHint: '新しいプロジェクトの保存先です。素材やキャッシュもプロジェクト内に置かれます。以前のプロジェクトはそのままの場所で開けます。',- projectsPick: '新しいプロジェクトの保存先を選択',+ projects: 'プロジェクトの場所',+ projectsHint: '各プロジェクトはここにあるフォルダで、素材やキャッシュも中にあります。このフォルダのプロジェクトはすべてプロジェクト一覧に表示されます。',+ projectsPick: 'プロジェクトの場所を選択',pickButton: '選択',change: '変更…',show: '開く',reset: 'デフォルトに戻す',save: '保存',free: 'このディスクの空き容量 {size}',+ moveTitle: '今あるプロジェクトも移動しますか?',+ moveDesc: '{from} に {count} 個のプロジェクトがあります。{to} に移動するか、元の場所に残せます。残してもプロジェクト一覧から開けます。',+ moveYes: 'プロジェクトを移動',+ moveNo: '元の場所に残す',+ moved: '{count} 個のプロジェクトを移動しました。',+ moveFailed: '移動できず元の場所に残ったプロジェクト:{names}',},playback: {group: "再生",@@ -1472,6 +1489,10 @@ export const ja: Words = {proxiesHint: "1080p を超える素材や、デコードが重い素材(ProRes、HEVC、10 ビット)は、バックグラウンドで作る軽いコピーで再生します。書き出しには常に元の素材を使います。",proxySize: "プロキシのサイズ",proxySizeHint: "小さいほど滑らかに再生でき、大きいほどビューアで鮮明に見えます。",+ fitPages: "Web ページをビューアのサイズで描画",+ fitPagesHint: "Web ページの Canvas と 3D を、ビューアに表示されるサイズで描画します。見た目は同じで、より滑らかに再生できます。オフにすると作品のフルサイズで描画します。書き出しは常にフルサイズです。",+ renders: "遅れる区間をレンダリング",+ rendersHint: "ビューアがフルスピードで再生できない区間を、再生を止めたあとバックグラウンドでレンダリングし、以後は滑らかに再生します。タイムラインのルーラーに表示されます:赤は遅れる区間、黄はレンダリング中、緑はレンダリング済みです。",},about: {group: 'このアプリについて',@@ -1496,6 +1517,46 @@ export const ja: Words = {appUnavailable: '現在アップデートを利用できません。しばらくしてからお試しください。',appFailed: 'アップデートを完了できませんでした。しばらくしてからお試しください。',},+ report: {+ title: '診断レポート',+ hint: 'このコンピュータとこのブラウザで OpenFilm が確認した内容、エージェント、この 1 週間の問題です。Issue に貼り付けてください。ホームフォルダ内のパスは ~ で表示され、キー、アカウント、プロジェクトは含まれません。',+ copy: 'レポートをコピー',+ making: '確認中…',+ copied: 'コピーしました',+ failed: 'レポートを作成できませんでした。もう一度お試しください。',+ select: 'ブラウザがコピーを許可しませんでした。下のレポートを選択してコピーしてください。',+ group: '診断',+ export: '診断ファイル',+ exportHint: '問題の原因がわかるその他の情報を、書き出しフォルダに 1 つの zip としてまとめます。レポート、この 2 週間の問題、ログ、失敗したターンの経過が入ります。Issue に添付する前に中身を確認してください。',+ exportButton: '書き出す',+ exporting: '書き出し中…',+ exported: '{name} を書き出し、フォルダに表示しました。',+ exportFailed: 'ファイルを書き出せませんでした。もう一度お試しください。',+ conversations: '失敗したターンの会話を含める',+ conversationsHint: 'オフのとき、失敗した各ターンについてファイルに入るのは経過だけです。使ったエージェントとモデル、各ステップの開始と終了の時刻、各ツールの種類と成否、エージェントの通知とエラーです。あなたのメッセージ、エージェントの返信、コマンド、ファイル名、ファイルの中身は一切入りません。',+ problems: '最近の問題',+ problemsHint: 'この 2 週間に起きた問題です。新しいものから表示します。このコンピュータにだけ保存されます。',+ noProblems: 'この 2 週間に問題はありません。',+ more: 'すべて表示({count} 件)',+ conversationsOn: 'オン:次に書き出すファイルには、失敗したターンの会話も入ります(オンにしたときに一覧で示した内容です)。入れたくないときはオフにしてください。',+ addsTitle: 'オンにすると、この 2 週間で最後に失敗した 5 つのターンについて、次の内容が加わります:',+ adds1: 'あなたのメッセージ(添付した画像は入りません)。',+ adds2: 'エージェントの返信と思考。',+ adds3: '各ステップのタイトル、コマンド、入力と出力。ファイル名やファイルの中身、コマンドの出力が含まれることがあります。',+ adds4: 'エージェントがあなたにした質問と、あなたの回答。',+ adds5: 'エージェントが開始時に受け取った指示。エージェントの設定にあなたが書いた指示も含みます。',+ addsKept: '引き続き取り除かれるもの:ホームフォルダ(~ と表示)、キー、トークン、メールアドレス。どこにも送信されません。あなたが添付するまで、ファイルはこのコンピュータに残ります。',+ addsWho: '添付した先を見られる人は誰でも読めます。公開の GitHub issue も同じです。送るつもりの相手にだけ送ってください。',+ addsYes: '含める',+ addsNo: 'キャンセル',+ exportedHas: '中身:',+ partReport: '診断レポート',+ partProblems: 'この 2 週間の問題',+ partLogs: 'Studio とアプリのログ {count} 件の末尾',+ partTurns: '失敗したターン {count} 件の経過(会話なし)',+ partTurnsWords: '失敗したターン {count} 件(会話あり)',+ partCodex: '問題の前後に Codex 自身が出した警告とエラー',+ },agents: {intro: '会話で使えるエージェントです。Codex、Claude Code など「あなたのエージェント」はあなた自身のもので、このコンピュータでサインインしているアカウントを使います。アカウントを変えるには、エージェント側で切り替えてから、ここで接続を解除して再接続してください。自分のキーは自分で設定したモデルで動き、モデルごとに別のサービスを使えます。',byokName: '自分のキー',@@ -1590,7 +1651,10 @@ export const ja: Words = {mcpUnfiltered: '{agent} は本来のアプリと同じく、OpenFilm でも自分の MCP サーバー {n} 個をすべて使います。',},developer: {- intro: 'エージェントが何をなぜ行ったかを正確に確かめるためのものです。エージェントの動作は変わりません。',+ playbackGroup: '再生',+ playbackStats: '再生の統計を表示',+ playbackStatsHint: '再生中、ビューアの隅に、1 秒間に描いた作品のフレーム数、画面が新しいフレームを得られなかった回数、レンダリング済みの区間を再生しているかを表示します。',+ intro: '何が問題だったのか、エージェントが何をなぜ行ったかを正確に確かめるためのものです。エージェントの動作は変わりません。',group: '各ターン',changes: '各ターンの変更を表示',changesHint: '各返信の下に、そのターンで追加・削除・変更されたファイルと、増減した行数を表示します。ファイルをクリックすると変更された行を確認できます。',@@ -1630,9 +1694,10 @@ export const ja: Words = {speedPanel: "選んだクリップの速度",detachAudio: "動画の音声を分離",nudgeClip: "選択したクリップを 1 フレーム移動",- toggleMagnet: "メイントラックマグネットのオン / オフ",+ toggleMagnet: "メイントラックのマグネットのオン / オフ",toggleSnap: "スナップのオン / オフ",toggleLinkage: "連動のオン / オフ",+ togglePreviewAxis: "プレビュー軸のオン / オフ",zoomFit: "全体が収まるようにズーム",frameStep: '再生ヘッドを 1 フレーム移動',jumpStep: "再生ヘッドを 10 フレーム移動",@@ -1663,7 +1728,7 @@ export const ja: Words = {selectMode: '選択ツール',splitMode: '分割ツール',splitModeAll: '分割ツールで押しながらクリック:すべてのトラックをその位置で分割',- editModeSwap: 'クリップを置くときに押す:挿入と上書きを入れ替え',+ editModeSwap: 'クリップを置くときに押す:間に挿入し、後ろのクリップを送る',copyDrag: '押しながらクリップをドラッグ:離した位置にコピー、元のクリップはそのまま',},providers: {diff --git a/packages/openfilm/studio/ui/src/i18n/ko.ts b/packages/openfilm/studio/ui/src/i18n/ko.tsindex 7e267e9..7b9e362 100644--- a/packages/openfilm/studio/ui/src/i18n/ko.ts+++ b/packages/openfilm/studio/ui/src/i18n/ko.ts@@ -10,7 +10,7 @@ export const ko: Words = {desktop: '데스크톱',},/* the app window's tabs (TabStrip), a new tab's launcher, and the examples (ExamplesGallery) */- tabs: { label: '탭', new: '프로젝트 열기', close: '탭 닫기' },+ tabs: { label: '탭', new: '프로젝트 열기', close: '탭 닫기', closeOthers: '다른 탭 닫기', closeRight: '오른쪽 탭 닫기' },launcher: { projects: '내 프로젝트', examples: '예시' },gallery: {title: '예시',@@ -155,6 +155,12 @@ export const ko: Words = {deleteFolderHintEmpty: '폴더를 삭제합니다. 폴더 안에 프로젝트가 없습니다.',renameTaken: '“{name}”은(는) 이미 사용 중인 폴더 이름입니다. 다른 이름을 선택하세요.',moveToFolder: '폴더로 이동',+ changeCover: '커버 변경…',+ restoreCover: '자동 커버로 되돌리기',+ coverFromFrame: '현재 화면을 커버로 설정',+ setAsCover: '프로젝트 커버로 설정',+ coverSet: '커버를 설정했습니다',+ coverFailed: '커버로 사용할 수 없습니다.',noFolder: '폴더 없음',folderEmpty: '이 폴더는 비어 있습니다',creating: '프로젝트 만드는 중',@@ -553,11 +559,10 @@ export const ko: Words = {stepTrimmed: '{clip} 트리밍',stepSplit: '{clip} 분할',stepDetachAudio: '{clip}의 오디오 분리',- stepRolled: '{clip} 뒤의 컷 롤',stepRippleTrimmed: '{clip} 리플 트림',stepGapClosed: '간격 메움',- stepMainClosed: '메인 트랙을 메움',stepGapsClosed: '트랙의 간격을 메움',+ stepMainClosed: '메인 트랙을 메움',stepLinked: '{clip} 연결',stepUnlinked: '{clip} 연결 해제',stepSpeed: '{clip} 속도 변경',@@ -854,6 +859,8 @@ export const ko: Words = {restackFailed: '이 레이어의 순서를 바꾸지 못했습니다. 화면이 바뀌었을 수 있으니 다시 시도하세요.',},viewer: {+ stats: '{fps} 프레임/초 · 지연 {late}',+ statsRendered: '렌더링에서 재생',loopRange: "범위 반복 재생",loopFilm: "반복 재생",play: '재생',@@ -944,7 +951,7 @@ export const ko: Words = {inPoint: '시작 지점',inPointWhole: '클립이 파일 전체를 재생하고 있습니다. 시작 지점을 옮기려면 먼저 줄이세요.',speed: '속도',- speedLimit: '{n}×보다 느리면 다음 클립과 겹칩니다. 메인 트랙에서는 타임라인의 메인 트랙 자석이 뒤로 밀어냅니다.',+ speedLimit: '{n}×보다 느리면 다음 클립과 겹칩니다. 메인 트랙에서는 타임라인의 자석이 뒤 클립을 밀어냅니다.',speedTooSlow: '{n}×보다 느리면 같은 트랙의 다음 클립과 겹칩니다.',sound: '사운드',gainDb: '볼륨',@@ -1165,6 +1172,10 @@ export const ko: Words = {mediaReconnecting: '이 클립에 다시 연결하는 중… 곧 자동으로 돌아옵니다.',resize: '타임라인 크기 조정',seek: '재생 헤드 드래그',+ previewLate: '여기는 느리게 재생됩니다: 재생을 멈추면 렌더링합니다',+ previewMaking: '부드럽게 재생하도록 렌더링 중… {p}%',+ previewReady: '렌더링됨: 여기는 부드럽게 재생됩니다',+ previewFailed: '이 구간은 렌더링하지 못했습니다: 실시간으로 재생합니다',split: '분할',subtitles: '자막',subtitlesNone: '아직 자막이 없습니다. 영상에 음성이 생기면 나타납니다',@@ -1259,24 +1270,24 @@ export const ko: Words = {snapOff: '끔: 손을 놓은 자리에 그대로 놓입니다',mainTrack: '메인 트랙',magnet: '메인 트랙 자석',- magnetOn: '켬: 메인 트랙의 클립이 빈틈없이 붙어 있습니다',+ magnetOn: '켬: 메인 트랙의 클립이 빈틈 없이 이어집니다',magnetOff: '끔: 메인 트랙의 클립이 놓은 자리에 그대로 있습니다',linkage: '연동',- linkageOn: '켬: 자막, 오버레이, 소리가 아래 메인 트랙 클립과 함께 움직입니다',- linkageOff: '끔: 메인 트랙 편집은 메인 트랙만 움직입니다',+ linkageOn: '켬: 자막, 오버레이, 소리가 아래 메인 트랙 클립과 함께 움직이고 함께 삭제됩니다',+ linkageOff: '끔: 메인 트랙을 편집하면 메인 트랙만 움직입니다',+ previewAxis: '미리보기 축',+ previewAxisOn: '켬: 타임라인 위 포인터를 따라 화면이 움직입니다',+ previewAxisOff: '끔: 화면이 재생 헤드 위치에 머뭅니다',rippleShort: '다른 트랙의 클립이 막고 있습니다: 동기를 유지하려고 {s}초 간격이 남았습니다.',- gapClosedAlone: '다른 트랙의 클립이 막고 있어 이 트랙에서만 간격을 메웠습니다.',menuCloseGap: '간격 메우기',menuCloseGaps: '이 트랙의 간격 모두 메우기',menuRippleStart: '재생 헤드까지 시작 리플 트림',menuRippleEnd: '재생 헤드부터 끝 리플 트림',menuLink: '연결',menuUnlink: '연결 해제',- rollHint: '드래그하여 컷 롤: 한 클립은 길어지고 다른 클립은 짧아집니다',tip: {trim: '트림',ripple: '리플',- roll: '롤',sourceEnd: '소스의 끝입니다',},trackLocked: '트랙 잠김',@@ -1350,7 +1361,7 @@ export const ko: Words = {replaceFromComputer: "이 컴퓨터에서…",replacePick: "클립을 바꿀 파일 선택",},- /* a clip's attributes copied onto others (lib/clip-attrs, components/PasteAttrsDialog), as CapCut's */+ /* a clip's attributes copied onto others (lib/clip-attrs, components/PasteAttrsDialog) */clipAttrs: {title: '속성 붙여넣기',picture: '화면',@@ -1455,15 +1466,21 @@ export const ko: Words = {},storage: {group: '저장 위치',- projects: '새 프로젝트',- projectsHint: '새 프로젝트가 저장되는 곳입니다. 소재와 캐시도 프로젝트 안에 있습니다. 이전 프로젝트는 원래 위치에서 그대로 열 수 있습니다.',- projectsPick: '새 프로젝트 위치 선택',+ projects: '프로젝트 위치',+ projectsHint: '각 프로젝트는 이곳의 폴더이며, 소재와 캐시도 그 안에 있습니다. 이 폴더의 프로젝트는 모두 프로젝트 목록에 표시됩니다.',+ projectsPick: '프로젝트 위치 선택',pickButton: '선택',change: '변경…',show: '열기',reset: '기본값으로',save: '저장',free: '이 디스크 남은 공간 {size}',+ moveTitle: '기존 프로젝트도 옮길까요?',+ moveDesc: '{from}에 프로젝트 {count}개가 있습니다. {to}(으)로 옮기거나 원래 위치에 둘 수 있습니다. 그대로 두어도 프로젝트 목록에서 열 수 있습니다.',+ moveYes: '프로젝트 옮기기',+ moveNo: '그대로 두기',+ moved: '프로젝트 {count}개를 옮겼습니다.',+ moveFailed: '옮기지 못해 원래 위치에 남은 프로젝트: {names}',},playback: {group: "재생",@@ -1471,6 +1488,10 @@ export const ko: Words = {proxiesHint: "1080p를 넘거나 디코딩이 무거운(ProRes, HEVC, 10비트) 영상은 백그라운드에서 만든 가벼운 사본으로 재생합니다. 내보내기에는 항상 원본을 씁니다.",proxySize: "프록시 크기",proxySizeHint: "작을수록 더 부드럽게 재생되고, 클수록 뷰어에서 더 선명합니다.",+ fitPages: "웹 페이지를 뷰어 크기로 그리기",+ fitPagesHint: "웹 페이지의 Canvas와 3D를 뷰어에 보이는 크기로 그립니다. 보기에는 같고 더 부드럽게 재생됩니다. 끄면 영상의 전체 크기로 그립니다. 내보내기는 항상 전체 크기입니다.",+ renders: "느리게 재생되는 구간 렌더링",+ rendersHint: "뷰어가 제 속도로 재생하지 못하는 구간은 재생을 멈춘 뒤 백그라운드에서 렌더링되고, 그 뒤로는 부드럽게 재생됩니다. 타임라인 눈금자에 표시됩니다: 빨강은 느린 구간, 노랑은 렌더링 중, 초록은 렌더링 완료입니다.",},about: {group: '정보',@@ -1495,6 +1516,46 @@ export const ko: Words = {appUnavailable: '지금은 업데이트를 사용할 수 없습니다. 나중에 다시 시도하세요.',appFailed: '업데이트를 완료하지 못했습니다. 나중에 다시 시도하세요.',},+ report: {+ title: '진단 보고서',+ hint: 'OpenFilm이 이 컴퓨터와 이 브라우저에서 확인한 내용, 에이전트, 최근 일주일의 문제입니다. 이슈에 붙여 넣으세요. 홈 폴더 안의 경로는 ~로 표시되며, 키, 계정, 프로젝트는 포함되지 않습니다.',+ copy: '보고서 복사',+ making: '확인 중…',+ copied: '복사됨',+ failed: '보고서를 만들지 못했습니다. 다시 시도해 주세요.',+ select: '브라우저가 복사를 허용하지 않았습니다. 아래 보고서를 선택해 복사하세요.',+ group: '진단',+ export: '진단 파일',+ exportHint: '문제의 원인을 알려 주는 나머지 정보를 내보내기 폴더에 zip 하나로 만듭니다. 보고서, 최근 2주의 문제, 로그, 실패한 턴의 진행 과정이 들어 있습니다. 이슈에 첨부하기 전에 확인하세요.',+ exportButton: '내보내기',+ exporting: '내보내는 중…',+ exported: '{name}을(를) 내보내고 폴더에 표시했습니다.',+ exportFailed: '파일을 쓰지 못했습니다. 다시 시도해 주세요.',+ conversations: '실패한 턴의 대화 포함',+ conversationsHint: '끄면, 실패한 각 턴에 대해 파일에는 진행 과정만 들어갑니다. 사용한 에이전트와 모델, 각 단계의 시작과 끝 시각, 각 도구의 종류와 성공 여부, 에이전트의 알림과 오류입니다. 메시지, 에이전트의 답변, 명령, 파일 이름이나 파일 내용은 전혀 들어가지 않습니다.',+ problems: '최근 문제',+ problemsHint: '최근 2주 동안 생긴 문제입니다. 최신 순으로 표시합니다. 이 컴퓨터에만 저장됩니다.',+ noProblems: '최근 2주 동안 문제가 없습니다.',+ more: '모두 보기 ({count}개)',+ conversationsOn: '켜짐: 다음에 내보내는 파일에는 실패한 턴의 대화도 들어갑니다(켤 때 목록으로 보여 준 내용). 빼려면 끄세요.',+ addsTitle: '켜면 최근 2주 동안 마지막으로 실패한 턴 5개에 대해 다음 내용이 추가됩니다:',+ adds1: '보낸 메시지 원문(첨부한 이미지는 들어가지 않습니다).',+ adds2: '에이전트의 답변과 생각 과정.',+ adds3: '각 단계의 제목, 명령, 입력과 출력. 파일 이름과 내용, 명령이 출력한 내용이 들어 있을 수 있습니다.',+ adds4: '에이전트가 한 질문과 사용자의 답변.',+ adds5: '에이전트가 시작할 때 받은 지시. 에이전트 설정에 직접 적은 지시도 포함됩니다.',+ addsKept: '계속 빠지는 것: 홈 폴더(~로 표시), 키, 토큰, 이메일 주소. 어디로도 전송되지 않습니다. 직접 첨부하기 전까지 파일은 이 컴퓨터에만 있습니다.',+ addsWho: '첨부한 곳을 볼 수 있는 사람은 누구나 읽을 수 있습니다. 공개 GitHub 이슈도 마찬가지입니다. 보낼 곳에만 보내세요.',+ addsYes: '포함하기',+ addsNo: '취소',+ exportedHas: '들어 있는 내용:',+ partReport: '진단 보고서',+ partProblems: '최근 2주의 문제',+ partLogs: 'Studio와 앱 로그 {count}개의 마지막 부분',+ partTurns: '실패한 턴 {count}개의 진행 과정(대화 없음)',+ partTurnsWords: '실패한 턴 {count}개(대화 포함)',+ partCodex: '문제 전후로 Codex가 직접 남긴 경고와 오류',+ },agents: {intro: '채팅에서 쓸 수 있는 에이전트입니다. Codex, Claude Code 등 「내 에이전트」는 나의 것이며 이 컴퓨터에 로그인된 계정을 사용합니다. 다른 계정을 쓰려면 에이전트에서 계정을 바꾼 뒤 여기서 연결을 끊고 다시 연결하세요. 내 키는 직접 설정한 모델로 실행되며, 모델마다 다른 서비스를 쓸 수 있습니다.',byokName: '내 키',@@ -1589,7 +1650,10 @@ export const ko: Words = {mcpUnfiltered: '{agent}는 자체 앱에서처럼 OpenFilm에서도 내 MCP 서버 {n}개를 모두 사용합니다.',},developer: {- intro: '에이전트가 무엇을 왜 했는지 정확히 확인하기 위한 기능입니다. 에이전트의 동작은 바뀌지 않습니다.',+ playbackGroup: '재생',+ playbackStats: '재생 통계 표시',+ playbackStatsHint: '재생 중 뷰어 모서리에 초당 그린 영상 프레임 수, 화면이 새 프레임을 받지 못한 횟수, 렌더링된 구간을 재생 중인지를 표시합니다.',+ intro: '무엇이 잘못되었는지, 에이전트가 무엇을 왜 했는지 정확히 확인하기 위한 기능입니다. 에이전트의 동작은 바뀌지 않습니다.',group: '각 턴',changes: '각 턴의 변경 사항 보기',changesHint: '각 답변 아래에 이번 턴에서 추가·삭제·변경된 파일과 늘고 줄어든 줄 수를 보여 줍니다. 파일을 누르면 변경된 줄을 볼 수 있습니다.',@@ -1632,6 +1696,7 @@ export const ko: Words = {toggleMagnet: "메인 트랙 자석 켜기 / 끄기",toggleSnap: "스냅 켜기 / 끄기",toggleLinkage: "연동 켜기 / 끄기",+ togglePreviewAxis: "미리보기 축 켜기 / 끄기",zoomFit: "전체가 보이게 확대/축소",frameStep: '재생 헤드를 1프레임 이동',jumpStep: "재생 헤드 10프레임 이동",@@ -1662,7 +1727,7 @@ export const ko: Words = {selectMode: '선택 도구',splitMode: '분할 도구',splitModeAll: '분할 도구에서 누른 채 클릭: 모든 트랙을 그 자리에서 분할',- editModeSwap: '클립을 놓을 때 누르기: 삽입과 덮어쓰기를 바꿈',+ editModeSwap: '클립을 놓을 때 누르기: 사이에 끼워 넣고 뒤 클립을 밀어냄',copyDrag: '누른 채 클립 드래그: 놓은 자리에 복사본, 원래 클립은 그대로',},providers: {diff --git a/packages/openfilm/studio/ui/src/i18n/zh-CN.ts b/packages/openfilm/studio/ui/src/i18n/zh-CN.tsindex 054d7a0..41bd116 100644--- a/packages/openfilm/studio/ui/src/i18n/zh-CN.ts+++ b/packages/openfilm/studio/ui/src/i18n/zh-CN.ts@@ -11,7 +11,7 @@ export const zhCN: Words = {desktop: '桌面版',},/* the app window's tabs (TabStrip), a new tab's launcher, and the examples (ExamplesGallery) */- tabs: { label: '标签页', new: '打开项目', close: '关闭标签页' },+ tabs: { label: '标签页', new: '打开项目', close: '关闭标签页', closeOthers: '关闭其他标签页', closeRight: '关闭右侧标签页' },launcher: { projects: '我的项目', examples: '示例' },gallery: {title: '示例',@@ -156,6 +156,12 @@ export const zhCN: Words = {deleteFolderHintEmpty: '删除此文件夹。其中没有项目。',renameTaken: '“{name}”已被占用:已有同名文件夹。请换一个名称。',moveToFolder: '移到文件夹',+ changeCover: '更换封面…',+ restoreCover: '恢复自动封面',+ coverFromFrame: '将当前画面设为封面',+ setAsCover: '设为项目封面',+ coverSet: '已设为封面',+ coverFailed: '无法用它做封面。',noFolder: '无文件夹',folderEmpty: '此文件夹为空',creating: '正在创建项目',@@ -554,11 +560,10 @@ export const zhCN: Words = {stepTrimmed: '修剪 {clip}',stepSplit: '分割 {clip}',stepDetachAudio: '分离 {clip} 的音频',- stepRolled: '滚动了 {clip} 之后的剪切点',stepRippleTrimmed: '波纹裁剪了 {clip}',stepGapClosed: '合拢了间隙',- stepMainClosed: '合拢了主轨',stepGapsClosed: '批量闭合了空隙',+ stepMainClosed: '合拢了主轨',stepLinked: '关联了 {clip}',stepUnlinked: '取消关联 {clip}',stepSpeed: '改了 {clip} 的速度',@@ -855,6 +860,8 @@ export const zhCN: Words = {restackFailed: '这个图层没能调整顺序。画面可能刚变过,再试一次。',},viewer: {+ stats: '{fps} 帧/秒 · 丢 {late}',+ statsRendered: '播放渲染片段',loopRange: "循环播放范围",loopFilm: "循环播放",play: '播放',@@ -1166,6 +1173,10 @@ export const zhCN: Words = {mediaReconnecting: '正在重新连接此片段…它会自动恢复。',resize: '调整时间轴大小',seek: '拖动播放头',+ previewLate: '这里播放卡顿:停止播放后渲染',+ previewMaking: '正在渲染以流畅播放… {p}%',+ previewReady: '已渲染:这里能流畅播放',+ previewFailed: '这一段无法渲染:按实时画面播放',split: '分割',subtitles: '字幕',subtitlesNone: '还没有字幕——影片有了人声后就会出现',@@ -1265,19 +1276,19 @@ export const zhCN: Words = {linkage: '联动',linkageOn: '开:字幕、画中画、声音跟着下面的主轨片段一起移动、删除',linkageOff: '关:编辑主轨时只动主轨',+ previewAxis: '预览轴',+ previewAxisOn: '开:鼠标在时间线上移动,画面跟着走',+ previewAxisOff: '关:画面停在播放头处',rippleShort: '其他轨道上有片段挡着:为保持同步,留下了 {s} 秒的空隙。',- gapClosedAlone: '其他轨道上有片段挡着,间隙只在本轨合上了。',menuCloseGap: '合拢间隙',menuCloseGaps: '批量闭合空隙',menuRippleStart: '波纹裁剪开头到播放头',menuRippleEnd: '波纹裁剪结尾到播放头',menuLink: '关联',menuUnlink: '取消关联',- rollHint: '拖动以滚动剪切点:一个片段变长,另一个变短',tip: {trim: '裁剪',ripple: '波纹',- roll: '滚动',sourceEnd: '素材到头了',},trackLocked: '轨道已锁定',@@ -1351,7 +1362,7 @@ export const zhCN: Words = {replaceFromComputer: "从电脑选择…",replacePick: "选择用来替换的文件",},- /* a clip's attributes copied onto others (lib/clip-attrs, components/PasteAttrsDialog), as CapCut's */+ /* a clip's attributes copied onto others (lib/clip-attrs, components/PasteAttrsDialog) */clipAttrs: {title: '粘贴属性',picture: '画面',@@ -1457,15 +1468,21 @@ export const zhCN: Words = {},storage: {group: '存储位置',- projects: '新项目位置',- projectsHint: '新建的项目放在这里,素材和缓存也在项目里。之前的项目留在原处,照常可以打开。',- projectsPick: '选择新项目的位置',+ projects: '项目位置',+ projectsHint: '每个项目是这里的一个文件夹,素材和缓存都在里面。这个文件夹里的项目都显示在项目列表里。',+ projectsPick: '选择项目位置',pickButton: '选择',change: '更改…',show: '打开',reset: '恢复默认',save: '保存',free: '所在磁盘剩余 {size}',+ moveTitle: '把现有项目一起移过去?',+ moveDesc: '{from} 里有 {count} 个项目。可以一起移到 {to},也可以留在原处,项目列表里照样能打开。',+ moveYes: '移动项目',+ moveNo: '留在原处',+ moved: '已移动 {count} 个项目。',+ moveFailed: '这些项目没能移动,仍在原处:{names}',},playback: {group: "播放",@@ -1473,6 +1490,10 @@ export const zhCN: Words = {proxiesHint: "超过 1080p 或解码较慢(ProRes、HEVC、10 位)的素材,会在后台生成一份轻量副本用于预览播放。导出始终使用原素材。",proxySize: "代理分辨率",proxySizeHint: "越小播放越流畅,越大预览越清晰。",+ fitPages: "按查看器尺寸绘制网页",+ fitPagesHint: "网页里的 Canvas 和 3D 按查看器实际显示的尺寸绘制,看起来一样,播放更流畅。关闭后按影片完整尺寸绘制。导出始终按完整尺寸。",+ renders: "渲染播放卡顿的片段",+ rendersHint: "查看器无法全速播放的片段,会在停止播放后于后台渲染,之后就能流畅播放。时间线标尺上会标出:红色是卡顿,黄色是正在渲染,绿色是已渲染。",},about: {group: '关于',@@ -1497,6 +1518,46 @@ export const zhCN: Words = {appUnavailable: '更新服务暂时不可用,请稍后再试。',appFailed: '更新没能完成,请稍后再试。',},+ report: {+ title: '诊断报告',+ hint: 'OpenFilm 在这台电脑和这个浏览器里检查到的情况、各个智能体和最近一周的问题,可以贴到 issue 里。主目录下的路径显示为 ~,不含密钥、账号和项目。',+ copy: '复制报告',+ making: '检查中…',+ copied: '已复制',+ failed: '报告没有生成,请再试一次。',+ select: '浏览器不允许 Studio 复制,请选中下面的报告手动复制。',+ group: '诊断',+ export: '诊断文件',+ exportHint: '其余能说明问题原因的内容,打成一个 zip 放在导出文件夹里:报告、最近两周的问题、日志,以及失败的那几轮是怎么进行的。附到 issue 之前请先看一下。',+ exportButton: '导出',+ exporting: '导出中…',+ exported: '已导出 {name},并在文件夹中显示。',+ exportFailed: '文件没有写成,请再试一次。',+ conversations: '包括失败那几轮的对话',+ conversationsHint: '关闭时,每个失败的回合在文件里只记录过程:用的哪个智能体和模型、每一步什么时候开始和结束、每个工具的类型和成没成功、智能体的提示和报错。不包含你的消息、智能体的回复、命令、文件名或你文件里的任何内容。',+ problems: '最近的问题',+ problemsHint: '最近两周出过的问题,最新的在前。只保存在这台电脑上。',+ noProblems: '最近两周没有问题。',+ more: '显示全部 {count} 条',+ conversationsOn: '已打开:下一次导出的文件会带上失败回合里的对话,内容就是打开时列出的那些。关闭即可不带。',+ addsTitle: '打开后,最近两周内最后五个失败的回合会多带上:',+ adds1: '你发的消息原文(你附上的图片不会带上)。',+ adds2: '智能体的回复和它的思考过程。',+ adds3: '每一步的标题、命令、输入和输出,其中可能有你的文件名、文件内容和命令打印出的内容。',+ adds4: '智能体问你的问题,以及你的回答。',+ adds5: '智能体启动时收到的说明,包括你在它的设置里自己写的说明。',+ addsKept: '仍然会去掉:你的主目录(显示为 ~)、密钥、令牌和邮箱地址。不会发送到任何地方:文件一直留在这台电脑上,直到你自己附到别处。',+ addsWho: '能看到你附件的人都能读到它,公开的 GitHub issue 也一样。只发到你想发的地方。',+ addsYes: '确认带上',+ addsNo: '取消',+ exportedHas: '文件里有:',+ partReport: '诊断报告',+ partProblems: '最近两周的问题',+ partLogs: 'Studio 和应用的 {count} 份日志的最后一段',+ partTurns: '{count} 个失败回合的过程,不含对话',+ partTurnsWords: '{count} 个失败回合,含对话',+ partCodex: 'Codex 自己在出问题前后的警告和报错',+ },agents: {intro: '对话可以使用的智能体。Codex、Claude Code 等「你的智能体」是你自己的,使用这台电脑上已登录的账号:想换账号,就在智能体里切换,再回到这里断开后重新连接。自有密钥使用你自己配置的模型,每个模型可以接不同的服务。',byokName: '自有密钥',@@ -1591,7 +1652,10 @@ export const zhCN: Words = {mcpUnfiltered: '{agent} 在 OpenFilm 里会使用你自己的全部 {n} 个 MCP 服务,和它自己的应用里一样。',},developer: {- intro: '用来弄清楚智能体到底做了什么、为什么这么做;这里的设置不会改变智能体的行为。',+ playbackGroup: '播放',+ playbackStats: '显示播放统计',+ playbackStatsHint: '播放时在查看器角落显示每秒画出的影片帧数、屏幕每秒有几次没拿到新帧,以及当前是否在播放渲染好的片段。',+ intro: '用来弄清楚哪里出了问题,以及智能体到底做了什么、为什么这么做;这里的设置不会改变智能体的行为。',group: '每一轮',changes: '显示每一轮的改动',changesHint: '每条回复下面列出这一轮新增、删除或修改的文件,以及增减的行数。点开一个文件可以看到改动的行。',@@ -1634,6 +1698,7 @@ export const zhCN: Words = {toggleMagnet: "开关主轨磁吸",toggleSnap: "开关吸附",toggleLinkage: "开关联动",+ togglePreviewAxis: "开关预览轴",zoomFit: "缩放到整片",frameStep: '播放头移动一帧',jumpStep: "播放头移动 10 帧",@@ -1664,7 +1729,7 @@ export const zhCN: Words = {selectMode: '选择工具',splitMode: '分割工具',splitModeAll: '分割工具下按住它点击:所有轨道都在这里切开',- editModeSwap: '放下片段时按住:插入改为覆盖,或反过来',+ editModeSwap: '放下片段时按住:插到中间,后面的片段跟着后移',copyDrag: '按住它拖动片段:在松手处复制一份,原片段不动',},providers: {diff --git a/packages/openfilm/studio/ui/src/lib/asset-timeline.test.ts b/packages/openfilm/studio/ui/src/lib/asset-timeline.test.tsindex 7dc6000..136325a 100644--- a/packages/openfilm/studio/ui/src/lib/asset-timeline.test.ts+++ b/packages/openfilm/studio/ui/src/lib/asset-timeline.test.ts@@ -4,7 +4,7 @@ import { assetClipElement, assetClipKindOf, assetDropInsert, assetDropSpot, asseimport type { TimelineTrack } from './timeline-layout.ts';/* A file from the media pane lands on the row under the pointer — a track has no kind (SPEC) — or, where its time- is taken, on a new track right there; never somewhere else. */+ is taken, on a new track right beside it; never somewhere else. */const row = (docIndex: number, role: TimelineTrack['role'], spans: [number, number][]): TimelineTrack => ({lane: `doc-${docIndex}`,@@ -29,8 +29,9 @@ test('footage dropped on a free stretch of a page track goes onto it', () => {assert.equal(assetDropSpot(sound, tracks, { lane: 1, band: 'body' }, 10_000)?.action, 'into');});-test('where the time is taken, a new track right under the row pointed at', () => {- assert.deepEqual(assetDropSpot(video, tracks, { lane: 0, band: 'body' }, 2000), { action: 'new-track', laneIndex: 1, docAt: 1 });+test('where the time is taken, a new track right above a picture row, right below a sound row', () => {+ assert.deepEqual(assetDropSpot(video, tracks, { lane: 0, band: 'body' }, 2000), { action: 'new-track', laneIndex: 0, docAt: 0 });+ assert.deepEqual(assetDropSpot(video, tracks, { lane: 1, band: 'body' }, 2000), { action: 'new-track', laneIndex: 1, docAt: 1 });assert.deepEqual(assetDropSpot(video, tracks, { lane: 2, band: 'body' }, 2000), { action: 'new-track', laneIndex: 3, docAt: 3 });});@@ -76,9 +77,9 @@ test('files dropped from the computer go one after another on one track, each fr{ element: { src: still.path, time: [0, 4] }, at: 13.033, durMs: 4000, track: 0 },],});- /* where the run does not fit, a new track opens under the row; the rest follow onto it */+ /* where the run does not fit, a new track opens above the row; the rest follow onto it */const run = assetRunInsert([clip, still], tracks, { lane: 0, band: 'body' }, 6000);- assert.deepEqual('inserts' in run && run.inserts.map((i) => i.track), [{ insert: 1 }, 1]);+ assert.deepEqual('inserts' in run && run.inserts.map((i) => i.track), [{ insert: 0 }, 0]);/* with an edit mode they go onto the row anyway: the edit makes room there */const onto = assetRunInsert([clip, still], tracks, { lane: 0, band: 'body' }, 6000, 'overwrite');assert.deepEqual('inserts' in onto && onto.inserts.map((i) => i.track), [0, 0]);diff --git a/packages/openfilm/studio/ui/src/lib/asset-timeline.ts b/packages/openfilm/studio/ui/src/lib/asset-timeline.tsindex 402ec42..1c9ad17 100644--- a/packages/openfilm/studio/ui/src/lib/asset-timeline.ts+++ b/packages/openfilm/studio/ui/src/lib/asset-timeline.ts@@ -6,7 +6,7 @@** There is one landing rule (assetDropSpot) and both the preview and the drop ask it, so a file lands where its* preview was drawn. Its first rule: never stack on a clip on the same track — stacked clips spread into two rows that- * share a badge and look broken. With an edit mode (the timeline's magnet), a file dropped onto a track goes onto it+ * share a badge and look broken. With an edit mode asked for (⌥: an overwrite), a file dropped onto a track goes onto it* whatever is there: an insert pushes it on, an overwrite cuts it out (lib/timeline-edit planRoom), and only the empty* space above or below the tracks opens a new one. Without one, a taken spot opens a new track, shown by a line.*/@@ -36,8 +36,8 @@ export function assetClipKindOf(file: { path: string; kind: string }): AssetClip}/**- * How long a dropped still, or a web page without a duration, stays: four seconds, as in Final Cut (Premiere and- * Resolve use five). The number matters less than having one: neither has a length, a drag cannot ask for one, and+ * How long a dropped still, or a web page without a duration, stays: four seconds. The number matters less than+ * having one: neither has a length, a drag cannot ask for one, and* film.html needs a length for it (`#t=0,4`). A person can pull the edge right after. (An agent writing film.html* gives the fragment itself.)*/@@ -63,7 +63,7 @@ export type StageSize = { w: number; h: number };/*** Where a dropped video or still sits: in its own shape, as large as the canvas holds, centered, so one side meets the- * canvas's edge (as CapCut places it). Without a box it would be the whole canvas with the picture letterboxed inside+ * canvas's edge. Without a box it would be the whole canvas with the picture letterboxed inside* it, and the box a person picks would not be the picture. None when its shape is the canvas's, or not known yet.*/export function assetFitBox(file: { w?: number | undefined; h?: number | undefined }, stage: StageSize | null | undefined): FilmBox | null {@@ -182,8 +182,8 @@ export function assetDropSpot(if (edit || !rangeOverlaps(range, occupiedOf(tracks, target.docIndex ?? null, hit.lane))) {return { action: 'into', laneIndex: hit.lane, lane: target.lane, docIndex: target.docIndex ?? null, locked: false };}- /* the time is taken: no stacking, a new track right under this one (newTrackSide) */- if (target.docIndex != null) return newTrackSpot(tracks, newTrackSide(target.docIndex));+ /* the time is taken: no stacking, a new track beside this one (newTrackSide) */+ if (target.docIndex != null) return newTrackSpot(tracks, newTrackSide(target.docIndex, target.role));/* a row not on film.html cannot open a track: land on it as it is */return { action: 'into', laneIndex: hit.lane, lane: target.lane, docIndex: null, locked: false };}diff --git a/packages/openfilm/studio/ui/src/lib/canvas-fit.test.ts b/packages/openfilm/studio/ui/src/lib/canvas-fit.test.tsindex c3a950e..5ae45e2 100644--- a/packages/openfilm/studio/ui/src/lib/canvas-fit.test.ts+++ b/packages/openfilm/studio/ui/src/lib/canvas-fit.test.ts@@ -12,7 +12,7 @@ test('another shape keeps the canvas short side (1920×1080 made 3:4 is 1080×14assert.deepEqual(canvasFor(wide, '2.35:1'), cinema);});-test('each picture is fitted to the new canvas on its own, as CapCut does: a full-frame video, a portrait photo, a title', () => {+test('each picture is fitted to the new canvas on its own: a full-frame video, a portrait photo, a title', () => {const out = fitToCanvas([{ id: 'v', kind: 'video', own: wide, box: { x: 0, y: 0, w: 1920, h: 1080 } },/* a 3:4 photo on another clip, filling the height in the middle */diff --git a/packages/openfilm/studio/ui/src/lib/canvas-fit.ts b/packages/openfilm/studio/ui/src/lib/canvas-fit.tsindex a457b5b..357dba9 100644--- a/packages/openfilm/studio/ui/src/lib/canvas-fit.ts+++ b/packages/openfilm/studio/ui/src/lib/canvas-fit.ts@@ -1,7 +1,7 @@/**- * A film's canvas changing shape, as CapCut's does: the canvas takes the new shape with its short side kept (a+ * A film's canvas changing shape: the canvas takes the new shape with its short side kept (a* 1920×1080 film made 3:4 is 1080×1440), and each picture is fitted to it on its own. A picture's place is read as- * CapCut keeps it: its size as a share of the size that fits it whole in the canvas (1: it meets the canvas's edges+ * two shares: its size as a share of the size that fits it whole in the canvas (1: it meets the canvas's edges* one way), and its center as a share of the canvas from the canvas's center. Both are kept, so a full-frame video* stays full-frame in any shape, a portrait photo on another clip fits by its own height, a title halfway up stays* halfway up, and shapes picked one after another never shrink anything.@@ -56,9 +56,9 @@ const fitted = (ratio: number, canvas: Size): Size => ();/**- * Each picture clip's box on the new canvas `to` (the old one is `from`), as CapCut fits each clip: the same share of- * its fitted size, its center the same share of the canvas from the canvas's center. Sounds, and videos and stills- * without a box (they are the canvas), are left out.+ * Each picture clip's box on the new canvas `to` (the old one is `from`), each clip fitted on its own: the same+ * share of its fitted size, its center the same share of the canvas from the canvas's center. Sounds, and videos and+ * stills without a box (they are the canvas), are left out.*/export function fitToCanvas(clips: readonly CanvasClip[], from: Size, to: Size): CanvasFit[] {const out: CanvasFit[] = [];diff --git a/packages/openfilm/studio/ui/src/lib/clip-attrs.ts b/packages/openfilm/studio/ui/src/lib/clip-attrs.tsindex f2be441..16018fe 100644--- a/packages/openfilm/studio/ui/src/lib/clip-attrs.ts+++ b/packages/openfilm/studio/ui/src/lib/clip-attrs.ts@@ -1,5 +1,5 @@/**- * A clip's attributes copied onto other clips (CapCut's 复制属性 / 粘贴属性, ⌘⇧C / ⌘⇧V): the groups its paste dialog+ * A clip's attributes copied onto other clips (copy / paste attributes, ⌘⇧C / ⌘⇧V): the groups its paste dialog* offers, all ticked unless unticked —* · `place`: where the picture sits and how big it is, turned (`box`);* · `blend`: how it shows through (`opacity`, `mix-blend-mode` in its style; the rest of its style stays);diff --git a/packages/openfilm/studio/ui/src/lib/clip-look.test.ts b/packages/openfilm/studio/ui/src/lib/clip-look.test.tsindex 85110f7..52c3bb1 100644--- a/packages/openfilm/studio/ui/src/lib/clip-look.test.ts+++ b/packages/openfilm/studio/ui/src/lib/clip-look.test.ts@@ -94,7 +94,7 @@ test('what the controls say is left out of the raw CSS', () => {assert.ok(ownedDeclaration('mask-image', 'linear-gradient(to right, transparent, #000 15%)', none));});-test('a stroke lies inside, across or outside the edge, as Figma\'s: an outline and its offset', () => {+test('a stroke lies inside, across or outside the edge: an outline and its offset', () => {const read = (css: Record<string, string>) => (prop: string) => css[prop];assert.deepEqual(placedStrokeOf(read({ outline: 'rgb(255, 255, 255) solid 4px', 'outline-offset': '-4px' })), { width: 4, style: 'solid', color: 'rgb(255, 255, 255)', position: 'inside' });assert.equal(placedStrokeOf(read({ outline: '#fff solid 4px', 'outline-offset': '-2px' }))?.position, 'center');diff --git a/packages/openfilm/studio/ui/src/lib/clip-look.ts b/packages/openfilm/studio/ui/src/lib/clip-look.tsindex 3686313..57d77de 100644--- a/packages/openfilm/studio/ui/src/lib/clip-look.ts+++ b/packages/openfilm/studio/ui/src/lib/clip-look.ts@@ -321,7 +321,7 @@ export function strokeCss(s: Stroke): string | null {/* ───────────── stroke with a place: outline ───────────── */-/** Where a stroke lies against the edge, as Figma's: inside it, across it, or outside it. */+/** Where a stroke lies against the edge: inside it, across it, or outside it. */export type StrokePosition = 'inside' | 'center' | 'outside';/** A stroke and where it lies; `border`: read from an older `border` (written as an outline once changed). */export type PlacedStroke = Stroke & { position: StrokePosition; border?: true };@@ -329,7 +329,7 @@ export type PlacedStroke = Stroke & { position: StrokePosition; border?: true };export const PLACED_STROKE_DEFAULT: PlacedStroke = { ...STROKE_DEFAULT, position: 'inside' };/**- * A picture's stroke, as Figma draws one: an `outline` (it adds nothing to the box or the layout), its+ * A picture's stroke: an `outline` (it adds nothing to the box or the layout), its* `outline-offset` saying where it lies (−width: inside, −width/2: across the edge, 0: outside). A `border` without an* outline is a stroke written before, inside the box. Undefined: none; null: one the panel cannot read.*/@@ -357,7 +357,7 @@ export function placedStrokeCss(s: PlacedStroke | null, was?: PlacedStroke | nul/* ───────────── inner shadow: an inset box-shadow ───────────── */-/** A shadow cast inside the box, over its fill (Figma's inner shadow). */+/** A shadow cast inside the box, over its fill (an inner shadow). */export type InnerShadow = { x: number; y: number; blur: number; spread: number; color: string };export const INNER_SHADOW_DEFAULT: InnerShadow = { x: 0, y: 4, blur: 12, spread: 0, color: '#00000066' };@@ -387,7 +387,7 @@ export function innerShadowCss(s: InnerShadow | null): string | null {/* ───────────── background blur: backdrop-filter ───────────── */-/** What is behind blurred (Figma's background blur): px; undefined when none, null when it is anything else. */+/** What is behind blurred (a background blur): px; undefined when none, null when it is anything else. */export function backdropBlurOf(v: string | undefined): number | null | undefined {const s = (v ?? '').trim();if (!s || s === 'none') return undefined;diff --git a/packages/openfilm/studio/ui/src/lib/clip-mask.ts b/packages/openfilm/studio/ui/src/lib/clip-mask.tsindex cc0a900..775a519 100644--- a/packages/openfilm/studio/ui/src/lib/clip-mask.ts+++ b/packages/openfilm/studio/ui/src/lib/clip-mask.ts@@ -1,5 +1,5 @@/**- * A mask (CapCut's 蒙版) as plain CSS: `mask-image` layers any browser draws, nothing of our own, no new attribute.+ * A mask as plain CSS: `mask-image` layers any browser draws, nothing of our own, no new attribute.* What the inspector's Mask section and the mask's handles on the picture read and write, for a whole clip (its* `style`) and a layer inside a page (its override's `style`) alike.*@@ -313,7 +313,7 @@ export function maskDefault(shape: MaskShape, box?: MaskBox | null, from?: Maskw: sized ? from!.w : square.w,h: sized ? from!.h : square.h,rotate: from && MASK_FIELDS[from.shape].rotate ? from.rotate : 0,- /* a hard edge until the person feathers it (CapCut's) */+ /* a hard edge until the person feathers it */feather: from && MASK_FIELDS[from.shape].feather ? from.feather : 0,radius: from?.radius ?? 0,invert: from?.invert ?? false,diff --git a/packages/openfilm/studio/ui/src/lib/clip-replace.ts b/packages/openfilm/studio/ui/src/lib/clip-replace.tsindex 0f9fc0f..dc1520a 100644--- a/packages/openfilm/studio/ui/src/lib/clip-replace.ts+++ b/packages/openfilm/studio/ui/src/lib/clip-replace.ts@@ -1,5 +1,5 @@/**- * Replace a clip: another file in its place, as Premiere's replace edit. The clip keeps its id, its place, its length+ * Replace a clip: another file in its place. The clip keeps its id, its place, its length* and its look (box, class, style); the new file plays from its start for that long, at the clip's speed. A file* shorter than that makes the clip shorter (`shortMs` says by how much); a still or a page without an end lasts the* clip's length. A picture is replaced by a picture (a video, a still, a page), a sound by a sound (a sound file, or adiff --git a/packages/openfilm/studio/ui/src/lib/diagnostics.test.ts b/packages/openfilm/studio/ui/src/lib/diagnostics.test.tsnew file mode 100644index 0000000..3ed043b--- /dev/null+++ b/packages/openfilm/studio/ui/src/lib/diagnostics.test.ts@@ -0,0 +1,40 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { browserLines, fullReport, type PageFacts } from './diagnostics.ts';++const chrome: PageFacts = {+ userAgent: 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/141.0.0.0 Safari/537.36',+ chromium: true,+ webgl: 'ANGLE (Apple, ANGLE Metal Renderer: Apple M2, Unspecified Version)',+ framed: false,+ cookies: true,+ storage: true,+ screen: '1512×982, window 1512×900 @2x',+};++test('a Chromium browser with WebGL and storage has nothing to fix', () => {+ const lines = browserLines(chrome);+ assert.ok(lines.some((l) => l.startsWith('✓ Engine') && l.includes('Chromium')));+ assert.ok(!lines.some((l) => l.startsWith('✗')));+ assert.ok(!lines.includes('To fix:'));+});++test('an agent\'s preview pane: another engine, no WebGL, blocked storage, each with what to do', () => {+ const lines = browserLines({ ...chrome, chromium: false, webgl: null, framed: true, storage: false });+ assert.ok(lines.some((l) => l.startsWith('✗ Engine')));+ assert.ok(lines.some((l) => l.startsWith('✗ WebGL') && l.includes('unavailable')));+ assert.ok(lines.some((l) => l.startsWith('✗ Storage') && l.includes('site data blocked, inside another page')));+ const fixes = lines.slice(lines.indexOf('To fix:') + 1);+ assert.equal(fixes.length, 3);+ assert.match(fixes[0], /Chrome, Edge or the desktop app/);+});++test('the whole report: the computer\'s, the browser\'s, then the app\'s when there is one', () => {+ const text = fullReport('OpenFilm doctor\n\n✓ Node v22', chrome, 'OpenFilm desktop 0.1.8');+ const parts = text.split('\n\n────────\n\n');+ assert.equal(parts.length, 3);+ assert.match(parts[0], /^OpenFilm doctor/);+ assert.match(parts[1], /^Browser Studio is open in/);+ assert.equal(parts[2], 'OpenFilm desktop 0.1.8');+ assert.equal(fullReport('x', chrome, null).split('────────').length, 2);+});diff --git a/packages/openfilm/studio/ui/src/lib/diagnostics.ts b/packages/openfilm/studio/ui/src/lib/diagnostics.tsnew file mode 100644index 0000000..5053ea1--- /dev/null+++ b/packages/openfilm/studio/ui/src/lib/diagnostics.ts@@ -0,0 +1,68 @@+/**+ * The diagnostic report Settings → Developer copies: `openfilm doctor` as Studio's server runs it (src/doctor.mjs), what+ * the browser Studio is open in can do (an agent's built-in browser can lack what Studio needs), and in the desktop+ * app, its agents (lib/host.ts `diagnostics`).+ */+import { chromiumBased } from './browser.ts';++export interface PageFacts {+ userAgent: string;+ chromium: boolean;+ /** what draws WebGL here; null without WebGL */+ webgl: string | null;+ /** inside another page's frame (a preview pane), where cookies and storage can be blocked */+ framed: boolean;+ cookies: boolean;+ storage: boolean;+ /** the screen and window, in CSS px, and the pixel ratio */+ screen: string;+}++/** What the page Studio is in can do, read now. */+export function pageFacts(): PageFacts {+ let webgl: string | null = null;+ try {+ const gl = document.createElement('canvas').getContext('webgl');+ if (gl) {+ const info = gl.getExtension('WEBGL_debug_renderer_info');+ webgl = String(gl.getParameter(info ? info.UNMASKED_RENDERER_WEBGL : gl.RENDERER));+ }+ } catch { /* none */ }+ let storage = false;+ try { localStorage.setItem('openfilm-doctor', '1'); localStorage.removeItem('openfilm-doctor'); storage = true; } catch { /* blocked */ }+ let framed = false;+ try { framed = window.top !== window; } catch { framed = true; }+ return {+ userAgent: navigator.userAgent,+ chromium: chromiumBased(),+ webgl,+ framed,+ cookies: navigator.cookieEnabled,+ storage,+ screen: `${screen.width}×${screen.height}, window ${window.innerWidth}×${window.innerHeight} @${window.devicePixelRatio}x`,+ };+}++/** The browser's lines of the report, each with ✓ or ✗ as the doctor's, and what to do about a ✗. */+export function browserLines(f: PageFacts): string[] {+ const line = (ok: boolean, label: string, text: string) => `${ok ? '✓' : '✗'} ${label.padEnd(10)}${text}`;+ const fixes: string[] = [];+ if (!f.chromium) fixes.push('Browser: open Studio in Chrome, Edge or the desktop app; previews can fail in other browsers');+ if (!f.webgl) fixes.push('WebGL: turn on hardware acceleration in the browser');+ if (!f.cookies || !f.storage) fixes.push('Storage: allow cookies and site data for 127.0.0.1, or open Studio in its own tab');+ return [+ 'Browser Studio is open in',+ '',+ line(f.chromium, 'Engine', f.chromium ? 'Chromium' : 'not Chromium'),+ line(true, 'UA', f.userAgent),+ line(Boolean(f.webgl), 'WebGL', f.webgl ?? 'unavailable'),+ line(f.cookies && f.storage, 'Storage', `cookies ${f.cookies ? 'on' : 'off'}, site data ${f.storage ? 'on' : 'blocked'}${f.framed ? ', inside another page' : ''}`),+ line(true, 'Screen', f.screen),+ ...(fixes.length ? ['', 'To fix:', ...fixes.map((fix) => ` ${fix}`)] : []),+ ];+}++/** The whole report: the computer's, the browser's, and the desktop app's when there is one. */+export function fullReport(computer: string, page: PageFacts, app?: string | null): string {+ return [computer, browserLines(page).join('\n'), ...(app ? [app] : [])].join('\n\n────────\n\n');+}diff --git a/packages/openfilm/studio/ui/src/lib/export-spec.test.ts b/packages/openfilm/studio/ui/src/lib/export-spec.test.tsindex 619f4d1..4204745 100644--- a/packages/openfilm/studio/ui/src/lib/export-spec.test.ts+++ b/packages/openfilm/studio/ui/src/lib/export-spec.test.ts@@ -1,6 +1,6 @@import { test } from 'node:test';import assert from 'node:assert/strict';-import { exportEstimateBytes, exportFilmPixels, exportFramedDims, exportGifDims, exportGifEstimateBytes, exportPresetsFor, rangeMarks } from './export-spec.ts';+import { exportEstimateBytes, exportFilmPixels, exportFramedDims, exportGifDims, exportGifEstimateBytes, exportPreset, exportPresetsFor, presetFps, rangeMarks } from './export-spec.ts';import { filmFrameBox } from './film-frame.ts';const stage = { w: 1920, h: 1080 };@@ -78,3 +78,13 @@ test('platforms: China\'s first in Chinese, none of them in any other language',const xhs = exportPresetsFor('zh-CN').find((p) => p.id === 'xiaohongshu');assert.deepEqual(exportFramedDims({ w: 1920, h: 1080 }, xhs.frame, 'contain', xhs.shortEdge), { w: 1080, h: 1440 });});++test('a platform gets the film\'s own frames a second, up to the most it shows', () => {+ const bilibili = exportPreset('bilibili')!;+ const douyin = exportPreset('douyin')!;+ assert.equal(presetFps(bilibili, 30), 30, 'a 30 fps film is not drawn at 60');+ assert.equal(presetFps(bilibili, 60), 60);+ assert.equal(presetFps(bilibili, 23.976), 23.976);+ assert.equal(presetFps(douyin, 60), 30, 'up to what the platform shows');+ assert.equal(presetFps(douyin, 0), 30, 'no rate known: the platform\'s');+});diff --git a/packages/openfilm/studio/ui/src/lib/export-spec.ts b/packages/openfilm/studio/ui/src/lib/export-spec.tsindex 011ccd1..88000f7 100644--- a/packages/openfilm/studio/ui/src/lib/export-spec.ts+++ b/packages/openfilm/studio/ui/src/lib/export-spec.ts@@ -40,6 +40,7 @@ export interface ExportPreset {group: ExportPresetGroup;frame: Exclude<FilmFrameId, 'native'>;shortEdge: number;+ /** The most frames a second the platform shows: a film is exported at its own rate up to it (presetFps). */fps: number;/** Vertical feeds are mostly watched muted: subtitles burned in by default. */burnSubtitles: boolean;@@ -70,6 +71,14 @@ export function exportPresetsFor(language: string): readonly ExportPreset[] {return language === 'zh-CN' ? [...EXPORT_PRESETS.filter((p) => p.china), ...EXPORT_PRESETS.filter((p) => !p.china)] : EXPORT_PRESETS.filter((p) => !p.china);}+/**+ * A film's frames a second on a platform: its own, up to the most the platform shows. A 30 fps film is not drawn+ * twice over for a platform that shows 60: no frame of it would be new.+ */+export function presetFps(preset: ExportPreset, filmFps: number): number {+ return filmFps > 0 ? Math.min(preset.fps, filmFps) : preset.fps;+}+export function exportPreset(id: string | undefined): ExportPreset | null {return EXPORT_PRESETS.find((p) => p.id === id) ?? null;}diff --git a/packages/openfilm/studio/ui/src/lib/field-input.ts b/packages/openfilm/studio/ui/src/lib/field-input.tsindex 3092a8b..808e351 100644--- a/packages/openfilm/studio/ui/src/lib/field-input.ts+++ b/packages/openfilm/studio/ui/src/lib/field-input.ts@@ -1,5 +1,5 @@/**- * What a person types into a number field of the inspector, read as Figma and the editors read it: arithmetic+ * What a person types into a number field of the inspector, and how it is read: arithmetic* (`1440/2`), a change of the value there (`+20`, `-20`, `*2`, `/2`), and units — `px` is dropped, `50%` is half of* what the field measures against (the stage, for a place or a size), and a time takes seconds (`2.5s`), frames* (`12f`, at the timecode's rate), milliseconds and timecodes (`00:00:02:15`, read as the timecode shows them).diff --git a/packages/openfilm/studio/ui/src/lib/film.ts b/packages/openfilm/studio/ui/src/lib/film.tsindex 8d18b71..fe9edc4 100644--- a/packages/openfilm/studio/ui/src/lib/film.ts+++ b/packages/openfilm/studio/ui/src/lib/film.ts@@ -43,10 +43,9 @@ export function filmTrackPrefix(kind: string): string {}/**- * Each track's name on the timeline (P1, V2, A1), worked out from position and kind, never stored, as Premiere and- * Resolve name theirs: picture tracks (P, V) counted from the bottom up, so V1 is the lowest and V2 covers it, and- * sound tracks (A) from the top down. Each prefix on its own. It names a track a person can point at; stacking is- * the position itself.+ * Each track's name on the timeline (P1, V2, A1), worked out from position and kind, never stored: picture tracks+ * (P, V) counted from the bottom up, so V1 is the lowest and V2 covers it, and sound tracks (A) from the top down.+ * Each prefix on its own. It names a track a person can point at; stacking is the position itself.*/export function filmTrackBadges(tracks: readonly ({ kind: string } | { clips: readonly { src: string }[] })[]): string[] {return rowBadges(tracks.map((track) => 'kind' in track ? track.kind : filmTrackKind(track)));diff --git a/packages/openfilm/studio/ui/src/lib/font-menu.ts b/packages/openfilm/studio/ui/src/lib/font-menu.tsindex cd474fd..cf1a37c 100644--- a/packages/openfilm/studio/ui/src/lib/font-menu.ts+++ b/packages/openfilm/studio/ui/src/lib/font-menu.ts@@ -1,5 +1,5 @@/**- * The font menu's rows, as Figma lays them out: "In this project" first — the families the project's pages declare+ * The font menu's rows: "In this project" first — the families the project's pages declare* with @font-face and the ones the current page names — then "Recent", then every font installed here, by script* (the CJK ones first for CJK text). Typing filters every section by name and alias, best matches first.*diff --git a/packages/openfilm/studio/ui/src/lib/font-styles.ts b/packages/openfilm/studio/ui/src/lib/font-styles.tsindex 5a19248..79453ae 100644--- a/packages/openfilm/studio/ui/src/lib/font-styles.ts+++ b/packages/openfilm/studio/ui/src/lib/font-styles.ts@@ -1,5 +1,5 @@/**- * A family's weights and italics, as the inspector's weight menu offers them (Figma's: "Light", "Bold Italic"), and+ * A family's weights and italics, as the inspector's weight menu offers them ("Light", "Bold Italic"), and* a CSS `font-family` stack's first family, as the font field shows and changes it.** What a family has comes from its faces: an installed font's OS/2 weight classes and italic bits (GET /api/fonts),@@ -102,7 +102,7 @@ export function snapStyle(styles: FontStyles, want: FontStyle): FontStyle {/* ── a font-family stack ── *//**- * The font field shows the first family only (as Figma does); the fallbacks after it stay as written — changing the+ * The font field shows the first family only; the fallbacks after it stay as written — changing the* main font must not replace `Inter, "PingFang SC", sans-serif` with one name.*/export function splitFontFamily(stack: string): [string, string] {diff --git a/packages/openfilm/studio/ui/src/lib/freeze-frame.test.ts b/packages/openfilm/studio/ui/src/lib/freeze-frame.test.tsindex bd8b3a2..ffad364 100644--- a/packages/openfilm/studio/ui/src/lib/freeze-frame.test.ts+++ b/packages/openfilm/studio/ui/src/lib/freeze-frame.test.ts@@ -23,9 +23,9 @@ test('the playhead\'s moment of the clip\'s file: its in point plus the time intassert.equal(freezeSourceMs({ startMs: 10_000, endMs: 14_000 }, 14_000), null);});-test('with the magnet the video is cut at the playhead, the still goes in, and the rest moves on 3 s', () => {+test('an insert cuts the video at the playhead, the still goes in, and the rest moves on 3 s', () => {const m = model();- const ops = planFreeze(m, { clip: shot as never, track: 0, atMs: 3000, still: 'assets/shot-frame-3s.png', mode: 'insert', sync: true })!;+ const ops = planFreeze(m, { clip: shot as never, track: 0, atMs: 3000, still: 'assets/shot-frame-3s.png', mode: 'insert' })!;const [picture, sound] = run(m, ops);assert.deepEqual(picture, ['shot.mp4@0#0,3.graded', 'assets/shot-frame-3s.png@3#0,3.graded', 'shot.mp4@6#3,6.graded', 'next.mp4@9#0,2']);/* a sound already playing at the playhead is not cut (as any insert there, see planRoom) */@@ -34,12 +34,12 @@ test('with the magnet the video is cut at the playhead, the still goes in, and ttest('without it the still covers 3 s of the video after the playhead; nothing else moves', () => {const m = model();- const ops = planFreeze(m, { clip: shot as never, track: 0, atMs: 3000, still: 'f.png', mode: 'overwrite', sync: true })!;+ const ops = planFreeze(m, { clip: shot as never, track: 0, atMs: 3000, still: 'f.png', mode: 'overwrite' })!;const [picture, sound] = run(m, ops);assert.deepEqual(picture, ['shot.mp4@0#0,3.graded', 'f.png@3#0,3.graded', 'next.mp4@6#0,2']);assert.deepEqual(sound, ['vo.mp3@1#0,8']);});test('a locked track takes no freeze frame', () => {- assert.equal(planFreeze(model(true), { clip: shot as never, track: 0, atMs: 3000, still: 'f.png', mode: 'insert', sync: true }), null);+ assert.equal(planFreeze(model(true), { clip: shot as never, track: 0, atMs: 3000, still: 'f.png', mode: 'insert' }), null);});diff --git a/packages/openfilm/studio/ui/src/lib/freeze-frame.ts b/packages/openfilm/studio/ui/src/lib/freeze-frame.tsindex 0833c18..80526af 100644--- a/packages/openfilm/studio/ui/src/lib/freeze-frame.ts+++ b/packages/openfilm/studio/ui/src/lib/freeze-frame.ts@@ -1,15 +1,15 @@/*** Freeze frame: the frame of a video clip under the playhead, made a still (studio/server/files.mjs freezeFrame) and- * put in at the playhead on the clip's track, in the timeline's edit mode: with the magnet the video is cut there and- * what follows moves on by the still's length (with sync lock, on every unlocked track); without it the still covers- * that much of the video after the playhead. The still looks as the video does (its box, class and style).+ * put in at the playhead on the clip's track: an insert cuts the video there and what follows on that track moves on+ * by the still's length (with linkage, what rides on the main track along); an overwrite has the still+ * cover that much of the video after the playhead. The still looks as the video does (its box, class and style).*/import type { Clip, Op } from '../api.ts';-import { planRoom, type EditMode, type EditModel } from './timeline-edit.ts';+import { planRoom, type EditMode, type EditModel, type Switches } from './timeline-edit.ts';import { snapToFrame } from './timecode.ts';import type { TimelineBlock } from './timeline-layout';-/** How long a freeze frame lasts: 3 s, as CapCut's. */+/** How long a freeze frame lasts: 3 s. */export const FREEZE_MS = 3000;/** The moment of the clip's file the playhead is on (ms), or null when the playhead is not on the clip. */@@ -18,7 +18,7 @@ export function freezeSourceMs(block: Pick<TimelineBlock, 'startMs' | 'endMs' |return Math.round((block.inMs ?? 0) + (atMs - block.startMs) * (block.speed ?? 1));}-export interface FreezeSpec {+export interface FreezeSpec extends Partial<Switches> {/** The video clip, as film.html has it. */clip: Clip;/** Its track (film.html index). */@@ -28,8 +28,6 @@ export interface FreezeSpec {/** The still made of its frame (a project path). */still: string;mode: EditMode;- sync: boolean;- linkage?: boolean;durMs?: number;}@@ -46,6 +44,6 @@ export function planFreeze(model: EditModel, spec: FreezeSpec): Op[] | null {...(cls ? { class: cls } : {}),...(style ? { style } : {}),};- const room = planRoom(model, [{ track: spec.track, startMs, endMs: startMs + durMs }], { mode: spec.mode, sync: spec.sync, linkage: spec.linkage });+ const room = planRoom(model, [{ track: spec.track, startMs, endMs: startMs + durMs }], { mode: spec.mode, magnet: spec.magnet, linkage: spec.linkage });return [{ op: 'insert', clip: still, at: Math.round(startMs) / 1000, track: spec.track }, ...room.ops];}diff --git a/packages/openfilm/studio/ui/src/lib/host.ts b/packages/openfilm/studio/ui/src/lib/host.tsindex 6245c2f..e739ff1 100644--- a/packages/openfilm/studio/ui/src/lib/host.ts+++ b/packages/openfilm/studio/ui/src/lib/host.ts@@ -92,6 +92,8 @@ export interface StudioHost {locate?: (id: HostAgentId, words?: { title?: string; button?: string }) => Promise<{ ok: boolean; error?: string; code?: 'not-a-program' | 'did-not-start' | string }>;useAutomatic?: (id: HostAgentId) => Promise<unknown>;diagnose?: (id: HostAgentId) => Promise<HostAgentDiagnosis | null>;+ /** The app's part of Settings → Developer's diagnostic report: the app, and each agent's program, version and state, as text. */+ report?: () => Promise<string>;/*** One of the person's own models set up (no `id`) or changed: checked before it is kept. A key left empty keeps its* own, or takes the one of another model on the same address.@@ -144,7 +146,8 @@ export interface StudioHost {* its top bar (where the projects button and the title are otherwise), with a `+` that opens the projects window to* pick the project a new tab shows (`open`; one open already is shown). With no tab open the page is at `/`, and* Studio shows the projects there. `list` gives the tabs and which is this page's (`self`); `onChange` every change.- * A page `report`s what it shows (its title, an export's progress, its project gone: its tab closes). Studio's+ * A page `report`s what it shows (its title, an export's progress, its project gone: its tab closes), and `retitle`s+ * another tab whose project it renamed. Studio's* "open this project" (heard by every page) goes to `openRequest`, which the app settles once; `onPick` is the app* asking for the projects window (a new tab from its menu).*/@@ -157,6 +160,8 @@ export interface StudioHost {open: (projectId: string) => void;move: (id: string, index: number) => void;report: (state: { title?: string; exporting?: number | null; gone?: boolean }) => void;+ /** another tab's title, its project renamed from this page's tabs (its page may be gone, and cannot say it) */+ retitle?: (id: string, title: string) => Promise<unknown>;openRequest: (to: string) => void;onPick: (listener: () => void) => () => void;};diff --git a/packages/openfilm/studio/ui/src/lib/inspect-scrub.ts b/packages/openfilm/studio/ui/src/lib/inspect-scrub.tsindex 8e6bf3f..8e79e21 100644--- a/packages/openfilm/studio/ui/src/lib/inspect-scrub.ts+++ b/packages/openfilm/studio/ui/src/lib/inspect-scrub.ts@@ -1,7 +1,7 @@/*** Dragging a number in the inspector: how many steps a horizontal drag of so many pixels is worth.*- * The step is the field's own; as in Figma, Shift is ten times coarser and Alt ten times finer — the same rule as+ * The step is the field's own; Shift is ten times coarser and Alt ten times finer — the same rule as* the arrow keys (Shift is ten steps).*/diff --git a/packages/openfilm/studio/ui/src/lib/media-place.test.ts b/packages/openfilm/studio/ui/src/lib/media-place.test.tsindex d92b93e..a8721d1 100644--- a/packages/openfilm/studio/ui/src/lib/media-place.test.ts+++ b/packages/openfilm/studio/ui/src/lib/media-place.test.ts@@ -20,42 +20,42 @@ const run = (m: EditTrack[], ops: Op[]) => (applyOps(filmOf(m) as never, ops asconst video = { path: 'assets/shot.mp4', kind: 'video' as const, durationMs: 3000 };const sound = { path: 'assets/music/bed.mp3', kind: 'audio' as const, durationMs: 5000 };-test('with no track targeted, a picture goes at the end of the main track (V1), a sound at the end of a sound track', () => {+test('with no track targeted, a picture goes at the end of the bottom picture track (V1), a sound at the end of a sound track', () => {const m = model();- const plan = placeMedia(m, { file: video, target: null, at: 'end', mode: 'insert', sync: true });+ const plan = placeMedia(m, { file: video, target: null, at: 'end', mode: 'insert' });assert.ok(!('error' in plan));assert.deepEqual(run(m, plan.ops)[1], ['v1.mp4@0#0,4', 'v2.mp4@4#0,4', 'assets/shot.mp4@8']);- const heard = placeMedia(m, { file: sound, target: null, at: 'end', mode: 'insert', sync: true });+ const heard = placeMedia(m, { file: sound, target: null, at: 'end', mode: 'insert' });assert.ok(!('error' in heard));assert.deepEqual(run(m, heard.ops)[2], ['vo.mp3@0#0,3', 'assets/music/bed.mp3@3']);});test('at the playhead on the targeted track: an insert pushes what follows, an overwrite covers it', () => {const m = model();- const ins = placeMedia(m, { file: video, range: { inMs: 1000, outMs: 2000 }, target: 1, at: 2000, mode: 'insert', sync: false });+ const ins = placeMedia(m, { file: video, range: { inMs: 1000, outMs: 2000 }, target: 1, at: 2000, mode: 'insert' });assert.ok(!('error' in ins));assert.deepEqual(run(m, ins.ops)[1], ['v1.mp4@0#0,2', 'assets/shot.mp4@2#1,2', 'v1.mp4@3#2,4', 'v2.mp4@5#0,4']);- const over = placeMedia(m, { file: video, range: { inMs: 1000, outMs: 2000 }, target: 1, at: 2000, mode: 'overwrite', sync: false });+ const over = placeMedia(m, { file: video, range: { inMs: 1000, outMs: 2000 }, target: 1, at: 2000, mode: 'overwrite' });assert.ok(!('error' in over));assert.deepEqual(run(m, over.ops)[1], ['v1.mp4@0#0,2', 'assets/shot.mp4@2#1,2', 'v1.mp4@3#3,4', 'v2.mp4@4#0,4']);});test('a sound aimed at a picture track goes to a sound track with room; a locked target refuses', () => {const m = model();- const plan = placeMedia(m, { file: sound, target: 1, at: 1000, mode: 'insert', sync: true });+ const plan = placeMedia(m, { file: sound, target: 1, at: 1000, mode: 'insert' });assert.ok(!('error' in plan));/* the voice-over's track is taken at 1 s: a new sound track under it, nothing pushed */assert.deepEqual(plan.track, { insert: 3 });const locked = model();locked[1]!.locked = true;- assert.deepEqual(placeMedia(locked, { file: video, target: 1, at: 0, mode: 'insert', sync: true }), { error: 'locked' });- assert.deepEqual(placeMedia(locked, { file: video, target: null, at: 'end', mode: 'insert', sync: true }), { error: 'locked' }, 'the main track is locked');- assert.deepEqual(placeMedia(m, { file: { path: 'notes.pdf', kind: 'other' as never }, target: null, at: 0, mode: 'insert', sync: true }), { error: 'not-clip' });+ assert.deepEqual(placeMedia(locked, { file: video, target: 1, at: 0, mode: 'insert' }), { error: 'locked' });+ assert.deepEqual(placeMedia(locked, { file: video, target: null, at: 'end', mode: 'insert' }), { error: 'locked' }, 'the bottom picture track is locked');+ assert.deepEqual(placeMedia(m, { file: { path: 'notes.pdf', kind: 'other' as never }, target: null, at: 0, mode: 'insert' }), { error: 'not-clip' });});test('a still keeps its own length; a film with no picture track gets one', () => {const m: EditTrack[] = [{ index: 0, role: 'audio', clips: [clip('vo', 0, 3)] }];- const plan = placeMedia(m, { file: { path: 'assets/p.png', kind: 'image' }, range: { inMs: 0, outMs: 900 }, target: null, at: 1000, mode: 'overwrite', sync: true });+ const plan = placeMedia(m, { file: { path: 'assets/p.png', kind: 'image' }, range: { inMs: 0, outMs: 900 }, target: null, at: 1000, mode: 'overwrite' });assert.ok(!('error' in plan));assert.deepEqual(plan.track, { insert: 0 });assert.deepEqual(run(m, plan.ops)[0], ['assets/p.png@1#0,4']);diff --git a/packages/openfilm/studio/ui/src/lib/media-place.ts b/packages/openfilm/studio/ui/src/lib/media-place.tsindex 5e9aee7..4e88f30 100644--- a/packages/openfilm/studio/ui/src/lib/media-place.ts+++ b/packages/openfilm/studio/ui/src/lib/media-place.ts@@ -1,16 +1,19 @@/**- * A file from the media pane put on the timeline without dragging it: its "+" button and Enter (in the timeline's edit- * mode), and `,` / `.` from the source viewer (insert / overwrite, as Premiere's keys). The part of the file marked in- * the source viewer (I and O there), else all of it, as one clip — a video carries its own sound.+ * A file from the media pane put on the timeline without dragging it: its "+" button and Enter, and `,` / `.` from the+ * source viewer (insert / overwrite). The part of the file marked in the source viewer (I and O+ * there), else all of it, as one clip — a video carries its own sound.** Where it goes: at the playhead on the targeted track (the track last clicked on the timeline), or without one at- * the end of the main track: the bottom picture track (V1) for a picture, a sound track for a sound (the first with- * room, else a new one under the others).+ * the end of the main track (V1) for a picture, of a sound track for a sound (the first with room, else a new one+ * under the others). How, without `,` / `.`: on the main track with the magnet it goes in between at the playhead (as a+ * clip dragged there does); anywhere else it is put down, never cutting what is there — a taken spot opens a track+ * beside it.*/import type { Op } from '../api.ts';import { assetClipElement, assetClipKindOf, dropDurMsOf, type StageSize } from './asset-timeline.ts';import type { ResourceDragItem } from './resource-drag';-import { magnetOn, planRoom, soundTrackFor, TOUCH_MS, type EditMode, type EditModel, type TrackDest } from './timeline-edit.ts';+import { newTrackSide } from './timeline-drag.ts';+import { insertPointOn, magnetOn, planRoom, soundTrackFor, TOUCH_MS, type EditMode, type EditModel, type Switches, type TrackDest } from './timeline-edit.ts';import { snapToFrame } from './timecode.ts';export type PlaceFile = Pick<ResourceDragItem, 'path' | 'kind' | 'durationMs' | 'endless' | 'reflows' | 'w' | 'h'>;@@ -18,18 +21,15 @@ export type PlaceFile = Pick<ResourceDragItem, 'path' | 'kind' | 'durationMs' |/** A part of the file, in its own ms (the source viewer's in and out). */export type SourceRange = { inMs: number; outMs: number };-export interface PlaceSpec {+export interface PlaceSpec extends Partial<Switches> {file: PlaceFile;range?: SourceRange | null;- /** The targeted track (film.html index), or null for the main one. */+ /** The targeted track (film.html index), or null for the lowest picture track. */target: number | null;/** Where: the playhead (ms), or `end`, after the last clip of the track it goes on. */at: number | 'end';- /** Insert or overwrite; not given, the magnet decides: an insert on the main track when it is on. */+ /** Insert or overwrite, asked for (the source viewer's keys); not given, as the timeline's switches say. */mode?: EditMode;- magnet?: boolean;- sync: boolean;- linkage?: boolean;/** The canvas: a picture of another shape gets a box in its own (asset-timeline assetFitBox). */stage?: StageSize | null;}@@ -77,16 +77,26 @@ export function placeMedia(model: EditModel, spec: PlaceSpec): PlacePlan {} else {/* the main track: the lowest picture track (V1), film.html's last picture track */const pictures = model.filter((t) => !isSoundTrack(t.role));- const main = pictures.at(-1);- if (main?.locked) return { error: 'locked' };- track = main ? main.index : { insert: 0 };+ const lowest = pictures.at(-1);+ if (lowest?.locked) return { error: 'locked' };+ track = lowest ? lowest.index : { insert: 0 };+ }+ let startMs = spec.at === 'end' ? (typeof track === 'number' ? endOf(track) : 0) : Math.max(0, snapToFrame(spec.at));+ if (typeof track !== 'number') return { ops: [{ op: 'insert', clip: made.element as never, at: Math.round(startMs) / 1000, track }], track, startMs, durMs: made.durMs };+ const switches = { magnet: Boolean(spec.magnet), linkage: Boolean(spec.linkage) };+ /* on the main track with the magnet: in between, where the playhead is (before or after the clip under it) */+ const mode: EditMode | 'place' = spec.mode ?? (magnetOn(model, track, switches.magnet) ? 'insert' : 'place');+ if (!spec.mode && mode === 'insert') startMs = insertPointOn(model, track, startMs, startMs);+ const clips = model.find((t) => t.index === track)?.clips ?? [];+ if (mode === 'place' && clips.some((c) => c.startMs < startMs + made.durMs - TOUCH_MS && c.endMs > startMs + TOUCH_MS)) {+ /* the time is taken: a new track beside, nothing cut */+ const role = model.find((t) => t.index === track)?.role;+ const beside: TrackDest = { insert: newTrackSide(track, role) };+ return { ops: [{ op: 'insert', clip: made.element as never, at: Math.round(startMs) / 1000, track: beside }], track: beside, startMs, durMs: made.durMs };}- const startMs = spec.at === 'end' ? (typeof track === 'number' ? endOf(track) : 0) : Math.max(0, snapToFrame(spec.at));const insert: Op = { op: 'insert', clip: made.element as never, at: Math.round(startMs) / 1000, track };- if (typeof track !== 'number') return { ops: [insert], track, startMs, durMs: made.durMs };/* at the very end nothing follows: no room to make */- const after = (model.find((t) => t.index === track)?.clips ?? []).some((c) => c.endMs > startMs + TOUCH_MS);- const mode = spec.mode ?? (magnetOn(model, track, spec.magnet ?? false) ? 'insert' : 'overwrite');- const room = after && !roomy ? planRoom(model, [{ track, startMs, endMs: startMs + made.durMs }], { mode, sync: spec.sync, linkage: spec.linkage }).ops : [];+ const after = clips.some((c) => c.endMs > startMs + TOUCH_MS);+ const room = after && !roomy && mode !== 'place' ? planRoom(model, [{ track, startMs, endMs: startMs + made.durMs }], { mode, ...switches }).ops : [];return { ops: [insert, ...room], track, startMs, durMs: made.durMs };}diff --git a/packages/openfilm/studio/ui/src/lib/mg-transform.ts b/packages/openfilm/studio/ui/src/lib/mg-transform.tsindex 4737e7c..c406d6a 100644--- a/packages/openfilm/studio/ui/src/lib/mg-transform.ts+++ b/packages/openfilm/studio/ui/src/lib/mg-transform.ts@@ -37,7 +37,7 @@ export interface MgGuide {at: number;}-/** The three places on an axis worth lining up: both edges and the middle (as in Figma). */+/** The three places on an axis worth lining up: both edges and the middle. */function anchorsOf(start: number, size: number): [number, number, number] {return [start, start + size / 2, start + size];}diff --git a/packages/openfilm/studio/ui/src/lib/preview-prefs.ts b/packages/openfilm/studio/ui/src/lib/preview-prefs.tsnew file mode 100644index 0000000..7711538--- /dev/null+++ b/packages/openfilm/studio/ui/src/lib/preview-prefs.ts@@ -0,0 +1,46 @@+/**+ * The preview's switches, kept on this machine across projects:+ * · `fitPages` (on by default): pages draw their canvas and 3D at the size the viewer shows them (their+ * devicePixelRatio is the viewer's, see editor/Preview), not at the film's full size scaled down: the same picture+ * in the viewer, for a fraction of the drawing. Exports always draw at full size.+ * · `renders` (on by default): a stretch that plays late is rendered in the background once the film stops, and+ * played from that render from then on (studio/server/preview-cache.mjs, editor/use-preview-renders).+ * · `stats` (off by default, Settings → Developer): the viewer's corner says how playing goes.+ */+import { useSyncExternalStore } from 'react';++export type PreviewPrefs = { fitPages: boolean; renders: boolean; stats: boolean };+type Pref = keyof PreviewPrefs;++const DEFAULTS: PreviewPrefs = { fitPages: true, renders: true, stats: false };+const KEY: Record<Pref, string> = { fitPages: 'openfilm.preview.fitPages', renders: 'openfilm.preview.renders', stats: 'openfilm.preview.stats' };++/** Without localStorage (private window), the choices last this session. */+const memory: Partial<PreviewPrefs> = {};+const listeners = new Set<() => void>();+let current: PreviewPrefs | null = null;++function read(pref: Pref): boolean {+ try {+ const raw = localStorage.getItem(KEY[pref]);+ if (raw != null) return raw !== '0';+ } catch { /* no localStorage: this session's choice */ }+ return memory[pref] ?? DEFAULTS[pref];+}++export function readPreviewPrefs(): PreviewPrefs {+ current ??= { fitPages: read('fitPages'), renders: read('renders'), stats: read('stats') };+ return current;+}++export function writePreviewPref(pref: Pref, on: boolean): void {+ memory[pref] = on;+ try { localStorage.setItem(KEY[pref], on ? '1' : '0'); } catch { /* not stored: `memory` has it */ }+ current = { ...readPreviewPrefs(), [pref]: on };+ for (const fn of listeners) fn();+}++/** The switches, kept up to date wherever one is changed. */+export function usePreviewPrefs(): PreviewPrefs {+ return useSyncExternalStore((fn) => { listeners.add(fn); return () => { listeners.delete(fn); }; }, readPreviewPrefs, () => DEFAULTS);+}diff --git a/packages/openfilm/studio/ui/src/lib/preview-renders.test.ts b/packages/openfilm/studio/ui/src/lib/preview-renders.test.tsnew file mode 100644index 0000000..2b45f4a--- /dev/null+++ b/packages/openfilm/studio/ui/src/lib/preview-renders.test.ts@@ -0,0 +1,29 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { addHeat, joinStretches, lateStretches, sameStretches, type Heat } from './preview-renders.ts';++test('a stretch is late where many refreshes got no new frame; joined across a short gap, padded, a second at least', () => {+ const heat: Heat = new Map();+ /* 10–11.5 s late on a third of its refreshes; 12–12.5 too; 3 s fine; 20 s late but only glimpsed */+ addHeat(heat, [[10, 60, 20], [10.5, 60, 20], [11, 60, 20], [12, 60, 30], [3, 60, 1], [20, 5, 5]]);+ assert.deepEqual(lateStretches(heat), [[9.75, 12.75]]);+ /* one late half second alone: a second around it */+ const one: Heat = new Map();+ addHeat(one, [[4, 60, 30]]);+ assert.deepEqual(lateStretches(one), [[3.75, 4.75]]);+ assert.deepEqual(lateStretches(new Map([[0, { frames: 60, late: 40 }]])), [[0, 1]], 'never before the film');+});++test('what a half second does now outweighs what it did: played smoothly again, it is no longer late', () => {+ const heat: Heat = new Map();+ addHeat(heat, [[5, 60, 40]]);+ assert.equal(lateStretches(heat).length, 1);+ for (let i = 0; i < 6; i++) addHeat(heat, [[5, 60, 0]]);+ assert.deepEqual(lateStretches(heat), []);+ assert.ok(sameStretches([[1, 2]], [[1, 2]]) && !sameStretches([[1, 2]], [[1, 3]]));+});++test('stretches known late before and found late now are one list, overlapping ones joined', () => {+ assert.deepEqual(joinStretches([[5, 6], [1, 2], [1.5, 3], [3, 4]]), [[1, 4], [5, 6]]);+ assert.deepEqual(joinStretches([]), []);+});diff --git a/packages/openfilm/studio/ui/src/lib/preview-renders.ts b/packages/openfilm/studio/ui/src/lib/preview-renders.tsnew file mode 100644index 0000000..46613f7--- /dev/null+++ b/packages/openfilm/studio/ui/src/lib/preview-renders.ts@@ -0,0 +1,71 @@+/**+ * Which stretches of a film play late in the preview, from how playing went (editor/Preview's `onPlayed`, about once a+ * second while playing): the refreshes the screen had per half second of film, and how many of them got no new frame.+ * A stretch where many did is rendered in the background (studio/server/preview-cache.mjs) and played from that+ * render from then on. Kept free of React so it is tested as it is.+ */++/** Per half second of film (its start, s): refreshes seen there while playing, and how many got no new frame. */+export type Heat = Map<number, { frames: number; late: number }>;++/** Refreshes a half second keeps counting before older ones count less: what it does now outweighs what it did. */+const HEAT_KEEP = 120;+/** Late on this share of refreshes or more, a half second plays late. */+export const LATE_SHARE = 0.12;+/** Refreshes a half second needs before it is judged (a stretch only glimpsed says little). */+const HEAT_SEEN = 20;+/** A stretch is rendered with this much more on each side (s), and at least this long. */+const PAD = 0.25;+const SHORTEST = 1;++/** Add how playing went (`spans`: [half second's start, refreshes, late]). */+export function addHeat(heat: Heat, spans: readonly (readonly [number, number, number])[]): void {+ for (const [t, frames, late] of spans) {+ if (!(frames > 0) || !Number.isFinite(t)) continue;+ const had = heat.get(t) ?? { frames: 0, late: 0 };+ let next = { frames: had.frames + frames, late: had.late + Math.min(late, frames) };+ if (next.frames > HEAT_KEEP) {+ const k = HEAT_KEEP / next.frames;+ next = { frames: next.frames * k, late: next.late * k };+ }+ heat.set(t, next);+ }+}++/**+ * The stretches that play late, film seconds [a, b): half seconds late on LATE_SHARE of their refreshes or more,+ * joined across a gap of half a second, PAD more on each side, SHORTEST at least, in order.+ */+export function lateStretches(heat: Heat): [number, number][] {+ const late = [...heat].filter(([, h]) => h.frames >= HEAT_SEEN && h.late / h.frames >= LATE_SHARE).map(([t]) => t).sort((a, b) => a - b);+ const out: [number, number][] = [];+ for (const t of late) {+ const last = out.at(-1);+ if (last && t <= last[1] + 0.5 + 1e-9) last[1] = t + 0.5;+ else out.push([t, t + 0.5]);+ }+ return out.map(([a, b]) => {+ let from = Math.max(0, a - PAD);+ let to = b + PAD;+ if (to - from < SHORTEST) { const mid = (from + to) / 2; from = Math.max(0, mid - SHORTEST / 2); to = from + SHORTEST; }+ return [round(from), round(to)] as [number, number];+ });+}++const round = (s: number) => Math.round(s * 1000) / 1000;++/** Two lists of stretches the same. */+export function sameStretches(a: readonly (readonly [number, number])[], b: readonly (readonly [number, number])[]): boolean {+ return a.length === b.length && a.every(([x, y], i) => x === b[i][0] && y === b[i][1]);+}++/** Stretches as one list: in order, those that overlap or touch joined. */+export function joinStretches(list: readonly (readonly [number, number])[]): [number, number][] {+ const out: [number, number][] = [];+ for (const [a, b] of [...list].sort((x, y) => x[0] - y[0])) {+ const last = out.at(-1);+ if (last && a <= last[1] + 1e-9) last[1] = Math.max(last[1], b);+ else out.push([a, b]);+ }+ return out;+}diff --git a/packages/openfilm/studio/ui/src/lib/select-all-key.ts b/packages/openfilm/studio/ui/src/lib/select-all-key.tsindex 91b7f4d..b98c690 100644--- a/packages/openfilm/studio/ui/src/lib/select-all-key.ts+++ b/packages/openfilm/studio/ui/src/lib/select-all-key.ts@@ -1,7 +1,7 @@/** A key that can be select-all: what a keydown, or a key passed on from the film, says of itself. */export interface KeyLike { key: string; metaKey: boolean; ctrlKey: boolean; shiftKey: boolean; altKey: boolean }-/** ⌘A on a Mac, Ctrl+A elsewhere, without Shift or Alt: select all, as Figma, Photoshop and Premiere have it. */+/** ⌘A on a Mac, Ctrl+A elsewhere, without Shift or Alt: select all. */export function isSelectAll(e: KeyLike, mac: boolean): boolean {return (mac ? e.metaKey : e.ctrlKey) && !e.shiftKey && !e.altKey && e.key.toLowerCase() === 'a';}diff --git a/packages/openfilm/studio/ui/src/lib/stage-clip.ts b/packages/openfilm/studio/ui/src/lib/stage-clip.tsindex 107e853..edf9dca 100644--- a/packages/openfilm/studio/ui/src/lib/stage-clip.ts+++ b/packages/openfilm/studio/ui/src/lib/stage-clip.ts@@ -41,7 +41,7 @@ export function compactBox(d: MgTransform, own: MgBox): FilmBox {return out;}-/** A clip's X / Y / W / H on the stage (its unturned box, as Figma shows them) for transform `t` in `box`. */+/** A clip's X / Y / W / H on the stage (its unturned box, as the inspector shows them) for transform `t` in `box`. */export function clipFields(t: MgTransform, box: MgBox): { x: number; y: number; w: number; h: number } {return { x: (box.x ?? 0) + t.x, y: (box.y ?? 0) + t.y, w: box.w * t.scaleX, h: box.h * t.scaleY };}diff --git a/packages/openfilm/studio/ui/src/lib/stage-gesture.ts b/packages/openfilm/studio/ui/src/lib/stage-gesture.tsindex 963a77c..76fe3b1 100644--- a/packages/openfilm/studio/ui/src/lib/stage-gesture.ts+++ b/packages/openfilm/studio/ui/src/lib/stage-gesture.ts@@ -241,7 +241,7 @@ export function pullGroup(d: GroupPull, at: { x: number; y: number }, shift: boo}/**- * One of several layers scaled or turned together by their box's handles (as Figma does a selection): its center+ * One of several layers scaled or turned together by their box's handles: its center* (`center`, stage px) goes with the box, scaled or turned about the same point, and it takes the same scale or turn* itself. How far its center goes (stage px), and its own scale and angle after.*/@@ -259,7 +259,7 @@ export function layerInGroup(d: GroupDrag, center: { x: number; y: number }, g:/*** Where one of several clips dragged together is now. `t0` is where it was (its unturned top left, stage px, and its* scale), `size` its picture's own size: its center moves with the others, scaled or turned about the same point, so- * the gaps between them change with them (Figma); a turn turns each one by as much.+ * the gaps between them change with them; a turn turns each one by as much.*/export function groupDragged<T extends { x: number; y: number; scaleX: number; scaleY: number; rotate: number }>(d: GroupDrag, t0: T, size: { w: number; h: number },diff --git a/packages/openfilm/studio/ui/src/lib/stage-mask.ts b/packages/openfilm/studio/ui/src/lib/stage-mask.tsindex bf7c262..74ab3b6 100644--- a/packages/openfilm/studio/ui/src/lib/stage-mask.ts+++ b/packages/openfilm/studio/ui/src/lib/stage-mask.ts@@ -1,5 +1,5 @@/**- * A mask's handles on the picture (as CapCut draws them), apart from the DOM so it can be tested: where the outline and+ * A mask's handles on the picture, apart from the DOM so it can be tested: where the outline and* the handles go, and what a drag of each makes of the mask (lib/clip-mask's numbers).** Everything is in the clip's or layer's box, unturned, px from its top left (the overlay's px, the picture's scalediff --git a/packages/openfilm/studio/ui/src/lib/stage-measure.ts b/packages/openfilm/studio/ui/src/lib/stage-measure.tsindex 5b8a1ac..7b044ba 100644--- a/packages/openfilm/studio/ui/src/lib/stage-measure.ts+++ b/packages/openfilm/studio/ui/src/lib/stage-measure.ts@@ -1,5 +1,5 @@/**- * Distances between the thing in hand and another box on the stage, as Figma draws them while Alt is held: red lines+ * Distances between the thing in hand and another box on the stage, drawn while Alt is held: red lines* with their length, from the selection's edges to the other box's (or to the stage's, when nothing else is pointed* at). Boxes are unturned rects in stage px; lines are horizontal or vertical.*/diff --git a/packages/openfilm/studio/ui/src/lib/subtitles.ts b/packages/openfilm/studio/ui/src/lib/subtitles.tsindex a4e7704..4f8cd8e 100644--- a/packages/openfilm/studio/ui/src/lib/subtitles.ts+++ b/packages/openfilm/studio/ui/src/lib/subtitles.ts@@ -84,7 +84,7 @@ export const SNAP_Y: readonly number[] = [1 - SUBTITLE_HOME_Y, 0.5, FILM_SUBTITL/*** The snap radius, in screen pixels rather than a fraction: 1% is a few pixels in a small pane (never catches) and- * twenty at full screen (cannot be avoided). Figma's 6px.+ * twenty at full screen (cannot be avoided). 6px.*/export const SNAP_PX = 6;diff --git a/packages/openfilm/studio/ui/src/lib/tab-menu.test.ts b/packages/openfilm/studio/ui/src/lib/tab-menu.test.tsnew file mode 100644index 0000000..8605929--- /dev/null+++ b/packages/openfilm/studio/ui/src/lib/tab-menu.test.ts@@ -0,0 +1,19 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import { tabsToClose } from './tab-menu.ts';++const tabs = [{ id: 'a' }, { id: 'b' }, { id: 'c' }];+const ids = (list: Array<{ id: string }>) => list.map((tab) => tab.id);++test('a tab menu closes the others, or those to its right, never the tab itself', () => {+ assert.deepEqual(ids(tabsToClose(tabs, 'b', 'others')), ['a', 'c']);+ assert.deepEqual(ids(tabsToClose(tabs, 'b', 'right')), ['c']);+ assert.deepEqual(ids(tabsToClose(tabs, 'a', 'right')), ['b', 'c']);+ assert.deepEqual(tabsToClose(tabs, 'c', 'right'), []);+ assert.deepEqual(tabsToClose([{ id: 'a' }], 'a', 'others'), []);+});++test('a tab that is gone closes nothing', () => {+ assert.deepEqual(tabsToClose(tabs, 'x', 'others'), []);+ assert.deepEqual(tabsToClose(tabs, 'x', 'right'), []);+});diff --git a/packages/openfilm/studio/ui/src/lib/tab-menu.ts b/packages/openfilm/studio/ui/src/lib/tab-menu.tsnew file mode 100644index 0000000..3c3ce28--- /dev/null+++ b/packages/openfilm/studio/ui/src/lib/tab-menu.ts@@ -0,0 +1,6 @@+/** The tabs a tab's menu closes (TabStrip): the others, or those to its right; none when the tab is not there. */+export function tabsToClose<T extends { id: string }>(tabs: readonly T[], id: string, which: 'others' | 'right'): T[] {+ const i = tabs.findIndex((tab) => tab.id === id);+ if (i < 0) return [];+ return which === 'others' ? tabs.filter((tab) => tab.id !== id) : tabs.slice(i + 1);+}diff --git a/packages/openfilm/studio/ui/src/lib/timecode.ts b/packages/openfilm/studio/ui/src/lib/timecode.tsindex cc75b5e..e1edbde 100644--- a/packages/openfilm/studio/ui/src/lib/timecode.ts+++ b/packages/openfilm/studio/ui/src/lib/timecode.ts@@ -19,8 +19,8 @@ import { useSyncExternalStore } from 'react';export const DISPLAY_FPS = 30;/**- * The rates a project can be set to and a video exported at, as editors name them: Premiere's and DaVinci Resolve's- * common ones (the NTSC 23.976, 29.97 and 59.94 are what cameras and phones record), and 120 for high frame rate.+ * The rates a project can be set to and a video exported at: the common ones (the NTSC 23.976, 29.97 and 59.94 are+ * what cameras and phones record), and 120 for high frame rate.*/export const FRAME_RATES = [23.976, 24, 25, 29.97, 30, 48, 50, 59.94, 60, 120] as const;@@ -147,8 +147,8 @@ export function formatTimecode(ms: number, opts?: { hours?: boolean; fps?: numbe}/**- * The short label on the ruler: `mm:ss` on whole seconds (with hours past an hour), `12f` in between — as OpenCut and- * CapCut do. Full timecodes on every tick would be a wall of `00:00:47:29`.+ * The short label on the ruler: `mm:ss` on whole seconds (with hours past an hour), `12f` in between. Full timecodes+ * on every tick would be a wall of `00:00:47:29`.*/export function formatRulerLabel(ms: number, fps = currentFps): string {/* a tick is a place on the clock, not a frame: a whole second is labeled as one even where no frame starts on it */diff --git a/packages/openfilm/studio/ui/src/lib/timeline-clipboard.test.ts b/packages/openfilm/studio/ui/src/lib/timeline-clipboard.test.tsindex fa95704..940ae9d 100644--- a/packages/openfilm/studio/ui/src/lib/timeline-clipboard.test.ts+++ b/packages/openfilm/studio/ui/src/lib/timeline-clipboard.test.ts@@ -1,11 +1,11 @@import { test } from 'node:test';import assert from 'node:assert/strict';import { applyOps } from '../../../server/ops.mjs';-import { clipboardItemsOf, clipboardNow, copyLinks, pasteEdit, pastePlan, planCopies, type TimelinePasteJob } from './timeline-clipboard.ts';+import { clipboardItemsOf, clipboardNow, copyLinks, pasteEdit, planCopies } from './timeline-clipboard.ts';import { editModelOf } from './timeline-edit.ts';import type { TimelineBlock, TimelineTrack } from './timeline-layout';-/* Clips on one track do not overlap (SPEC): a paste opens a track rather than put one clip on another. */+/* Clips on one track do not overlap (SPEC), and a paste never cuts what is there: a taken spot opens a track. */const block = (clipId: string, track: number, clip: number, startMs: number, endMs: number): TimelineBlock => ({ id: `b-${clipId}`, clipId, loc: `film.html#${track}.${clip}`, startMs, endMs } as unknown as TimelineBlock@@ -14,15 +14,27 @@ const track = (docIndex: number, blocks: TimelineBlock[], extra: Partial<Timelin{ lane: `doc-${docIndex}`, docIndex, blocks, ...extra } as unknown as TimelineTrack);-/* where each pasted clip ends up, by track: an inserted track counts as the index it opens */-function landing(jobs: readonly TimelinePasteJob[]) {- return jobs.map((job) => {- const on = job.track != null- ? `new ${typeof job.track === 'number' ? job.track : job.track.insert}`- : job.after ? `doc ${/#(\d+)\./.exec(job.after)![1]}` : `lane ${job.lane}`;- return { from: job.from, at: job.atSec, on };- });-}+type Film = { tracks: { locked?: boolean; clips: { id: string; src: string; at?: number; time?: number[]; attrs?: Record<string, string> }[] }[] };+const filmClip = (id: string, at: number, len: number, link?: string) => ({ id, src: `${id}.mp4`, ...(at ? { at } : {}), time: [0, len], ...(link ? { attrs: { 'data-link': link } } : {}) });+const blockOf = (id: string, track: number, clip: number, startMs: number, endMs: number) => ({+ ...block(id, track, clip, startMs, endMs), anchor: { move: 'at', resize: 'end', trimFrom: 0, parentStartMs: 0 }, sourceDurMs: 60_000,+} as unknown as TimelineBlock);+const spans = (film: Film) => film.tracks.map((t) => t.clips.map((c) => [c.id, c.at ?? 0, c.attrs?.['data-link'] ?? null] as const)+ .sort((x, y) => x[1] - y[1]));+/** The film of these rows: each clip as long as its block, starting where it does. */+const filmOfRows = (rows: readonly TimelineTrack[]): Film => {+ const out: Film = { tracks: [] };+ for (const row of rows) {+ const t = out.tracks[row.docIndex!] ??= { clips: [] };+ for (const b of row.blocks) t.clips.push(filmClip(b.clipId!, b.startMs / 1000, (b.endMs - b.startMs) / 1000));+ }+ return out;+};+/** The film after the copied clips are pasted (put down) at `atMs`, onto `lane` or their own tracks: [id, at] by track. */+const pasted = (rows: TimelineTrack[], copied: TimelineBlock[], atMs: number, lane: string | null = null) => {+ const ops = pasteEdit(clipboardItemsOf(copied, rows), rows, editModelOf(rows), atMs, lane, { mode: 'place' })!;+ return spans(applyOps(filmOfRows(rows) as never, ops as never) as unknown as Film).map((t) => t.map(([id, at]) => [id, at]));+};test('the clipboard keeps clips by id, so a paste after the track is renumbered copies the same clip', () => {const tracks = [track(0, [block('a', 0, 0, 0, 2000), block('c', 0, 2, 4000, 6000)])];@@ -30,10 +42,10 @@ test('the clipboard keeps clips by id, so a paste after the track is renumberedassert.deepEqual(copied, [{ clipId: 'c', startMs: 4000, durMs: 2000, lane: 'doc-0' }]);/* an earlier clip deleted: `c` is now at #0.1, and still the clip pasted */- const after = [track(0, [block('c', 0, 1, 4000, 6000)])];+ const after = [track(0, [blockOf('c', 0, 1, 4000, 6000)])];const now = clipboardNow(copied, after);assert.equal(now.missing, 0);- assert.deepEqual(pastePlan(now.items, after, 8000).map((j) => j.from), ['c']);+ assert.deepEqual(pasteEdit(now.items, after, editModelOf(after), 8000, null, { mode: 'place' })!.map((op) => op.op === 'insert' && op.from), ['c']);});test('a copied clip that is gone is counted, not swapped for whatever sits at its old place', () => {@@ -53,133 +65,84 @@ test('the length pasted is the clip as it is now, not as copied', () => {});test('clips copied from several tracks go back to their own tracks, even when a track was pointed at', () => {- const video = block('v', 0, 0, 0, 3000);- const sound = block('s', 1, 0, 0, 3000);- const tracks = [track(0, [video]), track(1, [sound])];- const copied = clipboardItemsOf([video, sound], tracks);+ const tracks = [track(0, [blockOf('v', 0, 0, 0, 3000)]), track(1, [blockOf('s', 1, 0, 0, 3000)])];for (const lane of [null, 'doc-0', 'doc-1']) {- const out = landing(pastePlan(copied, tracks, 6000, lane)).sort((a, b) => a.from.localeCompare(b.from));- assert.deepEqual(out, [- { from: 's', at: 6, on: 'doc 1' },- { from: 'v', at: 6, on: 'doc 0' },+ assert.deepEqual(pasted(tracks, [tracks[0]!.blocks[0]!, tracks[1]!.blocks[0]!], 6000, lane), [+ [['v', 0], ['v-2', 6]],+ [['s', 0], ['s-2', 6]],], `pointed at ${lane}`);}});test('clips copied from one track follow the track pointed at', () => {- const a = block('a', 0, 0, 0, 1000);- const b = block('b', 0, 1, 2000, 3000);- const tracks = [track(0, [a, b]), track(1, [block('z', 1, 0, 0, 500)])];- const out = landing(pastePlan(clipboardItemsOf([a, b], tracks), tracks, 6000, 'doc-1'));- assert.deepEqual(out, [- { from: 'b', at: 8, on: 'doc 1' },- { from: 'a', at: 6, on: 'doc 1' },+ const tracks = [track(0, [blockOf('a', 0, 0, 0, 1000), blockOf('b', 0, 1, 2000, 3000)]), track(1, [blockOf('z', 1, 0, 0, 500)])];+ assert.deepEqual(pasted(tracks, tracks[0]!.blocks, 6000, 'doc-1'), [+ [['a', 0], ['b', 2]],+ [['z', 0], ['a-2', 6], ['b-2', 8]],]);});-test('clips that overlap each other, forced onto one track, open tracks so none overlap', () => {- /* one film.html track spread over two rows: its clips overlap */- const a = block('a', 0, 0, 0, 3000);- const b = block('b', 0, 1, 1000, 4000);- const tracks = [- track(0, [a], { lane: 'doc-0' }),- track(0, [b], { lane: 'doc-0#2' }),- track(1, [block('z', 1, 0, 0, 500)]),- ];- const jobs = pastePlan(clipboardItemsOf([a, b], tracks), tracks, 10000, 'doc-1');- assert.deepEqual(jobs.map((j) => ({ from: j.from, track: j.track })), [- { from: 'a', track: { insert: 2 } },- { from: 'b', track: { insert: 3 } },- ]);+test('a paste never cuts: a taken spot opens a track above a picture track, below a sound track', () => {+ const pictures = [track(0, [blockOf('a', 0, 0, 0, 2000), blockOf('b', 0, 1, 2000, 6000)], { role: 'video' })];+ assert.deepEqual(pasted(pictures, [pictures[0]!.blocks[0]!], 3000), [[['a-2', 3]], [['a', 0], ['b', 2]]]);+ const sound = [track(0, [blockOf('v', 0, 0, 0, 6000)], { role: 'video' }), track(1, [blockOf('m', 1, 0, 0, 6000)], { role: 'audio' })];+ assert.deepEqual(pasted(sound, [sound[1]!.blocks[0]!], 2000), [[['v', 0]], [['m', 0]], [['m-2', 2]]]);});test('clips that meet end to end are not an overlap, a millisecond of rounding included', () => {- const a = block('a', 0, 0, 0, 1000.4);- const b = block('b', 0, 1, 1000.4, 2000);- const tracks = [track(0, [a, b])];- const jobs = pastePlan(clipboardItemsOf([a, b], tracks), tracks, 5000);- assert.ok(jobs.every((j) => j.track == null && j.after === 'film.html#0.1'));-});--test('a duplicate at the clip end opens a track when the next clip starts there', () => {- const a = block('a', 2, 0, 0, 2000);- const b = block('b', 2, 1, 2000, 4000);- const tracks = [track(2, [a, b])];- const jobs = pastePlan(clipboardItemsOf([a], tracks), tracks, a.endMs);- assert.deepEqual(jobs, [{ from: 'a', atSec: 2, after: null, lane: 'doc-2', track: { insert: 3 } }]);-- /* with room after it, it stays on the track */- const free = [track(2, [a, block('b', 2, 1, 5000, 6000)])];- assert.deepEqual(pastePlan(clipboardItemsOf([a], free), free, a.endMs), [- { from: 'a', atSec: 2, after: 'film.html#2.1', lane: 'doc-2' },+ const tracks = [track(0, [blockOf('a', 0, 0, 0, 1000.4), blockOf('b', 0, 1, 1000.4, 2000)])];+ assert.deepEqual(pasted(tracks, tracks[0]!.blocks, 5000), [[['a', 0], ['b', 1.0004], ['a-2', 5], ['b-2', 6]]]);+});++test('clips that overlap each other, put onto one track, open a track each so none overlap', () => {+ /* one film.html track spread over two rows: its clips overlap */+ const tracks = [+ track(0, [blockOf('a', 0, 0, 0, 3000)], { lane: 'doc-0' }),+ track(0, [blockOf('b', 0, 1, 1000, 4000)], { lane: 'doc-0#2' }),+ track(1, [blockOf('z', 1, 0, 0, 500)]),+ ];+ assert.deepEqual(pasted(tracks, [tracks[0]!.blocks[0]!, tracks[1]!.blocks[0]!], 10000, 'doc-1'), [+ [['a', 0], ['b', 1]],+ [['b-2', 11]],+ [['a-2', 10]],+ [['z', 0]],]);});-test('groups that open tracks go last, highest index first, each new track opened once', () => {- const v = block('v', 0, 0, 0, 3000);- const s = block('s', 2, 0, 0, 3000);- const tracks = [track(0, [v]), track(1, [block('free', 1, 0, 9000, 9500)]), track(2, [s])];- const jobs = pastePlan(clipboardItemsOf([v, s], tracks), tracks, 1000);- assert.deepEqual(jobs.map((j) => ({ from: j.from, track: j.track })), [- { from: 's', track: { insert: 3 } },- { from: 'v', track: { insert: 1 } },+test('copies opening tracks in several places each open beside their own track', () => {+ const tracks = [+ track(0, [blockOf('v', 0, 0, 0, 3000)], { role: 'video' }),+ track(1, [blockOf('free', 1, 0, 9000, 9500)], { role: 'video' }),+ track(2, [blockOf('s', 2, 0, 0, 3000)], { role: 'audio' }),+ ];+ assert.deepEqual(pasted(tracks, [tracks[0]!.blocks[0]!, tracks[2]!.blocks[0]!], 1000), [+ [['v-2', 1]],+ [['v', 0]],+ [['free', 9]],+ [['s', 0]],+ [['s-2', 1]],]);});-/* ── a paste in the timeline's mode ── */+/* ── a paste that makes room, and ⌥-drag copies ── */-type Film = { tracks: { locked?: boolean; clips: { id: string; src: string; at?: number; time?: number[]; attrs?: Record<string, string> }[] }[] };-const filmClip = (id: string, at: number, len: number, link?: string) => ({ id, src: `${id}.mp4`, ...(at ? { at } : {}), time: [0, len], ...(link ? { attrs: { 'data-link': link } } : {}) });-const blockOf = (id: string, track: number, clip: number, startMs: number, endMs: number) => ({- ...block(id, track, clip, startMs, endMs), anchor: { move: 'at', resize: 'end', trimFrom: 0, parentStartMs: 0 }, sourceDurMs: 60_000,-} as unknown as TimelineBlock);-const spans = (film: Film) => film.tracks.map((t) => t.clips.map((c) => [c.id, c.at ?? 0, c.attrs?.['data-link'] ?? null] as const)- .sort((x, y) => x[1] - y[1]));--test('a paste in insert mode makes room at the playhead on the track pointed at, and opens no track', () => {+test('a paste in insert mode makes room at the playhead on the track pointed at alone, and opens no track', () => {const film: Film = { tracks: [{ clips: [filmClip('a', 0, 2), filmClip('b', 2, 2)] }, { clips: [filmClip('vo', 3, 1)] }] };const tracks = [track(0, [blockOf('a', 0, 0, 0, 2000), blockOf('b', 0, 1, 2000, 4000)]), track(1, [blockOf('vo', 1, 0, 3000, 4000)])];const model = editModelOf(tracks);const copied = clipboardItemsOf([tracks[0]!.blocks[0]!], tracks);- const ops = pasteEdit(copied, tracks, model, 2000, 'doc-0', { mode: 'insert', sync: true })!;+ const ops = pasteEdit(copied, tracks, model, 2000, 'doc-0', { mode: 'insert' })!;const out = applyOps(structuredClone(film) as never, ops as never) as unknown as Film;- assert.deepEqual(spans(out), [[['a', 0, null], ['a-2', 2, null], ['b', 4, null]], [['vo', 5, null]]]);+ assert.deepEqual(spans(out), [[['a', 0, null], ['a-2', 2, null], ['b', 4, null]], [['vo', 3, null]]]);});-test('a paste in overwrite mode cuts what is under it; a locked track refuses it', () => {- const film: Film = { tracks: [{ clips: [filmClip('a', 0, 2), filmClip('b', 2, 4)] }] };- const tracks = [track(0, [blockOf('a', 0, 0, 0, 2000), blockOf('b', 0, 1, 2000, 6000)])];+test('a locked track refuses a paste', () => {+ const tracks = [track(0, [blockOf('a', 0, 0, 0, 2000)], { locked: true })];const copied = clipboardItemsOf([tracks[0]!.blocks[0]!], tracks);- const ops = pasteEdit(copied, tracks, editModelOf(tracks), 3000, 'doc-0', { mode: 'overwrite', sync: true })!;- const out = applyOps(structuredClone(film) as never, ops as never) as unknown as Film;- assert.deepEqual(spans(out), [[['a', 0, null], ['b', 2, null], ['a-2', 3, null], ['b-b', 5, null]]]);- const locked = [track(0, tracks[0]!.blocks, { locked: true })];- assert.equal(pasteEdit(copied, locked, editModelOf(locked), 3000, 'doc-0', { mode: 'overwrite', sync: true }), null);+ assert.equal(pasteEdit(copied, tracks, editModelOf(tracks), 3000, 'doc-0', { mode: 'place' }), null);});-test('with the magnet, as CapCut: a paste covers nothing and pushes nothing', () => {- const film: Film = { tracks: [{ clips: [filmClip('t1', 0, 2)] }, { clips: [filmClip('a', 0, 2), filmClip('b', 2, 2)] }] };- const tracks = [- track(0, [blockOf('t1', 0, 0, 0, 2000)], { role: 'mg' }),- track(1, [blockOf('a', 1, 0, 0, 2000), blockOf('b', 1, 1, 2000, 4000)], { role: 'video' }),- ];- const model = editModelOf(tracks);- const paste = (from: TimelineBlock, atMs: number, lane: string) => spans(applyOps(structuredClone(film) as never,- pasteEdit(clipboardItemsOf([from], tracks), tracks, model, atMs, lane, { magnet: true, sync: false, linkage: true }) as never) as unknown as Film);- /* the title pasted at 1 s over itself: a new title track opens above for the copy */- assert.deepEqual(paste(tracks[0]!.blocks[0]!, 1000, 'doc-0'), [[['t1-2', 1, null]], [['t1', 0, null]], [['a', 0, null], ['b', 2, null]]]);- /* at 3 s its own track is free: it goes there */- assert.deepEqual(paste(tracks[0]!.blocks[0]!, 3000, 'doc-0')[0], [['t1', 0, null], ['t1-2', 3, null]]);- /* a shot pasted at 2 s, where the main track is taken: the main track is left alone, the copy goes to the free- picture track above it */- assert.deepEqual(paste(tracks[1]!.blocks[0]!, 2000, 'doc-1'), [[['t1', 0, null], ['a-2', 2, null]], [['a', 0, null], ['b', 2, null]]]);- /* at 1 s nothing above is free either: a new track right above the main track */- assert.deepEqual(paste(tracks[1]!.blocks[0]!, 1000, 'doc-1'), [[['t1', 0, null]], [['a-2', 1, null]], [['a', 0, null], ['b', 2, null]]]);- /* past the main track's end: onto it, closed up against its last clip */- assert.deepEqual(paste(tracks[1]!.blocks[0]!, 6000, 'doc-1')[1], [['a', 0, null], ['b', 2, null], ['a-2', 4, null]]);-});--test('⌥-drag copies, as CapCut: the clip stays and a copy lands where it is let go', () => {+test('⌥-drag copies: the clips stay and a copy lands where it is let go, or beside the track when that is taken', () => {const film: Film = { tracks: [{ clips: [filmClip('t1', 0, 2)] }, { clips: [filmClip('a', 0, 2), filmClip('b', 2, 2)] }] };const tracks = [track(0, [blockOf('t1', 0, 0, 0, 2000)], { role: 'mg' }),@@ -187,23 +150,49 @@ test('⌥-drag copies, as CapCut: the clip stays and a copy lands where it is le];const model = editModelOf(tracks);const run = (plan: { ops: unknown[] } | null) => spans(applyOps(structuredClone(film) as never, plan!.ops as never) as unknown as Film);- const opts = { magnet: true, sync: false, linkage: true };- /* b copied onto the first half of a on the main track: it goes in before a, what follows moves on */- assert.deepEqual(run(planCopies(model, { ids: ['b'], deltaMs: -1500, pointerMs: 500, ...opts }))[1], [['b-2', 0, null], ['a', 2, null], ['b', 4, null]]);- /* the title copied onto itself 1 s later: off the main track nothing is covered, a new track above takes it */- assert.deepEqual(run(planCopies(model, { ids: ['t1'], deltaMs: 1000, pointerMs: 1500, ...opts })), [[['t1-2', 1, null]], [['t1', 0, null]], [['a', 0, null], ['b', 2, null]]]);- /* without the magnet a copy covers what is under it */- assert.deepEqual(run(planCopies(model, { ids: ['t1'], deltaMs: 1000, pointerMs: 1500, magnet: false, sync: false }))[0], [['t1', 0, null], ['t1-2', 1, null]]);+ /* the title copied onto itself 1 s later: the copy goes to a new track above it */+ const onItself = planCopies(model, { ids: ['t1'], deltaMs: 1000 })!;+ assert.deepEqual(run(onItself), [[['t1-2', 1, null]], [['t1', 0, null]], [['a', 0, null], ['b', 2, null]]]);+ assert.deepEqual(onItself.placed.get('t1'), { startMs: 1000, endMs: 3000, track: { insert: 0 } });+ /* b copied onto a at 0.5 s: a and b stay whole, the copy goes above them */+ assert.deepEqual(run(planCopies(model, { ids: ['b'], deltaMs: -1500 })), [[['t1', 0, null]], [['b-2', 0.5, null]], [['a', 0, null], ['b', 2, null]]]);+ /* b copied past the end: free there, on its own track */+ assert.deepEqual(run(planCopies(model, { ids: ['b'], deltaMs: 3000 }))[1], [['a', 0, null], ['b', 2, null], ['b-2', 5, null]]);});-test('⌥-drag copies of clips with the magnet go in at the insert point by the first of them, whichever is in hand', () => {+test('⌥-drag copies of several clips keep their spacing, together on one track', () => {const film: Film = { tracks: [{ clips: [filmClip('a', 0, 2), filmClip('b', 2, 2), filmClip('c', 5, 1)] }] };const tracks = [track(0, [blockOf('a', 0, 0, 0, 2000), blockOf('b', 0, 1, 2000, 4000), blockOf('c', 0, 2, 5000, 6000)], { role: 'video' })];const model = editModelOf(tracks);const run = (plan: { ops: unknown[] } | null) => spans(applyOps(structuredClone(film) as never, plan!.ops as never) as unknown as Film);- /* b and c in hand by c, let go past the end: the copies go on after c, b's first, the gap between them kept */- assert.deepEqual(run(planCopies(model, { ids: ['c', 'b'], deltaMs: 1000, pointerMs: 6500, magnet: true, sync: false, linkage: true }))[0],- [['a', 0, null], ['b', 2, null], ['c', 5, null], ['b-2', 6, null], ['c-2', 9, null]]);+ /* b and c copied 2 s later: b's copy would cover c, so both copies go to a new track above, the gap between them kept */+ assert.deepEqual(run(planCopies(model, { ids: ['c', 'b'], deltaMs: 2000 })),+ [[['b-2', 4, null], ['c-2', 7, null]], [['a', 0, null], ['b', 2, null], ['c', 5, null]]]);+});++test('with the magnet a copy of a main-track clip pastes onto a new track right above the main track', () => {+ const tracks = [+ track(0, [blockOf('t', 0, 0, 0, 1000)], { role: 'mg' }),+ track(1, [blockOf('a', 1, 0, 0, 2000), blockOf('b', 1, 1, 2000, 4000)], { role: 'video' }),+ ];+ const ops = pasteEdit(clipboardItemsOf([tracks[1]!.blocks[0]!], tracks), tracks, editModelOf(tracks), 9000, null, { mode: 'place', magnet: true, linkage: true })!;+ const out = spans(applyOps(filmOfRows(tracks) as never, ops as never) as unknown as Film).map((t) => t.map(([id, at]) => [id, at]));+ /* even where the main track is free (past its end): the main track is only changed by putting clips in between */+ assert.deepEqual(out, [[['t', 0]], [['a-2', 9]], [['a', 0], ['b', 2]]]);+});++test('with the magnet ⌥-drag copies onto the main track go in between, what follows moving on', () => {+ const film: Film = { tracks: [{ clips: [filmClip('t', 0, 1)] }, { clips: [filmClip('a', 0, 2), filmClip('b', 2, 2)] }] };+ const tracks = [+ track(0, [blockOf('t', 0, 0, 0, 1000)], { role: 'mg' }),+ track(1, [blockOf('a', 1, 0, 0, 2000), blockOf('b', 1, 1, 2000, 4000)], { role: 'video' }),+ ];+ const model = editModelOf(tracks);+ /* b copied and let go over the first half of a: the copy goes in before a */+ const plan = planCopies(model, { ids: ['b'], deltaMs: -2000, pointerMs: 500, magnet: true, linkage: true })!;+ const out = spans(applyOps(structuredClone(film) as never, plan.ops as never) as unknown as Film);+ assert.deepEqual(out, [[['t', 2, null]], [['b-2', 0, null], ['a', 2, null], ['b', 4, null]]]);+ assert.deepEqual(plan.placed.get('b'), { startMs: 0, endMs: 2000, track: 1 });});test('copies of linked clips pasted together are linked to each other, not to the originals', () => {diff --git a/packages/openfilm/studio/ui/src/lib/timeline-clipboard.ts b/packages/openfilm/studio/ui/src/lib/timeline-clipboard.tsindex 5007582..60b48d4 100644--- a/packages/openfilm/studio/ui/src/lib/timeline-clipboard.ts+++ b/packages/openfilm/studio/ui/src/lib/timeline-clipboard.ts@@ -9,10 +9,11 @@* back to their own tracks. Only clips copied from one track follow a track the person points at.*/import type { Op } from '../api.ts';-import { FILM_DOC_FILE } from './film.ts';-import { newTrackSide } from './timeline-drag.ts';-import { freshLink, freeTrackFor, insertPointOn, mainTrackOf, planRoom, TOUCH_MS, type EditMode, type EditModel, type EditPlan, type Follow, type TrackDest } from './timeline-edit.ts';+import {+ TOUCH_MS, freshLink, insertPointOn, mainTrackOf, magnetOn, planRoom,+ type EditModel, type EditPlan, type Placed, type Switches, type TrackDest,+} from './timeline-edit.ts';import type { TimelineBlock, TimelineTrack } from './timeline-layout';export type TimelineClipboardItem = {@@ -24,20 +25,6 @@ export type TimelineClipboardItem = {lane: string;};-export type TimelinePasteJob = {- /** The id of the clip copied. */- from: string;- atSec: number;- after: string | null;- lane: string;- /**- * When the spot is taken the copy does not stack on the original track (it would spread into two rows sharing a- * badge): it opens a track right after it. The first clip on each new track `{ insert: index }` opens it, the rest- * name it.- */- track?: number | { insert: number };-};-export function laneOfBlock(tracks: readonly TimelineTrack[], id: string): string | null {for (const track of tracks) {if (track.blocks.some((b) => b.id === id)) return track.lane;@@ -57,24 +44,6 @@ export function trackByLane(return tracks.find((tr) => tr.docIndex === Number(doc));}-/**- * The last clip of film.html track `index` — a paste goes after it. One track may be spread over several rows- * (`doc-3#2`), so every row is scanned.- */-export function lastLocOfDocTrack(- tracks: readonly TimelineTrack[],- index: number,-): string | null {- let best = -1;- for (const track of tracks) {- for (const b of track.blocks) {- const m = b.loc ? /#(\d+)\.(\d+)$/.exec(b.loc) : null;- if (m && Number(m[1]) === index) best = Math.max(best, Number(m[2]));- }- }- return best < 0 ? null : `${FILM_DOC_FILE}#${index}.${best}`;-}-export function clipboardItemsOf(blocks: readonly TimelineBlock[],tracks: readonly TimelineTrack[],@@ -114,104 +83,6 @@ function docIndexOfLane(lane: string): number | null {return doc == null ? null : Number(doc);}-type Range = { startMs: number; endMs: number };--/**- * Whether two clips would overlap on one track. The pasted start is rounded to the millisecond and clip ends are not,- * so clips that meet end to end may share up to 1 ms; that is not an overlap.- */-function clashes(range: Range, others: readonly Range[]): boolean {- return others.some((o) => o.startMs < range.endMs - 1 && o.endMs > range.startMs + 1);-}--/**- * The inserts one paste sends.- *- * `forceLane` = a track the person pointed at (right-click, or the selected clip's track): clips copied from one track- * all go there. Clips copied from several tracks each go back to their own track, whatever was pointed at — stacking- * them on one track would overlap a video with its own sound. The group's earliest clip lands at `atMs`, the rest- * keep their spacing, across tracks too.- *- * The pasted clips are checked against what is on the track and against each other. A taken spot sends that track's- * clips to a new track right after it (newTrackSide); clips that would still overlap each other there get one more- * track each, so nothing on one track ever overlaps. Opening a track shifts the indexes below it, so groups that open- * tracks go last, from the highest index down, and each group's new tracks are opened top to bottom.- */-export function pastePlan(- clipboard: readonly TimelineClipboardItem[],- tracks: readonly TimelineTrack[],- atMs: number,- forceLane?: string | null,-): TimelinePasteJob[] {- if (!clipboard.length) return [];- const base = Math.min(...clipboard.map((item) => item.startMs));- const copiedTracks = new Set(clipboard.map((item) => docIndexOfLane(item.lane) ?? item.lane));- const force = forceLane && copiedTracks.size === 1 ? forceLane : null;- /* rows of one film.html track are one track here: clips pasted onto two of its rows still land on the same track */- const groups = new Map<string, { lane: string; items: TimelineClipboardItem[] }>();- for (const item of clipboard) {- const lane = force || item.lane;- const key = String(docIndexOfLane(lane) ?? lane);- const group = groups.get(key) ?? { lane, items: [] };- group.items.push(item);- groups.set(key, group);- }- const plans = [...groups.values()].map(({ lane, items }) => {- const docIndex = docIndexOfLane(lane);- const ranges = items.map((item) => {- const startMs = Math.round(atMs + (item.startMs - base));- return { item, startMs, endMs: startMs + item.durMs };- }).sort((a, b) => a.startMs - b.startMs);- /* one track may be spread over several rows: scan every row with this index */- const occupied = docIndex == null- ? []- : tracks- .filter((tr) => tr.docIndex === docIndex)- .flatMap((tr) => tr.blocks.map((b) => ({ startMs: b.startMs, endMs: b.endMs })));- const collides = docIndex != null && ranges.some((r, i) => clashes(r, occupied) || clashes(r, ranges.slice(0, i)));- return { lane, ranges, docIndex, collides };- });- plans.sort((a, b) => (- Number(a.collides) - Number(b.collides)- || (b.docIndex ?? -1) - (a.docIndex ?? -1)- ));-- const out: TimelinePasteJob[] = [];- for (const { lane, ranges, docIndex, collides } of plans) {- if (collides) {- /* the spot is taken: the copies get tracks of their own right after the original, each filled without overlap */- const rows: (typeof ranges)[] = [];- for (const r of ranges) {- const row = rows.find((placed) => !clashes(r, placed));- if (row) row.push(r);- else rows.push([r]);- }- rows.forEach((row, n) => {- const insertAt = newTrackSide(docIndex!) + n;- row.forEach(({ item, startMs }, i) => {- out.push({ from: item.clipId, atSec: startMs / 1000, after: null, lane, track: i === 0 ? { insert: insertAt } : insertAt });- });- });- continue;- }- const after = docIndex == null ? null : lastLocOfDocTrack(tracks, docIndex);- for (const { item, startMs } of [...ranges].reverse()) {- out.push({ from: item.clipId, atSec: startMs / 1000, after, lane });- }- }- return out;-}--export function pasteDestLocked(- jobs: readonly TimelinePasteJob[],- tracks: readonly TimelineTrack[],-): boolean {- /* jobs that open a new track do not land on a locked one: the lock only stops pasting into that track */- return jobs.some((job) => (- job.track == null && Boolean(job.lane && trackByLane(tracks, job.lane)?.locked)- ));-}-/*** The links copies get: copies of clips linked together and pasted together are linked to each other, with a link* of their own (not the originals', or moving a copy would move the original); a copy pasted without the clips its@@ -242,14 +113,88 @@ export function copyLinks(clipIds: readonly string[], model: EditModel): Map<strreturn out;}+/** A copy to put down: of clip `from`, at this time, onto this track; `source` is the track it was copied from. */+type CopySpan = { from: string; startMs: number; endMs: number; dest: TrackDest; source: number };++const overlap = (a: { startMs: number; endMs: number }, b: { startMs: number; endMs: number }): boolean => (+ a.startMs < b.endMs - TOUCH_MS && a.endMs > b.startMs + TOUCH_MS+);++/**+ * Copies put down, never cutting or moving what is there. Onto their track where that time is free; where it is taken+ * (by a clip there, or by another copy) the copies headed there all go to a new track beside it instead (newTrackSide),+ * and one more for each that would still overlap another. `keepOff` (the main track with the magnet) is+ * always taken: copies headed there go to a new track right above it. Copies headed for a new track (`{ insert }`)+ * open one per track they came from, so a group keeps its rows. The inserts onto tracks that are there go first, then+ * the new tracks from the last place up, so every place written holds. `placed`: where each copy lands, by the id it+ * was copied from.+ */+function placeCopies(+ model: EditModel,+ spans: readonly CopySpan[],+ links: ReadonlyMap<string, string | null>,+ keepOff: number | null = null,+): { ops: Op[]; placed: Map<string, Placed> } {+ const there: CopySpan[] = [];+ /* a new track: where it opens, and how low it ends among those opened at that place (higher = lower down) */+ const opened: { at: number; low: number; key: string; spans: CopySpan[] }[] = [];+ const openAt = (at: number, low: number, key: string, span: CopySpan) => {+ const found = opened.find((o) => o.at === at && o.key === key);+ if (found) found.spans.push(span);+ else opened.push({ at, low, key, spans: [span] });+ };+ const byTrack = new Map<number, CopySpan[]>();+ for (const s of spans) {+ if (typeof s.dest === 'object') openAt(s.dest.insert, s.source, `from-${s.source}`, s);+ else byTrack.set(s.dest, [...(byTrack.get(s.dest) ?? []), s]);+ }+ for (const [index, group] of byTrack) {+ const track = model.find((t) => t.index === index);+ const clips = track?.clips ?? [];+ const taken = index === keepOff+ || group.some((s, i) => clips.some((c) => overlap(s, c)) || group.slice(0, i).some((o) => overlap(s, o)));+ if (!taken) {+ there.push(...group);+ continue;+ }+ const side = newTrackSide(index, track?.role);+ const rows: CopySpan[][] = [];+ for (const s of [...group].sort((a, b) => a.startMs - b.startMs)) {+ const row = rows.find((r) => !r.some((o) => overlap(s, o)));+ if (row) row.push(s);+ else rows.push([s]);+ }+ /* the first row next to the track, the others further away: above a picture track, below a sound one */+ rows.forEach((row, n) => {+ for (const s of row) openAt(side, side === index ? -n : n, `beside-${index}-${n}`, s);+ });+ }+ const insertOf = (s: CopySpan, track: TrackDest): Op => ({+ op: 'insert',+ from: s.from,+ at: Math.round(s.startMs) / 1000,+ track,+ ...(links.has(s.from) ? { link: links.get(s.from)! } : {}),+ });+ const ops: Op[] = there.map((s) => insertOf(s, s.dest));+ const placed = new Map<string, Placed>(there.map((s) => [s.from, { startMs: s.startMs, endMs: s.endMs, track: s.dest }]));+ /* a track opened at a place goes above those opened there before it: the lowest of them opens first */+ for (const o of [...opened].sort((a, b) => b.at - a.at || b.low - a.low)) {+ [...o.spans].sort((a, b) => a.startMs - b.startMs).forEach((s, i) => {+ ops.push(insertOf(s, i === 0 ? { insert: o.at } : o.at));+ placed.set(s.from, { startMs: s.startMs, endMs: s.endMs, track: { insert: o.at } });+ });+ }+ return { ops, placed };+}+/**- * A paste as an edit in the timeline's mode: copied from one track, the copies go onto the track pointed at- * (`forceLane`) if any; from several, each back onto its own. The group's earliest clip lands at `atMs`, the rest- * keep their spacing. An insert makes room there (pushing what follows on, with sync lock on every unlocked track);- * an overwrite takes that time off the tracks. With the magnet given (as CapCut's): nothing is covered or pushed — a- * copy whose time is taken goes to a free track or a new one, and onto the main track only past its end. The copies- * go in first, so a clip pasted over itself is copied whole before it is cut. Null when a track it goes onto is locked- * or gone.+ * A paste: copied from one track, the copies go onto the track pointed at (`forceLane`) if any; from several, each+ * back onto its own. The group's earliest clip lands at `atMs`, the rest keep their spacing. Put down (`place`), they+ * never cut or move what is there: a taken spot opens a track beside it (placeCopies), and with the magnet a copy+ * headed for the main track goes to a new track right above it. An insert makes room there instead,+ * pushing what follows on, on the tracks they go in on (with linkage, what rides on the main track along). Null when a+ * track it goes onto is locked or gone.*/export function pasteEdit(clipboard: readonly TimelineClipboardItem[],@@ -257,7 +202,7 @@ export function pasteEdit(model: EditModel,atMs: number,forceLane: string | null,- opts: Follow & ({ mode: EditMode } | { magnet: boolean }),+ opts: { mode: 'place' | 'insert' } & Partial<Switches>,): Op[] | null {if (!clipboard.length) return [];const base = Math.min(...clipboard.map((item) => item.startMs));@@ -270,95 +215,65 @@ export function pasteEdit(});if (spans.some((s) => s.track == null || s.locked)) return null;const links = copyLinks(clipboard.map((item) => item.clipId), model);- const insertOf = (s: Pick<(typeof spans)[number], 'item' | 'startMs'>, track: TrackDest): Op => ({+ if (opts.mode === 'place') {+ return placeCopies(model, spans.map((s) => ({+ from: s.item.clipId, startMs: s.startMs, endMs: s.endMs, dest: s.track!, source: s.track!,+ })), links, opts.magnet ? mainTrackOf(model) : null).ops;+ }+ const insertOf = (s: (typeof spans)[number]): Op => ({op: 'insert',from: s.item.clipId,at: s.startMs / 1000,- track,+ track: s.track!,...(links.has(s.item.clipId) ? { link: links.get(s.item.clipId)! } : {}),});- if ('mode' in opts || !opts.magnet) {- const mode = 'mode' in opts ? opts.mode : 'overwrite';- const room = planRoom(model, spans.map((s) => ({ track: s.track!, startMs: s.startMs, endMs: s.endMs })), { mode, sync: opts.sync, linkage: opts.linkage });- return [...spans.map((s) => insertOf(s, s.track!)), ...room.ops];- }- /* the magnet, as CapCut's: a paste covers nothing and pushes nothing — a copy whose time is taken goes to a free- track, else a new one (above the main track for a copy from it). On the main track only past its end, closed up */- const main = mainTrackOf(model);- const mainEnd = Math.max(0, ...(model.find((t) => t.index === main)?.clips ?? []).map((c) => c.endMs));- const taken: { track: number; startMs: number; endMs: number }[] = [];- const placed = spans.map((s) => {- if (s.track === main && s.startMs >= mainEnd - TOUCH_MS) {- const at = { ...s, startMs: mainEnd, endMs: mainEnd + s.item.durMs };- return { s: at, track: main as TrackDest };- }- const track = freeTrackFor(model, s.track!, s, taken);- if (typeof track === 'number') taken.push({ track, startMs: s.startMs, endMs: s.endMs });- return { s, track };- });- /* new tracks last, the lowest place first, so the places of the others hold while they open */- const opened = placed.filter((p) => typeof p.track === 'object')- .sort((x, y) => (y.track as { insert: number }).insert - (x.track as { insert: number }).insert);- return [- ...placed.filter((p) => typeof p.track === 'number').map((p) => insertOf(p.s, p.track)),- ...opened.map((p) => insertOf(p.s, p.track)),- ];+ /* the copies go in first, so a clip pasted inside itself is copied whole before the insert cuts it */+ const room = planRoom(model, spans.map((s) => ({ track: s.track!, startMs: s.startMs, endMs: s.endMs })), { ...opts, mode: 'insert' });+ return [...spans.map(insertOf), ...room.ops];}/**- * Copies of clips put down where a drag lets them go (⌥-drag, as CapCut's): the clips stay, a copy of each lands- * `deltaMs` later (earlier when negative) on its track or the one in `to`. As a paste does with the magnet: onto the- * main track an insert at the insert point under the hand (what follows moves on, with linkage what rides on it);- * off it nothing is covered, a copy whose time is taken going to a free track or a new one. Without the magnet a copy- * covers what is under it. Copies of clips linked together are linked to each other. Null when a track it goes onto- * is locked.+ * Copies of clips put down where a drag lets them go (⌥-drag): the clips stay, a copy of each lands+ * `deltaMs` later (earlier when negative) on its track or the one in `to`, never cutting what is there (placeCopies).+ * With the magnet, when the grabbed one's copy goes onto the main track, the copies headed there go in end to end at+ * the insert point under the hand (`pointerMs`), what follows moving on. Copies of clips linked together are linked to+ * each other. `placed`: where each copy lands, by the clip it copies. Null when a track it goes onto is locked.*/export function planCopies(model: EditModel,- spec: Follow & { ids: readonly string[]; deltaMs: number; pointerMs: number; to?: ReadonlyMap<string, TrackDest>; magnet: boolean },+ spec: { ids: readonly string[]; deltaMs: number; to?: ReadonlyMap<string, TrackDest>; pointerMs?: number } & Partial<Switches>,): EditPlan | null {const clips = model.flatMap((t) => t.clips.map((c) => ({ c, track: t.index })));const picked = spec.ids.flatMap((id) => clips.filter((x) => x.c.id === id));if (!picked.length) return null;- const main = mainTrackOf(model);- const lead = picked[0]!;- const offset = Math.max(spec.deltaMs, -Math.min(...picked.map((x) => x.c.startMs)));- /* the group keeps its shape; on the main track its first clip goes in at the insert point under the hand, whichever- is in hand */- const leadDest = spec.to?.get(lead.c.id) ?? lead.track;- const firstMs = Math.min(...picked.map((x) => x.c.startMs));- let shift = offset;- if (spec.magnet && leadDest === main) shift = insertPointOn(model, main, spec.pointerMs, firstMs + offset) - firstMs;- const spans = picked.map(({ c, track }) => {+ /* the group keeps its shape; none goes before 0 */+ const shift = Math.max(spec.deltaMs, -Math.min(...picked.map((x) => x.c.startMs)));+ const spans = picked.map(({ c, track }): CopySpan => {const startMs = Math.max(0, c.startMs + shift);- return { id: c.id, startMs, endMs: startMs + c.endMs - c.startMs, dest: spec.to?.get(c.id) ?? (track as TrackDest) };+ return { from: c.id, startMs, endMs: startMs + c.endMs - c.startMs, dest: spec.to?.get(c.id) ?? track, source: track };});if (spans.some((s) => typeof s.dest === 'number' && model.find((t) => t.index === s.dest)?.locked)) return null;- const onMain = spec.magnet ? spans.filter((s) => s.dest === main) : [];- const covering = spec.magnet ? [] : spans.filter((s) => typeof s.dest === 'number');- const room = onMain.length- ? planRoom(model, onMain.map((s) => ({ track: s.dest as number, startMs: s.startMs, endMs: s.endMs })), { mode: 'insert', sync: spec.sync, linkage: spec.linkage })- : covering.length- ? planRoom(model, covering.map((s) => ({ track: s.dest as number, startMs: s.startMs, endMs: s.endMs })), { mode: 'overwrite', sync: spec.sync, linkage: spec.linkage })- : { ops: [], placed: new Map(), shortMs: 0 };- const taken: { track: number; startMs: number; endMs: number }[] = [];- const placed = spans.map((s) => {- if (typeof s.dest !== 'number' || !spec.magnet || s.dest === main) return { s, track: s.dest };- const track = freeTrackFor(model, s.dest, s, taken);- if (typeof track === 'number') taken.push({ track, startMs: s.startMs, endMs: s.endMs });- return { s, track };- });const links = copyLinks(spec.ids, model);- const insertOf = ({ s, track }: (typeof placed)[number]): Op => ({- op: 'insert', from: s.id, at: Math.round(s.startMs) / 1000, track,- ...(links.has(s.id) ? { link: links.get(s.id)! } : {}),- });- /* the copies on tracks there are first; new tracks last, the lowest place first, so the places hold */- const opened = placed.filter((p) => typeof p.track === 'object')- .sort((x, y) => (y.track as { insert: number }).insert - (x.track as { insert: number }).insert);- return {- ops: [...placed.filter((p) => typeof p.track === 'number').map(insertOf), ...room.ops, ...opened.map(insertOf)],- placed: room.placed,- shortMs: room.shortMs,- };+ const main = mainTrackOf(model);+ const lead = spans[0]!;+ if (!(spec.magnet && main != null && lead.dest === main && magnetOn(model, main, true))) {+ const { ops, placed } = placeCopies(model, spans, links, spec.magnet ? main : null);+ return { ops, placed, shortMs: 0 };+ }+ /* onto the main track with the magnet: in end to end at the insert point, what follows (and rides on it) moving on */+ const going = spans.filter((s) => s.dest === main).sort((a, b) => a.startMs - b.startMs);+ let at = insertPointOn(model, main, spec.pointerMs ?? lead.startMs, lead.startMs);+ const inserts: Op[] = [];+ const placed = new Map<string, Placed>();+ const startAt = at;+ for (const s of going) {+ const len = s.endMs - s.startMs;+ inserts.push({ op: 'insert', from: s.from, at: Math.round(at) / 1000, track: main, ...(links.has(s.from) ? { link: links.get(s.from)! } : {}) });+ placed.set(s.from, { startMs: at, endMs: at + len, track: main });+ at += len;+ }+ const room = planRoom(model, [{ track: main, startMs: startAt, endMs: at }], { mode: 'insert', magnet: spec.magnet, linkage: spec.linkage });+ const rest = placeCopies(model, spans.filter((s) => s.dest !== main), links, main);+ for (const [id, p] of rest.placed) placed.set(id, p);+ return { ops: [...inserts, ...room.ops, ...rest.ops], placed, shortMs: room.shortMs };}diff --git a/packages/openfilm/studio/ui/src/lib/timeline-drag.test.ts b/packages/openfilm/studio/ui/src/lib/timeline-drag.test.tsindex 541d65a..8df702c 100644--- a/packages/openfilm/studio/ui/src/lib/timeline-drag.test.ts+++ b/packages/openfilm/studio/ui/src/lib/timeline-drag.test.ts@@ -170,23 +170,14 @@ test('a left edge pulled all the way out reaches the start of the source exactlyassert.deepEqual(edits.map((e) => [e.prop, e.value]), [['at', 2.74], ['start', 0]]);});-test('a press becomes a drag past the threshold: a click on a cut (a few px of jitter) is not a roll', () => {- assert.equal(dragLifted('roll', 3, 0), false);- assert.equal(dragLifted('roll', -4, 2), false);- assert.equal(dragLifted('roll', 5, 0), true);- assert.equal(dragLifted('roll', 0, 12), false, 'a roll only goes sideways');+test('a press becomes a drag past the threshold: a click (a few px of jitter) is not a move', () => {assert.equal(dragLifted('move', 0, 5), true, 'a move lifts up to another row');assert.equal(dragLifted('move', 4, 4), false);+ assert.equal(dragLifted('move', -5, 0), true);assert.equal(dragLifted('trim-end', 1, 0), true, 'an edge follows at once');- assert.equal(dragLifted('slip', 4, 0), false);});-/* a clip let go onto a neighbor on its own track goes in between (as an editor's main track does), never cuts it */-test('a move onto another clip of its track inserts; into free room it stays put; ⌥ the other way', () => {- assert.equal(moveEditMode({ magnet: false, alt: false, overlaps: true }), 'insert');- assert.equal(moveEditMode({ magnet: false, alt: false, overlaps: false }), 'overwrite');- assert.equal(moveEditMode({ magnet: false, alt: true, overlaps: true }), 'overwrite');- assert.equal(moveEditMode({ magnet: false, alt: true, overlaps: false }), 'insert');- assert.equal(moveEditMode({ magnet: true, alt: false, overlaps: false }), 'insert');- assert.equal(moveEditMode({ magnet: true, alt: true, overlaps: true }), 'overwrite');+test('a move is put down without cutting what is there; with ⌥ it goes in between', () => {+ assert.equal(moveEditMode(false), 'place');+ assert.equal(moveEditMode(true), 'insert');});diff --git a/packages/openfilm/studio/ui/src/lib/timeline-drag.ts b/packages/openfilm/studio/ui/src/lib/timeline-drag.tsindex 89c2483..1cd0b5a 100644--- a/packages/openfilm/studio/ui/src/lib/timeline-drag.ts+++ b/packages/openfilm/studio/ui/src/lib/timeline-drag.ts@@ -2,7 +2,7 @@* The arithmetic of dragging on the timeline: pixels to time, what to snap to, where to land.** Kept apart because a drag is dozens of pointer moves and a wrong step in any of them only feels "a bit off"; as pure- * functions they are easy to pin down. Following mature editors (OpenCut):+ * functions they are easy to pin down:* · a 5 px threshold: without one, clicking a clip is a zero-length drag that writes the same value back;* · snapping measured in screen pixels, not milliseconds, so it feels the same at every zoom;* · a clip never snaps to itself, or it could not move at all.@@ -13,13 +13,11 @@ import { snapToFrame } from './timecode.ts';export const DRAG_THRESHOLD_PX = 5;/**- * Whether a press `dx`, `dy` px along has become a drag. A move lifts in either direction (up to another row); a roll,- * a slip and a slide past the threshold sideways, so a click on a cut is a click (its transitions), not a roll; a- * trimmed edge follows at once.+ * Whether a press `dx`, `dy` px along has become a drag. A move lifts past the threshold in either direction (up to+ * another row), so a click on a clip is a click; a trimmed edge follows at once.*/-export function dragLifted(mode: 'move' | 'trim-start' | 'trim-end' | 'roll' | 'slip' | 'slide', dx: number, dy: number): boolean {+export function dragLifted(mode: DragMode, dx: number, dy: number): boolean {if (mode === 'move') return Math.abs(dx) >= DRAG_THRESHOLD_PX || Math.abs(dy) >= DRAG_THRESHOLD_PX;- if (mode === 'roll' || mode === 'slip' || mode === 'slide') return Math.abs(dx) >= DRAG_THRESHOLD_PX;return Math.abs(dx) >= 1;}@@ -438,7 +436,7 @@ export function marqueeHits(* Which track a dragged clip lands on.** A track has no kind (SPEC): any clip goes on any track. Onto a row it goes to that row's track, whatever is on it- * there: the edit mode decides what happens to what it lands on (an insert pushes it on, an overwrite cuts it out).+ * there: the edit mode decides what happens where it lands (put down, a taken spot opens a track; an insert pushes on).* Above or below every row it opens a new track there, the one gesture that does. Clips never swap.*/export type TrackDrop =@@ -463,14 +461,11 @@ export interface DropLane {}/**- * How a move is put down. The magnet decides (insert: it goes in between and what follows moves along; overwrite: it- * covers what is there), ⌥ held the other way. But a clip let go onto another clip of its own track goes in between- * with the magnet off too, as an editor's main track does: dropped on a neighbor it means "put it here", never "cut the- * neighbor"; ⌥ still overwrites then. Let go in free room, it stays where it was put. `overlaps`: the clip, where it- * would land (flush against a neighbor if it looks flush), covers part of another clip on its own track.+ * How a move is put down: where it is let go, never cutting what is there (a taken spot opens a track beside it, see+ * newTrackSide); with ⌥ held it goes in between and what follows moves along (an insert).*/-export function moveEditMode({ magnet, alt, overlaps }: { magnet: boolean; alt: boolean; overlaps: boolean }): 'insert' | 'overwrite' {- return (magnet || overlaps) !== alt ? 'insert' : 'overwrite';+export function moveEditMode(alt: boolean): 'insert' | 'place' {+ return alt ? 'insert' : 'place';}export function rangeOverlaps(@@ -481,12 +476,12 @@ export function rangeOverlaps(}/**- * Where a track that has to be opened goes: right after its source, one row down. The new track grew out of that one- * (a copied page belongs next to its original), and badges count top to bottom, so inserting after renames no track- * above — "my P1" stays P1.+ * Where a track opened beside a taken one goes (film.html place): away from V1 and A1, the way the badges count+ * (filmTrackBadges). A picture or page track opens right above it, so what is put there shows over what it was put+ * on; a sound track right below it. Either way the track pointed at keeps its badge.*/-export function newTrackSide(fromDocIndex: number): number {- return fromDocIndex + 1;+export function newTrackSide(docIndex: number, role?: string): number {+ return role === 'audio' ? docIndex + 1 : docIndex;}/**@@ -551,8 +546,8 @@ export interface GroupLaneShift {/*** Where a selection moved up or down lands.*- * One degree of freedom: the whole group moves the same number of rows, keeping the shape the user made (Premiere /- * Resolve do the same). Only the rows asked for are tried. Any track takes any clip; a track a clip moves to must be+ * One degree of freedom: the whole group moves the same number of rows, keeping the shape the user made. Only the+ * rows asked for are tried. Any track takes any clip; a track a clip moves to must be* unlocked. What is already on a track where a clip lands is the edit mode's to settle (insert or overwrite); the* landings themselves may not overlap each other: clips on one track do not overlap (SPEC).*/diff --git a/packages/openfilm/studio/ui/src/lib/timeline-edit.test.ts b/packages/openfilm/studio/ui/src/lib/timeline-edit.test.tsindex a8955ae..fb71121 100644--- a/packages/openfilm/studio/ui/src/lib/timeline-edit.test.ts+++ b/packages/openfilm/studio/ui/src/lib/timeline-edit.test.ts@@ -8,9 +8,8 @@ import {gapAt,gapsOf,insertPointOn,- hostOf,linkedIds,- magnetOn,+ hostOf,mainTrackOf,planCloseGap,planCloseMainGaps,@@ -25,7 +24,6 @@ import {planSpeed,planUnlink,ridesOn,- rollMoves,soundTrackFor,sourceLeftMs,type EditClip,@@ -96,45 +94,40 @@ function apart(tracks: [string, number, number][][]): void {/* ── delete ── */-test('a ripple delete closes the gap on its track only, without sync lock', () => {- const m = model([['a', 0, 2], ['b', 2, 5], ['c', 5, 7]], [['vo', 4, 8]]);- const out = after(m, planRemove(m, ['b'], { ripple: true, sync: false }));- assert.deepEqual(out, [[['a', 0, 2], ['c', 2, 4]], [['vo', 4, 8]]]);+test('a plain delete leaves the gap, on every track', () => {+ const m = model([['a', 0, 2], ['b', 2, 5], ['c', 5, 7]], [['vo', 6, 8]]);+ assert.deepEqual(after(m, planRemove(m, ['b'], { ripple: false })), [[['a', 0, 2], ['c', 5, 7]], [['vo', 6, 8]]]);});-test('with sync lock a ripple delete moves the other tracks too, never a locked one', () => {+test('a ripple delete closes the gap on its own track; the other tracks stay (they follow only by linkage)', () => {const m = model([['a', 0, 2], ['b', 2, 5], ['c', 5, 7]], [['vo', 6, 8]], { locked: true, clips: [['bed', 5, 9]] });- const plan = planRemove(m, ['b'], { ripple: true, sync: true });- assert.deepEqual(after(m, plan), [[['a', 0, 2], ['c', 2, 4]], [['vo', 3, 5]], [['bed', 5, 9]]]);+ const plan = planRemove(m, ['b'], { ripple: true });+ assert.deepEqual(after(m, plan), [[['a', 0, 2], ['c', 2, 4]], [['vo', 6, 8]], [['bed', 5, 9]]]);assert.equal(plan.shortMs, 0);});-test('a clip on a synced track in the way stops the ripple short, so nothing comes apart', () => {- /* the B-roll covers 3–4.5 s and the next clip on its track starts at 6: everything after 5 s can only move back- 1.5 s, on every track */- const m = model([['a', 0, 2], ['b', 2, 5], ['c', 5, 7]], [['broll', 3, 4.5], ['late', 6, 7]]);- const plan = planRemove(m, ['b'], { ripple: true, sync: true });- const out = after(m, plan);- assert.deepEqual(out, [[['a', 0, 2], ['c', 3.5, 5.5]], [['broll', 3, 4.5], ['late', 4.5, 5.5]]]);- assert.equal(plan.shortMs, 1500);- apart(out);-});--test('a plain delete leaves the gap', () => {- const m = model([['a', 0, 2], ['b', 2, 5], ['c', 5, 7]]);- assert.deepEqual(after(m, planRemove(m, ['b'], { ripple: false, sync: true })), [[['a', 0, 2], ['c', 5, 7]]]);+test('a ripple delete leaves a clip that starts before the cut where it is: a music bed under it stays', () => {+ const m = model({ role: 'video', clips: [['a', 0, 2], ['b', 2, 5], ['c', 5, 7]] }, { role: 'audio', clips: [['bed', 0, 9]] });+ assert.deepEqual(after(m, planRemove(m, ['b'], { ripple: true })), [[['a', 0, 2], ['c', 2, 4]], [['bed', 0, 9]]]);});test('linked clips are found by their link, and deleted together', () => {const m = model([['v', 0, 4, { link: 'v' }], ['w', 4, 6]], [['v-a', 0, 4, { link: 'v' }], ['x', 4, 5]]);assert.deepEqual(linkedIds(m, ['v']).sort(), ['v', 'v-a']);- const out = after(m, planRemove(m, linkedIds(m, ['v']), { ripple: true, sync: true }));+ const out = after(m, planRemove(m, linkedIds(m, ['v']), { ripple: true }));assert.deepEqual(out, [[['w', 0, 2]], [['x', 0, 1]]]);});+test('clips deleted on several tracks at once close up on each of their tracks', () => {+ const m = model([['t1', 0, 1], ['t2', 5, 6], ['t3', 7, 8]], [['a', 0, 2], ['b', 2, 3], ['c', 3, 9]]);+ const out = after(m, planRemove(m, ['b', 't2'], { ripple: true }));+ assert.deepEqual(out, [[['t1', 0, 1], ['t3', 6, 7]], [['a', 0, 2], ['c', 2, 8]]]);+ apart(out);+});+test('deleting the clips of a locked track does nothing to them', () => {const m = model({ locked: true, clips: [['a', 0, 2], ['b', 2, 4]] });- assert.deepEqual(planRemove(m, ['a'], { ripple: true, sync: true }).ops, []);+ assert.deepEqual(planRemove(m, ['a'], { ripple: true }).ops, []);});/* ── gaps ── */@@ -147,28 +140,32 @@ test('a gap is the empty time between clips, or before the first; not after theassert.equal(gapAt(m, 0, 6000), null);});-test('closing a gap moves what is after it back, on every unlocked track with sync lock', () => {+test('closing a gap moves what is after it back on its track', () => {const m = model([['a', 0, 2], ['b', 4, 5]], [['vo', 4, 6]], { locked: true, clips: [['bed', 4, 9]] });const gap = gapAt(m, 0, 3000)!;- assert.deepEqual(after(m, planCloseGap(m, 0, gap, { sync: true })), [[['a', 0, 2], ['b', 2, 3]], [['vo', 2, 4]], [['bed', 4, 9]]]);- assert.deepEqual(after(m, planCloseGap(m, 0, gap, { sync: false })), [[['a', 0, 2], ['b', 2, 3]], [['vo', 4, 6]], [['bed', 4, 9]]]);+ assert.deepEqual(after(m, planCloseGap(m, 0, gap)), [[['a', 0, 2], ['b', 2, 3]], [['vo', 4, 6]], [['bed', 4, 9]]]);/* a gap on a locked track stays */const locked = model({ locked: true, clips: [['a', 0, 2], ['b', 4, 5]] });- assert.deepEqual(planCloseGap(locked, 0, gap, { sync: true }).ops, []);+ assert.deepEqual(planCloseGap(locked, 0, gap).ops, []);});-test('a gap a synced track has no room for still closes, on its own track alone', () => {- /* the gap before the first clip on the top track ends at 4.6 s, where a clip on the track below is playing and- the next starts right after it: a synced ripple could not move at all */+test('a gap closes whole on its track, however little room another track has', () => {+ /* the gap before the first clip on the top track ends at 4.6 s, where a title below plays on to 5 s and the next+ follows right after it: the top track closes up, the title track has no room and stays */const m = model([['top', 4.6, 9.6]], [['title', 0, 5], ['cards', 5, 10]], [['bed', 0, 15]]);const gap = gapAt(m, 0, 1000)!;assert.deepEqual(gap, { startMs: 0, endMs: 4600 });- const plan = planCloseGap(m, 0, gap, { sync: true });- assert.equal(plan.alone, true);+ const plan = planCloseGap(m, 0, gap);assert.equal(plan.shortMs, 0);assert.deepEqual(after(m, plan), [[['top', 0, 5]], [['title', 0, 5], ['cards', 5, 10]], [['bed', 0, 15]]]);- /* with room on every track, sync lock is kept */- assert.equal(planCloseGap(model([['a', 0, 2], ['b', 4, 5]], [['vo', 4, 6]]), 0, { startMs: 2000, endMs: 4000 }, { sync: true }).alone, undefined);+});++test('all the gaps on a track closed at once, on that track', () => {+ const m = model([['t1', 1, 2], ['t2', 4, 5]], [['a', 0, 3], ['b', 3, 6]], [['vo', 4.5, 5]]);+ assert.deepEqual(gapsOf(m, 0), [{ startMs: 0, endMs: 1000 }, { startMs: 2000, endMs: 4000 }]);+ const out = after(m, planCloseTrackGaps(m, 0));+ assert.deepEqual(out, [[['t1', 0, 1], ['t2', 1, 2]], [['a', 0, 3], ['b', 3, 6]], [['vo', 4.5, 5]]]);+ assert.deepEqual(planCloseTrackGaps(m, 1).ops, [], 'no gap on the picture track');});test('how much source a clip can still show at each edge', () => {@@ -180,193 +177,54 @@ test('how much source a clip can still show at each edge', () => {assert.equal(sourceLeftMs(m, 'gone', 'end'), undefined);});-/* ── the main track and linkage (as CapCut) ── */--/* titles over the picture, the picture (the main track), music under it */-const film = (titles: Spec[], main: Spec[], music: Spec[] = []) => model(- { role: 'mg', clips: titles }, { role: 'video', clips: main }, { role: 'audio', clips: music },-);-const LINK = { sync: false, linkage: true } as const;--test('the main track is the lowest picture track; the magnet acts on it alone', () => {- const m = film([['t', 0, 1]], [['a', 0, 2]], [['bed', 0, 9]]);- assert.equal(mainTrackOf(m), 1);- assert.equal(magnetOn(m, 1, true), true);- assert.equal(magnetOn(m, 0, true), false);- assert.equal(magnetOn(m, 1, false), false);- assert.equal(mainTrackOf(model({ role: 'audio', clips: [] })), null);-});--test('a clip rides on the main-track clip its start falls in, or the last one after the end', () => {- const main = film([], [['a', 0, 2], ['b', 2, 5]])[1]!;- assert.equal(hostOf(main, { startMs: 2500 })?.id, 'b');- assert.equal(hostOf(main, { startMs: 2000 })?.id, 'b');- assert.equal(hostOf(main, { startMs: 7000 })?.id, 'b');- assert.equal(hostOf(film([], [['a', 1, 2]])[1]!, { startMs: 500 }), null);-});--test('with linkage a ripple delete on the main track carries the titles and sound after it, whatever is in the way', () => {- /* t2 sits over b, t3 over c; the bed runs under everything, so sync lock could not move at all */- const m = model(- { role: 'mg', clips: [['t2', 2.5, 3.5], ['t3', 5.5, 6.5]] },- { role: 'video', clips: [['a', 0, 2], ['b', 2, 5], ['c', 5, 7]] },- { role: 'audio', clips: [['bed', 0, 9]] },- { role: 'audio', clips: [['sfx', 5, 6]] },- );- const plan = planRemove(m, ['b'], { ripple: true, ...LINK });- assert.equal(plan.shortMs, 0);- /* t2 rode on b, which went: it goes with it. t3 moves back with c; the sound effect moves back; the bed spans the- cut and stays */- assert.deepEqual(after(m, plan), [[['t3', 2.5, 3.5]], [['a', 0, 2], ['c', 2, 4]], [['bed', 0, 9]], [['sfx', 2, 3]]]);- assert.equal(planRemove(m, ['b'], { ripple: true, sync: true }).shortMs, 1000);-});--test('with linkage what rides on a deleted main-track clip goes with it; a bed under several shots stays', () => {- const m = film([['ta', 0.5, 1.5], ['tb', 2.5, 3.5]], [['a', 0, 2], ['b', 2, 5], ['c', 5, 7]], [['bed', 0, 7]]);- assert.deepEqual(after(m, planRemove(m, ['b'], { ripple: 'main', ...LINK })), [[['ta', 0.5, 1.5]], [['a', 0, 2], ['c', 2, 4]], [['bed', 0, 7]]]);- /* without linkage the title stays */- assert.deepEqual(after(m, planRemove(m, ['b'], { ripple: 'main', sync: false }))[0], [['ta', 0.5, 1.5], ['tb', 2.5, 3.5]]);-});--test('linkage: a carried clip that runs into one that stayed goes to a free track above, else a new one', () => {- /* t1 rides on a (stays), t2 on b (moves back 2 s, onto t1) */- const m = film([['t1', 0.5, 1.8], ['t2', 2.5, 3.5]], [['a', 0, 1], ['x', 1, 2.5], ['b', 2.5, 5]]);- const out = after(m, planRemove(m, ['x'], { ripple: true, ...LINK }));- /* a new track opened above the titles takes t2; t1 stays on its own */- assert.deepEqual(out, [[['t2', 1, 2]], [['t1', 0.5, 1.8]], [['a', 0, 1], ['b', 1, 3.5]]]);- /* with a free title track above, it goes there */- const roomy = model({ role: 'mg', clips: [] }, { role: 'mg', clips: [['t1', 0.5, 1.8], ['t2', 2.5, 3.5]] }, { role: 'video', clips: [['a', 0, 1], ['x', 1, 2.5], ['b', 2.5, 5]] });- assert.deepEqual(after(roomy, planRemove(roomy, ['x'], { ripple: true, ...LINK })), [[['t2', 1, 2]], [['t1', 0.5, 1.8]], [['a', 0, 1], ['b', 1, 3.5]]]);-});--test('with the magnet a delete closes up the main track only; titles leave a gap', () => {- const m = film([['t1', 0, 1], ['t2', 1, 2], ['t3', 2, 3]], [['a', 0, 2], ['b', 2, 4], ['c', 4, 6]]);- const plan = planRemove(m, ['b', 't2'], { ripple: 'main', sync: false });- /* the title track keeps its gap where t2 was; c closes up (without linkage nothing else moves) */- assert.deepEqual(after(m, plan), [[['t1', 0, 1], ['t3', 2, 3]], [['a', 0, 2], ['c', 2, 4]]]);-});--test('with linkage a ripple trim of a main-track clip carries what comes after it, not what rides on it', () => {- /* the music's second clip starts right where its first ends, half a second after a's end */- const m = film([['ta', 0.5, 1], ['tb', 3, 4]], [['a', 0, 2], ['b', 2, 5]], [['m1', 0, 2.5], ['m2', 2.5, 9]]);- const plan = planRippleTrim(m, ['a'], 'end', -1000, LINK);- assert.equal(plan.deltaMs, -1000);- /* m1 starts over a and stays; m2 starts over b and moves back onto m1, so it goes to a new sound track below */- assert.deepEqual(after(m, plan), [[['ta', 0.5, 1], ['tb', 2, 3]], [['a', 0, 1], ['b', 1, 4]], [['m1', 0, 2.5]], [['m2', 1.5, 8]]]);- /* sync lock alone could not: the music is in the way */- assert.equal(planRippleTrim(m, ['a'], 'end', -1000, { sync: true }).deltaMs, 0);-});--test('with linkage an insert on the main track pushes what comes after on every track', () => {- const m = film([['tb', 3, 4]], [['a', 0, 2], ['b', 2, 5]], [['bed', 0, 9]]);- const plan = planRoom(m, [{ track: 1, startMs: 2000, endMs: 3000 }], { mode: 'insert', ...LINK });- assert.deepEqual(after(m, plan), [[['tb', 4, 5]], [['a', 0, 2], ['b', 3, 6]], [['bed', 0, 9]]]);-});--test('with linkage a main-track clip moved along the main track takes its titles along', () => {- /* b (2–5 s, its title at 3 s) goes to the front */- const m = film([['ta', 0.5, 1.5], ['tb', 3, 4]], [['a', 0, 2], ['b', 2, 5]]);- const plan = planMove(m, { ids: ['b'], deltaMs: -2000, pointerMs: 500, mode: 'insert', magnet: true, ...LINK })!;- const out = after(m, plan);- assert.deepEqual(out[1], [['b', 0, 3], ['a', 3, 5]]);- assert.deepEqual(out.flat().filter(([id]) => id.startsWith('t')).sort(), [['ta', 3.5, 4.5], ['tb', 1, 2]]);-});--test('linkage leaves a long clip crossing more than one cut where it is: a music bed is the film\'s, not a shot\'s', () => {- const main = film([], [['a', 0, 2], ['b', 2, 5], ['c', 5, 7]])[1]!;- assert.equal(ridesOn(main, { startMs: 0, endMs: 9000 }), false, 'under every shot');- assert.equal(ridesOn(main, { startMs: 1000, endMs: 3000 }), true, 'across one cut');- assert.equal(ridesOn(main, { startMs: 2500, endMs: 3500 }), true, 'inside a shot');- /* b moved to the front: its title goes with it, the bed under everything stays at 0 */- const m = film([['tb', 3, 4]], [['a', 0, 2], ['b', 2, 5], ['c', 5, 7]], [['bed', 0, 7]]);- const plan = planMove(m, { ids: ['b'], deltaMs: -2000, pointerMs: 500, mode: 'insert', magnet: true, ...LINK })!;- assert.deepEqual(after(m, plan), [[['tb', 1, 2]], [['b', 0, 3], ['a', 3, 5], ['c', 5, 7]], [['bed', 0, 7]]]);- /* an insert at the very start pushes the shots and their titles, not the bed */- const room = planRoom(m, [{ track: 1, startMs: 0, endMs: 1000 }], { mode: 'insert', ...LINK });- assert.deepEqual(after(m, room), [[['tb', 4, 5]], [['a', 1, 3], ['b', 3, 6], ['c', 6, 8]], [['bed', 0, 7]]]);-});--test('with the magnet a clip taken off the main track closes it up, wherever it lands', () => {- const m = film([], [['a', 0, 2], ['b', 2, 4], ['c', 4, 6]]);- const plan = planMove(m, { ids: ['b'], deltaMs: 0, pointerMs: 3000, to: new Map([['b', 0]]), mode: 'overwrite', magnet: true, ...LINK })!;- assert.deepEqual(after(m, plan), [[['b', 2, 4]], [['a', 0, 2], ['c', 2, 4]]]);- /* moved along a title track it closes nothing there */- const t = film([['t1', 0, 1], ['t2', 2, 3]], [['a', 0, 4]]);- const moved = planMove(t, { ids: ['t1'], deltaMs: 3000, pointerMs: 3500, mode: 'overwrite', magnet: true, ...LINK })!;- assert.deepEqual(after(t, moved), [[['t2', 2, 3], ['t1', 3, 4]], [['a', 0, 4]]]);-});--test('with the magnet clips moved together go in at the insert point by the first of them, whichever is in hand', () => {- /* b and c (a gap between them) in hand by c, dragged on past the end: back after a, the gap kept, a not cut */- const m = film([], [['a', 0, 10], ['b', 10, 20], ['c', 25, 30]]);- const plan = planMove(m, { ids: ['c', 'b'], deltaMs: 5000, pointerMs: 32_000, mode: 'insert', magnet: true, ...LINK })!;- assert.deepEqual(after(m, plan).flat(), [['a', 0, 10], ['b', 10, 20], ['c', 25, 30]]);- /* in hand by c, let go on a's first half: they go in before a */- const front = planMove(m, { ids: ['c', 'b'], deltaMs: -24_000, pointerMs: 2000, mode: 'insert', magnet: true, ...LINK })!;- assert.deepEqual(after(m, front).flat(), [['b', 0, 10], ['c', 15, 20], ['a', 20, 30]]);-});--test('with the magnet a clip let go on another off the main track covers nothing: it goes to a free track', () => {- /* two title tracks; t3 dragged onto t1's time on the lower one goes up to the free one */- const m = model({ role: 'mg', clips: [['t2', 4, 5]] }, { role: 'mg', clips: [['t1', 0, 2], ['t3', 3, 4]] }, { role: 'video', clips: [['a', 0, 6]] });- const plan = planMove(m, { ids: ['t3'], deltaMs: -2000, pointerMs: 1500, mode: 'overwrite', magnet: true, ...LINK })!;- assert.deepEqual(after(m, plan), [[['t3', 1, 2], ['t2', 4, 5]], [['t1', 0, 2]], [['a', 0, 6]]]);- /* no room anywhere: a new track above */- const full = model({ role: 'mg', clips: [['t1', 0, 2], ['t3', 3, 4]] }, { role: 'video', clips: [['a', 0, 6]] });- const opened = planMove(full, { ids: ['t3'], deltaMs: -2000, pointerMs: 1500, mode: 'overwrite', magnet: true, ...LINK })!;- assert.deepEqual(after(full, opened), [[['t3', 1, 2]], [['t1', 0, 2]], [['a', 0, 6]]]);- /* moved onto another track at the same time, onto a clip there: it is the one that goes, not the one there */- const across = model({ role: 'mg', clips: [['x', 1, 3]] }, { role: 'mg', clips: [['y', 0.5, 1.5]] }, { role: 'video', clips: [['a', 0, 6]] });- const moved = planMove(across, { ids: ['y'], deltaMs: 0, pointerMs: 1000, to: new Map([['y', 0]]), mode: 'overwrite', magnet: true, ...LINK })!;- assert.deepEqual(after(across, moved).flat().find(([id]) => id === 'x'), ['x', 1, 3]);- assert.deepEqual(after(across, moved)[0], [['x', 1, 3]]);-});-test('clips moved together to new tracks keep their rows: a new track per track they came from', () => {- /* a title and a shot dragged above every track */+ /* a title and a shot dragged above every track; the time the shot leaves stays open */const m = model({ role: 'mg', clips: [['t', 1, 3]] }, { role: 'video', clips: [['a', 0, 4], ['b', 4, 8]] });- const up = planMove(m, { ids: ['t', 'b'], deltaMs: 0, pointerMs: 2000, to: new Map([['t', { insert: 0 }], ['b', { insert: 0 }]]), mode: 'overwrite', magnet: true, ...LINK })!;- /* two new tracks on top, the title's above the shot's; b's place on the main track closes up */+ const up = planMove(m, { ids: ['t', 'b'], deltaMs: 0, pointerMs: 2000, to: new Map([['t', { insert: 0 }], ['b', { insert: 0 }]]), mode: 'overwrite' })!;assert.deepEqual(after(m, up), [[['t', 1, 3]], [['b', 4, 8]], [['a', 0, 4]]]);/* two clips of one track: one new track for both */const two = model({ role: 'mg', clips: [['t1', 0, 1], ['t2', 2, 3]] }, { role: 'video', clips: [['a', 0, 4]] });- const both = planMove(two, { ids: ['t1', 't2'], deltaMs: 0, pointerMs: 500, to: new Map([['t1', { insert: 0 }], ['t2', { insert: 0 }]]), mode: 'overwrite', magnet: true, ...LINK })!;+ const both = planMove(two, { ids: ['t1', 't2'], deltaMs: 0, pointerMs: 500, to: new Map([['t1', { insert: 0 }], ['t2', { insert: 0 }]]), mode: 'overwrite' })!;assert.deepEqual(after(two, both), [[['t1', 0, 1], ['t2', 2, 3]], [['a', 0, 4]]]);/* and below every track */- const down = planMove(m, { ids: ['t', 'b'], deltaMs: 0, pointerMs: 2000, to: new Map([['t', { insert: 2 }], ['b', { insert: 2 }]]), mode: 'overwrite', magnet: true, ...LINK })!;+ const down = planMove(m, { ids: ['t', 'b'], deltaMs: 0, pointerMs: 2000, to: new Map([['t', { insert: 2 }], ['b', { insert: 2 }]]), mode: 'overwrite' })!;assert.deepEqual(after(m, down), [[['a', 0, 4]], [['t', 1, 3]], [['b', 4, 8]]]);});-test('with linkage closing a gap on the main track always closes it whole', () => {- const m = film([['t', 3, 4]], [['a', 0, 2], ['b', 3, 5]], [['bed', 0, 9]]);- const gap = gapAt(m, 1, 2500)!;- const plan = planCloseGap(m, 1, gap, LINK);- assert.equal(plan.alone, undefined);- assert.deepEqual(after(m, plan), [[['t', 2, 3]], [['a', 0, 2], ['b', 2, 4]], [['bed', 0, 9]]]);- /* a gap on a title track closes on that track alone */- const g2 = gapAt(m, 0, 1000)!;- assert.deepEqual(after(m, planCloseGap(m, 0, g2, LINK)), [[['t', 0, 1]], [['a', 0, 2], ['b', 3, 5]], [['bed', 0, 9]]]);+test('a clip moved away leaves its time open; nothing else moves', () => {+ const m = model([['t1', 0, 1], ['t2', 2, 3]], [['a', 0, 2], ['b', 2, 4], ['c', 4, 6]]);+ const plan = planMove(m, { ids: ['b'], deltaMs: 0, pointerMs: 3000, to: new Map([['b', 0]]), mode: 'overwrite' })!;+ /* b lands on the title track over t2's time and covers it; c stays at 4 s */+ assert.deepEqual(after(m, plan), [[['t1', 0, 1], ['b', 2, 4]], [['a', 0, 2], ['c', 4, 6]]]);});-test('turning the magnet on closes up the main track, before its first clip too, carrying what rides on it', () => {- const m = film([['t', 6, 7]], [['a', 1, 3], ['b', 5, 8]], [['bed', 0, 9]]);- const plan = planCloseMainGaps(m, LINK);- assert.deepEqual(after(m, plan), [[['t', 3, 4]], [['a', 0, 2], ['b', 2, 5]], [['bed', 0, 9]]]);- assert.deepEqual(planCloseMainGaps(film([], [['a', 0, 2], ['b', 2, 4]]), LINK).ops, [], 'closed up already');- assert.deepEqual(planCloseMainGaps(model({ role: 'video', locked: true, clips: [['a', 1, 2]] }), LINK).ops, [], 'locked');+test('a clip put down on a taken spot goes to a new track right above it; nothing there is cut', () => {+ const m = model([['img', 0, 1], ['x', 5, 6]], [['v', 0, 10]]);+ const plan = planMove(m, { ids: ['img'], deltaMs: 3000, pointerMs: 3500, to: new Map([['img', 1]]), mode: 'place' })!;+ assert.deepEqual(after(m, plan), [[['x', 5, 6]], [['img', 3, 4]], [['v', 0, 10]]]);+ assert.deepEqual(plan.placed.get('img'), { startMs: 3000, endMs: 4000, track: { insert: 1 } });});-test('all the gaps on a track closed at once; on a title track only that track moves', () => {- const m = film([['t1', 1, 2], ['t2', 4, 5]], [['a', 0, 3], ['b', 3, 6]]);- assert.deepEqual(gapsOf(m, 0), [{ startMs: 0, endMs: 1000 }, { startMs: 2000, endMs: 4000 }]);- assert.deepEqual(after(m, planCloseTrackGaps(m, 0, LINK)), [[['t1', 0, 1], ['t2', 1, 2]], [['a', 0, 3], ['b', 3, 6]]]);- assert.deepEqual(planCloseTrackGaps(m, 1, LINK).ops, [], 'no gap on the main track');+test('a clip put down where the time is free lands on that track', () => {+ const m = model([['img', 0, 1], ['x', 5, 6]], [['v', 0, 2]]);+ const plan = planMove(m, { ids: ['img'], deltaMs: 3000, pointerMs: 3500, to: new Map([['img', 1]]), mode: 'place' })!;+ assert.deepEqual(after(m, plan), [[['x', 5, 6]], [['v', 0, 2], ['img', 3, 4]]]);+ /* touching a neighbor is not taking its time */+ const flush = model([['a', 0, 1], ['b', 3, 4]]);+ assert.deepEqual(after(flush, planMove(flush, { ids: ['a'], deltaMs: 2000, pointerMs: 2500, mode: 'place' })!), [[['a', 2, 3], ['b', 3, 4]]]);+});++test('a clip put down over its neighbor on its own track goes to a new track above', () => {+ const m = model([['a', 0, 2], ['b', 2, 4]]);+ const plan = planMove(m, { ids: ['a'], deltaMs: 1000, pointerMs: 2000, mode: 'place' })!;+ assert.deepEqual(after(m, plan), [[['a', 1, 3]], [['b', 2, 4]]]);});-test('with linkage a slower main-track clip pushes what comes after on every track', () => {- const m = film([['tb', 3, 4]], [['a', 0, 2], ['b', 2, 5]], [['bed', 0, 9]]);- const plan = planSpeed(m, ['a'], 0.5, { ripple: true, ...LINK });- assert.deepEqual(after(m, plan), [[['tb', 5, 6]], [['a', 0, 4], ['b', 4, 7]], [['bed', 0, 9]]]);+test('clips put down together: only those whose spot is taken open a track', () => {+ /* a picture and its sound: the picture lands on x, the sound in free time */+ const m = model([['v', 0, 2, { link: 'v' }], ['x', 5, 9]], [['s', 0, 2, { link: 'v' }], ['y', 10, 12]]);+ const plan = planMove(m, { ids: ['v', 's'], deltaMs: 4000, pointerMs: 5000, mode: 'place' })!;+ assert.deepEqual(after(m, plan), [[['v', 4, 6]], [['x', 5, 9]], [['s', 4, 6], ['y', 10, 12]]]);});/* ── insert and overwrite ── */@@ -381,35 +239,35 @@ test('an insert goes before or after the clip under the hand, in a gap where itassert.equal(insertPointOn(m, 1, 4233, 4233), 0, 'the first clip on an empty track starts at 0');});-test('insert pushes what comes after on, cutting a clip the point falls inside; sync takes the other tracks along', () => {+test('insert pushes what comes after on, cutting a clip the point falls inside, on the track it goes in on', () => {const m = model([['a', 0, 4], ['b', 4, 6]], [['vo', 1, 3], ['vo2', 5, 6]], { locked: true, clips: [['bed', 5, 9]] });- const plan = planRoom(m, [{ track: 0, startMs: 2000, endMs: 3000 }], { mode: 'insert', sync: true });+ const plan = planRoom(m, [{ track: 0, startMs: 2000, endMs: 3000 }], { mode: 'insert' });const out = after(m, plan);/* a is cut at 2 s: its rest a-b goes on with b, a second later */assert.deepEqual(out[0], [['a', 0, 2], ['a-b', 3, 5], ['b', 5, 7]]);- /* vo spans the point on another track: it stays whole, what is after it moves */- assert.deepEqual(out[1], [['vo', 1, 3], ['vo2', 6, 7]]);+ /* another track stays as it is */+ assert.deepEqual(out[1], [['vo', 1, 3], ['vo2', 5, 6]]);assert.deepEqual(out[2], [['bed', 5, 9]]);assert.deepEqual(timeOf(m, plan, 'a-b'), [2, 4], 'the rest plays on from where the cut was');});test('overwrite takes the time off a track: trims, removes, cuts what spans it, leaves no slivers', () => {const m = model([['a', 0, 3], ['b', 3, 4], ['c', 4, 9]]);- const out = after(m, planRoom(m, [{ track: 0, startMs: 2000, endMs: 5000 }], { mode: 'overwrite', sync: true }));+ const out = after(m, planRoom(m, [{ track: 0, startMs: 2000, endMs: 5000 }], { mode: 'overwrite' }));assert.deepEqual(out, [[['a', 0, 2], ['c', 5, 9]]]);const span = model([['a', 0, 10]]);- const plan = planRoom(span, [{ track: 0, startMs: 2000, endMs: 3000 }], { mode: 'overwrite', sync: true });+ const plan = planRoom(span, [{ track: 0, startMs: 2000, endMs: 3000 }], { mode: 'overwrite' });assert.deepEqual(after(span, plan), [[['a', 0, 2], ['a-b', 3, 10]]]);assert.deepEqual(timeOf(span, plan, 'a-b'), [3, 10]);/* 10 ms left of a clip is not a shot */const sliver = model([['a', 0, 2.01]]);- assert.deepEqual(after(sliver, planRoom(sliver, [{ track: 0, startMs: 0, endMs: 2000 }], { mode: 'overwrite', sync: true })), [], 'the track went with it');+ assert.deepEqual(after(sliver, planRoom(sliver, [{ track: 0, startMs: 0, endMs: 2000 }], { mode: 'overwrite' })), [], 'the track went with it');});test('room is never made on a locked track', () => {const m = model({ locked: true, clips: [['a', 0, 3]] });- assert.deepEqual(planRoom(m, [{ track: 0, startMs: 1000, endMs: 2000 }], { mode: 'overwrite', sync: true }).ops, []);- assert.deepEqual(planRoom(m, [{ track: 0, startMs: 1000, endMs: 2000 }], { mode: 'insert', sync: true }).ops, []);+ assert.deepEqual(planRoom(m, [{ track: 0, startMs: 1000, endMs: 2000 }], { mode: 'overwrite' }).ops, []);+ assert.deepEqual(planRoom(m, [{ track: 0, startMs: 1000, endMs: 2000 }], { mode: 'insert' }).ops, []);});/* ── moving ── */@@ -420,7 +278,7 @@ test('an overwrite also cuts the sound linked to what it covers, on its own trac[['s', 0, 6, { link: 'v' }], ['bed', 7, 9]],{ locked: true, clips: [['vo', 0, 6, { link: 'v' }]] },);- const plan = planRoom(m, [{ track: 0, startMs: 2000, endMs: 4000 }], { mode: 'overwrite', sync: true });+ const plan = planRoom(m, [{ track: 0, startMs: 2000, endMs: 4000 }], { mode: 'overwrite' });const film = applyOps(filmOf(m) as never, plan.ops as never) as unknown as FilmValue;const shown = film.tracks.map((t) => t.clips.map((c) => [c.id, r3(c.at ?? 0), c.attrs?.['data-link'] ?? null]).sort((a, b) => Number(a[1]) - Number(b[1])));/* both cut in two; the right halves linked to each other, not to the left ones; the locked track untouched */@@ -431,25 +289,25 @@ test('an overwrite also cuts the sound linked to what it covers, on its own trac]);/* a sound not linked keeps its time */const free = model([['v', 0, 6]], [['s', 0, 6]]);- assert.deepEqual(after(free, planRoom(free, [{ track: 0, startMs: 2000, endMs: 4000 }], { mode: 'overwrite', sync: true })), [[['v', 0, 2], ['v-b', 4, 6]], [['s', 0, 6]]]);+ assert.deepEqual(after(free, planRoom(free, [{ track: 0, startMs: 2000, endMs: 4000 }], { mode: 'overwrite' })), [[['v', 0, 2], ['v-b', 4, 6]], [['s', 0, 6]]]);});test('a half cut alone by an insert is linked to nothing', () => {const m = model([['v', 0, 6, { link: 'v' }]], [['s', 0, 2, { link: 'v' }]]);- const plan = planRoom(m, [{ track: 0, startMs: 3000, endMs: 4000 }], { mode: 'insert', sync: false });+ const plan = planRoom(m, [{ track: 0, startMs: 3000, endMs: 4000 }], { mode: 'insert' });const film = applyOps(filmOf(m) as never, plan.ops as never) as unknown as FilmValue;assert.deepEqual(film.tracks[0]!.clips.map((c) => [c.id, c.attrs?.['data-link'] ?? null]), [['v', 'v'], ['v-b', null]]);});test('a move in overwrite mode over a picture cuts its linked sound too', () => {const m = model([['a', 0, 2], ['v', 4, 8, { link: 'v' }]], [['s', 4, 8, { link: 'v' }]]);- const plan = planMove(m, { ids: ['a'], deltaMs: 4000, pointerMs: 5000, mode: 'overwrite', sync: true })!;+ const plan = planMove(m, { ids: ['a'], deltaMs: 4000, pointerMs: 5000, mode: 'overwrite' })!;assert.deepEqual(after(m, plan), [[['a', 4, 6], ['v', 6, 8]], [['s', 6, 8]]]);});test('a move in overwrite mode lands where it was let go and cuts what is under it', () => {const m = model([['a', 0, 2]], [['x', 0, 5]]);- const plan = planMove(m, { ids: ['a'], deltaMs: 1000, pointerMs: 2000, to: new Map([['a', 1]]), mode: 'overwrite', sync: true })!;+ const plan = planMove(m, { ids: ['a'], deltaMs: 1000, pointerMs: 2000, to: new Map([['a', 1]]), mode: 'overwrite' })!;const out = after(m, plan);assert.deepEqual(out, [[['a', 1, 3], ['x', 0, 1], ['x-b', 3, 5]]].map((t) => t.sort((p, q) => p[1] - q[1])));apart(out);@@ -458,10 +316,10 @@ test('a move in overwrite mode lands where it was let go and cuts what is undertest('a move in insert mode reorders: lifted out, the gap closes, in before or after the clip under the hand', () => {const m = model([['a', 0, 2], ['b', 2, 4], ['c', 4, 6]]);/* a grabbed in its middle (1 s) and let go over the second half of b (3.5 s) */- const plan = planMove(m, { ids: ['a'], deltaMs: 2500, pointerMs: 3500, mode: 'insert', sync: true })!;+ const plan = planMove(m, { ids: ['a'], deltaMs: 2500, pointerMs: 3500, mode: 'insert' })!;assert.deepEqual(after(m, plan), [[['b', 0, 2], ['a', 2, 4], ['c', 4, 6]]]);/* over the first half of b: back where it was, nothing to write */- const none = planMove(m, { ids: ['a'], deltaMs: 1500, pointerMs: 2500, mode: 'insert', sync: true })!;+ const none = planMove(m, { ids: ['a'], deltaMs: 1500, pointerMs: 2500, mode: 'insert' })!;assert.deepEqual(none.ops, []);});@@ -471,7 +329,7 @@ test('an insert move takes its linked sound along and keeps the other tracks in[['a1', 0, 2, { link: 'v1' }], ['vo', 2.5, 3.5]],);/* v1 with its sound, moved after v2 */- const plan = planMove(m, { ids: ['v1', 'a1'], deltaMs: 2000, pointerMs: 3500, mode: 'insert', sync: true })!;+ const plan = planMove(m, { ids: ['v1', 'a1'], deltaMs: 2000, pointerMs: 3500, mode: 'insert' })!;const out = after(m, plan);assert.deepEqual(out, [[['v2', 0, 2], ['v1', 2, 4]], [['vo', 0.5, 1.5], ['a1', 2, 4]]]);apart(out);@@ -479,13 +337,13 @@ test('an insert move takes its linked sound along and keeps the other tracks intest('a move onto a locked track, or off one, is refused', () => {const m = model([['a', 0, 2]], { locked: true, clips: [['x', 4, 5]] });- assert.equal(planMove(m, { ids: ['a'], deltaMs: 0, pointerMs: 0, to: new Map([['a', 1]]), mode: 'overwrite', sync: true }), null);- assert.equal(planMove(m, { ids: ['x'], deltaMs: 1000, pointerMs: 4000, mode: 'overwrite', sync: true }), null);+ assert.equal(planMove(m, { ids: ['a'], deltaMs: 0, pointerMs: 0, to: new Map([['a', 1]]), mode: 'overwrite' }), null);+ assert.equal(planMove(m, { ids: ['x'], deltaMs: 1000, pointerMs: 4000, mode: 'overwrite' }), null);});test('a move to a new track opens it; an insert move still closes the gap it leaves', () => {const m = model([['a', 0, 2], ['b', 2, 4]]);- const plan = planMove(m, { ids: ['a'], deltaMs: 0, pointerMs: 1000, to: new Map([['a', { insert: 0 }]]), mode: 'insert', sync: true })!;+ const plan = planMove(m, { ids: ['a'], deltaMs: 0, pointerMs: 1000, to: new Map([['a', { insert: 0 }]]), mode: 'insert' })!;assert.deepEqual(after(m, plan), [[['a', 0, 2]], [['b', 0, 2]]]);});@@ -507,21 +365,6 @@ test('a trim stops at the end of its source and at the shortest clip', () => {assert.equal(planEdges(m, [{ id: 'v', kind: 'end' }], -9000).deltaMs, -3900);});-test('a roll moves the cut: one clip longer, the next shorter, the film the same length', () => {- const m = model([['a', 0, 4, { sourceMs: 10_000 }], ['b', 4, 8, { inMs: 2000 }], ['c', 8, 9]]);- const plan = planEdges(m, rollMoves(m, 'a', 'b', false), 1000);- assert.deepEqual(after(m, plan), [[['a', 0, 5], ['b', 5, 8], ['c', 8, 9]]]);- assert.deepEqual(timeOf(m, plan, 'b'), [3, 6], 'b starts a second later in its source');- /* back as far as b has source before its in point */- assert.equal(planEdges(m, rollMoves(m, 'a', 'b', false), -3000).deltaMs, -2000);-});--test('a roll takes linked cuts along', () => {- const m = model([['a', 0, 4, { link: 'x' }], ['b', 4, 8, { link: 'y', inMs: 2000 }]], [['as', 0, 4, { link: 'x' }], ['bs', 4, 8, { link: 'y', inMs: 2000 }]]);- const out = after(m, planEdges(m, rollMoves(m, 'a', 'b', true), 500));- assert.deepEqual(out, [[['a', 0, 4.5], ['b', 4.5, 8]], [['as', 0, 4.5], ['bs', 4.5, 8]]]);-});-test('a slip changes what a clip shows, not where or how long, inside its source', () => {const m = model([['v', 2, 4, { inMs: 3000, sourceMs: 6000 }]]);const plan = planEdges(m, [{ id: 'v', kind: 'slip' }], 1000);@@ -534,58 +377,46 @@ test('a slip changes what a clip shows, not where or how long, inside its source/* ── ripple trims ── */-test('a ripple trim of the tail moves what follows, on every synced track', () => {+test('a ripple trim of the tail moves what follows on its own track alone', () => {const m = model([['a', 0, 4], ['b', 4, 6]], [['vo', 5, 6]], { locked: true, clips: [['bed', 4, 9]] });- const plan = planRippleTrim(m, ['a'], 'end', -1000, { sync: true });+ const plan = planRippleTrim(m, ['a'], 'end', -1000);assert.equal(plan.deltaMs, -1000);- assert.deepEqual(after(m, plan), [[['a', 0, 3], ['b', 3, 5]], [['vo', 4, 5]], [['bed', 4, 9]]]);- const longer = planRippleTrim(m, ['a'], 'end', 1500, { sync: false });+ assert.deepEqual(after(m, plan), [[['a', 0, 3], ['b', 3, 5]], [['vo', 5, 6]], [['bed', 4, 9]]]);+ const longer = planRippleTrim(m, ['a'], 'end', 1500);assert.deepEqual(after(m, longer), [[['a', 0, 5.5], ['b', 5.5, 7.5]], [['vo', 5, 6]], [['bed', 4, 9]]]);});-test('a ripple trim stops where a synced track has no room', () => {- /* vo spans the cut and vo2 follows it right away: nothing on that track can move back */- const m = model([['a', 0, 4], ['b', 4, 6]], [['vo', 3.5, 5], ['vo2', 5, 6]]);- const plan = planRippleTrim(m, ['a'], 'end', -2000, { sync: true });- assert.equal(plan.deltaMs, 0);- assert.deepEqual(plan.ops, []);- const room = model([['a', 0, 4], ['b', 4, 6]], [['vo', 2, 3], ['vo2', 4.5, 5]]);- const some = planRippleTrim(room, ['a'], 'end', -2000, { sync: true });- assert.equal(some.deltaMs, -1500);- apart(after(room, some));-});-test('a ripple trim of the head keeps the clip where it starts', () => {const m = model([['a', 1, 5, { inMs: 2000 }], ['b', 5, 6]]);- const plan = planRippleTrim(m, ['a'], 'start', 1000, { sync: true });+ const plan = planRippleTrim(m, ['a'], 'start', 1000);assert.deepEqual(after(m, plan), [[['a', 1, 4], ['b', 4, 5]]]);assert.deepEqual(timeOf(m, plan, 'a'), [3, 6]);/* pulled out: as far as the source goes */- assert.equal(planRippleTrim(m, ['a'], 'start', -5000, { sync: true }).deltaMs, -2000);+ assert.equal(planRippleTrim(m, ['a'], 'start', -5000).deltaMs, -2000);});test('Q and W trim to the playhead and close up', () => {const m = model([['a', 0, 4], ['b', 4, 6]], [['vo', 4, 5]]);- assert.deepEqual(after(m, planRippleTrimTo(m, ['a'], 'start', 1000, { sync: true })!), [[['a', 0, 3], ['b', 3, 5]], [['vo', 3, 4]]]);- assert.deepEqual(after(m, planRippleTrimTo(m, ['a'], 'end', 1000, { sync: false })!), [[['a', 0, 1], ['b', 1, 3]], [['vo', 4, 5]]]);- assert.equal(planRippleTrimTo(m, ['a'], 'end', 5000, { sync: true }), null, 'the playhead is not over it');+ assert.deepEqual(after(m, planRippleTrimTo(m, ['a'], 'start', 1000)!), [[['a', 0, 3], ['b', 3, 5]], [['vo', 4, 5]]]);+ assert.deepEqual(after(m, planRippleTrimTo(m, ['a'], 'end', 1000)!), [[['a', 0, 1], ['b', 1, 3]], [['vo', 4, 5]]]);+ assert.equal(planRippleTrimTo(m, ['a'], 'end', 5000), null, 'the playhead is not over it');});/* ── speed ── */-test('slower in magnetic mode pushes what follows; otherwise it says how slow it can go', () => {+test('slower with a ripple pushes what follows on its track; without, it says how slow it can go', () => {const m = model([['a', 0, 2], ['b', 3, 4]], [['vo', 3, 4]]);- const pushed = planSpeed(m, ['a'], 0.5, { ripple: true, sync: true });- assert.deepEqual(after(m, pushed), [[['a', 0, 4], ['b', 5, 6]], [['vo', 5, 6]]]);- const held = planSpeed(m, ['a'], 0.5, { ripple: false, sync: true });+ const pushed = planSpeed(m, ['a'], 0.5, { ripple: true });+ assert.deepEqual(after(m, pushed), [[['a', 0, 4], ['b', 5, 6]], [['vo', 3, 4]]]);+ const held = planSpeed(m, ['a'], 0.5, { ripple: false });assert.deepEqual(held.ops, []);assert.equal(held.slowest, 0.67);- assert.deepEqual(after(m, planSpeed(m, ['a'], 0.8, { ripple: false, sync: true })), [[['a', 0, 2.5], ['b', 3, 4]], [['vo', 3, 4]]]);+ assert.deepEqual(after(m, planSpeed(m, ['a'], 0.8, { ripple: false })), [[['a', 0, 2.5], ['b', 3, 4]], [['vo', 3, 4]]]);});test('linked clips get the speed together', () => {const m = model([['v', 0, 2, { link: 'v' }]], [['s', 0, 2, { link: 'v' }], ['x', 3, 4]]);- const out = after(m, planSpeed(m, ['v', 's'], 2, { ripple: true, sync: true }));+ const out = after(m, planSpeed(m, ['v', 's'], 2, { ripple: true }));assert.deepEqual(out, [[['v', 0, 1]], [['s', 0, 1], ['x', 2, 3]]]);});@@ -638,6 +469,107 @@ test('the model joins a track spread over rows and leaves out drops not writtenassert.deepEqual(m[0]!.clips.map((c) => [c.inMs, c.speed, c.sourceMs, c.link ?? null]), [[1500, 1, 9000, 'L'], [1500, 2, 9000, null]]);});+/* ── the main track: magnet and linkage ── */++const ON = { magnet: true, linkage: true };+/** A title track, the main track (the lowest picture track), a music bed and a sound effect. */+const filmWithMain = () => model(+ { role: 'mg', clips: [['title', 5, 7], ['logo', 9, 10]] },+ { role: 'video', clips: [['a', 0, 4], ['b', 4, 8], ['c', 8, 12]] },+ { role: 'audio', clips: [['bed', 0, 12]] },+ { role: 'audio', clips: [['sfx', 5, 6]] },+);++test('the main track is the lowest picture track; what rides on it starts over one of its clips', () => {+ const m = filmWithMain();+ assert.equal(mainTrackOf(m), 1);+ const main = m[1]!;+ assert.equal(hostOf(main, { startMs: 5000 })?.id, 'b');+ assert.ok(ridesOn(main, { startMs: 5000, endMs: 7000 }), 'a title over b');+ assert.ok(!ridesOn(main, { startMs: 0, endMs: 12_000 }), 'a music bed under several shots stays put');+ assert.equal(hostOf(main, { startMs: 12_500 }), null, 'past the end of the main track nothing rides');+});++test('with the magnet a delete on the main track closes up; with linkage what rides on it goes too', () => {+ const m = filmWithMain();+ assert.deepEqual(after(m, planRemove(m, ['b'], { ripple: false, ...ON })), [+ [['logo', 5, 6]],+ [['a', 0, 4], ['c', 4, 8]],+ [['bed', 0, 12]],+ ]);+ /* without linkage the main track closes up and the rest stays */+ assert.deepEqual(after(m, planRemove(m, ['b'], { ripple: false, magnet: true, linkage: false })), [+ [['title', 5, 7], ['logo', 9, 10]],+ [['a', 0, 4], ['c', 4, 8]],+ [['bed', 0, 12]],+ [['sfx', 5, 6]],+ ]);+ /* without the magnet a gap is left; linkage still takes what rides on b */+ assert.deepEqual(after(m, planRemove(m, ['b'], { ripple: false, magnet: false, linkage: true })), [+ [['logo', 9, 10]],+ [['a', 0, 4], ['c', 8, 12]],+ [['bed', 0, 12]],+ ]);+});++test('a clip past the end of the main track rides on nothing: deleting the last shot leaves it be', () => {+ /* the bug behind removing the main track on 10-18: a leftover fragment on V1 dragged what came after it along */+ const m = model({ role: 'mg', clips: [['late', 3, 5]] }, { role: 'video', clips: [['frag', 0, 1]] });+ assert.deepEqual(after(m, planRemove(m, ['frag'], { ripple: false, ...ON })), [[['late', 3, 5]]]);+});++test('with the magnet a move along the main track reorders it; what rides on its clips goes with them', () => {+ const m = filmWithMain();+ /* c grabbed in its middle and let go over the first half of a */+ const plan = planMove(m, { ids: ['c'], deltaMs: -9000, pointerMs: 1000, mode: 'place', ...ON })!;+ assert.deepEqual(after(m, plan), [+ [['logo', 1, 2], ['title', 9, 11]],+ [['c', 0, 4], ['a', 4, 8], ['b', 8, 12]],+ [['bed', 0, 12]],+ [['sfx', 9, 10]],+ ]);+});++test('with the magnet a clip put on the main track goes in between; one taken off it closes up after it', () => {+ const m = model({ role: 'video', clips: [['ov', 20, 22]] }, { role: 'video', clips: [['a', 0, 4], ['b', 4, 8]] });+ /* the overlay onto the main track over the first half of b: in before b */+ const into = planMove(m, { ids: ['ov'], deltaMs: -15_000, pointerMs: 5000, to: new Map([['ov', 1]]), mode: 'place', ...ON })!;+ assert.deepEqual(after(m, into), [[['a', 0, 4], ['ov', 4, 6], ['b', 6, 10]]]);+ /* a taken up to the top track: the main track closes up behind it */+ const off = planMove(m, { ids: ['a'], deltaMs: 0, pointerMs: 1000, to: new Map([['a', 0]]), mode: 'place', ...ON })!;+ assert.deepEqual(after(m, off), [[['a', 0, 4], ['ov', 20, 22]], [['b', 0, 4]]]);+});++test('with linkage a ripple trim and a new speed on the main track keep what rides on its footage', () => {+ const m = filmWithMain();+ assert.deepEqual(after(m, planRippleTrim(m, ['a'], 'end', -1000, ON)), [+ [['title', 4, 6], ['logo', 8, 9]],+ [['a', 0, 3], ['b', 3, 7], ['c', 7, 11]],+ [['bed', 0, 12]],+ [['sfx', 4, 5]],+ ]);+ /* b twice as fast: the title a second into b goes half a second into it, c and its logo come 2 s earlier */+ assert.deepEqual(after(m, planSpeed(m, ['b'], 2, { ripple: true, ...ON })), [+ [['title', 4.5, 6.5], ['logo', 7, 8]],+ [['a', 0, 4], ['b', 4, 6], ['c', 6, 10]],+ [['bed', 0, 12]],+ [['sfx', 4.5, 5.5]],+ ]);+});++test('a clip linkage carries into another on its track goes to a free track nearby', () => {+ /* n crosses two cuts (it rides on nothing) and stays; r rides on c and lands on it once b is gone */+ const m = model({ role: 'mg', clips: [['n', 1.5, 4.5], ['r', 5.2, 5.8]] }, { role: 'video', clips: [['a', 0, 2], ['b', 2, 4], ['c', 4, 6]] });+ const out = after(m, planRemove(m, ['b'], { ripple: false, ...ON }));+ assert.deepEqual(out, [[['r', 3.2, 3.8]], [['n', 1.5, 4.5]], [['a', 0, 2], ['c', 2, 4]]]);+ apart(out);+});++test('turning the magnet on closes up the main track, what rides on it along', () => {+ const m = model({ role: 'mg', clips: [['t', 4.5, 5]] }, { role: 'video', clips: [['a', 1, 2], ['b', 4, 5]] });+ assert.deepEqual(after(m, planCloseMainGaps(m, ON)), [[['t', 1.5, 2]], [['a', 0, 1], ['b', 1, 2]]]);+});+/* ── every plan keeps the film whole ── */test('no plan makes two clips on a track overlap', () => {@@ -647,16 +579,16 @@ test('no plan makes two clips on a track overlap', () => {[['f', 0, 9]],);const plans: (EditPlan | null)[] = [- planRemove(m, ['b'], { ripple: true, sync: true }),- planRemove(m, ['d', 'b'], { ripple: true, sync: false }),- planRoom(m, [{ track: 1, startMs: 2000, endMs: 5000 }], { mode: 'insert', sync: true }),- planRoom(m, [{ track: 2, startMs: 2000, endMs: 5000 }], { mode: 'overwrite', sync: true }),- planMove(m, { ids: ['e'], deltaMs: -3000, pointerMs: 2000, to: new Map([['e', 0]]), mode: 'overwrite', sync: true }),- planMove(m, { ids: ['c'], deltaMs: -5000, pointerMs: 1000, mode: 'insert', sync: true }),- planMove(m, { ids: ['a'], deltaMs: 4000, pointerMs: 5000, to: new Map([['a', 1]]), mode: 'insert', sync: false }),- planRippleTrim(m, ['b'], 'end', 3000, { sync: true }),- planEdges(m, rollMoves(m, 'a', 'b', true), 2000),- planSpeed(m, ['d'], 0.25, { ripple: true, sync: true }),+ planRemove(m, ['b'], { ripple: true }),+ planRemove(m, ['d', 'b'], { ripple: true }),+ planRoom(m, [{ track: 1, startMs: 2000, endMs: 5000 }], { mode: 'insert' }),+ planRoom(m, [{ track: 2, startMs: 2000, endMs: 5000 }], { mode: 'overwrite' }),+ planMove(m, { ids: ['e'], deltaMs: -3000, pointerMs: 2000, to: new Map([['e', 0]]), mode: 'overwrite' }),+ planMove(m, { ids: ['c'], deltaMs: -5000, pointerMs: 1000, mode: 'insert' }),+ planMove(m, { ids: ['a'], deltaMs: 4000, pointerMs: 5000, to: new Map([['a', 1]]), mode: 'insert' }),+ planRippleTrim(m, ['b'], 'end', 3000),+ planEdges(m, [{ id: 'b', kind: 'end' }, { id: 'c', kind: 'start' }], 2000),+ planSpeed(m, ['d'], 0.25, { ripple: true }),];for (const plan of plans) apart(after(m, plan!));});diff --git a/packages/openfilm/studio/ui/src/lib/timeline-edit.ts b/packages/openfilm/studio/ui/src/lib/timeline-edit.tsindex 7f72a4b..73d8c6a 100644--- a/packages/openfilm/studio/ui/src/lib/timeline-edit.ts+++ b/packages/openfilm/studio/ui/src/lib/timeline-edit.ts@@ -1,24 +1,25 @@/**- * Edits that change more than one clip: insert and overwrite, ripple, roll, slip, closing gaps, speed, and- * linked clips. Each works on a plain model of the tracks (film ms, and each clip's own source ms) and comes back as- * the operations film.html takes (studio/server/ops.mjs), in one batch: one write, one undo step.+ * Edits that change more than one clip: insert and overwrite, ripple, slip, closing gaps, speed, the main track's+ * magnet and linkage, and linked clips. Each works on a plain model of the tracks (film ms, and each clip's own source+ * ms) and comes back as the operations film.html takes (studio/server/ops.mjs), in one batch: one write, one undo step.** Rules every edit here keeps:* · a locked track never changes;- * · clips on one track never overlap;- * · a ripple moves what comes after the edit point on the tracks it reaches: the clips' own tracks and, with sync- * lock, every unlocked track, so a voice-over or B-roll stays with the picture it belongs to. Time is closed only- * as far as every one of those tracks has room (`shortMs` says how much could not be), so they never come apart;- * · with linkage (CapCut's 联动) an edit of the main track (the lowest picture track) carries the clips on the- * other tracks with the main-track clips they start over (rides). A long clip crossing more than one cut there (a- * music bed) stays where it is. The main track alone limits it; a clip carried into another on its track goes to- * a free track nearby (settle).+ * · clips on one track never overlap, and nothing put down cuts what is there: where its time is taken a clip goes+ * to a new track beside (an overwrite, asked for, is the one exception);+ * · the main track (the lowest picture track) stays closed up with the magnet on: a clip put on it goes in between,+ * one deleted or taken off it closes up after it, a trim or a new speed there moves what follows on it;+ * · with linkage, a clip on another track that rides on a main-track clip (ridesOn) keeps the moment of that clip's+ * footage it starts at wherever the edit takes the footage, and goes with the clip when it is deleted; carried+ * into another clip on its track, it goes to a free track nearby;+ * · a ripple (a ripple delete, a closed gap, an insert, a ripple trim) moves what follows on the tracks edited+ * alone; other tracks follow only by linkage. `shortMs` says how much time could not be closed.** Pure: the timeline draws a plan's `placed` while the hand is still on a clip, and sends its `ops` on release.*/import type { Op, PropValue } from '../api.ts';import type { TimelineTrack } from './timeline-layout';-import { MIN_BLOCK_MS } from './timeline-drag.ts';+import { MIN_BLOCK_MS, newTrackSide } from './timeline-drag.ts';import { frameMs } from './timecode.ts';/** Clips closer than this are touching: film.html rounds each time alone, to the millisecond. */@@ -41,6 +42,11 @@ export interface EditClip {sourceMs: number;/** A picture: no source to trim into, any length; its in point stays 0. */still?: boolean;+ /**+ * A still's moment at its start, in ms into it as it was first placed (0 until an edit moves its head): what a clip+ * riding on it holds on to (linkage). The edit's own; never written.+ */+ vin?: number;/** Its `data-link`: clips sharing one move, trim, split and delete together. */link?: string;}@@ -59,11 +65,11 @@ export interface EditTrack {export type EditModel = readonly EditTrack[];/**- * What a ripple carries besides the tracks edited. `sync` (sync lock, as Premiere): every unlocked track, as far as- * all of them have room. `linkage` (as CapCut): an edit of the main track carries the clips on every other unlocked- * track. Sync lock wins when both are on.+ * The switches an edit is planned by (lib/timeline-prefs): `magnet` keeps the main track closed up, `linkage`+ * carries what rides on main-track clips with them. Both act on the main track alone.*/-export interface Follow { sync: boolean; linkage?: boolean }+export interface Switches { magnet: boolean; linkage: boolean }+export const NO_SWITCHES: Switches = { magnet: false, linkage: false };/** The main track: the lowest picture track (V1), film.html's last track that is not a sound track. */export function mainTrackOf(model: readonly Pick<EditTrack, 'index' | 'role'>[]): number | null {@@ -71,26 +77,20 @@ export function mainTrackOf(model: readonly Pick<EditTrack, 'index' | 'role'>[])return pictures.length ? Math.max(...pictures.map((t) => t.index)) : null;}-/** Whether the magnet acts on a track: it is CapCut's main-track magnet, so only on the main track. */+/** Whether the magnet acts on a track: the main track alone, unlocked, with the magnet on. */export function magnetOn(model: EditModel, track: number | null | undefined, magnet: boolean): boolean {- return magnet && track != null && track === mainTrackOf(model);+ return magnet && track != null && track === mainTrackOf(model) && !model.find((t) => t.index === track)?.locked;}-/**- * The main-track clip a clip rides on with linkage: the one its start falls in, or the last when it starts after the- * main track ends. None in a gap of the main track.- */+/** The main-track clip a clip starts over (none when it starts in a gap of the main track or past its end). */export function hostOf(main: Pick<EditTrack, 'clips'>, clip: { startMs: number }): EditClip | null {- const on = main.clips.find((c) => clip.startMs >= c.startMs - TOUCH_MS && clip.startMs < c.endMs - TOUCH_MS);- if (on) return on;- const last = [...main.clips].sort((a, b) => b.endMs - a.endMs)[0];- return last && clip.startMs >= last.endMs - TOUCH_MS ? last : null;+ return main.clips.find((c) => clip.startMs >= c.startMs - TOUCH_MS && clip.startMs < c.endMs - TOUCH_MS) ?? null;}/**- * Whether a clip rides on the main track with linkage: it has a host (hostOf) and crosses at most one cut of the main- * track — a title, a sticker, a sound effect, B-roll over a shot or two. A clip crossing more (a music bed under- * several shots) belongs to the film's time, not to a shot, and stays where it is.+ * Whether a clip rides on the main track with linkage: it starts over a main-track clip (hostOf) and crosses at most+ * one cut of the main track — a title, a sticker, a sound effect, B-roll over a shot or two. A clip crossing more (a+ * music bed under several shots) belongs to the film's time, not to a shot, and stays where it is.*/export function ridesOn(main: Pick<EditTrack, 'clips'>, clip: { startMs: number; endMs: number }): boolean {if (!hostOf(main, clip)) return false;@@ -163,10 +163,6 @@ export interface Draft {/** The right half cut off a clip, by the clip's id. */cut: Map<string, EditClip>;shortMs: number;- /** Linkage carried clips without asking their tracks for room: some may now run into another (see settle). */- settle?: boolean;- /** With linkage, the clips on other tracks that do not ride on the main track (ridesOn, as the film was). */- anchored?: Set<string>;}/**@@ -220,9 +216,10 @@ function find(d: Draft, id: string): { track: EditTrack; clip: EditClip } | nullreturn null;}-/** The head moved to `ms`: the in point follows (a still keeps 0). */+/** The head moved to `ms`: the in point follows (a still keeps 0, its moment moves: `vin`). */function setStart(c: EditClip, ms: number): void {if (!c.still) c.inMs = Math.max(0, c.inMs + (ms - c.startMs) * c.speed);+ else c.vin = (c.vin ?? 0) + (ms - c.startMs);c.startMs = ms;}@@ -231,36 +228,14 @@ function shiftClip(c: EditClip, ms: number): void {c.endMs += ms;}-/** The tracks a ripple reaches: those edited and, with sync lock, every other; never a locked one. */-function reach(d: Draft, edited: Iterable<number>, sync: boolean): number[] {- const set = new Set(sync ? d.tracks.map((t) => t.index) : edited);- return d.tracks.filter((t) => set.has(t.index) && !t.locked).map((t) => t.index);-}-/**- * The tracks a ripple moves (`tracks`) and those whose room limits it (`bound`): with sync lock every unlocked track- * both moves and limits; with linkage an edit of the main track moves every unlocked track, limited by the tracks- * edited alone; else just the tracks edited.+ * The tracks a ripple moves and those whose room limits it: the unlocked tracks edited, both (other tracks follow+ * only by linkage, see carry).*/-function follow(d: Draft, edited: Iterable<number>, opts: Follow): { tracks: number[]; bound: number[] } {- const own = reach(d, edited, false);- if (opts.sync) {- const all = reach(d, [], true);- return { tracks: all, bound: all };- }- const main = mainTrackOf(d.tracks);- if (opts.linkage && main != null && own.includes(main)) {- d.anchored ??= anchoredOf(d, main);- return { tracks: reach(d, [], true), bound: own };- }- return { tracks: own, bound: own };-}--/** The clips on other tracks that stay put with linkage (they do not ride on the main track as it was). */-function anchoredOf(d: Draft, main: number): Set<string> {- const was = [...d.before.values()];- const mainWas = { clips: was.filter((x) => x.track === main).map((x) => x.clip) };- return new Set(was.filter((x) => x.track !== main && !ridesOn(mainWas, x.clip)).map((x) => x.clip.id));+function follow(d: Draft, edited: Iterable<number>): { tracks: number[]; bound: number[] } {+ const own = new Set(edited);+ const tracks = d.tracks.filter((t) => !t.locked && own.has(t.index)).map((t) => t.index);+ return { tracks, bound: tracks };}/**@@ -279,8 +254,10 @@ function roomBefore(track: EditTrack, point: number, skip?: ReadonlySet<string>)}/**- * Move what starts at or after `point` by `deltaMs` on these tracks. Leftwards only as far as every track has room;- * the time that could not be closed is added to `shortMs`. Returns the shift made.+ * Move what starts at or after `point` by `deltaMs` on these tracks. Leftwards, the tracks in `bound` (those edited)+ * go only as far as every one of them has room, and the time that could not be closed is added to `shortMs`; each+ * other track goes as far as that, or as far as its own room allows. Returns the shift made on the bound tracks;+ * `moved`, when given, gets each track's.*/function rippleAt(d: Draft,@@ -289,11 +266,14 @@ function rippleAt(tracks: readonly number[],skip?: ReadonlySet<string>,bound: readonly number[] = tracks,+ moved?: Map<number, number>,): number {const rows = tracks.map((i) => trackAt(d, i)).filter((t): t is EditTrack => Boolean(t && !t.locked));const limits = rows.filter((t) => bound.includes(t.index));let amount = deltaMs;if (amount < 0) {+ /* nothing edited to close: nothing moves */+ if (!limits.length) return 0;const room = Math.min(...limits.map((t) => roomBefore(t, point, skip)));if (-amount > room) {d.shortMs += -amount - room;@@ -301,39 +281,30 @@ function rippleAt(}}if (!amount) return 0;- if (limits.length < rows.length) d.settle = true;for (const t of rows) {- /* the tracks carried along (linkage): what does not ride on the main track stays */- const still = limits.includes(t) ? undefined : d.anchored;+ const by = amount < 0 && !limits.includes(t) ? Math.max(amount, -roomBefore(t, point, skip)) : amount;+ if (!by) continue;+ moved?.set(t.index, by);for (const c of t.clips) {- if (!skip?.has(c.id) && !still?.has(c.id) && c.startMs >= point - TOUCH_MS) shiftClip(c, amount);+ if (!skip?.has(c.id) && c.startMs >= point - TOUCH_MS) shiftClip(c, by);}}return amount;}/**- * Close spans of time: per track its own (`byTrack`), or with sync lock all of them merged, on every track; with- * linkage, when the main track has spans, those, carrying every unlocked track. From the last span back, so closing- * one does not move the ones before it. Returns the shifts made, for mapping a time from before to after (see- * mapThrough).+ * Close spans of time taken off tracks (`byTrack`): each track its own, from its last span back, so closing one does+ * not move the ones before it. Returns the shifts made, for mapping a time from before to after (see mapThrough).*/-interface Shift { point: number; amount: number; tracks: readonly number[] }-function closeSpans(d: Draft, byTrack: ReadonlyMap<number, { startMs: number; endMs: number }[]>, opts: Follow): Shift[] {+interface Shift { point: number; byTrack: ReadonlyMap<number, number> }+function closeSpans(d: Draft, byTrack: ReadonlyMap<number, { startMs: number; endMs: number }[]>): Shift[] {const shifts: Shift[] = [];- const main = mainTrackOf(d.tracks);- const onMain = main != null ? byTrack.get(main) : undefined;- type Group = { spans: { startMs: number; endMs: number }[]; tracks: number[]; bound: number[] };- const groups: Group[] = opts.sync- ? [{ spans: [...byTrack.values()].flat(), ...follow(d, [], opts) }]- : opts.linkage && onMain && !trackAt(d, main!)?.locked- ? [{ spans: onMain, ...follow(d, [main!], opts) }]- : [...byTrack.entries()].map(([t, spans]) => ({ spans, ...follow(d, [t], { sync: false }) }));- for (const group of groups) {- if (!group.tracks.length) continue;- for (const span of mergeSpans(group.spans).reverse()) {- const amount = rippleAt(d, span.endMs, -(span.endMs - span.startMs), group.tracks, undefined, group.bound);- if (amount) shifts.push({ point: span.endMs, amount, tracks: group.tracks });+ for (const [track, spans] of byTrack) {+ if (!trackAt(d, track) || trackAt(d, track)!.locked) continue;+ for (const span of mergeSpans(spans).reverse()) {+ const moved = new Map<number, number>();+ rippleAt(d, span.endMs, -(span.endMs - span.startMs), [track], undefined, [track], moved);+ if (moved.size) shifts.push({ point: span.endMs, byTrack: moved });}}return shifts;@@ -353,9 +324,10 @@ function mergeSpans(spans: readonly { startMs: number; endMs: number }[]): { stafunction mapThrough(ms: number, track: number, shifts: readonly Shift[]): number {let at = ms;for (const s of shifts) {- if (!s.tracks.includes(track)) continue;- if (at >= s.point - TOUCH_MS) at += s.amount;- else if (s.amount < 0 && at > s.point + s.amount) at = s.point + s.amount;+ const amount = s.byTrack.get(track);+ if (!amount) continue;+ if (at >= s.point - TOUCH_MS) at += amount;+ else if (amount < 0 && at > s.point + amount) at = s.point + amount;}return at;}@@ -446,21 +418,36 @@ function relinkCuts(d: Draft): void {}}-/* ── the plan: what changed, as film.html's operations ── */+/* ── linkage: what rides on the main track ── */-const sec = (ms: number): number => Math.round(ms) / 1000;+/** A clip's moment of its footage at film ms `ms`: source ms, or for a still ms into it. */+const momentAt = (c: EditClip, ms: number): number => (+ c.still ? (c.vin ?? 0) + (ms - c.startMs) : c.inMs + (ms - c.startMs) * c.speed+);-/** The source end film.html writes (`#t=in,end`); a still's is its length. */-const writtenEnd = (c: EditClip): number => (c.still ? lenOf(c) : Math.min(srcEndOf(c), c.sourceMs));+/** Where on the film a clip shows a moment of its footage now; null when it does not show it (trimmed away). */+function filmAtMoment(c: EditClip, at: number): number | null {+ const ms = c.still ? c.startMs + (at - (c.vin ?? 0)) : c.startMs + (at - c.inMs) / c.speed;+ return ms >= c.startMs - TOUCH_MS && ms < c.endMs - TOUCH_MS ? ms : null;+}-/** The fields of a clip that changed from `was` to `now`, as ops.mjs's props take them. */-function changedFields(was: EditClip, now: EditClip): Record<string, PropValue> {- const out: Record<string, PropValue> = {};- if (Math.abs(now.startMs - was.startMs) >= 0.5) out.at = sec(Math.max(0, now.startMs));- if (!now.still && Math.abs(now.inMs - was.inMs) >= 0.5) out.start = sec(Math.max(0, now.inMs));- if (Math.abs(writtenEnd(now) - writtenEnd(was)) >= 0.5) out.end = sec(writtenEnd(now));- if (now.speed !== was.speed) out.speed = now.speed === 1 ? null : now.speed;- if ((now.link ?? null) !== (was.link ?? null)) out.link = now.link ?? null;+/** A clip riding on a main-track clip: which one, and the moment of its footage the rider starts at. */+export interface Ride { host: string; at: number }++/**+ * The clips riding on the main track as the film was (ridesOn), on unlocked tracks, but those in `skip` (the clips in+ * hand: they go where the hand puts them).+ */+function ridesOf(d: Draft, main: number | null, skip: ReadonlySet<string> = new Set()): Map<string, Ride> {+ const out = new Map<string, Ride>();+ if (main == null || trackAt(d, main)?.locked) return out;+ const was = [...d.before.values()];+ const mainWas = { clips: was.filter((x) => x.track === main).map((x) => x.clip) };+ for (const { clip, track } of was) {+ if (track === main || skip.has(clip.id) || trackAt(d, track)?.locked || !ridesOn(mainWas, clip)) continue;+ const host = hostOf(mainWas, clip)!;+ out.set(clip.id, { host: host.id, at: momentAt(host, clip.startMs) });+ }return out;}@@ -469,90 +456,95 @@ const overlap = (a: { startMs: number; endMs: number }, b: { startMs: number; en);/**- * Clips carried (linkage) or put (the magnet, off the main track) into another clip on their track go to another- * track: the one that moved goes, the one that stayed stays. Where: the nearest unlocked track of their kind with room- * (above for a picture, below for a sound), not the main track; else a new track opened beside theirs.+ * The riders put back on their moments after an edit: each goes where its main-track clip now shows the moment it+ * started at (with the clip, when the clip moved; after a cut, with the half that shows it). One whose clip is gone+ * goes too with `dropWithHost` (a delete), else stays; one whose moment is trimmed away stays. Riders carried into+ * another clip on their track go to a free track nearby (settle).*/-function settle(d: Draft): void {- const main = mainTrackOf(d.tracks);- const moved = (c: EditClip, on: EditTrack): boolean => {- const was = d.before.get(c.id);- return !was || was.track !== on.index || Math.abs(was.clip.startMs - c.startMs) >= 0.5;- };- const relocate = (from: EditTrack, c: EditClip): void => {- const free = nearestFree(d.tracks, from, c);- if (free) {- free.clips.push(c);- return;+function carry(d: Draft, rides: ReadonlyMap<string, Ride>, dropWithHost = false): void {+ if (!rides.size) return;+ const live = (c: EditClip | undefined): c is EditClip => Boolean(c && d.tracks.some((t) => t.clips.includes(c)));+ const moved = new Set<EditClip>();+ for (const [id, ride] of rides) {+ const at = find(d, id);+ if (!at || at.track.locked) continue;+ const pieces = [find(d, ride.host)?.clip, d.cut.get(ride.host)].filter(live);+ if (!pieces.length) {+ if (dropWithHost) at.track.clips.splice(at.track.clips.indexOf(at.clip), 1);+ continue;}- const insert = newTrackBeside(from);- d.opened.set(c.id, insert);- /* clips settled beside one track share a new one while they fit on it */- let n = 0;- let opened = openTrack(d, insert, `settle-${from.index}-${n}`, from.role);- while (opened.clips.some((x) => overlap(x, c))) opened = openTrack(d, insert, `settle-${from.index}-${++n}`, from.role);- opened.clips.push(c);- };+ let to: number | null = null;+ for (const p of pieces) if (to == null) to = filmAtMoment(p, ride.at);+ if (to == null || Math.abs(Math.max(0, to) - at.clip.startMs) < 0.5) continue;+ shiftClip(at.clip, Math.max(0, to) - at.clip.startMs);+ moved.add(at.clip);+ }+ if (moved.size) settle(d, moved);+}++/**+ * Clips an edit carried into another clip on their track (linkage) go to another track: the one carried goes, the+ * one that stayed stays. Where: the nearest unlocked track of their kind (picture or sound) with room, not the main+ * track; else a new track beside theirs (newTrackSide).+ */+function settle(d: Draft, moved: ReadonlySet<EditClip>): void {+ const main = mainTrackOf(d.tracks);for (const t of [...d.tracks]) {- if (t.index < 0 || t.index === main || t.locked) continue;+ if (t.index < 0 || t.locked || t.index === main) continue;const kept: EditClip[] = [];for (const c of [...t.clips].sort((a, b) => a.startMs - b.startMs)) {const hits = kept.filter((k) => overlap(k, c));- if (!hits.length) {- kept.push(c);- continue;- }- const go = moved(c, t) || hits.some((h) => !moved(h, t)) ? [c] : hits;- for (const x of go) {+ const going = moved.has(c) ? (hits.length ? [c] : []) : hits.filter((h) => moved.has(h));+ for (const x of going) {t.clips.splice(t.clips.indexOf(x), 1);if (kept.includes(x)) kept.splice(kept.indexOf(x), 1);- relocate(t, x);+ relocate(d, t, x, main);}- if (!go.includes(c)) kept.push(c);+ if (!going.includes(c)) kept.push(c);}}}-/**- * The nearest unlocked track of the same kind as `from` (sound or picture) with `span` free, not the main track and- * not `from`: above for a picture, below for a sound at the same distance. Undefined when none has room.- */-type Lane = Pick<EditTrack, 'index' | 'role' | 'locked'> & { clips: readonly { startMs: number; endMs: number }[] };-function nearestFree<T extends Lane>(tracks: readonly T[], from: Lane, span: { startMs: number; endMs: number }): T | undefined {- const main = mainTrackOf(tracks);- const sound = (t: Lane) => t.role === 'audio';- return tracks+function relocate(d: Draft, from: EditTrack, c: EditClip, main: number | null): void {+ const sound = (t: EditTrack) => t.role === 'audio';+ const free = d.tracks.filter((t) => t !== from && t.index >= 0 && t.index !== main && !t.locked && sound(t) === sound(from))- .filter((t) => !t.clips.some((x) => overlap(x, span)))+ .filter((t) => !t.clips.some((x) => overlap(x, c))).sort((a, b) => {const away = Math.abs(a.index - from.index) - Math.abs(b.index - from.index);return away || (sound(from) ? b.index - a.index : a.index - b.index);})[0];+ if (free) {+ free.clips.push(c);+ return;+ }+ const insert = newTrackSide(from.index, from.role);+ d.opened.set(c.id, insert);+ let n = 0;+ let opened = openTrack(d, insert, `settle-${from.index}-${n}`, from.role);+ while (opened.clips.some((x) => overlap(x, c))) opened = openTrack(d, insert, `settle-${from.index}-${++n}`, from.role);+ opened.clips.push(c);}-/** Where a track opened for a clip that found no room goes: above a picture track, below a sound track. */-const newTrackBeside = (from: Lane): number => (from.role === 'audio' ? from.index + 1 : from.index);+/* ── the plan: what changed, as film.html's operations ── */-/**- * Where a clip put on a track off the main track goes with the magnet, as CapCut's: covering nothing. That track- * when the time is free there, else the nearest free track of its kind (nearestFree), else a new track beside it.- * `taken`: what has been put already in the same edit (on existing tracks).- */-export function freeTrackFor(- model: EditModel,- track: number,- span: { startMs: number; endMs: number },- taken: readonly { track: number; startMs: number; endMs: number }[] = [],-): TrackDest {- const tracks: Lane[] = model.map((t) => ({ ...t, clips: [...t.clips, ...taken.filter((x) => x.track === t.index)] }));- const own = tracks.find((t) => t.index === track);- if (!own) return track;- if (!own.clips.some((c) => overlap(c, span))) return track;- return nearestFree(tracks, own, span)?.index ?? { insert: newTrackBeside(own) };+const sec = (ms: number): number => Math.round(ms) / 1000;++/** The source end film.html writes (`#t=in,end`); a still's is its length. */+const writtenEnd = (c: EditClip): number => (c.still ? lenOf(c) : Math.min(srcEndOf(c), c.sourceMs));++/** The fields of a clip that changed from `was` to `now`, as ops.mjs's props take them. */+function changedFields(was: EditClip, now: EditClip): Record<string, PropValue> {+ const out: Record<string, PropValue> = {};+ if (Math.abs(now.startMs - was.startMs) >= 0.5) out.at = sec(Math.max(0, now.startMs));+ if (!now.still && Math.abs(now.inMs - was.inMs) >= 0.5) out.start = sec(Math.max(0, now.inMs));+ if (Math.abs(writtenEnd(now) - writtenEnd(was)) >= 0.5) out.end = sec(writtenEnd(now));+ if (now.speed !== was.speed) out.speed = now.speed === 1 ? null : now.speed;+ if ((now.link ?? null) !== (was.link ?? null)) out.link = now.link ?? null;+ return out;}function planOf(d: Draft): EditPlan {- if (d.settle) settle(d);relinkCuts(d);const ops: Op[] = [];const edits: { clip: string; prop: string; value: PropValue }[] = [];@@ -616,7 +608,7 @@ function planOf(d: Draft): EditPlan {}/* the draft's own steps, for edits planned elsewhere (lib/transitions) */-export { draftOf, find as findInDraft, follow, planOf, reach, rippleAt, trackAt };+export { carry, draftOf, find as findInDraft, follow, planOf, ridesOf, rippleAt, trackAt };/** An edit that changes nothing. */export function emptyPlan(): EditPlan {@@ -683,24 +675,14 @@ export function gapAt(model: EditModel, track: number, ms: number): { startMs: nreturn endMs - startMs > TOUCH_MS ? { startMs, endMs } : null;}-/**- * Close a gap: what comes after it moves back, on its track and, with sync lock, every unlocked track. A gap picked- * is closed whole: when a synced track has no room for it (a clip there spans the gap's end), it closes on its own- * track alone, and `alone` says so.- */-export function planCloseGap(- model: EditModel,- track: number,- gap: { startMs: number; endMs: number },- opts: Follow,-): EditPlan & { alone?: boolean } {+/** Close a gap: what comes after it on its track moves back (a ripple; with linkage, what rides on it along). */+export function planCloseGap(model: EditModel, track: number, gap: { startMs: number; endMs: number }, sw: Switches = NO_SWITCHES): EditPlan {const d = draftOf(model);if (trackAt(d, track)?.locked) return emptyPlan();- closeSpans(d, new Map([[track, [gap]]]), opts);- if (!opts.sync || d.shortMs <= 0) return planOf(d);- const alone = draftOf(model);- closeSpans(alone, new Map([[track, [gap]]]), { sync: false });- return { ...planOf(alone), alone: true };+ const rides = sw.linkage ? ridesOf(d, mainTrackOf(model)) : new Map<string, Ride>();+ closeSpans(d, new Map([[track, [gap]]]));+ carry(d, rides);+ return planOf(d);}/** The gaps on a track: before its first clip and between clips (not after the last). */@@ -714,53 +696,52 @@ export function gapsOf(model: EditModel, track: number): { startMs: number; endMreturn spans;}-/**- * Every gap on a track closed (CapCut's "批量闭合空隙"), carrying what follows as a ripple does (sync lock, linkage on- * the main track). Nothing on a locked track.- */-export function planCloseTrackGaps(model: EditModel, track: number, opts: Follow): EditPlan {+/** Every gap on a track closed at once, as closing each does. Nothing on a locked track. */+export function planCloseTrackGaps(model: EditModel, track: number, sw: Switches = NO_SWITCHES): EditPlan {const spans = gapsOf(model, track);if (!spans.length || model.find((t) => t.index === track)?.locked) return emptyPlan();const d = draftOf(model);- closeSpans(d, new Map([[track, spans]]), opts);+ const rides = sw.linkage ? ridesOf(d, mainTrackOf(model)) : new Map<string, Ride>();+ closeSpans(d, new Map([[track, spans]]));+ carry(d, rides);return planOf(d);}-/** The main track closed up, as CapCut does when its magnet is turned on (planCloseTrackGaps on the main track). */-export function planCloseMainGaps(model: EditModel, opts: Follow): EditPlan {+/** The main track closed up, when its magnet is turned on (planCloseTrackGaps on the main track). */+export function planCloseMainGaps(model: EditModel, sw: Switches): EditPlan {const main = mainTrackOf(model);- return main == null ? emptyPlan() : planCloseTrackGaps(model, main, opts);+ return main == null ? emptyPlan() : planCloseTrackGaps(model, main, sw);}/* ── delete ── *//**- * Delete clips. With `ripple` the time they took closes after them (each track its own, or with sync lock all the- * deleted time on every unlocked track, or with linkage the main track's, carrying the other tracks); `'main'` closes- * only the main track's (the magnet), the others leave a gap; without, they all leave a gap. With linkage the clips- * riding on a deleted main-track clip go too. Clips on locked tracks stay.+ * Delete clips. Without `ripple` they leave a gap (a lift), but on the main track with the magnet, which closes up;+ * with it the time they took closes on each of their tracks (a ripple delete). With linkage what rides on a deleted+ * main-track clip goes with it, and what rides on the clips after it moves with them. Clips on locked tracks stay.*/-export function planRemove(model: EditModel, ids: readonly string[], opts: Follow & { ripple: boolean | 'main' }): EditPlan {+export function planRemove(model: EditModel, ids: readonly string[], opts: { ripple: boolean } & Partial<Switches>): EditPlan {const d = draftOf(model);const main = mainTrackOf(model);- /* with linkage what rides on a main-track clip goes with it, as CapCut's ("随着主轨移动、删除") */- const mainTrack = model.find((t) => t.index === main);- if (opts.linkage && !opts.sync && mainTrack && !mainTrack.locked) {- const gone = new Set(mainTrack.clips.filter((c) => ids.includes(c.id)).map((c) => c.id));- const riders = model.filter((t) => t !== mainTrack && !t.locked).flatMap((t) => t.clips)- .filter((c) => gone.size && ridesOn(mainTrack, c) && gone.has(hostOf(mainTrack, c)?.id ?? ''));- if (riders.length) ids = [...ids, ...riders.map((c) => c.id)];+ const rides = opts.linkage ? ridesOf(d, main, new Set(ids)) : new Map<string, Ride>();+ /* what rides on a deleted main-track clip goes with it (it moves and is deleted with the main track) */+ const deleted = new Set(ids);+ for (const [id, ride] of rides) {+ if (!deleted.has(ride.host)) continue;+ deleted.add(id);+ rides.delete(id);}const spans = new Map<number, { startMs: number; endMs: number }[]>();for (const t of d.tracks) {if (t.locked) continue;- const gone = t.clips.filter((c) => ids.includes(c.id));+ const gone = t.clips.filter((c) => deleted.has(c.id));if (!gone.length) continue;- t.clips = t.clips.filter((c) => !ids.includes(c.id));- if (opts.ripple === 'main' && t.index !== main) continue;+ t.clips = t.clips.filter((c) => !deleted.has(c.id));+ if (!opts.ripple && !(opts.magnet && t.index === main)) continue;spans.set(t.index, gone.map((c) => ({ startMs: c.startMs, endMs: c.endMs })));}- if (opts.ripple && spans.size) closeSpans(d, spans, opts);+ if (spans.size) closeSpans(d, spans);+ carry(d, rides);return planOf(d);}@@ -769,7 +750,7 @@ export function planRemove(model: EditModel, ids: readonly string[], opts: Folloexport type EditMode = 'insert' | 'overwrite';/**- * Where an insert goes on a track, as in CapCut's main track: over a clip, before it when over its first half and+ * Where an insert goes on a track: over a clip, before it when over its first half and* after it over the second; in a gap, where it was put (`atMs`, kept inside the gap); past the last clip, right after* it (so a first clip on an empty track starts at 0). `pointerMs` is where the hand is.*/@@ -786,17 +767,18 @@ export function insertPointOn(model: EditModel, track: number, pointerMs: number/*** Room for clips coming in, `durMs` long from `atMs`, on these tracks: an insert pushes what starts there on, on them- * and with sync lock on every unlocked track (a clip on them that `atMs` falls inside is cut there first, and its rest- * goes on with them); an overwrite takes that time off them. The clips themselves are the caller's (insert ops after- * these).+ * (a clip on them that `atMs` falls inside is cut there first, and its rest goes on with them; with linkage, what+ * rides on the main track goes along); an overwrite takes that time off them. The clips themselves are the caller's+ * (insert ops after these).*/export function planRoom(model: EditModel,spans: readonly { track: number; startMs: number; endMs: number }[],- opts: Follow & { mode: EditMode },+ opts: { mode: EditMode } & Partial<Switches>,): EditPlan {const d = draftOf(model);if (spans.some((s) => trackAt(d, s.track)?.locked)) return emptyPlan();+ const rides = opts.linkage ? ridesOf(d, mainTrackOf(model)) : new Map<string, Ride>();if (opts.mode === 'overwrite') {const dests = spans.map((s) => s.track);for (const s of spans) clearLinked(d, dests, s.startMs, s.endMs);@@ -804,6 +786,7 @@ export function planRoom(const track = trackAt(d, s.track);if (track) clearRange(d, track, s.startMs, s.endMs);}+ carry(d, rides);return planOf(d);}if (!spans.length) return planOf(d);@@ -815,14 +798,18 @@ export function planRoom(if (!track) continue;for (const c of [...track.clips]) cutAt(d, track, c, at);}- const f = follow(d, dests, opts);+ const f = follow(d, dests);rippleAt(d, at, durMs, f.tracks, undefined, f.bound);+ carry(d, rides);return planOf(d);}/* ── moving clips ── */-export interface MoveSpec {+/** How moved clips go down: `place` never touches what is there (a taken spot opens a track); see planMove. */+export type MoveMode = EditMode | 'place';++export interface MoveSpec extends Partial<Switches> {/** The clips in hand, the one grabbed first. */ids: readonly string[];/** How far they move in time (where they land, after snapping). */@@ -831,30 +818,25 @@ export interface MoveSpec {pointerMs: number;/** Clips going to another track (an index), or to a new one (`{ insert }`). The rest stay on theirs. */to?: ReadonlyMap<string, TrackDest>;- mode: EditMode;- sync: boolean;- linkage?: boolean;- /**- * The main-track magnet. Given, the time clips leave on the main track closes up when it is on (wherever they land),- * and the time they leave on other tracks stays open; an overwrite off the main track covers nothing then: a clip- * landing on another goes to a free track (settle), as CapCut's. Not given, an insert closes the time they leave- * everywhere and an overwrite covers what is there.- */- magnet?: boolean;+ mode: MoveMode;}/**- * Clips moved. Overwrite: they land where they were let go and take that time off the tracks they land on. Insert:- * they are lifted out (the time they took closes, as a ripple delete) and go in at the insert point of the track the- * grabbed one lands on, pushing what comes after on (as an insert). A new track takes them as they are. With linkage,- * main-track clips moved along the main track take the clips riding on them (hostOf) along.- * Null when a track it would change is locked.+ * Clips moved. Place: they land where they were let go; on a track where that time is taken they go instead to a new+ * track opened beside it (newTrackSide), so nothing there is cut or moved. Overwrite: they land where they were let go+ * and take that time off the tracks they land on. Insert (⌥): they are lifted out (the time they took closes on their+ * tracks) and go in at the insert point of the track the grabbed one lands on, pushing what comes after on.+ *+ * With the magnet, the main track stays closed up: the time clips leave on it closes, and clips the+ * grabbed one takes onto it go in end to end at the insert point there (a move along it reorders). With linkage what+ * rides on main-track clips stays on their footage (carry). A new track takes clips as they are. Null when a track it+ * would change is locked.*/export function planMove(model: EditModel, spec: MoveSpec): (EditPlan & { landMs: number }) | null {const d = draftOf(model);const ids = spec.ids.filter((id) => d.before.has(id));- const main = ids[0];- if (!main) return null;+ const lead = ids[0];+ if (!lead) return null;const hand = new Set(ids);const destOf = (id: string): TrackDest => spec.to?.get(id) ?? d.before.get(id)!.track;for (const id of ids) {@@ -862,21 +844,9 @@ export function planMove(model: EditModel, spec: MoveSpec): (EditPlan & { landMsif (trackAt(d, d.before.get(id)!.track)?.locked) return null;if (typeof dest === 'number' && (!trackAt(d, dest) || trackAt(d, dest)!.locked)) return null;}- /* with linkage, what rides on main-track clips that stay on the main track goes with them: taken off too */- const mainIndex = mainTrackOf(model);- const mainTrack = mainIndex != null ? trackAt(d, mainIndex) : undefined;- const riders = new Map<EditClip, { track: EditTrack; host: string }>();- if (spec.linkage && !spec.sync && mainTrack && !mainTrack.locked) {- const hosts = new Set(mainTrack.clips.filter((c) => hand.has(c.id) && destOf(c.id) === mainIndex).map((c) => c.id));- for (const t of d.tracks) {- if (t === mainTrack || t.locked || !hosts.size) continue;- for (const c of t.clips) {- const host = hand.has(c.id) || !ridesOn(mainTrack, c) ? null : hostOf(mainTrack, c);- if (host && hosts.has(host.id)) riders.set(c, { track: t, host: host.id });- }- }- for (const [c, r] of riders) r.track.clips.splice(r.track.clips.indexOf(c), 1);- }+ const main = mainTrackOf(model);+ const magnet = Boolean(spec.magnet) && magnetOn(model, main, true);+ const rides = spec.linkage ? ridesOf(d, main, hand) : new Map<string, Ride>();/* take them off their tracks */const lifted = new Map<string, EditClip>();const spans = new Map<number, { startMs: number; endMs: number }[]>();@@ -887,43 +857,79 @@ export function planMove(model: EditModel, spec: MoveSpec): (EditPlan & { landMs}t.clips = t.clips.filter((c) => !hand.has(c.id));}- const mainWas = d.before.get(main)!.clip;- const mainDest = destOf(main);- let landMs = Math.max(0, mainWas.startMs + spec.deltaMs);+ const leadWas = d.before.get(lead)!.clip;+ const leadDest = destOf(lead);+ let landMs = Math.max(0, leadWas.startMs + spec.deltaMs);/* the group keeps its shape; none goes before 0 */- const offset = (c: EditClip) => c.startMs - mainWas.startMs;+ const offset = (c: EditClip) => c.startMs - leadWas.startMs;const minOffset = Math.min(...[...lifted.values()].map(offset));landMs = Math.max(landMs, -minOffset);- /* an insert lifts them out: the time they took closes, as a ripple delete (with the magnet given: on the main- track, when it is on) */- const closing = spec.magnet === undefined- ? (spec.mode === 'insert' ? spans : null)- : spec.magnet && mainIndex != null && spans.has(mainIndex) ? new Map([[mainIndex, spans.get(mainIndex)!]]) : null;- const shifts = closing ? closeSpans(d, closing, spec) : [];- if (spec.mode === 'insert' && typeof mainDest === 'number') {- /* the insert point, worked out on the track as it was (where the hand is), then carried through the lift; the- first of them goes in there, whichever is in hand (the group keeps its shape after it) */- const point = insertPointOn(model, mainDest, spec.pointerMs, landMs + minOffset, hand);- landMs = Math.max(-minOffset, mapThrough(point, mainDest, shifts) - minOffset);- const starts = [...lifted.values()].map((c) => landMs + offset(c));- const at = Math.min(...starts);- const durMs = Math.max(...[...lifted.values()].map((c) => landMs + offset(c) + lenOf(c))) - at;- const dests = [...new Set(ids.map(destOf).filter((t): t is number => typeof t === 'number'))];+ /* the time they leave closes: with ⌥ on every track they left, with the magnet on the main track */+ const closing = spec.mode === 'insert' ? spans+ : magnet && spans.has(main!) ? new Map([[main!, spans.get(main!)!]]) : null;+ const shifts = closing ? closeSpans(d, closing) : [];+ /* they go in between, what follows moving on: with ⌥, or onto the main track with the magnet */+ const insertOn = typeof leadDest === 'number' && (spec.mode === 'insert' || (magnet && leadDest === main)) ? leadDest : null;+ /* onto the main track with the magnet, the clips going there go in end to end (it stays closed up) */+ const packed = insertOn != null && magnet && insertOn === main+ ? [...lifted.values()].filter((c) => destOf(c.id) === main).sort((a, b) => a.startMs - b.startMs)+ : [];+ const startOf = new Map<string, number>();+ const inserted = new Set<string>();+ if (insertOn != null) {+ /* the insert point, worked out on the track as it was (where the hand is), then carried through the lift */+ const point = insertPointOn(model, insertOn, spec.pointerMs, landMs + minOffset, hand);+ const at = Math.max(0, mapThrough(point, insertOn, shifts));+ if (packed.length) {+ let t = at;+ for (const c of packed) {+ startOf.set(c.id, t);+ inserted.add(c.id);+ t += lenOf(c);+ }+ landMs = startOf.get(lead)!;+ } else {+ landMs = Math.max(-minOffset, at - minOffset);+ for (const [id] of lifted) if (typeof destOf(id) === 'number') inserted.add(id);+ }+ const going = [...lifted.values()].filter((c) => inserted.has(c.id));+ const startsIn = going.map((c) => startOf.get(c.id) ?? landMs + offset(c));+ const roomAt = Math.min(...startsIn);+ const durMs = Math.max(...going.map((c, i) => startsIn[i]! + lenOf(c))) - roomAt;+ const dests = packed.length ? [main!] : [...new Set(going.map((c) => destOf(c.id) as number))];for (const index of dests) {const track = trackAt(d, index);- if (track) for (const c of [...track.clips]) cutAt(d, track, c, at);+ if (track) for (const c of [...track.clips]) cutAt(d, track, c, roomAt);}- const f = follow(d, dests, spec);- rippleAt(d, at, durMs, f.tracks, undefined, f.bound);+ const f = follow(d, dests);+ rippleAt(d, roomAt, durMs, f.tracks, undefined, f.bound);}/* put them down */- for (const [id, c] of lifted) {- const startMs = landMs + offset(c);+ for (const c of lifted.values()) {+ const startMs = startOf.get(c.id) ?? landMs + offset(c);c.endMs = startMs + lenOf(c);c.startMs = startMs;+ }+ /* placing: a track where any of them would overlap a clip left there takes none of them; a new track beside it takes+ them all (they never overlap each other there: the group keeps its shape, one track per track) */+ const taken = new Set<number>();+ if (spec.mode === 'place') {+ for (const [id, c] of lifted) {+ const dest = destOf(id);+ if (typeof dest !== 'number' || inserted.has(id)) continue;+ if ((trackAt(d, dest)?.clips ?? []).some((x) => overlap(x, c))) taken.add(dest);+ }+ }+ for (const [id, c] of lifted) {const dest = destOf(id);+ if (typeof dest === 'number' && taken.has(dest)) {+ const side = newTrackSide(dest, trackAt(d, dest)?.role);+ d.opened.set(id, side);+ openTrack(d, side, `beside-${dest}`).clips.push(c);+ continue;+ }if (typeof dest === 'object') {/* a new track for each track the clips came from: a group keeps its rows */d.opened.set(id, dest.insert);@@ -931,21 +937,13 @@ export function planMove(model: EditModel, spec: MoveSpec): (EditPlan & { landMscontinue;}const track = trackAt(d, dest)!;- if (spec.mode === 'overwrite' && spec.magnet && dest !== mainIndex) {- d.settle = true;- } else if (spec.mode === 'overwrite') {+ if (spec.mode === 'overwrite' && !inserted.has(id)) {clearLinked(d, [dest], c.startMs, c.endMs, hand);clearRange(d, track, c.startMs, c.endMs, hand);}track.clips.push(c);}- /* the riders, where their clip went */- for (const [c, r] of riders) {- const host = lifted.get(r.host)!;- shiftClip(c, host.startMs - d.before.get(r.host)!.clip.startMs);- r.track.clips.push(c);- d.settle = true;- }+ carry(d, rides);const plan = planOf(d);return { ...plan, landMs };}@@ -995,11 +993,13 @@ function applyEdge(c: EditClip, kind: EdgeKind, ms: number): void {/*** Edges moved together by one amount, kept to what every one of them allows: a trim (one edge, and the same edge of- * linked clips), a roll (the end of one clip and the start of the next), a slip (the content of clips, the- * inspector's source bar), a nudge (clips shifted into free time). Moves on locked tracks are left out.+ * linked clips), a slip (the content of clips, the inspector's source bar), a shift (clips moved into free time).+ * Moves on locked tracks are left out. With linkage what rides on a main-track clip stays on its footage (a slip moves+ * it, a trim does not).*/-export function planEdges(model: EditModel, moves: readonly EdgeMove[], deltaMs: number): EditPlan & { deltaMs: number } {+export function planEdges(model: EditModel, moves: readonly EdgeMove[], deltaMs: number, sw: Switches = NO_SWITCHES): EditPlan & { deltaMs: number } {const d = draftOf(model);+ const rides = sw.linkage ? ridesOf(d, mainTrackOf(model), new Set(moves.map((m) => m.id))) : new Map<string, Ride>();const live = moves.map((m) => ({ m, at: find(d, m.id) })).filter((x): x is { m: EdgeMove; at: { track: EditTrack; clip: EditClip } } => Boolean(x.at && !x.at.track.locked));@@ -1014,23 +1014,25 @@ export function planEdges(model: EditModel, moves: readonly EdgeMove[], deltaMs:/* `+ 0`: no -0 from a fence at 0 */const amount = (live.length ? Math.min(Math.max(deltaMs, Math.min(lo, 0)), Math.max(hi, 0)) : 0) + 0;if (amount) for (const { m, at } of live) applyEdge(at.clip, m.kind, amount);+ carry(d, rides);return { ...planOf(d), deltaMs: amount };}/*** A ripple trim: one edge of these clips (the first is the one in hand, the rest linked to it) moves by `deltaMs` and- * what comes after follows, on their tracks and with sync lock every unlocked track. The start edge trims the head- * and keeps the clip where it starts, as in Premiere and CapCut: it is the clip that gets shorter, and what follows- * moves back. Shortening stops where a track the ripple reaches has no room.+ * what comes after follows on their tracks (with linkage, what rides on the main track along). The start edge trims+ * the head and keeps the clip where it starts: it is the clip that gets shorter, and what follows moves+ * back. Shortening stops where the clips' own tracks have no room.*/export function planRippleTrim(model: EditModel,ids: readonly string[],edge: 'start' | 'end',deltaMs: number,- opts: Follow,+ sw: Switches = NO_SWITCHES,): EditPlan & { deltaMs: number } {const d = draftOf(model);+ const rides = sw.linkage ? ridesOf(d, mainTrackOf(model), new Set(ids)) : new Map<string, Ride>();const parts = ids.map((id) => find(d, id)).filter((x): x is { track: EditTrack; clip: EditClip } => Boolean(x && !x.track.locked));const main = parts[0];if (!main) return { ...emptyPlan(), deltaMs: 0 };@@ -1041,7 +1043,7 @@ export function planRippleTrim(grow = Math.min(grow, edge === 'end' ? tailRoomOf(clip) : headRoomOf(clip));}const point = main.clip.endMs;- const { tracks, bound } = follow(d, parts.map((p) => p.track.index), opts);+ const { tracks, bound } = follow(d, parts.map((p) => p.track.index));const skip = new Set(parts.map((p) => p.clip.id));if (grow < 0) {const room = Math.min(...bound.map((i) => roomBefore(trackAt(d, i)!, point, skip)));@@ -1050,9 +1052,11 @@ export function planRippleTrim(if (!grow) return { ...planOf(d), deltaMs: 0 };for (const { clip } of parts) {if (edge === 'start' && !clip.still) clip.inMs = Math.max(0, clip.inMs - grow * clip.speed);+ else if (edge === 'start') clip.vin = (clip.vin ?? 0) - grow;clip.endMs += grow;}rippleAt(d, point, grow, tracks, skip, bound);+ carry(d, rides);return { ...planOf(d), deltaMs: edge === 'end' ? grow : -grow };}@@ -1060,41 +1064,29 @@ export function planRippleTrim(* Ripple trim to the playhead (Q and W): `start` takes off the head up to `atMs`, `end` the tail from it, and what* comes after closes up. Null when `atMs` is not inside the first clip.*/-export function planRippleTrimTo(model: EditModel, ids: readonly string[], edge: 'start' | 'end', atMs: number, opts: Follow): EditPlan | null {- const main = model.flatMap((t) => t.clips).find((c) => c.id === ids[0]);- if (!main || !(atMs > main.startMs + TOUCH_MS && atMs < main.endMs - TOUCH_MS)) return null;- const plan = planRippleTrim(model, ids, edge, edge === 'start' ? atMs - main.startMs : atMs - main.endMs, opts);+export function planRippleTrimTo(model: EditModel, ids: readonly string[], edge: 'start' | 'end', atMs: number, sw: Switches = NO_SWITCHES): EditPlan | null {+ const lead = model.flatMap((t) => t.clips).find((c) => c.id === ids[0]);+ if (!lead || !(atMs > lead.startMs + TOUCH_MS && atMs < lead.endMs - TOUCH_MS)) return null;+ const plan = planRippleTrim(model, ids, edge, edge === 'start' ? atMs - lead.startMs : atMs - lead.endMs, sw);return plan.ops.length ? plan : null;}-/**- * A roll of the cut after `leftId`: its end and the next clip's start move together. Linked clips with a cut at the- * same place roll too; a linked clip whose edge is elsewhere has it trimmed by the same amount.- */-export function rollMoves(model: EditModel, leftId: string, rightId: string, linked: boolean): EdgeMove[] {- const out: EdgeMove[] = [{ id: leftId, kind: 'end' }, { id: rightId, kind: 'start' }];- if (!linked) return out;- for (const id of linkedIds(model, [leftId]).filter((x) => x !== leftId)) out.push({ id, kind: 'end' });- for (const id of linkedIds(model, [rightId]).filter((x) => x !== rightId)) {- if (!out.some((m) => m.id === id)) out.push({ id, kind: 'start' });- }- return out;-}-/* ── speed ── *//*** A new speed for clips (the first and those linked to it): each keeps its part of the source, so its length on the- * film changes. With `ripple` what comes after follows; without, a clip that would run into the next one cannot get- * that slow: `slowest` says how slow it can go, and nothing changes.+ * film changes. With `ripple` what comes after on their tracks follows; without, a clip that would run into the next+ * one cannot get that slow: `slowest` says how slow it can go, and nothing changes. With linkage what rides on a+ * main-track clip stays on its footage.*/export function planSpeed(model: EditModel,ids: readonly string[],speed: number,- opts: Follow & { ripple: boolean },+ opts: { ripple: boolean } & Partial<Switches>,): EditPlan & { slowest?: number } {const d = draftOf(model);+ const rides = opts.linkage ? ridesOf(d, mainTrackOf(model), new Set(ids)) : new Map<string, Ride>();const parts = ids.map((id) => find(d, id)).filter((x): x is { track: EditTrack; clip: EditClip } => Boolean(x && !x.track.locked && !x.clip.still));const main = parts[0];if (!main || !(speed > 0)) return emptyPlan();@@ -1113,17 +1105,19 @@ export function planSpeed(clip.endMs += grow(clip);clip.speed = speed;}+ carry(d, rides);return planOf(d);}const point = main.clip.endMs;const by = grow(main.clip);- const { tracks, bound } = follow(d, parts.map((p) => p.track.index), opts);+ const { tracks, bound } = follow(d, parts.map((p) => p.track.index));const skip = new Set(parts.map((p) => p.clip.id));for (const { clip } of parts) {clip.endMs += grow(clip);clip.speed = speed;}rippleAt(d, point, by, tracks, skip, bound);+ carry(d, rides);return planOf(d);}diff --git a/packages/openfilm/studio/ui/src/lib/timeline-keys.test.ts b/packages/openfilm/studio/ui/src/lib/timeline-keys.test.tsindex e3524b4..a32e87b 100644--- a/packages/openfilm/studio/ui/src/lib/timeline-keys.test.ts+++ b/packages/openfilm/studio/ui/src/lib/timeline-keys.test.ts@@ -6,7 +6,7 @@ const press = (key: string, mods: Partial<KeyPress> = {}): KeyPress => ({ key, mconst mac = (key: string, mods: Partial<KeyPress> = {}) => keyCommandOf(press(key, mods), true);const win = (key: string, mods: Partial<KeyPress> = {}) => keyCommandOf(press(key, mods), false);-test('the keys, as Premiere and CapCut have them', () => {+test('the keys', () => {assert.equal(mac('j'), 'shuttle-back');assert.equal(mac('k'), 'shuttle-stop');assert.equal(mac('L'), 'shuttle-forward');@@ -31,7 +31,13 @@ test('the keys, as Premiere and CapCut have them', () => {assert.equal(mac('ArrowRight', { altKey: true }), 'nudge-forward');assert.equal(mac('Z', { shiftKey: true }), 'zoom-fit');assert.equal(mac('n'), 'toggle-snap');+ /* the switches: P (and ⇧N) the main-track magnet, ~ linkage, S the preview axis */assert.equal(mac('N', { shiftKey: true }), 'toggle-magnet');+ assert.equal(mac('p'), 'toggle-magnet');+ assert.equal(mac('`'), 'toggle-linkage');+ assert.equal(mac('~', { shiftKey: true }), 'toggle-linkage');+ assert.equal(mac('s'), 'toggle-preview-axis');+ assert.equal(mac('S', { shiftKey: true, ctrlKey: true }), 'detach-audio');assert.equal(mac('q'), 'ripple-start');assert.equal(mac('w'), 'ripple-end');assert.equal(mac(','), 'insert-source');@@ -46,13 +52,13 @@ test('M adds a marker, ⇧M and ⌥M go to the next and the one before (⌥M typassert.equal(keyCommandOf({ ...press('µ', { altKey: true }), code: 'KeyM' }, true), 'prev-marker');assert.equal(win('m', { altKey: true }), 'prev-marker');assert.equal(mac('m', { metaKey: true }), null);- assert.equal(mac('m', { altKey: true, shiftKey: true }), 'prev-marker', '⌥⇧M too, as CapCut\'s');+ assert.equal(mac('m', { altKey: true, shiftKey: true }), 'prev-marker', '⌥⇧M too');});-test('CapCut\'s keys (its Final Cut Pro X set on a Mac): P, ~, ⇧X, ⌥X, ⌘R, ⇧⌃S, ⌘⇧C, ⌘⇧V', () => {+test('the switch, range, speed, sound and attribute keys: P, ~, S, ⇧X, ⌥X, ⌘R, ⇧⌃S, ⌘⇧C, ⌘⇧V', () => {assert.equal(mac('p'), 'toggle-magnet');assert.equal(keyCommandOf({ ...press('`'), code: 'Backquote' }, true), 'toggle-linkage');- assert.equal(keyCommandOf({ ...press('~', { shiftKey: true }), code: 'Backquote' }, true), 'toggle-linkage');+ assert.equal(mac('s'), 'toggle-preview-axis');assert.equal(mac('X', { shiftKey: true }), 'range-clip');assert.equal(keyCommandOf({ ...press('≈', { altKey: true }), code: 'KeyX' }, true), 'clear-range');assert.equal(mac('r', { metaKey: true }), 'speed');diff --git a/packages/openfilm/studio/ui/src/lib/timeline-keys.ts b/packages/openfilm/studio/ui/src/lib/timeline-keys.tsindex 43d12b3..b86eabf 100644--- a/packages/openfilm/studio/ui/src/lib/timeline-keys.ts+++ b/packages/openfilm/studio/ui/src/lib/timeline-keys.ts@@ -1,6 +1,5 @@/**- * The editor's keys, as CapCut (剪映) has them on a Mac — its keys there are its Final Cut Pro X set — with Premiere's- * where CapCut has none: which key does what (`keyCommandOf`), the list Settings shows (`SHORTCUTS`), J / K / L shuttle+ * The editor's keys: which key does what (`keyCommandOf`), the list Settings shows (`SHORTCUTS`), J / K / L shuttle* (`shuttleRate`) and looping a range (`loopBack`, `playStart`).** Plain letters are read by the letter they type, so they follow the keyboard's layout; on a layout without Latin@@ -16,7 +15,7 @@ export type KeyCommand =| 'frame-back' | 'frame-forward' | 'jump-back' | 'jump-forward'| 'nudge-back' | 'nudge-forward'| 'start' | 'end'- | 'zoom-fit' | 'toggle-snap' | 'toggle-magnet' | 'toggle-linkage'+ | 'zoom-fit' | 'toggle-snap' | 'toggle-magnet' | 'toggle-linkage' | 'toggle-preview-axis'| 'range-clip' | 'speed' | 'detach-audio' | 'copy-attrs' | 'paste-attrs' | 'select-left' | 'select-right'| 'ripple-start' | 'ripple-end'| 'insert-source' | 'overwrite-source'@@ -39,7 +38,7 @@ export function letterOf(e: Pick<KeyPress, 'key' | 'code'>): string {return code ? code.toLowerCase() : key;}-/** How many frames ⇧← / ⇧→ move the playhead (CapCut's "大幅移动"). */+/** How many frames ⇧← / ⇧→ move the playhead (a big step). */export const JUMP_FRAMES = 10;/**@@ -49,7 +48,7 @@ export const JUMP_FRAMES = 10;export function keyCommandOf(e: KeyPress, mac: boolean): KeyCommand | null {const mod = mac ? e.metaKey : e.ctrlKey;const k = letterOf(e);- /* ⇧⌃S detaches a video's sound, as CapCut's (on a Mac Ctrl itself, elsewhere Ctrl the modifier) */+ /* ⇧⌃S detaches a video's sound (on a Mac Ctrl itself, elsewhere Ctrl the modifier) */if (k === 's' && e.shiftKey && e.ctrlKey && !e.metaKey && !e.altKey) return 'detach-audio';/* the other platform's modifier (Ctrl on a Mac) is no shortcut here */const other = mac ? e.ctrlKey : e.metaKey;@@ -57,7 +56,7 @@ export function keyCommandOf(e: KeyPress, mac: boolean): KeyCommand | null {if (mod) {if (e.altKey) return null;if (k === 'b') return e.shiftKey ? 'split-all' : 'split';- /* ⌘⇧C / ⌘⇧V copy a clip's look, place and sound onto others (CapCut's 复制属性 / 粘贴属性) */+ /* ⌘⇧C / ⌘⇧V copy a clip's look, place and sound onto others (copy / paste attributes) */if (k === 'c' && e.shiftKey) return 'copy-attrs';if (k === 'v' && e.shiftKey) return 'paste-attrs';if (k === 'r' && !e.shiftKey) return 'speed';@@ -78,10 +77,10 @@ export function keyCommandOf(e: KeyPress, mac: boolean): KeyCommand | null {case '.': return e.altKey || e.shiftKey ? null : 'overwrite-source';default: break;}- /* [ / ]: every clip before / after the playhead selected (CapCut's 向左全选 / 向右全选), read by where the key is */+ /* [ / ]: every clip before / after the playhead selected, read by where the key is */if (!e.shiftKey && !e.altKey && (e.code === 'BracketLeft' || e.key === '[')) return 'select-left';if (!e.shiftKey && !e.altKey && (e.code === 'BracketRight' || e.key === ']')) return 'select-right';- /* ~ (the key left of 1, with ⇧ or without): linkage on / off, as CapCut's */+ /* ~ (the key left of 1, with ⇧ or without): linkage on / off */if (e.code === 'Backquote' || e.key === '`' || e.key === '~') return e.altKey ? null : 'toggle-linkage';/* ⌥M / ⌥⇧M: the marker before; ⌥X: the range cleared (on a Mac ⌥ types another letter: read by where the key is) */if (e.altKey) return k === 'm' ? 'prev-marker' : k === 'x' && !e.shiftKey ? 'clear-range' : null;@@ -93,7 +92,7 @@ export function keyCommandOf(e: KeyPress, mac: boolean): KeyCommand | null {case 'z': return 'zoom-fit';case 'n': return 'toggle-magnet';case 'm': return 'next-marker';- /* ⇧X: the range is the selected clips' (CapCut's 以片段选定区域) */+ /* ⇧X: the range is the selected clips' */case 'x': return 'range-clip';default: return null;}@@ -107,6 +106,7 @@ export function keyCommandOf(e: KeyPress, mac: boolean): KeyCommand | null {case 'x': return 'clear-range';case 'n': return 'toggle-snap';case 'p': return 'toggle-magnet';+ case 's': return 'toggle-preview-axis';case 'q': return 'ripple-start';case 'w': return 'ripple-end';case 'm': return 'add-marker';@@ -183,6 +183,7 @@ export const SHORTCUTS: { group: 'groupPlayback' | 'groupMarks' | 'groupEdit' |{ label: 'toggleMagnet', keys: [k('P'), k('N', { shift: true })] },{ label: 'toggleSnap', keys: [k('N')] },{ label: 'toggleLinkage', keys: [k('~')] },+ { label: 'togglePreviewAxis', keys: [k('S')] },{ label: 'editModeSwap', keys: [k('', { alt: true })] },{ label: 'copyDrag', keys: [k('', { alt: true })] },],diff --git a/packages/openfilm/studio/ui/src/lib/timeline-layout.test.ts b/packages/openfilm/studio/ui/src/lib/timeline-layout.test.tsindex 4ab765e..bb244aa 100644--- a/packages/openfilm/studio/ui/src/lib/timeline-layout.test.ts+++ b/packages/openfilm/studio/ui/src/lib/timeline-layout.test.ts@@ -117,6 +117,7 @@ test('every rate a project can have puts a labeled tick on each whole second, at}});+test('the main track is marked: the lowest picture track, as the magnet takes it', () => {const two = { stage: doc.stage, tracks: [{ clips: [{ src: 'assets/footage/product.mp4', id: 'top', time: [0, 2] }] }, doc.tracks[0]!] };const top = { key: 'top#0.0', src: 'assets/footage/product.mp4', startMs: 0, durMs: 2000, inMs: 0, sourceDurMs: 10_000, loc: 'film.html#0.0', track: { index: 0, name: 'video', kind: 'video' }, clipId: 'top' };diff --git a/packages/openfilm/studio/ui/src/lib/timeline-layout.ts b/packages/openfilm/studio/ui/src/lib/timeline-layout.tsindex c46ad6c..e6ec745 100644--- a/packages/openfilm/studio/ui/src/lib/timeline-layout.ts+++ b/packages/openfilm/studio/ui/src/lib/timeline-layout.ts@@ -235,8 +235,7 @@ function clamp(n: number, lo: number, hi: number): number {/*** Label and tick spacing, worked out separately: labels need room to read (≥96 px), ticks are lines and can sit- * 12 px apart. One shared spacing forces a choice between overlapping labels and ticks too sparse to aim by (OpenCut's- * approach, which it says is CapCut's table).+ * 12 px apart. One shared spacing would force a choice between overlapping labels and ticks too sparse to aim by.** Steps are in frames of the project's rate, then whole seconds, because frames are what gets lined up: a* "1/2/5 × 10ⁿ ms" family gives 200 ms steps that are neither whole seconds nor whole frames. A step shorter than a@@ -422,7 +421,7 @@ export interface TimelineTrack {/** Row title. */name: string | null;/**- * The row's badge: `P1` / `V2` / `A1`, the Premiere / Resolve naming (pictures counted bottom up, sound top+ * The row's badge: `P1` / `V2` / `A1` (pictures counted bottom up, sound top* down), one per drawn row (rows of one track spread by overlap each get their own, see badgeRows).*/badge?: string;@@ -440,8 +439,8 @@ export interface TimelineTrack {/** How tall the row is drawn, px, when the person set it (lib/track-heights); else the timeline's own for its kind. */height?: number;/**- * The main track's rows: the lowest picture track, where the magnet acts (lib/timeline-edit mainTrackOf), marked and- * drawn taller as CapCut draws its main track.+ * The main track's rows: the lowest picture track, where the magnet and linkage act (lib/timeline-edit mainTrackOf),+ * marked and drawn taller than the others.*/main?: boolean;blocks: TimelineBlock[];@@ -638,7 +637,7 @@ function docTrackKind(track: Record<string, unknown>): string {}/**- * Row badges, Premiere / Resolve style: P1, P2… for page tracks, V1… for picture tracks, A1… for sound tracks, counted+ * Row badges: P1, P2… for page tracks, V1… for picture tracks, A1… for sound tracks, counted* from position and kind, never read from the film (filmTrackBadges).** Counted per drawn row, not per film.html track: a track spread into four rows by overlap is A2, A3, A4, A5 and thediff --git a/packages/openfilm/studio/ui/src/lib/timeline-nav.test.ts b/packages/openfilm/studio/ui/src/lib/timeline-nav.test.tsindex ee22f27..d64e32f 100644--- a/packages/openfilm/studio/ui/src/lib/timeline-nav.test.ts+++ b/packages/openfilm/studio/ui/src/lib/timeline-nav.test.ts@@ -33,21 +33,21 @@ test('the cuts ↑ / ↓ go to: every clip edge on tracks seen and not locked, otest('⌘B splits the selected clips under the playhead, else the main track\'s, else the targeted track\'s, else the top one seen', () => {const tracks = [row(0, [['top', 0, 4]], { hidden: true }),- row(1, [['v', 0, 4]]),+ row(1, [['v', 0, 4], ['v2', 9, 12]]),row(2, [['locked', 0, 4]], { locked: true }),row(3, [['s', 0, 4], ['s2', 4, 8]]),+ row(4, [['m', 0, 12]], { role: 'audio', kind: 'audio' }),];const ids = (bs: TimelineBlock[]) => bs.map((b) => b.clipId);assert.deepEqual(ids(splitTargets(tracks, ['b-s', 'b-s2', 'b-locked'], 2000, null)), ['s'], 'selected and under it, not locked');assert.deepEqual(ids(splitTargets(tracks, ['b-s2'], 2000, null)), [], 'a selection the playhead is not over: nothing');- assert.deepEqual(ids(splitTargets(tracks, [], 2000, 'doc-1')), ['s'], 'the main track before the targeted one');- /* no main-track clip to split (its track locked): the targeted track's, and a locked target splits nothing */- assert.deepEqual(ids(splitTargets(tracks.slice(0, 3), [], 2000, 'doc-1')), ['v']);- assert.deepEqual(ids(splitTargets(tracks.slice(0, 3), [], 2000, 'doc-2')), [], 'a locked target: nothing');- assert.deepEqual(ids(splitTargets(tracks, [], 2000, null)), ['s'], 'the main track: the lowest picture track');- assert.deepEqual(ids(splitTargets(tracks.slice(0, 3), [], 2000, null)), ['v'], 'a locked main track: the top one seen, not a hidden one');- assert.deepEqual(ids(splitTargets(tracks, [], 4000, null)), [], 'on a cut there is nothing to split');- assert.deepEqual(ids(splitAllTargets(tracks, 2000)), ['top', 'v', 's']);+ assert.deepEqual(ids(splitTargets(tracks, [], 2000, 'doc-1')), ['s'], 'the main track (the lowest picture track) first');+ /* past the main track's end: the targeted track, else the top one seen */+ assert.deepEqual(ids(splitTargets(tracks, [], 10_000, 'doc-4')), ['m'], 'the targeted track');+ assert.deepEqual(ids(splitTargets(tracks, [], 10_000, 'doc-2')), [], 'a locked target: nothing');+ assert.deepEqual(ids(splitTargets(tracks, [], 10_000, null)), ['v2'], 'no target: the top one seen, not a hidden one');+ assert.deepEqual(ids(splitTargets(tracks, [], 4000, 'doc-1')), [], 'on a cut there is nothing to split');+ assert.deepEqual(ids(splitAllTargets(tracks, 2000)), ['top', 'v', 's', 'm']);});test('[ and ] select every clip with a part before or after the playhead, on tracks not locked', () => {@@ -67,23 +67,24 @@ const filmOf = (m: EditTrack[]) => ({ tracks: m.map((t) => ({ ...(t.locked ? { lconst starts = (m: EditTrack[], ops: Op[]) => (applyOps(filmOf(m) as never, ops as never) as { tracks: { clips: { id: string; at?: number }[] }[] }).tracks.map((t) => t.clips.map((c) => [c.id, Math.round((c.at ?? 0) * 1000)]));-test('⌥ → moves the selection a frame: into free time with the magnet, over what is there without it', () => {+test('⌥ → moves the selection a frame, on the frame grid, stopping against a clip in the way', () => {const m: EditTrack[] = [{ index: 0, clips: [clip('a', 0, 2), clip('b', 3, 4)] }, { index: 1, clips: [clip('c', 2, 3)] }];- const one = planNudge(m, ['a'], 1, { mode: 'insert', sync: true })!;- assert.deepEqual(starts(m, one.ops)[0], [['a', 33], ['b', 3000]]);+ assert.deepEqual(starts(m, planNudge(m, ['a'], 1)!.ops)[0], [['a', 33], ['b', 3000]]);/* back from 0: nowhere to go */- assert.equal(planNudge(m, ['a'], -1, { mode: 'insert', sync: true }), null);- /* c touches nothing on its track: it moves either way, on the frame grid */- assert.deepEqual(starts(m, planNudge(m, ['c'], -1, { mode: 'overwrite', sync: true })!.ops)[1], [['c', 1967]]);- /* b against a's end: with the magnet it stops there, without it it covers a frame of a */+ assert.equal(planNudge(m, ['a'], -1), null);+ assert.deepEqual(starts(m, planNudge(m, ['c'], -1)!.ops)[1], [['c', 1967]]);+ /* b against a's end: nowhere to go, a is not cut */const tight: EditTrack[] = [{ index: 0, clips: [clip('a', 0, 2), clip('b', 2, 4)] }];- assert.equal(planNudge(tight, ['b'], -1, { mode: 'insert', sync: true }), null);- const over = planNudge(tight, ['b'], -1, { mode: 'overwrite', sync: true })!;- assert.deepEqual(starts(tight, over.ops)[0], [['a', 0], ['b', 1967]]);+ assert.equal(planNudge(tight, ['b'], -1), null);+ /* half a frame from a: b goes the half frame and stops against it */+ const near: EditTrack[] = [{ index: 0, clips: [clip('a', 0, 2), clip('b', 2.02, 4)] }];+ assert.deepEqual(starts(near, planNudge(near, ['b'], -1)!.ops)[0], [['a', 0], ['b', 2000]]);+ /* moving together, they stop against what is not moving */+ const both: EditTrack[] = [{ index: 0, clips: [clip('a', 0, 2), clip('b', 2, 4), clip('c', 4.02, 5)] }];+ assert.deepEqual(starts(both, planNudge(both, ['a', 'b'], 1)!.ops)[0], [['a', 20], ['b', 2020], ['c', 4020]]);/* a locked track does not move */const locked: EditTrack[] = [{ index: 0, locked: true, clips: [clip('a', 1, 2)] }];- assert.equal(planNudge(locked, ['a'], 1, { mode: 'overwrite', sync: true }), null);- assert.equal(planNudge(locked, ['a'], 1, { mode: 'insert', sync: true }), null);+ assert.equal(planNudge(locked, ['a'], 1), null);});test('a track\'s name follows its clips when tracks move, and its place when it has none', () => {diff --git a/packages/openfilm/studio/ui/src/lib/timeline-nav.ts b/packages/openfilm/studio/ui/src/lib/timeline-nav.tsindex 4943861..5efcd23 100644--- a/packages/openfilm/studio/ui/src/lib/timeline-nav.ts+++ b/packages/openfilm/studio/ui/src/lib/timeline-nav.ts@@ -4,7 +4,7 @@* the editor (components/ProjectView).*/import { MIN_BLOCK_MS } from './timeline-drag.ts';-import { planEdges, planMove, type EditMode, type EditModel, type EditPlan } from './timeline-edit.ts';+import { NO_SWITCHES, TOUCH_MS, mainTrackOf, planMove, type EditModel, type EditPlan, type Switches } from './timeline-edit.ts';import { stepFrames } from './timecode.ts';import type { TimelineBlock, TimelineTrack } from './timeline-layout';@@ -42,9 +42,8 @@ const lockedRows = (tracks: readonly TimelineTrack[]) => new Set(tracks.filter((/*** What ⌘B splits at the playhead: the selected clips it is inside; with nothing selected, the clip it is inside on the- * main track (the lowest picture track), as CapCut; else on the targeted track (`targetLane`), else on the topmost- * track that is seen and has one. Never a clip on a locked track. The clips linked to them are the caller's to add- * (the Linked switch).+ * main track (the lowest picture track); else on the targeted track (`targetLane`), else on the topmost+ * track that is seen and has one. Never a clip on a locked track. The clips linked to them are the caller's to add.*/export function splitTargets(tracks: readonly TimelineTrack[],@@ -73,7 +72,7 @@ export function splitTargets(}/**- * What [ / ] select (CapCut's 向左全选 / 向右全选): every clip with a part before the playhead (`dir` -1) or after it+ * What [ / ] select: every clip with a part before the playhead (`dir` -1) or after it* (`dir` 1), on every track not locked — what to move when the film before or after a point moves along.*/export function sideTargets(tracks: readonly TimelineTrack[], atMs: number, dir: -1 | 1): TimelineBlock[] {@@ -87,22 +86,30 @@ export function splitAllTargets(tracks: readonly TimelineTrack[], atMs: number):}/**- * Clips (by id, the first leading) moved `frames` frames along their tracks, landing on the frame grid. With the- * magnet (insert) they move into free time only and stop at a neighbor, as nothing is overwritten then; without it- * (overwrite) they land a frame on and cut what they cover. Null when nothing can move (a locked track, a neighbor- * right there, the film's start).+ * Clips (by id, the first leading) moved `frames` frames along their tracks, landing on the frame grid; a clip in the+ * way stops them against it, uncut. Null when nothing can move (a locked track, the film's start, a clip right there,+ * the main track with the magnet, which stays closed up).*/-export function planNudge(model: EditModel, ids: readonly string[], frames: number, opts: { mode: EditMode; sync: boolean }): EditPlan | null {- const main = model.flatMap((t) => t.clips).find((c) => c.id === ids[0]);- if (!main || !frames) return null;- const deltaMs = stepFrames(main.startMs, frames) - main.startMs;- if (!deltaMs) return null;- if (opts.mode === 'overwrite') {- const plan = planMove(model, { ids, deltaMs, pointerMs: main.startMs + deltaMs, mode: 'overwrite', sync: opts.sync });- return plan?.ops.length ? plan : null;+export function planNudge(model: EditModel, ids: readonly string[], frames: number, sw: Switches = NO_SWITCHES): EditPlan | null {+ const lead = model.flatMap((t) => t.clips).find((c) => c.id === ids[0]);+ if (!lead || !frames) return null;+ const main = mainTrackOf(model);+ if (sw.magnet && model.find((t) => t.index === main)?.clips.some((c) => ids.includes(c.id))) return null;+ let deltaMs = stepFrames(lead.startMs, frames) - lead.startMs;+ /* the room before the nearest clip they would run into, on each of their tracks */+ const moving = new Set(ids);+ for (const t of model) {+ const others = t.clips.filter((c) => !moving.has(c.id));+ for (const c of t.clips.filter((x) => moving.has(x.id))) {+ for (const o of others) {+ if (deltaMs > 0 && o.startMs >= c.endMs - TOUCH_MS) deltaMs = Math.min(deltaMs, o.startMs - c.endMs);+ if (deltaMs < 0 && o.endMs <= c.startMs + TOUCH_MS) deltaMs = Math.max(deltaMs, o.endMs - c.startMs);+ }+ }}- const plan = planEdges(model, ids.map((id) => ({ id, kind: 'shift' as const })), deltaMs);- return plan.ops.length ? plan : null;+ if (Math.abs(deltaMs) <= TOUCH_MS) return null;+ const plan = planMove(model, { ids, deltaMs, pointerMs: lead.startMs + deltaMs, mode: 'place', ...sw });+ return plan?.ops.length ? plan : null;}/** A track's name as Studio keeps it (`.film/settings.json`): the clips it had when it was named find it again. */diff --git a/packages/openfilm/studio/ui/src/lib/timeline-prefs.ts b/packages/openfilm/studio/ui/src/lib/timeline-prefs.tsindex 3955dee..768a7a4 100644--- a/packages/openfilm/studio/ui/src/lib/timeline-prefs.ts+++ b/packages/openfilm/studio/ui/src/lib/timeline-prefs.ts@@ -1,32 +1,31 @@/**- * The timeline's switches, kept on this machine across projects:- * · `snap` (on by default, as in CapCut, Premiere and OpenCut): drags line up with edges and the playhead; off means- * "it lands exactly where I let go";- * · `magnet` (on by default, as CapCut's main-track magnet): the main track (the lowest picture track) stays closed- * up — a clip put down on it inserts and pushes what follows, a delete or a clip taken off it closes the gap, a- * trim ripples. On other tracks nothing is covered: a clip put where another is goes to a free track, a delete- * leaves a gap. Off, the main track is like the others;- * · `linkage` (on, as CapCut's 联动): an edit of the main track carries the clips on the other tracks along with- * the main-track clips they start over, so titles, B-roll and sound stay with their picture.+ * The timeline's switches, kept on this machine across projects, in the toolbar's order and all on by default:+ * · `magnet` (主轨磁吸): the main track (the lowest picture track) stays closed up — a clip put on it goes in between,+ * one deleted or taken off it closes up after it, a trim or a new speed there moves what follows. Off, the main+ * track is like the others (lib/timeline-edit);+ * · `snap` (自动吸附): drags line up with edges and the playhead; off means "it lands exactly where I let go";+ * · `linkage` (联动): titles, overlays and sounds riding on a main-track clip move with it and go with it;+ * · `previewAxis` (预览轴): the picture follows the pointer over the timeline, the playhead staying where it is.** Clips sharing a `data-link` (a video and its detached sound) are always selected and edited together; ⌥-click picks- * one alone. Premiere's sync lock is not offered: linkage does that job, the CapCut way.- *- * The inspector reads them too (a slower speed pushes the next clip only with the magnet on), so a change is told to- * everyone listening.+ * one alone. The inspector reads the switches too (a slower speed pushes the next clip only with the magnet on), so a+ * change is told to everyone listening.*/import { useSyncExternalStore } from 'react';-export type TimelinePrefs = { snap: boolean; magnet: boolean; linkage: boolean };+import type { Switches } from './timeline-edit.ts';++export type TimelinePrefs = { snap: boolean; magnet: boolean; linkage: boolean; previewAxis: boolean };type Pref = keyof TimelinePrefs;-const DEFAULTS: TimelinePrefs = { snap: true, magnet: true, linkage: true };+const DEFAULTS: TimelinePrefs = { snap: true, magnet: true, linkage: true, previewAxis: true };const KEY: Record<Pref, string> = {snap: 'openfilm.timeline.snap',- /* new keys: the magnet now acts on the main track alone, and sync lock gave way to linkage, so the choices made- for the old switches do not carry over */- magnet: 'openfilm.timeline.mainMagnet',- linkage: 'openfilm.timeline.linkage',+ /* new keys: the main track came back on 10-19 with its magnet and linkage, so choices made for the switches before+ do not carry over */+ magnet: 'openfilm.timeline.mainTrackMagnet',+ linkage: 'openfilm.timeline.mainTrackLinkage',+ previewAxis: 'openfilm.timeline.previewAxis',};/** Without localStorage (private window), the choices last this session. */@@ -43,10 +42,15 @@ function read(pref: Pref): boolean {}export function readTimelinePrefs(): TimelinePrefs {- current ??= { snap: read('snap'), magnet: read('magnet'), linkage: read('linkage') };+ current ??= { snap: read('snap'), magnet: read('magnet'), linkage: read('linkage'), previewAxis: read('previewAxis') };return current;}+/** What an edit is planned by (lib/timeline-edit Switches), from the switches. */+export function switchesOf(prefs: Pick<TimelinePrefs, 'magnet' | 'linkage'>): Switches {+ return { magnet: prefs.magnet, linkage: prefs.linkage };+}+export function writeTimelinePref(pref: Pref, on: boolean): void {memory[pref] = on;try {@@ -65,8 +69,3 @@ function subscribe(fn: () => void): () => void {export function useTimelinePrefs(): TimelinePrefs {return useSyncExternalStore(subscribe, readTimelinePrefs, () => DEFAULTS);}--/** What a ripple carries along (timeline-edit Follow), from the switches. */-export function followOf(prefs: Pick<TimelinePrefs, 'linkage'>): { sync: boolean; linkage: boolean } {- return { sync: false, linkage: prefs.linkage };-}diff --git a/packages/openfilm/studio/ui/src/lib/timeline-view.test.ts b/packages/openfilm/studio/ui/src/lib/timeline-view.test.tsnew file mode 100644index 0000000..43f4803--- /dev/null+++ b/packages/openfilm/studio/ui/src/lib/timeline-view.test.ts@@ -0,0 +1,133 @@+import { test } from 'node:test';+import assert from 'node:assert/strict';+import {+ rebaseZoomPreview,+ rowBand,+ rowsNear,+ ROWS_PAD_VIEWS,+ zoomLayerTransform,+ zoomPreviewAt,+ zoomPreviewIsRest,+ zoomPreviewStep,+ type ZoomPreview,+} from './timeline-view.ts';++/* 44 rows as the intro film has them: two picture rows, then sounds */+const heights = [56, 56, ...Array.from({ length: 42 }, () => 44)];+const GAP = 3;+const PAD = 10;+const VIEW_H = 339;++/** Where each row is in the content: [top, bottom). */+const spans = (() => {+ let bottom = PAD;+ return heights.map((h) => {+ const top = bottom + GAP;+ bottom = top + h;+ return [top, bottom] as const;+ });+})();++test('every row in view is drawn at any scroll, and rows far away are not', () => {+ const contentH = spans.at(-1)![1] + PAD;+ for (let scrollTop = 0; scrollTop <= contentH - VIEW_H; scrollTop += 7) {+ const near = rowsNear(heights, { gap: GAP, padTop: PAD, band: rowBand(scrollTop, VIEW_H), viewH: VIEW_H });+ spans.forEach(([top, bottom], i) => {+ const inView = bottom > scrollTop && top < scrollTop + VIEW_H;+ /* half a view of room either side: a quick scroll is drawn before it gets there */+ const nearView = bottom > scrollTop - VIEW_H * ROWS_PAD_VIEWS && top < scrollTop + VIEW_H * (1 + ROWS_PAD_VIEWS);+ if (inView || nearView) assert.ok(i >= near.first && i <= near.last, `row ${i} at scroll ${scrollTop}`);+ });+ /* not the whole film: about two and a half views of rows */+ assert.ok(near.last - near.first + 1 <= 22, `${near.last - near.first + 1} rows drawn at ${scrollTop}`);+ }+});++test('the rows drawn change once per half view scrolled, not with every pixel', () => {+ assert.equal(rowBand(0, VIEW_H), 0);+ assert.equal(rowBand(VIEW_H / 2 - 1, VIEW_H), 0);+ assert.equal(rowBand(VIEW_H / 2, VIEW_H), 1);+ assert.equal(rowBand(-40, VIEW_H), 0);+});++test('before the view has a height, every row is drawn; no rows, none', () => {+ assert.deepEqual(rowsNear(heights, { gap: GAP, padTop: PAD, band: 0, viewH: 0 }), { first: 0, last: heights.length - 1 });+ const none = rowsNear([], { gap: GAP, padTop: PAD, band: 0, viewH: VIEW_H });+ assert.ok(none.last < none.first);+});++/* a 100 s film laid out at 2800 px on a 1400 px view; the canvas is the film, or the view when the film is narrower */+const VIEW_W = 1400;+const PX = 0.028;+const FILM_MS = 100_000;+const limits = {+ minScale: 0.125,+ maxScale: 40,+ maxScrollAt: (scale: number) => Math.max(VIEW_W, Math.ceil(FILM_MS * PX * scale)) - VIEW_W,+};+/** The film time drawn at view x. */+const timeAt = (p: ZoomPreview, x: number) => (x - p.offset) / (p.scale * PX);++test('a zoom step keeps the time under the pointer where it is', () => {+ let p = zoomPreviewAt(300);+ const before = timeAt(p, 700);+ for (let i = 0; i < 20; i += 1) p = zoomPreviewStep(p, 1.05, 700, limits);+ assert.ok(p.scale > 2.6 && p.scale < 2.7);+ assert.ok(Math.abs(timeAt(p, 700) - before) < 1e-6);+ /* and back out, around another point */+ const at = timeAt(p, 200);+ p = zoomPreviewStep(p, 1 / 1.3, 200, limits);+ assert.ok(Math.abs(timeAt(p, 200) - at) < 1e-6);+});++test('a zoom step stays within the zoom limits and the canvas, as a zoom laid out each step does', () => {+ /* out from the start: the film's start stays at the view's left edge instead of leaving a gap before it */+ let p = zoomPreviewStep(zoomPreviewAt(0), 0.5, 900, limits);+ assert.equal(p.offset, 0);+ assert.equal(p.scale, 0.5);+ /* out at the end of the canvas: the view stays inside it, the point slides */+ p = zoomPreviewStep(zoomPreviewAt(limits.maxScrollAt(1)), 0.8, 0, limits);+ assert.equal(p.offset, -limits.maxScrollAt(0.8));+ /* the zoom's limits: further steps change nothing */+ assert.equal(zoomPreviewStep(zoomPreviewAt(0), 1e-6, 900, limits).scale, limits.minScale);+ const top = zoomPreviewStep(zoomPreviewAt(300), 1e6, 500, limits);+ assert.equal(top.scale, limits.maxScale);+ assert.deepEqual(zoomPreviewStep(top, 2, 500, limits), top);+});++test('laid out at the density and scroll a gesture reached, it draws everything where the gesture did', () => {+ let p = zoomPreviewAt(120);+ p = zoomPreviewStep(p, 1.4, 300, limits);+ /* the layout: scale × the density, scrolled to -offset */+ const rebased = rebaseZoomPreview(p, PX, PX * p.scale);+ assert.ok(zoomPreviewIsRest(rebased, -p.offset));+ assert.equal(zoomLayerTransform(rebased, -p.offset, 'content'), '');+ /* a step that came in before the layout was drawn is still there after it */+ const later = zoomPreviewStep(p, 1.1, 300, limits);+ const left = rebaseZoomPreview(later, PX, PX * p.scale);+ assert.ok(!zoomPreviewIsRest(left, -p.offset));+ assert.ok(Math.abs(left.scale - 1.1) < 1e-9);+});++/** Applies `translate3d(tx) scaleX(s)` (origin at the left edge) to an x. */+function apply(transform: string, x: number): number {+ if (!transform) return x;+ const m = /translate3d\(([-\d.e]+)px,0,0\) scaleX\(([-\d.e]+)\)/.exec(transform);+ assert.ok(m, transform);+ return Number(m[1]) + Number(m[2]) * x;+}++test('the layers\' transforms draw a moment where the gesture puts it', () => {+ const scroll = 480;+ const p = zoomPreviewStep(zoomPreviewAt(scroll), 1.3, 640, limits);+ for (const ms of [0, 12_345, 50_000, 99_000]) {+ const want = p.offset + p.scale * ms * PX;+ /* a content layer: laid out at the content x, the scroll moves it */+ const content = apply(zoomLayerTransform(p, scroll, 'content'), ms * PX) - scroll;+ assert.ok(Math.abs(content - want) < 0.01, `content ${ms}`);+ /* a view layer: laid out with the scroll taken off, its left edge 8 px left of the view's (the playhead) */+ const view = apply(zoomLayerTransform(p, scroll, 'view', 8), ms * PX - scroll + 8) - 8;+ assert.ok(Math.abs(view - want) < 0.01, `view ${ms}`);+ }+ assert.equal(zoomLayerTransform(zoomPreviewAt(scroll), scroll, 'view'), '');+});diff --git a/packages/openfilm/studio/ui/src/lib/timeline-view.ts b/packages/openfilm/studio/ui/src/lib/timeline-view.tsnew file mode 100644index 0000000..3036957--- /dev/null+++ b/packages/openfilm/studio/ui/src/lib/timeline-view.ts@@ -0,0 +1,105 @@+/**+ * What the timeline draws of a big film, and how a zoom gesture moves it. Every clip drawn is laid out, layerized and+ * hit-tested again on each zoom step and scroll, and on a film of hundreds of clips most of them were out of view. So+ * only the rows near the view get their clips (rowsNear), and while a wheel or pinch zoom goes on, what is drawn is+ * scaled by transforms the compositor applies (ZoomPreview), and laid out at the new density once it stops.+ */++/** Rows are drawn this many views above and below the view: a quick scroll does not outrun them. */+export const ROWS_PAD_VIEWS = 0.5;+/** The rows drawn follow the vertical scroll in steps of this many views, not every pixel (each step is a render). */+export const ROWS_STEP_VIEWS = 0.5;++function clamp(n: number, lo: number, hi: number): number {+ return n < lo ? lo : n > hi ? hi : n;+}++/** Which step of the vertical scroll the view is at (see ROWS_STEP_VIEWS). */+export function rowBand(scrollTop: number, viewH: number): number {+ if (!(viewH > 0)) return 0;+ return Math.max(0, Math.floor(scrollTop / (viewH * ROWS_STEP_VIEWS)));+}++/**+ * The rows drawn at a step of the vertical scroll: the first and last index, inclusive (`last` < `first` when none).+ * `heights` are the rows' own, top to bottom; each has `gap` above it, the first `padTop` below the content's top.+ * Before the view has a height every row is drawn.+ */+export function rowsNear(+ heights: readonly number[],+ at: { gap: number; padTop: number; band: number; viewH: number },+): { first: number; last: number } {+ if (!(at.viewH > 0)) return { first: 0, last: heights.length - 1 };+ const step = at.viewH * ROWS_STEP_VIEWS;+ const pad = at.viewH * ROWS_PAD_VIEWS;+ /* every scroll inside the step is covered, with `pad` to spare either side */+ const from = at.band * step - pad;+ const to = (at.band + 1) * step + at.viewH + pad;+ let first = -1;+ let last = -2;+ let bottom = at.padTop;+ for (let i = 0; i < heights.length; i += 1) {+ const top = bottom + at.gap;+ bottom = top + heights[i]!;+ if (bottom <= from) continue;+ if (top >= to) break;+ if (first < 0) first = i;+ last = i;+ }+ return first < 0 ? { first: 0, last: -1 } : { first, last };+}++/**+ * A zoom gesture under way, against what is laid out now: what is laid out at x (px from the content's left edge) is+ * drawn at `offset + scale × x` (px from the view's left edge). Laid out again, the density is `scale` times what it+ * is and the scroll is `-offset`.+ */+export interface ZoomPreview {+ offset: number;+ scale: number;+}++/** No gesture: what is laid out, drawn where it is. */+export function zoomPreviewAt(scrollLeft: number): ZoomPreview {+ return { offset: -scrollLeft, scale: 1 };+}++/**+ * One step of a gesture: `factor` more density around the view x `at`, which stays where it is. The density stays+ * within `minScale`..`maxScale` and the view within the canvas (`maxScrollAt`: the furthest scroll at a scale), as a+ * zoom laid out at each step would: near an end, the point slides instead of the view leaving the canvas.+ */+export function zoomPreviewStep(+ p: ZoomPreview,+ factor: number,+ at: number,+ limits: { minScale: number; maxScale: number; maxScrollAt: (scale: number) => number },+): ZoomPreview {+ const scale = clamp(p.scale * factor, limits.minScale, Math.max(limits.minScale, limits.maxScale));+ const offset = at + (scale / p.scale) * (p.offset - at);+ return { offset: clamp(offset, -Math.max(0, limits.maxScrollAt(scale)), 0), scale };+}++/** The same gesture against the density laid out next (`toPx` where it was `fromPx`). */+export function rebaseZoomPreview(p: ZoomPreview, fromPx: number, toPx: number): ZoomPreview {+ return toPx > 0 && fromPx > 0 ? { offset: p.offset, scale: (p.scale * fromPx) / toPx } : p;+}++/** Whether a gesture draws things where they are laid out (at this scroll): nothing to transform. */+export function zoomPreviewIsRest(p: ZoomPreview, scrollLeft: number): boolean {+ return Math.abs(p.scale - 1) < 1e-6 && Math.abs(p.offset + scrollLeft) < 0.01;+}++/**+ * The transform that draws a layer as the gesture has it. `content`: laid out in content px, moved by the scroll+ * (the clips, the ruler, the subtitle and marker rows). `view`: drawn in view px with the scroll taken off already+ * (the playhead, the range), its left edge `bleed` px left of the view's. Empty at rest.+ */+export function zoomLayerTransform(p: ZoomPreview, scrollLeft: number, kind: 'content' | 'view', bleed = 0): string {+ if (zoomPreviewIsRest(p, scrollLeft)) return '';+ const x = kind === 'content' ? p.offset + scrollLeft : p.offset + p.scale * (scrollLeft - bleed) + bleed;+ return `translate3d(${round3(x)}px,0,0) scaleX(${round6(p.scale)})`;+}++const round3 = (n: number) => Math.round(n * 1000) / 1000;+const round6 = (n: number) => Math.round(n * 1e6) / 1e6;diff --git a/packages/openfilm/studio/ui/src/lib/track-heights.ts b/packages/openfilm/studio/ui/src/lib/track-heights.tsindex 3e1878a..e58752d 100644--- a/packages/openfilm/studio/ui/src/lib/track-heights.ts+++ b/packages/openfilm/studio/ui/src/lib/track-heights.ts@@ -20,7 +20,7 @@ export const TRACK_SIZES = {} as const;export type TrackSize = keyof typeof TRACK_SIZES;-/** The main track's own height: taller than the others, as CapCut draws its main track. */+/** The main track's own height: taller than the others. */export const MAIN_TRACK_H = 68;/** A track's own height (none set by the person): the main track's, else medium for its kind. */diff --git a/packages/openfilm/studio/ui/src/lib/transitions.test.ts b/packages/openfilm/studio/ui/src/lib/transitions.test.tsindex 981efc4..306e484 100644--- a/packages/openfilm/studio/ui/src/lib/transitions.test.ts+++ b/packages/openfilm/studio/ui/src/lib/transitions.test.ts@@ -78,9 +78,9 @@ const fades = (value: FilmValue) => Object.fromEntries(value.tracks.flatMap((t)return f ? [[c.id, f]] : [];}));-const opts = (more: Partial<TransitionOpts> = {}): TransitionOpts => ({ ripple: true, sync: false, linked: true, whiteSrc: WHITE, ...more });+const opts = (more: Partial<TransitionOpts> = {}): TransitionOpts => ({ ripple: true, linked: true, whiteSrc: WHITE, ...more });-test('cross dissolve: the incoming clip goes above, d earlier, and fades in over the outgoing one, which stays whole; with the magnet what follows closes up', () => {+test('cross dissolve: the incoming clip goes above, d earlier, and fades in over the outgoing one, which stays whole; what follows closes up', () => {const value = film([['a', 0, 4], ['b', 4, 8], ['c', 8, 10]]);const { model, facts } = read(value);const next = apply(value, planTransition(model, facts, 'dissolve', { a: 'a', b: 'b' }, 500, opts()));@@ -101,13 +101,13 @@ test('cross dissolve: the incoming clip goes above, d earlier, and fades in overassert.deepEqual(fades(back), {});});-test('cross dissolve without the magnet leaves what follows where it is; with sync lock other tracks close up too', () => {+test('cross dissolve without a ripple leaves what follows where it is; with one the cut\'s track closes up', () => {const value = film([['a', 0, 4], ['b', 4, 8], ['c', 8, 10]], [['m', 0, 3], ['n', 9, 10]]);const { model, facts } = read(value);const still = apply(value, planTransition(model, facts, 'dissolve', { a: 'a', b: 'b' }, 1000, opts({ ripple: false })));assert.deepEqual(layout(still), [[['b', 3, 7]], [['a', 0, 4], ['c', 8, 10]], [['m', 0, 3], ['n', 9, 10]]]);- const synced = apply(value, planTransition(model, facts, 'dissolve', { a: 'a', b: 'b' }, 1000, opts({ sync: true })));- assert.deepEqual(layout(synced), [[['b', 3, 7]], [['a', 0, 4], ['c', 7, 9]], [['m', 0, 3], ['n', 8, 9]]]);+ const closed = apply(value, planTransition(model, facts, 'dissolve', { a: 'a', b: 'b' }, 1000, opts()));+ assert.deepEqual(layout(closed), [[['b', 3, 7]], [['a', 0, 4], ['c', 7, 9]], [['m', 0, 3], ['n', 9, 10]]]);});test('cross dissolve takes the incoming clip\'s linked sound along: it overlaps on a sound track below, the sounds crossfade', () => {diff --git a/packages/openfilm/studio/ui/src/lib/transitions.ts b/packages/openfilm/studio/ui/src/lib/transitions.tsindex e076e7d..ced3798 100644--- a/packages/openfilm/studio/ui/src/lib/transitions.ts+++ b/packages/openfilm/studio/ui/src/lib/transitions.ts@@ -6,10 +6,9 @@* track with room: a picture above the outgoing clip's track (the one right above when it is free* there, else a new one just above), a sound below. The incoming picture fades in over d while the* outgoing one stays whole under it, so the two blend (both fading would dip through the black- * under them); sounds both fade, out and in. With the magnet on, what follows the cut moves d- * earlier too (on the clips' tracks, and with sync lock every unlocked one), so no gap opens and- * nothing comes apart; without it, what follows stays and a gap of d is left after the incoming- * clip.+ * under them); sounds both fade, out and in. With `ripple`, what follows the cut moves d+ * earlier too, on every unlocked track, so no gap opens and nothing comes apart; without it, what+ * follows stays and a gap of d is left after the incoming clip.* Audio crossfade the same, for two sounds (a sound track below).* Dip to black no clip moves: the outgoing clip fades out over d/2, the incoming one in over d/2. The picture dips* to what is under them: the stage's black where nothing is.@@ -23,7 +22,7 @@** On the timeline a transition is found again from the fades (findTransitions): two clips whose fades meet as one of* the above made them. Removed, its fades go and its clips come back as they were cut (the incoming clip back against- * the outgoing one, on its track when there is room, what follows moving back with the magnet on); resized, the clips+ * the outgoing one, on its track when there is room, what follows moving back with `ripple`); resized, the clips* move and the fades change by the difference.** Pure: every plan is film.html's operations, one write and one undo step.@@ -84,11 +83,8 @@ export function transitionSpan(tr: FilmTransition, durationMs: number): { startM}export interface TransitionOpts {- /** The magnet on the cut's track: an overlap closes up what follows, removing one opens it again. */+ /** An overlap closes up what follows on its tracks (the main track's magnet), removing one opens it again. */ripple: boolean;- sync: boolean;- /** Linkage (timeline-edit Follow): a ripple on the main track carries the other tracks. */- linkage?: boolean;/** Linked clips go with each other (the Linked switch, unless ⌥). */linked: boolean;/** The white page's path (dip to white). */@@ -192,16 +188,15 @@ const free = (track: EditTrack, startMs: number, endMs: number, skip: ReadonlySe(c) => !skip.has(c.id) && c.startMs < endMs - TOUCH_MS && c.endMs > startMs + TOUCH_MS,);-/** A ripple from a transition's edit, carrying what sync lock or linkage carries (timeline-edit follow). */+/** A ripple from a transition's edit, on the tracks it changes (timeline-edit follow). */function rippleThrough(d: Draft,point: number,deltaMs: number,edited: Iterable<number>,- opts: TransitionOpts,skip?: ReadonlySet<string>,): void {- const f = follow(d, edited, opts);+ const f = follow(d, edited);rippleAt(d, point, deltaMs, f.tracks, skip, f.bound);}@@ -333,7 +328,7 @@ export function planTransition(model: EditModel, facts: FactsOf, kind: Transitiothen put down d earlier where there is room (see landing) */const against = new Map(moving.map((m) => [m.clip.id, partnerTrack(d, facts, m.clip, m.clip.startMs, skip) ?? m.track.index]));for (const m of moving) m.track.clips = m.track.clips.filter((c) => c.id !== m.clip.id);- if (opts.ripple) rippleThrough(d, cutMs, -overlap, homes, opts);+ if (opts.ripple) rippleThrough(d, cutMs, -overlap, homes);for (const m of moving) {m.clip.startMs -= overlap;m.clip.endMs -= overlap;@@ -384,7 +379,7 @@ export function planRemoveTransition(model: EditModel, facts: FactsOf, tr: FilmT/* where each goes back to: against the clip it overlaps, on that one's track */const homes = moving.map((m) => ({ m, home: partnerTrack(d, facts, m.clip, m.clip.startMs + back, skip) }));const reached = new Set([a.track.index, ...homes.flatMap((h) => (h.home != null ? [h.home] : []))]);- if (opts.ripple) rippleThrough(d, a.clip.endMs, back, reached, opts, skip);+ if (opts.ripple) rippleThrough(d, a.clip.endMs, back, reached, skip);for (const { m, home } of homes) {m.clip.startMs += back;m.clip.endMs += back;@@ -404,7 +399,7 @@ export function planRemoveTransition(model: EditModel, facts: FactsOf, tr: FilmT/*** A transition made `durationMs` long: an overlap's incoming clips move by the difference (what follows with them,- * with the magnet on), a dip's fades and white page change; each as far as its clips have room.+ * with `ripple`), a dip's fades and white page change; each as far as its clips have room.*/export function planResizeTransition(model: EditModel, facts: FactsOf, tr: FilmTransition, durationMs: number, opts: TransitionOpts): TransitionPlan {const d = draftOf(model);@@ -440,7 +435,7 @@ export function planResizeTransition(model: EditModel, facts: FactsOf, tr: FilmTconst delta = want - now;if (Math.abs(delta) < 0.5) return { ops: [], shortMs: 0 };for (const m of moving) { m.clip.startMs -= delta; m.clip.endMs -= delta; }- if (opts.ripple) rippleThrough(d, a.clip.endMs, -delta, [a.track.index], opts, skip);+ if (opts.ripple) rippleThrough(d, a.clip.endMs, -delta, [a.track.index], skip);for (const c of outgoing) setFade(fades, facts, c, 'out', holds(d, facts, c.id, tr.b) ? 0 : want);for (const c of incoming) setFade(fades, facts, c, 'in', want);return opsOf(d, fades);diff --git a/packages/openfilm/studio/ui/src/lib/type-metrics.ts b/packages/openfilm/studio/ui/src/lib/type-metrics.tsindex 75e977e..3b19260 100644--- a/packages/openfilm/studio/ui/src/lib/type-metrics.ts+++ b/packages/openfilm/studio/ui/src/lib/type-metrics.ts@@ -1,6 +1,6 @@/**- * Line height and letter spacing as Figma takes them: "Auto", a percentage, px — and for line height a bare number,- * CSS's multiple of the size. What is written is plain CSS: `normal`, `120%`, `24px`, `1.2` for a line height;+ * Line height and letter spacing as the inspector takes them: "Auto", a percentage, px — and for line height a bare+ * number, CSS's multiple of the size. What is written is plain CSS: `normal`, `120%`, `24px`, `1.2` for a line height;* `normal`, `2px`, and a percentage of the size as `em` (`5%` → `0.05em`) for letter spacing.** The font size menu's common sizes live here too.@@ -10,7 +10,7 @@ export type MetricKind = 'line-height' | 'letter-spacing';/** A value as the field shows it: auto, or a number in a unit (`''`: a line height's multiple). */export type Metric = 'auto' | { n: number; unit: '' | 'px' | '%' };-/** The sizes the font size menu offers, as Figma's does. */+/** The sizes the font size menu offers. */export const FONT_SIZES = [12, 14, 16, 18, 20, 24, 28, 32, 36, 40, 48, 56, 64, 72, 80, 96, 120, 144, 160, 200] as const;const round = (n: number, d = 3) => Math.round(n * 10 ** d) / 10 ** d;diff --git a/packages/openfilm/studio/ui/src/lib/workspace-resources.ts b/packages/openfilm/studio/ui/src/lib/workspace-resources.tsindex 775e9d4..96919c7 100644--- a/packages/openfilm/studio/ui/src/lib/workspace-resources.ts+++ b/packages/openfilm/studio/ui/src/lib/workspace-resources.ts@@ -82,8 +82,8 @@ export interface MediaSources {/** A web page's own poster (its middle frame); undefined falls back to the timeline's frame, then an icon. */pagePoster?(file: WorkspaceResource): string | undefined;/**- * A web page on its own, on the film's origin with Studio's bridge in it (`openfilm-studio` seek messages,- * `openfilm-film` ready/error answers): the viewer plays a picked scene through it. Undefined: cannot be previewed.+ * A web page on its own, on the film's origin with Studio's bridge in it (`openfilm-studio` seek and play messages,+ * `openfilm-film` answers): the viewer plays a picked scene through it. Undefined: cannot be previewed.*/pageSurface?(file: WorkspaceResource): string | undefined;}diff --git a/packages/shared/src/contract.test.ts b/packages/shared/src/contract.test.tsindex 6dd63d4..43c41ca 100644--- a/packages/shared/src/contract.test.ts+++ b/packages/shared/src/contract.test.ts@@ -1,6 +1,6 @@import assert from 'node:assert/strict';import { test } from 'node:test';-import { TRANSCRIPT_TEXT_MAX, clipTranscriptText, mergeStreamText, publicGenerationEventSchema, videoResultSchema } from './contract';+import { TRANSCRIPT_TEXT_MAX, clipTranscriptText, mergeStreamText, publicGenerationEventSchema, turnAttachmentSchema, videoResultSchema } from './contract';test('clipped text fits the limit, the note included, and says how much was cut', () => {assert.equal(clipTranscriptText('short', 10), 'short');@@ -24,3 +24,10 @@ test('a public result drops what only the server keeps', () => {assert.equal('taskDir' in parsed, false);assert.equal(parsed.aspect, '16:9');});++test('a sent folder keeps its path, so the message can show where it is', () => {+ const folder = { kind: 'document', name: 'temp/', path: '/Users/me/Desktop/temp' } as const;+ assert.deepEqual(turnAttachmentSchema.parse(folder), folder);+ assert.equal('path' in turnAttachmentSchema.parse({ kind: 'image', name: 'a.png' }), false);+ assert.equal(turnAttachmentSchema.safeParse({ ...folder, path: '' }).success, false);+});diff --git a/packages/shared/src/contract.ts b/packages/shared/src/contract.tsindex c6171d3..a7dd079 100644--- a/packages/shared/src/contract.ts+++ b/packages/shared/src/contract.ts@@ -29,6 +29,8 @@ export const turnAttachmentSchema = z.object({thumb: z.string().max(TURN_ATTACHMENT_THUMB_MAX_CHARS).optional(),/** The original's sha256, to open it at full size (only its owner can). Older messages have none. */sha256: z.string().regex(/^[0-9a-f]{64}$/).optional(),+ /** A folder's path on this computer, to show it in the file manager. Files and older messages have none. */+ path: z.string().min(1).max(4096).optional(),});export type TurnAttachment = z.infer<typeof turnAttachmentSchema>;