@hypit/hypit 0.0.1 → 0.1.0

package/packages/image-transform/src/component.ts

@@ -0,0 +1,67 @@
+import { plannedNeedInputs } from "@hypit/component-kit";
+import type { ComponentPackage } from "@hypit/component-kit";
+import type { BlobRef, CanonicalValue, StoredValue } from "@hypit/protocol";
+import { canonicalize } from "@hypit/protocol";
+import { rasterTransformRequest } from "@hypit/raster";
+
+import { imageTransformProducers, imageTransformTypes } from "./manifest.js";
+import { rasterCapabilities } from "@hypit/raster";
+import { verifyImageTransformProgram } from "./program.js";
+import type { ImageTransformProgram } from "./types.js";
+
+function inline(value: StoredValue | undefined, subject: string): ImageTransformProgram {
+  if (value?.kind !== "inline") throw new Error(`${subject} must be inline`);
+  return value.value as unknown as ImageTransformProgram;
+}
+
+function blob(value: StoredValue | undefined, subject: string): BlobRef {
+  if (value?.kind !== "blob") throw new Error(`${subject} must be a BlobArtifact`);
+  if (!value.mediaType.startsWith("image/")) throw new Error(`${subject} must be image media`);
+  return value;
+}
+
+export const imageTransformComponent = {
+  validators: [{
+    type: imageTransformTypes.program,
+    handler: ({ value }) => {
+      verifyImageTransformProgram(inline(value, "ImageTransformProgram"));
+    },
+  }],
+  producers: [{
+    producer: imageTransformProducers.request,
+    handler: ({ inputs }) => {
+      const source = blob(inputs.source?.value, "ImageTransform source");
+      const program = inline(inputs.program?.value, "ImageTransformProgram");
+      verifyImageTransformProgram(program);
+      return { outputs: {}, needs: { image: canonicalize(rasterTransformRequest(source, program.operations)) } };
+    },
+  }],
+  plannedNeeds: [{
+    producer: imageTransformProducers.request,
+    port: "image",
+    capability: rasterCapabilities.execute,
+    plan({ state, step }) {
+      const operation = state.plan.steps.find((item) => item.id === step);
+      const programRecord = operation?.inputs.program;
+      const program = programRecord === undefined
+        ? undefined
+        : state.records.find((record) => record.id === programRecord)?.value;
+      if (program?.kind !== "inline") return undefined;
+      return {
+        constraints: { kind: "transform", program: program.value as CanonicalValue },
+        pendingInputs: plannedNeedInputs(state, step, { source: "image" }),
+      };
+    },
+    present(specification) {
+      const fields = specification.constraints as Readonly<Record<string, CanonicalValue>>;
+      const program = fields.program as Readonly<Record<string, CanonicalValue>> | undefined;
+      const operations = Array.isArray(program?.operations) ? program.operations.length : undefined;
+      return {
+        fields: operations === undefined ? {} : { operations: [operations] },
+        references: {
+          image: specification.pendingInputs.filter((input) => input.role === "image").length,
+        },
+      };
+    },
+  }],
+} satisfies ComponentPackage;

package/packages/image-transform/src/fragment.ts

@@ -0,0 +1,25 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGraphFragment } from "@hypit/elaborator";
+
+import { imageTransformProducers, imageTransformTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+export const imageTransformFragment = sealGraphFragment({
+  inputs: [
+    { name: "source", type: artifactTypes.blob },
+    { name: "program", type: imageTransformTypes.program },
+  ],
+  operations: [{
+    id: "image:transform",
+    producer: imageTransformProducers.request,
+    inputs: { source: input("source"), program: input("program") },
+    result: { kind: "need", name: "image" },
+  }],
+  exports: [{
+    name: "image",
+    type: artifactTypes.blob,
+    root: operation("image:transform"),
+  }],
+});

package/packages/image-transform/src/index.ts

@@ -0,0 +1,13 @@
+export { imageTransformComponent } from "./component.js";
+export { imageTransformFragment } from "./fragment.js";
+export { imageTransformManifest, imageTransformMarkupSurfaces, imageTransformModuleRef, imageTransformProducers, imageTransformProgramSchema, imageTransformTypes } from "./manifest.js";
+export {
+  gptImageDenoiseV1,
+  sealImageTransformProgram,
+  verifyImageTransformProgram,
+} from "./program.js";
+export {
+  decodeImageTransformProgramSurface,
+  decodeImageTransformSurface,
+} from "./surface.js";
+export type * from "./types.js";

package/packages/image-transform/src/manifest.ts

@@ -0,0 +1,209 @@
+import { artifactDependency, artifactTypes } from "@hypit/artifact";
+import { rasterCapabilities, rasterDependency, rasterTransformOperationSchema } from "@hypit/raster";
+import type {
+  ModuleManifest,
+  ProducerRef,
+  TypeRef,
+  ValueSchema,
+} from "@hypit/protocol";
+
+export const imageTransformModuleRef = { name: "@hypit/image-transform", version: "1" } as const;
+export const imageTransformTypes = {
+  program: { module: imageTransformModuleRef, name: "ImageTransformProgram" },
+} satisfies Record<string, TypeRef>;
+export const imageTransformProducers = {
+  request: { module: imageTransformModuleRef, name: "request-image-transform" },
+} satisfies Record<string, ProducerRef>;
+
+export const imageTransformProgramSchema: ValueSchema = { kind: "object", fields: {
+  operations: { schema: { kind: "array", minItems: 1, items: rasterTransformOperationSchema } },
+} };
+
+export const imageTransformMarkupSurfaces = [{
+    name: "program",
+    tag: "Program",
+    mode: "structured",
+    outputs: [imageTransformTypes.program],
+    vocabulary: {
+      summary:
+        "Names an ordered list of raster operations and publishes it as a reusable ImageTransformProgram Record.",
+      attributes: [
+        { name: "id", kind: "identifier", required: true,
+          summary: "Names the ImageTransformProgram Record this element publishes." },
+      ],
+      children: [
+        { tag: "Crop", cardinality: "many",
+          summary: "Cuts a rectangle out of the image, measured in fractions of the frame or in pixels.",
+          attributes: [
+            { name: "unit", kind: "literal", required: false, values: ["fraction", "pixel"],
+              summary: "Decides whether the rectangle is measured in fractions of the frame or in pixels; defaults to `fraction`." },
+            { name: "x", kind: "literal", required: true,
+              summary: "Sets the left edge of the rectangle." },
+            { name: "y", kind: "literal", required: true,
+              summary: "Sets the top edge of the rectangle." },
+            { name: "width", kind: "literal", required: true,
+              summary: "Sets how wide the rectangle is." },
+            { name: "height", kind: "literal", required: true,
+              summary: "Sets how tall the rectangle is." },
+          ] },
+        { tag: "Resize", cardinality: "many",
+          summary: "Scales the image to a pixel width and height under one fit rule.",
+          attributes: [
+            { name: "width", kind: "literal", required: true,
+              summary: "Sets the width in whole pixels the image is scaled to." },
+            { name: "height", kind: "literal", required: true,
+              summary: "Sets the height in whole pixels the image is scaled to." },
+            { name: "fit", kind: "literal", required: false, values: ["contain", "cover", "stretch"],
+              summary: "Decides how the image is sized into that width and height; defaults to `contain`." },
+            { name: "interpolation", kind: "literal", required: false,
+              values: ["nearest", "linear", "cubic", "area", "lanczos"],
+              summary: "Decides which filter resamples the image while it is scaled; defaults to `lanczos`." },
+            { name: "background", kind: "literal", required: false,
+              summary: "Sets the hexadecimal color filling the area `contain` leaves empty." },
+          ] },
+        { tag: "Rotate", cardinality: "many",
+          summary: "Turns the image by 90, 180 or 270 degrees.",
+          attributes: [
+            { name: "degrees", kind: "literal", required: true, values: ["90", "180", "270"],
+              summary: "Sets how far the image is turned clockwise." },
+          ] },
+        { tag: "Flip", cardinality: "many",
+          summary: "Mirrors the image across one axis.",
+          attributes: [
+            { name: "axis", kind: "literal", required: false, values: ["horizontal", "vertical", "both"],
+              summary: "Chooses the axis the image is mirrored across; defaults to `horizontal`." },
+          ] },
+        { tag: "Denoise", cardinality: "many",
+          summary: "Removes noise with YCrCb non-local means and recovers saturation.",
+          attributes: [
+            { name: "method", kind: "literal", required: false, values: ["nlm-ycrcb"],
+              summary: "Names the denoising method; defaults to `nlm-ycrcb`." },
+            { name: "luma", kind: "literal", required: false,
+              summary: "Sets how hard the luma channel is denoised; defaults to 2." },
+            { name: "chroma", kind: "literal", required: false,
+              summary: "Sets how hard the chroma channels are denoised; defaults to 10." },
+            { name: "template-window", kind: "literal", required: false,
+              summary: "Sets the odd pixel width of the patch each pixel is compared as; defaults to 7." },
+            { name: "search-window", kind: "literal", required: false,
+              summary: "Sets the odd pixel width of the area searched for similar patches; defaults to 21." },
+            { name: "saturation-recovery", kind: "literal", required: false,
+              summary: "Sets how much saturation is restored after denoising dulls it; defaults to 1.02." },
+          ] },
+        { tag: "Color", cardinality: "many",
+          summary: "Adjusts exposure, contrast, saturation, temperature, tint and gamma.",
+          attributes: [
+            { name: "exposure-stops", kind: "literal", required: false,
+              summary: "Shifts overall brightness in photographic stops; defaults to 0." },
+            { name: "contrast", kind: "literal", required: false,
+              summary: "Scales the distance of each pixel from mid grey; defaults to 1." },
+            { name: "saturation", kind: "literal", required: false,
+              summary: "Scales color intensity, where 0 is greyscale; defaults to 1." },
+            { name: "temperature", kind: "literal", required: false,
+              summary: "Shifts the image between blue and amber; defaults to 0." },
+            { name: "tint", kind: "literal", required: false,
+              summary: "Shifts the image between green and magenta; defaults to 0." },
+            { name: "gamma", kind: "literal", required: false,
+              summary: "Bends the tone curve between shadows and highlights; defaults to 1." },
+          ] },
+        { tag: "Sharpen", cardinality: "many",
+          summary: "Sharpens edges by an amount over a radius, above a threshold.",
+          attributes: [
+            { name: "amount", kind: "literal", required: false,
+              summary: "Sets how strongly edge contrast is raised; defaults to 0.5." },
+            { name: "radius", kind: "literal", required: false,
+              summary: "Sets how far either side of an edge the sharpening reaches; defaults to 1." },
+            { name: "threshold", kind: "literal", required: false,
+              summary: "Sets the edge contrast below which pixels are left alone; defaults to 0." },
+          ] },
+        { tag: "Blur", cardinality: "many",
+          summary: "Blurs the image by one sigma.",
+          attributes: [
+            { name: "sigma", kind: "literal", required: true,
+              summary: "Sets the radius of the Gaussian blur." },
+          ] },
+        { tag: "Alpha", cardinality: "many",
+          summary: "Keeps the alpha channel or flattens it onto a background color.",
+          attributes: [
+            { name: "mode", kind: "literal", required: false, values: ["preserve", "flatten"],
+              summary: "Decides whether transparency survives or is painted over; defaults to `preserve`." },
+            { name: "background", kind: "literal", required: false,
+              summary: "Sets the hexadecimal color transparency is flattened onto." },
+          ] },
+        { tag: "Encode", cardinality: "optional",
+          summary: "Encodes the result as PNG, JPEG or WebP.",
+          attributes: [
+            { name: "format", kind: "literal", required: false, values: ["png", "jpeg", "webp"],
+              summary: "Chooses the container the result is written as; defaults to `png`." },
+            { name: "quality", kind: "literal", required: false,
+              summary: "Sets the lossy encoding quality from 1 to 100." },
+            { name: "background", kind: "literal", required: false,
+              summary: "Sets the hexadecimal color an opaque format is written over." },
+          ] },
+      ],
+      example: [
+        '<image:Program id="clean-gpt-image">',
+        "  <image:Denoise/>",
+        '  <image:Encode format="png"/>',
+        "</image:Program>",
+      ].join("\n"),
+      notes: [
+        "Operation order is author meaning: the operations run in the order they are written, and a Program requires at least one.",
+        "In `fraction` a `Crop` measures 0 to 1 and must stay inside the source image; in `pixel` its origin and size are whole pixels.",
+        "A `Denoise` needs odd windows, with `search-window` wider than `template-window`, and runs on its defaults alone.",
+        "`Alpha` requires `background` when `mode` is `flatten` and refuses it when `mode` is `preserve`.",
+        "`Encode` may appear only once and must be written last; `quality` is refused by `png`, and `background` is accepted only by `jpeg`.",
+        "The ImageTransformProgram Record is published under the bare `id`, and the element carries no text content.",
+      ],
+    },
+  }, {
+    name: "transform",
+    tag: "Transform",
+    mode: "structured",
+    outputs: [artifactTypes.blob],
+    vocabulary: {
+      summary: "Runs one ImageTransformProgram over a source image Artifact and publishes the transformed image.",
+      attributes: [
+        { name: "id", kind: "identifier", required: true,
+          summary: "Names this transform so its image can be referenced elsewhere in the Source." },
+        { name: "source", kind: "reference", required: true, accepts: [artifactTypes.blob],
+          summary: "Chooses the image the operations are applied to." },
+        { name: "program", kind: "reference", required: true, accepts: [imageTransformTypes.program],
+          summary: "Chooses the ImageTransformProgram whose operations run over the source." },
+      ],
+      ports: [
+        { name: "image", type: artifactTypes.blob,
+          summary: "The transformed image, addressed as `<id>.image`." },
+      ],
+      example: `<image:Transform id="clean-shot" source={shot.image} program={clean-gpt-image}/>`,
+      notes: [
+        "The element is empty; it accepts no children and no text.",
+        "The published image is the transformed image itself, carrying no source digest, Provider name or copied upstream metadata.",
+        "A Program on its own produces no image; naming it here is what runs it.",
+      ],
+    },
+  }] as const;
+
+
+export const imageTransformManifest: ModuleManifest = {
+  format: "hypit.module@1",
+  name: imageTransformModuleRef.name,
+  version: imageTransformModuleRef.version,
+  dependencies: [artifactDependency, rasterDependency],
+  types: [{
+    name: imageTransformTypes.program.name,
+  }],
+  capabilities: [],
+  producers: [{
+    name: imageTransformProducers.request.name,
+    inputs: [
+      { name: "source", type: artifactTypes.blob },
+      { name: "program", type: imageTransformTypes.program },
+    ],
+    outputs: [],
+    needs: [{
+      name: "image",
+      capability: rasterCapabilities.execute,
+      returns: artifactTypes.blob,
+    }],
+  }],
+};

package/packages/image-transform/src/program.ts

@@ -0,0 +1,23 @@
+import { canonicalize } from "@hypit/protocol";
+import { assertRasterTransformOperations } from "@hypit/raster";
+
+import type { ImageTransformProgram } from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition { if (!condition) throw new Error(message); }
+
+export function verifyImageTransformProgram(program: ImageTransformProgram): void {
+  assertRasterTransformOperations(program.operations);
+}
+
+export function sealImageTransformProgram(program: ImageTransformProgram): ImageTransformProgram {
+  const sealed = canonicalize(program) as unknown as ImageTransformProgram;
+  verifyImageTransformProgram(sealed);
+  return sealed;
+}
+
+export const gptImageDenoiseV1 = sealImageTransformProgram({
+  operations: [{
+    kind: "denoise", method: "nlm-ycrcb", lumaStrength: 2, chromaStrength: 10,
+    templateWindow: 7, searchWindow: 21, saturationRecovery: 1.02,
+  }, { kind: "encode", format: "png" }],
+});

package/packages/image-transform/src/surface.ts

@@ -0,0 +1,216 @@
+import { artifactTypes } from "@hypit/artifact";
+import type {
+  StructuredElement,
+  StructuredSurfaceHandler,
+  SurfaceResolvedReference,
+  MarkupAttributeValue,
+} from "@hypit/markup";
+import type { CanonicalValue } from "@hypit/protocol";
+
+import { imageTransformFragment } from "./fragment.js";
+import { imageTransformTypes } from "./manifest.js";
+import { sealImageTransformProgram } from "./program.js";
+import type { ImageTransformOperation } from "./types.js";
+
+function localName(value: string): string {
+  return value.includes(":") ? value.slice(value.lastIndexOf(":") + 1) : value;
+}
+
+function exact(element: StructuredElement, allowed: readonly string[], required: readonly string[] = []): void {
+  const unknown = Object.keys(element.attributes).filter((name) => !allowed.includes(name));
+  if (unknown.length > 0) throw new Error(`${element.name} does not accept ${unknown[0]}`);
+  const missing = required.filter((name) => element.attributes[name] === undefined);
+  if (missing.length > 0) throw new Error(`${element.name} requires ${missing.join(", ")}`);
+}
+
+function text(element: StructuredElement, name: string, fallback?: string): string {
+  const value: MarkupAttributeValue | undefined = element.attributes[name];
+  if (value === undefined && fallback !== undefined) return fallback;
+  if (typeof value !== "string" || value.trim().length === 0) {
+    throw new Error(`${element.name}.${name} must be a non-empty string`);
+  }
+  return value.trim();
+}
+
+function numberValue(element: StructuredElement, name: string, fallback?: number): number {
+  const value = element.attributes[name];
+  if (value === undefined && fallback !== undefined) return fallback;
+  if (typeof value !== "string" || value.trim().length === 0) throw new Error(`${element.name}.${name} must be a number`);
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) throw new Error(`${element.name}.${name} must be a finite number`);
+  return parsed;
+}
+
+function optionalText(element: StructuredElement, name: string): string | undefined {
+  return element.attributes[name] === undefined ? undefined : text(element, name);
+}
+
+function optionalNumber(element: StructuredElement, name: string): number | undefined {
+  return element.attributes[name] === undefined ? undefined : numberValue(element, name);
+}
+
+function oneOf<T extends string>(value: string, values: readonly T[], subject: string): T {
+  if (!values.includes(value as T)) throw new Error(`${subject} must be one of ${values.join(", ")}`);
+  return value as T;
+}
+
+function integer(value: number, subject: string): number {
+  if (!Number.isSafeInteger(value)) throw new Error(`${subject} must be an integer`);
+  return value;
+}
+
+function operation(element: StructuredElement): ImageTransformOperation {
+  switch (localName(element.name)) {
+    case "Crop":
+      exact(element, ["unit", "x", "y", "width", "height"], ["x", "y", "width", "height"]);
+      return {
+        kind: "crop",
+        unit: oneOf(text(element, "unit", "fraction"), ["fraction", "pixel"] as const, `${element.name}.unit`),
+        x: numberValue(element, "x"), y: numberValue(element, "y"),
+        width: numberValue(element, "width"), height: numberValue(element, "height"),
+      };
+    case "Resize":
+      exact(element, ["width", "height", "fit", "interpolation", "background"], ["width", "height"]);
+      return {
+        kind: "resize",
+        width: integer(numberValue(element, "width"), `${element.name}.width`),
+        height: integer(numberValue(element, "height"), `${element.name}.height`),
+        fit: oneOf(text(element, "fit", "contain"), ["contain", "cover", "stretch"] as const, `${element.name}.fit`),
+        interpolation: oneOf(text(element, "interpolation", "lanczos"),
+          ["nearest", "linear", "cubic", "area", "lanczos"] as const, `${element.name}.interpolation`),
+        ...(optionalText(element, "background") === undefined ? {} : { background: text(element, "background") }),
+      };
+    case "Rotate": {
+      exact(element, ["degrees"], ["degrees"]);
+      const degrees = numberValue(element, "degrees");
+      if (degrees !== 90 && degrees !== 180 && degrees !== 270) throw new Error(`${element.name}.degrees must be 90, 180 or 270`);
+      return { kind: "rotate", degrees };
+    }
+    case "Flip":
+      exact(element, ["axis"]);
+      return { kind: "flip", axis: oneOf(text(element, "axis", "horizontal"),
+        ["horizontal", "vertical", "both"] as const, `${element.name}.axis`) };
+    case "Denoise":
+      exact(element, ["method", "luma", "chroma", "template-window", "search-window", "saturation-recovery"]);
+      return {
+        kind: "denoise",
+        method: oneOf(text(element, "method", "nlm-ycrcb"), ["nlm-ycrcb"] as const, `${element.name}.method`),
+        lumaStrength: numberValue(element, "luma", 2),
+        chromaStrength: numberValue(element, "chroma", 10),
+        templateWindow: integer(numberValue(element, "template-window", 7), `${element.name}.template-window`),
+        searchWindow: integer(numberValue(element, "search-window", 21), `${element.name}.search-window`),
+        saturationRecovery: numberValue(element, "saturation-recovery", 1.02),
+      };
+    case "Color":
+      exact(element, ["exposure-stops", "contrast", "saturation", "temperature", "tint", "gamma"]);
+      return {
+        kind: "color",
+        exposureStops: numberValue(element, "exposure-stops", 0),
+        contrast: numberValue(element, "contrast", 1),
+        saturation: numberValue(element, "saturation", 1),
+        temperature: numberValue(element, "temperature", 0),
+        tint: numberValue(element, "tint", 0),
+        gamma: numberValue(element, "gamma", 1),
+      };
+    case "Sharpen":
+      exact(element, ["amount", "radius", "threshold"]);
+      return {
+        kind: "sharpen",
+        amount: numberValue(element, "amount", 0.5),
+        radius: numberValue(element, "radius", 1),
+        threshold: numberValue(element, "threshold", 0),
+      };
+    case "Blur":
+      exact(element, ["sigma"], ["sigma"]);
+      return { kind: "blur", sigma: numberValue(element, "sigma") };
+    case "Alpha": {
+      exact(element, ["mode", "background"]);
+      const background = optionalText(element, "background");
+      return {
+        kind: "alpha",
+        mode: oneOf(text(element, "mode", "preserve"), ["preserve", "flatten"] as const, `${element.name}.mode`),
+        ...(background === undefined ? {} : { background }),
+      };
+    }
+    case "Encode": {
+      exact(element, ["format", "quality", "background"]);
+      const quality = optionalNumber(element, "quality");
+      const background = optionalText(element, "background");
+      return {
+        kind: "encode",
+        format: oneOf(text(element, "format", "png"), ["png", "jpeg", "webp"] as const, `${element.name}.format`),
+        ...(quality === undefined ? {} : { quality }),
+        ...(background === undefined ? {} : { background }),
+      };
+    }
+    default:
+      throw new Error(`${element.name} is not an ImageTransform operation`);
+  }
+}
+
+function sameType(left: SurfaceResolvedReference["type"], right: SurfaceResolvedReference["type"]): boolean {
+  return left.module.name === right.module.name && left.module.version === right.module.version && left.name === right.name;
+}
+
+function ref(
+  element: StructuredElement,
+  name: string,
+  expected: SurfaceResolvedReference["type"],
+  resolve: (path: string) => SurfaceResolvedReference | undefined,
+): SurfaceResolvedReference {
+  const value = element.attributes[name];
+  if (typeof value !== "object" || value.kind !== "reference") throw new Error(`${element.name}.${name} must be a reference`);
+  const resolved = resolve(value.path);
+  if (resolved === undefined || !sameType(resolved.type, expected)) {
+    throw new Error(`${element.name}.${name} cannot resolve the required type`);
+  }
+  return resolved;
+}
+
+function onlyTrivia(element: StructuredElement): void {
+  for (const child of element.children) {
+    if (child.kind === "element" || child.value.trim().length > 0) throw new Error(`${element.name} must be empty`);
+  }
+}
+
+export const decodeImageTransformProgramSurface: StructuredSurfaceHandler = ({ element }) => {
+  exact(element, ["id"], ["id"]);
+  const id = text(element, "id");
+  const operations = element.children.flatMap((child) => {
+    if (child.kind === "text") {
+      if (child.value.trim().length > 0) throw new Error(`${element.name} accepts only operation elements`);
+      return [];
+    }
+    return [operation(child)];
+  });
+  const program = sealImageTransformProgram({ operations });
+  return {
+    records: [{
+      id,
+      type: imageTransformTypes.program,
+      value: { kind: "inline", value: program as unknown as CanonicalValue },
+      range: element.range,
+    }],
+    components: [],
+    fragments: [],
+  };
+};
+
+export const decodeImageTransformSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  exact(element, ["id", "source", "program"], ["id", "source", "program"]);
+  onlyTrivia(element);
+  const id = text(element, "id");
+  const source = ref(element, "source", artifactTypes.blob, resolveReference);
+  const program = ref(element, "program", imageTransformTypes.program, resolveReference);
+  return {
+    records: [],
+    components: [{
+      id,
+      fragment: imageTransformFragment.id,
+      inputs: { source: source.ref, program: program.ref },
+      outputs: { image: `${id}.image` },
+      range: element.range,
+    }],
+    fragments: [imageTransformFragment],
+  };
+};

package/packages/image-transform/src/types.ts

@@ -0,0 +1,20 @@
+import type { RasterTransformOperation } from "@hypit/raster";
+
+export type {
+  RasterAlphaOperation as ImageAlphaOperation,
+  RasterBlurOperation as ImageBlurOperation,
+  RasterColorOperation as ImageColorOperation,
+  RasterCropOperation as ImageCropOperation,
+  RasterDenoiseOperation as ImageDenoiseOperation,
+  RasterEncodeOperation as ImageEncodeOperation,
+  RasterFlipOperation as ImageFlipOperation,
+  RasterResizeOperation as ImageResizeOperation,
+  RasterRotateOperation as ImageRotateOperation,
+  RasterSharpenOperation as ImageSharpenOperation,
+  RasterTransformOperation as ImageTransformOperation,
+} from "@hypit/raster";
+
+/** Authored transformation intent. Operation order is author meaning. */
+export type ImageTransformProgram = {
+  readonly operations: readonly RasterTransformOperation[];
+};

package/packages/interview-emoji-reveal/README.md

@@ -0,0 +1,39 @@
+# Emoji Reveal
+
+The Track Surface accepts `semantic={speech.semantic}` or `space={animation}`. Semantic context
+resolves Script Selections and Moments; authored space supports clock-based animation. Shared `at`
+inputs accept a Moment or a time such as `2s`; `at` with `for` produces a Window where required.
+
+Reusable Hypit author vocabulary for a top-of-frame icon answer strip.
+
+The strip owns one outer projected `TemporalWindow`. An Item is either preset from the first frame or
+accepts one authored Script `Moment`, projected outside this package to a traced `TemporalInstant`.
+Display order is source order: preset Items come first, then revealed Items in strict chronological
+order. The Track receives one placeholder image and every Item receives one answer image: `n` answers
+therefore have exactly `n + 1` explicit image inputs. A Moment replaces only its own slot, so earlier
+answers remain and later slots remain unanswered.
+
+```xml
+<media:Image id="question-icon" src="./icons/rendered/question-mark.png"/>
+<media:Image id="manifest-icon" src="./icons/rendered/sparkles.png"/>
+<media:Image id="real-estate-icon" src="./icons/rendered/building-estate.png"/>
+<media:Image id="bitcoin-icon" src="./icons/rendered/currency-bitcoin.png"/>
+
+<emoji:Style id="emoji-strip" recipe={styles.emoji-strip}/>
+
+<emoji:Track id="rules" semantic={speech.semantic} canvas={vertical}
+  style={emoji-strip} placeholder={question-icon} during="program">
+  <emoji:Item id="manifest" icon={manifest-icon} preset="true"/>
+  <emoji:Item id="real-estate" icon={real-estate-icon} at={story.moment.real-estate}/>
+  <emoji:Item id="bitcoin" icon={bitcoin-icon} at={story.moment.bitcoin}/>
+</emoji:Track>
+```
+
+`Selection`, `Segment`, numeric instants and a `boundary` fallback are deliberately not part of an
+Item's vocabulary. The component consumes only `ProgramSpace`, the projected outer Window and the
+projected Instants; it does not interpret Script semantics itself and has no Studio dependency.
+
+The bundled preview icons come from [Tabler Icons](https://tabler.io/icons), distributed under the
+MIT license and retrieved through the Iconify API. Their SVG files are the design sources and are
+explicitly rasterized to same-size transparent PNGs before video composition. They deliberately share
+one viewBox, stroke width, line-cap treatment and color instead of relying on platform emoji fonts.

package/packages/interview-emoji-reveal/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "@hypit/interview-emoji-reveal",
+  "version": "0.0.0-dev",
+  "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/markup": "workspace:*",
+    "@hypit/narrative": "workspace:*",
+    "@hypit/program-space": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/semantic-track": "workspace:*",
+    "@hypit/spatial": "workspace:*",
+    "@hypit/svs": "workspace:*",
+    "@hypit/temporal": "workspace:*",
+    "@hypit/temporal-markup": "workspace:*"
+  }
+}

package/packages/interview-emoji-reveal/src/activation.ts

@@ -0,0 +1,14 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import { emojiRevealComponent, emojiRevealManifest, emojiRevealMarkupSurfaces, emojiRevealModuleRef } from "./index.js";
+import { decodeEmojiRevealStyleSurface, decodeEmojiRevealTrackSurface } from "./surface.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: emojiRevealManifest }], components: [emojiRevealComponent],
+  hostFacets: [
+    createMarkupSurfaceHostFacet({ module: emojiRevealModuleRef, declaration: emojiRevealMarkupSurfaces.find((item) => item.name === "style")!, handler: decodeEmojiRevealStyleSurface }),
+    createMarkupSurfaceHostFacet({ module: emojiRevealModuleRef, declaration: emojiRevealMarkupSurfaces.find((item) => item.name === "track")!, handler: decodeEmojiRevealTrackSurface }),
+  ],
+};
+export default hypitPackage;