@woosh/meep-engine 3.15.0 → 3.16.0

package/src/shade/renderer/particles/graph/groups/particle_groups_utility.js

@@ -0,0 +1,161 @@
+import { ParticleGroupBuilder } from "../ParticleGroupBuilder.js";
+import {
+    PARTICLE_TYPE_F32,
+    PARTICLE_TYPE_VEC2,
+    PARTICLE_TYPE_VEC3,
+    PARTICLE_TYPE_VEC4,
+} from "../ParticleValueType.js";
+
+/**
+ * The small groups: the arithmetic everybody writes out by hand and then writes out again.
+ *
+ * None of these is difficult and that is the point. `1 - x` is two nodes and a wire, and a graph
+ * with six of them is a graph where six places look like arithmetic and none of them says what it is
+ * for. A node called "One Minus" says it.
+ *
+ * ## Shapes
+ *
+ * The ones that do the same thing to any number of lanes declare no type at all — see
+ * {@link ../ParticleNodeGroup.js ParticleGroupNodeDescription}. `remap` of a `vec3` is three remaps
+ * and comes out a `vec3`, exactly as `add` of a `vec3` does, and nothing warns about lanes that were
+ * never at risk.
+ *
+ * The ones that are *about* lanes — the decomposers — declare their shapes, because that is the
+ * whole content of the node.
+ */
+
+/**
+ * Round to the nearest whole number.
+ *
+ * `floor(x + 0.5)`, which rounds a half away from zero downward — `-0.5` goes to `0`, not to `-1`.
+ * That is what every shading language's `round` does with `roundEven` off, and what an author who
+ * writes `round` in one is used to.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_ROUND = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "round",
+        label: "Round",
+        icon: "M4 16h4l4-8h8 M6 12h4",
+        help: "the nearest whole number",
+        inputs: [{ name: "x", type: null }],
+        outputs: [{ name: "out", type: null }],
+    });
+
+    g.out("out", g.floor(g.add(g.in.x, 0.5)));
+
+    return g.build();
+})();
+
+/**
+ * Round upward, to the next whole number at or above.
+ *
+ * `-floor(-x)`, which is exact for every value a float can hold and costs one instruction more than
+ * `floor` does.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_CEIL = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "ceil",
+        label: "Ceiling",
+        icon: "M6 8h12 M12 20V11 M9 14l3-3 3 3",
+        help: "the next whole number at or above",
+        inputs: [{ name: "x", type: null }],
+        outputs: [{ name: "out", type: null }],
+    });
+
+    g.out("out", g.neg(g.floor(g.neg(g.in.x))));
+
+    return g.build();
+})();
+
+/**
+ * `1 - x`. The complement of a value in `0..1`: an alpha into a transparency, a fade into its
+ * inverse, a normalised age into how much life is left.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_ONE_MINUS = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "oneMinus",
+        label: "One Minus",
+        icon: "M8 6v12 M6 8l2-2 M14 12h6",
+        help: "1 - x",
+        inputs: [{ name: "x", type: null }],
+        outputs: [{ name: "out", type: null }],
+    });
+
+    g.out("out", g.sub(1, g.in.x));
+
+    return g.build();
+})();
+
+/**
+ * Move a value from one range to another, linearly.
+ *
+ * `out_low + (x - in_low) * (out_high - out_low) / (in_high - in_low)`. Nothing is clamped: a value
+ * outside the input range comes out outside the output range, which is what makes this composable
+ * with a `clamp` when that is wanted and usable as an extrapolation when it is not.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup}
+ */
+export const PARTICLE_GROUP_REMAP = (() => {
+    const g = new ParticleGroupBuilder({
+        name: "remap",
+        label: "Remap",
+        icon: "M4 8h16 M4 16h16 M7 8v8 M17 8v-3 M17 8v3",
+        help: "move a value from one range to another",
+        inputs: [
+            { name: "x", type: null },
+            { name: "in_low", type: null },
+            { name: "in_high", type: null },
+            { name: "out_low", type: null },
+            { name: "out_high", type: null },
+        ],
+        outputs: [{ name: "out", type: null }],
+    });
+
+    const t = g.div(g.sub(g.in.x, g.in.in_low), g.sub(g.in.in_high, g.in.in_low));
+
+    g.out("out", g.mad(t, g.sub(g.in.out_high, g.in.out_low), g.in.out_low));
+
+    return g.build();
+})();
+
+/**
+ * The decomposers: a vector taken apart into the numbers it is made of.
+ *
+ * The other half of `vec2`/`vec3`/`vec4`, which put one together. A `swizzle` already picks a lane,
+ * and this is four of those with the pattern already filled in and the lanes named — which is the
+ * difference between a node that says `.y` and a node that says `y`.
+ *
+ * One per width rather than one that covers them all, so that the node says how many lanes it is
+ * about: reading three lanes out of a `vec3` should not involve a `w` that is always zero.
+ *
+ * A lane nobody wires up costs nothing at all. Flattening leaves four independent `swizzle` nodes
+ * behind and the compiler starts from what is read, so an unread one is never lowered.
+ *
+ * @type {import("../ParticleNodeGroup.js").ParticleNodeGroup[]}
+ */
+export const PARTICLE_GROUP_DECOMPOSE = [2, 3, 4].map(components => {
+    const lanes = ["x", "y", "z", "w"].slice(0, components);
+
+    const type = [PARTICLE_TYPE_VEC2, PARTICLE_TYPE_VEC3, PARTICLE_TYPE_VEC4][components - 2];
+
+    const g = new ParticleGroupBuilder({
+        name: `decompose${components}`,
+        label: `Decompose ${type.name}`,
+        icon: `M4 12h5 M11 12h3 M14 12l4-4 M14 12l4 4 M14 12h4`,
+        help: `${type.name} apart into ${lanes.join(", ")}`,
+        inputs: [{ name: "v", type }],
+        outputs: lanes.map(lane => ({ name: lane, type: PARTICLE_TYPE_F32 })),
+    });
+
+    for (const lane of lanes) {
+        g.out(lane, g.swz(g.in.v, lane));
+    }
+
+    return g.build();
+});

package/src/shade/renderer/particles/graph/groups/simplex_reference.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Simplex noise over three dimensions, in roughly `[-1, 1]`.
+ *
+ * @param {number[]} point a three-element position
+ * @returns {number}
+ */
+export function simplex3_reference(point: number[]): number;
+//# sourceMappingURL=simplex_reference.d.ts.map

package/src/shade/renderer/particles/graph/groups/simplex_reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"simplex_reference.d.ts","sourceRoot":"","sources":["../../../../../../../src/shade/renderer/particles/graph/groups/simplex_reference.js"],"names":[],"mappings":"AA+EA;;;;;GAKG;AACH,0CAHW,MAAM,EAAE,GACN,MAAM,CA2ElB"}

package/src/shade/renderer/particles/graph/groups/simplex_reference.js

@@ -0,0 +1,159 @@
+/**
+ * Simplex noise, written out in JavaScript, for the group in
+ * {@link ./particle_groups_noise.js} to be checked against.
+ *
+ * A second implementation of a thing is usually a bad oracle — it goes wrong in the same way the
+ * first one did — but that is not the risk here. The group is not written as arithmetic at all; it is
+ * a graph of two hundred nodes assembled through a builder, lowered by a register allocator and run
+ * on an interpreter. This is the algorithm as anybody else would write it, and agreeing with it lane
+ * for lane is what says the graph is that algorithm.
+ *
+ * ## Why every step rounds
+ *
+ * The VM's register file is `f32`, so every instruction's result is rounded to single precision
+ * before the next one reads it. That is normally a difference of a few ulps and of no interest.
+ * Here it decides which gradient a corner gets: the gradient table is reached by asking whether
+ * `1 - |x| - |y|` is at or below zero, and a seventh of the table sits at exactly zero in exact
+ * arithmetic — and a hundred-millionth *above* it once the seventh has been rounded to `f32`. A
+ * double-precision oracle takes the other branch there and disagrees with the VM about a third of the
+ * time, and it would be the one that was wrong: a GPU is `f32` too.
+ *
+ * So `fr` is applied wherever the VM would have stored a register, and nowhere else. Sums inside a
+ * dot product are not rounded per term, because the opcode accumulates and stores once.
+ */
+
+/** @type {function(number):number} */
+const fr = Math.fround;
+
+/** Skew factor for the 3-simplex lattice. @type {number} */
+const F3 = 1 / 3;
+
+/** Unskew factor for the 3-simplex lattice. @type {number} */
+const G3 = 1 / 6;
+
+/**
+ * @param {number[]} a
+ * @param {number[]} b
+ * @returns {number} the dot product, accumulated wide and rounded once, as `DOT` does
+ */
+function dot(a, b) {
+    let sum = 0;
+
+    for (let i = 0; i < a.length; i++) {
+        sum += a[i] * b[i];
+    }
+
+    return fr(sum);
+}
+
+/**
+ * GLSL's `step`: 1 where `x` is at or above the edge.
+ *
+ * @param {number} edge
+ * @param {number} x
+ * @returns {number}
+ */
+function step(edge, x) {
+    return x < edge ? 0 : 1;
+}
+
+/**
+ * `x mod 289`, as the shader spells it. Exact in `f32` over the range the hash reaches.
+ *
+ * @param {number} x
+ * @returns {number}
+ */
+function mod289(x) {
+    return x - Math.floor(x * (1 / 289)) * 289;
+}
+
+/**
+ * The permutation polynomial, `(34x + 1) x mod 289`.
+ *
+ * @param {number} x
+ * @returns {number}
+ */
+function permute(x) {
+    return mod289((x * 34 + 1) * x);
+}
+
+/**
+ * Simplex noise over three dimensions, in roughly `[-1, 1]`.
+ *
+ * @param {number[]} point a three-element position
+ * @returns {number}
+ */
+export function simplex3_reference(point) {
+    const v = point.map(fr);
+
+    const skew = dot(v, [fr(F3), fr(F3), fr(F3)]);
+
+    const cell = v.map(c => Math.floor(fr(c + skew)));
+
+    const unskew = dot(cell, [fr(G3), fr(G3), fr(G3)]);
+
+    const x0 = v.map((c, k) => fr(fr(c - cell[k]) + unskew));
+
+    const order = [step(x0[1], x0[0]), step(x0[2], x0[1]), step(x0[0], x0[2])];
+    const rest = order.map(c => 1 - c);
+    const rest_zxy = [rest[2], rest[0], rest[1]];
+
+    const step1 = order.map((c, k) => Math.min(c, rest_zxy[k]));
+    const step2 = order.map((c, k) => Math.max(c, rest_zxy[k]));
+
+    const cell289 = cell.map(mod289);
+
+    let hashed = [0, step1[2], step2[2], 1].map(c => permute(c + cell289[2]));
+
+    hashed = hashed.map((c, k) => permute(c + cell289[1] + [0, step1[1], step2[1], 1][k]));
+    hashed = hashed.map((c, k) => permute(c + cell289[0] + [0, step1[0], step2[0], 1][k]));
+
+    const ns_x = fr(2 / 7);
+    const ns_y = fr((1 / 7) * 0.5 - 1);
+    const ns_z = fr(1 / 7);
+
+    const offsets = [
+        x0,
+        x0.map((c, k) => fr(fr(c - step1[k]) + fr(G3))),
+        x0.map((c, k) => fr(fr(c - step2[k]) + fr(G3 * 2))),
+        x0.map(c => fr(c - 0.5)),
+    ];
+
+    let total = 0;
+
+    for (let corner = 0; corner < 4; corner++) {
+        const index = hashed[corner];
+
+        const j = index - 49 * Math.floor(fr(index * fr(ns_z * ns_z)));
+
+        const row = Math.floor(fr(j * ns_z));
+        const column = Math.floor(fr(j - fr(7 * row)));
+
+        const gx = fr(row * ns_x + ns_y);
+        const gy = fr(column * ns_x + ns_y);
+        const gz = fr(fr(1 - Math.abs(gx)) - Math.abs(gy));
+
+        // at or below zero, matching the shader's `-step(h, 0)` — see the note above about why the
+        // boundary is reachable and which side of it single precision lands on
+        const outside = gz <= 0 ? 1 : 0;
+
+        const gradient = [
+            fr(gx - fr(fr(Math.floor(gx) * 2 + 1) * outside)),
+            fr(gy - fr(fr(Math.floor(gy) * 2 + 1) * outside)),
+            gz,
+        ];
+
+        const inverse_length = fr(fr(-0.85373472095314) * dot(gradient, gradient) + fr(1.79284291400159));
+
+        const normalized = gradient.map(c => fr(c * inverse_length));
+
+        const offset = offsets[corner];
+
+        const falloff = fr(Math.max(fr(fr(0.6) - dot(offset, offset)), 0));
+        const squared = fr(falloff * falloff);
+
+        total = fr(total + fr(fr(squared * squared) * dot(normalized, offset)));
+    }
+
+    return fr(fr(42) * total);
+}

package/src/shade/renderer/particles/graph/infer_particle_graph_types.d.ts

@@ -0,0 +1,88 @@
+/**
+ * @param {NodeGraph} graph
+ * @param {object} [context]
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} [context.layout] the effect's
+ *   attribute schema; without it, attribute reads and writes are of unknown type
+ * @returns {ParticleGraphTypes}
+ */
+export function infer_particle_graph_types(graph: NodeGraph, { layout }?: {
+    layout?: import("../layout/ParticleLayout.js").ParticleLayout;
+}): ParticleGraphTypes;
+/**
+ * Resolve the type of every value in a particle graph.
+ *
+ * A port's declared type says only that a value goes there; which value — one lane or four — is a
+ * property of the node instance and what it is wired to. This walks the graph once, sources first,
+ * and asks each node's {@link ./ParticleNodeDescription.js ParticleNodeDescription#infer_types}
+ * what it produces given what it is fed. The result is what an editor shows on a port, what the
+ * validator reports a mismatch from, and what the compiler runs its instructions at.
+ *
+ * It is tolerant where the compiler is not. An input with nothing on it, a node on a cycle, a
+ * parameter that does not describe a width — each of those makes a type *unknown* (`null`) and the
+ * walk carries on, because an author with three problems wants to see the types everywhere else.
+ * Unknowns propagate only as far as they must: an `add` with one input bound is typed by that
+ * input, and its empty port reads as the same type, which is exactly what the port is waiting for.
+ *
+ * ## What comes back
+ *
+ * For each node, its output type, and for each input port the type the node *reads* the input
+ * as — which is the port's type as a view should show it. Where that differs from what is wired
+ * into it, the wire carries a conversion, and {@link ParticleGraphTypes#diagnostics} says so:
+ * a scalar broadcasts silently, a vector read narrower or wider is a warning naming the lanes.
+ * See {@link ./ParticleValueType.js particle_type_conversion}.
+ */
+/**
+ * The types of one graph. See {@link infer_particle_graph_types}.
+ */
+export class ParticleGraphTypes {
+    /**
+     * Every conversion worth a word, against the node whose input it happens on.
+     * @type {import("./particle_graph_diagnostic.js").ParticleGraphDiagnostic[]}
+     */
+    diagnostics: import("./particle_graph_diagnostic.js").ParticleGraphDiagnostic[];
+    /**
+     * @param {number} node_id
+     * @param {import("./ParticleValueType.js").ParticleValueType|null} output
+     * @param {Object<string, import("./ParticleValueType.js").ParticleValueType|null>} inputs
+     * @param {Object<string, import("./ParticleValueType.js").ParticleValueType|null>} [outputs]
+     *   one entry per output port, for a node with more than the usual one
+     */
+    set(node_id: number, output: import("./ParticleValueType.js").ParticleValueType | null, inputs: {
+        [x: string]: import("./ParticleValueType.js").ParticleValueType | null;
+    }, outputs?: {
+        [x: string]: import("./ParticleValueType.js").ParticleValueType | null;
+    }): void;
+    /**
+     * @param {number} node_id
+     * @returns {boolean}
+     */
+    has(node_id: number): boolean;
+    /**
+     * The type of a node's output, or `null` where there is none or it is unknown.
+     *
+     * @param {number} node_id
+     * @param {string} [port] which output, for a node with more than one
+     * @returns {import("./ParticleValueType.js").ParticleValueType|null}
+     */
+    output(node_id: number, port?: string): import("./ParticleValueType.js").ParticleValueType | null;
+    /**
+     * The type a node reads one of its inputs as — the input port's type, as far as a view is
+     * concerned. `null` where it is unknown.
+     *
+     * @param {number} node_id
+     * @param {string} port input port name
+     * @returns {import("./ParticleValueType.js").ParticleValueType|null}
+     */
+    input(node_id: number, port: string): import("./ParticleValueType.js").ParticleValueType | null;
+    /**
+     * Every input port of a node and the type each is read as.
+     *
+     * @param {number} node_id
+     * @returns {Object<string, import("./ParticleValueType.js").ParticleValueType|null>}
+     */
+    inputs(node_id: number): {
+        [x: string]: import("./ParticleValueType.js").ParticleValueType | null;
+    };
+    #private;
+}
+//# sourceMappingURL=infer_particle_graph_types.d.ts.map

package/src/shade/renderer/particles/graph/infer_particle_graph_types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"infer_particle_graph_types.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/infer_particle_graph_types.js"],"names":[],"mappings":"AAgIA;;;;;;GAMG;AACH;IAJ0E,MAAM,GAArE,OAAO,6BAA6B,EAAE,cAAc;IAElD,kBAAkB,CAoG9B;AAtOD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH;;GAEG;AACH;IA0BI;;;OAGG;IACH,aAFU,OAAO,gCAAgC,EAAE,uBAAuB,EAAE,CAE3D;IAEjB;;;;;;OAMG;IACH,aANW,MAAM,UACN,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI;YAChD,MAAM,GAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI;;YAC/D,MAAM,GAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI;aAUhF;IAED;;;OAGG;IACH,aAHW,MAAM,GACJ,OAAO,CAInB;IAED;;;;;;OAMG;IACH,gBAJW,MAAM,SACN,MAAM,GACJ,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAYnE;IAED;;;;;;;OAOG;IACH,eAJW,MAAM,QACN,MAAM,GACJ,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI,CAInE;IAED;;;;;OAKG;IACH,gBAHW,MAAM;YACG,MAAM,GAAE,OAAO,wBAAwB,EAAE,iBAAiB,GAAC,IAAI;MAIlF;;CACJ"}

package/src/shade/renderer/particles/graph/infer_particle_graph_types.js

@@ -0,0 +1,234 @@
+import { PARTICLE_GRAPH_WARNING } from "./particle_graph_diagnostic.js";
+import { particle_type_conversion } from "./ParticleValueType.js";
+
+/**
+ * Resolve the type of every value in a particle graph.
+ *
+ * A port's declared type says only that a value goes there; which value — one lane or four — is a
+ * property of the node instance and what it is wired to. This walks the graph once, sources first,
+ * and asks each node's {@link ./ParticleNodeDescription.js ParticleNodeDescription#infer_types}
+ * what it produces given what it is fed. The result is what an editor shows on a port, what the
+ * validator reports a mismatch from, and what the compiler runs its instructions at.
+ *
+ * It is tolerant where the compiler is not. An input with nothing on it, a node on a cycle, a
+ * parameter that does not describe a width — each of those makes a type *unknown* (`null`) and the
+ * walk carries on, because an author with three problems wants to see the types everywhere else.
+ * Unknowns propagate only as far as they must: an `add` with one input bound is typed by that
+ * input, and its empty port reads as the same type, which is exactly what the port is waiting for.
+ *
+ * ## What comes back
+ *
+ * For each node, its output type, and for each input port the type the node *reads* the input
+ * as — which is the port's type as a view should show it. Where that differs from what is wired
+ * into it, the wire carries a conversion, and {@link ParticleGraphTypes#diagnostics} says so:
+ * a scalar broadcasts silently, a vector read narrower or wider is a warning naming the lanes.
+ * See {@link ./ParticleValueType.js particle_type_conversion}.
+ */
+
+/**
+ * The types of one graph. See {@link infer_particle_graph_types}.
+ */
+export class ParticleGraphTypes {
+    /**
+     * Node id -> the type of its `out` port; `null` for a sink, and for a node whose type could not
+     * be resolved.
+     * @type {Map<number, import("./ParticleValueType.js").ParticleValueType|null>}
+     */
+    #outputs = new Map();
+
+    /**
+     * Node id -> output port name -> the type of that port, for the nodes that have more than one.
+     *
+     * Only a {@link ./ParticleNodeGroup.js group} does: everything in the stock library produces one
+     * value, and the group that produces four is flattened away long before a compiler sees it. So
+     * this is here for what an editor draws, and {@link #output} falls back to the single answer for
+     * every node that has one.
+     *
+     * @type {Map<number, Object<string, import("./ParticleValueType.js").ParticleValueType|null>>}
+     */
+    #outputs_by_port = new Map();
+
+    /**
+     * Node id -> input port name -> the type the node reads that input as.
+     * @type {Map<number, Object<string, import("./ParticleValueType.js").ParticleValueType|null>>}
+     */
+    #inputs = new Map();
+
+    /**
+     * Every conversion worth a word, against the node whose input it happens on.
+     * @type {import("./particle_graph_diagnostic.js").ParticleGraphDiagnostic[]}
+     */
+    diagnostics = [];
+
+    /**
+     * @param {number} node_id
+     * @param {import("./ParticleValueType.js").ParticleValueType|null} output
+     * @param {Object<string, import("./ParticleValueType.js").ParticleValueType|null>} inputs
+     * @param {Object<string, import("./ParticleValueType.js").ParticleValueType|null>} [outputs]
+     *   one entry per output port, for a node with more than the usual one
+     */
+    set(node_id, output, inputs, outputs = undefined) {
+        this.#outputs.set(node_id, output);
+        this.#inputs.set(node_id, inputs);
+
+        if (outputs !== undefined) {
+            this.#outputs_by_port.set(node_id, outputs);
+        }
+    }
+
+    /**
+     * @param {number} node_id
+     * @returns {boolean}
+     */
+    has(node_id) {
+        return this.#outputs.has(node_id);
+    }
+
+    /**
+     * The type of a node's output, or `null` where there is none or it is unknown.
+     *
+     * @param {number} node_id
+     * @param {string} [port] which output, for a node with more than one
+     * @returns {import("./ParticleValueType.js").ParticleValueType|null}
+     */
+    output(node_id, port = undefined) {
+        if (port !== undefined) {
+            const by_port = this.#outputs_by_port.get(node_id);
+
+            if (by_port !== undefined && port in by_port) {
+                return by_port[port] ?? null;
+            }
+        }
+
+        return this.#outputs.get(node_id) ?? null;
+    }
+
+    /**
+     * The type a node reads one of its inputs as — the input port's type, as far as a view is
+     * concerned. `null` where it is unknown.
+     *
+     * @param {number} node_id
+     * @param {string} port input port name
+     * @returns {import("./ParticleValueType.js").ParticleValueType|null}
+     */
+    input(node_id, port) {
+        return this.#inputs.get(node_id)?.[port] ?? null;
+    }
+
+    /**
+     * Every input port of a node and the type each is read as.
+     *
+     * @param {number} node_id
+     * @returns {Object<string, import("./ParticleValueType.js").ParticleValueType|null>}
+     */
+    inputs(node_id) {
+        return this.#inputs.get(node_id) ?? {};
+    }
+}
+
+/**
+ * @param {NodeGraph} graph
+ * @param {object} [context]
+ * @param {import("../layout/ParticleLayout.js").ParticleLayout} [context.layout] the effect's
+ *   attribute schema; without it, attribute reads and writes are of unknown type
+ * @returns {ParticleGraphTypes}
+ */
+export function infer_particle_graph_types(graph, { layout } = {}) {
+    const types = new ParticleGraphTypes();
+
+    /** @type {Set<number>} nodes on the current path, so a cycle is noticed rather than followed */
+    const visiting = new Set();
+
+    /**
+     * @param {NodeInstance} node
+     * @returns {import("./ParticleValueType.js").ParticleValueType|null} the node's output type
+     */
+    function visit(node) {
+        if (types.has(node.id)) {
+            return types.output(node.id);
+        }
+
+        if (visiting.has(node.id)) {
+            // A cycle has no evaluation order and so no types; the validator says so in its own
+            // words, this only has to not hang.
+            return null;
+        }
+
+        const description = node.description;
+
+        if (description === null || description === undefined || description.isParticleNodeDescription !== true) {
+            types.set(node.id, null, {});
+
+            return null;
+        }
+
+        visiting.add(node.id);
+
+        /** @type {Object<string, import("./ParticleValueType.js").ParticleValueType|null>} */
+        const sources = {};
+
+        for (const port of description.inPorts) {
+            const connections = node.getEndpoint(port.id).inConnections;
+
+            // exactly one source is a value; none or several is a problem the validator reports
+            if (connections.length !== 1) {
+                sources[port.name] = null;
+
+                continue;
+            }
+
+            const source = connections[0].source;
+
+            visit(source.instance);
+
+            // by name, because the source may be a node with several outputs and they need not
+            // agree — a decomposed vector's lanes are scalars however wide the vector was
+            sources[port.name] = types.output(source.instance.id, source.port.name);
+        }
+
+        visiting.delete(node.id);
+
+        const { output, outputs, inputs } = description.infer_types({
+            inputs: sources,
+            parameters: node.parameters,
+            layout,
+        });
+
+        // every declared input is answered for, so a view never finds a port missing from the map
+        /** @type {Object<string, import("./ParticleValueType.js").ParticleValueType|null>} */
+        const read = {};
+
+        for (const port of description.inPorts) {
+            read[port.name] = inputs[port.name] ?? null;
+        }
+
+        types.set(node.id, description.is_sink ? null : output, read, description.is_sink ? undefined : outputs);
+
+        for (const port of description.inPorts) {
+            const from = sources[port.name];
+            const to = read[port.name];
+
+            if (from === null || to === null) {
+                continue;
+            }
+
+            const conversion = particle_type_conversion(from, to);
+
+            if (conversion !== null) {
+                types.diagnostics.push({
+                    node: node.id,
+                    message: `Input '${port.name}' ${conversion.message}`,
+                    severity: PARTICLE_GRAPH_WARNING,
+                });
+            }
+        }
+
+        return types.output(node.id);
+    }
+
+    for (const node of graph.getNodes()) {
+        visit(node);
+    }
+
+    return types;
+}