@yggy-tech/graphraum 0.34.0 → 0.34.1

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.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;

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.34.1",
+	"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"
+	}
 }