@hypit/hypit 0.0.1 → 0.1.0

package/packages/hyperframes/src/types.ts

@@ -0,0 +1,38 @@
+
+import type { BlobRef, ResourceId } from "@hypit/protocol";
+import type { CompositableSurfaceRef } from "@hypit/media";
+
+export type HyperframesFrameDomain = {
+  readonly frameRate: {
+    readonly numerator: number;
+    readonly denominator: number;
+  };
+  /** Legal frame indices are exactly [0, frameCount). */
+  readonly frameCount: number;
+};
+
+export type HyperframesCanvas = {
+  readonly width: number;
+  readonly height: number;
+};
+
+/** Portable input to a local or remote HyperFrames renderer. */
+export type HyperframesDocument = HyperframesFrameDomain & {
+  readonly visualIr: typeof VISUAL_IR_V1;
+  readonly canvas: HyperframesCanvas;
+  /** Every byte resource referenced by the HTML template. */
+  readonly artifacts: readonly BlobRef[];
+  /** Typed Surface dependencies that a Runtime must verify before rendering. */
+  readonly surfaces: readonly CompositableSurfaceRef[];
+  /** Media URLs remain hypit-resource:// placeholders until a Runtime materializes them. */
+  readonly html: string;
+};
+
+/** A half-open interval on the document frame clock, also used for local worker partitions. */
+export type HyperframesFrameSpan = {
+  readonly startFrame: number;
+  readonly endFrameExclusive: number;
+};
+
+export type ResourceUrlResolver = (artifact: BlobRef) => string;
+import { VISUAL_IR_V1 } from "@hypit/visual-ir";

package/packages/image-compose/README.md

@@ -0,0 +1,25 @@
+# @hypit/image-compose
+
+Deterministically flatten a fixed arrangement of existing still images into one PNG.
+
+The author graph supplies an explicit Canvas, an ordered list of image Layers, and an explicit Frame for every Layer. The package lowers that meaning to the shared `@hypit/raster` execution contract; an Endpoint such as `@hypit/provider-image-opencv-local` performs the pixels. Core knows nothing about images or compositing.
+
+```xml
+<import as="space" from="@hypit/spatial@1"/>
+<import as="compose" from="@hypit/image-compose@1"/>
+
+<space:Canvas id="comparison-canvas" width="2048" height="1024"/>
+<space:Frame id="before-panel" within={comparison-canvas}
+  left="0%" top="0%" right="50%" bottom="100%"/>
+<space:Frame id="after-panel" within={comparison-canvas}
+  left="50%" top="0%" right="100%" bottom="100%"/>
+
+<compose:Image id="comparison" canvas={comparison-canvas} background="#EEEAE2FF">
+  <compose:Layer source={before.image} frame={before-panel} fit="contain"/>
+  <compose:Layer source={after.image} frame={after-panel} fit="contain"/>
+</compose:Image>
+```
+
+Child order is paint order. Frames may extend beyond the Canvas and are clipped. Version 1 always produces a PNG using normal alpha compositing; it deliberately has no implicit base image, layout, or metadata propagation.
+
+This operation does no visual reasoning. It does not reconcile perspective, depth, light, subject scale, scene continuity or a natural seam between its inputs. Use an image-generation or image-editing model when the desired result should become one newly directed camera image. Keep independently timed or editable layers in Tracks and Film. Image Compose is for the narrower case where the intended result is precisely the fixed two-dimensional arrangement itself.

package/packages/image-compose/package.json

@@ -0,0 +1,18 @@
+{
+  "name": "@hypit/image-compose",
+  "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/elaborator": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/raster": "workspace:*",
+    "@hypit/spatial": "workspace:*",
+    "@hypit/markup": "workspace:*"
+  }
+}

package/packages/image-compose/src/activation.ts

@@ -0,0 +1,21 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+  decodeImageComposeSurface,
+  imageComposeComponent,
+  imageComposeManifest,
+  imageComposeModuleRef,
+  imageComposeMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{ manifest: imageComposeManifest }],
+  components: [imageComposeComponent],
+  hostFacets: [{ ...createMarkupSurfaceHostFacet({
+    module: imageComposeModuleRef,
+    declaration: imageComposeMarkupSurfaces.find((item) => item.name === "image")!, handler: decodeImageComposeSurface,
+  }) }],
+};
+
+export default hypitPackage;

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

@@ -0,0 +1,100 @@
+import { plannedNeedInputs } from "@hypit/component-kit";
+import type { ComponentPackage, ProducerHandlerContext } from "@hypit/component-kit";
+import type { BlobRef, CanonicalValue, StoredValue } from "@hypit/protocol";
+import { canonicalize } from "@hypit/protocol";
+import { rasterComposeRequest } from "@hypit/raster";
+import { rasterCapabilities } from "@hypit/raster";
+import type { CanvasSpace, SpatialFrame } from "@hypit/spatial";
+
+import { imageComposeProducers, imageComposeTypes } from "./manifest.js";
+import {
+  appendImageComposeLayer,
+  assertImageComposeLayerSet,
+  assertImageComposeLayerSpec,
+  assertImageComposeOptions,
+  createImageComposeLayerSet,
+} from "./program.js";
+import type { ImageComposeLayerSet, ImageComposeLayerSpec, ImageComposeOptions } from "./types.js";
+
+function inline<T>(value: StoredValue | undefined, label: string): T {
+  if (value?.kind !== "inline") throw new Error(`${label} must be inline.`);
+  return value.value as unknown as T;
+}
+function blob(value: StoredValue | undefined, label: string): BlobRef {
+  if (value?.kind !== "blob") throw new Error(`${label} must be a Blob Artifact.`);
+  return value;
+}
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+
+export const imageComposeComponent = {
+  producers: [{
+    producer: imageComposeProducers.createLayers,
+    handler: () => ({ outputs: { layers: output(createImageComposeLayerSet()) }, needs: {} }),
+  }, {
+    producer: imageComposeProducers.appendLayer,
+    handler: ({ inputs }: ProducerHandlerContext) => ({
+      outputs: { layers: output(appendImageComposeLayer(
+        inline<ImageComposeLayerSet>(inputs.layers?.value, "ImageComposeLayerSet"),
+        blob(inputs.source?.value, "Image Compose source"),
+        inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"),
+        inline<ImageComposeLayerSpec>(inputs.spec?.value, "ImageComposeLayerSpec"),
+      )) },
+      needs: {},
+    }),
+  }, {
+    producer: imageComposeProducers.request,
+    handler: ({ inputs }: ProducerHandlerContext) => {
+      const canvas = inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace");
+      const options = inline<ImageComposeOptions>(inputs.options?.value, "ImageComposeOptions");
+      const set = inline<ImageComposeLayerSet>(inputs.layers?.value, "ImageComposeLayerSet");
+      return { outputs: {}, needs: { image: rasterComposeRequest({
+        canvas, background: options.background,
+        layers: set.layers.map((layer) => ({
+          source: layer.source, frame: layer.frame, fit: layer.spec.fit,
+          interpolation: layer.spec.interpolation, opacity: layer.spec.opacity,
+        })),
+      }) } };
+    },
+  }],
+  validators: [{
+    type: imageComposeTypes.options,
+    handler: ({ value }) => assertImageComposeOptions(inline<ImageComposeOptions>(value, "ImageComposeOptions")),
+  }, {
+    type: imageComposeTypes.layerSpec,
+    handler: ({ value }) => assertImageComposeLayerSpec(inline<ImageComposeLayerSpec>(value, "ImageComposeLayerSpec")),
+  }, {
+    type: imageComposeTypes.layerSet,
+    handler: ({ value }) => assertImageComposeLayerSet(inline<ImageComposeLayerSet>(value, "ImageComposeLayerSet")),
+  }],
+  plannedNeeds: [{
+    producer: imageComposeProducers.request,
+    port: "image",
+    capability: rasterCapabilities.execute,
+    plan({ state, step }) {
+      const operation = state.plan.steps.find((item) => item.id === step);
+      if (operation === undefined) return undefined;
+      const read = (input: string) => {
+        const record = operation.inputs[input];
+        const value = record === undefined ? undefined : state.records.find((item) => item.id === record)?.value;
+        return value?.kind === "inline" ? value.value : undefined;
+      };
+      const canvas = read("canvas");
+      const options = read("options");
+      if (canvas === undefined || options === undefined) return undefined;
+      return {
+        constraints: { kind: "compose", canvas, options },
+        pendingInputs: plannedNeedInputs(state, step),
+      };
+    },
+    present(specification) {
+      const constraints = specification.constraints as Readonly<Record<string, CanonicalValue>>;
+      const canvas = constraints.canvas as Readonly<Record<string, CanonicalValue>> | undefined;
+      return {
+        fields: typeof canvas?.widthPx === "number" && typeof canvas.heightPx === "number"
+          ? { canvas: [`${canvas.widthPx}×${canvas.heightPx}`] }
+          : {},
+        references: {},
+      };
+    },
+  }],
+} satisfies ComponentPackage;

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

@@ -0,0 +1,54 @@
+import { artifactTypes } from "@hypit/artifact";
+import { sealGraphFragment } from "@hypit/elaborator";
+import type { FragmentOperation } from "@hypit/elaborator";
+import { spatialTypes } from "@hypit/spatial";
+
+import { imageComposeProducers, imageComposeTypes } from "./manifest.js";
+
+export type ImageComposeFragmentLayer = {
+  readonly sourceName: string;
+  readonly frameName: string;
+  readonly specName: string;
+};
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (id: string) => ({ kind: "fragment-operation" as const, operation: id });
+
+export function createImageComposeFragment(layers: readonly ImageComposeFragmentLayer[]) {
+  if (layers.length === 0) throw new Error("Image Compose Fragment requires at least one Layer.");
+  const operations: FragmentOperation[] = [{
+    id: "image:layers:empty", producer: imageComposeProducers.createLayers, inputs: {},
+    result: { kind: "output", name: "layers" },
+  }];
+  let previous = "image:layers:empty";
+  layers.forEach((layer, index) => {
+    const id = `image:layers:append:${String(index + 1).padStart(4, "0")}`;
+    operations.push({
+      id, producer: imageComposeProducers.appendLayer,
+      inputs: {
+        layers: operation(previous), source: input(layer.sourceName),
+        frame: input(layer.frameName), spec: input(layer.specName),
+      },
+      result: { kind: "output", name: "layers" },
+    });
+    previous = id;
+  });
+  operations.push({
+    id: "image:compose", producer: imageComposeProducers.request,
+    inputs: { canvas: input("canvas"), options: input("options"), layers: operation(previous) },
+    result: { kind: "need", name: "image" },
+  });
+  return sealGraphFragment({
+    inputs: [
+      { name: "canvas", type: spatialTypes.canvas },
+      { name: "options", type: imageComposeTypes.options },
+      ...layers.flatMap((layer) => [
+        { name: layer.sourceName, type: artifactTypes.blob },
+        { name: layer.frameName, type: spatialTypes.frame },
+        { name: layer.specName, type: imageComposeTypes.layerSpec },
+      ]),
+    ],
+    operations,
+    exports: [{ name: "image", type: artifactTypes.blob, root: operation("image:compose") }],
+  });
+}

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

@@ -0,0 +1,10 @@
+export { imageComposeComponent } from "./component.js";
+export { createImageComposeFragment } from "./fragment.js";
+export { imageComposeDependency, imageComposeManifest, imageComposeMarkupSurfaces, imageComposeModuleRef, imageComposeProducers, imageComposeTypes } from "./manifest.js";
+export {
+  appendImageComposeLayer, assertImageComposeLayerSet, assertImageComposeLayerSpec, assertImageComposeOptions,
+  createImageComposeLayerSet,
+  sealImageComposeLayerSpec, sealImageComposeOptions,
+} from "./program.js";
+export { decodeImageComposeSurface } from "./surface.js";
+export type * from "./types.js";

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

@@ -0,0 +1,119 @@
+import { artifactDependency, artifactTypes } from "@hypit/artifact";
+import type { ModuleManifest, ProducerRef, TypeRef, ValueSchema } from "@hypit/protocol";
+import { rasterCapabilities, rasterDependency } from "@hypit/raster";
+import { spatialDependency, spatialFrameSchema, spatialTypes } from "@hypit/spatial";
+
+export const imageComposeModuleRef = { name: "@hypit/image-compose", version: "1" } as const;
+export const imageComposeTypes = {
+  options: { module: imageComposeModuleRef, name: "ImageComposeOptions" },
+  layerSpec: { module: imageComposeModuleRef, name: "ImageComposeLayerSpec" },
+  layerSet: { module: imageComposeModuleRef, name: "ImageComposeLayerSet" },
+} satisfies Record<string, TypeRef>;
+export const imageComposeProducers = {
+  createLayers: { module: imageComposeModuleRef, name: "create-image-compose-layers" },
+  appendLayer: { module: imageComposeModuleRef, name: "append-image-compose-layer" },
+  request: { module: imageComposeModuleRef, name: "request-image-compose" },
+} satisfies Record<string, ProducerRef>;
+
+const string = { kind: "string", minLength: 1 } as const;
+const number = { kind: "number" } as const;
+const object = (fields: Readonly<Record<string, { readonly schema: ValueSchema; readonly optional?: boolean }>>): ValueSchema => ({ kind: "object", fields });
+const blob = object({
+  kind: { schema: { kind: "literal", value: "blob" } },
+  resource: { schema: { kind: "string", minLength: 5, maxLength: 256 } },
+  size: { schema: { kind: "number", integer: true, minimum: 0 } },
+  mediaType: { schema: string },
+});
+export const imageComposeOptionsSchema: ValueSchema = object({
+
+  background: { schema: string },
+});
+export const imageComposeLayerSpecSchema: ValueSchema = object({
+
+  fit: { schema: { kind: "string", enum: ["contain", "cover", "stretch"] } },
+  interpolation: { schema: { kind: "string", enum: ["nearest", "linear", "cubic", "area", "lanczos"] } },
+  opacity: { schema: { kind: "number", minimum: 0, maximum: 1 } },
+});
+const layer = object({
+  source: { schema: blob },
+  frame: { schema: spatialFrameSchema },
+  spec: { schema: imageComposeLayerSpecSchema },
+});
+export const imageComposeLayerSetSchema: ValueSchema = object({
+
+  layers: { schema: { kind: "array", maxItems: 64, items: layer } },
+});
+
+export const imageComposeMarkupSurfaces = [{
+    name: "image", tag: "Image", mode: "structured",
+    outputs: [imageComposeTypes.options, imageComposeTypes.layerSpec, artifactTypes.blob],
+    vocabulary: {
+      summary: "Flattens ordered still-image Layers at explicit rectangular Frames into one PNG Artifact.",
+      attributes: [
+        { name: "id", kind: "identifier", required: true,
+          summary: "Names this composition so its image can be referenced elsewhere in the Source." },
+        { name: "canvas", kind: "reference", required: true, accepts: [spatialTypes.canvas],
+          summary: "Chooses the Canvas every Layer is painted onto." },
+        { name: "background", kind: "literal", required: false,
+          summary: "Sets the color the Canvas is cleared to before the first Layer is painted." },
+      ],
+      children: [
+        { tag: "Layer", cardinality: "many",
+          summary: "One image painted into its own Frame, in document order, and empty of children and text.",
+          attributes: [
+            { name: "source", kind: "reference", required: true, accepts: [artifactTypes.blob],
+              summary: "Chooses the image Artifact this Layer paints." },
+            { name: "frame", kind: "reference", required: true, accepts: [spatialTypes.frame],
+              summary: "Chooses the Frame on the Canvas the image is painted into." },
+            { name: "fit", kind: "literal", required: false, values: ["contain", "cover", "stretch"],
+              summary: "Decides how the image is sized to its Frame; 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: "opacity", kind: "literal", required: false,
+              summary: "Sets how strongly this Layer covers what is beneath it, from 0 to 1; defaults to 1." },
+          ] },
+      ],
+      ports: [
+        { name: "image", type: artifactTypes.blob,
+          summary: "The composed picture, a PNG." },
+      ],
+      example: `<compose:Image id="comparison" canvas={comparison-canvas} background="#EEEAE2FF">
+  <compose:Layer source={before.image} frame={before-panel} fit="contain"/>
+  <compose:Layer source={after.image} frame={after-panel} fit="contain"/>
+</compose:Image>`,
+      notes: [
+        "`background` is written as `#RRGGBBAA` and defaults to `#00000000`.",
+        "The composition requires at least one Layer and holds at most 64.",
+        "Child order is paint order, and a Frame that extends beyond the Canvas is clipped.",
+        "The operation performs rectangular raster placement only; it does not redesign a scene or create timed layers.",
+      ],
+    },
+  }] as const;
+
+
+export const imageComposeManifest: ModuleManifest = {
+  format: "hypit.module@1",
+  name: imageComposeModuleRef.name,
+  version: imageComposeModuleRef.version,
+  dependencies: [artifactDependency, spatialDependency, rasterDependency],
+  types: [
+    { name: imageComposeTypes.options.name },
+    { name: imageComposeTypes.layerSpec.name },
+    { name: imageComposeTypes.layerSet.name },
+  ],
+  capabilities: [],
+  producers: [
+    { name: imageComposeProducers.createLayers.name, inputs: [], outputs: [{ name: "layers", type: imageComposeTypes.layerSet }], needs: [] },
+    { name: imageComposeProducers.appendLayer.name, inputs: [
+      { name: "layers", type: imageComposeTypes.layerSet }, { name: "source", type: artifactTypes.blob },
+      { name: "frame", type: spatialTypes.frame }, { name: "spec", type: imageComposeTypes.layerSpec },
+    ], outputs: [{ name: "layers", type: imageComposeTypes.layerSet }], needs: [] },
+    { name: imageComposeProducers.request.name, inputs: [
+      { name: "canvas", type: spatialTypes.canvas }, { name: "options", type: imageComposeTypes.options },
+      { name: "layers", type: imageComposeTypes.layerSet },
+    ], outputs: [], needs: [{ name: "image", capability: rasterCapabilities.execute, returns: artifactTypes.blob }] },
+  ],
+};
+
+export const imageComposeDependency = { module: imageComposeModuleRef } as const;

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

@@ -0,0 +1,75 @@
+import { assertSpatialFrame } from "@hypit/spatial";
+import { canonicalize, isResourceId } from "@hypit/protocol";
+
+import type {
+  ImageComposeLayer,
+  ImageComposeLayerSet,
+  ImageComposeLayerSpec,
+  ImageComposeOptions,
+} from "./types.js";
+
+function assert(condition: unknown, message: string): asserts condition {
+  if (!condition) throw new Error(message);
+}
+
+function color(value: string, label: string): void {
+  assert(/^#[0-9a-f]{8}$/iu.test(value), `${label} must be #RRGGBBAA.`);
+}
+
+export function assertImageComposeOptions(value: ImageComposeOptions): void {
+  color(value.background, "ImageComposeOptions.background");
+}
+
+export function sealImageComposeOptions(value: ImageComposeOptions): ImageComposeOptions {
+  assertImageComposeOptions(value);
+  return canonicalize(value) as unknown as ImageComposeOptions;
+}
+
+export function assertImageComposeLayerSpec(value: ImageComposeLayerSpec): void {
+  assert(["contain", "cover", "stretch"].includes(value.fit), "ImageComposeLayerSpec.fit is invalid.");
+  assert(["nearest", "linear", "cubic", "area", "lanczos"].includes(value.interpolation),
+    "ImageComposeLayerSpec.interpolation is invalid.");
+  assert(Number.isFinite(value.opacity) && value.opacity >= 0 && value.opacity <= 1,
+    "ImageComposeLayerSpec.opacity must be between zero and one.");
+}
+
+export function sealImageComposeLayerSpec(value: ImageComposeLayerSpec): ImageComposeLayerSpec {
+  assertImageComposeLayerSpec(value);
+  return canonicalize(value) as unknown as ImageComposeLayerSpec;
+}
+
+function assertLayer(value: ImageComposeLayer, label: string): void {
+  assert(value.source.kind === "blob" && isResourceId(value.source.resource)
+    && Number.isSafeInteger(value.source.size) && value.source.size >= 0
+    && value.source.mediaType.startsWith("image/"), `${label}.source must be an image BlobArtifact.`);
+  assertSpatialFrame(value.frame);
+  assertImageComposeLayerSpec(value.spec);
+}
+
+export function createImageComposeLayerSet(): ImageComposeLayerSet {
+  return { layers: [] };
+}
+
+export function assertImageComposeLayerSet(value: ImageComposeLayerSet): void {
+  assert(Array.isArray(value.layers),
+    "ImageComposeLayerSet is invalid.");
+  assert(value.layers.length <= 64, "ImageComposeLayerSet exceeds 64 Layers.");
+  value.layers.forEach((layer, index) => {
+    assertLayer(layer, `ImageComposeLayerSet.layers.${index + 1}`);
+  });
+}
+
+export function appendImageComposeLayer(
+  set: ImageComposeLayerSet,
+  source: ImageComposeLayer["source"],
+  frame: ImageComposeLayer["frame"],
+  spec: ImageComposeLayerSpec,
+): ImageComposeLayerSet {
+  assertImageComposeLayerSet(set);
+  const next: ImageComposeLayerSet = {
+
+    layers: [...set.layers, { source: structuredClone(source), frame: structuredClone(frame), spec: structuredClone(spec) }],
+  };
+  assertImageComposeLayerSet(next);
+  return canonicalize(next) as unknown as ImageComposeLayerSet;
+}

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

@@ -0,0 +1,83 @@
+import { artifactTypes } from "@hypit/artifact";
+import type { CanonicalValue } from "@hypit/protocol";
+import { spatialTypes } from "@hypit/spatial";
+import type { StructuredElement, StructuredSurfaceHandler, SurfaceResolvedReference, MarkupAttributeValue } from "@hypit/markup";
+
+import { createImageComposeFragment } from "./fragment.js";
+import { imageComposeTypes } from "./manifest.js";
+import { sealImageComposeLayerSpec, sealImageComposeOptions } from "./program.js";
+
+function localName(name: string): string { return name.slice(name.lastIndexOf(":") + 1); }
+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 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 = element.attributes[name];
+  if (value === undefined && fallback !== undefined) return fallback;
+  if (typeof value !== "string" || !value.trim()) throw new Error(`${element.name}.${name} must be text.`);
+  return value.trim();
+}
+function number(element: StructuredElement, name: string, fallback: number): number {
+  const value = Number(text(element, name, String(fallback)));
+  if (!Number.isFinite(value)) throw new Error(`${element.name}.${name} must be finite.`);
+  return value;
+}
+function reference(element: StructuredElement, name: string, expected: SurfaceResolvedReference["type"], resolve: (path: string) => SurfaceResolvedReference | undefined): SurfaceResolvedReference {
+  const raw: MarkupAttributeValue | undefined = element.attributes[name];
+  if (typeof raw !== "object" || raw.kind !== "reference") throw new Error(`${element.name}.${name} must be a reference.`);
+  const result = resolve(raw.path);
+  if (result === undefined || !sameType(result.type, expected)) throw new Error(`${element.name}.${name} has the wrong Type.`);
+  return result;
+}
+
+export const decodeImageComposeSurface: StructuredSurfaceHandler = ({ element, resolveReference }) => {
+  exact(element, ["id", "canvas", "background"], ["id", "canvas"]);
+  const id = text(element, "id");
+  const canvas = reference(element, "canvas", spatialTypes.canvas, resolveReference);
+  const optionsId = `${id}.__options`;
+  const records = [{
+    id: optionsId, type: imageComposeTypes.options,
+    value: { kind: "inline" as const, value: sealImageComposeOptions({
+      background: text(element, "background", "#00000000"),
+    }) as unknown as CanonicalValue }, range: element.range,
+  }];
+  const inputs: Record<string, typeof canvas.ref> = { canvas: canvas.ref, options: { kind: "record", id: optionsId } };
+  const layers: Parameters<typeof createImageComposeFragment>[0][number][] = [];
+  for (const child of element.children) {
+    if (child.kind === "text") {
+      if (child.value.trim()) throw new Error(`${element.name} accepts only Layer children.`);
+      continue;
+    }
+    if (localName(child.name) !== "Layer") throw new Error(`${element.name} accepts only Layer children.`);
+    exact(child, ["source", "frame", "fit", "interpolation", "opacity"], ["source", "frame"]);
+    if (child.children.some((node) => node.kind === "element" || node.value.trim())) throw new Error(`${child.name} must be empty.`);
+    const suffix = String(layers.length + 1).padStart(4, "0");
+    const source = reference(child, "source", artifactTypes.blob, resolveReference);
+    const frame = reference(child, "frame", spatialTypes.frame, resolveReference);
+    const specId = `${id}.layer.${suffix}.spec`;
+    records.push({
+      id: specId, type: imageComposeTypes.layerSpec,
+      value: { kind: "inline", value: sealImageComposeLayerSpec({
+
+        fit: text(child, "fit", "contain") as "contain",
+        interpolation: text(child, "interpolation", "lanczos") as "lanczos",
+        opacity: number(child, "opacity", 1),
+      }) as unknown as CanonicalValue }, range: child.range,
+    });
+    const sourceName = `layer-${suffix}-source`; const frameName = `layer-${suffix}-frame`; const specName = `layer-${suffix}-spec`;
+    inputs[sourceName] = source.ref; inputs[frameName] = frame.ref; inputs[specName] = { kind: "record", id: specId };
+    layers.push({ sourceName, frameName, specName });
+  }
+  const fragment = createImageComposeFragment(layers);
+  return {
+    records,
+    components: [{ id, fragment: fragment.id, inputs, outputs: { image: `${id}.image` }, range: element.range }],
+    fragments: [fragment],
+  };
+};

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

@@ -0,0 +1,22 @@
+import type { BlobRef } from "@hypit/protocol";
+import type { SpatialFrame } from "@hypit/spatial";
+
+export type ImageComposeOptions = {
+  readonly background: string;
+};
+
+export type ImageComposeLayerSpec = {
+  readonly fit: "contain" | "cover" | "stretch";
+  readonly interpolation: "nearest" | "linear" | "cubic" | "area" | "lanczos";
+  readonly opacity: number;
+};
+
+export type ImageComposeLayer = {
+  readonly source: BlobRef;
+  readonly frame: SpatialFrame;
+  readonly spec: ImageComposeLayerSpec;
+};
+
+export type ImageComposeLayerSet = {
+  readonly layers: readonly ImageComposeLayer[];
+};

package/packages/image-transform/README.md

@@ -0,0 +1,29 @@
+# `@hypit/image-transform`
+
+An ordinary graph component with two inputs and one result:
+
+```text
+BlobArtifact(image) + ImageTransformProgram -> Need -> BlobArtifact(image)
+```
+
+The result is the transformed image itself. It contains no source digest, Provider name,
+post-processing report or copied upstream metadata. The graph already contains the source and
+program edges; the Runtime selects the endpoint that fulfills the explicit Need.
+
+`gptImageDenoiseV1` applies the GPT Image cleanup profile: YCrCb NLM with luma 2,
+chroma 10, 7/21 windows and 1.02 saturation recovery, followed by PNG encoding. It is now an
+explicit reusable Program rather than hidden behavior inside GPT Image generation.
+
+The official Markup Surface separates declaration from use:
+
+```xml
+<image:Program id="clean-gpt-image">
+  <image:Denoise/>
+  <image:Encode format="png"/>
+</image:Program>
+
+<image:Transform id="clean-shot" source={shot.image} program={clean-gpt-image}/>
+```
+
+Operation order is author meaning. Geometry, NLM denoise, color, sharpen/blur, alpha handling and
+encoding are bounded closed data. OpenCV is only one Runtime realization.

package/packages/image-transform/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@hypit/image-transform",
+  "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/elaborator": "workspace:*",
+    "@hypit/protocol": "workspace:*",
+    "@hypit/raster": "workspace:*",
+    "@hypit/markup": "workspace:*"
+  }
+}

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

@@ -0,0 +1,33 @@
+import { createMarkupSurfaceHostFacet } from "@hypit/markup";
+
+import {
+  decodeImageTransformProgramSurface,
+  decodeImageTransformSurface,
+  imageTransformComponent,
+  imageTransformManifest,
+  imageTransformModuleRef,
+  imageTransformMarkupSurfaces,
+} from "./index.js";
+
+export const hypitPackage = {
+  format: "hypit.node-package@1" as const,
+  modules: [{
+    manifest: imageTransformManifest,
+  }],
+  components: [imageTransformComponent],
+  hostFacets: [{
+    ...createMarkupSurfaceHostFacet({
+      module: imageTransformModuleRef,
+    declaration: imageTransformMarkupSurfaces.find((item) => item.name === "program")!,
+      handler: decodeImageTransformProgramSurface,
+    }),
+  }, {
+    ...createMarkupSurfaceHostFacet({
+      module: imageTransformModuleRef,
+    declaration: imageTransformMarkupSurfaces.find((item) => item.name === "transform")!,
+      handler: decodeImageTransformSurface,
+    }),
+  }],
+};
+
+export default hypitPackage;