@hypit/hypit 0.1.3 → 0.1.5

package/dist/public/speech.d.ts

@@ -289,6 +289,45 @@ type NarrativeMoment = {
     /** The exact semantic anchor chosen by the author Surface's affinity syntax. */
     readonly anchorId: string;
 };
+/** One author-visible word surface. Punctuation owned by the surface is preserved. */
+type CaptionDisplayWord = {
+    readonly id: string;
+    readonly unitId: string;
+    readonly segmentId: string;
+    readonly turnId: string;
+    readonly role?: string;
+    readonly text: string;
+    /** Reserved for Script-native word attributes; empty until an inline Mark is authored. */
+    readonly attributes: readonly CaptionWordAttribute[];
+};
+type CaptionWordAttributeValue = string | number | boolean;
+type CaptionWordAttribute = {
+    readonly name: string;
+    readonly value: CaptionWordAttributeValue;
+};
+/** The smallest author-declared N:M display-to-speech correspondence unit. */
+type CaptionAlignmentUnit = {
+    readonly id: string;
+    readonly segmentId: string;
+    readonly turnId: string;
+    readonly role?: string;
+    readonly wordIds: readonly string[];
+    /** Speech tokens are retained here so Caption can project a Narrative Selection without frames. */
+    readonly sourceTokenIds: readonly string[];
+};
+type CaptionCueBreak = {
+    /** The Cue boundary is after this complete Alignment Unit. */
+    readonly afterUnitId: string;
+};
+/** Complete Script-owned Caption truth. It contains no frame or measured timing facts. */
+type CaptionDocument = {
+    /** Author-visible `<script id>` that owns this caption projection. */
+    readonly narrativeId: string;
+    readonly id: string;
+    readonly units: readonly CaptionAlignmentUnit[];
+    readonly words: readonly CaptionDisplayWord[];
+    readonly cueBreaks: readonly CaptionCueBreak[];
+};
 type SemanticAnchor = {
     readonly id: "program:start";
     readonly kind: "program-start";
@@ -305,12 +344,14 @@ type SemanticAnchor = {
     readonly segmentId: string;
     readonly tokenId?: string;
 };
+/** Complete authored content; local views are projections of this value. */
 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/dist/public/studio-adapter.d.ts

@@ -72,11 +72,11 @@ type Range = {
 type StudioTrackFamily = string;
 type StudioIcon = "brand" | "captions" | "component" | "layers" | "ranking" | "text" | "timeline" | "video" | "waveform";
 /** Studio-owned visual palette. Domain families never become CSS selectors. */
-type StudioTimelineTone = "blue" | "green" | "teal" | "violet" | "magenta" | "orange" | "orange-muted" | "neutral";
+type StudioTimelineTone = "blue" | "blue-muted" | "green" | "green-muted" | "teal" | "violet" | "magenta" | "magenta-muted" | "orange" | "orange-muted" | "neutral";
 type StudioTimelinePresentation = {
     readonly entity: string;
-    /** Studio-owned shell. It never decides whether title, time or body exists. */
-    readonly chrome: "standard" | "group" | "point";
+    /** Studio-owned shell. Compact presents the primary label in one line, with time in details. */
+    readonly chrome: "standard" | "group" | "point" | "compact";
 };
 type StudioTemporalSource = {
     readonly spaceId: string;
@@ -159,6 +159,33 @@ type StudioTemporalBinding = {
 declare const studioParameterControls: readonly ["text", "number", "boolean", "select", "color", "list", "record"];
 type StudioParameterControl = typeof studioParameterControls[number];
 type StudioParameterLanguage = "svml" | "svs" | "svrun";
+/** Data-only choices. Packages supply meaning; Studio owns all option rendering. */
+type StudioParameterOption = string | {
+    readonly value: string | number | boolean;
+    readonly label: string;
+    readonly description?: string;
+    readonly preview?: {
+        readonly kind: "color";
+        readonly color: string;
+    } | {
+        readonly kind: "font";
+        readonly family: string;
+        readonly sample?: string;
+    };
+};
+/** Displayed number = authored number × scale. Suffixes are retained, never converted. */
+type StudioNumberPresentation = {
+    readonly scale?: number;
+    readonly suffixes?: readonly string[];
+    readonly minimum?: number;
+    readonly maximum?: number;
+    readonly step?: number;
+};
+/** Attribute ranges are relative to the owning element's source preimage. */
+type StudioAttributeGroupEdit = {
+    readonly insertionOffset: number;
+    readonly ranges: Readonly<Record<string, Range | null>>;
+};
 /** A real author endpoint. Its existence never implies Inspector visibility. */
 type StudioSourceBinding = {
     readonly id: string;
@@ -181,9 +208,10 @@ type StudioSourceBinding = {
         readonly prefix?: string;
         readonly suffix?: string;
     };
+    readonly attributes?: StudioAttributeGroupEdit;
     readonly disabledReason?: string;
 };
-type StudioInspectorDomain = "where" | "how" | "when";
+type StudioInspectorDomain = "where" | "when" | "how";
 type StudioInspectorPageDeclaration = {
     readonly id: string;
     readonly label: string;
@@ -192,7 +220,7 @@ type StudioInspectorSectionDeclaration = {
     readonly id: string;
     readonly label: string;
 };
-/** One visible, writable field selected from a Companion's source bindings. */
+/** One visible field selected from a Companion's source bindings. */
 type StudioInspectorFieldDeclaration = {
     readonly binding: string;
     readonly label: string;
@@ -203,23 +231,42 @@ type StudioInspectorFieldDeclaration = {
     readonly summary?: string;
     /** Omit when the binding's public schema selects the finite Studio control. */
     readonly control?: StudioParameterControl;
-    readonly options?: readonly string[];
+    readonly options?: readonly StudioParameterOption[];
     readonly unit?: string;
+    readonly number?: StudioNumberPresentation;
+    readonly multiline?: boolean;
+    /** Optional suggested colors, independent of the accepted color value. */
+    readonly swatches?: readonly string[];
 };
-/** Resolved Inspector DTO. Studio renders it and executes its exact source write. */
-type StudioInspectorField = Omit<StudioInspectorFieldDeclaration, "control"> & {
+/** A selected entity's package-owned fact, with no author write endpoint. */
+type StudioInspectorValue = Pick<StudioInspectorFieldDeclaration, "label" | "domain" | "page" | "section" | "summary" | "unit"> & {
+    readonly id: string;
+    readonly value: CanonicalValue;
+};
+/** Display and edit authority are independent of the Where / When / How grouping. */
+type StudioInspectorField = Omit<StudioInspectorFieldDeclaration, "binding" | "control"> & {
+    readonly binding?: string;
     readonly id: string;
     readonly control: StudioParameterControl;
     readonly value: CanonicalValue;
     readonly schema?: ValueSchema;
-    readonly language: StudioParameterLanguage;
-    readonly source: StudioSourceBinding["source"];
+    readonly edit?: {
+        readonly language: StudioParameterLanguage;
+        readonly source: StudioSourceBinding["source"];
+        readonly attributes?: StudioAttributeGroupEdit;
+    };
 };
 /** Companion-owned source allowlist. It contains no editor presentation. */
 type StudioSourceBindingDeclaration = {
     readonly name: string;
     readonly writable?: boolean;
     readonly schema?: ValueSchema;
+    /** Typed value used when this editable attribute is omitted. */
+    readonly fallback?: CanonicalValue | ((authored: Readonly<Record<string, CanonicalValue>>) => CanonicalValue | undefined);
+    /** Compose the referenced object's package-owned parameter Companion. */
+    readonly companion?: boolean;
+    /** Edit these scalar attributes together as one schema-described record. */
+    readonly attributes?: readonly string[];
     /** Optional declaration for the authored element named by a reference. */
     readonly referenced?: readonly StudioSourceBindingDeclaration[];
     /**
@@ -241,7 +288,7 @@ type StudioRecipeBindingDeclaration = {
     /** Domain-owned public Recipe value structure, never editor presentation. */
     readonly schema?: ValueSchema;
     /** Typed public fallback; Studio writes the property only after the author changes it. */
-    readonly fallback?: CanonicalValue;
+    readonly fallback?: CanonicalValue | ((authored: Readonly<Record<string, CanonicalValue>>) => CanonicalValue | undefined);
 };
 type StudioTimelineGesture = "move" | "trim-start" | "trim-end";
 type StudioEditCoordinate = "program-frame" | "semantic-anchor" | "source-frame" | "canvas-pixel" | "normalized-progress";
@@ -308,12 +355,13 @@ type StudioDisplayLayer = {
     readonly layout: "repeat-x" | "cover" | "contain" | "storyboard" | "waveform";
 };
 type StudioEntityDisplay = {
-    /** First row. Studio always places computed time immediately after it. */
+    /** Primary label: a header in standard chrome, the complete single-line content in compact chrome. */
     readonly title: string;
     /** Ordered back-to-front body layers. */
     readonly layers: readonly StudioDisplayLayer[];
 };
 type StudioLaneDescription = {
+    /** Height of this single timeline lane; overlapping entities share it. */
     readonly heightPx: number;
     readonly groupId?: string;
     readonly attachedTo?: string;
@@ -469,7 +517,7 @@ type StudioResolvedTrack = {
     readonly surfacePreview?: StudioMaterialPreview;
     readonly value: unknown;
 };
-type StudioViewRole = "semantic-track" | "supporting-value" | "track";
+type StudioViewRole = "timeline" | "supporting-value" | "track";
 type StudioSpan = {
     readonly id: string;
     /** Exact public terminal provenance; never inferred from id syntax. */
@@ -484,17 +532,25 @@ type StudioEntityDraft = {
     readonly display: StudioEntityDisplay;
     readonly startFrame: number;
     readonly endFrameExclusive: number;
+    /** Back-to-front timeline order. Ties preserve projection order. Selection raises only the timeline item. */
     readonly stackOrder: number;
     readonly elementRange?: Range;
     readonly markerId?: string;
     readonly presentId?: string;
+    /** Rendered parts belonging to this entity, including phases beyond its editable timeline interval. */
     readonly renderIds?: readonly string[];
     /** Resolved author references that differ per derived entity, such as one Cue's actual Style. */
     readonly parameterReferences?: Readonly<Record<string, string>>;
+    /** Disjoint displayed intervals belonging to one selectable author entity. */
+    readonly selectionGroup?: string;
+    /** Deliberately selected facts, presented beside bound Inspector fields. */
+    readonly inspector?: readonly StudioInspectorValue[];
     readonly presentation?: StudioTimelinePresentation;
     readonly temporal?: StudioTemporalLineage;
-    /** Studio-local lane partition; omitted means the root lane. */
+    /** Independent child Track partition; omitted means this Track. */
     readonly lane?: string;
+    /** Internal band of this Track; mutually exclusive with lane. */
+    readonly band?: string;
 };
 type StudioTrackCompanionContext = {
     readonly track: StudioResolvedTrack;
@@ -527,6 +583,8 @@ type StudioTrackCompanion = {
         readonly source: "surface-preview";
     };
     readonly attachments?: readonly StudioLaneAttachment[];
+    /** Internal bands share this Track’s label and contain independently timed entities. */
+    readonly bands?: readonly StudioTrackBand[];
     /** Same-Surface output values required to project this Track for Studio. */
     readonly requiredValues?: readonly string[];
     readonly lane?: StudioLaneDescription;
@@ -536,11 +594,22 @@ type StudioTrackCompanion = {
     readonly inspector?: readonly StudioInspectorFieldDeclaration[];
     readonly project?: (context: StudioTrackCompanionContext) => readonly StudioEntityDraft[];
 };
+/** Parameters owned by an authored object, independently of its consumers. */
+type StudioParameterCompanion = {
+    readonly id: string;
+    readonly match: {
+        readonly module: ModuleRef;
+        readonly surface: string;
+    };
+    readonly bindings: readonly StudioSourceBindingDeclaration[];
+    readonly inspector: readonly StudioInspectorFieldDeclaration[];
+};
 type StudioCompanionContribution = {
     readonly format: "hypit.studio-companions@1";
     readonly tracks: readonly StudioTrackCompanion[];
     readonly films?: readonly StudioFilmCompanion[];
     readonly scripts?: readonly StudioScriptCompanion[];
+    readonly parameters?: readonly StudioParameterCompanion[];
 };
 /** Declarative Film boundary. Studio follows only the references named here. */
 type StudioFilmCompanion = {
@@ -597,6 +666,12 @@ type StudioScriptAdjustment = {
     readonly id: string;
     readonly anchorId: string;
 };
+type StudioScriptProjection = Pick<StudioSemanticTimeline, "anchors" | "segments" | "tokens" | "selections" | "moments">;
+type StudioScriptProjectionInput = {
+    readonly source: StudioScriptSourceMap;
+    readonly values: readonly StudioObservedValue[];
+    readonly anchors: ReadonlyMap<string, number>;
+};
 /** Script grammar companion. It owns source observation and semantic inverse edits. */
 type StudioScriptCompanion = {
     readonly id: string;
@@ -614,6 +689,7 @@ type StudioScriptCompanion = {
         readonly nextOffset?: number;
         readonly attributes: Readonly<Record<string, unknown>>;
     }) => Omit<StudioScriptSourceMap, "companion"> | undefined;
+    readonly project?: (input: StudioScriptProjectionInput) => StudioScriptProjection;
     readonly adjust: (input: {
         readonly sourceName: string;
         readonly source: string;
@@ -629,11 +705,13 @@ declare function createStudioCompanionHostFacet(input: {
     readonly tracks?: readonly StudioTrackCompanion[];
     readonly films?: readonly StudioFilmCompanion[];
     readonly scripts?: readonly StudioScriptCompanion[];
+    readonly parameters?: readonly StudioParameterCompanion[];
 }): StudioCompanionHostFacet;
 type StudioPackageContribution = {
     readonly tracks: readonly StudioTrackCompanion[];
     readonly films: readonly StudioFilmCompanion[];
     readonly scripts: readonly StudioScriptCompanion[];
+    readonly parameters: readonly StudioParameterCompanion[];
 };
 declare function studioContributionFromPackage(owner: string, facets: readonly HostFacet[]): StudioPackageContribution;
 /**
@@ -641,6 +719,17 @@ declare function studioContributionFromPackage(owner: string, facets: readonly H
  * The executable facet cannot choose or impersonate its physical owner.
  */
 declare function studioTrackCompanionsFromPackage(owner: string, facets: readonly HostFacet[]): readonly StudioTrackCompanion[];
+/** A contiguous internal strip, not a child Track. Declaration order is visual order. */
+type StudioTrackBand = {
+    readonly id: string;
+    readonly placement: "before" | "after";
+    readonly heightPx: number;
+    /** Label bands use the whole strip for each entity's title; content bands retain its chrome. */
+    readonly display: "label" | "content";
+    readonly tone?: StudioTimelineTone;
+    readonly bindings?: readonly StudioSourceBindingDeclaration[];
+    readonly inspector?: readonly StudioInspectorFieldDeclaration[];
+};
 type StudioLaneAttachment = {
     readonly id: string;
     readonly family: StudioTrackFamily;
@@ -670,6 +759,8 @@ declare function authoredChildFor(context: StudioTrackCompanionContext, authored
 declare function temporalLineageFor(context: StudioTrackCompanionContext, subjectId: string, input?: string): StudioTemporalLineage | undefined;
 /** Unique semantic author identity carried by one projection, when there is one. */
 declare function temporalSemanticSource(lineage: StudioTemporalLineage | undefined): StudioTemporalSource | undefined;
+/** A package chooses which source references can name an otherwise unnamed Item. */
+declare function authoredItemTitle(context: StudioTrackCompanionContext, authoredId: string, sourceTypes: readonly TypeRef[], sourceAttributes: readonly string[]): string;
 declare function childEntities(context: StudioTrackCompanionContext, items: readonly {
     /** Exact identity of the projected domain item consumed by Temporal/renderer bindings. */
     readonly id: string;
@@ -682,5 +773,5 @@ declare function childEntities(context: StudioTrackCompanionContext, items: read
     readonly sourceTypes?: readonly TypeRef[];
 }[], entity: StudioTimelinePresentation["entity"], chrome: StudioTimelinePresentation["chrome"]): readonly StudioEntityDraft[];
 
-export { artifactPreview, authoredChildFor, childEntities, createStudioCompanionHostFacet, createStudioTrackCompanionHostFacet, previewLayer, requiredReferencedValue, requiredSurfaceValue, sameSurfaceValue, studioCompanionHostAbi, studioContributionFromPackage, studioParameterControls, studioTrackCompanionsFromPackage, temporalBindingsFor, temporalLineageFor, temporalSemanticSource, textLayer };
-export type { Range, StudioCandidateProvenance, StudioCompanionContribution, StudioCompanionHostFacet, StudioDisplayLayer, StudioEditCoordinate, StudioEditHandle, StudioEditSource, StudioEditSourceRole, StudioEntityDisplay, StudioEntityDraft, StudioFilmCompanion, StudioIcon, StudioInspectorDomain, StudioInspectorField, StudioInspectorFieldDeclaration, StudioInspectorPageDeclaration, StudioInspectorSectionDeclaration, StudioLaneAttachment, StudioLaneDescription, StudioMaterialPreview, StudioObservedValue, StudioPackageContribution, StudioParameterControl, StudioParameterLanguage, StudioPlacement, StudioPlacementChild, StudioPreviewSource, StudioRecipeBindingDeclaration, StudioRecipeReferenceBindingDeclaration, StudioResolvedTrack, StudioScriptAdjustment, StudioScriptCompanion, StudioScriptSourceMap, StudioSemanticAnchor, StudioSemanticEditTarget, StudioSemanticSegment, StudioSemanticTimeline, StudioSemanticToken, StudioSnapTarget, StudioSourceBinding, StudioSourceBindingDeclaration, StudioSpan, StudioTemporalAuthority, StudioTemporalBinding, StudioTemporalConsumer, StudioTemporalConsumerInput, StudioTemporalInstantProjection, StudioTemporalLineage, StudioTemporalPhase, StudioTemporalProjection, StudioTemporalSource, StudioTemporalWindowProjection, StudioTimelineGesture, StudioTimelinePresentation, StudioTimelineTone, StudioTrackCompanion, StudioTrackCompanionContext, StudioTrackFamily, StudioTrackTrace, StudioViewRole };
+export { artifactPreview, authoredChildFor, authoredItemTitle, childEntities, createStudioCompanionHostFacet, createStudioTrackCompanionHostFacet, previewLayer, requiredReferencedValue, requiredSurfaceValue, sameSurfaceValue, studioCompanionHostAbi, studioContributionFromPackage, studioParameterControls, studioTrackCompanionsFromPackage, temporalBindingsFor, temporalLineageFor, temporalSemanticSource, textLayer };
+export type { Range, StudioAttributeGroupEdit, StudioCandidateProvenance, StudioCompanionContribution, StudioCompanionHostFacet, StudioDisplayLayer, StudioEditCoordinate, StudioEditHandle, StudioEditSource, StudioEditSourceRole, StudioEntityDisplay, StudioEntityDraft, StudioFilmCompanion, StudioIcon, StudioInspectorDomain, StudioInspectorField, StudioInspectorFieldDeclaration, StudioInspectorPageDeclaration, StudioInspectorSectionDeclaration, StudioInspectorValue, StudioLaneAttachment, StudioLaneDescription, StudioMaterialPreview, StudioNumberPresentation, StudioObservedValue, StudioPackageContribution, StudioParameterCompanion, StudioParameterControl, StudioParameterLanguage, StudioParameterOption, StudioPlacement, StudioPlacementChild, StudioPreviewSource, StudioRecipeBindingDeclaration, StudioRecipeReferenceBindingDeclaration, StudioResolvedTrack, StudioScriptAdjustment, StudioScriptCompanion, StudioScriptProjection, StudioScriptProjectionInput, StudioScriptSourceMap, StudioSemanticAnchor, StudioSemanticEditTarget, StudioSemanticSegment, StudioSemanticTimeline, StudioSemanticToken, StudioSnapTarget, StudioSourceBinding, StudioSourceBindingDeclaration, StudioSpan, StudioTemporalAuthority, StudioTemporalBinding, StudioTemporalConsumer, StudioTemporalConsumerInput, StudioTemporalInstantProjection, StudioTemporalLineage, StudioTemporalPhase, StudioTemporalProjection, StudioTemporalSource, StudioTemporalWindowProjection, StudioTimelineGesture, StudioTimelinePresentation, StudioTimelineTone, StudioTrackBand, StudioTrackCompanion, StudioTrackCompanionContext, StudioTrackFamily, StudioTrackTrace, StudioViewRole };

package/dist/public/temporal-markup.d.ts

@@ -203,59 +203,26 @@ type SurfaceAttributeVocabulary = {
 };
 
 type TemporalContext = {
-    readonly semantic?: SurfaceResolvedReference;
-    readonly space?: SurfaceResolvedReference;
+    readonly timeline: SurfaceResolvedReference;
 };
 declare const temporalContextAttributeVocabulary: readonly [{
-    readonly name: "semantic";
+    readonly name: "timeline";
     readonly kind: "reference";
-    readonly required: false;
+    readonly required: true;
     readonly accepts: readonly [{
         module: {
-            readonly name: "@hypit/semantic-track";
+            readonly name: "@hypit/timeline";
             readonly version: "1";
         };
         name: string;
     }];
-    readonly summary: "Uses the performance's time axis and resolves Script Selections and Moments.";
-}, {
-    readonly name: "space";
-    readonly kind: "reference";
-    readonly required: false;
-    readonly accepts: readonly [{
-        module: {
-            readonly name: "@hypit/program-space";
-            readonly version: "1";
-        };
-        name: string;
-    }];
-    readonly summary: "Uses a declared film time axis for authored animation. Supply semantic or space.";
+    readonly summary: "The complete film Timeline, with any placed material and semantic anchors.";
 }];
-/** Select the author's film time source. */
+/** One author-facing Timeline; projections share its range and evidence. */
 declare function resolveTemporalContext(input: {
     readonly element: StructuredElement;
     readonly resolveReference: (path: string) => SurfaceResolvedReference | undefined;
 }): TemporalContext;
-/** Give consumers a ProgramSpace while preserving semantic context for word-bound projections. */
-declare function createTemporalSpace(input: TemporalContext & {
-    readonly id: string;
-    readonly element: StructuredElement;
-}): {
-    records: never[];
-    components: {
-        id: string;
-        fragment: string;
-        inputs: {
-            semantic: AuthorValueRef;
-        };
-        outputs: {
-            space: string;
-        };
-        range: SourceRange;
-    }[];
-    fragments: GraphFragment[];
-    space: SurfaceResolvedReference;
-};
 
 /** Exact author duration. Decimal source spelling is reduced before reaching this value. */
 type TemporalDuration = {
@@ -321,8 +288,7 @@ declare function createTemporalWindowProjection(input: {
     readonly id: string;
     readonly subjectId?: string;
     readonly element: StructuredElement;
-    readonly semantic?: SurfaceResolvedReference;
-    readonly space?: SurfaceResolvedReference;
+    readonly timeline: SurfaceResolvedReference;
     readonly resolveReference: ResolveReference;
 }): TemporalMarkupProjection;
 /** Decode a semantic reference, an authored at time, or a projected instant expression. */
@@ -330,8 +296,7 @@ declare function createTemporalInstantProjection(input: {
     readonly id: string;
     readonly subjectId?: string;
     readonly element: StructuredElement;
-    readonly semantic?: SurfaceResolvedReference;
-    readonly space?: SurfaceResolvedReference;
+    readonly timeline: SurfaceResolvedReference;
     readonly resolveReference: ResolveReference;
     readonly semanticAttribute?: string;
     readonly boundaryAttribute?: string;
@@ -339,5 +304,5 @@ declare function createTemporalInstantProjection(input: {
     readonly projectedAttribute?: string | false;
 }): TemporalMarkupProjection;
 
-export { createTemporalInstantProjection, createTemporalSpace, createTemporalWindowProjection, parseTemporalDuration, parseTemporalInstant, resolveTemporalContext, temporalContextAttributeVocabulary, temporalInstantAttributeNames, temporalInstantAttributeVocabulary, temporalWindowAttributeNames, temporalWindowAttributeVocabulary };
+export { createTemporalInstantProjection, createTemporalWindowProjection, parseTemporalDuration, parseTemporalInstant, resolveTemporalContext, temporalContextAttributeVocabulary, temporalInstantAttributeNames, temporalInstantAttributeVocabulary, temporalWindowAttributeNames, temporalWindowAttributeVocabulary };
 export type { TemporalContext, TemporalMarkupProjection };

package/dist/public/temporal.d.ts

@@ -139,6 +139,22 @@ type NarrativeExcerpt = {
     readonly tokenEndExclusive: number;
 };
 
+type ProgramClock = {
+    readonly frameRate: {
+        readonly numerator: number;
+        readonly denominator: number;
+    };
+};
+type ProgramSpace = {
+    /** Author-visible identity of this film time axis. */
+    readonly id: string;
+    readonly durationSec: number;
+    readonly frameRate: {
+        readonly numerator: number;
+        readonly denominator: number;
+    };
+};
+
 type MediaRational = {
     readonly numerator: number;
     readonly denominator: number;
@@ -191,27 +207,14 @@ type SemanticTake = {
     }[];
 };
 
-type SemanticTrackItem = {
+type TimelineItem = {
     readonly take: SemanticTake;
+    readonly startFrame: number;
 };
-/**
- * The continuous program skeleton. Every item is a real SemanticTake and the
- * global frame domain is exactly their prefix sum: no gap or empty item exists.
- */
-type SemanticTrack = {
-    readonly id: string;
-    readonly narrativeId: string;
-    readonly items: readonly SemanticTrackItem[];
-};
-
-type ProgramSpace = {
-    /** Author-visible identity of this film time axis. */
-    readonly id: string;
-    readonly durationSec: number;
-    readonly frameRate: {
-        readonly numerator: number;
-        readonly denominator: number;
-    };
+/** One complete film time range, with prepared material placed where it belongs. */
+type Timeline = ProgramSpace & {
+    readonly narrativeId?: string;
+    readonly items: readonly TimelineItem[];
 };
 
 type FramePoint = {
@@ -347,10 +350,10 @@ type TriggeredSchedule = {
     readonly exclusive: readonly FrameSpan[];
 };
 
-declare function locateSelection(semantic: SemanticTrack, selection: NarrativeSelectionRef): LocatedSelection;
-declare function locateMoment(semantic: SemanticTrack, moment: NarrativeMomentRef): LocatedMoment;
-declare function locateProgram(semantic: SemanticTrack): LocatedProgram;
-declare function locateSegment(semantic: SemanticTrack, segment: NarrativeExcerpt): LocatedSegment;
+declare function locateSelection(semantic: Timeline, selection: NarrativeSelectionRef): LocatedSelection;
+declare function locateMoment(semantic: Timeline, moment: NarrativeMomentRef): LocatedMoment;
+declare function locateProgram(semantic: Timeline): LocatedProgram;
+declare function locateSegment(semantic: Timeline, segment: NarrativeExcerpt): LocatedSegment;
 
 type TemporalConsumption = {
     readonly subjectId: string;
@@ -370,7 +373,7 @@ declare function projectTemporalInstant(projection: TemporalInstantExpression, e
 declare function projectSelectionInstant(input: {
     readonly itemId: string;
     readonly subjectId: string;
-    readonly semantic: SemanticTrack;
+    readonly timeline: Timeline;
     readonly selection: NarrativeSelectionRef;
     readonly projection: TemporalInstantExpression;
     readonly authority: TemporalInstantSpec["authority"];
@@ -378,7 +381,7 @@ declare function projectSelectionInstant(input: {
 declare function projectMomentInstant(input: {
     readonly itemId: string;
     readonly subjectId: string;
-    readonly semantic: SemanticTrack;
+    readonly timeline: Timeline;
     readonly moment: NarrativeMomentRef;
     readonly projection: TemporalInstantExpression;
     readonly authority: TemporalInstantSpec["authority"];
@@ -386,14 +389,14 @@ declare function projectMomentInstant(input: {
 declare function projectProgramInstant(input: {
     readonly itemId: string;
     readonly subjectId: string;
-    readonly space: ProgramSpace;
+    readonly timeline: Timeline;
     readonly projection: TemporalInstantExpression;
     readonly authority: TemporalInstantSpec["authority"];
 }): ProjectedInstant;
 declare function projectSegmentInstant(input: {
     readonly itemId: string;
     readonly subjectId: string;
-    readonly semantic: SemanticTrack;
+    readonly timeline: Timeline;
     readonly segment: NarrativeExcerpt;
     readonly projection: TemporalInstantExpression;
     readonly authority: TemporalInstantSpec["authority"];
@@ -410,6 +413,12 @@ declare function resolveTriggeredSchedule(input: {
 /** Quantize one non-negative authored duration into the canonical sample domain exactly once. */
 declare function temporalDurationInSamples(duration: TemporalDuration, space: ProgramSpace, sampleRate?: number): number;
 
+type Rational = {
+    readonly numerator: bigint;
+    readonly denominator: bigint;
+};
+declare function durationInFrames(duration: TemporalDuration, space: ProgramClock): Rational;
+
 declare const temporalModuleRef: {
     readonly name: "@hypit/temporal";
     readonly version: "1";
@@ -493,5 +502,5 @@ declare const temporalInstantSchema: ValueSchema;
 declare const temporalWindowSpecSchema: ValueSchema;
 declare const temporalWindowSchema: ValueSchema;
 
-export { assertTemporalInstantFor, assertTemporalWindowFor, assertWindowRelation, composeTemporalWindow, locateMoment, locateProgram, locateSegment, locateSelection, projectMomentInstant, projectProgramInstant, projectSegmentInstant, projectSelectionInstant, projectTemporalInstant, resolveTriggeredSchedule, temporalDependency, temporalDurationInSamples, temporalInstantSchema, temporalInstantSpecSchema, temporalManifest, temporalModuleRef, temporalProducers, temporalTypes, temporalWindowSchema, temporalWindowSpecSchema };
+export { assertTemporalInstantFor, assertTemporalWindowFor, assertWindowRelation, composeTemporalWindow, durationInFrames, locateMoment, locateProgram, locateSegment, locateSelection, projectMomentInstant, projectProgramInstant, projectSegmentInstant, projectSelectionInstant, projectTemporalInstant, resolveTriggeredSchedule, temporalDependency, temporalDurationInSamples, temporalInstantSchema, temporalInstantSpecSchema, temporalManifest, temporalModuleRef, temporalProducers, temporalTypes, temporalWindowSchema, temporalWindowSpecSchema };
 export type { FramePoint, FrameSpan, LocatedMoment, LocatedProgram, LocatedSegment, LocatedSelection, ProjectedInstant, ProjectedWindow, TemporalConsumption, TemporalDuration, TemporalInstant, TemporalInstantAuthority, TemporalInstantExpression, TemporalInstantSpec, TemporalSource, TemporalWindow, TemporalWindowSpec, TriggerPoint, TriggeredSchedule, WindowRelation };