@simplex-viz/svg 0.1.2 → 0.1.3

package/README.md

@@ -1,3 +1,7 @@
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ghackenberg/simplex-viz/main/docs/assets/logo-svg.png" width="640" alt="SimplexViz / svg — @simplex-viz/svg" />
+</p>
+
 # @simplex-viz/svg
 
 Framework-agnostic SVG rendering engine and pluggable `SvgNodeView` architecture for `@simplex-viz/core`. Zero dependency on React—embeds cleanly into Vanilla TypeScript, Vue, Angular, Svelte, Solid, and Web Components.
@@ -6,7 +10,15 @@ Framework-agnostic SVG rendering engine and pluggable `SvgNodeView` architecture
 - **Source & Monorepo:** <https://github.com/ghackenberg/simplex-viz/tree/main/packages/svg>
 - **Companion Packages:** [`@simplex-viz/core`](https://www.npmjs.com/package/@simplex-viz/core) · [`@simplex-viz/react`](https://www.npmjs.com/package/@simplex-viz/react)
 
----
+## Visual Rendering Showcase
+
+While `@simplex-viz/core` computes pure spatial coordinates, `@simplex-viz/svg` turns each frame into live DOM `<svg>` elements inside any browser container or UI framework. The preview below renders its built-in views together in a single viewport:
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/ghackenberg/simplex-viz/main/docs/assets/preview-svg.png" width="100%" alt="@simplex-viz/svg rendering showcase showing GeometricShapeSvgView, MultiSectorGlyphSvgView, ClusterAnchorSvgView, and BadgeClusterSvgView" />
+</p>
+
+*Figure: Visual showcase of the four built-in `SvgNodeView` plugins rendered on an OKLab-tinted 60° simplex mesh. Content items mix `GeometricShapeSvgView` (circles, diamonds, hexagons, and stars that morph smoothly via 64-point paths) with `MultiSectorGlyphSvgView` (proportional donut glyphs whose sector arcs encode barycentric topic weights). Topic clusters alternate between compact `ClusterAnchorSvgView` vertex rings and auto-measured `BadgeClusterSvgView` cards sized via offscreen `getBBox()`.*
 
 ## Features
 
@@ -16,27 +28,26 @@ Framework-agnostic SVG rendering engine and pluggable `SvgNodeView` architecture
 - **Centralized root-SVG interactions**: Attaches pointer, click, right-click, wheel, drag-to-pan, and `ResizeObserver` listeners solely on the root `<svg>` element and delegates hit-testing to `@simplex-viz/core`'s exact convex geometry solver.
 - **Four built-in view plugins**: Ready-to-use views for geometric shape morphing, multi-sector topic glyphs, vertex anchors, and dynamic text badges.
 
----
-
 ## Installation
 
+Install `@simplex-viz/core` alongside `@simplex-viz/svg` in any browser or TypeScript project:
+
 ```bash
 npm install @simplex-viz/core @simplex-viz/svg
 ```
 
----
-
 ## Quickstart (Vanilla TypeScript)
 
+### Step 1 — Define Your Domain Record & `VisualResolver`
+
+Start by describing your data model (`Bookmark`) and mapping each item and topic cluster into visual descriptors for `GeometricShapeSvgView` and `ClusterAnchorSvgView`. `ctx.mixedColorHex` provides the item's barycentric OKLab color blend automatically:
+
 ```ts
-import {
-  SimplexSvgController,
-  GeometricShapeSvgView,
-  ClusterAnchorSvgView,
-  type GeometricShapeVisual,
-  type ClusterAnchorVisual,
-} from '@simplex-viz/svg';
 import type { VisualResolver } from '@simplex-viz/core';
+import type {
+  ClusterAnchorVisual,
+  GeometricShapeVisual,
+} from '@simplex-viz/svg';
 
 interface Bookmark {
   readonly url: string;
@@ -69,6 +80,18 @@ const visualResolver: VisualResolver<
       ? `${visual.shape}:${visual.radius}:${visual.fillHex}`
       : `${visual.code}:${visual.memberCount}:${visual.colorHex}`,
 };
+```
+
+### Step 2 — Mount `SimplexSvgController`
+
+Pass any container `HTMLElement` to `SimplexSvgController` along with `getId`, `getTags`, `visualResolver`, and the built-in views. The controller creates the root `<svg>`, attaches a `ResizeObserver`, computes the initial triangulation, and begins the 60 fps spring loop:
+
+```ts
+import {
+  SimplexSvgController,
+  GeometricShapeSvgView,
+  ClusterAnchorSvgView,
+} from '@simplex-viz/svg';
 
 const container = document.getElementById('graph')!;
 
@@ -79,41 +102,45 @@ const controller = new SimplexSvgController(container, {
   visualResolver,
   contentView: new GeometricShapeSvgView(),
   clusterView: new ClusterAnchorSvgView(),
-  meshOptions: {
-    innerPadding: 48,
-    minSideLength: 140,
-    maxSideLength: 280,
-    maxClusters: 10,
+  meshOptions: { innerPadding: 48, minSideLength: 140, maxSideLength: 280, maxClusters: 10 },
+  layoutOptions: { clusterGapPx: 14, itemGapPx: 5 },
+  onMetricsChange: (metrics) => {
+    console.log(`Clusters: ${metrics.clusterCount}, Overlaps: ${metrics.overlapCount}`);
   },
-  layoutOptions: {
-    clusterGapPx: 14,
-    itemGapPx: 5,
+});
+```
+
+### Step 3 — Wire Hover, Click & Wheel Interactions
+
+Attach centralized pointer, click, context-menu, and wheel handlers via `setInteractions` (or pass `interactions` directly in the constructor). Listeners live exclusively on the root `<svg>`, while hit-testing uses exact convex hulls:
+
+```ts
+controller.setInteractions({
+  onContentHover: (ev) => {
+    if (ev) console.log('Hovered item:', ev.item.title, ev.screenPosition);
   },
-  interactions: {
-    onContentHover: (ev) => {
-      if (ev) console.log('Hovered item:', ev.item.title, ev.screenPosition);
-    },
-    onLeftClick: (target) => {
-      if (target.kind === 'content') {
-        console.log('Clicked:', target.item.title);
-      } else if (target.kind === 'cluster') {
-        controller.setFocusedClusterUid(target.cluster.clusterUid);
-      } else {
-        controller.setFocusedClusterUid(null);
-      }
-    },
-    onRightClick: (target) => {
-      console.log('Context menu target:', target.kind);
-      return true; // Suppress browser default context menu
-    },
-    onWheel: 'zoom-to-cursor',
+  onLeftClick: (target) => {
+    if (target.kind === 'content') {
+      console.log('Clicked:', target.item.title);
+    } else if (target.kind === 'cluster') {
+      controller.setFocusedClusterUid(target.cluster.clusterUid);
+    } else {
+      controller.setFocusedClusterUid(null);
+    }
   },
-  onMetricsChange: (metrics) => {
-    console.log(`Clusters: ${metrics.clusterCount}, Overlaps: ${metrics.overlapCount}`);
+  onRightClick: (target) => {
+    console.log('Context menu target:', target.kind);
+    return true; // Suppress browser default context menu
   },
+  onWheel: 'zoom-to-cursor',
 });
+```
 
-// Live mutations & camera controls
+### Step 4 — Apply Live Mutations & Clean Up
+
+Mutate items or reset the camera smoothly at runtime without interrupting user navigation. Call `controller.destroy()` on unmount to stop animations and disconnect observers:
+
+```ts
 controller.addItems({
   url: 'https://example.com/oklab',
   title: 'Perceptual Color Mixing',
@@ -123,16 +150,14 @@ controller.addItems({
 controller.removeItems('https://example.com/old');
 controller.camera.reset();
 
-// Clean up DOM, ResizeObserver, and animation loop on unmount
+// Call on component unmount / teardown:
 // controller.destroy();
 ```
 
----
-
 ## Built-In `SvgNodeView` Plugins
 
 ### 1. `GeometricShapeSvgView`
-Renders `'circle' | 'diamond' | 'star' | 'hexagon'` with analytical convex hulls and **64-point parametric SVG path morphing** between shapes and colors.
+Renders `'circle' | 'diamond' | 'star' | 'hexagon'` with analytical convex hulls and **64-point parametric SVG path morphing** between shapes and colors. Pass a `GeometricShapeVisual` descriptor from `resolveContentVisual` to control polygon kind, radius, fill, and outline stroke:
 
 ```ts
 import type { GeometricShapeVisual } from '@simplex-viz/svg';
@@ -148,7 +173,7 @@ const visual: GeometricShapeVisual = {
 ```
 
 ### 2. `MultiSectorGlyphSvgView`
-Renders a multi-colored donut glyph whose sector arc angles match an item's exact barycentric weights across its active simplex unit (vertex, edge, or triangle).
+Renders a multi-colored donut glyph whose sector arc angles match an item's exact barycentric weights across its active simplex unit (vertex, edge, or triangle). Map `ctx.unitClusters` directly into `sectors` as shown below to reflect multi-topic membership visually:
 
 ```ts
 import type { MultiSectorGlyphVisual } from '@simplex-viz/svg';
@@ -165,7 +190,7 @@ const visual: MultiSectorGlyphVisual = {
 ```
 
 ### 3. `BadgeClusterSvgView`
-Renders dynamic pill/card cluster badges sized to their title and metadata line. Intentionally omits `measureConvexHull` so `@simplex-viz/svg` measures the rendered SVG element via `getBBox()`.
+Renders dynamic pill/card cluster badges sized to their title and metadata line. Because it intentionally omits `measureConvexHull`, `@simplex-viz/svg` measures the rendered `<svg>` elements via `getBBox()` so varying title lengths remain strictly overlap-free:
 
 ```ts
 import type { BadgeClusterVisual } from '@simplex-viz/svg';
@@ -179,7 +204,7 @@ const visual: BadgeClusterVisual = {
 ```
 
 ### 4. `ClusterAnchorSvgView`
-Renders calibrated double-ring vertex anchors showing the cluster code and member count.
+Renders calibrated double-ring vertex anchors showing the cluster code and member count. Supply a `ClusterAnchorVisual` descriptor when you want compact circular topic anchors on mesh vertices:
 
 ```ts
 import type { ClusterAnchorVisual } from '@simplex-viz/svg';
@@ -193,12 +218,12 @@ const visual: ClusterAnchorVisual = {
 };
 ```
 
----
-
 ## Writing Custom `SvgNodeView` Plugins
 
 Implement `SvgNodeView<TVisual>` centered around local origin `(0, 0)`. `SvgRendererAdapter` handles world positioning `(x, y)`, solver scale `α`, opacity, and crossfading on the parent `<g>`.
 
+First, define your visual descriptor and an optional analytical hull via `measureConvexHull` (if omitted, `@simplex-viz/svg` automatically measures the rendered SVG via offscreen `getBBox()`):
+
 ```ts
 import type { SvgNodeView } from '@simplex-viz/svg';
 import { rectToConvexPolygon } from '@simplex-viz/core';
@@ -208,18 +233,24 @@ interface CardVisual {
   readonly colorHex: string;
 }
 
+const getCardWidth = (title: string) => Math.max(80, title.length * 7 + 20);
+```
+
+Next, populate `mountOrUpdate` to construct pure SVG nodes inside `groupEl`, reacting to `state.interaction.isHovered` for instant border emphasis:
+
+```ts
 const SVG_NS = 'http://www.w3.org/2000/svg';
 
 export const CustomCardSvgView: SvgNodeView<CardVisual> = {
   // Optional: omit to measure automatically via offscreen getBBox()
   measureConvexHull: (visual) =>
-    rectToConvexPolygon(Math.max(80, visual.title.length * 7 + 20), 28, 6),
+    rectToConvexPolygon(getCardWidth(visual.title), 28, 6),
 
   mountOrUpdate: (groupEl, visual, state) => {
     const doc = groupEl.ownerDocument;
     while (groupEl.firstChild) groupEl.removeChild(groupEl.firstChild);
 
-    const width = Math.max(80, visual.title.length * 7 + 20);
+    const width = getCardWidth(visual.title);
     const rect = doc.createElementNS(SVG_NS, 'rect');
     rect.setAttribute('x', String(-width / 2));
     rect.setAttribute('y', '-14');
@@ -249,8 +280,6 @@ export const CustomCardSvgView: SvgNodeView<CardVisual> = {
 };
 ```
 
----
-
 ## `SimplexSvgController` API Summary
 
 | Method / Property | Description |
@@ -271,8 +300,6 @@ export const CustomCardSvgView: SvgNodeView<CardVisual> = {
 | `stepForTest(dtMs)` | Deterministically advances simulation time in unit/DOM tests. |
 | `destroy()` | Cancels `requestAnimationFrame`, disconnects `ResizeObserver`, and removes the `<svg>`. |
 
----
-
 ## License
 
 MIT — see [LICENSE](https://github.com/ghackenberg/simplex-viz/blob/main/LICENSE).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simplex-viz/svg",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Framework-agnostic SVG rendering engine, offscreen getBBox() hull measurer, and pluggable SvgNodeView system for @simplex-viz/core.",
   "license": "MIT",
   "type": "module",
@@ -20,7 +20,7 @@
     "LICENSE"
   ],
   "dependencies": {
-    "@simplex-viz/core": "^0.1.2"
+    "@simplex-viz/core": "^0.1.3"
   },
   "keywords": [
     "simplex",