@hypit/hypit 0.0.1 → 0.1.0

package/packages/media/src/component.ts

@@ -0,0 +1,16 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import { verifyMediaInspection, verifyMediaStreamSelection, verifyMuxedMedia, verifyRenderedVisual, verifySynchronizedMedia, verifyTimelineAudio } from "./identity.js";
+import { mediaTypes } from "./manifest.js";
+import { verifyMediaFrameRange } from "./frame-range.js";
+function inline(value: { readonly kind: string; readonly value?: unknown }, subject: string): unknown { if (value.kind !== "inline") throw new Error(`${subject} must be inline`); return value.value; }
+export const mediaComponent = {
+  validators: [
+    { type: mediaTypes.frameRange, handler: ({ value }) => verifyMediaFrameRange(inline(value, "MediaFrameRange")) },
+    { type: mediaTypes.inspection, handler: ({ value }) => verifyMediaInspection(inline(value, "MediaInspection")) },
+    { type: mediaTypes.streamSelection, handler: ({ value }) => verifyMediaStreamSelection(inline(value, "MediaStreamSelection")) },
+    { type: mediaTypes.synchronized, handler: ({ value }) => verifySynchronizedMedia(inline(value, "SynchronizedMedia")) },
+    { type: mediaTypes.renderedVisual, handler: ({ value }) => verifyRenderedVisual(inline(value, "RenderedVisual")) },
+    { type: mediaTypes.timelineAudio, handler: ({ value }) => verifyTimelineAudio(inline(value, "TimelineAudio")) },
+    { type: mediaTypes.muxed, handler: ({ value }) => verifyMuxedMedia(inline(value, "MuxedMedia")) },
+  ],
+} satisfies ComponentPackage;

package/packages/media/src/frame-range.ts

@@ -0,0 +1,33 @@
+import type { MediaRational } from "./types.js";
+
+/** A half-open selection on the original programme frame clock. */
+export type MediaFrameRange = {
+  readonly startFrame: number;
+  readonly endFrameExclusive: number;
+};
+
+export function verifyMediaFrameRange(value: unknown, frameCount?: number): asserts value is MediaFrameRange {
+  const range = value as MediaFrameRange | undefined;
+  if (range === null || typeof range !== "object"
+    || !Number.isSafeInteger(range.startFrame) || range.startFrame < 0
+    || !Number.isSafeInteger(range.endFrameExclusive) || range.endFrameExclusive <= range.startFrame
+    || (frameCount !== undefined && range.endFrameExclusive > frameCount)) {
+    throw new Error("Media frame range must satisfy 0 <= startFrame < endFrameExclusive <= frameCount");
+  }
+}
+
+/**
+ * Start on the original clock; duration belongs to the new zero-based frame clock.
+ * At rational rates, rounding the two clocks can differ by one PCM sample.
+ */
+export function mediaFrameRangeSamples(range: MediaFrameRange, frameRate: MediaRational) {
+  verifyMediaFrameRange(range);
+  const boundary = (frame: number): number => {
+    const n = BigInt(frame) * 48_000n * BigInt(frameRate.denominator);
+    const d = BigInt(frameRate.numerator);
+    return Number((2n * n + d) / (2n * d));
+  };
+  const startSample = boundary(range.startFrame);
+  const sampleFrames = boundary(range.endFrameExclusive - range.startFrame);
+  return { startSample, endSampleExclusive: startSample + sampleFrames, sampleFrames };
+}

package/packages/media/src/identity.ts

@@ -0,0 +1,227 @@
+import {
+  canonicalize,
+  isResourceId,
+} from "@hypit/protocol";
+import type { BlobRef } from "@hypit/protocol";
+
+import type {
+  MediaInspection,
+  MuxedMedia,
+  MediaRational,
+  RenderedVisual,
+  MediaStream,
+  MediaStreamSelection,
+  MediaTimestamp,
+  SynchronizedMedia,
+  TimelineAudio,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function object(value: unknown, subject: string): Record<string, unknown> {
+  assert(value !== null && typeof value === "object" && !Array.isArray(value), `${subject} must be an object`);
+  return value as Record<string, unknown>;
+}
+
+function nonNegativeInteger(value: unknown, subject: string): number {
+  assert(Number.isSafeInteger(value) && (value as number) >= 0, `${subject} must be a non-negative integer`);
+  return value as number;
+}
+
+function positiveInteger(value: unknown, subject: string): number {
+  const result = nonNegativeInteger(value, subject);
+  assert(result > 0, `${subject} must be positive`);
+  return result;
+}
+
+function verifyRational(value: unknown, subject: string): asserts value is MediaRational {
+  const item = object(value, subject);
+  positiveInteger(item.numerator, `${subject}.numerator`);
+  positiveInteger(item.denominator, `${subject}.denominator`);
+}
+
+function verifyTimestamp(value: unknown, subject: string): asserts value is MediaTimestamp {
+  const item = object(value, subject);
+  assert(typeof item.ticks === "string" && /^-?\d+$/u.test(item.ticks), `${subject}.ticks is invalid`);
+  verifyRational(item.timeBase, `${subject}.timeBase`);
+}
+
+function compareTimestamp(left: MediaTimestamp, right: MediaTimestamp): number {
+  const leftTicks = BigInt(left.ticks) * BigInt(left.timeBase.numerator);
+  const rightTicks = BigInt(right.ticks) * BigInt(right.timeBase.numerator);
+  const leftScaled = leftTicks * BigInt(right.timeBase.denominator);
+  const rightScaled = rightTicks * BigInt(left.timeBase.denominator);
+  return leftScaled < rightScaled ? -1 : leftScaled > rightScaled ? 1 : 0;
+}
+
+function verifyBlob(value: unknown, subject: string): asserts value is BlobRef {
+  const item = object(value, subject);
+  assert(item.kind === "blob", `${subject} must be a BlobRef`);
+  assert(typeof item.resource === "string" && isResourceId(item.resource), `${subject}.resource is invalid`);
+  nonNegativeInteger(item.size, `${subject}.size`);
+  assert(typeof item.mediaType === "string" && item.mediaType.length > 0, `${subject}.mediaType is invalid`);
+}
+
+function verifyStream(value: unknown, subject: string): asserts value is MediaStream {
+  const item = object(value, subject);
+  nonNegativeInteger(item.index, `${subject}.index`);
+  assert(typeof item.codecType === "string" && item.codecType.length > 0, `${subject}.codecType is invalid`);
+  assert(typeof item.codecName === "string" && item.codecName.length > 0, `${subject}.codecName is invalid`);
+  assert(item.timingStatus === "admissible" || item.timingStatus === "missing"
+    || item.timingStatus === "non-monotonic" || item.timingStatus === "discontinuous",
+  `${subject}.timingStatus is invalid`);
+  nonNegativeInteger(item.decodedUnitCount, `${subject}.decodedUnitCount`);
+  const disposition = object(item.disposition, `${subject}.disposition`);
+  assert(typeof disposition.default === "boolean", `${subject}.disposition.default is invalid`);
+  assert(typeof disposition.attachedPicture === "boolean", `${subject}.disposition.attachedPicture is invalid`);
+  if (item.timeBase !== undefined) verifyRational(item.timeBase, `${subject}.timeBase`);
+  if (item.startPts !== undefined) verifyTimestamp(item.startPts, `${subject}.startPts`);
+  if (item.endPts !== undefined) verifyTimestamp(item.endPts, `${subject}.endPts`);
+  assert((item.startPts === undefined) === (item.endPts === undefined), `${subject} must provide both presentation endpoints`);
+  assert(item.timingStatus !== "admissible" || item.startPts !== undefined,
+    `${subject} admissible timing has no presentation interval`);
+  if (item.startPts !== undefined && item.endPts !== undefined) {
+    assert(compareTimestamp(item.startPts, item.endPts) < 0, `${subject} presentation interval is empty or reversed`);
+  }
+  if (item.kind === "video") {
+    assert(item.codecType === "video", `${subject} video codecType differs`);
+    assert(item.role === "moving" || item.role === "attached-picture" || item.role === "still", `${subject}.role is invalid`);
+    positiveInteger(item.width, `${subject}.width`);
+    positiveInteger(item.height, `${subject}.height`);
+    verifyRational(item.sampleAspectRatio, `${subject}.sampleAspectRatio`);
+    assert(item.rotationDegrees === 0 || item.rotationDegrees === 90
+      || item.rotationDegrees === 180 || item.rotationDegrees === 270,
+    `${subject}.rotationDegrees is invalid`);
+    if (item.averageFrameRate !== undefined) verifyRational(item.averageFrameRate, `${subject}.averageFrameRate`);
+    if (item.nominalFrameRate !== undefined) verifyRational(item.nominalFrameRate, `${subject}.nominalFrameRate`);
+    if (item.role === "attached-picture") {
+      assert(disposition.attachedPicture === true, `${subject} attached-picture role differs from disposition`);
+    }
+  } else if (item.kind === "audio") {
+    assert(item.codecType === "audio", `${subject} audio codecType differs`);
+    positiveInteger(item.sampleRate, `${subject}.sampleRate`);
+    positiveInteger(item.channels, `${subject}.channels`);
+    nonNegativeInteger(item.decodedSampleFrames, `${subject}.decodedSampleFrames`);
+    if (item.channelLayout !== undefined) {
+      assert(typeof item.channelLayout === "string" && item.channelLayout.length > 0, `${subject}.channelLayout is invalid`);
+    }
+  } else {
+    assert(item.kind === "other", `${subject}.kind is invalid`);
+  }
+}
+
+function expectedSampleFrames(frameCount: number, frameRate: MediaRational): number {
+  const numerator = BigInt(frameCount) * 48_000n * BigInt(frameRate.denominator);
+  const denominator = BigInt(frameRate.numerator);
+  const rounded = (numerator * 2n + denominator) / (denominator * 2n);
+  assert(rounded > 0n && rounded <= BigInt(Number.MAX_SAFE_INTEGER), "Media frame domain has an invalid sample count");
+  return Number(rounded);
+}
+
+export function sealMediaInspection(value: MediaInspection): MediaInspection {
+  return canonicalize(value) as unknown as MediaInspection;
+}
+
+export function verifyMediaInspection(value: unknown): asserts value is MediaInspection {
+  const item = object(value, "MediaInspection") as unknown as MediaInspection;
+  assert(Array.isArray(item.container?.formatNames), "MediaInspection container formats are invalid");
+  item.container.formatNames.forEach((format) => assert(typeof format === "string" && format.length > 0,
+    "MediaInspection container format is invalid"));
+  assert(Array.isArray(item.streams), "MediaInspection streams are invalid");
+  item.streams.forEach((stream, index) => verifyStream(stream, `MediaInspection.streams[${index}]`));
+  assert(new Set(item.streams.map((stream) => stream.index)).size === item.streams.length,
+    "MediaInspection repeats a stream index");
+}
+
+export function sealMediaStreamSelection(value: MediaStreamSelection): MediaStreamSelection {
+  return canonicalize(value) as unknown as MediaStreamSelection;
+}
+
+export function verifyMediaStreamSelection(value: unknown): asserts value is MediaStreamSelection {
+  const item = object(value, "MediaStreamSelection") as unknown as MediaStreamSelection;
+  if (item.videoStreamIndex !== undefined) nonNegativeInteger(item.videoStreamIndex, "MediaStreamSelection.videoStreamIndex");
+  if (item.audioStreamIndex !== undefined) nonNegativeInteger(item.audioStreamIndex, "MediaStreamSelection.audioStreamIndex");
+  assert(item.videoStreamIndex !== undefined || item.audioStreamIndex !== undefined,
+    "MediaStreamSelection selects no stream");
+  assert(item.spanAuthority === "video" || item.spanAuthority === "audio", "MediaStreamSelection authority is invalid");
+  assert(item.spanAuthority === "video" ? item.videoStreamIndex !== undefined : item.audioStreamIndex !== undefined,
+    "MediaStreamSelection authority stream is absent");
+  assert(item.policy === "primary-moving@1" || item.policy === "default-audio@1"
+    || item.policy === "primary-moving-default-audio@1" || item.policy === "explicit-streams@1",
+    "MediaStreamSelection policy is invalid");
+}
+
+export function sealSynchronizedMedia(value: SynchronizedMedia): SynchronizedMedia {
+  return canonicalize(value) as unknown as SynchronizedMedia;
+}
+
+/** Exact 48 kHz sample span implied by one normalized frame domain. */
+export function synchronizedMediaSampleFrames(value: SynchronizedMedia): number {
+  const numerator = BigInt(value.timeline.frameCount) * 48_000n * BigInt(value.timeline.frameRate.denominator);
+  const denominator = BigInt(value.timeline.frameRate.numerator);
+  const rounded = (numerator * 2n + denominator) / (denominator * 2n);
+  assert(rounded > 0n && rounded <= BigInt(Number.MAX_SAFE_INTEGER),
+    "SynchronizedMedia frame domain has an invalid sample span");
+  return Number(rounded);
+}
+
+export function verifySynchronizedMedia(value: unknown): asserts value is SynchronizedMedia {
+  const item = object(value, "SynchronizedMedia") as unknown as SynchronizedMedia;
+  verifyRational(item.timeline.frameRate, "SynchronizedMedia.timeline.frameRate");
+  positiveInteger(item.timeline.frameCount, "SynchronizedMedia.timeline.frameCount");
+  synchronizedMediaSampleFrames(item);
+  assert(item.visual !== undefined || item.audio !== undefined, "SynchronizedMedia contains no media projection");
+  if (item.visual !== undefined) {
+    verifyBlob(item.visual.artifact, "SynchronizedMedia.visual.artifact");
+    assert(item.visual.artifact.mediaType.startsWith("video/"), "SynchronizedMedia visual artifact is not video");
+    positiveInteger(item.visual.width, "SynchronizedMedia.visual.width");
+    positiveInteger(item.visual.height, "SynchronizedMedia.visual.height");
+  }
+  if (item.audio !== undefined) {
+    verifyBlob(item.audio.artifact, "SynchronizedMedia.audio.artifact");
+    assert(item.audio.artifact.mediaType === "audio/wav", "SynchronizedMedia audio artifact must be WAV");
+  }
+}
+
+export function sealRenderedVisual(value: RenderedVisual): RenderedVisual {
+  return canonicalize(value) as unknown as RenderedVisual;
+}
+
+export function verifyRenderedVisual(value: unknown): asserts value is RenderedVisual {
+  const item = object(value, "RenderedVisual") as unknown as RenderedVisual;
+  verifyRational(item.frameRate, "RenderedVisual.frameRate");
+  positiveInteger(item.frameCount, "RenderedVisual.frameCount");
+  positiveInteger(item.canvas?.width, "RenderedVisual.canvas.width");
+  positiveInteger(item.canvas?.height, "RenderedVisual.canvas.height");
+  verifyBlob(item.artifact, "RenderedVisual.artifact");
+  assert(item.artifact.mediaType.startsWith("video/"), "RenderedVisual Artifact must be video");
+}
+
+export function sealTimelineAudio(value: TimelineAudio): TimelineAudio {
+  return canonicalize(value) as unknown as TimelineAudio;
+}
+
+export function verifyTimelineAudio(value: unknown): asserts value is TimelineAudio {
+  const item = object(value, "TimelineAudio") as unknown as TimelineAudio;
+  verifyBlob(item.artifact, "TimelineAudio.artifact");
+  assert(item.artifact.mediaType === "audio/wav", "TimelineAudio Artifact must be WAV");
+  positiveInteger(item.sampleFrames, "TimelineAudio.sampleFrames");
+}
+
+export function sealMuxedMedia(value: MuxedMedia): MuxedMedia {
+  return canonicalize(value) as unknown as MuxedMedia;
+}
+
+export function verifyMuxedMedia(value: unknown): asserts value is MuxedMedia {
+  const item = object(value, "MuxedMedia") as unknown as MuxedMedia;
+  verifyRational(item.frameRate, "MuxedMedia.frameRate");
+  positiveInteger(item.frameCount, "MuxedMedia.frameCount");
+  positiveInteger(item.canvas?.width, "MuxedMedia.canvas.width");
+  positiveInteger(item.canvas?.height, "MuxedMedia.canvas.height");
+  assert(item.presentationSampleFrames === expectedSampleFrames(item.frameCount, item.frameRate),
+    "MuxedMedia presentation sample count differs from its frame domain");
+  verifyBlob(item.artifact, "MuxedMedia.artifact");
+  assert(item.artifact.mediaType === "video/mp4", "MuxedMedia Artifact must be MP4");
+}

package/packages/media/src/index.ts

@@ -0,0 +1,15 @@
+export {
+  decodeMediaAudioSurface,
+  decodeMediaFontSurface,
+  decodeMediaImageSurface,
+  decodeMediaVideoSurface,
+} from "./surface.js";
+export { mediaComponent } from "./component.js";
+export { sealMediaInspection, sealMediaStreamSelection, sealMuxedMedia, sealRenderedVisual, sealSynchronizedMedia, sealTimelineAudio, synchronizedMediaSampleFrames, verifyMediaInspection, verifyMediaStreamSelection, verifyMuxedMedia, verifyRenderedVisual, verifySynchronizedMedia, verifyTimelineAudio } from "./identity.js";
+export { mediaDependency, mediaManifest, mediaMarkupSurfaces, mediaModuleRef, mediaTypes } from "./manifest.js";
+export { compositableSurfaceSchema, fontArtifactSchema, fontStackSchema, mediaInspectionSchema, mediaStreamSelectionSchema, muxedMediaSchema, renderedVisualSchema, synchronizedMediaSchema, timelineAudioSchema } from "./schema.js";
+export { assertCompositableSurfaceRef, assertFontArtifactRef, assertFontStackRef } from "./render.js";
+export type * from "./render.js";
+export type * from "./types.js";
+export { verifyMediaFrameRange, mediaFrameRangeSamples } from "./frame-range.js";
+export type { MediaFrameRange } from "./frame-range.js";

package/packages/media/src/manifest.ts

@@ -0,0 +1,122 @@
+import { artifactDependency, artifactTypes } from "@hypit/artifact";
+import type { ModuleManifest, TypeRef } from "@hypit/protocol";
+import { compositableSurfaceSchema, fontArtifactSchema, fontStackSchema, mediaInspectionSchema, mediaStreamSelectionSchema, muxedMediaSchema, renderedVisualSchema, synchronizedMediaSchema, timelineAudioSchema } from "./schema.js";
+export const mediaModuleRef = { name: "@hypit/media", version: "1" } as const;
+export const mediaTypes = {
+  frameRange: { module: mediaModuleRef, name: "MediaFrameRange" },
+  inspection: { module: mediaModuleRef, name: "MediaInspection" },
+  streamSelection: { module: mediaModuleRef, name: "MediaStreamSelection" }, synchronized: { module: mediaModuleRef, name: "SynchronizedMedia" },
+  renderedVisual: { module: mediaModuleRef, name: "RenderedVisual" }, timelineAudio: { module: mediaModuleRef, name: "TimelineAudio" },
+  muxed: { module: mediaModuleRef, name: "MuxedMedia" }, fontArtifact: { module: mediaModuleRef, name: "FontArtifactRef" },
+  fontStack: { module: mediaModuleRef, name: "FontStackRef" },
+  compositableSurface: { module: mediaModuleRef, name: "CompositableSurfaceRef" },
+  /** Declared by `@hypit/artifact`. A Type is identified by the Module that owns it, not the one that re-exports it. */
+  blobArtifact: artifactTypes.blob,
+} satisfies Record<string, TypeRef>;
+
+export const mediaMarkupSurfaces = [
+    {
+      name: "image", tag: "Image", mode: "structured", outputs: [artifactTypes.blob],
+      vocabulary: {
+        summary: "Requests one authored image file from the Host and publishes it as a byte Artifact.",
+        attributes: [
+          { name: "id", kind: "identifier", required: true,
+            summary: "Names the Artifact Record this element publishes." },
+          { name: "src", kind: "literal", required: true,
+            summary: "Points at the image file, resolved by the Host against the source that declares it." },
+          { name: "media-type", kind: "literal", required: false,
+            summary: "States the image media type when the src extension does not name one." },
+        ],
+        example: `<media:Image id="presenter" src="./assets/presenter.png"/>`,
+        notes: [
+          "The element is empty; it accepts no children and no text.",
+          "`.avif`, `.gif`, `.jpeg`, `.jpg`, `.png` and `.webp` name their own media type; any other file needs `media-type`.",
+          "A written `media-type` must begin with `image/`, and the resolved bytes must arrive as an image Artifact.",
+          "The Artifact is published under the bare `id`, and the consuming package decides what the image means.",
+        ],
+      },
+    },
+    {
+      name: "audio", tag: "Audio", mode: "structured", outputs: [artifactTypes.blob],
+      vocabulary: {
+        summary: "Requests one authored audio file from the Host and publishes it as a byte Artifact.",
+        attributes: [
+          { name: "id", kind: "identifier", required: true,
+            summary: "Names the Artifact Record this element publishes." },
+          { name: "src", kind: "literal", required: true,
+            summary: "Points at the audio file, resolved by the Host against the source that declares it." },
+          { name: "media-type", kind: "literal", required: false,
+            summary: "States the audio media type when the src extension does not name one." },
+        ],
+        example: `<media:Audio id="music" src="./assets/music.wav"/>`,
+        notes: [
+          "The element is empty; it accepts no children and no text.",
+          "`.aac`, `.flac`, `.m4a`, `.mp3`, `.oga`, `.ogg`, `.opus` and `.wav` name their own media type; any other file needs `media-type`.",
+          "A written `media-type` must begin with `audio/`, and the resolved bytes must arrive as an audio Artifact.",
+          "The Artifact is published under the bare `id`; declared audio is not promoted to speech here.",
+        ],
+      },
+    },
+    {
+      name: "video", tag: "Video", mode: "structured", outputs: [artifactTypes.blob],
+      vocabulary: {
+        summary: "Requests one authored video file from the Host and publishes it as a byte Artifact.",
+        attributes: [
+          { name: "id", kind: "identifier", required: true,
+            summary: "Names the Artifact Record this element publishes." },
+          { name: "src", kind: "literal", required: true,
+            summary: "Points at the video file, resolved by the Host against the source that declares it." },
+          { name: "media-type", kind: "literal", required: false,
+            summary: "States the video media type when the src extension does not name one." },
+        ],
+        example: `<media:Video id="reference" src="./assets/reference.mp4"/>`,
+        notes: [
+          "The element is empty; it accepts no children and no text.",
+          "`.m4v`, `.mov`, `.mp4` and `.webm` name their own media type; any other file needs `media-type`.",
+          "A written `media-type` must begin with `video/`, and the resolved bytes must arrive as a video Artifact.",
+          "The Artifact is published under the bare `id`, and the consuming package decides what the video means.",
+        ],
+      },
+    },
+    {
+      name: "font", tag: "Font", mode: "structured", outputs: [mediaTypes.fontArtifact],
+      vocabulary: {
+        summary: "Requests one authored font file from the Host and publishes it with its exact weight and style as a one-source FontArtifact.",
+        attributes: [
+          { name: "id", kind: "identifier", required: true,
+            summary: "Names the FontArtifact Record this element publishes." },
+          { name: "src", kind: "literal", required: true,
+            summary: "Points at the font file, resolved by the Host against the source that declares it." },
+          { name: "weight", kind: "literal", required: true,
+            summary: "States the exact weight the bytes carry, as a whole number from 1 to 1000." },
+          { name: "style", kind: "literal", required: true, values: ["normal", "italic", "oblique"],
+            summary: "States the exact style the bytes carry." },
+          { name: "media-type", kind: "literal", required: false,
+            summary: "States the font media type when the src extension does not name one." },
+        ],
+        example: `<media:Font id="brand" src="./assets/Brand-Semibold.woff2" weight="600" style="normal"/>`,
+        notes: [
+          "The element is empty; it accepts no children and no text.",
+          "`.otf`, `.ttf`, `.woff` and `.woff2` name their own media type; any other file needs `media-type`.",
+          "One element declares one face, so `weight` and `style` describe these bytes rather than a family.",
+          "The FontArtifact is published under the bare `id`, and an invalid weight or style fails before any bytes are read.",
+        ],
+      },
+    },
+  ] as const;
+
+export const mediaManifest: ModuleManifest = {
+  format: "hypit.module@1", name: mediaModuleRef.name, version: mediaModuleRef.version, dependencies: [artifactDependency],
+  types: [
+    { name: mediaTypes.frameRange.name },
+    { name: mediaTypes.inspection.name },
+    { name: mediaTypes.streamSelection.name },
+    { name: mediaTypes.synchronized.name },
+    { name: mediaTypes.renderedVisual.name },
+    { name: mediaTypes.timelineAudio.name },
+    { name: mediaTypes.muxed.name },
+    { name: mediaTypes.fontArtifact.name }, { name: mediaTypes.fontStack.name },
+    { name: mediaTypes.compositableSurface.name },
+  ], capabilities: [], producers: [],
+};
+export const mediaDependency = { module: mediaModuleRef } as const;

package/packages/media/src/render.ts

@@ -0,0 +1,140 @@
+import { isResourceId } from "@hypit/protocol";
+import type { BlobRef } from "@hypit/protocol";
+
+const FONT_MEDIA_TYPES = new Set([
+  "font/otf",
+  "font/ttf",
+  "font/woff",
+  "font/woff2",
+]);
+
+const ALPHA_SURFACE_MEDIA_TYPES = new Set([
+  "image/png",
+  "image/webp",
+  "video/webm",
+]);
+
+export type FontArtifactRef = {
+  /** One logical face may be split into independently addressed Unicode-range sources. */
+  readonly sources: readonly {
+    readonly artifact: BlobRef;
+    readonly unicodeRange?: string;
+  }[];
+  readonly weight: number;
+  readonly style: "normal" | "italic" | "oblique";
+};
+
+/** Ordered exact font faces. The first face is primary; the remainder are glyph fallbacks. */
+export type FontStackRef = {
+  readonly faces: readonly FontArtifactRef[];
+};
+
+export type CompositableSurfaceRef = {
+  readonly artifact: BlobRef;
+  readonly width: number;
+  readonly height: number;
+  readonly colorSpace: "srgb";
+  readonly alphaMode: "opaque" | "straight";
+  readonly timing:
+    | { readonly kind: "still" }
+    | {
+        readonly kind: "frames";
+        readonly frameRate: {
+          readonly numerator: number;
+          readonly denominator: number;
+        };
+        readonly frameCount: number;
+      };
+};
+
+function assertBlobRef(value: BlobRef, label: string): void {
+  if (
+    value.kind !== "blob"
+    || !isResourceId(value.resource)
+    || !Number.isSafeInteger(value.size)
+    || value.size < 0
+    || !value.mediaType
+  ) {
+    throw new Error(`${label} Artifact is invalid.`);
+  }
+}
+
+export function assertFontArtifactRef(value: FontArtifactRef, label = "FontArtifactRef"): void {
+  if (!Array.isArray(value.sources) || value.sources.length === 0) throw new Error(`${label} sources are empty.`);
+  const artifacts = new Set<string>();
+  for (const [index, source] of value.sources.entries()) {
+    assertBlobRef(source.artifact, `${label}.sources.${index}`);
+    if (!FONT_MEDIA_TYPES.has(source.artifact.mediaType)) {
+      throw new Error(`${label}.sources.${index} Artifact must use a supported font media type.`);
+    }
+    if (artifacts.has(source.artifact.resource)) throw new Error(`${label} repeats a source Artifact.`);
+    artifacts.add(source.artifact.resource);
+    if (source.unicodeRange !== undefined
+      && !/^U\+[0-9a-f?]{1,6}(?:-[0-9a-f]{1,6})?(?:,U\+[0-9a-f?]{1,6}(?:-[0-9a-f]{1,6})?)*$/iu.test(source.unicodeRange)) {
+      throw new Error(`${label}.sources.${index} Unicode range is invalid.`);
+    }
+  }
+  if (!Number.isSafeInteger(value.weight) || value.weight < 1 || value.weight > 1_000) {
+    throw new Error(`${label} weight is invalid.`);
+  }
+  if (!["normal", "italic", "oblique"].includes(value.style)) {
+    throw new Error(`${label} style is invalid.`);
+  }
+}
+
+export function assertFontStackRef(value: FontStackRef, label = "FontStackRef"): void {
+  if (value.faces.length === 0) throw new Error(`${label} faces are empty.`);
+  const identities = new Set<string>();
+  for (const [index, face] of value.faces.entries()) {
+    assertFontArtifactRef(face, `${label}.faces.${index}`);
+    const identity = JSON.stringify({
+      sources: face.sources.map((source) => [source.artifact.resource, source.unicodeRange ?? null]),
+      weight: face.weight,
+      style: face.style,
+    });
+    if (identities.has(identity)) throw new Error(`${label} repeats an exact face.`);
+    identities.add(identity);
+  }
+}
+
+export function assertCompositableSurfaceRef(
+  value: CompositableSurfaceRef,
+  label = "CompositableSurfaceRef",
+): void {
+  assertBlobRef(value.artifact, label);
+  if (
+    !Number.isSafeInteger(value.width)
+    || value.width <= 0
+    || !Number.isSafeInteger(value.height)
+    || value.height <= 0
+  ) {
+    throw new Error(`${label} dimensions are invalid.`);
+  }
+  if (value.colorSpace !== "srgb") throw new Error(`${label} colorSpace is unsupported.`);
+  if (value.alphaMode !== "opaque" && value.alphaMode !== "straight") {
+    throw new Error(`${label} alphaMode is unsupported.`);
+  }
+  if (value.alphaMode === "straight" && !ALPHA_SURFACE_MEDIA_TYPES.has(value.artifact.mediaType)) {
+    throw new Error(`${label} straight alpha requires PNG, WebP or WebM media.`);
+  }
+  if (value.timing.kind === "still") {
+    if (!value.artifact.mediaType.startsWith("image/")) {
+      throw new Error(`${label} still timing requires an image Artifact.`);
+    }
+    return;
+  }
+  if (value.timing.kind !== "frames") throw new Error(`${label} timing is unsupported.`);
+  if (!value.artifact.mediaType.startsWith("video/")) {
+    throw new Error(`${label} frame timing requires a video Artifact.`);
+  }
+  if (
+    !Number.isSafeInteger(value.timing.frameRate.numerator)
+    || value.timing.frameRate.numerator <= 0
+    || !Number.isSafeInteger(value.timing.frameRate.denominator)
+    || value.timing.frameRate.denominator <= 0
+    || !Number.isSafeInteger(value.timing.frameCount)
+    || value.timing.frameCount <= 0
+  ) {
+    throw new Error(`${label} frame timing is invalid.`);
+  }
+}

package/packages/media/src/schema.ts

@@ -0,0 +1,69 @@
+import type { ValueSchema } from "@hypit/protocol";
+const string = { kind: "string", minLength: 1 } as const;
+const number = { kind: "number", minimum: 0 } as const;
+const seconds = { kind: "number", minimum: 0 } as const;
+const integer = { kind: "number", integer: true, minimum: 0 } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+const blobArtifactSchema = (mediaTypes?: readonly string[]): ValueSchema => object({
+  kind: { schema: { kind: "literal", value: "blob" } },
+  resource: { schema: { kind: "string", minLength: 5, maxLength: 256 } },
+  size: { schema: integer },
+  mediaType: { schema: mediaTypes === undefined ? string : { kind: "string", enum: mediaTypes } },
+});
+const rational = object({ numerator: { schema: { kind: "number", integer: true, minimum: 1 } }, denominator: { schema: { kind: "number", integer: true, minimum: 1 } } });
+const timestamp = object({ ticks: { schema: { kind: "string", minLength: 1, maxLength: 128 } }, timeBase: { schema: rational } });
+const disposition = object({ default: { schema: { kind: "boolean" } }, attachedPicture: { schema: { kind: "boolean" } } });
+const streamBase = {
+  index: { schema: integer }, codecType: { schema: string }, codecName: { schema: string }, disposition: { schema: disposition },
+  timingStatus: { schema: { kind: "string", enum: ["admissible", "missing", "non-monotonic", "discontinuous"] } },
+  timeBase: { schema: rational, optional: true }, startPts: { schema: timestamp, optional: true },
+  endPts: { schema: timestamp, optional: true }, decodedUnitCount: { schema: integer },
+} as const;
+const videoStream = object({ ...streamBase, kind: { schema: { kind: "literal", value: "video" } }, codecType: { schema: { kind: "literal", value: "video" } },
+  role: { schema: { kind: "string", enum: ["moving", "attached-picture", "still"] } }, width: { schema: { kind: "number", integer: true, minimum: 1 } },
+  height: { schema: { kind: "number", integer: true, minimum: 1 } }, sampleAspectRatio: { schema: rational },
+  rotationDegrees: { schema: { kind: "oneOf", variants: [0, 90, 180, 270].map((value) => ({ kind: "literal", value })) } },
+  averageFrameRate: { schema: rational, optional: true }, nominalFrameRate: { schema: rational, optional: true } });
+const audioStream = object({ ...streamBase, kind: { schema: { kind: "literal", value: "audio" } }, codecType: { schema: { kind: "literal", value: "audio" } },
+  sampleRate: { schema: { kind: "number", integer: true, minimum: 1 } }, channels: { schema: { kind: "number", integer: true, minimum: 1 } },
+  channelLayout: { schema: string, optional: true }, decodedSampleFrames: { schema: integer } });
+const otherStream = object({ ...streamBase, kind: { schema: { kind: "literal", value: "other" } } });
+export const mediaInspectionSchema: ValueSchema = object({
+  container: { schema: object({ formatNames: { schema: { kind: "array", minItems: 1, items: string } } }) },
+  streams: { schema: { kind: "array", items: { kind: "oneOf", variants: [videoStream, audioStream, otherStream] } } },
+});
+export const mediaStreamSelectionSchema: ValueSchema = object({
+  videoStreamIndex: { schema: integer, optional: true }, audioStreamIndex: { schema: integer, optional: true },
+  spanAuthority: { schema: { kind: "string", enum: ["video", "audio"] } },
+  policy: { schema: { kind: "string", enum: ["primary-moving@1", "default-audio@1", "primary-moving-default-audio@1", "explicit-streams@1"] } },
+});
+export const synchronizedMediaSchema: ValueSchema = object({
+  timeline: { schema: object({ frameRate: { schema: rational },
+    frameCount: { schema: { kind: "number", integer: true, minimum: 1 } } }) },
+  visual: { schema: object({ artifact: { schema: blobArtifactSchema() },
+    width: { schema: { kind: "number", integer: true, minimum: 1 } }, height: { schema: { kind: "number", integer: true, minimum: 1 } },
+  }), optional: true },
+  audio: { schema: object({ artifact: { schema: blobArtifactSchema(["audio/wav"]) } }), optional: true },
+});
+export const renderedVisualSchema: ValueSchema = object({ frameRate: { schema: rational }, frameCount: { schema: { kind: "number", integer: true, minimum: 1 } },
+  canvas: { schema: object({ width: { schema: { kind: "number", integer: true, minimum: 1 } }, height: { schema: { kind: "number", integer: true, minimum: 1 } } }) },
+  artifact: { schema: blobArtifactSchema() } });
+export const timelineAudioSchema: ValueSchema = object({ artifact: { schema: blobArtifactSchema(["audio/wav"]) },
+  sampleFrames: { schema: { kind: "number", integer: true, minimum: 1 } } });
+export const muxedMediaSchema: ValueSchema = object({ frameRate: { schema: rational }, frameCount: { schema: { kind: "number", integer: true, minimum: 1 } },
+  canvas: { schema: object({ width: { schema: { kind: "number", integer: true, minimum: 1 } }, height: { schema: { kind: "number", integer: true, minimum: 1 } } }) },
+  presentationSampleFrames: { schema: { kind: "number", integer: true, minimum: 1 } }, artifact: { schema: blobArtifactSchema(["video/mp4"]) } });
+const fontSourceSchema: ValueSchema = object({
+  artifact: { schema: blobArtifactSchema(["font/otf", "font/ttf", "font/woff", "font/woff2"]) },
+  unicodeRange: { schema: { kind: "string", minLength: 3 }, optional: true },
+});
+export const fontArtifactSchema: ValueSchema = object({ sources: { schema: { kind: "array", minItems: 1, items: fontSourceSchema } },
+  weight: { schema: { kind: "number", integer: true, minimum: 1, maximum: 1_000 } }, style: { schema: { kind: "string", enum: ["normal", "italic", "oblique"] } } });
+export const fontStackSchema: ValueSchema = object({ faces: { schema: { kind: "array", minItems: 1, items: fontArtifactSchema } } });
+const surfaceTiming: ValueSchema = { kind: "oneOf", variants: [
+  object({ kind: { schema: { kind: "literal", value: "still" } } }),
+  object({ kind: { schema: { kind: "literal", value: "frames" } }, frameRate: { schema: rational }, frameCount: { schema: { kind: "number", integer: true, minimum: 1 } } }),
+] };
+export const compositableSurfaceSchema: ValueSchema = object({ artifact: { schema: blobArtifactSchema() }, width: { schema: { kind: "number", integer: true, minimum: 1 } },
+  height: { schema: { kind: "number", integer: true, minimum: 1 } }, colorSpace: { schema: { kind: "literal", value: "srgb" } },
+  alphaMode: { schema: { kind: "string", enum: ["opaque", "straight"] } }, timing: { schema: surfaceTiming } });