@graview/render 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,96 @@
+Elastic License 2.0
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject
+to the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set
+of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key
+functionality in the software, and you may not remove or obscure any
+functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other
+notices of the licensor in the software. Any use of the licensor's trademarks
+is subject to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license
+for the software granted under these terms ends immediately. If your company
+makes such a claim, your patent license ends immediately for work on behalf
+of your company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from
+you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not
+licensed, and your licenses will automatically terminate. If the licensor
+provides you with a notice of your violation, and you cease all violation of
+this license no later than 30 days after you receive that notice, your
+licenses will be reinstated retroactively. However, if you violate these
+terms after such reinstatement, any additional violation of these terms will
+cause your licenses to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is
+the software the licensor makes available under these terms, including any
+portion of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control
+over, are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of
+an entity, or the power to direct its management and policies by vote,
+contract, or otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your
+licenses.
+
+**trademark** means trademarks, service marks, and similar rights.
+
+---
+
+Copyright 2025-2026 En Dash Consulting

package/README.md

@@ -1,3 +1,44 @@
-# Temporary Holding Version
+# @graview/render
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The spatial renderer: three planes, an affine transform per plane, and
+connectors drawn in SVG over the scene.
+
+## Two paths, and which one ships
+
+**The DOM path is what ships.** Each view is an ordinary element with a CSS
+`matrix3d` — the same affine transform the GPU path uses, applied by the
+browser. It is fully interactive, fully accessible, and every claim this
+project makes about the interface is verified against it.
+
+**The GPU capture path is EXPERIMENTAL.** It rasterises each view's DOM
+subtree with `CanvasDrawElement` and composites the textures with per-plane
+blur, which is the part a shader is genuinely better at. It needs Chrome Canary
+with `--enable-blink-features=CanvasDrawElement`.
+
+It used to bring the renderer process down on a click. That is fixed. The cause
+was not the click: a plain hover over a captured view killed it just as
+reliably, and a keyboard selection of the same node did not. What is fatal is
+the browser's own hit-test descending into a `layoutsubtree` canvas child, so on
+this path the hosts carry `pointer-events: none` and `PointerRouter` answers
+instead — which it had to anyway, because `updateElementGeometry` does not
+redirect hit-testing in this build. `scripts/verify-capture.mjs` holds the
+claim: the pointer survives, a click still reaches the node that was drawn, and
+the keyboard still reaches the views.
+
+It stays experimental for a different reason: capture falls off a cliff past
+~128 live captures a frame, and every other claim this project makes is
+verified against the DOM path.
+
+It is published rather than withheld because `@graview/react` depends on this
+package for the plane model, the transforms and the frame planner, all of which
+both paths share. Opting into the capture path is an explicit
+`attachRenderer` — nothing reaches it by accident.
+
+## What is stable here
+
+- `PLANE_STYLES`, `styleFor`, `mixStyles`, `transformFor` — the plane model.
+- `planFrame` — what to capture, what to draw, where each view lands.
+- `routePointer` — hit-testing a click against drawn geometry.
+
+The compositor, the WGSL and the `html-in-canvas` platform bindings move with
+the browser feature they are built on.

package/dist/gpu.d.ts

@@ -0,0 +1,6 @@
+export { captureElement, captureElementImage, clearElementGeometry, detectCapabilities, IDENTITY, isAffine, perspectiveProbeMatrix, planeTransform, PlatformUnavailableError, requestPaint, setLayoutSubtree, toDOMMatrix, updateElementGeometry, } from "./platform/html-in-canvas.js";
+export type { CaptureMethodName, CaptureSource, ElementImage, GeometryUpdate, Matrix4, PlatformCapabilities, } from "./platform/html-in-canvas.js";
+export { Compositor, packUniform } from "./scene/compositor.js";
+export type { CompositorDeps, CompositorOptions, SceneView, SurfaceLike, VgpuLike, } from "./scene/compositor.js";
+export { COMPOSITOR_WGSL } from "./scene/compositor.wgsl.js";
+//# sourceMappingURL=gpu.d.ts.map

package/dist/gpu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu.d.ts","sourceRoot":"","sources":["../src/gpu.ts"],"names":[],"mappings":"AAmBA,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,QAAQ,EACR,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,qBAAqB,GACtB,MAAM,8BAA8B,CAAC;AACtC,YAAY,EACV,iBAAiB,EACjB,aAAa,EACb,YAAY,EACZ,cAAc,EACd,OAAO,EACP,oBAAoB,GACrB,MAAM,8BAA8B,CAAC;AAGtC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAChE,YAAY,EACV,cAAc,EACd,iBAAiB,EACjB,SAAS,EACT,WAAW,EACX,QAAQ,GACT,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/gpu.js

@@ -0,0 +1,23 @@
+/*
+ * The capture path: rasterise a DOM subtree into a texture and composite the
+ * textures with per-plane blur.
+ *
+ * A separate entry because its declarations name WebGPU globals, which are
+ * ambient rather than importable — a consumer reaching this needs
+ * `@webgpu/types` in their own compilation, and a consumer who never touches
+ * it should not. It is also the experimental half of this package: it needs
+ * Chrome Canary with `--enable-blink-features=CanvasDrawElement`, and capture
+ * falls off a cliff past ~128 live captures a frame.
+ *
+ * The renderer-process crash on pointer input is fixed — the hosts are out of
+ * hit-testing on this path, because the browser's hit-test descending into a
+ * `layoutsubtree` child is what was fatal, not the click. See
+ * `scripts/verify-capture.mjs`.
+ */
+// The platform seam. Every HTML-in-Canvas call in the framework goes here.
+// The platform seam. Every HTML-in-Canvas call in the framework goes here.
+export { captureElement, captureElementImage, clearElementGeometry, detectCapabilities, IDENTITY, isAffine, perspectiveProbeMatrix, planeTransform, PlatformUnavailableError, requestPaint, setLayoutSubtree, toDOMMatrix, updateElementGeometry, } from "./platform/html-in-canvas.js";
+// Capture and composite.
+export { Compositor, packUniform } from "./scene/compositor.js";
+export { COMPOSITOR_WGSL } from "./scene/compositor.wgsl.js";
+//# sourceMappingURL=gpu.js.map

package/dist/gpu.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gpu.js","sourceRoot":"","sources":["../src/gpu.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,2EAA2E;AAC3E,2EAA2E;AAC3E,OAAO,EACL,cAAc,EACd,mBAAmB,EACnB,oBAAoB,EACpB,kBAAkB,EAClB,QAAQ,EACR,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,wBAAwB,EACxB,YAAY,EACZ,gBAAgB,EAChB,WAAW,EACX,qBAAqB,GACtB,MAAM,8BAA8B,CAAC;AAUtC,yBAAyB;AACzB,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,uBAAuB,CAAC;AAQhE,OAAO,EAAE,eAAe,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export { IDENTITY, isAffine, perspectiveProbeMatrix, planeTransform, toDOMMatrix, } from "./platform/matrix.js";
+export type { Matrix4 } from "./platform/matrix.js";
+export { LIGHT_PLANE_STYLES, PLANES, PLANE_STYLES, mixStyles, styleFor, transformFor, } from "./scene/plane.js";
+export type { PlaneIndex, PlaneStyle, Scheme } from "./scene/plane.js";
+export { planFrame } from "./scene/frame-plan.js";
+export type { CaptureCommand, ConnectorDraw, FramePlan, GeometryReport, PlanOptions, PlannedConnector, PlannedView, ViewDraw, } from "./scene/frame-plan.js";
+export { fromLayout } from "./scene/from-layout.js";
+export { CONNECTOR_DASH, connectorStroke, connectorStyle, hueFor, connectorWidth, distinguishable, } from "./scene/connectors.js";
+export type { ConnectorStyle, EndCap, StrokePattern } from "./scene/connectors.js";
+export { PointerRouter, hitTest, invertPlaneTransform, toLocal } from "./interaction/pointer-router.js";
+export type { LocalHit, Placement, PointerRouterOptions } from "./interaction/pointer-router.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAqBA,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAC9B,YAAY,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAGpD,OAAO,EACL,kBAAkB,EAClB,MAAM,EACN,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,YAAY,GACb,MAAM,kBAAkB,CAAC;AAC1B,YAAY,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,kBAAkB,CAAC;AAGvE,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,YAAY,EACV,cAAc,EACd,aAAa,EACb,SAAS,EACT,cAAc,EACd,WAAW,EACX,gBAAgB,EAChB,WAAW,EACX,QAAQ,GACT,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAGpD,OAAO,EACL,cAAc,EACd,eAAe,EACf,cAAc,EACd,MAAM,EACN,cAAc,EACd,eAAe,GAChB,MAAM,uBAAuB,CAAC;AAC/B,YAAY,EAAE,cAAc,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAGnF,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC;AACxG,YAAY,EAAE,QAAQ,EAAE,SAAS,EAAE,oBAAoB,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/index.js

@@ -0,0 +1,31 @@
+/*
+ * The MAIN entry carries no WebGPU types.
+ *
+ * The plane model, the frame planner, the connector treatment and the pointer
+ * router are what every app uses, and they are pure geometry. The capture path
+ * is a different thing: it names `GPUDevice`, `GPUQueue` and `GPUTexture` in
+ * its declarations, and those are ambient globals from `@webgpu/types` rather
+ * than importable ones — so a `.d.ts` mentioning them makes every consumer
+ * install that package to typecheck an import they may never reach.
+ *
+ * Splitting it out is not a workaround. It matches what this package already
+ * says about itself: the DOM path is what ships and the capture path is
+ * experimental, and now the type surface says so too. Reach it explicitly:
+ *
+ *   import { Compositor } from "@graview/render/gpu";
+ *
+ * Found by typechecking a scratch project against the packed tarballs, which
+ * is the only place a public surface's ambient requirements show up.
+ */
+// Affine geometry: pure, and free of any ambient global.
+export { IDENTITY, isAffine, perspectiveProbeMatrix, planeTransform, toDOMMatrix, } from "./platform/matrix.js";
+// The plane model: discrete depths and their atmospheric treatment.
+export { LIGHT_PLANE_STYLES, PLANES, PLANE_STYLES, mixStyles, styleFor, transformFor, } from "./scene/plane.js";
+// The frame, as data: what captures, what draws, and where it lands.
+export { planFrame } from "./scene/frame-plan.js";
+export { fromLayout } from "./scene/from-layout.js";
+// Connector treatment, derived per edge kind.
+export { CONNECTOR_DASH, connectorStroke, connectorStyle, hueFor, connectorWidth, distinguishable, } from "./scene/connectors.js";
+// Pointer routing, until the platform redirects hit-testing itself.
+export { PointerRouter, hitTest, invertPlaneTransform, toLocal } from "./interaction/pointer-router.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,yDAAyD;AACzD,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,WAAW,GACZ,MAAM,sBAAsB,CAAC;AAG9B,oEAAoE;AACpE,OAAO,EACL,kBAAkB,EAClB,MAAM,EACN,YAAY,EACZ,SAAS,EACT,QAAQ,EACR,YAAY,GACb,MAAM,kBAAkB,CAAC;AAG1B,qEAAqE;AACrE,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAWlD,OAAO,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAC;AAEpD,8CAA8C;AAC9C,OAAO,EACL,cAAc,EACd,eAAe,EACf,cAAc,EACd,MAAM,EACN,cAAc,EACd,eAAe,GAChB,MAAM,uBAAuB,CAAC;AAG/B,oEAAoE;AACpE,OAAO,EAAE,aAAa,EAAE,OAAO,EAAE,oBAAoB,EAAE,OAAO,EAAE,MAAM,iCAAiC,CAAC"}

package/dist/interaction/pointer-router.d.ts

@@ -0,0 +1,94 @@
+import type { Matrix4 } from "../platform/matrix.js";
+/**
+ * Routes pointer events against where views were DRAWN, not where their
+ * source elements are laid out.
+ *
+ * This exists because of a measured platform gap, not a design preference:
+ * `updateElementGeometry` is accepted by Chromium 154 and does not redirect
+ * hit-testing (see `docs/platform-findings.md`). Keep calling it — it costs
+ * nothing and will start working — and route pointers here meanwhile, so the
+ * zoomed-out scene stays interactive rather than becoming a picture.
+ *
+ * Accessibility does NOT need this fallback: the source elements remain real,
+ * focusable DOM inside the `layoutsubtree` canvas, which the probe confirmed.
+ */
+export interface Placement {
+    /** The live element this quad was captured from. */
+    readonly element: Element;
+    /** Where it was drawn, in canvas pixels. Affine only. */
+    readonly transform: Matrix4;
+    /** The element's own size in CSS pixels, before the transform. */
+    readonly width: number;
+    readonly height: number;
+    /** Higher wins when quads overlap — plane 0 is nearest the viewer. */
+    readonly depth: number;
+}
+export interface LocalHit {
+    readonly placement: Placement;
+    /** Coordinates inside the element's own box, in CSS pixels. */
+    readonly x: number;
+    readonly y: number;
+}
+/**
+ * Inverts the affine part of a column-major 4x4 that only ever carries
+ * scale and translation in x/y. Restricting the shape is what makes the
+ * inverse exact and cheap — and the plane model emits nothing else.
+ */
+export declare function invertPlaneTransform(transform: Matrix4): {
+    scaleX: number;
+    scaleY: number;
+    translateX: number;
+    translateY: number;
+} | null;
+/** Canvas-space point to element-local point, or null if outside the quad. */
+export declare function toLocal(placement: Placement, canvasX: number, canvasY: number): LocalHit | null;
+/**
+ * The topmost placement under a canvas-space point. Depth ordering is
+ * explicit rather than array order, so a renderer may draw back-to-front
+ * without changing what a click means.
+ */
+export declare function hitTest(placements: readonly Placement[], canvasX: number, canvasY: number): LocalHit | null;
+export interface PointerRouterOptions {
+    /**
+     * Set true once a browser redirects hit-testing itself, to stand the
+     * router down rather than double-handling every event.
+     */
+    readonly platformHandlesHitTesting?: boolean;
+    /** Events to intercept. Defaults to the ones a view actually needs. */
+    readonly events?: readonly string[];
+}
+/**
+ * Attaches to the scene canvas, maps each pointer event onto the element that
+ * was drawn under the cursor, and replays it there.
+ *
+ * The replay targets the deepest real element at the corresponding point of
+ * the source element's own layout box — the source subtree is still laid out
+ * and hit-testable at its layout position, so the browser's own hit-testing
+ * does the hard part and this only has to move the coordinates.
+ */
+export declare class PointerRouter {
+    private readonly canvas;
+    private readonly options;
+    private placements;
+    private readonly detachers;
+    private replaying;
+    constructor(canvas: HTMLCanvasElement, options?: PointerRouterOptions);
+    /** Called by the renderer every time the scene's geometry changes. */
+    setPlacements(placements: readonly Placement[]): void;
+    attach(): () => void;
+    detach(): void;
+    /**
+     * The deepest real element at the corresponding point inside the source
+     * view's own layout box.
+     *
+     * `elementFromPoint` is not enough here: under `layoutsubtree` every
+     * immediate child of the canvas is laid out at the canvas origin, so all
+     * views stack on top of each other in layout space and the singular call
+     * always returns whichever one is topmost. Walking `elementsFromPoint` and
+     * taking the first hit that belongs to the view we actually want is what
+     * makes routing correct with overlapping views.
+     */
+    private deepestAt;
+    private route;
+}
+//# sourceMappingURL=pointer-router.d.ts.map

package/dist/interaction/pointer-router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer-router.d.ts","sourceRoot":"","sources":["../../src/interaction/pointer-router.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAC;AAErD;;;;;;;;;;;;GAYG;AAEH,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,sEAAsE;IACtE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,OAAO,GACjB;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAUnF;AAED,8EAA8E;AAC9E,wBAAgB,OAAO,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI,CAO/F;AAED;;;;GAIG;AACH,wBAAgB,OAAO,CACrB,UAAU,EAAE,SAAS,SAAS,EAAE,EAChC,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,QAAQ,GAAG,IAAI,CAQjB;AAED,MAAM,WAAW,oBAAoB;IACnC;;;OAGG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,OAAO,CAAC;IAC7C,uEAAuE;IACvE,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAID;;;;;;;;GAQG;AACH,qBAAa,aAAa;IAMtB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO;IAN1B,OAAO,CAAC,UAAU,CAA4B;IAC9C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAsB;IAChD,OAAO,CAAC,SAAS,CAAS;gBAGP,MAAM,EAAE,iBAAiB,EACzB,OAAO,GAAE,oBAAyB;IAGrD,sEAAsE;IACtE,aAAa,CAAC,UAAU,EAAE,SAAS,SAAS,EAAE,GAAG,IAAI;IAIrD,MAAM,IAAI,MAAM,IAAI;IAUpB,MAAM,IAAI,IAAI;IAId;;;;;;;;;;OAUG;IACH,OAAO,CAAC,SAAS;IAejB,OAAO,CAAC,KAAK;CA4Cd"}

package/dist/interaction/pointer-router.js

@@ -0,0 +1,148 @@
+/**
+ * Inverts the affine part of a column-major 4x4 that only ever carries
+ * scale and translation in x/y. Restricting the shape is what makes the
+ * inverse exact and cheap — and the plane model emits nothing else.
+ */
+export function invertPlaneTransform(transform) {
+    const scaleX = transform[0];
+    const scaleY = transform[5];
+    if (scaleX === 0 || scaleY === 0)
+        return null;
+    return {
+        scaleX: 1 / scaleX,
+        scaleY: 1 / scaleY,
+        translateX: transform[12],
+        translateY: transform[13],
+    };
+}
+/** Canvas-space point to element-local point, or null if outside the quad. */
+export function toLocal(placement, canvasX, canvasY) {
+    const inverse = invertPlaneTransform(placement.transform);
+    if (!inverse)
+        return null;
+    const x = (canvasX - inverse.translateX) * inverse.scaleX;
+    const y = (canvasY - inverse.translateY) * inverse.scaleY;
+    if (x < 0 || y < 0 || x > placement.width || y > placement.height)
+        return null;
+    return { placement, x, y };
+}
+/**
+ * The topmost placement under a canvas-space point. Depth ordering is
+ * explicit rather than array order, so a renderer may draw back-to-front
+ * without changing what a click means.
+ */
+export function hitTest(placements, canvasX, canvasY) {
+    let best = null;
+    for (const placement of placements) {
+        const hit = toLocal(placement, canvasX, canvasY);
+        if (!hit)
+            continue;
+        if (!best || placement.depth < best.placement.depth)
+            best = hit;
+    }
+    return best;
+}
+const DEFAULT_EVENTS = ["pointerdown", "pointerup", "click", "dblclick", "contextmenu"];
+/**
+ * Attaches to the scene canvas, maps each pointer event onto the element that
+ * was drawn under the cursor, and replays it there.
+ *
+ * The replay targets the deepest real element at the corresponding point of
+ * the source element's own layout box — the source subtree is still laid out
+ * and hit-testable at its layout position, so the browser's own hit-testing
+ * does the hard part and this only has to move the coordinates.
+ */
+export class PointerRouter {
+    canvas;
+    options;
+    placements = [];
+    detachers = [];
+    replaying = false;
+    constructor(canvas, options = {}) {
+        this.canvas = canvas;
+        this.options = options;
+    }
+    /** Called by the renderer every time the scene's geometry changes. */
+    setPlacements(placements) {
+        this.placements = placements;
+    }
+    attach() {
+        if (this.options.platformHandlesHitTesting)
+            return () => { };
+        for (const type of this.options.events ?? DEFAULT_EVENTS) {
+            const handler = (event) => this.route(event);
+            this.canvas.addEventListener(type, handler, true);
+            this.detachers.push(() => this.canvas.removeEventListener(type, handler, true));
+        }
+        return () => this.detach();
+    }
+    detach() {
+        for (const detach of this.detachers.splice(0))
+            detach();
+    }
+    /**
+     * The deepest real element at the corresponding point inside the source
+     * view's own layout box.
+     *
+     * `elementFromPoint` is not enough here: under `layoutsubtree` every
+     * immediate child of the canvas is laid out at the canvas origin, so all
+     * views stack on top of each other in layout space and the singular call
+     * always returns whichever one is topmost. Walking `elementsFromPoint` and
+     * taking the first hit that belongs to the view we actually want is what
+     * makes routing correct with overlapping views.
+     */
+    deepestAt(hit) {
+        const view = hit.placement.element;
+        const rect = view.getBoundingClientRect();
+        const x = rect.left + hit.x;
+        const y = rect.top + hit.y;
+        const stack = typeof document.elementsFromPoint === "function"
+            ? document.elementsFromPoint(x, y)
+            : [document.elementFromPoint(x, y)].filter((el) => el !== null);
+        for (const candidate of stack) {
+            if (candidate === view || view.contains(candidate))
+                return candidate;
+        }
+        return view;
+    }
+    route(event) {
+        if (this.replaying)
+            return;
+        const rect = this.canvas.getBoundingClientRect();
+        const hit = hitTest(this.placements, event.clientX - rect.left, event.clientY - rect.top);
+        if (!hit)
+            return;
+        const view = hit.placement.element;
+        const sourceRect = view.getBoundingClientRect();
+        const target = this.deepestAt(hit);
+        event.preventDefault();
+        event.stopPropagation();
+        this.replaying = true;
+        try {
+            target.dispatchEvent(new PointerEvent(event.type, {
+                bubbles: true,
+                cancelable: true,
+                composed: true,
+                clientX: sourceRect.left + hit.x,
+                clientY: sourceRect.top + hit.y,
+                pointerId: event.pointerId,
+                pointerType: event.pointerType,
+                button: event.button,
+                buttons: event.buttons,
+                ctrlKey: event.ctrlKey,
+                shiftKey: event.shiftKey,
+                altKey: event.altKey,
+                metaKey: event.metaKey,
+            }));
+            if (event.type === "pointerdown" && target instanceof HTMLElement) {
+                // Focus follows the pointer, so keyboard use continues from where the
+                // click landed rather than from the canvas.
+                target.focus({ preventScroll: true });
+            }
+        }
+        finally {
+            this.replaying = false;
+        }
+    }
+}
+//# sourceMappingURL=pointer-router.js.map

package/dist/interaction/pointer-router.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"pointer-router.js","sourceRoot":"","sources":["../../src/interaction/pointer-router.ts"],"names":[],"mappings":"AAmCA;;;;GAIG;AACH,MAAM,UAAU,oBAAoB,CAClC,SAAkB;IAElB,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAC5B,MAAM,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC,CAAC;IAC5B,IAAI,MAAM,KAAK,CAAC,IAAI,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAC;IAC9C,OAAO;QACL,MAAM,EAAE,CAAC,GAAG,MAAM;QAClB,MAAM,EAAE,CAAC,GAAG,MAAM;QAClB,UAAU,EAAE,SAAS,CAAC,EAAE,CAAC;QACzB,UAAU,EAAE,SAAS,CAAC,EAAE,CAAC;KAC1B,CAAC;AACJ,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,OAAO,CAAC,SAAoB,EAAE,OAAe,EAAE,OAAe;IAC5E,MAAM,OAAO,GAAG,oBAAoB,CAAC,SAAS,CAAC,SAAS,CAAC,CAAC;IAC1D,IAAI,CAAC,OAAO;QAAE,OAAO,IAAI,CAAC;IAC1B,MAAM,CAAC,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAC1D,MAAM,CAAC,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC,UAAU,CAAC,GAAG,OAAO,CAAC,MAAM,CAAC;IAC1D,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,SAAS,CAAC,KAAK,IAAI,CAAC,GAAG,SAAS,CAAC,MAAM;QAAE,OAAO,IAAI,CAAC;IAC/E,OAAO,EAAE,SAAS,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AAC7B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,OAAO,CACrB,UAAgC,EAChC,OAAe,EACf,OAAe;IAEf,IAAI,IAAI,GAAoB,IAAI,CAAC;IACjC,KAAK,MAAM,SAAS,IAAI,UAAU,EAAE,CAAC;QACnC,MAAM,GAAG,GAAG,OAAO,CAAC,SAAS,EAAE,OAAO,EAAE,OAAO,CAAC,CAAC;QACjD,IAAI,CAAC,GAAG;YAAE,SAAS;QACnB,IAAI,CAAC,IAAI,IAAI,SAAS,CAAC,KAAK,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK;YAAE,IAAI,GAAG,GAAG,CAAC;IAClE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAYD,MAAM,cAAc,GAAG,CAAC,aAAa,EAAE,WAAW,EAAE,OAAO,EAAE,UAAU,EAAE,aAAa,CAAC,CAAC;AAExF;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAa;IAML;IACA;IANX,UAAU,GAAyB,EAAE,CAAC;IAC7B,SAAS,GAAmB,EAAE,CAAC;IACxC,SAAS,GAAG,KAAK,CAAC;IAE1B,YACmB,MAAyB,EACzB,UAAgC,EAAE;QADlC,WAAM,GAAN,MAAM,CAAmB;QACzB,YAAO,GAAP,OAAO,CAA2B;IAClD,CAAC;IAEJ,sEAAsE;IACtE,aAAa,CAAC,UAAgC;QAC5C,IAAI,CAAC,UAAU,GAAG,UAAU,CAAC;IAC/B,CAAC;IAED,MAAM;QACJ,IAAI,IAAI,CAAC,OAAO,CAAC,yBAAyB;YAAE,OAAO,GAAG,EAAE,GAAE,CAAC,CAAC;QAC5D,KAAK,MAAM,IAAI,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,cAAc,EAAE,CAAC;YACzD,MAAM,OAAO,GAAG,CAAC,KAAY,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,KAAqB,CAAC,CAAC;YACpE,IAAI,CAAC,MAAM,CAAC,gBAAgB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC;YAClD,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,IAAI,CAAC,CAAC,CAAC;QAClF,CAAC;QACD,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,MAAM,EAAE,CAAC;IAC7B,CAAC;IAED,MAAM;QACJ,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC,CAAC;YAAE,MAAM,EAAE,CAAC;IAC1D,CAAC;IAED;;;;;;;;;;OAUG;IACK,SAAS,CAAC,GAAa;QAC7B,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC;QACnC,MAAM,IAAI,GAAG,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAC1C,MAAM,CAAC,GAAG,IAAI,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC,CAAC;QAC5B,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC,CAAC;QAC3B,MAAM,KAAK,GACT,OAAO,QAAQ,CAAC,iBAAiB,KAAK,UAAU;YAC9C,CAAC,CAAC,QAAQ,CAAC,iBAAiB,CAAC,CAAC,EAAE,CAAC,CAAC;YAClC,CAAC,CAAC,CAAC,QAAQ,CAAC,gBAAgB,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,EAAiB,EAAE,CAAC,EAAE,KAAK,IAAI,CAAC,CAAC;QACnF,KAAK,MAAM,SAAS,IAAI,KAAK,EAAE,CAAC;YAC9B,IAAI,SAAS,KAAK,IAAI,IAAI,IAAI,CAAC,QAAQ,CAAC,SAAS,CAAC;gBAAE,OAAO,SAAS,CAAC;QACvE,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAEO,KAAK,CAAC,KAAmB;QAC/B,IAAI,IAAI,CAAC,SAAS;YAAE,OAAO;QAC3B,MAAM,IAAI,GAAG,IAAI,CAAC,MAAM,CAAC,qBAAqB,EAAE,CAAC;QACjD,MAAM,GAAG,GAAG,OAAO,CACjB,IAAI,CAAC,UAAU,EACf,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,IAAI,EACzB,KAAK,CAAC,OAAO,GAAG,IAAI,CAAC,GAAG,CACzB,CAAC;QACF,IAAI,CAAC,GAAG;YAAE,OAAO;QAEjB,MAAM,IAAI,GAAG,GAAG,CAAC,SAAS,CAAC,OAAO,CAAC;QACnC,MAAM,UAAU,GAAG,IAAI,CAAC,qBAAqB,EAAE,CAAC;QAChD,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC;QAEnC,KAAK,CAAC,cAAc,EAAE,CAAC;QACvB,KAAK,CAAC,eAAe,EAAE,CAAC;QACxB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC;YACH,MAAM,CAAC,aAAa,CAClB,IAAI,YAAY,CAAC,KAAK,CAAC,IAAI,EAAE;gBAC3B,OAAO,EAAE,IAAI;gBACb,UAAU,EAAE,IAAI;gBAChB,QAAQ,EAAE,IAAI;gBACd,OAAO,EAAE,UAAU,CAAC,IAAI,GAAG,GAAG,CAAC,CAAC;gBAChC,OAAO,EAAE,UAAU,CAAC,GAAG,GAAG,GAAG,CAAC,CAAC;gBAC/B,SAAS,EAAE,KAAK,CAAC,SAAS;gBAC1B,WAAW,EAAE,KAAK,CAAC,WAAW;gBAC9B,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,OAAO,EAAE,KAAK,CAAC,OAAO;gBACtB,QAAQ,EAAE,KAAK,CAAC,QAAQ;gBACxB,MAAM,EAAE,KAAK,CAAC,MAAM;gBACpB,OAAO,EAAE,KAAK,CAAC,OAAO;aACvB,CAAC,CACH,CAAC;YACF,IAAI,KAAK,CAAC,IAAI,KAAK,aAAa,IAAI,MAAM,YAAY,WAAW,EAAE,CAAC;gBAClE,sEAAsE;gBACtE,4CAA4C;gBAC5C,MAAM,CAAC,KAAK,CAAC,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC,CAAC;YACxC,CAAC;QACH,CAAC;gBAAS,CAAC;YACT,IAAI,CAAC,SAAS,GAAG,KAAK,CAAC;QACzB,CAAC;IACH,CAAC;CACF"}

package/dist/platform/html-in-canvas.d.ts

@@ -0,0 +1,100 @@
+/**
+ * THE platform seam. Every call into the HTML-in-Canvas API passes through
+ * this module and nowhere else.
+ *
+ * The API is mid-origin-trial and its naming is still settling — the WICG
+ * README calls the capture entry point `drawElementImageToTexture` in one
+ * place and `copyElementImageToTexture` in another — so the whole surface is
+ * resolved once, at runtime, behind names of our own. When the spec settles,
+ * exactly one file changes.
+ *
+ * Verified against Chrome Canary 154.0.8032.0 with
+ * `--enable-blink-features=CanvasDrawElement`. What that build actually
+ * exposes, and the exact call shapes, are recorded in
+ * `docs/platform-findings.md`; the shapes below are what it accepts, not what
+ * the README suggests.
+ */
+import { IDENTITY, isAffine, perspectiveProbeMatrix, planeTransform, toDOMMatrix, type Matrix4 } from "./matrix.js";
+export { IDENTITY, isAffine, perspectiveProbeMatrix, planeTransform, toDOMMatrix };
+export type { Matrix4 };
+export type CaptureMethodName = "drawElementImageToTexture" | "copyElementImageToTexture";
+/** A 4x4 column-major matrix, the shape `canvasTransform` expects. */
+export interface ElementImage {
+    readonly width: number;
+    readonly height: number;
+    close(): void;
+}
+/** What may be captured or positioned: the live element, or its paint record. */
+export type CaptureSource = Element | ElementImage;
+export interface GeometryUpdate {
+    /** Where the element was actually drawn, in canvas space. */
+    readonly canvasTransform: Matrix4 | DOMMatrix;
+}
+export interface PlatformCapabilities {
+    /** The API is present in some form. */
+    readonly available: boolean;
+    /** Which spelling of the capture call this build exposes. */
+    readonly captureMethod: CaptureMethodName | null;
+    /** `updateElementGeometry` is present, so geometry can be reported. */
+    readonly geometrySync: boolean;
+    /**
+     * Whether reporting geometry actually redirects hit-testing. Separate from
+     * `geometrySync` on purpose: Chromium 154 accepts the call and ignores it
+     * for hit-testing, and the difference is the difference between an
+     * interactive scene and a picture.
+     */
+    readonly hitTestFollowsGeometry: "yes" | "no" | "unknown";
+    /** The canvas supports `layoutsubtree`. */
+    readonly layoutSubtree: boolean;
+    /** `paint` events and `requestPaint()` — the capture-safe moment. */
+    readonly paintEvents: boolean;
+    readonly webgpu: boolean;
+    /** Everything needed to composite views at depth. */
+    readonly usable: boolean;
+    readonly notes: readonly string[];
+}
+/**
+ * Resolves what this browser can actually do. Called once; everything else in
+ * the renderer branches on the result rather than sniffing again.
+ */
+export declare function detectCapabilities(queue?: GPUQueue, canvas?: HTMLCanvasElement): PlatformCapabilities;
+export declare class PlatformUnavailableError extends Error {
+    readonly capabilities: PlatformCapabilities;
+    constructor(capabilities: PlatformCapabilities);
+}
+/**
+ * Captures a DOM element (or a previously taken paint record) into an
+ * existing GPU texture.
+ *
+ * Two preconditions the errors do not make obvious:
+ * - the element must be a descendant of a `<canvas layoutsubtree>`, and
+ * - that canvas must have a CONFIGURED WebGPU context of its own, or the call
+ *   fails with "containing canvas does not have a rendering context".
+ *
+ * The texture is written in place, so the caller keeps ownership and no copy
+ * happens on our side.
+ */
+export declare function captureElement(queue: GPUQueue, source: CaptureSource, texture: GPUTexture): void;
+/**
+ * Takes a cached paint record for an element. Only valid inside a `paint`
+ * event — outside one the browser has no paint record and throws
+ * `InvalidStateError`.
+ */
+export declare function captureElementImage(canvas: HTMLCanvasElement, element: Element): ElementImage;
+/**
+ * Tells the browser where an element was actually drawn.
+ *
+ * The intent of the spec is that hit-testing, focus order, screen readers and
+ * find-in-page then resolve against the drawn pixels. In Chromium 154 the
+ * call is accepted and has no observable effect on hit-testing — see
+ * `docs/platform-findings.md`. Call it anyway (it costs nothing and will
+ * start working), and route pointers through `PointerRouter` meanwhile.
+ */
+export declare function updateElementGeometry(canvas: HTMLCanvasElement, source: CaptureSource, update: GeometryUpdate): void;
+/** Drops a reported geometry, returning the element to its layout position. */
+export declare function clearElementGeometry(canvas: HTMLCanvasElement, source: CaptureSource): void;
+/** Asks for a `paint` event — the moment at which capture is legal. */
+export declare function requestPaint(canvas: HTMLCanvasElement): void;
+/** Marks a canvas as owning its descendants' layout. */
+export declare function setLayoutSubtree(canvas: HTMLCanvasElement, on?: boolean): void;
+//# sourceMappingURL=html-in-canvas.d.ts.map

package/dist/platform/html-in-canvas.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"html-in-canvas.d.ts","sourceRoot":"","sources":["../../src/platform/html-in-canvas.ts"],"names":[],"mappings":"AAcA;;;;;;;;;;;;;;;GAeG;AAEH,OAAO,EACL,QAAQ,EACR,QAAQ,EACR,sBAAsB,EACtB,cAAc,EACd,WAAW,EACX,KAAK,OAAO,EACb,MAAM,aAAa,CAAC;AAErB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,sBAAsB,EAAE,cAAc,EAAE,WAAW,EAAE,CAAC;AACnF,YAAY,EAAE,OAAO,EAAE,CAAC;AAExB,MAAM,MAAM,iBAAiB,GACzB,2BAA2B,GAC3B,2BAA2B,CAAC;AAOhC,sEAAsE;AACtE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,KAAK,IAAI,IAAI,CAAC;CACf;AAED,iFAAiF;AACjF,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,YAAY,CAAC;AAEnD,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,eAAe,EAAE,OAAO,GAAG,SAAS,CAAC;CAC/C;AAED,MAAM,WAAW,oBAAoB;IACnC,uCAAuC;IACvC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACjD,uEAAuE;IACvE,QAAQ,CAAC,YAAY,EAAE,OAAO,CAAC;IAC/B;;;;;OAKG;IACH,QAAQ,CAAC,sBAAsB,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC;IAC1D,2CAA2C;IAC3C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,qDAAqD;IACrD,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,CAAC;CACnC;AAoBD;;;GAGG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,CAAC,EAAE,QAAQ,EAChB,MAAM,CAAC,EAAE,iBAAiB,GACzB,oBAAoB,CA0DtB;AAED,qBAAa,wBAAyB,SAAQ,KAAK;IACrC,QAAQ,CAAC,YAAY,EAAE,oBAAoB;gBAAlC,YAAY,EAAE,oBAAoB;CAIxD;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,QAAQ,EACf,MAAM,EAAE,aAAa,EACrB,OAAO,EAAE,UAAU,GAClB,IAAI,CAUN;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,iBAAiB,EACzB,OAAO,EAAE,OAAO,GACf,YAAY,CAMd;AAED;;;;;;;;GAQG;AACH,wBAAgB,qBAAqB,CACnC,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,aAAa,EACrB,MAAM,EAAE,cAAc,GACrB,IAAI,CAMN;AAED,+EAA+E;AAC/E,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,iBAAiB,EACzB,MAAM,EAAE,aAAa,GACpB,IAAI,CAEN;AAED,uEAAuE;AACvE,wBAAgB,YAAY,CAAC,MAAM,EAAE,iBAAiB,GAAG,IAAI,CAE5D;AAED,wDAAwD;AACxD,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,iBAAiB,EAAE,EAAE,UAAO,GAAG,IAAI,CAK3E"}