@graphty/graphty-element 2.2.0 → 2.2.2

package/dist/graphty.js

@@ -1,8 +1,8 @@
-import { A as e, a as E, b as r, D as O, E as o, d as S, G as R, e as _, I as t, L, N as C, O as A, R as N, S as n, f as I, g as T, h as g, U as i, i as l } from "./chunks/index-2VIpMJZP.js";
+import { A as e, a as E, b as r, D as O, E as o, d as S, G as R, e as _, I as t, L, N as C, O as A, R as N, S as n, f as I, g as T, h as g, U as i, i as l } from "./chunks/index-DnKqD4ge.js";
 import { a as p, S as G, b as f } from "./chunks/paletteRegistry-NrWOKT-A.js";
 import { D as y, E as D } from "./chunks/DataSource-DEg3igzS.js";
 import { k as P, l as U, g as c, h as m, A as u, C as x, i as B } from "./chunks/Algorithm-RQ629NLb.js";
-import { e as H, E as b, N as Y, a as F, P as W, R as k, S as K, d as v, b as w, c as Q } from "./chunks/NodeStyle-Cup9O1lu.js";
+import { e as H, E as b, N as Y, a as F, P as W, R as k, S as K, d as v, b as w, c as Q } from "./chunks/NodeStyle-DKj7HjMJ.js";
 import { A as j, a as q, G as z, i as J, b as Z } from "./chunks/GraphtyError-BwcnblTH.js";
 import { B as aa, a as sa, b as ea, C as Ea, G as ra, c as Oa, I as oa, O as Sa, d as Ra, e as _a, f as ta, P as La, g as Ca, h as Aa, R as Na, T as na, i as Ia, V as Ta, Y as ga } from "./chunks/sequential-Zym81qm7.js";
 import { a as la, G as da, V as pa, i as Ga } from "./chunks/GraphStyle-D0PXnZKu.js";

package/dist/schema.js

@@ -2,7 +2,7 @@ import { R as N, e as x } from "./chunks/types-B7bX5c0K.js";
 import { M as A, h as y, i as M } from "./chunks/interpolation-DY-PNpqX.js";
 import { B as D, a as U, b as B, C as P, G as H, c as V, I as $, O as w, d as F, e as W, f as Y, P as j, g as k, h as q, R as K, T as v, i as z, V as J, Y as Q } from "./chunks/sequential-Zym81qm7.js";
 import { D as Z, a as tt, G as nt, b as at, V as st, i as et } from "./chunks/GraphStyle-D0PXnZKu.js";
-import { E as rt, N as ct, a as it, R as Ot, d as St, b as Rt, c as lt } from "./chunks/NodeStyle-Cup9O1lu.js";
+import { E as rt, N as ct, a as it, R as Ot, d as St, b as Rt, c as lt } from "./chunks/NodeStyle-DKj7HjMJ.js";
 import { c as ft } from "./chunks/common-DWNKjpH_.js";
 function l(t) {
   const n = /^#?([a-f\d]{2})([a-f\d]{2})([a-f\d]{2})$/i.exec(t);

package/dist/session.js

@@ -1,10 +1,10 @@
 import { R as A, e as R } from "./chunks/types-B7bX5c0K.js";
 import { A as _, a as C, G as g, i as m, b as L } from "./chunks/GraphtyError-BwcnblTH.js";
 import { g as U, h as I, i as N } from "./chunks/Algorithm-RQ629NLb.js";
-import { D as h } from "./chunks/GraphSession-CtqyVNsw.js";
-import { a as y, b as D, c as w, Q as b, R as v, d as G, e as x, S as z, T as F, f as M, i as j, g as H, h as Y, j as k } from "./chunks/GraphSession-CtqyVNsw.js";
+import { D as h } from "./chunks/GraphSession-DDrQWABb.js";
+import { a as y, b as D, c as w, Q as b, R as v, d as G, e as x, S as z, T as F, f as M, i as j, g as H, h as Y, j as k } from "./chunks/GraphSession-DDrQWABb.js";
 import { R as Q, w as X, x as B, y as J, z as K, A as V } from "./chunks/paletteRegistry-NrWOKT-A.js";
-import { a as n } from "./chunks/scales-BUS7NWy2.js";
+import { a as n } from "./chunks/scales-DKsbJE2L.js";
 const u = Object.freeze({
   /** Above this node count the element draws less visual detail. A shipped default, not measured. */
   largeGraphThreshold: 1e4,

package/dist/src/Graph.d.ts

@@ -178,7 +178,7 @@ export declare class Graph implements GraphContext {
      *
      * The settings take effect on the next layout the element runs. `preSteps` is read when a
      * layout starts, so setting it after a graph has already settled changes nothing that is
-     * already on screen.
+     * already on screen. `labels.declutter` is the exception: it takes effect on the next frame.
      * @param behavior - The fields to change. Anything omitted keeps its current value.
      */
     setLayoutBehavior(behavior: GraphBehaviorConfig): void;

package/dist/src/Node.d.ts

@@ -212,9 +212,8 @@ export declare class Node {
      * EFFECTS only on the branch that rebuilds the mesh, so an `instance` channel's edit reached
      * the screen only if some unrelated `mesh` channel happened to change in the same repaint.
      * That is why a glow was drawn when its colour was in the stack before the first frame and
-     * ignored when a layer added it afterwards, and why `node.glowStrength` had been declared a
-     * `mesh` channel: minting a source mesh per strength was the only way to force the rebuild
-     * that made the strength visible.
+     * ignored when a layer added it afterwards. (`node.glowStrength` is a `mesh` channel for a
+     * different reason: a glow's strength is set per SOURCE mesh, like its colour.)
      *
      * So this method is everything the `instance` role promises, and `paintFrom` calls it on BOTH
      * of its branches -- once when it has just rebuilt the mesh, because every one of these lives

package/dist/src/config/EdgeStyle.d.ts

@@ -390,6 +390,10 @@ export declare const EdgeStyle: z.ZodObject<{
          * thousands and the frame rate collapses. Set this to cap it: the elements are then
          * spread evenly over the edge whatever its length or width.
          *
+         * It applies to the discrete patterns only (dot, star, box, dash, diamond, dash-dot).
+         * Zigzag and sinewave are drawn as fixed-length connected segments that always tile the
+         * whole edge, so they ignore it.
+         *
          * This is a USER choice, deliberately. The renderer does not silently impose a ceiling,
          * because that would change how a graph looks to buy performance the caller never asked
          * for -- the same reason an algorithm's style layer never mutes another layer.

package/dist/src/config/GraphBehavior.d.ts

@@ -27,6 +27,9 @@ export declare const GraphBehaviorOpts: z.ZodObject<{
     node: z.ZodPrefault<z.ZodObject<{
         pinOnDrag: z.ZodDefault<z.ZodBoolean>;
     }, z.core.$strict>>;
+    labels: z.ZodPrefault<z.ZodObject<{
+        declutter: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
     fetchNodes: z.ZodOptional<z.ZodCustom<Function, Function>>;
     fetchEdges: z.ZodOptional<z.ZodCustom<Function, Function>>;
 }, z.core.$strict>;

package/dist/src/config/StyleTemplate.d.ts

@@ -928,6 +928,9 @@ declare const StyleTemplateV1: z.ZodObject<{
         node: z.ZodPrefault<z.ZodObject<{
             pinOnDrag: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strict>>;
+        labels: z.ZodPrefault<z.ZodObject<{
+            declutter: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>;
         fetchNodes: z.ZodOptional<z.ZodCustom<Function, Function>>;
         fetchEdges: z.ZodOptional<z.ZodCustom<Function, Function>>;
     }, z.core.$strict>>;
@@ -1861,6 +1864,9 @@ export declare const StyleTemplate: z.ZodDiscriminatedUnion<[z.ZodObject<{
         node: z.ZodPrefault<z.ZodObject<{
             pinOnDrag: z.ZodDefault<z.ZodBoolean>;
         }, z.core.$strict>>;
+        labels: z.ZodPrefault<z.ZodObject<{
+            declutter: z.ZodDefault<z.ZodBoolean>;
+        }, z.core.$strict>>;
         fetchNodes: z.ZodOptional<z.ZodCustom<Function, Function>>;
         fetchEdges: z.ZodOptional<z.ZodCustom<Function, Function>>;
     }, z.core.$strict>>;

package/dist/src/graphty-element.d.ts

@@ -15,6 +15,13 @@ import type { SelectionDelta, SelectionTarget, SetOp } from "./session/selection
  */
 export declare class Graphty extends LitElement {
     #private;
+    /**
+     * The host is a block that fills its parent's width. Its height is the parent's when the
+     * parent has a definite height, the element's own when the page sets one, and otherwise half
+     * its width: `aspect-ratio` only applies while the used height is `auto`, so a bare tag keeps
+     * the 2:1 canvas it always had. Every rule here can be overridden from the page.
+     */
+    static styles: import("lit").CSSResult;
     /**
      * Creates a new Graphty element instance.
      */
@@ -425,13 +432,16 @@ export declare class Graphty extends LitElement {
      * unstepped force layout is a graph in mid-flight, and how far it has flown depends on when
      * the picture was taken. `layout.stepMultiplier`, `layout.minDelta` and
      * `layout.zoomStepInterval` pace the rest of it, and `node.pinOnDrag` decides whether a node
-     * a reader drags stays where they put it.
+     * a reader drags stays where they put it. `labels.declutter` (off by default) hides a node
+     * label whose words would be drawn over another label's, keeping a selected node's label
+     * first and then the label of the node with more edges; it takes effect on the next frame.
      *
      * Merged over what is already set, so naming one field leaves the others alone.
      * @since 2.0.0
      * @example
      * ```typescript
      * element.layoutBehavior = { layout: { preSteps: 1000 } };
+     * element.layoutBehavior = { labels: { declutter: true } };
      * ```
      * @returns The behaviour settings, or undefined when none have been set on this element
      */

package/dist/src/managers/DataManager.d.ts

@@ -67,6 +67,8 @@ export declare class DataManager implements Manager {
      * compiled, answered `undefined` for the edge whose id is `"0"`, and said nothing about it.
      */
     edges: Map<string, Edge>;
+    /** Goes up on every edge added or removed, so a cache over the edge set knows it is stale. */
+    edgeVersion: number;
     nodeCache: Map<NodeIdType, Node>;
     edgeCache: EdgeMap;
     /**

package/dist/src/managers/LabelDeclutter.d.ts

@@ -0,0 +1,97 @@
+import { type Camera, type Scene } from "@babylonjs/core";
+import type { Node } from "../Node";
+import type { GraphContext } from "./GraphContext";
+/**
+ * Hides node labels that would be drawn on top of each other, when the graph's behaviour
+ * configuration asks for it (`labels.declutter`, off by default).
+ *
+ * Every node label is its own billboarded plane, so two labelled nodes that land near each other
+ * on screen draw their words over one another. The pass projects each drawn label's WORDS -- not
+ * its padded plane -- to a screen rectangle, orders the labels by priority -- a selected node
+ * first, then the node with more edges, then the node id so the answer is stable -- and keeps a
+ * label only if its rectangle meets no label already kept. Kept rectangles are bucketed in a
+ * screen grid, so each label is tested against its neighbours rather than against every label.
+ *
+ * THE PASS RUNS ONLY WHEN SOMETHING THAT DECIDES PLACEMENT CHANGED: the camera's view or
+ * projection, the viewport size, a label added, rebuilt or removed, a node moved, shown, hidden
+ * or (de)selected, an edge added or removed, or the setting itself. A still scene costs one cheap
+ * walk over the labelled nodes per frame and no projection at all.
+ *
+ * A label that loses is hidden with `isVisible`, never with `setEnabled` and never through a
+ * style. `setEnabled` is the visibility mask's switch (`Node.applyRenderState`), and a style is
+ * the reader's answer to what a node looks like; this is a placement decision, so it has its own
+ * switch. Turning the setting off shows every label again.
+ *
+ * ONE PER SCENE, created by the first node that draws a label, and kept on `scene.metadata`
+ * the way `NodeEffects` keeps the glow layer.
+ */
+export declare class LabelDeclutter {
+    private readonly scene;
+    private readonly context;
+    /** How many full passes have run. Read by tests to prove a still scene is not re-measured. */
+    passes: number;
+    private readonly observer;
+    private readonly entries;
+    /** Reused every pass: the candidates in priority order. */
+    private readonly order;
+    /** Reused every pass: kept labels by grid cell. Emptied, not rebuilt. */
+    private readonly grid;
+    private columns;
+    private rows;
+    private dirty;
+    private wasOn;
+    private camera;
+    private readonly view;
+    private readonly projection;
+    private width;
+    private height;
+    private edgeVersion;
+    private degrees;
+    private readonly transform;
+    private readonly toPixels;
+    private readonly worldToPixels;
+    private readonly viewport;
+    private readonly right;
+    private readonly up;
+    private readonly centre;
+    private readonly corner;
+    private readonly centreOnScreen;
+    private readonly cornerOnScreen;
+    private constructor();
+    /**
+     * Make sure the scene has a declutter pass, and add a node that is drawing a label to it.
+     * @param scene - The scene the labels are drawn in.
+     * @param context - The graph: its configuration says whether to declutter, its edges give
+     *     the degree order.
+     * @param node - The node drawing a label.
+     */
+    static track(scene: Scene, context: GraphContext, node: Node): void;
+    /** Stop running before frames. */
+    dispose(): void;
+    /** Before every frame: decide whether placement could have changed, and if so, place. */
+    run(): void;
+    /**
+     * One full pass: decide which labels are drawn.
+     * @param camera - The camera the frame is drawn from.
+     */
+    place(camera: Camera): void;
+    /**
+     * Whether anything that decides placement differs from what the last pass saw.
+     * @param camera - The camera the frame is drawn from.
+     * @returns True when the labels have to be placed again.
+     */
+    private changed;
+    /**
+     * Record what this pass sees of one node, and drop it if its label is gone.
+     * @param entry - The node.
+     * @returns Its label plane, or null when it has none.
+     */
+    private observe;
+    private remember;
+    private isClear;
+    private keep;
+    /** The setting was turned off: every label is drawn again. */
+    private showAll;
+    /** How many edges each node has, counted again only when an edge is added or removed. */
+    private refreshDegrees;
+}

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

@@ -114,14 +114,38 @@ export declare class NodeEffects {
      * material. Unfreezing to set `emissiveColor` would make every glowing style pay a material
      * re-bind per frame and would change the node's lit appearance as a side effect.
      *
-     * KNOWN LIMIT, stated rather than hidden: `intensity` is a property of the LAYER, not of a
-     * mesh, so with two glowing styles on screen the last one applied sets the strength for both.
-     * Colour is per style (see {@link NodeEffects.resolveRenderedMesh}). Per-style strength needs
-     * one layer per strength, which costs a full-screen pass each and was not worth it here.
+     * STRENGTH IS PER SOURCE MESH, like colour, through {@link NodeEffects.syncGlowStrengths}.
+     * It used to be written to `glowLayer.intensity`, which belongs to the one layer the scene
+     * shares, so the last glowing style applied set the strength of every glowing node.
      * @param mesh - The mesh to apply the effect to
      * @param effect - The effect configuration from the node style
      */
     static applyGlowEffect(mesh: AbstractMesh, effect: NodeStyleConfig["effect"] | undefined): void;
+    /**
+     * The glow strength each glowing source mesh asked for, kept on scene.metadata beside the
+     * glow colours.
+     * @param scene - The Babylon.js scene
+     * @returns The per-source-mesh strengths
+     */
+    private static glowStrengths;
+    /**
+     * Draw every glowing source mesh at its own strength, with one layer.
+     *
+     * Babylon multiplies a per-mesh `setEffectIntensity` into the glow colour as the glow map is
+     * drawn, and the layer's `intensity` scales the blurred result. The glow map is an 8-bit
+     * texture, so a per-mesh factor above 1 clamps and a strength of 3 would read the same as 1.
+     * So the layer carries the LARGEST strength on screen and each mesh carries its share of it,
+     * which is never above 1.
+     *
+     * Only source meshes that still draw a node count toward the largest strength. MeshCache
+     * never evicts a source mesh, so a strength that is no longer used (a slider dragged from 100
+     * back to 0.1) leaves a mesh with no instances behind; counted, it would hold the layer at 100
+     * and round the live glow away in the 8-bit map. It keeps its entry, because a node that goes
+     * back to that strength reuses the cached mesh. A disposed mesh is dropped.
+     * @param glowLayer - The scene's glow layer
+     * @param scene - The Babylon.js scene
+     */
+    private static syncGlowStrengths;
     /**
      * Remove a mesh from the highlight layer.
      *
@@ -149,7 +173,7 @@ export declare class NodeEffects {
      */
     static disposeHighlightLayer(scene: Scene): void;
     /**
-     * Dispose the glow layer for a scene, and forget the per-style colours with it.
+     * Dispose the glow layer for a scene, and forget the per-style colours and strengths with it.
      *
      * The colour map is keyed by mesh uniqueId, so it MUST die with the layer: leaving it behind
      * would let a later mesh that happens to reuse a uniqueId inherit a dead style's glow colour.

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

@@ -42,6 +42,8 @@ export declare class RichTextLabel {
     private parsedContent;
     private actualDimensions;
     private contentArea;
+    /** The size of the words alone, in the same units as `actualDimensions`. */
+    private textSize;
     private totalBorderWidth;
     private pointerInfo;
     private _progressValue;
@@ -112,6 +114,21 @@ export declare class RichTextLabel {
      * @returns The Babylon.js mesh or null if not created
      */
     get labelMesh(): Mesh | null;
+    /**
+     * Where the words sit on the label's plane, without its margins, padding, borders or pointer.
+     *
+     * Each edge is a fraction of the plane: `left`/`right` across it from its left edge, and
+     * `top`/`bottom` down it from its top edge, so a label whose words fill it reads
+     * `{ left: 0, right: 1, top: 0, bottom: 1 }`. Two labels whose planes overlap only in their
+     * padding do not draw over each other's words; this is what tells them apart.
+     * @returns The words' rectangle as fractions of the plane.
+     */
+    get textBounds(): {
+        left: number;
+        right: number;
+        top: number;
+        bottom: number;
+    };
     /**
      * Gets the label's unique identifier
      * @returns The label ID

package/dist/src/session/styles/channels.d.ts

@@ -21,13 +21,12 @@
  *   compile error rather than a silent no-op.
  * - `edge.curvature` is a switch, not an amount. The edge renderer offsets its control points by
  *   a fixed fraction of the edge length, so "curve this edge" is the only thing it can be told.
- * - `node.glowStrength` is drawn, but Babylon keeps a glow's intensity on the LAYER rather than
- *   on a mesh, so two glowing styles on screen share whichever strength was applied last.
  * - `node.outline` is a colour and no width, for the same reason in the same shape: the stroke
  *   is drawn by a highlight LAYER whose blur size belongs to the layer, so every outline on
  *   screen is one width. This is the sentence the element's natural-language layer reads out
  *   when someone asks for an outline width, so it answers with a reason rather than a refusal.
- * - `edge.patternCount` counts the elements of a PATTERNED line. A solid line has none to count.
+ * - `edge.patternCount` counts the elements of a PATTERNED line. A solid line has none to count,
+ *   and zigzag and sinewave ignore it because they always tile the whole edge.
  * - The four arrow caption channels draw words at ONE END of an edge, hanging from the cap
  *   there. An end with no cap carries no caption, and the words are what switch one on.
  * - The two node tooltip channels draw on HOVER and only on hover, so a graph at rest carries

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@graphty/graphty-element",
-  "version": "2.2.0",
+  "version": "2.2.2",
   "description": "A Web Component library for 3D/2D graph visualization built with Lit and Babylon.js",
   "type": "module",
   "customElements": "./dist/custom-elements.json",
@@ -133,8 +133,8 @@
     "vite-plugin-eslint": "^1.8.1",
     "vitepress": "^1.6.3",
     "vitest": "^3.2.4",
-    "@graphty/remote-logger": "^1.3.6",
-    "@graphty/webgpu-graph-algorithms": "^0.6.3"
+    "@graphty/webgpu-graph-algorithms": "^0.6.4",
+    "@graphty/remote-logger": "^1.3.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.3"
+    "@graphty/webgpu-graph-algorithms": "^0.6.4"
   },
   "peerDependenciesMeta": {
     "@ai-sdk/anthropic": {
@@ -184,9 +184,9 @@
     "papaparse": "^5.5.3",
     "toposort": "^2.0.2",
     "zod": "^3.25.28",
-    "@graphty/algorithms": "^2.0.2",
-    "@graphty/graph-format": "^1.0.4",
-    "@graphty/layout": "^1.9.0"
+    "@graphty/algorithms": "^2.0.3",
+    "@graphty/graph-format": "^1.0.5",
+    "@graphty/layout": "^1.9.1"
   },
   "overrides": {
     "storybook": "$storybook"