@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/material/flowModel.ts

@@ -0,0 +1,441 @@
+// The graph, as React Flow wants it — and the memo that makes a keystroke cost
+// ONE card.
+//
+// ── THE DEFECT THIS MODULE EXISTS FOR ───────────────────────────────────
+//
+// v1 built the node array inside the canvas with a `useMemo` over the whole
+// graph, and every node's `data` was a fresh object literal carrying the WHOLE
+// graph. So typing one digit into one Float field rebuilt every card's props,
+// and React Flow re-rendered all of them: at forty nodes a held arrow key was
+// visibly behind the author's finger, and the profile was ninety-five percent
+// cards that had not changed.
+//
+// The fix is not "memo the components". A `memo()` compares props, and props
+// that are rebuilt every render compare unequal every render. The fix is to
+// stop rebuilding them: a WeakMap keyed on the GRAPH NODE OBJECT holds the flow
+// node it produced, beside a key naming everything about the card that is NOT
+// the node itself (its wires, its selection, its group's origin, its problem).
+// The store writes graphs with structural sharing — `{...graph, nodesById: {…}}`
+// — so an untouched node keeps its identity across an edit, hits the cache, and
+// its React Flow node object comes back `===`. React Flow's own reconciler then
+// skips it, and so does React.
+//
+// `materialGraphCanvas.test.tsx` pins that directly: build twice across a
+// one-node edit and assert the OTHER node's flow object is identity-equal.
+//
+// ── WHAT MAY NOT GO IN `data` ───────────────────────────────────────────
+//
+// Anything that changes for a reason unrelated to this card. The graph itself
+// is the obvious one and is gone. Node PREVIEWS are the subtle one: a thumbnail
+// arrives asynchronously for a handful of cards, and threading it through here
+// would invalidate the memo for every card each time one landed. They ride a
+// React context instead (`NodePreview.tsx`), which re-renders the previews and
+// nothing else.
+import type { Edge, Node } from "@xyflow/react";
+import { materialGraphNodeSockets, materialGraphNodeSpec } from "@dailies-studio/shot/doc";
+import type {
+  MaterialGraph3D,
+  MaterialGraphNode,
+  MaterialGraphNodeSpec,
+  MaterialGraphParameter,
+  MaterialGraphProblem,
+  MaterialGraphResolvedType,
+  MaterialGraphSocketSpec,
+  MaterialGraphTypeIndex,
+  ShotAsset,
+} from "@dailies-studio/shot/doc";
+import type { MaterialGraphSelection } from "../../state/types.js";
+
+/** The four renderers. `group` and `comment` are inert boxes, `reroute` is a
+ *  dot with one handle a side, and everything else is a compute card. */
+export type MaterialFlowNodeType = "material" | "materialGroup" | "materialComment" | "materialReroute";
+
+/** The two dropdown vocabularies every card shares. Built ONCE per graph and
+ *  handed to all of them by identity, so forty cards hold one array rather than
+ *  forty copies of the same options. */
+export interface MaterialChoices {
+  images: readonly { value: string; label: string }[];
+  parameters: readonly { value: string; label: string }[];
+}
+
+export interface MaterialFlowData extends Record<string, unknown> {
+  /** Carried rather than read from the store at commit time, for the reason
+   *  every graph verb takes them as parameters: a card built inside a function
+   *  must write to that function even after the canvas has climbed out. */
+  materialId: string;
+  path: readonly string[];
+  node: MaterialGraphNode;
+  spec: MaterialGraphNodeSpec;
+  /** Resolved PER NODE — a subgraph call's sockets are its function's
+   *  signature, not the static spec's empty lists. */
+  inputs: readonly MaterialGraphSocketSpec[];
+  outputs: readonly MaterialGraphSocketSpec[];
+  /** `"in:<socket>"` / `"out:<socket>"` for every socket a wire lands on. The
+   *  card needs it for the ink and the widgets need it to know an input is
+   *  driven and its literal no longer says anything. */
+  connected: ReadonlySet<string>;
+  parameter: MaterialGraphParameter | undefined;
+  assetLabel: string | undefined;
+  /** What this card actually produces, once the wires upstream are resolved.
+   *  Null while the type index cannot say, which is what a cycle or a dangling
+   *  wire looks like from here. */
+  outputType: MaterialGraphResolvedType | null;
+  /** The validator's sentence about this node, or null. */
+  problem: string | null;
+  choices: MaterialChoices;
+}
+
+export type MaterialFlowNode = Node<MaterialFlowData, MaterialFlowNodeType>;
+
+export interface MaterialFlowInput {
+  graph: MaterialGraph3D;
+  materialId: string;
+  /** The scope trail on screen. Only nodes whose `scope` is its last element
+   *  are drawn — a function body is a different canvas. */
+  path: readonly string[];
+  assets: Readonly<Record<string, ShotAsset>>;
+  selection: MaterialGraphSelection;
+  problems: readonly MaterialGraphProblem[];
+  /** Built once by the caller, which needs it for `isValidConnection` anyway. */
+  types: MaterialGraphTypeIndex;
+}
+
+/** The nodes belonging to one scope. Exported because the palette, the
+ *  scheduler and Select All all need the same answer. */
+export function nodesInScope(graph: MaterialGraph3D, path: readonly string[]): MaterialGraphNode[] {
+  const scope = path.length === 0 ? undefined : path[path.length - 1];
+  return Object.values(graph.nodesById).filter((node) => (node.scope ?? undefined) === scope);
+}
+
+/** Which renderer draws this kind. */
+function flowTypeOf(node: MaterialGraphNode): MaterialFlowNodeType {
+  if (node.kind === "group") return "materialGroup";
+  if (node.kind === "comment") return "materialComment";
+  if (node.kind === "reroute") return "materialReroute";
+  return "material";
+}
+
+// ── the choices memo ────────────────────────────────────────────────────────
+//
+// A one-entry cache keyed on the two SOURCE objects. Both are replaced by
+// identity when their contents change (the store never mutates in place), so
+// identity is the whole test — and one entry is enough because exactly one
+// graph is on screen.
+let choicesMemo: {
+  assets: object;
+  parameters: object;
+  value: MaterialChoices;
+  token: number;
+} | null = null;
+let choicesSerial = 0;
+
+function choicesFor(
+  assets: Readonly<Record<string, ShotAsset>>,
+  parameters: Readonly<Record<string, MaterialGraphParameter>>,
+): { value: MaterialChoices; token: number } {
+  if (choicesMemo !== null && choicesMemo.assets === assets && choicesMemo.parameters === parameters) {
+    return { value: choicesMemo.value, token: choicesMemo.token };
+  }
+  choicesSerial += 1;
+  const value: MaterialChoices = {
+    images: Object.values(assets)
+      .filter((asset) => asset.kind === "image")
+      .map((asset) => ({ value: asset.id, label: asset.path.split("/").pop() ?? asset.id }))
+      .sort((a, b) => a.label.localeCompare(b.label)),
+    parameters: Object.values(parameters)
+      .sort((a, b) => a.label.localeCompare(b.label))
+      .map((parameter) => ({ value: parameter.id, label: `${parameter.label} · ${parameter.type}` })),
+  };
+  choicesMemo = { assets, parameters, value, token: choicesSerial };
+  return { value, token: choicesSerial };
+}
+
+/** The suites build several unrelated documents in one process, and a stale
+ *  one-entry memo across them would hand the second document the first's
+ *  options. Never called by the app, where the cache is a hit or a miss and
+ *  both are correct. */
+export function resetMaterialChoicesMemo(): void {
+  choicesMemo = null;
+}
+
+// ── the node cache ──────────────────────────────────────────────────────────
+
+interface FlowCacheEntry {
+  key: string;
+  flow: MaterialFlowNode;
+}
+
+const FLOW_CACHE = new WeakMap<MaterialGraphNode, FlowCacheEntry>();
+const EDGE_CACHE = new WeakMap<object, { key: string; edge: Edge }>();
+
+/** Which sockets on each node carry a wire, in one pass over the edges. */
+function connectionsOf(graph: MaterialGraph3D): Map<string, Set<string>> {
+  const out = new Map<string, Set<string>>();
+  const add = (nodeId: string, key: string): void => {
+    const found = out.get(nodeId);
+    if (found === undefined) out.set(nodeId, new Set([key]));
+    else found.add(key);
+  };
+  for (const edge of graph.edges) {
+    add(edge.source.nodeId, `out:${edge.source.socket}`);
+    add(edge.target.nodeId, `in:${edge.target.socket}`);
+  }
+  return out;
+}
+
+/**
+ * The validator's problems, indexed by the node they are about.
+ *
+ * `at` is a document path — `nodesById.mgn_x.kind` — so the node id is its
+ * second segment. Only the FIRST problem per node is kept: a card has room for
+ * one sentence, and the panel below the canvas lists them all.
+ */
+function problemsByNode(problems: readonly MaterialGraphProblem[]): Map<string, string> {
+  const out = new Map<string, string>();
+  for (const problem of problems) {
+    const parts = problem.at.split(".");
+    if (parts[0] !== "nodesById") continue;
+    const id = parts[1];
+    if (id === undefined || out.has(id)) continue;
+    out.set(id, problem.message);
+  }
+  return out;
+}
+
+const EMPTY_SOCKETS: ReadonlySet<string> = new Set<string>();
+
+/**
+ * Build the whole canvas.
+ *
+ * GROUPS COME FIRST in the array, which is a React Flow requirement rather than
+ * a preference: a subflow child is dropped outright if its parent has not been
+ * seen yet, so a member whose group sorted after it would simply not render.
+ */
+export function buildMaterialFlow(input: MaterialFlowInput): {
+  nodes: MaterialFlowNode[];
+  edges: Edge[];
+} {
+  const { graph, materialId, path, assets, selection, problems, types } = input;
+  const scoped = nodesInScope(graph, path);
+  const connections = connectionsOf(graph);
+  const problemOf = problemsByNode(problems);
+  const selected = new Set(selection.nodeIds);
+  const selectedEdges = new Set(selection.edgeIds);
+  const { value: choices, token: choicesToken } = choicesFor(assets, graph.parameters);
+
+  const groups = scoped.filter((node) => node.kind === "group");
+  const rest = scoped.filter((node) => node.kind !== "group");
+  const nodes: MaterialFlowNode[] = [];
+
+  for (const node of [...groups, ...rest]) {
+    // A member's position is stored ABSOLUTE in the document and React Flow
+    // wants it relative to the parent, so the group's own origin is part of
+    // what this card depends on — and therefore part of its cache key.
+    const parent = node.groupId === undefined ? undefined : graph.nodesById[node.groupId];
+    const parentUsable = parent?.kind === "group" && (parent.scope ?? undefined) === (node.scope ?? undefined);
+    const origin = parentUsable ? parent.position : null;
+    const connected = connections.get(node.id) ?? EMPTY_SOCKETS;
+    const problem = problemOf.get(node.id) ?? null;
+    const isSelected = selected.has(node.id);
+    const spec = materialGraphNodeSpec(node.kind);
+    const sockets = spec === null ? { inputs: [], outputs: [] } : materialGraphNodeSockets(graph, node);
+    const outputType =
+      sockets.outputs[0] === undefined ? null : types.outputTypeOf(node.id, sockets.outputs[0].id);
+    const parameter = node.parameterId === undefined ? undefined : graph.parameters[node.parameterId];
+    const assetLabel =
+      node.assetId === undefined
+        ? undefined
+        : (assets[node.assetId]?.path.split("/").pop() ?? node.assetId);
+
+    const key = [
+      isSelected ? "1" : "0",
+      [...connected].sort().join(","),
+      origin === null ? "-" : `${origin[0]},${origin[1]}`,
+      problem ?? "",
+      outputType ?? "",
+      parameter === undefined ? "" : `${parameter.id}:${parameter.label}:${parameter.type}`,
+      assetLabel ?? "",
+      String(choicesToken),
+      // Dynamic sockets belong to the function, not the node — a rename of a
+      // function input changes this card and nothing about `node`.
+      sockets.inputs.map((s) => `${s.id}:${s.type}`).join("|"),
+      sockets.outputs.map((s) => `${s.id}:${s.type}`).join("|"),
+    ].join("
");
+
+    const hit = FLOW_CACHE.get(node);
+    if (hit !== undefined && hit.key === key) {
+      nodes.push(hit.flow);
+      continue;
+    }
+    if (spec === null) continue;
+
+    const data: MaterialFlowData = {
+      materialId,
+      path,
+      node,
+      spec,
+      inputs: sockets.inputs,
+      outputs: sockets.outputs,
+      connected,
+      parameter,
+      assetLabel,
+      outputType,
+      problem,
+      choices,
+    };
+    const flow: MaterialFlowNode = {
+      id: node.id,
+      type: flowTypeOf(node),
+      position:
+        origin === null
+          ? { x: node.position[0], y: node.position[1] }
+          : { x: node.position[0] - origin[0], y: node.position[1] - origin[1] },
+      selected: isSelected,
+      data,
+      ...(origin === null ? {} : { parentId: node.groupId! }),
+      ...(node.kind === "group" || node.kind === "comment"
+        ? { style: { width: node.size?.[0] ?? 240, height: node.size?.[1] ?? 160 } }
+        : {}),
+    };
+    FLOW_CACHE.set(node, { key, flow });
+    nodes.push(flow);
+  }
+
+  const edges: Edge[] = [];
+  const inScope = new Set(scoped.map((node) => node.id));
+  for (const edge of graph.edges) {
+    // An edge is drawn only when BOTH ends are on this canvas. A cross-scope
+    // wire cannot exist (`canConnect` refuses one), so this is really "the
+    // other scope's wires stay in the other scope".
+    if (!inScope.has(edge.source.nodeId) || !inScope.has(edge.target.nodeId)) continue;
+    const key = selectedEdges.has(edge.id) ? "1" : "0";
+    const hit = EDGE_CACHE.get(edge);
+    if (hit !== undefined && hit.key === key) {
+      edges.push(hit.edge);
+      continue;
+    }
+    const flow: Edge = {
+      id: edge.id,
+      source: edge.source.nodeId,
+      sourceHandle: edge.source.socket,
+      target: edge.target.nodeId,
+      targetHandle: edge.target.socket,
+      type: "smoothstep",
+      className: "material-edge",
+      selected: key === "1",
+      reconnectable: true,
+    };
+    EDGE_CACHE.set(edge, { key, edge: flow });
+    edges.push(flow);
+  }
+
+  return { nodes, edges };
+}
+
+/**
+ * A dragged React Flow node's position, back in DOCUMENT coordinates.
+ *
+ * The one place the subflow offset is undone. Doing it at each call site is how
+ * a group member ends up saved at its group-relative position and jumps to the
+ * top-left corner of the box on the next load.
+ */
+export function graphPositionOf(
+  flow: { position: { x: number; y: number }; parentId?: string | undefined },
+  graph: MaterialGraph3D,
+): [number, number] {
+  const parent = flow.parentId === undefined ? undefined : graph.nodesById[flow.parentId];
+  if (parent === undefined) return [Math.round(flow.position.x), Math.round(flow.position.y)];
+  return [
+    Math.round(flow.position.x + parent.position[0]),
+    Math.round(flow.position.y + parent.position[1]),
+  ];
+}
+
+export interface FlowRect {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * Does the segment a→b cross the rect?
+ *
+ * Liang–Barsky, which answers "does it cross" without computing where — the
+ * canvas only needs the boolean, once per edge per pointer frame. The two
+ * degenerate cases matter and are handled: a segment PARALLEL to a slab is in
+ * only if it already lies inside it, and a zero-length segment reduces to a
+ * point test.
+ */
+export function segmentIntersectsRect(
+  a: { x: number; y: number },
+  b: { x: number; y: number },
+  rect: FlowRect,
+): boolean {
+  const dx = b.x - a.x;
+  const dy = b.y - a.y;
+  let t0 = 0;
+  let t1 = 1;
+  const slabs: readonly [number, number][] = [
+    [-dx, a.x - rect.x],
+    [dx, rect.x + rect.width - a.x],
+    [-dy, a.y - rect.y],
+    [dy, rect.y + rect.height - a.y],
+  ];
+  for (const [p, q] of slabs) {
+    if (p === 0) {
+      // Parallel to this slab: outside it means it can never enter.
+      if (q < 0) return false;
+      continue;
+    }
+    const r = q / p;
+    if (p < 0) {
+      if (r > t1) return false;
+      if (r > t0) t0 = r;
+    } else {
+      if (r < t0) return false;
+      if (r < t1) t1 = r;
+    }
+  }
+  return true;
+}
+
+/** A group box's document rect. Mirrors the fallback `buildMaterialFlow` uses
+ *  when a box carries no size, so the picture and the hit test agree. */
+function groupRect(node: MaterialGraphNode): FlowRect {
+  return {
+    x: node.position[0],
+    y: node.position[1],
+    width: node.size?.[0] ?? 240,
+    height: node.size?.[1] ?? 160,
+  };
+}
+
+/**
+ * The group box under a DOCUMENT point, or null.
+ *
+ * SMALLEST AREA WINS. Boxes do not nest in schema v17, but two of them can
+ * still overlap because nothing stops an author dragging one over another, and
+ * "the one I am pointing at" is the tighter of the two every time. Ties break
+ * on id so a drop is not decided by object order.
+ */
+export function groupUnderPoint(
+  graph: MaterialGraph3D,
+  path: readonly string[],
+  point: readonly [number, number],
+): string | null {
+  const scope = path.length === 0 ? undefined : path[path.length - 1];
+  let best: { id: string; area: number } | null = null;
+  for (const node of Object.values(graph.nodesById)) {
+    if (node.kind !== "group") continue;
+    if ((node.scope ?? undefined) !== scope) continue;
+    const rect = groupRect(node);
+    if (point[0] < rect.x || point[0] > rect.x + rect.width) continue;
+    if (point[1] < rect.y || point[1] > rect.y + rect.height) continue;
+    const area = rect.width * rect.height;
+    if (best === null || area < best.area || (area === best.area && node.id < best.id)) {
+      best = { id: node.id, area };
+    }
+  }
+  return best === null ? null : best.id;
+}

package/src/panels/material/parameterValues.ts

@@ -0,0 +1,231 @@
+// ONE GRAPH PARAMETER'S VALUES ON EVERY MESH THAT WEARS THE GRAPH: the per-mesh
+// override and the keyframe track, on the whole model's binding and on each
+// submesh slot that binds the graph.
+//
+// A reusable graph's parameter is edited in one place and lives in many: each
+// mesh binding the graph may override it, and may animate it on a track at the
+// binding's own path (`materialGraphParamPath(id, slot)`). Two edits of the
+// parameter reach all of them at once and must agree about where they are:
+// deleting it (every override and track that names it goes too, or the save
+// refuses the orphans) and narrowing its range (a value left outside the new
+// range is refused by the save as well). Both walk the bindings here, so a
+// slot binding is never the one the walk forgot. Pure and React-free.
+import { valueEquals } from "@dailies-studio/engine";
+import type { Value } from "@dailies-studio/engine";
+import {
+  isGraphMaterial,
+  isMaterialGraphValueForType,
+  materialGraphParamPath,
+  parseMaterialSlotKey,
+} from "@dailies-studio/shot/doc";
+import type {
+  Doc3D,
+  Layer3D,
+  MaterialGraphBinding,
+  MaterialGraphParameter,
+  MaterialGraphValue,
+  ShotTrack,
+  ShotTracks,
+} from "@dailies-studio/shot/doc";
+
+/** One binding's half of a parameter: its override and its track. */
+export interface ParameterValues {
+  override: MaterialGraphValue | undefined;
+  track: ShotTrack | undefined;
+}
+
+/** A new override and track for a binding's old ones. Returning the inputs
+ *  (by identity) changes nothing; undefined drops that half. */
+type Rewrite = (values: ParameterValues) => ParameterValues;
+
+type Overrides = Record<string, MaterialGraphValue> | undefined;
+
+function rewriteLayer(layer: Layer3D, materialId: string, parameterId: string, rewrite: Rewrite): Layer3D {
+  if (layer.kind !== "mesh" || !isGraphMaterial(layer.mesh.material)) return layer;
+  const binding = layer.mesh.material;
+  let tracks: ShotTracks | undefined = layer.tracks;
+  let tracksMoved = false;
+
+  /** The binding's overrides after the rewrite (the same object when its
+   *  override did not move), with the track written into `tracks`. */
+  const visit = (slot: number | null, overrides: Overrides): Overrides => {
+    const path = materialGraphParamPath(parameterId, slot);
+    const before: ParameterValues = { override: overrides?.[parameterId], track: tracks?.[path] };
+    const after = rewrite(before);
+    if (after.track !== before.track) {
+      const next: ShotTracks = { ...tracks };
+      if (after.track === undefined) delete next[path];
+      else next[path] = after.track;
+      tracks = Object.keys(next).length === 0 ? undefined : next;
+      tracksMoved = true;
+    }
+    if (after.override === before.override) return overrides;
+    const next = { ...overrides };
+    if (after.override === undefined) delete next[parameterId];
+    else next[parameterId] = after.override;
+    return Object.keys(next).length === 0 ? undefined : next;
+  };
+
+  let material: MaterialGraphBinding = binding;
+  // The whole model's binding, only when it is THIS graph: another graph may
+  // hold a parameter with the same id, and its path is this one's too.
+  if (binding.materialId === materialId) {
+    const overrides = visit(null, binding.overrides);
+    if (overrides !== binding.overrides) {
+      const { overrides: _old, ...rest } = binding;
+      material = overrides === undefined ? rest : { ...rest, overrides };
+    }
+  }
+  if (binding.slots !== undefined) {
+    let slots = binding.slots;
+    for (const key of Object.keys(binding.slots)) {
+      const index = parseMaterialSlotKey(key);
+      const slot = Object.prototype.hasOwnProperty.call(binding.slots, key) ? binding.slots[key] : undefined;
+      if (index === null || slot === undefined || slot.materialId !== materialId) continue;
+      const overrides = visit(index, slot.overrides);
+      if (overrides === slot.overrides) continue;
+      if (slots === binding.slots) slots = { ...binding.slots };
+      slots[key] = overrides === undefined ? { materialId: slot.materialId } : { materialId: slot.materialId, overrides };
+    }
+    if (slots !== binding.slots) material = { ...material, slots };
+  }
+
+  if (material === binding && !tracksMoved) return layer;
+  const next: Layer3D = { ...layer, mesh: { ...layer.mesh, material } };
+  if (!tracksMoved) return next;
+  if (tracks !== undefined) return { ...next, tracks };
+  const { tracks: _dropped, ...bare } = next;
+  return bare as Layer3D;
+}
+
+function rewriteLayers(
+  layers: Readonly<Record<string, Layer3D>>,
+  materialId: string,
+  parameterId: string,
+  rewrite: Rewrite,
+): Readonly<Record<string, Layer3D>> {
+  let out: Record<string, Layer3D> | null = null;
+  for (const [id, layer] of Object.entries(layers)) {
+    const next = rewriteLayer(layer, materialId, parameterId, rewrite);
+    if (next === layer) continue;
+    out ??= { ...layers };
+    out[id] = next;
+  }
+  return out ?? layers;
+}
+
+/**
+ * The document with `rewrite` applied to one parameter's override and track
+ * on every binding of `materialId`, in every Shot and every definition. The
+ * same document when nothing moved.
+ */
+export function rewriteParameterValues(doc: Doc3D, materialId: string, parameterId: string, rewrite: Rewrite): Doc3D {
+  let scenesById: Doc3D["scenesById"] | null = null;
+  for (const [id, scene] of Object.entries(doc.scenesById)) {
+    const layersById = rewriteLayers(scene.layersById, materialId, parameterId, rewrite);
+    if (layersById === scene.layersById) continue;
+    scenesById ??= { ...doc.scenesById };
+    scenesById[id] = { ...scene, layersById: layersById as Record<string, Layer3D> };
+  }
+  let components: NonNullable<Doc3D["components"]> | null = null;
+  for (const [id, def] of Object.entries(doc.components ?? {})) {
+    const layersById = rewriteLayers(def.layersById, materialId, parameterId, rewrite);
+    if (layersById === def.layersById) continue;
+    components ??= { ...doc.components };
+    components[id] = { ...def, layersById: layersById as Record<string, Layer3D> };
+  }
+  if (scenesById === null && components === null) return doc;
+  return { ...doc, ...(scenesById === null ? {} : { scenesById }), ...(components === null ? {} : { components }) };
+}
+
+/** A float parameter's range; an absent end is open. */
+export interface ParameterRange {
+  min?: number;
+  max?: number;
+}
+
+function clampTo(value: number, range: ParameterRange): number {
+  return Math.max(range.min ?? -Infinity, Math.min(range.max ?? Infinity, value));
+}
+
+function outside(value: unknown, range: ParameterRange): boolean {
+  return typeof value === "number" && clampTo(value, range) !== value;
+}
+
+/** How many per-mesh values (overrides and keyframes) of a float parameter
+ *  sit outside `range`: what a narrowed range would leave the save to refuse. */
+export function valuesOutsideRange(doc: Doc3D, materialId: string, parameterId: string, range: ParameterRange): number {
+  let count = 0;
+  rewriteParameterValues(doc, materialId, parameterId, (values) => {
+    if (outside(values.override, range)) count += 1;
+    for (const key of values.track?.keyframes ?? []) if (outside(key.value, range)) count += 1;
+    return values;
+  });
+  return count;
+}
+
+/** A parameter with its range set (an absent end is open) and its default
+ *  moved inside it, which the graph's own check requires. The same object
+ *  when nothing moves. */
+export function withParameterRange(parameter: MaterialGraphParameter, range: ParameterRange): MaterialGraphParameter {
+  const fallback =
+    typeof parameter.default === "number" ? clampTo(parameter.default, range) : parameter.default;
+  if (parameter.min === range.min && parameter.max === range.max && fallback === parameter.default) return parameter;
+  const { min: _min, max: _max, ...rest } = parameter;
+  return {
+    ...rest,
+    ...(range.min === undefined ? {} : { min: range.min }),
+    ...(range.max === undefined ? {} : { max: range.max }),
+    default: fallback,
+  };
+}
+
+/**
+ * A parameter's DEFAULT written for the length of a drag: the narrow pure
+ * write a scrub re-derives from its base on every move (`writeMaterialNodeValue`'s
+ * precedent). It types the value by the parameter and keeps a float inside its
+ * range, so it can never change the graph's shape or break its own check; a
+ * typed value crosses `updateProjectMaterial`'s validated door instead.
+ */
+export function writeParameterDefault(
+  doc: Doc3D,
+  materialId: string,
+  parameterId: string,
+  value: unknown,
+): Doc3D {
+  const graph = doc.materials?.[materialId];
+  if (graph === undefined || !Object.prototype.hasOwnProperty.call(graph.parameters, parameterId)) return doc;
+  const parameter = graph.parameters[parameterId]!;
+  if (!isMaterialGraphValueForType(value, parameter.type)) return doc;
+  const next: MaterialGraphValue =
+    typeof value === "number"
+      ? clampTo(value, {
+          ...(parameter.min === undefined ? {} : { min: parameter.min }),
+          ...(parameter.max === undefined ? {} : { max: parameter.max }),
+        })
+      : value;
+  if (valueEquals(parameter.default as Value, next as Value)) return doc;
+  return {
+    ...doc,
+    materials: {
+      ...doc.materials,
+      [materialId]: { ...graph, parameters: { ...graph.parameters, [parameterId]: { ...parameter, default: next } } },
+    },
+  };
+}
+
+/** The document with every per-mesh override and keyframe value of a float
+ *  parameter clamped into `range`. */
+export function clampParameterValues(doc: Doc3D, materialId: string, parameterId: string, range: ParameterRange): Doc3D {
+  return rewriteParameterValues(doc, materialId, parameterId, ({ override, track }) => {
+    const clampedOverride = typeof override === "number" ? clampTo(override, range) : override;
+    let clampedTrack = track;
+    if (track !== undefined && track.keyframes.some((key) => outside(key.value, range))) {
+      clampedTrack = {
+        ...track,
+        keyframes: track.keyframes.map((key) => (outside(key.value, range) ? { ...key, value: clampTo(key.value as number, range) } : key)),
+      };
+    }
+    return { override: clampedOverride, track: clampedTrack };
+  });
+}