@glissade/scene 0.1.0

package/dist/layoutEngine.d.ts

@@ -0,0 +1,395 @@
+import { BindableSignal, ReadonlySignal, Vec2, Vec2Signal } from "@glissade/core";
+
+//#region src/matrix.d.ts
+
+type Mat2x3 = readonly [number, number, number, number, number, number];
+declare const IDENTITY: Mat2x3;
+declare function multiply(m1: Mat2x3, m2: Mat2x3): Mat2x3;
+/** Compose translate × rotate × scale (rotation in degrees). */
+declare function fromTRS(position: Vec2, rotationDeg: number, scale: Vec2): Mat2x3;
+declare function applyToPoint(m: Mat2x3, p: Vec2): Vec2;
+declare function matEquals(a: Mat2x3, b: Mat2x3): boolean;
+//#endregion
+//#region src/displayList.d.ts
+type ResourceId = number;
+/**
+ * Path data as plain segments (JSON-serializable; backends build Path2D/SkPath):
+ *   M/L: point; C: cubic; Q: quadratic; Z: close
+ *   E: ellipse arc — cx, cy, rx, ry, rotationRad, startAngleRad, endAngleRad
+ */
+type PathSeg = ['M', number, number] | ['L', number, number] | ['C', number, number, number, number, number, number] | ['Q', number, number, number, number] | ['E', number, number, number, number, number, number, number] | ['Z'];
+type Resource = {
+  kind: 'path';
+  segs: PathSeg[];
+} | {
+  kind: 'image';
+  assetId: string;
+}
+/** One source-grid video frame: backends resolve via their VideoFrameSource registry (§3.8). */ | {
+  kind: 'videoFrame';
+  assetId: string;
+  mediaT: number;
+};
+type BlendMode = 'source-over' | 'multiply' | 'screen' | 'overlay' | 'darken' | 'lighten';
+/** M1: solid colors. Gradients/patterns are additive later — backends switch on kind. */
+type Paint = {
+  kind: 'color';
+  color: string;
+};
+interface StrokeStyle {
+  width: number;
+  cap?: 'butt' | 'round' | 'square';
+  join?: 'miter' | 'round' | 'bevel';
+  miterLimit?: number;
+  dash?: number[];
+  dashOffset?: number;
+}
+interface FontSpec {
+  family: string;
+  size: number;
+  weight?: number;
+  style?: 'normal' | 'italic';
+}
+/** Enumerated at M2 (§3.4); reserved in the IR now. */
+interface FilterSpec {
+  kind: string;
+  [k: string]: unknown;
+}
+interface Rect$1 {
+  x: number;
+  y: number;
+  w: number;
+  h: number;
+}
+type DrawCommand = {
+  op: 'save';
+} | {
+  op: 'restore';
+} | {
+  op: 'transform';
+  m: Mat2x3;
+} | {
+  op: 'clip';
+  path: ResourceId;
+  rule?: 'nonzero' | 'evenodd';
+} | {
+  op: 'fillPath';
+  path: ResourceId;
+  paint: Paint;
+} | {
+  op: 'strokePath';
+  path: ResourceId;
+  paint: Paint;
+  stroke: StrokeStyle;
+} | {
+  op: 'fillText';
+  text: string;
+  font: FontSpec;
+  paint: Paint;
+  x: number;
+  y: number;
+  align?: 'left' | 'center' | 'right';
+} | {
+  op: 'drawImage';
+  image: ResourceId;
+  src?: Rect$1;
+  dst: Rect$1;
+  smoothing?: boolean;
+} | {
+  op: 'pushGroup';
+  opacity: number;
+  blend: BlendMode;
+  filters: FilterSpec[];
+  cacheKey?: string;
+} | {
+  op: 'popGroup';
+};
+interface DisplayList {
+  commands: DrawCommand[];
+  resources: Resource[];
+  size: {
+    w: number;
+    h: number;
+  };
+}
+interface DisplayListBuilder {
+  push(cmd: DrawCommand): void;
+  resource(res: Resource): ResourceId;
+}
+declare function createDisplayListBuilder(size: {
+  w: number;
+  h: number;
+}): DisplayListBuilder & {
+  finish(): DisplayList;
+};
+//#endregion
+//#region src/text.d.ts
+interface TextMetricsLite {
+  width: number;
+  ascent: number;
+  descent: number;
+}
+interface TextMeasurer {
+  measureText(text: string, font: FontSpec): TextMetricsLite;
+}
+/** §3.6 measurement quantum. */
+declare function quantize(v: number): number;
+/**
+ * Estimating fallback measurer — used only when no backend has been injected
+ * (e.g. evaluating for IR-level tests). Deterministic but not metrically
+ * faithful; mount(), the CLI, and exporters always inject the real one.
+ */
+declare const estimatingMeasurer: TextMeasurer;
+/**
+ * Greedy line breaking: explicit '\n' always breaks; otherwise word segments
+ * flow until maxWidth is exceeded (Intl.Segmenter boundaries, so CJK wraps
+ * without spaces). A segment wider than maxWidth gets its own line (no
+ * intra-word breaking in v1).
+ */
+declare function breakLines(text: string, font: FontSpec, maxWidth: number | undefined, measurer: TextMeasurer): string[];
+//#endregion
+//#region src/node.d.ts
+interface EvalContext {
+  /** The playhead value at evaluate() entry — the only time channel (§3.1). */
+  readonly time: number;
+  /** Derived: round(time * fps) when the timeline carries an fps advisory; -1 otherwise. */
+  readonly frame: number;
+  /** Injected by mount()/CLI/exporters (§3.2): the active backend's measurer. */
+  readonly measurer: TextMeasurer;
+}
+/** A property initializer: a value, or a computed source (§2.1). */
+type PropInit<T> = T | (() => T);
+interface NodeProps {
+  id?: string;
+  position?: PropInit<Vec2>;
+  rotation?: PropInit<number>;
+  scale?: PropInit<Vec2>;
+  opacity?: PropInit<number>;
+  blend?: PropInit<BlendMode>;
+  zIndex?: PropInit<number>;
+}
+interface BindablePropTarget {
+  bindSource(fn: () => unknown): void;
+  unbindSource(): void;
+}
+declare abstract class Node {
+  readonly id: string | undefined;
+  readonly position: Vec2Signal;
+  readonly rotation: BindableSignal<number>;
+  readonly scale: Vec2Signal;
+  readonly opacity: BindableSignal<number>;
+  readonly blend: BindableSignal<BlendMode>;
+  readonly zIndex: BindableSignal<number>;
+  readonly filters: BindableSignal<FilterSpec[]>;
+  parent: Node | null;
+  readonly localMatrix: ReadonlySignal<Mat2x3>;
+  readonly worldMatrix: ReadonlySignal<Mat2x3>;
+  /** Track-target paths → bindable signals; subclasses register their own props. */
+  protected readonly targets: Map<string, BindablePropTarget>;
+  constructor(props?: NodeProps);
+  protected registerTarget(path: string, sig: BindablePropTarget): void;
+  resolveTarget(path: string): BindablePropTarget | undefined;
+  /** Subclass drawing: emit own commands (and children for containers). */
+  protected abstract draw(out: DisplayListBuilder, ctx: EvalContext): void;
+  /**
+   * Natural size for flex flow (§3.2); null = not flowable (a Layout parent
+   * emits such children absolutely, untouched).
+   */
+  intrinsicSize(measurer: TextMeasurer): {
+    w: number;
+    h: number;
+  } | null;
+  /**
+   * Vector from the node origin to its intrinsic box's TOP-LEFT, so Layout
+   * can place any anchor correctly. Default: center-anchored (every shape).
+   * Text overrides — it draws from a left/center/right baseline origin.
+   */
+  flowOffset(measurer: TextMeasurer): {
+    x: number;
+    y: number;
+  };
+  /** §3.5 predicate: composite-as-a-unit when opacity/blend demand it. */
+  protected requiresGroup(): boolean;
+  emit(out: DisplayListBuilder, ctx: EvalContext): void;
+}
+//#endregion
+//#region src/nodes.d.ts
+declare class Group extends Node {
+  readonly children: Node[];
+  constructor(props?: NodeProps & {
+    children?: Node[];
+  });
+  add(child: Node): this;
+  protected draw(out: DisplayListBuilder, ctx: EvalContext): void;
+}
+interface ShapeProps extends NodeProps {
+  fill?: PropInit<string>;
+  stroke?: PropInit<string>;
+  strokeWidth?: PropInit<number>;
+}
+declare abstract class Shape extends Node {
+  readonly fill: BindableSignal<string>;
+  readonly stroke: BindableSignal<string>;
+  readonly strokeWidth: BindableSignal<number>;
+  constructor(props?: ShapeProps);
+  protected abstract pathSegs(): PathSeg[];
+  protected draw(out: DisplayListBuilder): void;
+}
+declare class Rect extends Shape {
+  readonly width: BindableSignal<number>;
+  readonly height: BindableSignal<number>;
+  /** Corner radius; clamped to half the smaller dimension. radius = h/2 makes a pill. */
+  readonly cornerRadius: BindableSignal<number>;
+  constructor(props?: ShapeProps & {
+    width?: PropInit<number>;
+    height?: PropInit<number>;
+    cornerRadius?: PropInit<number>;
+  });
+  intrinsicSize(): {
+    w: number;
+    h: number;
+  };
+  protected pathSegs(): PathSeg[];
+}
+declare class Circle extends Shape {
+  readonly radius: BindableSignal<number>;
+  constructor(props?: ShapeProps & {
+    radius?: PropInit<number>;
+  });
+  intrinsicSize(): {
+    w: number;
+    h: number;
+  };
+  protected pathSegs(): PathSeg[];
+}
+interface ImageProps extends NodeProps {
+  /** Asset id from the Timeline manifest (§2.3). */
+  assetId: string;
+  width?: PropInit<number>;
+  height?: PropInit<number>;
+}
+declare class ImageNode extends Node {
+  readonly assetId: string;
+  readonly width: BindableSignal<number>;
+  readonly height: BindableSignal<number>;
+  constructor(props: ImageProps);
+  intrinsicSize(): {
+    w: number;
+    h: number;
+  };
+  protected draw(out: DisplayListBuilder): void;
+}
+interface VideoProps extends NodeProps {
+  /** Asset id from the Timeline manifest (kind 'video'). */
+  assetId: string;
+  /** Timeline second at which the clip starts (§3.8). */
+  at?: number;
+  /** Seconds into the source where playback begins. */
+  trimStart?: number;
+  playbackRate?: number;
+  /** Clip length on the timeline (seconds); defaults to rest-of-source. */
+  clipDuration?: number;
+  /**
+   * Source frame rate; when set, mediaT is quantized to the source grid in
+   * the IR itself (§3.8) so equal-frame times emit identical DisplayLists.
+   * Unset: backends quantize at resolve time (pixels identical, IR not).
+   */
+  sourceFps?: number;
+  width?: PropInit<number>;
+  height?: PropInit<number>;
+}
+/**
+ * Pure given a warmed VideoFrameSource (§3.8): emit() does only the
+ * frame-indexed media-time arithmetic — mediaT = trimStart + (t - at) * rate —
+ * and references the exact source-grid frame; backends resolve it.
+ */
+declare class Video extends Node {
+  readonly assetId: string;
+  readonly at: number;
+  readonly trimStart: number;
+  readonly playbackRate: number;
+  readonly clipDuration: number | undefined;
+  readonly sourceFps: number | undefined;
+  readonly width: BindableSignal<number>;
+  readonly height: BindableSignal<number>;
+  constructor(props: VideoProps);
+  /** Frame-indexed media time for timeline time t; null when outside the clip. */
+  mediaTime(t: number): number | null;
+  protected draw(out: DisplayListBuilder, ctx: EvalContext): void;
+}
+interface TextProps extends NodeProps {
+  text?: PropInit<string>;
+  fill?: PropInit<string>;
+  fontFamily?: string;
+  fontSize?: PropInit<number>;
+  fontWeight?: number;
+  /** Horizontal alignment about the node position; default 'left'. */
+  align?: 'left' | 'center' | 'right';
+  /** Wrap width in px; unset = no wrapping (explicit \n still breaks). */
+  width?: PropInit<number>;
+  /** Line height as a multiple of fontSize; default 1.25. */
+  lineHeight?: number;
+}
+declare class Text extends Node {
+  readonly text: BindableSignal<string>;
+  readonly fill: BindableSignal<string>;
+  readonly fontSize: BindableSignal<number>;
+  readonly fontFamily: string;
+  readonly fontWeight: number;
+  readonly align: 'left' | 'center' | 'right';
+  readonly width: BindableSignal<number>;
+  readonly lineHeight: number;
+  constructor(props?: TextProps);
+  intrinsicSize(measurer: TextMeasurer): {
+    w: number;
+    h: number;
+  };
+  /** Text draws from a baseline origin at its align edge, not a center (§3.6). */
+  flowOffset(measurer: TextMeasurer): {
+    x: number;
+    y: number;
+  };
+  protected draw(out: DisplayListBuilder, ctx: EvalContext): void;
+}
+//#endregion
+//#region src/layoutEngine.d.ts
+/**
+ * The LayoutEngine seam (DESIGN.md §3.2): determinism demands the SAME layout
+ * engine in browser preview and headless export, so layout never delegates to
+ * the platform. Yoga implements this interface in the separately-budgeted
+ * '@glissade/scene/layout' entry; the seam keeps Taffy adoptable later and
+ * the base embed path free of wasm.
+ */
+interface LayoutBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+interface LayoutChildSpec {
+  width: number;
+  height: number;
+  grow?: number;
+  margin?: number;
+}
+interface LayoutContainerSpec {
+  width: number;
+  height: number;
+  direction: 'row' | 'column';
+  gap: number;
+  padding: number;
+  justify: 'start' | 'center' | 'end' | 'space-between' | 'space-around';
+  align: 'start' | 'center' | 'end' | 'stretch';
+}
+interface LayoutEngine {
+  /** Pure: child boxes (top-left relative to the container's top-left). */
+  compute(container: LayoutContainerSpec, children: LayoutChildSpec[]): LayoutBox[];
+}
+declare class LayoutEngineMissingError extends Error {
+  constructor();
+}
+declare function setLayoutEngine(e: LayoutEngine): void;
+declare function getLayoutEngine(): LayoutEngine | null;
+declare function requireLayoutEngine(): LayoutEngine;
+//#endregion
+export { DisplayList as A, StrokeStyle as B, PropInit as C, estimatingMeasurer as D, breakLines as E, Paint as F, fromTRS as G, IDENTITY as H, PathSeg as I, matEquals as K, Rect$1 as L, DrawCommand as M, FilterSpec as N, quantize as O, FontSpec as P, Resource as R, NodeProps as S, TextMetricsLite as T, Mat2x3 as U, createDisplayListBuilder as V, applyToPoint as W, Video as _, LayoutEngineMissingError as a, EvalContext as b, setLayoutEngine as c, ImageNode as d, ImageProps as f, TextProps as g, Text as h, LayoutEngine as i, DisplayListBuilder as j, BlendMode as k, Circle as l, ShapeProps as m, LayoutChildSpec as n, getLayoutEngine as o, Rect as p, multiply as q, LayoutContainerSpec as r, requireLayoutEngine as s, LayoutBox as t, Group as u, VideoProps as v, TextMeasurer as w, Node as x, BindablePropTarget as y, ResourceId as z };