gpucanvas 0.3.0 → 0.4.0

package/dist/{editor-BSRqjhN8.d.ts → editor-D87kaZBM.d.ts}

@@ -85,6 +85,8 @@ declare const EFFECTS: {
     readonly blur: Effect;
     readonly pixelate: Effect;
     readonly dissolve: Effect;
+    readonly fade: Effect;
+    readonly wipe: Effect;
     readonly grayscale: Effect;
 };
 
@@ -186,6 +188,13 @@ interface GpuCanvas {
      * class on `<html>` or a web font finishing loading.
      */
     invalidate(): void;
+    /**
+     * The node's pixels as it looks now, drawn fresh at `scale` texels per CSS pixel (default the
+     * device pixel ratio), with straight alpha. GPU backend only: the DOM backend rejects.
+     */
+    snapshot(node: HTMLElement, options?: {
+        scale?: number;
+    }): Promise<ImageData>;
     /** Changes the canvas background, any CSS color. */
     setBackground(color: string): void;
     /** Fits all nodes in view. */
@@ -264,4 +273,4 @@ interface Editor {
  */
 declare function bindEditor(canvas: GpuCanvas, options?: EditorOptions): Editor;
 
-export { type Camera as C, type Editor as E, type GpuCanvasOptions as G, type Layer as L, type Point as P, type Rect as R, type TransformEvent as T, type GpuCanvas as a, type EditorOptions as b, type EditorPick as c, type Effect as d, type EffectDefinition as e, type GpuCanvasMode as f, type GpuCanvasStats as g, bindEditor as h, defineEffect as i, EFFECTS as j, fitCamera as k, screenToWorld as s, worldToScreen as w, zoomAt as z };
+export { type Camera as C, type Effect as E, type GpuCanvas as G, type Layer as L, type Point as P, type Rect as R, type TransformEvent as T, type GpuCanvasOptions as a, type Editor as b, type EditorOptions as c, type EditorPick as d, type EffectDefinition as e, type GpuCanvasMode as f, type GpuCanvasStats as g, bindEditor as h, defineEffect as i, EFFECTS as j, fitCamera as k, screenToWorld as s, worldToScreen as w, zoomAt as z };

package/dist/index.d.ts

@@ -1,12 +1,174 @@
-import { G as GpuCanvasOptions, a as GpuCanvas } from './editor-BSRqjhN8.js';
-export { C as Camera, E as Editor, b as EditorOptions, c as EditorPick, d as Effect, e as EffectDefinition, f as GpuCanvasMode, g as GpuCanvasStats, L as Layer, P as Point, R as Rect, T as TransformEvent, h as bindEditor, i as defineEffect, j as effects, k as fitCamera, s as screenToWorld, w as worldToScreen, z as zoomAt } from './editor-BSRqjhN8.js';
+import { R as Rect, G as GpuCanvas, P as Point, E as Effect, a as GpuCanvasOptions } from './editor-D87kaZBM.js';
+export { C as Camera, b as Editor, c as EditorOptions, d as EditorPick, e as EffectDefinition, f as GpuCanvasMode, g as GpuCanvasStats, L as Layer, T as TransformEvent, h as bindEditor, i as defineEffect, j as effects, k as fitCamera, s as screenToWorld, w as worldToScreen, z as zoomAt } from './editor-D87kaZBM.js';
 
 declare function supportsGpuCanvas(): boolean;
 
+/** One element as an agent reads it: what it is, what it says, and where it sits on the canvas. */
+interface AgentElement {
+    /** Stable for the life of the agent view; pass it back to `element`, `capture` or a mark. */
+    id: string;
+    tag: string;
+    role?: string;
+    /** Its accessible name: aria-label, alt, title or a label's text. */
+    name?: string;
+    /** Its own text, trimmed. */
+    text?: string;
+    /** For inputs: the current value. */
+    value?: string;
+    /** For checkboxes and radios. */
+    checked?: boolean;
+    rect: Rect;
+    children?: AgentElement[];
+}
+interface DescribeOptions {
+    /** The world rect to read. Default: what is in view. */
+    rect?: Rect;
+    /** Levels below each node, counting only elements with a role, name, text or value. Default 6. */
+    depth?: number;
+    /** A name for an element when it has none of its own, such as its React component's. */
+    name?: (element: Element) => string | null | undefined;
+}
+/**
+ * The canvas as an agent sees it: a JSON tree of what is in a region, with ids it can point back
+ * at, and images of any region. Wrappers that add nothing (no text, no role, the same box as
+ * their only child) are left out, so the tree stays short.
+ */
+declare function createAgentView(canvas: GpuCanvas): {
+    /** What is in `rect` (default: the view), node by node, as plain JSON. */
+    describe(options?: DescribeOptions): AgentElement[];
+    /** The element behind an id from `describe`, or null once it is gone. */
+    element(id: string): Element | null;
+    /** Where an element (or the element behind an id) sits, in world units. */
+    rect(target: string | Element): Rect | null;
+    /**
+     * An image of a world rect (an element's box when given one) as the nodes look now, at
+     * `scale` texels per world unit. GPU backend only.
+     */
+    capture(target: Rect | string | Element, { scale, background }?: {
+        scale?: number;
+        background?: string;
+    }): Promise<ImageData>;
+};
+type AgentView = ReturnType<typeof createAgentView>;
+
+/** Something drawn above the nodes. `remove` takes it off the canvas. */
+interface Mark {
+    remove(): void;
+}
+interface CursorMark extends Mark {
+    /** Glides the cursor to a world point; null hides it. */
+    move(point: Point | null): void;
+}
+type Target = Element | Point;
+/**
+ * Marks above the nodes: connectors between elements, comment pins, notes that point at an
+ * element (what an agent is talking about), and live cursors. They follow the camera and the
+ * elements they are attached to, and stay the same size on screen at any zoom.
+ */
+declare function createMarks(canvas: GpuCanvas, { color }?: {
+    color?: string | undefined;
+}): {
+    /** An arrow from one element (or world point) to another, with an optional label. */
+    connect(from: Target, to: Target, options?: {
+        label?: string;
+        color?: string;
+        dashed?: boolean;
+    }): Mark;
+    /**
+     * A comment pin at an element's top right corner, or at a world point. Its text shows on
+     * hover; `onClick` makes it a button.
+     */
+    pin(target: Target, options?: {
+        text?: string;
+        label?: string;
+        color?: string;
+        onClick?: () => void;
+    }): Mark;
+    /** A dashed frame around an element with a note above it: what someone is pointing at. */
+    note(target: Element, text: string, options?: {
+        color?: string;
+    }): Mark;
+    /** Someone's cursor, with their name. It glides to each point given to `move`. */
+    cursor(name: string, options?: {
+        color?: string;
+    }): CursorMark;
+    /** Removes every mark. */
+    clear(): void;
+    destroy(): void;
+};
+type Marks = ReturnType<typeof createMarks>;
+
+/** A snapshot as an image file, PNG by default. */
+declare function toBlob(image: ImageData, type?: string, quality?: number): Promise<Blob>;
+interface ImageDiff {
+    /** Pixels that differ by more than the threshold, out of `total`. */
+    changed: number;
+    total: number;
+    /** The smallest rect around every changed pixel, in pixels of the images, or null. */
+    bounds: Rect | null;
+    /** `after` faded, with the changed pixels in `color` on top. */
+    image: ImageData;
+}
+/**
+ * Where two snapshots of the same node differ. Pixels count as changed when a channel moves by
+ * more than `threshold` (0 to 255). Images of different sizes compare over the larger one, and
+ * what only one of them covers counts as changed.
+ */
+declare function diffImages(before: ImageData, after: ImageData, { threshold, color }?: {
+    threshold?: number | undefined;
+    color?: [number, number, number] | undefined;
+}): ImageDiff;
+interface FilmstripFrame {
+    /** When the frame was taken, from performance.now(). */
+    at: number;
+    image: ImageData;
+}
+interface Filmstrip {
+    readonly frames: readonly FilmstripFrame[];
+    stop(): void;
+}
+/**
+ * Keeps a snapshot of `node` after each change to its content, once the change has settled.
+ * Starts with one of how it looks now. Keeps the latest `max` frames.
+ */
+declare function recordFilmstrip(canvas: Pick<GpuCanvas, 'snapshot'>, node: HTMLElement, { scale, max, settleMs, onFrame, }?: {
+    scale?: number;
+    max?: number;
+    settleMs?: number;
+    onFrame?: (frame: FilmstripFrame, frames: readonly FilmstripFrame[]) => void;
+}): Filmstrip;
+
+type Easing = (t: number) => number;
+declare const easeInOut: Easing;
+interface AnimateEffectOptions {
+    /** Progress at the start and the end, 0 (whole) to 1 (gone). Default 0 to 1. */
+    from?: number;
+    to?: number;
+    /** Milliseconds. Default 500. */
+    duration?: number;
+    easing?: Easing;
+    /** The effect's other parameters, after progress. */
+    params?: readonly number[];
+}
+/**
+ * Runs a transition effect (one whose first parameter is progress, such as dissolve, fade or
+ * wipe) on a node. Resolves true when it finishes, false when another animation on the same node
+ * replaced it. A node that ends whole (progress 0) loses the effect; one that ends gone keeps it,
+ * so it stays hidden until it is removed or animated back.
+ */
+declare function animateEffect(canvas: Pick<GpuCanvas, 'setEffect'>, node: HTMLElement, effect: Effect, { from, to, duration, easing, params }?: AnimateEffectOptions): Promise<boolean>;
+/**
+ * Takes `outgoing` away and brings `incoming` in at the same time, each through `effect`.
+ * `incoming` ends whole; `outgoing` ends hidden, ready to be removed.
+ */
+declare function swapNodes(canvas: Pick<GpuCanvas, 'setEffect'>, outgoing: HTMLElement, incoming: HTMLElement, { effect, ...options }?: Omit<AnimateEffectOptions, 'from' | 'to'> & {
+    effect?: Effect;
+}): Promise<boolean>;
+
 /**
  * Creates an infinite canvas inside `host`. Uses WebGPU + HTML-in-Canvas when the browser has
  * both (Chrome 157+), and plain DOM transforms everywhere else; the API is the same.
  */
 declare function createGpuCanvas(host: HTMLElement, options?: GpuCanvasOptions): Promise<GpuCanvas>;
 
-export { GpuCanvas, GpuCanvasOptions, createGpuCanvas, supportsGpuCanvas };
+export { type AgentElement, type AgentView, type AnimateEffectOptions, type CursorMark, type DescribeOptions, type Easing, Effect, type Filmstrip, type FilmstripFrame, GpuCanvas, GpuCanvasOptions, type ImageDiff, type Mark, type Marks, Point, Rect, animateEffect, createAgentView, createGpuCanvas, createMarks, diffImages, easeInOut, recordFilmstrip, supportsGpuCanvas, swapNodes, toBlob };

package/dist/index.js

@@ -1,22 +1,38 @@
 import {
   EFFECTS,
+  animateEffect,
   bindEditor,
+  createAgentView,
   createGpuCanvas,
+  createMarks,
   defineEffect,
+  diffImages,
+  easeInOut,
   fitCamera,
+  recordFilmstrip,
   screenToWorld,
   supportsGpuCanvas,
+  swapNodes,
+  toBlob,
   worldToScreen,
   zoomAt
-} from "./chunk-RBXGH44N.js";
+} from "./chunk-BQQVSR4B.js";
 export {
+  animateEffect,
   bindEditor,
+  createAgentView,
   createGpuCanvas,
+  createMarks,
   defineEffect,
+  diffImages,
+  easeInOut,
   EFFECTS as effects,
   fitCamera,
+  recordFilmstrip,
   screenToWorld,
   supportsGpuCanvas,
+  swapNodes,
+  toBlob,
   worldToScreen,
   zoomAt
 };

package/dist/react.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { ReactNode, CSSProperties } from 'react';
-import { d as Effect, G as GpuCanvasOptions, a as GpuCanvas$1, L as Layer, b as EditorOptions } from './editor-BSRqjhN8.js';
+import { E as Effect, a as GpuCanvasOptions, G as GpuCanvas$1, L as Layer, c as EditorOptions } from './editor-D87kaZBM.js';
 
 interface GpuCanvasProps extends GpuCanvasOptions {
     children?: ReactNode;

package/dist/react.js

@@ -2,7 +2,7 @@
 import {
   bindEditor,
   createGpuCanvas
-} from "./chunk-RBXGH44N.js";
+} from "./chunk-BQQVSR4B.js";
 
 // src/react.tsx
 import {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "gpucanvas",
-  "version": "0.3.0",
-  "description": "Put thousands of live DOM nodes on an infinite canvas: the GPU draws them, an editor selects, moves and resizes them, and shaders run on them.",
+  "version": "0.4.0",
+  "description": "Put thousands of live DOM nodes on an infinite canvas: the GPU draws them, an editor selects, moves and resizes them, shaders and transitions run on them, and an AI agent can read them and point at them.",
   "keywords": [
     "canvas",
     "infinite-canvas",
@@ -12,7 +12,9 @@
     "design-tools",
     "editor",
     "shaders",
-    "wgsl"
+    "wgsl",
+    "ai-agents",
+    "transitions"
   ],
   "author": "Berkant Ay",
   "license": "MIT",