domotion-svg 0.10.1 → 0.11.0

package/dist/animation/animator.d.ts

@@ -4,7 +4,7 @@
  * Takes captured SVG frame content and composes them into a single
  * animated SVG with CSS keyframe transitions.
  */
-import { type CursorOverlay, type SelectorResolver } from "./cursor-overlay.js";
+import { type CursorAtResolver, type CursorOverlay, type SelectorResolver } from "./cursor-overlay.js";
 import type { MagicMove } from "./magic-move.js";
 export interface AnimationFrame {
     /** SVG content for this frame (from dom-to-svg) */
@@ -244,6 +244,14 @@ export interface AnimationConfig {
      * uses `selector`; otherwise pass undefined / null.
      */
     resolveSelector?: SelectorResolver;
+    /**
+     * DM-1106: auto cursor-TYPE hit-tester — given a viewport point and frame
+     * index, returns the cursor keyword under it (the caller builds this from the
+     * per-frame captured trees via `cursorAtPoint`). When provided, the overlay
+     * paints the matching glyph per element and switches at boundary crossings;
+     * when omitted, the overlay paints the single arrow.
+     */
+    resolveCursorAt?: CursorAtResolver;
     /**
      * Canvas background color painted behind every frame (a full-viewport
      * `<rect>`). Mirrors the single-frame path's `transparentRootBgRect`

package/dist/animation/animator.js

@@ -305,8 +305,8 @@ export function generateAnimatedSvg(config) {
             frameStarts.push(acc);
             acc += frameAdvanceMs(f);
         }
-        const resolved = resolveCursorScript(config.cursorOverlay, totalDuration, frameStarts, config.resolveSelector ?? null);
-        overlayMarkup = "\n" + cursorOverlayMarkup(resolved.positions, resolved.clicks, resolved.style, totalDuration);
+        const resolved = resolveCursorScript(config.cursorOverlay, totalDuration, frameStarts, config.resolveSelector ?? null, config.resolveCursorAt ?? null);
+        overlayMarkup = "\n" + cursorOverlayMarkup(resolved.positions, resolved.clicks, resolved.style, totalDuration, resolved.cursorTimeline);
     }
     // Canvas background rect — only when a non-transparent background is given.
     // Default (none / transparent) emits nothing so the SVG composites over the

package/dist/animation/cursor-glyphs.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Cursor glyph catalog (DM-1106).
+ *
+ * Maps every CSS `cursor` keyword to a small SVG glyph drawn from Lucide icons
+ * (MIT-licensed, https://lucide.dev) — scaled, rotated, and occasionally
+ * composited (an arrow + a badge, the way real OS drag-drop cursors look) to
+ * approximate what a browser paints. Lucide's line-art look is intentionally
+ * OS-agnostic: it doesn't pixel-match macOS / Windows / X11, but it reads as the
+ * right cursor at a glance and renders crisply at any scale (the whole point of
+ * the SVG pipeline).
+ *
+ * Each glyph is authored in Lucide's native 24×24 coordinate box. The renderer
+ * paints a white halo under a dark stroke so the cursor stays legible on any
+ * background (mirroring the white-outlined arrow the overlay already used). The
+ * `hotspot` is the point IN THAT 24×24 BOX that aligns to the cursor's (x, y) —
+ * e.g. the arrow tip, the I-beam center — so callers translate the glyph by
+ * `(x − hotspotX·scale, y − hotspotY·scale)`.
+ *
+ * This module is pure markup generation (no DOM); the overlay (DM-1106 phase 2)
+ * picks a glyph per captured `cursor` value and animates its position.
+ */
+/** A glyph authored in the Lucide 24×24 box. */
+export interface CursorGlyph {
+    /** Inner SVG markup (paths/lines/circles) in the 24×24 Lucide coordinate box. */
+    body: string;
+    /** Filled silhouette (white fill + dark outline, like a classic arrow) vs.
+     *  stroked line-art (dark stroke + white halo, the Lucide default look). */
+    fill?: boolean;
+    /** The point in the 24×24 box that lands on the cursor coordinate. */
+    hotspot: [number, number];
+    /** Optional rotation (degrees, about the box center 12,12) — e.g. vertical-text. */
+    rotate?: number;
+}
+/**
+ * Every CSS `cursor` keyword → its glyph. `auto`, `default`, `inherit`,
+ * `initial`, and an unresolved `url(...)` fallback all resolve to the arrow
+ * here; the overlay resolves `auto` to `text` / `default` per Chrome BEFORE
+ * looking up this table (DM-1106 phase 2). `none` is an empty glyph.
+ */
+export declare const CURSOR_GLYPHS: Record<string, CursorGlyph>;
+/** Canonical display order, grouped by the MDN cursor categories. */
+export declare const CURSOR_CATEGORIES: {
+    title: string;
+    values: string[];
+}[];
+/**
+ * Render a cursor glyph as an SVG `<g>`, positioned so its hotspot sits at
+ * `(x, y)` and the 24-box is scaled to `size` px. Paints a white halo under the
+ * dark glyph (filled glyphs use a white fill + dark outline). Returns "" for an
+ * empty glyph (`none`).
+ */
+export declare function cursorGlyphSvg(value: string, x: number, y: number, size?: number, color?: string): string;

package/dist/animation/cursor-glyphs.js

@@ -0,0 +1,138 @@
+/**
+ * Cursor glyph catalog (DM-1106).
+ *
+ * Maps every CSS `cursor` keyword to a small SVG glyph drawn from Lucide icons
+ * (MIT-licensed, https://lucide.dev) — scaled, rotated, and occasionally
+ * composited (an arrow + a badge, the way real OS drag-drop cursors look) to
+ * approximate what a browser paints. Lucide's line-art look is intentionally
+ * OS-agnostic: it doesn't pixel-match macOS / Windows / X11, but it reads as the
+ * right cursor at a glance and renders crisply at any scale (the whole point of
+ * the SVG pipeline).
+ *
+ * Each glyph is authored in Lucide's native 24×24 coordinate box. The renderer
+ * paints a white halo under a dark stroke so the cursor stays legible on any
+ * background (mirroring the white-outlined arrow the overlay already used). The
+ * `hotspot` is the point IN THAT 24×24 BOX that aligns to the cursor's (x, y) —
+ * e.g. the arrow tip, the I-beam center — so callers translate the glyph by
+ * `(x − hotspotX·scale, y − hotspotY·scale)`.
+ *
+ * This module is pure markup generation (no DOM); the overlay (DM-1106 phase 2)
+ * picks a glyph per captured `cursor` value and animates its position.
+ */
+// ── Lucide icon bodies (verbatim path data from lucide-icons/lucide) ──────────
+const L = {
+    arrow: `<path d="M4.037 4.688a.495.495 0 0 1 .651-.651l16 6.5a.5.5 0 0 1-.063.947l-6.124 1.58a2 2 0 0 0-1.438 1.435l-1.579 6.126a.5.5 0 0 1-.947.063z"/>`,
+    pointer: `<path d="M22 14a8 8 0 0 1-8 8"/><path d="M18 11v-1a2 2 0 0 0-2-2a2 2 0 0 0-2 2"/><path d="M14 10V9a2 2 0 0 0-2-2a2 2 0 0 0-2 2v1"/><path d="M10 9.5V4a2 2 0 0 0-2-2a2 2 0 0 0-2 2v10"/><path d="M18 11a2 2 0 1 1 4 0v3a8 8 0 0 1-8 8h-2c-2.8 0-4.5-.86-5.99-2.34l-3.6-3.6a2 2 0 0 1 2.83-2.82L7 15"/>`,
+    ibeam: `<path d="M17 22h-1a4 4 0 0 1-4-4V6a4 4 0 0 1 4-4h1"/><path d="M7 22h1a4 4 0 0 0 4-4"/><path d="M7 2h1a4 4 0 0 1 4 4"/>`,
+    menu: `<path d="M4 5h16"/><path d="M4 12h16"/><path d="M4 19h16"/>`,
+    spinner: `<path d="M21 12a9 9 0 1 1-6.219-8.56"/>`,
+    plus: `<path d="M5 12h14"/><path d="M12 5v14"/>`,
+    shortcut: `<path d="m15 14 5-5-5-5"/><path d="M4 20v-7a4 4 0 0 1 4-4h12"/>`,
+    ban: `<circle cx="12" cy="12" r="10"/><path d="M4.929 4.929 19.07 19.071"/>`,
+    move: `<path d="M12 2v20"/><path d="m15 19-3 3-3-3"/><path d="m19 9 3 3-3 3"/><path d="M2 12h20"/><path d="m5 9-3 3 3 3"/><path d="m9 5 3-3 3 3"/>`,
+    hand: `<path d="M18 11V6a2 2 0 0 0-2-2a2 2 0 0 0-2 2"/><path d="M14 10V4a2 2 0 0 0-2-2a2 2 0 0 0-2 2v2"/><path d="M10 10.5V6a2 2 0 0 0-2-2a2 2 0 0 0-2 2v8"/><path d="M18 8a2 2 0 1 1 4 0v6a8 8 0 0 1-8 8h-2c-2.8 0-4.5-.86-5.99-2.34l-3.6-3.6a2 2 0 0 1 2.83-2.82L7 15"/>`,
+    handGrab: `<path d="M18 11.5V9a2 2 0 0 0-2-2a2 2 0 0 0-2 2v1.4"/><path d="M14 10V8a2 2 0 0 0-2-2a2 2 0 0 0-2 2v2"/><path d="M10 9.9V9a2 2 0 0 0-2-2a2 2 0 0 0-2 2v5"/><path d="M6 14a2 2 0 0 0-2-2a2 2 0 0 0-2 2"/><path d="M18 11a2 2 0 1 1 4 0v3a8 8 0 0 1-8 8h-4a8 8 0 0 1-8-8 2 2 0 1 1 4 0"/>`,
+    moveH: `<path d="m18 8 4 4-4 4"/><path d="M2 12h20"/><path d="m6 8-4 4 4 4"/>`,
+    moveV: `<path d="M12 2v20"/><path d="m8 18 4 4 4-4"/><path d="m8 6 4-4 4 4"/>`,
+    diag: `<path d="M5 5 19 19"/><path d="M5 10 5 5 10 5"/><path d="M19 14 19 19 14 19"/>`, // ↖↘ (nwse): TL–BR line, arrowheads pointing NW + SE
+    diag2: `<path d="M19 5 5 19"/><path d="M14 5 19 5 19 10"/><path d="M10 19 5 19 5 14"/>`, // ↗↙ (nesw): TR–BL line, arrowheads pointing NE + SW
+    zoomIn: `<circle cx="11" cy="11" r="8"/><line x1="21" x2="16.65" y1="21" y2="16.65"/><line x1="11" x2="11" y1="8" y2="14"/><line x1="8" x2="14" y1="11" y2="11"/>`,
+    zoomOut: `<circle cx="11" cy="11" r="8"/><line x1="21" x2="16.65" y1="21" y2="16.65"/><line x1="8" x2="14" y1="11" y2="11"/>`,
+    crosshair: `<line x1="22" x2="2" y1="12" y2="12"/><line x1="12" x2="12" y1="22" y2="2"/>`,
+    cell: `<rect x="4" y="4" width="16" height="16" rx="1"/><line x1="12" x2="12" y1="2" y2="22"/><line x1="2" x2="22" y1="12" y2="12"/>`,
+    // Hand-drawn "?" (lucide circle-help was unavailable on main); used as a badge.
+    question: `<path d="M9 9a3 3 0 1 1 4.2 2.75c-.9.5-1.2 1-1.2 1.75"/><path d="M12 17h.01"/>`,
+};
+/**
+ * Compose the macOS-style arrow with a small badge tucked at its lower-right —
+ * the shape real OS cursors use for copy (+), alias (shortcut), no-drop (∅),
+ * context-menu (☰), and progress (spinner). The badge sits in a white rounded
+ * chip for contrast against the arrow and the page.
+ */
+function arrowBadge(badgeBody) {
+    // Badge: a 10×10 white chip at (12.5, 12.5)–(23.5, 23.5) with the icon scaled
+    // into it. The icon is drawn in its own 24-box then mapped into the chip.
+    return `${L.arrow}<g transform="translate(12.5 12.5)"><rect x="0" y="0" width="11" height="11" rx="2.5" fill="#fff" stroke="#1a1a1a" stroke-width="1"/><g transform="translate(1.4 1.4) scale(0.342)" fill="none" stroke="#1a1a1a" stroke-width="3.2" stroke-linecap="round" stroke-linejoin="round">${badgeBody}</g></g>`;
+}
+const ARROW = { body: L.arrow, fill: true, hotspot: [4.5, 4.5] };
+const ARROW_TIP = [4.5, 4.5];
+/**
+ * Every CSS `cursor` keyword → its glyph. `auto`, `default`, `inherit`,
+ * `initial`, and an unresolved `url(...)` fallback all resolve to the arrow
+ * here; the overlay resolves `auto` to `text` / `default` per Chrome BEFORE
+ * looking up this table (DM-1106 phase 2). `none` is an empty glyph.
+ */
+export const CURSOR_GLYPHS = {
+    // General
+    default: ARROW,
+    auto: ARROW,
+    none: { body: "", hotspot: [12, 12] },
+    // Links & status
+    "context-menu": { body: arrowBadge(L.menu), fill: true, hotspot: ARROW_TIP },
+    help: { body: arrowBadge(L.question), fill: true, hotspot: ARROW_TIP },
+    pointer: { body: L.pointer, hotspot: [8, 2] },
+    progress: { body: arrowBadge(L.spinner), fill: true, hotspot: ARROW_TIP },
+    wait: { body: L.spinner, hotspot: [12, 12] },
+    // Selection
+    cell: { body: L.cell, hotspot: [12, 12] },
+    crosshair: { body: L.crosshair, hotspot: [12, 12] },
+    text: { body: L.ibeam, hotspot: [12, 12] },
+    "vertical-text": { body: L.ibeam, hotspot: [12, 12], rotate: 90 },
+    // Drag & drop
+    alias: { body: arrowBadge(L.shortcut), fill: true, hotspot: ARROW_TIP },
+    copy: { body: arrowBadge(L.plus), fill: true, hotspot: ARROW_TIP },
+    move: { body: L.move, hotspot: [12, 12] },
+    "no-drop": { body: arrowBadge(L.ban), fill: true, hotspot: ARROW_TIP },
+    "not-allowed": { body: L.ban, hotspot: [12, 12] },
+    grab: { body: L.hand, hotspot: [12, 12] },
+    grabbing: { body: L.handGrab, hotspot: [12, 12] },
+    // Resizing & scrolling
+    "all-scroll": { body: `${L.move}<circle cx="12" cy="12" r="1.6" fill="#1a1a1a" stroke="none"/>`, hotspot: [12, 12] },
+    "col-resize": { body: `${L.moveH}<line x1="12" y1="4" x2="12" y2="20"/>`, hotspot: [12, 12] },
+    "row-resize": { body: `${L.moveV}<line x1="4" y1="12" x2="20" y2="12"/>`, hotspot: [12, 12] },
+    "e-resize": { body: L.moveH, hotspot: [12, 12] },
+    "w-resize": { body: L.moveH, hotspot: [12, 12] },
+    "ew-resize": { body: L.moveH, hotspot: [12, 12] },
+    "n-resize": { body: L.moveV, hotspot: [12, 12] },
+    "s-resize": { body: L.moveV, hotspot: [12, 12] },
+    "ns-resize": { body: L.moveV, hotspot: [12, 12] },
+    "ne-resize": { body: L.diag2, hotspot: [12, 12] },
+    "sw-resize": { body: L.diag2, hotspot: [12, 12] },
+    "nesw-resize": { body: L.diag2, hotspot: [12, 12] },
+    "nw-resize": { body: L.diag, hotspot: [12, 12] },
+    "se-resize": { body: L.diag, hotspot: [12, 12] },
+    "nwse-resize": { body: L.diag, hotspot: [12, 12] },
+    // Zoom
+    "zoom-in": { body: L.zoomIn, hotspot: [11, 11] },
+    "zoom-out": { body: L.zoomOut, hotspot: [11, 11] },
+};
+/** Canonical display order, grouped by the MDN cursor categories. */
+export const CURSOR_CATEGORIES = [
+    { title: "General", values: ["auto", "default", "none"] },
+    { title: "Links & status", values: ["context-menu", "help", "pointer", "progress", "wait"] },
+    { title: "Selection", values: ["cell", "crosshair", "text", "vertical-text"] },
+    { title: "Drag & drop", values: ["alias", "copy", "move", "no-drop", "not-allowed", "grab", "grabbing"] },
+    { title: "Resizing & scrolling", values: ["all-scroll", "col-resize", "row-resize", "n-resize", "e-resize", "s-resize", "w-resize", "ew-resize", "ns-resize", "ne-resize", "nw-resize", "se-resize", "sw-resize", "nesw-resize", "nwse-resize"] },
+    { title: "Zooming", values: ["zoom-in", "zoom-out"] },
+];
+/**
+ * Render a cursor glyph as an SVG `<g>`, positioned so its hotspot sits at
+ * `(x, y)` and the 24-box is scaled to `size` px. Paints a white halo under the
+ * dark glyph (filled glyphs use a white fill + dark outline). Returns "" for an
+ * empty glyph (`none`).
+ */
+export function cursorGlyphSvg(value, x, y, size = 22, color = "#1a1a1a") {
+    const g = CURSOR_GLYPHS[value] ?? CURSOR_GLYPHS.default;
+    if (g.body === "")
+        return "";
+    const s = size / 24;
+    const tx = x - g.hotspot[0] * s;
+    const ty = y - g.hotspot[1] * s;
+    const rot = g.rotate ? ` rotate(${g.rotate} 12 12)` : "";
+    const inner = g.fill
+        // Filled silhouette: white fill + dark outline (classic arrow look).
+        ? `<g fill="#fff" stroke="${color}" stroke-width="1.4" stroke-linejoin="round">${g.body}</g>`
+        // Line-art: white halo stroke under the dark stroke.
+        : `<g fill="none" stroke-linecap="round" stroke-linejoin="round"><g stroke="#fff" stroke-width="3.4">${g.body}</g><g stroke="${color}" stroke-width="1.7">${g.body}</g></g>`;
+    return `<g transform="translate(${tx.toFixed(2)} ${ty.toFixed(2)}) scale(${s.toFixed(4)})"><g transform="${rot.trim() || "translate(0 0)"}">${inner}</g></g>`;
+}

package/dist/animation/cursor-overlay.d.ts

@@ -14,8 +14,19 @@
  * the caller supplies. The frame index is computed from the event's `t`
  * (each frame's start/end time is derived from the animation timing).
  *
+ * Cursor TYPE (DM-1106): by default the overlay paints the right cursor for
+ * whatever is under it — arrow over body, hand over a link, I-beam over text,
+ * resize arrows over a resizer, etc. — switching exactly at element boundaries
+ * as the pointer moves, matching what the browser showed. The keyword comes
+ * from the captured `cursor` field (resolved per Blink, including `auto`); the
+ * caller supplies a `resolveCursorAt(x, y, frameIndex)` hit-tester (built from
+ * the per-frame trees) and the glyphs come from `cursor-glyphs.ts`. A per-event
+ * `cursor` override forces a specific glyph. Without a resolver the overlay
+ * falls back to the single arrow (back-compat).
+ *
  * See docs/13-cursor-overlay.md for the design.
  */
+import type { CapturedElement } from "../capture/types.js";
 export interface CursorStyle {
     /** Pointer variant. v1: only `mouse` is rendered (touch falls through to the same arrow glyph). */
     pointer: "mouse" | "touch";
@@ -58,6 +69,8 @@ export interface CursorMoveEvent {
         dx: number;
         dy: number;
     };
+    /** DM-1106: force a specific cursor keyword for this move (skip auto hit-test). */
+    cursor?: string;
 }
 export interface CursorClickEvent {
     type: "click";
@@ -72,6 +85,8 @@ export interface CursorShowEvent {
     t: number;
     x: number;
     y: number;
+    /** DM-1106: force a specific cursor keyword from this point (skip auto hit-test). */
+    cursor?: string;
 }
 export interface CursorHideEvent {
     type: "hide";
@@ -90,11 +105,14 @@ export type SelectorResolver = (sel: string, frameIndex: number) => {
     w: number;
     h: number;
 } | null;
+/** DM-1106: hit-tester for the cursor TYPE at a viewport point in a given frame. */
+export type CursorAtResolver = (x: number, y: number, frameIndex: number) => string;
 interface KeyframePoint {
     t: number;
     x: number;
     y: number;
     visible: boolean;
+    cursor?: string;
 }
 interface ResolvedClick {
     t: number;
@@ -103,21 +121,48 @@ interface ResolvedClick {
     button: "primary" | "secondary" | "middle";
     style: CursorStyle;
 }
+/** A cursor-keyword timeline entry: from time `t` the active glyph is `cursor`
+ *  (or null = cursor hidden). DM-1106. */
+export interface CursorTimelineEntry {
+    t: number;
+    cursor: string | null;
+}
+/**
+ * DM-1106: the effective cursor keyword at viewport point (x, y) for a captured
+ * tree — the LAST element in paint order (DFS pre-order) whose box contains the
+ * point. `cursor` inherits and was resolved per element at capture, so the
+ * topmost element's stored value (or `default` when omitted) is what Chrome
+ * painted. A z-index-agnostic approximation: good for the nested-element and
+ * later-sibling-on-top cases a cursor overlay cares about.
+ */
+export declare function cursorAtPoint(roots: CapturedElement[], x: number, y: number): string;
 /**
  * Resolve a script into absolute-coord position keyframes + click pulses.
  * Caller passes a `resolveSelector(sel, frameIndex)` if the script uses
  * selectors; otherwise pass `null` and selector events become no-ops with
  * a console warning.
  */
-export declare function resolveCursorScript(overlay: CursorOverlay, totalDurationMs: number, frameStartTimes: number[], resolveSelector: SelectorResolver | null): {
+export declare function resolveCursorScript(overlay: CursorOverlay, totalDurationMs: number, frameStartTimes: number[], resolveSelector: SelectorResolver | null, 
+/** DM-1106: auto cursor-type hit-tester. When provided, the result includes a
+ *  `cursorTimeline` driving per-glyph switching; when null, the overlay paints
+ *  the single arrow (back-compat). */
+resolveCursorAt?: CursorAtResolver | null): {
     positions: KeyframePoint[];
     clicks: ResolvedClick[];
     style: CursorStyle;
+    cursorTimeline: CursorTimelineEntry[] | null;
 };
 /**
  * Emit the `<g class="cursor-overlay">` markup for an already-resolved
  * timeline. Returns "" when the timeline has no positions or every keyframe
  * is invisible.
+ *
+ * When `cursorTimeline` is provided (DM-1106), the pointer's GLYPH switches over
+ * time to match what was under it: each distinct keyword gets a glyph drawn
+ * hotspot-at-origin inside the shared position-animated group, with a discrete
+ * opacity track that turns it on only during its windows (and visibility folds
+ * in as the all-glyphs-off `null` state). Without a timeline, the single white
+ * arrow paints (back-compat).
  */
-export declare function cursorOverlayMarkup(positions: KeyframePoint[], clicks: ResolvedClick[], style: CursorStyle, totalDurationMs: number): string;
+export declare function cursorOverlayMarkup(positions: KeyframePoint[], clicks: ResolvedClick[], style: CursorStyle, totalDurationMs: number, cursorTimeline?: CursorTimelineEntry[] | null): string;
 export {};

package/dist/animation/cursor-overlay.js

@@ -14,8 +14,41 @@
  * the caller supplies. The frame index is computed from the event's `t`
  * (each frame's start/end time is derived from the animation timing).
  *
+ * Cursor TYPE (DM-1106): by default the overlay paints the right cursor for
+ * whatever is under it — arrow over body, hand over a link, I-beam over text,
+ * resize arrows over a resizer, etc. — switching exactly at element boundaries
+ * as the pointer moves, matching what the browser showed. The keyword comes
+ * from the captured `cursor` field (resolved per Blink, including `auto`); the
+ * caller supplies a `resolveCursorAt(x, y, frameIndex)` hit-tester (built from
+ * the per-frame trees) and the glyphs come from `cursor-glyphs.ts`. A per-event
+ * `cursor` override forces a specific glyph. Without a resolver the overlay
+ * falls back to the single arrow (back-compat).
+ *
  * See docs/13-cursor-overlay.md for the design.
  */
+import { cursorGlyphSvg } from "./cursor-glyphs.js";
+/**
+ * DM-1106: the effective cursor keyword at viewport point (x, y) for a captured
+ * tree — the LAST element in paint order (DFS pre-order) whose box contains the
+ * point. `cursor` inherits and was resolved per element at capture, so the
+ * topmost element's stored value (or `default` when omitted) is what Chrome
+ * painted. A z-index-agnostic approximation: good for the nested-element and
+ * later-sibling-on-top cases a cursor overlay cares about.
+ */
+export function cursorAtPoint(roots, x, y) {
+    let best = null;
+    const visit = (n) => {
+        if (n.width > 0 && n.height > 0 && x >= n.x && x < n.x + n.width && y >= n.y && y < n.y + n.height)
+            best = n;
+        const kids = n.children;
+        if (kids != null)
+            for (const c of kids)
+                visit(c);
+    };
+    for (const r of roots)
+        visit(r);
+    return best?.cursor ?? "default";
+}
 const DEFAULT_STYLE = {
     pointer: "mouse",
     cursorFill: "rgb(255, 255, 255)",
@@ -32,7 +65,11 @@ const DEFAULT_STYLE = {
  * selectors; otherwise pass `null` and selector events become no-ops with
  * a console warning.
  */
-export function resolveCursorScript(overlay, totalDurationMs, frameStartTimes, resolveSelector) {
+export function resolveCursorScript(overlay, totalDurationMs, frameStartTimes, resolveSelector, 
+/** DM-1106: auto cursor-type hit-tester. When provided, the result includes a
+ *  `cursorTimeline` driving per-glyph switching; when null, the overlay paints
+ *  the single arrow (back-compat). */
+resolveCursorAt = null) {
     const baseStyle = { ...DEFAULT_STYLE, ...overlay.style };
     const events = [...overlay.events].sort((a, b) => a.t - b.t);
     const positions = [];
@@ -40,8 +77,8 @@ export function resolveCursorScript(overlay, totalDurationMs, frameStartTimes, r
     let curX = 0;
     let curY = 0;
     let visible = false;
-    const pushKey = (t, x, y, vis) => {
-        positions.push({ t, x, y, visible: vis });
+    const pushKey = (t, x, y, vis, cursor) => {
+        positions.push({ t, x, y, visible: vis, cursor });
         curX = x;
         curY = y;
         visible = vis;
@@ -58,7 +95,7 @@ export function resolveCursorScript(overlay, totalDurationMs, frameStartTimes, r
     };
     for (const ev of events) {
         if (ev.type === "show") {
-            pushKey(ev.t, ev.x, ev.y, true);
+            pushKey(ev.t, ev.x, ev.y, true, ev.cursor);
         }
         else if (ev.type === "hide") {
             pushKey(ev.t, curX, curY, false);
@@ -73,11 +110,12 @@ export function resolveCursorScript(overlay, totalDurationMs, frameStartTimes, r
                 // interpolate to the target over `dur`, so it slides rather than popping
                 // in mid-frame. (Both the first-positioning and subsequent-move cases
                 // emit the same start keyframe — DM-1073 collapsed a no-op branch here.)
-                pushKey(ev.t, curX, curY, true);
-                pushKey(ev.t + dur, target.x, target.y, true);
+                // The `cursor` override (if any) rides the whole slide.
+                pushKey(ev.t, curX, curY, true, ev.cursor);
+                pushKey(ev.t + dur, target.x, target.y, true, ev.cursor);
             }
             else {
-                pushKey(ev.t, target.x, target.y, true);
+                pushKey(ev.t, target.x, target.y, true, ev.cursor);
             }
         }
         else if (ev.type === "click") {
@@ -96,9 +134,69 @@ export function resolveCursorScript(overlay, totalDurationMs, frameStartTimes, r
     // through the whole loop.
     if (positions[positions.length - 1].t < totalDurationMs) {
         const last = positions[positions.length - 1];
-        positions.push({ t: totalDurationMs, x: last.x, y: last.y, visible: last.visible });
+        positions.push({ t: totalDurationMs, x: last.x, y: last.y, visible: last.visible, cursor: last.cursor });
+    }
+    const cursorTimeline = resolveCursorAt != null
+        ? buildCursorTimeline(positions, totalDurationMs, frameForT, resolveCursorAt)
+        : null;
+    return { positions, clicks, style: baseStyle, cursorTimeline };
+}
+/** Interpolated cursor state at time `t` from the position keyframes. Position
+ *  lerps within a keyframe interval; visibility + the per-segment cursor
+ *  override are step-held from the interval's start keyframe. */
+function stateAtTime(positions, t) {
+    if (t <= positions[0].t)
+        return positions[0];
+    const n = positions.length;
+    for (let i = 0; i < n - 1; i++) {
+        const a = positions[i], b = positions[i + 1];
+        if (t >= a.t && t <= b.t) {
+            const span = b.t - a.t;
+            const f = span > 0 ? (t - a.t) / span : 0;
+            return { x: a.x + (b.x - a.x) * f, y: a.y + (b.y - a.y) * f, visible: a.visible, cursor: a.cursor };
+        }
+    }
+    return positions[n - 1];
+}
+/**
+ * Build the cursor-keyword timeline (DM-1106). Samples the position timeline,
+ * resolving the cursor at each sample (an override wins; otherwise hit-test the
+ * frame under the point); emits an entry whenever the keyword changes, with the
+ * change time bisection-refined so the glyph switches AT the element boundary
+ * the pointer crosses (not at the next coarse sample). `null` = cursor hidden.
+ */
+function buildCursorTimeline(positions, totalDurationMs, frameForT, resolveCursorAt) {
+    const cursorAtTime = (t) => {
+        const s = stateAtTime(positions, t);
+        if (!s.visible)
+            return null;
+        return s.cursor ?? resolveCursorAt(s.x, s.y, frameForT(t));
+    };
+    const step = Math.max(8, Math.min(40, totalDurationMs / 400));
+    const timeline = [];
+    let prev = cursorAtTime(0);
+    timeline.push({ t: 0, cursor: prev });
+    for (let t = step; t <= totalDurationMs; t += step) {
+        const c = cursorAtTime(t);
+        if (c !== prev) {
+            // Refine the crossing time in (t-step, t] so the switch lands on the
+            // boundary, not the sample grid.
+            let lo = t - step, hi = t;
+            for (let k = 0; k < 14; k++) {
+                const mid = (lo + hi) / 2;
+                if (cursorAtTime(mid) === prev)
+                    lo = mid;
+                else
+                    hi = mid;
+            }
+            timeline.push({ t: Math.min(totalDurationMs, hi), cursor: c });
+            prev = c;
+        }
+    }
+    if (timeline[timeline.length - 1].t < totalDurationMs) {
+        timeline.push({ t: totalDurationMs, cursor: prev });
     }
-    return { positions, clicks, style: baseStyle };
+    return timeline;
 }
 function resolveMoveTarget(ev, curX, curY, frameIndex, resolveSelector) {
     if (ev.to != null)
@@ -125,8 +223,15 @@ function resolveMoveTarget(ev, curX, curY, frameIndex, resolveSelector) {
  * Emit the `<g class="cursor-overlay">` markup for an already-resolved
  * timeline. Returns "" when the timeline has no positions or every keyframe
  * is invisible.
+ *
+ * When `cursorTimeline` is provided (DM-1106), the pointer's GLYPH switches over
+ * time to match what was under it: each distinct keyword gets a glyph drawn
+ * hotspot-at-origin inside the shared position-animated group, with a discrete
+ * opacity track that turns it on only during its windows (and visibility folds
+ * in as the all-glyphs-off `null` state). Without a timeline, the single white
+ * arrow paints (back-compat).
  */
-export function cursorOverlayMarkup(positions, clicks, style, totalDurationMs) {
+export function cursorOverlayMarkup(positions, clicks, style, totalDurationMs, cursorTimeline = null) {
     if (positions.length === 0 || totalDurationMs <= 0)
         return "";
     const totalSec = totalDurationMs / 1000;
@@ -139,21 +244,42 @@ export function cursorOverlayMarkup(positions, clicks, style, totalDurationMs) {
     }
     // SMIL animateTransform requires keyTimes to start at 0 and end at 1; the
     // resolveCursorScript anchor at t=0 and t=totalDurationMs guarantees this.
-    // Visibility timeline: opacity flips between 0 and 1 at keyframes whose
-    // `visible` differs from the previous one. Use `discrete` calc-mode for
-    // step-wise transitions (no interpolation between 0 and 1).
-    const visValues = [];
-    for (const p of positions)
-        visValues.push(p.visible ? "1" : "0");
-    const cursorPath = macosCursorPath(style.cursorScale);
+    const posAnim = `<animateTransform attributeName="transform" type="translate" values="${valueStrs.join("; ")}" keyTimes="${keyTimes.join("; ")}" dur="${totalSec}s" repeatCount="indefinite" fill="freeze" />`;
     // Pulse SVG fragments — one per click, with timing keyed off `t`.
     const pulseMarkup = clicks.map((c, i) => buildPulseFragment(c, i, totalDurationMs)).join("\n");
-    return `  <g class="cursor-overlay" pointer-events="none">
-    <g class="cursor-arrow" opacity="0">
-      <animateTransform attributeName="transform" type="translate" values="${valueStrs.join("; ")}" keyTimes="${keyTimes.join("; ")}" dur="${totalSec}s" repeatCount="indefinite" fill="freeze" />
+    let pointerGroup;
+    if (cursorTimeline != null && cursorTimeline.length > 0) {
+        // DM-1106: one glyph per distinct keyword, each toggled by a discrete
+        // opacity track derived from the keyword timeline. The shared parent group
+        // carries the position animation; glyphs are hotspot-at-origin so each lands
+        // correctly regardless of its own hotspot.
+        const size = 22 * (style.cursorScale || 1);
+        const tKeyTimes = cursorTimeline.map((e) => (e.t / totalDurationMs).toFixed(4));
+        const kinds = Array.from(new Set(cursorTimeline.map((e) => e.cursor).filter((c) => c != null)));
+        const glyphLayers = kinds.map((kind) => {
+            const glyph = cursorGlyphSvg(kind, 0, 0, size, style.cursorStroke);
+            const opVals = cursorTimeline.map((e) => (e.cursor === kind ? "1" : "0"));
+            return `      <g opacity="0">
+        <animate attributeName="opacity" values="${opVals.join(";")}" keyTimes="${tKeyTimes.join(";")}" dur="${totalSec}s" repeatCount="indefinite" calcMode="discrete" fill="freeze" />
+        ${glyph}
+      </g>`;
+        }).join("\n");
+        pointerGroup = `    <g class="cursor-pointer">
+      ${posAnim}
+${glyphLayers}
+    </g>`;
+    }
+    else {
+        // Legacy single-arrow path (no auto cursor-type resolver supplied).
+        const visValues = positions.map((p) => (p.visible ? "1" : "0"));
+        pointerGroup = `    <g class="cursor-arrow" opacity="0">
+      ${posAnim}
       <animate attributeName="opacity" values="${visValues.join(";")}" keyTimes="${keyTimes.join(";")}" dur="${totalSec}s" repeatCount="indefinite" calcMode="discrete" fill="freeze" />
-      ${cursorPath}
-    </g>
+      ${macosCursorPath(style.cursorScale)}
+    </g>`;
+    }
+    return `  <g class="cursor-overlay" pointer-events="none">
+${pointerGroup}
 ${pulseMarkup}
   </g>`;
 }

package/dist/animation/index.d.ts

@@ -1,3 +1,4 @@
 export { buildMagicMove, type MagicMove, type MagicMoveSlide, } from "./magic-move.js";
 export { generateAnimatedSvg, type AnimationConfig, type AnimationFrame, type AnimationOverlay, type TypingOverlay, type TapOverlay, type SvgOverlay, type IntraFrameAnimation, } from "./animator.js";
-export { cursorOverlayMarkup, resolveCursorScript, type CursorOverlay, type CursorEvent, type CursorMoveEvent, type CursorClickEvent, type CursorShowEvent, type CursorHideEvent, type CursorStyle, type SelectorResolver, } from "./cursor-overlay.js";
+export { cursorOverlayMarkup, resolveCursorScript, cursorAtPoint, type CursorOverlay, type CursorEvent, type CursorMoveEvent, type CursorClickEvent, type CursorShowEvent, type CursorHideEvent, type CursorStyle, type CursorTimelineEntry, type SelectorResolver, type CursorAtResolver, } from "./cursor-overlay.js";
+export { CURSOR_GLYPHS, CURSOR_CATEGORIES, cursorGlyphSvg, type CursorGlyph } from "./cursor-glyphs.js";

package/dist/animation/index.js

@@ -5,4 +5,5 @@
 // typing / tap / SVG / cursor overlays.
 export { buildMagicMove, } from "./magic-move.js";
 export { generateAnimatedSvg, } from "./animator.js";
-export { cursorOverlayMarkup, resolveCursorScript, } from "./cursor-overlay.js";
+export { cursorOverlayMarkup, resolveCursorScript, cursorAtPoint, } from "./cursor-overlay.js";
+export { CURSOR_GLYPHS, CURSOR_CATEGORIES, cursorGlyphSvg } from "./cursor-glyphs.js";