@hypit/hypit 0.1.2 → 0.1.4

package/README.md

@@ -26,7 +26,7 @@
 <p align="center">
   <a href="https://hypit.ai"><img alt="Visit our website" src="https://img.shields.io/badge/Visit%20our%20website-DF3C68?style=for-the-badge&logo=data:image/svg%2Bxml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjI1Ny4wMyAyODcuNDggNDg2Ljk0IDQyNi4wNCI%2BPHBhdGggZmlsbD0iI2ZmZiIgZD0iTTczMy4wMDEsNDYyLjU5MmMtMTEuNDQtMTYuNTEtMzAuMjg1LTI2LjM0NC01MC4zNTMtMjYuMzQ0aC0xNzguNzA1Yy0yMy40OTMsMC00Ny42NzUsMTQuMjM0LTU2LjYyOCwzNS45NjdsLTU0LjA2NSwxNDUuMDUzYy04LjgsMjEuNTIzLTguNjg2LDQ2LjAxMSw0LjI0Nyw2NS4zNTIsMTIuOTksMTkuNDE4LDM3LjAzOCwzMC44OTcsNjAuMzk3LDMwLjg5N2gxNjQuNDljMjcuMDEzLDAsNTEuNDYzLTE2Ljk4OSw2MC45MTQtNDIuMjhsNTYuODAxLTE1Mi4yMjdjNy4wMjEtMTguODI1LDQuMzgxLTM5LjkwOC03LjA1OS01Ni4zOTl2LS4wMzhoLS4wMzh2LjAxOVpNNjMzLjk3OCw2NTIuODEzYy0xLjc5OCw0LjgyMS02LjQ4NSw4LjA3My0xMS42MzIsOC4wNzNoLTE1OS42NWMtOC4zMDMsMC0xMi43OC01LjM1Ny0xNC4zMjktNy42MzNzLTQuNzgzLTguNDc1LTEuNjA3LTE2LjE0N2w0NS42MjgtMTI2LjcyNWM0LjM4MS0xMi4xNDgsMTUuNDU4LTIwLjc5NiwyOC4zNTItMjEuNDY1LjYzMS0uMDM4LDEuMjgyLS4wMzgsMS45NTEtLjAzOGgxNDQuMjY5czIzLjkzMywyLjcxNywxNy43NzMsMjcuOTUxbC01MC43NTUsMTM2LjAwNGgwdi0uMDE5Wk0zNTYuMjUsNjIzLjEyMnMtNDIuNzc3LTIyLjE3My0zMy43ODYtNjIuNDgzbDU2Ljc2Mi0xNTcuMzE2YzkuMTQ1LTI1LjM0OSwzMy4yMTItNDIuMjYxLDYwLjE2OC00Mi4yNjFoMTgxLjc4NWMxMS45NTcsMCwyMy4xNDksNS43OTcsMzAuMDU1LDE1LjU3M2wyNi41NzMsMzcuNjVoLTIxNi4xMjVjLTE2LjY0NCwwLTMxLjU0NywxMC4zNS0zNy4zNDQsMjUuOTYxbC02OC4wODgsMTgyLjg5NWgwdi0uMDE5Wk0yOTIuMDY0LDU0OS41NDNzLTQyLjc5Ny0yMi4xNzMtMzMuNzg2LTYyLjQ4M2w1Ni43NjItMTU3LjMxNmM5LjE2NC0yNS4zNDksMzMuMjMxLTQyLjI2MSw2MC4xNjgtNDIuMjYxaDE3Mi4wMDljMTEuOTU3LDAsMjMuMTQ5LDUuNzk3LDMwLjA1NSwxNS41NzNsMjYuNTczLDM3LjY1aC0yMDYuMzExYy0xNi42NDQsMC0zMS41NDcsMTAuMzUtMzcuMzQ0LDI1Ljk2MWwtNjguMDg4LDE4Mi44OTVoLS4wMzh2LS4wMTlaIi8%2BPC9zdmc%2B"></a>
   <a href="https://discord.gg/85hnyQnxpn"><img alt="Join our Discord" src="https://img.shields.io/badge/Join%20our%20Discord-5865F2?style=for-the-badge&logo=discord&logoColor=white"></a>
-  <a href="https://t.me/hypit"><img alt="Join our Telegram" src="https://img.shields.io/badge/Join%20our%20Telegram-26A5E4?style=for-the-badge&logo=telegram&logoColor=white"></a>
+  <a href="https://t.me/hypitai"><img alt="Join our Telegram" src="https://img.shields.io/badge/Join%20our%20Telegram-26A5E4?style=for-the-badge&logo=telegram&logoColor=white"></a>
   <a href="https://x.com/hypitai"><img alt="Follow @hypitai on X" src="https://img.shields.io/badge/Follow%20%40hypitai-000000?style=for-the-badge&logo=x&logoColor=white"></a>
 </p>
 

package/dist/public/studio-adapter.d.ts

@@ -159,6 +159,28 @@ type StudioTemporalBinding = {
 declare const studioParameterControls: readonly ["text", "number", "boolean", "select", "color", "list", "record"];
 type StudioParameterControl = typeof studioParameterControls[number];
 type StudioParameterLanguage = "svml" | "svs" | "svrun";
+/** Data-only choices. Packages supply meaning; Studio owns all option rendering. */
+type StudioParameterOption = string | {
+    readonly value: string | number | boolean;
+    readonly label: string;
+    readonly description?: string;
+    readonly preview?: {
+        readonly kind: "color";
+        readonly color: string;
+    } | {
+        readonly kind: "font";
+        readonly family: string;
+        readonly sample?: string;
+    };
+};
+/** Displayed number = authored number × scale. Suffixes are retained, never converted. */
+type StudioNumberPresentation = {
+    readonly scale?: number;
+    readonly suffixes?: readonly string[];
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly step?: number;
+};
 /** A real author endpoint. Its existence never implies Inspector visibility. */
 type StudioSourceBinding = {
     readonly id: string;
@@ -203,8 +225,12 @@ type StudioInspectorFieldDeclaration = {
     readonly summary?: string;
     /** Omit when the binding's public schema selects the finite Studio control. */
     readonly control?: StudioParameterControl;
-    readonly options?: readonly string[];
+    readonly options?: readonly StudioParameterOption[];
     readonly unit?: string;
+    readonly number?: StudioNumberPresentation;
+    readonly multiline?: boolean;
+    /** Optional suggested colors, independent of the accepted color value. */
+    readonly swatches?: readonly string[];
 };
 /** Resolved Inspector DTO. Studio renders it and executes its exact source write. */
 type StudioInspectorField = Omit<StudioInspectorFieldDeclaration, "control"> & {
@@ -314,6 +340,7 @@ type StudioEntityDisplay = {
     readonly layers: readonly StudioDisplayLayer[];
 };
 type StudioLaneDescription = {
+    /** Height of this single timeline lane; overlapping entities share it. */
     readonly heightPx: number;
     readonly groupId?: string;
     readonly attachedTo?: string;
@@ -484,10 +511,12 @@ type StudioEntityDraft = {
     readonly display: StudioEntityDisplay;
     readonly startFrame: number;
     readonly endFrameExclusive: number;
+    /** Back-to-front timeline order. Ties preserve projection order. Selection raises only the timeline item. */
     readonly stackOrder: number;
     readonly elementRange?: Range;
     readonly markerId?: string;
     readonly presentId?: string;
+    /** Rendered parts belonging to this entity, including phases beyond its editable timeline interval. */
     readonly renderIds?: readonly string[];
     /** Resolved author references that differ per derived entity, such as one Cue's actual Style. */
     readonly parameterReferences?: Readonly<Record<string, string>>;
@@ -683,4 +712,4 @@ declare function childEntities(context: StudioTrackCompanionContext, items: read
 }[], entity: StudioTimelinePresentation["entity"], chrome: StudioTimelinePresentation["chrome"]): readonly StudioEntityDraft[];
 
 export { artifactPreview, authoredChildFor, childEntities, createStudioCompanionHostFacet, createStudioTrackCompanionHostFacet, previewLayer, requiredReferencedValue, requiredSurfaceValue, sameSurfaceValue, studioCompanionHostAbi, studioContributionFromPackage, studioParameterControls, studioTrackCompanionsFromPackage, temporalBindingsFor, temporalLineageFor, temporalSemanticSource, textLayer };
-export type { Range, StudioCandidateProvenance, StudioCompanionContribution, StudioCompanionHostFacet, StudioDisplayLayer, StudioEditCoordinate, StudioEditHandle, StudioEditSource, StudioEditSourceRole, StudioEntityDisplay, StudioEntityDraft, StudioFilmCompanion, StudioIcon, StudioInspectorDomain, StudioInspectorField, StudioInspectorFieldDeclaration, StudioInspectorPageDeclaration, StudioInspectorSectionDeclaration, StudioLaneAttachment, StudioLaneDescription, StudioMaterialPreview, StudioObservedValue, StudioPackageContribution, StudioParameterControl, StudioParameterLanguage, StudioPlacement, StudioPlacementChild, StudioPreviewSource, StudioRecipeBindingDeclaration, StudioRecipeReferenceBindingDeclaration, StudioResolvedTrack, StudioScriptAdjustment, StudioScriptCompanion, StudioScriptSourceMap, StudioSemanticAnchor, StudioSemanticEditTarget, StudioSemanticSegment, StudioSemanticTimeline, StudioSemanticToken, StudioSnapTarget, StudioSourceBinding, StudioSourceBindingDeclaration, StudioSpan, StudioTemporalAuthority, StudioTemporalBinding, StudioTemporalConsumer, StudioTemporalConsumerInput, StudioTemporalInstantProjection, StudioTemporalLineage, StudioTemporalPhase, StudioTemporalProjection, StudioTemporalSource, StudioTemporalWindowProjection, StudioTimelineGesture, StudioTimelinePresentation, StudioTimelineTone, StudioTrackCompanion, StudioTrackCompanionContext, StudioTrackFamily, StudioTrackTrace, StudioViewRole };
+export type { Range, StudioCandidateProvenance, StudioCompanionContribution, StudioCompanionHostFacet, StudioDisplayLayer, StudioEditCoordinate, StudioEditHandle, StudioEditSource, StudioEditSourceRole, StudioEntityDisplay, StudioEntityDraft, StudioFilmCompanion, StudioIcon, StudioInspectorDomain, StudioInspectorField, StudioInspectorFieldDeclaration, StudioInspectorPageDeclaration, StudioInspectorSectionDeclaration, StudioLaneAttachment, StudioLaneDescription, StudioMaterialPreview, StudioNumberPresentation, StudioObservedValue, StudioPackageContribution, StudioParameterControl, StudioParameterLanguage, StudioParameterOption, StudioPlacement, StudioPlacementChild, StudioPreviewSource, StudioRecipeBindingDeclaration, StudioRecipeReferenceBindingDeclaration, StudioResolvedTrack, StudioScriptAdjustment, StudioScriptCompanion, StudioScriptSourceMap, StudioSemanticAnchor, StudioSemanticEditTarget, StudioSemanticSegment, StudioSemanticTimeline, StudioSemanticToken, StudioSnapTarget, StudioSourceBinding, StudioSourceBindingDeclaration, StudioSpan, StudioTemporalAuthority, StudioTemporalBinding, StudioTemporalConsumer, StudioTemporalConsumerInput, StudioTemporalInstantProjection, StudioTemporalLineage, StudioTemporalPhase, StudioTemporalProjection, StudioTemporalSource, StudioTemporalWindowProjection, StudioTimelineGesture, StudioTimelinePresentation, StudioTimelineTone, StudioTrackCompanion, StudioTrackCompanionContext, StudioTrackFamily, StudioTrackTrace, StudioViewRole };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypit/hypit",
-  "version": "0.1.2",
+  "version": "0.1.4",
   "homepage": "https://hypit.ai",
   "repository": {
     "type": "git",
@@ -115,6 +115,8 @@
     "packages/*/*.html",
     "packages/*/package.json",
     "packages/*/README.md",
+    "packages/temporal-markup/EDITING.md",
+    "packages/studio/INSPECTOR.md",
     "services/image-opencv/pyproject.toml",
     "services/image-opencv/package.json",
     "services/image-opencv/uv.lock",
@@ -259,6 +261,7 @@
   },
   "dependencies": {
     "@puppeteer/browsers": "3.2.2",
+    "koffi": "3.2.1",
     "puppeteer-core": "25.10.0",
     "sharp": "0.35.3",
     "cmu-pronouncing-dictionary": "3.0.0",

package/packages/audio-track-studio/src/index.ts

@@ -48,22 +48,25 @@ export const audioTrackStudioTrackCompanions: readonly StudioTrackCompanion[] =
     ],
     inspector: [
       {
-        binding: "playback", label: "Playback", domain: "how",
+        binding: "playback", label: "Playback", domain: "when",
         page: { id: "playback", label: "Playback" }, section: { id: "playback", label: "Playback" },
         control: "select", options: ["once", "once-start", "once-end", "loop", "loop-start", "loop-end", "stretch"],
       },
       ...(["trim-start", "trim-end"] as const).map((binding) => ({
-        binding, label: binding === "trim-start" ? "Trim Start" : "Trim End", domain: "how" as const,
-        page: { id: "playback", label: "Playback" }, section: { id: "trim", label: "Trim" }, control: "text" as const,
+        binding, label: binding === "trim-start" ? "Trim Start" : "Trim End", domain: "when" as const,
+        page: { id: "playback", label: "Playback" }, section: { id: "trim", label: "Trim" }, control: "number" as const,
+        number: { suffixes: ["ms", "s", "f"], minimum: 0 },
       })),
       ...(["min-rate", "max-rate", "gain"] as const).map((binding) => ({
         binding, label: binding === "min-rate" ? "Minimum Rate" : binding === "max-rate" ? "Maximum Rate" : "Gain",
         domain: "how" as const, page: { id: "mix", label: "Mix" }, section: { id: "mix", label: "Mix" },
         control: "number" as const,
+        unit: "%", number: { scale: 100, minimum: 0, step: 1 },
       })),
       ...(["fade-in", "fade-out"] as const).map((binding) => ({
         binding, label: binding === "fade-in" ? "Fade In" : "Fade Out", domain: "when" as const,
-        page: { id: "fade", label: "Fade" }, section: { id: "fade", label: "Fade" }, control: "text" as const,
+        page: { id: "fade", label: "Fade" }, section: { id: "fade", label: "Fade" }, control: "number" as const,
+        number: { suffixes: ["ms", "s", "f"], minimum: 0 },
       })),
     ],
     requiredValues: ["program"], project: projectAudio,

package/packages/build-result/README.md

@@ -0,0 +1,58 @@
+# `@hypit/build-result`
+
+Build Results retain accepted public Outputs and the attempt's final outcome. Execution state belongs
+to Runtime. A Result records which value satisfied each Output; a new Output record does not imply a
+new media file.
+
+## Values and file ownership
+
+| Value source | Persisted representation |
+| --- | --- |
+| New Resource without an existing durable address | One file owned by this Build |
+| Explicit Workspace file | `external-file` with the Workspace's URI |
+| Resource from an earlier Result | `build-file` with its original `build` and `path` |
+| Entire earlier public Output | `build-output` pointing to its terminal Build and Output |
+| Composite value | A Value Document whose Resource bindings follow the same rules at every depth |
+
+A local `build-file` omits `build` when its owner is the containing Result. When imported into another
+Build, its owner becomes explicit. Arrays and nested objects do not change ownership: a new Composite
+can save new structure while referencing old video, audio and images. Only newly produced Resources
+get new files. The encoder recognizes Resource values, independently of their domain Type or field name.
+
+An `external-file` stays live. Replacing that file changes subsequent reads; deleting it leaves an
+unavailable dependency. The stored size describes the file when admitted; `describeFile` and public
+Output resolution obtain its current size. Readers use the explicit address without searching for
+alternatives or comparing file contents.
+
+## Passing references through execution
+
+Workspace attachments may supply a `location` URI. The Node compiler preserves it, and the CLI maps
+these addresses and explicitly imported Result files to the compilation's Resource identities. It
+passes that map as `BuildResultSeed.resourceReferences` alongside whole-Output `forwards`.
+
+The Result writer keeps this per-Build map in its private writer state while publishing. It uses the
+map for both direct Resource Outputs and all nested Resource bindings. Persistent Output documents
+contain the references they actually use; private writer state is removed at the terminal outcome.
+Core still receives ordinary typed Records, Candidates and Resource identities. It has no knowledge
+of file paths or Result repositories. Runtime may stage input bytes for execution independently of
+Result publication.
+
+Repositories own address access. `describeFile` obtains metadata and `openFile` streams bytes or a byte
+range. The filesystem and S3 implementations accept `ExternalFileAccess` for external addresses; the
+Node default opens Workspace `file:` URIs. A custom adapter can supply a different address reader.
+Selecting S3 for Result storage does not implicitly upload external file dependencies.
+
+`fileReferenceIdentity` identifies the explicit URI or owning Build and path. Studio uses this identity
+to group multiple uses of a file. Separate files remain separate even when their bytes happen to match.
+
+An explicit `hypit get` export collects the selected Output's referenced bytes into its destination.
+Composite exports rewrite bindings to local files, including references with different owners but the
+same relative filename. This makes that export self-contained; ordinary Build publication preserves
+references. Moving editable projects also requires preserving or updating their external file addresses.
+
+Published Outputs can carry an optional author `displayName` for browsers such as Studio.
+It is presentation text only: Output names, forwarding and file ownership do not change.
+
+`updatePresentation` accepts `outputDisplayNames`, keyed by exact public Output name. Each
+nonempty string sets that Output’s `displayName`; null removes it. Like title and note editing,
+this applies to finished Results and preserves all values, file references and Output identifiers.

package/packages/build-result/package.json

@@ -8,6 +8,7 @@
     ".": "./src/index.ts"
   },
   "dependencies": {
-    "@hypit/protocol": "workspace:*"
+    "@hypit/protocol": "workspace:*",
+    "koffi": "3.2.1"
   }
 }

package/packages/build-result/src/decode.ts

@@ -70,14 +70,9 @@ function resultPath(value: unknown, subject: string): string {
 
 function outputValue(value: unknown, subject: string): BuildResultOutputValue {
   const item = object(value, subject);
-  if (item.kind === "build-file") {
+  if (item.kind === "build-file" || item.kind === "external-file") {
     assertBuildResultFileRef(item, subject);
-    return {
-      kind: "build-file",
-      path: item.path,
-      size: item.size,
-      mediaType: item.mediaType,
-    };
+    return { ...item };
   }
   if (item.kind === "build-output") {
     return {
@@ -106,6 +101,7 @@ function outputs(value: unknown, subject: string): Readonly<Record<string, Build
     text(name, `${subject} Output name`);
     const item = object(value, `${subject}[${JSON.stringify(name)}]`);
     return [name, {
+      ...(item.displayName === undefined ? {} : { displayName: text(item.displayName, `${subject}.displayName`) }),
       type: typeRef(item.type, `${subject}[${JSON.stringify(name)}].type`),
       value: outputValue(item.value, `${subject}[${JSON.stringify(name)}].value`),
     }] as const;
@@ -255,7 +251,7 @@ export function decodeBuildResultWriterState(
     if (logicalOutputs.has(output)) throw new Error(`${subject} publishes Logical Output ${output} more than once`);
     names.add(name);
     logicalOutputs.add(output);
-    return { name, output };
+    return { name, output, ...(published.displayName === undefined ? {} : { displayName: text(published.displayName, `${subject}.displayName`) }) };
   });
   const forwardedOutputs = new Set<string>();
   const forwards = item.forwards.map((value, index) => {
@@ -270,6 +266,12 @@ export function decodeBuildResultWriterState(
     };
   });
   return {
+    ...(item.resourceReferences === undefined ? {} : { resourceReferences: Object.fromEntries(
+      Object.entries(object(item.resourceReferences, `${subject}.resourceReferences`)).map(([resource, reference]) => {
+        assertBuildResultFileRef(reference, `${subject}.resourceReferences.${resource}`);
+        return [resource, reference];
+      }),
+    ) }),
     resources: pathMap(item.resources, `${subject}.resources`),
     values: pathMap(item.values, `${subject}.values`),
     publishedOutputs,

package/packages/build-result/src/file-reference.ts

@@ -0,0 +1,42 @@
+import { createReadStream } from "node:fs";
+import { stat } from "node:fs/promises";
+import { fileURLToPath } from "node:url";
+import type { BuildResultFileRange, BuildResultFileRef } from "./types.js";
+
+/** Address access belongs to the Repository adapter, not the value or domain graph. */
+export type ExternalFileAccess = {
+  size(uri: string): Promise<number>;
+  open(uri: string, range?: BuildResultFileRange): Promise<AsyncIterable<Uint8Array>>;
+};
+
+/** The Node distribution's external files are explicit file: URLs supplied by its Workspace. */
+export const localExternalFiles: ExternalFileAccess = {
+  async size(uri) { return (await stat(fileURLToPath(uri))).size; },
+  async open(uri, range) {
+    if (range !== undefined) {
+      const size = await localExternalFiles.size(uri);
+      if (!Number.isSafeInteger(range.start) || range.start < 0
+        || !Number.isSafeInteger(range.endExclusive) || range.endExclusive <= range.start
+        || range.endExclusive > size) throw new Error(`Invalid file range for ${uri}`);
+    }
+    return createReadStream(fileURLToPath(uri), range === undefined ? {} : { start: range.start, end: range.endExclusive - 1 });
+  },
+};
+
+export function fileReferenceIdentity(owner: string, file: BuildResultFileRef): string {
+  return file.kind === "external-file" ? JSON.stringify(["external", file.uri])
+    : JSON.stringify(["result", file.build ?? owner, file.path]);
+}
+
+/** Make a relative Result file reference independent of its enclosing value document. */
+export function ownedFileReference(owner: string, file: BuildResultFileRef): BuildResultFileRef {
+  return file.kind === "build-file" ? { ...file, build: file.build ?? owner } : file;
+}
+
+/** Reopening an external reference reads its current metadata, without comparing versions. */
+export async function currentFileReference(
+  file: BuildResultFileRef,
+  access: ExternalFileAccess = localExternalFiles,
+): Promise<BuildResultFileRef> {
+  return file.kind === "external-file" ? { ...file, size: await access.size(file.uri) } : file;
+}

package/packages/build-result/src/index.ts

@@ -23,3 +23,6 @@ export {
 } from "./store.js";
 export type * from "./types.js";
 export type * from "./writer.js";
+
+export { currentFileReference, fileReferenceIdentity, ownedFileReference, localExternalFiles } from "./file-reference.js";
+export type { ExternalFileAccess } from "./file-reference.js";

package/packages/build-result/src/replace-file-windows.ts

@@ -0,0 +1,58 @@
+import { toNamespacedPath } from "node:path";
+import koffi from "koffi";
+
+const kernel = koffi.load("kernel32.dll");
+const createFile = kernel.func("intptr_t __stdcall CreateFileW(const char16_t *path, uint32_t access, uint32_t share, void *security, uint32_t disposition, uint32_t attributes, intptr_t templateFile)");
+const setInformation = kernel.func("int __stdcall SetFileInformationByHandle(intptr_t file, int infoClass, void *info, uint32_t size)");
+const closeHandle = kernel.func("int __stdcall CloseHandle(intptr_t file)");
+const getLastError = kernel.func("uint32_t __stdcall GetLastError()");
+
+const renameInfo = koffi.struct({
+  Flags: "uint32_t",
+  RootDirectory: "void *",
+  FileNameLength: "uint32_t",
+  FileName: koffi.array("uint16_t", 1),
+});
+
+const DELETE = 0x00010000;
+const SHARE_READ_WRITE_DELETE = 0x7;
+const OPEN_EXISTING = 3;
+const FILE_ATTRIBUTE_NORMAL = 0x80;
+const FileRenameInfoEx = 22;
+const REPLACE_IF_EXISTS = 0x1;
+const POSIX_SEMANTICS = 0x2;
+
+function failure(syscall: string, from: string, to: string): Error {
+  const win32Code = getLastError() as number;
+  return Object.assign(new Error(`Windows file replacement failed (${win32Code}): '${from}' -> '${to}'`), {
+    code: `WIN32_${win32Code}`, win32Code, syscall, path: from, dest: to,
+  });
+}
+
+/**
+ * FileRenameInfoEx preserves open readers of the old file while publishing the new name.
+ * Node's Windows rename uses MoveFileExW, whose replacement semantics differ here.
+ * https://learn.microsoft.com/en-us/openspecs/windows_protocols/ms-fscc/4217551b-d2c0-42cb-9dc1-69a716cf6d0c
+ */
+export function replaceWindowsFile(from: string, to: string): void {
+  const filename = Buffer.from(toNamespacedPath(to), "utf16le");
+  const nameOffset = koffi.offsetof(renameInfo, "FileName");
+  // Win32 requires a NUL-terminated FileName even though FileNameLength excludes
+  // that terminator. Buffer.alloc leaves the final WCHAR zero-initialized.
+  // https://learn.microsoft.com/en-us/windows/win32/api/winbase/ns-winbase-file_rename_info
+  const info = Buffer.alloc(Math.max(koffi.sizeof(renameInfo), nameOffset + filename.length + 2));
+  info.writeUInt32LE(REPLACE_IF_EXISTS | POSIX_SEMANTICS, koffi.offsetof(renameInfo, "Flags"));
+  info.writeUInt32LE(filename.length, koffi.offsetof(renameInfo, "FileNameLength"));
+  filename.copy(info, nameOffset);
+
+  const handle = createFile(toNamespacedPath(from), DELETE, SHARE_READ_WRITE_DELETE,
+    null, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, 0) as number | bigint;
+  if (handle === -1 || handle === -1n) throw failure("CreateFileW", from, to);
+  try {
+    if (!setInformation(handle, FileRenameInfoEx, info, info.length)) {
+      throw failure("SetFileInformationByHandle", from, to);
+    }
+  } finally {
+    closeHandle(handle);
+  }
+}

package/packages/build-result/src/replace-file.ts

@@ -0,0 +1,11 @@
+import { rename } from "node:fs/promises";
+
+/** Publish a complete file without changing the bytes held by existing readers. */
+export async function replaceFile(from: string, to: string): Promise<void> {
+  if (process.platform === "win32") {
+    const { replaceWindowsFile } = await import("./replace-file-windows.js");
+    replaceWindowsFile(from, to);
+  } else {
+    await rename(from, to);
+  }
+}

package/packages/build-result/src/store.ts

@@ -1,3 +1,5 @@
+import { currentFileReference, localExternalFiles } from "./file-reference.js";
+import type { ExternalFileAccess } from "./file-reference.js";
 import { randomUUID } from "node:crypto";
 import {
   mkdir,
@@ -40,6 +42,7 @@ import {
   encodeBuildResultManifest,
 } from "./decode.js";
 import { syncBuildResultOutputs } from "./writer.js";
+import { replaceFile } from "./replace-file.js";
 
 const manifestName = "result.json";
 const writerStateName = ".writer.json";
@@ -83,6 +86,22 @@ export function applyBuildResultPresentation(
     if (highlighted.length === 0) delete base.highlightedOutputs;
     else base.highlightedOutputs = highlighted;
   }
+  if (update.outputDisplayNames !== undefined) {
+    const outputs = { ...manifest.outputs };
+    for (const [name, value] of Object.entries(update.outputDisplayNames)) {
+      const entry = manifest.outputs[name];
+      assert(Object.hasOwn(manifest.outputs, name) && entry !== undefined,
+        `Build Result ${manifest.id} has no Output ${name}`);
+      const { displayName: _priorName, ...rest } = entry;
+      if (value === null) outputs[name] = rest;
+      else {
+        const displayName = value.trim();
+        assert(displayName.length > 0, "Output display name must not be empty");
+        outputs[name] = { ...rest, displayName };
+      }
+    }
+    return { ...base, outputs };
+  }
   return base;
 }
 
@@ -95,7 +114,7 @@ async function writeJsonAtomic(path: string, value: unknown): Promise<void> {
   const temporary = `${path}.part-${randomUUID()}`;
   try {
     await writeFile(temporary, `${JSON.stringify(value, null, 2)}\n`, { flag: "wx" });
-    await rename(temporary, path);
+    await replaceFile(temporary, path);
   } catch (error) {
     await rm(temporary, { force: true });
     throw error;
@@ -123,7 +142,7 @@ async function copyArtifactAtomic(
       await output.write(chunk);
     }
     await output.close();
-    await rename(temporary, destination);
+    await replaceFile(temporary, destination);
   } catch (error) {
     await output.close().catch(() => undefined);
     await rm(temporary, { force: true });
@@ -221,6 +240,7 @@ export async function resolveBuildResultOutput(
   root: string,
   build: string,
   output: string,
+  externalFiles: ExternalFileAccess = localExternalFiles,
 ): Promise<ResolvedBuildResultOutput | undefined> {
   const seen = new Set<string>();
   let currentBuild = build;
@@ -254,14 +274,14 @@ export async function resolveBuildResultOutput(
       };
     }
     const terminalKind = (entry.value as { readonly kind?: unknown }).kind;
-    assert(terminalKind === "build-file" || terminalKind === "inline",
+    assert(terminalKind === "build-file" || terminalKind === "external-file" || terminalKind === "inline",
       `Build ${currentBuild} Output ${currentOutput} has unsupported Result value kind ${String(terminalKind)}`);
     return {
       build: currentBuild,
       output: currentOutput,
       directory,
       type: entry.type,
-      value: entry.value,
+      value: entry.value.kind === "external-file" ? await currentFileReference(entry.value, externalFiles) : entry.value,
     };
   }
 }
@@ -270,6 +290,7 @@ export async function describeBuildResultOutput(
   root: string,
   build: string,
   output: string,
+  externalFiles: ExternalFileAccess = localExternalFiles,
 ): Promise<RepositoryBuildResultOutputDescription | undefined> {
   const seen = new Set<string>();
   let currentBuild = build;
@@ -286,8 +307,9 @@ export async function describeBuildResultOutput(
       currentOutput = entry.value.output;
       continue;
     }
-    return entry.value.kind === "build-file"
-      ? { type: entry.type, kind: "resource", size: entry.value.size, mediaType: entry.value.mediaType }
+    const file = entry.value.kind === "external-file" ? await currentFileReference(entry.value, externalFiles) : entry.value;
+    return file.kind === "build-file" || file.kind === "external-file"
+      ? { type: entry.type, kind: "resource", size: file.size, mediaType: file.mediaType }
       : entry.value.kind === "value"
         ? { type: entry.type, kind: "composite" }
         : { type: entry.type, kind: "scalar" };
@@ -334,12 +356,12 @@ export class FileBuildResult {
     this.directory = resolve(directory);
   }
 
-  static async create(root: string, seed: BuildResultSeed): Promise<FileBuildResult> {
+  static async create(root: string, seed: BuildResultSeed, externalFiles: ExternalFileAccess = localExternalFiles): Promise<FileBuildResult> {
     assertOrderedBuildId(seed.id);
     assertBuildResultSeed(seed);
     const forwards = await normalizeBuildResultForwards({
       read: async (build) => await readBuildResult(buildResultDirectory(root, build)),
-      resolve: async (build, output) => await resolveBuildResultOutput(root, build, output),
+      resolve: async (build, output) => await resolveBuildResultOutput(root, build, output, externalFiles),
     }, seed.forwards ?? []);
     const directory = buildResultDirectory(root, seed.id);
     await mkdir(dirname(directory), { recursive: true });
@@ -360,6 +382,7 @@ export class FileBuildResult {
         resources: {},
         values: {},
         publishedOutputs: seed.publishedOutputs,
+        ...(seed.resourceReferences === undefined ? {} : { resourceReferences: seed.resourceReferences }),
         forwards,
       });
       await rename(temporary, directory);
@@ -405,6 +428,7 @@ export class FileBuildResult {
         },
       },
     });
+    if (!updated.changed) return manifest;
     await writeJsonAtomic(join(this.directory, writerStateName), updated.writer);
     await writeManifestAtomic(join(this.directory, manifestName), updated.manifest);
     return updated.manifest;
@@ -434,15 +458,17 @@ export class FileBuildResult {
 
 /** Default zero-configuration project repository backed by one ordinary directory tree. */
 export class FileBuildResultRepository implements BuildResultRepository {
+  readonly externalFiles: ExternalFileAccess;
   readonly root: string;
 
-  constructor(root: string) {
+  constructor(root: string, externalFiles: ExternalFileAccess = localExternalFiles) {
+    this.externalFiles = externalFiles;
     assert(root.trim().length > 0, "Build Result root must not be empty");
     this.root = resolve(root);
   }
 
   async create(seed: BuildResultSeed): Promise<FileBuildResult> {
-    return await FileBuildResult.create(this.root, seed);
+    return await FileBuildResult.create(this.root, seed, this.externalFiles);
   }
 
   async openWriter(build: string): Promise<FileBuildResult | undefined> {
@@ -477,22 +503,27 @@ export class FileBuildResultRepository implements BuildResultRepository {
   }
 
   async describeOutput(build: string, output: string): Promise<RepositoryBuildResultOutputDescription | undefined> {
-    return await describeBuildResultOutput(this.root, build, output);
+    return await describeBuildResultOutput(this.root, build, output, this.externalFiles);
   }
 
   async resolve(build: string, output: string): Promise<RepositoryBuildResultOutput | undefined> {
-    const resolvedOutput = await resolveBuildResultOutput(this.root, build, output);
+    const resolvedOutput = await resolveBuildResultOutput(this.root, build, output, this.externalFiles);
     if (resolvedOutput === undefined) return undefined;
     const { directory: _directory, ...portable } = resolvedOutput;
     return portable;
   }
 
+  async describeFile(_build: string, file: BuildResultFileRef): Promise<BuildResultFileRef> {
+    return await currentFileReference(file, this.externalFiles);
+  }
+
   async openFile(
     build: string,
     file: BuildResultFileRef,
     range?: BuildResultFileRange,
   ): Promise<AsyncIterable<Uint8Array> | undefined> {
-    const directory = buildResultDirectory(this.root, build);
+    if (file.kind === "external-file") return await this.externalFiles.open(file.uri, range);
+    const directory = buildResultDirectory(this.root, file.build ?? build);
     const path = containedResultPath(directory, file.path);
     if (!await exists(path)) return undefined;
     if (range === undefined) return createReadStream(path);