@aethervtt/shard-noise 0.0.1

package/dist/planet.d.ts

@@ -0,0 +1,44 @@
+/** The planet graph from the spec. */
+export declare const PLANET: {
+    output: string;
+    nodes: {
+        continents: {
+            fbm: {
+                source: string;
+                octaves: number;
+                frequency: number;
+                gain: number;
+                lacunarity: number;
+                seed: number;
+            };
+        };
+        mountains: {
+            ridged: {
+                source: string;
+                octaves: number;
+                frequency: number;
+                seed: number;
+            };
+        };
+        mask: {
+            remap: {
+                input: string;
+                from: number[];
+                to: number[];
+                clamp: boolean;
+            };
+        };
+        warped: {
+            warp: {
+                input: string;
+                by: string;
+                amount: number;
+            };
+        };
+        height: {
+            add: (string | {
+                multiply: string[];
+            })[];
+        };
+    };
+};

package/dist/planet.js

@@ -0,0 +1,15 @@
+const PLANET = {
+  output: "height",
+  nodes: {
+    continents: {
+      fbm: { source: "simplex", octaves: 5, frequency: 0.8, gain: 0.5, lacunarity: 2, seed: 1 }
+    },
+    mountains: { ridged: { source: "simplex", octaves: 6, frequency: 3.2, seed: 2 } },
+    mask: { remap: { input: "continents", from: [0.1, 0.4], to: [0, 1], clamp: true } },
+    warped: { warp: { input: "mountains", by: "continents", amount: 0.15 } },
+    height: { add: ["continents", { multiply: ["warped", "mask"] }] }
+  }
+};
+export {
+  PLANET
+};

package/dist/plugin.d.ts

@@ -0,0 +1,2 @@
+/** noise.sample and noise.stats, and the kernel loaded before the first frame. */
+export declare const noisePlugin: import("@aethervtt/shard-runtime").Plugin;

package/dist/plugin.js

@@ -0,0 +1,18 @@
+import { definePlugin } from "@aethervtt/shard-runtime";
+import { loadNoiseKernel } from "./loader.js";
+import * as methodsModule from "./methods.js";
+import { noiseMethods } from "./methods.js";
+import * as noiseGraphModule from "./noise-graph.js";
+const noisePlugin = definePlugin({
+  name: "noise",
+  provides: [methodsModule, noiseGraphModule],
+  build(app) {
+    app.addMethod(...noiseMethods);
+  },
+  async ready() {
+    await loadNoiseKernel();
+  }
+});
+export {
+  noisePlugin
+};

package/dist/reference.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Test-only f64 reference evaluators for the gradient sources: the kernel's algorithms with every
+ * position in f64 and cells as exact integers. They show what the true value at a far-away point
+ * is, so tests can check that origin-offset sampling finds it (and plain f32 sampling doesn't).
+ */
+/** Perlin 3D at an f64 lattice position. */
+export declare function perlin3Reference(seed: number, x: number, y: number, z: number): number;
+/** OpenSimplex2 3D at an f64 position in lattice units (before the rotation). */
+export declare function simplex3Reference(seed: number, x: number, y: number, z: number): number;

package/dist/reference.js

@@ -0,0 +1,97 @@
+const PX = 501125321;
+const PY = 1136930381;
+const PZ = 1720413743;
+const SEED_FLIP_3D = 1389709235;
+const R3 = Math.fround(0.6);
+const TWO_THIRDS = Math.fround(2 / 3);
+const gradHash3 = (s, x, y, z) => Math.imul(s ^ x ^ y ^ z, 668265261) >>> 28;
+function grad3(g, x, y, z) {
+  const drop = g >> 2;
+  const a = drop === 0 ? y : x;
+  const b = drop === 2 ? y : z;
+  return (g & 1 ? -a : a) + (g & 2 ? -b : b);
+}
+const fade = (t) => t * t * t * (t * (t * 6 - 15) + 10);
+const lerp = (a, b, t) => a + t * (b - a);
+function perlin3Reference(seed, x, y, z) {
+  const fx = Math.floor(x);
+  const fy = Math.floor(y);
+  const fz = Math.floor(z);
+  const tx = x - fx;
+  const ty = y - fy;
+  const tz = z - fz;
+  const x0 = Math.imul(fx, PX);
+  const y0 = Math.imul(fy, PY);
+  const z0 = Math.imul(fz, PZ);
+  const x1 = x0 + PX | 0;
+  const y1 = y0 + PY | 0;
+  const z1 = z0 + PZ | 0;
+  const g = (a2, b2, c, dx, dy, dz) => grad3(gradHash3(seed, a2, b2, c), dx, dy, dz);
+  const u = fade(tx);
+  const v = fade(ty);
+  const w = fade(tz);
+  const a = lerp(g(x0, y0, z0, tx, ty, tz), g(x1, y0, z0, tx - 1, ty, tz), u);
+  const b = lerp(g(x0, y1, z0, tx, ty - 1, tz), g(x1, y1, z0, tx - 1, ty - 1, tz), u);
+  const d = lerp(g(x0, y0, z1, tx, ty, tz - 1), g(x1, y0, z1, tx - 1, ty, tz - 1), u);
+  const e = lerp(g(x0, y1, z1, tx, ty - 1, tz - 1), g(x1, y1, z1, tx - 1, ty - 1, tz - 1), u);
+  return Math.max(-1, Math.min(1, lerp(lerp(a, b, v), lerp(d, e, v), w)));
+}
+function simplex3Reference(seed, x, y, z) {
+  const r = (x + y + z) * TWO_THIRDS;
+  const px = r - x;
+  const py = r - y;
+  const pz = r - z;
+  const rx = Math.round(px);
+  const ry = Math.round(py);
+  const rz = Math.round(pz);
+  let xb = Math.imul(rx, PX);
+  let yb = Math.imul(ry, PY);
+  let zb = Math.imul(rz, PZ);
+  let xr = px - rx;
+  let yr = py - ry;
+  let zr = pz - rz;
+  let xs = xr < 0 ? 1 : -1;
+  let ys = yr < 0 ? 1 : -1;
+  let zs = zr < 0 ? 1 : -1;
+  let ax = Math.abs(xr);
+  let ay = Math.abs(yr);
+  let az = Math.abs(zr);
+  let a = R3 - xr * xr - (yr * yr + zr * zr);
+  let s = seed;
+  let value = 0;
+  for (let l = 0; ; l++) {
+    const a0 = Math.max(a, 0);
+    value += a0 * a0 * a0 * a0 * grad3(gradHash3(s, xb, yb, zb), xr, yr, zr);
+    const mx = ax >= ay && ax >= az;
+    const my = !mx && ay >= az;
+    const am = Math.max(ax, ay, az);
+    const b0 = Math.max(a + am + am - 1, 0);
+    const hx = mx ? xb - Math.imul(xs, PX) | 0 : xb;
+    const hy = my ? yb - Math.imul(ys, PY) | 0 : yb;
+    const hz = !mx && !my ? zb - Math.imul(zs, PZ) | 0 : zb;
+    const ox = xr + (mx ? xs : 0);
+    const oy = yr + (my ? ys : 0);
+    const oz = zr + (!mx && !my ? zs : 0);
+    value += b0 * b0 * b0 * b0 * grad3(gradHash3(s, hx, hy, hz), ox, oy, oz);
+    if (l === 1) break;
+    ax = 0.5 - ax;
+    ay = 0.5 - ay;
+    az = 0.5 - az;
+    xr = xs * ax;
+    yr = ys * ay;
+    zr = zs * az;
+    a += 0.75 - ax - (ay + az);
+    if (xs === -1) xb = xb + PX | 0;
+    if (ys === -1) yb = yb + PY | 0;
+    if (zs === -1) zb = zb + PZ | 0;
+    xs = -xs;
+    ys = -ys;
+    zs = -zs;
+    s ^= SEED_FLIP_3D;
+  }
+  return Math.max(-1, Math.min(1, value * 32));
+}
+export {
+  perlin3Reference,
+  simplex3Reference
+};

package/dist/sample.d.ts

@@ -0,0 +1,67 @@
+import type { Workers } from '@aethervtt/shard-platform';
+import { type Grid2d, type SpherePatch } from './kernel.js';
+import type { NoiseGraph } from './noise-graph.js';
+export type { Grid2d, SpherePatch } from './kernel.js';
+/** A grid as the helpers take it: `size` and `resolution` may be one number for both axes. */
+export interface GridParams {
+    readonly origin: readonly [number, number];
+    readonly size: number | readonly [number, number];
+    readonly resolution: number | readonly [number, number];
+    readonly z?: number;
+}
+/**
+ * Samples a graph at absolute positions (`xyz…`, or `xyzw…` for a 4D graph) into `out`. Precise
+ * near the origin only (past ~10⁵ units fine octaves lose their fraction bits): use `sampleOffset`
+ * for large domains. Sync, on the calling thread; meant for small batches (a raycast's worth).
+ */
+export declare function sampleNoise(graph: NoiseGraph, seed: number, points: Float32Array, out: Float32Array, node?: string): void;
+/**
+ * Samples at `origin + local`: `origin` is an f64 point (a chunk's center) and `local` small f32
+ * offsets from it. Every source splits its lattice position of the origin into an integer cell and
+ * a fraction in f64, so precision depends only on the size of `local`, not on where the origin is.
+ * Throws `noise/frequency-too-high` if a lattice cell leaves the i32 range.
+ */
+export declare function sampleOffset(graph: NoiseGraph, seed: number, origin: ArrayLike<number>, localPoints: Float32Array, out: Float32Array, node?: string): void;
+/** The origin records `noise_<name>_at` reads in WGSL, for sampling around `origin`. */
+export declare function noiseOrigins(graph: NoiseGraph, origin: ArrayLike<number>, out?: Int32Array): Int32Array;
+export declare function normalizeGrid(g: GridParams): Grid2d;
+/**
+ * Samples a `resolution` grid spanning `origin` to `origin + size` on the z plane (x along a row,
+ * rows along y) into `out`, row by row. Offsets from the grid's center, so it's precise anywhere.
+ */
+export declare function sampleGrid2d(graph: NoiseGraph, seed: number, grid: GridParams, out: Float32Array, node?: string): void;
+/**
+ * Samples a cube-sphere patch: `resolution`² vertices over face coordinates [x0, x0 + extent] ×
+ * [y0, y0 + extent] (tangent-adjusted, as 0043's terrain), at direction × radius. Offsets from the
+ * patch center, so a chunk on a gas giant samples as precisely as one at the origin.
+ */
+export declare function sampleSpherePatch(graph: NoiseGraph, seed: number, patch: SpherePatch, out: Float32Array, node?: string): void;
+/**
+ * The gradient of the graph at each point, by central differences of `h` (default: a thousandth
+ * of the finest lattice cell), written to `dx`, `dy`, `dz`; `out` gets the values. For CPU normals
+ * and slope masks. Positions are absolute, as in `sampleNoise`.
+ */
+export declare function sampleNoiseGradient(graph: NoiseGraph, seed: number, points: Float32Array, out: Float32Array, dx: Float32Array, dy: Float32Array, dz: Float32Array, h?: number): void;
+export interface AsyncOptions {
+    readonly priority?: 'high' | 'normal';
+    /** Sample `node` instead of the graph's output. */
+    readonly node?: string;
+}
+/**
+ * `sampleNoise` (or `sampleOffset`, with `origin`) on the worker pool. `points` is copied and
+ * moves to the worker; the values move back and are copied into `out`.
+ */
+export declare function sampleNoiseAsync(workers: Workers, graph: NoiseGraph, seed: number, points: Float32Array, out: Float32Array, options?: AsyncOptions & {
+    origin?: ArrayLike<number>;
+}): Promise<void>;
+/**
+ * Milliseconds the calling thread spent in pool sampling since the last reset: posting jobs and
+ * copying results into `out`. The bench checks it stays small next to the work itself.
+ */
+export declare const poolTiming: {
+    mainThreadMs: number;
+};
+/** `sampleSpherePatch` on the worker pool, split by rows across its workers. */
+export declare function sampleSpherePatchAsync(workers: Workers, graph: NoiseGraph, seed: number, patch: SpherePatch, out: Float32Array, options?: AsyncOptions): Promise<void>;
+/** `sampleGrid2d` on the worker pool, split by rows across its workers. */
+export declare function sampleGrid2dAsync(workers: Workers, graph: NoiseGraph, seed: number, grid: GridParams, out: Float32Array, options?: AsyncOptions): Promise<void>;

package/dist/sample.js

@@ -0,0 +1,232 @@
+import { ShardError } from "@aethervtt/shard-core";
+import {
+  computeOrigins,
+  evalProgram,
+  gridOrigin,
+  gridPoints,
+  patchOrigin,
+  patchPoints
+} from "./kernel.js";
+import { loadNoiseKernel, noiseKernel } from "./loader.js";
+const WORKER = new URL("./worker.js", import.meta.url).href;
+let originScratch = new Int32Array(0);
+let localScratch = new Float32Array(0);
+const origin64 = new Float64Array(4);
+function origins(program) {
+  const n = program.zeroOrigins.length;
+  if (originScratch.length < n) originScratch = new Int32Array(n);
+  return n === originScratch.length ? originScratch : originScratch.subarray(0, n);
+}
+function local(n) {
+  if (localScratch.length < n) localScratch = new Float32Array(n);
+  return localScratch;
+}
+function shard(err) {
+  if (err instanceof ShardError) throw err;
+  const e = err;
+  throw new ShardError(e.code ?? "noise/sample-failed", e.message ?? String(err), {
+    ...e.hint ? { hint: e.hint } : {}
+  });
+}
+function stride(graph) {
+  return graph.program.dimensions === 4 ? 4 : 3;
+}
+function check(count, out) {
+  if (out.length < count) {
+    throw new ShardError(
+      "noise/out-too-small",
+      `out holds ${out.length} values; the call writes ${count}`,
+      {
+        hint: "Size out to one value per point (resolution\xB2 for patches, nx \xD7 ny for grids)."
+      }
+    );
+  }
+}
+function sampleNoise(graph, seed, points, out, node) {
+  const program = graph.programFor(node);
+  const s = stride(graph);
+  const count = Math.floor(points.length / s);
+  check(count, out);
+  evalProgram(noiseKernel().state, program, seed, program.zeroOrigins, points, s, count, out);
+}
+function sampleOffset(graph, seed, origin, localPoints, out, node) {
+  const program = graph.programFor(node);
+  const s = stride(graph);
+  const count = Math.floor(localPoints.length / s);
+  check(count, out);
+  const records = origins(program);
+  try {
+    computeOrigins(program.terms, origin, records);
+  } catch (err) {
+    shard(err);
+  }
+  evalProgram(noiseKernel().state, program, seed, records, localPoints, s, count, out);
+}
+function noiseOrigins(graph, origin, out) {
+  const program = graph.program;
+  const records = out ?? new Int32Array(program.zeroOrigins.length);
+  try {
+    return computeOrigins(program.terms, origin, records);
+  } catch (err) {
+    shard(err);
+  }
+}
+function normalizeGrid(g) {
+  const size = typeof g.size === "number" ? [g.size, g.size] : g.size;
+  const res = typeof g.resolution === "number" ? [g.resolution, g.resolution] : g.resolution;
+  return { origin: g.origin, size, resolution: res, ...g.z !== void 0 ? { z: g.z } : {} };
+}
+function sampleGrid2d(graph, seed, grid, out, node) {
+  const g = normalizeGrid(grid);
+  const [nx, ny] = g.resolution;
+  check(nx * ny, out);
+  gridOrigin(g, origin64);
+  const pts = gridPoints(g, origin64, 0, ny, local(nx * ny * 3));
+  sampleArea(graph, seed, pts, nx * ny, out, node);
+}
+function sampleSpherePatch(graph, seed, patch, out, node) {
+  const n = patch.resolution;
+  check(n * n, out);
+  patchOrigin(patch, origin64);
+  const pts = patchPoints(patch, origin64, 0, n, local(n * n * 3));
+  sampleArea(graph, seed, pts, n * n, out, node);
+}
+function sampleArea(graph, seed, pts, count, out, node) {
+  const program = graph.programFor(node);
+  if (program.dimensions === 4) {
+    throw new ShardError(
+      "noise/domain-mismatch",
+      "Grids and sphere patches are 3D; this graph is 4D",
+      {
+        hint: "Sample a 4D graph with sampleNoise or sampleOffset and xyzw points."
+      }
+    );
+  }
+  const records = origins(program);
+  try {
+    computeOrigins(program.terms, origin64, records);
+  } catch (err) {
+    shard(err);
+  }
+  evalProgram(noiseKernel().state, program, seed, records, pts, 3, count, out);
+}
+function sampleNoiseGradient(graph, seed, points, out, dx, dy, dz, h) {
+  const s = stride(graph);
+  const count = Math.floor(points.length / s);
+  check(count, out);
+  let finest = 0;
+  for (const a of graph.program.terms.a) finest = Math.max(finest, Math.abs(a));
+  const step = h ?? (finest > 0 ? 1e-3 / finest : 1e-3);
+  const pts = local(count * s * 7);
+  const values = new Float32Array(count * 7);
+  for (let i = 0; i < count; i++) {
+    for (let v = 0; v < 7; v++) {
+      const o = (v * count + i) * s;
+      for (let c = 0; c < s; c++) pts[o + c] = points[i * s + c];
+    }
+    for (let axis = 0; axis < 3; axis++) {
+      pts[((1 + axis * 2) * count + i) * s + axis] += step;
+      pts[((2 + axis * 2) * count + i) * s + axis] -= step;
+    }
+  }
+  const program = graph.program;
+  evalProgram(noiseKernel().state, program, seed, program.zeroOrigins, pts, s, count * 7, values);
+  const inv = 1 / (2 * step);
+  for (let i = 0; i < count; i++) {
+    out[i] = values[i];
+    dx[i] = (values[count + i] - values[2 * count + i]) * inv;
+    dy[i] = (values[3 * count + i] - values[4 * count + i]) * inv;
+    dz[i] = (values[5 * count + i] - values[6 * count + i]) * inv;
+  }
+}
+async function sampleNoiseAsync(workers, graph, seed, points, out, options = {}) {
+  const program = graph.programFor(options.node);
+  const s = stride(graph);
+  const count = Math.floor(points.length / s);
+  check(count, out);
+  const { module } = await loadNoiseKernel();
+  const copy = points.slice(0, count * s);
+  const job = {
+    kind: "points",
+    points: copy,
+    stride: s,
+    ...options.origin ? { origin: Float64Array.from(options.origin) } : {}
+  };
+  const values = await workers.run(WORKER, "sample", [module, program, seed >>> 0, job], {
+    transfer: [copy.buffer],
+    priority: options.priority
+  }).catch(shard);
+  out.set(values);
+}
+const poolTiming = { mainThreadMs: 0 };
+function splits(workers, rows) {
+  const lanes = workers.size > 0 ? workers.size : 1;
+  return Math.max(1, Math.min(lanes, Math.ceil(rows / 16)));
+}
+async function areaAsync(workers, graph, seed, kind, area, width, rows, out, options) {
+  const program = graph.programFor(options.node);
+  const { module } = await loadNoiseKernel();
+  const t0 = performance.now();
+  const jobs = splits(workers, rows);
+  const per = Math.ceil(rows / jobs);
+  const pending = [];
+  for (let row0 = 0; row0 < rows; row0 += per) {
+    const row1 = Math.min(rows, row0 + per);
+    pending.push(
+      workers.run(
+        WORKER,
+        "sample",
+        [module, program, seed >>> 0, { kind, area, row0, row1 }],
+        {
+          priority: options.priority
+        }
+      ).then((values) => {
+        const t = performance.now();
+        out.set(values, row0 * width);
+        poolTiming.mainThreadMs += performance.now() - t;
+      }, shard)
+    );
+  }
+  poolTiming.mainThreadMs += performance.now() - t0;
+  await Promise.all(pending);
+}
+function sampleSpherePatchAsync(workers, graph, seed, patch, out, options = {}) {
+  check(patch.resolution * patch.resolution, out);
+  const area = {
+    face: patch.face,
+    x0: patch.x0,
+    y0: patch.y0,
+    extent: patch.extent,
+    resolution: patch.resolution,
+    radius: patch.radius
+  };
+  return areaAsync(
+    workers,
+    graph,
+    seed,
+    "patch",
+    area,
+    patch.resolution,
+    patch.resolution,
+    out,
+    options
+  );
+}
+function sampleGrid2dAsync(workers, graph, seed, grid, out, options = {}) {
+  const g = normalizeGrid(grid);
+  check(g.resolution[0] * g.resolution[1], out);
+  return areaAsync(workers, graph, seed, "grid", g, g.resolution[0], g.resolution[1], out, options);
+}
+export {
+  noiseOrigins,
+  normalizeGrid,
+  poolTiming,
+  sampleGrid2d,
+  sampleGrid2dAsync,
+  sampleNoise,
+  sampleNoiseAsync,
+  sampleNoiseGradient,
+  sampleOffset,
+  sampleSpherePatch,
+  sampleSpherePatchAsync
+};

package/dist/schema.d.ts

@@ -0,0 +1,2 @@
+/** `.shard/schemas/noise.schema.json`, generated from the node table. */
+export declare function noiseJsonSchema(): Record<string, unknown>;

package/dist/schema.js

@@ -0,0 +1,132 @@
+import { NODE_DEFS } from "./nodes.js";
+function paramSchema(p) {
+  const base = { description: p.description };
+  switch (p.type) {
+    case "input":
+      return { ...base, $ref: "#/definitions/input" };
+    case "number":
+      return {
+        ...base,
+        type: "number",
+        ...p.default !== void 0 ? { default: p.default } : {},
+        ...p.min !== void 0 ? { minimum: p.min } : {},
+        ...p.max !== void 0 ? { maximum: p.max } : {},
+        ...p.positive ? { exclusiveMinimum: 0 } : {}
+      };
+    case "integer":
+      return {
+        ...base,
+        type: "integer",
+        ...p.default !== void 0 ? { default: p.default } : {},
+        ...p.min !== void 0 ? { minimum: p.min } : {},
+        ...p.max !== void 0 ? { maximum: p.max } : {}
+      };
+    case "boolean":
+      return {
+        ...base,
+        type: "boolean",
+        ...p.default !== void 0 ? { default: p.default } : {}
+      };
+    case "enum":
+      return {
+        ...base,
+        enum: [...p.values],
+        ...p.default !== void 0 ? { default: p.default } : {}
+      };
+    case "pair":
+      return {
+        ...base,
+        type: "array",
+        items: { type: "number" },
+        minItems: 2,
+        maxItems: 2,
+        ...p.default ? { default: [...p.default] } : {}
+      };
+    case "vec":
+      return {
+        ...base,
+        anyOf: [
+          { type: "number" },
+          { type: "array", items: { type: "number" }, minItems: 2, maxItems: 4 }
+        ],
+        ...p.default !== void 0 ? { default: p.default } : {}
+      };
+    case "points":
+      return {
+        ...base,
+        type: "array",
+        minItems: 2,
+        items: { type: "array", items: { type: "number" }, minItems: 2, maxItems: 2 }
+      };
+  }
+}
+function noiseJsonSchema() {
+  const nodes = [];
+  for (const def of NODE_DEFS) {
+    let body;
+    if (def.form === "value") body = { type: "number" };
+    else if (def.form === "list")
+      body = { type: "array", minItems: 2, items: { $ref: "#/definitions/input" } };
+    else {
+      const properties = {};
+      const required = [];
+      for (const [name, p] of Object.entries(def.params)) {
+        properties[name] = paramSchema(p);
+        if (p.type === "input" || p.type === "points") required.push(name);
+      }
+      const object = {
+        type: "object",
+        properties,
+        additionalProperties: false,
+        ...required.length ? { required } : {}
+      };
+      body = def.form === "unary" ? { anyOf: [{ $ref: "#/definitions/input" }, object] } : object;
+    }
+    nodes.push({
+      type: "object",
+      description: `${def.description} Range: ${def.range}.`,
+      properties: { [def.name]: { ...body, description: def.description } },
+      required: [def.name],
+      additionalProperties: false,
+      examples: [def.example]
+    });
+  }
+  return {
+    $schema: "http://json-schema.org/draft-07/schema#",
+    title: "Noise graph",
+    description: "A noise graph (*.noise.json): named nodes, and `output` naming the one the graph returns. The CPU kernel and the generated WGSL both evaluate it; seeds per source mix with the seed it is sampled with.",
+    type: "object",
+    properties: {
+      $schema: { type: "string" },
+      description: { type: "string", description: "What the graph is for." },
+      output: { type: "string", description: "The node the graph returns." },
+      dimensions: {
+        enum: [2, 3, 4],
+        default: 3,
+        description: "Domain dimensions. 4 adds a w coordinate (animated or looping noise)."
+      },
+      extent: {
+        type: "number",
+        exclusiveMinimum: 0,
+        description: "Largest distance from the origin the graph is sampled at (a planet radius). The importer rejects frequencies too fine to address at that distance (noise/frequency-too-high)."
+      },
+      nodes: {
+        type: "object",
+        minProperties: 1,
+        additionalProperties: { $ref: "#/definitions/node" }
+      }
+    },
+    required: ["output", "nodes"],
+    additionalProperties: false,
+    definitions: {
+      input: {
+        description: "A node name, an inline node, or a number.",
+        anyOf: [{ type: "string" }, { type: "number" }, { $ref: "#/definitions/node" }]
+      },
+      node: { anyOf: [{ type: "number" }, ...nodes] }
+    }
+  };
+}
+export {
+  noiseJsonSchema
+};

package/dist/stats.d.ts

@@ -0,0 +1,58 @@
+import type { PreviewImage } from '@aethervtt/shard-assets';
+import type { NoiseGraph } from './noise-graph.js';
+export interface NoiseDomain {
+    /** `plane`: a square on z = 0, centered on the origin. `sphere`: a sphere's surface. */
+    readonly kind?: 'plane' | 'sphere';
+    /** Plane side length. Default: twice the graph's extent, or 4. */
+    readonly size?: number;
+    /** Sphere radius. Default: the graph's extent, or 1. */
+    readonly radius?: number;
+    /** Samples per side (per cube face for spheres). Default 256 (plane) or 105 (six faces). */
+    readonly resolution?: number;
+}
+export interface NoiseStats {
+    readonly samples: number;
+    readonly min: number;
+    readonly max: number;
+    readonly mean: number;
+    readonly stdDev: number;
+    /** `bins` equal-width buckets from `from` to `to`, as fractions of the domain. */
+    readonly histogram: {
+        readonly from: number;
+        readonly to: number;
+        readonly bins: number[];
+    };
+    /** For each requested threshold, the fraction of the domain below it. */
+    readonly below: {
+        readonly threshold: number;
+        readonly fraction: number;
+    }[];
+}
+/**
+ * Samples a graph over a domain and summarizes it: min, max, mean, standard deviation, a histogram,
+ * and the fraction below each threshold. Sphere samples are weighted by the area they cover, so
+ * "30% below sea level" means 30% of the surface. Deterministic: the same numbers on every host.
+ */
+export declare function noiseStats(graph: NoiseGraph, seed: number, domain?: NoiseDomain, options?: {
+    node?: string;
+    thresholds?: readonly number[];
+}): NoiseStats;
+export interface NoisePreviewOptions {
+    /** `plane` (default): the domain's square. `sphere`: an orthographic view of the sphere from +z. */
+    readonly domain?: 'plane' | 'sphere';
+    readonly seed?: number;
+    /** Image side in pixels; overrides width and height. */
+    readonly size?: number;
+    /** Preview an intermediate node instead of the output. */
+    readonly node?: string;
+    /** Plane side length or sphere radius; defaults as in `noiseStats`. */
+    readonly span?: number;
+}
+/**
+ * A grayscale picture of a graph (black at its minimum, white at its maximum). Returns the image and
+ * the value range it maps.
+ */
+export declare function previewNoise(graph: NoiseGraph, width: number, height: number, options?: NoisePreviewOptions): PreviewImage & {
+    min: number;
+    max: number;
+};