@vectojs/core 1.32.7 → 1.34.0

package/dist/tree/scene/content-break-carrier.d.ts

@@ -0,0 +1,77 @@
+/**
+ * How a projected line carries its trailing hard break.
+ *
+ * A projected line must hold its own line break in the DOM: copy, find-in-page
+ * and screen readers all read the projection, and a block whose lines are
+ * separate absolutely-positioned carriers has no flow structure a browser could
+ * synthesize a newline from. So the break character is written out explicitly.
+ *
+ * Writing it as an ordinary inline character is what this module exists to stop.
+ * The carriers are `white-space: pre`, so a trailing `\n` is a real preserved
+ * character in an inline context, and a browser gives it a selection rectangle
+ * of **zero width and full line height** at the end of the line. Chrome paints
+ * that rectangle, so selecting a line drew a caret-like vertical bar just past
+ * the last glyph — ink the canvas never drew, at a position no glyph occupies.
+ *
+ * Measured in real headed Chrome (DPR 1.76) on a live page, selecting one
+ * paragraph line of `1. 极致的性能与定制化：\n`: four selection rects, the last
+ * `x 495.18, w 0, h 31.82`. The same line with the break character removed
+ * produced one rect and no bar. Both projection paths were affected — a
+ * `CodeBlock` fixture reported one such rect on every line that owned a break
+ * (3 of 4 rows, including the empty row whose entire content is the break).
+ *
+ * ## Why the character stays in the DOM
+ *
+ * Deleting it fixes the bar and breaks copy: measured on the same page,
+ * stripping the trailing `\n` from every line of a block made
+ * `getSelection().toString()` return the block as one unbroken run. The break
+ * has to remain selectable text; it merely must not paint.
+ *
+ * `font-size: 0` is what separates those two. A zero font size leaves the
+ * character in the text content and in the selected string, while collapsing the
+ * line box it would otherwise contribute — measured on the same block, the
+ * zero-width full-height rect became `w 0, h 0` and the selected string still
+ * ended in `\n`.
+ *
+ * Rejected alternatives, each measured on the same live block:
+ *
+ * - **An absolutely positioned zero-size box** (`position: absolute; width: 0;
+ *   height: 0; overflow: hidden`) still produced the full-height rect, *and*
+ *   dropped the newline from the selected string — out of flow, the break no
+ *   longer serialises. Worse on both counts.
+ * - **Removing the character** and relying on the carriers' own box structure.
+ *   The line carriers do compute to `display: block`, so it is a reasonable
+ *   guess that the browser would synthesize the break — it does not. Copy came
+ *   back unbroken (see above).
+ *
+ * ## Why a shared module
+ *
+ * Both projection branches own break text and both had the defect:
+ * `Scene.syncContentProjection`'s carrier branch (plain and positioned-run
+ * lines) and {@link ContentGridProjector.syncGrid} (the last cell of a line, and
+ * an empty line's whole content). This follows the `content-line-window`
+ * precedent — a stateless helper both sides of the grid cut call, rather than a
+ * member on either — so the two cannot drift into disagreeing about how a break
+ * is represented, which would make copy fidelity depend on which branch drew a
+ * given block.
+ *
+ * Stateless by design: no `Scene`, no entities, no state beyond the node passed
+ * in.
+ */
+/**
+ * Append `breakText` to `owner`, suppressing its paint only if it is a hard
+ * break.
+ *
+ * A no-op for empty text, so callers can pass a separator that may legitimately
+ * be absent (the document's last line owns no break) without branching.
+ *
+ * A hard break goes into a `font-size: 0` span: still selectable, copyable and
+ * announced, but contributing no line box. Any other separator — a soft-wrap
+ * space — is appended as a plain text node, because its width is part of the
+ * line the canvas drew.
+ *
+ * The span is deliberately **not** `aria-hidden` and does **not** set
+ * `user-select: none`: the break is real content that a screen reader and a copy
+ * both want. Only its painted geometry is suppressed.
+ */
+export declare function appendContentBreak(owner: Node, breakText: string): void;

package/dist/tree/scene/content-caret.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Caret addressing inside a content projection: the shared vocabulary for
+ * describing "this exact position in this projected text".
+ *
+ * Extracted as a **shared module** rather than as part of any one collaborator
+ * because both sides of the extraction-3 cut need it. The selection-preservation
+ * pass that moves to {@link ContentSelectionManager} converts a live `Selection`
+ * endpoint into a linear character offset and back, while the pointer-to-caret
+ * resolution that stays in `Scene.ts` (`nearestTextPositionInProjection` and its
+ * per-line helpers) builds the same positions from hit coordinates. Duplicating
+ * the offset walk in both places would let the two drift, and a caret that
+ * disagrees with the offset it was derived from restores a selection to the wrong
+ * text.
+ *
+ * Every symbol here was module-private in `Scene.ts` and stays module-private to
+ * the package: `packages/core/src/index.ts` is `export * from './tree/Scene'`, so
+ * re-exporting would silently widen the public API. `DEC-0019` rule 3.
+ *
+ * Stateless and DOM-only by design — no `Scene`, no entities, no engine state.
+ */
+/** A concrete text caret position, usable as a Selection anchor or focus. */
+export interface TextCaretPosition {
+    node: Text;
+    offset: number;
+}
+export declare function collectTextNodes(root: HTMLElement): Text[];
+export declare function projectionAbsoluteOffset(root: HTMLElement, caret: TextCaretPosition): number | null;
+export declare function projectionCaretAt(root: HTMLElement, absoluteOffset: number, affinity: 'forward' | 'backward'): TextCaretPosition | null;

package/dist/tree/scene/content-line-window.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Which projected lines a content block materializes for a given visible band.
+ *
+ * Extracted as a **shared module** rather than onto a collaborator because both
+ * sides of the grid cut need it. `Scene.syncContentProjection` calls
+ * {@link projectionLineWindow} for the plain carrier branch and stays on the
+ * facade; {@link ContentGridProjector} calls {@link projectionGridLineWindow} for
+ * the grid branch and has moved. Duplicating the scan would let the two branches
+ * disagree about which lines are present, and a window that disagrees with the
+ * carriers it drives serves stale geometry to selection and find-in-page.
+ *
+ * This is the `content-caret` precedent from `DEC-0022`: a stateless helper that
+ * outlived the class it was private to.
+ *
+ * Every symbol here was module-private in `Scene.ts` and stays module-private to
+ * the package. The core barrel re-exports everything from `./tree/Scene`, so
+ * re-exporting from there would silently widen the public API (`DEC-0019` rule 3).
+ *
+ * Stateless by design — no `Scene`, no entities, no DOM.
+ */
+import type { PreparedContentGrid } from '@vectojs/text';
+import type { ContentProjection } from '../Entity';
+/** Half-open range of projected line indices to materialize. */
+export interface ProjectionLineWindow {
+    start: number;
+    /** Exclusive. */
+    end: number;
+    /** False when the whole document is being projected. */
+    gated: boolean;
+}
+/**
+ * The contiguous run of lines overlapping `band`, in entity-local y.
+ *
+ * **Contiguous on purpose.** A gap would break selection: the DOM order of
+ * carriers is what the browser walks when extending a selection or serialising
+ * a copy, so materializing lines 0-9 and 90-99 with nothing between them would
+ * let a drag from line 5 to line 95 silently splice out 80 lines of text. A
+ * single window can only lose text at its *edges*, where the user cannot reach
+ * without scrolling, and scrolling rebuilds the window.
+ *
+ * Falls back to the whole document whenever the answer is not clearly better:
+ * a null band, a document that fits, or a window that would cover everything
+ * anyway. Emitting nothing is never correct — projected text is what serves
+ * find-in-page, copy and, for static text, the screen reader.
+ */
+export declare function projectionLineWindow(lines: ReadonlyArray<{
+    y: number;
+    lineHeight?: number;
+}>, band: {
+    minY: number;
+    maxY: number;
+} | null, fallbackLineHeight: number): ProjectionLineWindow;
+/**
+ * {@link projectionLineWindow} for a prepared grid.
+ *
+ * A grid line's y comes from the parallel `projection.lines` entry when present
+ * and otherwise from `lineIndex * grid.lineHeight`, which is the same fallback
+ * the materialization loop uses for positioning — so the window and the carriers
+ * always agree on where a line is.
+ */
+export declare function projectionGridLineWindow(grid: PreparedContentGrid, projectionLines: ContentProjection['lines'], band: {
+    minY: number;
+    maxY: number;
+} | null): ProjectionLineWindow;

package/package.json

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