forwardfig 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kenichiro Goto
+
+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

@@ -1,3 +1,163 @@
-# Temporary Holding Version
+# forwardfig
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Draw ML architecture figures in TypeScript, written the way you write the model. It has zero dependencies, is about 19 KB gzipped, and outputs SVG (it also works in Node).
+
+Docs: https://frinfo702.github.io/forwardfig/docs/
+
+Demo (paper figure gallery and playground): https://frinfo702.github.io/forwardfig/demo/
+
+```ts
+import { Figure, Module, Tensor, mha, norm, ffn, text } from 'forwardfig'
+
+class EncoderLayer extends Module {        // like nn.Module
+  attn = mha()
+  n1 = norm()
+  ff = ffn()
+  n2 = norm()
+  forward(x: Tensor) {
+    const h = this.n1(this.attn(x), x)     // Add & Norm with a residual
+    return this.n2(this.ff(h), h)
+  }
+}
+
+const fig = new Figure({ flow: 'BT' })      // drawing side, like matplotlib
+const y = new EncoderLayer({ repeat: 'N×' }).freeze()(fig.input('$\\mathbf{x}$'))
+text('$\\mathbf{h}$')(y)
+fig.mount('#figure')                        // or fig.svg() for a string
+```
+
+## Model
+
+| | Role | Analogy |
+|---|---|---|
+| `Layer` | One block (one node). Calling it as `layer(x, y)` draws edges into it and returns a Tensor. Calling the same layer again adds edges to the same node, so shared weights stay one block. | `nn.Linear` / `keras.layers.Dense` |
+| `Module` | A subclass that implements `forward()`. Instances are callable. Pass `label` / `repeat` / `box` to draw a group box. `repeatSide: 'auto' \| 'top' \| 'bottom' \| 'left' \| 'right'` sets where `repeat` (e.g. ×N) goes. `auto` (the default) picks the first spot that doesn't collide with blocks, edges, labels or other groups. | `nn.Module` |
+| `Tensor` | The value flowing between blocks. `x.edge('$r$')` and `x.edge({ dashed: true })` style the next edge it enters. | KerasTensor |
+| `Figure` | The drawing side: `input()` (a label, or a layer plus extra options), `edge()` (edges outside forward), `rank()`, `svg()` / `mount()`. | `plt.figure` |
+
+There are two ways to write a figure. Use whichever suits the figure, or mix them.
+
+- **All in the figure**: `figure(fig => { ... })` or `figure({ flow: 'LR' }, fig => { ... })` builds everything in one place.
+- **By module**: define each `Module` alongside your model code, then call them in the figure.
+
+```ts
+// functional style
+const fig = new Figure({ flow: 'BT' })
+const x = fig.input('$\\mathbf{x}$')
+const W = block('Pretrained $W$').freeze()               // 🧊
+const A = thin('$A$').trainable(), B = thin('$B$').trainable()   // 🔥
+add(W(x), B(A(x).edge('$r$')))
+```
+
+## Layers
+
+All layers take `(label?, options?)` or `(options?)`; `image(src, …)` and `vector(values, …)` take their data first.
+
+- Basic: `block` `thin` `text` `circle` `op('+' | '*' | '~')` `enc` `dec` `tensor({ size: [w,h,d] })` `stack({ n, size, offset })` `neurons({ n })` `vector(values, label?, options?)`
+- ML presets: `mha` `attention` `ffn` `mlp` `norm` `embed` `linear` `softmax` `matmul` `concat` `conv` `pool` `act` `dropout` `loss`
+- Functional: `add(...xs)` (⊕) and `mul(...xs)` (⊗) create a new node on each call.
+- Grids: `matrix({ rows, cols, cells, cellSize })` (2D) and `voxels({ rows, cols, depth, cells, cellSize })` (3D, the front, top and right faces as cells). `cells` is a 2D array or `(r, c) => cell` (`(r, c, d) => cell` for voxels, with d = 0 in front). A cell is a number in 0–1 (a shade of the block's colour), a colour string, or `{ value | color, texture, label, crossed }`. When `cells` is omitted, varied shades are used. Textures inside cells use the lightweight vector looks. `axes: { rows, cols, depth }` names the extent along each axis (TeX works). `cols` goes under the bottom edge, `rows` to the left and `depth` beside the receding edge; any that would sit on an arrow are moved off its line.
+- Magnify: `magnify({ patch: [col, row] | region: [x, y, w, h], lens: 'circle' | 'square' })(img)`. Enlarges part of the image it's called on with a magnifying glass (`circle`, the default) or an inset (`square`). `patch` is one cell of the source's `grid`, and `region` is a range given as 0–1 fractions. It draws the range's outline and zoom lines instead of an arrow, and the enlarged part can feed the next block (e.g. Linear Projection). The lens shows the source range cropped by default; `src` (URL, `<img>`, `<canvas>`, with `fit`) puts any other image in it, such as a high-resolution crop.
+- 3D:
+  - `gaussian({ peaks: [[x, y, amp?, sigma?]], mesh })`: a Gaussian or mixture surface.
+  - `space({ points: [[x, y, z, class?]], axes: { x, y, z } })`: a 3D scatter on axis panes.
+  - `sphere({ points })`: points on a hypersphere.
+  - `pointcloud({ points: [[x, y, z, class?]], shape: 'torus' | 'sphere' | 'cube', n })`: a point cloud. Closer points are drawn larger and darker. When `points` is omitted, they're sampled from `shape`.
+- Signals: `waveform({ samples })`. `samples` takes raw audio in [-1, 1] (`number[]` or `Float32Array`). Long signals are reduced to at most 256 min/max columns, so the SVG stays light. When omitted, a synthetic speech-like waveform is drawn.
+- Images: `image(src, label?, { size, fit: 'cover' | 'contain', grid, n, tilt, rotate })`. `src` can be a URL, a data URL, an `<img>` or a `<canvas>`. Passing an array (`image([t0, t1, t2])`) draws a stack of frames, each its own image, with the first one in front. `grid` draws a ViT-style patch grid, and `n` draws a batch of frames. `tilt` (degrees) turns the image around its vertical axis and draws it obliquely; a positive value sends the right edge back (up), a negative one the left; combined with `n`, it reads as a video volume. `rotate` (degrees) rotates it in-plane. The layout uses the transformed frame's bounding box.
+
+Common options: `color` `texture` `frozen` `trainable` `crossed` `dashed` `bold` `w` `h` `ghost` `caption` `id`
+
+- `color`: a palette name (`pink orange yellow green blue purple teal red gray white`) or `#hex`. If it's omitted, the block is a neutral grey that reads on both light and dark pages.
+- `crossed: true` dims the block and lays a red ✕ over it, for removed or ablated parts. On an edge it puts a ✕ in the middle, for a cut connection.
+- `texture` sets a block's surface. Set it on a module to style its group box.
+
+  | texture | Look | Example use |
+  |---|---|---|
+  | `ice` | Clear ice (WebGL) | Frozen weights. This is what `freeze()` gives |
+  | `magma` | Cracked magma (WebGL) | Trainable weights. This is what `trainable()` gives |
+  | `glass` | Frosted glass that keeps the block's colour (WebGL) | Soft prompts, adapters |
+  | `metal` | Brushed metal (WebGL) | Fixed ops, hardware |
+  | `noise` | Gaussian grain (WebGL) | Noise injection, diffusion |
+  | `quantized` | A 4-level mosaic of the block's colour (SVG) | Low-bit weights |
+  | `sparse` | A dot grid with gaps (SVG) | Pruning, sparsity |
+  | `hatch` | Diagonal lines (SVG) | Masked, stop-gradient |
+
+  When both are set, `texture` decides the surface, and the ❄/🔥 badge follows `freeze()` / `trainable()` (for example `block({ texture: 'quantized' }).freeze()` in QLoRA). Without WebGL, glass, metal and noise fall back to lightweight vector versions.
+
+- `new Figure({ legend: true })` adds a key under the figure for the looks it uses (❄ frozen, 🔥 trainable, each texture, ✕ crossed). `legend: { position: 'right', labels: { quantized: '4-bit' } }` moves it beside the figure and renames entries.
+- Placement is automatic by default. To override it, use `lane` (fractions allowed), `align: ref`, `leftOf` / `rightOf` / `above` / `below: ref` (with `dist`), `at: [x, y]` or `nudge: [dx, dy]`.
+- `freeze()` / `trainable()` can be called on a layer or on a module. On a module they apply to every block inside it, unless a layer is marked explicitly.
+- A 🧊 or 🔥 in a label works the same way.
+
+Edges (`x.edge({...})` / `fig.edge(a, b, {...})`): `label` `crossed` `join: 'side'` (comes down the source's line and turns into the target's side, an L; for conditioning taps. It doesn't affect column assignment) `dashed` `arrow: 'end' | 'both' | 'none'` `thick` `dense` (fully connected between `neurons`) `skip` `curve` `side` (where a detour runs: `left` / `right` in TB / BT, `top` / `bottom` in LR / RL) `color`
+
+Labels: a newline (`\n`) starts a new line, and `$...$` is TeX.
+
+- **When the page loads MathJax 3**, math is typeset by it automatically. It's embedded in the SVG as paths drawn with real TeX metrics and glyphs. Use `tex-svg-full.js`, because the other builds load some extensions asynchronously.
+
+  ```html
+  <script>window.MathJax = { startup: { typeset: false }, svg: { fontCache: 'local' } }</script>
+  <script defer src="https://cdn.jsdelivr.net/npm/mathjax@3.2.2/es5/tex-svg-full.js"></script>
+  <script type="module">await MathJax.startup.promise; /* draw figures */</script>
+  ```
+
+- **In Node, or with any other engine**, pass a function that returns an `<svg viewBox>` (1000 units per em) via `configure({ tex: src => ... })`. With `mathjax-full`, `tex: t => adaptor.outerHTML(html.convert(t, { display: false }))` works.
+- **Without MathJax**, a built-in lightweight engine handles it. It covers `^ _ \mathbf \mathrm \text \boldsymbol \mathcal \mathbb`, Greek letters, common symbols, `\hat \tilde \bar \vec` and `\frac` (rendered as a/b), with TeX-like spacing. Force it with `configure({ tex: null })`.
+
+## Custom presets
+
+The built-in presets (`mha`, `norm` and so on) are just a shape plus a default label and colour. You can define your own the same way.
+
+```ts
+const rmsnorm = preset('thin', 'RMSNorm', 'yellow')
+const moe = preset('block', 'MoE', { color: 'orange', ghost: 3, kind: 'moe' })
+rmsnorm()(x)                       // default label and colour
+rmsnorm('Pre-Norm', { color: 'blue' })(x)  // override them
+```
+
+`kind` is the key that `kinds` (below) matches on. It defaults to the shape name.
+
+## Style config
+
+Like matplotlib's rcParams, you can set defaults globally and narrow them down by scope. A narrower scope always wins, so a value applies unless a lower level sets its own.
+
+```ts
+configure({ style: { fontSize: 14 }, kinds: { mha: { color: 'purple' } } })  // whole library
+new Figure({ style: { color: 'gray', fontFamily: 'Times New Roman, serif' } }) // this figure
+new Encoder({ style: { fontSize: 11, texture: 'glass' } })                  // blocks made inside this module
+block('x', { fontSize: 20 })                                                // the block itself wins
+configure(null)                                                             // reset
+```
+
+- Precedence, strongest first: the block's own options > inner Module > outer Module > Figure > `configure()` > the preset's defaults.
+- At each level, `kinds[kind]` (for one preset) beats `style` (for all blocks).
+- `style` can set `color` `texture` `fontSize` `fontFamily` `dashed` `bold`. At the Figure / `configure` level, `fontSize` also sizes edge labels, group titles and captions, and `fontFamily` (any CSS font family) sets the font of the whole figure, e.g. to match a paper's body text. Math (`$...$`) keeps its TeX font.
+- A `texture` set through style doesn't override `freeze()` / `trainable()` (ice and magma win). A texture set on the block itself does.
+- `configure` also takes `theme` `flow` `gap` `materials` `legend`.
+
+## Export
+
+```ts
+await fig.download('figure.png')                 // the format follows the extension: .svg .png .jpg/.jpeg .webp
+await fig.download('figure.png', { scale: 3 })   // raster resolution
+const blob = await fig.toBlob({ format: 'webp', quality: 0.9, background: '#fff', theme: 'dark' })
+fig.svg()                                        // string (works in Node too)
+```
+
+- Raster formats (png / jpeg / webp) need a browser (canvas). External image URLs inside are inlined as data URLs before export. JPEG gets a white background by default.
+- PDF isn't supported. For papers, an SVG export (vector) can go into LaTeX via Inkscape or `svg2pdf`.
+
+From the command line (e.g. in a Makefile), `npx forwardfig model.ts -o fig.svg` writes the module's default export (a `Figure`, or a function returning one). The format follows the extension: `.svg`, or `.png` / `.jpg` / `.jpeg` / `.webp`, which need the optional peer dependency `sharp` (`npm i -D sharp`) and take `--scale` (default 2) and `--background`. Without a default export, each exported `Figure` becomes `<name>.svg` in the `-o` directory. `--theme dark` picks the theme. `.ts` files need Node ≥ 22.6 (`NODE_OPTIONS=--experimental-strip-types` before 23.6) or Bun.
+
+## Drawing core
+
+The layout and rendering engine is independent of the API above. `fig.diagram()` returns plain `Diagram` data (nodes, edges, groups, ranks), which `draw(diagram, { theme })` turns into SVG. Anything that can generate a Diagram, from another language or as JSON, can reuse the same engine.
+
+- Layout: a grid of ranks (longest path) and lanes (a block inherits its first input's lane), so chains are always straight. Edges against the flow (e.g. a column that goes back up, aligned with `fig.rank`) are drawn straight, as an L or as a Z when the path is clear. A block whose only inputs come against the flow inherits the lane of the block it feeds. Edges are orthogonal: straight, one Z bend, or a detour. When several arrows enter one block, the one that goes dead straight never moves, and on a small ⊕ the others join from the side.
+- Materials: 🧊 / 🔥 run the WebGL shaders from [portfolio](https://github.com/frinfo702/portfolio) once per block size and embed the result as an image. Without WebGL it falls back to a vector look, and `new Figure({ materials: false })` forces that fallback.
+- Text is measured with canvas `measureText` (cached). Without a DOM, a width-table approximation is used.
+
+To develop locally: run `bun install && bun test && bun run build`, then `python3 -m http.server` and open `demo/`. `bun run docs:dev` builds the docs in `doc/` and serves them at http://localhost:4321. Pushing to `main` deploys the demo to GitHub Pages.
+
+Known limits: crossings are reduced by reordering lanes, not minimized (a greedy pass that stops at a local minimum, and never moves a `lane` you set). TeX is a subset.

package/dist/api.d.ts

@@ -0,0 +1,410 @@
+import { type TexEngine } from './tex';
+import type { Diagram, Dir, Group } from './types';
+type V2 = [number, number];
+export type Ref = Tensor | Layer<any>;
+/**
+ * Surface of a block. ice / magma are what freeze() / trainable() give; the rest are
+ * for whatever a figure wants to call out:
+ * glass (soft prompts, adapters), metal (fixed ops, hardware), noise (noise
+ * injection, diffusion), quantized (low-bit weights), sparse (pruned), hatch (masked).
+ */
+export type Texture = 'ice' | 'magma' | 'glass' | 'metal' | 'noise' | 'quantized' | 'sparse' | 'hatch';
+export interface NodeOptions {
+    id?: string;
+    /** palette name (pink orange yellow green blue purple teal red gray white) or #hex */
+    color?: string;
+    /** 🧊 frozen weights (ice) */
+    frozen?: boolean;
+    /** 🔥 trainable weights (magma) */
+    trainable?: boolean;
+    /** surface texture; wins over frozen / trainable */
+    texture?: Texture;
+    dashed?: boolean;
+    bold?: boolean;
+    /** a ✕ over the block: removed, ablated, dropped */
+    crossed?: boolean;
+    w?: number;
+    h?: number;
+    /** stacked copies behind the block, e.g. heads of multi-head attention */
+    ghost?: number;
+    /** small text under the block */
+    caption?: string;
+    /** cross-axis column; fractions sit between columns */
+    lane?: number;
+    /** same column as another block */
+    align?: Ref;
+    leftOf?: Ref;
+    rightOf?: Ref;
+    above?: Ref;
+    below?: Ref;
+    /** gap for leftOf/rightOf/above/below (px) */
+    dist?: number;
+    /** absolute position (px) */
+    at?: V2;
+    /** shift after layout (px) */
+    nudge?: V2;
+}
+export interface TensorOptions extends NodeOptions {
+    size?: [w: number, h: number, depth: number];
+}
+export interface StackOptions extends NodeOptions {
+    n?: number;
+    size?: V2;
+    offset?: number;
+}
+export interface NeuronOptions extends NodeOptions {
+    n?: number;
+}
+export interface ImageOptions extends NodeOptions {
+    size?: V2;
+    fit?: 'cover' | 'contain';
+    /** overlay a g×g patch grid (ViT) */
+    grid?: number;
+    /** draw a batch of n frames */
+    n?: number;
+    /** degrees: turn the image around its vertical axis, drawn obliquely; positive sends the right edge back (up), negative the left */
+    tilt?: number;
+    /** degrees: rotate in-plane */
+    rotate?: number;
+}
+export interface MagnifyOptions extends NodeOptions {
+    /** region of the input image to enlarge: [x, y, w, h] as fractions of its frame */
+    region?: [number, number, number, number];
+    /** or one cell of the input image's patch grid: [column, row] */
+    patch?: [number, number];
+    /** 'circle' (default): a magnifying glass; 'square': an inset */
+    lens?: 'circle' | 'square';
+    /** what the lens shows; default: the region cropped from the input image */
+    src?: ImageSource;
+    fit?: 'cover' | 'contain';
+    size?: V2;
+}
+/**
+ * One cell of a matrix / voxels block: a number in [0, 1] is a shade of the block's
+ * color, a string is any color, an object can also set texture, label and crossed.
+ */
+export type Cell = number | string | {
+    value?: number;
+    color?: string;
+    texture?: Texture;
+    label?: string;
+    crossed?: boolean;
+};
+export interface MatrixOptions extends NodeOptions {
+    rows?: number;
+    cols?: number;
+    /** per cell, as rows of cells or (row, col) => cell; default: varied shades */
+    cells?: Cell[][] | ((r: number, c: number) => Cell);
+    /** cell size (px, default 16) */
+    cellSize?: number;
+    /** names for the extent along each axis, e.g. { rows: '$T$', cols: '$d$' } */
+    axes?: {
+        rows?: string;
+        cols?: string;
+    };
+}
+export interface VoxelOptions extends NodeOptions {
+    rows?: number;
+    cols?: number;
+    depth?: number;
+    /** per cell, (row, col, depth) => cell with depth 0 in front, or [row][col][depth]; default: varied shades */
+    cells?: Cell[][][] | ((r: number, c: number, d: number) => Cell);
+    /** cell size (px, default 16) */
+    cellSize?: number;
+    /** names for the extent along each axis, e.g. { rows: 'H', cols: 'W', depth: 'C' } */
+    axes?: {
+        rows?: string;
+        cols?: string;
+        depth?: string;
+    };
+}
+export interface GaussianOptions extends NodeOptions {
+    /** [x, y, amplitude?, sigma?] in [-1, 1]²; default one centered bump */
+    peaks?: [number, number, number?, number?][];
+    size?: V2;
+    mesh?: number;
+}
+export interface SpaceOptions extends NodeOptions {
+    /** [x, y, z, class?] in [-1, 1]³ */
+    points?: number[][];
+    /** axis names (default x, y, z) */
+    axes?: {
+        x?: string;
+        y?: string;
+        z?: string;
+    };
+    size?: V2;
+}
+export interface PointCloudOptions extends NodeOptions {
+    /** [x, y, z, class?] in [-1, 1]³; default: sampled from `shape` */
+    points?: number[][];
+    shape?: 'torus' | 'sphere' | 'cube';
+    /** points sampled when `points` is omitted (default 240) */
+    n?: number;
+    size?: V2;
+}
+export interface WaveformOptions extends NodeOptions {
+    /** raw audio in [-1, 1]; reduced to ≤256 min/max columns. Default: a short synthetic utterance */
+    samples?: ArrayLike<number>;
+    size?: V2;
+}
+export interface SphereOptions extends NodeOptions {
+    /** directions [x, y, z, class?]; normalized onto the sphere */
+    points?: number[][];
+    size?: V2;
+}
+export interface EdgeOptions {
+    label?: string;
+    dashed?: boolean;
+    arrow?: 'end' | 'both' | 'none';
+    thick?: boolean;
+    /** all-to-all lines between two neurons() layers */
+    dense?: boolean;
+    /** force the detour around blocks (residuals usually get it automatically) */
+    skip?: boolean;
+    curve?: boolean;
+    /** side a detour runs on: left / right in TB / BT, top / bottom in LR / RL */
+    side?: 'left' | 'right' | 'top' | 'bottom';
+    color?: string;
+    /** a ✕ on the edge: a cut connection */
+    crossed?: boolean;
+    /** 'side': come down the source's line and turn into the target's side (an L), e.g. conditioning taps */
+    join?: 'side';
+}
+type Rec = {
+    id: string;
+    mods: Module<any>[];
+    groups: string[];
+};
+/** @internal the trace a Figure records into */
+export declare class Graph {
+    nodes: Map<Layer<any>, Rec>;
+    edges: {
+        from: string;
+        to: Ref;
+        style: EdgeOptions;
+    }[];
+    groups: Map<Module<any>, Group>;
+    scope: Module<any>[];
+    ranks: Ref[][];
+    ids: Set<string>;
+    /** a user id must be unique; an auto id (prefix + counter) skips taken ones */
+    claim(id: string | undefined, prefix: string, i: number): string;
+    node(L: Layer<any>): string;
+    apply(L: Layer<any>, xs: Tensor[]): Tensor;
+    enter(m: Module<any>): void;
+    id(r: Ref): string;
+}
+export declare class Tensor {
+    readonly graph: Graph;
+    readonly node: string;
+    readonly style: EdgeOptions;
+    /** @internal */
+    constructor(graph: Graph, node: string, style?: EdgeOptions);
+    /** Style the edge(s) this tensor flows into next: x.edge('$r$'), x.edge({ dashed: true }) */
+    edge(style: EdgeOptions | string): Tensor;
+}
+export type Shape = 'block' | 'thin' | 'text' | 'circle' | 'op' | 'enc' | 'dec' | 'tensor' | 'stack' | 'neurons' | 'vector' | 'matrix' | 'voxels' | 'image' | 'magnify' | 'gaussian' | 'space' | 'sphere' | 'pointcloud' | 'waveform';
+export interface Layer<O extends NodeOptions = NodeOptions> {
+    (...inputs: Tensor[]): Tensor;
+    readonly shape: Shape;
+    /** preset name, used to look up `kinds` in a style config (e.g. 'mha', 'norm', 'block') */
+    readonly kind: string;
+    label: string;
+    /** what the caller passed; always wins */
+    options: O;
+    /** what the preset supplies; loses to any style config */
+    readonly defaults: NodeOptions;
+    /** mark as frozen (🧊) */
+    freeze(): this;
+    /** mark as trainable (🔥) */
+    trainable(): this;
+}
+export declare function layer<O extends NodeOptions>(shape: Shape, label: string, options: O, kind?: string, defaults?: NodeOptions): Layer<O>;
+export type Factory<O extends NodeOptions = NodeOptions> = {
+    (label?: string, options?: O): Layer<O>;
+    (options?: O): Layer<O>;
+};
+/**
+ * Define a block type, the way the built-in presets are defined:
+ *   const rmsnorm = preset('thin', 'RMSNorm', 'yellow')
+ *   const moe = preset('block', 'MoE', { color: 'orange', ghost: 3, kind: 'moe' })
+ * The third argument is a color or default options. `kind` (default: the shape)
+ * is the key a style config's `kinds` uses.
+ */
+export declare function preset<O extends NodeOptions = NodeOptions>(shape: Shape, label?: string, defaults?: string | (NodeOptions & {
+    kind?: string;
+})): Factory<O>;
+export declare const block: Factory<NodeOptions>;
+export declare const thin: Factory<NodeOptions>;
+export declare const text: Factory<NodeOptions>;
+export declare const circle: Factory<NodeOptions>;
+export declare const op: Factory<NodeOptions>;
+export declare const enc: Factory<NodeOptions>;
+export declare const dec: Factory<NodeOptions>;
+export declare const tensor: Factory<TensorOptions>;
+export declare const stack: Factory<StackOptions>;
+export declare const neurons: Factory<NeuronOptions>;
+export declare function vector(values: string[], a?: string | NodeOptions, b?: NodeOptions): Layer<NodeOptions>;
+export declare const mha: Factory<NodeOptions>;
+export declare const attention: Factory<NodeOptions>;
+export declare const ffn: Factory<NodeOptions>;
+export declare const mlp: Factory<NodeOptions>;
+export declare const norm: Factory<NodeOptions>;
+export declare const embed: Factory<NodeOptions>;
+export declare const linear: Factory<NodeOptions>;
+export declare const softmax: Factory<NodeOptions>;
+export declare const matmul: Factory<NodeOptions>;
+export declare const concat: Factory<NodeOptions>;
+export declare const conv: Factory<NodeOptions>;
+export declare const pool: Factory<NodeOptions>;
+export declare const act: Factory<NodeOptions>;
+export declare const dropout: Factory<NodeOptions>;
+export declare const loss: Factory<NodeOptions>;
+export declare const gaussian: Factory<GaussianOptions>;
+export declare const space: Factory<SpaceOptions>;
+export declare const sphere: Factory<SphereOptions>;
+export declare const pointcloud: Factory<PointCloudOptions>;
+/** Audio as a waveform. Long signals are reduced to min/max columns, so the SVG stays small. */
+export declare function waveform(a?: string | WaveformOptions, b?: WaveformOptions): Layer<WaveformOptions>;
+export type ImageSource = string | {
+    currentSrc?: string;
+    src?: string;
+} | {
+    toDataURL(type?: string): string;
+};
+/**
+ * A real image: URL, data URL, <img> or <canvas>. An array draws a stack of
+ * frames, the first one in front: image([t0, t1, t2], { tilt: 35 }).
+ */
+export declare function image(src: ImageSource | ImageSource[], a?: string | ImageOptions, b?: ImageOptions): Layer<ImageOptions>;
+/**
+ * Enlarge part of the image it's called on, like a magnifying glass: magnify({ patch: [1, 2] })(img).
+ * `src` puts your own picture in the lens (e.g. a high-resolution crop) instead of the cropped region.
+ */
+export declare function magnify(a?: string | MagnifyOptions, b?: MagnifyOptions): Layer<MagnifyOptions>;
+/** A grid of cells, each with its own shade, color, texture or label. */
+export declare function matrix(a?: string | MatrixOptions, b?: MatrixOptions): Layer<MatrixOptions>;
+/** A block of voxels seen from the front, top and right, each cell with its own look. */
+export declare function voxels(a?: string | VoxelOptions, b?: VoxelOptions): Layer<VoxelOptions>;
+export declare const add: (...xs: Tensor[]) => Tensor;
+export declare const mul: (...xs: Tensor[]) => Tensor;
+/** What a style config can set on blocks. */
+export interface Style {
+    color?: string;
+    texture?: Texture;
+    /** label size (px); at figure / configure level it also sizes edge, group and caption text */
+    fontSize?: number;
+    /** CSS font family; at figure / configure level it sets the whole figure's font */
+    fontFamily?: string;
+    dashed?: boolean;
+    bold?: boolean;
+}
+/** `style` applies to every block in scope, `kinds` to one preset (wins over `style` at the same level). */
+export interface StyleConfig {
+    style?: Style;
+    kinds?: Record<string, Style>;
+}
+export interface ModuleOptions extends StyleConfig {
+    id?: string;
+    /** group title */
+    label?: string;
+    /** side note such as "N×" */
+    repeat?: string;
+    /** where `repeat` goes; 'auto' (default) takes the first side that collides with nothing */
+    repeatSide?: 'auto' | 'top' | 'bottom' | 'left' | 'right';
+    /** draw a group box (default: when label or repeat is given) */
+    box?: boolean;
+    color?: string;
+    dashed?: boolean;
+    /** texture of the group box */
+    texture?: Texture;
+    /** 🧊 every block inside, like freeze() */
+    frozen?: boolean;
+    /** 🔥 every block inside, like trainable() */
+    trainable?: boolean;
+}
+export interface Module<O = Tensor> {
+    (...inputs: Tensor[]): O;
+}
+/**
+ * Subclass and implement forward(), like nn.Module. Instances are callable:
+ * `this.attn(x)` inside forward, `model(x)` in a figure.
+ */
+export declare abstract class Module<O = Tensor> {
+    options: ModuleOptions;
+    constructor(options?: ModuleOptions);
+    abstract forward(...inputs: Tensor[]): O;
+    /** freeze every block created inside (🧊), like requires_grad_(False) */
+    freeze(): this;
+    /** mark every block created inside as trainable (🔥) */
+    trainable(): this;
+}
+export interface FigureOptions extends StyleConfig {
+    flow?: Dir;
+    theme?: 'light' | 'dark';
+    /** [along the flow, across it] in px */
+    gap?: V2;
+    /** bake WebGL ice / magma when available (default true) */
+    materials?: boolean;
+    /** a key to the looks used: ❄ frozen, 🔥 trainable, each texture, ✕ crossed */
+    legend?: boolean | LegendOptions;
+}
+export interface LegendOptions {
+    /** default 'bottom' */
+    position?: 'bottom' | 'right';
+    /** names to show instead of the defaults, e.g. { trainable: 'Trained', quantized: '4-bit' } */
+    labels?: Partial<Record<'frozen' | 'trainable' | Exclude<Texture, 'ice' | 'magma'> | 'crossed', string>>;
+}
+export type { TexEngine };
+/** configure() also takes the TeX engine: MathJax is used automatically when the page has it */
+export interface Config extends FigureOptions {
+    /** tex → <svg viewBox> (MathJax tex2svg shape); null = built-in fallback only */
+    tex?: TexEngine | null;
+}
+/**
+ * Library-wide defaults, like matplotlib's rcParams. Figures, modules and blocks
+ * override them; `configure(null)` resets. Returns the current config.
+ *   configure({ style: { fontSize: 14, color: 'gray' }, kinds: { mha: { color: 'purple' } } })
+ */
+export declare function configure(config: Config | null): FigureOptions;
+export declare class Figure {
+    readonly options: FigureOptions;
+    private g;
+    constructor(options?: FigureOptions);
+    /** A starting point: a text label, or any layer used as a source (options are added to it). */
+    input(what?: string | Layer<any>, options?: NodeOptions): Tensor;
+    /** An extra edge that isn't a forward call, e.g. a backward process. */
+    edge(from: Tensor, to: Ref, style?: EdgeOptions | string): this;
+    /** Put blocks on the same rank (row in TB/BT, column in LR/RL). */
+    rank(...refs: Ref[]): this;
+    /** Compile to the drawing core's plain data. */
+    diagram(): Diagram;
+    /** Render to an SVG string (works without a DOM). */
+    svg(options?: {
+        theme?: 'light' | 'dark';
+    }): string;
+    /** Export as svg / png / jpeg / webp. Raster formats need a browser. */
+    toBlob(options?: ExportOptions): Promise<Blob>;
+    /** Save to a file; the format follows the extension: fig.download('figure.png') */
+    download(filename?: string, options?: ExportOptions): Promise<void>;
+    /** Render into an element (or a CSS selector). */
+    mount(target: string | Element, options?: {
+        theme?: 'light' | 'dark';
+    }): this;
+}
+export type ExportFormat = 'svg' | 'png' | 'jpeg' | 'webp';
+export interface ExportOptions {
+    /** default: from the file name in download(), else 'svg' */
+    format?: ExportFormat;
+    theme?: 'light' | 'dark';
+    /** raster resolution multiplier (default 2) */
+    scale?: number;
+    /** raster background; default transparent (white for jpeg, or the theme's background) */
+    background?: string;
+    /** jpeg / webp quality 0–1 (default 0.92) */
+    quality?: number;
+}
+/** Build a figure in one block: figure(fig => { ... }) or figure({ flow: 'BT' }, fig => { ... }) */
+export declare function figure(build: (fig: Figure) => unknown): Figure;
+export declare function figure(options: FigureOptions, build: (fig: Figure) => unknown): Figure;

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import{writeFileSync as d}from"node:fs";import{join as S,resolve as E}from"node:path";import{pathToFileURL as R}from"node:url";import{parseArgs as L}from"node:util";var l=(t)=>{let e={},r=t.split(" ");for(let i=0;i<r.length;i+=2)e[r[i]]=r[i+1];return e},N=l("alpha α beta β gamma γ delta δ epsilon ϵ varepsilon ε zeta ζ eta η theta θ vartheta ϑ iota ι kappa κ lambda λ mu μ nu ν xi ξ pi π rho ρ sigma σ tau τ upsilon υ phi ϕ varphi φ chi χ psi ψ omega ω Gamma Γ Delta Δ Theta Θ Lambda Λ Xi Ξ Pi Π Sigma Σ Phi Φ Psi Ψ Omega Ω"),C=l("cdot · times × oplus ⊕ otimes ⊗ odot ⊙ to → rightarrow → leftarrow ← gets ← Rightarrow ⇒ leftrightarrow ↔ mapsto ↦ sum ∑ prod ∏ int ∫ infty ∞ partial ∂ nabla ∇ in ∈ notin ∉ sim ∼ approx ≈ propto ∝ leq ≤ le ≤ geq ≥ ge ≥ neq ≠ ne ≠ pm ± mp ∓ ldots … dots … cdots ⋯ vdots ⋮ mid ∣ | ‖ ast ∗ star ⋆ circ ∘ bullet • forall ∀ exists ∃ emptyset ∅ cup ∪ cap ∩ subset ⊂ subseteq ⊆ top ⊤ perp ⊥ langle ⟨ rangle ⟩ ell ℓ hbar ℏ dagger † prime ′ { { } } % % _ _ # # & & $ $"),f={};for(let t of"+−×·±∓⊕⊗⊙∘∗⋆∪∩")f[t]="bin";for(let t of"=<>≤≥≠≈∼∝∈∉⊂⊆→←⇒↔↦∣")f[t]="rel";for(let t of",;")f[t]="punct";f["|"]="mid";for(let t of"([⟨")f[t]="open";for(let t of")]⟩")f[t]="close";var P=new Set("log exp ln sin cos tanh max min arg argmax argmin softmax lim det tr sup inf Pr KL diag sign".split(" ")),I=l("hat ̂ widehat ̂ tilde ̃ widetilde ̃ bar ̄ overline ̅ dot ̇ ddot ̈ vec ⃗"),j=l(",   :   ;   quad   qquad    ! ​"),T=l("B ℬ E ℰ F ℱ H ℋ I ℐ L ℒ M ℳ R ℛ"),B=l("C ℂ H ℍ N ℕ P ℙ Q ℚ R ℝ Z ℤ");var F=new Set("left right big Big bigl bigr Bigl Bigr displaystyle".split(" "));var u={light:{none:["#e2e5e9","#7f8794"],bg:"none",text:"#1d2430",sub:"#5b6474",edge:"#39414f",halo:"#fff",group:["#f5f6f9","#d5dae2"],shadow:"rgba(30,40,60,.10)",dark:!1,ice:["#f7fdff","#d2effb","#aedcf2","#6fb9de"],fire:["#fff6e8","#ffcf9f","#ee7d36"],c:{white:["#ffffff","#8b95a5"],gray:["#eceff3","#9aa3b2"],pink:["#fde1e4","#e58c98"],orange:["#fde4c8","#e69a50"],yellow:["#f4f5cc","#c0c064"],green:["#d8f1de","#68b880"],blue:["#d6eafc","#5f9fd8"],purple:["#e4defa","#9584db"],red:["#ffd7d2","#dd6559"],teal:["#d1f0ec","#48a99f"]}},dark:{none:["#2a2f37","#8a93a2"],bg:"#0e1117",text:"#e8edf5",sub:"#9aa4b5",edge:"#c3cad6",halo:"#0e1117",group:["#161a22","#2b323f"],shadow:"rgba(0,0,0,.45)",dark:!0,ice:["#29506a","#163a50","#0f2c3e","#7fd4ff"],fire:["#4a2a12","#33180a","#ff9447"],c:{white:["#1b2029","#7d8799"],gray:["#1f242d","#8792a4"],pink:["#3a1e29","#ff8ea2"],orange:["#3a2916","#ffae5c"],yellow:["#2f3018","#e3da66"],green:["#142e22","#5ad08a"],blue:["#13273c","#5ab1ff"],purple:["#241e3f","#a892ff"],red:["#3c1b19","#ff786a"],teal:["#11312f","#4cd3c3"]}}};var v=-0.65,y=0.45,et=Math.cos(v),ot=Math.sin(v),rt=Math.cos(y),st=Math.sin(y);var m=`Usage: forwardfig <file> [-o out.svg|.png|.jpg|.webp] [--theme light|dark]
+
+Renders the module's default export (a Figure, or a function returning one) to the
+-o file, in the format of its extension, or as SVG to stdout. Without a default export,
+every exported Figure is written as <name>.svg into the -o directory (default: the
+current directory).
+
+Options:
+  -o, --out <path>       output file (default export) or directory (named exports)
+      --theme <name>     ${Object.keys(u).join(" | ")} (default: the figure's own)
+      --scale <n>        raster resolution multiplier (default 2)
+      --background <css> raster background (default transparent; white for JPEG)
+  -h, --help             show this help
+
+.ts files need Node >= 22.6 (with --experimental-strip-types before 23.6) or Bun.
+PNG / JPEG / WebP need sharp: npm i -D sharp`,g=(t)=>typeof t?.svg==="function",b={png:"png",jpg:"jpeg",jpeg:"jpeg",webp:"webp"};function n(t){process.stderr.write(`forwardfig: ${t}
+`),process.exit(1)}async function A(){let t;try{t=L({allowPositionals:!0,options:{out:{type:"string",short:"o"},theme:{type:"string"},scale:{type:"string"},background:{type:"string"},help:{type:"boolean",short:"h"}}})}catch(o){n(`${o.message}
+
+${m}`)}let{values:e,positionals:r}=t;if(e.help)return void process.stdout.write(m+`
+`);if(r.length!==1)n(`expected one input file
+
+${m}`);if(e.theme&&!(e.theme in u))n(`unknown theme "${e.theme}" (${Object.keys(u).join(", ")})`);let i=Number(e.scale??2);if(!(i>0))n(`--scale must be a positive number, got "${e.scale}"`);let s=e.out&&/\.(\w+)$/.exec(e.out)?.[1].toLowerCase();if(s&&s!=="svg"&&!(s in b))n(`unknown output format ".${s}" (svg, png, jpg, jpeg, webp)`);let a;try{a=await import(R(E(r[0])).href)}catch(o){n(`cannot import ${r[0]}: ${o.message}`)}let c=(o)=>o.svg({theme:e.theme});if(a.default!==void 0){let o=typeof a.default==="function"&&!g(a.default)?await a.default():a.default;if(!g(o))n(`the default export of ${r[0]} is not a Figure`);if(!e.out)process.stdout.write(c(o));else if(s&&s in b)d(e.out,await z(c(o),b[s],i,e.background));else d(e.out,c(o));return}let h=Object.entries(a).filter(([,o])=>g(o));if(!h.length)n(`${r[0]} exports no Figure (export default a Figure, or export named Figures)`);for(let[o,p]of h){let x=S(e.out??".",`${o}.svg`);d(x,c(p)),process.stderr.write(`wrote ${x}
+`)}}async function z(t,e,r,i){let s;try{s=(await import("sharp")).default}catch{n(`${e.toUpperCase()} output needs sharp: npm i -D sharp`)}for(let h of new Set([...t.matchAll(/<image href="(https?:[^"]+)"/g)].map((o)=>o[1])))try{let o=await fetch(h.replace(/&amp;/g,"&")),p=`data:${o.headers.get("content-type")??""};base64,${Buffer.from(await o.arrayBuffer()).toString("base64")}`;t=t.split(`href="${h}"`).join(`href="${p}"`)}catch{}let a=i??(e==="jpeg"?"#ffffff":void 0),c=s(Buffer.from(t),{density:72*r});return(a?c.flatten({background:a}):c).toFormat(e,{quality:92}).toBuffer()}A().catch((t)=>n(t?.stack??String(t)));