@hypit/hypit 0.1.3 → 0.1.5

package/packages/audio-track/src/manifest.ts

@@ -1,11 +1,12 @@
+import { timelineTypes } from "@hypit/timeline";
 import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
 import { compositionDependency, compositionTypes } from "@hypit/composition";
 import { mediaDependency, mediaTypes } from "@hypit/media";
 import { narrativeDependency } from "@hypit/narrative";
-import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
+
 import { blobRefObjectSchema } from "@hypit/protocol";
 import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
-import { semanticTrackDependency } from "@hypit/semantic-track";
+import { timelineDependency } from "@hypit/timeline";
 import { temporalDependency, temporalTypes } from "@hypit/temporal";
 import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
 
@@ -68,7 +69,7 @@ export const audioTrackProgramSchema: ValueSchema = object({
 
 const baseInputs = [
   { name: "set", type: audioTrackTypes.set }, { name: "header", type: audioTrackTypes.header },
-  { name: "space", type: programSpaceTypes.programSpace }, { name: "media", type: mediaTypes.synchronized },
+  { name: "timeline", type: timelineTypes.track }, { name: "media", type: mediaTypes.synchronized },
   { name: "spec", type: audioTrackTypes.clipSpec }, { name: "window", type: temporalTypes.window },
 ] as const;
 
@@ -76,20 +77,20 @@ export const audioTrackMarkupSurfaces = [{
     name: "track", tag: "Track", mode: "structured",
     outputs: [audioTrackTypes.header, audioTrackTypes.clipSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, audioTrackTypes.program, compositionTypes.audioTrack],
     vocabulary: {
-      summary: "One Audio Track: explicitly prepared audio Clips placed on the selected film time axis and lowered to one ordinary peer AudioTrack.",
+      summary: "One Audio Track: explicitly prepared audio Items placed on the selected film time axis and lowered to one ordinary peer AudioTrack.",
       attributes: [
-        { name: "id", kind: "identifier", required: true, summary: "Names this Audio Track and prefixes the identity of every Clip that does not name itself." },
+        { name: "id", kind: "identifier", required: true, summary: "Names this Audio Track and prefixes the identity of every Item that does not name itself." },
         ...temporalContextAttributeVocabulary,
       ],
       children: [
-        { tag: "Clip", cardinality: "many",
+        { tag: "Item", cardinality: "many",
           summary: "Places one SynchronizedMedia source on an exact program window with its own trim, occupancy and mix.",
           attributes: [
             { name: "id", kind: "identifier", required: false,
-              summary: "Names this Clip; the Track derives `<track>.clip.<index>` when it is absent." },
+              summary: "Names this Item; the Track derives `<track>.item.<index>` when it is absent." },
             { name: "source", kind: "reference", required: true,
               accepts: [mediaTypes.synchronized],
-              summary: "Selects the explicitly prepared audio this Clip plays." },
+              summary: "Selects the explicitly prepared audio this Item plays." },
             ...temporalWindowAttributeVocabulary,
             { name: "trim-start", kind: "literal", required: false,
               summary: "Sets the source start position; defaults to the source beginning." },
@@ -103,7 +104,7 @@ export const audioTrackMarkupSurfaces = [{
             { name: "max-rate", kind: "literal", required: false,
               summary: "Bounds the fastest rate bounded stretch may use." },
             { name: "gain", kind: "literal", required: false,
-              summary: "Scales this Clip by a linear gain; defaults to `1`." },
+              summary: "Scales this Item by a linear gain; defaults to `1`." },
             { name: "fade-in", kind: "literal", required: false,
               summary: "Fixes the exact fade-in length; defaults to `0f`." },
             { name: "fade-out", kind: "literal", required: false,
@@ -112,15 +113,15 @@ export const audioTrackMarkupSurfaces = [{
       ],
       ports: [
         { name: "program", type: audioTrackTypes.program, summary: "The resolved sample-exact item list this Track renders from." },
-        { name: "track", type: compositionTypes.audioTrack, summary: "The rendered AudioTrack that Film composes with its peers." },
+        { name: "audio", type: compositionTypes.audioTrack, summary: "The rendered AudioTrack that Film composes with its peers." },
       ],
-      example: `<audio:Track id="music-bed" semantic={speech.semantic}>
-  <audio:Clip source={music-media.media} during="program"
+      example: `<audio:Track id="music-bed" timeline={speech.timeline}>
+  <audio:Item source={music-media.media} during="program"
     playback="loop-end" gain="0.28" fade-in="600ms" fade-out="800ms"/>
 </audio:Track>`,
       notes: [
-        "A Track requires at least one Clip, and neither a Track nor a Clip accepts text content.",
-        "A Clip states exactly one window form: `during`, `at` with `for`, `until` with `for`, or `start` with `end`.",
+        "A Track requires at least one Item, and neither a Track nor a Item accepts text content.",
+        "A Item states exactly one window form: `during`, `at` with `for`, `until` with `for`, or `start` with `end`.",
         "A point expression is `program.start`, `program.end`, `selection.start`, `selection.end`, `segment.start`, `segment.end` or `moment.cue`, each optionally offset by `+` or `-` and a duration, or a bare duration read as an absolute position.",
         "Bind selection, segment and/or moment only when the start/end expressions use them; different endpoints can use different bindings.",
         "`min-rate` and `max-rate` are rejected unless `playback` is `stretch`.",
@@ -133,7 +134,7 @@ export const audioTrackManifest: ModuleManifest = {
   format: "hypit.module@1",
   name: audioTrackModuleRef.name,
   version: audioTrackModuleRef.version,
-  dependencies: [mediaDependency, narrativeDependency, programSpaceDependency, semanticTrackDependency, temporalDependency, compositionDependency],
+  dependencies: [mediaDependency, narrativeDependency, timelineDependency, temporalDependency, compositionDependency],
   types: [
     { name: audioTrackTypes.header.name },
     { name: audioTrackTypes.clipSpec.name },
@@ -145,7 +146,7 @@ export const audioTrackManifest: ModuleManifest = {
     { name: audioTrackProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: audioTrackTypes.set }], needs: [] },
     { name: audioTrackProducers.appendItem.name, inputs: [...baseInputs], outputs: [{ name: "set", type: audioTrackTypes.set }], needs: [] },
     { name: audioTrackProducers.finalize.name, inputs: [{ name: "set", type: audioTrackTypes.set }, { name: "header", type: audioTrackTypes.header }], outputs: [{ name: "program", type: audioTrackTypes.program }], needs: [] },
-    { name: audioTrackProducers.render.name, inputs: [{ name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: audioTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.audioTrack }], needs: [] },
+    { name: audioTrackProducers.render.name, inputs: [{ name: "timeline", type: timelineTypes.track }, { name: "program", type: audioTrackTypes.program }], outputs: [{ name: "track", type: compositionTypes.audioTrack }], needs: [] },
   ],
 };
 export const audioTrackDependency = { module: audioTrackModuleRef } as const;

package/packages/audio-track/src/program.ts

@@ -1,13 +1,9 @@
+import type { Timeline } from "@hypit/timeline";
 import { assertAudioTrackIdentity, sealAudioTrack } from "@hypit/composition";
 import type { AudioClip, AudioTrack } from "@hypit/composition";
 import { synchronizedMediaSampleFrames, verifySynchronizedMedia } from "@hypit/media";
 import type { SynchronizedMedia } from "@hypit/media";
-import {
-  assertProgramSpaceIdentity,
-  programFrameSampleBoundary,
-  programSpaceSampleFrames,
-} from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
+import { assertProgramSpaceIdentity, programFrameSampleBoundary, programSpaceSampleFrames } from "@hypit/program-space";
 import { canonicalize, isResourceId } from "@hypit/protocol";
 import { assertTemporalWindowFor, temporalDurationInSamples } from "@hypit/temporal";
 import type { ProjectedWindow, TemporalDuration } from "@hypit/temporal";
@@ -94,23 +90,23 @@ function sourceFacts(media: SynchronizedMedia): AudioItemProgram["source"] {
 function realizedItems(
   set: AudioTrackSet,
   header: AudioTrackHeader,
-  space: ProgramSpace,
+  timeline: Timeline,
   media: SynchronizedMedia,
   spec: AudioClipSpec,
   window: ProjectedWindow,
 ): AudioTrackSet {
   assertAudioTrackSet(set);
   assertAudioTrackHeader(header);
-  assertProgramSpaceIdentity(space);
+  assertProgramSpaceIdentity(timeline);
   assertAudioClipSpec(spec);
-  assertTemporalWindowFor(window, { subjectId: spec.id, space });
+  assertTemporalWindowFor(window, { subjectId: spec.id, space: timeline });
   const source = sourceFacts(media);
-  const trimStart = spec.trim.start === undefined ? 0 : temporalDurationInSamples(spec.trim.start, space);
-  const trimEnd = spec.trim.end === undefined ? source.sampleFrames : temporalDurationInSamples(spec.trim.end, space);
+  const trimStart = spec.trim.start === undefined ? 0 : temporalDurationInSamples(spec.trim.start, timeline);
+  const trimEnd = spec.trim.end === undefined ? source.sampleFrames : temporalDurationInSamples(spec.trim.end, timeline);
   assert(trimStart >= 0 && trimStart < source.sampleFrames, `Audio Clip ${spec.id} trim start is outside its source.`);
   assert(trimEnd > trimStart && trimEnd <= source.sampleFrames, `Audio Clip ${spec.id} trim end is outside its source.`);
-  const fadeInSamples = temporalDurationInSamples(spec.mix.fadeIn, space);
-  const fadeOutSamples = temporalDurationInSamples(spec.mix.fadeOut, space);
+  const fadeInSamples = temporalDurationInSamples(spec.mix.fadeIn, timeline);
+  const fadeOutSamples = temporalDurationInSamples(spec.mix.fadeOut, timeline);
   const addition = {
     id: window.id,
     subjectId: spec.id,
@@ -129,12 +125,12 @@ function realizedItems(
 export function appendProjectedAudioItem(
   set: AudioTrackSet,
   header: AudioTrackHeader,
-  space: ProgramSpace,
+  timeline: Timeline,
   media: SynchronizedMedia,
   spec: AudioClipSpec,
   window: ProjectedWindow,
 ): AudioTrackSet {
-  return realizedItems(set, header, space, media, spec, window);
+  return realizedItems(set, header, timeline, media, spec, window);
 }
 
 function normalizeProgram(value: AudioTrackProgram): AudioTrackProgram {
@@ -183,9 +179,9 @@ export function assertAudioTrackProgram(value: AudioTrackProgram): void {
   }
 }
 
-function terminalClip(item: AudioItemProgram, space: ProgramSpace): AudioClip {
-  const windowStart = programFrameSampleBoundary(space, item.window.startFrame, 48_000);
-  const windowEnd = programFrameSampleBoundary(space, item.window.endFrameExclusive, 48_000);
+function terminalClip(item: AudioItemProgram, timeline: Timeline): AudioClip {
+  const windowStart = programFrameSampleBoundary(timeline, item.window.startFrame, 48_000);
+  const windowEnd = programFrameSampleBoundary(timeline, item.window.endFrameExclusive, 48_000);
   const windowLength = windowEnd - windowStart;
   const effectiveLength = item.trim.endSampleExclusive - item.trim.startSample;
   let targetStart = windowStart;
@@ -237,18 +233,18 @@ function terminalClip(item: AudioItemProgram, space: ProgramSpace): AudioClip {
   };
 }
 
-export function renderAudioTrack(space: ProgramSpace, program: AudioTrackProgram): AudioTrack {
-  assertProgramSpaceIdentity(space);
+export function renderAudioTrack(timeline: Timeline, program: AudioTrackProgram): AudioTrack {
+  assertProgramSpaceIdentity(timeline);
   assertAudioTrackProgram(program);
-  const totalSamples = programSpaceSampleFrames(space, 48_000);
+  const totalSamples = programSpaceSampleFrames(timeline, 48_000);
   const track = sealAudioTrack({
-    programSpaceId: space.id,
+    programSpaceId: timeline.id,
     id: program.id,
-    clips: program.items.map((item) => terminalClip(item, space)),
+    clips: program.items.map((item) => terminalClip(item, timeline)),
   });
   for (const clip of track.clips) {
-    assert(clip.target.endSampleExclusive <= totalSamples, `Audio Clip ${clip.id} is outside ProgramSpace.`);
+    assert(clip.target.endSampleExclusive <= totalSamples, `Audio Clip ${clip.id} is outside Timeline.`);
   }
-  assertAudioTrackIdentity(track, space);
+  assertAudioTrackIdentity(track, timeline);
   return track;
 }

package/packages/audio-track/src/surface.ts

@@ -1,4 +1,4 @@
-import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { resolveTemporalContext } from "@hypit/temporal-markup";
 import { mediaTypes } from "@hypit/media";
 import type {
   StructuredElement,
@@ -85,8 +85,10 @@ function numeric(element: StructuredElement, name: string, fallback?: number): n
   return value;
 }
 
+export const audioItemDefaults = { playback: "once", gain: 1, "fade-in": "0f", "fade-out": "0f" } as const;
+
 function occupancy(element: StructuredElement): AudioOccupancy {
-  switch (text(element, "playback", "once")) {
+  switch (text(element, "playback", audioItemDefaults.playback)) {
     case "once":
     case "once-start": return { mode: "once", align: "start" };
     case "once-end": return { mode: "once", align: "end" };
@@ -104,10 +106,9 @@ function occupancy(element: StructuredElement): AudioOccupancy {
 }
 
 export const decodeAudioTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  allowed(element, ["id", "semantic", "space"]);
+  allowed(element, ["id", "timeline"]);
   const id = text(element, "id");
   const context = resolveTemporalContext({ element, resolveReference });
-  const time = createTemporalSpace({ id: id, element, ...context });
   const headerId = `${id}.header`;
   const records: SurfaceRecordDraft[] = [{
     id: headerId,
@@ -115,20 +116,20 @@ export const decodeAudioTrackSurface: StructuredSurfaceHandler = ({ element, res
     value: { kind: "inline", value: sealAudioTrackHeader({ id }) },
     range: element.range,
   }];
-  const temporalComponents: SurfaceComponentDraft[] = [...time.components];
-  const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [...time.fragments];
+  const temporalComponents: SurfaceComponentDraft[] = [];
+  const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];
   const fragmentItems: Parameters<typeof createAudioTrackFragment>[0][number][] = [];
   const inputs: Record<string, { kind: "record"; id: string } | { kind: "component-output"; component: string; output: string }> = {
     header: { kind: "record", id: headerId },
-    space: time.space.ref,
+    timeline: context.timeline.ref,
   };
   let itemIndex = 0;
   for (const child of element.children) {
     if (child.kind === "text") {
-      if (child.value.trim()) throw new Error(`${element.name} accepts only Clip children.`);
+      if (child.value.trim()) throw new Error(`${element.name} accepts only Item children.`);
       continue;
     }
-    if (!child.name.endsWith(":Clip") && child.name !== "Clip") throw new Error(`${element.name} accepts only Clip children.`);
+    if (!child.name.endsWith(":Item") && child.name !== "Item") throw new Error(`${element.name} accepts only Item children.`);
     if (child.children.some((node) => node.kind === "element" || node.value.trim())) throw new Error(`${child.name} must be empty.`);
     allowed(child, [
       "id", "source", ...temporalWindowAttributeNames,
@@ -136,9 +137,9 @@ export const decodeAudioTrackSurface: StructuredSurfaceHandler = ({ element, res
     ]);
     itemIndex += 1;
     const suffix = String(itemIndex).padStart(4, "0");
-    const clipId = optionalText(child, "id") ?? `${id}.clip.${suffix}`;
+    const clipId = optionalText(child, "id") ?? `${id}.item.${suffix}`;
     const source = resolved(child.attributes.source, `${child.name}.source`, mediaTypes.synchronized, resolveReference);
-    const temporal = createTemporalWindowProjection({ id: clipId, element: child, ...context, space: time.space, resolveReference });
+    const temporal = createTemporalWindowProjection({ id: clipId, element: child, ...context, resolveReference });
     records.push(...temporal.records);
     temporalComponents.push(...temporal.components);
     temporalFragments.push(...temporal.fragments);
@@ -155,22 +156,22 @@ export const decodeAudioTrackSurface: StructuredSurfaceHandler = ({ element, res
       },
       occupancy: playback,
       mix: {
-        gain: numeric(child, "gain", 1),
-        fadeIn: duration(text(child, "fade-in", "0f"), `${child.name}.fade-in`),
-        fadeOut: duration(text(child, "fade-out", "0f"), `${child.name}.fade-out`),
+        gain: numeric(child, "gain", audioItemDefaults.gain),
+        fadeIn: duration(text(child, "fade-in", audioItemDefaults["fade-in"]), `${child.name}.fade-in`),
+        fadeOut: duration(text(child, "fade-out", audioItemDefaults["fade-out"]), `${child.name}.fade-out`),
       },
     });
     const windowName = `item-${suffix}-window`;
     inputs[windowName] = temporal.ref;
     const mediaName = `item-${suffix}-media`;
     const specName = `item-${suffix}-spec`;
-    const specId = `${id}.clip.${suffix}.spec`;
+    const specId = `${id}.item.${suffix}.spec`;
     records.push({ id: specId, type: audioTrackTypes.clipSpec, value: { kind: "inline", value: clipSpec }, range: child.range });
     inputs[mediaName] = source.ref;
     inputs[specName] = { kind: "record", id: specId };
     fragmentItems.push({ mediaName, specName, windowName });
   }
-  if (fragmentItems.length === 0) throw new Error(`${element.name} requires at least one Clip.`);
+  if (fragmentItems.length === 0) throw new Error(`${element.name} requires at least one Item.`);
   const fragment = createAudioTrackFragment(fragmentItems);
   return {
     records,
@@ -178,10 +179,10 @@ export const decodeAudioTrackSurface: StructuredSurfaceHandler = ({ element, res
       id,
       fragment: fragment.id,
       inputs,
-      outputs: { program: `${id}.program`, track: `${id}.track` },
+      outputs: { program: `${id}.program`, audio: `${id}.audio` },
       range: element.range,
     }],
     fragments: [...temporalFragments, fragment],
-    exports: [`${id}.program`, `${id}.track`],
+    exports: [`${id}.program`, `${id}.audio`],
   };
 };

package/packages/audio-track-studio/README.md

@@ -1,3 +1,26 @@
 # `@hypit/audio-track-studio`
 
 Hypit Studio Companion for `@hypit/audio-track`. The domain package does not depend on this package.
+
+Each Item has a title and waveform body. An explicit author `id` supplies its
+title; otherwise the Companion displays the exact `source` reference. Display
+names do not replace the Item's identity or writeback endpoint. This is the same
+rule as Media Items. For example, `id="soundtrack" source={music.media}` shows
+`soundtrack`; omitting the id shows `music.media`. Here `.media` is the source
+output port, not an Audio-specific name suffix.
+
+When groups placement, source trim, playback rates and fades. How contains gain.
+Gain displays as a percentage (0–6400%) and writes back as a scalar; duration controls preserve their authored `f`, `ms` or `s` unit.
+Omitted gain and fade defaults remain editable; the first edit writes an explicit
+attribute. Playback uses the standard parameter controls and saves when editing ends. Stretch also
+asks for minimum and maximum rate multipliers (1 means original speed). Switching
+to once/loop removes these bounds in the same edit. The Surface retains final
+validation of positive, ordered rates. No arbitrary bounds are supplied for the author.
+
+The Companion declares a schema-described `attributes` group. Studio provides
+record alternatives, completion hints and grouped source serialization without knowing
+any Audio mode names.
+
+Selecting an overlapping Item raises it in the editing lane while all sounds
+continue to mix. Timing gestures use the same temporal projection bindings as
+Media Track.

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

@@ -1,8 +1,8 @@
-import { audioTrackModuleRef, audioTrackTypes } from "@hypit/audio-track";
+import { audioItemDefaults, audioTrackModuleRef, audioTrackTypes } from "@hypit/audio-track";
 import type { AudioTrackProgram } from "@hypit/audio-track";
 import { compositionTypes } from "@hypit/composition";
 import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft } from "@hypit/studio-adapter";
-import { artifactPreview, childEntities, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
+import { artifactPreview, authoredItemTitle, childEntities, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
 
 function projectAudio(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
   const program = requiredSurfaceValue(context, "program") as AudioTrackProgram;
@@ -21,7 +21,10 @@ function projectAudio(context: StudioTrackCompanionContext): readonly StudioEnti
     const semanticSource = temporalSemanticSource(temporal);
     return {
       ...entity,
-      display: { ...entity.display, layers: [previewLayer(item.preview, "waveform")] },
+      display: {
+        title: authoredItemTitle(context, entity.authoredId, item.sourceTypes, ["source"]),
+        layers: [previewLayer(item.preview, "waveform")],
+      },
       ...(semanticSource?.id === undefined
         ? {}
         : { markerId: semanticSource.id }),
@@ -39,31 +42,42 @@ export const audioTrackStudioTrackCompanions: readonly StudioTrackCompanion[] =
       { name: "source" },
       { name: "trim-start", writable: true },
       { name: "trim-end", writable: true },
-      { name: "playback", writable: true },
-      { name: "min-rate", writable: true },
-      { name: "max-rate", writable: true },
-      { name: "gain", writable: true },
-      { name: "fade-in", writable: true },
-      { name: "fade-out", writable: true },
+      { name: "playback-settings", writable: true,
+        attributes: ["playback", "min-rate", "max-rate"],
+        fallback: { playback: audioItemDefaults.playback },
+        schema: { kind: "oneOf", variants: ["once", "once-start", "once-end", "loop", "loop-start", "loop-end", "stretch"].map(mode => ({
+          kind: "object", fields: {
+            playback: { schema: { kind: "literal", value: mode } },
+            ...(mode === "stretch" ? {
+              "min-rate": { schema: { kind: "number", minimum: 0, maximum: 100 } },
+              "max-rate": { schema: { kind: "number", minimum: 0, maximum: 100 } },
+            } : {}),
+          },
+        })) },
+      },
+      { name: "gain", writable: true, fallback: audioItemDefaults.gain },
+      { name: "fade-in", writable: true, fallback: audioItemDefaults["fade-in"] },
+      { name: "fade-out", writable: true, fallback: audioItemDefaults["fade-out"] },
     ],
     inspector: [
       {
-        binding: "playback", label: "Playback", domain: "how",
+        binding: "playback-settings", 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"],
+        control: "record",
+        summary: "Rates are multipliers (1 = original speed). Stretch requires both rate bounds.",
       },
       ...(["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,
-      })),
-      ...(["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,
+        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 },
       })),
+      { binding: "gain", label: "Gain", domain: "how",
+        page: { id: "mix", label: "Mix" }, section: { id: "mix", label: "Mix" },
+        control: "number", unit: "%", number: { scale: 100, minimum: 0, maximum: 6400, 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/author-kit/README.md

@@ -4,7 +4,7 @@ Small public framework API for an Author Package.
 
 It joins four stable authoring boundaries: nominal Module declarations, deterministic component
 handlers, sealed Graph Fragments and Markup Surface handlers. Domain facts still come from their
-owners—for example `@hypit/composition`, `@hypit/semantic-track` and `@hypit/spatial`. This package
+owners—for example `@hypit/composition`, `@hypit/timeline` and `@hypit/spatial`. This package
 does not re-export the video vocabulary or turn those packages into one central object.
 
 `@hypit/hypit/author-kit` contains no registry, package search, installer, Runtime, Provider or Studio

package/packages/background-removal/README.md

@@ -12,13 +12,10 @@ Use it for a product, portrait or graphic that will be composited over another p
 image Output. `{cutout.image}` publishes one image BlobArtifact with transparency. Keep its actual
 dimensions when placing it in Media Track, or use Image Compose when a flattened still is wanted.
 
-The package declares the visual operation; the selected Endpoint implements it. The existing
-`@hypit/provider-kie` route uses
-[KIE Recraft Remove Background](https://docs.kie.ai/market/recraft/remove-background), sending
-`model: "recraft/remove-background"` and `input.image`. It follows the ordinary submit, poll and
-collect lifecycle and expects one image result. Another Provider can fulfill the same capability
-without changing the Source. This operation therefore needs no separate Recraft-specific author
-Model to use the existing KIE implementation.
+The package declares the visual operation; a project Provider implements the capability
+`@hypit/background-removal@1#remove-background`, accepting `{ source: BlobRef }` and returning one
+image BlobRef with transparency. The Provider owns its service's request mapping and task lifecycle.
+A service-specific author Model is unnecessary when the operation has this same meaning.
 
 For a moving portrait, [Volcengine Matting](../volcengine-matting/README.md) provides
 `<matte:Portrait source={performance.video}/>` through HypiHub. Normalize its processed video

package/packages/browser-capture/package.json

@@ -10,6 +10,6 @@
   "dependencies": {
     "@puppeteer/browsers": "3.2.2",
     "puppeteer-core": "25.10.0",
-    "sharp": "0.35.3"
+    "sharp": "0.35.4"
   }
 }

package/packages/build-result/README.md

@@ -0,0 +1,69 @@
+# `@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.
+
+## Execution evidence
+
+A finished manifest may contain `executionLog`, an ordinary Result file reference separate from
+`outputs`. `BuildResultWriter.finish({ executionLog, outcome, ... })` accepts a byte stream. Repositories
+preserve it as `execution.jsonl` before the terminal manifest is published. The filesystem and S3
+implementations use the same interface. Repeating an already completed finish does not rewrite it.
+
+This file describes how the Build ran; it is neither an authored Output nor a gallery asset. Consumers
+read it with `openFile(build, manifest.executionLog)`. Its absence means no log was recorded, including
+Results made before logging was available; readers do not reconstruct history from other projects.

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;
@@ -206,6 +202,7 @@ export function decodeBuildResultManifest(
     throw new Error(`${subject} must be either unfinished or have both outcome and finishedAt`);
   }
   const failure = optionalString(item.failure, `${subject}.failure`);
+  if (item.executionLog !== undefined) assertBuildResultFileRef(item.executionLog, `${subject}.executionLog`);
   return {
     format: "hypit.build-result@1",
     id,
@@ -219,6 +216,7 @@ export function decodeBuildResultManifest(
     ...(outcome === undefined ? {} : { outcome }),
     ...(failure === undefined ? {} : { failure }),
     outputs: outputs(item.outputs, `${subject}.outputs`),
+    ...(item.executionLog === undefined ? {} : { executionLog: item.executionLog }),
     ...(item.operations === undefined ? {} : { operations: operationReceipts(item.operations, `${subject}.operations`) }),
   };
 }
@@ -255,7 +253,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 +268,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/execution-log.ts

@@ -0,0 +1,17 @@
+import type { BuildResultFileRef } from "./types.js";
+
+/** Execution evidence is a Result file, not an authored Output or generated asset. */
+export async function preserveExecutionLog(
+  chunks: AsyncIterable<Uint8Array> | undefined,
+  write: (path: string, chunks: AsyncIterable<Uint8Array>, mediaType: string) => Promise<void>,
+): Promise<BuildResultFileRef | undefined> {
+  if (chunks === undefined) return undefined;
+  let size = 0;
+  const counted = (async function* () {
+    for await (const chunk of chunks) { size += chunk.byteLength; yield chunk; }
+  })();
+  const path = "execution.jsonl";
+  const mediaType = "application/x-ndjson";
+  await write(path, counted, mediaType);
+  return { kind: "build-file", path, size, mediaType };
+}