@fusion.dev/helix-graph 0.121.0 → 0.122.0

package/README.md

@@ -205,6 +205,57 @@ layout beside its neighbors. `stencil` also takes `inside(x, y)`, a test of
 whether a point in the box is in the shape, in place of `path`, and
 `fitToStencil` fits places a page has into one.
 
+**Every shape becomes a distance field**: for each point in its box, how far
+it is from the shape's edge, below zero inside. `@fusion.dev/helix-graph/shapes`
+makes one from what a page has, and a field is a stencil itself:
+
+| Function | Makes |
+|---|---|
+| `shapeFromPath(path, width, height)` | A flat field from an SVG path |
+| `shapeFromInside(inside, { width, height, depth })` | A flat field, or a solid where `depth` is given, from a test of what is inside |
+| `inflate(field, { depth, roundness })` | A solid puffed out of a flat field, as a cushion is, cut through where the flat shape has a hole |
+
+## In three dimensions
+
+**`threeDriver(box)` draws the graph in three dimensions** with three.js, to
+be turned and looked into. The frame, the list, selection, names and signals
+are the same as in two:
+
+```sh
+bun add three d3-force-3d
+```
+
+```js
+import { connectGraph } from '@fusion.dev/helix-graph'
+import { inflate, shapeFromPath } from '@fusion.dev/helix-graph/shapes'
+import { threeDriver } from '@fusion.dev/helix-graph/three'
+
+connectGraph(frame, threeDriver(box), {
+  stencil: { ...inflate(shapeFromPath(path, 220, 170), { depth: 140 }), place: 'surface' },
+})
+```
+
+- **A solid stencil draws the notes in the solid**: all through it, or, with
+  `place: 'surface'`, in a thin shell just inside its edge, which is how a
+  solid reads as the thing it is shaped like. Each group takes one side of
+  the shape, and each hub's notes a patch around it.
+- **Without a stencil, a layout runs in three dimensions** with d3-force-3d.
+- **Dragging turns the graph, and the wheel and a pinch bring it nearer.** It
+  turns slowly by itself while nobody is handling it, and never for a reader
+  who asks for less motion.
+- **The far side recedes.** On a surface, the far side of the shape falls to
+  a tenth, so the near side reads; through a graph, its far notes are a
+  little quieter than its near ones.
+- **Each group is named over its near side**, and a group's name moves a line
+  where it would cover another's.
+
+| `threeDriver` option | Default | What else it takes |
+|---|---|---|
+| `autoRotate` | `true` | `false` leaves the graph still until the reader turns it |
+| `shape` | `circle` | `square` or `diamond`, for every note that does not say |
+| `groupLabels` | `true` | `false` leaves each group unnamed |
+| `layoutLimit` | `10000` | The longest a layout runs, in milliseconds |
+
 ## What it exports
 
 | Import | What |
@@ -212,8 +263,10 @@ whether a point in the box is in the shape, in place of `path`, and
 | `@fusion.dev/helix-graph` | `connectGraph`, `diffGraph`, `fitToStencil`, `graphColorsFrom`, `seedPositions`, and the `GraphDriver`, `GraphChanges` and `GraphStencil` types |
 | `@fusion.dev/helix-graph/sigma` | `sigmaDriver(sigma, options)` |
 | `@fusion.dev/helix-graph/cosmos` | `cosmosDriver(graph, box, options)` |
+| `@fusion.dev/helix-graph/three` | `threeDriver(box, options)` |
+| `@fusion.dev/helix-graph/shapes` | `shapeFromPath`, `shapeFromInside`, `inflate`, and the `ShapeField` type |
 
-**Sigma and cosmos.gl are optional peers, and graphology is the page's.** Each
+**Sigma, cosmos.gl, three.js and d3-force-3d are optional peers, and graphology is the page's.** Each
 driver types its renderer by the calls it makes on it, so a page brings
 whichever version it has, and a spec holds those shapes to the real classes,
 so a renamed method fails a typecheck here before it reaches a page. `@fusion.dev/helix-graph/sigma` imports
@@ -223,7 +276,7 @@ Sigma 3 is a peer dependency.
 | `connectGraph` option | Default | What else it takes |
 |---|---|---|
 | `center` | `true` | `false` leaves the view where it is when a note is chosen in the list |
-| `stencil` | none | A shape to draw the notes in: `{ path, width, height }` or `{ inside, width, height }` |
+| `stencil` | none | A shape to draw the notes in: a field from `shapes`, `{ path, width, height }` or `{ inside, width, height }`, with `place`, `fill` or `surface` |
 
 | `sigmaDriver` option | Default | What else it takes |
 |---|---|---|

package/dist/connect-graph/arrange.d.ts

@@ -6,7 +6,7 @@ export interface ArrangedNode {
 }
 /**
  * Places for every note from the graph's structure alone, with no layout to
- * wait for: **each group around a circle, each hub in its group, and each
+ * wait for: **each group around a circle, or a sphere in a solid, each hub in its group, and each
  * note beside the hub it hangs from**, the most connected note it links to
  * in its group.
  *
@@ -15,4 +15,6 @@ export interface ArrangedNode {
  * so the shape is drawn from the first frame with each group a region and
  * each hub's notes around it.
  */
-export declare const arrangeByGroup: (nodes: readonly ArrangedNode[], links: readonly SeedLink[]) => Map<string, GraphPoint>;
+export declare const arrangeByGroup: (nodes: readonly ArrangedNode[], links: readonly SeedLink[], { solid }?: {
+    solid?: boolean;
+}) => Map<string, GraphPoint>;

package/dist/connect-graph/arrange.js

@@ -1,9 +1,36 @@
 const TURN = Math.PI * (3 - Math.sqrt(5));
-const spiral = (at, spacing) => ({
-    x: Math.cos(at * TURN) * Math.sqrt(at + 0.5) * spacing,
-    y: Math.sin(at * TURN) * Math.sqrt(at + 0.5) * spacing,
+const STEP = (Math.sqrt(5) - 1) / 2;
+const spiral = (at, spacing, solid) => {
+    if (!solid) {
+        return {
+            x: Math.cos(at * TURN) * Math.sqrt(at + 0.5) * spacing,
+            y: Math.sin(at * TURN) * Math.sqrt(at + 0.5) * spacing,
+        };
+    }
+    const height = 1 - 2 * ((at * STEP) % 1);
+    const around = Math.sqrt(1 - height * height);
+    const out = Math.cbrt(at + 0.5) * spacing;
+    return {
+        x: Math.cos(at * TURN) * around * out,
+        y: height * out,
+        z: Math.sin(at * TURN) * around * out,
+    };
+};
+const around = (at, count, solid) => {
+    if (!solid) {
+        const turn = (at / count) * Math.PI * 2;
+        return { x: Math.cos(turn), y: Math.sin(turn) };
+    }
+    const height = 1 - (2 * (at + 0.5)) / count;
+    const ring = Math.sqrt(1 - height * height);
+    return { x: Math.cos(at * TURN) * ring, y: height, z: Math.sin(at * TURN) * ring };
+};
+const plus = (one, other) => ({
+    x: one.x + other.x,
+    y: one.y + other.y,
+    ...(one.z === undefined && other.z === undefined ? {} : { z: (one.z ?? 0) + (other.z ?? 0) }),
 });
-export const arrangeByGroup = (nodes, links) => {
+export const arrangeByGroup = (nodes, links, { solid = false } = {}) => {
     const groupOf = new Map(nodes.map((node) => [node.id, node.group ?? '']));
     const degree = new Map();
     const neighbors = new Map();
@@ -65,26 +92,32 @@ export const arrangeByGroup = (nodes, links) => {
         for (const members of hubs.values()) {
             count += members.length + 1;
         }
-        return Math.sqrt(count) * 1.5;
+        return (solid ? Math.cbrt(count) : Math.sqrt(count)) * 1.5;
     };
     const radii = [...groups.values()].map(radiusOf);
     const widest = Math.max(0, ...radii);
-    const ring = groups.size > 1 ? (widest * 1.2) / Math.sin(Math.PI / groups.size) : 0;
+    const ring = groups.size > 1
+        ? solid
+            ? (widest * 2.4) / Math.sqrt((4 * Math.PI) / groups.size)
+            : (widest * 1.2) / Math.sin(Math.PI / groups.size)
+        : 0;
     const positions = new Map();
     [...groups.values()].forEach((hubs, at) => {
-        const turn = (at / groups.size) * Math.PI * 2;
-        const middle = { x: Math.cos(turn) * ring, y: Math.sin(turn) * ring };
+        const way = around(at, groups.size, solid);
+        const middle = {
+            x: way.x * ring,
+            y: way.y * ring,
+            ...(solid ? { z: (way.z ?? 0) * ring } : {}),
+        };
         const ordered = [...hubs].sort(([, one], [, other]) => other.length - one.length);
         const mean = ordered.reduce((sum, [, members]) => sum + members.length + 1, 0) / ordered.length;
         ordered.forEach(([hub, members], place) => {
-            const spot = spiral(place, Math.sqrt(mean) * 2);
-            const center = { x: middle.x + spot.x, y: middle.y + spot.y };
+            const center = plus(middle, spiral(place, (solid ? Math.cbrt(mean) : Math.sqrt(mean)) * 2, solid));
             positions.set(hub, center);
             members
                 .sort((one, other) => rank(other) - rank(one))
                 .forEach((member, step) => {
-                const off = spiral(step + 1, 1);
-                positions.set(member, { x: center.x + off.x, y: center.y + off.y });
+                positions.set(member, plus(center, spiral(step + 1, 1, solid)));
             });
         });
     });

package/dist/connect-graph/connect-graph.d.ts

@@ -81,6 +81,13 @@ export interface GraphDriver {
      * outside the group is selected.
      */
     groups?(groups: readonly GraphGroup[]): void;
+    /**
+     * Where in a shape the notes are drawn, where a `stencil` gives one:
+     * `surface`, a shell, whose far side a renderer that draws in three
+     * dimensions sets back so its near side reads; `fill`, all through it; or
+     * undefined, no shape.
+     */
+    shape?(place: 'fill' | 'surface' | undefined): void;
     /** Removes whatever the driver added to the renderer or the page, when the connection ends. */
     stop?(): void;
 }

package/dist/connect-graph/connect-graph.js

@@ -3,7 +3,7 @@ import { arrangeByGroup } from './arrange.js';
 import { diffGraph, isEmpty, linkKey, } from './diff.js';
 import { graphColorsFrom, looksOf, toneColor, } from './looks.js';
 import { seedPositions } from './seed.js';
-import { fitToStencil } from './stencil.js';
+import { fieldOf, fitToStencil } from './stencil.js';
 const viewportOf = (frame) => {
     const box = (frame.shadowRoot?.querySelector('[part="viewport"]') ?? frame).getBoundingClientRect();
     return { height: box.height, width: box.width };
@@ -95,8 +95,11 @@ export const connectGraph = (frame, driver, options = {}) => {
         }
         let { positions, unplaced } = seedPositions(nodes, [...nextLinks.values()], known);
         const shaped = options.stencil && ids.size > 0 && unplaced.size === ids.size
-            ? fitToStencil(arrangeByGroup(nodes, [...nextLinks.values()]), options.stencil)
+            ? fitToStencil(arrangeByGroup(nodes, [...nextLinks.values()], {
+                solid: fieldOf(options.stencil).depth > 0,
+            }), options.stencil)
             : undefined;
+        driver.shape?.(options.stencil ? (options.stencil.place ?? 'fill') : undefined);
         if (shaped) {
             positions = shaped;
             unplaced = new Set();
@@ -118,6 +121,7 @@ export const connectGraph = (frame, driver, options = {}) => {
                     : 1 + Math.min(Math.sqrt(degree.get(node.id) ?? 0), 6),
                 x: at.x,
                 y: at.y,
+                ...(at.z === undefined ? {} : { z: at.z }),
             });
         }
         for (const id of waiting) {
@@ -153,7 +157,7 @@ export const connectGraph = (frame, driver, options = {}) => {
                 for (const [id, at] of settled) {
                     const node = drawnNodes.get(id);
                     if (node) {
-                        drawnNodes.set(id, { ...node, x: at.x, y: at.y });
+                        drawnNodes.set(id, { ...node, x: at.x, y: at.y, z: at.z });
                     }
                 }
                 graph.laidOut?.(Object.fromEntries([...settled].map(([id, at]) => [id, { ...at }])));

package/dist/connect-graph/diff.d.ts

@@ -6,6 +6,8 @@ export interface DrawnNode {
     size: number;
     x: number;
     y: number;
+    /** How near the viewer, for a renderer that draws in three dimensions. */
+    z?: number | undefined;
 }
 /** A link as the renderer draws it, between two notes the graph holds. */
 export interface DrawnLink {

package/dist/connect-graph/diff.js

@@ -20,7 +20,8 @@ export const diffGraph = (before, after) => {
         else if (was.label !== node.label ||
             was.size !== node.size ||
             was.x !== node.x ||
-            was.y !== node.y) {
+            was.y !== node.y ||
+            was.z !== node.z) {
             changes.changeNodes.push(node);
         }
     }

package/dist/connect-graph/seed.d.ts

@@ -2,12 +2,15 @@
 export interface GraphPoint {
     x: number;
     y: number;
+    /** How near the viewer, for a renderer that draws in three dimensions. */
+    z?: number | undefined;
 }
 /** A note as the connector reads it off the frame. */
 export interface SeedNode {
     id: string;
     x?: number | undefined;
     y?: number | undefined;
+    z?: number | undefined;
 }
 /** A link as the connector reads it off the frame. */
 export interface SeedLink {

package/dist/connect-graph/seed.js

@@ -13,7 +13,11 @@ export const seedPositions = (nodes, links, known = new Map()) => {
     const unplaced = new Set();
     for (const node of nodes) {
         if (Number.isFinite(node.x) && Number.isFinite(node.y)) {
-            positions.set(node.id, { x: node.x, y: node.y });
+            positions.set(node.id, {
+                x: node.x,
+                y: node.y,
+                ...(Number.isFinite(node.z) ? { z: node.z } : {}),
+            });
         }
         else {
             const kept = known.get(node.id);
@@ -46,7 +50,11 @@ export const seedPositions = (nodes, links, known = new Map()) => {
         const beside = placed === undefined ? undefined : positions.get(placed);
         if (beside) {
             const offset = nudge(node.id);
-            positions.set(node.id, { x: beside.x + offset.x, y: beside.y + offset.y });
+            positions.set(node.id, {
+                x: beside.x + offset.x,
+                y: beside.y + offset.y,
+                ...(beside.z === undefined ? {} : { z: beside.z + offset.x * offset.y }),
+            });
             continue;
         }
         const radius = Math.sqrt(spiral + 0.5);

package/dist/connect-graph/shape-field.d.ts

@@ -0,0 +1,47 @@
+/**
+ * A shape as a signed distance field: for any point in its box, how far it is
+ * from the shape's edge, below zero inside and above zero outside, in the
+ * box's units. **Flat when `depth` is zero**, and solid otherwise.
+ *
+ * One form for every shape, however it was given, so placing notes inside a
+ * shape, on its surface, or at the nearest point inside it is the same work
+ * in two dimensions and three.
+ */
+export interface ShapeField {
+    /** How deep the box is, from front to back: zero for a flat shape. */
+    readonly depth: number;
+    /** How far a point is from the shape's edge: below zero inside. `z` is ignored for a flat shape. */
+    distance(x: number, y: number, z?: number): number;
+    /** How tall the box is. Its y points down, as an SVG's does. */
+    readonly height: number;
+    /** How wide the box is. */
+    readonly width: number;
+}
+/**
+ * A field from a test of whether a point in the box is inside, sampled at
+ * the center of each cell: flat when `depth` is zero, solid otherwise.
+ */
+export declare const fieldFromInside: (inside: (x: number, y: number, z: number) => boolean, box: {
+    depth?: number | undefined;
+    height: number;
+    width: number;
+}, resolution?: number) => ShapeField;
+/**
+ * A flat field from an SVG path in a box `width` by `height`, its holes cut by
+ * the even-odd rule. Drawn once to a canvas and read off it, which is what
+ * lets a detailed outline become a field in a moment.
+ */
+export declare const fieldFromPath: (path: string, width: number, height: number, resolution?: number) => ShapeField;
+/**
+ * A solid puffed out of a flat shape, as a cushion is: as thick as `depth`
+ * where the shape is widest, rounding to nothing at its edge, and cut
+ * through wherever the flat shape has a hole.
+ *
+ * `roundness`, from 0 to 1, is how far in from the edge the rounding runs, as
+ * a share of the way to the shape's middle: 1, the default, rounds the whole
+ * way, as a pebble; less leaves a flat face, as a coin.
+ */
+export declare const inflate: (flat: ShapeField, { depth, roundness }: {
+    depth: number;
+    roundness?: number;
+}) => ShapeField;

package/dist/connect-graph/shape-field.js

@@ -0,0 +1,172 @@
+const FLAT = 512;
+const SOLID = 96;
+const FAR = 1e20;
+const line = (values, count, out) => {
+    const hull = new Int32Array(count);
+    const bounds = new Float64Array(count + 1);
+    const crossing = (at, from) => (values[at] + at * at - (values[from] + from * from)) /
+        (2 * at - 2 * from);
+    let top = 0;
+    hull[0] = 0;
+    bounds[0] = -FAR;
+    bounds[1] = FAR;
+    for (let at = 1; at < count; at++) {
+        let cross = crossing(at, hull[top]);
+        while (cross <= bounds[top]) {
+            top -= 1;
+            cross = crossing(at, hull[top]);
+        }
+        top += 1;
+        hull[top] = at;
+        bounds[top] = cross;
+        bounds[top + 1] = FAR;
+    }
+    top = 0;
+    for (let at = 0; at < count; at++) {
+        while (bounds[top + 1] < at) {
+            top += 1;
+        }
+        const from = hull[top];
+        out[at] = (at - from) * (at - from) + values[from];
+    }
+};
+const transform = (marked, sizes) => {
+    const [nx, ny, nz] = sizes;
+    const grid = new Float64Array(nx * ny * nz);
+    for (let at = 0; at < grid.length; at++) {
+        grid[at] = marked[at] ? 0 : FAR;
+    }
+    const longest = Math.max(nx, ny, nz);
+    const values = new Float64Array(longest);
+    const out = new Float64Array(longest);
+    const pass = (count, stride, starts) => {
+        for (const start of starts) {
+            for (let step = 0; step < count; step++) {
+                values[step] = grid[start + step * stride];
+            }
+            line(values, count, out);
+            for (let step = 0; step < count; step++) {
+                grid[start + step * stride] = out[step];
+            }
+        }
+    };
+    const along = function* (outer, inner, outerStride, innerStride) {
+        for (let one = 0; one < outer; one++) {
+            for (let two = 0; two < inner; two++) {
+                yield one * outerStride + two * innerStride;
+            }
+        }
+    };
+    pass(nx, 1, along(nz, ny, nx * ny, nx));
+    pass(ny, nx, along(nz, nx, nx * ny, 1));
+    if (nz > 1) {
+        pass(nz, nx * ny, along(ny, nx, nx, 1));
+    }
+    for (let at = 0; at < grid.length; at++) {
+        grid[at] = Math.sqrt(grid[at]);
+    }
+    return grid;
+};
+const fieldFromCells = (inside, sizes, cell, box) => {
+    const outside = new Uint8Array(inside.length);
+    for (let at = 0; at < inside.length; at++) {
+        outside[at] = inside[at] ? 0 : 1;
+    }
+    const toInside = transform(inside, sizes);
+    const toOutside = transform(outside, sizes);
+    const [nx, ny, nz] = sizes;
+    const signed = new Float32Array(inside.length);
+    for (let at = 0; at < inside.length; at++) {
+        signed[at] = inside[at]
+            ? -(toOutside[at] - 0.5) * cell
+            : (toInside[at] - 0.5) * cell;
+    }
+    const read = (x, y, z) => signed[Math.min(Math.max(z, 0), nz - 1) * nx * ny +
+        Math.min(Math.max(y, 0), ny - 1) * nx +
+        Math.min(Math.max(x, 0), nx - 1)];
+    return {
+        ...box,
+        distance: (x, y, z = 0) => {
+            const fx = x / cell - 0.5;
+            const fy = y / cell - 0.5;
+            const fz = nz > 1 ? z / cell - 0.5 : 0;
+            const x0 = Math.floor(fx);
+            const y0 = Math.floor(fy);
+            const z0 = Math.floor(fz);
+            const tx = fx - x0;
+            const ty = fy - y0;
+            const tz = fz - z0;
+            const plane = (layer) => (read(x0, y0, layer) * (1 - tx) + read(x0 + 1, y0, layer) * tx) * (1 - ty) +
+                (read(x0, y0 + 1, layer) * (1 - tx) + read(x0 + 1, y0 + 1, layer) * tx) * ty;
+            const within = nz > 1 ? plane(z0) * (1 - tz) + plane(z0 + 1) * tz : plane(0);
+            const past = Math.hypot(Math.max(-x, x - box.width, 0), Math.max(-y, y - box.height, 0), nz > 1 ? Math.max(-z, z - box.depth, 0) : 0);
+            return past > 0 ? Math.max(within, 0) + past : within;
+        },
+    };
+};
+export const fieldFromInside = (inside, box, resolution = box.depth ? SOLID : FLAT) => {
+    const depth = box.depth ?? 0;
+    const cell = Math.max(box.width, box.height, depth) / resolution;
+    const nx = Math.max(1, Math.ceil(box.width / cell));
+    const ny = Math.max(1, Math.ceil(box.height / cell));
+    const nz = depth > 0 ? Math.max(1, Math.ceil(depth / cell)) : 1;
+    const cells = new Uint8Array(nx * ny * nz);
+    for (let z = 0; z < nz; z++) {
+        for (let y = 0; y < ny; y++) {
+            for (let x = 0; x < nx; x++) {
+                cells[z * nx * ny + y * nx + x] = inside((x + 0.5) * cell, (y + 0.5) * cell, depth > 0 ? (z + 0.5) * cell : 0)
+                    ? 1
+                    : 0;
+            }
+        }
+    }
+    return fieldFromCells(cells, [nx, ny, nz], cell, {
+        depth,
+        height: box.height,
+        width: box.width,
+    });
+};
+export const fieldFromPath = (path, width, height, resolution = FLAT) => {
+    const cell = Math.max(width, height, 1) / resolution;
+    const nx = Math.max(1, Math.ceil(width / cell));
+    const ny = Math.max(1, Math.ceil(height / cell));
+    const canvas = document.createElement('canvas');
+    canvas.width = nx;
+    canvas.height = ny;
+    const context = canvas.getContext('2d', { willReadFrequently: true });
+    const cells = new Uint8Array(nx * ny);
+    if (context) {
+        context.scale(1 / cell, 1 / cell);
+        context.fill(new Path2D(path), 'evenodd');
+        const alpha = context.getImageData(0, 0, nx, ny).data;
+        for (let at = 0; at < cells.length; at++) {
+            cells[at] = (alpha[at * 4 + 3] ?? 0) > 127 ? 1 : 0;
+        }
+    }
+    else {
+        cells.fill(1);
+    }
+    return fieldFromCells(cells, [nx, ny, 1], cell, { depth: 0, height, width });
+};
+export const inflate = (flat, { depth, roundness = 1 }) => {
+    let deepest = 0;
+    const probes = 128;
+    for (let row = 0; row < probes; row++) {
+        for (let column = 0; column < probes; column++) {
+            deepest = Math.max(deepest, -flat.distance(((column + 0.5) / probes) * flat.width, ((row + 0.5) / probes) * flat.height));
+        }
+    }
+    const reach = Math.max(deepest * Math.min(Math.max(roundness, 0.01), 1), 1e-6);
+    const middle = depth / 2;
+    return {
+        depth,
+        distance: (x, y, z = middle) => {
+            const across = flat.distance(x, y);
+            const inset = Math.min(Math.max(-across, 0) / reach, 1);
+            const half = middle * Math.sqrt(1 - (1 - inset) ** 2);
+            return Math.max(across, Math.abs(z - middle) - half);
+        },
+        height: flat.height,
+        width: flat.width,
+    };
+};

package/dist/connect-graph/stencil.d.ts

@@ -1,11 +1,12 @@
 import type { GraphPoint } from './seed.js';
+import { type ShapeField } from './shape-field.js';
 /**
- * A shape the notes are fitted into once a layout settles, in a box `width`
- * by `height`, as an SVG's `viewBox="0 0 width height"` gives one: an SVG
- * path, whose holes are cut by the even-odd rule, or a test of whether a
- * point in the box is inside.
+ * A shape the notes are drawn in. **Any shape field**, flat or solid, such as
+ * `inflate` makes; or, flat, an SVG path in a box `width` by `height`, as an
+ * SVG's `viewBox="0 0 width height"` gives one, whose holes are cut by the
+ * even-odd rule; or a test of whether a point in that box is inside.
  */
-export type GraphStencil = {
+export type GraphStencil = (ShapeField | {
     height: number;
     path: string;
     width: number;
@@ -13,22 +14,37 @@ export type GraphStencil = {
     height: number;
     inside: (x: number, y: number) => boolean;
     width: number;
+}) & {
+    /**
+     * Where in the shape the notes go: `fill`, all through it, which unset is;
+     * or `surface`, a thin shell just inside its edge, which is how a solid
+     * reads as the thing it is shaped like.
+     */
+    place?: 'fill' | 'surface' | undefined;
+    /** How thick the surface's shell is, as a share of the shape's size. 0.04 by default. */
+    shell?: number | undefined;
 };
+/** The field a stencil is, or is made into. */
+export declare const fieldOf: (stencil: GraphStencil) => ShapeField;
 /**
- * `count` places spread evenly over the inside of a shape: a grid sized to
- * the shape's area, each place shaken within its cell so no rows show, and
- * the grid made finer until it holds enough.
+ * `count` places spread evenly over a shape: through all of it, or through a
+ * shell just inside its edge. A grid sized to the room there is, each place
+ * shaken within its cell so no rows show, and made finer until it holds
+ * enough.
  */
-export declare const placesIn: (inside: (x: number, y: number) => boolean, width: number, height: number, count: number) => GraphPoint[];
+export declare const placesIn: (field: ShapeField, count: number, { place, shell }?: {
+    place?: 'fill' | 'surface';
+    shell?: number;
+}) => GraphPoint[];
 /**
- * Places a layout put anywhere, moved into the stencil's shape and filling it
- * evenly. **The notes keep their order**, left to right and, within each
- * strip, top to bottom, so notes the layout put together land together, and
- * each group takes a region of the shape.
+ * Places a layout or an arrangement put anywhere, moved into the stencil's
+ * shape and spread evenly over it. **The notes keep their order**, left to
+ * right, top to bottom, and front to back in a solid, so notes put together
+ * land together, and each group takes a region of the shape.
  *
- * Centered where the layout was, and as large. The stencil's y points down,
- * as an SVG's does, and the layout's up, as Sigma and cosmos.gl draw it.
- * Places the shape cannot hold, as when it has no inside, come back as they
- * were.
+ * Centered where the places were, and as large. The stencil's y points down,
+ * as an SVG's does, and the places' up, as Sigma, cosmos.gl and three.js draw
+ * them. Places the shape cannot hold, as when it has no inside, come back as
+ * they were.
  */
 export declare const fitToStencil: (positions: ReadonlyMap<string, GraphPoint>, stencil: GraphStencil) => Map<string, GraphPoint>;