@hypit/hypit 0.0.1 → 0.1.0

package/packages/studio/README.md

@@ -0,0 +1,125 @@
+# Hypit Studio
+
+The single official Web Studio for SVML. It opens an explicit Run Source,
+traces its Film or Render target back to the semantic and visual projections
+Studio can edit, runs deterministic Producers and explicitly permitted transient Needs, and composites the
+resulting Tracks with HyperFrames.
+
+```bash
+cd /path/to/external-video-project
+hypit studio --run build.svrun
+```
+
+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.
+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.
+
+No project manifest, Studio database, output-directory scan or inferred campaign
+folder structure is involved. With no selected Runtime, finished Result tasks and
+Artifacts remain available. Preview and Source display work when the selected display
+closure can resolve without Endpoint execution; active status and Provider-backed
+transient processing require the selected Runtime.
+
+## Opening and editing a session
+
+The selected targets must reach one Film and its resolved time source. Studio rejects several
+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.
+
+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
+for edits to the same Run. The Run and loaded Author/Recipe files are watched and
+recompiled together. Domain packages, Companion registry, Runtime and Result library
+are opened at startup; restart this Studio process after changing those selections,
+package code or imports that introduce new packages. Browser refresh does not reload
+server-side package modules.
+
+The Source pane can edit the selected `.svml`, `.svs` or `.svrun` file. The Inspector
+shows project facts when no entity is selected and only declared writable fields for
+the selected entity. A reference can resolve to a shared Frame or Recipe, so one edit
+may affect several consumers. Structured fields use Apply/Reset for their local draft.
+Check save status; source conflicts reject stale edits rather than overwrite newer files.
+
+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.
+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
+
+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
+current Source closure may contribute their own Companion facet. The application
+assembles both sets into one immutable registry for that session; there is no second
+Studio profile, package scan or replacement map.
+
+Project packages live at `<project>/packages/<package-basename>/`. Neither the
+project nor its packages are added to the Hypit Distribution or contributor workspace.
+The Host resolves selected project packages from the project first and official
+`@hypit/*` imports from the read-only tool Distribution. The `@hypit/*`
+namespace is Distribution-owned and cannot be shadowed by a project install.
+External Companions compile against `@hypit/hypit/studio-adapter` and the other public `@hypit/hypit/*`
+subpaths, with `@hypit/hypit` as a development dependency. The active Distribution supplies those APIs
+at runtime. Ship the Companion's compiled JavaScript with its component package.
+
+The companion owns what its Track means: matching, required same-Surface values,
+entities, lane range, finite chrome, title and ordered text/material layers,
+source bindings, Inspector fields and executed temporal lineage. Inspector fields
+select real writable bindings and organize them under the Studio-owned
+`Where / How / When` domains, optional companion-owned pages and sections. A
+source binding is never shown merely because Studio can reach it. Material layers carry a
+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,
+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.
+
+The finite control set includes scalar controls plus generic `list` and flat
+`record` composition. Structured values are validated against the domain-owned
+canonical schema, edited as a local draft, and written atomically through the
+same revisioned `parameter.adjust` operation. Studio contains no Ranking,
+Caption or Media list codec.
+
+Inspector controls are Studio behavior, not browser defaults supplied by a
+companion. Focused controls suspend transport shortcuts; numeric values use
+non-spinning text entry so wheel scrolling cannot mutate Source; selects use
+the Studio menu and keyboard navigation. Values still commit only on an
+explicit change through the normal revisioned mutation path.
+
+Temporal lineage comes from the exact executed graph selected by the Run. Studio indexes the
+`TemporalInstant` and `TemporalWindow` records in each Track's dependency closure, including each
+endpoint's author authority and direct consumer edge. Common timeline inverses come from that
+authority rather than Companion declarations. Track Companions never infer semantic sources from SVML
+attribute names, runtime id prefixes or coincident frame spans.
+
+Opening Studio never spends and never creates a Build. Its display closure contains
+the Candidates selected by the Run, deterministic Producers and exact Needs that
+their Provider explicitly allows in transient authoring execution. The Runtime owns
+Endpoint activation, Profile bindings, request-level `supports`, credentials and
+invocation; Studio receives no Endpoint Registry and makes no decision from pricing,
+process location, model name or package name. A Need without transient support stops
+with its exact capability named. Existing media and completed Outputs enter through
+ordinary Run Candidates selected with `satisfy`.
+
+Studio and an encoded review use the same ordinary Run. Studio evaluates its
+transient display closure in the browser; building that Run evaluates the
+full target closure and sends the resulting HyperFrames document to the chosen
+render Endpoint. A separate review Run is useful only when the author wants a
+different Candidate selection. Its path and filename carry no execution
+semantics.
+
+Read [`@hypit/studio-adapter`](../studio-adapter/README.md) for the Companion ABI,
+project activation example, value projection and Inspector declarations.

package/packages/studio/index.html

@@ -0,0 +1,10 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width,initial-scale=1" />
+    <link rel="icon" href="data:," />
+    <title>Hypit Studio</title>
+  </head>
+  <body><div id="app"></div><script type="module" src="/src/ui/main.ts"></script></body>
+</html>

package/packages/studio/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@hypit/studio",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./start": "./start.ts",
+    "./src/*": "./src/*"
+  },
+  "dependencies": {
+    "@hypit/audio-track-studio": "workspace:*",
+    "@hypit/build-result": "workspace:*",
+    "@hypit/caption-fine-studio": "workspace:*",
+    "@hypit/cli": "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/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/program-space": "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/speech": "workspace:*",
+    "@hypit/semantic-track": "workspace:*",
+    "@hypit/svs": "workspace:*",
+    "@hypit/temporal": "workspace:*",
+    "@hypit/studio-adapter": "workspace:*",
+    "@hypit/speech-track-studio": "workspace:*",
+    "@hypit/typography-track-studio": "workspace:*",
+    "@hypit/validation": "workspace:*",
+    "@hypit/video-cli": "workspace:*",
+    "@hypit/workspace": "workspace:*",
+    "@hypit/workspace-fs-node": "workspace:*",
+    "vite": "8.2.2"
+  }
+}

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

@@ -0,0 +1,281 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+import { buildIdCreatedAt } from "@hypit/protocol";
+import type { BuildView, NodeRuntimeHost, RuntimeHostTransientExecution } from "@hypit/runtime-host-node";
+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";
+
+type RuntimeControl = Awaited<ReturnType<NodeRuntimeHost["openControl"]>>;
+
+export type StudioBuildLibrary = {
+  readonly profile?: string;
+  readonly runtime?: Pick<RuntimeControl, "activity">;
+  /** Runtime-owned, disposable execution for the current authoring session. */
+  readonly transientExecution?: RuntimeHostTransientExecution;
+  readonly library: (before?: string) => Promise<StudioLibraryView>;
+  readonly resolveHistoricalOutput: (
+    build: string,
+    output: string,
+  ) => Promise<{
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+    readonly attachments?: readonly import("@hypit/workspace").ArtifactAttachment[];
+  } | undefined>;
+  readonly openArtifact: (
+    build: string,
+    output: string,
+    valuePath: string,
+  ) => Promise<{
+    readonly mediaType: string;
+    readonly size: number;
+    open(range?: BuildResultFileRange): Promise<AsyncIterable<Uint8Array> | undefined>;
+  } | undefined>;
+  readonly close: () => Promise<void>;
+};
+
+function projectPath(root: string, path: string): string {
+  return isAbsolute(path) ? resolve(path) : resolve(root, path);
+}
+
+function isWithin(root: string, path: string): boolean {
+  const rel = relative(resolve(root), projectPath(root, path));
+  return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+}
+
+/**
+ * A path inside the project reads the same on every platform, so the Studio library shows one Run
+ * under one name wherever it is opened. A path outside the project is the machine's own, and stays
+ * in that machine's form.
+ */
+function presentedPath(root: string, path: string): string {
+  const absolute = projectPath(root, path);
+  if (!isWithin(root, path)) return absolute;
+  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.activity === "submitting" || view.activity === "ready") return "queued";
+  if (view.activity === "saving-result") return "active";
+  return view.activity;
+}
+
+function taskView(
+  root: string,
+  view: BuildView,
+  result?: BuildResultManifest,
+): StudioTaskView {
+  if (view.source === undefined) throw new Error(`Active Build ${view.id} has no source`);
+  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,
+    status: taskStatus(view),
+    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 }),
+      ...(operation.progress?.completed === undefined ? {} : { completed: operation.progress.completed }),
+      ...(operation.progress?.total === undefined ? {} : { total: operation.progress.total }),
+      ...(operation.progress?.unit === undefined ? {} : { unit: operation.progress.unit }),
+    })),
+  };
+}
+
+function resultTaskView(root: string, result: FinishedBuildResultManifest): StudioTaskView {
+  return {
+    id: result.id,
+    ...(result.title === undefined ? {} : { title: result.title }),
+    ...(result.note === undefined ? {} : { note: result.note }),
+    ...(result.highlightedOutputs === undefined ? {} : { highlightedOutputs: result.highlightedOutputs }),
+    createdAt: buildIdCreatedAt(result.id)!,
+    status: result.outcome,
+    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 [];
+}
+
+async function artifactsForResults(
+  root: string,
+  repository: BuildResultRepository,
+  manifests: readonly BuildResultManifest[],
+): 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}`,
+        build: manifest.id,
+        createdAt: buildIdCreatedAt(manifest.id)!,
+        output,
+        highlighted: manifest.highlightedOutputs?.includes(output) === true,
+        ...(manifest.title === undefined ? {} : { buildTitle: manifest.title }),
+        ...(manifest.note === undefined ? {} : { buildNote: manifest.note }),
+        valuePath,
+        ownerBuild: resolved.build,
+        ownerOutput: resolved.output,
+        filePath: file.path,
+        size: file.size,
+        mediaType: file.mediaType,
+        source: presentedPath(root, manifest.source.path),
+        ...(manifest.run === undefined ? {} : { run: presentedPath(root, manifest.run.path) }),
+      }));
+    })));
+  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));
+}
+
+/** Build the Studio library from execution status and project-owned Build Results. */
+export async function readStudioLibrary(input: {
+  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 active = input.runtime === undefined || input.before !== undefined
+    ? []
+    : (await input.runtime.activity()).builds;
+  const views = active.filter((view) => buildBelongsTo(input.workspaceRoot, view));
+  return {
+    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),
+      )),
+      ...manifests
+        .filter((manifest) => !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),
+  };
+}
+
+/** Open a Runtime profile read-only; Studio never creates or mutates a Build. */
+export async function openStudioBuildLibrary(
+  profile: string | undefined,
+  packageRoot: string,
+  workspaceRoot: string,
+  distributionPackageRoot?: string,
+): Promise<StudioBuildLibrary> {
+  const resolvedProfile = profile === undefined ? undefined : resolve(profile);
+  const host = resolvedProfile === undefined
+    ? undefined
+    : await videoCliDistribution.openRuntimeHost(resolvedProfile, {
+        packageRoot,
+        ...(distributionPackageRoot === undefined ? {} : { distributionPackageRoot }),
+      });
+  const runtime = await host?.openControl({ readOnly: true });
+  let transientExecution: RuntimeHostTransientExecution | undefined;
+  let openedResults: Awaited<ReturnType<typeof videoCliDistribution.openProjectResults>>;
+  try {
+    transientExecution = await host?.openTransientExecution();
+    openedResults = await videoCliDistribution.openProjectResults(workspaceRoot, {
+      packageRoot,
+      ...(distributionPackageRoot === undefined ? {} : { distributionPackageRoot }),
+    });
+  } catch (error) {
+    await transientExecution?.close();
+    await runtime?.close();
+    throw error;
+  }
+  const results = openedResults.repository;
+  return {
+    ...(resolvedProfile === undefined ? {} : { profile: resolvedProfile }),
+    ...(runtime === undefined ? {} : { runtime }),
+    ...(transientExecution === undefined ? {} : { transientExecution }),
+    async library(before) {
+      return await readStudioLibrary({
+        ...(resolvedProfile === undefined ? {} : { profile: resolvedProfile }),
+        workspaceRoot,
+        ...(runtime === undefined ? {} : { runtime }),
+        results,
+        ...(before === undefined ? {} : { before }),
+      });
+    },
+    async resolveHistoricalOutput(build, output) {
+      return await resolveBuildResultValue(results, build, output);
+    },
+    async openArtifact(build, output, valuePath) {
+      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;
+      return {
+        mediaType: match.file.mediaType,
+        size: match.file.size,
+        open: async (range) => await results.openFile(resolved.build, match.file, range),
+      };
+    },
+    async close() {
+      await openedResults.close();
+      await transientExecution?.close();
+      await runtime?.close();
+    },
+  };
+}

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

@@ -0,0 +1,39 @@
+import { installDistributionPackageResolution, loadNodePackageSelection } from "@hypit/package-loader-node";
+import type { LoadedPackage } from "@hypit/package-loader-node";
+import { studioContributionFromPackage } from "@hypit/studio-adapter";
+
+import { fallbackStudioTrackCompanions } from "./fallback-companions.js";
+import { StudioCompanionRegistry } from "./studio-registry.js";
+
+/**
+ * Assemble the immutable Companion Registry for one Source closure.
+ *
+ * The distribution contributes its normal video vocabulary. Every package
+ * actually selected by the Source may contribute its own Companion through the
+ * same package host-facet boundary. There is no second project profile and no
+ * replacement table.
+ */
+export async function loadStudioCompanionRegistry(input: {
+  readonly distributionPackageRoot: string;
+  readonly distributionPackages: readonly string[];
+  readonly sourcePackages: readonly LoadedPackage[];
+}): Promise<StudioCompanionRegistry> {
+  installDistributionPackageResolution([input.distributionPackageRoot]);
+  const distribution = await loadNodePackageSelection(
+    input.distributionPackages,
+    input.distributionPackageRoot,
+  );
+  const selected = new Map<string, LoadedPackage>();
+  for (const item of [...distribution, ...input.sourcePackages]) {
+    if (!selected.has(item.specifier)) selected.set(item.specifier, item);
+  }
+  const contributions = [...selected.values()].map((item) =>
+    studioContributionFromPackage(item.specifier, item.contribution.hostFacets ?? []));
+  return new StudioCompanionRegistry(
+    [...fallbackStudioTrackCompanions, ...contributions.flatMap((item) => item.tracks)],
+    {
+      films: contributions.flatMap((item) => item.films),
+      scripts: contributions.flatMap((item) => item.scripts),
+    },
+  );
+}

package/packages/studio/src/compile.ts

@@ -0,0 +1,166 @@
+import type { NodeCompiledSourceClosure } from "@hypit/compiler-node";
+import type { AuthorElementProvenance, AuthorValueRef } from "@hypit/elaborator";
+import type { ArtifactAttachment } from "@hypit/workspace";
+import type { TypeRef } from "@hypit/protocol";
+
+import type { Observations } from "./observe.js";
+import type { Placement } from "./observe.js";
+
+export type ServedFile = {
+  readonly mediaType: string;
+  readonly bytes: Uint8Array;
+  readonly source?: string;
+};
+
+export type CompiledSource = {
+  readonly compiled: NodeCompiledSourceClosure;
+  readonly observations: Observations;
+  readonly served: ReadonlyMap<string, ServedFile>;
+  readonly exports: readonly {
+    readonly name: string;
+    readonly type: string;
+    readonly typeRef: TypeRef;
+    readonly ref: string;
+  }[];
+};
+
+/**
+ * Attach Studio's observations to the exact Author compilation a Run was
+ * resolved against. Keeping this conversion separate lets the Run compiler and
+ * Studio share one Author graph instead of compiling two look-alike graphs.
+ */
+export async function observedCompiledSource(
+  compiled: NodeCompiledSourceClosure,
+  observations: Observations,
+): Promise<CompiledSource> {
+  const served = new Map<string, ServedFile>();
+  for (const attachment of compiled.attachments) {
+    served.set(attachment.artifact.resource, {
+      mediaType: attachment.artifact.mediaType,
+      bytes: await bytesOf(attachment),
+    });
+  }
+  const normalized = normalizeObservations(compiled, observations);
+  const names = new Map(compiled.provenance.elements.flatMap((element) =>
+    element.outputs.map((output) => [output.id, output.local] as const)));
+  return {
+    compiled,
+    observations: normalized,
+    served,
+    exports: compiled.graph.outputs.map((item) => ({
+      name: compiled.exports.find((candidate) => "id" in candidate.ref && candidate.ref.id === item.id)?.name
+        ?? names.get(item.id)
+        ?? item.id,
+      type: item.type.name,
+      typeRef: item.type,
+      ref: item.id,
+    })),
+  };
+}
+
+function sameRange(
+  left: { readonly start: number; readonly end: number },
+  right: { readonly start: number; readonly end: number },
+): boolean {
+  return left.start === right.start && left.end === right.end;
+}
+
+function exactElement(
+  compiled: NodeCompiledSourceClosure,
+  sourcePath: string,
+  range: { readonly start: number; readonly end: number },
+): AuthorElementProvenance | undefined {
+  return compiled.provenance.elements.find((element) =>
+    element.sourceName === sourcePath && sameRange(element.range, range));
+}
+
+function resolvedRef(compiled: NodeCompiledSourceClosure, ref: AuthorValueRef): string | undefined {
+  if (ref.kind === "record") return ref.id;
+  return compiled.provenance.elements.flatMap((element) => element.outputs)
+    .find((output) => output.component === ref.component && output.name === ref.output)?.id;
+}
+
+function decorate(
+  compiled: NodeCompiledSourceClosure,
+  sourcePath: string,
+  range: { readonly start: number; readonly end: number },
+): {
+  readonly element?: AuthorElementProvenance;
+  readonly records: ReadonlyMap<string, string>;
+  readonly outputs: ReadonlyMap<string, string>;
+  readonly references: Readonly<Record<string, string>>;
+  readonly endpoints: Readonly<Record<string, string>>;
+} {
+  const element = exactElement(compiled, sourcePath, range);
+  if (element === undefined) {
+    return { records: new Map(), outputs: new Map(), references: {}, endpoints: {} };
+  }
+  return {
+    element,
+    records: new Map(element.records.map((record) => [record.local, record.id] as const)),
+    outputs: new Map(element.outputs.map((output) => [output.local, output.id] as const)),
+    references: Object.fromEntries(element.inputs.flatMap((input) => {
+      if (input.ref === undefined) return [];
+      const ref = resolvedRef(compiled, input.ref);
+      return ref === undefined ? [] : [[input.name, ref]];
+    })),
+    endpoints: Object.fromEntries(element.inputs.map((input) => [input.name, input.id])),
+  };
+}
+
+/** Join Studio presentation to compiler-owned identities without re-matching authored names. */
+function normalizeObservations(
+  compiled: NodeCompiledSourceClosure,
+  observations: Observations,
+): Observations {
+  const placements: Placement[] = observations.placements.map((placement) => {
+    const own = decorate(compiled, placement.sourcePath, placement.range);
+    return {
+      ...placement,
+      ...(own.element === undefined ? {} : {
+        authorElement: own.element.id,
+        authorEndpoints: own.endpoints,
+        resolvedReferenceAttributes: own.references,
+        records: placement.records.map((id) => own.records.get(id) ?? id),
+        outputs: placement.outputs.map((id) => own.outputs.get(id) ?? id),
+        outputPorts: placement.outputPorts.map((port) => ({
+          ...port,
+          ref: own.outputs.get(port.ref) ?? port.ref,
+        })),
+        values: placement.values.map((value) => ({ ...value, id: own.records.get(value.id) ?? value.id })),
+      }),
+      children: placement.children.map((child) => {
+        const held = decorate(compiled, child.sourcePath, child.range);
+        return {
+          ...child,
+          ...(held.element === undefined ? {} : {
+            authorElement: held.element.id,
+            authorEndpoints: held.endpoints,
+            resolvedReferenceAttributes: held.references,
+            records: [...held.records.values()],
+            outputs: [...held.outputs.values()],
+            values: child.values.map((value) => ({ ...value, id: held.records.get(value.id) ?? value.id })),
+          }),
+        };
+      }),
+    };
+  });
+  return { placements, sourceMaps: observations.sourceMaps };
+}
+
+async function bytesOf(attachment: ArtifactAttachment): Promise<Uint8Array> {
+  const chunks: Uint8Array[] = [];
+  let size = 0;
+  for await (const chunk of await attachment.open()) {
+    const copy = Uint8Array.from(chunk);
+    chunks.push(copy);
+    size += copy.byteLength;
+  }
+  const bytes = new Uint8Array(size);
+  let offset = 0;
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset);
+    offset += chunk.byteLength;
+  }
+  return bytes;
+}