@graphty/graphty-element 2.4.0 → 2.5.0

package/dist/src/meshes/FilledArrowRenderer.d.ts

@@ -1,4 +1,5 @@
-import { Mesh, Scene, ShaderMaterial, Vector3 } from "@babylonjs/core";
+import "@babylonjs/core/Meshes/instancedMesh";
+import { type AbstractMesh, InstancedMesh, Mesh, Scene, ShaderMaterial, Vector3 } from "@babylonjs/core";
 export interface FilledArrowOptions {
     size: number;
     color: string;
@@ -18,16 +19,23 @@ export interface FilledArrowOptions {
  */
 export declare class FilledArrowRenderer {
     private static shadersRegistered;
-    private static activeMaterials;
-    private static cameraCallbackRegistered;
+    /**
+     * Every billboarding material, grouped by scene, each scene's group given that scene's
+     * camera position once per frame. See {@link PerSceneMaterials} for the defect (issue #45).
+     */
+    private static readonly cameraTracked;
+    /**
+     * The arrowhead batches: per scene, one hidden source mesh per batch key. See
+     * {@link FilledArrowRenderer.instanceOf}.
+     */
+    private static readonly batches;
     /**
      * Unregister a shader material so the per-frame camera-uniform walk stops visiting it.
      *
      * WHY THIS EXISTS -- the defect it repairs:
      * {@link FilledArrowRenderer.applyShader} builds a fresh `ShaderMaterial` per mesh and
-     * adds it to {@link FilledArrowRenderer.activeMaterials}, which is iterated once per
-     * frame. Nothing removed entries. The `catch` inside that walk reads as an eviction
-     * path but cannot fire: `ShaderMaterial.setVector3` does not throw on a disposed
+     * adds it to the per-frame camera walk. Nothing used to remove entries. A `catch` inside
+     * that walk read as an eviction path but could not fire: `ShaderMaterial.setVector3` does not throw on a disposed
      * material, it just records the value into a dead material's uniform cache. So every
      * arrowhead and every pattern element ever built stayed in the walk for the lifetime of
      * the page, and since both are rebuilt wholesale on every style change the walk grew
@@ -48,21 +56,15 @@ export declare class FilledArrowRenderer {
      * Exists so the leak described on {@link FilledArrowRenderer.releaseMaterial} is
      * OBSERVABLE from a test; it has no visible symptom until the frame rate has already
      * collapsed, and asserting on frame time instead would be flaky.
+     * @param scene - Count only this scene's materials; omit for every scene
      * @returns Count of tracked materials
      * @public
      */
-    static getActiveMaterialCount(): number;
+    static getActiveMaterialCount(scene?: Scene): number;
     /**
      * Register filled arrow shaders
      */
     static registerShaders(): void;
-    /**
-     * Register the shared camera position update callback
-     * This callback updates ALL arrow materials at once, instead of having one callback per material.
-     * This dramatically improves performance when rendering many arrows.
-     * @param scene - The Babylon.js scene to register the callback on
-     */
-    private static registerCameraCallback;
     /**
      * Create a filled triangle arrow mesh
      *
@@ -191,13 +193,11 @@ export declare class FilledArrowRenderer {
      *
      * This line used to read `mesh.alwaysSelectAsActiveMesh = true`, with a comment
      * explaining that thin instances needed it because their base mesh was parked at
-     * y = -10000. Both halves of that comment are now false. The same function's comment two
-     * lines above says thin instances are no longer used, and `applyShader` has exactly three
-     * call sites -- `PatternedLineRenderer.createPatternMesh` twice and
-     * `EdgeMesh.createFilledArrow` once -- none of which parks a template anywhere: arrowhead
-     * meshes are built one per edge and positioned at the real arrow location by `Edge`, and
-     * the `MeshCache` template that genuinely does sit at y = -10000 holds NODE meshes, uses
-     * `InstancedMesh`, and never reaches this function. The flag's effect today is simply that
+     * y = -10000. Both halves of that comment are now false. This function is reached from
+     * `applyShader` (pattern elements, one mesh each) and from `createArrowInstance`, which
+     * calls it on each arrowhead INSTANCE -- positioned at the real arrow location by `Edge` --
+     * never on a parked template; and the `MeshCache` template that genuinely does sit at
+     * y = -10000 holds NODE meshes and never reaches this function. The flag's effect was that
      * every mesh carrying this shader is submitted every frame regardless of where the camera
      * is pointing -- which, at the mesh counts a dotted line used to reach, was thousands of
      * pointless draw calls per frame.
@@ -230,10 +230,48 @@ export declare class FilledArrowRenderer {
     /**
      * Set the line direction for a filled arrow mesh
      * This should be called every frame when the edge updates
-     * @param mesh - Filled arrow mesh
+     * @param mesh - Filled arrow mesh, or an arrowhead instance from {@link FilledArrowRenderer.createArrowInstance}
      * @param direction - Line direction vector (normalized)
      */
-    static setLineDirection(mesh: Mesh, direction: Vector3): void;
+    static setLineDirection(mesh: AbstractMesh, direction: Vector3): void;
+    /**
+     * Draw one arrowhead as an instance of its scene's batch for `key`, building the batch's
+     * hidden source mesh with `build` the first time the scene needs it.
+     *
+     * WHY -- issue #25: every arrowhead used to be its own `Mesh` with its own material, so N
+     * arrowheaded edges cost N draw calls a frame (and, through issue #27, O(N^2) to load). A
+     * batch is drawn in one call however many edges use it. Each instance keeps its own
+     * transform, and Babylon refills the per-instance buffers once per frame in one pass, so this
+     * does not bring back the per-edge buffer writes that made thin instances 35x slower.
+     *
+     * The source mesh goes when its last instance does, so a cleared graph leaves nothing in the
+     * scene, and the batches of one scene are never seen by another.
+     * @param scene - The scene the arrowhead is drawn in
+     * @param key - What the batch's heads have in common: shape, and whatever else lives on the material
+     * @param build - Builds the source mesh (with its material) for a new batch
+     * @returns The arrowhead: an instance of the batch's source mesh
+     */
+    static instanceOf(scene: Scene, key: string, build: () => Mesh): InstancedMesh;
+    /**
+     * Draw one billboarded 3D arrowhead as an instance of its scene's batch for that shape and
+     * opacity. The direction, size and colour are the instance's own attributes, so edges of
+     * every colour and size share one draw call.
+     * @param shape - The arrow type, which names the batch's geometry
+     * @param createShape - Builds that geometry, for a new batch
+     * @param options - The head's size (world-space length), colour and opacity
+     * @param scene - Babylon.js scene
+     * @returns The arrowhead instance; point it with {@link FilledArrowRenderer.setLineDirection}
+     */
+    static createArrowInstance(shape: string, createShape: () => Mesh, options: FilledArrowOptions, scene: Scene): InstancedMesh;
+    /**
+     * Give a batch's source mesh the billboard shader, reading direction, size and colour from
+     * instance attributes instead of uniforms.
+     * @param mesh - The batch's source mesh
+     * @param opacity - The opacity every head in the batch is drawn at
+     * @param scene - Babylon.js scene
+     * @returns The same mesh
+     */
+    private static applyInstancedShader;
     /**
      * Create a 2D arrow mesh with flat StandardMaterial
      *

package/dist/src/meshes/PatternedLineRenderer.d.ts

@@ -45,42 +45,16 @@ export declare const PATTERN_DEFINITIONS: Record<PatternType, PatternDefinition>
  * Static utility class for creating mesh-based pattern geometries for line visualization
  */
 export declare class PatternedLineRenderer {
-    private static activeMaterials;
-    private static cameraCallbackRegistered;
     /**
-     * Unregister a pattern material so the per-frame camera-uniform walk stops visiting it.
+     * Stop a pattern material receiving per-frame camera updates.
      *
-     * WHY THIS EXISTS -- the defect it repairs:
-     * Every pattern element (every dot, dash, star, diamond) owns its own `ShaderMaterial`,
-     * and creating one adds it to {@link PatternedLineRenderer.activeMaterials} and, inside
-     * `FilledArrowRenderer.applyShader`, to that class's own active set as well. Both sets
-     * are iterated once per frame to push the camera position uniform. Nothing ever removed
-     * an entry: `PatternedLineMesh.dispose` disposed the mesh with Babylon's default
-     * arguments, which leaves the material alive, and the `catch` inside each per-frame walk
-     * that looks like an eviction path cannot fire, because `ShaderMaterial.setVector3` does
-     * not throw on a disposed material. The result was a per-frame loop that grew
-     * monotonically for the lifetime of the page: every change of line style, width or colour
-     * rebuilt every edge's meshes and left the previous generation's materials in the walk
-     * forever. That is a second, slower-burning half of the same halt the product owner
-     * reported ("I changed line style to dot and width to 1 and everything crawled to a halt").
-     *
-     * Removal must reach BOTH sets, which is why this delegates to
-     * {@link FilledArrowRenderer.releaseMaterial} as well as clearing its own.
+     * Every pattern element owns its own `ShaderMaterial`, built by
+     * `FilledArrowRenderer.applyShader`, which registers it in that renderer's per-scene camera
+     * walk (see `PerSceneMaterials`). Disposing the material ends the registration on its own;
+     * `PatternedLineMesh` calls this as well, eagerly, before it disposes one.
      * @param material - The ShaderMaterial to stop tracking; passing an untracked material is a no-op
-     * @public
      */
     static releaseMaterial(material: ShaderMaterial): void;
-    /**
-     * Number of pattern materials currently receiving per-frame camera updates.
-     *
-     * Exists so the material leak described on {@link PatternedLineRenderer.releaseMaterial}
-     * is OBSERVABLE from a test. The leak has no visible symptom until the frame rate has
-     * already collapsed, and the count is the only direct evidence that a disposed pattern
-     * line truly stopped costing anything; asserting on frame time instead would be flaky.
-     * @returns Count of tracked materials
-     * @public
-     */
-    static getActiveMaterialCount(): number;
     /**
      * Create a PatternedLineMesh instance
      * Note: start/end are already adjusted by Edge.transformArrowCap() for node surfaces and arrows
@@ -233,11 +207,5 @@ export declare class PatternedLineRenderer {
      * @returns The default shape type for the pattern
      */
     private static getDefaultShapeType;
-    /**
-     * Register camera position update callback
-     * Updates all pattern materials in one batch per frame
-     * @param scene - Babylon.js scene
-     */
-    private static registerCameraCallback;
 }
 export {};

package/dist/src/meshes/PerSceneMaterials.d.ts

@@ -0,0 +1,49 @@
+import type { Scene, ShaderMaterial } from "@babylonjs/core";
+/**
+ * Called once per frame for one scene, with the shader materials that scene draws.
+ */
+type RefreshFn = (scene: Scene, materials: Iterable<ShaderMaterial>) => void;
+/**
+ * Shader materials grouped by the scene that draws them, each group refreshed by an observer on
+ * its OWN scene, just before that scene renders.
+ *
+ * WHY THIS EXISTS -- the defect it repairs (issue #45): the line, arrowhead and pattern renderers
+ * push per-frame uniforms (the render resolution, the camera position) into their shader
+ * materials. Each kept those materials in one static set shared by every `<graphty-element>` on
+ * the page, and registered its per-frame observer either once per page (on whichever scene came
+ * first) or once per scene switch. So a second element's arrowheads billboarded towards the
+ * FIRST element's camera, an element created after the first was disposed got no camera
+ * position at all, and each scene's observer walked every other scene's materials.
+ *
+ * Here each scene gets its own set and its own observer, which reads that scene's own engine and
+ * camera. A material leaves its set when it is disposed, and a scene's set and observer go when
+ * the scene is disposed, so nothing outlives the element that drew it.
+ */
+export declare class PerSceneMaterials {
+    private readonly refresh;
+    private readonly scenes;
+    /**
+     * Track materials whose uniforms `refresh` writes once per frame.
+     * @param refresh - Writes the per-frame uniforms of one scene's materials
+     */
+    constructor(refresh: RefreshFn);
+    /**
+     * Track a material under its own scene and give it its uniforms now, so it draws correctly
+     * even on the first frame.
+     * @param material - The shader material to keep refreshed
+     */
+    add(material: ShaderMaterial): void;
+    /**
+     * Stop refreshing a material. Disposing the material does this on its own.
+     * @param material - The material to forget; an untracked material is a no-op
+     */
+    delete(material: ShaderMaterial): void;
+    /**
+     * Number of tracked materials.
+     * @param scene - Count only this scene's materials; omit for every scene
+     * @returns How many materials are refreshed each frame
+     */
+    count(scene?: Scene): number;
+    private materialsOf;
+}
+export {};

package/dist/src/xr/XRSessionManager.d.ts

@@ -11,7 +11,7 @@ interface XRSessionConfig {
         referenceSpaceType: XRReferenceSpaceType;
         optionalFeatures?: string[];
     };
-    /** Whether XR sessions track hands (`xr.input.handTracking`). On, Babylon downloads hand meshes. Defaults to true. */
+    /** Whether XR sessions track hands (`xr.input.handTracking`). Defaults to true. */
     handTracking?: boolean;
 }
 /**

package/dist/webgpu.d.ts

@@ -46,6 +46,14 @@
  * republishes rather than finishing that work anywhere else. Recorded in
  * `docs/decisions/device-computes-incorrectly.md`.
  *
+ * That the ELEMENT reports `E_DEVICE_INCORRECT` on the Windows WARP renderer is inference, by
+ * decision, not a test: no lane runs graphty-element on WARP. The host matrix (`hosts.yml`) runs
+ * only webgpu-graph-algorithms there, whose own tests show the multi-block scan failing. This
+ * file's side -- a failed check becomes `E_DEVICE_INCORRECT`, and the controller refuses the
+ * device at attach -- is pinned against a stubbed peer and a deliberately wrong fake. Adding an
+ * element job to the Windows lane is a CI cost that can be taken on later if the two halves ever
+ * disagree.
+ *
  * ## Detection is not a fallback
  *
  * Finding out, before anything runs, that this host has no WebGPU and letting the element take

package/dist/webgpu.js

@@ -1,7 +1,7 @@
 import { EXACT_MAX_NODES as n, createAccelerator as p, verifyDevice as u } from "@graphty/webgpu-graph-algorithms";
 import { probeBrowserWebGpu as l, requestGpuContext as d } from "@graphty/webgpu-graph-algorithms/browser";
-import { r as h } from "./chunks/registry-jB46Gmeb.js";
-import { G as s } from "./chunks/GraphtyError-B93WRH3e.js";
+import { r as h } from "./chunks/registry-DQeq4B2K.js";
+import { G as s } from "./chunks/pluginRegistry-MaTIDh6l.js";
 const a = "webgpu-graph-algorithms", w = /* @__PURE__ */ new Set(["kind", "ctx", "options", "dispose", "verify"]);
 function b(o, e) {
   for (const [r, t] of Object.entries(o))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/graphty-element",
-  "version": "2.4.0",
+  "version": "2.5.0",
   "description": "A Web Component library for 3D/2D graph visualization built with Lit and Babylon.js",
   "type": "module",
   "customElements": "./dist/custom-elements.json",
@@ -134,7 +134,7 @@
     "vitepress": "^1.6.3",
     "vitest": "^3.2.4",
     "@graphty/remote-logger": "^1.3.7",
-    "@graphty/webgpu-graph-algorithms": "^0.6.6"
+    "@graphty/webgpu-graph-algorithms": "^0.6.7"
   },
   "peerDependencies": {
     "@ai-sdk/anthropic": "^2.0.50",
@@ -146,7 +146,7 @@
     "ai": "^5.0.104",
     "encrypt-storage": "^2.14.7",
     "lit": "^3.0.0",
-    "@graphty/webgpu-graph-algorithms": "^0.6.6"
+    "@graphty/webgpu-graph-algorithms": "^0.6.7"
   },
   "peerDependenciesMeta": {
     "@ai-sdk/anthropic": {
@@ -184,9 +184,9 @@
     "papaparse": "^5.5.3",
     "toposort": "^2.0.2",
     "zod": "^3.25.28",
-    "@graphty/layout": "^1.10.0",
     "@graphty/algorithms": "^2.0.4",
-    "@graphty/graph-format": "^1.0.5"
+    "@graphty/graph-format": "^1.0.5",
+    "@graphty/layout": "^1.10.0"
   },
   "overrides": {
     "storybook": "$storybook"

package/dist/chunks/GraphtyError-B93WRH3e.js

@@ -1,134 +0,0 @@
-const N = {
-  E_BAD_COMMAND: "E_BAD_COMMAND",
-  E_BAD_QUERY: "E_BAD_QUERY",
-  E_BAD_LAYER: "E_BAD_LAYER",
-  E_BAD_SELECTOR: "E_BAD_SELECTOR",
-  E_BAD_FORMULA: "E_BAD_FORMULA",
-  E_SELECTOR_EMPTY: "E_SELECTOR_EMPTY",
-  E_UNSCOPED_RUN_ENCODING: "E_UNSCOPED_RUN_ENCODING",
-  E_UNKNOWN_SCALE: "E_UNKNOWN_SCALE",
-  E_UNKNOWN_CHANNEL: "E_UNKNOWN_CHANNEL",
-  E_UNKNOWN_OPTION: "E_UNKNOWN_OPTION",
-  E_OPTION_RANGE: "E_OPTION_RANGE",
-  E_UNKNOWN_ATTRIBUTE: "E_UNKNOWN_ATTRIBUTE",
-  E_UNKNOWN_ALGORITHM: "E_UNKNOWN_ALGORITHM",
-  E_UNKNOWN_LAYOUT: "E_UNKNOWN_LAYOUT",
-  E_UNKNOWN_FORMAT: "E_UNKNOWN_FORMAT",
-  E_UNKNOWN_PALETTE: "E_UNKNOWN_PALETTE",
-  E_UNKNOWN_CAMERA: "E_UNKNOWN_CAMERA",
-  E_UNKNOWN_SINK: "E_UNKNOWN_SINK",
-  E_UNKNOWN_RUN: "E_UNKNOWN_RUN",
-  E_UNSTABLE_RUN_ID: "E_UNSTABLE_RUN_ID",
-  E_DUPLICATE_ID: "E_DUPLICATE_ID",
-  E_DUPLICATE_EDGE: "E_DUPLICATE_EDGE",
-  E_DUPLICATE_PLUGIN: "E_DUPLICATE_PLUGIN",
-  E_PROTECTED: "E_PROTECTED",
-  E_FETCH_FAILED: "E_FETCH_FAILED",
-  E_PARSE_FAILED: "E_PARSE_FAILED",
-  E_EDGE_ENDPOINTS_UNRESOLVED: "E_EDGE_ENDPOINTS_UNRESOLVED",
-  E_ID_MISSING: "E_ID_MISSING",
-  E_EMPTY_LOAD: "E_EMPTY_LOAD",
-  E_SUPERSEDED: "E_SUPERSEDED",
-  E_TOO_LARGE: "E_TOO_LARGE",
-  E_OUT_OF_MEMORY: "E_OUT_OF_MEMORY",
-  E_CAP_EXCEEDED: "E_CAP_EXCEEDED",
-  E_SCOPE_EMPTY: "E_SCOPE_EMPTY",
-  E_NOT_CONVERGED: "E_NOT_CONVERGED",
-  E_NO_ACCELERATOR: "E_NO_ACCELERATOR",
-  E_NO_WEBGPU: "E_NO_WEBGPU",
-  E_NO_ADAPTER: "E_NO_ADAPTER",
-  E_SOFTWARE_ONLY: "E_SOFTWARE_ONLY",
-  E_DEVICE_INCORRECT: "E_DEVICE_INCORRECT",
-  E_DEVICE_LOST: "E_DEVICE_LOST",
-  E_NO_WEBGL: "E_NO_WEBGL",
-  E_UNSUPPORTED: "E_UNSUPPORTED",
-  E_READONLY: "E_READONLY",
-  E_DISPOSED: "E_DISPOSED",
-  E_INTERNAL: "E_INTERNAL"
-}, U = Object.freeze(Object.values(N)), C = Object.freeze([
-  N.E_NO_WEBGPU,
-  N.E_NO_ADAPTER,
-  N.E_SOFTWARE_ONLY,
-  N.E_DEVICE_INCORRECT,
-  N.E_DEVICE_LOST,
-  N.E_TOO_LARGE
-]);
-function s(_) {
-  return typeof _ == "string" && Object.hasOwn(N, _);
-}
-const o = Object.freeze({});
-function r(_) {
-  if (typeof _ != "object" || _ === null || !("code" in _))
-    return;
-  const { code: E } = _;
-  return s(E) ? E : void 0;
-}
-function R(_) {
-  if (typeof _ != "object" || _ === null || !("code" in _))
-    return;
-  const { code: E } = _;
-  return typeof E == "string" && !s(E) ? E : void 0;
-}
-class e extends Error {
-  /**
-   * Builds an error.
-   * @param init - The code, the message, the failing area and anything else known about the
-   * failure.
-   */
-  constructor(E) {
-    super(E.message, E.cause === void 0 ? void 0 : { cause: E.cause }), this.name = "GraphtyError", Object.setPrototypeOf(this, new.target.prototype), this.code = E.code, this.source = E.source, this.recoverable = E.recoverable ?? !1, this.details = E.details === void 0 ? o : Object.freeze({ ...E.details }), E.target !== void 0 && (this.target = E.target);
-  }
-  /**
-   * Re-reports a failure from somewhere else as a `GraphtyError`.
-   *
-   * A sibling package -- graph-io, graph-format, the WebGPU peer -- throws its own class. The
-   * class does not cross the boundary, so the element carries the code instead: when the
-   * original's `code` is one the element knows, that code wins; when it is a string the
-   * element does not know, it is kept in `details.sourceCode` and the caller's code is used.
-   * A value that is already a `GraphtyError` is returned untouched, so the most specific code
-   * survives.
-   * @param cause - The thrown value being wrapped.
-   * @param init - The code, area and facts to use when the original supplies none.
-   * @returns The error to throw.
-   */
-  static wrap(E, O) {
-    if (E instanceof e)
-      return E;
-    const A = r(E), t = R(E), T = O.message ?? (E instanceof Error ? E.message : String(E)), D = t === void 0 ? O.details : { ...O.details, sourceCode: t };
-    return new e({
-      ...O,
-      code: A ?? O.code,
-      message: T,
-      details: D,
-      cause: E
-    });
-  }
-  /**
-   * Renders the error as plain JSON.
-   *
-   * Called by `JSON.stringify`, and used wherever an error has to survive a boundary a class
-   * cannot cross: a log line, a worker message, a bug report.
-   * @returns The serialisable form.
-   */
-  toJSON() {
-    const E = {
-      name: this.name,
-      code: this.code,
-      message: this.message,
-      source: this.source,
-      recoverable: this.recoverable,
-      details: this.details
-    };
-    return this.target !== void 0 && (E.target = this.target), this.cause instanceof Error && (E.causeMessage = this.cause.message), E;
-  }
-}
-function L(_) {
-  return _ instanceof e;
-}
-export {
-  C as A,
-  e as G,
-  U as a,
-  s as b,
-  L as i
-};