@aceshooting/lyra-ui 3.7.0 → 3.9.0

package/dist/components/graph/graph.class.js

@@ -5,16 +5,30 @@ var __decorate = (this && this.__decorate) || function (decorators, target, key,
     return c > 3 && r && Object.defineProperty(target, key, r), r;
 };
 import { html, nothing, svg } from 'lit';
-import { property, state } from 'lit/decorators.js';
+import { property, state, query } from 'lit/decorators.js';
 import { styleMap } from 'lit/directives/style-map.js';
 import { LyraElement } from '../../internal/lyra-element.js';
 import { nextId, srOnly } from '../../internal/a11y.js';
 import { prefersReducedMotion } from '../../internal/motion.js';
 import { isRtl } from '../../internal/rtl.js';
+import { getScratchCtx } from '../../internal/canvas.js';
 import { styles } from './graph.styles.js';
 import { loadD3 } from './graph-loader.js';
+import { convexHull, hullPathD, hullCentroidX, hullTopY } from './graph-hull.js';
+import { drawGraphScene, drawPickingScene, pickColorToIndex } from './graph-canvas.js';
+import { layeredLayout } from '../../internal/layered-layout.js';
+import { finiteNumber, finiteRange, finiteInteger } from '../../internal/numbers.js';
 import '../skeleton/skeleton.class.js';
 const STUB_OFFSET_PX = 14; // matches the length of a typical broken-link stub in comparable UIs
+const EDGE_LABEL_OFFSET_PX = 4; // perpendicular offset from the segment midpoint, in world px
+const EDGE_LABEL_LENGTH_GATE_RATIO = 0.85; // label hides when its measured width exceeds this * edge length
+const EDGE_LABEL_WIDTH_CACHE_MAX = 512; // distinct measured label texts kept before the oldest entry is evicted
+const EXPAND_KEY_INTERVAL_MS = 500; // window for a double-Enter/Space to count as a double-activate
+const EXPAND_BADGE_R = 5; // world px, the "+" badge circle radius
+const EXPAND_BADGE_OFFSET = Math.SQRT1_2; // places the badge at the node's edge, diagonally upper-right
+const FOCUS_HALO_PADDING = 6; // world px added to the node's own radius for the halo ring
+const HULL_PADDING = 24; // world px; CSS mirrors this via stroke-width: 2 * --lyra-size-24px
+const CANVAS_NODE_LABEL_MIN_ZOOM = 0.5; // canvas-only declutter -- node labels draw only at/above this scale
 /**
  * Tiny deterministic PRNG (mulberry32, public-domain) used only when `seed`
  * is set, so a node's initial x/y is reproducible instead of whatever
@@ -65,6 +79,29 @@ function normalizeLinkDash(dash) {
         return undefined;
     return dash.join(' ');
 }
+/** Assigns a typed node with no explicit color a slot from the ordered categorical fallback
+ *  palette, cycling every 8 entries (`--lyra-graph-cat-1`…`--lyra-graph-cat-8`). `index` is the
+ *  node's `GraphNodeType`'s position in `nodeTypes`, not the node's own index in `nodes`. */
+function categoricalPaletteColor(index) {
+    return `var(--lyra-graph-cat-${(index % 8) + 1})`;
+}
+/** side = r * sqrt(pi), area-matched to a circle of radius r (side^2 = pi*r^2). Half-side is what
+ *  the path data actually needs, since both shapes are drawn centered on the origin and
+ *  positioned via a `transform="translate(x,y)"` per tick, never via absolute cx/cy. */
+function shapeHalfSide(r) {
+    return (r * Math.sqrt(Math.PI)) / 2;
+}
+/** A square, centered on the origin, side ~= 1.772 * r (area-matched to the circle of radius r). */
+function squarePath(r) {
+    const s = shapeHalfSide(r);
+    return `M ${-s} ${-s} L ${s} ${-s} L ${s} ${s} L ${-s} ${s} Z`;
+}
+/** The same square as `squarePath()`, rotated 45 degrees: same side length, vertices at the
+ *  half-diagonal distance (s * sqrt(2)) along each axis instead of the square's own corners. */
+function diamondPath(r) {
+    const d = shapeHalfSide(r) * Math.SQRT2;
+    return `M 0 ${-d} L ${d} 0 L 0 ${d} L ${-d} 0 Z`;
+}
 /**
  * `<lyra-graph>` — a force-directed node-link diagram with pan/zoom/drag.
  * Requires the optional peer deps `d3-force`/`d3-drag`/`d3-zoom`/`d3-selection`
@@ -80,26 +117,117 @@ function normalizeLinkDash(dash) {
  * already-rendered graph is a no-op; nothing re-derives already-positioned
  * nodes' x/y from the new value.
  *
+ * `hiddenTypes` filters nodes/links by `GraphNode.type` without discarding position state --
+ * `lastPositionById` remembers every node's last settled x/y across a hide/show round-trip, so
+ * toggling a type off and back on restores each node where it was instead of re-randomizing it.
+ *
+ * `communities` draws one translucent convex-hull blob per entry, behind links/nodes -- a hull's
+ * membership is the union of its own `memberIds` and every node whose `communityId` matches its
+ * `id`. A community with no currently-visible members (all its nodes hidden by `hiddenTypes`, or
+ * simply empty) renders no hull.
+ *
+ * `layout="layered"` swaps the d3-force simulation for a deterministic layered layout (see
+ * `src/internal/layered-layout.ts`) -- node drag is disabled in that mode, and `chargeStrength` is
+ * a documented no-op.
+ *
+ * `renderer="canvas"` swaps the per-node/per-link SVG DOM for a single DPR-aware `<canvas>` --
+ * every event/method/property behaves identically to `renderer="svg"` (the default), with hit-
+ * testing resolved via an offscreen color-picking canvas instead of DOM event targets. The
+ * documented trade-offs: no `::part(node)`/`::part(link)` styling (pixels, not elements -- theme
+ * via cssprops instead), no native SVG `<title>` tooltip (replaced by `part="tooltip"`), and a
+ * drawn focus ring instead of a CSS one. Keyboard roving/announcements are preserved through an
+ * offscreen `part="cursor-item"` button per node/link/hull, driving the identical roving-tabindex
+ * logic as `renderer="svg"`.
+ *
  * @customElement lyra-graph
- * @event lyra-node-click - `detail: { id }`.
+ * @event lyra-node-click - `detail: { id, x, y }`, where `x` and `y` are the
+ *   node's current coordinates in the graph's local drawing space.
  * @event lyra-link-click - `detail: { source, target, id? }`.
+ * @event lyra-node-enter - A node was hovered. `detail: { id }`. Suppressed while dragging or
+ *   panning. Also toggles a `data-hovered` attribute on that node's `[part="node"]` element for
+ *   pure-CSS theming (not a substitute for this event — a consumer computing its own
+ *   adjacency-based highlight needs the id, which only the event carries).
+ * @event lyra-node-leave - The hover from `lyra-node-enter` ended. `detail: { id }`.
+ * @event lyra-link-enter - A link was hovered. `detail: { source, target, id? }`. Same
+ *   suppression/`data-hovered` behavior as `lyra-node-enter`.
+ * @event lyra-link-leave - The hover from `lyra-link-enter` ended. `detail: { source, target, id?
+ *   }`.
+ * @event lyra-node-expand - A node was double-activated (native `dblclick`, or two Enter/Space
+ *   activations of the same focused node within 500ms). `detail: { id }`. Fires for any node
+ *   regardless of `GraphNode.expandable` -- that flag only controls the visual "+" affordance and
+ *   spoken "expandable" suffix.
+ * @event lyra-selection-change - `detail: { nodeIds, linkIds }`. Fires when `selectionMode` is not
+ *   `'none'` and the user activates/clears a node or link. The component never assigns
+ *   `selectedNodeIds`/`selectedLinkIds` itself -- controlled, mirroring `lyra-heatmap.selectedCell`.
+ * @event lyra-community-click - A hull was activated. `detail: { id }`.
  * @csspart base - The graph wrapper.
  * @csspart svg - The graph SVG.
  * @csspart node - A graph node.
  * @csspart link - A graph link.
  * @csspart arrowhead - The marker used by directed graph links.
  * @csspart label - A node label.
+ * @csspart link-label - A drawn edge label (only rendered when `showEdgeLabels` is set).
+ * @csspart expand-indicator - The "+" badge rendered on a node with `expandable: true`.
+ * @csspart focus-halo - The persistent ring tracking `focusId`'s node.
+ * @csspart hull - A community hull (behind links/nodes; role="button").
+ * @csspart community-label - A hull's label text.
  * @csspart live-region - The current graph item announcement.
  * @csspart data-list - A visually hidden list alternative for graph data.
  * @csspart empty - The empty-state message, shown when `nodes` is empty.
+ * @csspart canvas - The single canvas surface (`renderer="canvas"` only).
+ * @csspart tooltip - The hover tooltip (`renderer="canvas"` only; the SVG `<title>` replacement).
+ * @csspart cursor-items - The container of offscreen keyboard-roving items (`renderer="canvas"` only).
+ * @csspart cursor-item - An offscreen keyboard-roving item (`renderer="canvas"`'s a11y virtual cursor).
  * @cssprop [--lyra-node-fill=var(--lyra-color-brand)] - Default node fill, overridden per-node by `GraphNode.color`.
  * @cssprop [--lyra-link-color=var(--lyra-color-border)] - Default link stroke, overridden per-link by a link's own `color`.
+ * @cssprop [--lyra-graph-cat-1..8] - Ordered categorical fallback palette for a typed node with no
+ *   `GraphNodeType.color`, assigned by the type's index in `nodeTypes` (wraps every 8 entries).
+ *   Declared centrally in `tokens.styles.ts` so `<lyra-graph>` and any future `<lyra-graph-legend>`-
+ *   style component resolve the identical default.
+ * @cssprop [--lyra-graph-edge-label-halo=var(--lyra-color-surface)] - Legibility halo (`stroke`)
+ *   behind a drawn edge label, painted under the fill via `paint-order: stroke`.
+ * @cssprop [--lyra-graph-focus-halo-color=var(--lyra-color-brand)] - `focus-halo` stroke color.
+ * @cssprop [--lyra-graph-selected-color=var(--lyra-color-success)] - Selected node/link stroke.
+ * @cssprop [--lyra-graph-dimmed-opacity=1] - Opacity applied to a node/link when
+ *   `dimmedNodeIds`/`dimmedLinkIds` includes its id (both SVG and canvas renderers). `1` (the
+ *   default) is a no-op -- an unset host sees no visual change.
+ * @cssprop [--lyra-graph-hull-fill=var(--lyra-color-brand)] - Hull fill/stroke color.
+ * @cssprop [--lyra-graph-hull-opacity=0.12] - Hull element opacity (composites fill+stroke as one
+ *   group, avoiding a double-opacity seam at the fill/stroke boundary).
  */
 export class LyraGraph extends LyraElement {
     constructor() {
         super(...arguments);
         this.nodes = [];
         this.links = [];
+        /** Declares each `GraphNode.type` value's legend label, fill color, and shape. A typed node with
+         *  no matching entry here renders as untyped (default circle, token fill) but still participates
+         *  in `hiddenTypes` filtering by its raw `type` string. */
+        this.nodeTypes = [];
+        /** Hides every node whose raw `type` value is listed here (no matching `nodeTypes` entry
+         *  required), plus every link incident to a hidden node -- removed from the render, the
+         *  simulation input, the keyboard roving ring, the sr-only data list, and the accessible
+         *  diagram counts, as if absent. Positions round-trip via `lastPositionById`: toggling a type
+         *  off and back on restores each node where it was. */
+        this.hiddenTypes = [];
+        /** Renders one translucent hull per entry, behind links/nodes. Membership is the union of
+         *  `memberIds` and every node whose `communityId` matches this entry's `id`. */
+        this.communities = [];
+        /** `'force'` (default) runs the existing d3-force simulation, untouched. `'layered'` computes a
+         *  deterministic Sugiyama-lite layout (`src/internal/layered-layout.ts`, a shared,
+         *  dependency-free util suitable for any future layered-diagram consumer) instead -- no settle
+         *  animation, node drag disabled (dragging would fight a computed layout), `chargeStrength` a
+         *  documented no-op, `linkDistance` retunes the layer gap. Switching at runtime repositions
+         *  without a tween. */
+        this.layout = 'force';
+        /** `'svg'` (default, unchanged) renders the existing per-node/per-link DOM. `'canvas'` swaps to
+         *  a single `<canvas part="canvas">` -- the scale path (an honest ceiling for `'svg'`: dozens to
+         *  low hundreds of nodes; `'canvas'` targets roughly 5,000 nodes / 10,000 links). Feature-reduced
+         *  by design: no `::part(node)`/`::part(link)` styling (pixels, not elements -- theme via
+         *  cssprops), no SVG `<title>`, a drawn focus ring instead of a CSS one. All events/methods/
+         *  props otherwise behave identically across renderers. Runtime changes tear down and rebuild
+         *  the surface; positions survive via `prevById`/`lastPositionById`. */
+        this.renderer = 'svg';
         this.width = 800;
         this.height = 600;
         this.chargeStrength = -300;
@@ -108,12 +236,52 @@ export class LyraGraph extends LyraElement {
         this.maxZoom = 8;
         /** Accessible name forwarded from the host to the semantic graph SVG. */
         this.accessibleLabel = null;
+        /** Draws each resolved (non-dangling) link's `label` as visible SVG text at the segment
+         *  midpoint. Off by default — `GraphLink.label` stays spoken/tooltip-only, matching today's
+         *  behavior, unless this is set. */
+        this.showEdgeLabels = false;
+        /** Below this zoom scale, every drawn edge label is hidden (a `data-edge-labels-hidden`
+         *  attribute toggled on the zoomed `<g>`, no Lit re-render). Ignored when `showEdgeLabels` is
+         *  false. */
+        this.edgeLabelMinZoom = 0.6;
+        /** Declaratively centers the camera on this node id once, the first time it resolves (on mount
+         *  or when the id first appears in `nodes`) -- does not re-center on later mutations, so it
+         *  can't fight a user's panning on a streaming graph. Renders a persistent halo
+         *  (`part="focus-halo"`) around the node while set. See `focusNode()` for the imperative twin. */
+        this.focusId = null;
+        /** `'none'` (default) preserves today's behavior exactly -- no `aria-pressed`/`data-selected`,
+         *  no `lyra-selection-change`. Controlled, mirroring `lyra-heatmap.selectedCell`: the component
+         *  never mutates `selectedNodeIds`/`selectedLinkIds` itself, only emits intent; the host assigns
+         *  them back. */
+        this.selectionMode = 'none';
+        this.selectedNodeIds = [];
+        this.selectedLinkIds = [];
+        /** Node ids to render dimmed (`data-dimmed` on the matching `[part="node"]`, themeable via
+         *  `--lyra-graph-dimmed-opacity`). Controlled, mirroring `selectedNodeIds`/`selectedLinkIds`: the
+         *  component never assigns this itself, only renders it -- a host typically computes it from a
+         *  `lyra-node-enter`/`lyra-link-enter` hover (the complement of the hovered id's neighbor set,
+         *  computed from the host's own `links` array) and assigns the result back. Empty (the default)
+         *  renders every node at full opacity, unchanged from today. */
+        this.dimmedNodeIds = [];
+        /** Same contract as `dimmedNodeIds`, for links. A link's dimming key is the same `linkKey()`
+         *  value (`GraphLink.id`, else `` `${source}->${target}` ``) `selectedLinkIds` already uses. */
+        this.dimmedLinkIds = [];
         this.arrowMarkerId = nextId('graph-arrow');
         /** True until the lazy-loaded d3 peer dependencies have settled (success or failure). */
         this.loading = true;
         this.simNodes = [];
         this.simLinks = [];
         this.danglingLinks = [];
+        /** Every node's last-known settled position, keyed by id, independent of current visibility --
+         *  consulted by `rebuildSimulation()` (after the existing carried-over-position map) so a
+         *  `hiddenTypes` toggle restores a node where it was instead of re-randomizing it. Pruned to ids
+         *  present in `this.nodes` (not just currently-visible ones) on every rebuild. */
+        this.lastPositionById = new Map();
+        /** The `hiddenNodeCount` computed by the most recent `rebuildSimulation()` -- lets that method
+         *  tell "nothing has ever been hidden" (never touch `graphLiveText`, so a consumer that never
+         *  sets `hiddenTypes` keeps today's exact live-region output) apart from "a hide was just
+         *  cleared" (still announce the resulting "0 of N" count). */
+        this.lastHiddenNodeCount = 0;
         /** One roving tab stop across all nodes and links; nodes are the initial entry order. */
         this.activeGraphItem = 0;
         this.graphLiveText = '';
@@ -126,11 +294,165 @@ export class LyraGraph extends LyraElement {
          *  simNodes/simLinks properties (see rebuildSimulation()'s doc comment). */
         this.nodeEls = [];
         this.nodeLabelEls = [];
+        this.expandIndicatorEls = [];
+        /** Tracks the index/time of the last Enter/Space activation, for double-Enter expand detection
+         *  (mirroring native dblclick semantics for keyboard users). */
+        this.lastKeyActivateIndex = null;
+        this.lastKeyActivateTime = 0;
+        /** The last `focusId` value `focusNode()` was auto-invoked for by `updated()`'s declarative
+         *  centering branch -- guards against re-centering on every update while `focusId` stays set
+         *  (see the `focusId` property doc for why it only ever centers once per value). Reset to `null`
+         *  whenever `focusId` itself is cleared, so the same id can center again later. */
+        this.lastAppliedFocusId = null;
+        this.communityHullEls = [];
+        this.communityLabelEls = [];
+        this.pickDirty = true;
+        this.canvasCamera = { k: 1, x: 0, y: 0 };
+        /** Flat, index-aligned list matching `drawPickingScene()`'s own hulls-then-links-then-nodes pick
+         *  order -- rebuilt by `redrawPickCanvas()` alongside the pick canvas itself, so a pick color's
+         *  decoded index always maps back to the exact item it was drawn for. */
+        this.pickItems = [];
+        /** Whether `canvasScene` was built with edge labels included -- the zoom gate makes the scene
+         *  camera-dependent at exactly two thresholds (`edgeLabelMinZoom`, `CANVAS_NODE_LABEL_MIN_ZOOM`),
+         *  so a camera-only draw that crosses either must rebuild instead of reusing the cache. */
+        this.canvasSceneHasEdgeLabels = false;
+        /** True for a camera tween's whole duration (set before its first frame, cleared on
+         *  resolution) -- `isPanning` alone doesn't cover this: `applyZoomTransform()`'s per-frame
+         *  `zoomBehavior.transform()` call on a non-transition selection fires d3-zoom's
+         *  start/zoom/end synchronously within that single call, so `isPanning` flips true-then-false
+         *  within one frame rather than staying true for the tween's real duration the way an actual
+         *  user gesture does. */
+        this.isCameraTweening = false;
         this.linkEls = [];
+        this.linkLabelEls = [];
+        /** Per-simLink-index flip cache for the length declutter gate -- `onTick()` only writes
+         *  `visibility` when the boolean actually changes, not every tick. */
+        this.linkLabelHiddenByLength = [];
+        this.edgeLabelWidthCache = new Map();
         /** Dangling-stub `<line>`s, index-aligned with `danglingLinks` -- cached separately from
          *  `linkEls` (real, simulated links only) so onTick() can write their positions too; see
          *  onTick()'s own comment for why a stub needs this at all. */
         this.danglingLinkEls = [];
+        /** Writing a transform on a plain (non-transition) selection makes d3-zoom fire its own
+         *  start/zoom/end sequence synchronously, in this same call -- `isApplyingZoomTransform` lets
+         *  the zoom `'start'` handler tell that self-triggered echo apart from a genuine external
+         *  gesture, so a camera tween's own per-frame write doesn't cancel itself. */
+        this.isApplyingZoomTransform = false;
+        this.onCanvasDprChange = () => {
+            this.watchCanvasDpr();
+            this.markCanvasDirty();
+        };
+        this.onCanvasPointerDown = (e) => {
+            if (e.button !== 0)
+                return; // primary button only, matching native `click`'s own semantics
+            this.canvasPointerDownAt = { x: e.clientX, y: e.clientY };
+            if (this.layout === 'layered')
+                return; // drag disabled in layered mode, same as svg mode
+            const hit = this.hitTest(e.clientX, e.clientY);
+            if (hit?.kind === 'node') {
+                this.canvasDragNode = hit.node;
+                this.canvasPointerId = e.pointerId;
+                this.canvasEl.setPointerCapture(e.pointerId);
+                hit.node.fx = hit.node.x;
+                hit.node.fy = hit.node.y;
+                this.simulation?.alphaTarget(0.3).restart();
+            }
+        };
+        this.onCanvasPointerMove = (e) => {
+            if (this.canvasDragNode && this.canvasPointerId === e.pointerId) {
+                const rect = this.canvasEl.getBoundingClientRect();
+                this.canvasDragNode.fx = (e.clientX - rect.left - this.canvasCamera.x) / this.canvasCamera.k;
+                this.canvasDragNode.fy = (e.clientY - rect.top - this.canvasCamera.y) / this.canvasCamera.k;
+                this.markCanvasDirty();
+                return;
+            }
+            // Coalesce hover hit-testing to one per animation frame (see pendingHover's doc) -- only the
+            // latest position matters, and running the readback-per-pointermove would multiply the cost
+            // by however many moves the browser delivers between paints.
+            this.pendingHover = { x: e.clientX, y: e.clientY };
+            if (this.hoverRafId != null)
+                return;
+            this.hoverRafId = requestAnimationFrame(() => {
+                this.hoverRafId = undefined;
+                const pending = this.pendingHover;
+                this.pendingHover = undefined;
+                if (!pending)
+                    return;
+                // While the force simulation is still ticking, every tick invalidates the pick canvas, so
+                // resolving hover here would re-render the full offscreen picking scene once per frame on
+                // top of the per-tick visible redraw -- and the result would be stale a frame later anyway,
+                // since positions are still moving. Defer hover resolution until the layout settles; the
+                // next pointermove after that picks it up.
+                if (this.pickDirty && this.simulationIsTicking())
+                    return;
+                const hit = this.hitTest(pending.x, pending.y);
+                this.updateCanvasTooltip(hit, pending.x, pending.y);
+            });
+        };
+        this.onCanvasPointerUp = (e) => {
+            // Starting a drag on a node (onCanvasPointerDown) and ending it here without ever crossing the
+            // move-distance threshold below is exactly a plain click -- release the drag state first, but
+            // keep going into the same click-vs-drag distance check every pointerup goes through, instead
+            // of returning early and silently swallowing the click. This mirrors svg mode, where a plain
+            // click on a node fires both d3-drag's own start/end (a no-op, since fx/fy never actually
+            // moved) and the browser's native `click` event -- the two aren't mutually exclusive there
+            // either.
+            if (this.canvasDragNode && this.canvasPointerId === e.pointerId) {
+                this.simulation?.alphaTarget(0);
+                this.canvasDragNode.fx = null;
+                this.canvasDragNode.fy = null;
+                this.canvasDragNode = undefined;
+                this.canvasPointerId = undefined;
+                this.markCanvasDirty();
+            }
+            const down = this.canvasPointerDownAt;
+            this.canvasPointerDownAt = undefined;
+            if (!down)
+                return;
+            if (Math.hypot(e.clientX - down.x, e.clientY - down.y) > 5)
+                return; // a pan/drag gesture, not a click
+            const hit = this.hitTest(e.clientX, e.clientY);
+            if (!hit) {
+                this.clearSelection();
+                return;
+            }
+            if (hit.kind === 'node')
+                this.onNodeClick(hit.node, e);
+            else if (hit.kind === 'link')
+                this.onLinkClick(hit.link, e);
+            else
+                this.onCommunityClick(hit.entry.community);
+        };
+        this.onCanvasPointerLeave = () => {
+            // Drop any coalesced hover still waiting on its frame -- letting it run after the pointer
+            // already left would re-show the tooltip this handler is about to hide.
+            this.pendingHover = undefined;
+            if (this.hoverRafId != null) {
+                cancelAnimationFrame(this.hoverRafId);
+                this.hoverRafId = undefined;
+            }
+            this.updateCanvasTooltip(undefined, 0, 0);
+        };
+        this.onCanvasDblClick = (e) => {
+            const hit = this.hitTest(e.clientX, e.clientY);
+            const node = hit?.kind === 'node' ? hit.node : this.nodeAtCanvasPoint(e.clientX, e.clientY);
+            if (!node)
+                return; // background dblclick still reaches d3-zoom's own zoom-in, same as svg mode
+            // d3-zoom's own default double-click-to-zoom-in handler is bound to this identical <canvas>
+            // element (not an ancestor, so plain stopPropagation() -- which only blocks *bubbling*, not a
+            // sibling listener on the very same target -- would not suppress it). Matches svg mode's own
+            // onNodeDblClick(), which stops the equivalent bubble-phase echo on the svg one level up.
+            e.stopImmediatePropagation();
+            this.emit('lyra-node-expand', { id: node.id });
+        };
+        /** Suppresses hover events/`data-hovered` while a node drag is in progress (tracked from the
+         *  existing d3-drag `.on('start')`/`.on('end')` handlers in `applyInteractions()`) — a drag
+         *  crossing over other nodes/links would otherwise spam enter/leave pairs unrelated to genuine
+         *  pointer hovering. */
+        this.isDragging = false;
+        /** Same purpose as `isDragging`, for d3-zoom pan/zoom gestures (tracked from `applyInteractions()`'s
+         *  zoom `.on('start')`/`.on('end')` handlers, added by this same change). */
+        this.isPanning = false;
     }
     static { this.styles = [LyraElement.styles, styles, srOnly]; }
     connectedCallback() {
@@ -146,6 +468,16 @@ export class LyraGraph extends LyraElement {
         // the existing simulation in place instead.
         if (this.d3) {
             this.simulation?.restart();
+            // renderer="canvas" mode's own resize/DPR watchers are torn down by disconnectedCallback()
+            // below on every disconnect (including this reconnect) -- the <canvas> element itself
+            // survived the reparent along with the rest of this shadow tree (canvasEl === zoomedEl still
+            // holds), so re-arm them in place instead of waiting for a property-driven update that a bare
+            // reparent never triggers.
+            if (this.renderer === 'canvas' && this.canvasEl && this.canvasEl === this.zoomedEl) {
+                this.watchCanvasResize();
+                this.watchCanvasDpr();
+                this.markCanvasDirty();
+            }
             return;
         }
         void loadD3().then((mods) => {
@@ -162,6 +494,21 @@ export class LyraGraph extends LyraElement {
     disconnectedCallback() {
         super.disconnectedCallback();
         this.simulation?.stop();
+        // An in-flight focusNode()/fit() tween would otherwise keep scheduling frames and writing
+        // zoom transforms against the detached tree -- cancel it (which also settles the caller's
+        // pending Promise with `false` instead of leaving it hanging forever).
+        this.cancelCameraTween();
+        this.canvasResizeObserver?.disconnect();
+        this.canvasDprQuery?.removeEventListener('change', this.onCanvasDprChange);
+        if (this.canvasDrawRafId != null) {
+            cancelAnimationFrame(this.canvasDrawRafId);
+            this.canvasDrawRafId = undefined;
+        }
+        if (this.hoverRafId != null) {
+            cancelAnimationFrame(this.hoverRafId);
+            this.hoverRafId = undefined;
+        }
+        this.pendingHover = undefined;
     }
     /**
      * A caller-supplied `radius` is clamped to [MIN_RADIUS, MAX_RADIUS] (and a
@@ -174,6 +521,636 @@ export class LyraGraph extends LyraElement {
         const r = n.radius ?? (MIN_RADIUS + MAX_RADIUS) / 2;
         return Number.isFinite(r) ? Math.min(MAX_RADIUS, Math.max(MIN_RADIUS, r)) : (MIN_RADIUS + MAX_RADIUS) / 2;
     }
+    /** `width`/`height` normalized to a finite, positive viewport size — an invalid attribute value
+     *  would otherwise flow straight into `forceCenter`, the SVG `viewBox`, and the canvas backing
+     *  store's `width`/`height`, producing `NaN` geometry/transforms that silently render nothing
+     *  instead of erroring. */
+    get safeWidth() {
+        return finiteRange(this.width, 800, 1);
+    }
+    get safeHeight() {
+        return finiteRange(this.height, 600, 1);
+    }
+    /** `minZoom`/`maxZoom` normalized to finite, positive scale bounds before ever reaching
+     *  d3-zoom's `scaleExtent()` or a camera-clamp `Math.min`/`Math.max` — a non-finite bound would
+     *  otherwise poison every subsequent zoom/pan computation with `NaN`. */
+    get safeMinZoom() {
+        return finiteRange(this.minZoom, 0.1, 0.001, 1000);
+    }
+    get safeMaxZoom() {
+        return finiteRange(this.maxZoom, 8, 0.001, 1000);
+    }
+    /** `edgeLabelMinZoom` is compared directly against the live camera scale (same domain as
+     *  `minZoom`/`maxZoom`), so it's normalized with the same bounds -- a non-finite value would
+     *  otherwise make every `>=`/`<` comparison against it silently `false`/`true` forever. */
+    get safeEdgeLabelMinZoom() {
+        return finiteRange(this.edgeLabelMinZoom, 0.6, 0.001, 1000);
+    }
+    /** `seed`, normalized to a finite integer when set -- `undefined` (unseeded/random) is left
+     *  untouched, since it's a meaningful third state, not a missing number. Without this,
+     *  `hashNodeSeed`/`mulberry32`'s `>>> 0` coercion would silently fold `NaN`/`Infinity` to `0`
+     *  instead of normalizing an out-of-range attribute value the way every other numeric prop here
+     *  does. */
+    get safeSeed() {
+        return this.seed == null ? undefined : finiteInteger(this.seed, 0);
+    }
+    /** `chargeStrength` is a signed d3-force strength (negative = repulsion, positive = attraction)
+     *  — only guarded for finiteness, not clamped to a range, since either sign is a legitimate
+     *  value. */
+    get safeChargeStrength() {
+        return finiteNumber(this.chargeStrength, -300);
+    }
+    /** `linkDistance` normalized to a finite, non-negative pixel distance — feeds `forceLink()`'s
+     *  `distance()`, the layered layout's `gapY`, and the neighbor-jitter spawn radius, none of
+     *  which have a sane meaning for a negative/non-finite value. */
+    get safeLinkDistance() {
+        return finiteRange(this.linkDistance, 100, 0);
+    }
+    resolveNodeType(node) {
+        return node.type != null ? this.nodeTypes.find((t) => t.id === node.type) : undefined;
+    }
+    nodeShape(node) {
+        return this.resolveNodeType(node)?.shape ?? 'circle';
+    }
+    /** Resolution precedence: `node.color` (existing, most specific) > matched `GraphNodeType.color`
+     *  > the ordered categorical fallback palette by the type's index in `nodeTypes` > (returns
+     *  `undefined`, letting the untyped `--lyra-node-fill` token default apply). Both data-driven
+     *  color sources pass the existing `sanitizeNodeColor()`. */
+    nodeFill(node) {
+        const ownColor = sanitizeNodeColor(node.color);
+        if (ownColor)
+            return ownColor;
+        const type = this.resolveNodeType(node);
+        if (!type)
+            return undefined;
+        const typeColor = sanitizeNodeColor(type.color);
+        if (typeColor)
+            return typeColor;
+        return categoricalPaletteColor(this.nodeTypes.indexOf(type));
+    }
+    /** `this.nodes` filtered down to the ids `hiddenTypes` doesn't hide -- an untyped node (`type ==
+     *  null`) is never hidden, regardless of `hiddenTypes`' contents. */
+    visibleNodes() {
+        if (!this.hiddenTypes.length)
+            return this.nodes;
+        const hidden = new Set(this.hiddenTypes);
+        return this.nodes.filter((n) => n.type == null || !hidden.has(n.type));
+    }
+    /** Resolves `this.links` against an already-built `byId` node map: a link whose source isn't in
+     *  `byId` is dropped (hidden source, or a genuinely missing one); a link whose target isn't in
+     *  `byId` either stubs as a dangling link (target id doesn't exist in `this.nodes` at all) or is
+     *  dropped (target exists but is hidden by `hiddenTypes`). Shared by both the force and layered
+     *  layout paths in `rebuildSimulation()`. */
+    resolveLinksAgainst(byId) {
+        const nodeExists = new Set(this.nodes.map((n) => n.id));
+        const resolved = [];
+        const dangling = [];
+        for (const l of this.links) {
+            const source = byId.get(l.source);
+            if (!source)
+                continue;
+            const target = byId.get(l.target);
+            if (target) {
+                resolved.push({ ...l, source, target });
+            }
+            else if (!nodeExists.has(l.target)) {
+                dangling.push({ ...l, source, target: { id: l.target, x: source.x, y: source.y }, dangling: true });
+            }
+        }
+        return { resolved, dangling };
+    }
+    /** A community's currently-visible members -- the union of `memberIds` and every currently
+     *  simulated node (already filtered by `hiddenTypes`) whose `communityId` matches. */
+    communityMembers(community) {
+        const idSet = new Set(community.memberIds);
+        return this.simNodes.filter((n) => idSet.has(n.id) || n.communityId === community.id);
+    }
+    /** `communities` narrowed to entries with at least one currently-visible member -- a community
+     *  whose members are all hidden by `hiddenTypes` (or that starts out empty) draws no hull and
+     *  doesn't occupy a roving-ring slot. */
+    visibleCommunities() {
+        if (!this.visibleCommunitiesCache) {
+            this.visibleCommunitiesCache = this.communities
+                .map((community) => ({ community, members: this.communityMembers(community) }))
+                .filter((entry) => entry.members.length > 0);
+        }
+        return this.visibleCommunitiesCache;
+    }
+    communityHull(members) {
+        return convexHull(members.map((n) => ({ x: n.x ?? 0, y: n.y ?? 0 })));
+    }
+    onCommunityClick(community) {
+        this.emit('lyra-community-click', { id: community.id });
+    }
+    cameraTransitionMs() {
+        const parsed = parseFloat(getComputedStyle(this).getPropertyValue('--lyra-transition-base'));
+        return Number.isFinite(parsed) ? parsed : 180;
+    }
+    cancelCameraTween() {
+        if (this.cameraTweenId != null) {
+            cancelAnimationFrame(this.cameraTweenId);
+            this.cameraTweenId = undefined;
+        }
+        this.isCameraTweening = false;
+        const resolve = this.cameraTweenResolve;
+        if (resolve) {
+            this.cameraTweenResolve = undefined;
+            resolve(false);
+        }
+    }
+    applyZoomTransform(transform) {
+        if (!this.d3 || !this.zoomedEl || !this.zoomBehavior)
+            return;
+        this.isApplyingZoomTransform = true;
+        try {
+            this.zoomBehavior.transform(this.d3.select(this.zoomedEl), transform);
+        }
+        finally {
+            this.isApplyingZoomTransform = false;
+        }
+    }
+    /** Animates from the zoom behavior's current transform toward `computeTarget()`'s result via a
+     *  rAF tween that calls `zoomBehavior.transform()` every frame -- keeps d3-zoom's own internal
+     *  state consistent (so the next user pan doesn't jump), unlike writing the `<g>` transform
+     *  attribute directly. `computeTarget` is re-invoked on every single frame (not read once
+     *  up-front) so the tween keeps tracking a still-settling force simulation's live node positions
+     *  instead of tweening toward a stale snapshot from the moment the call was made --
+     *  `focusNode()`/`fit()` are just as likely to run while the graph is still animating its initial
+     *  layout as after it's settled. `prefers-reduced-motion` jumps straight to one write of the
+     *  then-current target. A concurrent call cancels the previous tween -- resolves `true` on
+     *  genuine arrival, `false` if superseded or interrupted by a user gesture before completing. */
+    tweenCamera(computeTarget) {
+        return new Promise((resolve) => {
+            if (!this.d3 || !this.zoomedEl || !this.zoomBehavior) {
+                resolve(false);
+                return;
+            }
+            this.cancelCameraTween();
+            this.cameraTweenResolve = resolve;
+            this.isCameraTweening = true;
+            if (prefersReducedMotion()) {
+                this.applyZoomTransform(computeTarget());
+                this.isCameraTweening = false;
+                this.cameraTweenResolve = undefined;
+                resolve(true);
+                return;
+            }
+            const current = this.d3.zoomTransform(this.zoomedEl);
+            const duration = this.cameraTransitionMs();
+            const start = performance.now();
+            const startK = current.k;
+            const startX = current.x;
+            const startY = current.y;
+            const step = (now) => {
+                const t = duration > 0 ? Math.min(1, (now - start) / duration) : 1;
+                const target = computeTarget();
+                const targetK = target.k;
+                const targetX = target.x;
+                const targetY = target.y;
+                this.applyZoomTransform(this.d3.zoomIdentity
+                    .translate(startX + (targetX - startX) * t, startY + (targetY - startY) * t)
+                    .scale(startK + (targetK - startK) * t));
+                if (t < 1) {
+                    this.cameraTweenId = requestAnimationFrame(step);
+                }
+                else {
+                    this.cameraTweenId = undefined;
+                    this.isCameraTweening = false;
+                    this.cameraTweenResolve = undefined;
+                    resolve(true);
+                }
+            };
+            this.cameraTweenId = requestAnimationFrame(step);
+        });
+    }
+    /** Animates the camera so `id` centers in the viewport (the `width` x `height` viewBox), at
+     *  `options.zoom` (clamped to `[minZoom, maxZoom]`) or the current scale when omitted. Resolves
+     *  `true` on arrival; `false` for an id with no matching entry in `simNodes` -- there's nothing
+     *  to center on. Announces `graphNodeFocused` through the existing live region. Does not move DOM
+     *  focus -- this is a camera operation, not a roving-focus one. */
+    async focusNode(id, options) {
+        const node = this.simNodes.find((n) => n.id === id);
+        if (!node || !this.d3 || !this.zoomedEl || !this.zoomBehavior)
+            return false;
+        const current = this.d3.zoomTransform(this.zoomedEl);
+        const k = Math.min(this.safeMaxZoom, Math.max(this.safeMinZoom, options?.zoom ?? current.k));
+        const arrived = await this.tweenCamera(() => this.d3.zoomIdentity
+            .translate(this.safeWidth / 2 - k * (node.x ?? 0), this.safeHeight / 2 - k * (node.y ?? 0))
+            .scale(k));
+        if (arrived) {
+            this.graphLiveText = this.localize('graphNodeFocused', undefined, { label: this.nodeAccessibleText(node) });
+        }
+        return arrived;
+    }
+    /** Animates the camera to frame the bounding box of every currently visible node position (plus
+     *  each node's own radius) at the largest scale that fits within `width` x `height` minus
+     *  `padding` viewport-px on each side (clamped to `[minZoom, maxZoom]`). Silent -- no data
+     *  changed, so no announcement. A no-op with no visible nodes. */
+    fit(options) {
+        if (!this.d3 || !this.zoomedEl || !this.zoomBehavior || !this.simNodes.length)
+            return;
+        const padding = options?.padding ?? 24;
+        void this.tweenCamera(() => {
+            let minX = Infinity;
+            let minY = Infinity;
+            let maxX = -Infinity;
+            let maxY = -Infinity;
+            for (const n of this.simNodes) {
+                const r = this.nodeRadius(n);
+                minX = Math.min(minX, (n.x ?? 0) - r);
+                maxX = Math.max(maxX, (n.x ?? 0) + r);
+                minY = Math.min(minY, (n.y ?? 0) - r);
+                maxY = Math.max(maxY, (n.y ?? 0) + r);
+            }
+            for (const entry of this.visibleCommunities()) {
+                for (const p of this.communityHull(entry.members)) {
+                    minX = Math.min(minX, p.x - HULL_PADDING);
+                    maxX = Math.max(maxX, p.x + HULL_PADDING);
+                    minY = Math.min(minY, p.y - HULL_PADDING);
+                    maxY = Math.max(maxY, p.y + HULL_PADDING);
+                }
+            }
+            const boxW = Math.max(1, maxX - minX);
+            const boxH = Math.max(1, maxY - minY);
+            const availW = Math.max(1, this.safeWidth - padding * 2);
+            const availH = Math.max(1, this.safeHeight - padding * 2);
+            const k = Math.min(this.safeMaxZoom, Math.max(this.safeMinZoom, Math.min(availW / boxW, availH / boxH)));
+            const cx = (minX + maxX) / 2;
+            const cy = (minY + maxY) / 2;
+            return this.d3.zoomIdentity.translate(this.safeWidth / 2 - k * cx, this.safeHeight / 2 - k * cy).scale(k);
+        });
+    }
+    updateFocusHalo() {
+        if (!this.focusHaloEl)
+            return;
+        const node = this.focusId != null ? this.simNodes.find((n) => n.id === this.focusId) : undefined;
+        if (node) {
+            this.focusHaloEl.setAttribute('cx', String(node.x ?? 0));
+            this.focusHaloEl.setAttribute('cy', String(node.y ?? 0));
+            this.focusHaloEl.setAttribute('r', String(this.nodeRadius(node) + FOCUS_HALO_PADDING));
+            this.focusHaloEl.removeAttribute('hidden');
+        }
+        else {
+            this.focusHaloEl.setAttribute('hidden', '');
+        }
+    }
+    // ---------------------------------------------------------------------------------------------
+    // renderer="canvas": surface setup, DPR/resize watching, scene building, and the static draw.
+    // ---------------------------------------------------------------------------------------------
+    setUpCanvasSurface() {
+        this.canvasCtx = this.canvasEl.getContext('2d') ?? undefined;
+        this.pickCanvas = document.createElement('canvas');
+        this.pickCtx = this.pickCanvas.getContext('2d', { willReadFrequently: true });
+        this.watchCanvasResize();
+        this.watchCanvasDpr();
+        this.canvasTooltipEl = this.renderRoot.querySelector('[part="tooltip"]') ?? undefined;
+        // bindCanvasPointer() (which owns onCanvasDblClick) is bound BEFORE bindCanvasZoom() -- both
+        // end up with a 'dblclick' listener on this same <canvas>, and d3-zoom's own default
+        // double-click-to-zoom-in handler calls stopImmediatePropagation() unconditionally (see
+        // onCanvasDblClick()'s own comment). Registering first means onCanvasDblClick() runs first and
+        // gets the chance to itself stop the event (only when it actually hit a node) before d3-zoom's
+        // handler would otherwise suppress it from ever being observed at all.
+        this.bindCanvasPointer();
+        this.bindCanvasZoom();
+    }
+    watchCanvasResize() {
+        // Re-arming replaces the observer instance -- disconnect the previous one first, or a
+        // canvas -> svg -> canvas renderer round trip leaves an orphaned observer still watching the
+        // host (disconnectedCallback only ever cleans up whichever instance is current).
+        this.canvasResizeObserver?.disconnect();
+        this.canvasResizeObserver = new ResizeObserver(() => this.markCanvasDirty());
+        this.canvasResizeObserver.observe(this);
+    }
+    watchCanvasDpr() {
+        // A MediaQueryList's `matches` is fixed at creation time, so crossing the DPR threshold it was
+        // built for means building a fresh one for the new ratio -- remove the previous instance's
+        // listener first, or it leaks (disconnectedCallback only ever cleans up whichever is current).
+        this.canvasDprQuery?.removeEventListener('change', this.onCanvasDprChange);
+        this.canvasDprQuery = matchMedia(`(resolution: ${window.devicePixelRatio}dppx)`);
+        this.canvasDprQuery.addEventListener('change', this.onCanvasDprChange);
+    }
+    markCanvasDirty() {
+        this.canvasScene = undefined;
+        this.pickDirty = true;
+        this.scheduleCanvasDraw();
+    }
+    /** The camera-only sibling of `markCanvasDirty()`: a pan/zoom moves the camera but leaves every
+     *  world-space scene value (positions, colors, labels) untouched, so the cached `canvasScene`
+     *  stays valid and only needs redrawing under the new transform. The pick canvas bakes the
+     *  camera transform into its pixels, though, so it still needs a redraw before the next hit
+     *  test. */
+    markCanvasCameraDirty() {
+        this.pickDirty = true;
+        this.scheduleCanvasDraw();
+    }
+    scheduleCanvasDraw() {
+        if (this.canvasDrawRafId != null)
+            return;
+        this.canvasDrawRafId = requestAnimationFrame(() => {
+            this.canvasDrawRafId = undefined;
+            this.drawCanvas();
+        });
+    }
+    /** Canvas 2D's `fillStyle`/`strokeStyle` don't accept a raw `var(--x)` string the way an inline
+     *  SVG `style` attribute does -- resolves it to the actual cascaded color via `getComputedStyle`
+     *  first (the same "canvas can't consume var() directly" resolution `<lyra-heatmap>` already
+     *  uses for its own canvas-drawn tokens). `value` untouched when it isn't a bare `var(...)` ref
+     *  (a literal `GraphNode.color`/`GraphLink.color` hex/rgb string already resolves fine as-is). */
+    resolveCssColorValue(value, cs) {
+        const match = value.match(/^var\((--[\w-]+)/);
+        if (!match)
+            return value;
+        return cs.getPropertyValue(match[1]).trim() || value;
+    }
+    buildCanvasScene(cs) {
+        const hullFillDefault = cs.getPropertyValue('--lyra-graph-hull-fill').trim() || cs.getPropertyValue('--lyra-color-brand').trim();
+        const hulls = this.visibleCommunities().map((entry) => ({
+            d: hullPathD(this.communityHull(entry.members)),
+            fill: sanitizeNodeColor(entry.community.color) ?? hullFillDefault,
+        }));
+        const linkColorDefault = cs.getPropertyValue('--lyra-link-color').trim() || cs.getPropertyValue('--lyra-color-border').trim();
+        const links = this.simLinks.map((l) => {
+            const coords = this.linkCoordinates(l);
+            const own = sanitizeNodeColor(l.color);
+            return {
+                x1: coords.x1,
+                y1: coords.y1,
+                x2: coords.x2,
+                y2: coords.y2,
+                color: own ? this.resolveCssColorValue(own, cs) : linkColorDefault,
+                width: l.width ?? 1.5,
+                dash: l.dash,
+                directed: l.directed,
+                selected: this.isSelected('link', this.linkKey(l)),
+                dimmed: this.isDimmed('link', this.linkKey(l)),
+            };
+        });
+        const edgeLabels = this.showEdgeLabels && this.canvasCamera.k >= this.safeEdgeLabelMinZoom
+            ? this.simLinks
+                .filter((l) => l.label)
+                .map((l) => {
+                const pos = this.edgeLabelPosition(l);
+                const coords = this.linkCoordinates(l);
+                const edgeLength = Math.hypot(coords.x2 - coords.x1, coords.y2 - coords.y1);
+                const tooLong = this.edgeLabelWidth(l.label) > edgeLength * EDGE_LABEL_LENGTH_GATE_RATIO;
+                return { x: pos.x, y: pos.y, text: l.label, tooLong };
+            })
+                .filter((l) => !l.tooLong)
+                .map(({ x, y, text }) => ({ x, y, text }))
+            : [];
+        const nodeFillDefault = cs.getPropertyValue('--lyra-node-fill').trim() || cs.getPropertyValue('--lyra-color-brand').trim();
+        const nodes = this.simNodes.map((n) => {
+            const fill = this.nodeFill(n);
+            return {
+                x: n.x ?? 0,
+                y: n.y ?? 0,
+                r: this.nodeRadius(n),
+                shape: this.nodeShape(n),
+                fill: fill ? this.resolveCssColorValue(fill, cs) : nodeFillDefault,
+                selected: this.isSelected('node', n.id),
+                dimmed: this.isDimmed('node', n.id),
+            };
+        });
+        const nodeLabels = this.simNodes
+            .filter((n) => n.label)
+            .map((n) => ({ x: (n.x ?? 0) + this.nodeRadius(n) + 2, y: n.y ?? 0, text: n.label }));
+        const focusNode = this.focusId != null ? this.simNodes.find((n) => n.id === this.focusId) : undefined;
+        const activeNode = this.activeGraphItem >= 0 && this.activeGraphItem < this.simNodes.length
+            ? this.simNodes[this.activeGraphItem]
+            : undefined;
+        return {
+            hulls,
+            links,
+            edgeLabels,
+            nodes,
+            nodeLabels,
+            focusHalo: focusNode
+                ? { x: focusNode.x ?? 0, y: focusNode.y ?? 0, r: this.nodeRadius(focusNode) + FOCUS_HALO_PADDING }
+                : undefined,
+            keyboardFocusRing: activeNode
+                ? { x: activeNode.x ?? 0, y: activeNode.y ?? 0, r: this.nodeRadius(activeNode) + 4 }
+                : undefined,
+            showNodeLabels: this.canvasCamera.k >= CANVAS_NODE_LABEL_MIN_ZOOM,
+            haloColor: cs.getPropertyValue('--lyra-graph-focus-halo-color').trim() || cs.getPropertyValue('--lyra-color-brand').trim(),
+            selectedColor: cs.getPropertyValue('--lyra-graph-selected-color').trim() || cs.getPropertyValue('--lyra-color-success').trim(),
+            dimmedOpacity: Number(cs.getPropertyValue('--lyra-graph-dimmed-opacity').trim()) || 1,
+            labelColor: cs.getPropertyValue('--lyra-color-text').trim(),
+            labelHaloColor: cs.getPropertyValue('--lyra-graph-edge-label-halo').trim() || cs.getPropertyValue('--lyra-color-surface').trim(),
+            font: `${this.edgeLabelFontPx()}px ${cs.getPropertyValue('--lyra-font').trim() || 'sans-serif'}`,
+        };
+    }
+    /** Sizes the backing store to the canvas's own rendered CSS box (`clientWidth`/`clientHeight`,
+     *  themselves stretched to fill the host via `[part="base"]`/`[part="canvas"]`'s `100%` sizing)
+     *  times `devicePixelRatio`, only touching `width`/`height` when the target actually changed --
+     *  reassigning either unconditionally would implicitly clear the canvas and reset its transform
+     *  on every single draw, even a pure pan/zoom repaint. Mirrors `<lyra-heatmap>`'s own DPR-scaled
+     *  backing-store convention (`watchDpr()`/`onDprChange()`), adapted to `setTransform()` (an
+     *  absolute reset) rather than a relative `scale()`, since this canvas -- unlike heatmap's, which
+     *  always resizes its backing store on every draw -- only resizes conditionally. */
+    drawCanvas() {
+        if (!this.canvasEl || !this.canvasCtx)
+            return;
+        const dpr = window.devicePixelRatio || 1;
+        const w = this.canvasEl.clientWidth || this.safeWidth;
+        const h = this.canvasEl.clientHeight || this.safeHeight;
+        const backingW = Math.round(w * dpr);
+        const backingH = Math.round(h * dpr);
+        if (this.canvasEl.width !== backingW || this.canvasEl.height !== backingH) {
+            this.canvasEl.width = backingW;
+            this.canvasEl.height = backingH;
+        }
+        const ctx = this.canvasCtx;
+        ctx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        ctx.clearRect(0, 0, w, h);
+        // Reuse the cached scene for a camera-only repaint; rebuild when it was invalidated
+        // (markCanvasDirty()) or when the camera crossed one of the two label-visibility zoom gates
+        // the scene bakes in (see canvasSceneHasEdgeLabels' doc).
+        const edgeLabelsVisible = this.showEdgeLabels && this.canvasCamera.k >= this.safeEdgeLabelMinZoom;
+        const nodeLabelsVisible = this.canvasCamera.k >= CANVAS_NODE_LABEL_MIN_ZOOM;
+        if (!this.canvasScene ||
+            this.canvasScene.showNodeLabels !== nodeLabelsVisible ||
+            this.canvasSceneHasEdgeLabels !== edgeLabelsVisible) {
+            this.canvasScene = this.buildCanvasScene(getComputedStyle(this));
+            this.canvasSceneHasEdgeLabels = edgeLabelsVisible;
+        }
+        drawGraphScene(ctx, this.canvasCamera, this.canvasScene);
+    }
+    // ---------------------------------------------------------------------------------------------
+    // renderer="canvas": color-picking hit-testing, pointer interaction, and the hover tooltip.
+    // ---------------------------------------------------------------------------------------------
+    rebuildPickItems() {
+        this.pickItems = [
+            ...this.visibleCommunities().map((entry) => ({ kind: 'hull', entry })),
+            ...this.simLinks.map((link) => ({ kind: 'link', link })),
+            ...this.simNodes.map((node) => ({ kind: 'node', node })),
+        ];
+    }
+    redrawPickCanvas() {
+        if (!this.pickCtx || !this.canvasEl || !this.pickCanvas)
+            return;
+        if (this.pickCanvas.width !== this.canvasEl.width || this.pickCanvas.height !== this.canvasEl.height) {
+            this.pickCanvas.width = this.canvasEl.width;
+            this.pickCanvas.height = this.canvasEl.height;
+        }
+        this.rebuildPickItems();
+        const dpr = window.devicePixelRatio || 1;
+        this.pickCtx.setTransform(dpr, 0, 0, dpr, 0, 0);
+        drawPickingScene(this.pickCtx, this.canvasCamera, {
+            hulls: this.pickItems
+                .filter((i) => i.kind === 'hull')
+                .map((i) => ({ d: hullPathD(this.communityHull(i.entry.members)) })),
+            links: this.pickItems
+                .filter((i) => i.kind === 'link')
+                .map((i) => {
+                const c = this.linkCoordinates(i.link);
+                return { x1: c.x1, y1: c.y1, x2: c.x2, y2: c.y2, width: i.link.width ?? 1.5 };
+            }),
+            nodes: this.pickItems
+                .filter((i) => i.kind === 'node')
+                .map((i) => ({
+                x: i.node.x ?? 0,
+                y: i.node.y ?? 0,
+                r: this.nodeRadius(i.node) + 2,
+                shape: this.nodeShape(i.node),
+            })),
+        });
+        this.pickDirty = false;
+    }
+    hitTest(clientX, clientY) {
+        if (!this.canvasEl || !this.pickCtx)
+            return undefined;
+        if (this.pickDirty)
+            this.redrawPickCanvas();
+        const rect = this.canvasEl.getBoundingClientRect();
+        const dpr = window.devicePixelRatio || 1;
+        const px = Math.round((clientX - rect.left) * dpr);
+        const py = Math.round((clientY - rect.top) * dpr);
+        if (px < 0 || py < 0 || px >= this.pickCtx.canvas.width || py >= this.pickCtx.canvas.height)
+            return undefined;
+        const data = this.pickCtx.getImageData(px, py, 1, 1).data;
+        const index = pickColorToIndex(data[0], data[1], data[2]);
+        return index >= 0 ? this.pickItems[index] : undefined;
+    }
+    bindCanvasZoom() {
+        if (!this.d3 || !this.canvasEl)
+            return;
+        this.zoomBehavior = this.d3
+            .zoom()
+            .scaleExtent([this.safeMinZoom, this.safeMaxZoom])
+            .on('start', () => {
+            // Same self-triggered-echo guard as the svg zoom bind's own 'start' handler above (see its
+            // comment) -- a camera tween's per-frame applyZoomTransform() call fires this synchronously,
+            // and without the guard cancelCameraTween() here would cancel that very tween on its own
+            // first frame.
+            if (this.isApplyingZoomTransform)
+                return;
+            this.isPanning = true;
+            this.cancelCameraTween();
+        })
+            .on('zoom', (event) => {
+            this.canvasCamera = { k: event.transform.k, x: event.transform.x, y: event.transform.y };
+            this.markCanvasCameraDirty();
+        })
+            .on('end', () => {
+            this.isPanning = false;
+        });
+        this.d3.select(this.canvasEl).call(this.zoomBehavior);
+    }
+    bindCanvasPointer() {
+        const canvas = this.canvasEl;
+        canvas.addEventListener('pointerdown', this.onCanvasPointerDown);
+        canvas.addEventListener('pointermove', this.onCanvasPointerMove);
+        canvas.addEventListener('pointerup', this.onCanvasPointerUp);
+        canvas.addEventListener('pointerleave', this.onCanvasPointerLeave);
+        canvas.addEventListener('dblclick', this.onCanvasDblClick);
+    }
+    /** `alpha` decays toward `alphaMin` and d3-force stops its internal timer once it crosses below
+     *  it, so `alpha > alphaMin` mirrors the simulation's own running condition -- including a drag's
+     *  `alphaTarget(0.3)` reheat, and correctly excluding a seeded/reduced-motion graph whose settle
+     *  loop already converged synchronously. */
+    simulationIsTicking() {
+        return this.simulation != null && this.simulation.alpha() > this.simulation.alphaMin();
+    }
+    /** Geometric fallback for dblclick: browsers can deliver the event before the offscreen pick
+     * canvas has painted the latest frame, while the simulation coordinates are already current. */
+    nodeAtCanvasPoint(clientX, clientY) {
+        if (!this.canvasEl)
+            return undefined;
+        const rect = this.canvasEl.getBoundingClientRect();
+        const worldX = (clientX - rect.left - this.canvasCamera.x) / this.canvasCamera.k;
+        const worldY = (clientY - rect.top - this.canvasCamera.y) / this.canvasCamera.k;
+        let closest;
+        let closestDistance = Infinity;
+        for (const node of this.simNodes) {
+            const distance = Math.hypot((node.x ?? 0) - worldX, (node.y ?? 0) - worldY);
+            if (distance <= this.nodeRadius(node) + 2 / this.canvasCamera.k && distance < closestDistance) {
+                closest = node;
+                closestDistance = distance;
+            }
+        }
+        return closest;
+    }
+    updateCanvasTooltip(hit, clientX, clientY) {
+        if (!this.canvasTooltipEl)
+            return;
+        if (!hit || hit.kind === 'hull') {
+            this.canvasTooltipEl.setAttribute('hidden', '');
+            return;
+        }
+        const rect = this.canvasEl.getBoundingClientRect();
+        this.canvasTooltipEl.textContent =
+            hit.kind === 'node' ? this.nodeAccessibleText(hit.node) : this.linkAccessibleText(hit.link);
+        // `clientX - rect.left`/`clientY - rect.top` are physical viewport offsets, so they must be
+        // written to the physical `left`/`top` -- a logical `inset-inline-start` maps to `right` under
+        // RTL and would mirror the tooltip across the canvas instead of tracking the cursor.
+        this.canvasTooltipEl.style.left = `${clientX - rect.left}px`;
+        this.canvasTooltipEl.style.top = `${clientY - rect.top}px`;
+        this.canvasTooltipEl.removeAttribute('hidden');
+    }
+    isSelected(kind, id) {
+        return kind === 'node' ? this.selectedNodeIds.includes(id) : this.selectedLinkIds.includes(id);
+    }
+    isDimmed(kind, id) {
+        return kind === 'node' ? this.dimmedNodeIds.includes(id) : this.dimmedLinkIds.includes(id);
+    }
+    linkKey(link) {
+        const source = typeof link.source === 'object' ? link.source.id : String(link.source);
+        const target = typeof link.target === 'object' ? link.target.id : String(link.target);
+        return link.id ?? `${source}->${target}`;
+    }
+    /** Computes and emits the selection intent for activating `id`; never assigns
+     *  `selectedNodeIds`/`selectedLinkIds` itself -- see the class doc's controlled-selection note. */
+    emitSelectionIntent(kind, id, toggle) {
+        if (this.selectionMode === 'none')
+            return;
+        const selected = this.isSelected(kind, id);
+        if (this.selectionMode === 'single' || !toggle) {
+            if (this.selectionMode === 'single' && selected) {
+                this.emit('lyra-selection-change', { nodeIds: [], linkIds: [] });
+                return;
+            }
+            this.emit('lyra-selection-change', kind === 'node' ? { nodeIds: [id], linkIds: [] } : { nodeIds: [], linkIds: [id] });
+            return;
+        }
+        const nodeIds = kind === 'node'
+            ? selected
+                ? this.selectedNodeIds.filter((x) => x !== id)
+                : [...this.selectedNodeIds, id]
+            : this.selectedNodeIds;
+        const linkIds = kind === 'link'
+            ? selected
+                ? this.selectedLinkIds.filter((x) => x !== id)
+                : [...this.selectedLinkIds, id]
+            : this.selectedLinkIds;
+        this.emit('lyra-selection-change', { nodeIds, linkIds });
+    }
+    clearSelection() {
+        if (this.selectionMode === 'none')
+            return;
+        if (!this.selectedNodeIds.length && !this.selectedLinkIds.length)
+            return;
+        this.emit('lyra-selection-change', { nodeIds: [], linkIds: [] });
+    }
     willUpdate(changed) {
         // rebuildSimulation() (re)assigns the simNodes/simLinks reactive
         // properties — doing that from willUpdate() folds them into the render
@@ -181,9 +1158,27 @@ export class LyraGraph extends LyraElement {
         // instead would set a reactive property *after* the update completed,
         // which Lit schedules as a whole extra update pass (a dev-mode warning,
         // and pointless work).
-        if (this.d3 && (changed.has('nodes') || changed.has('links'))) {
+        if (this.d3 &&
+            (changed.has('nodes') ||
+                changed.has('links') ||
+                changed.has('hiddenTypes') ||
+                changed.has('layout') ||
+                (this.layout === 'layered' && changed.has('linkDistance')))) {
             this.rebuildSimulation();
         }
+        // rebuildSimulation() above always reassigns simNodes, so checking it here (after that call)
+        // also catches a nodes/links/hiddenTypes-driven rebuild, not just a direct communities set.
+        if (changed.has('simNodes') || changed.has('communities')) {
+            this.visibleCommunitiesCache = undefined;
+        }
+        // Same reasoning as rebuildSimulation() above -- assigning graphLiveText from updated() would
+        // schedule a whole extra update pass instead of landing in the render this update is already
+        // about to perform.
+        if (changed.has('selectedNodeIds') || changed.has('selectedLinkIds')) {
+            this.graphLiveText = this.localize('graphSelectionCount', undefined, {
+                count: this.selectedNodeIds.length + this.selectedLinkIds.length,
+            });
+        }
     }
     updated(changed) {
         if (this.loading)
@@ -192,13 +1187,13 @@ export class LyraGraph extends LyraElement {
             this.removeAttribute('aria-busy');
         if (!this.d3)
             return;
-        if (!changed.has('nodes') && !changed.has('links')) {
+        if (!changed.has('nodes') && !changed.has('links') && !changed.has('hiddenTypes')) {
             // These two branches are independent (not else-if): a consumer can set
             // width/height and chargeStrength/linkDistance in the same reactive
             // update batch, and both retunes must apply — not just whichever branch
             // happens to come first.
             if (changed.has('width') || changed.has('height')) {
-                this.simulation?.force('center', this.d3.forceCenter(this.width / 2, this.height / 2));
+                this.simulation?.force('center', this.d3.forceCenter(this.safeWidth / 2, this.safeHeight / 2));
                 this.simulation?.alpha(0.1).restart();
             }
             if (changed.has('chargeStrength') || changed.has('linkDistance')) {
@@ -207,9 +1202,9 @@ export class LyraGraph extends LyraElement {
                 // them fresh) — retune the already-created force objects in place
                 // instead of rebuilding the whole simulation.
                 if (changed.has('chargeStrength'))
-                    this.chargeForce?.strength(this.chargeStrength);
+                    this.chargeForce?.strength(this.safeChargeStrength);
                 if (changed.has('linkDistance'))
-                    this.linkForce?.distance(this.linkDistance);
+                    this.linkForce?.distance(this.safeLinkDistance);
                 this.simulation?.alpha(0.3).restart();
             }
         }
@@ -218,6 +1213,15 @@ export class LyraGraph extends LyraElement {
         // node/link querySelectorAll scan on that is equivalent to "structurally
         // changed" without needing a separate flag.
         this.applyInteractions(changed);
+        this.applyCanvasInteractions();
+        if (this.focusId == null) {
+            this.lastAppliedFocusId = null;
+        }
+        else if (this.focusId !== this.lastAppliedFocusId && this.simNodes.some((n) => n.id === this.focusId)) {
+            this.lastAppliedFocusId = this.focusId;
+            void this.focusNode(this.focusId);
+        }
+        this.updateFocusHalo();
     }
     /**
      * Imperatively wires up d3-zoom (pan/zoom on the `<svg>`) and d3-drag
@@ -243,58 +1247,115 @@ export class LyraGraph extends LyraElement {
     applyInteractions(changed) {
         if (!this.d3)
             return;
+        if (this.renderer !== 'svg')
+            return;
         const svgEl = this.renderRoot.querySelector('svg');
         if (svgEl && svgEl !== this.zoomedEl) {
+            // Binding a fresh svg means any previous renderer="canvas" surface is gone -- stop its
+            // resize watcher now (it observes the host, not the removed <canvas>, so it would keep
+            // firing markCanvasDirty() for as long as the element lives in svg mode).
+            this.canvasResizeObserver?.disconnect();
+            this.canvasResizeObserver = undefined;
             this.zoomedEl = svgEl;
             this.gEl = this.renderRoot.querySelector('g') ?? undefined;
+            this.focusHaloEl = this.renderRoot.querySelector('[part="focus-halo"]') ?? undefined;
             this.zoomBehavior = this.d3
                 .zoom()
-                .scaleExtent([this.minZoom, this.maxZoom])
+                .scaleExtent([this.safeMinZoom, this.safeMaxZoom])
+                .on('start', () => {
+                // A camera tween writes a transform on every frame via applyZoomTransform(), which
+                // itself synchronously replays this same 'start' handler -- ignore that self-triggered
+                // echo so a tween doesn't cancel itself on its own first frame.
+                if (this.isApplyingZoomTransform)
+                    return;
+                this.isPanning = true;
+                this.cancelCameraTween();
+            })
                 .on('zoom', (event) => {
                 this.gEl?.setAttribute('transform', event.transform.toString());
+                this.updateEdgeLabelZoomGate(event.transform.k);
+            })
+                .on('end', () => {
+                this.isPanning = false;
             });
             this.d3.select(svgEl).call(this.zoomBehavior);
+            // `.call(zoomBehavior)` does not synchronously fire the 'zoom' handler above (only a real
+            // user gesture or an explicit `.transform()` call does, and nothing in this component ever
+            // calls `.transform()`) -- so the initial transform right here is always d3-zoom's own
+            // identity transform, k=1. Apply the edge-label zoom gate against that known value now, or
+            // it stays unset (edge labels wrongly visible) until the user's first pan/zoom, regardless
+            // of what edgeLabelMinZoom actually is.
+            this.updateEdgeLabelZoomGate(1);
         }
         else if (this.zoomBehavior && (changed.has('minZoom') || changed.has('maxZoom'))) {
-            this.zoomBehavior.scaleExtent([this.minZoom, this.maxZoom]);
+            this.zoomBehavior.scaleExtent([this.safeMinZoom, this.safeMaxZoom]);
         }
-        if (!(changed.has('simNodes') || changed.has('simLinks')))
+        if (!(changed.has('simNodes') ||
+            changed.has('simLinks') ||
+            changed.has('nodeTypes') ||
+            changed.has('showEdgeLabels') ||
+            changed.has('communities')))
             return;
         const nodeEls = Array.from(this.renderRoot.querySelectorAll('[part="node"]'));
         this.nodeEls = nodeEls;
         this.nodeLabelEls = nodeEls.map((el) => el.parentElement?.querySelector('[part="label"]') ?? null);
+        this.expandIndicatorEls = nodeEls.map((el) => el.parentElement?.querySelector('[part="expand-indicator"]') ?? null);
         // Dangling stubs also carry part="link" (so they inherit the same themeable styling as a
         // real edge) -- excluded here explicitly so `linkEls` stays index-aligned with `simLinks`
         // rather than relying on stubs always sorting after real links in template/DOM order.
         this.linkEls = Array.from(this.renderRoot.querySelectorAll('[part="link"]:not([data-dangling])'));
+        this.linkLabelEls = this.linkEls.map((el) => el.parentElement?.querySelector('[part="link-label"]') ?? null);
+        this.linkLabelHiddenByLength = [];
         this.danglingLinkEls = Array.from(this.renderRoot.querySelectorAll('[part="link"][data-dangling]'));
-        nodeEls.forEach((el, i) => {
-            if (this.boundNodeEls.has(el))
-                return;
-            const n = this.simNodes[i];
-            if (!n)
-                return;
-            this.boundNodeEls.add(el);
-            this.d3.select(el).call(this.d3.drag()
-                .on('start', (event) => {
-                // Keep a node drag from also triggering the svg's own pan gesture.
-                event.sourceEvent?.stopPropagation();
-                if (!event.active)
-                    this.simulation?.alphaTarget(0.3).restart();
-                n.fx = n.x;
-                n.fy = n.y;
-            })
-                .on('drag', (event) => {
-                n.fx = event.x;
-                n.fy = event.y;
-            })
-                .on('end', (event) => {
-                if (!event.active)
-                    this.simulation?.alphaTarget(0);
-                n.fx = null;
-                n.fy = null;
-            }));
-        });
+        this.communityHullEls = Array.from(this.renderRoot.querySelectorAll('[part="hull"]'));
+        this.communityLabelEls = Array.from(this.renderRoot.querySelectorAll('[part="community-label"]'));
+        if (this.layout !== 'layered') {
+            nodeEls.forEach((el, i) => {
+                if (this.boundNodeEls.has(el))
+                    return;
+                const n = this.simNodes[i];
+                if (!n)
+                    return;
+                this.boundNodeEls.add(el);
+                this.d3.select(el).call(this.d3.drag()
+                    .on('start', (event) => {
+                    this.isDragging = true;
+                    // Keep a node drag from also triggering the svg's own pan gesture.
+                    event.sourceEvent?.stopPropagation();
+                    if (!event.active)
+                        this.simulation?.alphaTarget(0.3).restart();
+                    n.fx = n.x;
+                    n.fy = n.y;
+                })
+                    .on('drag', (event) => {
+                    n.fx = event.x;
+                    n.fy = event.y;
+                })
+                    .on('end', (event) => {
+                    this.isDragging = false;
+                    if (!event.active)
+                        this.simulation?.alphaTarget(0);
+                    n.fx = null;
+                    n.fy = null;
+                }));
+            });
+        }
+    }
+    /** The `renderer="canvas"` twin of `applyInteractions()`'s svg zoom-bind branch -- binds d3-zoom
+     *  and the pointer/hit-testing handlers to the just-rendered `<canvas>` once (guarded by the same
+     *  `zoomedEl` field `applyInteractions()` uses, so `focusNode()`/`fit()`/`tweenCamera()` keep
+     *  working unmodified against whichever element -- svg or canvas -- is currently bound), then
+     *  marks the canvas dirty on every call so any structural/style-affecting change (new nodes/
+     *  links, a selection change, a hiddenTypes toggle, ...) schedules a fresh draw the same way a
+     *  Lit re-render already does for svg mode. */
+    applyCanvasInteractions() {
+        if (this.renderer !== 'canvas' || !this.canvasEl)
+            return;
+        if (this.canvasEl !== this.zoomedEl) {
+            this.zoomedEl = this.canvasEl;
+            this.setUpCanvasSurface();
+        }
+        this.markCanvasDirty();
     }
     /**
      * Runs on every d3-force simulation tick (up to ~300 while a graph settles
@@ -315,11 +1376,26 @@ export class LyraGraph extends LyraElement {
             target.x = (source.x ?? 0) + STUB_OFFSET_PX;
             target.y = (source.y ?? 0) + STUB_OFFSET_PX;
         }
+        // Keep the remembered-position cache current with a position captured mid-settle or mid-drag
+        // (not just the one snapshotted at the end of rebuildSimulation()) -- a hiddenTypes toggle
+        // that lands before the next structural rebuild should still restore a node to where it
+        // actually was, not an earlier, since-superseded snapshot. Plain Map writes, no DOM/no
+        // reactive-property touch, so this stays on the same cheap per-tick path as the rest of this
+        // method.
+        for (const n of this.simNodes) {
+            if (n.x != null && n.y != null)
+                this.lastPositionById.set(n.id, { x: n.x, y: n.y });
+        }
         this.simNodes.forEach((n, i) => {
-            const circle = this.nodeEls[i];
-            if (circle) {
-                circle.setAttribute('cx', String(n.x ?? 0));
-                circle.setAttribute('cy', String(n.y ?? 0));
+            const el = this.nodeEls[i];
+            if (el) {
+                if (el.tagName === 'circle') {
+                    el.setAttribute('cx', String(n.x ?? 0));
+                    el.setAttribute('cy', String(n.y ?? 0));
+                }
+                else {
+                    el.setAttribute('transform', `translate(${n.x ?? 0},${n.y ?? 0})`);
+                }
             }
             const label = this.nodeLabelEls[i];
             if (label) {
@@ -337,6 +1413,28 @@ export class LyraGraph extends LyraElement {
             line.setAttribute('x2', String(coordinates.x2));
             line.setAttribute('y2', String(coordinates.y2));
         });
+        if (this.showEdgeLabels) {
+            this.simLinks.forEach((l, i) => {
+                const labelEl = this.linkLabelEls[i];
+                if (!labelEl)
+                    return;
+                const pos = this.edgeLabelPosition(l);
+                labelEl.setAttribute('x', String(pos.x));
+                labelEl.setAttribute('y', String(pos.y));
+                const { x1, y1, x2, y2 } = this.linkCoordinates(l);
+                const edgeLength = Math.hypot(x2 - x1, y2 - y1);
+                const tooLong = this.edgeLabelWidth(l.label ?? '') > edgeLength * EDGE_LABEL_LENGTH_GATE_RATIO;
+                if (this.linkLabelHiddenByLength[i] !== tooLong) {
+                    this.linkLabelHiddenByLength[i] = tooLong;
+                    labelEl.setAttribute('visibility', tooLong ? 'hidden' : 'visible');
+                }
+            });
+        }
+        this.simNodes.forEach((n, i) => {
+            const indicator = this.expandIndicatorEls[i];
+            if (indicator)
+                indicator.setAttribute('transform', `translate(${n.x ?? 0},${n.y ?? 0})`);
+        });
         // Dangling stubs are excluded from d3-force's own simulation input (see
         // rebuildSimulation()'s "stubs never enter d3-force's own simulation input"), so the
         // synthetic target position the danglingLinks loop at the top of this method just
@@ -353,12 +1451,41 @@ export class LyraGraph extends LyraElement {
             line.setAttribute('x2', String(coordinates.x2));
             line.setAttribute('y2', String(coordinates.y2));
         });
+        this.updateFocusHalo();
+        this.visibleCommunities().forEach((entry, i) => {
+            const hullEl = this.communityHullEls[i];
+            const labelEl = this.communityLabelEls[i];
+            if (!hullEl && !labelEl)
+                return;
+            const hull = this.communityHull(entry.members);
+            if (hullEl)
+                hullEl.setAttribute('d', hullPathD(hull));
+            if (labelEl) {
+                labelEl.setAttribute('x', String(hullCentroidX(hull)));
+                labelEl.setAttribute('y', String(hullTopY(hull) - HULL_PADDING));
+            }
+        });
+        // renderer="canvas" mode has no DOM to write positions straight to (everything above this line
+        // no-ops there: nodeEls/linkEls/etc. are only ever populated by applyInteractions()'s svg-only
+        // branch) -- schedule a fresh draw off the same simulation tick instead, so the settle
+        // animation and a live node drag actually repaint the canvas rather than freezing at whatever
+        // was last drawn on mount.
+        if (this.renderer === 'canvas')
+            this.markCanvasDirty();
     }
     rebuildSimulation() {
         if (!this.d3)
             return;
         this.simulation?.stop();
         this.boundNodeEls = new WeakSet();
+        // Prune remembered positions for ids no longer present in `this.nodes` at all (not merely
+        // hidden by hiddenTypes) -- otherwise this cache would grow forever across a long-lived,
+        // mutating graph instead of tracking only ids that could plausibly reappear.
+        const liveIds = new Set(this.nodes.map((n) => n.id));
+        for (const id of this.lastPositionById.keys()) {
+            if (!liveIds.has(id))
+                this.lastPositionById.delete(id);
+        }
         // Carry over each existing SimNode's settled position/velocity (and any
         // in-progress drag fx/fy) by id instead of starting every node fresh —
         // otherwise any structural nodes/links change (e.g. appending one new
@@ -367,60 +1494,98 @@ export class LyraGraph extends LyraElement {
         // start settle animation from scratch. Only nodes with no previous
         // counterpart (genuinely new ids) get forceSimulation()'s default
         // fresh random start below.
+        const visible = this.visibleNodes();
+        if (this.layout === 'layered') {
+            this.rebuildLayeredLayout(visible);
+            return;
+        }
         const prevById = new Map(this.simNodes.map((n) => [n.id, n]));
-        const nodes = this.nodes.map((n) => {
+        const nodes = visible.map((n) => {
             const prev = prevById.get(n.id);
-            return prev ? { ...prev, ...n } : { ...n };
+            if (prev)
+                return { ...prev, ...n };
+            // A node hidden by hiddenTypes and now visible again has no prevById entry (it fell out of
+            // simNodes while hidden) but may still have a remembered settled position from before it was
+            // hidden -- restore that instead of leaving it for the neighbor-jitter/seed spawn logic below,
+            // or forceSimulation()'s own random start, to place it as if it were a brand-new node.
+            const remembered = this.lastPositionById.get(n.id);
+            return remembered ? { ...n, x: remembered.x, y: remembered.y } : { ...n };
         });
         const byId = new Map(nodes.map((n) => [n.id, n]));
-        const resolvedLinks = [];
-        const danglingLinks = [];
-        for (const l of this.links) {
-            const source = byId.get(l.source);
-            if (!source)
-                continue; // no real position to draw a stub from -- stays dropped, unchanged
-            const target = byId.get(l.target);
-            if (target) {
-                resolvedLinks.push({ ...l, source, target });
-            }
-            else {
-                danglingLinks.push({
-                    ...l,
-                    source,
-                    target: { id: l.target, x: source.x, y: source.y },
-                    dangling: true,
-                });
-            }
-        }
+        const { resolved: resolvedLinks, dangling: danglingLinks } = this.resolveLinksAgainst(byId);
         const links = resolvedLinks; // stubs never enter d3-force's own simulation input
         this.danglingLinks = danglingLinks;
-        // Give brand-new nodes (no carried-over position from prevById above) a
-        // deterministic starting x/y, keyed by node id, instead of leaving them
-        // for forceSimulation() below to randomize. Nodes that already have a
-        // position are left untouched — same "only randomize nodes without x/y"
-        // rule forceSimulation() itself follows — so an incremental update to a
+        const seedForSpawn = this.safeSeed;
+        // Give a brand-new node with no carried-over position (from prevById above) a spawn point
+        // near an already-positioned neighbor instead of forceSimulation()'s eventual random start --
+        // expanded neighborhoods bloom around their origin instead of flying in from nowhere. Only
+        // touches nodes with no position yet, so it can't move anything already settled.
+        for (const n of nodes) {
+            if (n.x != null && n.y != null)
+                continue;
+            const neighborLink = resolvedLinks.find((l) => {
+                const source = l.source;
+                const target = l.target;
+                return (source.id === n.id && target.x != null) || (target.id === n.id && source.x != null);
+            });
+            if (!neighborLink)
+                continue;
+            const source = neighborLink.source;
+            const target = neighborLink.target;
+            const neighbor = source.id === n.id ? target : source;
+            const jitterRadius = this.safeLinkDistance / 2;
+            const angle = seedForSpawn != null
+                ? (hashNodeSeed(seedForSpawn, n.id) / 4294967296) * Math.PI * 2
+                : Math.random() * Math.PI * 2;
+            n.x = (neighbor.x ?? 0) + Math.cos(angle) * jitterRadius;
+            n.y = (neighbor.y ?? 0) + Math.sin(angle) * jitterRadius;
+        }
+        // Give any remaining brand-new nodes (no carried-over position from prevById above, and no
+        // already-positioned neighbor for the jitter spawn above to anchor to) a deterministic
+        // starting x/y, keyed by node id, instead of leaving them for forceSimulation() below to
+        // randomize. Nodes that already have a position are left untouched — same "only randomize
+        // nodes without x/y" rule forceSimulation() itself follows — so an incremental update to a
         // seeded, already-settled graph doesn't reshuffle existing nodes.
-        const seed = this.seed;
-        if (seed != null) {
+        if (seedForSpawn != null) {
             for (const n of nodes) {
                 if (n.x != null && n.y != null)
                     continue;
-                const rng = mulberry32(hashNodeSeed(seed, n.id));
-                n.x = rng() * this.width;
-                n.y = rng() * this.height;
+                const rng = mulberry32(hashNodeSeed(seedForSpawn, n.id));
+                n.x = rng() * this.safeWidth;
+                n.y = rng() * this.safeHeight;
             }
         }
-        this.linkForce = this.d3.forceLink(links).distance(this.linkDistance);
-        this.chargeForce = this.d3.forceManyBody().strength(this.chargeStrength);
+        this.linkForce = this.d3.forceLink(links).distance(this.safeLinkDistance);
+        this.chargeForce = this.d3.forceManyBody().strength(this.safeChargeStrength);
         const simulation = this.d3
             .forceSimulation(nodes)
             .force('link', this.linkForce)
             .force('charge', this.chargeForce)
-            .force('center', this.d3.forceCenter(this.width / 2, this.height / 2))
+            .force('center', this.d3.forceCenter(this.safeWidth / 2, this.safeHeight / 2))
             .force('collide', this.d3.forceCollide().radius((n) => this.nodeRadius(n) + 10))
             .on('tick', () => this.onTick());
         this.simulation = simulation;
-        if (prefersReducedMotion() || this.seed != null) {
+        if (prefersReducedMotion() || this.safeSeed != null) {
+            // Pin every node that already had a known position before this rebuild -- either carried
+            // over directly (fx/fy, the same mechanism a user drag uses) or restored from
+            // lastPositionById after being hidden by hiddenTypes -- so introducing a new node/link can't
+            // visibly reposition it during this synchronous settle. Only a genuinely new node (no prior
+            // counterpart in either source) is free to move while the simulation converges. A node whose
+            // fx/fy was already set (an active user drag concurrent with this rebuild) is left alone
+            // entirely -- both the pin and the later release below only apply to a node this loop itself
+            // pinned, so a real in-progress drag's own fx/fy is never clobbered. Everything this loop
+            // does pin gets released again immediately below, so this has no lasting effect on a later
+            // user-initiated drag, nor on the live, async settle a non-seeded/non-reduced-motion graph
+            // still animates over ~300 frames.
+            const pinnedForSettle = new Set();
+            for (const n of nodes) {
+                const hadKnownPosition = prevById.has(n.id) || this.lastPositionById.has(n.id);
+                if (hadKnownPosition && n.x != null && n.y != null && n.fx == null && n.fy == null) {
+                    n.fx = n.x;
+                    n.fy = n.y;
+                    pinnedForSettle.add(n.id);
+                }
+            }
             // Converge synchronously instead of animating the settle over ~300
             // rendered frames — the simulation is already stopped (alpha at
             // alphaMin) by the time the DOM for this rebuild is first painted.
@@ -431,6 +1596,12 @@ export class LyraGraph extends LyraElement {
             simulation.stop();
             while (simulation.alpha() > simulation.alphaMin())
                 simulation.tick();
+            for (const n of nodes) {
+                if (pinnedForSettle.has(n.id)) {
+                    n.fx = null;
+                    n.fy = null;
+                }
+            }
         }
         // Assign these SAME array/object references (not copies) exactly once
         // for this structural rebuild: forceSimulation(nodes) above already
@@ -442,17 +1613,137 @@ export class LyraGraph extends LyraElement {
         // re-render up to ~300 times on load and continuously while dragging.
         this.simNodes = nodes;
         this.simLinks = links;
+        for (const n of nodes) {
+            if (n.x != null && n.y != null)
+                this.lastPositionById.set(n.id, { x: n.x, y: n.y });
+        }
+        this.announceHiddenNodeCount(nodes.length);
+    }
+    /** Announces the current hidden-node count via the live region -- shared by both the force and
+     *  layered rebuild paths (each calls this with its own final visible-node count) so `hiddenTypes`
+     *  filtering announces identically regardless of `layout`. Called from right here (not from
+     *  willUpdate()/updated() gated on a 'hiddenTypes'/'nodes' PropertyValues diff) because
+     *  rebuildSimulation() itself is also invoked directly from connectedCallback() once the lazy d3
+     *  peer deps resolve -- a call that never goes through Lit's changed-property diffing at all.
+     *  Computing it there instead would miss that path entirely: a graph mounted with hiddenTypes
+     *  already set would compute this from a still-empty simNodes (0 settled nodes yet) on the
+     *  property-driven pass, then never get a chance to correct it once the real simNodes became
+     *  available. Only ever touches graphLiveText when there's something to say -- a node is
+     *  currently hidden, or one just stopped being hidden -- so a consumer that never sets
+     *  hiddenTypes keeps today's exact live-region output. */
+    announceHiddenNodeCount(visibleNodeCount) {
+        const totalNodeCount = this.nodes.length;
+        const hiddenNodeCount = totalNodeCount - visibleNodeCount;
+        if (totalNodeCount > 0 && (hiddenNodeCount > 0 || this.lastHiddenNodeCount > 0)) {
+            this.graphLiveText = this.localize('graphNodesHidden', undefined, {
+                hidden: hiddenNodeCount,
+                total: totalNodeCount,
+            });
+        }
+        this.lastHiddenNodeCount = hiddenNodeCount;
+    }
+    /** The `layout="layered"` path: computes final positions synchronously via the shared
+     *  `layeredLayout()` util (2r x 2r boxes, `gapY = linkDistance`, `gapX = 12`), centers the
+     *  drawing in `width` x `height`, and skips forceSimulation() entirely -- no `this.simulation`,
+     *  no ticking, no `prevById` carry-over (deterministic input -> output makes it unnecessary; a
+     *  structural change simply recomputes wholesale). `lyra-graph` never passes `fixedPositions`. */
+    rebuildLayeredLayout(visible) {
+        const boxes = visible.map((n) => {
+            const r = this.nodeRadius(n);
+            return { id: n.id, width: r * 2, height: r * 2 };
+        });
+        const visibleIds = new Set(visible.map((n) => n.id));
+        const edges = this.links
+            .filter((l) => visibleIds.has(l.source) && visibleIds.has(l.target))
+            .map((l) => ({ source: l.source, target: l.target }));
+        const raw = layeredLayout({ nodes: boxes, edges, options: { gapX: 12, gapY: this.safeLinkDistance } });
+        let minX = Infinity;
+        let minY = Infinity;
+        let maxX = -Infinity;
+        let maxY = -Infinity;
+        for (const p of raw.values()) {
+            minX = Math.min(minX, p.x);
+            maxX = Math.max(maxX, p.x);
+            minY = Math.min(minY, p.y);
+            maxY = Math.max(maxY, p.y);
+        }
+        const offsetX = raw.size ? this.safeWidth / 2 - (minX + (maxX - minX) / 2) : this.safeWidth / 2;
+        const offsetY = raw.size ? this.safeHeight / 2 - (minY + (maxY - minY) / 2) : this.safeHeight / 2;
+        const nodes = visible.map((n) => {
+            const p = raw.get(n.id);
+            return { ...n, x: (p?.x ?? this.safeWidth / 2) + offsetX, y: (p?.y ?? this.safeHeight / 2) + offsetY };
+        });
+        const byId = new Map(nodes.map((n) => [n.id, n]));
+        const { resolved, dangling } = this.resolveLinksAgainst(byId);
+        this.danglingLinks = dangling;
+        this.simulation = undefined;
+        this.simNodes = nodes;
+        this.simLinks = resolved;
+        for (const n of nodes) {
+            if (n.x != null && n.y != null)
+                this.lastPositionById.set(n.id, { x: n.x, y: n.y });
+        }
+        this.announceHiddenNodeCount(nodes.length);
     }
-    onNodeClick(node) {
-        this.emit('lyra-node-click', { id: node.id });
+    onNodeClick(node, e) {
+        this.emit('lyra-node-click', { id: node.id, x: node.x ?? 0, y: node.y ?? 0 });
+        this.emitSelectionIntent('node', node.id, !!(e?.ctrlKey || e?.metaKey));
     }
-    onLinkClick(link) {
+    /** Returns a node's current position in the graph's local drawing space. */
+    getNodePosition(id) {
+        const node = this.simNodes.find((candidate) => candidate.id === id);
+        if (!node || !Number.isFinite(node.x) || !Number.isFinite(node.y))
+            return undefined;
+        return { x: node.x, y: node.y };
+    }
+    onLinkClick(link, e) {
         const source = typeof link.source === 'object' ? link.source.id : String(link.source);
         const target = typeof link.target === 'object' ? link.target.id : String(link.target);
         this.emit('lyra-link-click', { source, target, ...(link.id ? { id: link.id } : {}) });
+        this.emitSelectionIntent('link', this.linkKey(link), !!(e?.ctrlKey || e?.metaKey));
+    }
+    onNodeEnter(node, e) {
+        if (this.isDragging || this.isPanning || this.isCameraTweening)
+            return;
+        e.currentTarget.setAttribute('data-hovered', '');
+        this.emit('lyra-node-enter', { id: node.id });
+    }
+    onNodeLeave(node, e) {
+        if (this.isDragging || this.isPanning || this.isCameraTweening)
+            return;
+        e.currentTarget.removeAttribute('data-hovered');
+        this.emit('lyra-node-leave', { id: node.id });
+    }
+    onNodeDblClick(node, e) {
+        // Stops the dblclick from also reaching the svg's own d3-zoom double-click-to-zoom-in
+        // listener -- background double-click (not on a node) keeps that default behavior.
+        e.stopPropagation();
+        this.emit('lyra-node-expand', { id: node.id });
+    }
+    onLinkEnter(link, e) {
+        if (this.isDragging || this.isPanning || this.isCameraTweening)
+            return;
+        e.currentTarget.setAttribute('data-hovered', '');
+        const source = typeof link.source === 'object' ? link.source.id : String(link.source);
+        const target = typeof link.target === 'object' ? link.target.id : String(link.target);
+        this.emit('lyra-link-enter', { source, target, ...(link.id ? { id: link.id } : {}) });
+    }
+    onLinkLeave(link, e) {
+        if (this.isDragging || this.isPanning || this.isCameraTweening)
+            return;
+        e.currentTarget.removeAttribute('data-hovered');
+        const source = typeof link.source === 'object' ? link.source.id : String(link.source);
+        const target = typeof link.target === 'object' ? link.target.id : String(link.target);
+        this.emit('lyra-link-leave', { source, target, ...(link.id ? { id: link.id } : {}) });
     }
     nodeAccessibleText(node) {
-        return node.accessibleLabel || node.label || node.id;
+        let text = node.accessibleLabel || node.label || node.id;
+        const type = this.resolveNodeType(node);
+        if (type)
+            text = this.localize('graphTypedNode', undefined, { label: text, type: type.label });
+        if (node.expandable)
+            text = this.localize('graphExpandableItem', undefined, { item: text });
+        return text;
     }
     linkAccessibleText(link) {
         if (link.accessibleLabel)
@@ -487,8 +1778,69 @@ export class LyraGraph extends LyraElement {
             y2: targetY - (dy / distance) * inset,
         };
     }
+    /** World-space midpoint of a link, offset EDGE_LABEL_OFFSET_PX perpendicular to the segment
+     *  (horizontal, unrotated text — rotated edge-label text is a readability and RTL hazard). */
+    edgeLabelPosition(link) {
+        const { x1, y1, x2, y2 } = this.linkCoordinates(link);
+        const dx = x2 - x1;
+        const dy = y2 - y1;
+        const len = Math.hypot(dx, dy);
+        const mx = (x1 + x2) / 2;
+        const my = (y1 + y2) / 2;
+        if (len === 0)
+            return { x: mx, y: my };
+        return {
+            x: mx + (-dy / len) * EDGE_LABEL_OFFSET_PX,
+            y: my + (dx / len) * EDGE_LABEL_OFFSET_PX,
+        };
+    }
+    edgeLabelFontPx() {
+        const raw = getComputedStyle(this).getPropertyValue('--lyra-font-size-2xs').trim();
+        const parsed = parseFloat(raw);
+        if (!Number.isFinite(parsed))
+            return 10;
+        // rem tokens are resolved relative to the root font-size; this is a decluttering heuristic,
+        // not a pixel-perfect layout, so the standard 16px/rem approximation is sufficient.
+        return raw.endsWith('rem') ? parsed * 16 : parsed;
+    }
+    edgeLabelWidth(text) {
+        const cached = this.edgeLabelWidthCache.get(text);
+        if (cached != null)
+            return cached;
+        const ctx = getScratchCtx();
+        let width;
+        if (ctx) {
+            const fontFamily = getComputedStyle(this).getPropertyValue('--lyra-font').trim() || 'sans-serif';
+            ctx.font = `${this.edgeLabelFontPx()}px ${fontFamily}`;
+            width = ctx.measureText(text).width;
+        }
+        else {
+            width = text.length * this.edgeLabelFontPx() * 0.6;
+        }
+        // Bound the cache under label churn (a streaming graph can cycle through unbounded distinct
+        // label texts) -- Map iteration yields insertion order, so evicting the first key drops the
+        // oldest-measured entry.
+        if (this.edgeLabelWidthCache.size >= EDGE_LABEL_WIDTH_CACHE_MAX) {
+            const oldest = this.edgeLabelWidthCache.keys().next().value;
+            if (oldest !== undefined)
+                this.edgeLabelWidthCache.delete(oldest);
+        }
+        this.edgeLabelWidthCache.set(text, width);
+        return width;
+    }
+    /** Toggles `data-edge-labels-hidden` on the cached zoomed `<g>` when crossing `edgeLabelMinZoom`
+     *  -- called from the d3-zoom `'zoom'` handler (render-free, CSS hides `[part="link-label"]`
+     *  beneath the attribute) so this scales with every pan/zoom event without a Lit re-render. */
+    updateEdgeLabelZoomGate(k) {
+        if (!this.gEl)
+            return;
+        if (k < this.safeEdgeLabelMinZoom)
+            this.gEl.setAttribute('data-edge-labels-hidden', '');
+        else
+            this.gEl.removeAttribute('data-edge-labels-hidden');
+    }
     graphItemCount() {
-        return this.simNodes.length + this.simLinks.length;
+        return this.simNodes.length + this.simLinks.length + this.visibleCommunities().length;
     }
     normalizedGraphItem(index = this.activeGraphItem) {
         const count = this.graphItemCount();
@@ -499,8 +1851,19 @@ export class LyraGraph extends LyraElement {
             const node = this.simNodes[index];
             return node ? this.localize('graphNode', undefined, { label: this.nodeAccessibleText(node) }) : '';
         }
-        const link = this.simLinks[index - this.simNodes.length];
-        return link ? this.linkAccessibleText(link) : '';
+        const linkIndex = index - this.simNodes.length;
+        if (linkIndex < this.simLinks.length) {
+            const link = this.simLinks[linkIndex];
+            return link ? this.linkAccessibleText(link) : '';
+        }
+        const hullIndex = linkIndex - this.simLinks.length;
+        const entry = this.visibleCommunities()[hullIndex];
+        return entry
+            ? this.localize('graphCommunity', undefined, {
+                label: entry.community.label ?? entry.community.id,
+                count: entry.members.length,
+            })
+            : '';
     }
     graphItemAnnouncement(index) {
         return this.localize('graphItemAnnouncement', undefined, {
@@ -522,10 +1885,16 @@ export class LyraGraph extends LyraElement {
         this.activeGraphItem = normalized;
         this.graphLiveText = this.graphItemAnnouncement(normalized);
         void this.updateComplete.then(() => {
-            const items = [
-                ...Array.from(this.renderRoot.querySelectorAll('[part="node"]')),
-                ...Array.from(this.renderRoot.querySelectorAll('[part="link"]')),
-            ];
+            // renderer="canvas" has no [part="node"]/[part="link"]/[part="hull"] elements at all -- the
+            // roving tab stop lives on the offscreen [part="cursor-item"] buttons instead (see render()),
+            // in the same flat nodes-then-links-then-hulls order.
+            const items = (this.renderer === 'canvas'
+                ? Array.from(this.renderRoot.querySelectorAll('[part="cursor-item"]'))
+                : [
+                    ...Array.from(this.renderRoot.querySelectorAll('[part="node"]')),
+                    ...Array.from(this.renderRoot.querySelectorAll('[part="link"]')),
+                    ...Array.from(this.renderRoot.querySelectorAll('[part="hull"]')),
+                ]);
             items[normalized]?.focus();
         });
     }
@@ -542,7 +1911,20 @@ export class LyraGraph extends LyraElement {
         if (e.key === 'Enter' || e.key === ' ') {
             e.preventDefault();
             this.onGraphItemFocus(index);
-            activate();
+            activate(e);
+            if (index < this.simNodes.length) {
+                const now = performance.now();
+                if (this.lastKeyActivateIndex === index && now - this.lastKeyActivateTime <= EXPAND_KEY_INTERVAL_MS) {
+                    const node = this.simNodes[index];
+                    if (node)
+                        this.emit('lyra-node-expand', { id: node.id });
+                    this.lastKeyActivateIndex = null;
+                }
+                else {
+                    this.lastKeyActivateIndex = index;
+                    this.lastKeyActivateTime = now;
+                }
+            }
             return;
         }
         const count = this.graphItemCount();
@@ -571,7 +1953,7 @@ export class LyraGraph extends LyraElement {
         <div part="base">
           <lyra-skeleton
             variant="rect"
-            style=${`--lyra-skeleton-w:${this.width}px;--lyra-skeleton-h:${this.height}px`}
+            style=${`--lyra-skeleton-w:${this.safeWidth}px;--lyra-skeleton-h:${this.safeHeight}px`}
           ></lyra-skeleton>
         </div>
       `;
@@ -579,6 +1961,99 @@ export class LyraGraph extends LyraElement {
         if (!this.nodes.length) {
             return html `<div part="base"><div part="empty">${this.localize('noData')}</div></div>`;
         }
+        if (this.renderer === 'canvas') {
+            return html `
+        <div part="base">
+          <canvas
+            part="canvas"
+            role="group"
+            aria-label=${this.accessibleLabel ||
+                this.localize('graphDiagram', undefined, {
+                    nodeCount: this.simNodes.length,
+                    linkCount: this.simLinks.length,
+                })}
+            tabindex=${this.graphItemCount() ? '-1' : '0'}
+          ></canvas>
+          <div part="tooltip" hidden></div>
+          <div part="live-region" class="sr-only" role="status" aria-live="polite" aria-atomic="true">
+            ${this.graphLiveText ||
+                (this.normalizedGraphItem() >= 0 ? this.graphItemAnnouncement(this.normalizedGraphItem()) : '')}
+          </div>
+          <ul part="data-list" class="sr-only" aria-label=${this.localize('graphDataList')}>
+            ${this.simNodes.map((node) => html `<li>${this.localize('graphNode', undefined, { label: this.nodeAccessibleText(node) })}</li>`)}
+            ${this.simLinks.map((link) => html `<li>${this.linkAccessibleText(link)}</li>`)}
+            ${this.visibleCommunities().map((entry) => html `<li>${this.localize('graphCommunity', undefined, {
+                label: entry.community.label ?? entry.community.id,
+                count: entry.members.length,
+            })}</li>`)}
+          </ul>
+          <div
+            part="cursor-items"
+            class="sr-only"
+            @keydown=${(e) => {
+                // Escape-clears-selection lives here (not on the canvas itself) because keydown from
+                // a focused cursor-item bubbles up through this container, never through the canvas
+                // -- the cursor-items list is canvas's sibling, not its descendant. Mirrors the svg
+                // template's own root-level Escape handler; each cursor-item's own onGraphKeyDown()
+                // (Enter/Space/arrows/Home/End) leaves Escape unhandled the same way a node/link
+                // element does, so it bubbles here.
+                if (e.key === 'Escape')
+                    this.clearSelection();
+            }}
+          >
+            ${this.simNodes.map((n, i) => html `
+                <!-- hit-area-exempt: this button lives inside [part="cursor-items"]'s
+                     class="sr-only" (internal/a11y.ts's clip: rect(0 0 0 0) box) -- it's
+                     the offscreen keyboard-roving a11y virtual cursor described in this
+                     class's own doc comment, never a visible/pointer-clickable box, so
+                     the 40px hit-area floor (meant for on-screen tap targets) doesn't apply. -->
+                <button
+                  part="cursor-item"
+                  tabindex=${this.normalizedGraphItem() === i ? '0' : '-1'}
+                  aria-label=${this.nodeAccessibleText(n)}
+                  @focus=${() => this.onGraphItemFocus(i)}
+                  @keydown=${(e) => this.onGraphKeyDown(e, i, (ev) => this.onNodeClick(n, ev))}
+                  @click=${(e) => this.onNodeClick(n, e)}
+                ></button>
+              `)}
+            ${this.simLinks.map((l, li) => {
+                const i = this.simNodes.length + li;
+                return html `
+                <!-- hit-area-exempt: see the node cursor-item above -- same offscreen
+                     sr-only virtual-cursor button, no visible/pointer-clickable box. -->
+                <button
+                  part="cursor-item"
+                  tabindex=${this.normalizedGraphItem() === i ? '0' : '-1'}
+                  aria-label=${this.linkAccessibleText(l)}
+                  @focus=${() => this.onGraphItemFocus(i)}
+                  @keydown=${(e) => this.onGraphKeyDown(e, i, (ev) => this.onLinkClick(l, ev))}
+                  @click=${(e) => this.onLinkClick(l, e)}
+                ></button>
+              `;
+            })}
+            ${this.visibleCommunities().map((entry, hi) => {
+                const i = this.simNodes.length + this.simLinks.length + hi;
+                const label = this.localize('graphCommunity', undefined, {
+                    label: entry.community.label ?? entry.community.id,
+                    count: entry.members.length,
+                });
+                return html `
+                <!-- hit-area-exempt: see the node cursor-item above -- same offscreen
+                     sr-only virtual-cursor button, no visible/pointer-clickable box. -->
+                <button
+                  part="cursor-item"
+                  tabindex=${this.normalizedGraphItem() === i ? '0' : '-1'}
+                  aria-label=${label}
+                  @focus=${() => this.onGraphItemFocus(i)}
+                  @keydown=${(e) => this.onGraphKeyDown(e, i, () => this.onCommunityClick(entry.community))}
+                  @click=${() => this.onCommunityClick(entry.community)}
+                ></button>
+              `;
+            })}
+          </div>
+        </div>
+      `;
+        }
         return html `
       <div part="base">
         <svg
@@ -589,8 +2064,16 @@ export class LyraGraph extends LyraElement {
                 nodeCount: this.simNodes.length,
                 linkCount: this.simLinks.length,
             })}
-          viewBox="0 0 ${this.width} ${this.height}"
+          viewBox="0 0 ${this.safeWidth} ${this.safeHeight}"
           tabindex=${this.graphItemCount() ? '-1' : '0'}
+          @click=${(e) => {
+            if (e.target === e.currentTarget)
+                this.clearSelection();
+        }}
+          @keydown=${(e) => {
+            if (e.key === 'Escape')
+                this.clearSelection();
+        }}
         >
           <defs>
             <marker
@@ -607,28 +2090,64 @@ export class LyraGraph extends LyraElement {
             </marker>
           </defs>
           <g transform="">
+            ${this.visibleCommunities().map((entry, hullIndex) => {
+            const itemIndex = this.simNodes.length + this.simLinks.length + hullIndex;
+            const hull = this.communityHull(entry.members);
+            const fill = sanitizeNodeColor(entry.community.color);
+            const label = this.localize('graphCommunity', undefined, {
+                label: entry.community.label ?? entry.community.id,
+                count: entry.members.length,
+            });
+            return svg `<g>
+                <path
+                  part="hull"
+                  role="button"
+                  tabindex=${this.normalizedGraphItem() === itemIndex ? '0' : '-1'}
+                  aria-label=${label}
+                  d=${hullPathD(hull)}
+                  style=${styleMap(fill ? { '--lyra-graph-hull-fill': fill } : {})}
+                  @click=${() => this.onCommunityClick(entry.community)}
+                  @focus=${() => this.onGraphItemFocus(itemIndex)}
+                  @keydown=${(e) => this.onGraphKeyDown(e, itemIndex, () => this.onCommunityClick(entry.community))}
+                ></path>
+                <text part="community-label" aria-hidden="true" x=${hullCentroidX(hull)} y=${hullTopY(hull) - HULL_PADDING}>${entry.community.label ?? entry.community.id}</text>
+              </g>`;
+        })}
             ${this.simLinks.map((l, linkIndex) => {
             const itemIndex = this.simNodes.length + linkIndex;
             const coordinates = this.linkCoordinates(l);
             const color = sanitizeNodeColor(l.color);
             const dash = normalizeLinkDash(l.dash);
-            return svg `<line
-                part="link"
-                role="button"
-                tabindex=${this.normalizedGraphItem() === itemIndex ? '0' : '-1'}
-                aria-label=${this.linkAccessibleText(l)}
-                stroke-width=${l.width ?? 1.5}
-                stroke-dasharray=${dash ?? nothing}
-                marker-end=${l.directed ? `url(#${this.arrowMarkerId})` : nothing}
-                style=${styleMap(color ? { '--lyra-link-color': color } : {})}
-                x1=${coordinates.x1}
-                y1=${coordinates.y1}
-                x2=${coordinates.x2}
-                y2=${coordinates.y2}
-                @click=${() => this.onLinkClick(l)}
-                @focus=${() => this.onGraphItemFocus(itemIndex)}
-                @keydown=${(e) => this.onGraphKeyDown(e, itemIndex, () => this.onLinkClick(l))}
-              >${l.description || l.label ? svg `<title>${l.description || l.label}</title>` : nothing}</line>`;
+            const labelPos = this.showEdgeLabels && l.label ? this.edgeLabelPosition(l) : undefined;
+            const lineEl = svg `<line
+                  part="link"
+                  role="button"
+                  tabindex=${this.normalizedGraphItem() === itemIndex ? '0' : '-1'}
+                  aria-label=${this.linkAccessibleText(l)}
+                  aria-pressed=${this.selectionMode !== 'none' ? String(this.isSelected('link', this.linkKey(l))) : nothing}
+                  ?data-selected=${this.isSelected('link', this.linkKey(l))}
+                  ?data-dimmed=${this.isDimmed('link', this.linkKey(l))}
+                  stroke-width=${l.width ?? 1.5}
+                  stroke-dasharray=${dash ?? nothing}
+                  marker-end=${l.directed ? `url(#${this.arrowMarkerId})` : nothing}
+                  style=${styleMap(color ? { '--lyra-link-color': color } : {})}
+                  x1=${coordinates.x1}
+                  y1=${coordinates.y1}
+                  x2=${coordinates.x2}
+                  y2=${coordinates.y2}
+                  @click=${(e) => this.onLinkClick(l, e)}
+                  @focus=${() => this.onGraphItemFocus(itemIndex)}
+                  @keydown=${(e) => this.onGraphKeyDown(e, itemIndex, (ev) => this.onLinkClick(l, ev))}
+                  @mouseenter=${(e) => this.onLinkEnter(l, e)}
+                  @mouseleave=${(e) => this.onLinkLeave(l, e)}
+                >${l.description || l.label ? svg `<title>${l.description || l.label}</title>` : nothing}</line>`;
+            // Only wrap in a <g> when a label will actually be drawn -- an unconditional wrapper
+            // would change existing consumers' rendered link DOM (bare <line part="link">) even
+            // when showEdgeLabels is never set, breaking the "existing usage renders byte-for-byte
+            // identical output" contract this drawn-edge-label feature must preserve.
+            return labelPos
+                ? svg `<g>${lineEl}<text part="link-label" aria-hidden="true" text-anchor="middle" x=${labelPos.x} y=${labelPos.y}>${l.label}</text></g>`
+                : lineEl;
         })}
             ${this.danglingLinks.map((l) => {
             const source = l.source;
@@ -644,27 +2163,69 @@ export class LyraGraph extends LyraElement {
               ></line>`;
         })}
             ${this.simNodes.map((n, nodeIndex) => {
-            const fill = sanitizeNodeColor(n.color);
+            const shape = this.nodeShape(n);
+            const fill = this.nodeFill(n);
             const itemIndex = nodeIndex;
+            const tabindex = this.normalizedGraphItem() === itemIndex ? '0' : '-1';
+            const label = this.nodeAccessibleText(n);
+            // Unlike link styling below (which always renders style=${styleMap(...)}, even as
+            // an empty string), an untyped/unknown-type node must render with NO style
+            // attribute at all -- not just an empty one -- so hasAttribute('style') distinguishes
+            // "no fill override" from "fill override present" for consumers/tests probing the DOM.
+            const style = fill ? styleMap({ '--lyra-node-fill': fill }) : nothing;
+            const title = n.description ? svg `<title>${n.description}</title>` : nothing;
+            const shapeEl = shape === 'circle'
+                ? svg `<circle
+                      part="node"
+                      role="button"
+                      tabindex=${tabindex}
+                      aria-label=${label}
+                      aria-pressed=${this.selectionMode !== 'none' ? String(this.isSelected('node', n.id)) : nothing}
+                      ?data-selected=${this.isSelected('node', n.id)}
+                      ?data-dimmed=${this.isDimmed('node', n.id)}
+                      r=${this.nodeRadius(n)}
+                      cx=${n.x ?? 0}
+                      cy=${n.y ?? 0}
+                      style=${style}
+                      @click=${(e) => this.onNodeClick(n, e)}
+                      @dblclick=${(e) => this.onNodeDblClick(n, e)}
+                      @focus=${() => this.onGraphItemFocus(itemIndex)}
+                      @keydown=${(e) => this.onGraphKeyDown(e, itemIndex, (ev) => this.onNodeClick(n, ev))}
+                      @mouseenter=${(e) => this.onNodeEnter(n, e)}
+                      @mouseleave=${(e) => this.onNodeLeave(n, e)}
+                    >${title}</circle>`
+                : svg `<path
+                      part="node"
+                      role="button"
+                      tabindex=${tabindex}
+                      aria-label=${label}
+                      aria-pressed=${this.selectionMode !== 'none' ? String(this.isSelected('node', n.id)) : nothing}
+                      ?data-selected=${this.isSelected('node', n.id)}
+                      ?data-dimmed=${this.isDimmed('node', n.id)}
+                      d=${shape === 'square' ? squarePath(this.nodeRadius(n)) : diamondPath(this.nodeRadius(n))}
+                      transform="translate(${n.x ?? 0},${n.y ?? 0})"
+                      style=${style}
+                      @click=${(e) => this.onNodeClick(n, e)}
+                      @dblclick=${(e) => this.onNodeDblClick(n, e)}
+                      @focus=${() => this.onGraphItemFocus(itemIndex)}
+                      @keydown=${(e) => this.onGraphKeyDown(e, itemIndex, (ev) => this.onNodeClick(n, ev))}
+                      @mouseenter=${(e) => this.onNodeEnter(n, e)}
+                      @mouseleave=${(e) => this.onNodeLeave(n, e)}
+                    >${title}</path>`;
             return svg `<g>
-                <circle
-                  part="node"
-                  role="button"
-                  tabindex=${this.normalizedGraphItem() === itemIndex ? '0' : '-1'}
-                  aria-label=${this.nodeAccessibleText(n)}
-                  r=${this.nodeRadius(n)}
-                  cx=${n.x ?? 0}
-                  cy=${n.y ?? 0}
-                  style=${styleMap(fill ? { '--lyra-node-fill': fill } : {})}
-                  @click=${() => this.onNodeClick(n)}
-                  @focus=${() => this.onGraphItemFocus(itemIndex)}
-                  @keydown=${(e) => this.onGraphKeyDown(e, itemIndex, () => this.onNodeClick(n))}
-                >${n.description ? svg `<title>${n.description}</title>` : nothing}</circle>
+                ${shapeEl}
                 ${n.label
                 ? svg `<text part="label" aria-hidden="true" x=${(n.x ?? 0) + this.nodeRadius(n) + 2} y=${n.y ?? 0}>${n.label}</text>`
                 : ''}
+                ${n.expandable
+                ? svg `<g part="expand-indicator" aria-hidden="true" transform="translate(${n.x ?? 0},${n.y ?? 0})">
+                      <circle r=${EXPAND_BADGE_R} cx=${this.nodeRadius(n) * EXPAND_BADGE_OFFSET} cy=${-this.nodeRadius(n) * EXPAND_BADGE_OFFSET}></circle>
+                      <path d="M ${this.nodeRadius(n) * EXPAND_BADGE_OFFSET - EXPAND_BADGE_R / 2} ${-this.nodeRadius(n) * EXPAND_BADGE_OFFSET} L ${this.nodeRadius(n) * EXPAND_BADGE_OFFSET + EXPAND_BADGE_R / 2} ${-this.nodeRadius(n) * EXPAND_BADGE_OFFSET} M ${this.nodeRadius(n) * EXPAND_BADGE_OFFSET} ${-this.nodeRadius(n) * EXPAND_BADGE_OFFSET - EXPAND_BADGE_R / 2} L ${this.nodeRadius(n) * EXPAND_BADGE_OFFSET} ${-this.nodeRadius(n) * EXPAND_BADGE_OFFSET + EXPAND_BADGE_R / 2}"></path>
+                    </g>`
+                : ''}
               </g>`;
         })}
+            <circle part="focus-halo" aria-hidden="true" hidden r="0" cx="0" cy="0"></circle>
           </g>
         </svg>
         <div part="live-region" class="sr-only" role="status" aria-live="polite" aria-atomic="true">
@@ -674,6 +2235,10 @@ export class LyraGraph extends LyraElement {
         <ul part="data-list" class="sr-only" aria-label=${this.localize('graphDataList')}>
           ${this.simNodes.map((node) => html `<li>${this.localize('graphNode', undefined, { label: this.nodeAccessibleText(node) })}</li>`)}
           ${this.simLinks.map((link) => html `<li>${this.linkAccessibleText(link)}</li>`)}
+          ${this.visibleCommunities().map((entry) => html `<li>${this.localize('graphCommunity', undefined, {
+            label: entry.community.label ?? entry.community.id,
+            count: entry.members.length,
+        })}</li>`)}
         </ul>
       </div>
     `;
@@ -685,6 +2250,21 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], LyraGraph.prototype, "links", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraGraph.prototype, "nodeTypes", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraGraph.prototype, "hiddenTypes", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraGraph.prototype, "communities", void 0);
+__decorate([
+    property()
+], LyraGraph.prototype, "layout", void 0);
+__decorate([
+    property()
+], LyraGraph.prototype, "renderer", void 0);
 __decorate([
     property({ type: Number })
 ], LyraGraph.prototype, "width", void 0);
@@ -709,6 +2289,30 @@ __decorate([
 __decorate([
     property({ type: Number })
 ], LyraGraph.prototype, "seed", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'show-edge-labels' })
+], LyraGraph.prototype, "showEdgeLabels", void 0);
+__decorate([
+    property({ type: Number, attribute: 'edge-label-min-zoom' })
+], LyraGraph.prototype, "edgeLabelMinZoom", void 0);
+__decorate([
+    property({ attribute: 'focus-id' })
+], LyraGraph.prototype, "focusId", void 0);
+__decorate([
+    property({ attribute: 'selection-mode' })
+], LyraGraph.prototype, "selectionMode", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraGraph.prototype, "selectedNodeIds", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraGraph.prototype, "selectedLinkIds", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraGraph.prototype, "dimmedNodeIds", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraGraph.prototype, "dimmedLinkIds", void 0);
 __decorate([
     state()
 ], LyraGraph.prototype, "loading", void 0);
@@ -724,4 +2328,7 @@ __decorate([
 __decorate([
     state()
 ], LyraGraph.prototype, "graphLiveText", void 0);
+__decorate([
+    query('canvas')
+], LyraGraph.prototype, "canvasEl", void 0);
 //# sourceMappingURL=graph.class.js.map