@hypit/hypit 0.0.1 → 0.1.1

package/dist/public/svs.d.ts

@@ -0,0 +1,311 @@
+/** Opaque identity for one admitted byte resource. Equal bytes may have different identities. */
+type ResourceId = `res_${string}`;
+type RecordId = 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 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 ResolvedModule = {
+    readonly manifest: ModuleManifest;
+};
+type ResolvedModuleClosure = {
+    readonly format: "hypit.closure@1";
+    readonly modules: readonly ResolvedModule[];
+};
+
+type SourceRange = {
+    readonly start: number;
+    readonly end: number;
+};
+/** 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;
+};
+
+declare const svsModuleRef: {
+    readonly name: "@hypit/svs";
+    readonly version: "1";
+};
+declare const svsRecipeType: {
+    module: {
+        readonly name: "@hypit/svs";
+        readonly version: "1";
+    };
+    name: string;
+};
+declare const svsFrontendId = "@hypit/svs@1";
+declare const svsManifest: ModuleManifest;
+
+type SvsRecipe = {
+    readonly path: string;
+    readonly properties: Readonly<Record<string, CanonicalValue>>;
+};
+type ParsedSvsRecipe = {
+    readonly value: SvsRecipe;
+    readonly range: SourceRange;
+    /** Exact author-source spans, for editors that must preserve surrounding trivia. */
+    readonly properties: readonly ParsedSvsProperty[];
+};
+type ParsedSvsProperty = {
+    readonly name: string;
+    /** From the property name through its terminating semicolon. */
+    readonly range: SourceRange;
+    /** The trimmed value only; replacing this span preserves author formatting. */
+    readonly valueRange: SourceRange;
+};
+type ParsedSvsSheet = {
+    readonly id?: string;
+    readonly recipes: readonly ParsedSvsRecipe[];
+};
+
+declare class SvsSyntaxError extends Error {
+    readonly code: string;
+    readonly sourceName: string;
+    readonly offset: number;
+    constructor(code: string, message: string, sourceName: string, offset: number);
+}
+declare function parseSvs(sourceName: string, source: string): ParsedSvsSheet;
+
+/** Serialize one canonical value without knowing which component consumes it. */
+declare function formatSvsValue(value: CanonicalValue): string;
+
+type FragmentInputRef = {
+    readonly kind: "fragment-input";
+    readonly name: string;
+};
+type FragmentOperationRef = {
+    readonly kind: "fragment-operation";
+    readonly operation: string;
+};
+type FragmentValueRef = FragmentInputRef | FragmentOperationRef;
+type FragmentOperationResult = {
+    readonly kind: "output";
+    readonly name: string;
+} | {
+    readonly kind: "need";
+    readonly name: string;
+};
+type FragmentOperation = {
+    readonly id: string;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, FragmentValueRef>>;
+    readonly result: FragmentOperationResult;
+};
+type FragmentExport = {
+    readonly name: string;
+    readonly type: TypeRef;
+    readonly root: FragmentOperationRef;
+};
+type GraphFragment = {
+    readonly format: "hypit.fragment@1";
+    readonly id: string;
+    readonly inputs: readonly {
+        readonly name: string;
+        readonly type: TypeRef;
+    }[];
+    readonly operations: readonly FragmentOperation[];
+    readonly exports: readonly FragmentExport[];
+};
+
+/** A reference to an authored fact that already exists in the Linked Program. */
+type AuthorRecordRef = {
+    readonly kind: "record";
+    readonly id: string;
+};
+/** A symbolic reference to one public export of another component instance. */
+type AuthorComponentOutputRef = {
+    readonly kind: "component-output";
+    readonly component: string;
+    readonly output: string;
+};
+type AuthorValueRef = AuthorRecordRef | AuthorComponentOutputRef;
+/**
+ * One author-visible component call. `outputs` binds every public Fragment export to a Logical Output.
+ */
+type AuthorComponent = {
+    readonly id: string;
+    readonly fragment: string;
+    readonly inputs: Readonly<Record<string, AuthorValueRef>>;
+    readonly outputs: Readonly<Record<string, string>>;
+};
+
+type SourceHeader = {
+    /** Logical Frontend request. A trusted Host resolves it to one exact implementation. */
+    readonly using: string;
+    readonly start: number;
+    readonly end: number;
+};
+
+type SourceUnit = {
+    /** Host-canonical identity used only for recursion and diagnostics. */
+    readonly id: string;
+    readonly name: string;
+    readonly text: string;
+};
+type SourceImportRequest = {
+    readonly from: string;
+    readonly alias: string;
+    readonly range?: SourceRange;
+};
+type SourceAssetRequest = {
+    readonly from: string;
+    readonly mediaType: string;
+    /** Package-owned bytes admitted by the compiler before a Workspace is consulted. */
+    readonly bytes?: Uint8Array;
+    readonly range?: SourceRange;
+};
+type ResolvedSourceAsset = {
+    readonly artifact: BlobRef;
+};
+
+type AuthorSourceUnit = SourceUnit;
+/** Source presented to a Frontend after the mandatory Header has been admitted and masked. */
+type AuthorFrontendSourceUnit = AuthorSourceUnit & {
+    readonly header: SourceHeader;
+};
+type AuthorSourceImport = SourceImportRequest;
+type AuthorSourceDiscovery = {
+    readonly modules: readonly string[];
+    readonly sources: readonly AuthorSourceImport[];
+};
+/** A semantic source dependency requested by a Frontend or package-owned Surface. */
+type AuthorSourceAssetRequest = SourceAssetRequest;
+type ResolvedAuthorSourceAsset = ResolvedSourceAsset;
+type AuthorSourceExport = {
+    /** Relative public name. The importing source contributes its own alias. */
+    readonly name: string;
+    readonly ref: AuthorValueRef;
+    readonly type: TypeRef;
+};
+/**
+ * One author-visible identity whose uniqueness is part of a domain's public
+ * contract. The Frontend only carries the declaration; the owning Surface
+ * chooses the Type namespace and the Source closure enforces it generically.
+ */
+type AuthorSourceIdentity = {
+    readonly namespace: TypeRef;
+    readonly id: string;
+};
+/** One author input before Source-local graph identities are hygienized. */
+type AuthorInputProvenanceDraft = {
+    readonly name: string;
+    readonly range: SourceRange;
+    readonly kind: "literal" | "reference";
+    readonly ref?: AuthorValueRef;
+};
+/**
+ * Structural origin retained by a Frontend while it lowers author syntax.
+ * It contains no editor presentation and is never persisted beside the Source.
+ */
+type AuthorElementProvenanceDraft = {
+    readonly range: SourceRange;
+    readonly records: readonly string[];
+    readonly components: readonly string[];
+    readonly outputs: readonly {
+        readonly component: string;
+        readonly name: string;
+        readonly id: string;
+    }[];
+    readonly inputs: readonly AuthorInputProvenanceDraft[];
+};
+type ResolvedAuthorSourceImport = {
+    readonly request: AuthorSourceImport;
+    readonly source: string;
+    readonly exports: readonly AuthorSourceExport[];
+    /** Public record exports available to a package-owned Surface during author compilation. */
+    readonly records: readonly TypedRecord[];
+};
+type AuthorSourceDecodeContext = {
+    readonly closure: ResolvedModuleClosure;
+    readonly imports: readonly ResolvedAuthorSourceImport[];
+    /** Host authority: Frontends declare asset dependencies but never open files themselves. */
+    readonly resolveAsset: (request: AuthorSourceAssetRequest) => Awaitable<ResolvedAuthorSourceAsset>;
+};
+type DecodedAuthorSource = {
+    readonly records: readonly TypedRecord[];
+    readonly components: readonly AuthorComponent[];
+    readonly fragments: readonly GraphFragment[];
+    readonly exports: readonly AuthorSourceExport[];
+    readonly identities?: readonly AuthorSourceIdentity[];
+    readonly provenance?: readonly AuthorElementProvenanceDraft[];
+};
+type Awaitable<T> = T | Promise<T>;
+type AuthorFrontend = {
+    readonly id: string;
+    discover(source: AuthorFrontendSourceUnit): Awaitable<AuthorSourceDiscovery>;
+    decode(source: AuthorFrontendSourceUnit, context: AuthorSourceDecodeContext): Awaitable<DecodedAuthorSource>;
+};
+
+declare const svsFrontend: AuthorFrontend;
+
+export { SvsSyntaxError, formatSvsValue, parseSvs, svsFrontend, svsFrontendId, svsManifest, svsModuleRef, svsRecipeType };
+export type { ParsedSvsProperty, ParsedSvsRecipe, ParsedSvsSheet, SvsRecipe };

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

@@ -0,0 +1,343 @@
+/** Opaque identity for one admitted byte resource. Equal bytes may have different identities. */
+type ResourceId = `res_${string}`;
+type RecordId = 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 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 SourceRange = {
+    readonly start: number;
+    readonly end: number;
+};
+/** 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 FragmentInputRef = {
+    readonly kind: "fragment-input";
+    readonly name: string;
+};
+type FragmentOperationRef = {
+    readonly kind: "fragment-operation";
+    readonly operation: string;
+};
+type FragmentValueRef = FragmentInputRef | FragmentOperationRef;
+type FragmentOperationResult = {
+    readonly kind: "output";
+    readonly name: string;
+} | {
+    readonly kind: "need";
+    readonly name: string;
+};
+type FragmentOperation = {
+    readonly id: string;
+    readonly producer: ProducerRef;
+    readonly inputs: Readonly<Record<string, FragmentValueRef>>;
+    readonly result: FragmentOperationResult;
+};
+type FragmentExport = {
+    readonly name: string;
+    readonly type: TypeRef;
+    readonly root: FragmentOperationRef;
+};
+type GraphFragment = {
+    readonly format: "hypit.fragment@1";
+    readonly id: string;
+    readonly inputs: readonly {
+        readonly name: string;
+        readonly type: TypeRef;
+    }[];
+    readonly operations: readonly FragmentOperation[];
+    readonly exports: readonly FragmentExport[];
+};
+
+/** A reference to an authored fact that already exists in the Linked Program. */
+type AuthorRecordRef = {
+    readonly kind: "record";
+    readonly id: string;
+};
+/** A symbolic reference to one public export of another component instance. */
+type AuthorComponentOutputRef = {
+    readonly kind: "component-output";
+    readonly component: string;
+    readonly output: string;
+};
+type AuthorValueRef = AuthorRecordRef | AuthorComponentOutputRef;
+/**
+ * One author-visible component call. `outputs` binds every public Fragment export to a Logical Output.
+ */
+type AuthorComponent = {
+    readonly id: string;
+    readonly fragment: string;
+    readonly inputs: Readonly<Record<string, AuthorValueRef>>;
+    readonly outputs: Readonly<Record<string, string>>;
+};
+
+type MarkupReference = {
+    readonly kind: "reference";
+    readonly path: string;
+};
+type MarkupAttributeValue = string | MarkupReference;
+type StructuredText = {
+    readonly kind: "text";
+    readonly value: string;
+    readonly range: SourceRange;
+};
+type StructuredElement = {
+    readonly kind: "element";
+    readonly name: string;
+    readonly attributes: Readonly<Record<string, MarkupAttributeValue>>;
+    /** Exact ranges of literal/reference values in the opening tag. */
+    readonly attributeValueRanges?: Readonly<Record<string, SourceRange>>;
+    readonly children: readonly StructuredNode[];
+    readonly range: SourceRange;
+};
+type StructuredNode = StructuredText | StructuredElement;
+type SurfaceRecordDraft = {
+    readonly id: string;
+    readonly type: TypeRef;
+    readonly value: StoredValue;
+    readonly range: SourceRange;
+};
+/** Source-local diagnostics are removed before the component enters semantic elaboration. */
+type SurfaceComponentDraft = AuthorComponent & {
+    readonly range: SourceRange;
+};
+type SurfaceResolvedReference = {
+    readonly path: string;
+    readonly ref: AuthorValueRef;
+    readonly type: TypeRef;
+    readonly record?: TypedRecord;
+};
+type SurfaceAttributeKind = "identifier" | "literal" | "reference" | "expression";
+type SurfaceRecipePropertyVocabulary = {
+    readonly name: string;
+    readonly required: boolean;
+    readonly summary: string;
+    /** The author value's public structure; it contains no editor presentation. */
+    readonly schema?: ValueSchema;
+    readonly values?: readonly string[];
+    /** Decoded author default; when a schema is present this value conforms to that public structure. */
+    readonly fallback?: CanonicalValue;
+};
+type SurfaceAttributeVocabulary = {
+    readonly name: string;
+    readonly kind: SurfaceAttributeKind;
+    readonly required: boolean;
+    readonly summary: string;
+    readonly values?: readonly string[];
+    readonly accepts?: readonly TypeRef[];
+    readonly recipe?: readonly SurfaceRecipePropertyVocabulary[];
+};
+
+type TemporalContext = {
+    readonly semantic?: SurfaceResolvedReference;
+    readonly space?: SurfaceResolvedReference;
+};
+declare const temporalContextAttributeVocabulary: readonly [{
+    readonly name: "semantic";
+    readonly kind: "reference";
+    readonly required: false;
+    readonly accepts: readonly [{
+        module: {
+            readonly name: "@hypit/semantic-track";
+            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.";
+}];
+/** Select the author's film time source. */
+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 = {
+    readonly unit: "frames";
+    readonly value: number;
+} | {
+    readonly unit: "milliseconds";
+    readonly value: number;
+} | {
+    readonly unit: "seconds";
+    readonly numerator: number;
+    readonly denominator: number;
+};
+/** A single projected boundary before it is resolved into ProgramSpace. */
+type TemporalInstantExpression = {
+    readonly ref: "program.start";
+    readonly offset?: TemporalDuration;
+} | {
+    readonly ref: "program.end";
+    readonly offset?: TemporalDuration;
+} | {
+    readonly ref: "selection.start";
+    readonly offset?: TemporalDuration;
+} | {
+    readonly ref: "selection.end";
+    readonly offset?: TemporalDuration;
+} | {
+    readonly ref: "segment.start";
+    readonly offset?: TemporalDuration;
+} | {
+    readonly ref: "segment.end";
+    readonly offset?: TemporalDuration;
+} | {
+    readonly ref: "moment.cue";
+    readonly offset?: TemporalDuration;
+} | {
+    readonly ref: "absolute";
+    readonly at: TemporalDuration;
+    readonly offset?: TemporalDuration;
+};
+
+type ResolveReference = (path: string) => SurfaceResolvedReference | undefined;
+/** Complete author vocabulary for one Window consumer. Domain packages may only add non-time fields. */
+declare const temporalWindowAttributeVocabulary: readonly SurfaceAttributeVocabulary[];
+declare const temporalWindowAttributeNames: string[];
+/** Complete author vocabulary for a semantic or explicitly projected Instant. */
+declare const temporalInstantAttributeVocabulary: readonly SurfaceAttributeVocabulary[];
+declare const temporalInstantAttributeNames: string[];
+type TemporalMarkupProjection = {
+    readonly records: readonly SurfaceRecordDraft[];
+    readonly components: readonly SurfaceComponentDraft[];
+    readonly fragments: readonly GraphFragment[];
+    readonly ref: {
+        readonly kind: "component-output";
+        readonly component: string;
+        readonly output: string;
+    };
+};
+declare function parseTemporalDuration(value: string, label: string): TemporalDuration;
+declare function parseTemporalInstant(value: string, label: string): TemporalInstantExpression;
+/** Decode exactly one of during, at/for, until/for, or start/end. */
+declare function createTemporalWindowProjection(input: {
+    readonly id: string;
+    readonly subjectId?: string;
+    readonly element: StructuredElement;
+    readonly semantic?: SurfaceResolvedReference;
+    readonly space?: SurfaceResolvedReference;
+    readonly resolveReference: ResolveReference;
+}): TemporalMarkupProjection;
+/** Decode a semantic reference, an authored at time, or a projected instant expression. */
+declare function createTemporalInstantProjection(input: {
+    readonly id: string;
+    readonly subjectId?: string;
+    readonly element: StructuredElement;
+    readonly semantic?: SurfaceResolvedReference;
+    readonly space?: SurfaceResolvedReference;
+    readonly resolveReference: ResolveReference;
+    readonly semanticAttribute?: string;
+    readonly boundaryAttribute?: string;
+    readonly boundaryFallback?: "start" | "end";
+    readonly projectedAttribute?: string | false;
+}): TemporalMarkupProjection;
+
+export { createTemporalInstantProjection, createTemporalSpace, createTemporalWindowProjection, parseTemporalDuration, parseTemporalInstant, resolveTemporalContext, temporalContextAttributeVocabulary, temporalInstantAttributeNames, temporalInstantAttributeVocabulary, temporalWindowAttributeNames, temporalWindowAttributeVocabulary };
+export type { TemporalContext, TemporalMarkupProjection };