@vectojs/core 1.39.1 → 1.40.1

package/dist/tree/scene/ProjectionPolicy.d.ts

@@ -0,0 +1,162 @@
+/**
+ * Per-node visual projection policy (RFC4 §2, CTX-0601).
+ *
+ * This is the RFC's `projection` field under its in-tree name: the per-node
+ * knob lives on {@link Entity.domPolicy} (named before the RFC), so
+ * `ProjectionPolicy` is the value vocabulary and `Entity.domPolicy` is where
+ * it is stored. `a11yProjection` keeps governing the _semantic/AT_ mirror
+ * independently — the two knobs compose, neither silently overrides the other
+ * (RFC4 §2).
+ *
+ * - `'canvas'` — always canvas pixels through the scene's `IRenderer`. The
+ *   default: existing scenes behave byte-for-byte as today.
+ * - `'dom'` — always materialize through the DOM projection backend. Requires
+ *   a DOM backend and a supported node kind; otherwise falls back per §3 and
+ *   reports the fallback, never silently.
+ * - `'auto'` — the engine decides per node per frame from the Capability
+ *   Matrix below: native-interaction value vs materialization cost vs backend
+ *   availability. The only mode the engine may flip frame to frame.
+ */
+export type ProjectionPolicy = 'canvas' | 'dom' | 'auto';
+/** Where the negotiation landed, and why it landed anywhere but the request. */
+export type ProjectionFallbackReason = 'no-dom-backend' | 'unsupported-kind' | 'prohibitive-cost' | 'bulk-budget' | 'active-gesture' | 'focus-pinned' | 'hysteresis';
+/** Native-interaction value of materializing this kind in the DOM (§4). */
+export type ProjectionNativeValue = 'none' | 'low' | 'medium' | 'high';
+/** Materialization cost in one backend (§4). */
+export type ProjectionCost = 'low' | 'medium' | 'high' | 'prohibitive' | 'unsupported' | 'n/a';
+/**
+ * One Capability Matrix row (RFC4 §4): the negotiation inputs for a `domKind`.
+ *
+ * Values are **[opinions-to-measure]** starting positions from research §§8–10
+ * and the measured mirror costs — P1 must replace them with numbers. The only
+ * cell that overrides an explicit `'dom'` request besides `unsupported-kind`
+ * is `domCost: 'prohibitive'`, and even then it reports rather than refusing
+ * silently (§3 rule 2).
+ */
+export interface ProjectionCapabilityRow {
+    /** `false` means the kind has no DOM representation at all. */
+    readonly domSupported: boolean;
+    /** What native interaction (selection, IME, focus, form semantics) DOM buys. */
+    readonly nativeValue: ProjectionNativeValue;
+    /** Cost of one live element for this kind. */
+    readonly domCost: ProjectionCost;
+    /** Cost of (re-)implementing this kind in canvas pixels. */
+    readonly canvasCost: ProjectionCost;
+    /**
+     * The table's last column verbatim: where `'auto'` rests when no rule fires.
+     * Unknown kinds (absent from the matrix) default to `'canvas'`.
+     */
+    readonly autoDefault: 'canvas' | 'dom';
+}
+/**
+ * Capability Matrix (RFC4 §4) keyed by `Entity.domKind`.
+ *
+ * The matrix is keyed by backend creation hint, not entity class: `domKind`
+ * is the tag/content mapping the DOM backend consumes, so the row travels
+ * with the representation, and custom kinds start at the unknown-kind default
+ * (`unsupported-kind` → canvas) until a scene registers a row via
+ * {@link Scene.registerProjectionCapability | Scene.registerProjectionCapability}.
+ */
+export declare const DEFAULT_PROJECTION_CAPABILITIES: Readonly<Record<string, ProjectionCapabilityRow>>;
+/** Fallback row for `domKind`s absent from the matrix: canvas, reported. */
+export declare const UNKNOWN_PROJECTION_CAPABILITY: ProjectionCapabilityRow;
+/**
+ * Consecutive syncs an `'auto'` node must keep voting for the other backend
+ * before the sticky resolution flips (RFC4 §3 rule 3).
+ *
+ * Documented tunable: scenes override per scene via the
+ * `projectionHysteresisFrames` option. Each flip pays `unmount` + `mount`
+ * plus, for text, layout handoff — the count is P1 measurement work, not dogma.
+ */
+export declare const PROJECTION_AUTO_HYSTERESIS_FRAMES = 3;
+/**
+ * Maximum `'auto'`-resolved DOM residents per scene per frame (RFC4 §4
+ * particle-row backstop: bulk-count nodes stay canvas).
+ *
+ * Explicit `'dom'` requests are the author's choice and bypass the budget;
+ * only the engine's own `'auto'` placements count. Documented tunable: scenes
+ * override per scene via the `projectionAutoDomBudget` option.
+ */
+export declare const PROJECTION_AUTO_DOM_BUDGET = 500;
+/** Inputs to {@link resolveProjection} beyond the node's own policy. */
+export interface ProjectionNegotiationContext {
+    /** A `'dom'`-kind backend is registered on the scene. */
+    readonly domBackendMounted: boolean;
+    /** `false` under SSR/Node — negotiation short-circuits before the matrix. */
+    readonly hasDOM: boolean;
+}
+/** Output of {@link resolveProjection}: where, and why if not as requested. */
+export interface ProjectionOutcome {
+    readonly resolved: 'canvas' | 'dom';
+    /** `null` when the resolution honors the request (or _is_ the default). */
+    readonly reason: ProjectionFallbackReason | null;
+}
+/**
+ * Capability negotiation (RFC4 §3): resolve one node's policy to a backend.
+ *
+ * Pure: hysteresis, gesture/focus pins, and the bulk budget live scene-side
+ * (they need cross-frame and cross-node state); this function is the
+ * per-node-per-sync rule set, so it stays unit-testable without a `Scene`.
+ *
+ * Rules:
+ *
+ * 1. Explicit beats automatic; possible beats explicit. `'canvas'` and a
+ *    satisfiable `'dom'` are never second-guessed.
+ * 2. Fallbacks are reported, not silent — every non-honored request carries
+ *    its reason for the per-scene queryable surface.
+ * 3. No-DOM environments always resolve `'canvas'` before touching the matrix.
+ */
+export declare function resolveProjection(want: ProjectionPolicy, cap: ProjectionCapabilityRow, ctx: ProjectionNegotiationContext): ProjectionOutcome;
+/**
+ * One node's last negotiation, for the per-scene queryable surface (RFC4 §3
+ * rule 2 — precedent shape: the proposed `scene.inputCapabilities` in
+ * input-dispatch-contract-v2 §4). Plain data only: resolution data never
+ * carries an `HTMLElement`, materialization stays in `@vectojs/dom`.
+ */
+export interface ProjectionResolution {
+    readonly nodeId: string;
+    readonly want: ProjectionPolicy;
+    readonly resolved: 'canvas' | 'dom';
+    /** `null` when the resolution honors the request. */
+    readonly reason: ProjectionFallbackReason | null;
+}
+/**
+ * Scene-level projection capabilities (RFC4 §3 rule 2).
+ *
+ * Follows the proposed `scene.inputCapabilities` precedent shape
+ * (input-dispatch-contract-v2 §4 "Feature detection story"): a plain-data
+ * getter apps and devtools query to adapt, never to mutate.
+ */
+export interface SceneProjectionCapabilities {
+    /** A real DOM is present (false under SSR/Node). */
+    readonly hasDOM: boolean;
+    /** A `'dom'`-kind backend is registered on this scene. */
+    readonly domBackendMounted: boolean;
+    /** Kinds of all registered backends, in registration order. */
+    readonly backends: readonly string[];
+    /** Live hysteresis tunables (scene overrides of the module constants). */
+    readonly autoHysteresisFrames: number;
+    readonly autoDomBudget: number;
+}
+/** Per-node hysteresis + memo state owned by the scene (RFC4 §3 rule 3). */
+export interface ProjectionHysteresisState {
+    resolved: 'canvas' | 'dom';
+    /** Consecutive syncs voting against {@link resolved}. */
+    consecutive: number;
+    /** Frame id of the last vote, so render + a11y sync agree within a frame. */
+    lastFrame: number;
+}
+/**
+ * Sticky-vote half of hysteresis, factored pure for tests.
+ *
+ * Returns the resolution to keep plus the updated consecutive count: votes
+ * for the current backend reset the counter, votes against accumulate until
+ * `hysteresisFrames` consecutive, at which point the flip commits. The first
+ * vote for a node (no current) always commits — stickiness pins flips, never
+ * first placement.
+ */
+export declare function hysteresisVote(current: 'canvas' | 'dom' | undefined, desired: 'canvas' | 'dom', consecutive: number, hysteresisFrames: number): {
+    resolved: 'canvas' | 'dom';
+    consecutive: number;
+    flipped: boolean;
+};

package/dist/tree/scene/SemanticProjectionPolicy.d.ts

@@ -0,0 +1,119 @@
+import type { Entity } from '../Entity';
+/**
+ * Per-node semantic projection decision (RFC3 §5, CTX-0599).
+ *
+ * - `'project'` — materialize the node's semantic mirror (today's behaviour).
+ * - `'defer-to-browser'` — let browser recovery (canvas-a11y capture,
+ *   `html-in-canvas`, …) own this node's platform semantics. Allow-listed per
+ *   content class (§5): plain display text first, never controls, and always
+ *   feature-detected at runtime with a projection fallback. Unreachable while
+ *   {@link supportsHTMLInCanvas} is `false` — see
+ *   {@link isDeferrableSemanticNode}.
+ * - `'never'` — suppress the node's semantic mirror (the policy-level
+ *   equivalent of `Entity.a11yProjection: 'never'`).
+ *
+ * Adapters plug in _below_ the semantic tree: a future backend changes how
+ * text is painted, not what the entity means. The upper API (`projection`,
+ * `selectable`, `A11yAttributes`) stays stable across backend switches.
+ */
+export type SemanticProjectionDecision = 'project' | 'defer-to-browser' | 'never';
+/**
+ * Browser capabilities the policy may consult. Sourced live per decision via
+ * {@link getSemanticProjectionCapabilities} — capability only narrows cost,
+ * the framework-known default stays `'project'`.
+ */
+export interface SemanticProjectionCapabilities {
+    /** A real `html-in-canvas` backend exists (cf. RFC §7 standing). */
+    readonly htmlInCanvas: boolean;
+    /**
+     * Stable cross-engine canvas text recovery exists. Chromium capture is
+     * experimental as of RFC §7, so per RFC §3 rule 2 no conformance claim may
+     * depend on it — honestly `false` until that changes.
+     */
+    readonly canvasTextRecovery: boolean;
+}
+/** Runtime environment the policy may consult. */
+export interface SemanticProjectionEnvironment {
+    /** `false` under SSR/Node, where projection is a no-op (the `!a11yRoot` guard). */
+    readonly hasDOM: boolean;
+}
+/**
+ * Policy seam for the semantic tier (RFC3 §5). Wired at the single point
+ * where the tier decides per node (`Scene.shouldProjectA11y`); the default
+ * below preserves current behaviour exactly.
+ *
+ * Constraints on implementations (RFC §5):
+ *
+ * - `defer-to-browser` is allow-listed per content class via
+ *   {@link isDeferrableSemanticNode} — plain display text first, never the
+ *   default for controls — and always feature-detected at runtime with a
+ *   projection fallback.
+ * - A throwing policy must never drop semantics; `Scene` falls back to
+ *   `'project'` on throw.
+ */
+export interface SemanticProjectionPolicy {
+    /**
+     * Framework-known default per node; browser capability only narrows cost.
+     *
+     * @param node - The entity the semantic tier is deciding about.
+     * @param capabilities - Live browser capabilities (see {@link getSemanticProjectionCapabilities}).
+     * @param environment - Runtime environment (DOM presence, …).
+     */
+    choose(node: Entity, capabilities: SemanticProjectionCapabilities, environment: SemanticProjectionEnvironment): SemanticProjectionDecision;
+}
+/**
+ * Framework-known default: always `'project'`. Browser capability only
+ * narrows cost, never widens it — so the out-of-the-box behaviour is
+ * identical to having no policy at all.
+ */
+export declare const DEFAULT_SEMANTIC_PROJECTION_POLICY: SemanticProjectionPolicy;
+/** Live capabilities snapshot for {@link SemanticProjectionPolicy.choose}. */
+export declare function getSemanticProjectionCapabilities(): SemanticProjectionCapabilities;
+/**
+ * Whether `node` belongs to a content class that may one day defer its
+ * platform semantics to the browser (RFC §5 allow-list).
+ *
+ * Allow-listed today: nodes with no control semantics — no native-control tag,
+ * no control role, no keyboard tab stop — i.e. plain display text first, per
+ * §5. Everything else (controls, tab stops, natively selectable text whose
+ * DOM mirror owns selection per RFC §6) always keeps its framework mirror.
+ *
+ * Structural today: `Scene` additionally requires a real backend before any
+ * deferral takes effect, so this predicate changes no behaviour on its own —
+ * it is the gate a future backend consults, and the contract custom policies
+ * must honour when returning `'defer-to-browser'`.
+ */
+export declare function isDeferrableSemanticNode(node: Entity): boolean;
+/**
+ * Honest detail behind {@link supportsHTMLInCanvas}: `supported` is `false`
+ * until a real backend exists, and `reason` says why.
+ */
+export type HTMLInCanvasSupport = {
+    readonly supported: true;
+} | {
+    readonly supported: false;
+    readonly reason: 'no-dom' | 'no-backend';
+};
+/**
+ * Feature-detection contract for a future `html-in-canvas` backend
+ * (RFC §5 + RFC2 §8). Honest by construction:
+ *
+ * - SSR/Node (`typeof document === 'undefined'`) → `{ supported: false }`
+ *   without touching the DOM at all (core owns no unguarded
+ *   `document`/`window` contact per RFC1 §4).
+ * - Any probe throw (e.g. jsdom's unimplemented `getContext`) → `false`.
+ * - No backend today → `{ supported: false, reason: 'no-backend' }`.
+ *
+ * The probe is written as a real detection — a `2d` context exposing the
+ * `html-in-canvas` entry point (`drawElementImage`, RFC §7) reports `true` —
+ * so the day a browser ships it, this flips without a framework change. Until
+ * then there are no fake positives: nothing claims support it cannot use.
+ */
+export declare function describeHTMLInCanvasSupport(): HTMLInCanvasSupport;
+/**
+ * Whether an `html-in-canvas` backend is available right now (RFC §5 seam).
+ * `false` until a real backend exists — detection contract per RFC §5 +
+ * RFC2 §8, no fake positives. See {@link describeHTMLInCanvasSupport} for
+ * the reasoned form.
+ */
+export declare function supportsHTMLInCanvas(): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectojs/core",
-  "version": "1.39.1",
+  "version": "1.40.1",
   "publishConfig": {
     "access": "public"
   },
@@ -74,7 +74,7 @@
     "@vitest/coverage-v8": "^4.1.11",
     "esbuild": "^0.28.1",
     "jsdom": "^30.0.1",
-    "puppeteer-core": "^25.8.0",
+    "puppeteer-core": "^25.9.0",
     "tsup": "^8.3.5",
     "vitest": "^4.1.11"
   }