@hypit/hypit 0.1.3 → 0.1.5

package/packages/studio/package.json

@@ -12,34 +12,35 @@
     "@hypit/build-result": "workspace:*",
     "@hypit/caption-fine-studio": "workspace:*",
     "@hypit/cli": "workspace:*",
+    "@hypit/comment-sticker-studio": "workspace:*",
     "@hypit/compiler-node": "workspace:*",
     "@hypit/component-kit": "workspace:*",
     "@hypit/composition": "workspace:*",
-    "@hypit/comment-sticker-studio": "workspace:*",
     "@hypit/core": "workspace:*",
-    "@hypit/driver-node": "workspace:*",
     "@hypit/deck-track-studio": "workspace:*",
+    "@hypit/driver-node": "workspace:*",
     "@hypit/elaborator": "workspace:*",
     "@hypit/film-studio": "workspace:*",
     "@hypit/hyperframes": "workspace:*",
     "@hypit/markup": "workspace:*",
     "@hypit/media-track-studio": "workspace:*",
-    "@hypit/narrative": "workspace:*",
     "@hypit/package-loader-node": "workspace:*",
+    "@hypit/performance-studio": "workspace:*",
+    "@hypit/sound-studio": "workspace:*",
     "@hypit/program-space": "workspace:*",
+    "@hypit/project-context-node": "workspace:*",
     "@hypit/protocol": "workspace:*",
     "@hypit/ranking-studio": "workspace:*",
     "@hypit/run": "workspace:*",
     "@hypit/runtime": "workspace:*",
     "@hypit/runtime-host-node": "workspace:*",
-    "@hypit/script-studio": "workspace:*",
     "@hypit/screen-overlay-studio": "workspace:*",
+    "@hypit/script-studio": "workspace:*",
     "@hypit/speech": "workspace:*",
-    "@hypit/semantic-track": "workspace:*",
+    "@hypit/studio-adapter": "workspace:*",
     "@hypit/svs": "workspace:*",
     "@hypit/temporal": "workspace:*",
-    "@hypit/studio-adapter": "workspace:*",
-    "@hypit/speech-track-studio": "workspace:*",
+    "@hypit/timeline": "workspace:*",
     "@hypit/typography-track-studio": "workspace:*",
     "@hypit/validation": "workspace:*",
     "@hypit/video-cli": "workspace:*",

package/packages/studio/src/build-library.ts

@@ -1,3 +1,4 @@
+import { fileReferenceIdentity } from "@hypit/build-result";
 import { isAbsolute, relative, resolve, sep } from "node:path";
 
 import { buildIdCreatedAt } from "@hypit/protocol";
@@ -5,17 +6,16 @@ import type { BuildView, NodeRuntimeHost, RuntimeHostTransientExecution } from "
 import type { StoredValue, TypeRef } from "@hypit/protocol";
 import type {
   BuildResultFileRange,
-  BuildResultFileRef,
   BuildResultManifest,
   BuildResultRepository,
   FinishedBuildResultManifest,
-  RepositoryBuildResultOutput,
 } from "@hypit/build-result";
 
 import { resolveBuildResultValue } from "@hypit/cli";
 import { videoCliDistribution } from "@hypit/video-cli";
 
-import type { StudioArtifactView, StudioLibraryView, StudioTaskView } from "./shared.js";
+import type { StudioArtifactView, StudioLibraryRequest, StudioLibraryView, StudioTaskView } from "./shared.js";
+import { mergeStudioArtifacts } from "./library-media.js";
 
 type RuntimeControl = Awaited<ReturnType<NodeRuntimeHost["openControl"]>>;
 
@@ -24,7 +24,8 @@ export type StudioBuildLibrary = {
   readonly runtime?: Pick<RuntimeControl, "activity">;
   /** Runtime-owned, disposable execution for the current authoring session. */
   readonly transientExecution?: RuntimeHostTransientExecution;
-  readonly library: (before?: string) => Promise<StudioLibraryView>;
+  readonly library: (request: StudioLibraryRequest) => Promise<StudioLibraryView>;
+  readonly renameArtifact: (build: string, output: string, displayName: string | null) => Promise<string | undefined>;
   readonly resolveHistoricalOutput: (
     build: string,
     output: string,
@@ -36,7 +37,6 @@ export type StudioBuildLibrary = {
   readonly openArtifact: (
     build: string,
     output: string,
-    valuePath: string,
   ) => Promise<{
     readonly mediaType: string;
     readonly size: number;
@@ -51,7 +51,7 @@ function projectPath(root: string, path: string): string {
 
 function isWithin(root: string, path: string): boolean {
   const rel = relative(resolve(root), projectPath(root, path));
-  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
 }
 
 /**
@@ -65,15 +65,9 @@ function presentedPath(root: string, path: string): string {
   return (relative(resolve(root), absolute) || ".").split(sep).join("/");
 }
 
-function buildBelongsTo(root: string, view: BuildView): boolean {
-  return view.source !== undefined
-    && (isWithin(root, view.run?.path ?? view.source.path) || isWithin(root, view.source.path));
-}
-
 function taskStatus(view: BuildView): StudioTaskView["status"] {
-  if (view.issue !== undefined) return "blocked";
+  if (view.issue !== undefined) return "attention";
   if (view.activity === "submitting" || view.activity === "ready") return "queued";
-  if (view.activity === "saving-result") return "active";
   return view.activity;
 }
 
@@ -83,18 +77,20 @@ function taskView(
   result?: BuildResultManifest,
 ): StudioTaskView {
   if (view.source === undefined) throw new Error(`Active Build ${view.id} has no source`);
+  const detail = view.issue?.message ?? view.stop?.reason;
   return {
     id: view.id,
     ...(result?.title === undefined ? {} : { title: result.title }),
     ...(result?.note === undefined ? {} : { note: result.note }),
     ...(result?.highlightedOutputs === undefined ? {} : { highlightedOutputs: result.highlightedOutputs }),
     createdAt: view.createdAt,
+    ongoing: true,
     status: taskStatus(view),
+    ...(detail === undefined ? {} : { detail }),
+    ...(view.requests === undefined ? {} : { requests: view.requests }),
     source: presentedPath(root, view.source.path),
     ...(view.run === undefined ? {} : { run: presentedPath(root, view.run.path) }),
     targets: result?.targets ?? view.targets,
-    acceptedRecords: view.acceptedRecords,
-    outstandingCommands: view.outstandingCommands,
     operations: view.operations.map((operation) => ({
       status: operation.status,
       ...(operation.progress?.phase === undefined ? {} : { phase: operation.progress.phase }),
@@ -112,107 +108,117 @@ function resultTaskView(root: string, result: FinishedBuildResultManifest): Stud
     ...(result.note === undefined ? {} : { note: result.note }),
     ...(result.highlightedOutputs === undefined ? {} : { highlightedOutputs: result.highlightedOutputs }),
     createdAt: buildIdCreatedAt(result.id)!,
+    finishedAt: result.finishedAt,
+    ongoing: false,
     status: result.outcome,
+    ...(result.failure === undefined ? {} : { detail: result.failure }),
     source: presentedPath(root, result.source.path),
     ...(result.run === undefined ? {} : { run: presentedPath(root, result.run.path) }),
     targets: result.targets,
-    acceptedRecords: Object.keys(result.outputs).length,
-    outstandingCommands: 0,
     operations: [],
   };
 }
 
-function presentedValuePath(path: readonly (string | number)[]): string {
-  return path.reduce<string>((current, segment) => typeof segment === "number"
-    ? `${current}[${segment}]`
-    : /^[A-Za-z_$][A-Za-z0-9_$]*$/u.test(segment)
-      ? `${current}.${segment}`
-      : `${current}[${JSON.stringify(segment)}]`, "$");
-}
-
-function filesInResolvedOutput(resolved: RepositoryBuildResultOutput): readonly {
-  readonly valuePath: string;
-  readonly file: BuildResultFileRef;
-}[] {
-  if (resolved.value.kind === "build-file") return [{ valuePath: "$", file: resolved.value }];
-  if (resolved.value.kind === "value") {
-    return resolved.value.document.resources.map((binding) => ({
-      valuePath: presentedValuePath(binding.at),
-      file: binding.file,
-    }));
-  }
-  return [];
+function isMedia(mediaType: string): boolean {
+  return /^(image|video|audio)\//u.test(mediaType);
 }
 
 async function artifactsForResults(
   root: string,
   repository: BuildResultRepository,
   manifests: readonly BuildResultManifest[],
+  media?: StudioLibraryRequest["media"],
 ): Promise<readonly StudioArtifactView[]> {
   const nested = await Promise.all(manifests.flatMap((manifest) =>
-    Object.keys(manifest.outputs).map(async (output) => {
-      const resolved = await repository.resolve(manifest.id, output);
-      if (resolved === undefined) return [];
-      return filesInResolvedOutput(resolved).map(({ valuePath, file }) => ({
-        id: `${manifest.id}:${output}:${valuePath}`,
+    Object.entries(manifest.outputs).map(async ([output, entry]): Promise<StudioArtifactView[]> => {
+      // Composite Outputs remain intact. Listing media never opens their Value Documents.
+      if (entry.value.kind !== "build-file" && entry.value.kind !== "external-file" && entry.value.kind !== "build-output") return [];
+      const description = entry.value.kind === "build-file" || entry.value.kind === "external-file"
+        ? { kind: "resource", mediaType: entry.value.mediaType }
+        : await repository.describeOutput(manifest.id, output);
+      if (description?.kind !== "resource" || (description.mediaType === undefined || !isMedia(description.mediaType))) return [];
+      if (media !== undefined && !description.mediaType.startsWith(`${media}/`)) return [];
+      const resolved = entry.value.kind === "build-file"
+        ? { build: manifest.id, output, value: entry.value }
+        : await repository.resolve(manifest.id, output);
+      if (resolved === undefined || (resolved.value.kind !== "build-file" && resolved.value.kind !== "external-file")) return [];
+      const file = resolved.value;
+      const source = presentedPath(root, manifest.source.path);
+      const run = manifest.run === undefined ? undefined : presentedPath(root, manifest.run.path);
+      return [{
+        id: fileReferenceIdentity(resolved.build, file),
         build: manifest.id,
         createdAt: buildIdCreatedAt(manifest.id)!,
         output,
+        nameEditable: manifest.outcome !== undefined,
+        ...(entry.displayName === undefined ? {} : { displayName: entry.displayName }),
         highlighted: manifest.highlightedOutputs?.includes(output) === true,
         ...(manifest.title === undefined ? {} : { buildTitle: manifest.title }),
         ...(manifest.note === undefined ? {} : { buildNote: manifest.note }),
-        valuePath,
-        ownerBuild: resolved.build,
+        ...(file.kind === "external-file" ? {} : { ownerBuild: file.build ?? resolved.build }),
         ownerOutput: resolved.output,
-        filePath: file.path,
+        filePath: file.kind === "external-file" ? file.uri : file.path,
         size: file.size,
         mediaType: file.mediaType,
-        source: presentedPath(root, manifest.source.path),
-        ...(manifest.run === undefined ? {} : { run: presentedPath(root, manifest.run.path) }),
-      }));
+        source,
+        ...(run === undefined ? {} : { run }),
+        origins: [{ build: manifest.id, output, source, ...(run === undefined ? {} : { run }) }],
+      }];
     })));
-  return nested.flat().sort((left, right) =>
-    Number(right.highlighted) - Number(left.highlighted)
-      || right.createdAt - left.createdAt
-      || left.output.localeCompare(right.output)
-      || left.valuePath.localeCompare(right.valuePath));
+  return mergeStudioArtifacts(nested.flat());
 }
 
-/** Build the Studio library from execution status and project-owned Build Results. */
-export async function readStudioLibrary(input: {
+/** Query only the selected library view, through Runtime and Repository interfaces. */
+export async function readStudioLibrary(input: StudioLibraryRequest & {
   readonly profile?: string;
   readonly workspaceRoot: string;
   readonly runtime?: Pick<RuntimeControl, "activity">;
   readonly results: BuildResultRepository;
-  readonly before?: string;
 }): Promise<StudioLibraryView> {
-  const page = await input.results.browse({
-    limit: 25,
-    ...(input.before === undefined ? {} : { before: input.before }),
-  });
-  const manifests = page.results.filter((manifest) =>
-    isWithin(input.workspaceRoot, manifest.run?.path ?? manifest.source.path)
-      || isWithin(input.workspaceRoot, manifest.source.path));
-  const resultsByBuild = new Map(manifests.map((manifest) => [manifest.id, manifest]));
+  const matches = (item: { readonly id: string; readonly source: { readonly path: string }; readonly run?: { readonly path: string } }) =>
+    (isWithin(input.workspaceRoot, item.run?.path ?? item.source.path) || isWithin(input.workspaceRoot, item.source.path))
+    && (input.build === undefined || item.id === input.build)
+    && (input.run === undefined || (item.run !== undefined
+      && projectPath(input.workspaceRoot, item.run.path) === projectPath(input.workspaceRoot, input.run)));
+  // Read activity before Results so a Build that finishes during this query is still represented.
   const active = input.runtime === undefined || input.before !== undefined
-    ? []
-    : (await input.runtime.activity()).builds;
-  const views = active.filter((view) => buildBelongsTo(input.workspaceRoot, view));
+    ? [] : (await input.runtime.activity()).builds;
+  const views = active.filter((view) => view.source !== undefined && matches({ ...view, source: view.source }));
+  let page = input.build === undefined
+    ? await input.results.browse({ limit: 25, ...(input.before === undefined ? {} : { before: input.before }) })
+    : { results: [await input.results.read(input.build)].filter((item): item is BuildResultManifest => item !== undefined) };
+  const manifests = page.results.filter(matches);
+  const resultsByBuild = new Map(manifests.map((manifest) => [manifest.id, manifest]));
+  await Promise.all(views.filter((view) => !resultsByBuild.has(view.id)).map(async (view) => {
+    const result = await input.results.read(view.id);
+    if (result !== undefined && matches(result)) resultsByBuild.set(view.id, result);
+  }));
+  let artifacts: readonly StudioArtifactView[] = [];
+  if (input.section === "artifacts") {
+    artifacts = await artifactsForResults(input.workspaceRoot, input.results, [...resultsByBuild.values()], input.media);
+    // Page through Result metadata until there is a useful media page. The repository still
+    // owns Build order and cursors; no media directory or secondary persistent index is needed.
+    while (artifacts.length < 25 && "next" in page && page.next !== undefined) {
+      const cursor = page.next;
+      page = await input.results.browse({ limit: 25, before: cursor });
+      if ("next" in page && page.next === cursor) throw new Error("Result pagination did not advance");
+      artifacts = mergeStudioArtifacts([...artifacts,
+        ...await artifactsForResults(input.workspaceRoot, input.results, page.results.filter(matches), input.media)]);
+    }
+  }
   return {
+    section: input.section,
     environment: resolve(input.workspaceRoot),
     ...(input.profile === undefined ? {} : { runtime: resolve(input.profile) }),
-    ...(page.next === undefined ? {} : { next: page.next }),
-    tasks: [
-      ...views.map((view) => taskView(
-        input.workspaceRoot,
-        view,
-        resultsByBuild.get(view.id),
-      )),
+    ...("next" in page && page.next !== undefined ? { next: page.next } : {}),
+    tasks: input.section !== "tasks" ? [] : [
+      ...views.map((view) => taskView(input.workspaceRoot, view, resultsByBuild.get(view.id))),
       ...manifests
-        .filter((manifest) => !views.some((view) => view.id === manifest.id))
+        .filter((manifest): manifest is FinishedBuildResultManifest => manifest.outcome !== undefined
+          && !views.some((view) => view.id === manifest.id))
         .map((manifest) => resultTaskView(input.workspaceRoot, manifest)),
     ].sort((left, right) => right.createdAt - left.createdAt || left.id.localeCompare(right.id)),
-    artifacts: await artifactsForResults(input.workspaceRoot, input.results, manifests),
+    artifacts,
   };
 }
 
@@ -245,31 +251,40 @@ export async function openStudioBuildLibrary(
     throw error;
   }
   const results = openedResults.repository;
+  let presentationWrite: Promise<unknown> = Promise.resolve();
   return {
     ...(resolvedProfile === undefined ? {} : { profile: resolvedProfile }),
     ...(runtime === undefined ? {} : { runtime }),
     ...(transientExecution === undefined ? {} : { transientExecution }),
-    async library(before) {
+    async library(request) {
       return await readStudioLibrary({
         ...(resolvedProfile === undefined ? {} : { profile: resolvedProfile }),
         workspaceRoot,
         ...(runtime === undefined ? {} : { runtime }),
         results,
-        ...(before === undefined ? {} : { before }),
+        ...request,
+      });
+    },
+    async renameArtifact(build, output, displayName) {
+      const saved = presentationWrite.then(async () => {
+        const updated = await results.updatePresentation(build, { outputDisplayNames: { [output]: displayName } });
+        return updated.outputs[output]?.displayName;
       });
+      presentationWrite = saved.catch(() => undefined);
+      return await saved;
     },
     async resolveHistoricalOutput(build, output) {
       return await resolveBuildResultValue(results, build, output);
     },
-    async openArtifact(build, output, valuePath) {
+    async openArtifact(build, output) {
       const resolved = await results.resolve(build, output);
       if (resolved === undefined) return undefined;
-      const match = filesInResolvedOutput(resolved).find((item) => item.valuePath === valuePath);
-      if (match === undefined) return undefined;
+      if ((resolved.value.kind !== "build-file" && resolved.value.kind !== "external-file") || !isMedia(resolved.value.mediaType)) return undefined;
+      const file = resolved.value;
       return {
-        mediaType: match.file.mediaType,
-        size: match.file.size,
-        open: async (range) => await results.openFile(resolved.build, match.file, range),
+        mediaType: file.mediaType,
+        size: file.size,
+        open: async (range) => await results.openFile(resolved.build, file, range),
       };
     },
     async close() {

package/packages/studio/src/companion-assembly.ts

@@ -34,6 +34,7 @@ export async function loadStudioCompanionRegistry(input: {
     {
       films: contributions.flatMap((item) => item.films),
       scripts: contributions.flatMap((item) => item.scripts),
+      parameters: contributions.flatMap((item) => item.parameters),
     },
   );
 }

package/packages/studio/src/domain.ts

@@ -33,7 +33,7 @@ export type StudioDomain = {
 
 /**
  * Assemble Studio from the same recursive package selection as the official CLI.
- * The application owns this video-domain view; packages never register Studio metadata.
+ * The application assembles the video-domain view; selected packages contribute Studio Companions through host facets.
  */
 export async function loadStudioDomain(input: {
   readonly run: string;

package/packages/studio/src/fallback-companions.ts

@@ -1,7 +1,7 @@
 import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft } from "@hypit/studio-adapter";
 import { artifactPreview, previewLayer, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
 import { compositionTypes } from "@hypit/composition";
-import { semanticTrackTypes } from "@hypit/semantic-track";
+import { timelineTypes } from "@hypit/timeline";
 
 type TerminalVisualTrack = {
   readonly presents?: readonly {
@@ -79,8 +79,8 @@ function projectTerminalAudio(context: StudioTrackCompanionContext): readonly St
 /** Cross-domain terminal protocols understood even when no Companion is installed. */
 export const fallbackStudioTrackCompanions: readonly StudioTrackCompanion[] = [
   {
-    id: "@hypit/studio#semantic-track", role: "semantic-track", output: { type: semanticTrackTypes.track },
-    family: "semantic", tone: "teal", label: "Semantic", icon: "brand",
+    id: "@hypit/studio#timeline", role: "timeline", output: { type: timelineTypes.track },
+    family: "semantic", tone: "teal", label: "Timeline", icon: "brand",
     lane: { heightPx: 45 },
   },
   {

package/packages/studio/src/feedback-server.ts

@@ -0,0 +1,51 @@
+import { watch } from "node:fs";
+import { relative } from "node:path";
+import type { Plugin } from "vite";
+import { createFeedbackStore, FeedbackConflict } from "./feedback-store.js";
+import { readFeedbackMutation } from "./feedback.js";
+import type { FeedbackDocument, FeedbackView } from "./feedback.js";
+
+/** Review storage is separate from compilation, Results and Agent delivery. */
+export function studioFeedbackPlugin(workspaceRoot: string, runPath: string): Plugin {
+  const store = createFeedbackStore(workspaceRoot);
+  const run = relative(workspaceRoot, runPath).replaceAll("\\", "/");
+  const view = (document: FeedbackDocument): FeedbackView => ({
+    file: "FEEDBACK.json", run, comments: document.comments.filter((comment) => comment.run === run),
+  });
+  return {
+    name: "hypit-studio-feedback",
+    configureServer(server) {
+      const watcher = watch(workspaceRoot, (_event, filename) => {
+        if (filename === null || filename.toString() === "FEEDBACK.json") {
+          server.ws.send({ type: "custom", event: "studio:feedback-changed", data: {} });
+        }
+      });
+      server.httpServer?.once("close", () => watcher.close());
+      server.middlewares.use((request, response, next) => {
+        if (new URL(request.url ?? "/", "http://studio.hypit.local").pathname !== "/__studio/feedback") return next();
+        response.setHeader("content-type", "application/json; charset=utf-8");
+        response.setHeader("cache-control", "no-store");
+        void (async () => {
+          try {
+            if (request.method === "GET") {
+              response.end(JSON.stringify(view(await store.read())));
+              return;
+            }
+            if (request.method !== "POST") { response.statusCode = 405; response.end(); return; }
+            const chunks: Buffer[] = [];
+            for await (const chunk of request) chunks.push(Buffer.from(chunk));
+            const mutation = readFeedbackMutation(JSON.parse(Buffer.concat(chunks).toString("utf8")));
+            const comment = mutation.type === "delete" ? mutation.before : mutation.comment;
+            if (comment.run !== run) throw new Error("The comment belongs to another Run.");
+            const result = view(await store.mutate(mutation));
+            response.end(JSON.stringify(result));
+            server.ws.send({ type: "custom", event: "studio:feedback-changed", data: {} });
+          } catch (error) {
+            response.statusCode = error instanceof FeedbackConflict ? 409 : 400;
+            response.end(JSON.stringify({ error: error instanceof Error ? error.message : String(error) }));
+          }
+        })();
+      });
+    },
+  };
+}

package/packages/studio/src/feedback-store.ts

@@ -0,0 +1,66 @@
+import { isDeepStrictEqual } from "node:util";
+import { randomUUID } from "node:crypto";
+import { readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { readFeedbackDocument } from "./feedback.js";
+import type { FeedbackDocument, FeedbackMutation } from "./feedback.js";
+
+export class FeedbackConflict extends Error {}
+
+/** The file is authoritative; every operation reads it afresh and edits one note. */
+export function createFeedbackStore(workspaceRoot: string) {
+  const path = join(workspaceRoot, "FEEDBACK.json");
+  let pending: Promise<unknown> = Promise.resolve();
+  const readText = async (): Promise<string | undefined> => {
+    try { return await readFile(path, "utf8"); }
+    catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return undefined;
+      throw error;
+    }
+  };
+  const decode = (text: string | undefined): FeedbackDocument => text === undefined
+    ? { comments: [] } : readFeedbackDocument(JSON.parse(text));
+
+  const apply = async (mutation: FeedbackMutation): Promise<FeedbackDocument> => {
+    const previous = await readText();
+    const document = decode(previous);
+    const comments = [...document.comments];
+    if (mutation.type === "add") {
+      if (comments.some((comment) => comment.id === mutation.comment.id)) throw new FeedbackConflict("This comment already exists.");
+      comments.push(mutation.comment);
+    } else {
+      const index = comments.findIndex((comment) => comment.id === mutation.before.id);
+      if (index < 0 || !isDeepStrictEqual(comments[index], mutation.before)) {
+        throw new FeedbackConflict("This comment changed outside this view. Your unsaved text is kept in the editor; reopen the comment to edit its latest version.");
+      }
+      if (mutation.type === "delete") comments.splice(index, 1);
+      else {
+        if (mutation.comment.id !== mutation.before.id || mutation.comment.run !== mutation.before.run) {
+          throw new Error("Editing a comment preserves its id and Run.");
+        }
+        comments[index] = mutation.comment;
+      }
+    }
+    const next = { ...document, comments };
+    const temporary = join(workspaceRoot, `.FEEDBACK.${randomUUID()}.tmp`);
+    try {
+      await writeFile(temporary, `${JSON.stringify(next, null, 2)}\n`, { encoding: "utf8", flag: "wx" });
+      if (await readText() !== previous) throw new FeedbackConflict("FEEDBACK.json changed while saving. Your draft is kept; please try again.");
+      await rename(temporary, path);
+    } finally {
+      await unlink(temporary).catch((error: NodeJS.ErrnoException) => { if (error.code !== "ENOENT") throw error; });
+    }
+    return next;
+  };
+
+  return {
+    path,
+    read: async (): Promise<FeedbackDocument> => decode(await readText()),
+    mutate(mutation: FeedbackMutation): Promise<FeedbackDocument> {
+      // Serialize browser submissions, without keeping a second copy of the document.
+      const result = pending.then(() => apply(mutation));
+      pending = result.catch(() => undefined);
+      return result;
+    },
+  };
+}

package/packages/studio/src/feedback.ts

@@ -0,0 +1,60 @@
+/** Project-owned review notes. Times are seconds in the reviewed Run. */
+export type FeedbackComment = {
+  readonly id: string;
+  readonly run: string;
+  readonly at: number;
+  readonly text: string;
+  readonly resolved?: boolean;
+};
+
+export type FeedbackDocument = { readonly comments: readonly FeedbackComment[] };
+export type FeedbackView = FeedbackDocument & { readonly file: string; readonly run: string };
+export type FeedbackMutation =
+  | { readonly type: "add"; readonly comment: FeedbackComment }
+  | { readonly type: "replace"; readonly before: FeedbackComment; readonly comment: FeedbackComment }
+  | { readonly type: "delete"; readonly before: FeedbackComment };
+
+function record(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function nonempty(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0;
+}
+
+function time(value: unknown): value is number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0;
+}
+
+export function readFeedbackComment(value: unknown): FeedbackComment {
+  if (!record(value) || !nonempty(value.id) || !nonempty(value.run) || !nonempty(value.text) || !time(value.at)) {
+    throw new Error("Each comment needs an id, run, non-empty text and a non-negative time in seconds.");
+  }
+  if (value.resolved !== undefined && typeof value.resolved !== "boolean") throw new Error("Comment resolved must be true or false.");
+  // Preserve any project-added fields when Studio edits this document.
+  return value as FeedbackComment;
+}
+
+export function readFeedbackDocument(value: unknown): FeedbackDocument {
+  if (!record(value) || !Array.isArray(value.comments)) throw new Error("FEEDBACK.json needs a comments array.");
+  const ids = new Set<string>();
+  for (const entry of value.comments) {
+    const comment = readFeedbackComment(entry);
+    if (ids.has(comment.id)) throw new Error(`Duplicate comment id: ${comment.id}`);
+    ids.add(comment.id);
+  }
+  return value as FeedbackDocument;
+}
+
+export function readFeedbackMutation(value: unknown): FeedbackMutation {
+  if (!record(value)) throw new Error("Expected a comment operation.");
+  if (value.type === "add") return { type: "add", comment: readFeedbackComment(value.comment) };
+  if (value.type === "delete") return { type: "delete", before: readFeedbackComment(value.before) };
+  if (value.type === "replace") return { type: "replace", before: readFeedbackComment(value.before), comment: readFeedbackComment(value.comment) };
+  throw new Error("Unknown comment operation.");
+}
+
+export function feedbackClock(seconds: number): string {
+  const ticks = Math.round(seconds * 100);
+  return `${String(Math.floor(ticks / 6000)).padStart(2, "0")}:${String(Math.floor(ticks / 100) % 60).padStart(2, "0")}.${String(ticks % 100).padStart(2, "0")}`;
+}

package/packages/studio/src/library-media.ts

@@ -0,0 +1,19 @@
+import type { StudioArtifactView } from "./shared.js";
+
+/** Merge known references, without reading or comparing media bytes. */
+export function mergeStudioArtifacts(items: readonly StudioArtifactView[]): StudioArtifactView[] {
+  const files = new Map<string, StudioArtifactView>();
+  for (const item of items) {
+    const prior = files.get(item.id);
+    if (prior === undefined) {
+      files.set(item.id, item);
+      continue;
+    }
+    const latest = item.createdAt > prior.createdAt ? item : prior;
+    const origins = new Map([...prior.origins, ...item.origins].map((origin) =>
+      [JSON.stringify([origin.build, origin.output]), origin]));
+    files.set(item.id, { ...latest, highlighted: prior.highlighted || item.highlighted, origins: [...origins.values()] });
+  }
+  return [...files.values()].sort((left, right) => Number(right.highlighted) - Number(left.highlighted)
+    || right.createdAt - left.createdAt || left.output.localeCompare(right.output));
+}