@hypit/hypit 0.0.1 → 0.1.0

package/packages/ranking-studio/src/index.ts

@@ -0,0 +1,255 @@
+import { rankingMarkupSurfaces, rankingModuleRef, rankingTypes } from "@hypit/ranking";
+import type { RankingProgram, RankingSchedule } from "@hypit/ranking";
+import { compositionTypes } from "@hypit/composition";
+import type { StudioTrackCompanion, StudioTrackCompanionContext, StudioEntityDraft, StudioInspectorFieldDeclaration, StudioSourceBindingDeclaration } from "@hypit/studio-adapter";
+import { artifactPreview, authoredChildFor, previewLayer, requiredSurfaceValue, temporalLineageFor, temporalSemanticSource } from "@hypit/studio-adapter";
+
+const frameParameters: readonly StudioSourceBindingDeclaration[] = [
+  { name: "within" },
+  ...["left", "top", "right", "bottom", "x", "y", "width", "height"].map((name) => ({ name, writable: true })),
+];
+
+function rankingProperties(surface: "column-style" | "tier-style" | "top-three-style") {
+  return rankingMarkupSurfaces.find((candidate) => candidate.name === surface)
+    ?.vocabulary.attributes.find((attribute) => attribute.name === "recipe")?.recipe ?? [];
+}
+
+function title(name: string): string {
+  return name.split("-").map((part) => `${part.slice(0, 1).toUpperCase()}${part.slice(1)}`).join(" ");
+}
+
+type RankingInspectorPlacement = Pick<StudioInspectorFieldDeclaration, "domain" | "page" | "section">;
+
+function place(domain: "where" | "how" | "when", page: string, section: string): RankingInspectorPlacement {
+  return {
+    domain,
+    page: { id: page.toLowerCase().replaceAll(" ", "-"), label: page },
+    section: { id: section.toLowerCase().replaceAll(" ", "-"), label: section },
+  };
+}
+
+const rankingInspectorPlacement = {
+  rows: place("how", "Board", "Tier Rows"),
+  "rank-colors": place("how", "Board", "Rank Badges"),
+  "slot-colors": place("how", "Board", "Podium Slots"),
+  "font-size": place("how", "Text", "Typography"),
+  "font-weight": place("how", "Text", "Typography"),
+  "text-color": place("how", "Text", "Typography"),
+  "label-text-color": place("how", "Labels", "Typography"),
+  "label-size": place("how", "Labels", "Typography"),
+  "line-height": place("how", "Text", "Typography"),
+  "board-background": place("how", "Board", "Board Paint"),
+  "board-border-color": place("how", "Board", "Board Paint"),
+  "board-border-width": place("how", "Board", "Board Paint"),
+  "board-radius": place("how", "Board", "Board Paint"),
+  "board-shadow-x": place("how", "Board", "Board Shadow"),
+  "board-shadow-y": place("how", "Board", "Board Shadow"),
+  "board-shadow-blur": place("how", "Board", "Board Shadow"),
+  "board-shadow-spread": place("how", "Board", "Board Shadow"),
+  "board-shadow-color": place("how", "Board", "Board Shadow"),
+  "appear-frames": place("when", "Motion", "Entrance"),
+  "move-frames": place("when", "Motion", "Movement"),
+  "motion-easing": place("when", "Motion", "Movement"),
+  "label-width": place("where", "Layout", "Rows"),
+  padding: place("where", "Layout", "Board"),
+  "row-height": place("where", "Layout", "Rows"),
+  "row-gap": place("where", "Layout", "Rows"),
+  "cell-gap": place("where", "Layout", "Rows"),
+  "icon-size": place("where", "Layout", "Items"),
+  "icon-radius": place("how", "Board", "Items"),
+  "icon-radius-ratio": place("how", "Board", "Items"),
+  "icon-fit": place("how", "Board", "Items"),
+  "stage-x": place("where", "Stage", "Position"),
+  "stage-y": place("where", "Stage", "Position"),
+  "stage-size": place("where", "Stage", "Size"),
+  "center-x": place("where", "Layout", "Podium"),
+  "baseline-y": place("where", "Layout", "Podium"),
+  "slot-gap": place("where", "Layout", "Podium"),
+  "ring-width": place("how", "Board", "Podium Slots"),
+  "label-gap": place("where", "Layout", "Podium"),
+  "board-stack": place("where", "Stacking", "Layers"),
+  "stage-stack": place("where", "Stacking", "Layers"),
+  "item-stack": place("where", "Stacking", "Layers"),
+  "appear-gain": place("how", "Sound", "Levels"),
+  "move-gain": place("how", "Sound", "Levels"),
+  "sound-fade-frames": place("when", "Sound", "Envelope"),
+} as const satisfies Readonly<Record<string, RankingInspectorPlacement>>;
+
+function rankingInspector(surface: "column-style" | "tier-style" | "top-three-style"): readonly StudioInspectorFieldDeclaration[] {
+  return rankingProperties(surface).map((property) => {
+    const placement = rankingInspectorPlacement[property.name as keyof typeof rankingInspectorPlacement];
+    if (placement === undefined) throw new Error(`Ranking Studio has no explicit placement for ${property.name}.`);
+    return {
+      binding: `style.${property.name}`,
+      label: title(property.name),
+      ...placement,
+      ...(property.summary === undefined ? {} : { summary: property.summary }),
+    };
+  });
+}
+
+function rankingStyle(surface: "column-style" | "tier-style" | "top-three-style"): StudioSourceBindingDeclaration {
+  return {
+    name: "style",
+    recipe: { through: ["recipe"], bindings: rankingProperties(surface).map(({ name, schema, fallback }) => ({
+      name,
+      schema,
+      ...(fallback === undefined ? {} : { fallback }),
+    })) },
+  };
+}
+
+function projectRanking(context: StudioTrackCompanionContext): readonly StudioEntityDraft[] {
+  const placement = context.placement;
+  const schedule = requiredSurfaceValue(context, "schedule") as RankingSchedule;
+  const program = requiredSurfaceValue(context, "program") as RankingProgram;
+  if (placement === undefined) return context.generic();
+  const boardId = placement.id ?? context.track.outputRef;
+  const outerTemporal = temporalLineageFor(context, boardId, "outer");
+  const outerSemanticSource = temporalSemanticSource(outerTemporal);
+  const group: StudioEntityDraft = {
+    id: `${context.track.outputRef}:entity:${boardId}`,
+    authoredId: boardId,
+    ...(outerSemanticSource?.id === undefined ? {} : { markerId: outerSemanticSource.id }),
+    display: { title: boardId, layers: [] },
+    startFrame: schedule.outer.startFrame,
+    endFrameExclusive: schedule.outer.endFrameExclusive,
+    stackOrder: Math.max(...context.spans.map((span) => span.stackOrder), 0),
+    elementRange: placement.range,
+    renderIds: context.spans.map((span) => span.id),
+    presentation: { entity: "ranking", chrome: "group" },
+    ...(outerTemporal === undefined ? {} : { temporal: outerTemporal }),
+  };
+  const programItems = new Map(program?.items.map((item) => [item.id, item] as const) ?? []);
+  const reveals = schedule.entries.flatMap((entry): readonly StudioEntityDraft[] => {
+    if ("mode" in entry && entry.mode !== "reveal") return [];
+    const child = authoredChildFor(context, entry.itemId, [rankingTypes.itemSpec, rankingTypes.textItemShell]);
+    const item = programItems.get(entry.itemId);
+    const temporal = temporalLineageFor(context, entry.itemId, "mode" in entry ? "window" : "activation");
+    const semanticSource = temporalSemanticSource(temporal);
+    const visible = "mode" in entry ? entry.window : entry.cumulative;
+    const icon = item?.icon;
+    const label = item !== undefined && "label" in item ? item.label : child?.attributes.label ?? entry.itemId;
+    return [{
+      id: `${context.track.outputRef}:entity:${entry.itemId}`,
+      authoredId: entry.itemId,
+      ...(semanticSource?.id === undefined ? {} : { markerId: semanticSource.id }),
+      display: {
+        title: label,
+        layers: icon === undefined ? [] : [previewLayer(artifactPreview("image", icon.resource), "repeat-x")],
+      },
+      startFrame: visible.startFrame,
+      endFrameExclusive: visible.endFrameExclusive,
+      stackOrder: group.stackOrder + 1,
+      ...(child === undefined ? {} : { elementRange: child.range }),
+      lane: "mode" in entry ? "reveal" : "activation",
+      presentation: { entity: "ranking-reveal", chrome: "standard" },
+      ...(temporal === undefined ? {} : { temporal }),
+    }];
+  }).sort((left, right) => left.startFrame - right.startFrame || left.id.localeCompare(right.id));
+  return [group, ...reveals];
+}
+
+const commonBindings: readonly StudioSourceBindingDeclaration[] = [
+  { name: "frame", referenced: frameParameters },
+  { name: "appear-sound" },
+  { name: "move-sound" },
+];
+
+const frameInspector: readonly StudioInspectorFieldDeclaration[] = frameParameters
+  .filter(({ writable }) => writable === true)
+  .map(({ name }) => ({
+    binding: `frame.${name}`, label: title(name), domain: "where",
+    page: { id: "frame", label: "Frame" }, section: { id: "frame", label: "Frame" }, control: "text",
+  }));
+
+export const rankingStudioTrackCompanions: readonly StudioTrackCompanion[] = [
+  {
+    id: "column", role: "track",
+    output: { type: compositionTypes.visualTrack, surface: "column", modules: [rankingModuleRef] },
+    family: "ranking", tone: "orange", label: "Ranking", icon: "ranking", requiredValues: ["schedule", "program"],
+    bindings: [
+      ...commonBindings,
+      rankingStyle("column-style"),
+    ],
+    inspector: [...frameInspector, ...rankingInspector("column-style")],
+    poster: { source: "surface-preview" },
+    lane: {
+      heightPx: 80, groupId: "ranking-reveals",
+    },
+    attachments: [{
+      id: "reveal", family: "ranking-reveal", tone: "orange-muted", label: "Reveals", icon: "ranking", facet: "visual",
+      lane: { heightPx: 40 },
+      bindings: [
+        { name: "label", writable: true },
+        { name: "icon" },
+        { name: "rank", writable: true },
+        { name: "stack", writable: true },
+      ],
+      inspector: [
+        { binding: "label", label: "Label", domain: "how", page: { id: "item", label: "Item" }, section: { id: "item", label: "Item" }, control: "text" },
+        { binding: "rank", label: "Rank", domain: "how", page: { id: "item", label: "Item" }, section: { id: "item", label: "Item" }, control: "number" },
+        { binding: "stack", label: "Stack", domain: "where", page: { id: "stacking", label: "Stacking" }, section: { id: "stacking", label: "Stacking" }, control: "number" },
+      ],
+    }],
+    project: projectRanking,
+  },
+  {
+    id: "tier", role: "track",
+    output: { type: compositionTypes.visualTrack, surface: "tier", modules: [rankingModuleRef] },
+    family: "ranking", tone: "orange", label: "Tier Board", icon: "ranking", requiredValues: ["schedule", "program"],
+    bindings: [
+      ...commonBindings,
+      rankingStyle("tier-style"),
+    ],
+    inspector: [
+      ...frameInspector,
+      ...rankingInspector("tier-style"),
+    ],
+    poster: { source: "surface-preview" },
+    lane: { heightPx: 80, groupId: "tier-reveals" },
+    attachments: [{
+      id: "reveal", family: "ranking-reveal", tone: "orange-muted", label: "Reveals", icon: "ranking", facet: "visual",
+      lane: { heightPx: 40 },
+      bindings: [
+        { name: "tier", writable: true },
+        { name: "entry", writable: true },
+        { name: "icon" },
+        { name: "stack", writable: true },
+      ],
+      inspector: [
+        { binding: "tier", label: "Tier", domain: "how", page: { id: "item", label: "Item" }, section: { id: "item", label: "Item" }, control: "text" },
+        { binding: "entry", label: "Entry", domain: "when", page: { id: "entrance", label: "Entrance" }, section: { id: "entrance", label: "Entrance" }, control: "select", options: ["direct", "drop"] },
+        { binding: "stack", label: "Stack", domain: "where", page: { id: "stacking", label: "Stacking" }, section: { id: "stacking", label: "Stacking" }, control: "number" },
+      ],
+    }],
+    project: projectRanking,
+  },
+  {
+    id: "top-three", role: "track",
+    output: { type: compositionTypes.visualTrack, surface: "top-three", modules: [rankingModuleRef] },
+    family: "ranking", tone: "orange", label: "Top Three", icon: "ranking", requiredValues: ["schedule", "program"],
+    bindings: [
+      ...commonBindings,
+      rankingStyle("top-three-style"),
+      { name: "terminal" },
+    ],
+    inspector: [...frameInspector, ...rankingInspector("top-three-style")],
+    poster: { source: "surface-preview" },
+    lane: { heightPx: 80, groupId: "top-three-activations" },
+    attachments: [{
+      id: "activation", family: "ranking-reveal", tone: "orange-muted", label: "Activations", icon: "ranking", facet: "visual",
+      lane: { heightPx: 40 },
+      bindings: [
+        { name: "label", writable: true },
+        { name: "icon" },
+        { name: "stack", writable: true },
+      ],
+      inspector: [
+        { binding: "label", label: "Label", domain: "how", page: { id: "item", label: "Item" }, section: { id: "item", label: "Item" }, control: "text" },
+        { binding: "stack", label: "Stack", domain: "where", page: { id: "stacking", label: "Stacking" }, section: { id: "stacking", label: "Stacking" }, control: "number" },
+      ],
+    }],
+    project: projectRanking,
+  },
+];

package/packages/raster/README.md

@@ -0,0 +1,7 @@
+# @hypit/raster
+
+The closed deterministic raster-execution waist. It owns one `execute-raster` capability and a
+finite `RasterRequest` union. Author packages such as Image Transform and Image Compose lower their
+different author meanings into this contract; Providers implement the pixel engine once.
+
+Raster contains no author Surface, queue, filesystem, OpenCV or remote placement policy.

package/packages/raster/package.json

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

package/packages/raster/src/activation.ts

@@ -0,0 +1,7 @@
+import { rasterManifest } from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: rasterManifest }],
+};
+export default hypitPackage;

package/packages/raster/src/index.ts

@@ -0,0 +1,7 @@
+export { rasterCapabilities, rasterDependency, rasterManifest, rasterModuleRef } from "./manifest.js";
+export { rasterTransformOperationSchema } from "./schema.js";
+export {
+  assertRasterRequest, assertRasterTransformOperations, rasterComposeRequest,
+  rasterOutputMediaType, rasterSources, rasterTransformRequest,
+} from "./program.js";
+export type * from "./types.js";

package/packages/raster/src/manifest.ts

@@ -0,0 +1,14 @@
+import { artifactDependency, artifactTypes } from "@hypit/artifact";
+import type { CapabilityRef, ModuleManifest } from "@hypit/protocol";
+
+export const rasterModuleRef = { name: "@hypit/raster", version: "1" } as const;
+export const rasterCapabilities = {
+  execute: { module: rasterModuleRef, name: "execute-raster" },
+} satisfies Record<string, CapabilityRef>;
+export const rasterManifest: ModuleManifest = {
+  format: "hypit.module@1", name: rasterModuleRef.name, version: rasterModuleRef.version,
+  dependencies: [artifactDependency], types: [],
+  capabilities: [{ name: rasterCapabilities.execute.name, returns: artifactTypes.blob }],
+  producers: [],
+};
+export const rasterDependency = { module: rasterModuleRef } as const;

package/packages/raster/src/program.ts

@@ -0,0 +1,128 @@
+import { canonicalize, isResourceId } from "@hypit/protocol";
+import { assertCanvasSpace, assertSpatialFrame } from "@hypit/spatial";
+
+import type {
+  RasterComposeRequest, RasterEncodeOperation, RasterLayer, RasterRequest,
+  RasterTransformOperation, RasterTransformRequest,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }
+function finite(value: number, minimum: number, maximum: number, subject: string): void {
+  assert(Number.isFinite(value) && value >= minimum && value <= maximum,
+    `${subject} must be between ${minimum} and ${maximum}`);
+}
+function positiveInteger(value: number, maximum: number, subject: string): void {
+  assert(Number.isSafeInteger(value) && value > 0 && value <= maximum,
+    `${subject} must be a positive integer no greater than ${maximum}`);
+}
+function color(value: string | undefined, subject: string, alpha = true): void {
+  if (value === undefined) return;
+  const pattern = alpha ? /^#[0-9a-f]{6}(?:[0-9a-f]{2})?$/iu : /^#[0-9a-f]{8}$/iu;
+  assert(pattern.test(value), `${subject} must be ${alpha ? "#RRGGBB or #RRGGBBAA" : "#RRGGBBAA"}`);
+}
+function image(value: RasterLayer["source"], subject: string): void {
+  assert(value.kind === "blob" && isResourceId(value.resource) && Number.isSafeInteger(value.size)
+    && value.size >= 0 && value.mediaType.startsWith("image/"), `${subject} must be an image Blob Artifact`);
+}
+
+function assertTransformOperation(operation: RasterTransformOperation, index: number): void {
+  const subject = `Raster transform operation ${index + 1}`;
+  switch (operation.kind) {
+    case "crop":
+      if (operation.unit === "fraction") {
+        finite(operation.x, 0, 1, `${subject}.x`); finite(operation.y, 0, 1, `${subject}.y`);
+        finite(operation.width, Number.EPSILON, 1, `${subject}.width`);
+        finite(operation.height, Number.EPSILON, 1, `${subject}.height`);
+        assert(operation.x + operation.width <= 1 + 1e-9 && operation.y + operation.height <= 1 + 1e-9,
+          `${subject} lies outside the source image`);
+      } else {
+        assert(operation.unit === "pixel", `${subject}.unit is invalid`);
+        assert(Number.isSafeInteger(operation.x) && operation.x >= 0 && Number.isSafeInteger(operation.y) && operation.y >= 0,
+          `${subject} pixel origin is invalid`);
+        positiveInteger(operation.width, 65_535, `${subject}.width`);
+        positiveInteger(operation.height, 65_535, `${subject}.height`);
+      }
+      return;
+    case "resize":
+      positiveInteger(operation.width, 16_384, `${subject}.width`);
+      positiveInteger(operation.height, 16_384, `${subject}.height`);
+      assert(["contain", "cover", "stretch"].includes(operation.fit), `${subject}.fit is invalid`);
+      assert(["nearest", "linear", "cubic", "area", "lanczos"].includes(operation.interpolation), `${subject}.interpolation is invalid`);
+      color(operation.background, `${subject}.background`); return;
+    case "rotate": assert([90, 180, 270].includes(operation.degrees), `${subject}.degrees is invalid`); return;
+    case "flip": assert(["horizontal", "vertical", "both"].includes(operation.axis), `${subject}.axis is invalid`); return;
+    case "denoise":
+      assert(operation.method === "nlm-ycrcb", `${subject}.method is invalid`);
+      finite(operation.lumaStrength, 0, 50, `${subject}.lumaStrength`);
+      finite(operation.chromaStrength, 0, 50, `${subject}.chromaStrength`);
+      positiveInteger(operation.templateWindow, 31, `${subject}.templateWindow`);
+      positiveInteger(operation.searchWindow, 63, `${subject}.searchWindow`);
+      assert(operation.templateWindow % 2 === 1 && operation.searchWindow % 2 === 1
+        && operation.searchWindow > operation.templateWindow, `${subject} NLM windows are invalid`);
+      finite(operation.saturationRecovery, 0, 4, `${subject}.saturationRecovery`); return;
+    case "color":
+      finite(operation.exposureStops, -8, 8, `${subject}.exposureStops`);
+      finite(operation.contrast, 0, 4, `${subject}.contrast`); finite(operation.saturation, 0, 4, `${subject}.saturation`);
+      finite(operation.temperature, -1, 1, `${subject}.temperature`); finite(operation.tint, -1, 1, `${subject}.tint`);
+      finite(operation.gamma, 0.1, 10, `${subject}.gamma`); return;
+    case "sharpen":
+      finite(operation.amount, 0, 5, `${subject}.amount`); finite(operation.radius, 0.1, 20, `${subject}.radius`);
+      finite(operation.threshold, 0, 255, `${subject}.threshold`); return;
+    case "blur": finite(operation.sigma, 0.1, 100, `${subject}.sigma`); return;
+    case "alpha":
+      assert(operation.mode === "preserve" || operation.mode === "flatten", `${subject}.mode is invalid`);
+      color(operation.background, `${subject}.background`);
+      assert(operation.mode !== "flatten" || operation.background !== undefined, `${subject}.background is required`);
+      assert(operation.mode !== "preserve" || operation.background === undefined, `${subject}.background is unused`); return;
+    case "encode":
+      assert(["png", "jpeg", "webp"].includes(operation.format), `${subject}.format is invalid`);
+      if (operation.quality !== undefined) finite(operation.quality, 1, 100, `${subject}.quality`);
+      assert(operation.format !== "png" || operation.quality === undefined, `${subject}.quality is not defined for PNG`);
+      color(operation.background, `${subject}.background`);
+      assert(operation.format === "jpeg" || operation.background === undefined, `${subject}.background is only defined for JPEG`); return;
+  }
+}
+
+export function assertRasterTransformOperations(operations: readonly RasterTransformOperation[]): void {
+  assert(Array.isArray(operations) && operations.length > 0, "Raster transform requires at least one operation");
+  operations.forEach(assertTransformOperation);
+  const encodes = operations.filter((operation) => operation.kind === "encode");
+  assert(encodes.length <= 1, "Raster transform may encode only once");
+  assert(encodes.length === 0 || operations.at(-1)?.kind === "encode", "Raster encode must be final");
+}
+
+export function assertRasterRequest(value: RasterRequest): void {
+  if (value.kind === "transform") {
+    image(value.source, "Raster transform source");
+    assertRasterTransformOperations(value.operations);
+    return;
+  }
+  assert(value.kind === "compose", "RasterRequest.kind is invalid");
+  assertCanvasSpace(value.canvas); color(value.background, "Raster compose background", false);
+  assert(value.layers.length > 0 && value.layers.length <= 64, "Raster compose requires one to 64 Layers");
+  value.layers.forEach((layer, index) => {
+    image(layer.source, `Raster Layer ${index + 1}.source`); assertSpatialFrame(layer.frame);
+    assert(["contain", "cover", "stretch"].includes(layer.fit), `Raster Layer ${index + 1}.fit is invalid`);
+    assert(["nearest", "linear", "cubic", "area", "lanczos"].includes(layer.interpolation),
+      `Raster Layer ${index + 1}.interpolation is invalid`);
+    finite(layer.opacity, 0, 1, `Raster Layer ${index + 1}.opacity`);
+  });
+}
+
+export function rasterTransformRequest(source: RasterTransformRequest["source"], operations: readonly RasterTransformOperation[]): RasterTransformRequest {
+  const request = canonicalize({ kind: "transform", source, operations }) as unknown as RasterTransformRequest;
+  assertRasterRequest(request); return request;
+}
+export function rasterComposeRequest(value: Omit<RasterComposeRequest, "kind">): RasterComposeRequest {
+  const request = canonicalize({ kind: "compose", ...value }) as unknown as RasterComposeRequest;
+  assertRasterRequest(request); return request;
+}
+export function rasterSources(request: RasterRequest): readonly RasterLayer["source"][] {
+  assertRasterRequest(request); return request.kind === "transform" ? [request.source] : request.layers.map((layer) => layer.source);
+}
+export function rasterOutputMediaType(request: RasterRequest): string {
+  assertRasterRequest(request);
+  if (request.kind === "compose") return "image/png";
+  const encode = request.operations.find((operation): operation is RasterEncodeOperation => operation.kind === "encode");
+  return encode?.format === "jpeg" ? "image/jpeg" : encode?.format === "webp" ? "image/webp" : "image/png";
+}

package/packages/raster/src/schema.ts

@@ -0,0 +1,53 @@
+import type { ValueSchema } from "@hypit/protocol";
+
+const number = (minimum?: number, maximum?: number): ValueSchema => ({
+  kind: "number", ...(minimum === undefined ? {} : { minimum }), ...(maximum === undefined ? {} : { maximum }),
+});
+const integer = (minimum: number, maximum: number): ValueSchema => ({ kind: "number", integer: true, minimum, maximum });
+const stringEnum = (values: readonly string[]): ValueSchema => ({ kind: "string", enum: values });
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+const color: ValueSchema = { kind: "string", minLength: 7, maxLength: 9 };
+
+/** Declarative mirror of the closed transform vocabulary, shared by every author Surface. */
+export const rasterTransformOperationSchema: ValueSchema = {
+  kind: "oneOf",
+  variants: [
+    object({
+      kind: { schema: { kind: "literal", value: "crop" } }, unit: { schema: stringEnum(["fraction", "pixel"]) },
+      x: { schema: number(0) }, y: { schema: number(0) }, width: { schema: number(Number.EPSILON) }, height: { schema: number(Number.EPSILON) },
+    }),
+    object({
+      kind: { schema: { kind: "literal", value: "resize" } }, width: { schema: integer(1, 16_384) }, height: { schema: integer(1, 16_384) },
+      fit: { schema: stringEnum(["contain", "cover", "stretch"]) },
+      interpolation: { schema: stringEnum(["nearest", "linear", "cubic", "area", "lanczos"]) },
+      background: { schema: color, optional: true },
+    }),
+    object({ kind: { schema: { kind: "literal", value: "rotate" } }, degrees: { schema: { kind: "oneOf", variants: [
+      { kind: "literal", value: 90 }, { kind: "literal", value: 180 }, { kind: "literal", value: 270 },
+    ] } } }),
+    object({ kind: { schema: { kind: "literal", value: "flip" } }, axis: { schema: stringEnum(["horizontal", "vertical", "both"]) } }),
+    object({
+      kind: { schema: { kind: "literal", value: "denoise" } }, method: { schema: { kind: "literal", value: "nlm-ycrcb" } },
+      lumaStrength: { schema: number(0, 50) }, chromaStrength: { schema: number(0, 50) },
+      templateWindow: { schema: integer(1, 31) }, searchWindow: { schema: integer(1, 63) }, saturationRecovery: { schema: number(0, 4) },
+    }),
+    object({
+      kind: { schema: { kind: "literal", value: "color" } }, exposureStops: { schema: number(-8, 8) },
+      contrast: { schema: number(0, 4) }, saturation: { schema: number(0, 4) }, temperature: { schema: number(-1, 1) },
+      tint: { schema: number(-1, 1) }, gamma: { schema: number(0.1, 10) },
+    }),
+    object({
+      kind: { schema: { kind: "literal", value: "sharpen" } }, amount: { schema: number(0, 5) },
+      radius: { schema: number(0.1, 20) }, threshold: { schema: number(0, 255) },
+    }),
+    object({ kind: { schema: { kind: "literal", value: "blur" } }, sigma: { schema: number(0.1, 100) } }),
+    object({
+      kind: { schema: { kind: "literal", value: "alpha" } }, mode: { schema: stringEnum(["preserve", "flatten"]) },
+      background: { schema: color, optional: true },
+    }),
+    object({
+      kind: { schema: { kind: "literal", value: "encode" } }, format: { schema: stringEnum(["png", "jpeg", "webp"]) },
+      quality: { schema: number(1, 100), optional: true }, background: { schema: color, optional: true },
+    }),
+  ],
+};

package/packages/raster/src/types.ts

@@ -0,0 +1,61 @@
+import type { BlobRef } from "@hypit/protocol";
+import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
+
+export type RasterInterpolation = "nearest" | "linear" | "cubic" | "area" | "lanczos";
+export type RasterFit = "contain" | "cover" | "stretch";
+
+export type RasterCropOperation = {
+  readonly kind: "crop"; readonly unit: "fraction" | "pixel";
+  readonly x: number; readonly y: number; readonly width: number; readonly height: number;
+};
+export type RasterResizeOperation = {
+  readonly kind: "resize"; readonly width: number; readonly height: number;
+  readonly fit: RasterFit; readonly interpolation: RasterInterpolation; readonly background?: string;
+};
+export type RasterRotateOperation = { readonly kind: "rotate"; readonly degrees: 90 | 180 | 270 };
+export type RasterFlipOperation = { readonly kind: "flip"; readonly axis: "horizontal" | "vertical" | "both" };
+export type RasterDenoiseOperation = {
+  readonly kind: "denoise"; readonly method: "nlm-ycrcb";
+  readonly lumaStrength: number; readonly chromaStrength: number;
+  readonly templateWindow: number; readonly searchWindow: number; readonly saturationRecovery: number;
+};
+export type RasterColorOperation = {
+  readonly kind: "color"; readonly exposureStops: number; readonly contrast: number;
+  readonly saturation: number; readonly temperature: number; readonly tint: number; readonly gamma: number;
+};
+export type RasterSharpenOperation = {
+  readonly kind: "sharpen"; readonly amount: number; readonly radius: number; readonly threshold: number;
+};
+export type RasterBlurOperation = { readonly kind: "blur"; readonly sigma: number };
+export type RasterAlphaOperation = {
+  readonly kind: "alpha"; readonly mode: "preserve" | "flatten"; readonly background?: string;
+};
+export type RasterEncodeOperation = {
+  readonly kind: "encode"; readonly format: "png" | "jpeg" | "webp";
+  readonly quality?: number; readonly background?: string;
+};
+export type RasterTransformOperation =
+  | RasterCropOperation | RasterResizeOperation | RasterRotateOperation | RasterFlipOperation
+  | RasterDenoiseOperation | RasterColorOperation | RasterSharpenOperation | RasterBlurOperation
+  | RasterAlphaOperation | RasterEncodeOperation;
+
+export type RasterLayer = {
+  readonly source: BlobRef;
+  readonly frame: SpatialFrame;
+  readonly fit: RasterFit;
+  readonly interpolation: RasterInterpolation;
+  readonly opacity: number;
+};
+
+export type RasterTransformRequest = {
+  readonly kind: "transform";
+  readonly source: BlobRef;
+  readonly operations: readonly RasterTransformOperation[];
+};
+export type RasterComposeRequest = {
+  readonly kind: "compose";
+  readonly canvas: CanvasSpace;
+  readonly background: string;
+  readonly layers: readonly RasterLayer[];
+};
+export type RasterRequest = RasterTransformRequest | RasterComposeRequest;

package/packages/render-hyperframes/README.md

@@ -0,0 +1,58 @@
+# `@hypit/render-hyperframes`
+
+The Surface accepts `semantic={speech.semantic}` for performance time or `space={animation}` for an
+authored ProgramSpace. Its Fragment receives `space` directly; rendering does not require Script
+or prepared performance media. Both time sources use the same frame and audio pipeline.
+
+Explicit author and capability boundary for final HyperFrames video rendering.
+
+The package owns `<render:Video composition={...}/>` and lowers it to ordinary Operations that:
+
+1. obtain the `ProgramSpace` from the semantic input and compile the referenced `Composition` into a `HyperframesDocument`;
+2. request a silent, frame-exact `RenderedVisual`;
+3. compile every peer `AudioTrack` into one `AudioProgramPlan`;
+4. request an exact 48 kHz `TimelineAudio`;
+5. request one `MuxedMedia` from those two independently verified Products;
+6. expose the verified mux Artifact unchanged as a domain-neutral `BlobArtifact`.
+
+The package is not a renderer and contains no queue, credentials or deployment choice. A local
+HyperFrames process, a hosted endpoint or another conforming execution package may register a
+Provider for the exact visual capability. Media Providers independently realize audio rendering and
+mux. None parses SVML or decides which Composition to render. Every result is bound to the same
+ProgramSpace and exact frame/sample domain before it can become a final video Record.
+
+The output does not carry copied duration or lineage metadata. It is an ordinary Resource-backed
+Blob and can therefore be connected directly to any later component that accepts Blob bytes. A
+consumer that needs stream or duration facts must request explicit media inspection.
+
+Core therefore sees three real byte-operation Needs, not one opaque mega-render. Frame workers,
+contiguous or interleaved chunks, retries and image-sequence assembly remain inside the selected
+visual Endpoint; clip decoding/mixing remains inside the audio Endpoint; container encoding remains
+inside the mux Endpoint. A single Provider package may implement all three locally, or a Runtime may
+bind them to separate Lambda-backed Endpoints. The author still sees one `<render:Video>` result.
+
+Film is not a dependency of this author meaning. Any package that produces the common Composition
+contract can feed the render Surface. Conversely, targeting Composition never demands this package;
+rendering exists only when the author declares and the Build targets the video output.
+
+`@hypit/provider-hyperframes-local` is the first concrete visual implementation. It stages the
+document's exact `BlobRef` dependencies, partitions the requested frame domain across
+configured Chrome workers, emits a silent MP4 and rejects output unless ffprobe proves one H.264
+stream with the declared canvas, rational frame rate and frame count.
+
+Select a contiguous interval using zero-based, half-open frame bounds:
+
+```xml
+<render:Video id="preview" composition={main.composition} semantic={speech.semantic}
+  start-frame="240" end-frame-exclusive="360"/>
+```
+
+At 30 fps this renders seconds 8–12, with 120 output frames. Write both bounds, or omit both to
+render the whole programme. The HTML and animation clock remain unchanged. Visual and audio Needs
+receive the same range; mux consumes their selected outputs. `workers` belongs in the local
+Provider's Runtime configuration.
+
+In TypeScript, `hyperframesVisualRequest(document, { range })` constructs the visual request;
+`createRenderHyperframesFragment(true)` accepts a `MediaFrameRange` input and connects it to visual
+and audio requests. The AWS Lambda Provider currently declines range requests. Selection limits
+final rendering work; it does not prune upstream generation dependencies.

package/packages/render-hyperframes/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@hypit/render-hyperframes",
+  "version": "0.0.0-dev",
+  "license": "SEE LICENSE IN LICENSE",
+  "private": true,
+  "type": "module",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "hypit": {
+    "activation": "./src/activation.ts"
+  },
+  "dependencies": {
+    "@hypit/artifact": "workspace:*",
+    "@hypit/component-kit": "workspace:*",
+    "@hypit/composition": "workspace:*",
+    "@hypit/elaborator": "workspace:*",
+    "@hypit/hyperframes": "workspace:*",
+    "@hypit/media": "workspace:*",
+    "@hypit/media-pipeline": "workspace:*",
+    "@hypit/program-space": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/semantic-track": "workspace:*",
+    "@hypit/markup": "workspace:*",
+    "@hypit/temporal-markup": "workspace:*"
+  },
+  "devDependencies": {
+    "@hypit/core": "workspace:*",
+    "@hypit/driver-node": "workspace:*",
+    "@hypit/svs": "workspace:*",
+    "@hypit/validation": "workspace:*"
+  }
+}