@vectojs/core 1.19.0 → 1.21.0

package/dist/renderer/GlyphRasterAtlas.d.ts

@@ -0,0 +1,186 @@
+/**
+ * A texture atlas of rasterized glyphs, for grids that draw the *same small set
+ * of glyphs* thousands of times per frame.
+ *
+ * Named `GlyphRasterAtlas` rather than `GlyphAtlas` because `@vectojs/layout`
+ * already exports a `GlyphAtlas` interface — a map of grapheme to *vector* path
+ * metrics — and the core barrel re-exports that package, so the shorter name is a
+ * hard collision. The distinction is also worth keeping: that one holds path data
+ * for measuring, this one holds pixels for blitting.
+ *
+ * ## Why this exists alongside {@link TextRasterCache}
+ *
+ * Both replace per-cell `fillText` with a bitmap blit. The difference is where
+ * the pixels live, and measurement says that difference decides whether the idea
+ * works at all.
+ *
+ * `TextRasterCache` allocates **one canvas per cached run**. A warm cache for a
+ * syntax-highlighted code grid holds a few hundred of them (glyphs x theme
+ * colours), so a frame blits from a few hundred distinct source textures and the
+ * GPU re-binds on nearly every call. Measured on real hardware, that per-source
+ * cost is invisible at 2k cells and dominant at 40k: Chrome went 1.82x at 2k to
+ * **0.87x at 40k** — slower than the `fillText` it replaced. Its per-call cost
+ * grows with cell count (1.22 -> 2.89 us) rather than staying flat.
+ *
+ * This atlas keeps every glyph in **one** canvas and selects with a source rect,
+ * so the source texture never changes. Same call count, same pixels, same
+ * geometry — and per-call cost is flat as the grid grows (Chrome 1.10 -> 1.11
+ * us), giving **1.90-2.27x over `fillText` on both engines at every size**.
+ * Full data: `vectojs-docs/forge/baselines/raster-cache-findings.md`.
+ *
+ * The win comes from *reuse*, so this is for bounded glyph sets: a monospace code
+ * grid, a terminal, a data grid, a numeric HUD. Prose is the wrong customer —
+ * every run is distinct, so an atlas is pure overhead (use `RichText`'s coalesced
+ * runs there instead).
+ *
+ * ## Requires a source-rect blit
+ *
+ * Selecting one slot needs {@link IRenderer.drawImageRect}, which is optional:
+ * `CanvasRenderer` implements it, `SVGRenderer` deliberately does not (an SVG
+ * blit embeds its source as a data URL, so a per-cell sub-rect would inline the
+ * whole atlas thousands of times — and vector text is the correct output for a
+ * vector export anyway). Callers must keep their `fillText` path for renderers
+ * that lack it:
+ *
+ * ```ts
+ * const slot = atlas.get(font, color, glyph);
+ * if (slot && r.drawImageRect) {
+ *   r.drawImageRect(atlas.source, slot.sx, slot.sy, slot.sw, slot.sh,
+ *                   x - slot.offsetX, baselineY - slot.offsetY, slot.w, slot.h);
+ * } else {
+ *   r.fillText(glyph, x, baselineY, font, color);
+ * }
+ * ```
+ */
+/** Where one glyph lives in the atlas, and how to blit it at a baseline. */
+export interface GlyphSlot {
+    /** Source X in atlas *device* pixels. */
+    sx: number;
+    /** Source Y in atlas *device* pixels. */
+    sy: number;
+    /** Source width in atlas *device* pixels. */
+    sw: number;
+    /** Source height in atlas *device* pixels. */
+    sh: number;
+    /** Destination width in CSS pixels. */
+    w: number;
+    /** Destination height in CSS pixels. */
+    h: number;
+    /** Left inset (CSS px) of the glyph origin inside the slot. */
+    offsetX: number;
+    /** Distance (CSS px) from the slot top down to the text baseline. */
+    offsetY: number;
+    /** The cluster these pixels represent. */
+    glyph: string;
+    /** The CSS font shorthand these pixels were rasterized with. */
+    font: string;
+    /** Advance width (CSS px) of the cluster, i.e. `measureText().width`. */
+    advance: number;
+    /**
+     * Ink extent left of the glyph origin (CSS px), from `actualBoundingBoxLeft`.
+     *
+     * Carried on the slot so a blit can be mapped back to the same geometry a
+     * `fillText` would have produced. Without it, instrumentation that traces draw
+     * calls to verify grid positioning (`e2e/text-projection.e2e.ts`) can see only
+     * a destination rect and cannot recover where the glyph origin sat inside it.
+     */
+    left: number;
+    /** Ink extent right of the glyph origin (CSS px), from `actualBoundingBoxRight`. */
+    right: number;
+}
+/** Instrumentation counters, e.g. to surface a HUD hit rate. */
+export interface GlyphRasterAtlasStats {
+    /** Requests served from an existing slot. */
+    hits: number;
+    /** Requests that had to rasterize. */
+    misses: number;
+    /** Glyphs currently resident. */
+    size: number;
+    /**
+     * Times the atlas filled up and was reset.
+     *
+     * Steady-state thrash means the glyph set is unbounded for the configured
+     * size, and the atlas is doing net harm — every reset re-rasterizes everything.
+     * A caller that watches this can fall back to `fillText` permanently.
+     */
+    resets: number;
+}
+/** Options for {@link GlyphRasterAtlas}. */
+export interface GlyphRasterAtlasOptions {
+    /**
+     * Device-pixel-ratio to rasterize at. Slots record device pixels while `w`/`h`
+     * stay in CSS pixels, so the blit is DPR-correct without caller arithmetic.
+     * Default `1`.
+     */
+    dpr?: number;
+    /**
+     * Max atlas edge in device pixels, capped at 8192 — comfortably inside the
+     * lowest common `maxTextureSize` while leaving room for thousands of glyphs.
+     * Exceeding a browser's real limit yields a silently blank canvas, so this is
+     * clamped rather than trusted. Default `2048`.
+     */
+    maxSize?: number;
+}
+/**
+ * A glyph atlas. Create one per renderer/scene — instances share no state, so
+ * multiple scenes or an SSR pass never collide.
+ */
+export declare class GlyphRasterAtlas {
+    private readonly slots;
+    private readonly dpr;
+    private readonly maxSize;
+    private canvas;
+    private ctx;
+    /**
+     * Shelf packing: glyphs land left-to-right on a row, then a new row starts.
+     * A monospace grid produces near-uniform widths, so shelves waste very little
+     * and cost one comparison per insert — a real 2D packer would buy nothing here.
+     */
+    private penX;
+    private penY;
+    private rowHeight;
+    private _hits;
+    private _misses;
+    private _resets;
+    constructor(options?: GlyphRasterAtlasOptions);
+    /** Live instrumentation snapshot. */
+    get stats(): GlyphRasterAtlasStats;
+    /**
+     * The atlas canvas, to pass as the blit source.
+     *
+     * `null` until the first successful {@link get}, and in any non-DOM context.
+     */
+    get source(): HTMLCanvasElement | null;
+    private ensureCanvas;
+    /**
+     * Look up a glyph, rasterizing it into the atlas on first request.
+     *
+     * @param font - Full CSS `font` shorthand, used for measuring and painting.
+     * @param color - CSS color baked into the pixels.
+     * @param glyph - A single grapheme cluster. Long strings are rejected
+     *   (`null`): they defeat the atlas's fixed-slot packing and belong in
+     *   `fillText` or {@link TextRasterCache}.
+     * @returns The slot, or `null` when the caller must fall back to `fillText`
+     *   (headless, unrasterizable, or too large to pack).
+     */
+    get(font: string, color: string, glyph: string): GlyphSlot | null;
+    /**
+     * Find the slot occupying a source position, or `null`.
+     *
+     * The inverse of {@link get}: it maps a blit back to the glyph it drew. Exists
+     * for instrumentation — a test or devtool that traces `drawImage` calls sees
+     * only a source rect, and needs this to recover which cluster was painted and
+     * with what metrics. Linear over resident slots, so it is a diagnostic, not a
+     * per-frame call.
+     */
+    slotAt(sx: number, sy: number): GlyphSlot | null;
+    /**
+     * Drop every glyph and reuse the canvas.
+     *
+     * Call after a font or theme change: slots are keyed by `(font, color, glyph)`
+     * so stale entries are never *returned* wrongly, but they do occupy space.
+     */
+    reset(): void;
+    /** Release the backing canvas and all slots. */
+    destroy(): void;
+}

package/dist/renderer/IRenderer.d.ts

@@ -115,6 +115,37 @@ export interface IRenderer {
      * @param dh - Destination height.
      */
     drawImage(source: CanvasImageSource, dx: number, dy: number, dw: number, dh: number): void;
+    /**
+     * Draw a sub-rectangle of an image source — the 9-argument `drawImage`.
+     *
+     * **Optional.** Callers must feature-detect and keep a fallback path:
+     *
+     * ```ts
+     * if (r.drawImageRect) r.drawImageRect(atlas, sx, sy, sw, sh, dx, dy, dw, dh);
+     * else r.fillText(glyph, x, baselineY, font, color);
+     * ```
+     *
+     * This exists for texture atlases (see `GlyphRasterAtlas`), where selecting one slot
+     * out of a shared canvas is what makes the blit cheap: a per-source-canvas
+     * cache re-binds a different texture almost every call and measured *slower*
+     * than the `fillText` it replaced on Chrome at scale, while atlas blits stay
+     * flat and run ~2x faster on both engines.
+     *
+     * `SVGRenderer` deliberately omits it: an SVG image embeds its source as a data
+     * URL, so a per-cell sub-rect would inline the entire atlas once per cell —
+     * and vector text is the correct output for a vector export regardless.
+     *
+     * @param source - The image source.
+     * @param sx - Source X, in source-image pixels.
+     * @param sy - Source Y, in source-image pixels.
+     * @param sw - Source width, in source-image pixels.
+     * @param sh - Source height, in source-image pixels.
+     * @param dx - Destination X.
+     * @param dy - Destination Y.
+     * @param dw - Destination width.
+     * @param dh - Destination height.
+     */
+    drawImageRect?(source: CanvasImageSource, sx: number, sy: number, sw: number, sh: number, dx: number, dy: number, dw: number, dh: number): void;
     /**
      * Fill the current path with the given color or gradient.
      *

package/dist/renderer/index.d.ts

@@ -4,4 +4,5 @@ export * from './WebGLPointRenderer';
 export * from './WebGPUParticleSystemManager';
 export * from './IRenderer';
 export * from './colorParse';
+export * from './GlyphRasterAtlas';
 export * from './TextRasterCache';

package/dist/renderer.js

@@ -6,12 +6,14 @@
 
 
 
-var _chunkL4SWVP2Hjs = require('./chunk-L4SWVP2H.js');
 
+var _chunkGKSCJ6AFjs = require('./chunk-GKSCJ6AF.js');
 
 
 
 
 
 
-exports.CanvasRenderer = _chunkL4SWVP2Hjs.CanvasRenderer; exports.SVGRenderer = _chunkL4SWVP2Hjs.SVGRenderer; exports.TextRasterCache = _chunkL4SWVP2Hjs.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkL4SWVP2Hjs.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkL4SWVP2Hjs.createWebGLPointRenderer; exports.parseColorToRGBA = _chunkL4SWVP2Hjs.parseColorToRGBA;
+
+
+exports.CanvasRenderer = _chunkGKSCJ6AFjs.CanvasRenderer; exports.GlyphRasterAtlas = _chunkGKSCJ6AFjs.GlyphRasterAtlas; exports.SVGRenderer = _chunkGKSCJ6AFjs.SVGRenderer; exports.TextRasterCache = _chunkGKSCJ6AFjs.TextRasterCache; exports.WebGPUParticleSystemManager = _chunkGKSCJ6AFjs.WebGPUParticleSystemManager; exports.createWebGLPointRenderer = _chunkGKSCJ6AFjs.createWebGLPointRenderer; exports.parseColorToRGBA = _chunkGKSCJ6AFjs.parseColorToRGBA;

package/dist/renderer.mjs

@@ -1,13 +1,15 @@
 import {
   CanvasRenderer,
+  GlyphRasterAtlas,
   SVGRenderer,
   TextRasterCache,
   WebGPUParticleSystemManager,
   createWebGLPointRenderer,
   parseColorToRGBA
-} from "./chunk-QS3CUV7H.mjs";
+} from "./chunk-RTENOAYT.mjs";
 export {
   CanvasRenderer,
+  GlyphRasterAtlas,
   SVGRenderer,
   TextRasterCache,
   WebGPUParticleSystemManager,

package/dist/text.js

@@ -2,11 +2,11 @@
 
 
 
-var _chunkIA3KW4CGjs = require('./chunk-IA3KW4CG.js');
+var _chunkAGP4VLF4js = require('./chunk-AGP4VLF4.js');
 
 // src/text/index.ts
 var _text = require('@vectojs/text'); _createStarExport(_text);
 
 
 
-exports.MSDFTextEntity = _chunkIA3KW4CGjs.MSDFTextEntity; exports.SVGEntity = _chunkIA3KW4CGjs.SVGEntity;
+exports.MSDFTextEntity = _chunkAGP4VLF4js.MSDFTextEntity; exports.SVGEntity = _chunkAGP4VLF4js.SVGEntity;

package/dist/text.mjs

@@ -1,7 +1,7 @@
 import {
   MSDFTextEntity,
   SVGEntity
-} from "./chunk-XWBVBXFZ.mjs";
+} from "./chunk-FRMLD4PP.mjs";
 
 // src/text/index.ts
 export * from "@vectojs/text";

package/dist/tree/Entity.d.ts

@@ -159,6 +159,105 @@ export interface TextInputStyle {
  * to create and label the shadow DOM node (e.g. a real `<button>` or `<a href>`)
  * so the canvas stays accessible and clickable by automation/agents.
  */
+/**
+ * One value in a {@link DevtoolsDescriptor} group.
+ *
+ * JSON-safe by construction: DevTools serializes descriptors to render a panel,
+ * to write a snapshot, and to cross a `postMessage` bridge, so a value that
+ * cannot survive `structuredClone` is a bug rather than a limitation.
+ */
+export interface DevtoolsField {
+    /** Field name as shown in the inspector, e.g. `'scrollTop'`. */
+    label: string;
+    /** Current value. Keep to primitives, or short arrays/records of primitives. */
+    value: string | number | boolean | null | ReadonlyArray<string | number> | Record<string, string | number | boolean>;
+    /**
+     * Optional one-line explanation, shown as a tooltip.
+     *
+     * Worth spending: a reader looking at `visibleRange: [12, 34]` cannot tell
+     * whether the bounds are inclusive without being told.
+     */
+    hint?: string;
+    /**
+     * Mark a value that reflects derived or externally-owned state, so the panel
+     * can show it as read-only rather than inviting an edit that will be silently
+     * reverted. A `Stack`-laid-out child's `x` is the canonical example.
+     */
+    readOnly?: boolean;
+}
+/**
+ * A component's self-description for DevTools.
+ *
+ * Without this, the inspector can only show generic `Entity` properties —
+ * position, size, opacity — so everything that makes a component a component is
+ * invisible: `Input.value`, `Slider.min`/`max`, `ScrollView.scrollTop`,
+ * `VirtualList.visibleRange`, a `Markdown` block's token counts. The alternative
+ * is DevTools carrying a table of component types, which inverts the dependency
+ * (a debug tool would gate every new component) and breaks under minified builds
+ * where `constructor.name` is unreliable.
+ *
+ * Implement {@link Entity.getDevtoolsDescriptor} to opt in. Cost is paid only
+ * when a panel actually inspects the entity, so a descriptor may compute values
+ * it would not compute per frame.
+ *
+ * @example
+ * ```ts
+ * public override getDevtoolsDescriptor(): DevtoolsDescriptor {
+ *   return {
+ *     kind: 'ScrollView',
+ *     groups: [{
+ *       label: 'Scroll',
+ *       fields: [
+ *         { label: 'scrollTop', value: this.scrollTop },
+ *         { label: 'contentHeight', value: this.contentHeight, readOnly: true },
+ *       ],
+ *     }],
+ *   };
+ * }
+ * ```
+ */
+export interface DevtoolsDescriptor {
+    /**
+     * Component kind for display, e.g. `'VirtualList'`.
+     *
+     * Provided explicitly rather than read from `constructor.name`, which minifies
+     * to something meaningless in a production bundle.
+     */
+    kind: string;
+    /** Grouped fields, rendered as sections in the order given. */
+    groups: ReadonlyArray<{
+        label: string;
+        fields: ReadonlyArray<DevtoolsField>;
+    }>;
+    /**
+     * Free-form notes: a caveat, a known-slow path, a link to a doc section.
+     * Rendered under the groups.
+     */
+    notes?: ReadonlyArray<string>;
+    /**
+     * Stable identity for snapshot diffing, independent of tree position.
+     *
+     * Snapshot paths are structural indices (`root > Card[0] > Text[2]`), so
+     * inserting at the head of a list renames every sibling and cascades into a
+     * large diff. A key that survives reordering — a row id, a message id — keeps
+     * the diff proportional to what actually changed. Most relevant to
+     * `VirtualList` and `Table`, where recycling moves entities constantly.
+     */
+    devtoolsKey?: string;
+}
+/**
+ * Entity properties a parent computes for its children.
+ *
+ * Editing one of these on a child is silently reverted by the next layout pass,
+ * which looks like the editor being broken rather than the value being owned
+ * elsewhere. A container declares what it controls so a tool can say so up front
+ * instead of letting a user discover it by watching their change disappear.
+ *
+ * Declared by the parent rather than detected by the tool: only the container
+ * knows whether it writes `x` unconditionally, and a table of container types
+ * inside DevTools would gate every new layout component on a debug-tool change.
+ */
+export type LayoutControlledProperty = 'x' | 'y' | 'width' | 'height' | 'scaleX' | 'scaleY' | 'rotation' | 'opacity';
 export interface A11yAttributes {
     /** Shadow element tag to create. Defaults to `'div'`. */
     tag?: 'div' | 'a' | 'button' | 'img' | 'input' | 'textarea';
@@ -416,6 +515,24 @@ export declare abstract class Entity {
      * nodes, so on-top components stay clickable.
      */
     a11yFullViewport: boolean;
+    /**
+     * Hide this entity AND its whole subtree from the accessibility/automation
+     * projection, regardless of each node's own `interactive` flag.
+     *
+     * For a container that is logically closed while still mounted — an `Overlay`
+     * after `hide()`, a collapsed panel kept in the tree for its transition. Setting
+     * `interactive = false` on the container alone is not enough: the projection walk
+     * still descends, and any still-interactive child is re-created on the next
+     * frame. Measured before this existed: after `Popover.hide()` the popover's own
+     * element was gone while its button stayed projected with `tabIndex: 0` and a
+     * live box, so a keyboard user could Tab into a hidden popover.
+     *
+     * Deliberately NOT inferred from `opacity`: `Overlay.hide()` springs opacity
+     * toward 0, so mid-transition it reads nonzero (~0.26 when measured) and an
+     * `=== 0` test never fires; a threshold would instead silently un-project a
+     * faint-but-live control.
+     */
+    a11yHidden: boolean;
     /**
      * Clip this node's children to its local box (`[0,0]–[width,height]`) while
      * rendering. Combined with translating a content child, this is how
@@ -708,6 +825,33 @@ export declare abstract class Entity {
      *
      * @returns The {@link A11yAttributes} for this entity's shadow node.
      */
+    /**
+     * Describe this entity's own debug surface for DevTools.
+     *
+     * Returns `null` by default, meaning "nothing beyond the generic `Entity`
+     * fields the inspector already shows". Override in a component to expose the
+     * state that makes it inspectable — see {@link DevtoolsDescriptor}.
+     *
+     * Called only while a panel is inspecting this entity, never per frame, so it
+     * may compute values that would be too expensive to track continuously.
+     *
+     * @returns A descriptor, or `null` to opt out.
+     */
+    getDevtoolsDescriptor(): DevtoolsDescriptor | null;
+    /**
+     * Which of a child's properties this entity computes during layout.
+     *
+     * Returns an empty array by default, meaning "this entity does not position its
+     * children". A container that lays out children — `Stack`, `Table`, `Tabs` —
+     * overrides it so tooling can mark those values as parent-owned: editing `x` on
+     * a `Stack` child is reverted by the next layout, and knowing that in advance is
+     * the difference between a confusing tool and a correct one.
+     *
+     * @param child - The child being asked about. Containers whose control depends
+     *   on the child (a `Table` cell versus its header) can answer per child.
+     * @returns Property names this entity overwrites on that child.
+     */
+    getLayoutControlledProperties(child: Entity): ReadonlyArray<LayoutControlledProperty>;
     getA11yAttributes(): A11yAttributes;
     /**
      * Local-space axis-aligned bounding box of what this entity's {@link render}