@hypit/hypit 0.0.1 → 0.1.0

package/packages/caption-fine/src/manifest.ts

@@ -0,0 +1,383 @@
+import { readFile } from "node:fs/promises";
+
+import { captionManifest, captionModuleRef, captionTypes } from "@hypit/caption";
+import { compositionDependency, compositionTypes } from "@hypit/composition";
+import { mediaDependency, mediaTypes } from "@hypit/media";
+import { narrativeDependency, narrativeTypes } from "@hypit/narrative";
+import { programSpaceDependency, programSpaceTypes } from "@hypit/program-space";
+import type { ModuleManifest, ProducerRef } from "@hypit/protocol";
+import { semanticTrackDependency, semanticTrackTypes } from "@hypit/semantic-track";
+import { spatialDependency, spatialTypes } from "@hypit/spatial";
+import { svsRecipeType } from "@hypit/svs";
+
+import { fineCaptionOneShotMotions } from "./recipe.js";
+
+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 captionFineModuleRef = { name: "@hypit/caption-fine", version: "1" } as const;
+export const captionFineTypes = {
+  schedule: { module: captionFineModuleRef, name: "FineCaptionSchedule" },
+} as const;
+export const captionFineProducers = {
+  schedule: { module: captionFineModuleRef, name: "schedule-fine-caption" },
+  render: { module: captionFineModuleRef, name: "render-fine-caption" },
+  renderWithRegions: { module: captionFineModuleRef, name: "render-fine-caption-with-regions" },
+} satisfies Record<string, ProducerRef>;
+
+export const captionFineMarkupSurfaces = [
+    {
+      name: "style", tag: "Style", mode: "structured", outputs: [captionTypes.style],
+      vocabulary: {
+        summary: "Resolves one SVS Recipe and one exact font stack into a complete fine-grained Caption Style.",
+        attributes: [
+          { name: "id", kind: "identifier", required: true,
+            summary: "Names this Style so a Caption Program can assign it." },
+          { name: "recipe", kind: "reference", required: true, accepts: [svsRecipeType],
+            summary: "Chooses the Recipe that carries Cue geometry, Paint and local motion.",
+            recipe: [
+              { name: "stack-order", required: true,
+                summary: "Places this Style's Cues in the Track's drawing order, low behind high." },
+              { name: "x", required: true,
+                summary: "Places the Cue box horizontally as a fraction of the Canvas width." },
+              { name: "y", required: true,
+                summary: "Places the Cue box vertically as a fraction of the Canvas height." },
+              { name: "width", required: true,
+                summary: "Sets the Cue box width as a fraction of the Canvas width." },
+              { name: "height", required: false,
+                summary: "Optionally gives the Caption Region a fixed fraction of Canvas height; without it the Region hugs its Cue." },
+              { name: "anchor-x", required: false, values: ["left", "center", "right"], fallback: "left",
+                summary: "Decides which horizontal edge of the Cue box sits on the placement point." },
+              { name: "anchor-y", required: false, values: ["top", "center", "bottom"], fallback: "top",
+                summary: "Decides which vertical edge of the Cue box sits on the placement point." },
+              { name: "align", required: true, values: ["left", "center", "right"],
+                summary: "Aligns the Words within each line of the Cue." },
+              { name: "block-align", required: false, values: ["start", "center", "end"], fallback: "center",
+                summary: "Aligns the Cue vertically inside a fixed-height Caption Region." },
+              { name: "inline-size", required: false, values: ["hug", "fixed"], fallback: "hug",
+                summary: "Chooses whether the Cue hugs its text up to the Region width or fills the Region width." },
+              { name: "wrap", required: false, values: ["word", "grapheme"], fallback: "word",
+                summary: "Wraps at Word boundaries, falling back for an over-wide Word, or permits a break at any grapheme." },
+              { name: "max-lines", required: false,
+                summary: "Rejects too many counted rows; requires max-words-per-line. Does not measure browser wrapping or guarantee a single physical line." },
+              { name: "max-words-per-line", required: false,
+                summary: "Optional counted row breaks between complete alignment units. Counts display Words, normally individual characters in Chinese; preserves Cues. Omit for width-based flow." },
+              { name: "direction", required: false, values: ["ltr", "rtl"], fallback: "ltr",
+                summary: "Sets the writing direction the Words are laid out in." },
+              { name: "line-height", required: true,
+                summary: "Sets the line box height as a multiple of the type size." },
+              { name: "letter-spacing", required: false, fallback: "0",
+                summary: "Adds pixels of tracking between glyphs." },
+              { name: "word-gap", required: false, fallback: "a quarter of size",
+                summary: "Sets pixel spacing between Latin words and at Chinese/Latin boundaries. Adjacent Han characters and full-width punctuation have no extra word gap; use letter-spacing for tracking." },
+              { name: "size", required: true,
+                summary: "Sets the type size in pixels." },
+              { name: "kerning", required: false, values: ["auto", "normal", "none"], fallback: "auto",
+                summary: "Controls font kerning for the complete uniform Cue flow." },
+              { name: "caps", required: false, values: ["normal", "small-caps", "all-small-caps"], fallback: "normal",
+                summary: "Chooses the OpenType caps presentation for every Word." },
+              { name: "text-transform", required: false, values: ["none", "uppercase", "lowercase", "capitalize"], fallback: "none",
+                summary: "Recases every display Word before it is drawn." },
+              { name: "fill", required: true,
+                summary: "Paints the glyph body of an ordinary Word, as an RGB or RGBA hex color." },
+              { name: "opacity", required: false, fallback: "1",
+                summary: "Fades the whole glyph Paint of an ordinary Word." },
+              { name: "gradient-from", required: false,
+                summary: "Starts a glyph gradient that replaces the flat fill, and must be written together with gradient-to." },
+              { name: "gradient-to", required: false,
+                summary: "Ends the glyph gradient, and must be written together with gradient-from." },
+              { name: "gradient-angle", required: false, fallback: "90",
+                summary: "Turns the glyph gradient by this many degrees." },
+              { name: "stroke-color", required: false, fallback: "#000000",
+                summary: "Paints the outline drawn around each glyph." },
+              { name: "stroke-width", required: false, fallback: "0",
+                summary: "Sets the glyph outline thickness in pixels, and the number that matters is its share of `size`: about a twentieth. At a `size` of 46 that is 2px, at 54 it is 3px. Write it from `size` every time rather than picking a pixel count, because the whole width shows — the outline is placed outside the letter, so it keeps the letterform but grows into the space around it twice as fast as a centred one would. Past about a tenth of `size` neighbouring letters meet, the counters fill in, and the caption reads as a slab rather than as words." },
+              { name: "shadow-color", required: false, fallback: "#000000",
+                summary: "Paints the soft drop shadow behind each glyph." },
+              { name: "shadow-opacity", required: false, fallback: "0",
+                summary: "Sets how strongly the glyph drop shadow reads." },
+              { name: "shadow-x", required: false, fallback: "0",
+                summary: "Slides the whole shadow sideways, so its ink lands at this plus `shadow-spread` plus about one and a half times `shadow-blur` from the letter. A shadow that reads as depth rather than as a second copy of the word stays under its own blur: around a fortieth of `size`, 1px at 46." },
+              { name: "shadow-y", required: false, fallback: "0",
+                summary: "Drops the whole shadow, positive downward, reaching this plus `shadow-spread` plus about one and a half times `shadow-blur`. Down is the direction that runs out of room: the gap between line boxes is `line-height` minus one, times `size`, and past it the shadow lands on the line below. Around a fortieth of `size`, 1px at 46." },
+              { name: "shadow-blur", required: false, fallback: "0",
+                summary: "Softens the glyph drop shadow by this many pixels. A shadow that only has to lift the caption off the picture is soft and short — a blur near a tenth of `size` with an offset a fraction of that. Much more and the shadow stops being an edge and becomes a grey cloud the letters sit in, which costs the contrast the shadow was there to protect." },
+              { name: "shadow-spread", required: false, fallback: "0",
+                summary: "Grows the shadow's silhouette before it is blurred, on every side. The shadow then reaches this plus the offset plus about one and a half times `shadow-blur`, so it is the smallest of the three: around a fiftieth of `size`, 1px at 46. Zero and below dilate nothing; the filter grows the shape and has no way to shrink it." },
+              { name: "long-shadow-color", required: false, fallback: "#000000",
+                summary: "Paints the solid extruded shadow trailing each glyph." },
+              { name: "long-shadow-opacity", required: false, fallback: "0",
+                summary: "Sets how strongly the extruded glyph shadow reads." },
+              { name: "long-shadow-distance", required: false, fallback: "0",
+                summary: "Sets how far the extruded glyph shadow travels in pixels. It is a deliberate graphic effect rather than separation from the picture, so it is chosen on purpose or left at zero. When used, a travel of a tenth to a fifth of `size` reads as depth; beyond that the extrusion reaches the line below and the block stops being readable as lines of text." },
+              { name: "long-shadow-angle", required: false, fallback: "45",
+                summary: "Sets the direction the extruded glyph shadow travels in degrees." },
+              { name: "glow-color", required: false, fallback: "#FFFFFF",
+                summary: "Paints the halo bloomed around each glyph." },
+              { name: "glow-opacity", required: false, fallback: "0",
+                summary: "Sets how strongly the glyph halo reads." },
+              { name: "glow-blur", required: false, fallback: "0",
+                summary: "Spreads the glyph halo by this many pixels. A halo reads as a halo while it stays close to the glyph — near a tenth of `size`. Spread wide it stops tracing the letters, fills the space between them and washes the caption into a bright smear; the gaps between letters go first, exactly as they do under a heavy outline." },
+              { name: "glow-spread", required: false, fallback: "0",
+                summary: "Grows the letterform before the halo is blurred, hard-edged, on every side. It adds to the blur rather than replacing it — the halo reaches this plus about one and a half times `glow-blur` — so it is the smaller number of the two: around a fiftieth of `size`, 1px at 46. At a fifth of `size` the dilated letters touch before any softening and the counters close." },
+              { name: "active-fill", required: false, fallback: "#FFD54A",
+                summary: "Paints the glyph body of the Word being spoken." },
+              { name: "active-opacity", required: false, fallback: "opacity",
+                summary: "Fades the whole glyph Paint of the Word being spoken." },
+              { name: "active-gradient-from", required: false,
+                summary: "Starts the active glyph gradient, and must be written together with active-gradient-to." },
+              { name: "active-gradient-to", required: false,
+                summary: "Ends the active glyph gradient, and must be written together with active-gradient-from." },
+              { name: "active-gradient-angle", required: false, fallback: "gradient-angle",
+                summary: "Turns the active glyph gradient by this many degrees." },
+              { name: "active-stroke-color", required: false, fallback: "stroke-color",
+                summary: "Paints the outline around the Word being spoken." },
+              { name: "active-stroke-width", required: false, fallback: "stroke-width",
+                summary: "Sets the active glyph outline thickness in pixels. It inherits `stroke-width`, and the same share of `size` holds: emphasis on the spoken Word is carried by its Paint, so thickening its outline past the rest buys little and closes the gaps between its letters first." },
+              { name: "active-shadow-color", required: false, fallback: "shadow-color",
+                summary: "Paints the drop shadow behind the Word being spoken." },
+              { name: "active-shadow-opacity", required: false, fallback: "shadow-opacity",
+                summary: "Sets how strongly the active drop shadow reads." },
+              { name: "active-shadow-x", required: false, fallback: "shadow-x",
+                summary: "Slides the spoken Word's shadow sideways. It inherits `shadow-x`, and the visible quantity is the difference: the shadow jumps by it as the Word becomes active and jumps back as it stops, which reads as the light moving mid-line." },
+              { name: "active-shadow-y", required: false, fallback: "shadow-y",
+                summary: "Drops the spoken Word's shadow, positive downward. It inherits `shadow-y`, and the visible quantity is the difference: the shadow steps down as the Word becomes active and back up as it stops, which reads as the Word lifting off the line." },
+              { name: "active-shadow-blur", required: false, fallback: "shadow-blur",
+                summary: "Softens the spoken Word's drop shadow, reaching about one and a half times this number. It inherits `shadow-blur`, and the visible quantity is the difference: any gap between the two reads as the Word sitting at a different depth from the words beside it." },
+              { name: "active-shadow-spread", required: false, fallback: "shadow-spread",
+                summary: "Grows the spoken Word's shadow silhouette before blur. It inherits `shadow-spread`, and the visible quantity is the difference. Zero and below dilate nothing; the filter grows the shape and has no way to shrink it." },
+              { name: "active-long-shadow-color", required: false, fallback: "long-shadow-color",
+                summary: "Paints the extruded shadow trailing the Word being spoken." },
+              { name: "active-long-shadow-opacity", required: false, fallback: "long-shadow-opacity",
+                summary: "Sets how strongly the active extruded shadow reads." },
+              { name: "active-long-shadow-distance", required: false, fallback: "long-shadow-distance",
+                summary: "Sets how far the active extruded shadow travels in pixels." },
+              { name: "active-long-shadow-angle", required: false, fallback: "long-shadow-angle",
+                summary: "Sets the direction the active extruded shadow travels in degrees." },
+              { name: "active-glow-color", required: false, fallback: "glow-color",
+                summary: "Paints the halo bloomed around the Word being spoken." },
+              { name: "active-glow-opacity", required: false, fallback: "glow-opacity",
+                summary: "Sets how strongly the active halo reads." },
+              { name: "active-glow-blur", required: false, fallback: "glow-blur",
+                summary: "Spreads the active halo by this many pixels. Widening it is the usual way of trying to make the spoken Word stand out, and the usual way of losing it: the halo leaves the glyph, fills the gaps to its neighbours and blurs the very Word it was meant to pick out. The Word is already picked out by its own Paint — leave this near `glow-blur`." },
+              { name: "active-glow-spread", required: false, fallback: "glow-spread",
+                summary: "Grows the spoken Word's letterform before its halo is blurred. It inherits `glow-spread`, and the visible quantity is the difference: the Word's halo is thicker than its neighbours' by exactly that, and the gap it closes first is `word-gap`." },
+              { name: "background", required: true,
+                summary: "Paints the Cue box behind the Words, as an RGB or RGBA hex color." },
+              { name: "border-color", required: false, fallback: "#00000000",
+                summary: "Paints the Cue box border." },
+              { name: "border-width", required: false, fallback: "0",
+                summary: "Sets the Cue box border thickness in pixels." },
+              { name: "padding", required: true,
+                summary: "Insets the Words from the Cue box edge, as one pixel number or a vertical and horizontal pair." },
+              { name: "radius", required: true,
+                summary: "Rounds the Cue box corners by this many pixels." },
+              { name: "cue-shadow-color", required: false, fallback: "#000000",
+                summary: "Paints the shadow cast by the Cue box rather than by its glyphs." },
+              { name: "cue-shadow-opacity", required: false, fallback: "0",
+                summary: "Sets the Cue box shadow opacity." },
+              { name: "cue-shadow-x", required: false, fallback: "0",
+                summary: "Slides the whole Cue box shadow sideways, so it clears the box on one side by this plus spread plus blur and is hidden behind it on the other. Kept under the blur it reads as depth; past it the shadow becomes a band beside the box." },
+              { name: "cue-shadow-y", required: false, fallback: "0",
+                summary: "Drops the whole Cue box shadow, positive downward. Kept under `cue-shadow-blur` it reads as the box lifting off the picture; past it the shadow's top edge clears the box and shows as a bare band under it." },
+              { name: "cue-shadow-blur", required: false, fallback: "0",
+                summary: "Softens the Cue box shadow, reaching about this far past the box and no further. This is the one place the two shadow families differ: a glyph `shadow-blur` is halved into a deviation and reaches half again as far, while this number is the reach. Around a tenth of `size`, 5px at 46." },
+              { name: "cue-shadow-spread", required: false, fallback: "0",
+                summary: "Grows the shadow rectangle before it is blurred, and unlike the glyph shadow it does contract: a negative spread equal to the blur pulls the shadow entirely behind the box. The edge sits at this plus `cue-shadow-blur` past every side, before any offset." },
+              { name: "underline", required: false, values: ["off", "always"], fallback: "off",
+                summary: "Decides whether every Word carries a rule beneath it." },
+              { name: "underline-color", required: false, fallback: "fill",
+                summary: "Paints the ordinary Word underline." },
+              { name: "underline-thickness", required: false, fallback: "2",
+                summary: "Sets the ordinary Word underline thickness in pixels." },
+              { name: "underline-offset", required: false, fallback: "4",
+                summary: "Drops the ordinary Word underline this many pixels below the baseline." },
+              { name: "active-underline", required: false, values: ["off", "current", "trail"], fallback: "off",
+                summary: "Decides whether the Word being spoken, or every Word up to it, carries a rule beneath it." },
+              { name: "active-underline-color", required: false, fallback: "#FFD54A",
+                summary: "Paints the active Word underline." },
+              { name: "active-underline-thickness", required: false, fallback: "3",
+                summary: "Sets the active Word underline thickness in pixels." },
+              { name: "active-underline-offset", required: false, fallback: "4",
+                summary: "Drops the active Word underline this many pixels below the baseline." },
+              { name: "karaoke", required: false, values: ["off", "current", "trail"], fallback: "off",
+                summary: "Decides whether the active Paint marks only the Word being spoken or every Word up to it." },
+              { name: "karaoke-transition", required: false, values: ["step", "wipe"], fallback: "step",
+                summary: "Decides whether the karaoke Paint snaps at the Word boundary or sweeps across the glyphs." },
+              { name: "active-box", required: false, values: ["off", "current", "trail"], fallback: "off",
+                summary: "Decides whether a highlight box sits behind the Word being spoken or behind every Word up to it." },
+              { name: "active-box-continuity", required: false, values: ["isolated", "joined"], fallback: "isolated",
+                summary: "Decides whether trailing highlight boxes stand apart or merge into one run." },
+              { name: "active-box-background", required: false, fallback: "#FFD54A",
+                summary: "Paints the highlight box behind the active Word." },
+              { name: "active-box-border-color", required: false, fallback: "#00000000",
+                summary: "Paints the highlight box border." },
+              { name: "active-box-border-width", required: false, fallback: "0",
+                summary: "Sets the highlight box border thickness in pixels." },
+              { name: "active-box-padding", required: false, fallback: "0",
+                summary: "Insets the Word from the highlight box edge, as one pixel number or a vertical and horizontal pair." },
+              { name: "active-box-radius", required: false, fallback: "8",
+                summary: "Rounds the highlight box corners by this many pixels." },
+              { name: "active-box-enter", required: false, values: fineCaptionOneShotMotions, fallback: "none",
+                summary: "Plays this motion as the highlight box arrives on a Word." },
+              { name: "active-box-exit", required: false, values: fineCaptionOneShotMotions, fallback: "none",
+                summary: "Plays this motion as the highlight box leaves a Word." },
+              { name: "active-box-transition-frames", required: false, fallback: "0",
+                summary: "Sets how many Frames the highlight box entrance and exit each run for." },
+              { name: "cue-enter", required: false, values: fineCaptionOneShotMotions, fallback: "none",
+                summary: "Plays this motion as a Cue arrives." },
+              { name: "cue-enter-frames", required: false, fallback: "0",
+                summary: "Sets how many Frames the Cue entrance runs for." },
+              { name: "cue-enter-start-scale", required: false,
+                summary: "Overrides the Cue entrance motion's initial uniform scale while preserving that motion's own curve; 0.55 begins at fifty-five percent size and settles at one." },
+              { name: "cue-exit", required: false, values: fineCaptionOneShotMotions, fallback: "none",
+                summary: "Plays this motion as a Cue leaves." },
+              { name: "cue-exit-frames", required: false, fallback: "0",
+                summary: "Sets how many Frames the Cue exit runs for." },
+              { name: "atom-enter", required: false, values: fineCaptionOneShotMotions, fallback: "none",
+                summary: "Plays this motion as an Atom arrives within its Cue." },
+              { name: "atom-enter-frames", required: false, fallback: "0",
+                summary: "Sets how many Frames the Atom entrance runs for." },
+              { name: "atom-exit", required: false, values: fineCaptionOneShotMotions, fallback: "none",
+                summary: "Plays this motion as an Atom leaves within its Cue." },
+              { name: "atom-exit-frames", required: false, fallback: "0",
+                summary: "Sets how many Frames the Atom exit runs for." },
+              { name: "atom-reveal", required: false, values: ["all", "on-start", "typewriter"], fallback: "all",
+                summary: "Decides whether a Cue shows all of its Atoms at once or uncovers them as they are spoken." },
+              { name: "active-response", required: false, values: fineCaptionOneShotMotions, fallback: "none",
+                summary: "Plays this motion on a Word at the moment it becomes the spoken one." },
+              { name: "active-response-frames", required: false, fallback: "6",
+                summary: "Sets how many Frames the active response runs for." },
+              { name: "active-scale", required: false, fallback: "1.08",
+                summary: "Sets how far the active response grows the Word." },
+              { name: "slide-distance", required: false, fallback: "24",
+                summary: "Sets how far the sliding and wiping motions travel in pixels." },
+              { name: "loop", required: false, fallback: "none",
+                values: ["none", "shake", "wobble", "glow-pulse", "breathe", "float", "pulse", "flicker"],
+                summary: "Plays this motion continuously for as long as its target is on screen." },
+              { name: "loop-target", required: false, values: ["cue", "active-atom"], fallback: "cue",
+                summary: "Decides whether the looping motion moves the whole Cue or only the Atom being spoken." },
+              { name: "loop-period-frames", required: false, fallback: "12",
+                summary: "Sets how many Frames one cycle of the looping motion takes." },
+              { name: "loop-intensity", required: false, fallback: "1",
+                summary: "Scales how far the looping motion carries." },
+              { name: "lead-frames", required: false, fallback: "0",
+                summary: "Makes the Cue visible this many Frames before its first semantic Word without moving any Word timing." },
+              { name: "tail-frames", required: false, fallback: "0",
+                summary: "Keeps the Cue visible this many Frames after its last semantic Word without extending any Word timing." },
+              { name: "handoff", required: false, values: ["cut", "overlap"], fallback: "cut",
+                summary: "Chooses whether adjacent Cue visibility envelopes meet without overlap or may coexist." },
+            ] },
+          { name: "font", kind: "reference", required: true,
+            accepts: [mediaTypes.fontArtifact, mediaTypes.fontStack],
+            summary: "Chooses the primary face, or a whole reusable stack that already carries its own fallbacks." },
+        ],
+        children: [
+          { tag: "Fallback", cardinality: "many",
+            summary: "Appends one more exact face after the primary one, in the order written, and accepts no children of its own.",
+            attributes: [
+              { name: "font", kind: "reference", required: true, accepts: [mediaTypes.fontArtifact],
+                summary: "Chooses the single face this fallback contributes." },
+            ] },
+        ],
+        example: `<fonts:Stack id="caption-font" family="inter" weight="800" style="normal"/>
+<caption-fine:Style id="primary-caption" recipe={recipes.caption.primary} font={caption-font}/>`,
+        notes: [
+          "Referencing a font stack in `font` and writing `<Fallback>` children are both allowed; the stack's faces come first.",
+          "The Style is addressed by its own id, and the element accepts no text.",
+          "The Recipe accepts only the properties declared here; any other property is rejected.",
+          "A gradient needs both of its colors: writing any one of `gradient-from`, `gradient-to` or `gradient-angle` without both colors is rejected, and the same holds for the `active-` gradient.",
+          "The active glyph Paint inherits every base property it does not override, except the gradient, which the active Paint drops unless it writes its own.",
+        ],
+      },
+    },
+    {
+      name: "track", tag: "Track", mode: "structured", outputs: [captionFineTypes.schedule, compositionTypes.visualTrack],
+      vocabulary: {
+        summary: "Joins the authored CaptionDocument against the SemanticTrack and renders it as one ordinary peer VisualTrack.",
+        appearance: "One block of caption text wrapped into lines inside a rounded Cue box, placed at a Recipe-chosen point on the Canvas and spanning a fraction of its width. Cues follow the speech one after another, each arriving and leaving with its own motion, and the Words of a Cue either stand there together from its first Frame or uncover as they are spoken. As the speech advances, the Word being spoken, or every Word up to it, is repainted in the active Paint, snapping at the Word boundary or sweeping across the glyphs, and it may take a rule beneath it, a rounded highlight capsule behind it and a brief pop at the moment it becomes the spoken one. That capsule either stands alone on each Atom or grows as one continuous run over everything already read, following the Words across line breaks.\n\nEvery Cue uses the ordered exact font stack its Style names, with fallback faces supplying glyphs for other scripts. Emphasis varies by timed unit through the active Paint. Lines follow the common flow, so a line cannot be given a separate face, colour or weight of its own. A caption whose lines are set in different typefaces is outside what this Track can draw.",
+        preview: previewImage("Track.png"),
+        attributes: [
+          { name: "id", kind: "identifier", required: true,
+            summary: "Names this Track so its rendered output can be placed in a Film." },
+          { name: "document", kind: "reference", required: true, accepts: [narrativeTypes.captionDocument],
+            summary: "Chooses the Script-owned CaptionDocument." },
+          { name: "semantic", kind: "reference", required: true, accepts: [semanticTrackTypes.track],
+            summary: "Chooses the continuous SemanticTrack whose Word anchors give every Cue its time." },
+          { name: "program", kind: "reference", required: true, accepts: [captionTypes.program],
+            summary: "Chooses the Style assignment that decides which Style each run is rendered in." },
+          { name: "regions", kind: "reference", required: false, accepts: [spatialTypes.regionTimeline],
+            summary: "Optionally follows external, frame-exact regions whose ids equal Script Roles, placing a Cue at its measured speaker region's top center and hiding it on null Frames." },
+        ],
+        ports: [
+          { name: "schedule", type: captionFineTypes.schedule,
+            summary: "The visible Cue schedule consumed by the renderer and other declared tools." },
+          { name: "track", type: compositionTypes.visualTrack,
+            summary: "The rendered Caption as one self-contained VisualTrack." },
+        ],
+        example: `<caption-fine:Track id="captions" document={story.caption} semantic={speech.semantic} program={caption-program}/>`,
+        notes: [
+          "The element is empty; it accepts no children and no text.",
+          "One Track renders the Program's default Style and every ordered replacement together.",
+          "Without regions, Recipe x/y placement is unchanged. With regions, a measured region overrides x/y for that Frame; a null Frame on that Role track hides the Cue, while a missing Role track retains authored x/y.",
+          "The tracked point replaces Recipe x/y while width and the Recipe anchor still decide the Caption box geometry; anchor-x=center and anchor-y=bottom place the box immediately above the measured region.",
+        ],
+      },
+    },
+  ] as const;
+
+
+export const captionFineManifest: ModuleManifest = {
+  format: "hypit.module@1",
+  name: captionFineModuleRef.name,
+  version: captionFineModuleRef.version,
+  dependencies: [
+    { module: captionModuleRef },
+    compositionDependency,
+    mediaDependency,
+    narrativeDependency,
+    programSpaceDependency,
+    semanticTrackDependency,
+    spatialDependency,
+  ],
+  types: [{ name: captionFineTypes.schedule.name }],
+  capabilities: [],
+  producers: [
+    {
+      name: captionFineProducers.schedule.name,
+      inputs: [
+        { name: "caption", type: captionTypes.timedProjection },
+        { name: "program", type: captionTypes.program },
+        { name: "document", type: narrativeTypes.captionDocument },
+      ],
+      outputs: [{ name: "schedule", type: captionFineTypes.schedule }],
+      needs: [],
+    },
+    {
+      name: captionFineProducers.render.name,
+      inputs: [
+        { name: "schedule", type: captionFineTypes.schedule },
+        { name: "program", type: captionTypes.program },
+        { name: "document", type: narrativeTypes.captionDocument },
+        { name: "space", type: programSpaceTypes.programSpace },
+      ],
+      outputs: [{ name: "track", type: compositionTypes.visualTrack }],
+      needs: [],
+    },
+    {
+      name: captionFineProducers.renderWithRegions.name,
+      inputs: [
+        { name: "schedule", type: captionFineTypes.schedule },
+        { name: "program", type: captionTypes.program },
+        { name: "document", type: narrativeTypes.captionDocument },
+        { name: "space", type: programSpaceTypes.programSpace },
+        { name: "regions", type: spatialTypes.regionTimeline },
+      ],
+      outputs: [{ name: "track", type: compositionTypes.visualTrack }],
+      needs: [],
+    },
+  ],
+};

package/packages/caption-fine/src/recipe.ts

@@ -0,0 +1,120 @@
+import type { ValueSchema } from "@hypit/protocol";
+
+export const fineCaptionOneShotMotions = [
+  "none", "fade", "pop", "scale", "spring", "bounce", "elastic", "stamp", "tilt", "zoom-blur",
+  "flip-x", "flip-y", "spin", "squash", "stretch", "slide-left", "slide-right", "slide-up", "slide-down",
+  "blur-in", "wipe-left", "wipe-right", "wipe-up", "wipe-down",
+] as const;
+
+const paired = (...names: readonly string[]): readonly string[] =>
+  names.flatMap((name) => [name, `active-${name}`]);
+
+const colors = new Set([
+  ...paired("fill", "glow-color", "gradient-from", "gradient-to", "long-shadow-color", "shadow-color", "stroke-color"),
+  "background", "border-color", "cue-shadow-color", "underline-color",
+  "active-box-background", "active-box-border-color", "active-underline-color",
+]);
+
+const unitFractions = new Set([
+  "cue-shadow-opacity", "height", "x", "y", "width",
+  ...paired("opacity", "glow-opacity", "long-shadow-opacity", "shadow-opacity"),
+]);
+
+const integers = new Set([
+  "stack-order",
+  "lead-frames", "tail-frames",
+  "max-lines", "max-words-per-line",
+  "active-box-transition-frames", "active-response-frames",
+  "atom-enter-frames", "atom-exit-frames", "cue-enter-frames", "cue-exit-frames",
+  "loop-period-frames",
+]);
+
+const numbers = new Set([
+  "size", "radius", "line-height", "border-width", "letter-spacing", "loop-intensity",
+  "cue-shadow-blur", "cue-shadow-spread", "cue-shadow-x", "cue-shadow-y",
+  "cue-enter-start-scale",
+  "slide-distance", "word-gap", "active-box-border-width", "active-box-radius", "active-scale",
+  "underline-offset", "underline-thickness", "active-underline-offset", "active-underline-thickness",
+  ...paired("glow-blur", "glow-spread", "gradient-angle", "long-shadow-angle", "long-shadow-distance",
+    "shadow-blur", "shadow-spread", "shadow-x", "shadow-y", "stroke-width"),
+]);
+
+const strings = new Set(["padding", "active-box-padding"]);
+
+const enums: Readonly<Record<string, readonly string[]>> = {
+  "handoff": ["cut", "overlap"],
+  "align": ["left", "center", "right"],
+  "block-align": ["start", "center", "end"],
+  "anchor-x": ["left", "center", "right"],
+  "anchor-y": ["top", "center", "bottom"],
+  "direction": ["ltr", "rtl"],
+  "inline-size": ["hug", "fixed"],
+  "wrap": ["word", "grapheme"],
+  "kerning": ["auto", "normal", "none"],
+  "caps": ["normal", "small-caps", "all-small-caps"],
+  "text-transform": ["none", "uppercase", "lowercase", "capitalize"],
+  "atom-reveal": ["all", "on-start", "typewriter"],
+  "karaoke": ["off", "current", "trail"],
+  "karaoke-transition": ["step", "wipe"],
+  "underline": ["off", "always"],
+  "active-underline": ["off", "current", "trail"],
+  "active-box": ["off", "current", "trail"],
+  "active-box-continuity": ["isolated", "joined"],
+  "loop": ["none", "shake", "wobble", "glow-pulse", "breathe", "float", "pulse", "flicker"],
+  "loop-target": ["cue", "active-atom"],
+  "cue-enter": fineCaptionOneShotMotions,
+  "cue-exit": fineCaptionOneShotMotions,
+  "atom-enter": fineCaptionOneShotMotions,
+  "atom-exit": fineCaptionOneShotMotions,
+  "active-box-enter": fineCaptionOneShotMotions,
+  "active-box-exit": fineCaptionOneShotMotions,
+  "active-response": fineCaptionOneShotMotions,
+};
+
+export const fineCaptionRequiredRecipeProperties = [
+  "align", "background", "fill",
+  "line-height", "padding", "radius", "size", "stack-order", "width", "x", "y",
+] as const;
+
+export const fineCaptionOptionalRecipeProperties = [
+  "active-box", "active-box-background", "active-box-border-color", "active-box-border-width",
+  "active-box-continuity", "active-box-enter", "active-box-exit", "active-box-padding", "active-box-radius",
+  "active-box-transition-frames", "active-fill", "active-glow-blur", "active-glow-color", "active-glow-opacity",
+  "active-glow-spread",
+  "active-gradient-angle", "active-gradient-from", "active-gradient-to", "active-long-shadow-angle",
+  "active-long-shadow-color", "active-long-shadow-distance", "active-long-shadow-opacity", "active-opacity",
+  "active-response", "active-response-frames", "active-scale", "active-shadow-blur", "active-shadow-color", "active-shadow-opacity",
+  "active-shadow-spread", "active-shadow-x", "active-shadow-y", "active-stroke-color", "active-stroke-width", "active-underline",
+  "active-underline-color", "active-underline-offset", "active-underline-thickness", "anchor-x", "anchor-y",
+  "atom-enter", "atom-enter-frames", "atom-exit", "atom-exit-frames", "atom-reveal", "block-align", "border-color", "border-width", "caps", "cue-enter",
+  "cue-shadow-blur", "cue-shadow-color", "cue-shadow-opacity", "cue-shadow-spread", "cue-shadow-x", "cue-shadow-y",
+  "cue-enter-frames", "cue-enter-start-scale", "cue-exit", "cue-exit-frames", "direction", "glow-blur", "glow-color",
+  "glow-opacity", "glow-spread", "gradient-angle", "gradient-from", "gradient-to", "height", "inline-size", "karaoke", "karaoke-transition", "kerning",
+  "handoff", "lead-frames", "letter-spacing", "long-shadow-angle", "long-shadow-color", "long-shadow-distance", "long-shadow-opacity",
+  "loop", "loop-intensity", "loop-period-frames", "loop-target", "max-lines", "max-words-per-line", "opacity", "shadow-blur", "shadow-color",
+  "shadow-opacity", "shadow-spread", "shadow-x", "shadow-y", "slide-distance", "stroke-color", "stroke-width", "text-transform",
+  "tail-frames", "underline", "underline-color", "underline-offset", "underline-thickness", "word-gap", "wrap",
+] as const;
+
+function schemaFor(name: string): ValueSchema {
+  if (colors.has(name)) return { kind: "string" };
+  if (unitFractions.has(name)) return { kind: "number", minimum: 0, maximum: 1 };
+  if (integers.has(name)) return { kind: "number", integer: true };
+  if (numbers.has(name)) return { kind: "number" };
+  if (strings.has(name)) return { kind: "string" };
+  const values = enums[name];
+  if (values !== undefined) return { kind: "string", enum: values };
+  throw new Error(`Fine Caption Recipe property ${name} has no declared value shape`);
+}
+
+const required = new Set<string>(fineCaptionRequiredRecipeProperties);
+const properties = [...fineCaptionRequiredRecipeProperties, ...fineCaptionOptionalRecipeProperties];
+
+/** Public author contract for the exact properties accepted by a Fine Caption SVS Recipe. */
+export const fineCaptionRecipeSchema: ValueSchema = {
+  kind: "object",
+  fields: Object.fromEntries(properties.map((name) => [
+    name,
+    required.has(name) ? { schema: schemaFor(name) } : { schema: schemaFor(name), optional: true },
+  ])),
+};