gpucanvas 0.2.0 → 0.3.1

package/README.md

@@ -1,14 +1,32 @@
 # gpucanvas
 
-Put thousands of live DOM nodes on an infinite canvas and let the GPU pan and zoom them.
+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.
 
 ![The same 5,000 live React screens as plain DOM (left) and in gpucanvas (right), with each side's frame rate measured live](docs/benchmark.gif)
 
 The same session on both sides: 5,000 live React screens, the same camera path, a message typed and sent. Left, every screen is plain DOM under a CSS transform. Right, gpucanvas. Recorded in Chrome on a MacBook Pro; the frame rates are measured live in each run. Run it yourself in the [live demo](https://berkantay.github.io/gpucanvas/).
 
+- **[Canvas](#how-it-works).** Live React or plain DOM nodes, drawn by WebGPU in one instanced
+  pass. Pan and zoom never touch the DOM, and clicks, typing and state still reach the real
+  elements.
+- **[Editor](#editing).** Click to select, double-click to go a layer deeper, down to any element
+  or React component. Move and resize with snapping guides.
+- **[Shader effects](#shader-effects).** Run WGSL on live components: a glass lens, frost,
+  shockwaves, glitch, VHS, or your own.
+
 ## Try it
 
-Open **[berkantay.github.io/gpucanvas](https://berkantay.github.io/gpucanvas/)** in Chrome 157 or later. Thirty agent cursors build the first view, then the camera pulls out to all 5,000 screens. Press `b` to run the benchmark tour.
+Open **[berkantay.github.io/gpucanvas](https://berkantay.github.io/gpucanvas/)** in Chrome 157 or
+later. Thirty agent cursors build the first view, then the camera pulls out to all 5,000 screens.
+
+- Click a screen to select it, double-click to go deeper, drag to move it.
+- Pick a shader effect in the toolbar, or open one directly:
+  [glass](https://berkantay.github.io/gpucanvas/?effect=glass),
+  [shockwave](https://berkantay.github.io/gpucanvas/?effect=shockwave) (click anywhere),
+  [frost](https://berkantay.github.io/gpucanvas/?effect=frost),
+  [glitch](https://berkantay.github.io/gpucanvas/?effect=glitch).
+- Press `b` to run the benchmark tour.
 
 The GPU path needs HTML-in-Canvas, which is behind a flag:
 
@@ -18,7 +36,7 @@ The GPU path needs HTML-in-Canvas, which is behind a flag:
 
 Without the flag the demo runs the DOM fallback with 1,000 screens and says so.
 
-Status: early (0.2). The API can still change.
+Status: early (0.3). The API can still change.
 
 ```sh
 npm install gpucanvas
@@ -41,17 +59,130 @@ HTML-in-Canvas are available (Chrome 157+), nodes are snapshotted into a GPU atl
 one instanced draw call. Everywhere else it falls back to a CSS-transformed container with the
 same API.
 
-## Selection
+## Editing
+
+`bindEditor` turns the canvas into an editor: select, drill in, move and resize. The GPU draws
+the outlines, 2 CSS pixels wide at any zoom, and they follow their element's layout. Names,
+sizes, handles and snapping guides sit in a thin overlay above it.
+
+```ts
+import { bindEditor } from 'gpucanvas';
+
+const editor = bindEditor(canvas, {
+  pick: 'element', // 'node' (default), 'element', or a function
+  trigger: 'click', // an edit mode; the default 'shift-click' leaves clicks to your components
+  onChange: (layers) => console.log(layers),
+  onTransform: ({ phase, layers, to }) => {
+    // The editor never moves anything itself. Apply `to` with updateNode, state or styles.
+  },
+});
+```
+
+A click selects the outermost layer under the pointer, a whole node. Each double-click goes one
+layer deeper, and later clicks stay at that depth. Wrappers the size of their parent are skipped,
+so every double-click visibly changes something.
+
+| Input              | Does                                                                         |
+| ------------------ | ---------------------------------------------------------------------------- |
+| Double-click       | One layer deeper                                                             |
+| Enter, Shift+Enter | First child, parent                                                          |
+| Tab, Shift+Tab     | Next and previous sibling                                                    |
+| Escape             | Cancels a drag, then goes up a layer, then clears                            |
+| Drag               | Moves, snapping to the edges and centers of neighbors (Shift locks the axis) |
+| Handles            | Resize (Shift on a corner keeps the ratio)                                   |
+| Drag on open space | A box that selects the layers it touches, inside the layer you are in        |
 
-Selected nodes get an outline drawn by the GPU, 2 CSS pixels wide at any zoom.
+With the default `trigger: 'shift-click'`, the same works with Shift held, and clicks still reach
+your components. A layer is an array of elements, so one layer can be a component that renders
+several. `pick` decides the layers:
+
+- `'node'`: whole nodes only.
+- `'element'`: every element from the node down to the one under the pointer.
+- a function of that element, returning the layers that hold it, outermost first.
+
+In React, `useEditor` gives the selection as state, and `pickComponents` makes the layers React
+components:
+
+```tsx
+import { labelComponent, pickComponents, useEditor } from 'gpucanvas/react';
+
+// Inside <GpuCanvas>:
+const { selected, clear } = useEditor({ pick: pickComponents, label: labelComponent });
+// Click a screen, double-click: SignIn, SignInCard, Button.
+```
+
+`pickComponents` and `componentOf` read React's internal fibers, as click-to-component tools do.
+Production builds usually minify component names, so mark components with your own attributes
+when you need names there.
+
+The building blocks, for your own interactions:
 
 ```ts
-const hits = canvas.getNodesIn({ x, y, width, height }); // world units, such as a selection box
-canvas.setSelection(hits); // replaces the selection; [] clears it
+canvas.getElementAt(point); // deepest element at a world point
+canvas.getElementRect(el); // any element's rect in world units
+canvas.getNodeOf(el); // the node that holds it
+canvas.getNodesIn(rect); // nodes overlapping a world rect
+canvas.setSelection(elements); // outline these; [] clears
+canvas.setHover(el); // a lighter outline; null clears
+canvas.screenToWorld(point); // surface pixels to world units, and worldToScreen back
 ```
 
-The color is the `selectionColor` option. Shift-drags on the background don't pan, so an app
-can use them for a selection box, as the demo does.
+Colors are the `selectionColor` and `hoverColor` options. The demo picks React components in the edit mode;
+`?pick=element` or `?pick=node` picks elements or whole screens, and `?edit=0` leaves clicks to
+the components.
+
+## Shader effects
+
+Components stay live DOM, and the GPU draws them through a shader. One call per node:
+
+```ts
+import { effects } from 'gpucanvas';
+
+canvas.setEffect(node, effects.ripple); // the effect's default parameters
+canvas.setEffect(node, effects.glow, [1, 0.4, 0.2, 32]); // orange, 32 px reach
+canvas.setEffect(node, null); // back to plain
+```
+
+Built in:
+
+- Following the pointer: `glass` (a magnifying lens), `frost` (ice, clear around the pointer),
+  `dither` (a lens of big dithered pixels).
+- On each press: `shockwave`, a ring that bends the node as it spreads.
+- Running on their own: `glitch`, `vhs`, `glow`, `hue`, `ripple`.
+- Still: `blur`, `pixelate`, `grayscale`, and `dissolve` for a node leaving or arriving (its
+  parameter is the progress, 0 to 1).
+
+Animated effects draw every frame while their node is in view; still ones cost nothing once
+drawn.
+
+Your own is a WGSL function over the node's pixels:
+
+```ts
+import { defineEffect } from 'gpucanvas';
+
+const scanlines = defineEffect({
+  name: 'scanlines',
+  animated: true,
+  params: [3], // line spacing in CSS pixels
+  wgsl: /* wgsl */ `
+    fn effect(input: EffectInput) -> vec4f {
+      let color = source(input.uv);
+      let y = input.uv.y * input.size.y + input.time * 20.0;
+      return color * (0.85 + 0.15 * step(0.5, fract(y / input.params.x)));
+    }`,
+});
+```
+
+`EffectInput` has `uv` (0 to 1 across the node), `size` in CSS pixels, `time` in seconds,
+`zoom`, the four `params`, the `pointer` and the last `press` in the node's uv, and
+`sincePress` in seconds. `source(uv)` reads the node's pixels, premultiplied, and is
+transparent outside it; `hash` and `noise` give random values. An effect that draws past its
+node, like a glow, declares how far with `pad`. Effects read the node's whole snapshot, so very
+close in they are softer than plain nodes. In React, `<CanvasNode effect={effects.glass}>` does
+the same.
+
+The DOM backend shows effects that have a `css` look as a CSS `filter` (animated ones as filter
+animations) and the rest as plain nodes. The demo's toolbar puts one effect on every component.
 
 ## Run the demo
 
@@ -60,6 +191,12 @@ bun install
 bun run dev        # http://localhost:5199/?mode=gpu&n=10000  (mode: auto | gpu | dom)
 ```
 
+## Releases
+
+Publishing a GitHub release for a `vX.Y.Z` tag that matches `package.json` publishes the package
+to npm from GitHub Actions, with provenance, through npm trusted publishing. See
+[release.yml](.github/workflows/release.yml).
+
 ## How it works
 
 1. **Pages.** Nodes are live DOM inside `<canvas content="drawable">`, packed side by side into
@@ -75,7 +212,8 @@ bun run dev        # http://localhost:5199/?mode=gpu&n=10000  (mode: auto | gpu
 4. **Tiles up close.** Past 100% zoom on a 2x display, only the visible part of a node is
    rasterized, as sharp tiles, center first. While its content animates, one half-resolution preview stands in.
 5. **One draw call.** Each frame culls nodes against the view and draws every visible one with
-   one instanced quad draw. Panning and zooming never touch the DOM. Raster work has a
+   one instanced quad draw, or one per run of nodes sharing a shader effect. Panning and zooming
+   never touch the DOM. Raster work has a
    per-frame budget, so the camera stays smooth while pixels fill in.
 6. **Live updates.** A MutationObserver marks a node dirty when its content changes, and
    loading images, web fonts and CSS transitions trigger a redraw. Animated content on nodes
@@ -124,6 +262,8 @@ DOM is the same screens in one CSS-transformed container, which is also the fall
 
 ## Next
 
+- **Snapshots as data.** Every node is already a texture: export it as an image without a
+  headless browser, diff two versions of a screen on the GPU, keep a filmstrip of its history.
 - **Keyboard and accessibility.** Parked pages use `content-visibility: hidden`, so Tab skips
   their nodes. A focused node already stays live; moving focus across pages needs a focus model.
 - **Workers.** Composite in a worker with `captureElementImage`, and drive culling from the GPU.