@woosh/meep-engine 3.16.0 → 3.17.0

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

@@ -1,159 +1,185 @@
-/**
- * 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);
-}
+/**
+ * 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;
+}
+
+/**
+ * `NORMALIZE`, as the opcode does it: the length is accumulated and taken wide and only the lanes
+ * are rounded, and a zero vector normalises to zero rather than to nothing.
+ *
+ * The group used to spell this as Gustavson's `taylorInvSqrt` — a line through the band the gradient
+ * table's squared lengths fall in — and now calls the opcode, which is one instruction rather than
+ * five and is exact where the line was not. The field moves by the approximation's error, which is
+ * where this oracle moved with it.
+ *
+ * @param {number[]} v
+ * @returns {number[]}
+ */
+function normalize(v) {
+    let sum = 0;
+
+    for (const component of v) {
+        sum += component * component;
+    }
+
+    const length = Math.sqrt(sum);
+
+    const inverse = length > 0 ? 1 / length : 0;
+
+    return v.map(component => fr(component * inverse));
+}
+
+/**
+ * `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. Negated, as the
+        // group negates it, so each reflection is one multiply-add and rounds once.
+        const inside = gz <= 0 ? -1 : 0;
+
+        const gradient = [
+            fr(fr(Math.floor(gx) * 2 + 1) * inside + gx),
+            fr(fr(Math.floor(gy) * 2 + 1) * inside + gy),
+            gz,
+        ];
+
+        const normalized = normalize(gradient);
+
+        const offset = offsets[corner];
+
+        // `saturate`, which for a falloff that cannot exceed 0.6 is the `max` it replaced
+        const falloff = fr(Math.min(1, 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/make_particle_group.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"make_particle_group.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/make_particle_group.js"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAtB6B,KAAK;IACE,KAAK,EAA9B,SAAS,MAAM,CAAC;IACD,IAAI,EAAnB,MAAM;IACU,KAAK,GAArB,MAAM;IACU,IAAI,GAApB,MAAM;IACU,IAAI,GAApB,MAAM;IACuB,MAAM;IAII,cAAc;IAES,MAAM,GAApE,OAAO,6BAA6B,EAAE,cAAc;;WAGnD,iBAAiB;YAChB,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAAC;aACxD,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAC,CAAA;KAAC,CAAC;EAgE3E;kCAnI6D,wBAAwB"}
+{"version":3,"file":"make_particle_group.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/make_particle_group.js"],"names":[],"mappings":"AAKA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH;IAtB6B,KAAK;IACE,KAAK,EAA9B,SAAS,MAAM,CAAC;IACD,IAAI,EAAnB,MAAM;IACU,KAAK,GAArB,MAAM;IACU,IAAI,GAApB,MAAM;IACU,IAAI,GAApB,MAAM;IACuB,MAAM;IAII,cAAc;IAES,MAAM,GAApE,OAAO,6BAA6B,EAAE,cAAc;;WAGnD,iBAAiB;YAChB,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAA;KAAC,CAAC;aACxD,MAAM;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM;YAAC,IAAI,EAAE,MAAM,CAAC;YAAC,IAAI,EAAE,MAAM,CAAA;SAAC,CAAC,CAAA;KAAC,CAAC;EAgE3E;kCAnI6D,wBAAwB"}

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

@@ -1,5 +1,6 @@
 import { PortDirection } from "../../../../core/model/node-graph/node/PortDirection.js";
 import { infer_particle_graph_types } from "./infer_particle_graph_types.js";
+import { clone_particle_parameters } from "./particle_node_parameters.js";
 import { is_particle_group_boundary, ParticleNodeGroup } from "./ParticleNodeGroup.js";
 
 /**
@@ -282,7 +283,7 @@ function fill_body(group, graph, selected, boundary, visual, visualRegistry) {
 
         const copy = body.getNodeSafe(body.createNode(outer.description));
 
-        copy.setParameters(clone_parameters(outer.parameters));
+        copy.setParameters(clone_particle_parameters(outer.parameters));
 
         copies.set(id, copy);
 
@@ -406,22 +407,3 @@ function unique_name(candidate, claimed) {
 
     return name;
 }
-
-/**
- * A node's parameters, deep enough that the copy and the original cannot write through to each
- * other. See the same function in {@link ./flatten_particle_graph.js}.
- *
- * @param {object} parameters
- * @returns {object}
- */
-function clone_parameters(parameters) {
-    const result = {};
-
-    for (const key of Object.keys(parameters)) {
-        const value = parameters[key];
-
-        result[key] = Array.isArray(value) ? value.slice() : value;
-    }
-
-    return result;
-}

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

@@ -0,0 +1,17 @@
+/**
+ * Comparison operators the single `compare` node type covers, and the opcode each lowers to.
+ *
+ * A file of its own, small as it is, because it is the one thing
+ * {@link ./particle_node_parameters.js} needs from the node library *while it is being defined* —
+ * the parameter schema lists these options as its module body runs. Left in
+ * {@link ./ParticleNodeRegistry.js} it made the two modules a cycle that only held together while
+ * nobody imported them in the wrong order, and the registry now reaches for
+ * {@link ./ParticleGroupBuilder.js} — which reaches back through the parameter schema — so the
+ * order it held together in is no longer the order they load in.
+ *
+ * @type {Object<string, number>}
+ */
+export const PARTICLE_COMPARE_OPCODES: {
+    [x: string]: number;
+};
+//# sourceMappingURL=particle_compare_ops.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"particle_compare_ops.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_compare_ops.js"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AACH;QAFiB,MAAM,GAAE,MAAM;EAQ5B"}

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

@@ -0,0 +1,22 @@
+import { VM_OP } from "../isa/ParticleVMISA.js";
+
+/**
+ * Comparison operators the single `compare` node type covers, and the opcode each lowers to.
+ *
+ * A file of its own, small as it is, because it is the one thing
+ * {@link ./particle_node_parameters.js} needs from the node library *while it is being defined* —
+ * the parameter schema lists these options as its module body runs. Left in
+ * {@link ./ParticleNodeRegistry.js} it made the two modules a cycle that only held together while
+ * nobody imported them in the wrong order, and the registry now reaches for
+ * {@link ./ParticleGroupBuilder.js} — which reaches back through the parameter schema — so the
+ * order it held together in is no longer the order they load in.
+ *
+ * @type {Object<string, number>}
+ */
+export const PARTICLE_COMPARE_OPCODES = Object.freeze({
+    lt: VM_OP.CMP_LT,
+    le: VM_OP.CMP_LE,
+    gt: VM_OP.CMP_GT,
+    ge: VM_OP.CMP_GE,
+    eq: VM_OP.CMP_EQ,
+});

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

@@ -8,30 +8,50 @@
  * importing the other.
  */
 /**
- * One problem with a graph.
+ * One finding about a graph.
  *
  * @typedef {object} ParticleGraphDiagnostic
- * @property {number} node the offending node's id, or -1 for a problem with the graph as a whole
+ * @property {number} node the node it is about, or -1 for the graph as a whole
  * @property {string} message
- * @property {string} severity {@link PARTICLE_GRAPH_ERROR} — the graph will not compile — or
- *   {@link PARTICLE_GRAPH_WARNING}
+ * @property {string} severity {@link PARTICLE_GRAPH_ERROR} — the graph will not compile —
+ *   {@link PARTICLE_GRAPH_WARNING}, or {@link PARTICLE_GRAPH_INFO}
  */
 /** @type {string} */
 export const PARTICLE_GRAPH_ERROR: string;
 /** @type {string} */
 export const PARTICLE_GRAPH_WARNING: string;
 /**
- * One problem with a graph.
+ * Something worth knowing about a graph that is not wrong with it.
+ *
+ * A node no sink reads is the one that matters: it is not compiled, so nothing about it can break
+ * the effect and nothing about it is worth a warning — but an author who cannot see why their edit
+ * changed nothing is owed the reason. Saying it at this level is what lets the graph compile with
+ * half-built work sitting next to it.
+ *
+ * @type {string}
+ */
+export const PARTICLE_GRAPH_INFO: string;
+/**
+ * How loudly each level speaks, so a caller with several findings about one node can show the
+ * loudest. Higher outranks lower.
+ *
+ * @type {Object<string, number>}
+ */
+export const PARTICLE_GRAPH_SEVERITY_RANK: {
+    [x: string]: number;
+};
+/**
+ * One finding about a graph.
  */
 export type ParticleGraphDiagnostic = {
     /**
-     * the offending node's id, or -1 for a problem with the graph as a whole
+     * the node it is about, or -1 for the graph as a whole
      */
     node: number;
     message: string;
     /**
-     * {@link PARTICLE_GRAPH_ERROR } — the graph will not compile — or
-     * {@link PARTICLE_GRAPH_WARNING }
+     * {@link PARTICLE_GRAPH_ERROR } — the graph will not compile —
+     * {@link PARTICLE_GRAPH_WARNING }, or {@link PARTICLE_GRAPH_INFO }
      */
     severity: string;
 };

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

@@ -1 +1 @@
-{"version":3,"file":"particle_graph_diagnostic.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_graph_diagnostic.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;GAQG;AAEH,qBAAqB;AACrB,mCADW,MAAM,CAC2B;AAE5C,qBAAqB;AACrB,qCADW,MAAM,CAC+B;;;;;;;;UAVlC,MAAM;aACN,MAAM;;;;;cACN,MAAM"}
+{"version":3,"file":"particle_graph_diagnostic.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_graph_diagnostic.js"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;GAQG;AAEH,qBAAqB;AACrB,mCADW,MAAM,CAC2B;AAE5C,qBAAqB;AACrB,qCADW,MAAM,CAC+B;AAEhD;;;;;;;;;GASG;AACH,kCAFU,MAAM,CAE0B;AAE1C;;;;;GAKG;AACH;QAFiB,MAAM,GAAE,MAAM;EAM5B;;;;;;;;UAlCW,MAAM;aACN,MAAM;;;;;cACN,MAAM"}

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

@@ -1,25 +1,49 @@
-/**
- * What a check of a particle graph has to say about it, one finding at a time.
- *
- * Findings come from more than one place — the structural checks in
- * {@link ./validate_particle_graph.js} and the type resolution in
- * {@link ./infer_particle_graph_types.js} — and go to one place, a view that marks nodes and
- * lists messages. This is the shape they agree on, kept where both can import it without either
- * importing the other.
- */
-
-/**
- * One problem with a graph.
- *
- * @typedef {object} ParticleGraphDiagnostic
- * @property {number} node the offending node's id, or -1 for a problem with the graph as a whole
- * @property {string} message
- * @property {string} severity {@link PARTICLE_GRAPH_ERROR} — the graph will not compile — or
- *   {@link PARTICLE_GRAPH_WARNING}
- */
-
-/** @type {string} */
-export const PARTICLE_GRAPH_ERROR = "error";
-
-/** @type {string} */
-export const PARTICLE_GRAPH_WARNING = "warning";
+/**
+ * What a check of a particle graph has to say about it, one finding at a time.
+ *
+ * Findings come from more than one place — the structural checks in
+ * {@link ./validate_particle_graph.js} and the type resolution in
+ * {@link ./infer_particle_graph_types.js} — and go to one place, a view that marks nodes and
+ * lists messages. This is the shape they agree on, kept where both can import it without either
+ * importing the other.
+ */
+
+/**
+ * One finding about a graph.
+ *
+ * @typedef {object} ParticleGraphDiagnostic
+ * @property {number} node the node it is about, or -1 for the graph as a whole
+ * @property {string} message
+ * @property {string} severity {@link PARTICLE_GRAPH_ERROR} — the graph will not compile —
+ *   {@link PARTICLE_GRAPH_WARNING}, or {@link PARTICLE_GRAPH_INFO}
+ */
+
+/** @type {string} */
+export const PARTICLE_GRAPH_ERROR = "error";
+
+/** @type {string} */
+export const PARTICLE_GRAPH_WARNING = "warning";
+
+/**
+ * Something worth knowing about a graph that is not wrong with it.
+ *
+ * A node no sink reads is the one that matters: it is not compiled, so nothing about it can break
+ * the effect and nothing about it is worth a warning — but an author who cannot see why their edit
+ * changed nothing is owed the reason. Saying it at this level is what lets the graph compile with
+ * half-built work sitting next to it.
+ *
+ * @type {string}
+ */
+export const PARTICLE_GRAPH_INFO = "info";
+
+/**
+ * How loudly each level speaks, so a caller with several findings about one node can show the
+ * loudest. Higher outranks lower.
+ *
+ * @type {Object<string, number>}
+ */
+export const PARTICLE_GRAPH_SEVERITY_RANK = Object.freeze({
+    [PARTICLE_GRAPH_INFO]: 0,
+    [PARTICLE_GRAPH_WARNING]: 1,
+    [PARTICLE_GRAPH_ERROR]: 2,
+});

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

@@ -1,3 +1,22 @@
+/**
+ * A node's parameters, copied deeply enough that the copy and the original cannot write through to
+ * each other.
+ *
+ * There are four places a parameter object is copied — flattening a group, making one, taking one
+ * apart again, and handing a fresh node its defaults — and until the library had a parameter with a
+ * shape inside it they were all one level deep and all correct. A gradient's stops are a level
+ * further down than a literal's lanes, and a copy that stopped at the array would have left an
+ * ungrouped gradient sharing its stops with the group definition it came out of: edit the colour on
+ * one and it changes on the other, and on every other instance of that group.
+ *
+ * So there is one of these now, and it goes all the way down. Values are numbers, strings, and arrays
+ * and plain records of those; it is written out rather than handed to `structuredClone` because
+ * flattening a `curl4` runs it four thousand times and none of these values needs the machinery.
+ *
+ * @param {object} parameters
+ * @returns {object}
+ */
+export function clone_particle_parameters(parameters: object): object;
 /**
  * The parameters of one node type.
  *
@@ -74,6 +93,16 @@ export const PARTICLE_PARAMETER_KIND: Readonly<{
     SWIZZLE: "swizzle";
     /** a non-negative integer — a curve handle */
     INTEGER: "integer";
+    /**
+     * an {@link ../../../../engine/animation/curve/AnimationCurve.js AnimationCurve}, as the
+     * `{keys: [...]}` record that class writes and reads
+     */
+    CURVE: "curve";
+    /**
+     * a colour gradient: a list of `{position, color}` stops, see
+     * {@link ./particle_ramp.js ParticleGradientStop}
+     */
+    GRADIENT: "gradient";
 }>;
 /**
  * One parameter of one node type.
@@ -84,6 +113,10 @@ export const PARTICLE_PARAMETER_KIND: Readonly<{
  * @property {*} [default] the value a freshly created node takes; absent for
  *   {@link PARTICLE_PARAMETER_KIND.ATTRIBUTE}, whose default can only come from the effect's layout
  * @property {Object<string, *>} [options] for {@link PARTICLE_PARAMETER_KIND.ENUM}: label -> value
+ * @property {boolean} [alpha] for {@link PARTICLE_PARAMETER_KIND.GRADIENT}: whether the node reads
+ *   the alpha channel. Both gradients *store* one — see {@link ./particle_ramp.js} — so that a
+ *   gradient moved from the RGBA node to the RGB one and back keeps it; this says whether to offer
+ *   it for editing.
  * @property {string} [description] one line of help, shown by the editor
  */
 /**
@@ -138,6 +171,13 @@ export type ParticleNodeParameter = {
     options?: {
         [x: string]: any;
     };
+    /**
+     * for {@link PARTICLE_PARAMETER_KIND.GRADIENT }: whether the node reads
+     * the alpha channel. Both gradients *store* one — see {@link  ./particle_ramp.js} — so that a
+     * gradient moved from the RGBA node to the RGB one and back keeps it; this says whether to offer
+     * it for editing.
+     */
+    alpha?: boolean;
     /**
      * one line of help, shown by the editor
      */

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

@@ -1 +1 @@
-{"version":3,"file":"particle_node_parameters.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_node_parameters.js"],"names":[],"mappings":"AAqKA;;;;;;GAMG;AACH,+CAJW,MAAM,GACJ,qBAAqB,EAAE,CAcnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,uDANW,MAAM;IAEyD,MAAM,GAArE,OAAO,6BAA6B,EAAE,cAAc;IAElD,MAAM,CAoBlB;AAED;;;;GAIG;AACH,2CAFa,MAAM;IAAC,WAAW,EAAE,OAAO,8BAA8B,EAAE,uBAAuB,CAAC;IAAC,UAAU,EAAE,qBAAqB,EAAE,CAAA;CAAC,CAAC,CAOrI;;;;sCAjNS,MAAM;AApBhB;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH;IACI,0FAA0F;;IAE1F,kFAAkF;;IAElF,mFAAmF;;IAEnF,2EAA2E;;IAE3E,kEAAkE;;IAElE,8CAA8C;;GAE/C;AAEH;;;;;;;;;;GAUG;AAEH;;;;;;;;;GASG;AACH,gDAFU,MAAM,EAAE,CAUf;AAEH;;;;;GAKG;AACH;QAFiB,MAAM,GAAE,MAAM;EAI7B;AAEF;;;;;GAKG;AACH;QAFiB,MAAM,GAAE,qBAAqB,EAAE;EA4E7C;;;;;;;;UAtHW,MAAM;;;;UACN,MAAM;;;;;;;;;;YAGC,MAAM;;;;;kBACb,MAAM"}
+{"version":3,"file":"particle_node_parameters.d.ts","sourceRoot":"","sources":["../../../../../../src/shade/renderer/particles/graph/particle_node_parameters.js"],"names":[],"mappings":"AAwMA;;;;;;;;;;;;;;;;;GAiBG;AACH,sDAHW,MAAM,GACJ,MAAM,CAIlB;AAwBD;;;;;;GAMG;AACH,+CAJW,MAAM,GACJ,qBAAqB,EAAE,CAcnC;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,uDANW,MAAM;IAEyD,MAAM,GAArE,OAAO,6BAA6B,EAAE,cAAc;IAElD,MAAM,CAmBlB;AAED;;;;GAIG;AACH,2CAFa,MAAM;IAAC,WAAW,EAAE,OAAO,8BAA8B,EAAE,uBAAuB,CAAC;IAAC,UAAU,EAAE,qBAAqB,EAAE,CAAA;CAAC,CAAC,CAOrI;;;;sCA7RS,MAAM;AApBhB;;;;;;;;;;;;;;;;GAgBG;AAEH;;;GAGG;AACH;IACI,0FAA0F;;IAE1F,kFAAkF;;IAElF,mFAAmF;;IAEnF,2EAA2E;;IAE3E,kEAAkE;;IAElE,8CAA8C;;IAE9C;;;OAGG;;IAEH;;;OAGG;;GAEJ;AAEH;;;;;;;;;;;;;;GAcG;AAEH;;;;;;;;;GASG;AACH,gDAFU,MAAM,EAAE,CAWf;AAEH;;;;;GAKG;AACH;QAFiB,MAAM,GAAE,MAAM;EAI7B;AAEF;;;;;GAKG;AACH;QAFiB,MAAM,GAAE,qBAAqB,EAAE;EA8F7C;;;;;;;;UA7IW,MAAM;;;;UACN,MAAM;;;;;;;;;;YAGC,MAAM;;;;;;;;YACb,OAAO;;;;kBAIP,MAAM"}