@vectojs/core 1.29.0 → 1.31.0

package/dist/tree/Entity.d.ts

@@ -103,6 +103,43 @@ export interface ContentProjectionLine {
     /** Styled text runs in visual order. */
     runs?: ContentProjectionRun[];
 }
+/**
+ * Advice from the {@link Scene} about which part of an entity is worth
+ * describing in {@link Entity.getContentProjection}.
+ *
+ * **Purely an optimization, and ignoring it is always correct.** The Scene
+ * windows the DOM itself, so an entity that returns its whole document still
+ * behaves correctly — it just pays to build lines that get discarded. An entity
+ * whose projection is O(glyphs) can use this to make that build O(visible)
+ * instead, which is the difference between per-frame cost that scales with the
+ * document and cost that scales with the viewport.
+ *
+ * Why a hint rather than a strict window: the entity owns the mapping from its
+ * own text to visual lines, and only it knows things like where a wrapped
+ * paragraph begins. Handing it a band and letting it round outward keeps that
+ * knowledge in one place. An entity may return more than asked — never less
+ * than it can, because text absent from the projection is invisible to
+ * find-in-page, copy and, for static text, the screen reader.
+ */
+export interface ContentProjectionHint {
+    /**
+     * Inclusive band of entity-local y worth projecting, already expanded by the
+     * scene's `contentProjectionMargin` and intersected with every clipping
+     * ancestor. Absent when no useful bound exists (a rotated or skewed
+     * transform, a boundless entity), in which case project everything.
+     */
+    minY?: number;
+    maxY?: number;
+}
+/**
+ * Whether a line at `y` of height `height` is worth projecting under `hint`.
+ *
+ * Shared so every consumer rounds the same way: a line is kept when its box
+ * overlaps the band at all, which retains a line straddling the edge whole
+ * rather than clipping it mid-glyph. Returns `true` when the hint carries no
+ * band, so the default is always "project it".
+ */
+export declare function contentLineInHint(hint: ContentProjectionHint | undefined, y: number, height: number): boolean;
 export interface ContentProjection {
     /** The logical source text exposed to find, selection, copy, and assistive technology. */
     text: string;
@@ -540,6 +577,42 @@ export declare abstract class Entity {
      * nodes, so on-top components stay clickable.
      */
     a11yFullViewport: boolean;
+    /**
+     * When this entity's a11y shadow node is materialized.
+     *
+     * `'eager'` (the default) keeps today's behaviour: a shadow node exists for as
+     * long as the entity is `interactive` with a box. That is right for a button or
+     * a link, and wrong for thousands of ephemeral, individually-meaningless
+     * entities — particles, danmaku, graph nodes — where it produces one DOM node
+     * per entity every frame.
+     *
+     * Measured on 5,000 moving interactive entities (`benchmarks/lazy-a11y/`):
+     * eager costs **72.2 ms/frame on Chrome and 114.3 ms on Firefox**, missing even
+     * 60 Hz, against **1.55/1.63 ms** for the same scene with one node projected —
+     * within noise of the 1.26/1.65 ms floor of projecting nothing at all.
+     *
+     * `'onDemand'` projects a node only while {@link Scene} considers the entity
+     * *engaged*: it is focused, it is the current pointer target, or it has been
+     * explicitly requested via {@link Scene.requestA11yProjection}. Crucially the
+     * trigger is not hover alone — a keyboard or assistive-technology user
+     * generates no hover, so a hover-only gate would remove exactly those users'
+     * access. Engagement therefore includes focus and an explicit request, and the
+     * entity stays hit-testable on canvas throughout, so a click still reaches it
+     * and promotes it.
+     *
+     * `'never'` suppresses the node entirely. Prefer `interactive = false` unless
+     * the entity genuinely needs pointer events without any semantic presence;
+     * this exists so a purely decorative interactive surface can opt out without
+     * losing canvas hit-testing.
+     *
+     * **This does not replace an aggregate description.** A thousand `'onDemand'`
+     * danmaku are individually reachable but say nothing collectively. The proven
+     * pattern is one aggregate live region (`role: 'status'`, `a11yFullViewport`)
+     * plus a small pool of persistent hotspots for the current selection — see
+     * `vectojs-native/danmaku`. Use `'onDemand'` to stop paying per entity, not as
+     * the whole accessibility story.
+     */
+    a11yProjection: 'eager' | 'onDemand' | 'never';
     /**
      * Hide this entity AND its whole subtree from the accessibility/automation
      * projection, regardless of each node's own `interactive` flag.
@@ -920,9 +993,39 @@ export declare abstract class Entity {
      * `selectable` is set — natively selectable. Returns `null` by default.
      * Read on the a11y sync cadence, so text changes propagate automatically.
      *
+     * @param hint - Optional advice about which part of the entity is worth
+     *   describing. Purely an optimization: ignoring it is always correct, which
+     *   is why it is a parameter rather than a required contract change. See
+     *   {@link ContentProjectionHint}.
      * @returns The projection descriptor, or `null` to project nothing.
      */
-    getContentProjection(): ContentProjection | null;
+    getContentProjection(hint?: ContentProjectionHint): ContentProjection | null;
+    /**
+     * A cheap, monotonically-increasing stamp of this entity's projected content.
+     *
+     * Purely an optimization, and opt-in: returning `null` (the default) means
+     * "I cannot cheaply tell whether my content changed", and the {@link Scene}
+     * then rebuilds the projection every synced frame exactly as before. An
+     * implementation must bump the value whenever anything
+     * {@link getContentProjection} would report changes — text, fonts, line
+     * geometry, `selectable`, grid revision.
+     *
+     * When two consecutive syncs report the same epoch AND the entity's geometry
+     * is unchanged, `Scene` skips the block *before* calling
+     * {@link getContentProjection}. That matters because the projection call is
+     * O(glyphs-in-block) and the DOM diff around it costs about the same again:
+     * measured on a 1500-resident-block document, a sync in which the projected
+     * text was byte-identical before and after still cost 17.875 ms, and skipping
+     * unchanged blocks took that to 0.475 ms (carryctx CTX-0199, vectojs#343).
+     *
+     * Correctness is entirely on the implementer: a stale epoch means stale DOM,
+     * so bump it in the same place the content is invalidated rather than trying
+     * to enumerate mutation sites afterwards. Any monotonic counter works; the
+     * value is only ever compared for equality with the previous sync's.
+     *
+     * @returns The current content epoch, or `null` to disable skipping.
+     */
+    getContentEpoch(): number | null;
     /**
      * Whether this entity still has a queued/running tween animation, or an
      * active {@link setTransition}/{@link animateTo}/{@link springTo} property

package/dist/tree/Scene.d.ts

@@ -201,6 +201,34 @@ export interface SceneOptions {
      * height (`undefined` → resolved to `Scene.height` at sync time).
      */
     contentProjectionMargin?: number;
+    /**
+     * Virtualization margin (px) for the *semantic* tier of content projection —
+     * whether a block has **any** projected DOM at all, as opposed to
+     * {@link SceneOptions.contentProjectionMargin}, which decides whether that
+     * block's per-line **carriers** are windowed.
+     *
+     * Splitting the two makes a coarse resident tier expressible: with
+     * `contentSemanticMargin: Infinity` and a finite `contentProjectionMargin`,
+     * every block in the document keeps an element holding its full text — so
+     * find-in-page and screen-reader read-ahead see the whole document — while
+     * only blocks near the viewport pay for per-line carriers. One scalar could
+     * not express that, because a finite value freed off-band blocks entirely and
+     * `Infinity` also unwindowed every carrier, which is O(total document glyphs).
+     *
+     * `Infinity` is safe **here** and remains unsupported for
+     * `contentProjectionMargin`: the cost that made it unsupported comes from an
+     * unwindowed carrier band, not from resident text.
+     *
+     * Note the one-time cost. A resident tier materializes one element per block
+     * on the first sync — measured ~13µs per node created, so ~20ms at 1000 blocks
+     * and ~146ms at 10000 — as one synchronous block. Steady state is cheap
+     * (unchanged blocks skip via {@link Entity.getContentEpoch}), so this is a
+     * document-open stall, not a per-frame cost.
+     *
+     * Default: whatever `contentProjectionMargin` resolves to, so omitting this
+     * leaves behaviour unchanged.
+     */
+    contentSemanticMargin?: number;
     /**
      * Reading direction used to order the accessibility/automation shadow tree so
      * keyboard **tab order** and screen-reader traversal follow the *visual*
@@ -240,7 +268,7 @@ export interface SceneOptions {
  * against. A new option must be added here too — the test suite asserts the two
  * stay in sync.
  */
-export declare const SCENE_OPTION_KEYS: readonly ['a11ySyncInterval', 'autoThrottle', 'contentProjection', 'contentProjectionMargin', 'debugA11y', 'disableWindowResize', 'maxDPR', 'maxFPS', 'particleBackend', 'pointBackend', 'readingDirection', 'renderer', 'renderMode', 'respectReducedMotion', 'userTiming'];
+export declare const SCENE_OPTION_KEYS: readonly ['a11ySyncInterval', 'autoThrottle', 'contentProjection', 'contentProjectionMargin', 'contentSemanticMargin', 'debugA11y', 'disableWindowResize', 'maxDPR', 'maxFPS', 'particleBackend', 'pointBackend', 'readingDirection', 'renderer', 'renderMode', 'respectReducedMotion', 'userTiming'];
 /** Frame-rate the loop is capped to when the OS requests reduced motion. */
 export declare const REDUCED_MOTION_FPS = 30;
 /**
@@ -488,6 +516,15 @@ export declare class Scene {
     private a11yElements;
     /** DOM nodes mirroring static text content, keyed by entity id. */
     private contentElements;
+    /**
+     * What the last completed content-projection sync was built from, per entity.
+     *
+     * Compared at the top of {@link syncContentProjection} to skip a block whose
+     * content AND geometry are both unchanged, before the O(glyphs) projection
+     * build. Only populated for entities that opt in via
+     * {@link Entity.getContentEpoch}. (carryctx CTX-0199)
+     */
+    private contentSyncState;
     /** Pending cold font-calibration frame per projected grid entity. */
     private contentGridCalibrationFrames;
     /** Detached, untransformed font probes used by the cold calibration pass. */
@@ -522,6 +559,7 @@ export declare class Scene {
     private contentMetricScaleX;
     private contentProjectionEnabled;
     private contentProjectionMargin;
+    private contentSemanticMargin;
     /**
      * True while a text-selection drag that started on a projection's blank
      * region (no text node under the press) is being driven manually — the
@@ -555,6 +593,14 @@ export declare class Scene {
      *  mid-hover synthesize the `pointerleave` the browser never sends for a
      *  detached element, so the entity doesn't keep its hover state. */
     private readonly hoveredA11yElements;
+    /**
+     * Entity ids the application has pinned via {@link requestA11yProjection}.
+     *
+     * Ids rather than entities so a removed entity cannot be retained by this set;
+     * a stale id simply never matches. Cleared per-entity by
+     * {@link releaseA11yProjection}.
+     */
+    private readonly a11yProjectionRequests;
     /** Persistent tabindex=-1 element in a11yRoot. When the focused a11y mirror is
      *  pruned (virtualization/streaming/removal) while it holds focus, we move
      *  focus here instead of letting the browser drop it to <body> — keeping the
@@ -1324,6 +1370,58 @@ export declare class Scene {
      * predicate, which is only tractable while it has one home.
      */
     private shouldProjectA11y;
+    /**
+     * Whether an `a11yProjection: 'onDemand'` entity is currently engaged enough to
+     * deserve a shadow node.
+     *
+     * Deliberately **not** hover alone. A keyboard or assistive-technology user
+     * generates no pointer events, so a hover-only trigger would withhold the
+     * semantic node from precisely the users it exists for. Three signals, any of
+     * which counts:
+     *
+     * - **Focus.** Covers keyboard traversal and AT-driven focus. Checked against
+     *   the live element so a node keeps its own focus rather than being pruned out
+     *   from under the user mid-interaction.
+     * - **Pointer target.** The entity under the pointer, so a mouse user gets the
+     *   same node a hover-gated design would have given them.
+     * - **Explicit request.** {@link Scene.requestA11yProjection}, for anything the
+     *   app knows is significant — the selected item, a search hit, a
+     *   just-announced element. This is the escape hatch that keeps the mode usable
+     *   when neither focus nor pointer applies.
+     *
+     * The entity stays hit-testable on canvas regardless, so a click always reaches
+     * it and promotes it on the next sync.
+     */
+    private a11yEngaged;
+    /**
+     * Whether `node` mirrors selectable text of its own.
+     *
+     * Such an entity must not be promoted by the pointer: its interactive a11y node
+     * would sit above the text mirror and eat the mousedown that starts a native
+     * selection.
+     */
+    private projectsSelectableText;
+    /**
+     * Keep `entity`'s a11y shadow node projected while it has
+     * `a11yProjection: 'onDemand'`.
+     *
+     * For anything the application knows matters but the engine cannot infer — the
+     * selected danmaku, a search hit, a node just announced in a live region.
+     * Without this, `'onDemand'` would be reachable only by focus or pointer, and
+     * an app-driven selection change would leave the selected entity semantically
+     * invisible.
+     *
+     * Idempotent. Has no effect on an `'eager'` entity, which is always projected.
+     */
+    requestA11yProjection(entity: Entity | string): void;
+    /**
+     * Drop a projection request made by {@link requestA11yProjection}.
+     *
+     * The node is not removed immediately: it survives while it is focused or under
+     * the pointer, and is pruned on the next sync that finds it unengaged. Releasing
+     * a request the scene does not hold is a no-op.
+     */
+    releaseA11yProjection(entity: Entity | string): void;
     private syncA11y;
     /**
      * Mirror one entity's static text ({@link Entity.getContentProjection}) as a
@@ -1341,6 +1439,34 @@ export declare class Scene {
      * culling and always count as visible, matching the legacy behavior.
      */
     private projectionBoxVisible;
+    /**
+     * The band of an entity's own y coordinates that is worth projecting, or
+     * `null` to project everything.
+     *
+     * {@link projectionBoxVisible} answers "is this entity near the viewport",
+     * which frees whole blocks that scroll away. It cannot help a single entity
+     * *taller* than the viewport: that entity's box always intersects, so every
+     * one of its visual lines was materialized — a `<span>` per line and, on the
+     * grid path, a `<span>` per glyph cluster. That is where "14.8k elements for a
+     * 346KB Markdown doc" comes from, and it is O(document) rather than
+     * O(viewport) in both element count and per-frame walk cost.
+     *
+     * Measured on one entity scrolled to its middle, real headed browsers
+     * (`benchmarks/projection-per-line/`): at 4000 lines, materializing every line
+     * costs 6.28 ms/frame on Chrome and 6.51 ms on Firefox with 36,000 child
+     * elements, against 0.28/0.16 ms and 963 elements when only the visible band
+     * is emitted. The gated cost is *flat* across a 20x document-size range, so
+     * this converts an asymptote rather than shaving a constant.
+     *
+     * Returns local-y bounds in the entity's own coordinate space, already
+     * expanded by `margin` and intersected with every `clipChildren` ancestor, so
+     * a line inside a scrolled container is measured against the container rather
+     * than the window. `null` means "no useful bound" — a degenerate transform, a
+     * rotation/skew that makes a y-band meaningless, or a boundless entity — and
+     * the caller must then project every line, because emitting nothing would
+     * silently drop text from selection, find-in-page and screen readers.
+     */
+    private projectionVisibleLocalYBand;
     private syncContentProjection;
     /**
      * Materialize a prepared grid in logical source order while positioning each

package/package.json

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