gpucanvas 0.2.0 → 0.3.0

package/README.md

@@ -18,7 +18,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 +41,128 @@ 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
 
-Selected nodes get an outline drawn by the GPU, 2 CSS pixels wide at any zoom.
+`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
-const hits = canvas.getNodesIn({ x, y, width, height }); // world units, such as a selection box
-canvas.setSelection(hits); // replaces the selection; [] clears it
+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.
+  },
+});
 ```
 
-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.
+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        |
+
+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
+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
+```
+
+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.
+
+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