@hypit/hypit 0.1.4 → 0.1.5

package/packages/media-track/src/sampling.ts

@@ -1,10 +1,10 @@
+import type { Timeline } from "@hypit/timeline";
 import type {
   VisualSamplingRational,
   VisualSamplingSegment,
   VisualTimedSampling,
 } from "@hypit/composition";
 import { assertProgramSpaceIdentity } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
 
 import type { MediaVisualOccupancy, MediaVisualTrim } from "./types.js";
 
@@ -58,21 +58,21 @@ function assertOccupancy(value: MediaVisualOccupancy): void {
  * frame. This avoids a second, renderer-specific frame quantizer.
  */
 export function resolveVisualSampling(input: {
-  readonly space: ProgramSpace;
+  readonly timeline: Timeline;
   readonly sourceFrameRate: { readonly numerator: number; readonly denominator: number };
   readonly sourceFrameCount: number;
   readonly targetFrameCount: number;
   readonly trim?: MediaVisualTrim;
   readonly occupancy: MediaVisualOccupancy;
 }): VisualTimedSampling {
-  assertProgramSpaceIdentity(input.space);
+  assertProgramSpaceIdentity(input.timeline);
   assert(Number.isSafeInteger(input.sourceFrameCount) && input.sourceFrameCount > 0,
     "Timed visual source frame count is invalid.");
   assert(Number.isSafeInteger(input.targetFrameCount) && input.targetFrameCount > 0,
     "Timed visual target frame count is invalid.");
-  assert(input.sourceFrameRate.numerator === input.space.frameRate.numerator
-    && input.sourceFrameRate.denominator === input.space.frameRate.denominator,
-  "Timed visual source must be normalized to ProgramSpace frame rate before Media authoring.");
+  assert(input.sourceFrameRate.numerator === input.timeline.frameRate.numerator
+    && input.sourceFrameRate.denominator === input.timeline.frameRate.denominator,
+  "Timed visual source must be normalized to Timeline frame rate before Media authoring.");
   assertOccupancy(input.occupancy);
   const trim = input.trim ?? { startFrame: 0, endFrameExclusive: input.sourceFrameCount };
   assert(Number.isSafeInteger(trim.startFrame) && Number.isSafeInteger(trim.endFrameExclusive)

package/packages/media-track/src/sequence.ts

@@ -1,3 +1,4 @@
+import type { Timeline } from "@hypit/timeline";
 import type {
   VisualAnimation,
   VisualEasing,
@@ -5,7 +6,6 @@ import type {
   VisualStyleDeclaration,
 } from "@hypit/composition";
 import { assertProgramSpaceIdentity, programSpaceFrameCount } from "@hypit/program-space";
-import type { ProgramSpace } from "@hypit/program-space";
 import { canonicalize } from "@hypit/protocol";
 import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
 import type { CanvasSpace } from "@hypit/spatial";
@@ -109,12 +109,12 @@ function appendMediaSequenceMemberAtFrame(
 
 export function appendMediaSequenceMember(
   set: MediaSequenceMemberSet,
-  space: ProgramSpace,
+  timeline: Timeline,
   layers: MediaLayerSet,
   spec: MediaSequenceMemberSpec,
   activation: TemporalInstant,
 ): MediaSequenceMemberSet {
-  assertTemporalInstantFor(activation, { subjectId: spec.id, space });
+  assertTemporalInstantFor(activation, { subjectId: spec.id, space: timeline });
   return appendMediaSequenceMemberAtFrame(set, layers, spec, activation.frame);
 }
 
@@ -180,7 +180,7 @@ function resolvedHandoff(
 
 export function resolveMediaSequence(
   header: MediaTrackHeader,
-  space: ProgramSpace,
+  timeline: Timeline,
   canvas: CanvasSpace,
   memberSet: MediaSequenceMemberSet,
   frame: MediaSequenceProgram["frame"],
@@ -188,7 +188,7 @@ export function resolveMediaSequence(
   sounds: MediaSoundSet,
   terminalFrame: number,
 ): MediaSequenceProgram {
-  assertProgramSpaceIdentity(space);
+  assertProgramSpaceIdentity(timeline);
   assertCanvasSpace(canvas);
   assertMediaSequenceMemberSet(memberSet);
   assertMediaSequenceSpec(spec);
@@ -205,7 +205,7 @@ export function resolveMediaSequence(
     terminalFrame,
     triggers: memberSet.members.map((member) => ({ id: member.id, frame: member.activationFrame })),
   });
-  assert(terminalFrame <= programSpaceFrameCount(space), `Media Sequence ${spec.id} exits ProgramSpace.`);
+  assert(terminalFrame <= programSpaceFrameCount(timeline), `Media Sequence ${spec.id} exits Timeline.`);
   const handoffs = spec.handoffs.map((handoff, index) => {
     const from = memberSet.members[index]!;
     const to = memberSet.members[index + 1]!;
@@ -360,7 +360,7 @@ export function sequenceMemberHandoffAnimation(
 
 export function lowerMediaSequencePresents(
   sequence: MediaSequenceProgram,
-  space: ProgramSpace,
+  timeline: Timeline,
 ): readonly VisualPresent[] {
   return sequence.members.map((member, index) => {
     const incoming = sequence.handoffs[index - 1];
@@ -389,7 +389,7 @@ export function lowerMediaSequencePresents(
       subjectId: sequence.id,
       span: { ...item.span },
       stacking: { ...item.stacking },
-      elements: lowerMediaItemElements(item, space, {
+      elements: lowerMediaItemElements(item, timeline, {
         includeHandoffWrapper: true,
         ...(handoffAnimation === undefined ? {} : { handoffAnimation }),
         lifecycleAnimationOverride: lifecycleAnimationWindow(

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

@@ -1,4 +1,4 @@
-import { createTemporalSpace, resolveTemporalContext } from "@hypit/temporal-markup";
+import { resolveTemporalContext } from "@hypit/temporal-markup";
 import {
   assertEmptyElement as empty,
   assertAttributes as allowed,
@@ -85,7 +85,6 @@ type FragmentLayer =
 type FragmentSound = { readonly sourceName: string; readonly specName: string };
 
 type FragmentItem = {
-  readonly performance?: { readonly fitName: string; readonly sampleName: string };
   readonly suffix: string;
   readonly windowName: string;
   readonly frameName: string;
@@ -167,11 +166,11 @@ function createMediaTrackSurfaceFragment(inputTypes: readonly { readonly name: s
       spec = operation(bindId);
     }
     const common = {
-      set: operation(set), header: input("header"), space: input("space"), canvas: input("canvas"),
+      set: operation(set), header: input("header"), timeline: input("timeline"), canvas: input("canvas"),
       layers: operation(layers), frame: input(item.frameName), spec, sounds: operation(sounds), window: input(item.windowName),
     };
-    operations.push({ id: appendId, producer: item.performance === undefined ? mediaTrackProducers.appendItem : mediaTrackProducers.appendPerformance,
-      inputs: { ...common, ...(item.performance === undefined ? {} : { semantic: input("semantic"), fit: input(item.performance.fitName), sampleSpec: input(item.performance.sampleName) }) }, result: { kind: "output", name: "set" } });
+    operations.push({ id: appendId, producer: mediaTrackProducers.appendItem,
+      inputs: common, result: { kind: "output", name: "set" } });
     set = appendId;
   }
   for (const sequence of sequences) {
@@ -184,7 +183,7 @@ function createMediaTrackSurfaceFragment(inputTypes: readonly { readonly name: s
       const layers = appendLayers(operations, memberPrefix, member.layers);
       const appendId = `${memberPrefix}:append`;
       operations.push({ id: appendId, producer: mediaTrackProducers.appendMember, inputs: {
-        members: operation(members), space: input("space"), layers: operation(layers), spec: input(member.specName), activation: input(member.instantName),
+        members: operation(members), timeline: input("timeline"), layers: operation(layers), spec: input(member.specName), activation: input(member.instantName),
       }, result: { kind: "output", name: "members" } });
       members = appendId;
     }
@@ -199,7 +198,7 @@ function createMediaTrackSurfaceFragment(inputTypes: readonly { readonly name: s
       spec = operation(bindId);
     }
     const common = {
-      set: operation(set), header: input("header"), space: input("space"), canvas: input("canvas"),
+      set: operation(set), header: input("header"), timeline: input("timeline"), canvas: input("canvas"),
       members: operation(members), frame: input(sequence.frameName), spec, sounds: operation(sounds),
     };
     operations.push({ id: appendId, producer: mediaTrackProducers.appendSequence,
@@ -207,10 +206,10 @@ function createMediaTrackSurfaceFragment(inputTypes: readonly { readonly name: s
     set = appendId;
   }
   operations.push(
-    { id: "track:finalize", producer: mediaTrackProducers.finalize, inputs: { set: operation(set), header: input("header"), space: input("space") }, result: { kind: "output", name: "program" } },
-    { id: "track:visual", producer: mediaTrackProducers.projectVisual, inputs: { space: input("space"), program: operation("track:finalize") }, result: { kind: "output", name: "track" } },
+    { id: "track:finalize", producer: mediaTrackProducers.finalize, inputs: { set: operation(set), header: input("header"), timeline: input("timeline") }, result: { kind: "output", name: "program" } },
+    { id: "track:visual", producer: mediaTrackProducers.projectVisual, inputs: { timeline: input("timeline"), program: operation("track:finalize") }, result: { kind: "output", name: "track" } },
   );
-  if (audio) operations.push({ id: "track:audio", producer: mediaTrackProducers.projectAudio, inputs: { space: input("space"), program: operation("track:finalize") }, result: { kind: "output", name: "track" } });
+  if (audio) operations.push({ id: "track:audio", producer: mediaTrackProducers.projectAudio, inputs: { timeline: input("timeline"), program: operation("track:finalize") }, result: { kind: "output", name: "track" } });
   return sealGraphFragment({
     inputs: inputTypes,
     operations,
@@ -495,39 +494,33 @@ function sound(
 }
 
 export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
-  allowed(element, ["id", "semantic", "space", "canvas"]);
+  allowed(element, ["id", "timeline", "canvas"]);
   const trackId = text(element, "id");
   const state = builder();
   const context = resolveTemporalContext({ element, resolveReference });
-  const time = createTemporalSpace({ id: trackId, element, ...context });
-  state.addReference("space", time.space);
+  state.addReference("timeline", context.timeline);
   state.addReference("canvas", reference(element.attributes.canvas, `${element.name}.canvas`, spatialTypes.canvas, resolveReference));
   const headerId = `${trackId}.header`;
   state.addRecord("header", headerId, mediaTrackTypes.header,
     sealMediaTrackHeader({ id: trackId }), element.range);
   const items: FragmentItem[] = [];
   const sequences: FragmentSequence[] = [];
-  const temporalComponents: SurfaceComponentDraft[] = [...time.components];
-  const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [...time.fragments];
+  const temporalComponents: SurfaceComponentDraft[] = [];
+  const temporalFragments: ReturnType<typeof createTemporalWindowProjection>["fragments"][number][] = [];
   let itemIndex = 0;
   let sequenceIndex = 0;
   let hasAudio = false;
   for (const child of element.children) {
     if (child.kind === "text") {
-      if (child.value.trim().length > 0) throw new Error(`${element.name} accepts only Performance, Item and Sequence children.`);
+      if (child.value.trim().length > 0) throw new Error(`${element.name} accepts only Item and Sequence children.`);
       continue;
     }
-    const isPerformance = child.name.endsWith(":Performance") || child.name === "Performance";
-    if (isPerformance) {
-      if (context.semantic === undefined) throw new Error(`${child.name} requires semantic performance input.`);
-      if (state.inputs.semantic === undefined) state.addReference("semantic", context.semantic);
-    }
-    if (isPerformance || child.name.endsWith(":Item") || child.name === "Item") {
+    if (child.name.endsWith(":Item") || child.name === "Item") {
       itemIndex += 1;
       const itemSuffix = suffix(itemIndex);
       allowed(child, [
         "id", "frame", "appearance", "motion",
-        ...(isPerformance ? [] : ["image", "media", "surface", "extent", "source-audio", "audio-gain"]),
+        "image", "media", "surface", "extent", "source-audio", "audio-gain",
         "clip", ...temporalWindowAttributeNames,
       ]);
       const id = optionalText(child, "id") ?? `${trackId}.item.${itemSuffix}`;
@@ -539,23 +532,12 @@ export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, res
       }
       const motionRecipe = child.attributes.motion === undefined ? undefined
         : recipe(reference(child.attributes.motion, `${child.name}.motion`, svsRecipeType, resolveReference), `${child.name}.motion`);
-      const temporal = createTemporalWindowProjection({ id, element: child, ...context, space: time.space, resolveReference });
+      const temporal = createTemporalWindowProjection({ id, element: child, ...context, resolveReference });
       state.records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);
-      const performance = isPerformance ? {
-        fitName: `item-${itemSuffix}-fit`, sampleName: `item-${itemSuffix}-sample`,
-      } : undefined;
-      const directSource = isPerformance ? undefined : declaredVisualSource(child, resolveReference);
-      validateUnitChildren(child, isPerformance || directSource !== undefined, true);
-      if (performance !== undefined) {
-        state.addRecord(performance.fitName, `${id}.fit`, spatialTypes.fit, decodeMediaFit(appearance), child.range);
-        if (appearance.properties.playback !== undefined || appearance.properties["trim-start"] !== undefined || appearance.properties["trim-end"] !== undefined) {
-          throw new Error(`${child.name} follows the performance's source time. Select its interval with during or start/end.`);
-        }
-        state.addRecord(performance.sampleName, `${id}.sample`, mediaTrackTypes.sampleLayerSpec,
-          decodeMediaSampleSpec(appearance, "content", "timed", decodeSamplingMotion(child, true), true), child.range);
-      }
+      const directSource = declaredVisualSource(child, resolveReference);
+      validateUnitChildren(child, directSource !== undefined, true);
       const layers = unitLayers(state, { trackId, unitSuffix: `item-${itemSuffix}`, element: child, appearance,
-        ...(directSource === undefined ? {} : { directSource }), allowFramePaint: true, allowEmpty: isPerformance }, resolveReference);
+        ...(directSource === undefined ? {} : { directSource }), allowFramePaint: true, allowEmpty: false }, resolveReference);
       const selectedAudio = sourceAudio(child);
       const specName = `item-${itemSuffix}-spec`;
       const windowName = `item-${itemSuffix}-window`;
@@ -572,12 +554,12 @@ export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, res
         }
       }
       if (selectedAudio !== undefined || fragmentSounds.length > 0) hasAudio = true;
-      items.push({ suffix: itemSuffix, windowName, frameName, specName, ...(performance === undefined ? {} : { performance }),
+      items.push({ suffix: itemSuffix, windowName, frameName, specName,
         ...(clipPathName === undefined ? {} : { clipPathName }), layers, sounds: fragmentSounds });
       continue;
     }
     if (!(child.name.endsWith(":Sequence") || child.name === "Sequence")) {
-      throw new Error(`${element.name} accepts only Performance, Item and Sequence children.`);
+      throw new Error(`${element.name} accepts only Item and Sequence children.`);
     }
     sequenceIndex += 1;
     const sequenceSuffix = suffix(sequenceIndex);
@@ -611,7 +593,7 @@ export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, res
     for (const [index, member] of memberElements.entries()) {
       const memberSuffix = suffix(index + 1);
       allowed(member, ["id", "image", "media", "surface", "extent", "appearance", ...temporalInstantAttributeNames, "source-audio", "audio-gain"]);
-      const temporal = createTemporalInstantProjection({ id: `${id}.${memberIds[index]}`, subjectId: memberIds[index]!, element: member, ...context, space: time.space, resolveReference });
+      const temporal = createTemporalInstantProjection({ id: `${id}.${memberIds[index]}`, subjectId: memberIds[index]!, element: member, ...context, resolveReference });
       state.records.push(...temporal.records); temporalComponents.push(...temporal.components); temporalFragments.push(...temporal.fragments);
       const memberAppearance = member.attributes.appearance === undefined ? appearance
         : recipe(reference(member.attributes.appearance, `${member.name}.appearance`, svsRecipeType, resolveReference), `${member.name}.appearance`);
@@ -641,7 +623,7 @@ export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, res
     }
     if (sequenceSounds.length > 0) hasAudio = true;
     const terminalTemporal = createTemporalInstantProjection({
-      id: `${id}.terminal`, subjectId: id, element: child, ...context, space: time.space, resolveReference,
+      id: `${id}.terminal`, subjectId: id, element: child, ...context, resolveReference,
       semanticAttribute: "until", boundaryAttribute: "until-boundary", projectedAttribute: false,
       boundaryFallback: "end",
     });
@@ -656,7 +638,7 @@ export const decodeMediaTrackSurface: StructuredSurfaceHandler = ({ element, res
     sequences.push({ suffix: sequenceSuffix, terminalName, frameName, specName,
       ...(clipPathName === undefined ? {} : { clipPathName }), members, sounds: sequenceSounds });
   }
-  if (items.length === 0 && sequences.length === 0) throw new Error(`${element.name} requires at least one Performance, Item or Sequence.`);
+  if (items.length === 0 && sequences.length === 0) throw new Error(`${element.name} requires at least one Item or Sequence.`);
   const fragment = createMediaTrackSurfaceFragment(state.inputTypes, items, sequences, hasAudio);
   return {
     records: state.records,

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

@@ -1,3 +1,12 @@
 # `@hypit/media-track-studio`
 
 Hypit Studio Companion for `@hypit/media-track`.
+
+Each Item has a title and image or video body. An explicit author `id` supplies
+its title; otherwise the Companion displays its `image`, `media` or `surface`
+reference. Display names do not replace the Item's identity or writeback
+endpoint. Source-audio gain uses the same percentage display and scalar
+writeback as Audio Track.
+
+Media and Audio Track share selection and temporal editing behavior. Media
+composes pictures by draw order; Audio Track mixes overlapping sounds.

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

@@ -1,4 +1,4 @@
-import { mediaTrackMarkupSurfaces, mediaTrackModuleRef, mediaTrackTypes } from "@hypit/media-track";
+import { mediaAppearanceDefaults, mediaTrackMarkupSurfaces, mediaTrackModuleRef, mediaTrackTypes } from "@hypit/media-track";
 import type { MediaLayerProgram, MediaTrackProgram } from "@hypit/media-track";
 import { compositionTypes } from "@hypit/composition";
 import { sameType } from "@hypit/protocol";
@@ -10,7 +10,7 @@ import type {
   StudioMaterialPreview,
   StudioSourceBindingDeclaration,
 } 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";
 
 const frameParameters: readonly StudioSourceBindingDeclaration[] = [
   { name: "within" },
@@ -70,13 +70,15 @@ const mediaPercentProperties = new Set(["frame-x", "frame-y", "content-x", "cont
 const mediaPixelProperties = new Set(["fit-offset-x", "fit-offset-y", "radius", "blur", "border-width"]);
 
 function mediaRecipe(name: "appearance" | "motion"): {
-  readonly bindings: readonly { readonly name: string }[];
+  readonly bindings: readonly import("@hypit/studio-adapter").StudioRecipeBindingDeclaration[];
   readonly inspector: readonly StudioInspectorFieldDeclaration[];
 } {
   const attribute = mediaItemAttributes.find((candidate) => candidate.name === name);
   const properties = attribute !== undefined && "recipe" in attribute ? attribute.recipe : [];
   return {
-    bindings: properties.map(({ name: property }) => ({ name: property })),
+    bindings: properties.map(({ name: property }) => ({ name: property,
+      ...(Object.hasOwn(mediaAppearanceDefaults, property) ? { fallback: mediaAppearanceDefaults[property as keyof typeof mediaAppearanceDefaults] } : {}),
+    })),
     inspector: properties.map((property) => {
       const placement = mediaPlacement.get(property.name);
       if (placement === undefined) throw new Error(`Media Studio has no explicit Inspector declaration for ${property.name}.`);
@@ -99,7 +101,8 @@ function mediaRecipe(name: "appearance" | "motion"): {
   };
 }
 
-const mediaAppearanceRecipe = mediaRecipe("appearance");
+export const mediaAppearanceStudioFields = mediaRecipe("appearance");
+const mediaAppearanceRecipe = mediaAppearanceStudioFields;
 const mediaMotionRecipe = mediaRecipe("motion");
 
 function materialPreview(
@@ -153,15 +156,16 @@ function projectMedia(context: StudioTrackCompanionContext): readonly StudioEnti
       const semanticSource = temporalSemanticSource(temporal);
       return {
         ...entity,
+        display: {
+          ...entity.display,
+          title: authoredItemTitle(context, entity.authoredId, item.sourceTypes, ["image", "media", "surface"]),
+          ...(item.preview === undefined ? {} : {
+            layers: [previewLayer(item.preview, facet === "audio" ? "waveform" : item.preview.kind === "video" ? "storyboard" : "repeat-x")],
+          }),
+        },
         ...(semanticSource?.id === undefined
           ? {}
           : { markerId: semanticSource.id }),
-        ...(item.preview === undefined ? {} : {
-          display: {
-            ...entity.display,
-            layers: [previewLayer(item.preview, facet === "audio" ? "waveform" : item.preview.kind === "video" ? "storyboard" : "repeat-x")],
-          },
-        }),
         ...(temporal === undefined ? {} : { temporal }),
       };
     });
@@ -178,6 +182,7 @@ const commonInspector: readonly StudioInspectorFieldDeclaration[] = [
   {
     binding: "audio-gain", label: "Audio Gain", domain: "how",
     page: { id: "audio", label: "Audio" }, section: { id: "audio", label: "Audio" }, control: "number",
+    unit: "%", number: { scale: 100, minimum: 0, step: 1 },
   },
   {
     binding: "until-boundary", label: "Until Boundary", domain: "when",

package/packages/mimo-speech/README.md

@@ -9,7 +9,7 @@ The package owns two distinct speech operations:
 - `mimo-v2.5-tts-voiceclone` uses one accepted audio voice reference to create independent speech.
 
 It contains no API URL, credential, retry, queue or Xiaomi wire encoding. Those belong to a Runtime
-Endpoint such as `@hypit/provider-xiaomi-mimo`. Both models return the shared `GeneratedAudioSet`;
+Endpoint implementing the selected speech capability. Both models return the shared `GeneratedAudioSet`;
 the author Surfaces expose its primary member as an ordinary audio Resource.
 
 ```xml

package/packages/minimax-h3/README.md

@@ -5,7 +5,7 @@ Exact author/compute contracts and package-owned author Surfaces for MiniMax H3
 Text, frame-guided and subject-reference modes are separate Surfaces rather than one dynamic
 port mode. Each produces an ordinary video Artifact. This package owns request semantics
 and validation only; Provider calls, credentials, retries and queueing belong to a Runtime Endpoint
-such as `@hypit/provider-kie`.
+selected in the Runtime Profile.
 
 ```xml
 <h3:TextVideo id="idea" prompt={prompt} duration="6" resolution="768P" aspect-ratio="9:16"/>

package/packages/nano-banana/README.md

@@ -4,7 +4,7 @@ Exact author/compute contracts and package-owned author Surfaces for Nano Banana
 
 The model variants are separate endpoints with exact request validation. Their Surfaces project the
 primary result to an ordinary image Artifact. The package contains no Provider selection, API key or
-network execution; `@hypit/provider-kie` is one optional Runtime implementation.
+network execution. The selected Provider implements its exact capability.
 
 Import the model variant you mean and connect prompt and references as ordinary graph edges:
 

package/packages/narrative/README.md

@@ -4,4 +4,26 @@ External components use `@hypit/hypit/narrative` from their `@hypit/hypit` devel
 owns the types and helpers below; Source imports retain the `@hypit/narrative@1` Module identity.
 
 
-Public, provider-neutral contracts for authored speech and semantic selections.
+Public, provider-neutral values for complete authored content and its semantic references.
+
+A `Narrative` owns speech Tokens, Segments, Turns, semantic Anchors, Selections and Moments, plus
+its `caption: CaptionDocument`. The document supplies display Words, speech/display correspondence
+and Cue breaks. These are authored relationships; frame timing and visual Styles belong downstream.
+Script exports the complete value as `story` and the same document as the narrow `story.caption`
+Record. A third-party author package can produce the same values without importing the Script parser.
+
+## Query content through semantic references
+
+- `narrativeAnchorTokenBoundary(narrative, anchorId)` resolves a boundary in authored token order.
+- `narrativeSelectionTokenRange(narrative, selection)` returns the half-open authored token range.
+- `narrativeTokensForSelection(narrative, selection)` returns those Tokens in authored order.
+
+These pure queries use existing Anchors and Tokens, with no stored secondary index. An exported
+Selection retains its Narrative identity; content lookup checks that identity. Structural anchors
+remain distinct even when they resolve to the same token boundary, and an empty Segment can select
+no Tokens. Authored order is independent of gaps, overlap or placement order in a Timeline.
+
+Caption uses this content query and the Narrative's display correspondence to select complete
+subtitle units. Timeline projection uses the same semantic references to locate events in physical
+time. Neither operation substitutes for the other. Token lookup returns Tokens, not reconstructed
+source prose: whitespace, comments and source-preserving edits remain the author language's concern.

package/packages/narrative/src/identity.ts

@@ -25,6 +25,17 @@ export function assertNarrativeIdentity(value: Narrative): void {
   if (value.segments.length === 0) throw new Error("Narrative must contain at least one Segment.");
   const segmentIds = unique(value.segments.map((item) => item.id), "Narrative Segment id");
   const tokenIds = unique(value.tokens.map((item) => item.id), "Narrative Token id");
+  assertCaptionDocumentIdentity(value.caption);
+  if (value.caption.narrativeId !== value.id) throw new Error("Narrative CaptionDocument belongs to another Narrative.");
+  const turns = new Map(value.turns.map((turn) => [turn.id, turn]));
+  const tokens = new Map(value.tokens.map((token) => [token.id, token]));
+  for (const unit of value.caption.units) {
+    const turn = turns.get(unit.turnId);
+    if (turn === undefined || turn.segmentId !== unit.segmentId || turn.role !== unit.role
+      || unit.sourceTokenIds.some((id) => tokens.get(id)?.segmentId !== unit.segmentId)) {
+      throw new Error(`Caption unit ${unit.id} disagrees with its authored speech.`);
+    }
+  }
   unique(value.turns.map((item) => item.id), "Narrative Turn id");
   unique(value.selections.map((item) => item.id), "Narrative Selection id");
   unique(value.moments.map((item) => item.id), "Narrative Moment id");

package/packages/narrative/src/index.ts

@@ -9,3 +9,6 @@ export {
 } from "./identity.js";
 export { captionDocumentSchema, narrativeExcerptSchema, narrativeMomentSchema, narrativeSchema, narrativeSelectionSchema } from "./schema.js";
 export type * from "./types.js";
+
+export { narrativeAnchorTokenBoundary, narrativeSelectionTokenRange, narrativeTokensForSelection } from "./selection.js";
+export type { NarrativeTokenRange } from "./selection.js";

package/packages/narrative/src/schema.ts

@@ -23,33 +23,6 @@ const semanticAnchor: ValueSchema = { kind: "oneOf", variants: [
     kind: { schema: { kind: "literal", value: "program-end" } },
   }),
 ] };
-export const narrativeSchema: ValueSchema = object({
-  id: { schema: string },
-  segments: { schema: { kind: "array", minItems: 1, items: object({
-    id: { schema: string }, startAnchorId: { schema: string },
-    endAnchorId: { schema: string }, tokenStart: { schema: integer }, tokenEndExclusive: { schema: integer },
-  }) } },
-  tokens: { schema: { kind: "array", items: object({
-    id: { schema: string }, segmentId: { schema: string },
-    startAnchorId: { schema: string }, endAnchorId: { schema: string },
-    text: { schema: string }, normalized: { schema: string },
-  }) } },
-  turns: { schema: { kind: "array", items: object({
-    id: { schema: string }, segmentId: { schema: string }, role: { schema: string, optional: true },
-    tokenStart: { schema: integer }, tokenEndExclusive: { schema: integer },
-  }) } },
-  selections: { schema: { kind: "array", items: object({
-    id: { schema: string }, startAnchorId: { schema: string }, endAnchorId: { schema: string },
-  }) } },
-  moments: { schema: { kind: "array", items: object({
-    id: { schema: string }, anchorId: { schema: string },
-  }) } },
-  semanticIndex: { schema: object({
-
-    anchors: { schema: { kind: "array", minItems: 2, items: semanticAnchor } },
-  }) },
-});
-
 export const narrativeExcerptSchema: ValueSchema = object({
   narrativeId: { schema: string },
   kind: { schema: { kind: "literal", value: "segment" } }, id: { schema: string },
@@ -77,6 +50,34 @@ export const captionDocumentSchema: ValueSchema = object({
   words: { schema: { kind: "array", items: captionDisplayWord } },
   cueBreaks: { schema: { kind: "array", items: captionCueBreak } },
 });
+export const narrativeSchema: ValueSchema = object({
+  id: { schema: string },
+  caption: { schema: captionDocumentSchema },
+  segments: { schema: { kind: "array", minItems: 1, items: object({
+    id: { schema: string }, startAnchorId: { schema: string },
+    endAnchorId: { schema: string }, tokenStart: { schema: integer }, tokenEndExclusive: { schema: integer },
+  }) } },
+  tokens: { schema: { kind: "array", items: object({
+    id: { schema: string }, segmentId: { schema: string },
+    startAnchorId: { schema: string }, endAnchorId: { schema: string },
+    text: { schema: string }, normalized: { schema: string },
+  }) } },
+  turns: { schema: { kind: "array", items: object({
+    id: { schema: string }, segmentId: { schema: string }, role: { schema: string, optional: true },
+    tokenStart: { schema: integer }, tokenEndExclusive: { schema: integer },
+  }) } },
+  selections: { schema: { kind: "array", items: object({
+    id: { schema: string }, startAnchorId: { schema: string }, endAnchorId: { schema: string },
+  }) } },
+  moments: { schema: { kind: "array", items: object({
+    id: { schema: string }, anchorId: { schema: string },
+  }) } },
+  semanticIndex: { schema: object({
+
+    anchors: { schema: { kind: "array", minItems: 2, items: semanticAnchor } },
+  }) },
+});
+
 export const narrativeMomentSchema: ValueSchema = object({
   narrativeId: { schema: string },
   id: { schema: string },

package/packages/narrative/src/selection.ts

@@ -0,0 +1,52 @@
+import type { Narrative, NarrativeSelection, NarrativeSelectionRef, NarrativeToken } from "./types.js";
+
+/** A range in authored token order, independent of material placement and frame timing. */
+export type NarrativeTokenRange = {
+  readonly narrativeId: string;
+  readonly tokenStart: number;
+  readonly tokenEndExclusive: number;
+};
+
+/** Resolve a semantic anchor to a boundary in the authored token sequence. */
+export function narrativeAnchorTokenBoundary(narrative: Narrative, anchorId: string): number {
+  const anchor = narrative.semanticIndex.anchors.find((item) => item.id === anchorId);
+  if (anchor === undefined) throw new Error(`Narrative ${narrative.id} has no anchor ${anchorId}.`);
+  if (anchor.kind === "program-start") return 0;
+  if (anchor.kind === "program-end") return narrative.tokens.length;
+  const segment = narrative.segments.find((item) => item.id === anchor.segmentId);
+  if (segment === undefined) throw new Error(`Anchor ${anchorId} has no authored Segment.`);
+  if (anchor.kind === "segment-start") return segment.tokenStart;
+  if (anchor.kind === "segment-end") return segment.tokenEndExclusive;
+  const index = narrative.tokens.findIndex((item) => item.id === anchor.tokenId);
+  if (index < 0) throw new Error(`Anchor ${anchorId} has no authored token.`);
+  return anchor.kind === "token-start" ? index : index + 1;
+}
+
+export function narrativeSelectionTokenRange(
+  narrative: Narrative,
+  selection: NarrativeSelection | NarrativeSelectionRef,
+): NarrativeTokenRange {
+  if ("narrativeId" in selection && selection.narrativeId !== narrative.id) {
+    throw new Error(`Selection ${selection.id} belongs to another Narrative.`);
+  }
+  const anchors = narrative.semanticIndex.anchors;
+  const start = anchors.findIndex((item) => item.id === selection.startAnchorId);
+  const end = anchors.findIndex((item) => item.id === selection.endAnchorId);
+  if (start < 0 || end < 0 || end < start) {
+    throw new Error(`Selection ${selection.id} has invalid authored anchor order.`);
+  }
+  return {
+    narrativeId: narrative.id,
+    tokenStart: narrativeAnchorTokenBoundary(narrative, selection.startAnchorId),
+    tokenEndExclusive: narrativeAnchorTokenBoundary(narrative, selection.endAnchorId),
+  };
+}
+
+/** Select content without consulting a Timeline or reconstructing prose from token strings. */
+export function narrativeTokensForSelection(
+  narrative: Narrative,
+  selection: NarrativeSelection | NarrativeSelectionRef,
+): readonly NarrativeToken[] {
+  const range = narrativeSelectionTokenRange(narrative, selection);
+  return narrative.tokens.slice(range.tokenStart, range.tokenEndExclusive);
+}

package/packages/narrative/src/types.ts

@@ -113,12 +113,14 @@ export type SemanticAnchor =
       readonly tokenId?: string;
     };
 
+/** Complete authored content; local views are projections of this value. */
 export type Narrative = {
   /** Author-visible `<script id>`; every exported semantic view retains it. */
   readonly id: string;
   readonly segments: readonly NarrativeSegment[];
   readonly tokens: readonly NarrativeToken[];
   readonly turns: readonly NarrativeTurn[];
+  readonly caption: CaptionDocument;
   readonly selections: readonly NarrativeSelection[];
   readonly moments: readonly NarrativeMoment[];
   readonly semanticIndex: {

package/packages/package-loader-node/README.md

@@ -21,3 +21,33 @@ It does not use a CommonJS root export as evidence that a package is installed:
 import-only and resource-only packages are valid. The active Distribution owns `@hypit/*`;
 Distribution code may use upstream dependencies from the machine npm home, while project packages
 continue to resolve their own dependencies from the project.
+
+The machine home stores `<package-name>/<exact-version>/node_modules`, with the importing package's
+ordinary `dependencies` selecting the version. Loading a second Distribution does not replace an
+existing release. ESM, resource and executable lookup use the same selection; project dependencies
+retain ordinary project ownership. There is no inventory or source-content matching.
+
+Runtime declaration discovery may use `deferExternalDependencies` to inspect capabilities and
+Managed Programs before their execution tools are prepared. Actual JavaScript imports still follow
+Node resolution and must be available. A selected Profile remains a valid package configuration;
+Endpoint scoping is not permission to execute an invalid or absent Provider implementation.
+
+## Execution-owned module scopes
+
+`NodePackageLoadOptions.importModule` lets the Host own module lifetime while package selection and
+contribution validation stay here. The default uses ordinary process imports. The local execution
+Host supplies a `NodeModuleScope` for each Build: selected project packages and their transitive
+JavaScript dependencies receive scope-local module identities. The installed `@hypit/*` Distribution
+remains shared process code. Registries and configured adapter instances are still created per Build.
+
+`NodeModuleScope` uses Node resolution/loading hooks and transpiles scope-owned TypeScript/TSX. Its CommonJS
+bridge has a scope-owned module cache, Node-style named-export discovery and synchronous evaluation;
+Node's VM dynamic-import support is enabled only for the execution carrier. Public paths such as
+`import.meta.url`, `__filename` and relative asset reads remain real filesystem locations. Module
+identity URLs are internal names; no copied source directory is created. Closing a scope drops its
+live lookup and CommonJS table; the Host retires an empty carrier to release Node's ESM cache.
+
+This is trusted execution, not a sandbox. Builtins, native libraries and process-global state
+(including `process.cwd()` and `process.env`) remain shared. Existing module bindings do not change
+under an active Build; a file or dependency first
+read later uses ordinary filesystem semantics. Scoped loading does not make a project tree immutable.