@grida/svg-editor 1.0.0-alpha.18 → 1.0.0-alpha.20

package/README.md

@@ -228,11 +228,21 @@ Each will become a public seam when a second surface implementation arrives and
 
 Geometry (world-space bboxes, screen ↔ local projection) is exposed via `editor.geometry`, not the `Surface` itself — the DOM surface registers a `MemoizedGeometryProvider` with the editor on attach so headless callers can query bounds without going through the surface.
 
-`@grida/svg-editor/dom` exports `attach_dom_surface(editor, { container, ... })` as the default DOM implementation, plus the surface-scoped types (`Camera`, `Gestures`, `SnapOptions`, `MemoizedGeometryProvider`, `DomComputedResolver`) that callers writing alternative surfaces or advanced integrations may need. It mounts the SVG into the container, wires pointer / keyboard listeners scoped to that container, and uses native `getBBox` / `getScreenCTM` for geometry. It is the only place in this package that imports DOM types.
+`@grida/svg-editor/dom` exports `attach_dom_surface(editor, { container, ... })` as the default DOM implementation, plus the surface-scoped types (`Camera`, `Gestures`, `SnapOptions`, `AttentionScope`, `MemoizedGeometryProvider`, `DomComputedResolver`) that callers writing alternative surfaces or advanced integrations may need. It mounts the SVG into the container, wires pointer / keyboard listeners scoped to that container, and uses native `getBBox` / `getScreenCTM` for geometry. It is the only place in this package that imports DOM types.
 
-The container is **exclusively owned** by the surface. Render toolbars, layer lists, inspectors, and any other interactive chrome as **siblings** of the container, not children. Children of the container interfere with pointer routing (capture redirects, hit-test ordering) and produce silent click breakage. The shipped `SvgEditorCanvas` React component enforces this by creating its own internal div; hosts using `domSurface` / `keynote.attach` directly are responsible for the same discipline. In development, the surface emits a `console.warn` at attach time when the container is non-empty.
+The container is **exclusively owned** by the surface. Render toolbars, layer lists, inspectors, and any other interactive chrome as **siblings** of the container, not children. Children of the container interfere with pointer routing (capture redirects, hit-test ordering) and produce silent click breakage. The shipped `SvgEditorCanvas` React component enforces this by creating its own internal div; hosts using `domSurface` / `keynote.attach` directly are responsible for the same discipline. In development, the surface emits a `console.warn` at attach time when the container is non-empty. Sibling chrome that drives editor commands should be registered into the attention scope (`handle.attention`, below) so the keymap stays live while the user works in it.
 
-**Attention gate.** The DOM surface installs document- and window-level keydown listeners (so a user with focus on a side-panel button can still hit editor shortcuts while the pointer is on the canvas). Those listeners are gated by an internal attention predicate: a key is claimed (and `preventDefault()`-ed) only when **focus is inside the container's subtree OR the pointer is over the container**. Body-focus alone — the natural state when the surface is embedded as a block in a longer document — is not attended, so the editor stays out of the way of page-level shortcuts (Space / arrows to scroll, Cmd+= to zoom, etc.). Passive observation listeners (modifier mirrors, blur resets) are not gated — they don't call `preventDefault()` and need to stay live across focus boundaries.
+**Attention gate.** The DOM surface installs document- and window-level keydown listeners (so a user with focus on a side-panel button can still hit editor shortcuts while the pointer is on the canvas). Those listeners are gated by an internal attention predicate: a key is claimed (and `preventDefault()`-ed) only when **focus is inside the attention scope OR the pointer is over it**. Body-focus alone — the natural state when the surface is embedded as a block in a longer document — is not attended, so the editor stays out of the way of page-level shortcuts (Space / arrows to scroll, Cmd+= to zoom, etc.). Passive observation listeners (modifier mirrors, blur resets) are not gated — they don't call `preventDefault()` and need to stay live across focus boundaries.
+
+The scope starts as the container alone. Editor-adjacent host chrome — an inspector, a toolbar, a zoom menu; anything that drives `commands.*` — is a DOM sibling of the container (per the exclusive-ownership rule above), so by default the gate cannot tell it from unrelated app surface: clicking its buttons moves focus out of the container, hovering it leaves the container, and the whole keymap (undo / delete / tool keys) goes dark until the user re-attends the canvas. Register such chrome into the scope via the handle:
+
+```ts
+const handle = attach_dom_surface(editor, { container });
+handle.attention.add(inspectorEl); // counts for focus-within + pointer-over
+handle.attention.remove(inspectorEl); // e.g. on unmount
+```
+
+Registered elements get the full keymap — with text inputs inside them still excluded by the keymap's own guard. The native clipboard gate (deliberately stricter: focus-only, never pointer-over) honors the registered set's focus arm the same way. `add` is idempotent; registrations live until removed or the surface detaches.
 
 ### Lifecycle
 
@@ -380,6 +390,7 @@ Write — selection-scoped. Writing the same value to every selected node has no
 editor.commands.set_property(name: string, value: string | null): void;
 
 editor.commands.preview_property(name: string): {
+  readonly live: boolean; // false once the session has ended, for any reason
   update(value: string): void;
   commit(): void;
   discard(): void;
@@ -388,6 +399,8 @@ editor.commands.preview_property(name: string): {
 
 The editor decides whether to write a presentation attribute vs. inline style for each selected node based on whichever wins the cascade for that element (P1). The preview session is what a number-input scrub or color-picker drag uses: many `update()` calls during drag, one `commit()` on pointer-up.
 
+A preview session ends as soon as its result can no longer become the document's next state — and after it ends, every method is a no-op and `session.live` is `false`. A discrete write to the same property (`set_property(name, …)`, or `set_paint` / `set_paint_from_gradient` on the same channel) **supersedes** an open session on that name, so a UI that mixes a picker drag with preset buttons cannot replay the stale dragged value when it commits on close; sessions on other property names are unaffected by discrete writes. Operations that detach the session's targets (`remove` / `cut`, `ungroup`), a document swap (`load` / `reset`), and `undo` / `redo` end open sessions on every name. Hosts that cache a session should consult `live` and lazily reopen — the bundled React hooks do.
+
 ### Observation — paint (`fill` / `stroke`)
 
 `fill` and `stroke` are common enough — and shape-different enough from a plain string — that they get a dedicated typed API. A solid color, a paint-server reference, and `currentColor` are not interchangeable strings; pretending they are is what produces editors that round-trip badly.
@@ -415,7 +428,9 @@ type PaintFallback = { kind: "none" } | { kind: "color"; value: Color };
 // Color preserves currentColor as a keyword at computed time (CSS Color 4 §4.4); the
 // rgb resolution happens at *used* value, which requires the surface's painting context.
 type Color =
-  | { kind: "rgb"; value: string } // any resolvable CSS color, normalized to rgb-ish
+  | { kind: "rgb"; value: string } // canonical lowercase hex (#rrggbb / #rrggbbaa) for any
+  //   literal resolvable without a rendering context (named / hex / rgb() / hsl() / hwb());
+  //   unresolved spaces (lab() / oklch() / color()) pass through as authored
   | { kind: "current_color" }; // unresolved keyword; surface dereferences at paint time
 
 type PaintValue = {
@@ -443,6 +458,7 @@ Write — selection-scoped (same reasoning as for generic properties):
 editor.commands.set_paint(channel: "fill" | "stroke", paint: Paint): void;
 
 editor.commands.preview_paint(channel: "fill" | "stroke"): {
+  readonly live: boolean; // false once the session has ended, for any reason
   update(paint: Paint): void;
   commit(): void;
   discard(): void;
@@ -946,6 +962,7 @@ What this editor will never be. Each one is a defensive perimeter for the princi
 - **Not a plugin host.** No public registry for tools, capabilities, gestures, HUD overlays, or serializers. (P1, P6.)
 - **Not a Figma-style multiplayer canvas.** State is local. Sync is the consumer's problem.
 - **Not customizable in HUD layout.** Style spec only — no overlay slots, no handle replacement, no custom chrome components.
+- **Not a customizable selection policy.** What a pick or a marquee selects (the marquee shadow rule, meta routing, additive) is a fixed product decision, owned by the labeled policy layer (`src/selection/`, spec [`docs/marquee-selection.md`](./docs/marquee-selection.md)). No host hook, provider, or registry swaps it; the opinion lives above the engine, never inside it, and never as a public knob.
 - **Not a private IR.** SVG is the source of truth. The editor does not maintain an alternative on-disk format, and the bytes are not projected from any in-memory canonical store. (The internal typed element IR described under [Paradigm § Element IR (internal)](#element-ir-internal) is a typed view over the parsed AST, not a store the file is derived from — the AST and the file are the source of truth, and the IR is rebuilt from them on each load.)
 - **Not a serializer playground.** Round-trip rules are fixed (P1). No "compact mode," no "Prettier mode," no consumer-supplied formatter.
 - **Not an input-interception hook.** The pick/tap observation (`subscribe_pick`) reports a click that already happened; it cannot prevent, delay, or replace the editor's own selection and gesture handling. A host that needs to intercept input owns the container and splices its own layer in (the DOM escape hatch) — it does not get a veto through the observation surface.

package/dist/{dom-BMzX1CXZ.d.ts → dom-CQkWJNrK.d.ts}

@@ -1,5 +1,54 @@
-import { c as SvgEditor, p as Gestures, s as SurfaceHandle, w as Camera } from "./editor-BSxTUsW_.js";
+import { c as SvgEditor, p as Gestures, s as SurfaceHandle, w as Camera } from "./editor-CxqRhhzP.js";
 import cmath from "@grida/cmath";
+//#region src/util/attention.d.ts
+/** The runtime handle returned by `create_attention_tracker`. */
+interface AttentionTracker {
+  /**
+   * `true` iff focus is inside the attention scope (the container's
+   * subtree or a registered element's subtree) OR the pointer is
+   * currently over any element of the scope. See module doc for the
+   * rationale.
+   *
+   * Pure read; no DOM mutation. Cheap enough to call once per keydown.
+   */
+  is_attended(): boolean;
+  /**
+   * `true` iff focus is inside the attention scope — the focus arm of
+   * {@link is_attended} alone, WITHOUT the pointer-over arm.
+   *
+   * Exists for the native clipboard gate (`dom.ts`): pointer-over is a
+   * sufficient signal to claim a keystroke (worst case: a stolen scroll)
+   * but NOT a copy/cut/paste gesture (worst case: destroying what the
+   * user believed they copied, or routing a paste meant for a host text
+   * field into the document). See docs/wg/feat-svg-editor/clipboard.md
+   * §Transport "Gating the native events".
+   */
+  is_focus_within(): boolean;
+  /**
+   * Register a host-chrome element into the attention scope. Editor-
+   * adjacent chrome — an inspector, a toolbar, a zoom menu; anything that
+   * drives `commands.*` — is a DOM *sibling* of the container (the
+   * container is exclusively surface-owned), so without registration the
+   * tracker cannot tell it apart from unrelated page surface: clicking
+   * its buttons moves focus out of the container, and hovering it fires
+   * the container's `pointerleave`, blacking out the whole keymap.
+   * Registered elements count for both arms — focus-within and
+   * pointer-over. Idempotent; re-adding a registered element is a no-op.
+   */
+  add(element: Element): void;
+  /**
+   * Unregister an element added via {@link add}. Also clears any
+   * still-latched pointer-over contribution from it (the element may be
+   * unmounted mid-hover — e.g. a popover closing under the cursor).
+   * Unknown elements are a no-op. The container itself cannot be
+   * removed; it is the scope's fixed root, not a registered extra.
+   */
+  remove(element: Element): void;
+  /** Detach the internal pointer-tracking listeners (container and every
+   *  registered element). */
+  dispose(): void;
+}
+//#endregion
 //#region src/core/snap/options.d.ts
 type SnapOptions = {
   /** When false, snap behavior and snap-guide rendering are both off. */enabled: boolean;
@@ -86,17 +135,39 @@ type DomSurfaceOptions = {
    */
   font_load_source?: EventTarget;
 };
+/**
+ * Host-extendable attention scope — public via `handle.attention`.
+ *
+ * The document-level keymap (undo / redo / delete / tool keys) is gated on
+ * attention: focus inside the scope, or pointer over it. The scope starts
+ * as the container alone, which makes editor-adjacent host chrome — an
+ * inspector, a toolbar, a zoom menu; anything that drives `commands.*` —
+ * indistinguishable from unrelated page surface (chrome must be a DOM
+ * *sibling* of the container, never a child). Registering a chrome element
+ * keeps the full keymap live while the user works in it, with
+ * text-input focus still excluded by the keymap's own guard. The native
+ * clipboard gate (deliberately stricter: focus-only, never pointer-over)
+ * honors the registered set's focus arm the same way.
+ *
+ * `add` is idempotent; `remove` of an unregistered element is a no-op.
+ * Registrations live for the surface's lifetime — `detach()` drops them
+ * with the tracker. Hosts with mounting/unmounting chrome (popovers,
+ * panels) pair `add` on mount with `remove` on unmount.
+ */
+type AttentionScope = Pick<AttentionTracker, "add" | "remove">;
 /**
  * Surface handle for the DOM surface. Extends the editor's core
- * `SurfaceHandle` with the viewport-scoped concerns: pan/zoom (`camera`)
- * and pointer/wheel/keyboard gesture bindings (`gestures`).
+ * `SurfaceHandle` with the viewport-scoped concerns: pan/zoom (`camera`),
+ * pointer/wheel/keyboard gesture bindings (`gestures`), and the
+ * host-extendable attention scope (`attention`).
  *
- * Camera + gestures are **surface-scoped**: detaching the surface drops
- * both. They never appear on the headless `SvgEditor`.
+ * Camera, gestures, and attention are **surface-scoped**: detaching the
+ * surface drops all three. They never appear on the headless `SvgEditor`.
  */
 type DomSurfaceHandle = SurfaceHandle & {
   camera: Camera;
   gestures: Gestures;
+  attention: AttentionScope;
 };
 /**
  * Attach a DOM surface to a headless editor. Returns a `DomSurfaceHandle`
@@ -163,4 +234,4 @@ declare function inverse_project_rect(rect: {
   f: number;
 }, offset: readonly [number, number]): cmath.Rectangle | null;
 //#endregion
-export { inverse_project_rect as a, DEFAULT_SNAP_OPTIONS as c, install_font_load_geometry_bump as i, SnapOptions as l, DomSurfaceOptions as n, project_delta_inverse_ctm as o, attach_dom_surface as r, project_point_through_ctm as s, DomSurfaceHandle as t };
+export { install_font_load_geometry_bump as a, project_point_through_ctm as c, attach_dom_surface as i, DEFAULT_SNAP_OPTIONS as l, DomSurfaceHandle as n, inverse_project_rect as o, DomSurfaceOptions as r, project_delta_inverse_ctm as s, AttentionScope as t, SnapOptions as u };