@hypit/hypit 0.1.2 → 0.1.4

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/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));
+}

package/packages/studio/src/parameter-values.ts

@@ -1,5 +1,44 @@
 import type { CanonicalValue, ValueSchema } from "@hypit/protocol";
 import { formatSvsValue } from "@hypit/svs";
+import type { StudioInspectorField, StudioParameterOption, StudioNumberPresentation } from "@hypit/studio-adapter";
+
+export const parameterOption = (option: StudioParameterOption): Exclude<StudioParameterOption, string> =>
+  typeof option === "string" ? { value: option, label: option } : option;
+
+// Keep binary floating-point residue out of decimal controls (0.55 × 100 is 55).
+const scaledDecimal = (value: number, scale: number): number =>
+  scale === 1 ? value : Number((value * scale).toPrecision(15));
+
+export function parameterNumber(value: CanonicalValue, presentation: StudioNumberPresentation = {}): { value: number; suffix: string } {
+  let held = value;
+  let suffix = "";
+  if (presentation.suffixes !== undefined) {
+    if (typeof held !== "string") throw new Error("A suffixed number must be authored as text.");
+    const text = held.trim();
+    const found = [...presentation.suffixes].sort((a, b) => b.length - a.length).find(item => text.endsWith(item));
+    if (found === undefined) throw new Error("The authored unit is not supported by this field.");
+    suffix = found;
+    held = text.slice(0, text.length - suffix.length).trim();
+  }
+  if (typeof held !== "number" && (typeof held !== "string" || !/^[+-]?(?:\d+(?:\.\d*)?|\.\d+)(?:e[+-]?\d+)?$/iu.test(held.trim()))) {
+    throw new Error("This field needs a numeric value.");
+  }
+  const number = scaledDecimal(Number(held), presentation.scale ?? 1);
+  if (!Number.isFinite(number)) throw new Error("This field needs a finite number.");
+  return { value: number, suffix };
+}
+
+/** Decode the displayed edit before validating and serializing the authored value. */
+export function parameterAuthorValue(field: StudioInspectorField, displayed: CanonicalValue): CanonicalValue {
+  if (field.control !== "number") return displayed;
+  if (typeof displayed !== "number" || !Number.isFinite(displayed)) throw new Error(`${field.label} expects a finite number.`);
+  const presentation = field.number ?? {};
+  if (presentation.minimum !== undefined && displayed < presentation.minimum) throw new Error(`${field.label} must be at least ${presentation.minimum}.`);
+  if (presentation.maximum !== undefined && displayed > presentation.maximum) throw new Error(`${field.label} must be at most ${presentation.maximum}.`);
+  const value = scaledDecimal(displayed, 1 / (presentation.scale ?? 1));
+  if (!Number.isFinite(value)) throw new Error(`${field.label} cannot be represented.`);
+  return presentation.suffixes === undefined ? value : `${value}${parameterNumber(field.value, presentation).suffix}`;
+}
 
 function fail(path: string, expectation: string): never {
   throw new Error(`${path} ${expectation}.`);
@@ -76,6 +115,7 @@ export function validateParameterValue(value: CanonicalValue, schema: ValueSchem
 
 export function serializeParameterValue(value: CanonicalValue, language: "svml" | "svs" | "svrun"): string {
   if (language === "svs") return formatSvsValue(value);
-  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return String(value);
+  if (typeof value === "string") return value.replaceAll("&", "&amp;").replaceAll('"', "&quot;").replaceAll("'", "&apos;").replaceAll("<", "&lt;").replaceAll(">", "&gt;");
+  if (typeof value === "number" || typeof value === "boolean") return String(value);
   throw new Error(`${language.toUpperCase()} parameter bindings currently accept scalar values only.`);
 }

package/packages/studio/src/parameters.ts

@@ -238,8 +238,16 @@ function referencedParameters(input: {
   const file = sourceFor(input.root, target.sourcePath, input.files);
   if (file === undefined) return [];
   return input.declarations.flatMap((declaration) => {
+    const nestedPath = target.references[declaration.name];
+    const nested = nestedPath === undefined || declaration.referenced === undefined ? [] : referencedParameters({
+      root: input.root, files: input.files, draft: input.draft, placements: input.placements,
+      referenceName: `${input.referenceName}.${declaration.name}`,
+      referencePath: nestedPath,
+      ...(target.resolvedReferences[declaration.name] === undefined ? {} : { referenceRef: target.resolvedReferences[declaration.name] }),
+      declarations: declaration.referenced,
+    });
     const range = target.attributeValueRanges[declaration.name];
-    if (range === undefined) return [];
+    if (range === undefined) return nested;
     const preimage = file.text.slice(range.start, range.end);
     const reference = target.references[declaration.name];
     const value = reference === undefined ? (target.attributes[declaration.name] ?? preimage) : reference;
@@ -263,7 +271,7 @@ function referencedParameters(input: {
       ...(!writable
         ? { disabledReason: reference === undefined ? "该几何值由组件声明为只读。" : "引用由作者在 SVML 中绑定，面板不替换引用关系。" }
         : {}),
-    } satisfies StudioSourceBinding];
+    } satisfies StudioSourceBinding, ...nested];
   });
 }
 
@@ -484,7 +492,7 @@ export function resolveTimelineEditHandles(
     moveEffect?: "translate-window" | "move-start",
   ): StudioEditHandle => {
     const unavailable = affected.find(({ endpoint }) => endpoint.authority.kind === "fixed");
-    if (unavailable !== undefined) return disabled(gesture, "该端点由 Program 或 Segment 结构固定，不能从组件时间线反写。");
+    if (unavailable !== undefined) return disabled(gesture, "该时间表达未开放时间轴回写。");
     const projected: ({ readonly missing: string } | StudioEditSource)[] = [];
     for (const { endpoint, role } of affected) {
       if (endpoint.authority.kind !== "parameter") continue;
@@ -527,24 +535,15 @@ export function resolveTimelineEditHandles(
   }
   const start = { endpoint: projection.start, role: "start" as const };
   const end = { endpoint: projection.end, role: "end" as const };
-  const move = projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start"
-    ? [start]
-    : projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end"
-      ? [end]
-      : [start, end];
-  const trimStart = projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end"
-    ? [start]
-    : projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start"
-      ? [start, end]
-      : [start];
-  const trimEnd = projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start"
-    ? [end]
-    : projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end"
-      ? [start, end]
-      : [end];
+  if (projection.end.authority.kind === "parameter" && projection.end.authority.relation === "after-start") {
+    return [handle("move", [start], "translate-window"), handle("trim-end", [end])];
+  }
+  if (projection.start.authority.kind === "parameter" && projection.start.authority.relation === "before-end") {
+    return [handle("move", [end], "translate-window"), handle("trim-start", [start])];
+  }
   return [
-    handle("move", move, "translate-window"),
-    handle("trim-start", trimStart),
-    handle("trim-end", trimEnd),
+    handle("move", [start, end], "translate-window"),
+    handle("trim-start", [start]),
+    handle("trim-end", [end]),
   ];
 }

package/packages/studio/src/server.ts

@@ -15,12 +15,13 @@ import type { ServedFile } from "./compile.js";
 import type { StudioDomain } from "./domain.js";
 import type { StudioCompanionRegistry } from "./studio-registry.js";
 import { loadStudioRun } from "./run.js";
-import { serializeParameterValue, validateParameterValue } from "./parameter-values.js";
+import { parameterAuthorValue, parameterOption, serializeParameterValue, validateParameterValue } from "./parameter-values.js";
 import { readStudioSession } from "./session.js";
-import type { Range, StudioFailure, StudioLibraryView, StudioMutation, StudioSnapshot } from "./shared.js";
+import type { Range, StudioFailure, StudioLibraryRequest, StudioLibraryView, StudioMutation, StudioSnapshot } from "./shared.js";
 import { createStudioStoryboard } from "./storyboard.js";
 import type { StudioStoryboard } from "./storyboard.js";
 import { findSurfacePreview } from "./surface-preview.js";
+import { formatTemporalPointEdit, semanticGestureSpan } from "./temporal-edit.js";
 import { replaceSourceFiles } from "./source-transaction.js";
 
 export type StudioPluginOptions = {
@@ -93,8 +94,9 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
   const watchedFiles = new Set<string>();
   const storyboards = new Map<string, Promise<StudioStoryboard>>();
 
-  const readLibrary = async (before?: string): Promise<StudioLibraryView> => {
-    return await options.buildLibrary?.library(before) ?? {
+  const readLibrary = async (request: StudioLibraryRequest): Promise<StudioLibraryView> => {
+    return await options.buildLibrary?.library(request) ?? {
+      section: request.section,
       environment: options.workspaceRoot,
       tasks: [],
       artifacts: [],
@@ -271,7 +273,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
       throw new Error("A timeline target must use valid whole frames.");
     }
     if (temporal.kind === "window") {
-      if (mutation.gesture === "move"
+      if (mutation.gesture === "move" && handle.semantic?.kind !== "selection"
         && endFrameExclusive - startFrame !== clip.endFrameExclusive - clip.startFrame) {
         throw new Error("Move must preserve the Window duration.");
       }
@@ -287,6 +289,7 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
 
     const patches: Patch[] = [];
     const semanticTarget = mutation.target.semantic;
+    if (handle.semantic !== undefined && semanticTarget === undefined) throw new Error("A semantic edit requires explicit target anchors.");
     if (semanticTarget !== undefined) {
       if (handle.semantic?.kind !== semanticTarget.kind) {
         throw new Error(`Entity ${mutation.entityId} is not bound to a writable ${semanticTarget.kind}.`);
@@ -298,15 +301,9 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
         || script.narrativeId !== current.semantic.narrativeId) {
         throw new Error("The timeline entity and writable Script do not belong to the selected Narrative.");
       }
-      if (semanticTarget.kind === "selection") {
-        const startIndex = current.semantic.anchors.findIndex((anchor) => anchor.id === semanticTarget.startAnchorId);
-        const endIndex = current.semantic.anchors.findIndex((anchor) => anchor.id === semanticTarget.endAnchorId);
-        if (startIndex < 0 || endIndex < 0 || startIndex >= endIndex
-          || current.semantic.anchors[startIndex]!.frame >= current.semantic.anchors[endIndex]!.frame) {
-          throw new Error("A Selection must span two ordered semantic Anchors with positive time.");
-        }
-      } else if (!current.semantic.anchors.some((anchor) => anchor.id === semanticTarget.anchorId)) {
-        throw new Error(`Moment Anchor ${semanticTarget.anchorId} does not exist in the current semantic Candidate.`);
+      const projected = semanticGestureSpan(current.semantic.anchors, handle, semanticTarget);
+      if (projected === undefined || projected.startFrame !== startFrame || projected.endFrameExclusive !== endFrameExclusive) {
+        throw new Error("The semantic edit does not produce the requested timeline projection.");
       }
       const absolute = resolve(options.workspaceRoot, script.sourcePath);
       const source = await readFile(absolute, "utf8");
@@ -366,20 +363,15 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
       }
       return snapshot?.semantic?.moments.find((candidate) => candidate.id === id)?.frame;
     };
-    const projectedPointValue = (endpoint: StudioTemporalInstantProjection, desired: number): string => {
-      if (endpoint.reference === "absolute") return frame(desired);
-      const base = projectionBaseFrame(endpoint);
-      if (base === undefined) throw new Error(`The ${endpoint.reference} projection base is unavailable.`);
-      const offset = desired - base;
-      return offset === 0 ? endpoint.reference : `${endpoint.reference}${offset > 0 ? "+" : ""}${offset}f`;
-    };
+    const projectedPointValue = (endpoint: StudioTemporalInstantProjection, desired: number): string =>
+      formatTemporalPointEdit(endpoint.reference, desired, projectionBaseFrame(endpoint));
     const writeEndpoint = (
       endpoint: StudioTemporalInstantProjection,
       desired: number,
       role: "start" | "end",
     ): void => {
       if (desired === endpoint.frame) return;
-      if (endpoint.authority.kind === "fixed") throw new Error(`The ${role} endpoint is structurally fixed.`);
+      if (endpoint.authority.kind === "fixed") throw new Error(`The ${role} endpoint has no timeline write target.`);
       if (endpoint.authority.kind === "semantic") {
         if (semanticFrame(endpoint) !== desired) throw new Error(`The ${role} endpoint does not match its semantic Anchor.`);
         return;
@@ -413,20 +405,22 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
     if (parameter === undefined) {
       throw new Error(`Entity ${mutation.entityId} has no writable parameter ${mutation.parameterId}.`);
     }
+    const authorValue = parameterAuthorValue(parameter, mutation.value);
     if (parameter.schema !== undefined) {
-      validateParameterValue(mutation.value, parameter.schema, parameter.label);
+      validateParameterValue(authorValue, parameter.schema, parameter.label);
     } else if (parameter.control === "boolean" && typeof mutation.value !== "boolean") {
       throw new Error(`${parameter.label} expects true or false.`);
     } else if (parameter.control === "number" && (typeof mutation.value !== "number" || !Number.isFinite(mutation.value))) {
       throw new Error(`${parameter.label} expects a number.`);
-    } else if ((parameter.control === "text" || parameter.control === "color" || parameter.control === "select")
+    } else if ((parameter.control === "text" || parameter.control === "color")
       && typeof mutation.value !== "string") {
       throw new Error(`${parameter.label} expects text.`);
     }
-    if (parameter.options !== undefined && (typeof mutation.value !== "string" || !parameter.options.includes(mutation.value))) {
+    if (parameter.options !== undefined && !parameter.options.some(option => parameterOption(option).value === authorValue)) {
       throw new Error(`${parameter.label} does not accept ${mutation.value}.`);
     }
-    const encoded = serializeParameterValue(mutation.value, parameter.language);
+    if (parameter.control === "color") validateParameterValue(authorValue, { kind: "string", format: "color" }, parameter.label);
+    const encoded = serializeParameterValue(authorValue, parameter.language);
     const replacement = `${parameter.source.prefix ?? ""}${encoded}${parameter.source.suffix ?? ""}`;
     return replacement === parameter.source.preimage ? [] : [{
       ...parameter.source,
@@ -525,6 +519,28 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
           })();
           return;
         }
+        if (request.method === "PUT" && url.pathname === "/__studio/artifact-name") {
+          void (async () => {
+            try {
+              const chunks: Buffer[] = [];
+              for await (const chunk of request) chunks.push(Buffer.from(chunk));
+              const body = JSON.parse(Buffer.concat(chunks).toString("utf8")) as {
+                build?: unknown; output?: unknown; displayName?: unknown;
+              };
+              if (typeof body.build !== "string" || typeof body.output !== "string"
+                || (typeof body.displayName !== "string" && body.displayName !== null)) {
+                json(response, 400, { error: "Expected Build, Output and displayName" });
+                return;
+              }
+              if (options.buildLibrary === undefined) throw new Error("Result Repository is unavailable");
+              const displayName = await options.buildLibrary.renameArtifact(body.build, body.output, body.displayName);
+              json(response, 200, { displayName: displayName ?? null });
+            } catch (error) {
+              json(response, 422, { error: error instanceof Error ? error.message : String(error) });
+            }
+          })();
+          return;
+        }
         if (request.method === "POST" && url.pathname === "/__studio/mutation") {
           void (async () => {
             try {
@@ -577,8 +593,21 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
           return;
         }
         if (url.pathname === "/__studio/library") {
+          const section = url.searchParams.get("section");
+          if (section !== "tasks" && section !== "artifacts") {
+            json(response, 400, { error: "Choose tasks or artifacts with the section parameter" });
+            return;
+          }
+          const media = url.searchParams.get("media") ?? undefined;
+          if (media !== undefined && media !== "image" && media !== "video" && media !== "audio") {
+            json(response, 400, { error: "Choose image, video or audio with the media parameter" });
+            return;
+          }
           const before = url.searchParams.get("before") ?? undefined;
-          void readLibrary(before).then(
+          const run = url.searchParams.get("run") ?? undefined;
+          const build = url.searchParams.get("build") ?? undefined;
+          void readLibrary({ section, ...(media === undefined ? {} : { media }), ...(before === undefined ? {} : { before }),
+            ...(run === undefined ? {} : { run }), ...(build === undefined ? {} : { build }) }).then(
             (view) => json(response, 200, view),
             (error) => json(response, 500, { error: error instanceof Error ? error.message : String(error) }),
           );
@@ -662,13 +691,12 @@ export function studioPlugin(options: StudioPluginOptions): Plugin {
           void (async () => {
             const build = url.searchParams.get("build");
             const output = url.searchParams.get("output");
-            const valuePath = url.searchParams.get("path");
-            if (build === null || output === null || valuePath === null || options.buildLibrary === undefined) {
+            if (build === null || output === null || options.buildLibrary === undefined) {
               response.statusCode = 404;
               response.end();
               return;
             }
-            const artifact = await options.buildLibrary.openArtifact(build, output, valuePath);
+            const artifact = await options.buildLibrary.openArtifact(build, output);
             if (artifact === undefined) {
               response.statusCode = 404;
               response.end();