@yggy-tech/graphraum 0.34.0 → 0.35.0

package/README.md

@@ -1,7 +1,7 @@
 <p align="center">
   <picture>
     <source media="(prefers-color-scheme: dark)" srcset="./docs/src/assets/logo-dark.svg">
-    <img src="./docs/src/assets/logo-light.svg" alt="graphraum logo" width="128" height="128">
+    <img src="./docs/src/assets/logo-light.svg" alt="graphraum" width="128" height="128">
   </picture>
   <br>
   <strong>graphraum</strong>
@@ -11,9 +11,9 @@
 
 # graphraum
 
-An opinionated WebGL engine for interactive node-edge graphs in 2D and 3D.
+yggy's WebGL engine for interactive node-edge graphs in 2D and 3D.
 
-graphraum is deliberately narrow: it renders graphs, accepts positions from any layout engine, and keeps the hot path outside a component framework. Nodes use one instanced mesh, edges use one batched geometry, and rendering happens on demand.
+graphraum renders graphs, accepts positions from any layout engine, and keeps the hot path outside a component framework. Nodes use one instanced mesh, edges use one batched geometry, and rendering happens on demand.
 
 > Pre-1.0 development. The API will continue to evolve while the rendering and visual contracts are proven.
 
@@ -47,25 +47,20 @@ Repository decisions and agent instructions live in [`AGENTS.md`](./AGENTS.md).
 
 ## Install
 
-graphraum is currently published to the GitHub Packages npm registry. Configure the `@domudev` scope and authenticate with a classic GitHub token that has `read:packages` permission:
-
-```ini
-# .npmrc
-@domudev:registry=https://npm.pkg.github.com
-//npm.pkg.github.com/:_authToken=${GITHUB_PACKAGES_TOKEN}
-```
-
-Then install it with Bun:
-
 ```sh
-bun add @domudev/graphraum
+npm install @yggy-tech/graphraum
+yarn add @yggy-tech/graphraum
+pnpm add @yggy-tech/graphraum
+bun add @yggy-tech/graphraum
 ```
 
-Publishing is automated with semantic-release after CI succeeds on `main`. Commit types determine the next version, semantic-release creates the `v<version>` tag and GitHub Release, and the package is published to GitHub Packages. Do not manually edit the package version or create routine release tags.
+Use the line for your package manager.
+
+Publishing is automated with semantic-release after CI succeeds on `main`. Commit types determine the next version, semantic-release creates the `v<version>` tag and GitHub Release, and the package is published to npm. Do not manually edit the package version or create routine release tags.
 
 ## Documentation
 
-The [documentation](https://domudev.github.io/graphraum/), [API reference](https://domudev.github.io/graphraum/reference/api/), and the live [playground](https://domudev.github.io/graphraum/playground/) with the Prove benchmark are published on GitHub Pages. Run them locally with:
+The [documentation](https://yggy-tech.github.io/graphraum/), [API reference](https://yggy-tech.github.io/graphraum/reference/api/), and the live [playground](https://yggy-tech.github.io/graphraum/playground/) with the Prove benchmark are published on GitHub Pages. Run them locally with:
 
 ```sh
 bun install --cwd docs

package/dist/index.d.ts

@@ -72,6 +72,14 @@ interface GraphraumData<NodeAttributes = undefined, EdgeAttributes = undefined>
   nodes: readonly GraphraumNode<NodeAttributes>[];
   edges: readonly GraphraumEdge<EdgeAttributes>[];
 }
+interface GraphraumSetDataOptions {
+  /**
+   * Fit the camera to the new data (default `true`). `false` replaces the data and leaves the camera
+   * where it is, for hosts that pass a full snapshot on every change. On a graph that never had a
+   * fit the camera keeps its initial pose, so call `fitView()` once after the first data.
+   */
+  fit?: boolean;
+}
 interface GraphraumDataPatch<NodeAttributes = undefined, EdgeAttributes = undefined> {
   addedNodes?: readonly GraphraumNode<NodeAttributes>[];
   addedEdges?: readonly GraphraumEdge<EdgeAttributes>[];
@@ -531,7 +539,8 @@ declare class Graphraum<NodeAttributes = undefined, EdgeAttributes = undefined>
   private readonly focusListeners;
   private lastHoveredNodeId;
   constructor(container: HTMLElement, options?: GraphraumOptions<NodeAttributes, EdgeAttributes>);
-  setData(data: GraphraumData<NodeAttributes, EdgeAttributes>): void;
+  /** Replaces the whole graph. Fits the camera unless `options.fit` is `false`. */
+  setData(data: GraphraumData<NodeAttributes, EdgeAttributes>, options?: GraphraumSetDataOptions): void;
   /** Merge a topology patch without fitting or resetting the current camera. */
   applyDataPatch(patch: GraphraumDataPatch<NodeAttributes, EdgeAttributes>): void;
   private canAppendDataPatch;
@@ -851,4 +860,4 @@ declare function isTransparentGraphraumBackground(background: GraphraumBackgroun
 /** Defines typed, serializable graph visuals without coupling application data to the render loop. */
 declare function defineVisuals<NodeAttributes = undefined, EdgeAttributes = undefined>(visuals: GraphraumVisualMapper<NodeAttributes, EdgeAttributes>): GraphraumVisualMapper<NodeAttributes, EdgeAttributes>;
 //#endregion
-export { type CompiledGraphraumPresentation, DEFAULT_ENDPOINT_ATTACH, DEFAULT_ENDPOINT_CLEARANCE, DEFAULT_FORCE_SETTINGS, type EndpointAttach, type EndpointOutline, type ForceLayoutRequest, type ForceSettings, type GraphologyEdgeAttributes, type GraphologyNodeAttributes, type GraphologyRenderer, Graphraum, type GraphraumAutoOrbitOptions, type GraphraumAutoOrbitStatus, type GraphraumBackground, type GraphraumColor, type GraphraumData, type GraphraumDataPatch, type GraphraumDiagnostics, type GraphraumEdge, type GraphraumEdgeEncoding, type GraphraumEdgeMarker, type GraphraumEdgeMarkerEnd, type GraphraumEdgePath, type GraphraumEdgeState, type GraphraumEdgeStyle, type GraphraumEdgeVisual, type GraphraumFlyToOptions, type GraphraumLabelCandidate, type GraphraumLayoutPositions, type GraphraumMode, type GraphraumNode, type GraphraumNodeEncoding, type GraphraumNodeGeometry, type GraphraumNodeShape, type GraphraumNodeState, type GraphraumNodeUpdate, type GraphraumNodeVisual, type GraphraumOptions, GraphraumOverlay, type GraphraumOverlayNode, type GraphraumOverlayOptions, type GraphraumPatternBackground, type GraphraumPickHit, type GraphraumPosition, type GraphraumPresentation, type GraphraumPresentationAction, type GraphraumPresentationProperty, type GraphraumPropertyValue, type GraphraumScreenPosition, type GraphraumTheme, type GraphraumThemeName, type GraphraumVisualMapper, type LabelBudgetCandidate, type RichNodePolicy, type SelectBudgetedLabelIdsInput, type SelectFocusLabelIdsInput, attachPointOnOutline, bindGraphology, boundOverlayIds, computeClusteredForcePositions, computeForcePositions, createForceSimulation, defineVisuals, forceIterationCount, graphraumEdgePaths, graphraumNodeShapes, graphraumTheme, graphraumThemeDark, graphraumThemeLight, graphraumThemes, isTransparentGraphraumBackground, normalizeGraphraumBackground, orderFocusNodeIds, resolveGraphraumTheme, selectBudgetedLabelIds, selectFocusLabelIds, selectRichNodeIds, trimEdgeEndpoints };
+export { type CompiledGraphraumPresentation, DEFAULT_ENDPOINT_ATTACH, DEFAULT_ENDPOINT_CLEARANCE, DEFAULT_FORCE_SETTINGS, type EndpointAttach, type EndpointOutline, type ForceLayoutRequest, type ForceSettings, type GraphologyEdgeAttributes, type GraphologyNodeAttributes, type GraphologyRenderer, Graphraum, type GraphraumAutoOrbitOptions, type GraphraumAutoOrbitStatus, type GraphraumBackground, type GraphraumColor, type GraphraumData, type GraphraumDataPatch, type GraphraumDiagnostics, type GraphraumEdge, type GraphraumEdgeEncoding, type GraphraumEdgeMarker, type GraphraumEdgeMarkerEnd, type GraphraumEdgePath, type GraphraumEdgeState, type GraphraumEdgeStyle, type GraphraumEdgeVisual, type GraphraumFlyToOptions, type GraphraumLabelCandidate, type GraphraumLayoutPositions, type GraphraumMode, type GraphraumNode, type GraphraumNodeEncoding, type GraphraumNodeGeometry, type GraphraumNodeShape, type GraphraumNodeState, type GraphraumNodeUpdate, type GraphraumNodeVisual, type GraphraumOptions, GraphraumOverlay, type GraphraumOverlayNode, type GraphraumOverlayOptions, type GraphraumPatternBackground, type GraphraumPickHit, type GraphraumPosition, type GraphraumPresentation, type GraphraumPresentationAction, type GraphraumPresentationProperty, type GraphraumPropertyValue, type GraphraumScreenPosition, type GraphraumSetDataOptions, type GraphraumTheme, type GraphraumThemeName, type GraphraumVisualMapper, type LabelBudgetCandidate, type RichNodePolicy, type SelectBudgetedLabelIdsInput, type SelectFocusLabelIdsInput, attachPointOnOutline, bindGraphology, boundOverlayIds, computeClusteredForcePositions, computeForcePositions, createForceSimulation, defineVisuals, forceIterationCount, graphraumEdgePaths, graphraumNodeShapes, graphraumTheme, graphraumThemeDark, graphraumThemeLight, graphraumThemes, isTransparentGraphraumBackground, normalizeGraphraumBackground, orderFocusNodeIds, resolveGraphraumTheme, selectBudgetedLabelIds, selectFocusLabelIds, selectRichNodeIds, trimEdgeEndpoints };

package/dist/index.js

@@ -124,6 +124,14 @@ function outlineRadius(outline, headingX, headingY) {
 	return low;
 }
 /**
+* How far an edge end stops short of a 3D node's center, in world units: the outline radius (stroke
+* included) less `clearance`. The renderer applies it on screen, where the camera-facing outline
+* is, so it is exact for circles from every view. Other shapes use their radius along +x.
+*/
+function outlineReach(outline, clearance = DEFAULT_ENDPOINT_CLEARANCE) {
+	return Math.max(0, outlineRadius(outline, 1, 0) - Math.max(clearance, 0));
+}
+/**
 * Walk from the node center toward the far point and stop on the outline,
 * then pull back by `clearance` so the stroke is not stabbed.
 *
@@ -1333,34 +1341,40 @@ function packEdgeInstances(input) {
 		let x2 = input.endpointPositions[base + 3] ?? 0;
 		let y2 = input.endpointPositions[base + 4] ?? 0;
 		let z2 = input.endpointPositions[base + 5] ?? 0;
+		let trimSource = 0;
+		let trimTarget = 0;
 		if (attach === "boundary" && input.nodeOutlines && input.edgeNodeIndices) {
 			const sourceIndex = input.edgeNodeIndices[edgeIndex * 2] ?? 0;
 			const targetIndex = input.edgeNodeIndices[edgeIndex * 2 + 1] ?? 0;
 			const sourceOutline = input.nodeOutlines[sourceIndex] ?? {};
 			const targetOutline = input.nodeOutlines[targetIndex] ?? {};
-			const trimmed = trimEdgeEndpoints({
-				attach,
-				clearance,
-				mode: input.mode,
-				source: {
-					x: x1,
-					y: y1,
-					z: z1
-				},
-				target: {
-					x: x2,
-					y: y2,
-					z: z2
-				},
-				sourceOutline,
-				targetOutline
-			});
-			x1 = trimmed.source.x;
-			y1 = trimmed.source.y;
-			z1 = trimmed.source.z ?? 0;
-			x2 = trimmed.target.x;
-			y2 = trimmed.target.y;
-			z2 = trimmed.target.z ?? 0;
+			if (input.mode === "3d") {
+				trimSource = outlineReach(sourceOutline, clearance);
+				trimTarget = outlineReach(targetOutline, clearance);
+			} else {
+				const trimmed = trimEdgeEndpoints({
+					attach,
+					clearance,
+					source: {
+						x: x1,
+						y: y1,
+						z: z1
+					},
+					target: {
+						x: x2,
+						y: y2,
+						z: z2
+					},
+					sourceOutline,
+					targetOutline
+				});
+				x1 = trimmed.source.x;
+				y1 = trimmed.source.y;
+				z1 = trimmed.source.z ?? 0;
+				x2 = trimmed.target.x;
+				y2 = trimmed.target.y;
+				z2 = trimmed.target.z ?? 0;
+			}
 		}
 		const { color, opacity } = resolveEdgePaint(edgeIndex, visual, input.defaults, input.tier, input.edgeStates);
 		const width = input.tier === "overview" ? input.defaults.width : visual.width ?? input.defaults.width;
@@ -1396,7 +1410,9 @@ function packEdgeInstances(input) {
 				color,
 				width,
 				opacity,
-				style
+				style,
+				trimStart: index === 0 ? trimSource : 0,
+				trimEnd: index === segmentSpans - 1 ? trimTarget : 0
 			});
 		}
 		if (input.tier === "overview") continue;
@@ -1421,7 +1437,8 @@ function packEdgeInstances(input) {
 				dz: fromSource ? (first.z ?? 0) - (second.z ?? 0) : (last.z ?? 0) - (previous.z ?? 0),
 				color,
 				size: markerSize,
-				opacity
+				opacity,
+				trim: fromSource ? trimSource : trimTarget
 			});
 		};
 		if (ends === "source" || ends === "both") add("source");
@@ -1494,6 +1511,7 @@ attribute vec3 instanceEndB;
 attribute vec4 instanceColor;
 attribute float instanceWidth;
 attribute float instanceStyle;
+attribute vec2 instanceTrim;
 
 varying vec4 edgeColor;
 varying float edgeKind;
@@ -1517,6 +1535,18 @@ void main() {
 		vec2 delta = viewB.xy - viewA.xy;
 		float len = length(delta);
 		vec2 dir = len > 0.0001 ? delta / len : vec2(1.0, 0.0);
+		// 3D boundary ends (see trimViewSegment): stop on the camera-facing outline. A trimmed end
+		// keeps its node's depth, where the billboard is, so it meets the rim from every view.
+		if (instanceTrim.x + instanceTrim.y > 0.0) {
+			if (len - instanceTrim.x - instanceTrim.y <= 0.0) {
+				gl_Position = vec4(0.0, 0.0, 2.0, 1.0); // hidden behind its nodes: clip it away
+				return;
+			}
+			viewA.xy += dir * instanceTrim.x;
+			viewB.xy -= dir * instanceTrim.y;
+			delta = viewB.xy - viewA.xy;
+			len = length(delta);
+		}
 		vec2 perp = vec2(-dir.y, dir.x);
 		vec2 mid = (viewA.xy + viewB.xy) * 0.5;
 		vec2 offset = dir * position.x * len + perp * position.y * instanceWidth;
@@ -1531,8 +1561,10 @@ void main() {
 		vec2 dir = dirLen > 0.0001 ? dirVec / dirLen : vec2(1.0, 0.0);
 		vec2 perp = vec2(-dir.y, dir.x);
 		float t = position.x + 0.5;
+		// 3D boundary ends pull the apex back onto the camera-facing outline (see markerApexInView).
+		vec2 apex = viewA.xy - dir * instanceTrim.x;
 		vec2 offset = dir * instanceWidth * (t - 1.0) + perp * position.y * instanceWidth;
-		viewPosition = vec4(viewA.xy + offset, viewA.z, 1.0);
+		viewPosition = vec4(apex + offset, viewA.z, 1.0);
 	}
 
 	gl_Position = projectionMatrix * viewPosition;
@@ -1565,6 +1597,16 @@ void main() {
 	${OUTPUT_COLOR_SPACE_FRAGMENT}
 }
 `;
+/** Per-instance attributes of the edge geometry; updates mark each of them dirty. */
+const EDGE_INSTANCE_ATTRIBUTES = [
+	"instanceKind",
+	"instanceEndA",
+	"instanceEndB",
+	"instanceColor",
+	"instanceWidth",
+	"instanceStyle",
+	"instanceTrim"
+];
 function createEdgeGeometry(capacity) {
 	const geometry = new PlaneGeometry(1, 1);
 	geometry.setAttribute("instanceKind", new InstancedBufferAttribute(new Float32Array(capacity), 1));
@@ -1573,6 +1615,7 @@ function createEdgeGeometry(capacity) {
 	geometry.setAttribute("instanceColor", new InstancedBufferAttribute(new Float32Array(capacity * 4), 4));
 	geometry.setAttribute("instanceWidth", new InstancedBufferAttribute(new Float32Array(capacity), 1));
 	geometry.setAttribute("instanceStyle", new InstancedBufferAttribute(new Float32Array(capacity), 1));
+	geometry.setAttribute("instanceTrim", new InstancedBufferAttribute(new Float32Array(capacity * 2), 2));
 	return geometry;
 }
 function createEdgeMaterial() {
@@ -1602,6 +1645,7 @@ function writeEdgeSegmentInstance(geometry, slot, segment) {
 	writeEdgeColorSlots(color, slot, 1, segment);
 	width.setX(slot, segment.width);
 	style.setX(slot, encodeEdgeStyle(segment.style));
+	getInstancedAttribute(geometry, "instanceTrim").setXY(slot, segment.trimStart, segment.trimEnd);
 }
 function writeEdgeMarkerInstance(geometry, slot, marker) {
 	const kind = getInstancedAttribute(geometry, "instanceKind");
@@ -1616,6 +1660,7 @@ function writeEdgeMarkerInstance(geometry, slot, marker) {
 	writeEdgeColorSlots(color, slot, 1, marker);
 	width.setX(slot, marker.size);
 	style.setX(slot, 0);
+	getInstancedAttribute(geometry, "instanceTrim").setXY(slot, marker.trim, 0);
 }
 /** Writes one color and opacity into `count` consecutive instance slots starting at `start`. */
 function writeEdgeColorSlots(color, start, count, paint) {
@@ -1624,14 +1669,6 @@ function writeEdgeColorSlots(color, start, count, paint) {
 }
 //#endregion
 //#region src/edge-viewport-patch.ts
-const EDGE_INSTANCE_ATTRIBUTES$1 = [
-	"instanceKind",
-	"instanceEndA",
-	"instanceEndB",
-	"instanceColor",
-	"instanceWidth",
-	"instanceStyle"
-];
 /** Records GPU slot ranges for each visible edge after a full viewport materialize. */
 function buildVisibleEdgeLayouts(segments, markers, segmentInstanceCount) {
 	const layouts = /* @__PURE__ */ new Map();
@@ -1719,7 +1756,7 @@ function patchVisibleEdgeInstances(geometry, input, pickableSegments) {
 		ok: true,
 		pickableSegments: nextPickable
 	};
-	for (const name of EDGE_INSTANCE_ATTRIBUTES$1) {
+	for (const name of EDGE_INSTANCE_ATTRIBUTES) {
 		const attribute = geometry.getAttribute(name);
 		attribute.addUpdateRange(dirtySlotStart * attribute.itemSize, (dirtySlotEnd - dirtySlotStart + 1) * attribute.itemSize);
 		attribute.needsUpdate = true;
@@ -2725,14 +2762,6 @@ const FLIGHT_CANCEL_EVENTS = [
 	"pointerdown",
 	"wheel"
 ];
-const EDGE_INSTANCE_ATTRIBUTES = [
-	"instanceKind",
-	"instanceEndA",
-	"instanceEndB",
-	"instanceColor",
-	"instanceWidth",
-	"instanceStyle"
-];
 /** A small, explicit WebGL graph renderer: one instanced node mesh and one batched edge geometry. */
 var Graphraum = class {
 	container;
@@ -2853,8 +2882,11 @@ var Graphraum = class {
 		this.resizeObserver.observe(container);
 		this.resize();
 	}
-	setData(data) {
-		this.replaceData(data, true);
+	/** Replaces the whole graph. Fits the camera unless `options.fit` is `false`. */
+	setData(data, options = {}) {
+		const { fit = true } = options;
+		if (typeof fit !== "boolean") throw new Error("setData option fit must be a boolean.");
+		this.replaceData(data, fit);
 	}
 	/** Merge a topology patch without fitting or resetting the current camera. */
 	applyDataPatch(patch) {

package/package.json

@@ -1,57 +1,56 @@
 {
-  "name": "@yggy-tech/graphraum",
-  "version": "0.34.0",
-  "description": "An opinionated WebGL engine for interactive graphs in 2D and 3D",
-  "type": "module",
-  "license": "Apache-2.0",
-  "packageManager": "bun@1.3.1",
-  "publishConfig": {
-    "access": "public",
-    "registry": "https://registry.npmjs.org"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/yggy-tech/graphraum.git"
-  },
-  "sideEffects": false,
-  "files": [
-    "dist"
-  ],
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    }
-  },
-  "scripts": {
-    "build": "tsdown",
-    "check": "biome check . && tsc --noEmit",
-    "dev": "vite examples/benchmark",
-    "docs:build": "bun run --cwd docs build",
-    "docs:archive": "bun run docs/scripts/build-release-archives.ts",
-    "docs:check": "bun run --cwd docs check",
-    "docs:dev": "bun run --cwd docs dev",
-    "docs:test": "bun run --cwd docs test",
-    "prepack": "bun run build",
-    "release": "semantic-release",
-    "test": "vitest run src examples --exclude 'docs/**'"
-  },
-  "engines": {
-    "bun": ">=1.2.0"
-  },
-  "dependencies": {
-    "graphology": "^0.26.0",
-    "three": "^0.185.1"
-  },
-  "devDependencies": {
-    "@biomejs/biome": "^2.5.5",
-    "@commitlint/cli": "^21.2.1",
-    "@commitlint/config-conventional": "^21.2.0",
-    "@types/three": "^0.185.1",
-    "semantic-release": "^25.0.8",
-    "tsdown": "^0.22.13",
-    "typescript": "^6.0.3",
-    "vite": "^8.1.5",
-    "vitest": "^4.1.10"
-  }
+	"name": "@yggy-tech/graphraum",
+	"version": "0.35.0",
+	"description": "yggy's WebGL engine for interactive graphs in 2D and 3D",
+	"type": "module",
+	"license": "Apache-2.0",
+	"packageManager": "bun@1.3.1",
+	"publishConfig": {
+		"access": "public"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/yggy-tech/graphraum.git"
+	},
+	"sideEffects": false,
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js"
+		}
+	},
+	"scripts": {
+		"build": "tsdown",
+		"check": "biome check . && tsc --noEmit",
+		"dev": "vite examples/benchmark",
+		"docs:build": "bun run --cwd docs build",
+		"docs:archive": "bun run docs/scripts/build-release-archives.ts",
+		"docs:check": "bun run --cwd docs check",
+		"docs:dev": "bun run --cwd docs dev",
+		"docs:test": "bun run --cwd docs test",
+		"prepack": "bun run build",
+		"release": "semantic-release",
+		"test": "vitest run src examples --exclude 'docs/**'"
+	},
+	"engines": {
+		"bun": ">=1.2.0"
+	},
+	"dependencies": {
+		"graphology": "^0.26.0",
+		"three": "^0.185.1"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "^2.5.5",
+		"@commitlint/cli": "^21.2.1",
+		"@commitlint/config-conventional": "^21.2.0",
+		"@types/three": "^0.185.1",
+		"semantic-release": "^25.0.8",
+		"tsdown": "^0.22.13",
+		"typescript": "^6.0.3",
+		"vite": "^8.1.5",
+		"vitest": "^4.1.10"
+	}
 }