@hypit/hypit 0.0.1 → 0.1.0

package/dist/public/semantic-track.d.ts

@@ -0,0 +1,418 @@
+/** Opaque identity for one admitted byte resource. Equal bytes may have different identities. */
+type ResourceId = `res_${string}`;
+type RecordId = string;
+type StepId = string;
+type CommandId = string;
+type ModuleRef = {
+    readonly name: string;
+    readonly version: string;
+};
+/**
+ * A Type is its owning Module and its name, and nothing else is compared. Two Types whose values
+ * carry identical shapes are distinct, so one is refused where the other is declared — there is no
+ * structural fallback to fall back to.
+ */
+type TypeRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+type ProducerRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+type CapabilityRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+
+type CanonicalValue = null | boolean | number | string | readonly CanonicalValue[] | {
+    readonly [key: string]: CanonicalValue;
+};
+type BlobRef = {
+    readonly kind: "blob";
+    /** One admitted resource instance. Equal bytes admitted twice keep distinct identities. */
+    readonly resource: ResourceId;
+    readonly size: number;
+    readonly mediaType: string;
+};
+type StoredValue = {
+    readonly kind: "inline";
+    readonly value: CanonicalValue;
+} | BlobRef;
+type ValueSchema = {
+    readonly kind: "null";
+} | {
+    readonly kind: "boolean";
+} | {
+    readonly kind: "number";
+    readonly integer?: boolean;
+    readonly minimum?: number;
+    readonly maximum?: number;
+} | {
+    readonly kind: "string";
+    readonly enum?: readonly string[];
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    /** UI-neutral semantic format shared by authoring, validation and tools. */
+    readonly format?: "color";
+} | {
+    readonly kind: "literal";
+    readonly value: CanonicalValue;
+} | {
+    readonly kind: "array";
+    readonly items: ValueSchema;
+    readonly minItems?: number;
+    readonly maxItems?: number;
+} | {
+    readonly kind: "object";
+    readonly fields: Readonly<Record<string, ObjectFieldSchema>>;
+    readonly allowUnknown?: boolean;
+} | {
+    readonly kind: "oneOf";
+    readonly variants: readonly ValueSchema[];
+} | {
+    readonly kind: "blob";
+    readonly mediaTypes?: readonly string[];
+    readonly maxBytes?: number;
+};
+type ObjectFieldSchema = {
+    readonly schema: ValueSchema;
+    readonly optional?: boolean;
+};
+
+type ModuleDependency = {
+    readonly module: ModuleRef;
+};
+type TypeDeclaration = {
+    readonly name: string;
+};
+type PortDeclaration = {
+    readonly name: string;
+    readonly type: TypeRef;
+};
+type NeedPortDeclaration = {
+    readonly name: string;
+    readonly capability: CapabilityRef;
+    readonly returns: TypeRef;
+};
+type CapabilityDeclaration = {
+    readonly name: string;
+    readonly returns: TypeRef;
+};
+type ProducerDeclaration = {
+    readonly name: string;
+    readonly inputs: readonly PortDeclaration[];
+    readonly outputs: readonly PortDeclaration[];
+    readonly needs: readonly NeedPortDeclaration[];
+};
+type ModuleManifest = {
+    readonly format: "hypit.module@1";
+    readonly name: string;
+    readonly version: string;
+    readonly dependencies: readonly ModuleDependency[];
+    readonly types: readonly TypeDeclaration[];
+    readonly capabilities: readonly CapabilityDeclaration[];
+    readonly producers: readonly ProducerDeclaration[];
+};
+
+/** One typed value in the graph; semantic validation happens at the Host admission boundary. */
+type TypedRecord = {
+    readonly id: RecordId;
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+};
+type InvokeProducerCommand = {
+    readonly kind: "invoke-producer";
+    readonly id: CommandId;
+    readonly step: StepId;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, RecordId>>;
+};
+
+type TypeValidatorContext = {
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+};
+/**
+ * Pure compute context. Artifact bytes, credentials, network and stores are deliberately absent;
+ * those effects must cross an explicit Need into a Provider.
+ */
+type ProducerHandlerContext = {
+    readonly command: InvokeProducerCommand;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, TypedRecord>>;
+};
+
+declare const semanticTrackComponent: {
+    producers: ({
+        producer: {
+            module: {
+                readonly name: "@hypit/semantic-track";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ inputs }: ProducerHandlerContext) => {
+            outputs: {
+                space: {
+                    kind: "inline";
+                    value: CanonicalValue;
+                };
+            };
+            needs: {};
+        };
+    } | {
+        producer: {
+            module: {
+                readonly name: "@hypit/semantic-track";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ inputs }: ProducerHandlerContext) => {
+            outputs: {
+                audio: {
+                    kind: "inline";
+                    value: CanonicalValue;
+                };
+            };
+            needs: {};
+        };
+    })[];
+    validators: {
+        type: {
+            module: {
+                readonly name: "@hypit/semantic-track";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ value }: TypeValidatorContext) => void;
+    }[];
+};
+
+type MediaRational = {
+    readonly numerator: number;
+    readonly denominator: number;
+};
+type SynchronizedMedia = {
+    readonly timeline: {
+        readonly frameRate: MediaRational;
+        readonly frameCount: number;
+    };
+    readonly visual?: {
+        readonly artifact: BlobRef;
+        readonly width: number;
+        readonly height: number;
+    };
+    readonly audio?: {
+        readonly artifact: BlobRef;
+    };
+};
+
+/** One authored Script token located in one normalized Take's local frame domain. */
+type SemanticTakeToken = {
+    readonly tokenId: string;
+    readonly segmentId: string;
+    readonly text: string;
+    readonly startAnchorId: string;
+    readonly endAnchorId: string;
+    readonly startFrame: number;
+    readonly endFrameExclusive: number;
+};
+/**
+ * A self-contained semantic media product. Media bytes remain ordinary BlobRefs
+ * inside SynchronizedMedia; the authored word surface and its local frame
+ * coordinates travel with this Take instead of requiring a second Script edge.
+ */
+type SemanticTake = {
+    /** Author-visible Script identity carried through every semantic projection. */
+    readonly narrativeId: string;
+    readonly media: SynchronizedMedia;
+    readonly segment: {
+        readonly segmentId: string;
+        readonly startAnchorId: string;
+        readonly endAnchorId: string;
+        readonly startFrame: number;
+        readonly endFrameExclusive: number;
+    };
+    readonly tokens: readonly SemanticTakeToken[];
+    readonly anchors: readonly {
+        readonly identity: string;
+        readonly frame: number;
+    }[];
+};
+
+type NarrativeSelection = {
+    readonly id: string;
+    /** The exact semantic anchors chosen by the author Surface's affinity syntax. */
+    readonly startAnchorId: string;
+    readonly endAnchorId: string;
+};
+/** One explicitly authored semantic window, independently referenceable by graph edges. */
+type NarrativeSelectionRef = NarrativeSelection & {
+    /** Author-visible `<script id>` that owns this independently exported Selection. */
+    readonly narrativeId: string;
+};
+type NarrativeMoment = {
+    readonly id: string;
+    /** The exact semantic anchor chosen by the author Surface's affinity syntax. */
+    readonly anchorId: string;
+};
+/** One explicitly authored semantic instant, independently referenceable by graph edges. */
+type NarrativeMomentRef = NarrativeMoment & {
+    /** Author-visible `<script id>` that owns this independently exported Moment. */
+    readonly narrativeId: string;
+};
+/**
+ * One author-selected contiguous excerpt. Script is one possible producer;
+ * generation and speech packages consume this shared value without importing
+ * Script's parser or source representation.
+ */
+type NarrativeExcerpt = {
+    readonly kind: "segment";
+    /** Author-visible `<script id>` that owns this Segment. */
+    readonly narrativeId: string;
+    readonly id: string;
+    readonly tokenStart: number;
+    readonly tokenEndExclusive: number;
+};
+
+type SemanticTrackItem = {
+    readonly take: SemanticTake;
+};
+/**
+ * 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 SemanticTrackSpan = {
+    readonly item: SemanticTrackItem;
+    readonly startFrame: number;
+    readonly endFrameExclusive: number;
+};
+type LocatedFrameSpan = {
+    readonly startFrame: number;
+    readonly endFrameExclusive: number;
+};
+
+declare function sealSemanticTrack(value: SemanticTrack): SemanticTrack;
+declare function assertSemanticTrackIdentity(track: SemanticTrack): void;
+declare function semanticTrackSpans(track: SemanticTrack): readonly SemanticTrackSpan[];
+declare function semanticTrackFrameCount(track: SemanticTrack): number;
+
+declare function assertNarrativeSelectionIdentity(selection: NarrativeSelectionRef): void;
+declare function assertNarrativeMomentIdentity(moment: NarrativeMomentRef): void;
+declare function semanticAnchorFrames(track: SemanticTrack): ReadonlyMap<string, number>;
+declare function selectionFrameSpan(track: SemanticTrack, selection: NarrativeSelectionRef): LocatedFrameSpan;
+declare function segmentFrameSpan(track: SemanticTrack, segment: NarrativeExcerpt): LocatedFrameSpan;
+declare function tokenFrameSpan(track: SemanticTrack, tokenIds: readonly string[]): LocatedFrameSpan | undefined;
+declare function momentFrame(track: SemanticTrack, moment: NarrativeMomentRef): number;
+
+declare const semanticTrackModuleRef: {
+    readonly name: "@hypit/semantic-track";
+    readonly version: "1";
+};
+declare const semanticTrackTypes: {
+    track: {
+        module: {
+            readonly name: "@hypit/semantic-track";
+            readonly version: "1";
+        };
+        name: string;
+    };
+};
+declare const semanticTrackProducers: {
+    projectProgramSpace: {
+        module: {
+            readonly name: "@hypit/semantic-track";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    projectAudio: {
+        module: {
+            readonly name: "@hypit/semantic-track";
+            readonly version: "1";
+        };
+        name: string;
+    };
+};
+declare const semanticTrackSchema: ValueSchema;
+declare const semanticTrackManifest: ModuleManifest;
+declare const semanticTrackDependency: {
+    readonly module: {
+        readonly name: "@hypit/semantic-track";
+        readonly version: "1";
+    };
+};
+
+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 AudioClip = {
+    readonly id: string;
+    /** Optional domain entity implemented by this renderer Clip. */
+    readonly subjectId?: string;
+    /** Bytes only. Exact duration belongs to source.sampleFrames, not duplicated floating metadata. */
+    readonly artifact: BlobRef;
+    /** Exact audible placement in the canonical 48 kHz ProgramSpace sample domain. */
+    readonly target: {
+        readonly startSample: number;
+        readonly endSampleExclusive: number;
+    };
+    /** Exact sampling interval in one canonical 48 kHz stereo WAV Artifact. */
+    readonly source: {
+        readonly sampleFrames: number;
+        readonly startSample: number;
+        readonly endSampleExclusive: number;
+        readonly loop: boolean;
+        /** Offset inside the effective source interval used only when looping. */
+        readonly phaseSample: number;
+    };
+    readonly playbackRate: number;
+    readonly pitch: "preserve";
+    readonly gain: number;
+    readonly fadeInSamples: number;
+    readonly fadeOutSamples: number;
+};
+type AudioTrack = {
+    readonly kind: "audio";
+    /** ProgramSpace identity this terminal placement was rendered against. */
+    readonly programSpaceId: string;
+    readonly id: string;
+    readonly clips: readonly AudioClip[];
+};
+
+/** Prepared material in an authored program interval, with its original source position retained. */
+declare function projectSemanticMedia(track: SemanticTrack, window?: {
+    startFrame: number;
+    endFrameExclusive: number;
+}): {
+    segmentId: string;
+    media: SynchronizedMedia;
+    span: {
+        startFrame: number;
+        endFrameExclusive: number;
+    };
+    source: {
+        startFrame: number;
+        endFrameExclusive: number;
+    };
+}[];
+declare function projectSemanticProgramSpace(track: SemanticTrack): ProgramSpace;
+declare function projectSemanticAudioTrack(track: SemanticTrack): AudioTrack;
+
+export { assertNarrativeMomentIdentity, assertNarrativeSelectionIdentity, assertSemanticTrackIdentity, momentFrame, projectSemanticAudioTrack, projectSemanticMedia, projectSemanticProgramSpace, sealSemanticTrack, segmentFrameSpan, selectionFrameSpan, semanticAnchorFrames, semanticTrackComponent, semanticTrackDependency, semanticTrackFrameCount, semanticTrackManifest, semanticTrackModuleRef, semanticTrackProducers, semanticTrackSchema, semanticTrackSpans, semanticTrackTypes, tokenFrameSpan };
+export type { LocatedFrameSpan, SemanticTrack, SemanticTrackItem, SemanticTrackSpan };