@hypit/hypit 0.1.4 → 0.1.6

package/packages/sound/src/index.ts

@@ -0,0 +1,5 @@
+export * from "./style.js";
+export * from "./program.js";
+export * from "./component.js";
+export * from "./surface.js";
+export * from "./manifest.js";

package/packages/sound/src/manifest.ts

@@ -0,0 +1,47 @@
+import { compositionDependency, compositionTypes } from "@hypit/composition";
+import { timelineDependency, timelineTypes } from "@hypit/timeline";
+import { temporalDependency, temporalTypes } from "@hypit/temporal";
+import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
+import type { ModuleManifest, ProducerRef, TypeRef } from "@hypit/protocol";
+
+export const soundModuleRef = { name: "@hypit/sound", version: "1" } as const;
+export const soundTypes = Object.fromEntries(["Style", "Set", "Header", "Gain"].map(name => [name.toLowerCase(), { module: soundModuleRef, name: `Sound${name}` }])) as Record<"style" | "set" | "header" | "gain", TypeRef>;
+export const soundProducers = Object.fromEntries(["create", "append", "resolve", "ordinary"].map(name => [name, { module: soundModuleRef, name }])) as Record<"create" | "append" | "resolve" | "ordinary", ProducerRef>;
+export const ordinaryInputs = [
+  { name: "timeline", type: timelineTypes.track }, { name: "window", type: temporalTypes.window },
+  { name: "spec", type: soundTypes.gain },
+];
+export const soundManifest: ModuleManifest = {
+  format: "hypit.module@1", ...soundModuleRef,
+  dependencies: [compositionDependency, timelineDependency, temporalDependency],
+  types: Object.values(soundTypes).map(type => ({ name: type.name })), capabilities: [],
+  producers: [
+    { name: "create", inputs: [], outputs: [{ name: "set", type: soundTypes.set }], needs: [] },
+    { name: "append", inputs: [{ name: "set", type: soundTypes.set }, { name: "window", type: temporalTypes.window }, { name: "audio", type: compositionTypes.audioTrack }], outputs: [{ name: "set", type: soundTypes.set }], needs: [] },
+    { name: "resolve", inputs: [{ name: "set", type: soundTypes.set }, { name: "timeline", type: timelineTypes.track }, { name: "header", type: soundTypes.header }], outputs: [{ name: "audio", type: compositionTypes.audioTrack }], needs: [] },
+    { name: "ordinary", inputs: ordinaryInputs, outputs: [{ name: "audio", type: compositionTypes.audioTrack }], needs: [] },
+  ],
+};
+export const soundMarkupSurfaces = [
+  { name: "style", tag: "Style", mode: "structured", outputs: [soundTypes.style, soundTypes.gain], vocabulary: {
+    summary: "Presents existing Timeline sound, choosing the last declared active audio source. Gain may change linearly across each Use.",
+    example: `<sound:Style id="fade-in" gain="0" end-gain="1"/>`,
+    attributes: [
+      { name: "id", kind: "identifier", required: true, summary: "Style name." },
+      { name: "gain", kind: "literal", required: false, summary: "Linear gain at the beginning of a Use; defaults to 1. Zero silences the presentation." },
+      { name: "end-gain", kind: "literal", required: false, summary: "Linear gain at the end of a Use; defaults to gain. The original Use interval owns the ramp." },
+    ],
+  } },
+  { name: "track", tag: "Track", mode: "structured", outputs: [compositionTypes.audioTrack, soundTypes.set, soundTypes.header, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window], vocabulary: {
+    summary: "Presents Timeline sound through ordered Uses. Later Uses replace earlier presentation locally without restarting source playback or gain curves.",
+    example: `<sound:Track id="voice" timeline={program.timeline}><sound:Use style={normal}/><sound:Use at="0f" for="2s" style={fade-in}/></sound:Track>`,
+    attributes: [
+      { name: "id", kind: "identifier", required: true, summary: "Sound presentation name." },
+      { name: "timeline", kind: "reference", required: true, accepts: [timelineTypes.track], summary: "Complete film time and placed sources." },
+    ], children: [{ tag: "Use", cardinality: "many", summary: "Last matching Use wins, including silence. No time selector covers the complete Timeline.", attributes: [
+      { name: "id", kind: "identifier", required: false, summary: "Optional occurrence identity." },
+      { name: "style", kind: "reference", required: true, accepts: [soundTypes.style], summary: "Ordinary or project-authored sound Style. Explicit source bindings belong to the Style." },
+      ...temporalWindowAttributeVocabulary,
+    ] }],
+  } },
+] as const;

package/packages/sound/src/program.ts

@@ -0,0 +1,84 @@
+import { sealAudioTrack, assertAudioTrackIdentity } from "@hypit/composition";
+import type { AudioTrack, AudioClip, AudioSampleSpan, AudioGainPoint } from "@hypit/composition";
+import { assertTemporalWindowFor } from "@hypit/temporal";
+import type { TemporalWindow } from "@hypit/temporal";
+import { projectTimelineAudio } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
+import type { NarrativeExcerpt } from "@hypit/narrative";
+import { programFrameSampleBoundary } from "@hypit/program-space";
+
+export type SoundUse = { readonly window: TemporalWindow; readonly audio: AudioTrack };
+export type SoundSet = { readonly uses: readonly SoundUse[] };
+export type SoundGain = { readonly gain: number; readonly endGain: number };
+
+export function soundWindow(timeline: Timeline, window: TemporalWindow): AudioSampleSpan {
+  assertTemporalWindowFor(window, { subjectId: window.subjectId, space: timeline });
+  return { startSample: programFrameSampleBoundary(timeline, window.span.startFrame, 48000),
+    endSampleExclusive: programFrameSampleBoundary(timeline, window.span.endFrameExclusive, 48000) };
+}
+export function intersectAudioSpans(left: readonly AudioSampleSpan[], right: readonly AudioSampleSpan[]): AudioSampleSpan[] {
+  return left.flatMap(a => right.flatMap(b => {
+    const startSample = Math.max(a.startSample, b.startSample), endSampleExclusive = Math.min(a.endSampleExclusive, b.endSampleExclusive);
+    return endSampleExclusive > startSample ? [{ startSample, endSampleExclusive }] : [];
+  }));
+}
+function subtract(spans: readonly AudioSampleSpan[], cut: AudioSampleSpan): AudioSampleSpan[] {
+  return spans.flatMap(span => {
+    if (cut.endSampleExclusive <= span.startSample || cut.startSample >= span.endSampleExclusive) return [span];
+    return [
+      ...(cut.startSample > span.startSample ? [{ startSample: span.startSample, endSampleExclusive: cut.startSample }] : []),
+      ...(cut.endSampleExclusive < span.endSampleExclusive ? [{ startSample: cut.endSampleExclusive, endSampleExclusive: span.endSampleExclusive }] : []),
+    ];
+  });
+}
+function envelope(span: AudioSampleSpan, gain: SoundGain): readonly AudioGainPoint[] {
+  if (![gain.gain, gain.endGain].every(value => Number.isFinite(value) && value >= 0 && value <= 64)) throw new Error("Sound gain must be from 0 to 64.");
+  return [{ sample: span.startSample, gain: gain.gain }, { sample: span.endSampleExclusive, gain: gain.endGain }];
+}
+const unity = { gain: 1, endGain: 1 };
+
+/** Default source choice is declaration order, independently of the order of Use rules. */
+export function ordinarySound(timeline: Timeline, window: TemporalWindow, gain: SoundGain = unity): AudioTrack {
+  const span = soundWindow(timeline, window), gainEnvelope = envelope(span, gain);
+  const sources = new Map(projectTimelineAudio(timeline).clips.map(clip => [clip.id, clip]));
+  const clips = timeline.items.flatMap(item => { const clip = sources.get(item.take.segment.segmentId); return clip ? [clip] : []; });
+  const result: AudioClip[] = [];
+  for (const [index, clip] of clips.entries()) {
+    let audibility = intersectAudioSpans([span], [clip.target]);
+    for (const later of clips.slice(index + 1)) audibility = subtract(audibility, later.target);
+    if (audibility.length && (gain.gain !== 0 || gain.endGain !== 0)) result.push({ ...clip, gainEnvelope, audibility });
+  }
+  return sealAudioTrack({ id: window.subjectId, programSpaceId: timeline.id, clips: result });
+}
+
+/** Explicit source selection for project Styles, with its original placement/sampling retained. */
+export function sourceSound(timeline: Timeline, window: TemporalWindow, segment: NarrativeExcerpt, gain: SoundGain = unity): AudioTrack {
+  if (segment.kind !== "segment" || segment.narrativeId !== timeline.narrativeId) throw new Error("Sound source must be a Segment of this Timeline's Narrative.");
+  if (!timeline.items.some(item => item.take.segment.segmentId === segment.id)) throw new Error(`Unknown Sound Segment ${segment.id}.`);
+  const span = soundWindow(timeline, window), gainEnvelope = envelope(span, gain);
+  const clip = projectTimelineAudio(timeline).clips.find(clip => clip.id === segment.id);
+  const audibility = clip ? intersectAudioSpans([span], [clip.target]) : [];
+  return sealAudioTrack({ id: `${window.subjectId}:${segment.id}`, programSpaceId: timeline.id,
+    clips: clip && audibility.length && (gain.gain !== 0 || gain.endGain !== 0) ? [{ ...clip, gainEnvelope, audibility }] : [] });
+}
+export function appendSoundUse(set: SoundSet, window: TemporalWindow, audio: AudioTrack): SoundSet {
+  assertAudioTrackIdentity(audio);
+  if (audio.programSpaceId !== window.start.source.spaceId) throw new Error("Sound Use and audio belong to different Timelines.");
+  return { uses: [...set.uses, { window, audio }] };
+}
+/** Resolve presentation coverage without changing original targets, source clocks or envelopes. */
+export function resolveSound(timeline: Timeline, id: string, set: SoundSet): AudioTrack {
+  const windows = set.uses.map(use => { assertAudioTrackIdentity(use.audio, timeline); return soundWindow(timeline, use.window); });
+  const clips: AudioClip[] = [];
+  for (const [index, use] of set.uses.entries()) {
+    let active = [windows[index]!];
+    for (const cut of windows.slice(index + 1)) active = subtract(active, cut);
+    for (const clip of use.audio.clips) {
+      const audibility = intersectAudioSpans(active, clip.audibility ?? [clip.target]);
+      if (audibility.length) clips.push({ ...clip, id: `${index + 1}:${clip.id}`, audibility });
+    }
+  }
+  const result = sealAudioTrack({ id, programSpaceId: timeline.id, clips });
+  assertAudioTrackIdentity(result, timeline);
+  return result;
+}

package/packages/sound/src/style.ts

@@ -0,0 +1,34 @@
+import { sealGraphFragment } from "@hypit/elaborator";
+import type { GraphFragment } from "@hypit/elaborator";
+import { compositionTypes } from "@hypit/composition";
+import { timelineTypes } from "@hypit/timeline";
+import { temporalTypes } from "@hypit/temporal";
+import { sameType } from "@hypit/protocol";
+import type { SurfaceResolvedReference } from "@hypit/markup";
+
+/** Author-time closure: bound references become ordinary graph edges at each Use. */
+export type SoundStyle = {
+  readonly fragment: GraphFragment;
+  readonly bindings: Readonly<Record<string, { readonly type: SurfaceResolvedReference["type"]; readonly ref: SurfaceResolvedReference["ref"] }>>;
+};
+export function soundStyle(fragment: GraphFragment, bindings: SoundStyle["bindings"] = {}): SoundStyle {
+  fragment = sealGraphFragment(fragment);
+  const common = { timeline: timelineTypes.track, window: temporalTypes.window };
+  for (const [name, type] of Object.entries(common)) {
+    const port = fragment.inputs.find(port => port.name === name);
+    if (port === undefined || !sameType(port.type, type)) throw new Error(`Sound Style requires ${name} input.`);
+    if (bindings[name] !== undefined) throw new Error(`Sound supplies ${name} at each Use.`);
+  }
+  for (const port of fragment.inputs) {
+    if (port.name in common) continue;
+    const binding = bindings[port.name];
+    if (binding === undefined || !sameType(port.type, binding.type)) throw new Error(`Sound Style binding ${port.name} has the wrong Type.`);
+  }
+  for (const name of Object.keys(bindings)) {
+    if (!fragment.inputs.some(port => port.name === name)) throw new Error(`Sound Style has unknown binding ${name}.`);
+  }
+  if (fragment.exports.length !== 1 || fragment.exports[0]?.name !== "audio" || !sameType(fragment.exports[0].type, compositionTypes.audioTrack)) {
+    throw new Error("Sound Style must export audio: AudioTrack.");
+  }
+  return { fragment, bindings: Object.fromEntries(Object.entries(bindings).map(([name, value]) => [name, { ref: value.ref, type: value.type }])) };
+}

package/packages/sound/src/surface.ts

@@ -0,0 +1,90 @@
+import { assertAttributes, assertEmptyElement, textAttribute, optionalTextAttribute } from "@hypit/markup";
+import type { StructuredSurfaceHandler, SurfaceResolvedReference, SurfaceRecordDraft, SurfaceComponentDraft, StructuredElement } from "@hypit/markup";
+import { canonicalize, sameType } from "@hypit/protocol";
+import type { TypeRef } from "@hypit/protocol";
+import { sealGraphFragment } from "@hypit/elaborator";
+import type { FragmentOperation } from "@hypit/elaborator";
+import { createTemporalWindowProjection, resolveTemporalContext, temporalWindowAttributeNames } from "@hypit/temporal-markup";
+import { temporalTypes } from "@hypit/temporal";
+import { compositionTypes } from "@hypit/composition";
+import { timelineTypes } from "@hypit/timeline";
+import { soundStyle } from "./style.js";
+import type { SoundStyle } from "./style.js";
+import { soundTypes, soundProducers, ordinaryInputs } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+function reference(element: StructuredElement, name: string, type: TypeRef, resolve: (path: string) => SurfaceResolvedReference | undefined): SurfaceResolvedReference {
+  const raw = element.attributes[name];
+  if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${element.name}.${name} must be a reference.`);
+  const found = resolve(raw.path);
+  if (found === undefined || !sameType(found.type, type)) throw new Error(`${element.name}.${name} has the wrong Type.`);
+  return found;
+}
+function authored<T>(value: SurfaceResolvedReference): T {
+  if (value.record?.value.kind !== "inline") throw new Error("A presentation Style or Recipe must be an authored inline value.");
+  return value.record.value.value as unknown as T;
+}
+export const decodeSoundTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  assertAttributes(element, ["id", "timeline"]);
+  const id = textAttribute(element, "id"), context = resolveTemporalContext({ element, resolveReference });
+  const records: SurfaceRecordDraft[] = [{ id: `${id}.header`, type: soundTypes.header, value: { kind: "inline", value: { id } }, range: element.range }];
+  const components: SurfaceComponentDraft[] = [];
+  const fragments = [] as ReturnType<typeof sealGraphFragment>[];
+  const collectorInputs = [{ name: "timeline", type: timelineTypes.track }, { name: "header", type: soundTypes.header }];
+  const bindings: Record<string, SurfaceResolvedReference["ref"]> = { timeline: context.timeline.ref, header: { kind: "record", id: `${id}.header` } };
+  const operations: FragmentOperation[] = [{ id: "empty", producer: soundProducers.create, inputs: {}, result: { kind: "output", name: "set" } }];
+  let previous = "empty", index = 0;
+  for (const child of element.children) {
+    if (child.kind === "text") { if (child.value.trim()) throw new Error("Sound Track accepts Use children."); continue; }
+    if (child.name.split(":").at(-1) !== "Use") throw new Error("Sound Track accepts Use children.");
+    assertAttributes(child, ["id", "style", ...temporalWindowAttributeNames]); assertEmptyElement(child);
+    const useId = optionalTextAttribute(child, "id") ?? `${id}.use.${index + 1}`;
+    index += 1;
+    const hasTime = temporalWindowAttributeNames.some(name => child.attributes[name] !== undefined);
+    const temporal = createTemporalWindowProjection({ id: useId, ...context, resolveReference,
+      element: hasTime ? child : { ...child, attributes: { ...child.attributes, during: "program" } } });
+    records.push(...temporal.records); components.push(...temporal.components); fragments.push(...temporal.fragments);
+    const value = authored<SoundStyle>(reference(child, "style", soundTypes.style, resolveReference));
+    const style = soundStyle(value.fragment, value.bindings);
+    fragments.push(style.fragment);
+    const audioId = `${useId}.audio`;
+    components.push({ id: `${useId}.__style`, fragment: style.fragment.id,
+      inputs: { ...Object.fromEntries(Object.entries(style.bindings).map(([key, bound]) => [key, bound.ref])),
+        timeline: context.timeline.ref, window: temporal.ref }, outputs: { audio: audioId }, range: child.range });
+    const suffix = `use-${operations.length}`;
+    collectorInputs.push({ name: `${suffix}-window`, type: temporalTypes.window }, { name: `${suffix}-audio`, type: compositionTypes.audioTrack });
+    bindings[`${suffix}-window`] = temporal.ref; bindings[`${suffix}-audio`] = { kind: "component-output", component: `${useId}.__style`, output: "audio" };
+    operations.push({ id: suffix, producer: soundProducers.append, inputs: { set: operation(previous), window: input(`${suffix}-window`), audio: input(`${suffix}-audio`) }, result: { kind: "output", name: "set" } });
+    previous = suffix;
+  }
+  operations.push({ id: "resolve", producer: soundProducers.resolve, inputs: { set: operation(previous), timeline: input("timeline"), header: input("header") }, result: { kind: "output", name: "audio" } });
+  const collector = sealGraphFragment({ inputs: collectorInputs, operations, exports: [{ name: "audio", type: compositionTypes.audioTrack, root: operation("resolve") }, { name: "program", type: soundTypes.set, root: operation(previous) }] });
+  fragments.push(collector);
+  components.push({ id, fragment: collector.id, inputs: bindings, outputs: { audio: `${id}.audio`, program: `${id}.program` }, range: element.range });
+  return { records, components, fragments, exports: [`${id}.audio`, `${id}.program`] };
+};
+
+export const ordinarySoundFragment = sealGraphFragment({
+  inputs: ordinaryInputs,
+  operations: [{ id: "ordinary", producer: soundProducers.ordinary,
+    inputs: Object.fromEntries(ordinaryInputs.map(port => [port.name, input(port.name)])), result: { kind: "output", name: "audio" } }],
+  exports: [{ name: "audio", type: compositionTypes.audioTrack, root: operation("ordinary") }],
+});
+export const decodeSoundStyleSurface: StructuredSurfaceHandler = ({ element }) => {
+  assertAttributes(element, ["id", "gain", "end-gain"]); assertEmptyElement(element);
+  const id = textAttribute(element, "id");
+  const number = (name: string, fallback: number): number => {
+    const raw = optionalTextAttribute(element, name);
+    const value = raw === undefined ? fallback : raw.trim() === "" ? NaN : Number(raw);
+    if (!Number.isFinite(value) || value < 0 || value > 64) throw new Error(`Sound Style ${name} must be a gain from 0 to 64.`);
+    return value;
+  };
+  const gain = number("gain", 1), endGain = number("end-gain", gain);
+  const specId = `${id}.gain`;
+  const style = soundStyle(ordinarySoundFragment, { spec: { ref: { kind: "record", id: specId }, type: soundTypes.gain } });
+  return { records: [
+    { id: specId, type: soundTypes.gain, value: { kind: "inline", value: { gain, endGain } }, range: element.range },
+    { id, type: soundTypes.style, value: { kind: "inline", value: canonicalize(style) }, range: element.range },
+  ], components: [], fragments: [] };
+};

package/packages/sound-studio/README.md

@@ -0,0 +1,22 @@
+# Sound Studio Companion
+
+Sound contributes one Track with content and a bottom Uses band through the public Companion interface:
+
+- The content lane shows placed audio Takes with waveforms. Each Take retains its actual interval, including gaps and overlaps. Picture-only Takes contribute no sound item.
+- The Uses label band shows each authored Style application. Later declarations appear over earlier ones; selection raises an item for editing without changing that priority. Silent and fully covered Uses remain selectable.
+
+One Sound label spans the waveform content and Uses band. Selecting a Take shows its Segment and placed frame range.
+Selecting a Use shows its Style and resolved frame range, alongside the ordinary Style's authored
+`gain` and `end-gain` parameters. Gain is displayed as a percentage: 100% writes the linear value 1.
+The end gain defaults to the start gain. The parameter Companion exposes this dependent default;
+the first edit inserts an explicit attribute into the Style.
+
+The fields live in When and How. Shared Style edits affect all Uses selecting that Style.
+Temporal gestures follow the existing Selection/Moment/clock projection and exact source endpoint
+rules. Project Styles expose their own parameters through `createStudioCompanionHostFacet({ parameters })`,
+matching their own Module and Surface. The Track opts `style` into this owner with `companion: true`.
+
+`Sound Track.program` exports the already-computed ordered Use set before presentation coverage
+is resolved. `Sound Track.audio` exports the effective audio arrangement. The Companion reads the
+former to preserve editing choices even when they currently produce no sound; rendering consumes
+the latter. Studio does not reconstruct the rule set from audible output or inspect Sound internals.

package/packages/sound-studio/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@hypit/sound-studio",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/timeline": "workspace:*",
+    "@hypit/temporal": "workspace:*",
+    "@hypit/composition": "workspace:*",
+    "@hypit/studio-adapter": "workspace:*",
+    "@hypit/sound": "workspace:*"
+  }
+}

package/packages/sound-studio/src/activation.ts

@@ -0,0 +1,6 @@
+import { createStudioCompanionHostFacet } from "@hypit/studio-adapter";
+import { soundStudioTrackCompanions, soundStudioParameterCompanions } from "./index.js";
+export default {
+  format: "hypit.node-package@1" as const,
+  hostFacets: [createStudioCompanionHostFacet({ tracks: soundStudioTrackCompanions, parameters: soundStudioParameterCompanions })],
+};

package/packages/sound-studio/src/index.ts

@@ -0,0 +1,74 @@
+import { soundModuleRef } from "@hypit/sound";
+import type { SoundSet } from "@hypit/sound";
+import { projectTimelineMedia, timelineTypes } from "@hypit/timeline";
+import type { Timeline } from "@hypit/timeline";
+import { temporalTypes } from "@hypit/temporal";
+import { compositionTypes } from "@hypit/composition";
+import { artifactPreview, authoredChildFor, previewLayer, requiredReferencedValue, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
+import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft } from "@hypit/studio-adapter";
+
+export function projectSound(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+  const timeline = requiredReferencedValue(context, "timeline", timelineTypes.track) as Timeline;
+  const program = requiredSurfaceValue(context, "program") as SoundSet;
+  // Source content keeps its own placement. A Use changes its presentation, not its media clock.
+  const content: StudioEntityDraft[] = projectTimelineMedia(timeline).flatMap((clip, index) => {
+    if (clip.media.audio === undefined) return [];
+    return [{
+      id: `${context.track.outputRef}:content:${clip.segmentId}`,
+      authoredId: clip.segmentId,
+      display: { title: clip.segmentId, layers: [previewLayer(artifactPreview("audio", clip.media.audio.artifact.resource), "waveform")] },
+      ...clip.span, stackOrder: index,
+      inspector: [
+        { id: "segment", label: "Segment", domain: "how", section: { id: "content", label: "Content" }, value: clip.segmentId },
+        { id: "range", label: "Range", domain: "when", section: { id: "placement", label: "Placement" }, value: `${clip.span.startFrame}–${clip.span.endFrameExclusive}`, unit: "f", summary: "Placed interval; the end frame is exclusive." },
+      ],
+      presentation: { entity: "sound-content", chrome: "standard" },
+    }];
+  });
+  const uses: StudioEntityDraft[] = program.uses.map((use, index) => {
+    const authoredId = use.window.subjectId;
+    const child = authoredChildFor(context, authoredId, [temporalTypes.windowSpec]);
+    if (child === undefined) throw new Error(`Sound Use ${authoredId} has no author provenance.`);
+    const style = child.referenceAttributes.style;
+    const temporal = temporalLineageFor(context, authoredId, "window");
+    const semantic = temporalSemanticSource(temporal);
+    return {
+      id: `${context.track.outputRef}:use:${authoredId}`, authoredId,
+      display: { title: style ?? authoredId, layers: [] },
+      ...use.window.span, stackOrder: index,
+      elementRange: child.range,
+      ...(temporal === undefined ? {} : { temporal }),
+      ...(semantic === undefined ? {} : { markerId: semantic.id }),
+      presentation: { entity: "sound-use", chrome: "standard" },
+      band: "uses",
+      inspector: [{ id: "range", label: "Range", domain: "when", section: { id: "placement", label: "Placement" }, value: `${use.window.span.startFrame}–${use.window.span.endFrameExclusive}`, unit: "f", summary: "Resolved Use interval; the end frame is exclusive. Timeline gestures follow this Use's author timing." }],
+    };
+  });
+  return [...content, ...uses];
+}
+
+export const soundStudioTrackCompanions: readonly StudioTrackCompanion[] = [{
+  id: "audio", role: "track",
+  output: { type: compositionTypes.audioTrack, surface: "track", modules: [soundModuleRef] },
+  family: "sound", label: "Sound", tone: "green", icon: "waveform",
+  lane: { heightPx: 48 },
+  requiredValues: ["program"],
+  bands: [{
+    id: "uses", placement: "after", heightPx: 15, display: "label",
+    bindings: [{ name: "style", companion: true }],
+    inspector: [{ binding: "style", label: "Style", domain: "how", section: { id: "sound", label: "Sound" }, control: "text", summary: "This Style is shared by every Use that selects it." }],
+  }],
+  project: projectSound,
+}];
+
+export const soundStudioParameterCompanions: readonly import("@hypit/studio-adapter").StudioParameterCompanion[] = [{
+  id: "style", match: { module: soundModuleRef, surface: "style" },
+  bindings: [ { name: "gain", writable: true, fallback: 1 },
+    { name: "end-gain", writable: true, fallback: authored => Number(authored.gain ?? 1) } ],
+  inspector: (["gain", "end-gain"] as const).map(name => ({
+    binding: name, label: name === "gain" ? "Gain" : "End Gain", domain: "how",
+    section: { id: "sound", label: "Sound" }, control: "number", unit: "%",
+    number: { scale: 100, minimum: 0, maximum: 6400, step: 1 },
+    summary: name === "gain" ? "Linear gain at the start of each Use. 100% preserves the source level." : "Linear gain at the end of each Use. The Use interval owns the ramp.",
+  })),
+}];

package/packages/speech/README.md

@@ -6,8 +6,8 @@ owns the types and helpers below; Source imports retain the `@hypit/speech@1` Mo
 
 Public contracts for speech duration, normalized semantic Takes and provider-neutral evidence audio.
 A `SemanticTake` contains one normalized media product, one authored Segment, its words and local
-frame anchors. Ordered Takes are assembled by `@hypit/speech-track` into a `SemanticTrack`, which is
-the program's continuous semantic skeleton. `SpeechEvidenceAudio` carries canonical 16 kHz WAV bytes
+frame anchors. Ordered Takes are assembled by `@hypit/timeline-author` into a `Timeline`, which is
+the complete Program range and Take placements, including gaps or overlap. `SpeechEvidenceAudio` carries canonical 16 kHz WAV bytes
 and their exact sample count; it never carries Script or Segment identity.
 
 The package also owns deterministic boundary materialization for a Segment with no Tokens. It maps

package/packages/speech-alignment/src/local.ts

@@ -16,8 +16,16 @@ function segmentNarrative(narrative: Narrative, excerpt: NarrativeExcerpt): Narr
     throw new Error(`NarrativeExcerpt ${excerpt.id} does not describe its authored Segment.`);
   }
   const tokens = narrative.tokens.slice(segment.tokenStart, segment.tokenEndExclusive);
+  const units = narrative.caption.units.filter((unit) => unit.segmentId === segment.id);
+  const unitIds = new Set(units.map((unit) => unit.id));
   return {
     id: narrative.id,
+    caption: {
+      ...narrative.caption,
+      units,
+      words: narrative.caption.words.filter((word) => unitIds.has(word.unitId)),
+      cueBreaks: narrative.caption.cueBreaks.filter((cue) => unitIds.has(cue.afterUnitId)),
+    },
     segments: [{ ...segment, tokenStart: 0, tokenEndExclusive: tokens.length }],
     tokens,
     turns: narrative.turns

package/packages/speech-alignment/src/locate.ts

@@ -456,7 +456,7 @@ export function locateAlignedSegmentTiming(
   const tokensById = new Map(timedTokens.map((token) => [token.tokenId, token]));
   const segmentsById = new Map(timedSegments.map((segment) => [segment.segmentId, segment]));
   const anchors: LocalSemanticTimePoint[] = narrative.semanticIndex.anchors.flatMap((anchor): LocalSemanticTimePoint[] => {
-    // Program boundaries belong to the assembled SemanticTrack, never to one Segment-local Take.
+    // Program boundaries belong to the assembled Timeline, never to one Segment-local Take.
     if (anchor.kind === "program-start" || anchor.kind === "program-end") return [];
     if (anchor.kind === "segment-start" || anchor.kind === "segment-end") {
       const segment = segmentsById.get(anchor.segmentId)!;

package/packages/store-sqlite/README.md

@@ -12,3 +12,10 @@ has recorded them. Unknown remote outcomes do not keep a failed Build active.
 Artifact bytes and secret credential values never enter this database. Components and Endpoint packages do not import
 SQLite. `SqliteRuntimeState` exposes the narrow stores needed by the local Runtime and owns their shared
 connection.
+
+Execution choices live in `context_json` on the existing submission/execution records. The store treats
+that value as opaque Host data. `started_at` distinguishes queued work from an executor that was lost.
+`listUnstarted` and `listReady` return only IDs for dispatch, without parsing every Profile or graph.
+Scoped claims and shared capacity updates remain atomic across execution contexts and processes. No global Profile
+pin prevents a new Build from using new selections. An interrupted executor is concluded only after
+its supervisor knows the process has exited; stored Operation receipts are retained for Result writing.