@hypit/hypit 0.0.1 → 0.1.1

package/dist/public/spatial.d.ts

@@ -0,0 +1,1193 @@
+/** 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[];
+};
+
+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 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 spatialComponent: {
+    producers: ({
+        producer: {
+            module: {
+                readonly name: "@hypit/spatial";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ inputs }: ProducerHandlerContext) => {
+            outputs: {
+                frame: {
+                    kind: "inline";
+                    value: CanonicalValue;
+                };
+            };
+            needs: {};
+        };
+    } | {
+        producer: {
+            module: {
+                readonly name: "@hypit/spatial";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ inputs }: ProducerHandlerContext) => {
+            outputs: {
+                fitted: {
+                    kind: "inline";
+                    value: CanonicalValue;
+                };
+            };
+            needs: {};
+        };
+    })[];
+    validators: {
+        type: {
+            module: {
+                readonly name: "@hypit/spatial";
+                readonly version: "1";
+            };
+            name: string;
+        };
+        handler: ({ value }: TypeValidatorContext) => void;
+    }[];
+};
+
+type CanvasSpace = {
+    readonly widthPx: number;
+    readonly heightPx: number;
+    readonly origin: "top-left";
+    readonly xDirection: "right";
+    readonly yDirection: "down";
+    readonly pixelAspect: "square";
+};
+type SpatialPoint = {
+    readonly xPx: number;
+    readonly yPx: number;
+};
+type SpatialFrame = {
+    readonly xPx: number;
+    readonly yPx: number;
+    readonly widthPx: number;
+    readonly heightPx: number;
+};
+/** One named, frame-exact sequence of measured regions in one Canvas. */
+type SpatialRegionTrack = {
+    readonly id: string;
+    readonly frames: readonly (SpatialFrame | null)[];
+};
+/** External spatial evidence indexed directly by ProgramSpace Frame. */
+type SpatialRegionTimeline = {
+    readonly canvas: CanvasSpace;
+    readonly frameCount: number;
+    readonly tracks: readonly SpatialRegionTrack[];
+};
+type SpatialPathCommand = {
+    readonly kind: "move";
+    readonly xPx: number;
+    readonly yPx: number;
+} | {
+    readonly kind: "line";
+    readonly xPx: number;
+    readonly yPx: number;
+} | {
+    readonly kind: "quadratic";
+    readonly controlX: number;
+    readonly controlY: number;
+    readonly xPx: number;
+    readonly yPx: number;
+} | {
+    readonly kind: "cubic";
+    readonly control1X: number;
+    readonly control1Y: number;
+    readonly control2X: number;
+    readonly control2Y: number;
+    readonly xPx: number;
+    readonly yPx: number;
+} | {
+    readonly kind: "close";
+};
+type SpatialPath = {
+    readonly commands: readonly SpatialPathCommand[];
+};
+type IntrinsicExtent = {
+    readonly widthPx: number;
+    readonly heightPx: number;
+};
+type NormalizedPoint = {
+    readonly x: number;
+    readonly y: number;
+};
+type ContentFit = {
+    readonly sizing: "contain" | "cover" | "fit-width" | "fit-height" | "native" | "scale-down" | "stretch";
+    readonly framePoint: NormalizedPoint;
+    readonly contentPoint: NormalizedPoint;
+    readonly offsetPx: {
+        readonly x: number;
+        readonly y: number;
+    };
+    readonly constraint: "bounded" | "free";
+};
+type FittedContent = {
+    readonly contentFrame: SpatialFrame;
+};
+type SpatialLength = {
+    readonly unit: "px" | "percent";
+    readonly value: number;
+};
+type FrameEdgesProgram = {
+    readonly left: SpatialLength;
+    readonly top: SpatialLength;
+    readonly right: SpatialLength;
+    readonly bottom: SpatialLength;
+};
+type SpatialAnchor = "top-left" | "top-center" | "top-right" | "middle-left" | "center" | "middle-right" | "bottom-left" | "bottom-center" | "bottom-right";
+type AnchoredFrameProgram = {
+    readonly x: SpatialLength;
+    readonly y: SpatialLength;
+    readonly width: SpatialLength;
+    readonly height: SpatialLength;
+    readonly anchor: SpatialAnchor;
+    readonly offsetPx: {
+        readonly x: number;
+        readonly y: number;
+    };
+};
+type AspectFrameProgram = {
+    readonly x: SpatialLength;
+    readonly y: SpatialLength;
+    readonly primary: "width" | "height";
+    readonly size: SpatialLength;
+    readonly anchor: SpatialAnchor;
+    readonly offsetPx: {
+        readonly x: number;
+        readonly y: number;
+    };
+};
+
+declare const contentFitPropertyNames: readonly ["fit", "frame-x", "frame-y", "content-x", "content-y", "fit-offset-x", "fit-offset-y", "fit-constraint"];
+/** Decode the shared spatial-fit vocabulary from any author-side property map. */
+declare function decodeContentFitProperties(properties: Readonly<Record<string, CanonicalValue>>, owner?: string): ContentFit;
+
+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 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;
+};
+
+/** A semantic source dependency requested by a Frontend or package-owned Surface. */
+type AuthorSourceAssetRequest = SourceAssetRequest;
+type ResolvedAuthorSourceAsset = ResolvedSourceAsset;
+/**
+ * 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;
+};
+type Awaitable<T> = T | Promise<T>;
+
+declare const canvasFrameFragment: GraphFragment;
+declare const frameEdgesFragment: GraphFragment;
+declare const anchoredFrameFragment: GraphFragment;
+declare const aspectFrameFragment: GraphFragment;
+declare const fitContentFragment: GraphFragment;
+
+declare function assertCanvasSpace(value: CanvasSpace): void;
+declare function assertSpatialPoint(value: SpatialPoint): void;
+declare function assertSpatialFrame(value: SpatialFrame): void;
+declare function assertSpatialRegionTimeline(value: SpatialRegionTimeline): void;
+declare function assertIntrinsicExtent(value: IntrinsicExtent): void;
+declare function assertContentFit(value: ContentFit): void;
+declare function assertFittedContent(value: FittedContent): void;
+declare function assertSpatialPath(value: SpatialPath): void;
+declare function canvasFrame(canvas: CanvasSpace): SpatialFrame;
+declare function frameFromEdges(parent: SpatialFrame, program: FrameEdgesProgram): SpatialFrame;
+declare function anchoredFrame(parent: SpatialFrame, program: AnchoredFrameProgram): SpatialFrame;
+declare function aspectFrame(parent: SpatialFrame, extent: IntrinsicExtent, program: AspectFrameProgram): SpatialFrame;
+declare function fitContent(frame: SpatialFrame, extent: IntrinsicExtent, fit: ContentFit): FittedContent;
+declare function sealCanvasSpace(value: CanvasSpace): CanvasSpace;
+declare function sealSpatialPoint(value: SpatialPoint): SpatialPoint;
+declare function sealSpatialFrame(value: SpatialFrame): SpatialFrame;
+declare function sealSpatialRegionTimeline(value: SpatialRegionTimeline): SpatialRegionTimeline;
+declare function sealSpatialPath(value: SpatialPath): SpatialPath;
+declare function sealIntrinsicExtent(value: IntrinsicExtent): IntrinsicExtent;
+declare function sealContentFit(value: ContentFit): ContentFit;
+declare function sealFittedContent(value: FittedContent): FittedContent;
+
+declare const spatialModuleRef: {
+    readonly name: "@hypit/spatial";
+    readonly version: "1";
+};
+declare const spatialTypes: {
+    canvas: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    point: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    frame: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    regionTimeline: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    path: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    extent: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    fit: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    fitted: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    frameEdgesProgram: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    anchoredFrameProgram: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    aspectFrameProgram: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+};
+declare const spatialProducers: {
+    canvasFrame: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    frameEdges: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    anchoredFrame: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    aspectFrame: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+    fitContent: {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    };
+};
+declare const spatialMarkupSurfaces: readonly [{
+    readonly name: "canvas";
+    readonly tag: "Canvas";
+    readonly mode: "structured";
+    readonly outputs: readonly [{
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    }];
+    readonly vocabulary: {
+        readonly summary: "Declares one Canvas: the pixel extent every Frame is measured inside.";
+        readonly attributes: readonly [{
+            readonly name: "id";
+            readonly kind: "identifier";
+            readonly required: true;
+            readonly summary: "Names the CanvasSpace Record this element publishes.";
+        }, {
+            readonly name: "width";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "States how many pixels wide the Canvas is.";
+        }, {
+            readonly name: "height";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "States how many pixels tall the Canvas is.";
+        }];
+        readonly example: "<space:Canvas id=\"vertical\" width=\"1080\" height=\"1920\"/>";
+        readonly notes: readonly ["The element is empty; it accepts no children and no text.", "`width` and `height` are positive whole numbers of pixels.", "The coordinate system is fixed: the origin is top-left, x increases to the right, y increases downward and pixels are square.", "The CanvasSpace is published under the bare `id`."];
+    };
+}, {
+    readonly name: "point";
+    readonly tag: "Point";
+    readonly mode: "structured";
+    readonly outputs: readonly [{
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    }];
+    readonly vocabulary: {
+        readonly summary: "Names one position on the Canvas in pixels.";
+        readonly attributes: readonly [{
+            readonly name: "id";
+            readonly kind: "identifier";
+            readonly required: true;
+            readonly summary: "Names the SpatialPoint Record this element publishes.";
+        }, {
+            readonly name: "x";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "Places the Point this many pixels along the Canvas x axis.";
+        }, {
+            readonly name: "y";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "Places the Point this many pixels down the Canvas y axis.";
+        }];
+        readonly example: "<space:Point id=\"headline-origin\" x=\"120\" y=\"280\"/>";
+        readonly notes: readonly ["The element is empty; it accepts no children and no text.", "`x` and `y` are finite pixel numbers, so a Point may be fractional, negative or outside the Canvas.", "The SpatialPoint is published under the bare `id`."];
+    };
+}, {
+    readonly name: "path";
+    readonly tag: "Path";
+    readonly mode: "structured";
+    readonly outputs: readonly [{
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    }];
+    readonly vocabulary: {
+        readonly summary: "Draws one Path in Canvas pixels from an ordered list of commands.";
+        readonly attributes: readonly [{
+            readonly name: "id";
+            readonly kind: "identifier";
+            readonly required: true;
+            readonly summary: "Names the SpatialPath Record this element publishes.";
+        }];
+        readonly children: readonly [{
+            readonly tag: "Move";
+            readonly cardinality: "many";
+            readonly summary: "Lifts the pen and starts a new subpath at a point.";
+            readonly attributes: readonly [{
+                readonly name: "x";
+                readonly kind: "literal";
+                readonly required: true;
+                readonly summary: "Starts the subpath this many pixels along the Canvas x axis.";
+            }, {
+                readonly name: "y";
+                readonly kind: "literal";
+                readonly required: true;
+                readonly summary: "Starts the subpath this many pixels down the Canvas y axis.";
+            }];
+        }, {
+            readonly tag: "Line";
+            readonly cardinality: "many";
+            readonly summary: "Draws a straight segment to a point.";
+            readonly attributes: readonly [{
+                readonly name: "x";
+                readonly kind: "literal";
+                readonly required: true;
+                readonly summary: "Ends the segment this many pixels along the Canvas x axis.";
+            }, {
+                readonly name: "y";
+                readonly kind: "literal";
+                readonly required: true;
+                readonly summary: "Ends the segment this many pixels down the Canvas y axis.";
+            }];
+        }, {
+            readonly tag: "Quadratic";
+            readonly cardinality: "many";
+            readonly summary: "Draws a quadratic curve to a point through one control point.";
+            readonly attributes: readonly [{
+                readonly name: "control-x";
+                readonly kind: "literal";
+                readonly required: true;
+                readonly summary: "Places the control point this many pixels along the Canvas x axis.";
+            }, {
+                readonly name: "control-y";
+                readonly kind: "literal";
+                readonly required: true;
+                readonly summary: "Places the control point this many pixels down the Canvas y axis.";
+            }, {
+                readonly name: "x";
+                readonly kind: "literal";
+                readonly required: true;
+                readonly summary: "Ends the curve this many pixels along the Canvas x axis.";
+            }, {
+                readonly name: "y";
+                readonly kind: "literal";
+                readonly required: true;
+                readonly summary: "Ends the curve this many pixels down the Canvas y axis.";
+            }];
+        }, {
+            readonly tag: "Cubic";
+            readonly cardinality: "many";
+            readonly summary: "Draws a cubic curve to a point through two control points.";
+            readonly attributes: readonly [{
+                readonly name: "control1-x";
+                readonly kind: "literal";
+                readonly required: true;
+                readonly summary: "Places the control point leaving the current point this many pixels along the Canvas x axis.";
+            }, {
+                readonly name: "control1-y";
+                readonly kind: "literal";
+                readonly required: true;
+                readonly summary: "Places the control point leaving the current point this many pixels down the Canvas y axis.";
+            }, {
+                readonly name: "control2-x";
+                readonly kind: "literal";
+                readonly required: true;
+                readonly summary: "Places the control point entering the end point this many pixels along the Canvas x axis.";
+            }, {
+                readonly name: "control2-y";
+                readonly kind: "literal";
+                readonly required: true;
+                readonly summary: "Places the control point entering the end point this many pixels down the Canvas y axis.";
+            }, {
+                readonly name: "x";
+                readonly kind: "literal";
+                readonly required: true;
+                readonly summary: "Ends the curve this many pixels along the Canvas x axis.";
+            }, {
+                readonly name: "y";
+                readonly kind: "literal";
+                readonly required: true;
+                readonly summary: "Ends the curve this many pixels down the Canvas y axis.";
+            }];
+        }, {
+            readonly tag: "Close";
+            readonly cardinality: "many";
+            readonly summary: "Closes the open subpath back to where it began.";
+            readonly attributes: readonly [];
+        }];
+        readonly example: "<space:Path id=\"headline-path\">\n  <space:Move x=\"120\" y=\"280\"/>\n  <space:Cubic control1-x=\"360\" control1-y=\"180\" control2-x=\"720\" control2-y=\"380\" x=\"960\" y=\"280\"/>\n</space:Path>";
+        readonly notes: readonly ["The Path accepts only command children and no text.", "Every command is written empty, and every coordinate is a finite pixel number.", "A Path begins with `<Move>`, carries at least one drawable segment, and reopens with `<Move>` after a `<Close>`.", "The SpatialPath is published under the bare `id`."];
+    };
+}, {
+    readonly name: "extent";
+    readonly tag: "Extent";
+    readonly mode: "structured";
+    readonly outputs: readonly [{
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    }];
+    readonly vocabulary: {
+        readonly summary: "States the intrinsic pixel extent of content, independent of the Frame it is placed in.";
+        readonly attributes: readonly [{
+            readonly name: "id";
+            readonly kind: "identifier";
+            readonly required: true;
+            readonly summary: "Names the IntrinsicExtent Record this element publishes.";
+        }, {
+            readonly name: "width";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "States how many pixels wide the content is.";
+        }, {
+            readonly name: "height";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "States how many pixels tall the content is.";
+        }];
+        readonly example: "<space:Extent id=\"portrait\" width=\"540\" height=\"960\"/>";
+        readonly notes: readonly ["The element is empty; it accepts no children and no text.", "`width` and `height` are positive whole numbers of pixels.", "The IntrinsicExtent is published under the bare `id`."];
+    };
+}, {
+    readonly name: "region-timeline";
+    readonly tag: "RegionTimeline";
+    readonly mode: "structured";
+    readonly outputs: readonly [{
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    }];
+    readonly vocabulary: {
+        readonly summary: "Resolves externally measured, normalized AABB sequences into one frame-exact set of named Canvas-space region tracks.";
+        readonly attributes: readonly [{
+            readonly name: "id";
+            readonly kind: "identifier";
+            readonly required: true;
+            readonly summary: "Names the SpatialRegionTimeline Record this element publishes.";
+        }, {
+            readonly name: "within";
+            readonly kind: "reference";
+            readonly required: true;
+            readonly accepts: readonly [{
+                module: {
+                    readonly name: "@hypit/spatial";
+                    readonly version: "1";
+                };
+                name: string;
+            }];
+            readonly summary: "Chooses the Canvas that normalized regions are measured inside.";
+        }, {
+            readonly name: "recipe";
+            readonly kind: "reference";
+            readonly required: true;
+            readonly accepts: readonly [{
+                module: {
+                    readonly name: "@hypit/svs";
+                    readonly version: "1";
+                };
+                name: string;
+            }];
+            readonly summary: "Chooses the external frame-indexed region data.";
+            readonly recipe: readonly [{
+                readonly name: "frame-count";
+                readonly required: true;
+                readonly summary: "States the exact number of ProgramSpace Frames covered by every named track.";
+            }, {
+                readonly name: "tracks";
+                readonly required: true;
+                readonly summary: "Lists objects shaped as {id, regions}; each regions array contains frame-count normalized [x, y, width, height] AABBs or null when the region is absent.";
+            }];
+        }];
+        readonly example: "<space:RegionTimeline id=\"heads\" within={vertical} recipe={tracking.heads.default}/>";
+        readonly notes: readonly ["The element is empty; it accepts no children and no text.", "Detection and tracking happen before authoring; this Surface consumes finished numeric evidence and never invokes them during a Build.", "The array index is the ProgramSpace Frame; the Surface performs no timestamp conversion, interpolation, smoothing or identity inference.", "Each normalized AABB lies inside [0, 1] and is resolved into Canvas pixels during author compilation; null remains explicit absence.", "Track ids are ordinary external labels; a consumer may interpret them as Script Roles without Spatial knowing what a Role is."];
+    };
+}, {
+    readonly name: "frame";
+    readonly tag: "Frame";
+    readonly mode: "structured";
+    readonly outputs: readonly [{
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    }, {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    }];
+    readonly vocabulary: {
+        readonly summary: "Places one Frame by its four edges inside a Canvas or a parent Frame.";
+        readonly attributes: readonly [{
+            readonly name: "id";
+            readonly kind: "identifier";
+            readonly required: true;
+            readonly summary: "Names the Frame this element publishes.";
+        }, {
+            readonly name: "within";
+            readonly kind: "reference";
+            readonly required: true;
+            readonly accepts: readonly [{
+                module: {
+                    readonly name: "@hypit/spatial";
+                    readonly version: "1";
+                };
+                name: string;
+            }, {
+                module: {
+                    readonly name: "@hypit/spatial";
+                    readonly version: "1";
+                };
+                name: string;
+            }];
+            readonly summary: "Chooses the Canvas or parent Frame the four edges are measured against.";
+        }, {
+            readonly name: "left";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "Places the left edge, measured from the parent's left.";
+        }, {
+            readonly name: "top";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "Places the top edge, measured from the parent's top.";
+        }, {
+            readonly name: "right";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "Places the right edge, measured from the parent's left.";
+        }, {
+            readonly name: "bottom";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "Places the bottom edge, measured from the parent's top.";
+        }];
+        readonly ports: readonly [{
+            readonly name: "";
+            readonly type: {
+                module: {
+                    readonly name: "@hypit/spatial";
+                    readonly version: "1";
+                };
+                name: string;
+            };
+            readonly summary: "The resolved Frame, addressed by the element's own id.";
+        }];
+        readonly example: "<space:Frame id=\"safe\" within={vertical} left=\"6%\" top=\"4%\" right=\"94%\" bottom=\"96%\"/>";
+        readonly notes: readonly ["The element is empty; it accepts no children and no text.", "A length is a number followed by `px` or `%`; a percentage resolves against the parent Frame's width on the x axis and its height on the y axis.", "`right` must resolve past `left` and `bottom` past `top`, because a Frame has positive width and height.", "A Canvas written in `within` is first resolved to its own full-Canvas Frame, so every Frame is placed inside a Frame."];
+    };
+}, {
+    readonly name: "anchored-frame";
+    readonly tag: "AnchoredFrame";
+    readonly mode: "structured";
+    readonly outputs: readonly [{
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    }, {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    }];
+    readonly vocabulary: {
+        readonly summary: "Places one Frame of a stated size by pinning one of its nine anchor points to a position in the parent.";
+        readonly attributes: readonly [{
+            readonly name: "id";
+            readonly kind: "identifier";
+            readonly required: true;
+            readonly summary: "Names the Frame this element publishes.";
+        }, {
+            readonly name: "within";
+            readonly kind: "reference";
+            readonly required: true;
+            readonly accepts: readonly [{
+                module: {
+                    readonly name: "@hypit/spatial";
+                    readonly version: "1";
+                };
+                name: string;
+            }, {
+                module: {
+                    readonly name: "@hypit/spatial";
+                    readonly version: "1";
+                };
+                name: string;
+            }];
+            readonly summary: "Chooses the Canvas or parent Frame the position and size are measured against.";
+        }, {
+            readonly name: "x";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "Places the anchor point along the parent's width.";
+        }, {
+            readonly name: "y";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "Places the anchor point down the parent's height.";
+        }, {
+            readonly name: "width";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "Sizes the Frame across the parent's width.";
+        }, {
+            readonly name: "height";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "Sizes the Frame down the parent's height.";
+        }, {
+            readonly name: "anchor";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly values: readonly ["top-left", "top-center", "top-right", "middle-left", "center", "middle-right", "bottom-left", "bottom-center", "bottom-right"];
+            readonly summary: "Chooses which point of the Frame lands on `x` and `y`.";
+        }, {
+            readonly name: "offset-x";
+            readonly kind: "literal";
+            readonly required: false;
+            readonly summary: "Nudges the placed Frame this many pixels along x; defaults to `0`.";
+        }, {
+            readonly name: "offset-y";
+            readonly kind: "literal";
+            readonly required: false;
+            readonly summary: "Nudges the placed Frame this many pixels along y; defaults to `0`.";
+        }];
+        readonly ports: readonly [{
+            readonly name: "";
+            readonly type: {
+                module: {
+                    readonly name: "@hypit/spatial";
+                    readonly version: "1";
+                };
+                name: string;
+            };
+            readonly summary: "The resolved Frame, addressed by the element's own id.";
+        }];
+        readonly example: "<space:AnchoredFrame id=\"card\" within={safe} x=\"50%\" y=\"78%\" width=\"82%\" height=\"28%\" anchor=\"center\"/>";
+        readonly notes: readonly ["The element is empty; it accepts no children and no text.", "A length is a number followed by `px` or `%`; a percentage resolves against the parent Frame's width on the x axis and its height on the y axis.", "`offset-x` and `offset-y` are finite pixel numbers, and a Frame may deliberately sit partly or wholly outside its parent.", "A Canvas written in `within` is first resolved to its own full-Canvas Frame, so every Frame is placed inside a Frame."];
+    };
+}, {
+    readonly name: "aspect-frame";
+    readonly tag: "AspectFrame";
+    readonly mode: "structured";
+    readonly outputs: readonly [{
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    }, {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    }, {
+        module: {
+            readonly name: "@hypit/spatial";
+            readonly version: "1";
+        };
+        name: string;
+    }];
+    readonly vocabulary: {
+        readonly summary: "Places one Frame that keeps a stated aspect ratio, sized on one axis and anchored in the parent.";
+        readonly attributes: readonly [{
+            readonly name: "id";
+            readonly kind: "identifier";
+            readonly required: true;
+            readonly summary: "Names the Frame this element publishes.";
+        }, {
+            readonly name: "within";
+            readonly kind: "reference";
+            readonly required: true;
+            readonly accepts: readonly [{
+                module: {
+                    readonly name: "@hypit/spatial";
+                    readonly version: "1";
+                };
+                name: string;
+            }, {
+                module: {
+                    readonly name: "@hypit/spatial";
+                    readonly version: "1";
+                };
+                name: string;
+            }];
+            readonly summary: "Chooses the Canvas or parent Frame the position and size are measured against.";
+        }, {
+            readonly name: "x";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "Places the anchor point along the parent's width.";
+        }, {
+            readonly name: "y";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly summary: "Places the anchor point down the parent's height.";
+        }, {
+            readonly name: "aspect";
+            readonly kind: "expression";
+            readonly required: true;
+            readonly accepts: readonly [{
+                module: {
+                    readonly name: "@hypit/spatial";
+                    readonly version: "1";
+                };
+                name: string;
+            }];
+            readonly summary: "Fixes the ratio the Frame keeps, as a referenced IntrinsicExtent or a written `width/height` ratio.";
+        }, {
+            readonly name: "anchor";
+            readonly kind: "literal";
+            readonly required: true;
+            readonly values: readonly ["top-left", "top-center", "top-right", "middle-left", "center", "middle-right", "bottom-left", "bottom-center", "bottom-right"];
+            readonly summary: "Chooses which point of the Frame lands on `x` and `y`.";
+        }, {
+            readonly name: "width";
+            readonly kind: "literal";
+            readonly required: false;
+            readonly summary: "Sizes the Frame across the parent's width and derives its height from the ratio.";
+        }, {
+            readonly name: "height";
+            readonly kind: "literal";
+            readonly required: false;
+            readonly summary: "Sizes the Frame down the parent's height and derives its width from the ratio.";
+        }, {
+            readonly name: "offset-x";
+            readonly kind: "literal";
+            readonly required: false;
+            readonly summary: "Nudges the placed Frame this many pixels along x; defaults to `0`.";
+        }, {
+            readonly name: "offset-y";
+            readonly kind: "literal";
+            readonly required: false;
+            readonly summary: "Nudges the placed Frame this many pixels along y; defaults to `0`.";
+        }];
+        readonly ports: readonly [{
+            readonly name: "";
+            readonly type: {
+                module: {
+                    readonly name: "@hypit/spatial";
+                    readonly version: "1";
+                };
+                name: string;
+            };
+            readonly summary: "The resolved Frame, addressed by the element's own id.";
+        }];
+        readonly example: "<space:AspectFrame id=\"sticker\" within={safe} x=\"100%\" y=\"100%\" width=\"32%\" aspect=\"9/16\" anchor=\"bottom-right\"/>";
+        readonly notes: readonly ["The element is empty; it accepts no children and no text.", "Exactly one of `width` or `height` is written; the other axis follows from the ratio.", "A length is a number followed by `px` or `%`; a percentage resolves against the parent Frame's width on the x axis and its height on the y axis.", "A written `aspect` is two positive numbers separated by `/`, such as `9/16`; a referenced `aspect` must be an IntrinsicExtent.", "A Canvas written in `within` is first resolved to its own full-Canvas Frame, so every Frame is placed inside a Frame."];
+    };
+}];
+declare const spatialManifest: ModuleManifest;
+declare const spatialDependency: {
+    readonly module: {
+        readonly name: "@hypit/spatial";
+        readonly version: "1";
+    };
+};
+
+declare const spatialPointSchema: ValueSchema;
+declare const spatialFrameSchema: ValueSchema;
+declare const spatialRegionTimelineSchema: ValueSchema;
+declare const spatialPathSchema: ValueSchema;
+declare const intrinsicExtentSchema: ValueSchema;
+declare const contentFitSchema: ValueSchema;
+
+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 SurfaceDecodeOutput = {
+    readonly records: readonly SurfaceRecordDraft[];
+    readonly components: readonly SurfaceComponentDraft[];
+    readonly fragments: readonly GraphFragment[];
+    /** Domain-owned public identities that must be unique in the Source closure. */
+    readonly identities?: readonly AuthorSourceIdentity[];
+    /**
+     * Public source bindings contributed by this Surface invocation. Omit to
+     * publish every generated binding; use an explicit list to keep plumbing
+     * addressable inside the source without exposing it from the source.
+     */
+    readonly exports?: readonly string[];
+};
+type StructuredSurfaceInput = {
+    readonly sourceName: string;
+    readonly element: StructuredElement;
+    /**
+     * Resolve an explicitly written author reference. Imported record values are
+     * available because their source has already been compiled and admitted.
+     * A component output has a ref and Type but no compile-time Record value.
+     */
+    readonly resolveReference: (path: string) => SurfaceResolvedReference | undefined;
+    readonly resolveAsset: (request: AuthorSourceAssetRequest) => Awaitable<ResolvedAuthorSourceAsset>;
+};
+type SurfaceResolvedReference = {
+    readonly path: string;
+    readonly ref: AuthorValueRef;
+    readonly type: TypeRef;
+    readonly record?: TypedRecord;
+};
+type StructuredSurfaceHandler = (input: StructuredSurfaceInput) => Awaitable<SurfaceDecodeOutput>;
+
+declare const decodeCanvasSurface: StructuredSurfaceHandler;
+declare const decodePointSurface: StructuredSurfaceHandler;
+declare const decodePathSurface: StructuredSurfaceHandler;
+declare const decodeExtentSurface: StructuredSurfaceHandler;
+declare const decodeRegionTimelineSurface: StructuredSurfaceHandler;
+declare const decodeFrameSurface: StructuredSurfaceHandler;
+declare const decodeAnchoredFrameSurface: StructuredSurfaceHandler;
+declare const decodeAspectFrameSurface: StructuredSurfaceHandler;
+
+type SvsRecipe = {
+    readonly path: string;
+    readonly properties: Readonly<Record<string, CanonicalValue>>;
+};
+
+/** Resolve normalized author data into frame-exact Canvas-pixel evidence. */
+declare function spatialRegionTimeline(recipe: SvsRecipe, canvas: CanvasSpace): SpatialRegionTimeline;
+
+export { anchoredFrame, anchoredFrameFragment, aspectFrame, aspectFrameFragment, assertCanvasSpace, assertContentFit, assertFittedContent, assertIntrinsicExtent, assertSpatialFrame, assertSpatialPath, assertSpatialPoint, assertSpatialRegionTimeline, canvasFrame, canvasFrameFragment, contentFitPropertyNames, contentFitSchema, decodeAnchoredFrameSurface, decodeAspectFrameSurface, decodeCanvasSurface, decodeContentFitProperties, decodeExtentSurface, decodeFrameSurface, decodePathSurface, decodePointSurface, decodeRegionTimelineSurface, fitContent, fitContentFragment, frameEdgesFragment, frameFromEdges, intrinsicExtentSchema, sealCanvasSpace, sealContentFit, sealFittedContent, sealIntrinsicExtent, sealSpatialFrame, sealSpatialPath, sealSpatialPoint, sealSpatialRegionTimeline, spatialComponent, spatialDependency, spatialFrameSchema, spatialManifest, spatialMarkupSurfaces, spatialModuleRef, spatialPathSchema, spatialPointSchema, spatialProducers, spatialRegionTimeline, spatialRegionTimelineSchema, spatialTypes };
+export type { AnchoredFrameProgram, AspectFrameProgram, CanvasSpace, ContentFit, FittedContent, FrameEdgesProgram, IntrinsicExtent, NormalizedPoint, SpatialAnchor, SpatialFrame, SpatialLength, SpatialPath, SpatialPathCommand, SpatialPoint, SpatialRegionTimeline, SpatialRegionTrack };