@hypit/hypit 0.0.1 → 0.1.1

package/packages/screen-overlay/src/manifest.ts

@@ -0,0 +1,305 @@
+import { temporalContextAttributeVocabulary } from "@hypit/temporal-markup";
+import { readFile } from "node:fs/promises";
+
+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 { semanticTrackDependency } from "@hypit/semantic-track";
+import { spatialDependency, spatialTypes } from "@hypit/spatial";
+import { temporalDependency, temporalTypes } from "@hypit/temporal";
+import { temporalWindowAttributeVocabulary } from "@hypit/temporal-markup";
+
+const previewImage = (file: string) => ({
+  mediaType: "image/png",
+  path: `preview/${file}`,
+  open: async () => Uint8Array.from(await readFile(new URL(`../preview/${file}`, import.meta.url))),
+});
+
+export const screenOverlayModuleRef = { name: "@hypit/screen-overlay", version: "1" } as const;
+export const screenOverlayTypes = {
+  header: { module: screenOverlayModuleRef, name: "ScreenOverlayHeader" },
+  itemSpec: { module: screenOverlayModuleRef, name: "ScreenOverlayItemSpec" },
+  set: { module: screenOverlayModuleRef, name: "ScreenOverlaySet" },
+  program: { module: screenOverlayModuleRef, name: "ScreenOverlayProgram" },
+} satisfies Record<string, TypeRef>;
+export const screenOverlayProducers = {
+  createSet: { module: screenOverlayModuleRef, name: "create-screen-overlay-set" },
+  appendItem: { module: screenOverlayModuleRef, name: "append-screen-overlay-item" },
+  finalize: { module: screenOverlayModuleRef, name: "finalize-screen-overlay" },
+  render: { module: screenOverlayModuleRef, name: "render-screen-overlay" },
+} satisfies Record<string, ProducerRef>;
+
+const string = { kind: "string", minLength: 1 } as const;
+const number = { kind: "number" } as const;
+const nonNegative = { kind: "number", minimum: 0 } as const;
+const integer = { kind: "number", integer: true } as const;
+const unsignedInteger = { 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 normalizedPoint = object({ x: { schema: number }, y: { schema: number } });
+const colorArray: ValueSchema = { kind: "array", minItems: 1, items: string };
+const component: ValueSchema = { kind: "oneOf", variants: [
+  object({ kind: { schema: { kind: "literal", value: "flash" } }, color: { schema: string }, intensity: { schema: nonNegative }, attackFrames: { schema: unsignedInteger }, holdFrames: { schema: unsignedInteger }, decayFrames: { schema: unsignedInteger } }),
+  object({ kind: { schema: { kind: "literal", value: "color-wash" } }, color: { schema: string }, opacity: { schema: nonNegative } }),
+  object({ kind: { schema: { kind: "literal", value: "vignette" } }, center: { schema: normalizedPoint }, radius: { schema: normalizedPoint }, softness: { schema: nonNegative }, color: { schema: string }, opacity: { schema: nonNegative } }),
+  object({ kind: { schema: { kind: "literal", value: "scan-lines" } }, spacingPx: { schema: nonNegative }, thicknessPx: { schema: nonNegative }, angleDeg: { schema: number }, opacity: { schema: nonNegative }, travelPx: { schema: number } }),
+  object({ kind: { schema: { kind: "literal", value: "directional-matte" } }, angleDeg: { schema: number }, coverage: { schema: nonNegative }, feather: { schema: nonNegative }, color: { schema: string }, opacity: { schema: nonNegative }, progress: { schema: object({ from: { schema: number }, to: { schema: number } }) } }),
+  object({ kind: { schema: { kind: "literal", value: "whip-veil" } }, direction: { schema: { kind: "string", enum: ["left", "right", "up", "down"] } }, widthPx: { schema: nonNegative }, softnessPx: { schema: nonNegative }, travelPx: { schema: nonNegative }, opacity: { schema: nonNegative } }),
+  object({ kind: { schema: { kind: "literal", value: "glitch-veil" } }, bars: { schema: unsignedInteger }, colors: { schema: colorArray }, opacity: { schema: nonNegative }, travelPx: { schema: number }, seed: { schema: unsignedInteger } }),
+  object({ kind: { schema: { kind: "literal", value: "grain" } }, amount: { schema: nonNegative }, grainSizePx: { schema: nonNegative }, chroma: { schema: { kind: "string", enum: ["monochrome", "color"] } }, motionRatePxPerFrame: { schema: number }, seed: { schema: unsignedInteger } }),
+  object({ kind: { schema: { kind: "literal", value: "light-leak" } }, colors: { schema: colorArray }, angleDeg: { schema: number }, softness: { schema: nonNegative }, travelPx: { schema: number }, intensity: { schema: nonNegative }, seed: { schema: unsignedInteger } }),
+  object({ kind: { schema: { kind: "literal", value: "bokeh" } }, amount: { schema: nonNegative }, sizeMinPx: { schema: nonNegative }, sizeMaxPx: { schema: nonNegative }, color: { schema: string }, warmth: { schema: number }, driftPx: { schema: number }, seed: { schema: unsignedInteger } }),
+  object({ kind: { schema: { kind: "literal", value: "tv-static" } }, amount: { schema: nonNegative }, noiseSizePx: { schema: nonNegative }, scanLineOpacity: { schema: nonNegative }, motionRatePxPerFrame: { schema: number }, seed: { schema: unsignedInteger } }),
+] };
+const itemSpec = object({
+  id: { schema: string },
+  content: { schema: component },
+  stackingOrder: { schema: integer },
+});
+const frameSpan = object({ startFrame: { schema: unsignedInteger }, endFrameExclusive: { schema: unsignedInteger } });
+const item = object({
+  id: { schema: string }, span: { schema: frameSpan }, content: { schema: component },
+  stacking: { schema: object({ order: { schema: integer }, tieBreak: { schema: string } }) },
+});
+export const screenOverlayHeaderSchema: ValueSchema = object({ id: { schema: string } });
+export const screenOverlayItemSpecSchema: ValueSchema = itemSpec;
+export const screenOverlaySetSchema: ValueSchema = object({ items: { schema: { kind: "array", items: item } } });
+export const screenOverlayProgramSchema: ValueSchema = object({ id: { schema: string }, items: { schema: { kind: "array", minItems: 1, items: item } } });
+const appendInputs = [{ name: "set", type: screenOverlayTypes.set }, { name: "header", type: screenOverlayTypes.header }, { name: "space", type: programSpaceTypes.programSpace }, { name: "spec", type: screenOverlayTypes.itemSpec }, { name: "window", type: temporalTypes.window }] as const;
+
+const itemAttributes = [
+  { name: "id", kind: "identifier", required: false,
+    summary: "Names this item; the overlay numbers the item after its kind when it is omitted." },
+  { name: "z", kind: "literal", required: true,
+    summary: "Sets the stacking order this item is painted in against its siblings." },
+  ...temporalWindowAttributeVocabulary,
+] as const;
+
+export const screenOverlayMarkupSurfaces = [
+  { name: "track", tag: "Track", mode: "structured", outputs: [screenOverlayTypes.header, screenOverlayTypes.itemSpec, temporalTypes.instantSpec, temporalTypes.windowSpec, temporalTypes.instant, temporalTypes.window, screenOverlayTypes.program, compositionTypes.visualTrack],
+    vocabulary: {
+      summary: "Paints self-contained screen treatments across the whole Canvas and publishes the overlay Program and the VisualTrack it renders to.",
+      appearance: "Treatments laid edge to edge over the whole Canvas, never a panel, a card or text, each item covering the frame for its own span only and painted over its siblings in `z` order. Flash pulses one color up to full and back down across the frame, ColorWash holds that same flat color still, and Vignette leaves the middle clear and darkens outwards to one color in an ellipse around a chosen centre. Four items cross the frame as travelling geometry: ScanLines rule it with evenly spaced white stripes at an angle, DirectionalMatte sweeps a feathered wall of color over it, WhipVeil slides a single soft-edged white band left, right, up or down, and LightLeak drags a heavily blurred angled gradient of colors from one side to the other. The remaining four scatter many small shapes from a seed: GlitchVeil throws wide colored horizontal bars that jump sideways, Grain sprinkles fine specks that crawl diagonally, Bokeh floats blurred round discs of one color that drift apart, and TVStatic fills the frame with grey noise cells beneath fine horizontal scan lines.",
+      preview: previewImage("Track.png"),
+      attributes: [
+        { name: "id", kind: "identifier", required: true,
+          summary: "Names this overlay so its Program and Track can be referenced elsewhere in the Source." },
+        { name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas],
+          summary: "Chooses the Canvas every item is painted across." },
+        ...temporalContextAttributeVocabulary,
+      ],
+      children: [
+        { tag: "Flash", cardinality: "many",
+          summary: "A full-Canvas flash of one color with its own attack, hold and decay in frames.",
+          attributes: [
+            ...itemAttributes,
+            { name: "color", kind: "literal", required: true,
+              summary: "Sets the hexadecimal color the Canvas flashes." },
+            { name: "intensity", kind: "literal", required: true,
+              summary: "Sets how strong the flash is, from 0 to 1." },
+            { name: "attack", kind: "literal", required: true,
+              summary: "Sets how many frames the flash takes to reach full intensity." },
+            { name: "hold", kind: "literal", required: true,
+              summary: "Sets how many frames the flash stays at full intensity." },
+            { name: "decay", kind: "literal", required: true,
+              summary: "Sets how many frames the flash takes to fade away." },
+          ] },
+        { tag: "ColorWash", cardinality: "many",
+          summary: "One flat color held over the whole Canvas at a fixed opacity.",
+          attributes: [
+            ...itemAttributes,
+            { name: "color", kind: "literal", required: true,
+              summary: "Sets the hexadecimal color held over the Canvas." },
+            { name: "opacity", kind: "literal", required: true,
+              summary: "Sets how opaque the wash is, from 0 to 1." },
+          ] },
+        { tag: "Vignette", cardinality: "many",
+          summary: "An elliptical falloff of one color around a normalized centre.",
+          attributes: [
+            ...itemAttributes,
+            { name: "center-x", kind: "literal", required: true,
+              summary: "Sets the horizontal centre of the falloff as a fraction of the Canvas width." },
+            { name: "center-y", kind: "literal", required: true,
+              summary: "Sets the vertical centre of the falloff as a fraction of the Canvas height." },
+            { name: "radius-x", kind: "literal", required: true,
+              summary: "Sets the horizontal radius of the falloff as a fraction of the Canvas width." },
+            { name: "radius-y", kind: "literal", required: true,
+              summary: "Sets the vertical radius of the falloff as a fraction of the Canvas height." },
+            { name: "softness", kind: "literal", required: true,
+              summary: "Sets how gradually the falloff fades outwards, from 0 to 1." },
+            { name: "color", kind: "literal", required: true,
+              summary: "Sets the hexadecimal color the edges are darkened with." },
+            { name: "opacity", kind: "literal", required: true,
+              summary: "Sets how opaque the vignette is, from 0 to 1." },
+          ] },
+        { tag: "ScanLines", cardinality: "many",
+          summary: "Repeating lines at a fixed spacing, thickness and angle, travelling across the Canvas.",
+          attributes: [
+            ...itemAttributes,
+            { name: "spacing", kind: "literal", required: true,
+              summary: "Sets how many pixels apart the lines are." },
+            { name: "thickness", kind: "literal", required: true,
+              summary: "Sets how many pixels thick each line is, at most the spacing." },
+            { name: "angle", kind: "literal", required: true,
+              summary: "Sets the angle in degrees the lines run at." },
+            { name: "opacity", kind: "literal", required: true,
+              summary: "Sets how opaque the lines are, from 0 to 1." },
+            { name: "travel", kind: "literal", required: true,
+              summary: "Sets how many pixels the lines travel across the item's span." },
+          ] },
+        { tag: "DirectionalMatte", cardinality: "many",
+          summary: "A feathered matte of one color crossing the Canvas at an angle over an explicit progress range.",
+          attributes: [
+            ...itemAttributes,
+            { name: "angle", kind: "literal", required: true,
+              summary: "Sets the angle in degrees the matte edge crosses the Canvas at." },
+            { name: "coverage", kind: "literal", required: true,
+              summary: "Sets how much of the Canvas the matte covers, from 0 to 1." },
+            { name: "feather", kind: "literal", required: true,
+              summary: "Sets how soft the matte edge is, from 0 to 1." },
+            { name: "color", kind: "literal", required: true,
+              summary: "Sets the hexadecimal color the matte is filled with." },
+            { name: "opacity", kind: "literal", required: true,
+              summary: "Sets how opaque the matte is, from 0 to 1." },
+            { name: "from", kind: "literal", required: true,
+              summary: "Sets the progress the matte starts its crossing at, from -1 to 2." },
+            { name: "to", kind: "literal", required: true,
+              summary: "Sets the progress the matte ends its crossing at, from -1 to 2." },
+          ] },
+        { tag: "WhipVeil", cardinality: "many",
+          summary: "A soft band that travels across the Canvas in one of four directions.",
+          attributes: [
+            ...itemAttributes,
+            { name: "direction", kind: "literal", required: true, values: ["left", "right", "up", "down"],
+              summary: "Chooses which way the band travels across the Canvas." },
+            { name: "width", kind: "literal", required: true,
+              summary: "Sets how many pixels wide the band is." },
+            { name: "softness", kind: "literal", required: true,
+              summary: "Sets how many pixels the band's edges are blurred over." },
+            { name: "travel", kind: "literal", required: true,
+              summary: "Sets how many pixels the band travels across the item's span." },
+            { name: "opacity", kind: "literal", required: true,
+              summary: "Sets how opaque the band is, from 0 to 1." },
+          ] },
+        { tag: "GlitchVeil", cardinality: "many",
+          summary: "Colored bars laid across the Canvas and displaced from an explicit seed.",
+          attributes: [
+            ...itemAttributes,
+            { name: "bars", kind: "literal", required: true,
+              summary: "Sets how many bars are laid across the Canvas, up to 256." },
+            { name: "colors", kind: "literal", required: true,
+              summary: "Lists the hexadecimal colors the bars are drawn in, separated by commas." },
+            { name: "opacity", kind: "literal", required: true,
+              summary: "Sets how opaque the bars are, from 0 to 1." },
+            { name: "travel", kind: "literal", required: true,
+              summary: "Sets how many pixels the bars are displaced across the item's span." },
+            { name: "seed", kind: "literal", required: true,
+              summary: "Sets the seed the bar placement and displacement are drawn from." },
+          ] },
+        { tag: "Grain", cardinality: "many",
+          summary: "Grain at a chosen amount, size and chroma, moving from an explicit seed.",
+          attributes: [
+            ...itemAttributes,
+            { name: "amount", kind: "literal", required: true,
+              summary: "Sets how much grain is laid over the Canvas, from 0 to 1." },
+            { name: "size", kind: "literal", required: true,
+              summary: "Sets how many pixels across one grain particle is." },
+            { name: "chroma", kind: "literal", required: true, values: ["monochrome", "color"],
+              summary: "Decides whether the grain is monochrome or colored." },
+            { name: "motion-rate", kind: "literal", required: true,
+              summary: "Sets how many pixels the grain moves each frame." },
+            { name: "seed", kind: "literal", required: true,
+              summary: "Sets the seed the grain pattern is drawn from." },
+          ] },
+        { tag: "LightLeak", cardinality: "many",
+          summary: "Colored light angled across the Canvas and moving from an explicit seed.",
+          attributes: [
+            ...itemAttributes,
+            { name: "colors", kind: "literal", required: true,
+              summary: "Lists the hexadecimal colors the leak is drawn in, separated by commas." },
+            { name: "angle", kind: "literal", required: true,
+              summary: "Sets the angle in degrees the light crosses the Canvas at." },
+            { name: "softness", kind: "literal", required: true,
+              summary: "Sets how soft the leak's edges are, from 0 to 1." },
+            { name: "travel", kind: "literal", required: true,
+              summary: "Sets how many pixels the leak travels across the item's span." },
+            { name: "intensity", kind: "literal", required: true,
+              summary: "Sets how strong the leak is, from 0 to 1." },
+            { name: "seed", kind: "literal", required: true,
+              summary: "Sets the seed the leak's placement is drawn from." },
+          ] },
+        { tag: "Bokeh", cardinality: "many",
+          summary: "Out-of-focus highlights between a minimum and maximum size, drifting from an explicit seed.",
+          attributes: [
+            ...itemAttributes,
+            { name: "amount", kind: "literal", required: true,
+              summary: "Sets how many highlights are scattered over the Canvas, from 0 to 1." },
+            { name: "min-size", kind: "literal", required: true,
+              summary: "Sets how many pixels across the smallest highlight is." },
+            { name: "max-size", kind: "literal", required: true,
+              summary: "Sets how many pixels across the largest highlight is, never below `min-size`." },
+            { name: "color", kind: "literal", required: true,
+              summary: "Sets the hexadecimal color the highlights are drawn in." },
+            { name: "warmth", kind: "literal", required: true,
+              summary: "Sets how warm or cool the highlights are, from -1 to 1." },
+            { name: "drift", kind: "literal", required: true,
+              summary: "Sets how many pixels the highlights drift across the item's span." },
+            { name: "seed", kind: "literal", required: true,
+              summary: "Sets the seed the highlight placement is drawn from." },
+          ] },
+        { tag: "TVStatic", cardinality: "many",
+          summary: "Broadcast noise with its own scan-line opacity, moving from an explicit seed.",
+          attributes: [
+            ...itemAttributes,
+            { name: "amount", kind: "literal", required: true,
+              summary: "Sets how much noise covers the Canvas, from 0 to 1." },
+            { name: "size", kind: "literal", required: true,
+              summary: "Sets how many pixels across one noise cell is." },
+            { name: "scan-lines", kind: "literal", required: true,
+              summary: "Sets how opaque the scan lines over the noise are, from 0 to 1." },
+            { name: "motion-rate", kind: "literal", required: true,
+              summary: "Sets how many pixels the noise moves each frame." },
+            { name: "seed", kind: "literal", required: true,
+              summary: "Sets the seed the noise is drawn from." },
+          ] },
+      ],
+      ports: [
+        { name: "program", type: screenOverlayTypes.program,
+          summary: "The resolved overlay: every item with its frame span, its content and its stacking." },
+        { name: "track", type: compositionTypes.visualTrack,
+          summary: "The rendered overlay, an ordinary peer VisualTrack." },
+      ],
+      example: `<screen:Track id="effects" semantic={speech.semantic} canvas={vertical}>
+  <screen:Flash during={story.selection.overlay} z="80"
+    color="#ffffff" intensity="0.6" attack="2" hold="2" decay="6"/>
+</screen:Track>`,
+      notes: [
+        "The overlay requires at least one component child, and a component child is empty.",
+        "A component child writes exactly one temporal form, `during`, `at`, or `start` with `end`; none of them or more than one is refused.",
+        "`during` takes the literal `program` for the whole programme, or a Selection reference.",
+        "`at` requires `for`.",
+        "`start` and `end` each take `program.start`, `program.end`, `selection.start`, `selection.end` or `moment.cue` with an optional `+` or `-` offset, or a bare duration read as an absolute point.",
+        "Explicit `start` and `end` timing binds a Selection through `selection` or a Moment through `moment`, never both.",
+        "A duration is written as an integral `f` or `ms` count, or as an `s` count that may carry a decimal fraction.",
+      ],
+    } },
+] as const;
+
+
+export const screenOverlayManifest: ModuleManifest = {
+  format: "hypit.module@1", name: screenOverlayModuleRef.name, version: screenOverlayModuleRef.version,
+  dependencies: [narrativeDependency, programSpaceDependency, semanticTrackDependency, spatialDependency, temporalDependency, compositionDependency],
+  types: [
+    { name: screenOverlayTypes.header.name },
+    { name: screenOverlayTypes.itemSpec.name },
+    { name: screenOverlayTypes.set.name },
+    { name: screenOverlayTypes.program.name },
+  ], capabilities: [],
+  producers: [
+    { name: screenOverlayProducers.createSet.name, inputs: [], outputs: [{ name: "set", type: screenOverlayTypes.set }], needs: [] },
+    { name: screenOverlayProducers.appendItem.name, inputs: [...appendInputs], outputs: [{ name: "set", type: screenOverlayTypes.set }], needs: [] },
+    { name: screenOverlayProducers.finalize.name, inputs: [{ name: "set", type: screenOverlayTypes.set }, { name: "header", type: screenOverlayTypes.header }], outputs: [{ name: "program", type: screenOverlayTypes.program }], needs: [] },
+    { name: screenOverlayProducers.render.name, inputs: [{ name: "canvas", type: spatialTypes.canvas }, { name: "space", type: programSpaceTypes.programSpace }, { name: "program", type: screenOverlayTypes.program }], outputs: [{ name: "track", type: compositionTypes.visualTrack }], needs: [] },
+  ],
+};
+export const screenOverlayDependency = { module: screenOverlayModuleRef } as const;

package/packages/screen-overlay/src/program.ts

@@ -0,0 +1,321 @@
+import { assertVisualTrackIdentity, sealVisualTrack } from "@hypit/composition";
+import type { VisualAnimation, VisualElement, VisualStyleDeclaration, VisualTrack } from "@hypit/composition";
+import { assertProgramSpaceIdentity } from "@hypit/program-space";
+import type { ProgramSpace } from "@hypit/program-space";
+import { canonicalize } from "@hypit/protocol";
+import { assertCanvasSpace } from "@hypit/spatial";
+import type { CanvasSpace } from "@hypit/spatial";
+import { assertTemporalWindowFor } from "@hypit/temporal";
+import type { ProjectedWindow } from "@hypit/temporal";
+
+import type {
+  ScreenOverlayComponent,
+  ScreenOverlayHeader,
+  ScreenOverlayItemProgram,
+  ScreenOverlayItemSpec,
+  ScreenOverlayProgram,
+  ScreenOverlaySet,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }
+function identity(value: string, label: string): void {
+  assert(/^[A-Za-z][A-Za-z0-9_.:#-]{0,191}$/u.test(value), `${label} is invalid.`);
+}
+function finite(value: number, label: string): void { assert(Number.isFinite(value), `${label} is invalid.`); }
+function range(value: number, minimum: number, maximum: number, label: string): void {
+  finite(value, label); assert(value >= minimum && value <= maximum, `${label} is outside ${minimum}..${maximum}.`);
+}
+function positive(value: number, label: string): void { finite(value, label); assert(value > 0, `${label} must be positive.`); }
+function nonNegativeInteger(value: number, label: string): void {
+  assert(Number.isSafeInteger(value) && value >= 0, `${label} must be a non-negative integer.`);
+}
+function color(value: string, label: string): void {
+  assert(/^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu.test(value), `${label} must be a hexadecimal color.`);
+}
+function colors(values: readonly string[], label: string): void {
+  assert(values.length > 0, `${label} requires at least one color.`);
+  values.forEach((value, index) => color(value, `${label}.${index + 1}`));
+}
+
+export function assertScreenOverlayComponent(value: ScreenOverlayComponent): void {
+  switch (value.kind) {
+    case "flash":
+      color(value.color, "Flash color"); range(value.intensity, 0, 1, "Flash intensity");
+      nonNegativeInteger(value.attackFrames, "Flash attack"); nonNegativeInteger(value.holdFrames, "Flash hold");
+      nonNegativeInteger(value.decayFrames, "Flash decay"); return;
+    case "color-wash": color(value.color, "ColorWash color"); range(value.opacity, 0, 1, "ColorWash opacity"); return;
+    case "vignette":
+      range(value.center.x, 0, 1, "Vignette center.x"); range(value.center.y, 0, 1, "Vignette center.y");
+      positive(value.radius.x, "Vignette radius.x"); positive(value.radius.y, "Vignette radius.y");
+      range(value.softness, 0, 1, "Vignette softness"); color(value.color, "Vignette color");
+      range(value.opacity, 0, 1, "Vignette opacity"); return;
+    case "scan-lines":
+      positive(value.spacingPx, "ScanLines spacing"); positive(value.thicknessPx, "ScanLines thickness");
+      assert(value.thicknessPx <= value.spacingPx, "ScanLines thickness exceeds spacing.");
+      finite(value.angleDeg, "ScanLines angle"); range(value.opacity, 0, 1, "ScanLines opacity");
+      finite(value.travelPx, "ScanLines travel"); return;
+    case "directional-matte":
+      finite(value.angleDeg, "DirectionalMatte angle"); range(value.coverage, 0, 1, "DirectionalMatte coverage");
+      range(value.feather, 0, 1, "DirectionalMatte feather"); color(value.color, "DirectionalMatte color");
+      range(value.opacity, 0, 1, "DirectionalMatte opacity"); range(value.progress.from, -1, 2, "DirectionalMatte progress.from");
+      range(value.progress.to, -1, 2, "DirectionalMatte progress.to"); return;
+    case "whip-veil":
+      assert(["left", "right", "up", "down"].includes(value.direction), "WhipVeil direction is invalid.");
+      positive(value.widthPx, "WhipVeil width"); assert(Number.isFinite(value.softnessPx) && value.softnessPx >= 0, "WhipVeil softness is invalid.");
+      positive(value.travelPx, "WhipVeil travel"); range(value.opacity, 0, 1, "WhipVeil opacity"); return;
+    case "glitch-veil":
+      assert(Number.isSafeInteger(value.bars) && value.bars > 0 && value.bars <= 256, "GlitchVeil bars are invalid.");
+      colors(value.colors, "GlitchVeil colors"); range(value.opacity, 0, 1, "GlitchVeil opacity");
+      finite(value.travelPx, "GlitchVeil travel"); nonNegativeInteger(value.seed, "GlitchVeil seed"); return;
+    case "grain":
+      range(value.amount, 0, 1, "Grain amount"); positive(value.grainSizePx, "Grain size");
+      assert(value.chroma === "monochrome" || value.chroma === "color", "Grain chroma is invalid.");
+      finite(value.motionRatePxPerFrame, "Grain motion rate"); nonNegativeInteger(value.seed, "Grain seed"); return;
+    case "light-leak":
+      colors(value.colors, "LightLeak colors"); finite(value.angleDeg, "LightLeak angle");
+      range(value.softness, 0, 1, "LightLeak softness"); finite(value.travelPx, "LightLeak travel");
+      range(value.intensity, 0, 1, "LightLeak intensity"); nonNegativeInteger(value.seed, "LightLeak seed"); return;
+    case "bokeh":
+      range(value.amount, 0, 1, "Bokeh amount"); positive(value.sizeMinPx, "Bokeh minimum size");
+      assert(Number.isFinite(value.sizeMaxPx) && value.sizeMaxPx >= value.sizeMinPx, "Bokeh size range is invalid.");
+      color(value.color, "Bokeh color"); range(value.warmth, -1, 1, "Bokeh warmth"); finite(value.driftPx, "Bokeh drift");
+      nonNegativeInteger(value.seed, "Bokeh seed"); return;
+    case "tv-static":
+      range(value.amount, 0, 1, "TVStatic amount"); positive(value.noiseSizePx, "TVStatic noise size");
+      range(value.scanLineOpacity, 0, 1, "TVStatic scan-line opacity");
+      finite(value.motionRatePxPerFrame, "TVStatic motion rate"); nonNegativeInteger(value.seed, "TVStatic seed"); return;
+  }
+  throw new Error("Screen Overlay component kind is unsupported.");
+}
+
+export function sealScreenOverlayHeader(value: ScreenOverlayHeader): ScreenOverlayHeader {
+  assertScreenOverlayHeader(value); return canonicalize(value) as unknown as ScreenOverlayHeader;
+}
+export function assertScreenOverlayHeader(value: ScreenOverlayHeader): void {
+  identity(value.id, "ScreenOverlayHeader.id");
+}
+export function sealScreenOverlayItemSpec(value: ScreenOverlayItemSpec): ScreenOverlayItemSpec {
+  assertScreenOverlayItemSpec(value); return canonicalize(value) as unknown as ScreenOverlayItemSpec;
+}
+export function assertScreenOverlayItemSpec(value: ScreenOverlayItemSpec): void {
+  identity(value.id, "ScreenOverlayItemSpec.id"); assertScreenOverlayComponent(value.content);
+  assert(Number.isSafeInteger(value.stackingOrder), "ScreenOverlay stacking order must be an integer.");
+}
+export function createScreenOverlaySet(): ScreenOverlaySet { return { items: [] }; }
+export function assertScreenOverlaySet(value: ScreenOverlaySet): void {
+  assert(Array.isArray(value.items), "ScreenOverlaySet is invalid.");
+}
+
+function realized(
+  set: ScreenOverlaySet, header: ScreenOverlayHeader, space: ProgramSpace, spec: ScreenOverlayItemSpec,
+  window: ProjectedWindow,
+): ScreenOverlaySet {
+  assertScreenOverlaySet(set); assertScreenOverlayHeader(header); assertScreenOverlayItemSpec(spec);
+  assertTemporalWindowFor(window, { subjectId: spec.id, space });
+  const addition = {
+    id: window.id,
+    subjectId: spec.id,
+    span: { ...window.span },
+    content: structuredClone(spec.content),
+    stacking: { order: spec.stackingOrder, tieBreak: `${header.id}:${spec.id}` },
+  } satisfies ScreenOverlayItemProgram;
+  const ids = new Set(set.items.map((item) => item.id));
+  assert(!ids.has(addition.id), `Screen Overlay already contains Item ${addition.id}.`);
+  return { items: [...set.items, addition] };
+}
+
+/** Component entry point: timing has already been resolved into a TemporalWindow. */
+export function appendProjectedScreenOverlay(
+  set: ScreenOverlaySet,
+  header: ScreenOverlayHeader,
+  space: ProgramSpace,
+  spec: ScreenOverlayItemSpec,
+  window: ProjectedWindow,
+): ScreenOverlaySet {
+  return realized(set, header, space, spec, window);
+}
+export function sealScreenOverlayProgram(value: ScreenOverlayProgram): ScreenOverlayProgram {
+  const normalized = { id: value.id,
+    items: [...value.items].map((item) => structuredClone(item)).sort((a, b) => a.id.localeCompare(b.id)) };
+  assertScreenOverlayProgram(normalized); return canonicalize(normalized) as unknown as ScreenOverlayProgram;
+}
+export function finalizeScreenOverlay(set: ScreenOverlaySet, header: ScreenOverlayHeader): ScreenOverlayProgram {
+  assertScreenOverlaySet(set); assertScreenOverlayHeader(header); assert(set.items.length > 0, "Screen Overlay requires at least one Item.");
+  return sealScreenOverlayProgram({ id: header.id, items: set.items });
+}
+export function assertScreenOverlayProgram(value: ScreenOverlayProgram): void {
+  identity(value.id, "ScreenOverlayProgram.id"); assert(value.items.length > 0, "ScreenOverlayProgram requires Items.");
+  const ids = new Set<string>();
+  for (const item of value.items) {
+    identity(item.id, "ScreenOverlayItemProgram.id"); identity(item.subjectId, "ScreenOverlayItemProgram.subjectId");
+    assert(!ids.has(item.id), `Duplicate Screen Overlay Item ${item.id}.`); ids.add(item.id);
+    assert(item.span.startFrame >= 0 && item.span.endFrameExclusive > item.span.startFrame,
+      `Screen Overlay Item ${item.id} timing is invalid.`);
+    assertScreenOverlayComponent(item.content); assert(Number.isSafeInteger(item.stacking.order) && item.stacking.tieBreak.length > 0,
+      `Screen Overlay Item ${item.id} stacking is invalid.`);
+  }
+}
+
+type Random = () => number;
+function random(seed: number): Random {
+  let state = seed >>> 0;
+  return () => {
+    state += 0x6d2b79f5;
+    let value = state;
+    value = Math.imul(value ^ value >>> 15, value | 1);
+    value ^= value + Math.imul(value ^ value >>> 7, value | 61);
+    return ((value ^ value >>> 14) >>> 0) / 4_294_967_296;
+  };
+}
+function px(value: number): string { return `${Number(value.toFixed(6))}px`; }
+function percent(value: number): string { return `${Number((value * 100).toFixed(6))}%`; }
+function rootStyle(): VisualStyleDeclaration[] { return [
+  { name: "inset", value: "0" }, { name: "overflow", value: "hidden" }, { name: "position", value: "absolute" },
+]; }
+function fullChild(
+  id: string,
+  style: readonly VisualStyleDeclaration[],
+  animation?: VisualAnimation,
+  order = 1,
+): VisualElement {
+  const names = new Set(style.map((item) => item.name));
+  return { id, parent: "root", order, kind: "box", style: [
+    ...(names.has("inset") ? [] : [{ name: "inset", value: "0" }]),
+    ...(names.has("position") ? [] : [{ name: "position", value: "absolute" }]),
+    ...style,
+  ], ...(animation === undefined ? {} : { animation }) };
+}
+function animation(duration: number, start: readonly VisualStyleDeclaration[], end: readonly VisualStyleDeclaration[]): VisualAnimation {
+  return { keyframes: [{ atFrame: 0, style: start }, { atFrame: duration, style: end }] };
+}
+function flashElements(content: Extract<ScreenOverlayComponent, { kind: "flash" }>, duration: number): readonly VisualElement[] {
+  const total = content.attackFrames + content.holdFrames + content.decayFrames;
+  if (total === 0) return [{ id: "root", order: 0, kind: "box", style: [...rootStyle(), { name: "background-color", value: content.color }, { name: "opacity", value: content.intensity }] }];
+  const marks = new Map<number, number>();
+  marks.set(0, content.attackFrames === 0 ? content.intensity : 0);
+  marks.set(content.attackFrames, content.intensity);
+  marks.set(content.attackFrames + content.holdFrames, content.intensity);
+  marks.set(total, 0);
+  marks.set(duration, 0);
+  return [{ id: "root", order: 0, kind: "box", style: [...rootStyle(), { name: "background-color", value: content.color }],
+    animation: { keyframes: [...marks].sort(([a], [b]) => a - b).map(([atFrame, opacity]) => ({ atFrame, style: [{ name: "opacity", value: opacity }] })) } }];
+}
+
+function overlayElements(content: ScreenOverlayComponent, canvas: CanvasSpace, duration: number): readonly VisualElement[] {
+  if (content.kind === "flash") return flashElements(content, duration);
+  const root: VisualElement = { id: "root", order: 0, kind: "box", style: rootStyle() };
+  switch (content.kind) {
+    case "color-wash": return [root, fullChild("wash", [{ name: "background-color", value: content.color }, { name: "opacity", value: content.opacity }])];
+    case "vignette": {
+      const inner = Math.max(0, 1 - content.softness) * 100;
+      return [root, fullChild("vignette", [{ name: "background-image", value: `radial-gradient(ellipse ${percent(content.radius.x)} ${percent(content.radius.y)} at ${percent(content.center.x)} ${percent(content.center.y)},transparent ${inner}%,${content.color} 100%)` }, { name: "opacity", value: content.opacity }])];
+    }
+    case "scan-lines": {
+      const travel = `translate3d(${px(content.travelPx * Math.cos(content.angleDeg * Math.PI / 180))},${px(content.travelPx * Math.sin(content.angleDeg * Math.PI / 180))},0)`;
+      return [root, fullChild("scan-lines", [
+        { name: "background-image", value: `repeating-linear-gradient(${content.angleDeg}deg,#ffffff 0 ${px(content.thicknessPx)},transparent ${px(content.thicknessPx)} ${px(content.spacingPx)})` },
+        { name: "inset", value: "-20%" }, { name: "opacity", value: content.opacity },
+      ], animation(duration, [{ name: "transform", value: "translate3d(0px,0px,0)" }], [{ name: "transform", value: travel }]))];
+    }
+    case "directional-matte": {
+      const extent = Math.hypot(canvas.widthPx, canvas.heightPx) * 2;
+      const move = (progress: number) => `rotate(${content.angleDeg}deg) translate3d(${px((progress - 0.5) * extent)},0px,0)`;
+      const edge = Math.max(0.001, content.feather) * 100;
+      return [root, fullChild("matte", [
+        { name: "background-image", value: `linear-gradient(90deg,${content.color} 0 ${100 - edge}%,transparent 100%)` },
+        { name: "height", value: "200%" }, { name: "left", value: "-50%" }, { name: "opacity", value: content.opacity },
+        { name: "top", value: "-50%" }, { name: "width", value: `${200 * content.coverage}%` },
+      ], animation(duration, [{ name: "transform", value: move(content.progress.from) }], [{ name: "transform", value: move(content.progress.to) }]))];
+    }
+    case "whip-veil": {
+      const horizontal = content.direction === "left" || content.direction === "right";
+      const sign = content.direction === "left" || content.direction === "up" ? -1 : 1;
+      const gradient = horizontal ? "90deg" : "180deg";
+      const transform = (distance: number) => horizontal ? `translate3d(${px(distance)},0px,0)` : `translate3d(0px,${px(distance)},0)`;
+      return [root, fullChild("veil", [
+        { name: "background-image", value: `linear-gradient(${gradient},transparent 0,#ffffff ${px(content.softnessPx)},#ffffff calc(100% - ${px(content.softnessPx)}),transparent 100%)` },
+        { name: "height", value: horizontal ? "100%" : px(content.widthPx) }, { name: "opacity", value: content.opacity },
+        { name: "width", value: horizontal ? px(content.widthPx) : "100%" },
+      ], animation(duration, [{ name: "transform", value: transform(-sign * content.travelPx) }], [{ name: "transform", value: transform(sign * content.travelPx) }]))];
+    }
+    case "glitch-veil": {
+      const rng = random(content.seed);
+      return [root, ...Array.from({ length: content.bars }, (_, index): VisualElement => {
+        const height = 1 + rng() * 12;
+        const y = rng() * 100;
+        const x = (rng() - 0.5) * 20;
+        const colorValue = content.colors[index % content.colors.length]!;
+        return { id: `bar-${index + 1}`, parent: "root", order: index + 1, kind: "box", style: [
+          { name: "background-color", value: colorValue }, { name: "height", value: percent(height / 100) },
+          { name: "left", value: percent(x / 100) }, { name: "opacity", value: content.opacity * (0.35 + rng() * 0.65) },
+          { name: "position", value: "absolute" }, { name: "top", value: percent(y / 100) }, { name: "width", value: "120%" },
+        ], animation: animation(duration, [{ name: "transform", value: "translate3d(0px,0px,0)" }], [{ name: "transform", value: `translate3d(${px(content.travelPx * (rng() < 0.5 ? -1 : 1))},0px,0)` }]) };
+      })];
+    }
+    case "grain": {
+      const rng = random(content.seed); const count = Math.max(1, Math.round(content.amount * 160));
+      return [root, ...Array.from({ length: count }, (_, index): VisualElement => {
+        const hue = content.chroma === "color" ? Math.round(rng() * 360) : 0;
+        const shade = Math.round(rng() * 255);
+        const background = content.chroma === "color" ? `hsl(${hue} 85% 60%)` : `rgb(${shade} ${shade} ${shade})`;
+        const drift = content.motionRatePxPerFrame * duration * (rng() < 0.5 ? -1 : 1);
+        return { id: `grain-${index + 1}`, parent: "root", order: index + 1, kind: "box", style: [
+          { name: "background-color", value: background }, { name: "height", value: px(content.grainSizePx) },
+          { name: "left", value: percent(rng()) }, { name: "opacity", value: 0.08 + content.amount * 0.42 },
+          { name: "position", value: "absolute" }, { name: "top", value: percent(rng()) }, { name: "width", value: px(content.grainSizePx) },
+        ], animation: animation(duration, [{ name: "transform", value: "translate3d(0px,0px,0)" }], [{ name: "transform", value: `translate3d(${px(drift)},${px(-drift)},0)` }]) };
+      })];
+    }
+    case "light-leak": {
+      const rng = random(content.seed); const offset = (rng() - 0.5) * 30;
+      const stops = content.colors.map((entry, index) => `${entry} ${Number(index * 100 / Math.max(1, content.colors.length - 1)).toFixed(3)}%`).join(",");
+      return [root, fullChild("light-leak", [
+        { name: "background-image", value: `linear-gradient(${content.angleDeg + offset}deg,transparent 0,${stops},transparent 100%)` },
+        { name: "filter", value: `blur(${px(content.softness * 80)})` }, { name: "inset", value: "-20%" },
+        { name: "opacity", value: content.intensity },
+      ], animation(duration, [{ name: "transform", value: `translate3d(${px(-content.travelPx)},0px,0)` }], [{ name: "transform", value: `translate3d(${px(content.travelPx)},0px,0)` }]))];
+    }
+    case "bokeh": {
+      const rng = random(content.seed); const count = Math.max(1, Math.round(content.amount * 48));
+      return [root, ...Array.from({ length: count }, (_, index): VisualElement => {
+        const size = content.sizeMinPx + rng() * (content.sizeMaxPx - content.sizeMinPx);
+        const warmthFilter = content.warmth === 0 ? "" : `sepia(${Math.abs(content.warmth)}) hue-rotate(${content.warmth < 0 ? 180 : 0}deg) `;
+        return { id: `bokeh-${index + 1}`, parent: "root", order: index + 1, kind: "box", style: [
+          { name: "background-color", value: content.color }, { name: "border-radius", value: "50%" },
+          { name: "filter", value: `${warmthFilter}blur(${px(size * 0.08)})` }, { name: "height", value: px(size) },
+          { name: "left", value: percent(rng()) }, { name: "opacity", value: 0.08 + rng() * 0.32 },
+          { name: "position", value: "absolute" }, { name: "top", value: percent(rng()) }, { name: "width", value: px(size) },
+        ], animation: animation(duration, [{ name: "transform", value: "translate3d(0px,0px,0)" }], [{ name: "transform", value: `translate3d(${px((rng() - 0.5) * content.driftPx)},${px((rng() - 0.5) * content.driftPx)},0)` }]) };
+      })];
+    }
+    case "tv-static": {
+      const rng = random(content.seed); const columns = Math.ceil(canvas.widthPx / content.noiseSizePx);
+      const rows = Math.ceil(canvas.heightPx / content.noiseSizePx); const count = Math.min(512, Math.max(1, Math.round(columns * rows * content.amount)));
+      const cells = Array.from({ length: count }, (_, index): VisualElement => {
+        const shade = Math.round(rng() * 255); const drift = content.motionRatePxPerFrame * duration;
+        return { id: `static-${index + 1}`, parent: "root", order: index + 1, kind: "box", style: [
+          { name: "background-color", value: `rgb(${shade} ${shade} ${shade})` }, { name: "height", value: px(content.noiseSizePx) },
+          { name: "left", value: percent(rng()) }, { name: "opacity", value: 0.2 + content.amount * 0.6 },
+          { name: "position", value: "absolute" }, { name: "top", value: percent(rng()) }, { name: "width", value: px(content.noiseSizePx) },
+        ], animation: animation(duration, [{ name: "transform", value: "translate3d(0px,0px,0)" }], [{ name: "transform", value: `translate3d(0px,${px(drift * (rng() < 0.5 ? -1 : 1))},0)` }]) };
+      });
+      return [root, ...cells, fullChild("static-scan-lines", [
+        { name: "background-image", value: "repeating-linear-gradient(180deg,transparent 0 3px,#000000 3px 4px)" },
+        { name: "opacity", value: content.scanLineOpacity },
+      ], undefined, cells.length + 1)];
+    }
+  }
+}
+
+export function renderScreenOverlay(canvas: CanvasSpace, space: ProgramSpace, program: ScreenOverlayProgram): VisualTrack {
+  assertCanvasSpace(canvas); assertProgramSpaceIdentity(space); assertScreenOverlayProgram(program);
+  const track = sealVisualTrack({
+    programSpaceId: space.id, visualIr: "hypit.visual-ir@1", id: program.id,
+    presents: program.items.map((item) => ({
+      id: item.id, subjectId: item.subjectId, span: { ...item.span }, stacking: { ...item.stacking },
+      elements: overlayElements(item.content, canvas, item.span.endFrameExclusive - item.span.startFrame),
+    })),
+  });
+  assertVisualTrackIdentity(track, space);
+  return track;
+}