nnet-svg 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David Kirkby
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# nnet-svg
+
+[![CI](https://github.com/dkirkby/nnet-svg/actions/workflows/ci.yml/badge.svg)](https://github.com/dkirkby/nnet-svg/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/nnet-svg)](https://www.npmjs.com/package/nnet-svg)
+
+Render a dense feed-forward neural network as a static, accessible, inspectable SVG.
+
+- **Framework-independent**: returns a native `SVGSVGElement`; works in vanilla JS,
+  Observable notebooks, or wrapped by React/Vue/etc.
+- **Automatic layout**: spacing, node radii, and stroke widths derived from the
+  viewBox; large layers truncate around an ellipsis glyph.
+- **Data-driven styling**: attach numeric values to nodes/edges once, then style,
+  label, and tooltip them through callbacks.
+- **Deterministic and testable**: predictable classes and `data-*` attributes,
+  and a pure layout API with no DOM dependency.
+
+## Install
+
+```sh
+npm install nnet-svg
+```
+
+## Quick start
+
+```js
+import { createDenseNetworkSvg } from "nnet-svg";
+
+const svg = createDenseNetworkSvg({
+  layers: [4, 16, 8, 2],
+  maxDisplayedNodes: 8,
+});
+document.body.append(svg);
+```
+
+### Observable
+
+In a classic notebook cell, import from a CDN:
+
+```js
+nn = import("https://esm.sh/nnet-svg@0.1")
+```
+
+```js
+nn.createDenseNetworkSvg({ layers: [4, 16, 8, 2], maxDisplayedNodes: 8 })
+```
+
+In Observable Framework or Notebook Kit:
+
+```js
+import { createDenseNetworkSvg } from "npm:nnet-svg";
+```
+
+### Plain HTML
+
+```html
+<script type="importmap">
+  { "imports": { "nnet-svg": "https://esm.sh/nnet-svg@0.1" } }
+</script>
+<script type="module">
+  import { createDenseNetworkSvg } from "nnet-svg";
+  document.body.append(createDenseNetworkSvg({ layers: [3, 8, 4, 1] }));
+</script>
+```
+
+## API
+
+### `createDenseNetworkSvg(options): SVGSVGElement`
+
+Creates and returns a new SVG element displaying the network. The primary API.
+
+### `renderDenseNetworkSvg(container, options): SVGSVGElement`
+
+Convenience helper: creates the SVG, replaces `container`'s contents with it,
+and returns it.
+
+### `layoutDenseNetwork(options): DenseNetworkLayout`
+
+**Advanced.** Computes node/ellipsis placement and edge geometry without
+creating any DOM — useful for testing, debugging, or alternative renderers.
+Accepts the same options object as the SVG APIs (rendering-only options are
+ignored) and returns `{ viewBox, orientation, items, edges, nodeRadius,
+ellipsisDotRadius, nodeStrokeWidth, edgeLabelPos }`, where `items` mixes
+`kind: "node"` and `kind: "ellipsis"` entries in drawing order.
+
+## Options
+
+### Network and layout
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `layers` | `number[]` | required | Layer sizes, e.g. `[3, 8, 4, 1]`; at least 2 positive integers. |
+| `maxDisplayedNodes` | `number` | `12` | Even integer ≥ 2. Larger layers are truncated around a central ellipsis; displayed nodes keep their true indices. |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Layer flow direction. |
+| `viewBox` | `{ width, height }` | `640×360` (horizontal), `360×640` (vertical) | Internal coordinate system for layout, radii, and font sizes. |
+| `nodeSpread` | `number` | `0` | Node-stack spacing shape, ≥ −1. `-1` pins outer nodes to the padded axis ends; `+1` makes edge insets equal inter-node gaps. |
+| `layerSpread` | `number` | `0` | Same, for layer placement. |
+| `nodeRadius` | `number` | ⅛ of smallest node gap | Node circle radius. |
+| `ellipsisDotRadius` | `number` | `nodeRadius / 4` | Radius of the three ellipsis dots. |
+| `nodeStrokeWidth` | `number` | `max(nodeRadius / 8, 0.75)` | Node circle stroke width; `0` disables the stroke. |
+| `edgeLabelPos` | `number` | `0.4` | Fractional position of edge labels along the edge from source (0) to target (1). `0.5` is the exact midpoint, where symmetric labels can overlap. |
+
+### Rendering
+
+| Option | Type | Default | Description |
+| --- | --- | --- | --- |
+| `responsive` | `boolean` | `true` | Scale to container width (`width="100%"`, no fixed height). When `false`, fixed pixel `width`/`height` from the viewBox. |
+| `classPrefix` | `string` | `"dn"` | Prefix for generated CSS classes (`dn-root`, `dn-node`, `dn-edge`, …). |
+| `idPrefix` | `string` | generated | Prefix for the title/desc ids. **If you provide it, you are responsible for uniqueness within the page.** |
+| `strict` | `boolean` | `false` | When `true`, callback errors and invalid callback results throw; otherwise they log to `console.error` and rendering continues. |
+| `title` | `string` | — | Accessible top-level SVG `<title>`. |
+| `desc` | `string` | generated summary | Accessible top-level SVG `<desc>`. |
+| `svgAttrs` | `object` | — | Extra attributes merged onto the root `<svg>`. `class` is appended to the generated class; `viewBox` is **ignored** (it is controlled by `options.viewBox` only). |
+
+### Callbacks
+
+All callbacks receive semantic datum objects with **true original node indices**
+(never display-slot indices or coordinates). Returning `null`/`undefined` means
+"nothing" everywhere.
+
+| Option | Signature | Purpose |
+| --- | --- | --- |
+| `nodeValue` / `edgeValue` | `(ref) => number \| null \| undefined` | Attach a numeric value. Called **exactly once** per visible node/edge; results are cached and exposed as `datum.value` to all callbacks below. `NaN` and `±Infinity` are preserved; non-numbers are logged and ignored (throw when `strict`). |
+| `nodeAttrs` / `edgeAttrs` | `(datum) => attrs` | SVG attributes merged over the defaults (callback wins; `class` is appended). |
+| `nodeLabel` / `edgeLabel` | `(datum) => string \| number \| null` | Visible label text, converted with `String(...)`. Node labels center in the circle; edge labels sit at `edgeLabelPos` along the edge. |
+| `nodeLabelAttrs` / `edgeLabelAttrs` | `(datum) => attrs` | Attributes for the label `<text>` elements (only called when a label rendered). |
+| `nodeTitle` / `edgeTitle` | `(datum) => string \| null` | Native browser tooltip via a `<title>` child. |
+
+### Example
+
+```js
+const svg = createDenseNetworkSvg({
+  layers: [3, 16, 8, 2],
+  maxDisplayedNodes: 6,
+  title: "Dense neural network",
+  nodeValue: (node) => activations[node.layerIndex]?.[node.nodeIndex],
+  nodeLabel: (node) => (node.value === undefined ? null : node.value.toFixed(2)),
+  nodeAttrs: (node) =>
+    node.value === undefined ? null : { fill: node.value > 0 ? "white" : "#eee" },
+  edgeValue: (edge) =>
+    weights[edge.sourceLayerIndex]?.[edge.sourceNodeIndex]?.[edge.targetNodeIndex],
+  edgeAttrs: (edge) =>
+    edge.value === undefined
+      ? null
+      : { "stroke-width": Math.min(4, 1 + Math.abs(edge.value)) },
+});
+```
+
+## Generated structure
+
+The SVG is grouped in drawing order — edges, then nodes/ellipses, then labels —
+so nodes always sit above edges and labels above both:
+
+```html
+<svg class="dn-root" role="img" aria-labelledby="…">
+  <title>…</title>   <!-- when the title option is given -->
+  <desc>…</desc>     <!-- always: user-provided or generated -->
+  <g class="dn-edges">…</g>
+  <g class="dn-items">…</g>
+  <g class="dn-labels">…</g>
+</svg>
+```
+
+Every element carries deterministic `data-*` attributes with true indices
+(`data-layer-index`, `data-node-index`, `data-edge-index`,
+`data-omitted-count`, …) for inspection, testing, and post-processing. CSS
+classes are secondary metadata; styling is intended to flow through the attr
+callbacks.
+
+## Development
+
+```sh
+npm install
+npm test           # vitest (layout unit tests + jsdom DOM tests)
+npm run typecheck  # tsc --noEmit
+npm run build      # emits ESM + .d.ts to dist/
+npm run demo       # then open http://localhost:3000/demo/ (build first)
+```
+
+See [DESIGN_SPEC.md](DESIGN_SPEC.md) for the full specification and
+[RELEASING.md](RELEASING.md) for the release process.
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export { layoutDenseNetwork } from "./layout.js";
+export { createDenseNetworkSvg, renderDenseNetworkSvg } from "./renderSvg.js";

package/dist/index.js

@@ -0,0 +1,3 @@
+export * from "./types.js";
+export { layoutDenseNetwork } from "./layout.js";
+export { createDenseNetworkSvg, renderDenseNetworkSvg } from "./renderSvg.js";

package/dist/layout.d.ts

@@ -0,0 +1,8 @@
+import type { DenseNetworkLayout, DenseNetworkLayoutOptions } from "./types.js";
+export declare const DEFAULT_MAX_DISPLAYED_NODES = 12;
+/**
+ * Computes node/ellipsis placement and edge geometry without creating any
+ * DOM elements. Accepts the full SVG options object; rendering-only options
+ * are ignored (spec §3.3).
+ */
+export declare function layoutDenseNetwork(options: DenseNetworkLayoutOptions): DenseNetworkLayout;

package/dist/layout.js

@@ -0,0 +1,150 @@
+// Layout computation (DESIGN_SPEC.md §8, §9, §12).
+// This module must stay pure: no DOM access and no d3 imports.
+import { validateLayoutOptions } from "./validate.js";
+export const DEFAULT_MAX_DISPLAYED_NODES = 12;
+// Minimum default node stroke width in viewBox units, so strokes stay
+// visible for small nodes (spec §8).
+const MIN_NODE_STROKE_WIDTH = 0.75;
+// Default fractional edge label position (spec §16): slightly off the
+// midpoint, where symmetric edge labels would overlap.
+const DEFAULT_EDGE_LABEL_POS = 0.4;
+const DEFAULT_VIEWBOX = {
+    horizontal: { width: 640, height: 360 },
+    vertical: { width: 360, height: 640 },
+};
+/**
+ * Positions of `count` points along an axis of length `axisLength` (spec §8):
+ * gap = L/(N+spread), inset = (1+spread)/(N+spread) * (L/2), so that
+ * 2*inset + (N-1)*gap = L. A single point is centered without evaluating
+ * the gap formula (avoids division by zero when spread is -1).
+ *
+ * A non-zero `margin` pads both axis ends, computing positions over the
+ * reduced length `axisLength - 2*margin` and shifting them by `margin`.
+ */
+function axisPositions(count, axisLength, spread, margin) {
+    if (count === 1)
+        return [axisLength / 2];
+    const usableLength = axisLength - 2 * margin;
+    const gap = usableLength / (count + spread);
+    const inset = margin + ((1 + spread) / (count + spread)) * (usableLength / 2);
+    return Array.from({ length: count }, (_, index) => inset + index * gap);
+}
+/**
+ * Visible slots for a layer of `size` nodes (spec §9). Layers larger than
+ * maxDisplayedNodes get maxDisplayedNodes+1 slots with the central slot
+ * replaced by an ellipsis; displayed nodes keep their true indices.
+ */
+function layerSlots(size, maxDisplayedNodes) {
+    if (size <= maxDisplayedNodes) {
+        return Array.from({ length: size }, (_, nodeIndex) => ({
+            kind: "node",
+            nodeIndex,
+        }));
+    }
+    const half = maxDisplayedNodes / 2;
+    const slots = [];
+    for (let nodeIndex = 0; nodeIndex < half; nodeIndex++) {
+        slots.push({ kind: "node", nodeIndex });
+    }
+    slots.push({ kind: "ellipsis", omittedCount: size - maxDisplayedNodes });
+    for (let nodeIndex = size - half; nodeIndex < size; nodeIndex++) {
+        slots.push({ kind: "node", nodeIndex });
+    }
+    return slots;
+}
+/**
+ * Computes node/ellipsis placement and edge geometry without creating any
+ * DOM elements. Accepts the full SVG options object; rendering-only options
+ * are ignored (spec §3.3).
+ */
+export function layoutDenseNetwork(options) {
+    validateLayoutOptions(options);
+    const orientation = options.orientation ?? "horizontal";
+    const viewBox = options.viewBox ?? DEFAULT_VIEWBOX[orientation];
+    const maxDisplayedNodes = options.maxDisplayedNodes ?? DEFAULT_MAX_DISPLAYED_NODES;
+    const nodeSpread = options.nodeSpread ?? 0;
+    const layerSpread = options.layerSpread ?? 0;
+    const horizontal = orientation === "horizontal";
+    const layerAxisLength = horizontal ? viewBox.width : viewBox.height;
+    const nodeAxisLength = horizontal ? viewBox.height : viewBox.width;
+    const slotsPerLayer = options.layers.map((size) => layerSlots(size, maxDisplayedNodes));
+    // Default radius: 1/8 of the smallest displayed inter-node gap; if every
+    // layer displays a single node there is no gap, so fall back to L/25.
+    // Gaps are measured on the unpadded axis: the spread margin below depends
+    // on nodeRadius, so the radius must be resolved first (spec §8).
+    let smallestNodeGap = Infinity;
+    for (const slots of slotsPerLayer) {
+        if (slots.length > 1) {
+            smallestNodeGap = Math.min(smallestNodeGap, nodeAxisLength / (slots.length + nodeSpread));
+        }
+    }
+    const nodeRadius = options.nodeRadius ??
+        (Number.isFinite(smallestNodeGap) ? smallestNodeGap / 8 : nodeAxisLength / 25);
+    const ellipsisDotRadius = options.ellipsisDotRadius ?? nodeRadius / 4;
+    const nodeStrokeWidth = options.nodeStrokeWidth ?? Math.max(nodeRadius / 8, MIN_NODE_STROKE_WIDTH);
+    const edgeLabelPos = options.edgeLabelPos ?? DEFAULT_EDGE_LABEL_POS;
+    // A spread of -1 pins outer positions to the axis ends, which would clip
+    // node circles at the viewBox boundary; pad that axis by the drawn node
+    // extent, radius plus half the (edge-centered) stroke (spec §8).
+    const margin = nodeRadius + nodeStrokeWidth / 2;
+    const layerMargin = layerSpread === -1 ? margin : 0;
+    const nodeMargin = nodeSpread === -1 ? margin : 0;
+    const layerPositions = axisPositions(options.layers.length, layerAxisLength, layerSpread, layerMargin);
+    const items = [];
+    // Displayed real nodes per layer, in visible order, for edge generation.
+    const displayedNodes = [];
+    slotsPerLayer.forEach((slots, layerIndex) => {
+        const nodePositions = axisPositions(slots.length, nodeAxisLength, nodeSpread, nodeMargin);
+        const layerNodes = [];
+        slots.forEach((slot, visibleIndex) => {
+            const layerPosition = layerPositions[layerIndex];
+            const nodePosition = nodePositions[visibleIndex];
+            const x = horizontal ? layerPosition : nodePosition;
+            const y = horizontal ? nodePosition : layerPosition;
+            if (slot.kind === "node") {
+                items.push({ kind: "node", layerIndex, nodeIndex: slot.nodeIndex, visibleIndex, x, y });
+                layerNodes.push({ nodeIndex: slot.nodeIndex, x, y });
+            }
+            else {
+                items.push({
+                    kind: "ellipsis",
+                    layerIndex,
+                    visibleIndex,
+                    omittedCount: slot.omittedCount,
+                    x,
+                    y,
+                });
+            }
+        });
+        displayedNodes.push(layerNodes);
+    });
+    const edges = [];
+    let edgeIndex = 0;
+    for (let layerIndex = 0; layerIndex + 1 < displayedNodes.length; layerIndex++) {
+        for (const source of displayedNodes[layerIndex]) {
+            for (const target of displayedNodes[layerIndex + 1]) {
+                edges.push({
+                    sourceLayerIndex: layerIndex,
+                    sourceNodeIndex: source.nodeIndex,
+                    targetLayerIndex: layerIndex + 1,
+                    targetNodeIndex: target.nodeIndex,
+                    edgeIndex: edgeIndex++,
+                    x1: source.x,
+                    y1: source.y,
+                    x2: target.x,
+                    y2: target.y,
+                });
+            }
+        }
+    }
+    return {
+        viewBox: { width: viewBox.width, height: viewBox.height },
+        orientation,
+        items,
+        edges,
+        nodeRadius,
+        ellipsisDotRadius,
+        nodeStrokeWidth,
+        edgeLabelPos,
+    };
+}

package/dist/renderSvg.d.ts

@@ -0,0 +1,11 @@
+import type { DenseNetworkSvgOptions } from "./types.js";
+/**
+ * Creates and returns a new `SVGSVGElement` displaying the network.
+ * This is the primary public API (spec §3.1).
+ */
+export declare function createDenseNetworkSvg(options: DenseNetworkSvgOptions): SVGSVGElement;
+/**
+ * Creates an SVG with {@link createDenseNetworkSvg}, replaces the container
+ * contents with it, and returns the SVG (spec §3.2).
+ */
+export declare function renderDenseNetworkSvg(container: Element, options: DenseNetworkSvgOptions): SVGSVGElement;

package/dist/renderSvg.js

@@ -0,0 +1,313 @@
+// SVG rendering (DESIGN_SPEC.md §3, §7, §10–§17, §19, §21–§24).
+import { create } from "d3-selection";
+import { DEFAULT_MAX_DISPLAYED_NODES, layoutDenseNetwork } from "./layout.js";
+import { validateSvgOptions } from "./validate.js";
+// Default styling (spec §15): neutral and legible, overridable per element.
+// The node stroke-width is resolved by the layout (spec §8), not fixed here.
+const NODE_DEFAULT_ATTRS = {
+    fill: "white",
+    stroke: "currentColor",
+};
+const EDGE_DEFAULT_ATTRS = {
+    stroke: "currentColor",
+    "stroke-opacity": 0.25,
+    "stroke-width": 1,
+};
+const ELLIPSIS_DOT_DEFAULT_ATTRS = {
+    fill: "currentColor",
+};
+const LABEL_DEFAULT_ATTRS = {
+    fill: "currentColor",
+    "font-size": 10,
+    "text-anchor": "middle",
+    "dominant-baseline": "middle",
+    "pointer-events": "none",
+};
+// Dot offsets from the slot center in units of the dot radius, so the glyph
+// spans roughly one node diameter (spec §10 fixes only the central dot).
+const ELLIPSIS_DOT_OFFSETS = [-3, 0, 3];
+/**
+ * Merges override attributes onto defaults (spec §15/§23): overrides win,
+ * except `class`, where the override is appended to the generated class.
+ */
+function mergeAttrs(defaults, overrides) {
+    const merged = { ...defaults, ...overrides };
+    if (defaults.class != null) {
+        merged.class =
+            overrides?.class != null ? `${defaults.class} ${overrides.class}` : defaults.class;
+    }
+    return merged;
+}
+/** Applies attributes to a selection, skipping null/undefined values. */
+function setAttrs(selection, attrs) {
+    for (const [name, value] of Object.entries(attrs)) {
+        if (value !== null && value !== undefined) {
+            selection.attr(name, String(value));
+        }
+    }
+}
+/**
+ * Wraps user callbacks (spec §24): in strict mode exceptions propagate;
+ * otherwise they are logged via console.error and treated as no result.
+ * Calling with an undefined callback is a no-op returning undefined.
+ */
+function makeSafeCall(strict) {
+    return function safeCall(name, callback, arg) {
+        if (!callback)
+            return undefined;
+        try {
+            return callback(arg);
+        }
+        catch (error) {
+            if (strict)
+                throw error;
+            console.error(`nnet-svg: ${name} callback threw; treating its result as absent.`, error);
+            return undefined;
+        }
+    };
+}
+/** Applies the value rules of spec §14 to a raw nodeValue/edgeValue result. */
+function coerceValue(name, raw, strict) {
+    if (raw === null || raw === undefined)
+        return undefined;
+    if (typeof raw === "number")
+        return raw; // NaN and ±Infinity are preserved
+    const message = `nnet-svg: ${name} must return a number, null, or undefined; received ${typeof raw}`;
+    if (strict)
+        throw new Error(message);
+    console.error(message);
+    return undefined;
+}
+const nodeKey = (layerIndex, nodeIndex) => `${layerIndex}:${nodeIndex}`;
+// Generated id prefixes (spec §20): unique per call so multiple independent
+// networks can coexist on one page; the random suffix guards against other
+// copies of this module keeping their own counters.
+let idCounter = 0;
+function generateIdPrefix() {
+    idCounter += 1;
+    return `dn-${idCounter.toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+/** Default accessible description summarizing the network (spec §18). */
+function defaultDescription(layers, orientation, maxDisplayedNodes, truncated) {
+    let text = `Dense neural network with ${layers.length} layers of sizes ${layers.join(", ")}, ` +
+        `drawn in ${orientation} orientation.`;
+    if (truncated) {
+        text += ` Layers with more than ${maxDisplayedNodes} nodes are truncated around a central ellipsis.`;
+    }
+    return text;
+}
+/**
+ * Creates and returns a new `SVGSVGElement` displaying the network.
+ * This is the primary public API (spec §3.1).
+ */
+export function createDenseNetworkSvg(options) {
+    validateSvgOptions(options);
+    const layout = layoutDenseNetwork(options);
+    const strict = options.strict ?? false;
+    const safeCall = makeSafeCall(strict);
+    const classPrefix = options.classPrefix ?? "dn";
+    const cls = (name) => `${classPrefix}-${name}`;
+    const responsive = options.responsive ?? true;
+    const { width, height } = layout.viewBox;
+    const horizontal = layout.orientation === "horizontal";
+    const nodeItems = layout.items.filter((item) => item.kind === "node");
+    // ---- Value pass (spec §14): nodeValue/edgeValue run exactly once per
+    // visible node/edge; results are cached and reused by all later callbacks.
+    const nodeValues = new Map();
+    if (options.nodeValue) {
+        for (const item of nodeItems) {
+            const ref = {
+                kind: "node",
+                layerIndex: item.layerIndex,
+                nodeIndex: item.nodeIndex,
+            };
+            const value = coerceValue("nodeValue", safeCall("nodeValue", options.nodeValue, ref), strict);
+            if (value !== undefined)
+                nodeValues.set(nodeKey(item.layerIndex, item.nodeIndex), value);
+        }
+    }
+    const edgeValues = new Map();
+    if (options.edgeValue) {
+        for (const edge of layout.edges) {
+            const ref = {
+                kind: "edge",
+                sourceLayerIndex: edge.sourceLayerIndex,
+                sourceNodeIndex: edge.sourceNodeIndex,
+                targetLayerIndex: edge.targetLayerIndex,
+                targetNodeIndex: edge.targetNodeIndex,
+                edgeIndex: edge.edgeIndex,
+            };
+            const value = coerceValue("edgeValue", safeCall("edgeValue", options.edgeValue, ref), strict);
+            if (value !== undefined)
+                edgeValues.set(edge.edgeIndex, value);
+        }
+    }
+    // Semantic datum objects passed to styling/label/title callbacks (spec §13):
+    // true indices plus the cached value, never layout geometry.
+    const nodeDatums = new Map();
+    for (const item of nodeItems) {
+        const datum = {
+            kind: "node",
+            layerIndex: item.layerIndex,
+            nodeIndex: item.nodeIndex,
+        };
+        const value = nodeValues.get(nodeKey(item.layerIndex, item.nodeIndex));
+        if (value !== undefined)
+            datum.value = value;
+        nodeDatums.set(nodeKey(item.layerIndex, item.nodeIndex), datum);
+    }
+    const edgeDatums = layout.edges.map((edge) => {
+        const datum = {
+            kind: "edge",
+            sourceLayerIndex: edge.sourceLayerIndex,
+            sourceNodeIndex: edge.sourceNodeIndex,
+            targetLayerIndex: edge.targetLayerIndex,
+            targetNodeIndex: edge.targetNodeIndex,
+            edgeIndex: edge.edgeIndex,
+        };
+        const value = edgeValues.get(edge.edgeIndex);
+        if (value !== undefined)
+            datum.value = value;
+        return datum;
+    });
+    const datumOfEdge = (edge) => edgeDatums[edge.edgeIndex];
+    const datumOfNode = (item) => nodeDatums.get(nodeKey(item.layerIndex, item.nodeIndex));
+    // ---- Accessibility metadata (spec §18) and generated ids (spec §20).
+    // The description always exists (user-provided or generated); the title
+    // only when the option is given. aria-labelledby lists whichever exist.
+    const idPrefix = options.idPrefix ?? generateIdPrefix();
+    const titleId = options.title === undefined ? undefined : `${idPrefix}-title`;
+    const descId = `${idPrefix}-desc`;
+    const truncated = layout.items.some((item) => item.kind === "ellipsis");
+    const desc = options.desc ??
+        defaultDescription(options.layers, layout.orientation, options.maxDisplayedNodes ?? DEFAULT_MAX_DISPLAYED_NODES, truncated);
+    // ---- Root <svg> (spec §7.2, §23): defaults and accessibility attrs, then
+    // responsive attrs, then user svgAttrs. svgAttrs.viewBox is ignored: the
+    // viewBox is controlled exclusively by options.viewBox.
+    const { viewBox: _unsupported, ...userSvgAttrs } = options.svgAttrs ?? {};
+    const responsiveAttrs = responsive
+        ? { width: "100%", style: "max-width: 100%; height: auto;" }
+        : { width, height };
+    const rootAttrs = mergeAttrs({
+        xmlns: "http://www.w3.org/2000/svg",
+        viewBox: `0 0 ${width} ${height}`,
+        preserveAspectRatio: "xMidYMid meet",
+        class: cls("root"),
+        role: "img",
+        "aria-labelledby": titleId === undefined ? descId : `${titleId} ${descId}`,
+        ...responsiveAttrs,
+    }, userSvgAttrs);
+    const svg = create("svg");
+    setAttrs(svg, rootAttrs);
+    if (titleId !== undefined) {
+        svg.append("title").attr("id", titleId).text(options.title ?? "");
+    }
+    svg.append("desc").attr("id", descId).text(desc);
+    // Drawing order (spec §22): edges behind nodes/ellipses, labels on top.
+    const edgesGroup = svg.append("g").attr("class", cls("edges"));
+    const itemsGroup = svg.append("g").attr("class", cls("items"));
+    const labelsGroup = svg.append("g").attr("class", cls("labels"));
+    // ---- Edges (spec §11, §21.3).
+    for (const edge of layout.edges) {
+        const datum = datumOfEdge(edge);
+        const line = edgesGroup
+            .append("line")
+            .attr("data-kind", "edge")
+            .attr("data-source-layer-index", edge.sourceLayerIndex)
+            .attr("data-source-node-index", edge.sourceNodeIndex)
+            .attr("data-target-layer-index", edge.targetLayerIndex)
+            .attr("data-target-node-index", edge.targetNodeIndex)
+            .attr("data-edge-index", edge.edgeIndex)
+            .attr("x1", edge.x1)
+            .attr("y1", edge.y1)
+            .attr("x2", edge.x2)
+            .attr("y2", edge.y2);
+        const userAttrs = safeCall("edgeAttrs", options.edgeAttrs, datum);
+        setAttrs(line, mergeAttrs({ ...EDGE_DEFAULT_ATTRS, class: cls("edge") }, userAttrs));
+        const title = safeCall("edgeTitle", options.edgeTitle, datum);
+        if (title !== null && title !== undefined)
+            line.append("title").text(String(title));
+    }
+    // ---- Nodes and ellipsis glyphs (spec §10, §21.1, §21.2).
+    for (const item of layout.items) {
+        if (item.kind === "node") {
+            const datum = datumOfNode(item);
+            const circle = itemsGroup
+                .append("circle")
+                .attr("data-kind", "node")
+                .attr("data-layer-index", item.layerIndex)
+                .attr("data-node-index", item.nodeIndex)
+                .attr("cx", item.x)
+                .attr("cy", item.y)
+                .attr("r", layout.nodeRadius);
+            const userAttrs = safeCall("nodeAttrs", options.nodeAttrs, datum);
+            setAttrs(circle, mergeAttrs({
+                ...NODE_DEFAULT_ATTRS,
+                "stroke-width": layout.nodeStrokeWidth,
+                class: cls("node"),
+            }, userAttrs));
+            const title = safeCall("nodeTitle", options.nodeTitle, datum);
+            if (title !== null && title !== undefined)
+                circle.append("title").text(String(title));
+        }
+        else {
+            const glyph = itemsGroup
+                .append("g")
+                .attr("class", cls("ellipsis"))
+                .attr("data-kind", "ellipsis")
+                .attr("data-layer-index", item.layerIndex)
+                .attr("data-omitted-count", item.omittedCount);
+            // Dots stack along the node-stack direction (spec §10): vertically for
+            // horizontal networks, horizontally for vertical networks.
+            for (const step of ELLIPSIS_DOT_OFFSETS) {
+                const offset = step * layout.ellipsisDotRadius;
+                const dot = glyph
+                    .append("circle")
+                    .attr("cx", horizontal ? item.x : item.x + offset)
+                    .attr("cy", horizontal ? item.y + offset : item.y)
+                    .attr("r", layout.ellipsisDotRadius);
+                setAttrs(dot, { ...ELLIPSIS_DOT_DEFAULT_ATTRS, class: cls("ellipsis-dot") });
+            }
+        }
+    }
+    // ---- Labels (spec §16): positioned by the renderer, drawn above all
+    // other elements. Label attr callbacks run only when a label is rendered.
+    for (const edge of layout.edges) {
+        const datum = datumOfEdge(edge);
+        const raw = safeCall("edgeLabel", options.edgeLabel, datum);
+        if (raw === null || raw === undefined)
+            continue;
+        const text = labelsGroup.append("text").attr("data-edge-index", edge.edgeIndex);
+        const userAttrs = safeCall("edgeLabelAttrs", options.edgeLabelAttrs, datum);
+        setAttrs(text, mergeAttrs({
+            ...LABEL_DEFAULT_ATTRS,
+            x: edge.x1 + (edge.x2 - edge.x1) * layout.edgeLabelPos,
+            y: edge.y1 + (edge.y2 - edge.y1) * layout.edgeLabelPos,
+            class: cls("edge-label"),
+        }, userAttrs));
+        text.text(String(raw));
+    }
+    for (const item of nodeItems) {
+        const datum = datumOfNode(item);
+        const raw = safeCall("nodeLabel", options.nodeLabel, datum);
+        if (raw === null || raw === undefined)
+            continue;
+        const text = labelsGroup
+            .append("text")
+            .attr("data-layer-index", item.layerIndex)
+            .attr("data-node-index", item.nodeIndex);
+        const userAttrs = safeCall("nodeLabelAttrs", options.nodeLabelAttrs, datum);
+        setAttrs(text, mergeAttrs({ ...LABEL_DEFAULT_ATTRS, x: item.x, y: item.y, class: cls("node-label") }, userAttrs));
+        text.text(String(raw));
+    }
+    return svg.node();
+}
+/**
+ * Creates an SVG with {@link createDenseNetworkSvg}, replaces the container
+ * contents with it, and returns the SVG (spec §3.2).
+ */
+export function renderDenseNetworkSvg(container, options) {
+    const svg = createDenseNetworkSvg(options);
+    container.replaceChildren(svg);
+    return svg;
+}

package/dist/types.d.ts

@@ -0,0 +1,164 @@
+export type Orientation = "horizontal" | "vertical";
+/** Internal SVG coordinate system used for layout, radii and font sizes. */
+export type ViewBox = {
+    width: number;
+    height: number;
+};
+/**
+ * SVG attributes as a plain object, e.g. `{ fill: "red", "stroke-width": 2 }`.
+ * `null` and `undefined` values remove/skip the attribute.
+ */
+export type SvgAttrs = Record<string, string | number | boolean | null | undefined>;
+/** Options accepted by {@link layoutDenseNetwork} (and included in the SVG options). */
+export type DenseNetworkLayoutOptions = {
+    /** Layer sizes, e.g. `[3, 8, 4, 1]`. Required; at least 2 positive integers. */
+    layers: number[];
+    /**
+     * Layers larger than this are truncated around a central ellipsis.
+     * Must be an even integer >= 2. Default: 12.
+     */
+    maxDisplayedNodes?: number;
+    /** Direction of layer flow. Default: "horizontal" (left to right). */
+    orientation?: Orientation;
+    /**
+     * Internal coordinate system. Defaults: 640x360 (horizontal), 360x640 (vertical).
+     */
+    viewBox?: ViewBox;
+    /**
+     * Controls edge insets of the node stack within a layer. Finite number >= -1;
+     * -1 pins outer nodes to the edges, +1 makes edge insets equal inter-node gaps.
+     * Default: 0.
+     */
+    nodeSpread?: number;
+    /** Same as {@link DenseNetworkLayoutOptions.nodeSpread}, for layer placement. Default: 0. */
+    layerSpread?: number;
+    /** Node circle radius. Default: 1/8 of the smallest inter-node gap. */
+    nodeRadius?: number;
+    /** Radius of the three ellipsis dots. Default: nodeRadius / 4. */
+    ellipsisDotRadius?: number;
+    /** Node circle stroke width. Default: nodeRadius / 8, minimum 0.75. */
+    nodeStrokeWidth?: number;
+    /**
+     * Fractional position of edge labels along their edge, measured from the
+     * source node (0 = source, 1 = target). Default: 0.4, slightly off the
+     * midpoint where symmetric edge labels would overlap.
+     */
+    edgeLabelPos?: number;
+};
+/** Reference to a real node, using true original indices. */
+export type NodeRef = {
+    kind: "node";
+    layerIndex: number;
+    nodeIndex: number;
+};
+/** Reference to an edge, using true original node indices. */
+export type EdgeRef = {
+    kind: "edge";
+    sourceLayerIndex: number;
+    sourceNodeIndex: number;
+    targetLayerIndex: number;
+    targetNodeIndex: number;
+    /** Global index across all edges in the network. */
+    edgeIndex: number;
+};
+/** Datum passed to node styling/label/title callbacks. */
+export type NodeDatum = NodeRef & {
+    /** Cached result of the `nodeValue` callback, if it produced a number. */
+    value?: number;
+};
+/** Datum passed to edge styling/label/title callbacks. */
+export type EdgeDatum = EdgeRef & {
+    /** Cached result of the `edgeValue` callback, if it produced a number. */
+    value?: number;
+};
+/** Options accepted by {@link createDenseNetworkSvg} and {@link renderDenseNetworkSvg}. */
+export type DenseNetworkSvgOptions = DenseNetworkLayoutOptions & {
+    /**
+     * When true (the default), the SVG scales to its container width;
+     * when false, it gets fixed width/height attributes from the viewBox.
+     */
+    responsive?: boolean;
+    /** Prefix for generated CSS classes. Default: "dn". */
+    classPrefix?: string;
+    /**
+     * Prefix for generated SVG ids (title/desc). Generated uniquely if omitted;
+     * if provided, the caller is responsible for uniqueness within the page.
+     */
+    idPrefix?: string;
+    /**
+     * When true, callback errors and invalid callback results throw;
+     * when false (the default), they are logged via console.error and ignored.
+     */
+    strict?: boolean;
+    /** Accessible title; rendered as a top-level SVG <title>. */
+    title?: string;
+    /** Accessible description; a summary is generated if omitted. */
+    desc?: string;
+    /** Extra attributes merged onto the root <svg> (viewBox cannot be overridden). */
+    svgAttrs?: SvgAttrs;
+    nodeValue?: (node: NodeRef) => number | null | undefined;
+    edgeValue?: (edge: EdgeRef) => number | null | undefined;
+    nodeAttrs?: (node: NodeDatum) => SvgAttrs | null | undefined;
+    edgeAttrs?: (edge: EdgeDatum) => SvgAttrs | null | undefined;
+    nodeLabel?: (node: NodeDatum) => string | number | null | undefined;
+    edgeLabel?: (edge: EdgeDatum) => string | number | null | undefined;
+    nodeLabelAttrs?: (node: NodeDatum) => SvgAttrs | null | undefined;
+    edgeLabelAttrs?: (edge: EdgeDatum) => SvgAttrs | null | undefined;
+    nodeTitle?: (node: NodeDatum) => string | null | undefined;
+    edgeTitle?: (edge: EdgeDatum) => string | null | undefined;
+};
+/** A displayed real node with its resolved position. */
+export type LayoutNodeItem = {
+    kind: "node";
+    layerIndex: number;
+    /** True index in the original layer. */
+    nodeIndex: number;
+    /** Slot index within the visible layer. */
+    visibleIndex: number;
+    x: number;
+    y: number;
+};
+/** An ellipsis glyph standing in for omitted nodes in a truncated layer. */
+export type LayoutEllipsisItem = {
+    kind: "ellipsis";
+    layerIndex: number;
+    /** Slot index within the visible layer. */
+    visibleIndex: number;
+    /** Number of real nodes hidden by this ellipsis. */
+    omittedCount: number;
+    x: number;
+    y: number;
+};
+export type LayoutItem = LayoutNodeItem | LayoutEllipsisItem;
+/** A straight edge between two displayed real nodes in adjacent layers. */
+export type LayoutEdge = {
+    sourceLayerIndex: number;
+    /** True source node index. */
+    sourceNodeIndex: number;
+    targetLayerIndex: number;
+    /** True target node index. */
+    targetNodeIndex: number;
+    /** Global index across all edges in the network. */
+    edgeIndex: number;
+    x1: number;
+    y1: number;
+    x2: number;
+    y2: number;
+};
+/** Result of {@link layoutDenseNetwork}: resolved geometry without any DOM. */
+export type DenseNetworkLayout = {
+    viewBox: ViewBox;
+    orientation: Orientation;
+    /** Ordered by layer index, then visible slot position within the layer. */
+    items: LayoutItem[];
+    /** Ordered by layer pair, then source visible order, then target visible order. */
+    edges: LayoutEdge[];
+    /** Resolved node circle radius (default or from options). */
+    nodeRadius: number;
+    /** Resolved ellipsis dot radius (default or from options). */
+    ellipsisDotRadius: number;
+    /** Resolved node circle stroke width (default or from options). */
+    nodeStrokeWidth: number;
+    /** Resolved fractional edge label position (default or from options). */
+    edgeLabelPos: number;
+};

package/dist/types.js

@@ -0,0 +1,2 @@
+// Public type definitions (DESIGN_SPEC.md §12, §13, §25).
+export {};

package/dist/validate.d.ts

@@ -0,0 +1,8 @@
+import type { DenseNetworkLayoutOptions, DenseNetworkSvgOptions } from "./types.js";
+/**
+ * Validates the layout-level options (spec §5). Rendering-only options such as
+ * callbacks, labels and `responsive` are ignored here (spec §3.3).
+ */
+export declare function validateLayoutOptions(options: DenseNetworkLayoutOptions): void;
+/** Validates the full SVG options: layout rules plus rendering-only rules (spec §5). */
+export declare function validateSvgOptions(options: DenseNetworkSvgOptions): void;

package/dist/validate.js

@@ -0,0 +1,108 @@
+// Input validation (DESIGN_SPEC.md §5).
+// Top-level invalid inputs always throw descriptive errors, regardless of `strict`.
+function fail(message) {
+    throw new Error(`nnet-svg: ${message}`);
+}
+function show(value) {
+    if (typeof value === "string")
+        return JSON.stringify(value);
+    if (Array.isArray(value))
+        return `[${value.map(show).join(", ")}]`;
+    if (typeof value === "function")
+        return "a function";
+    if (typeof value === "object" && value !== null) {
+        try {
+            return JSON.stringify(value) ?? String(value);
+        }
+        catch {
+            return String(value);
+        }
+    }
+    // Covers numbers (incl. NaN/Infinity), booleans, null, undefined, symbols, bigints.
+    return String(value);
+}
+/**
+ * Validates the layout-level options (spec §5). Rendering-only options such as
+ * callbacks, labels and `responsive` are ignored here (spec §3.3).
+ */
+export function validateLayoutOptions(options) {
+    if (typeof options !== "object" || options === null) {
+        fail(`options must be an object; received ${show(options)}`);
+    }
+    const { layers, maxDisplayedNodes, orientation, viewBox, nodeSpread, layerSpread, nodeRadius, ellipsisDotRadius, nodeStrokeWidth, edgeLabelPos, } = options;
+    if (layers === undefined) {
+        fail("layers is required");
+    }
+    if (!Array.isArray(layers)) {
+        fail(`layers must be an array of positive integers; received ${show(layers)}`);
+    }
+    if (layers.length < 2) {
+        fail(`layers must contain at least 2 layer sizes; received ${layers.length}`);
+    }
+    layers.forEach((size, index) => {
+        if (typeof size !== "number" || !Number.isInteger(size) || size < 1) {
+            fail(`every layer size must be a positive integer; layers[${index}] is ${show(size)}`);
+        }
+    });
+    if (maxDisplayedNodes !== undefined &&
+        (typeof maxDisplayedNodes !== "number" ||
+            !Number.isInteger(maxDisplayedNodes) ||
+            maxDisplayedNodes < 2 ||
+            maxDisplayedNodes % 2 !== 0)) {
+        fail(`maxDisplayedNodes must be an even integer >= 2; received ${show(maxDisplayedNodes)}`);
+    }
+    if (orientation !== undefined && orientation !== "horizontal" && orientation !== "vertical") {
+        fail(`orientation must be "horizontal" or "vertical"; received ${show(orientation)}`);
+    }
+    if (viewBox !== undefined) {
+        if (typeof viewBox !== "object" || viewBox === null) {
+            fail(`viewBox must be an object with width and height; received ${show(viewBox)}`);
+        }
+        for (const dimension of ["width", "height"]) {
+            const value = viewBox[dimension];
+            if (typeof value !== "number" || !Number.isFinite(value) || value <= 0) {
+                fail(`viewBox.${dimension} must be a positive finite number; received ${show(value)}`);
+            }
+        }
+    }
+    for (const [name, value] of [
+        ["nodeSpread", nodeSpread],
+        ["layerSpread", layerSpread],
+    ]) {
+        if (value !== undefined &&
+            (typeof value !== "number" || !Number.isFinite(value) || value < -1)) {
+            fail(`${name} must be a finite number >= -1; received ${show(value)}`);
+        }
+    }
+    for (const [name, value] of [
+        ["nodeRadius", nodeRadius],
+        ["ellipsisDotRadius", ellipsisDotRadius],
+    ]) {
+        if (value !== undefined &&
+            (typeof value !== "number" || !Number.isFinite(value) || value <= 0)) {
+            fail(`${name} must be a positive finite number; received ${show(value)}`);
+        }
+    }
+    // Zero is allowed: it means no visible stroke.
+    if (nodeStrokeWidth !== undefined &&
+        (typeof nodeStrokeWidth !== "number" || !Number.isFinite(nodeStrokeWidth) || nodeStrokeWidth < 0)) {
+        fail(`nodeStrokeWidth must be a non-negative finite number; received ${show(nodeStrokeWidth)}`);
+    }
+    if (edgeLabelPos !== undefined &&
+        (typeof edgeLabelPos !== "number" ||
+            !Number.isFinite(edgeLabelPos) ||
+            edgeLabelPos < 0 ||
+            edgeLabelPos > 1)) {
+        fail(`edgeLabelPos must be a number between 0 and 1; received ${show(edgeLabelPos)}`);
+    }
+}
+/** Validates the full SVG options: layout rules plus rendering-only rules (spec §5). */
+export function validateSvgOptions(options) {
+    validateLayoutOptions(options);
+    for (const name of ["responsive", "strict"]) {
+        const value = options[name];
+        if (value !== undefined && typeof value !== "boolean") {
+            fail(`${name} must be a boolean; received ${show(value)}`);
+        }
+    }
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "nnet-svg",
+  "version": "0.1.0",
+  "description": "Render a dense feed-forward neural network as a static SVG",
+  "keywords": [
+    "neural-network",
+    "svg",
+    "visualization",
+    "d3",
+    "observable"
+  ],
+  "homepage": "https://github.com/dkirkby/nnet-svg#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dkirkby/nnet-svg.git"
+  },
+  "bugs": {
+    "url": "https://github.com/dkirkby/nnet-svg/issues"
+  },
+  "license": "MIT",
+  "author": "David Kirkby <dkirkby@uci.edu>",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "demo": "npx -y serve .",
+    "prepublishOnly": "npm run test && npm run build"
+  },
+  "dependencies": {
+    "d3-selection": "^3.0.0"
+  },
+  "devDependencies": {
+    "@types/d3-selection": "^3.0.11",
+    "jsdom": "^29.1.1",
+    "typescript": "^7.0.2",
+    "vitest": "^4.1.10"
+  }
+}