@hypit/hypit 0.0.1 → 0.1.0

package/packages/semantic-track/src/identity.ts

@@ -0,0 +1,58 @@
+import { assertSemanticTakeIdentity } from "@hypit/speech";
+
+import type { SemanticTrack, SemanticTrackSpan } from "./types.js";
+
+export function sealSemanticTrack(value: SemanticTrack): SemanticTrack {
+  const track = structuredClone(value);
+  assertSemanticTrackIdentity(track);
+  return track;
+}
+
+export function assertSemanticTrackIdentity(track: SemanticTrack): void {
+  if (!track.id.trim() || !track.narrativeId.trim() || track.items.length === 0) {
+    throw new Error("SemanticTrack must have identities and contain at least one item.");
+  }
+  const segmentIds = new Set<string>();
+  const tokenIds = new Set<string>();
+  const anchorIds = new Set<string>();
+  let frameRate: SemanticTrack["items"][number]["take"]["media"]["timeline"]["frameRate"] | undefined;
+  for (const item of track.items) {
+    assertSemanticTakeIdentity(item.take);
+    if (item.take.narrativeId !== track.narrativeId) {
+      throw new Error(`SemanticTrack ${track.id} mixes Narrative ${item.take.narrativeId} into ${track.narrativeId}.`);
+    }
+    const rate = item.take.media.timeline.frameRate;
+    if (frameRate === undefined) frameRate = rate;
+    else if (frameRate.numerator !== rate.numerator || frameRate.denominator !== rate.denominator) {
+      throw new Error("SemanticTrack items must use one frame rate.");
+    }
+    const segmentId = item.take.segment.segmentId;
+    if (segmentIds.has(segmentId)) throw new Error(`SemanticTrack repeats Segment ${segmentId}.`);
+    segmentIds.add(segmentId);
+    for (const token of item.take.tokens) {
+      if (tokenIds.has(token.tokenId)) throw new Error(`SemanticTrack repeats Token ${token.tokenId}.`);
+      tokenIds.add(token.tokenId);
+    }
+    for (const anchor of item.take.anchors) {
+      if (anchor.identity === "program:start" || anchor.identity === "program:end") {
+        throw new Error(`SemanticTake cannot declare reserved Program Anchor ${anchor.identity}.`);
+      }
+      if (anchorIds.has(anchor.identity)) throw new Error(`SemanticTrack repeats Anchor ${anchor.identity}.`);
+      anchorIds.add(anchor.identity);
+    }
+  }
+}
+
+export function semanticTrackSpans(track: SemanticTrack): readonly SemanticTrackSpan[] {
+  assertSemanticTrackIdentity(track);
+  let frame = 0;
+  return track.items.map((item) => {
+    const startFrame = frame;
+    frame += item.take.media.timeline.frameCount;
+    return { item, startFrame, endFrameExclusive: frame };
+  });
+}
+
+export function semanticTrackFrameCount(track: SemanticTrack): number {
+  return semanticTrackSpans(track).at(-1)!.endFrameExclusive;
+}

package/packages/semantic-track/src/index.ts

@@ -0,0 +1,6 @@
+export { semanticTrackComponent } from "./component.js";
+export { assertSemanticTrackIdentity, sealSemanticTrack, semanticTrackFrameCount, semanticTrackSpans } from "./identity.js";
+export { assertNarrativeMomentIdentity, assertNarrativeSelectionIdentity, momentFrame, segmentFrameSpan, selectionFrameSpan, semanticAnchorFrames, tokenFrameSpan } from "./location.js";
+export { semanticTrackDependency, semanticTrackManifest, semanticTrackModuleRef, semanticTrackProducers, semanticTrackSchema, semanticTrackTypes } from "./manifest.js";
+export { projectSemanticAudioTrack, projectSemanticProgramSpace, projectSemanticMedia } from "./projection.js";
+export type * from "./types.js";

package/packages/semantic-track/src/location.ts

@@ -0,0 +1,81 @@
+import type { NarrativeExcerpt, NarrativeMomentRef, NarrativeSelectionRef } from "@hypit/narrative";
+
+import { assertSemanticTrackIdentity, semanticTrackFrameCount, semanticTrackSpans } from "./identity.js";
+import type { LocatedFrameSpan, SemanticTrack } from "./types.js";
+
+export function assertNarrativeSelectionIdentity(selection: NarrativeSelectionRef): void {
+  if (!selection.narrativeId || !selection.id || !selection.startAnchorId || !selection.endAnchorId) throw new Error("NarrativeSelection is invalid");
+}
+
+export function assertNarrativeMomentIdentity(moment: NarrativeMomentRef): void {
+  if (!moment.narrativeId || !moment.id || !moment.anchorId) throw new Error("NarrativeMoment is invalid");
+}
+
+function assertNarrativeOwner(track: SemanticTrack, narrativeId: string, label: string): void {
+  if (narrativeId !== track.narrativeId) {
+    throw new Error(`${label} belongs to Narrative ${narrativeId}, not SemanticTrack ${track.id}.`);
+  }
+}
+
+export function semanticAnchorFrames(track: SemanticTrack): ReadonlyMap<string, number> {
+  assertSemanticTrackIdentity(track);
+  return new Map([
+    ["program:start", 0] as const,
+    ...semanticTrackSpans(track).flatMap(({ item, startFrame }) =>
+      item.take.anchors.map((anchor) => [anchor.identity, startFrame + anchor.frame] as const)),
+    ["program:end", semanticTrackFrameCount(track)] as const,
+  ]);
+}
+
+function frameFor(frames: ReadonlyMap<string, number>, anchorId: string, owner: string): number {
+  const frame = frames.get(anchorId);
+  if (frame === undefined) throw new Error(`${owner} names Anchor ${anchorId}, which this SemanticTrack does not contain.`);
+  return frame;
+}
+
+export function selectionFrameSpan(
+  track: SemanticTrack,
+  selection: NarrativeSelectionRef,
+): LocatedFrameSpan {
+  assertSemanticTrackIdentity(track);
+  assertNarrativeSelectionIdentity(selection);
+  assertNarrativeOwner(track, selection.narrativeId, `NarrativeSelection ${selection.id}`);
+  const frames = semanticAnchorFrames(track);
+  return {
+    startFrame: frameFor(frames, selection.startAnchorId, `NarrativeSelection ${selection.id}`),
+    endFrameExclusive: frameFor(frames, selection.endAnchorId, `NarrativeSelection ${selection.id}`),
+  };
+}
+
+export function segmentFrameSpan(track: SemanticTrack, segment: NarrativeExcerpt): LocatedFrameSpan {
+  assertSemanticTrackIdentity(track);
+  if (segment.kind !== "segment" || !segment.id) throw new Error("Narrative Segment excerpt is invalid");
+  assertNarrativeOwner(track, segment.narrativeId, `Narrative Segment ${segment.id}`);
+  const found = semanticTrackSpans(track).find(({ item }) => item.take.segment.segmentId === segment.id);
+  if (found === undefined) throw new Error(`SemanticTrack does not contain Segment ${segment.id}.`);
+  return { startFrame: found.startFrame, endFrameExclusive: found.endFrameExclusive };
+}
+
+export function tokenFrameSpan(track: SemanticTrack, tokenIds: readonly string[]): LocatedFrameSpan | undefined {
+  assertSemanticTrackIdentity(track);
+  if (tokenIds.length === 0) return undefined;
+  const timing = new Map(semanticTrackSpans(track).flatMap(({ item, startFrame }) =>
+    item.take.tokens.map((token) => [token.tokenId, {
+      startFrame: startFrame + token.startFrame,
+      endFrameExclusive: startFrame + token.endFrameExclusive,
+    }] as const)));
+  const located = tokenIds.map((id) => timing.get(id));
+  if (located.some((item) => item === undefined)) return undefined;
+  return {
+    startFrame: located[0]!.startFrame,
+    endFrameExclusive: located.at(-1)!.endFrameExclusive,
+  };
+}
+
+export function momentFrame(track: SemanticTrack, moment: NarrativeMomentRef): number {
+  assertSemanticTrackIdentity(track);
+  assertNarrativeMomentIdentity(moment);
+  assertNarrativeOwner(track, moment.narrativeId, `NarrativeMoment ${moment.id}`);
+  const frames = semanticAnchorFrames(track);
+  return frameFor(frames, moment.anchorId, `NarrativeMoment ${moment.id}`);
+}

package/packages/semantic-track/src/manifest.ts

@@ -0,0 +1,38 @@
+import { compositionDependency, compositionTypes } from "@hypit/composition";
+import { narrativeDependency } from "@hypit/narrative";
+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
+import { semanticTakeSchema, speechDependency } from "@hypit/speech";
+
+export const semanticTrackModuleRef = { name: "@hypit/semantic-track", version: "1" } as const;
+export const semanticTrackTypes = {
+  track: { module: semanticTrackModuleRef, name: "SemanticTrack" },
+} satisfies Record<string, TypeRef>;
+export const semanticTrackProducers = {
+  projectProgramSpace: { module: semanticTrackModuleRef, name: "project-program-space" },
+  projectAudio: { module: semanticTrackModuleRef, name: "project-audio-track" },
+} satisfies Record<string, ProducerRef>;
+
+const string = { kind: "string", minLength: 1 } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+export const semanticTrackSchema: ValueSchema = object({
+  id: { schema: string },
+  narrativeId: { schema: string },
+  items: { schema: { kind: "array", minItems: 1, items: object({
+    take: { schema: semanticTakeSchema },
+  }) } },
+});
+
+export const semanticTrackManifest: ModuleManifest = {
+  format: "hypit.module@1",
+  name: semanticTrackModuleRef.name,
+  version: semanticTrackModuleRef.version,
+  dependencies: [speechDependency, narrativeDependency, programSpaceDependency, compositionDependency],
+  types: [{ name: semanticTrackTypes.track.name }],
+  capabilities: [],
+  producers: [
+    { name: semanticTrackProducers.projectProgramSpace.name, inputs: [{ name: "track", type: semanticTrackTypes.track }], outputs: [{ name: "space", type: programSpaceTypes.programSpace }], needs: [] },
+    { name: semanticTrackProducers.projectAudio.name, inputs: [{ name: "track", type: semanticTrackTypes.track }], outputs: [{ name: "audio", type: compositionTypes.audioTrack }], needs: [] },
+  ],
+};
+export const semanticTrackDependency = { module: semanticTrackModuleRef } as const;

package/packages/semantic-track/src/projection.ts

@@ -0,0 +1,71 @@
+import { sealAudioTrack } from "@hypit/composition";
+import type { AudioTrack } from "@hypit/composition";
+import { synchronizedMediaSampleFrames } from "@hypit/media";
+import {
+  programFrameSampleBoundary,
+  sealProgramSpace,
+} from "@hypit/program-space";
+import type { ProgramSpace } from "@hypit/program-space";
+
+import { assertSemanticTrackIdentity, semanticTrackFrameCount, semanticTrackSpans } from "./identity.js";
+import type { SemanticTrack } from "./types.js";
+
+/** Prepared material in an authored program interval, with its original source position retained. */
+export function projectSemanticMedia(track: SemanticTrack, window = {
+  startFrame: 0, endFrameExclusive: semanticTrackFrameCount(track),
+}) {
+  assertSemanticTrackIdentity(track);
+  if (!Number.isSafeInteger(window.startFrame) || !Number.isSafeInteger(window.endFrameExclusive)
+    || window.startFrame < 0 || window.endFrameExclusive <= window.startFrame
+    || window.endFrameExclusive > semanticTrackFrameCount(track)) throw new Error("Semantic media window is outside the performance.");
+  return semanticTrackSpans(track).flatMap(({ item, startFrame, endFrameExclusive }) => {
+    const start = Math.max(window.startFrame, startFrame);
+    const end = Math.min(window.endFrameExclusive, endFrameExclusive);
+    return end <= start ? [] : [{
+      segmentId: item.take.segment.segmentId,
+      media: item.take.media,
+      span: { startFrame: start, endFrameExclusive: end },
+      source: { startFrame: start - startFrame, endFrameExclusive: end - startFrame },
+    }];
+  });
+}
+
+export function projectSemanticProgramSpace(track: SemanticTrack): ProgramSpace {
+  assertSemanticTrackIdentity(track);
+  const frameRate = track.items[0]!.take.media.timeline.frameRate;
+  return sealProgramSpace({
+    id: track.id,
+    durationSec: semanticTrackFrameCount(track) * frameRate.denominator / frameRate.numerator,
+    frameRate,
+  });
+}
+
+export function projectSemanticAudioTrack(track: SemanticTrack): AudioTrack {
+  const space = projectSemanticProgramSpace(track);
+  const clips = semanticTrackSpans(track).flatMap(({ item, startFrame, endFrameExclusive }) => {
+    const audio = item.take.media.audio;
+    if (audio === undefined) return [];
+    const sourceSampleFrames = synchronizedMediaSampleFrames(item.take.media);
+    const targetStartSample = programFrameSampleBoundary(space, startFrame, 48_000);
+    const targetEndSampleExclusive = programFrameSampleBoundary(space, endFrameExclusive, 48_000);
+    return [{
+      id: item.take.segment.segmentId,
+      subjectId: item.take.segment.segmentId,
+      artifact: audio.artifact,
+      target: { startSample: targetStartSample, endSampleExclusive: targetEndSampleExclusive },
+      source: {
+        sampleFrames: sourceSampleFrames,
+        startSample: 0,
+        endSampleExclusive: sourceSampleFrames,
+        loop: false,
+        phaseSample: 0,
+      },
+      playbackRate: 1,
+      pitch: "preserve" as const,
+      gain: 1,
+      fadeInSamples: 0,
+      fadeOutSamples: 0,
+    }];
+  });
+  return sealAudioTrack({ programSpaceId: space.id, id: `${track.id}:audio`, clips });
+}

package/packages/semantic-track/src/types.ts

@@ -0,0 +1,26 @@
+import type { SemanticTake } from "@hypit/speech";
+
+export 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.
+ */
+export type SemanticTrack = {
+  readonly id: string;
+  readonly narrativeId: string;
+  readonly items: readonly SemanticTrackItem[];
+};
+
+export type SemanticTrackSpan = {
+  readonly item: SemanticTrackItem;
+  readonly startFrame: number;
+  readonly endFrameExclusive: number;
+};
+
+export type LocatedFrameSpan = {
+  readonly startFrame: number;
+  readonly endFrameExclusive: number;
+};

package/packages/source/README.md

@@ -0,0 +1,13 @@
+# `@hypit/source`
+
+The smallest source bootstrap shared by Author and Run compilation.
+
+It recognizes exactly one mandatory bounded Header:
+
+```xml
+<?svml using="@hypit/markup@1"?>
+```
+
+The Header selects an exact trusted Frontend. There is no suffix dispatch and no default parser.
+The package masks the Header while preserving character offsets, but does not recognize imports,
+XML, Script, Recipes, Run syntax or domain Types. Those belong to the selected Frontend.

package/packages/source/package.json

@@ -0,0 +1,13 @@
+{
+  "name": "@hypit/source",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@hypit/protocol": "workspace:*"
+  }
+}

package/packages/source/src/header.ts

@@ -0,0 +1,80 @@
+export type SourceHeader = {
+  /** Logical Frontend request. A trusted Host resolves it to one exact implementation. */
+  readonly using: string;
+  readonly start: number;
+  readonly end: number;
+};
+
+export class SourceHeaderError extends Error {
+  readonly code: string;
+  readonly sourceName: string;
+  readonly offset: number;
+  readonly line: number;
+  readonly column: number;
+
+  constructor(code: string, message: string, sourceName: string, source: string, offset: number) {
+    const before = source.slice(0, offset);
+    const line = before.split("\n").length;
+    const column = [...(before.split("\n").at(-1) ?? "")].length + 1;
+    super(`${sourceName}:${line}:${column}: ${message}`);
+    this.name = "SourceHeaderError";
+    this.code = code;
+    this.sourceName = sourceName;
+    this.offset = offset;
+    this.line = line;
+    this.column = column;
+  }
+}
+
+const FRONTEND = /^[^\s<>&'"]+$/u;
+
+function fail(sourceName: string, source: string, code: string, message: string, offset: number): never {
+  throw new SourceHeaderError(code, message, sourceName, source, offset);
+}
+
+/**
+ * Parse the single irreducible SVML bootstrap directive.
+ *
+ * The grammar deliberately has no comments, aliases, interpolation or defaults:
+ *
+ *     [UTF-8 BOM] <?svml using="logical-frontend-request"?>
+ */
+export function parseSourceHeader(sourceName: string, text: string): SourceHeader {
+  const start = text.charCodeAt(0) === 0xfeff ? 1 : 0;
+  if (!text.startsWith("<?svml", start)) {
+    fail(sourceName, text, "SOURCE_HEADER_MISSING", 'Source must begin with <?svml using="..."?>', start);
+  }
+  const relativeClose = text.indexOf("?>", start + "<?svml".length);
+  if (relativeClose < 0) {
+    fail(sourceName, text, "SOURCE_HEADER_UNCLOSED", "Source Header is not closed", start);
+  }
+  const close = relativeClose;
+  const raw = text.slice(start, close + 2);
+  const match = /^<\?svml[ \t]+using=(['"])([^'"\r\n]+)\1[ \t]*\?>$/u.exec(raw);
+  if (match === null) {
+    fail(
+      sourceName,
+      text,
+      "SOURCE_HEADER_INVALID",
+      'Source Header must use exactly <?svml using="logical-frontend-request"?>',
+      start,
+    );
+  }
+  const using = match[2]!;
+  if (!FRONTEND.test(using)) {
+    fail(sourceName, text, "SOURCE_HEADER_FRONTEND", "Source Header Frontend request must not be empty or padded", start);
+  }
+  const end = close + 2;
+  const after = text.slice(end);
+  const nextContent = /\S/u.exec(after);
+  if (nextContent !== null && after.startsWith("<?svml", nextContent.index)) {
+    fail(sourceName, text, "SOURCE_HEADER_DUPLICATE", "Source declares more than one Source Header", end + nextContent.index);
+  }
+  return { using, start, end };
+}
+
+/** Preserve every original offset while making the Header ordinary whitespace to body Frontends. */
+export function maskSourceHeader(text: string, header: SourceHeader): string {
+  const prefix = text.slice(0, header.end).replace(/[^\r\n]/gu, " ");
+  return `${prefix}${text.slice(header.end)}`;
+}

package/packages/source/src/index.ts

@@ -0,0 +1,17 @@
+export {
+  maskSourceHeader,
+  parseSourceHeader,
+  SourceHeaderError,
+} from "./header.js";
+export type { SourceHeader } from "./header.js";
+export type {
+  Awaitable,
+  ResolvedSourceAsset,
+  SourceAssetRequest,
+  SourceAssetResolver,
+  SourceImportRequest,
+  SourceResolver,
+  SourceUnit,
+} from "./unit.js";
+/** Logical package address for Source Frontends selected by a Source Header. */
+export const sourceFrontendPackageAbi = "hypit.source-frontend@1";

package/packages/source/src/unit.ts

@@ -0,0 +1,38 @@
+import type { BlobRef, SourceRange } from "@hypit/protocol";
+
+export type SourceUnit = {
+  /** Host-canonical identity used only for recursion and diagnostics. */
+  readonly id: string;
+  readonly name: string;
+  readonly text: string;
+};
+
+export type SourceImportRequest = {
+  readonly from: string;
+  readonly alias: string;
+  readonly range?: SourceRange;
+};
+
+export 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;
+};
+
+export type ResolvedSourceAsset = {
+  readonly artifact: BlobRef;
+};
+
+export type Awaitable<T> = T | Promise<T>;
+
+export type SourceResolver = (
+  importer: SourceUnit,
+  request: SourceImportRequest,
+) => Awaitable<SourceUnit>;
+
+export type SourceAssetResolver = (
+  importer: SourceUnit,
+  request: SourceAssetRequest,
+) => Awaitable<ResolvedSourceAsset>;

package/packages/spatial/README.md

@@ -0,0 +1,77 @@
+# `@hypit/spatial`
+
+Shared video-domain geometry: explicit Canvas coordinates, Points, Frames, Paths, externally measured
+Region Timelines, intrinsic extents and deterministic two-frame content fitting. It owns no semantic
+timing, Paint, motion, media decoding,
+renderer, Provider or Core behavior.
+
+The package exposes self-described `Canvas`, `Point`, `Path`, `Extent`, `RegionTimeline`, `Frame`,
+`AnchoredFrame` and `AspectFrame` author Surfaces plus pure geometry functions and fixed-port Producers.
+
+## Destination and fitted content
+
+`SpatialFrame` is a destination rectangle in Canvas pixels. `IntrinsicExtent` supplies source
+dimensions. `fitContent(frame, extent, fit)` returns a `FittedContent.contentFrame`: the scaled
+source's rectangle in the same coordinates. The caller supplies the fitting area; Media Track
+derives that area by subtracting its border and padding from its outer Frame.
+
+`ContentFit.sizing` selects the size before alignment:
+
+| Sizing | Result |
+| --- | --- |
+| `contain` | Preserve aspect and fit both dimensions inside the destination |
+| `cover` | Preserve aspect and cover both destination dimensions |
+| `fit-width` / `fit-height` | Preserve aspect and match the named dimension |
+| `native` | Keep the source's pixel dimensions |
+| `scale-down` | Use `contain` while limiting scale to at most 1 |
+| `stretch` | Use the destination width and height independently |
+
+`framePoint` and `contentPoint` are separate normalized points in `[0,1]`. The scaled source point
+is placed at the destination point, then `offsetPx` is added. Before any constraint, the horizontal
+position is `frame.xPx + frame.widthPx * framePoint.x - contentWidth * contentPoint.x + offsetPx.x`;
+the vertical position follows the same relationship.
+
+`constraint: bounded` clamps each coordinate between `frameStart` and
+`frameStart + frameSize - contentSize`, whichever is lower or higher. Large content keeps the
+destination covered on that axis, and small content stays inside it. `free` leaves the calculated
+position unchanged. Fitting calculates rectangles; the consuming component owns clipping.
+
+`decodeContentFitProperties` exposes these through Recipe keys: `fit`, `frame-x`, `frame-y`,
+`content-x`, `content-y`, `fit-offset-x`, `fit-offset-y`, and `fit-constraint`. Defaults are `contain`,
+center points (`0.5`), zero pixel offsets and `bounded`. These alignment fractions place the source
+inside the supplied destination. Canvas placement remains the job of Frame / AnchoredFrame /
+AspectFrame. Media Track uses this decoder for Items, Performances and Sequence members; project
+components can use the same fitting functions where that presentation fits their role.
+
+## Measured regions
+
+`RegionTimeline` accepts already measured data rather than running a detector. Face detection and
+tracking can observe the footage produced by an earlier Build: keep useful boxes as ordinary numbers,
+then reuse that media while rendering Caption with the finished timeline. Measurement precedes the
+composition that consumes it; it need not precede the first media-producing Build. RegionTimeline
+does not start a detector to discover its own layout. One SVS Recipe holds the exact ProgramSpace
+frame count and named tracks whose array positions are Frames:
+
+```svs
+heads.default {
+  frame-count: 3;
+  tracks: [
+    {"id":"WIFE","regions":[[0.12,0.09,0.20,0.26],null,[0.13,0.10,0.20,0.26]]}
+  ];
+}
+```
+
+```svml
+<space:RegionTimeline id="heads" within={vertical} recipe={tracking.heads.default}/>
+```
+
+Every measured region is normalized `[x, y, width, height]`; `null` says that this track has no
+measured region on that Frame. The Surface converts measured regions to the selected Canvas's pixels
+at author time; it never fills missing Frames or interprets a track id.
+
+Prepare measurements against the exact edited media, clock and Canvas used by the composition.
+Individual Take measurements need their actual frame offsets in the program; boxes measured before
+a crop, resize or inset need that placement transform. Face-to-head expansion, identity association,
+cut handling and any interpolation are explicit external preparation decisions. The resulting
+Recipe records their output. Caption consumers can assign Role meaning to track ids without making
+Spatial aware of speakers, detector APIs or generated-media Providers.

package/packages/spatial/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@hypit/spatial",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/component-kit": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/markup": "workspace:*",
+    "@hypit/svs": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/core": "workspace:*",
+    "@hypit/validation": "workspace:*"
+  }
+}

package/packages/spatial/src/activation.ts

@@ -0,0 +1,43 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+  decodeAnchoredFrameSurface,
+  decodeAspectFrameSurface,
+  decodeCanvasSurface,
+  decodeExtentSurface,
+  decodeFrameSurface,
+  decodePathSurface,
+  decodePointSurface,
+  decodeRegionTimelineSurface,
+} from "./surface.js";
+import {
+  spatialManifest,
+  spatialModuleRef,
+  spatialMarkupSurfaces,
+} from "./manifest.js";
+import { spatialComponent } from "./component.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: spatialManifest }],
+  components: [spatialComponent],
+  hostFacets: [
+    createMarkupSurfaceHostFacet({ module: spatialModuleRef,
+    declaration: spatialMarkupSurfaces.find((item) => item.name === "canvas")!, handler: decodeCanvasSurface }),
+    createMarkupSurfaceHostFacet({ module: spatialModuleRef,
+    declaration: spatialMarkupSurfaces.find((item) => item.name === "point")!, handler: decodePointSurface }),
+    createMarkupSurfaceHostFacet({ module: spatialModuleRef,
+    declaration: spatialMarkupSurfaces.find((item) => item.name === "path")!, handler: decodePathSurface }),
+    createMarkupSurfaceHostFacet({ module: spatialModuleRef,
+    declaration: spatialMarkupSurfaces.find((item) => item.name === "extent")!, handler: decodeExtentSurface }),
+    createMarkupSurfaceHostFacet({ module: spatialModuleRef,
+    declaration: spatialMarkupSurfaces.find((item) => item.name === "region-timeline")!, handler: decodeRegionTimelineSurface }),
+    createMarkupSurfaceHostFacet({ module: spatialModuleRef,
+    declaration: spatialMarkupSurfaces.find((item) => item.name === "frame")!, handler: decodeFrameSurface }),
+    createMarkupSurfaceHostFacet({ module: spatialModuleRef,
+    declaration: spatialMarkupSurfaces.find((item) => item.name === "anchored-frame")!, handler: decodeAnchoredFrameSurface }),
+    createMarkupSurfaceHostFacet({ module: spatialModuleRef,
+    declaration: spatialMarkupSurfaces.find((item) => item.name === "aspect-frame")!, handler: decodeAspectFrameSurface }),
+  ],
+};
+export default hypitPackage;

package/packages/spatial/src/author.ts

@@ -0,0 +1,59 @@
+import type { CanonicalValue } from "@hypit/protocol";
+
+import { sealContentFit } from "./geometry.js";
+import type { ContentFit } from "./types.js";
+
+export const contentFitPropertyNames = [
+  "fit", "frame-x", "frame-y", "content-x", "content-y",
+  "fit-offset-x", "fit-offset-y", "fit-constraint",
+] as const;
+
+function number(
+  properties: Readonly<Record<string, CanonicalValue>>,
+  name: string,
+  fallback: number,
+  owner: string,
+): number {
+  const value = properties[name];
+  if (value === undefined) return fallback;
+  if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${owner} ${name} must be a finite number.`);
+  return value;
+}
+
+function oneOf<T extends string>(
+  properties: Readonly<Record<string, CanonicalValue>>,
+  name: string,
+  allowed: readonly T[],
+  fallback: T,
+  owner: string,
+): T {
+  const value = properties[name];
+  if (value === undefined) return fallback;
+  if (typeof value !== "string" || !allowed.includes(value as T)) {
+    throw new Error(`${owner} ${name} must be ${allowed.join(" | ")}.`);
+  }
+  return value as T;
+}
+
+/** Decode the shared spatial-fit vocabulary from any author-side property map. */
+export function decodeContentFitProperties(
+  properties: Readonly<Record<string, CanonicalValue>>,
+  owner = "Content-fit properties",
+): ContentFit {
+  return sealContentFit({
+    sizing: oneOf(properties, "fit", ["contain", "cover", "fit-width", "fit-height", "native", "scale-down", "stretch"] as const, "contain", owner),
+    framePoint: {
+      x: number(properties, "frame-x", 0.5, owner),
+      y: number(properties, "frame-y", 0.5, owner),
+    },
+    contentPoint: {
+      x: number(properties, "content-x", 0.5, owner),
+      y: number(properties, "content-y", 0.5, owner),
+    },
+    offsetPx: {
+      x: number(properties, "fit-offset-x", 0, owner),
+      y: number(properties, "fit-offset-y", 0, owner),
+    },
+    constraint: oneOf(properties, "fit-constraint", ["bounded", "free"] as const, "bounded", owner),
+  });
+}