@hypit/hypit 0.0.1 → 0.1.1

package/dist/public/narrative.d.ts

@@ -0,0 +1,315 @@
+/** Opaque identity for one admitted byte resource. Equal bytes may have different identities. */
+type ResourceId = `res_${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 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[];
+};
+
+declare const narrativeModuleRef: {
+    readonly name: "@hypit/narrative";
+    readonly version: "1";
+};
+declare const narrativeTypes: {
+    narrative: {
+        module: {
+            readonly name: "@hypit/narrative";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    excerpt: {
+        module: {
+            readonly name: "@hypit/narrative";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    selection: {
+        module: {
+            readonly name: "@hypit/narrative";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    moment: {
+        module: {
+            readonly name: "@hypit/narrative";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    captionDocument: {
+        module: {
+            readonly name: "@hypit/narrative";
+            readonly version: "1";
+        };
+        name: string;
+    };
+};
+declare const narrativeManifest: ModuleManifest;
+declare const narrativeDependency: {
+    readonly module: {
+        readonly name: "@hypit/narrative";
+        readonly version: "1";
+    };
+};
+
+type TypeValidatorContext = {
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+};
+
+declare const narrativeComponent: {
+    validators: {
+        type: {
+            module: {
+                readonly name: "@hypit/narrative";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ value }: TypeValidatorContext) => void;
+    }[];
+};
+
+type NarrativeSegment = {
+    readonly id: string;
+    readonly startAnchorId: string;
+    readonly endAnchorId: string;
+    readonly tokenStart: number;
+    readonly tokenEndExclusive: number;
+};
+type NarrativeToken = {
+    readonly id: string;
+    readonly segmentId: string;
+    readonly startAnchorId: string;
+    readonly endAnchorId: string;
+    readonly text: string;
+    readonly normalized: string;
+};
+type NarrativeTurn = {
+    readonly id: string;
+    readonly segmentId: string;
+    readonly role?: string;
+    readonly tokenStart: number;
+    readonly tokenEndExclusive: 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-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";
+    readonly segmentId?: never;
+    readonly tokenId?: never;
+} | {
+    readonly id: "program:end";
+    readonly kind: "program-end";
+    readonly segmentId?: never;
+    readonly tokenId?: never;
+} | {
+    readonly id: string;
+    readonly kind: "segment-start" | "token-start" | "token-end" | "segment-end";
+    readonly segmentId: string;
+    readonly tokenId?: string;
+};
+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 selections: readonly NarrativeSelection[];
+    readonly moments: readonly NarrativeMoment[];
+    readonly semanticIndex: {
+        readonly anchors: readonly SemanticAnchor[];
+    };
+};
+/**
+ * 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;
+};
+
+declare function assertNarrativeIdentity(value: Narrative): void;
+declare function assertNarrativeExcerptIdentity(value: NarrativeExcerpt): void;
+declare function assertNarrativeSelectionRefIdentity(value: NarrativeSelectionRef): void;
+declare function assertNarrativeMomentRefIdentity(value: NarrativeMomentRef): void;
+declare function assertCaptionDocumentIdentity(value: CaptionDocument): void;
+
+declare const narrativeSchema: ValueSchema;
+declare const narrativeExcerptSchema: ValueSchema;
+declare const captionDocumentSchema: ValueSchema;
+declare const narrativeMomentSchema: ValueSchema;
+declare const narrativeSelectionSchema: ValueSchema;
+
+export { assertCaptionDocumentIdentity, assertNarrativeExcerptIdentity, assertNarrativeIdentity, assertNarrativeMomentRefIdentity, assertNarrativeSelectionRefIdentity, captionDocumentSchema, narrativeComponent, narrativeDependency, narrativeExcerptSchema, narrativeManifest, narrativeModuleRef, narrativeMomentSchema, narrativeSchema, narrativeSelectionSchema, narrativeTypes };
+export type { CaptionAlignmentUnit, CaptionCueBreak, CaptionDisplayWord, CaptionDocument, CaptionWordAttribute, CaptionWordAttributeValue, Narrative, NarrativeExcerpt, NarrativeMoment, NarrativeMomentRef, NarrativeSegment, NarrativeSelection, NarrativeSelectionRef, NarrativeToken, NarrativeTurn, SemanticAnchor };

package/dist/public/program-space.d.ts

@@ -0,0 +1,193 @@
+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 CapabilityRef = {
+    readonly module: ModuleRef;
+    readonly name: string;
+};
+
+type CanonicalValue = null | boolean | number | string | readonly CanonicalValue[] | {
+    readonly [key: string]: CanonicalValue;
+};
+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[];
+};
+
+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;
+    };
+};
+declare const programSpaceModuleRef: {
+    readonly name: "@hypit/program-space";
+    readonly version: "1";
+};
+declare const programSpaceTypes: {
+    programSpace: {
+        module: {
+            readonly name: "@hypit/program-space";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    clock: {
+        module: {
+            readonly name: "@hypit/program-space";
+            readonly version: "1";
+        };
+        name: string;
+    };
+};
+declare const programSpaceSchema: ValueSchema;
+declare const programSpaceManifest: ModuleManifest;
+declare const programSpaceDependency: {
+    readonly module: {
+        readonly name: "@hypit/program-space";
+        readonly version: "1";
+    };
+};
+declare const programSpaceMarkupSurfaces: readonly [{
+    readonly name: "clock";
+    readonly tag: "Clock";
+    readonly mode: "structured";
+    readonly outputs: readonly [{
+        module: {
+            readonly name: "@hypit/program-space";
+            readonly version: "1";
+        };
+        name: string;
+    }];
+}, {
+    readonly name: "space";
+    readonly tag: "Space";
+    readonly mode: "structured";
+    readonly outputs: readonly [{
+        module: {
+            readonly name: "@hypit/program-space";
+            readonly version: "1";
+        };
+        name: string;
+    }];
+    readonly vocabulary: {
+        readonly summary: "Declares a film's frame rate and authored duration, for animation whose timing is directed without a performance.";
+        readonly attributes: readonly [{
+            readonly name: "id";
+            readonly kind: "identifier";
+            readonly required: true;
+            readonly summary: "Names the shared film time axis.";
+        }, {
+            readonly name: "frame-rate";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "Frames per second, such as 30 or 30000/1001.";
+        }, {
+            readonly name: "duration";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "Total duration in seconds, milliseconds or frames, such as 8s or 240f; ends on a frame boundary.";
+        }];
+        readonly example: "<time:Space id=\"animation\" frame-rate=\"30\" duration=\"8s\"/>";
+    };
+}];
+declare function sealProgramClock(value: ProgramClock): ProgramClock;
+declare function assertProgramClockIdentity(clock: ProgramClock): void;
+declare function sealProgramSpace(value: ProgramSpace): ProgramSpace;
+declare function programSpaceFrameCount(programSpace: ProgramSpace): number;
+declare function programSpaceSampleFrames(programSpace: ProgramSpace, sampleRate: number): number;
+declare function programFrameSampleBoundary(programSpace: ProgramSpace, frame: number, sampleRate: number): number;
+declare function assertProgramSpaceIdentity(programSpace: ProgramSpace): void;
+
+export { assertProgramClockIdentity, assertProgramSpaceIdentity, programFrameSampleBoundary, programSpaceDependency, programSpaceFrameCount, programSpaceManifest, programSpaceMarkupSurfaces, programSpaceModuleRef, programSpaceSampleFrames, programSpaceSchema, programSpaceTypes, sealProgramClock, sealProgramSpace };
+export type { ProgramClock, ProgramSpace };