@hypit/hypit 0.1.3 → 0.1.4

package/packages/studio/INSPECTOR.md

@@ -0,0 +1,104 @@
+# Companion-owned Inspector fields
+
+The Inspector asks three questions. **Where** describes spatial placement and organization;
+**When** describes scheduling, playback and changes over time; **How** describes appearance,
+content and sound. These are navigation domains, not restrictions on component behavior.
+
+| Domain | Useful pages and sections |
+| --- | --- |
+| Where | Position, size, anchor, fitting/cropping, padding, clipping, stacking, layout |
+| When | Placement in time, playback/cycling, source trim, entrance, sustained motion, exit, transitions, fades |
+| How | Text/content, typography, fill/stroke, image adjustments, shadows, effect character, audio levels |
+
+Each Companion supplies page and section IDs and labels in declaration order. These examples are
+a shared vocabulary, not a registry of permitted pages. A new component can name a useful grouping
+without a Studio change. Put a field where its authoring decision belongs: motion duration is When,
+its color is How, and the object's frame is Where. One field has one owner and one location.
+
+## Controls describe the editing task
+
+`bindings` exposes actual author endpoints; `inspector` chooses which to show. A resolved field is
+shown only when its binding is writable. The finite controls are independent of the three domains:
+
+| Control | Use |
+| --- | --- |
+| `text` | Text, identifiers, or a meaningful expression. `multiline: true` provides a textarea. |
+| `number` | A scalar with optional limits, stepping, display scaling, or an authored suffix. |
+| `boolean` | A two-state switch. |
+| `select` | A finite choice, including presets, font families or numeric weights. |
+| `color` | Hex text and a native color picker; optional `swatches` offers package-chosen colors. |
+| `list` | An ordered value described by an array schema, such as a palette or repeated settings. |
+| `record` | Named values described by an object schema, such as one shadow's parameters. |
+
+Lists and records retain Apply/Reset drafts. Their schema owns value shape. There is no separate
+palette database, font control protocol, generic CSS editor, or component-supplied DOM renderer.
+Use text for an expression whose parts cannot meaningfully be edited as one number.
+
+## Separate author values from display values
+
+The DTO retains the authored `value`. A numeric presentation describes the small, reversible
+conversion into the editor. The server applies the inverse, validates the **authored** value against
+its public schema, and uses the author language's serializer. Source ranges and existing transactions
+still own the write. Failed validation or recompilation does not publish a partial edit.
+
+```ts
+// Authored as "78%" or "240px": edit only the magnitude, keep the existing unit.
+{ binding: "frame.width", label: "Width", domain: "where",
+  section: { id: "size", label: "Size" }, control: "number",
+  number: { suffixes: ["%", "px"], step: 1 } }
+
+// Authored as 0.78: display 78 %, write 0.42 when the author enters 42.
+{ binding: "appearance.opacity", label: "Opacity", domain: "how",
+  section: { id: "image", label: "Image" }, control: "number", unit: "%",
+  number: { scale: 100, minimum: 0, maximum: 100, step: 1 } }
+```
+
+`unit` is a label, not an instruction to append text. `suffixes` explicitly declares a string-valued
+number and retains whichever admitted suffix the current source uses. It does not convert `%` into
+pixels or seconds into frames. `scale` is positive; displayed value = authored magnitude × scale.
+Limits and step in `number` refer to displayed values. A number schema's limits and integer setting
+also inform the input when no presentation override is provided. Empty input is not silently zero.
+
+SVML strings escape attribute delimiters and entity characters. SVS values use `formatSvsValue`.
+Neither the UI nor a Companion writes source text through an arbitrary callback. Timeline temporal
+gestures are separate from Inspector field conversion; see the temporal author forms for their
+semantic-anchor and local-offset editing behavior.
+
+## Choices retain their actual value
+
+Existing string options are shorthand for identical value and label. Rich options can supply a
+different label, description and one small visual hint:
+
+```ts
+options: [
+  { value: "brand-serif", label: "Brand Serif", description: "Project headline face",
+    preview: { kind: "font", family: "Project Serif", sample: "Aa 字幕" } },
+  { value: "brand-sans", label: "Brand Sans" },
+]
+```
+
+A color hint uses `{ kind: "color", color: "#FF584A" }`. Values may be strings, numbers or booleans;
+the selected value, not its display label, is validated and written. Preview hints contain data only.
+Options remain named keyboard-operable choices. Font hints use a family available to the Studio
+document; declaring a hint does not install or load a font or change the composition's font bytes.
+
+The optional `@hypit/fonts-open/studio` helper owns its catalog labels and descriptions. Caption,
+Typography and Ranking Companions use it to reach a Style's referenced font and edit its `family`
+attribute. It appears for an actual writable family attribute; a `media:Font` file has no such
+attribute. The family still has to supply the authored weight and style. A local font keeps its exact
+file binding. Changing a shared font changes every consumer; this is visible Source reuse.
+
+Nested `referenced` declarations follow explicit author references, such as Style → Font → family.
+They neither scan for candidates nor replace whole-value references with strings. Project components
+can declare their own option values and binding paths through the same ABI.
+
+## Implementation owners
+
+- `studio-adapter` owns the data-only declarations and snapshot types.
+- Component Companions own grouping, choices, units and references to writable author facts.
+- Studio resolves endpoints, renders controls, converts display values and commits source edits.
+- SVML/SVS and the component's ordinary compilation remain the authority for valid authored work.
+
+The UI follows native numeric input behavior and named listbox options; reference material:
+[MDN numeric inputs](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input/number),
+[WAI listbox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/listbox/).

package/packages/studio/README.md

@@ -14,11 +14,55 @@ When `--runtime` is omitted, Studio reads the resolved project's `.hypit/runtime
 selection made by `hypit runtime use`. It does not search parent projects for a
 Profile. `--workspace` explicitly selects the project boundary; `--package-root`
 overrides the author package resolution root when those locations intentionally differ.
+Startup prints the project, Run, Profile and whether the Profile came from the command argument or
+the project's selection file. Relative command-line paths start at the invoking directory;
+`--workspace` selects the project without rebasing `--run` or `--runtime`.
 The upper-left library is intentionally not a filesystem browser:
 
 - Source is the exact Run + Author closure and writes back only the selected file;
-- Tasks combine finished project Results with read-only active `BuildView` and Operation information;
-- Artifacts are public files exposed by project Build Results.
+- Tasks show one card per Build, with All, In progress and Finished filters. Active progress comes from
+  the selected Runtime's read-only control interface; completed, failed and cancelled Builds come
+  from the project's Result Repository. Saving a Result and an issue requiring attention remain
+  visible, with the source Run and available progress or failure reason.
+- Artifacts show top-level file Outputs whose declared MIME type is image, video or audio,
+  including files already published by ongoing Builds. Composite Outputs retain their structure:
+  the library does not extract their embedded resources. Forwarded file Outputs resolve to their
+  owner; references to the same owner file share one card and retain their origins. Highlighted
+  Outputs sort first, without excluding other media.
+
+Source, Tasks and Artifacts use the shared `ui/sidebar-panel.ts` layout and navigation buttons. Each view
+owns its toolbar content, data and actions; the shared shell owns geometry and navigation styling.
+
+Views load on entry; returning to Tasks preserves its loaded list and selection. Explicit Refresh reads the latest state. There is no library polling.
+Refresh replaces the current snapshot; scrolling to the end loads more finished Results. Failed
+refreshes preserve the last view and show the error. Artifacts show project media through an icon sidebar: All media, Videos, Images and Audio.
+The header names the category and offers Refresh. Selecting a Task adds its name beside the category in the existing header, establishing a session-local task context without shifting the list; its arrow opens that Build's media. The context remains across tab changes. Click its name to return to the selected Task, or clear it to browse project media. Task selection does not write Source, Result or Runtime state. Selected tasks expand the complete error text with a copy action. Source details are available on each media card. A media category is sent to the server, which
+walks Result metadata pages until it collects a useful batch of matching files or reaches the end.
+This keeps Build storage unchanged while avoiding empty category pages. The browser appends
+older matches on scroll; Refresh reads the latest results for the current category.
+
+Media cards use fixed-size square cells, contain the file at its own aspect ratio, and show up to two
+wrapped name lines below. Selection colors the thumbnail area and name separately, without an
+outer card border. Resizing the
+sidebar distributes spare width between columns, then adds a column when another fixed-size
+card fits. Card size stays unchanged. Video thumbnails decode a frame in the browser; audio waveforms are also
+browser presentation, not additional Result files. Thumbnails load as their cells enter view.
+The CLI carries the author's component name from compilation provenance into the Result's
+optional Output `displayName`. The public Output identifier stays intact for references;
+Outputs without a display name show that identifier unchanged. Double-click a name or press F2
+to edit it in full; Enter or blur saves, Escape cancels. Failed saves retain the text and show the
+reason. A completed, failed or cancelled Build's name is written through Result Repository
+`updatePresentation` to that exact Output's `displayName`. Ongoing Builds become editable when
+they finish, following the existing Result presentation-edit boundary. Renaming never changes
+Output identity, referenced media files or other Builds' names for the same file.
+
+The composition has a frame-snapped progress slider and current/total time.
+Clicking a card opens the file in the central preview and pauses the composition. Images need
+no transport; video and audio share the play/mute controls and a seconds-based scrubber above
+the playback bar. The previous/next buttons skip five seconds for media, and step one frame
+for the composition. Back to composition restores the existing composition playhead. Selecting
+or seeking in the composition timeline also returns to it. Opening media changes no Source,
+Run, or Candidate selection.
 
 No project manifest, Studio database, output-directory scan or inferred campaign
 folder structure is involved. With no selected Runtime, finished Result tasks and
@@ -32,7 +76,10 @@ The selected targets must reach one Film and its resolved time source. Studio re
 distinct Films in one view; use separate Runs/sessions for those. A SemanticTrack supplies the
 Script lane and performance timing, including wordless Segments with media spans. A declared
 ProgramSpace supplies authored animation time without a Script lane. Both show their component
-tracks and use the same rendering and parameter-editing machinery.
+tracks and use the same rendering and parameter-editing machinery. When the snapshot contains
+a semantic timeline, its lane and label stay pinned directly below the time ruler while
+component tracks scroll. Its presence follows the resolved semantic timeline, including
+wordless content, rather than a component name or the presence of spoken words.
 
 Open the URL printed by Vite. Studio requests port 5179 by default, accepts `--port`,
 and Vite can choose another available port when it is occupied. Reuse that process
@@ -52,11 +99,25 @@ Timeline gestures use explicit temporal authority. Moving a shared Selection or
 Moment edits Script and moves its consumers after recompilation. A parameter-based
 handle edits its exact authored parameter. Fixed or derived values with no supported
 inverse remain read-only. Seeing an entity does not promise every drag gesture.
+
+A direct `during={selection}` move advances both endpoints by the same number of semantic
+stops (distinct frame positions), so its duration may change. `at/for` moves its event and
+offers a trailing duration trim; `until/for` offers the corresponding leading trim.
+An Instant reference expression edits only its offset; a bare reference has an implicit zero offset.
+`start/end` trims edit the corresponding expression; moving the window shifts both by the same
+frame delta. Edited clock values and offsets are written in frames at the current ProgramSpace rate.
+The semantic marker Inspector exposes exact anchor identities and, where a
+declared handle supports it, offers choices among coincident anchors.
+See [temporal author forms](../temporal-markup/EDITING.md) for the complete behavior.
+
 Tasks and Artifacts are inspection surfaces; selecting an Artifact does not write a
 Run Candidate. Use `build-record`/`satisfy` in the Run for explicit Output reuse.
 
 ## Component presentation
 
+[Inspector fields](INSPECTOR.md) describes Where/When/How grouping, numeric unit conversion,
+rich choices, fonts, color suggestions and exact Source writeback.
+
 Studio is an application boundary. Core and domain computation do not import it or
 register UI metadata. The installed Distribution explicitly selects one independent
 Studio Companion per supported official domain. Packages actually selected by the
@@ -82,7 +143,7 @@ source binding is never shown merely because Studio can reach it. Material layer
 Resource id or Surface identity, never a Studio HTTP URL. Studio always owns
 time formatting and transport resolution, so chrome and material cannot hide a
 title or its time.
-Studio owns session-wide behavior and chrome: Companion assembly, collision rules,
+Studio owns session-wide behavior and chrome: Companion assembly, single-row overlap display,
 fallback defaults, selection treatment, playback, zoom,
 scrolling, the finite Inspector control set and source mutation transport. A
 companion cannot ship arbitrary DOM or CSS into the application.

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.`);
 }