@vectojs/core 1.20.0 → 1.21.0

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 _chunkYLH7F4ZVjs = require('./chunk-YLH7F4ZV.js');
+var _chunkAGP4VLF4js = require('./chunk-AGP4VLF4.js');
 
 // src/text/index.ts
 var _text = require('@vectojs/text'); _createStarExport(_text);
 
 
 
-exports.MSDFTextEntity = _chunkYLH7F4ZVjs.MSDFTextEntity; exports.SVGEntity = _chunkYLH7F4ZVjs.SVGEntity;
+exports.MSDFTextEntity = _chunkAGP4VLF4js.MSDFTextEntity; exports.SVGEntity = _chunkAGP4VLF4js.SVGEntity;

package/dist/text.mjs

@@ -1,7 +1,7 @@
 import {
   MSDFTextEntity,
   SVGEntity
-} from "./chunk-TJCXB2F6.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';
@@ -726,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}

package/dist/tree/Scene.d.ts

@@ -25,7 +25,41 @@ import { type ParticleModuleSource, type ParticleBackend } from '../wasm/particl
  * `a11ySync` and `a11yOrder` run after `render` in the frame loop, so they are
  * siblings of it, not children.
  */
-export type RenderPhase = 'render' | 'transform' | 'drawWalk' | 'flush' | 'a11ySync' | 'a11yOrder'
+export type RenderPhase = 'render' | 'transform' | 'drawWalk' | 'flush' | 'a11ySync'
+/**
+ * Time inside {@link Scene.syncContentGridProjection} materializing DOM
+ * carriers, nested inside `a11ySync`.
+ *
+ * Split out because `a11ySync` for a streaming code block measured 1661-1875 ms
+ * against a 210-671 ms render, and attributing that to grid materialization was
+ * an assumption. Nothing should be optimised here on the strength of the parent
+ * phase alone.
+ */
+ | 'gridMaterialize'
+/**
+ * Whole of {@link Scene.syncContentProjection}, nested inside `a11ySync`.
+ *
+ * Measured at 99.8-99.9% of `a11ySync` for a streaming code block, so per-node
+ * a11y attribute and geometry work is not where that phase's cost lives.
+ */
+ | 'contentProjection'
+/** Per-node a11y attribute/geometry work, excluding content projection and descendants. */
+ | 'a11yNodes'
+/** Whole of `syncContentGridProjection`, of which `gridMaterialize` is one part. */
+ | 'gridSync'
+/**
+ * Synchronous part of `scheduleContentGridCalibration` — building the probe DOM.
+ *
+ * The measurement itself is deferred to a rAF, but the probe is constructed
+ * here. Measured at 77-80% of `gridSync` on Chrome (3.7-4.5 ms per frame, i.e.
+ * the entire 240Hz budget) against about 1 ms on Firefox, making it the largest
+ * remaining cost of projecting a streaming code block once carrier reuse landed.
+ */
+ | 'gridCalibrateSchedule'
+/** The `querySelectorAll` + per-cell scan inside calibration scheduling. */
+ | 'calibScan'
+/** Probe DOM construction and insertion inside calibration scheduling. */
+ | 'calibProbeBuild' | 'a11yOrder'
 /** Sum of every entity's own render(), nested inside drawWalk. */
  | 'entityPaint';
 export interface RenderPhaseEntry {
@@ -358,6 +392,29 @@ export declare class Scene {
     private contentGridCalibrationFrames;
     /** Detached, untransformed font probes used by the cold calibration pass. */
     private contentGridCalibrationProbes;
+    /**
+     * Monotonic stamp identifying the conditions grid cells were calibrated under.
+     *
+     * Calibration measures the difference between the advance the canvas grid assigns
+     * a cluster and the width the browser lays it out at, then writes a per-cell
+     * `scaleX`. That result stays valid until the font or the page scale changes, and
+     * it lives on the cell element — so a cell carrying this stamp needs no further
+     * work.
+     *
+     * The scan that feeds calibration was O(cells) on every revision bump: for a
+     * streaming code block it re-derived a measurement key for every cell in the
+     * block each frame in order to produce only ~20 distinct keys, costing about
+     * 2.5 ms/frame after the `style.font` fix and still over half of `a11ySync`. Since
+     * carrier reuse (#244) leaves untouched lines — and therefore their calibrated
+     * transforms — in place, cells stamped with the current generation can simply be
+     * skipped, making the scan O(new cells) instead.
+     *
+     * A plain incrementing integer rather than the descriptive calibration key,
+     * because it goes into an attribute selector and must not need escaping.
+     */
+    private contentGridCalibrationGeneration;
+    /** The `(fontEpoch, pageScale)` pair the current generation corresponds to. */
+    private contentGridCalibrationStamp;
     /** Invalidates grid font calibration after browser font availability changes. */
     private contentFontEpoch;
     /** Cached Canvas-to-client scale for the current font/viewport epoch. */
@@ -800,6 +857,15 @@ export declare class Scene {
      */
     private setupGLContextRecovery;
     private endContentSelectionDrag;
+    /**
+     * Index of the carrier line currently holding a selection inside `el`, or
+     * `null`.
+     *
+     * Lets a partial re-materialization decide whether the user's selection is even
+     * affected. Checks the tracked anchor first (it survives a drag) and falls back
+     * to the live DOM selection.
+     */
+    private contentGridSelectionLine;
     private releaseContentSelectionForRebuild;
     /**
      * Rebuild a content-projection element's DOM (`rebuild`) while preserving a
@@ -836,6 +902,17 @@ export declare class Scene {
      * @example scene.add(new CircleEntity());
      */
     add(entity: Entity): this;
+    /**
+     * Reset per-grid calibration and bookkeeping before a (re)materialization.
+     *
+     * @param entityId - Owning entity, keyed into the calibration maps.
+     * @param el - The projection element.
+     * @param releaseSelection - Whether to drop a selection this element owns.
+     *   Pass `false` when carrier lines are being reused: the selection's DOM nodes
+     *   survive the pass, so tearing it down would wipe a user's selection on every
+     *   streamed chunk — the exact bug `preserveContentSelectionAcrossRebuild`
+     *   exists to prevent on the non-grid path.
+     */
     private clearContentGridState;
     /**
      * Drop any projected elements under `node` without touching the entity tree.
@@ -933,6 +1010,26 @@ export declare class Scene {
     get rootEntity(): Entity;
     /** The overlay layer root (see {@link showOverlay}), read-only for tooling. */
     get overlayRootEntity(): Entity;
+    /**
+     * Advance and render exactly one frame, synchronously.
+     *
+     * This renders UNCONDITIONALLY: it consults neither {@link renderMode} nor
+     * {@link dirty}, and it does not apply the `always`-mode idle auto-throttle.
+     * That is deliberate — a deterministic driver (video export, a test, a
+     * fixed-step benchmark) asks for a frame because it wants that frame, not a
+     * scheduler opinion about whether it is needed.
+     *
+     * The consequence is a measurement footgun worth stating explicitly: a
+     * benchmark that drives frames through `step()` CANNOT observe frame skipping,
+     * so `always` and `onDemand` produce byte-identical draw counts through this
+     * path. An investigation into whether `onDemand` skips redundant repaints once
+     * concluded "it does not" on exactly that basis; on the real rAF loop the same
+     * workload rendered ~1.0 frames per content change. To measure anything about
+     * scheduling, use {@link start} and let `requestAnimationFrame` drive.
+     *
+     * @param dt Seconds to advance. Not clamped by `MAX_FRAME_DT` — the caller
+     *   chooses the step, since determinism is the point.
+     */
     step(dt: number): void;
     /**
      * Mark the scene as needing a redraw on the next frame.
@@ -941,6 +1038,22 @@ export declare class Scene {
      * entity state outside of {@link Entity.animate} so the change is rendered.
      */
     markDirty(source?: DirtySource): void;
+    /**
+     * Increments whenever the tree's shape changes: add, remove or reparent.
+     *
+     * Already maintained for the resident WASM transform store (see
+     * {@link markStructureChanged}, called from `Entity.add`/`remove`), and exposed
+     * here because a cache of the tree's shape — a DevTools tree model, a serialized
+     * snapshot — is valid exactly as long as this value is unchanged. Comparing it is
+     * O(1) against re-walking the tree, which is what it replaces: DevTools rebuilt
+     * both trees on a fixed 500 ms interval, a constant cost proportional to entity
+     * count, purely because it had no way to ask whether the shape had changed.
+     *
+     * Property changes do NOT bump it. Moving or restyling an entity leaves the
+     * shape intact, so a consumer that also cares about values must read those
+     * directly rather than rebuilding a tree.
+     */
+    get structureVersion(): number;
     /**
      * Record who marked the scene dirty and why.
      *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/core",
-  "version": "1.20.0",
+  "version": "1.21.0",
   "publishConfig": {
     "access": "public"
   },