@grafloria/element 0.3.18 → 0.3.20

package/src/libs/renderer/src/canvas/canvas-context.js

@@ -0,0 +1,267 @@
+"use strict";
+// canvas-context.ts — the 2D-context surface the painter is allowed to use,
+// plus a RECORDING implementation of it.
+//
+// Two reasons the painter talks to an interface instead of
+// `CanvasRenderingContext2D` directly:
+//
+//   1. TESTABILITY. `libs/renderer` is framework-agnostic and its tests run in
+//      jsdom, which has no rasteriser. A recording context turns "what did the
+//      canvas backend draw?" into an ordinary, assertable data structure — the
+//      draw-call sequence — so canvas output can be diffed against the VNode
+//      tree exactly, with no image snapshots and no `node-canvas` dependency.
+//
+//   2. A SMALL, HONEST SURFACE. The painter normalises every SVG primitive to
+//      path commands (see path-geometry.ts), so it only ever needs move/line/
+//      cubic/quad/close + fill/stroke/clip + text. That is the whole interface
+//      below. A backend that can implement these can render a Grafloria diagram.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NULL_CONTEXT = exports.RecordingContext2D = void 0;
+/**
+ * A `Canvas2DLike` that records what was drawn instead of rasterising it.
+ *
+ * The recording is the assertion surface for the canvas backend's unit tests:
+ * "the VNode tree said `<rect fill=#fff stroke=#333 stroke-width=2>` at
+ * (100,100)" ⇒ "the context received a fill with fillStyle #fff and a stroke
+ * with lineWidth 2 over exactly that path, under exactly that transform".
+ *
+ * It faithfully models the parts of the 2D state machine the painter depends on
+ * — the save/restore stack, the current transform, the current path — so a bug
+ * in the painter's state handling (a missing `restore`, a transform applied
+ * twice) shows up in the recording rather than hiding behind a mock.
+ */
+class RecordingContext2D {
+    constructor() {
+        this.calls = [];
+        this.stack = [];
+        this.state = {
+            fillStyle: '#000000',
+            strokeStyle: '#000000',
+            lineWidth: 1,
+            lineJoin: 'miter',
+            lineCap: 'butt',
+            globalAlpha: 1,
+            font: '10px sans-serif',
+            textAlign: 'start',
+            textBaseline: 'alphabetic',
+            filter: 'none',
+            lineDash: [],
+            transform: { a: 1, b: 0, c: 0, d: 1, e: 0, f: 0 },
+        };
+        this.path = [];
+        /** Width of one character, used by `measureText`. Matches the SVG-side estimate. */
+        this.charWidthRatio = 0.6;
+    }
+    get fillStyle() {
+        return this.state.fillStyle;
+    }
+    set fillStyle(v) {
+        this.state.fillStyle = v;
+    }
+    get strokeStyle() {
+        return this.state.strokeStyle;
+    }
+    set strokeStyle(v) {
+        this.state.strokeStyle = v;
+    }
+    get lineWidth() {
+        return this.state.lineWidth;
+    }
+    set lineWidth(v) {
+        this.state.lineWidth = v;
+    }
+    get lineJoin() {
+        return this.state.lineJoin;
+    }
+    set lineJoin(v) {
+        this.state.lineJoin = v;
+    }
+    get lineCap() {
+        return this.state.lineCap;
+    }
+    set lineCap(v) {
+        this.state.lineCap = v;
+    }
+    get globalAlpha() {
+        return this.state.globalAlpha;
+    }
+    set globalAlpha(v) {
+        this.state.globalAlpha = v;
+    }
+    get font() {
+        return this.state.font;
+    }
+    set font(v) {
+        this.state.font = v;
+    }
+    get textAlign() {
+        return this.state.textAlign;
+    }
+    set textAlign(v) {
+        this.state.textAlign = v;
+    }
+    get textBaseline() {
+        return this.state.textBaseline;
+    }
+    set textBaseline(v) {
+        this.state.textBaseline = v;
+    }
+    get filter() {
+        return this.state.filter;
+    }
+    set filter(v) {
+        this.state.filter = v;
+    }
+    save() {
+        this.stack.push(Object.assign(Object.assign({}, this.state), { lineDash: [...this.state.lineDash] }));
+        this.calls.push({ op: 'save' });
+    }
+    restore() {
+        const prev = this.stack.pop();
+        if (prev)
+            this.state = prev;
+        this.calls.push({ op: 'restore' });
+    }
+    setTransform(a, b, c, d, e, f) {
+        this.state.transform = { a, b, c, d, e, f };
+        this.calls.push({ op: 'setTransform', transform: { a, b, c, d, e, f } });
+    }
+    beginPath() {
+        this.path = [];
+    }
+    moveTo(x, y) {
+        this.path.push({ op: 'M', x, y });
+    }
+    lineTo(x, y) {
+        this.path.push({ op: 'L', x, y });
+    }
+    bezierCurveTo(x1, y1, x2, y2, x, y) {
+        this.path.push({ op: 'C', x1, y1, x2, y2, x, y });
+    }
+    quadraticCurveTo(x1, y1, x, y) {
+        this.path.push({ op: 'Q', x1, y1, x, y });
+    }
+    closePath() {
+        this.path.push({ op: 'Z' });
+    }
+    fill() {
+        this.calls.push(Object.assign({ op: 'fill', path: [...this.path], fillStyle: this.state.fillStyle, globalAlpha: this.state.globalAlpha, transform: Object.assign({}, this.state.transform) }, (this.state.filter && this.state.filter !== 'none' ? { filter: this.state.filter } : {})));
+    }
+    stroke() {
+        this.calls.push(Object.assign({ op: 'stroke', path: [...this.path], strokeStyle: this.state.strokeStyle, lineWidth: this.state.lineWidth, lineDash: [...this.state.lineDash], globalAlpha: this.state.globalAlpha, transform: Object.assign({}, this.state.transform) }, (this.state.filter && this.state.filter !== 'none' ? { filter: this.state.filter } : {})));
+    }
+    clip() {
+        this.calls.push({ op: 'clip', path: [...this.path], transform: Object.assign({}, this.state.transform) });
+    }
+    clearRect(x, y, w, h) {
+        this.calls.push({ op: 'clearRect', x, y, w, h, transform: Object.assign({}, this.state.transform) });
+    }
+    fillRect(x, y, w, h) {
+        this.calls.push({
+            op: 'fillRect',
+            x,
+            y,
+            w,
+            h,
+            fillStyle: this.state.fillStyle,
+            transform: Object.assign({}, this.state.transform),
+        });
+    }
+    setLineDash(segments) {
+        this.state.lineDash = [...segments];
+    }
+    fillText(text, x, y) {
+        this.calls.push({
+            op: 'fillText',
+            text,
+            x,
+            y,
+            font: this.state.font,
+            fillStyle: this.state.fillStyle,
+            textAlign: this.state.textAlign,
+            textBaseline: this.state.textBaseline,
+            globalAlpha: this.state.globalAlpha,
+            transform: Object.assign({}, this.state.transform),
+        });
+    }
+    /**
+     * The same average-glyph estimate the SVG text-block engine uses
+     * (`text.length * fontSize * 0.6`), so headless measurement agrees with the
+     * line-breaking the VNode producer already did. A real 2D context measures
+     * glyphs properly; this is only the headless stand-in.
+     */
+    measureText(text) {
+        var _a, _b;
+        const size = parseFloat((_b = (_a = /(\d+(?:\.\d+)?)px/.exec(this.state.font)) === null || _a === void 0 ? void 0 : _a[1]) !== null && _b !== void 0 ? _b : '12');
+        return { width: text.length * size * this.charWidthRatio };
+    }
+    createLinearGradient(x0, y0, x1, y1) {
+        const stops = [];
+        return {
+            __gradient: 'linear',
+            x0,
+            y0,
+            x1,
+            y1,
+            stops,
+            addColorStop(offset, color) {
+                stops.push({ offset, color });
+            },
+        };
+    }
+    createRadialGradient(x0, y0, r0, x1, y1, r1) {
+        const stops = [];
+        return {
+            __gradient: 'radial',
+            x0,
+            y0,
+            r0,
+            x1,
+            y1,
+            r1,
+            stops,
+            addColorStop(offset, color) {
+                stops.push({ offset, color });
+            },
+        };
+    }
+    /** Drop the recording (keeps the current state — mirrors a fresh frame). */
+    reset() {
+        this.calls.length = 0;
+    }
+    /** Every paint call (ignores bookkeeping ops) — the usual assertion target. */
+    paintCalls() {
+        return this.calls.filter((c) => c.op === 'fill' || c.op === 'stroke' || c.op === 'fillText' || c.op === 'fillRect');
+    }
+}
+exports.RecordingContext2D = RecordingContext2D;
+/** A `Canvas2DLike` that does nothing — the measure pass draws into it. */
+exports.NULL_CONTEXT = {
+    fillStyle: '',
+    strokeStyle: '',
+    lineWidth: 1,
+    lineJoin: 'miter',
+    lineCap: 'butt',
+    globalAlpha: 1,
+    font: '',
+    textAlign: 'start',
+    textBaseline: 'alphabetic',
+    save: () => undefined,
+    restore: () => undefined,
+    setTransform: () => undefined,
+    beginPath: () => undefined,
+    moveTo: () => undefined,
+    lineTo: () => undefined,
+    bezierCurveTo: () => undefined,
+    quadraticCurveTo: () => undefined,
+    closePath: () => undefined,
+    fill: () => undefined,
+    stroke: () => undefined,
+    clip: () => undefined,
+    clearRect: () => undefined,
+    fillRect: () => undefined,
+    setLineDash: () => undefined,
+    fillText: () => undefined,
+    measureText: (text) => ({ width: text.length * 6 }),
+};
+//# sourceMappingURL=canvas-context.js.map

package/src/libs/renderer/src/canvas/canvas-renderer.d.ts

@@ -0,0 +1,194 @@
+import type { DiagramEngine } from '@grafloria/engine';
+import type { ExportFormat, ExportOptions, IRenderer, PerformanceMetrics, RendererCapabilities, SVGRendererConfig, TextStyle, TextMetrics } from '../types/renderer.interface';
+import type { Rectangle } from '../types/geometry.types';
+import type { Theme } from '../types/theme.types';
+import type { VNode } from '../types/vnode.types';
+import { SVGRenderer } from '../svg/svg-renderer';
+import { type Canvas2DLike } from './canvas-context';
+import { type HitRecord } from './vnode-painter';
+/** A canvas element, structurally — so tests can hand in a fake. */
+export interface CanvasLike {
+    width: number;
+    height: number;
+    style?: {
+        width?: string;
+        height?: string;
+        [key: string]: unknown;
+    };
+    getContext(id: '2d', options?: unknown): Canvas2DLike | null;
+    toDataURL?(type?: string, quality?: number): string;
+}
+export interface CanvasRendererOptions {
+    /** The visible canvas. Required to paint; omit only for pure measurement. */
+    canvas?: CanvasLike | null;
+    /**
+     * The offscreen picking canvas. Created from `canvas`'s document when absent.
+     * Pass `null` (with `enableHitDetection: false`) to run without one.
+     */
+    hitCanvas?: CanvasLike | null;
+    /** Default: `globalThis.devicePixelRatio ?? 1`. Overridable for tests. */
+    devicePixelRatio?: number;
+    theme?: Theme;
+    /** Config for the VNode producer. Defaults match the SVG backend exactly. */
+    producerConfig?: SVGRendererConfig;
+    /**
+     * Reuse an existing VNode producer — this is how a live diagram switches
+     * backends without rebuilding its scene (render-backend.ts).
+     */
+    producer?: SVGRenderer;
+    /** Enable the colour-keyed hit canvas. Default true. */
+    enableHitDetection?: boolean;
+    /**
+     * Sub-sampling factor for the hit canvas. 1 = pixel-exact picking (default).
+     * 0.5 halves its memory at the cost of ~1px of picking slop.
+     */
+    hitCanvasScale?: number;
+    /** Enable dirty-rectangle partial redraw. Default true. */
+    enableDirtyRegions?: boolean;
+    /**
+     * Element whose computed `--grafloria-*` custom properties override the theme —
+     * normally the canvas's host. This is what lets a host theme canvas mode with
+     * the same CSS variables it uses for SVG mode.
+     */
+    styleHost?: Element | null;
+}
+/** What was under the cursor. */
+export interface CanvasPick {
+    kind: HitRecord['kind'];
+    id: string;
+    vnode: VNode;
+}
+/** Per-frame numbers the dirty-redraw path actually produces. */
+export interface CanvasFrameStats {
+    /** Elements drawn this frame. */
+    painted: number;
+    /** Elements skipped because they fell outside every dirty rect. */
+    culled: number;
+    /** Dirty rects this frame; 0 means a full repaint. */
+    dirtyRects: number;
+    /** True when the whole canvas was repainted. */
+    fullRepaint: boolean;
+    /** Entities whose VNode changed. */
+    changedEntities: number;
+}
+export declare class CanvasRenderer implements IRenderer {
+    readonly mode: "canvas";
+    readonly capabilities: RendererCapabilities;
+    private readonly producer;
+    private readonly ownsProducer;
+    private readonly resolver;
+    private readonly painter;
+    private readonly tracker;
+    private canvas;
+    private ctx;
+    private hitCanvas;
+    private hitCtx;
+    private theme;
+    private dpr;
+    private readonly enableHitDetection;
+    private readonly enableDirtyRegions;
+    private readonly hitCanvasScale;
+    private readonly styleHost;
+    /** Colour keys, memoised on a STABLE element id — see PaintOptions.allocateColorKey. */
+    private readonly colorKeys;
+    private colorKeyCounter;
+    private lastWorldToDevice;
+    private hitRecords;
+    private colorKeyIndex;
+    private unpaintable;
+    private readonly textCache;
+    private lastViewportKey;
+    private lastRenderTime;
+    private lastStats;
+    private frameCount;
+    private fps;
+    private fpsTimer;
+    private disposed;
+    constructor(engine: DiagramEngine, options?: CanvasRendererOptions);
+    /**
+     * Produce the frame's VNode tree and paint it.
+     *
+     * Returns the tree (rather than `void`) on purpose: it is the same tree SVG
+     * mode would have reconciled, so a caller can assert parity, or hand it to the
+     * SVG patcher, without re-rendering.
+     */
+    render(viewport: Rectangle, zoom: number): VNode;
+    getPerformanceMetrics(): PerformanceMetrics;
+    /**
+     * The topmost element at a WORLD coordinate.
+     *
+     * Colour-keyed pixel picking when a real hit canvas is available (O(1), and
+     * exactly what was drawn); the geometric fallback otherwise. They are two
+     * implementations of ONE geometry — both read the hit records the paint pass
+     * produced — and they are pinned to each other, and to the engine's own
+     * `getNodeAtPosition`, in `canvas-hit-parity.spec.ts` and in the browser e2e.
+     */
+    hitTest(x: number, y: number): VNode | null;
+    /** Hit-test, with the entity identity the interaction layer wants. */
+    pick(x: number, y: number): CanvasPick | null;
+    /**
+     * Colour-key pick: read one pixel off the hit canvas and look the colour up.
+     * `null` when there is no hit canvas (headless) OR when the pixel is empty.
+     */
+    pickPixel(x: number, y: number): HitRecord | null;
+    /**
+     * Geometric pick: reverse paint order over the hit records, point-in-path for
+     * filled regions and distance-to-path for stroked ones. O(n), used headlessly
+     * and as the oracle the pixel picker is checked against.
+     */
+    pickGeometric(x: number, y: number): HitRecord | null;
+    /**
+     * Text measurement through the real 2D context when there is one (proper glyph
+     * metrics), falling back to the same average-glyph estimate the SVG text-block
+     * engine uses so headless measurement stays consistent with the wrapping the
+     * producer already did.
+     */
+    measureText(text: string, style: TextStyle): TextMetrics;
+    /** Export the CURRENT canvas contents. `svg` is not a canvas capability. */
+    export(format: ExportFormat, options?: ExportOptions): Promise<string>;
+    dispose(): void;
+    getTheme(): Theme;
+    /** Swap the theme. Repaints everything: every resolved colour just changed. */
+    setTheme(theme: Theme): void;
+    /** The VNode producer — shared with the SVG backend on a mode switch. */
+    getProducer(): SVGRenderer;
+    /** Attach (or replace) the canvas this renderer paints into. */
+    setCanvas(canvas: CanvasLike | null, hitCanvas?: CanvasLike | null): void;
+    /** Change the device pixel ratio (a window moved to a retina display). */
+    setDevicePixelRatio(dpr: number): void;
+    getDevicePixelRatio(): number;
+    /** What the last frame actually repainted — the dirty-region proof. */
+    getFrameStats(): CanvasFrameStats;
+    /** Every pickable region of the current frame, in paint order. */
+    getHitRecords(): readonly HitRecord[];
+    /**
+     * Nodes the canvas could not paint (`foreignObject` — live HTML/components).
+     * A host that uses them should mount an HTML overlay for exactly these.
+     */
+    getUnpaintableNodes(): readonly VNode[];
+    /** Force the next frame to repaint the whole canvas. */
+    invalidate(): void;
+    /**
+     * World → DEVICE pixels.
+     *
+     * Read straight off the tree's `viewBox`, so the canvas maps world space with
+     * the exact same transform the SVG backend hands to the browser. If these two
+     * ever disagreed, the picture and the hit-tester would silently drift apart at
+     * zoom ≠ 1 — which is precisely the bug the shared `viewBox` convention in
+     * `ViewportController` exists to prevent.
+     */
+    private computeWorldToDevice;
+    /**
+     * High-DPI: the backing store is in DEVICE pixels, the element stays in CSS
+     * pixels. Skipping this is what makes a naive canvas look soft on a retina
+     * screen — the browser upscales a 1x bitmap into a 2x box.
+     */
+    private syncCanvasSize;
+    private paintFrame;
+    /** Stable colour key for an element id, minted once and never recycled. */
+    private colorKeyFor;
+    private startFPSTracking;
+    private estimateMemoryUsage;
+}
+/** `"0 0 800 600"` → a rectangle. */
+export declare function parseViewBox(raw: unknown): Rectangle | null;