@hypit/hypit 0.1.4 → 0.1.5

package/packages/script-studio/src/projection.ts

@@ -0,0 +1,105 @@
+import { narrativeTypes } from "@hypit/narrative";
+import { sameType } from "@hypit/protocol";
+import type { StudioScriptProjectionInput, StudioScriptProjection } from "@hypit/studio-adapter";
+
+type NarrativeValue = {
+  readonly id?: string;
+  readonly segments?: readonly {
+    readonly id: string;
+    readonly startAnchorId: string;
+    readonly endAnchorId: string;
+  }[];
+  readonly tokens?: readonly {
+    readonly id: string;
+    readonly segmentId: string;
+    readonly startAnchorId: string;
+    readonly endAnchorId: string;
+    readonly text: string;
+  }[];
+  readonly selections?: readonly {
+    readonly id: string;
+    readonly startAnchorId: string;
+    readonly endAnchorId: string;
+  }[];
+  readonly moments?: readonly {
+    readonly id: string;
+    readonly anchorId: string;
+  }[];
+  readonly semanticIndex?: {
+    readonly anchors?: readonly {
+      readonly id: string;
+      readonly kind: "program-start" | "segment-start" | "segment-end" | "token-start" | "token-end" | "program-end";
+      readonly segmentId?: string;
+      readonly tokenId?: string;
+    }[];
+  };
+};
+
+export function projectScriptTimeline(input: StudioScriptProjectionInput): StudioScriptProjection {
+  const records = input.values.filter((item) =>
+    sameType(item.type, narrativeTypes.narrative)
+    && (item.value as NarrativeValue).id === input.source.narrativeId);
+  if (records.length > 1) {
+    throw new Error(`Studio Narrative id ${input.source.narrativeId} resolves to more than one authored value.`);
+  }
+  const record = records[0];
+  const narrative = record?.value as NarrativeValue | undefined;
+  if (narrative === undefined) throw new Error("Studio Narrative is not an inline authored value.");
+
+  const segmentRanges = new Map((input.source.segments ?? []).map((item) => [item.id, item.range]));
+  const tokenRanges = new Map((input.source.tokens ?? []).map((item) => [item.id, item.range]));
+  const frame = (id: string): number | undefined => input.anchors.get(id);
+
+  const segments = (narrative.segments ?? []).flatMap((segment) => {
+    const startFrame = frame(segment.startAnchorId);
+    const endFrame = frame(segment.endAnchorId);
+    if (startFrame === undefined || endFrame === undefined) return [];
+    return [{
+      id: segment.id,
+      startFrame,
+      endFrameExclusive: Math.max(startFrame + 1, endFrame),
+      ...(segmentRanges.has(segment.id) ? { range: segmentRanges.get(segment.id)! } : {}),
+    }];
+  });
+  const tokens = (narrative.tokens ?? []).flatMap((token) => {
+    const startFrame = frame(token.startAnchorId);
+    const endFrame = frame(token.endAnchorId);
+    if (startFrame === undefined || endFrame === undefined) return [];
+    return [{
+      id: token.id,
+      segmentId: token.segmentId,
+      text: token.text,
+      startFrame,
+      endFrameExclusive: Math.max(startFrame + 1, endFrame),
+      ...(tokenRanges.has(token.id) ? { range: tokenRanges.get(token.id)! } : {}),
+    }];
+  });
+  const anchors = (narrative.semanticIndex?.anchors ?? []).flatMap((anchor) => {
+    const at = frame(anchor.id);
+    if (at === undefined) return [];
+    return [{
+      id: anchor.id,
+      kind: anchor.kind,
+      frame: at,
+      ...(anchor.segmentId === undefined ? {} : { segmentId: anchor.segmentId }),
+      ...(anchor.tokenId === undefined ? {} : { tokenId: anchor.tokenId }),
+    }];
+  });
+  const selections = (narrative.selections ?? []).flatMap((selection) => {
+    const startFrame = frame(selection.startAnchorId);
+    const endFrameExclusive = frame(selection.endAnchorId);
+    if (startFrame === undefined || endFrameExclusive === undefined || endFrameExclusive <= startFrame) return [];
+    return [{
+      id: selection.id,
+      startAnchorId: selection.startAnchorId,
+      endAnchorId: selection.endAnchorId,
+      startFrame,
+      endFrameExclusive,
+    }];
+  });
+  const moments = (narrative.moments ?? []).flatMap((moment) => {
+    const at = frame(moment.anchorId);
+    return at === undefined ? [] : [{ id: moment.id, anchorId: moment.anchorId, frame: at }];
+  });
+  return { anchors, segments, tokens, selections, moments };
+}

package/packages/seedance/README.md

@@ -1,7 +1,7 @@
 # `@hypit/seedance`
 
 Exact Seedance author model module. It owns the request schema and exactly three invocation Surfaces;
-it does not contain KIE credentials, HTTP code, queues, runtime routing or usage-specific Prompt assembly.
+it does not contain service credentials, HTTP code, queues, runtime routing or usage-specific Prompt assembly.
 
 The three model invocation shapes are deliberately separate:
 
@@ -17,3 +17,32 @@ generic Text Template or third-party author module can feed them without becomin
 the author's literal, in whole seconds inside the model's declared range; measure the spoken line first
 with `hypit measure` and write the number here. Nothing in the graph computes it, so a Build plan is
 complete before it starts.
+
+## Visual reference metadata
+
+Declare whether each image or video contains a person/avatar reference, including an AI-generated
+human likeness. This describes the supplied material, independently of the prompt's requested action:
+
+```xml
+<seedance:ReferenceVideo id="dance" model="mini" prompt={direction} duration="8">
+  <seedance:Reference image={presenter.image} person-reference="true"/>
+  <seedance:Reference video={motion.video} person-reference="true"/>
+  <seedance:Reference image={room.image} person-reference="false"/>
+</seedance:ReferenceVideo>
+```
+
+`person-reference` is optional, accepts literal `true` or `false`, and applies to image/video, not
+voice audio. Omission carries no classification; it is distinct from explicitly declaring false.
+Inspect the actual reference when deciding the value. For `FrameVideo`, use
+`first-frame-person-reference` and `last-frame-person-reference` beside their respective frame
+inputs. A last-frame classification requires a last-frame input.
+
+The model's media ports carry this as `fields.personReference`. Providers interpret it through their
+service's media handling; it is not a prompt sentence or a Core-level identity. HypiHub sends it as
+`is_person_reference` when uploading the file, then uses the returned URL in the ordinary video
+request. A project Provider maps it according to its own API.
+
+Video references can carry motion or camera behavior while image references carry the target
+appearance. Request duration and reference-clip duration are different limits. Check the selected
+Endpoint's reference duration and media limits when choosing an excerpt; the author's output duration
+alone does not validate the input clip.

package/packages/seedance/src/index.ts

@@ -19,14 +19,16 @@ export type SeedanceModel = typeof seedanceModels[number];
 
 const ASPECT_RATIOS = ["1:1", "4:3", "3:4", "16:9", "9:16", "21:9", "adaptive"] as const;
 
+const PERSON_REFERENCE_FIELDS = [{ name: "personReference", value: { kind: "boolean" }, optional: true }] as const;
+
 const SEEDANCE_25_DURATIONS = [-1, ...Array.from({ length: 27 }, (_item, index) => index + 4)] as const;
 
 /**
  * Exact Seedance model inputs. Provider wire names are deliberately absent:
- * KIE, Volcengine or another service maps these ports independently.
+ * Each service maps these ports independently.
  *
  * Seedance 2.5 is not treated as an alias for a Seedance 2 variant. Its public
- * KIE contract widens prompt/reference capacities and duration independently,
+ * request definition widens prompt/reference capacities and duration independently,
  * so it receives its own exact Capability while reusing the same three author
  * Surfaces.
  */
@@ -37,11 +39,11 @@ function seedancePortTable(model: SeedanceModel): GenerationPortTable {
     result: "video",
     ports: [
       { name: "prompt", value: { kind: "text", maxChars: is25 ? 30_000 : 20_000 }, minItems: 1, maxItems: 1 },
-      { name: "referenceImage", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: is25 ? 30 : 9 },
-      { name: "referenceVideo", value: { kind: "media", accepts: ["video"] }, minItems: 0, maxItems: is25 ? 10 : 3 },
+      { name: "referenceImage", value: { kind: "media", accepts: ["image"], itemFields: PERSON_REFERENCE_FIELDS }, minItems: 0, maxItems: is25 ? 30 : 9 },
+      { name: "referenceVideo", value: { kind: "media", accepts: ["video"], itemFields: PERSON_REFERENCE_FIELDS }, minItems: 0, maxItems: is25 ? 10 : 3 },
       { name: "referenceAudio", value: { kind: "media", accepts: ["audio"] }, minItems: 0, maxItems: is25 ? 10 : 3 },
-      { name: "firstFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
-      { name: "lastFrame", value: { kind: "media", accepts: ["image"] }, minItems: 0, maxItems: 1 },
+      { name: "firstFrame", value: { kind: "media", accepts: ["image"], itemFields: PERSON_REFERENCE_FIELDS }, minItems: 0, maxItems: 1 },
+      { name: "lastFrame", value: { kind: "media", accepts: ["image"], itemFields: PERSON_REFERENCE_FIELDS }, minItems: 0, maxItems: 1 },
       {
         name: "resolution",
         value: {
@@ -174,6 +176,11 @@ const seedanceCommonAttributes: readonly SurfaceAttributeVocabulary[] = [
   },
 ];
 
+const personReferenceAttribute = (name: string): SurfaceAttributeVocabulary => ({
+  name, kind: "literal", required: false, values: ["true", "false"],
+  summary: "Declares whether this visual input contains a person/avatar reference, including an AI-generated human likeness. Omission leaves it unclassified.",
+});
+
 const seedanceVideoPort: readonly SurfacePortVocabulary[] = [{
   name: "video",
   type: artifactTypes.blob,
@@ -229,6 +236,8 @@ export const seedanceMarkupSurfaces = [
       summary: "Generates one video with an exact Seedance model from a Text prompt and the images the video opens and closes on.",
       attributes: [
         ...seedanceCommonAttributes,
+        personReferenceAttribute("first-frame-person-reference"),
+        personReferenceAttribute("last-frame-person-reference"),
         {
           name: "first-frame",
           kind: "reference",
@@ -268,6 +277,7 @@ export const seedanceMarkupSurfaces = [
         cardinality: "many",
         summary: "Attaches one Artifact as a reference through exactly one of its `image`, `video` or `audio` references.",
         attributes: [
+          personReferenceAttribute("person-reference"),
           {
             name: "image",
             kind: "reference",
@@ -301,12 +311,13 @@ export const seedanceMarkupSurfaces = [
   aspect-ratio="9:16"
   generate-audio="true"
 >
-  <seedance:Reference image={presenter-clean}/>
+  <seedance:Reference image={presenter-clean} person-reference="true"/>
   <seedance:Reference audio={presenter-voice}/>
 </seedance:ReferenceVideo>`,
       notes: [
         ...seedanceSettingNotes,
         "The element requires at least one `Reference` child, and the model's port limits cap how many of each role it accepts.",
+        "`person-reference` applies to image/video references; voice audio carries no visual classification. The Provider transports the declared fact according to its API.",
         "A `Reference` carries exactly one of `image`, `video` or `audio`, and is empty.",
       ],
     },

package/packages/seedance/src/surface.ts

@@ -28,6 +28,7 @@ type MediaInput = {
   readonly port: "referenceImage" | "referenceVideo" | "referenceAudio" | "firstFrame" | "lastFrame";
   readonly role: GenerationMediaRole;
   readonly source: SurfaceResolvedReference;
+  readonly fields?: { readonly personReference: boolean };
 };
 
 function localName(value: string): string {
@@ -142,6 +143,11 @@ function booleanAttribute(element: StructuredElement, name: string, fallback: bo
   throw new Error(`${element.name}.${name} must be true or false`);
 }
 
+function personReferenceFields(element: StructuredElement, name: string) {
+  return element.attributes[name] === undefined ? undefined
+    : { personReference: booleanAttribute(element, name, false) };
+}
+
 function enumeratedPort(table: GenerationPortTable, name: string): readonly (string | number)[] {
   const port = generationPort(table, name);
   if (port.value.kind !== "enum") throw new Error(`${table.model} port ${name} is not enumerated`);
@@ -204,12 +210,15 @@ function referenceInputs(
       continue;
     }
     if (localName(child.name) !== "Reference") throw new Error(`${element.name} accepts only Reference children`);
-    attributes(child, [], accepted);
+    attributes(child, [], [...accepted, "person-reference"]);
     empty(child);
     const kinds = accepted.filter((kind) => child.attributes[kind] !== undefined);
     if (kinds.length !== 1) throw new Error(`${child.name} requires exactly one of ${accepted.join(", ")}`);
     const role = kinds[0]!;
+    const fields = personReferenceFields(child, "person-reference");
+    if (role === "audio" && fields !== undefined) throw new Error(`${child.name}.person-reference applies to image or video, not audio`);
     result.push({
+      ...(fields === undefined ? {} : { fields }),
       role,
       port: REFERENCE_PORTS[role],
       source: mediaReference(resolved(child, role, resolveReference), role, `${child.name}.${role}`),
@@ -230,10 +239,14 @@ function frameInputs(
   resolveReference: (path: string) => SurfaceResolvedReference | undefined,
 ): MediaInput[] {
   const first = mediaReference(resolved(element, "first-frame", resolveReference), "image", `${element.name}.first-frame`);
-  const result: MediaInput[] = [{ port: "firstFrame", role: "image", source: first }];
+  const firstFields = personReferenceFields(element, "first-frame-person-reference");
+  const result: MediaInput[] = [{ port: "firstFrame", role: "image", source: first, ...(firstFields === undefined ? {} : { fields: firstFields }) }];
+  const lastFields = personReferenceFields(element, "last-frame-person-reference");
+  if (lastFields !== undefined && element.attributes["last-frame"] === undefined) throw new Error(`${element.name}.last-frame-person-reference requires last-frame`);
   if (element.attributes["last-frame"] !== undefined) {
     result.push({
       port: "lastFrame",
+      ...(lastFields === undefined ? {} : { fields: lastFields }),
       role: "image",
       source: mediaReference(resolved(element, "last-frame", resolveReference), "image", `${element.name}.last-frame`),
     });
@@ -266,7 +279,7 @@ function assembleMedia(
       type: binding.type,
       value: {
         kind: "inline",
-        value: sealGenerationMediaBinding(port as GenerationMediaPort, { role: value.role }) as unknown as CanonicalValue,
+        value: sealGenerationMediaBinding(port as GenerationMediaPort, { role: value.role, ...(value.fields === undefined ? {} : { fields: value.fields }) }) as unknown as CanonicalValue,
       },
       range,
     });
@@ -330,7 +343,7 @@ export const decodeSeedanceTextVideoSurface: StructuredSurfaceHandler = ({ eleme
 };
 
 export const decodeSeedanceFrameVideoSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  attributes(element, ["id", "model", "prompt", "duration", "first-frame"], [...COMMON_OPTIONAL, "last-frame"]);
+  attributes(element, ["id", "model", "prompt", "duration", "first-frame"], [...COMMON_OPTIONAL, "last-frame", "first-frame-person-reference", "last-frame-person-reference"]);
   empty(element);
   const selected = modelSelection(element);
   const promptSource = resolved(element, "prompt", resolveReference);

package/packages/seedance-kits/README.md

@@ -44,7 +44,7 @@ Speaker uses the same graph vocabulary. The Kit assumes `@image1` is the visible
 <seedance:ReferenceVideo id="hook-take" model="mini"
   prompt={hook-prompt} duration="8"
   resolution="720p" aspect-ratio="9:16" generate-audio="true">
-  <seedance:Reference image={presenter}/>
+  <seedance:Reference image={presenter} person-reference="true"/>
   <seedance:Reference audio={voice}/>
 </seedance:ReferenceVideo>
 ```
@@ -153,3 +153,9 @@ Avoid exaggerated reactions or constantly moving every person simply to prevent
 For a multi-scene B-roll montage, `story` can name the references in scene order and give each a small
 action. Choose an edit language compatible with cuts. “Continuous within each scene” and “one
 continuous shot for the whole montage” ask for different results.
+
+Visual input classification belongs to the Seedance Reference, separately from Kit text. The
+[Seedance author package](../seedance/README.md#visual-reference-metadata) explains `person-reference`
+and its frame variants. The Kit supplies direction; the actual reference edges supply media and
+metadata. For movement-led work, a reference video can carry the motion while the text explains what
+to preserve and change.

package/packages/seedream/README.md

@@ -4,7 +4,7 @@ Exact author/compute contracts and package-owned author Surfaces for Seedream im
 
 The two modes are separate Surfaces and project the primary result to an ordinary image Artifact.
 This package defines what the author requested, not where it runs: API translation, credentials,
-retry and queue behavior belong to a selected Runtime Endpoint such as `@hypit/provider-kie`.
+retry and queue behavior belong to a selected Runtime Endpoint selected in the Runtime Profile.
 
 The modes stay explicit in the source:
 

package/packages/sound/README.md

@@ -0,0 +1,81 @@
+# Sound
+
+Sound presents audio already placed on a Timeline. Audio Track takes independent material such as
+music and effects. Sound obtains existing sources and playback positions from Timeline and chooses
+how they are heard. Visual Performance and Caption remain independent presentations.
+
+```svml
+<import as="sound" from="@hypit/sound@1"/>
+<sound:Style id="normal"/>
+<sound:Style id="fade-in" gain="0" end-gain="1"/>
+<sound:Style id="silent" gain="0"/>
+<sound:Track id="voice" timeline={program.timeline}>
+  <sound:Use style={normal}/>
+  <sound:Use at="0f" for="2s" style={fade-in}/>
+  <sound:Use during={story.selection.demonstration} style={silent}/>
+</sound:Track>
+```
+
+Include `voice.audio` in Film to hear this presentation. Timeline exports `.timeline`, retaining
+the material for consumers; Sound selects and presents its audio explicitly.
+
+Sound also exports `.program`: the ordered Use windows and their audio presentations before
+coverage is resolved. The Studio Companion consumes this value to keep silent and covered Uses
+available for editing. `.audio` remains the effective arrangement for Film.
+
+## Two separate choices
+
+The last declared matching Use selects the complete presentation locally. No selector means the
+whole Timeline. No matching Use contributes no sound; an empty winning Style remains silent.
+Later Uses can restore sound inside an earlier silent interval. Separate Sound Tracks can coexist.
+
+Within the ordinary Style, the last Timeline-declared active source with audio wins. Declaration
+order is independent of start-time order. A video-only Take supplies no sound candidate; a recorded
+silent audio source is still a source. Gaps and zero-Take Timelines have no sound to present. When a
+later source ends, an earlier still-active source resumes at its current source position.
+
+`gain` and `end-gain` are linear amplitude multipliers from 0 to 64. `gain` defaults to 1 and
+`end-gain` defaults to `gain`. They describe a linear ramp over the original Use Window. Equal values
+produce constant gain; zero produces silence. Changing the Window changes the ramp duration.
+The interval's right endpoint describes the gain reached at the boundary, while sample coverage is
+half-open. Matching adjacent Style endpoints is an authoring choice.
+
+## Time and continuity
+
+Use accepts shared `during`, `at` + `for`, `until` + `for`, and `start` + `end`, including independently
+bound `start-source` / `end-source`. A source role and a time endpoint are distinct inputs.
+
+A Use starting at program second 7 does not restart a Take placed at second 5: its sound is already
+at source second 2. A partially overridden Use keeps its original gain-ramp progress. Resolution
+intersects audible subranges and preserves original Clip targets, sampling and envelopes. The same
+holds for a partial audio render. Sound does not move Takes, change words or retime semantic anchors.
+
+## Write a project Style
+
+The public TypeScript entry is `@hypit/hypit/sound`.
+`soundStyle(fragment, bindings)` creates an authored Style. Its fragment takes `timeline` and
+`window`, plus explicitly bound family inputs, and exports `audio: AudioTrack`. Bound references
+become ordinary graph edges at each Use. The fragment may produce an empty Track, one source or
+multiple sources; the renderer consumes the resulting ordinary AudioTrack.
+
+`ordinarySound(timeline, window, { gain, endGain })` supplies ordinary last-source presentation.
+`sourceSound(timeline, window, segment, { gain, endGain })` selects one explicit Narrative Segment,
+retaining its existing source and target positions. A known Segment without audio returns an empty
+Track; a foreign or unknown Segment is an error. Neither helper invents sound outside source coverage.
+A family can publish richer program-sample `gainEnvelope` points through the common AudioClip data.
+
+The [project crossfade example](../../examples/semantic-composition/packages/sound-styles/README.md)
+binds `outgoing` and `incoming` independently. Its two gains move in opposite directions across the
+Use Window. There is no transition-mode registry or automatic source pairing. Other families can
+own different curves or source combinations through the same fragment interface.
+
+## Rendering boundary
+
+[Composition](../composition/README.md) owns generic AudioClip presentation fields: optional
+`gainEnvelope` points and `audibility` subranges, both on the complete 48 kHz program clock. Sound
+resolves Uses into those values. The media pipeline preserves them; the execution package applies
+them per sample after source playback and existing fades, before render-range cropping.
+
+The [Sound Companion](../sound-studio/README.md) presents placed audio content and authored Uses.
+Studio playback consumes the same gain envelopes, audible regions and fades through its generic
+AudioTrack player.

package/packages/sound/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@hypit/sound",
+  "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/component-kit": "workspace:*",
+    "@hypit/composition": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/markup": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/program-space": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/temporal": "workspace:*",
+    "@hypit/temporal-markup": "workspace:*",
+    "@hypit/timeline": "workspace:*"
+  }
+}

package/packages/sound/src/activation.ts

@@ -0,0 +1,11 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+import { soundManifest, soundModuleRef, soundMarkupSurfaces } from "./manifest.js";
+import { soundComponent } from "./component.js";
+import { decodeSoundStyleSurface, decodeSoundTrackSurface } from "./surface.js";
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: soundManifest }], components: [soundComponent],
+  hostFacets: soundMarkupSurfaces.map(declaration => createMarkupSurfaceHostFacet({ module: soundModuleRef, declaration,
+    handler: declaration.name === "style" ? decodeSoundStyleSurface : decodeSoundTrackSurface })),
+};
+export default hypitPackage;

package/packages/sound/src/component.ts

@@ -0,0 +1,28 @@
+import { canonicalize } from "@hypit/protocol";
+import type { StoredValue } from "@hypit/protocol";
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { Timeline } from "@hypit/timeline";
+import type { AudioTrack } from "@hypit/composition";
+import type { TemporalWindow } from "@hypit/temporal";
+import { ordinarySound, appendSoundUse, resolveSound } from "./program.js";
+import type { SoundSet, SoundGain } from "./program.js";
+import { soundProducers } from "./manifest.js";
+function inline<T>(value: StoredValue | undefined): T {
+  if (value?.kind !== "inline") throw new Error("Sound input must be inline.");
+  return value.value as unknown as T;
+}
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+export const soundComponent: ComponentPackage = {
+  producers: [
+    { producer: soundProducers.create, handler: () => ({ outputs: { set: output({ uses: [] }) }, needs: {} }) },
+    { producer: soundProducers.append, handler: ({ inputs }) => ({ outputs: { set: output(appendSoundUse(
+      inline<SoundSet>(inputs.set?.value), inline<TemporalWindow>(inputs.window?.value), inline<AudioTrack>(inputs.audio?.value),
+    )) }, needs: {} }) },
+    { producer: soundProducers.resolve, handler: ({ inputs }) => ({ outputs: { audio: output(resolveSound(
+      inline<Timeline>(inputs.timeline?.value), inline<{ id: string }>(inputs.header?.value).id, inline<SoundSet>(inputs.set?.value),
+    )) }, needs: {} }) },
+    { producer: soundProducers.ordinary, handler: ({ inputs }) => ({ outputs: { audio: output(ordinarySound(
+      inline<Timeline>(inputs.timeline?.value), inline<TemporalWindow>(inputs.window?.value), inline<SoundGain>(inputs.spec?.value),
+    )) }, needs: {} }) },
+  ],
+};

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;
+}