@hypit/hypit 0.0.1 → 0.1.0

package/packages/spatial/src/component.ts

@@ -0,0 +1,45 @@
+import type { ComponentPackage } from "@hypit/component-kit";
+import { canonicalize } from "@hypit/protocol";
+import type { StoredValue } from "@hypit/protocol";
+
+import { anchoredFrame, aspectFrame, assertCanvasSpace, assertContentFit, assertFittedContent, assertIntrinsicExtent, assertSpatialFrame, assertSpatialPath, assertSpatialPoint, assertSpatialRegionTimeline, canvasFrame, fitContent, frameFromEdges } from "./geometry.js";
+import { spatialProducers, spatialTypes } from "./manifest.js";
+import type {
+  AnchoredFrameProgram,
+  AspectFrameProgram,
+  CanvasSpace,
+  ContentFit,
+  FittedContent,
+  FrameEdgesProgram,
+  IntrinsicExtent,
+  SpatialFrame,
+  SpatialPath,
+  SpatialPoint,
+  SpatialRegionTimeline,
+} 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;
+}
+const output = (value: unknown) => ({ kind: "inline" as const, value: canonicalize(value) });
+
+export const spatialComponent = {
+  producers: [
+    { producer: spatialProducers.canvasFrame, handler: ({ inputs }) => ({ outputs: { frame: output(canvasFrame(inline<CanvasSpace>(inputs.canvas?.value, "CanvasSpace"))) }, needs: {} }) },
+    { producer: spatialProducers.frameEdges, handler: ({ inputs }) => ({ outputs: { frame: output(frameFromEdges(inline<SpatialFrame>(inputs.parent?.value, "SpatialFrame"), inline<FrameEdgesProgram>(inputs.program?.value, "FrameEdgesProgram"))) }, needs: {} }) },
+    { producer: spatialProducers.anchoredFrame, handler: ({ inputs }) => ({ outputs: { frame: output(anchoredFrame(inline<SpatialFrame>(inputs.parent?.value, "SpatialFrame"), inline<AnchoredFrameProgram>(inputs.program?.value, "AnchoredFrameProgram"))) }, needs: {} }) },
+    { producer: spatialProducers.aspectFrame, handler: ({ inputs }) => ({ outputs: { frame: output(aspectFrame(inline<SpatialFrame>(inputs.parent?.value, "SpatialFrame"), inline<IntrinsicExtent>(inputs.extent?.value, "IntrinsicExtent"), inline<AspectFrameProgram>(inputs.program?.value, "AspectFrameProgram"))) }, needs: {} }) },
+    { producer: spatialProducers.fitContent, handler: ({ inputs }) => ({ outputs: { fitted: output(fitContent(inline<SpatialFrame>(inputs.frame?.value, "SpatialFrame"), inline<IntrinsicExtent>(inputs.extent?.value, "IntrinsicExtent"), inline<ContentFit>(inputs.fit?.value, "ContentFit"))) }, needs: {} }) },
+  ],
+  validators: [
+    { type: spatialTypes.canvas, handler: ({ value }) => assertCanvasSpace(inline<CanvasSpace>(value, "CanvasSpace")) },
+    { type: spatialTypes.point, handler: ({ value }) => assertSpatialPoint(inline<SpatialPoint>(value, "SpatialPoint")) },
+    { type: spatialTypes.frame, handler: ({ value }) => assertSpatialFrame(inline<SpatialFrame>(value, "SpatialFrame")) },
+    { type: spatialTypes.regionTimeline, handler: ({ value }) => assertSpatialRegionTimeline(inline<SpatialRegionTimeline>(value, "SpatialRegionTimeline")) },
+    { type: spatialTypes.path, handler: ({ value }) => assertSpatialPath(inline<SpatialPath>(value, "SpatialPath")) },
+    { type: spatialTypes.extent, handler: ({ value }) => assertIntrinsicExtent(inline<IntrinsicExtent>(value, "IntrinsicExtent")) },
+    { type: spatialTypes.fit, handler: ({ value }) => assertContentFit(inline<ContentFit>(value, "ContentFit")) },
+    { type: spatialTypes.fitted, handler: ({ value }) => assertFittedContent(inline<FittedContent>(value, "FittedContent")) },
+  ],
+} satisfies ComponentPackage;

package/packages/spatial/src/fragment.ts

@@ -0,0 +1,36 @@
+import { sealGraphFragment } from "@hypit/elaborator";
+
+import { spatialProducers, spatialTypes } from "./manifest.js";
+
+const input = (name: string) => ({ kind: "fragment-input" as const, name });
+const operation = (name: string) => ({ kind: "fragment-operation" as const, operation: name });
+
+export const canvasFrameFragment = sealGraphFragment({
+  inputs: [{ name: "canvas", type: spatialTypes.canvas }],
+  operations: [{ id: "resolve", producer: spatialProducers.canvasFrame, inputs: { canvas: input("canvas") }, result: { kind: "output", name: "frame" } }],
+  exports: [{ name: "frame", type: spatialTypes.frame, root: operation("resolve") }],
+});
+
+export const frameEdgesFragment = sealGraphFragment({
+  inputs: [{ name: "parent", type: spatialTypes.frame }, { name: "program", type: spatialTypes.frameEdgesProgram }],
+  operations: [{ id: "resolve", producer: spatialProducers.frameEdges, inputs: { parent: input("parent"), program: input("program") }, result: { kind: "output", name: "frame" } }],
+  exports: [{ name: "frame", type: spatialTypes.frame, root: operation("resolve") }],
+});
+
+export const anchoredFrameFragment = sealGraphFragment({
+  inputs: [{ name: "parent", type: spatialTypes.frame }, { name: "program", type: spatialTypes.anchoredFrameProgram }],
+  operations: [{ id: "resolve", producer: spatialProducers.anchoredFrame, inputs: { parent: input("parent"), program: input("program") }, result: { kind: "output", name: "frame" } }],
+  exports: [{ name: "frame", type: spatialTypes.frame, root: operation("resolve") }],
+});
+
+export const aspectFrameFragment = sealGraphFragment({
+  inputs: [{ name: "parent", type: spatialTypes.frame }, { name: "extent", type: spatialTypes.extent }, { name: "program", type: spatialTypes.aspectFrameProgram }],
+  operations: [{ id: "resolve", producer: spatialProducers.aspectFrame, inputs: { parent: input("parent"), extent: input("extent"), program: input("program") }, result: { kind: "output", name: "frame" } }],
+  exports: [{ name: "frame", type: spatialTypes.frame, root: operation("resolve") }],
+});
+
+export const fitContentFragment = sealGraphFragment({
+  inputs: [{ name: "frame", type: spatialTypes.frame }, { name: "extent", type: spatialTypes.extent }, { name: "fit", type: spatialTypes.fit }],
+  operations: [{ id: "resolve", producer: spatialProducers.fitContent, inputs: { frame: input("frame"), extent: input("extent"), fit: input("fit") }, result: { kind: "output", name: "fitted" } }],
+  exports: [{ name: "fitted", type: spatialTypes.fitted, root: operation("resolve") }],
+});

package/packages/spatial/src/geometry.ts

@@ -0,0 +1,238 @@
+
+import type {
+  AnchoredFrameProgram,
+  AspectFrameProgram,
+  CanvasSpace,
+  ContentFit,
+  FittedContent,
+  FrameEdgesProgram,
+  IntrinsicExtent,
+  SpatialAnchor,
+  SpatialFrame,
+  SpatialLength,
+  SpatialPath,
+  SpatialPoint,
+  SpatialRegionTimeline,
+} from "./types.js";
+
+function finite(value: number, label: string): void {
+  if (!Number.isFinite(value)) throw new Error(`${label} must be finite.`);
+}
+
+function positive(value: number, label: string): void {
+  finite(value, label);
+  if (value <= 0) throw new Error(`${label} must be positive.`);
+}
+
+export function assertCanvasSpace(value: CanvasSpace): void {
+  if (!Number.isSafeInteger(value.widthPx) || value.widthPx <= 0
+    || !Number.isSafeInteger(value.heightPx) || value.heightPx <= 0
+    || value.origin !== "top-left" || value.xDirection !== "right"
+    || value.yDirection !== "down" || value.pixelAspect !== "square") {
+    throw new Error("CanvasSpace is invalid.");
+  }
+}
+
+export function assertSpatialPoint(value: SpatialPoint): void {
+  finite(value.xPx, "SpatialPoint.xPx");
+  finite(value.yPx, "SpatialPoint.yPx");
+}
+
+export function assertSpatialFrame(value: SpatialFrame): void {
+  finite(value.xPx, "SpatialFrame.xPx");
+  finite(value.yPx, "SpatialFrame.yPx");
+  positive(value.widthPx, "SpatialFrame.widthPx");
+  positive(value.heightPx, "SpatialFrame.heightPx");
+}
+
+export function assertSpatialRegionTimeline(value: SpatialRegionTimeline): void {
+  assertCanvasSpace(value.canvas);
+  if (!Number.isSafeInteger(value.frameCount) || value.frameCount <= 0 || value.tracks.length === 0) {
+    throw new Error("SpatialRegionTimeline is empty or has an invalid Frame count.");
+  }
+  const ids = new Set<string>();
+  for (const track of value.tracks) {
+    if (!track.id.trim() || ids.has(track.id)) throw new Error(`SpatialRegionTimeline repeats or omits Track id ${track.id}.`);
+    ids.add(track.id);
+    if (track.frames.length !== value.frameCount) {
+      throw new Error(`SpatialRegionTimeline Track ${track.id} does not cover every Frame.`);
+    }
+    for (const frame of track.frames) {
+      if (frame !== null) assertSpatialFrame(frame);
+    }
+  }
+}
+
+export function assertIntrinsicExtent(value: IntrinsicExtent): void {
+  positive(value.widthPx, "IntrinsicExtent.widthPx");
+  positive(value.heightPx, "IntrinsicExtent.heightPx");
+}
+
+function assertNormalizedPoint(value: { readonly x: number; readonly y: number }, label: string): void {
+  finite(value.x, `${label}.x`);
+  finite(value.y, `${label}.y`);
+  if (value.x < 0 || value.x > 1 || value.y < 0 || value.y > 1) {
+    throw new Error(`${label} must lie inside [0, 1].`);
+  }
+}
+
+export function assertContentFit(value: ContentFit): void {
+  if (!["contain", "cover", "fit-width", "fit-height", "native", "scale-down", "stretch"].includes(value.sizing)) {
+    throw new Error("ContentFit.sizing is invalid.");
+  }
+  assertNormalizedPoint(value.framePoint, "ContentFit.framePoint");
+  assertNormalizedPoint(value.contentPoint, "ContentFit.contentPoint");
+  finite(value.offsetPx.x, "ContentFit.offsetPx.x");
+  finite(value.offsetPx.y, "ContentFit.offsetPx.y");
+  if (value.constraint !== "bounded" && value.constraint !== "free") throw new Error("ContentFit.constraint is invalid.");
+}
+
+export function assertFittedContent(value: FittedContent): void {
+  assertSpatialFrame(value.contentFrame);
+}
+
+function commandNumbers(command: SpatialPath["commands"][number]): readonly number[] {
+  switch (command.kind) {
+    case "move":
+    case "line": return [command.xPx, command.yPx];
+    case "quadratic": return [command.controlX, command.controlY, command.xPx, command.yPx];
+    case "cubic": return [command.control1X, command.control1Y, command.control2X, command.control2Y, command.xPx, command.yPx];
+    case "close": return [];
+  }
+}
+
+export function assertSpatialPath(value: SpatialPath): void {
+  if (value.commands.length < 2 || value.commands[0]?.kind !== "move") {
+    throw new Error("SpatialPath must begin with move and contain drawable commands.");
+  }
+  let open = true;
+  let drawable = false;
+  for (const [index, command] of value.commands.entries()) {
+    for (const coordinate of commandNumbers(command)) finite(coordinate, `SpatialPath command ${index}`);
+    if (command.kind === "move") {
+      open = true;
+    } else if (command.kind === "close") {
+      if (!open) throw new Error("SpatialPath cannot close an already closed subpath.");
+      open = false;
+    } else {
+      if (!open) throw new Error("SpatialPath requires move after a closed subpath.");
+      drawable = true;
+    }
+  }
+  if (!drawable) throw new Error("SpatialPath contains no drawable segment.");
+}
+
+function length(value: SpatialLength, dimension: number, label: string): number {
+  finite(value.value, label);
+  if (value.unit === "px") return value.value;
+  if (value.unit === "percent") return dimension * value.value / 100;
+  throw new Error(`${label} uses an unsupported unit.`);
+}
+
+function anchorPoint(anchor: SpatialAnchor): { readonly x: number; readonly y: number } {
+  const [vertical, horizontal] = anchor === "center" ? ["middle", "center"] : anchor.split("-");
+  const x = horizontal === "left" ? 0 : horizontal === "center" ? 0.5 : horizontal === "right" ? 1 : undefined;
+  const y = vertical === "top" ? 0 : vertical === "middle" ? 0.5 : vertical === "bottom" ? 1 : undefined;
+  if (x === undefined || y === undefined) throw new Error(`Spatial anchor ${anchor} is invalid.`);
+  return { x, y };
+}
+
+function sealFrame(value: SpatialFrame): SpatialFrame {
+  const frame = { ...value };
+  assertSpatialFrame(frame);
+  return frame;
+}
+
+export function canvasFrame(canvas: CanvasSpace): SpatialFrame {
+  assertCanvasSpace(canvas);
+  return sealFrame({ xPx: 0, yPx: 0, widthPx: canvas.widthPx, heightPx: canvas.heightPx });
+}
+
+export function frameFromEdges(parent: SpatialFrame, program: FrameEdgesProgram): SpatialFrame {
+  assertSpatialFrame(parent);
+  const left = parent.xPx + length(program.left, parent.widthPx, "Frame left");
+  const right = parent.xPx + length(program.right, parent.widthPx, "Frame right");
+  const top = parent.yPx + length(program.top, parent.heightPx, "Frame top");
+  const bottom = parent.yPx + length(program.bottom, parent.heightPx, "Frame bottom");
+  return sealFrame({ xPx: left, yPx: top, widthPx: right - left, heightPx: bottom - top });
+}
+
+export function anchoredFrame(parent: SpatialFrame, program: AnchoredFrameProgram): SpatialFrame {
+  assertSpatialFrame(parent);
+  const widthPx = length(program.width, parent.widthPx, "AnchoredFrame width");
+  const heightPx = length(program.height, parent.heightPx, "AnchoredFrame height");
+  positive(widthPx, "AnchoredFrame width");
+  positive(heightPx, "AnchoredFrame height");
+  const targetX = parent.xPx + length(program.x, parent.widthPx, "AnchoredFrame x");
+  const targetY = parent.yPx + length(program.y, parent.heightPx, "AnchoredFrame y");
+  finite(program.offsetPx.x, "AnchoredFrame offset x");
+  finite(program.offsetPx.y, "AnchoredFrame offset y");
+  const anchor = anchorPoint(program.anchor);
+  return sealFrame({
+    xPx: targetX - widthPx * anchor.x + program.offsetPx.x,
+    yPx: targetY - heightPx * anchor.y + program.offsetPx.y,
+    widthPx,
+    heightPx,
+  });
+}
+
+export function aspectFrame(parent: SpatialFrame, extent: IntrinsicExtent, program: AspectFrameProgram): SpatialFrame {
+  assertSpatialFrame(parent);
+  assertIntrinsicExtent(extent);
+  const primary = length(program.size, program.primary === "width" ? parent.widthPx : parent.heightPx, "AspectFrame size");
+  positive(primary, "AspectFrame size");
+  const widthPx = program.primary === "width" ? primary : primary * extent.widthPx / extent.heightPx;
+  const heightPx = program.primary === "height" ? primary : primary * extent.heightPx / extent.widthPx;
+  return anchoredFrame(parent, {
+    x: program.x,
+    y: program.y,
+    width: { unit: "px", value: widthPx },
+    height: { unit: "px", value: heightPx },
+    anchor: program.anchor,
+    offsetPx: program.offsetPx,
+  });
+}
+
+function boundedCoordinate(position: number, contentSize: number, frameStart: number, frameSize: number): number {
+  const first = frameStart;
+  const second = frameStart + frameSize - contentSize;
+  const low = Math.min(first, second);
+  const high = Math.max(first, second);
+  return Math.min(high, Math.max(low, position));
+}
+
+export function fitContent(frame: SpatialFrame, extent: IntrinsicExtent, fit: ContentFit): FittedContent {
+  assertSpatialFrame(frame);
+  assertIntrinsicExtent(extent);
+  assertContentFit(fit);
+  const containScale = Math.min(frame.widthPx / extent.widthPx, frame.heightPx / extent.heightPx);
+  const scale = fit.sizing === "contain" ? containScale
+    : fit.sizing === "cover" ? Math.max(frame.widthPx / extent.widthPx, frame.heightPx / extent.heightPx)
+    : fit.sizing === "fit-width" ? frame.widthPx / extent.widthPx
+    : fit.sizing === "fit-height" ? frame.heightPx / extent.heightPx
+    : fit.sizing === "native" ? 1
+    : fit.sizing === "scale-down" ? Math.min(1, containScale)
+    : undefined;
+  const widthPx = fit.sizing === "stretch" ? frame.widthPx : extent.widthPx * (scale ?? 1);
+  const heightPx = fit.sizing === "stretch" ? frame.heightPx : extent.heightPx * (scale ?? 1);
+  let xPx = frame.xPx + frame.widthPx * fit.framePoint.x - widthPx * fit.contentPoint.x + fit.offsetPx.x;
+  let yPx = frame.yPx + frame.heightPx * fit.framePoint.y - heightPx * fit.contentPoint.y + fit.offsetPx.y;
+  if (fit.constraint === "bounded") {
+    xPx = boundedCoordinate(xPx, widthPx, frame.xPx, frame.widthPx);
+    yPx = boundedCoordinate(yPx, heightPx, frame.yPx, frame.heightPx);
+  }
+  const result: FittedContent = {
+    contentFrame: sealFrame({ xPx, yPx, widthPx, heightPx }),
+  };
+  assertFittedContent(result);
+  return result;
+}
+
+export function sealCanvasSpace(value: CanvasSpace): CanvasSpace { assertCanvasSpace(value); return structuredClone(value); }
+export function sealSpatialPoint(value: SpatialPoint): SpatialPoint { assertSpatialPoint(value); return structuredClone(value); }
+export function sealSpatialFrame(value: SpatialFrame): SpatialFrame { assertSpatialFrame(value); return structuredClone(value); }
+export function sealSpatialRegionTimeline(value: SpatialRegionTimeline): SpatialRegionTimeline { assertSpatialRegionTimeline(value); return structuredClone(value); }
+export function sealSpatialPath(value: SpatialPath): SpatialPath { assertSpatialPath(value); return structuredClone(value); }
+export function sealIntrinsicExtent(value: IntrinsicExtent): IntrinsicExtent { assertIntrinsicExtent(value); return structuredClone(value); }
+export function sealContentFit(value: ContentFit): ContentFit { assertContentFit(value); return structuredClone(value); }
+export function sealFittedContent(value: FittedContent): FittedContent { assertFittedContent(value); return structuredClone(value); }

package/packages/spatial/src/index.ts

@@ -0,0 +1,37 @@
+export { spatialComponent } from "./component.js";
+export { contentFitPropertyNames, decodeContentFitProperties } from "./author.js";
+export {
+  anchoredFrameFragment,
+  aspectFrameFragment,
+  canvasFrameFragment,
+  fitContentFragment,
+  frameEdgesFragment,
+} from "./fragment.js";
+export * from "./geometry.js";
+export {
+  spatialDependency,
+  spatialManifest, spatialMarkupSurfaces,
+  spatialModuleRef,
+  spatialProducers,
+  spatialTypes,
+} from "./manifest.js";
+export {
+  contentFitSchema,
+  intrinsicExtentSchema,
+  spatialFrameSchema,
+  spatialRegionTimelineSchema,
+  spatialPathSchema,
+  spatialPointSchema,
+} from "./schema.js";
+export {
+  decodeAnchoredFrameSurface,
+  decodeAspectFrameSurface,
+  decodeCanvasSurface,
+  decodeExtentSurface,
+  decodeFrameSurface,
+  decodePathSurface,
+  decodePointSurface,
+  decodeRegionTimelineSurface,
+} from "./surface.js";
+export { spatialRegionTimeline } from "./region-timeline.js";
+export type * from "./types.js";