dsh-hyperframes 0.9.1 → 0.9.2

package/skills/media-use/references/mixing.md

@@ -0,0 +1,72 @@
+# Mixing in HyperFrames
+
+Preview and render run the same Web Audio graph, so what plays while scrubbing is what renders. Everything lives in attributes on the `<audio>` or `<video>` element.
+
+## Level and fades
+
+| Attribute                       | Meaning                                                                                   |
+| ------------------------------- | ----------------------------------------------------------------------------------------- |
+| `data-volume`                   | Track gain, 1 = 0 dB                                                                      |
+| `data-fade-in`, `data-fade-out` | Edge fades in seconds                                                                     |
+| `data-playback-rate`            | Constant speed, 0.1–10, pitch preserved; give a video and its paired audio the same value |
+
+A crossfade is two clips on different tracks that overlap, each with a fade.
+
+## `data-automation`: envelopes
+
+```html
+<audio
+  id="music"
+  data-automation='{"version":1,"lanes":[{"target":"volume","points":[{"t":0,"v":1},{"t":2.5,"v":0.35}]}]}'
+  …
+></audio>
+```
+
+- `target` is `volume`, `rate` (a speed ramp, 0.1–10, overrides `data-playback-rate`) or `fx.<nodeId>.<param>`.
+- `t` is seconds from the start of the clip, not of the composition. `v` is in the parameter's unit: 0..1 for volume, dB for a gain, Hz for a frequency.
+- A `volume` lane multiplies `data-volume` in preview and render, so write the level in one of them: `data-volume="0.5"` under a lane at `0.5` plays at `0.25`.
+- A lane holds its first value back to the clip's start and its last value to its end, so a bed that starts before the voice needs an explicit full-level point at `t: 0`.
+- `curve` (-1..1) bends the segment leaving a point. 512 points per lane at most.
+- Don't also tween `volume` with GSAP on a track that has a volume lane or a `data-volume`; lint flags both.
+
+## `data-fx-chain`: effects
+
+```json
+{
+  "version": 1,
+  "nodes": [
+    { "type": "highpass", "id": "n1", "label": "Remove rumble", "params": { "frequency": 80 } },
+    {
+      "type": "peaking",
+      "id": "n2",
+      "label": "Clarity",
+      "params": { "frequency": 3000, "gain": 2.5, "q": 1 }
+    },
+    { "type": "limiter", "id": "n3", "params": { "limit": -1 } }
+  ]
+}
+```
+
+- Write the attribute double-quoted with the JSON's quotes as `&quot;`.
+- Order is signal order. `id` is what automation targets (`fx.n2.gain`); give every node one, and a `label` when it does a named job. `enabled: false` bypasses a node.
+- Effects: `gain`, `highpass`, `lowpass`, `peaking`, `lowshelf`, `highshelf`, `compressor`, `limiter`, `gate`, `saturate`, `delay`, `reverb`, `chorus`, `phaser`, `bitcrush`.
+- `compressor`, `limiter`, `gate` and `bitcrush` can't be automated; a lane on them does nothing. Automate a `gain` before them instead.
+- Never set `fromCarve` by hand.
+- `reverb` and `delay` make the rendered track longer than its source; that is expected.
+
+| It sounds like              | Reach for                                   |
+| --------------------------- | ------------------------------------------- |
+| Hum, rumble, handling noise | `highpass` at 80 Hz                         |
+| Boomy, too close            | `peaking` 200 Hz, −4 dB                     |
+| Muffled                     | `peaking` 250 Hz, −3 dB                     |
+| Words hard to make out      | `peaking` 3 kHz, +2.5 dB, or duck the music |
+| Harsh                       | `peaking` 3.2 kHz, −3 dB                    |
+| Peaks clipping              | `limiter` last in the chain                 |
+
+## Music under a voice
+
+Duck the bed with a `volume` lane on the music: full level before the voice, down to about 0.3–0.4 while anyone speaks (word timings from `npx hyperframes transcribe` or the voiceover give the times), back up after. Then carve the bed, which dips only the bands the voice uses: `node <SKILL_DIR>/audio/scripts/carve.mjs --comp index.html` (needs `ffmpeg` and `@hyperframes/core` in the project; `--dry-run` to see the plan). It is the same analysis as Studio's carve panel. It reads only double-quoted attributes (JSON quotes as `&quot;`), so write the bed's chain and lanes that way or it overwrites them. Never put a carve on a voice track.
+
+## Group buses
+
+Give clips the same `data-audio-group="<id>"` to treat them as one group. An `<hf-audio-group id="<id>"></hf-audio-group>` element with that id (closed like that: `/>` does not close it) makes the group a submix bus with one `data-fx-chain`, one volume and one automation clock for every member. Keep one role per group: `voiceover`, `music`, `sfx`.

package/skills/media-use/references/operations.md

@@ -16,7 +16,7 @@ ffmpeg -i in.mp4 -ss 00:00:12 -to 00:00:20 -c copy out.mp4   # 0:12–0:20, no r
 ```
 
 In-composition trimming usually needs **no new file**: a clip plays a sub-window
-via `data-media-start` + `data-duration` (see hyperframes-core). Only cut a
+via `data-media-start` + `data-duration` (see `/hyperframes` → `references/format.md`). Only cut a
 physical file when exporting/assembling outside the composition.
 
 ## Reframe / crop: change aspect ratio
@@ -121,7 +121,9 @@ VERIFIED on 24GB: accurate, ~3s (cached) for 8s audio. Parakeet covers 25
 European languages, English included. For other languages, or when parakeet-mlx is not
 installed, transcribe.mjs falls back to `hyperframes transcribe`, which uses the
 CLI's Parakeet when `models install parakeet` has run and whisper.cpp (99
-languages) otherwise. `--engine parakeet|whisper` forces one. (Cohere
+languages) otherwise. `--engine parakeet|whisper` forces one, except that a
+`--language` other than English runs whisper whenever it is installed, since
+Parakeet detects the language itself. (Cohere
 Transcribe tops the leaderboard on paper but its mlx-audio quants produced
 garbage and ran 40-70x slower on a Mac in testing, so it is not wired in.)
 
@@ -210,9 +212,9 @@ ffmpeg -i mix.wav \
 GENERATES. Two paths, best-for-the-machine picked automatically:
 
 1. **Local (default, free, private): mflux** (FLUX-on-MLX). `resolve` spec-checks
-   AVAILABLE RAM and runs the best FLUX-class model that fits, via
-   `scripts/lib/local-models.mjs` (`imagegen` ladder) + `mflux-provider.mjs`.
-   The RAM ladder (agent sees it via `describeModelLadder("imagegen", specs)`):
+   AVAILABLE RAM and runs the best FLUX-class model that fits, using the
+   CLI-bundled `imagegen` ladder (its modules are not shipped in the standalone
+   skill). The RAM ladder:
 
    | Tier   | Model                | Needs (available RAM) | Notes                               |
    | ------ | -------------------- | --------------------- | ----------------------------------- |
@@ -245,7 +247,7 @@ clip), so treat the fallback as "HeyGen wasn't reachable," not "upgrade the
 quality":
 
 - **HeyGen avatar video (default, free for new API users):**
-  `heygenVideoGenerate` (`scripts/lib/heygen-video-provider.mjs`) shells the
+  The CLI-bundled provider shells the
   `heygen` CLI — never the raw API — auto-picking a public avatar and a
   starfish voice (override with `--avatar-id`/`--voice-id`, threaded through
   as `ctx.avatarId`/`ctx.voiceId`). If the CLI reports `not_authenticated`,
@@ -253,13 +255,13 @@ quality":
   new API users — sign in) to stderr and falls through to LTX instead of
   hard-failing.
 - **Local fallback: LTX 2.3 on MLX** via `dgrauet/ltx-2-mlx`, the `videogen`
-  ladder in `local-models.mjs` (`ltx-video-provider.mjs`). Generative clips
+  ladder bundled in the HyperFrames CLI. Generative clips
   (t2v), spec-gated to RAM. Verified on 24GB: 512x320 x 33f with audio.
 
 Every generating `heygen` call from media-use — TTS, avatar video, and
 catalog search — sends the allowlisted `X-HeyGen-Client-Source: media-use`
 header (persistent flag, works on every subcommand) via the shared
-`HEYGEN_CLIENT_SOURCE_ARGV` constant (`scripts/lib/heygen-cli.mjs`), so usage
+CLI-internal `HEYGEN_CLIENT_SOURCE_ARGV` constant, so usage
 tags correctly in billing/resource meta and shows up in the API dashboards.
 Read-only discovery (`avatar list`, `voice list`) doesn't need it.
 

package/skills/media-use/references/resolve.md

@@ -11,7 +11,7 @@ Returns one line: `resolved <id> → <path> (<type>, <metadata>)`
 | Type    | What it finds                    | Provider / cascade                                           |
 | ------- | -------------------------------- | ------------------------------------------------------------ |
 | `bgm`   | Background music                 | HeyGen audio catalog (10k+ tracks)                           |
-| `sfx`   | Sound effects                    | Bundled 19-file library + HeyGen catalog                     |
+| `sfx`   | Sound effects                    | Openverse (CC0 / CC BY), then the bundled 21-file library    |
 | `image` | Photos, backgrounds              | HeyGen asset search (75k+ vectors)                           |
 | `icon`  | Icons, symbols                   | HeyGen asset search (type=icon)                              |
 | `logo`  | Official brand marks             | theSVG → GitHub org avatar → domain favicon                  |

package/skills/media-use/references/setup-providers.md

@@ -9,25 +9,40 @@ heygen update             # free usage needs the OAuth-capable CLI (v0.3.0+)
 heygen auth login --oauth # OAuth = free subscription credits; --api-key bills API credits
 ```
 
-This unlocks the FREE path for bgm/sfx/image/icon catalog search, TTS (voice), and avatar videos. Sign in with `--oauth` — the free allowance rides on the OAuth session (an API key bills API credits instead). **media-use requires heygen >= v0.3.0 uniformly** (the OAuth free-usage path needs it), so `--doctor` nudges older CLIs to update even for API-key-only use. Before resolving anything, verify setup with:
+This unlocks the FREE path for bgm/image/icon catalog search, TTS (voice), and avatar videos. Sign in with `--oauth` — the free allowance rides on the OAuth session (an API key bills API credits instead). **media-use requires heygen >= v0.3.0 uniformly** (the OAuth free-usage path needs it), so `--doctor` nudges older CLIs to update even for API-key-only use. Before resolving anything, verify setup with:
 
 ```bash
 npx hyperframes media-use resolve --doctor
 ```
 
+## Host HeyGen access (no CLI sign-in)
+
+A host app can give media-use HeyGen access of its own by setting
+`HEYGEN_API_BASE` (its gateway), `HEYGEN_API_KEY` (the token that gateway
+accepts) and, for a loopback gateway, `HEYGEN_ALLOW_HTTP=1`. The gateway adds
+the host's key, so it never enters the agent's environment, and every
+call is charged to that key's API credits. The `heygen` CLI honours the same
+variables, so `resolve` (bgm/sfx/image/icon/voice/avatar-video) and the audio
+engine's TTS all go through the host. With host access, skip CLI install and
+sign-in, prefer the host's own HeyGen tools where it has them, never fall back
+to a local or third-party generator on your own, and relay a refused call's
+message (for example "add a key in Settings > Account") as written.
+
 ## Providers
 
 media-use holds no keys; every external tool owns its auth. Generation is
 centered on the HeyGen CLI free-usage path. Install and authenticate `heygen`
-before resolving bgm/sfx/image/icon/voice/avatar-video. Local tools are opt-in
+before resolving bgm/sfx/image/icon/voice/avatar-video; music and sound effects from
+a host app's own tools need none of it. Local tools are opt-in
 alternatives where they exist: mflux for image, Kokoro for voice, Parakeet for
 transcription, and LTX for local video generation. `resolve` spec-checks
-AVAILABLE RAM for those local ladders (`describeModelLadder`); the agent can
-see the ladder and override.
+AVAILABLE RAM for those local ladders inside the CLI (the image tiers are listed
+in `references/operations.md`).
 
 | Type      | Provider / path                                                                                                                                                               |
 | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| bgm/sfx   | heygen catalog free-usage path                                                                                                                                                |
+| bgm       | heygen catalog free-usage path; a host app's own music tools come first                                                                                                       |
+| sfx       | Openverse (CC0 / CC BY, no account), bundled library offline; a host app's own sound tools come first                                                                         |
 | image     | heygen search free-usage path; optional local mflux; codex `image_gen` upsell                                                                                                 |
 | voice     | heygen tts free-usage path; optional local **Kokoro** (free, on-device)                                                                                                       |
 | icon      | heygen asset search free-usage path                                                                                                                                           |
@@ -53,25 +68,24 @@ HeyGen-only types, that means no fresh resolve.
 ## CLI tools used (what to run, and how to enable each)
 
 `resolve` auto-cascades; each provider shells one CLI. HeyGen is the
-free-usage path for bgm/sfx/image/icon catalog search, TTS (voice), and avatar
+free-usage path for bgm/image/icon catalog search, TTS (voice), and avatar
 video, so those capabilities need `heygen` installed and authenticated. Local
 tools are OPT-IN alternatives where they exist; install one to unlock its free,
 private, on-device path instead of or ahead of HeyGen for that type. Only
 `ffmpeg`/`ffprobe` are strictly required for the tool to run at all.
 
-| Tool               | Serves                                                                          | Install                                                                                                                                                                                     |
-| ------------------ | ------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm                | system package (`brew install ffmpeg`)                                                                                                                                                      |
-| `heygen`           | catalog (bgm/sfx/image/icon) + TTS (voice) + avatar video — the free-usage path | install through [verified HeyGen release instructions](https://developers.heygen.com/cli), then `heygen auth login --oauth` (needs >= v0.3.0)                                               |
-| `mflux-generate`   | local image gen (FLUX), best-for-RAM                                            | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6`                                                                                                          |
-| `codex`            | image gen upsell (ChatGPT sub)                                                  | Codex CLI, logged in via ChatGPT (owns its own auth)                                                                                                                                        |
-| `parakeet-mlx`     | local transcription (default ASR, best) on Apple Silicon                        | `uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx`                                                                                                    |
-| `ltx-2-mlx`        | local video gen                                                                 | `git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras`                                                                                                    |
-| `npx hyperframes`  | Kokoro TTS (voice), Parakeet or whisper.cpp (transcribe), remove-background     | via the hyperframes CLI; Parakeet on macOS, Windows and glibc 2.32+ Linux: `npx hyperframes models install parakeet`; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake) |
+| Tool               | Serves                                                                      | Install                                                                                                                                                                                     |
+| ------------------ | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `ffmpeg`/`ffprobe` | adopt probing, smart-grade signalstats, cut, duck bake, loudnorm            | system package (`brew install ffmpeg`)                                                                                                                                                      |
+| `heygen`           | catalog (bgm/image/icon) + TTS (voice) + avatar video — the free-usage path | install through [verified HeyGen release instructions](https://developers.heygen.com/cli), then `heygen auth login --oauth` (needs >= v0.3.0)                                               |
+| `mflux-generate`   | local image gen (FLUX), best-for-RAM                                        | `uv venv ~/.venvs/mflux && VIRTUAL_ENV=~/.venvs/mflux uv pip install mflux==0.9.6`                                                                                                          |
+| `codex`            | image gen upsell (ChatGPT sub)                                              | Codex CLI, logged in via ChatGPT (owns its own auth)                                                                                                                                        |
+| `parakeet-mlx`     | local transcription (default ASR, best) on Apple Silicon                    | `uv venv ~/.venvs/parakeet && VIRTUAL_ENV=~/.venvs/parakeet uv pip install parakeet-mlx`                                                                                                    |
+| `ltx-2-mlx`        | local video gen                                                             | `git clone https://github.com/dgrauet/ltx-2-mlx && cd ltx-2-mlx && uv sync --all-extras`                                                                                                    |
+| `npx hyperframes`  | Kokoro TTS (voice), Parakeet or whisper.cpp (transcribe), remove-background | via the hyperframes CLI; Parakeet on macOS, Windows and glibc 2.32+ Linux: `npx hyperframes models install parakeet`; whisper.cpp is built on first use (Homebrew on macOS, else git+cmake) |
 
 The RAM-graded local-model shortlist + exact per-tier install/invoke lives in
-`scripts/lib/local-models.mjs` (the agent can read `describeModelLadder(cap, specs)`
-to see which model fits this machine). Without a tool on PATH, its provider
+the CLI's bundled media-use engine, not in the standalone skill. Without a tool on PATH, its provider
 prints a one-line diagnostic to stderr and resolve falls through where another
 provider exists (e.g. no `mflux` -> codex image upsell; no `parakeet-mlx` -> whisper.cpp).
 

package/skills/media-use/scripts/compatibility.test.mjs

@@ -1,10 +1,8 @@
-import assert from "node:assert/strict";
-import { cpSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, mkdtempSync, rmSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { execFileSync } from "node:child_process";
 import test from "node:test";
-import { pathToFileURL } from "node:url";
 
 process.env.HYPERFRAMES_MEDIA_HOME = mkdtempSync(join(tmpdir(), "media-use-compat-home-"));
 
@@ -41,56 +39,3 @@ test("published audio helpers import without the CLI package tree", () => {
     rmSync(root, { recursive: true, force: true });
   }
 });
-
-for (const name of ["faceless-explainer", "pr-to-video", "product-launch-video"]) {
-  test(name + " assembles from its installed directory alone", () => {
-    const root = mkdtempSync(join(tmpdir(), "installed-workflow-"));
-    try {
-      const skill = join(root, name);
-      cpSync(new URL("../../" + name, import.meta.url), skill, { recursive: true });
-      const project = join(root, "project");
-      mkdirSync(join(project, "compositions/frames"), { recursive: true });
-      writeFileSync(
-        join(project, "STORYBOARD.md"),
-        "---\nformat: 1920x1080\nmessage: Test\n---\n\n## Frame 1\n- duration: 3s\n- src: compositions/frames/01-a.html\n",
-      );
-      writeFileSync(
-        join(project, "compositions/frames/01-a.html"),
-        '<template><div data-composition-id="01-a" data-duration="3" data-width="1920" data-height="1080"><section class="clip" data-start="0" data-duration="3"></section></div></template>',
-      );
-      run(join(skill, "scripts"), "assemble-index.mjs", [
-        "--hyperframes",
-        project,
-        "--storyboard",
-        join(project, "STORYBOARD.md"),
-      ]);
-      assert.match(readFileSync(join(project, "index.html"), "utf8"), /01-a/);
-      importPacketBuilder(join(skill, "scripts/frame-packets.mjs"));
-    } finally {
-      rmSync(root, { recursive: true, force: true });
-    }
-  });
-}
-
-test("general-video packet builder starts from its installed directory alone", () => {
-  const root = mkdtempSync(join(tmpdir(), "installed-packets-"));
-  try {
-    cpSync(new URL("../../general-video", import.meta.url), root, { recursive: true });
-    importPacketBuilder(join(root, "scripts/frame-packets.mjs"));
-  } finally {
-    rmSync(root, { recursive: true, force: true });
-  }
-});
-
-function importPacketBuilder(path) {
-  execFileSync(
-    process.execPath,
-    [
-      "--input-type=module",
-      "-e",
-      'const m = await import(process.argv[1]); if (typeof m.buildFramePackets !== "function") throw new Error("missing builder");',
-      pathToFileURL(path).href,
-    ],
-    { stdio: "pipe" },
-  );
-}

package/skills/media-use/scripts/lib/cutlist.mjs

@@ -148,7 +148,7 @@ function clampRanges(ranges, duration) {
 
 function mergeRanges(ranges) {
   const sorted = ranges
-    .map((range) => ({ start: round3(range.start), end: round3(range.end) }))
+    .map((range) => ({ start: round6(range.start), end: round6(range.end) }))
     .sort((a, b) => a.start - b.start || a.end - b.end);
   const merged = [];
   for (const range of sorted) {
@@ -173,12 +173,19 @@ function invertRanges(removals, duration) {
   return kept;
 }
 
+// Range bounds are rounded only to shed float noise, never to the millisecond:
+// these values become ffmpeg's -ss/-to, where a millisecond is wide enough to
+// step a boundary onto the next frame at 29.97/30/60 fps.
 function finalizeKept(ranges) {
   return mergeRanges(ranges)
-    .map((range) => ({ start: round3(range.start), end: round3(range.end) }))
+    .map((range) => ({ start: round6(range.start), end: round6(range.end) }))
     .filter((range) => round3(range.end - range.start) >= MIN_SEGMENT_SECONDS);
 }
 
+function round6(n) {
+  return Math.round(Number(n) * 1e6) / 1e6;
+}
+
 function round3(n) {
   return Math.round(Number(n) * 1000) / 1000;
 }

package/skills/media-use/scripts/lib/duck.mjs

@@ -5,7 +5,7 @@ export function speechSpans(meta, { mergeGap = 0.6, offsets, sequential = false,
   const merge = Number(mergeGap);
   const lists = wordListsFromMediaMeta(meta);
   const voices = Array.isArray(meta?.voices) ? meta.voices : [];
-  if (lists.length > 1 && !offsets && !sequential) {
+  if (lists.filter((words) => words.length > 0).length > 1 && !offsets && !sequential) {
     throw new Error(
       "audio_meta has multiple voice lines with file-relative times; pass --sequential or --offsets so spans land at composition time",
     );
@@ -16,6 +16,7 @@ export function speechSpans(meta, { mergeGap = 0.6, offsets, sequential = false,
     const voice = voices[i];
     let offset = 0;
     if (offsets) {
+      if (lists[i].length === 0) continue;
       const id = voice?.id ?? String(i);
       if (!(id in offsets)) throw new Error(`--offsets is missing voice "${id}"`);
       offset = Number(offsets[id]) || 0;
@@ -62,11 +63,27 @@ export function duckLane(keyframes, { clipStart = 0, baseVolume = 1 } = {}) {
     if (t > points.at(-1).t) points.push({ t: round3(t), v });
   };
   for (const kf of keyframes) {
-    const t = Math.max(0, kf.time - start);
+    const t = Math.max(0, kf.time);
     push(t, points.at(-1).v);
     push(t + kf.duration, kf.volume);
   }
-  return { version: 1, lanes: [{ target: "volume", points }] };
+
+  const next = points.findIndex((point) => point.t > start);
+  const before = points[next - 1] ?? points.at(-1);
+  const after = points[next];
+  const initial =
+    next === 0
+      ? points[0].v
+      : after
+        ? before.v + ((after.v - before.v) * (start - before.t)) / (after.t - before.t)
+        : before.v;
+  const localPoints = [
+    { t: 0, v: initial },
+    ...points
+      .filter((point) => point.t > start)
+      .map((point) => ({ t: round3(point.t - start), v: point.v })),
+  ];
+  return { version: 1, lanes: [{ target: "volume", points: localPoints }] };
 }
 
 function mergeIntervals(intervals, mergeGap) {

package/skills/media-use/scripts/lib/index-gen.mjs

@@ -1,6 +1,6 @@
 import { writeFileSync, mkdirSync } from "node:fs";
 import { dirname } from "node:path";
-import { readManifest, indexPath } from "./manifest.mjs";
+import { currentRecords, indexPath } from "./manifest.mjs";
 
 function pad(str, len) {
   return String(str ?? "").padEnd(len);
@@ -54,7 +54,7 @@ export function generateIndexContent(records) {
 }
 
 export function regenerateIndex(projectDir) {
-  const records = readManifest(projectDir);
+  const records = currentRecords(projectDir);
   const content = generateIndexContent(records);
   const p = indexPath(projectDir);
   mkdirSync(dirname(p), { recursive: true });

package/skills/media-use/scripts/lib/manifest.mjs

@@ -10,7 +10,8 @@ import {
   rmSync,
   statSync,
 } from "node:fs";
-import { join } from "node:path";
+import { randomBytes } from "node:crypto";
+import { basename, join } from "node:path";
 
 const MANIFEST_FILE = "manifest.jsonl";
 const INDEX_FILE = "index.md";
@@ -79,6 +80,45 @@ export function appendRecord(projectDir, record) {
   appendFileSync(p, line);
 }
 
+/** Sources that mean the agent made or fetched the file; any other file is the person's own. */
+export const AGENT_SOURCES = ["generated", "search", "bundled"];
+
+/** The record a path has now: the manifest only appends, so the last one for a path wins. */
+export function latestRecordFor(projectDir, path) {
+  return readManifest(projectDir).findLast((record) => record.path === path);
+}
+
+/** Records with every older record for the same path dropped, since the last one for a path is its record. */
+export function currentRecords(projectDir) {
+  const records = readManifest(projectDir);
+  const last = new Map(records.map((record, index) => [record.path, index]));
+  return records.filter((record, index) => !record.path || last.get(record.path) === index);
+}
+
+/** Records a file already in the project where it is, unless its current record already says the same thing. */
+export function recordInPlace(
+  projectDir,
+  { type, path, source, description, duration, provenance },
+) {
+  const fields = {
+    type,
+    path,
+    source,
+    description: description || basename(path),
+    ...(duration != null && { duration: Math.round(duration * 10) / 10 }),
+  };
+  return withMediaLock(projectDir, () => {
+    const latest = latestRecordFor(projectDir, path);
+    const same = ["source", "description", "duration"].every(
+      (key) => latest?.[key] === fields[key],
+    );
+    if (latest && same) return latest;
+    const record = { id: nextFreeId(projectDir, type), ...fields, provenance };
+    appendRecord(projectDir, record);
+    return record;
+  });
+}
+
 // Match prompts forgivingly. Agents rarely re-emit a byte-identical intent, so
 // keying cache lookups on exact equality meant "Calm piano" and "calm  piano"
 // re-searched and re-downloaded. Normalize (trim, lowercase, collapse internal
@@ -93,7 +133,7 @@ export function normalizePrompt(prompt) {
 export function findByPrompt(projectDir, prompt, type) {
   const key = normalizePrompt(prompt);
   if (!key) return null;
-  const records = readManifest(projectDir);
+  const records = currentRecords(projectDir);
   return (
     records.find(
       (r) => normalizePrompt(r.provenance?.prompt) === key && (type == null || r.type === type),
@@ -103,7 +143,7 @@ export function findByPrompt(projectDir, prompt, type) {
 
 export function findByEntity(projectDir, entity) {
   const lower = entity.toLowerCase();
-  const records = readManifest(projectDir);
+  const records = currentRecords(projectDir);
   return records.find((r) => r.entity && r.entity.toLowerCase() === lower) || null;
 }
 
@@ -162,56 +202,69 @@ function withLock(dir, fn) {
   }
 }
 
-// Atomically allocate the next free id for `type` AND reserve its file, so a
+/** Runs `fn` holding the project's `.media/.lock`, so concurrent resolves take turns on what it guards. */
+export function withMediaLock(projectDir, fn) {
+  mkdirSync(mediaDir(projectDir), { recursive: true });
+  return withLock(mediaDir(projectDir), fn);
+}
+
+// Atomically allocate the next free id for `type` AND reserve it on disk, so a
 // slow download/copy between allocation and appendRecord can't let a concurrent
 // caller grab the same id (the MU-23 clobber). Under the lock we take the max id
 // across BOTH the manifest and any already-reserved files in the type dir, then
-// O_EXCL-create an empty placeholder at the target path; freeze/copy overwrites
-// it. Returns { id, localPath }.
+// O_EXCL-create an empty marker under core's atomic temp name, which Studio's
+// project history skips. Returns { id, localPath, markerPath }.
 export function allocateId(projectDir, type, ext) {
-  mkdirSync(mediaDir(projectDir), { recursive: true });
-  const typeDir = typeDirPath(projectDir, type);
-  mkdirSync(typeDir, { recursive: true });
-  return withLock(mediaDir(projectDir), () => {
-    const re = new RegExp(`^${type}_(\\d+)`);
-    let max = 0;
-    for (const r of readManifest(projectDir)) {
-      if (r.type !== type) continue;
-      const m = r.id?.match(re);
-      if (m) max = Math.max(max, parseInt(m[1], 10));
-    }
-    for (const f of readdirSync(typeDir)) {
-      const m = f.match(re);
-      if (m) max = Math.max(max, parseInt(m[1], 10)); // skip ids reserved but not yet appended
-    }
-    const id = `${type}_${String(max + 1).padStart(3, "0")}`;
+  mkdirSync(typeDirPath(projectDir, type), { recursive: true });
+  return withMediaLock(projectDir, () => {
+    const id = nextFreeId(projectDir, type);
     const localPath = `.media/${typeSubdir(type)}/${id}${ext}`;
-    writeFileSync(join(projectDir, localPath), "", { flag: "wx" }); // durable reservation
-    return { id, localPath };
+    // Same shape as core atomicTempPath: an empty file at the final name would be committed.
+    const markerPath = `${join(projectDir, localPath)}.hf${randomBytes(3).toString("hex")}.tmp`;
+    writeFileSync(markerPath, "", { flag: "wx" }); // durable reservation
+    return { id, localPath, markerPath };
   });
 }
 
+// Call under the lock: counts recorded ids and ids reserved by a file not yet recorded.
+function nextFreeId(projectDir, type) {
+  const re = new RegExp(`^${type}_(\\d+)`);
+  let max = 0;
+  for (const r of readManifest(projectDir)) {
+    if (r.type !== type) continue;
+    const m = r.id?.match(re);
+    if (m) max = Math.max(max, parseInt(m[1], 10));
+  }
+  const typeDir = typeDirPath(projectDir, type);
+  for (const f of existsSync(typeDir) ? readdirSync(typeDir) : []) {
+    const m = f.match(re);
+    if (m) max = Math.max(max, parseInt(m[1], 10));
+  }
+  return `${type}_${String(max + 1).padStart(3, "0")}`;
+}
+
 function reservedFile(projectDir, type, ext) {
   const allocation = allocateId(projectDir, type, ext);
   return { ...allocation, fullPath: join(projectDir, allocation.localPath) };
 }
 
-function rollbackReservation(reservation) {
-  rmSync(reservation.fullPath, { force: true });
+function releaseReservation(reservation, committed) {
+  if (!committed) rmSync(reservation.fullPath, { force: true });
+  rmSync(reservation.markerPath, { force: true });
 }
 
 // A reservation is committed only when populate returns a non-null value.
 // Throwing/rejecting or returning null means no usable asset was produced, so
-// the placeholder must be released. Keeping this transaction beside allocateId
-// prevents individual provider/cache/LUT paths from forgetting the rollback.
+// the reservation and any partial asset are released. Keeping this transaction
+// beside allocateId prevents provider/cache/LUT paths from forgetting the rollback.
 export function withReservedFileSync(projectDir, type, ext, populate) {
   const reservation = reservedFile(projectDir, type, ext);
   try {
     const result = populate(reservation);
-    if (result == null) rollbackReservation(reservation);
+    releaseReservation(reservation, result != null);
     return result;
   } catch (error) {
-    rollbackReservation(reservation);
+    releaseReservation(reservation, false);
     throw error;
   }
 }
@@ -220,10 +273,10 @@ export async function withReservedFile(projectDir, type, ext, populate) {
   const reservation = reservedFile(projectDir, type, ext);
   try {
     const result = await populate(reservation);
-    if (result == null) rollbackReservation(reservation);
+    releaseReservation(reservation, result != null);
     return result;
   } catch (error) {
-    rollbackReservation(reservation);
+    releaseReservation(reservation, false);
     throw error;
   }
 }