@untangle-code/cli 0.0.0-stage → 0.1.1

package/src/commands/graph/feature-map.ts

@@ -0,0 +1,270 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, open, realpath, rm, rmdir, stat } from "node:fs/promises";
+import path from "node:path";
+
+import { analyzeProductAlignment } from "@untangle-code/core";
+import { canonicalJson, sha256Hex, type ProductAlignmentReportV1 } from "@untangle-code/domain";
+import { discoverFiles } from "@untangle-code/scanner";
+import { NodeFileSystem } from "@untangle-code/scanner/node-fs";
+
+import { enumFlag, integerFlag, stringFlag, type ParsedArgs } from "../../cli/args.js";
+import type { CommandContext } from "../../cli/command.js";
+import { UsageError } from "../../cli/exit.js";
+import { line, note } from "../../cli/io.js";
+
+import { createFeatureMapHtml } from "./feature-html.js";
+import {
+  buildFeatureMapGraph,
+  featureMapLimits,
+  type FeatureMapGraphV1,
+  type FeatureMapLimitsV1,
+} from "./feature-model.js";
+
+export interface FeatureMapOptionsV1 extends FeatureMapLimitsV1 {
+  root: string;
+  manifestPath?: string;
+  testEvidencePath?: string;
+  signal?: AbortSignal;
+}
+export interface FeatureMapWriteResultV1 {
+  schemaVersion: 1;
+  kind: "feature_map_artifact";
+  htmlPath: string;
+  jsonPath: string;
+  sha256: { html: string; json: string };
+  summary: FeatureMapGraphV1["summary"];
+  graph: FeatureMapGraphV1;
+  report: ProductAlignmentReportV1;
+}
+
+/** Reuse the safe scanner for a declared-feature-free census; never invent ownership or metrics. */
+async function unassignedCensus(root: string, signal?: AbortSignal): Promise<string[]> {
+  const paths: string[] = [];
+  for await (const file of discoverFiles({
+    fs: new NodeFileSystem(),
+    roots: [root],
+    repoRoot: root,
+    ignore: {
+      additionalDefaultExcludes: [
+        "/.untangle",
+        "/untangle.toml",
+        "/untangle.toml.untangle-init-tmp",
+      ],
+    },
+    ...(signal === undefined ? {} : { signal }),
+  })) {
+    signal?.throwIfAborted();
+    if (
+      file.languageId === "unknown" ||
+      file.languageId === "markdown" ||
+      /\.(?:json|toml|ya?ml|lock)$/iu.test(file.relativePath)
+    )
+      continue;
+    paths.push(file.relativePath);
+    if (paths.length >= 50_000) break;
+  }
+  return paths;
+}
+
+interface CreatedDirectory {
+  path: string;
+  ino: number;
+  dev: number;
+}
+async function metadataDirectory(
+  root: string,
+  created: CreatedDirectory[],
+  signal?: AbortSignal,
+): Promise<string> {
+  let directory = root;
+  for (const component of [".untangle", "feature-map"]) {
+    signal?.throwIfAborted();
+    directory = path.join(directory, component);
+    let made = true;
+    await mkdir(directory, { mode: 0o700 }).catch((error: unknown) => {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+      made = false;
+    });
+    const info = await lstat(directory);
+    if (!info.isDirectory() || info.isSymbolicLink() || (await realpath(directory)) !== directory)
+      throw new Error(
+        "Feature-map metadata directories must be physical in-project directories, not symlinks.",
+      );
+    if (made) created.push({ path: directory, ino: info.ino, dev: info.dev });
+  }
+  return directory;
+}
+
+async function removeEmptyOwnDirectories(created: CreatedDirectory[]): Promise<void> {
+  for (const directory of [...created].reverse()) {
+    const current = await lstat(directory.path).catch(() => null);
+    if (current?.ino === directory.ino && current.dev === directory.dev && current.isDirectory())
+      await rmdir(directory.path).catch((error: unknown) => {
+        if (
+          !["ENOENT", "ENOTEMPTY", "EEXIST"].includes((error as NodeJS.ErrnoException).code ?? "")
+        )
+          throw error;
+      });
+  }
+}
+
+async function readRegular(filePath: string): Promise<string> {
+  const handle = await open(filePath, constants.O_RDONLY | constants.O_NOFOLLOW);
+  try {
+    if (!(await handle.stat()).isFile())
+      throw new Error("Feature-map artifact must be a regular file.");
+    return await handle.readFile("utf8");
+  } finally {
+    await handle.close();
+  }
+}
+
+/** Exclusive creation preserves foreign bytes; interrupted own partial files are removed. */
+async function preserve(filePath: string, content: string, signal?: AbortSignal): Promise<boolean> {
+  signal?.throwIfAborted();
+  const handle = await open(
+    filePath,
+    constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW,
+    0o600,
+  ).catch(async (error: unknown) => {
+    if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    if ((await readRegular(filePath)) !== content)
+      throw new Error("Existing feature-map artifact differs; refusing to overwrite it.");
+    return null;
+  });
+  if (handle === null) return false;
+  try {
+    signal?.throwIfAborted();
+    await handle.writeFile(content, "utf8");
+    await handle.sync();
+    signal?.throwIfAborted();
+  } catch (error) {
+    const identity = await handle.stat();
+    const observed = await lstat(filePath).catch(() => null);
+    if (observed?.ino === identity.ino && observed.dev === identity.dev) await rm(filePath);
+    throw error;
+  } finally {
+    await handle.close();
+  }
+  return true;
+}
+
+/** Builds an index-free, source-bound artifact without executing tests or opening a browser. */
+export async function writeFeatureMap(
+  options: FeatureMapOptionsV1,
+  deps: { analyze?: typeof analyzeProductAlignment } = {},
+): Promise<FeatureMapWriteResultV1> {
+  options.signal?.throwIfAborted();
+  const limits = featureMapLimits(options);
+  const root = await realpath(path.resolve(options.root));
+  if (!(await stat(root)).isDirectory())
+    throw new TypeError("Feature-map root must be a directory.");
+  // Own metadata exists before the census, so its excluded-directory event is
+  // stable on the second run; every measurement and source digest remains raw.
+  const createdDirectories: CreatedDirectory[] = [];
+  try {
+    const directory = await metadataDirectory(root, createdDirectories, options.signal);
+    const report = await (deps.analyze ?? analyzeProductAlignment)({
+      root,
+      ...(options.manifestPath === undefined
+        ? {}
+        : { manifestPath: path.resolve(root, options.manifestPath) }),
+      ...(options.testEvidencePath === undefined
+        ? {}
+        : { testEvidencePath: path.resolve(root, options.testEvidencePath) }),
+      ...(options.signal === undefined ? {} : { signal: options.signal }),
+    });
+    options.signal?.throwIfAborted();
+    const unassigned =
+      report.status === "needs_manifest" ? await unassignedCensus(root, options.signal) : [];
+    if (unassigned.length > 0) {
+      const current = await (deps.analyze ?? analyzeProductAlignment)({
+        root,
+        ...(options.manifestPath === undefined
+          ? {}
+          : { manifestPath: path.resolve(root, options.manifestPath) }),
+        ...(options.signal === undefined ? {} : { signal: options.signal }),
+      });
+      if (current.sourceTreeDigest !== report.sourceTreeDigest)
+        throw new Error(
+          "Project sources changed while collecting unassigned file paths; regenerate the feature map.",
+        );
+    }
+    const graph = buildFeatureMapGraph(report, limits, unassigned);
+    const json =
+      JSON.stringify({ schemaVersion: 1, kind: "feature_map_snapshot", graph, report }, null, 2) +
+      "\n";
+    const html = createFeatureMapHtml(graph);
+    const digest = sha256Hex(canonicalJson({ json, html }));
+    const prefix = path.join(directory, `feature-map-${digest.slice(0, 16)}`);
+    const jsonPath = `${prefix}.json`,
+      htmlPath = `${prefix}.html`;
+    let createdJson = false;
+    let createdHtml = false;
+    try {
+      createdJson = await preserve(jsonPath, json, options.signal);
+      createdHtml = await preserve(htmlPath, html, options.signal);
+      options.signal?.throwIfAborted();
+    } catch (error) {
+      if (createdHtml && (await readRegular(htmlPath).catch(() => null)) === html)
+        await rm(htmlPath);
+      if (createdJson && (await readRegular(jsonPath).catch(() => null)) === json)
+        await rm(jsonPath);
+      throw error;
+    }
+    return {
+      schemaVersion: 1,
+      kind: "feature_map_artifact",
+      htmlPath,
+      jsonPath,
+      sha256: { html: sha256Hex(html), json: sha256Hex(json) },
+      summary: graph.summary,
+      graph,
+      report,
+    };
+  } catch (error) {
+    await removeEmptyOwnDirectories(createdDirectories);
+    throw error;
+  }
+}
+
+/** `graph features`: deliberately bypasses stored-graph loading and all service probes. */
+export async function runFeatureMap(ctx: CommandContext, args: ParsedArgs): Promise<number> {
+  if (args.positionals.length !== 0)
+    throw new UsageError("graph features accepts no additional positional arguments.");
+  const format = enumFlag(args, "format", ["text", "json"] as const, "text");
+  const root = path.resolve(ctx.cwd, stringFlag(args, "root") ?? ".");
+  const manifestPath = stringFlag(args, "feature-map");
+  const testEvidencePath = stringFlag(args, "test-evidence");
+  const maxNodes = integerFlag(args, "max-nodes", 500),
+    maxEdges = integerFlag(args, "max-edges", 2_000);
+  try {
+    featureMapLimits({ maxNodes, maxEdges });
+  } catch (error) {
+    throw new UsageError((error as Error).message);
+  }
+  const result = await writeFeatureMap({
+    root,
+    maxNodes,
+    maxEdges,
+    signal: ctx.signal,
+    ...(manifestPath === undefined ? {} : { manifestPath }),
+    ...(testEvidencePath === undefined ? {} : { testEvidencePath }),
+  });
+  if (format === "json") line(ctx.io, JSON.stringify(result, null, 2));
+  else {
+    line(ctx.io, result.htmlPath);
+    note(
+      ctx.io,
+      `Feature map: ${result.summary.features} declared features, ${result.summary.shownNodes}/${result.summary.totalNodes} nodes, ${result.summary.shownEdges}/${result.summary.totalEdges} edges; ${result.summary.status}.`,
+    );
+    note(ctx.io, `Complete report: ${result.jsonPath}`);
+    note(
+      ctx.io,
+      "Open the local HTML file in a browser. No index, service, network request or test execution is required.",
+    );
+    if (result.summary.truncated)
+      note(ctx.io, "Bounded diagram; complete feature metrics remain in the JSON report.");
+  }
+  return 0;
+}

package/src/commands/graph/feature-model.ts

@@ -0,0 +1,234 @@
+import {
+  canonicalJson,
+  compareCodepoints,
+  uuidv5,
+  type ProductAlignmentReportV1,
+} from "@untangle-code/domain";
+
+export type FeatureMapNodeKind = "feature" | "code" | "test" | "owner" | "intent" | "unmapped";
+export type FeatureMapEdgeKind = "code" | "test" | "ownership" | "intent" | "dependency";
+export interface FeatureMapNodeV1 {
+  id: string;
+  kind: FeatureMapNodeKind;
+  label: string;
+  path?: string;
+  status: string;
+  cognitive?: number;
+  details: Record<string, unknown>;
+}
+export interface FeatureMapEdgeV1 {
+  id: string;
+  from: string;
+  to: string;
+  kind: FeatureMapEdgeKind;
+}
+export interface FeatureMapSummaryV1 {
+  status: ProductAlignmentReportV1["status"];
+  features: number;
+  shownNodes: number;
+  totalNodes: number;
+  shownEdges: number;
+  totalEdges: number;
+  truncated: boolean;
+  mappedCodeFiles: number;
+  unmappedCodeFiles: number;
+  inventoryFiles: number;
+}
+export interface FeatureMapGraphV1 {
+  schemaVersion: 1;
+  sourceTreeDigest: string;
+  nodes: FeatureMapNodeV1[];
+  edges: FeatureMapEdgeV1[];
+  summary: FeatureMapSummaryV1;
+  limits: { maxNodes: number; maxEdges: number };
+  limitations: string[];
+  issues: string[];
+  dependencyCycles: string[][];
+}
+export interface FeatureMapLimitsV1 {
+  maxNodes?: number;
+  maxEdges?: number;
+}
+
+export function featureMapLimits(input: FeatureMapLimitsV1): {
+  maxNodes: number;
+  maxEdges: number;
+} {
+  const maxNodes = input.maxNodes ?? 500;
+  const maxEdges = input.maxEdges ?? 2_000;
+  if (!Number.isInteger(maxNodes) || maxNodes < 1 || maxNodes > 2_000)
+    throw new RangeError("maxNodes must be an integer between 1 and 2000.");
+  if (!Number.isInteger(maxEdges) || maxEdges < 1 || maxEdges > 10_000)
+    throw new RangeError("maxEdges must be an integer between 1 and 10000.");
+  return { maxNodes, maxEdges };
+}
+
+function identity(kind: string, key: string): string {
+  return uuidv5(canonicalJson({ surface: "feature-map-v1", kind, key }));
+}
+
+/** Relations are declarations/evidence, never inferred semantic or runtime calls. */
+export function buildFeatureMapGraph(
+  report: ProductAlignmentReportV1,
+  input: FeatureMapLimitsV1 = {},
+  unassignedPaths: readonly string[] = [],
+): FeatureMapGraphV1 {
+  const limits = featureMapLimits(input);
+  const nodes = new Map<string, FeatureMapNodeV1>();
+  const edges = new Map<string, FeatureMapEdgeV1>();
+  const addNode = (
+    kind: FeatureMapNodeKind,
+    key: string,
+    data: Omit<FeatureMapNodeV1, "kind" | "id">,
+  ): string => {
+    const id = identity(kind === "test" ? "code" : kind, key);
+    const existing = nodes.get(id);
+    // A file selected as both code and test keeps one identity and both role facts.
+    if (existing !== undefined && (kind === "code" || kind === "test")) {
+      const roles = new Set([...(existing.details["roles"] as string[]), kind]);
+      existing.details["roles"] = [...roles].sort(compareCodepoints);
+    } else if (existing === undefined) nodes.set(id, { id, kind, ...data });
+    return id;
+  };
+  const addEdge = (from: string, to: string, kind: FeatureMapEdgeKind): void => {
+    const id = identity("edge", canonicalJson({ from, to, kind }));
+    edges.set(id, { id, from, to, kind });
+  };
+  const features = [...report.features].sort((a, b) => compareCodepoints(a.id, b.id));
+  for (const feature of features) {
+    addNode("feature", feature.id, {
+      label: feature.title,
+      status: feature.status,
+      ...(feature.code.metrics === null
+        ? {}
+        : { cognitive: feature.code.metrics.cognitive.execution_unit }),
+      details: {
+        featureId: feature.id,
+        stage: feature.stage,
+        review: feature.review,
+        codeComplete: feature.code.complete,
+        testComplete: feature.tests.complete,
+        metrics: feature.code.metrics,
+        testMetrics: feature.tests.metrics,
+        testEvidence: feature.testEvidence,
+        dimensions: feature.dimensions,
+        criteria: feature.criteria,
+        hotspots: feature.code.hotspots,
+        agentHints: feature.agentHints,
+        issues: feature.issues,
+      },
+    });
+  }
+  for (const feature of features) {
+    const featureId = identity("feature", feature.id);
+    for (const owner of feature.ownership) {
+      const ownerId = addNode("owner", owner.id, {
+        label: owner.label ?? owner.id,
+        status: owner.status,
+        details: {
+          ownerId: owner.id,
+          authority: report.ownershipAuthority,
+          sources: owner.sources,
+        },
+      });
+      addEdge(featureId, ownerId, "ownership");
+    }
+    for (const intent of feature.intent) {
+      const intentId = addNode(
+        "intent",
+        canonicalJson({ path: intent.path, heading: intent.heading }),
+        {
+          label: intent.heading || intent.path,
+          path: intent.path,
+          status: intent.status,
+          details: {
+            role: intent.role,
+            heading: intent.heading,
+            contentHash: intent.contentHash,
+            startLine: intent.startLine,
+            endLine: intent.endLine,
+          },
+        },
+      );
+      addEdge(featureId, intentId, "intent");
+    }
+    for (const role of ["code", "test"] as const) {
+      const selection = role === "code" ? feature.code : feature.tests;
+      for (const file of selection.files) {
+        const fileId = addNode(role, file.path, {
+          label: file.path,
+          path: file.path,
+          status: file.status,
+          details: {
+            roles: [role],
+            contentHash: file.contentHash,
+            sharedFeatures:
+              report.coverage.sharedFiles.find((shared) => shared.path === file.path)?.featureIds ??
+              [],
+          },
+        });
+        addEdge(featureId, fileId, role);
+      }
+    }
+    for (const dependency of feature.dependsOn) {
+      const target = identity("feature", dependency);
+      if (nodes.has(target)) addEdge(featureId, target, "dependency");
+    }
+  }
+  const unmapped = [...new Set([...report.coverage.unmappedCodeFiles, ...unassignedPaths])].sort(
+    compareCodepoints,
+  );
+  for (const filePath of unmapped) {
+    // The fallback census is not an AST measurement and does not imply a feature.
+    if (nodes.has(identity("code", filePath))) continue;
+    addNode("unmapped", filePath, {
+      label: filePath,
+      path: filePath,
+      status: "unmapped",
+      details: { featureAssignment: "none", measurement: "not_provided_by_feature_report" },
+    });
+  }
+  const allNodes = [...nodes.values()];
+  const shownNodes = allNodes.slice(0, limits.maxNodes);
+  const visible = new Set(shownNodes.map((node) => node.id));
+  const allEdges = [...edges.values()].sort((a, b) => compareCodepoints(a.id, b.id));
+  const shownEdges = allEdges
+    .filter((edge) => visible.has(edge.from) && visible.has(edge.to))
+    .slice(0, limits.maxEdges);
+  return {
+    schemaVersion: 1,
+    sourceTreeDigest: report.sourceTreeDigest,
+    nodes: shownNodes,
+    edges: shownEdges,
+    summary: {
+      status: report.status,
+      features: report.features.length,
+      shownNodes: shownNodes.length,
+      totalNodes: allNodes.length,
+      shownEdges: shownEdges.length,
+      totalEdges: allEdges.length,
+      truncated:
+        shownNodes.length < allNodes.length ||
+        shownEdges.length < allEdges.length ||
+        report.inventory.truncated,
+      mappedCodeFiles: report.coverage.mappedCodeFiles,
+      unmappedCodeFiles: Math.max(report.coverage.unmappedCodeFileCount, unmapped.length),
+      inventoryFiles: report.inventory.files,
+    },
+    limits,
+    issues: report.issues,
+    dependencyCycles: report.dependencyCycles,
+    limitations: [
+      ...report.limitations,
+      "Only declared feature, code/test, intent and ownership relations are drawn. Feature dependency edges are not code imports or runtime calls.",
+      "Node size represents complete feature cognitive execution_unit complexity only when measured. File sizes do not claim file complexity.",
+      "The diagram is a bounded source snapshot. Filtered or omitted nodes never reduce the complete feature metrics in the report.",
+      "Spatial positions, depth and thread curvature are visualization choices, not semantic similarity, coupling scores or additional relationships.",
+      ...(unassignedPaths.length === 0
+        ? []
+        : [
+            "Unassigned paths come from an accepted scanner census; they carry no inferred feature, owner or AST metric.",
+          ]),
+    ],
+  };
+}

package/src/commands/graph/feature-untangle-motion.ts

@@ -0,0 +1,192 @@
+import type { FeaturePoint3D } from "./feature-3d.js";
+
+export interface FeatureUntangleState {
+  phase: "idle" | "running" | "paused" | "complete";
+  target: "wool" | "clusters";
+  progress: number;
+}
+
+export interface FeatureUntangleTransition {
+  from: Readonly<Record<string, FeaturePoint3D>>;
+  to: Readonly<Record<string, FeaturePoint3D>>;
+  fromAmount: number;
+  toAmount: number;
+  target: "wool" | "clusters";
+}
+
+export interface FeatureUntangleMotionOptions {
+  requestFrame?: (callback: (timestamp: number) => void) => number;
+  cancelFrame?: (id: number) => void;
+  reducedMotion: () => boolean;
+  visible: () => boolean;
+  onFrame: (positions: Record<string, FeaturePoint3D>, clusterAmount: number) => void;
+  onState: (state: FeatureUntangleState) => void;
+  durationMs?: number;
+  frameIntervalMs?: number;
+}
+
+/** Self-contained for the offline viewer's CSP-hashed serialized runtime. */
+export function createFeatureUntangleMotion(options: FeatureUntangleMotionOptions) {
+  const duration = Math.max(1, options.durationMs ?? 2600);
+  const interval = Math.max(33, Math.min(160, options.frameIntervalMs ?? 33));
+  if (!Number.isFinite(duration) || !Number.isFinite(interval))
+    throw new RangeError("Untangling requires bounded timing.");
+  let phase: FeatureUntangleState["phase"] = "idle";
+  let target: FeatureUntangleState["target"] = "clusters";
+  let transition: FeatureUntangleTransition | null = null;
+  let elapsed = 0;
+  let lastTimestamp: number | null = null;
+  let lastPaint = -Infinity;
+  let frame: number | null = null;
+  let generation = 0;
+
+  function getState(): FeatureUntangleState {
+    return { phase, target, progress: Math.min(1, elapsed / duration) };
+  }
+
+  function announce() {
+    options.onState(getState());
+  }
+
+  function clearFrame() {
+    generation += 1;
+    if (frame !== null) options.cancelFrame?.(frame);
+    frame = null;
+    lastTimestamp = null;
+  }
+
+  function render(progress: number) {
+    if (!transition) return;
+    const eased = 1 - (1 - progress) ** 3;
+    const positions: Record<string, FeaturePoint3D> = Object.create(null) as Record<
+      string,
+      FeaturePoint3D
+    >;
+    for (const id of Object.keys(transition.from)) {
+      const from = transition.from[id]!;
+      const to = transition.to[id]!;
+      positions[id] =
+        progress === 1
+          ? { ...to }
+          : progress === 0
+            ? { ...from }
+            : {
+                x: from.x + (to.x - from.x) * eased,
+                y: from.y + (to.y - from.y) * eased,
+                z: from.z + (to.z - from.z) * eased,
+              };
+    }
+    try {
+      options.onFrame(
+        positions,
+        transition.fromAmount + (transition.toAmount - transition.fromAmount) * eased,
+      );
+    } catch (error) {
+      clearFrame();
+      phase = "paused";
+      announce();
+      throw error;
+    }
+  }
+
+  function schedule() {
+    if (phase !== "running" || frame !== null || !options.requestFrame) return;
+    const token = generation;
+    frame = options.requestFrame((timestamp) => {
+      if (token !== generation || phase !== "running") return;
+      frame = null;
+      if (options.reducedMotion()) {
+        finish();
+        return;
+      }
+      if (!options.visible()) {
+        pause();
+        return;
+      }
+      if (lastTimestamp !== null) elapsed += Math.max(0, timestamp - lastTimestamp);
+      lastTimestamp = timestamp;
+      if (elapsed >= duration) {
+        finish();
+        return;
+      }
+      if (timestamp - lastPaint >= interval) {
+        render(elapsed / duration);
+        lastPaint = timestamp;
+      }
+      schedule();
+    });
+  }
+
+  function finish() {
+    if (!transition || phase === "complete") return;
+    clearFrame();
+    elapsed = duration;
+    phase = "complete";
+    render(1);
+    announce();
+  }
+
+  function pause() {
+    if (phase !== "running") return;
+    clearFrame();
+    phase = "paused";
+    announce();
+  }
+
+  function resume() {
+    if (phase !== "paused") return;
+    if (options.reducedMotion() || !options.requestFrame) {
+      finish();
+      return;
+    }
+    if (!options.visible()) return;
+    phase = "running";
+    announce();
+    schedule();
+  }
+
+  function cancel() {
+    clearFrame();
+    transition = null;
+    elapsed = 0;
+    phase = "idle";
+    announce();
+  }
+
+  function start(input: FeatureUntangleTransition) {
+    const ids = Object.keys(input.from).sort();
+    const targets = Object.keys(input.to).sort();
+    if (ids.length !== targets.length || ids.some((id, index) => id !== targets[index]))
+      throw new Error("Untangling must preserve every node identity.");
+    for (const collection of [input.from, input.to]) {
+      for (const point of Object.values(collection)) {
+        if (![point.x, point.y, point.z].every(Number.isFinite))
+          throw new Error("Untangling requires finite coordinates.");
+      }
+    }
+    if (
+      ![input.fromAmount, input.toAmount].every(
+        (value) => Number.isFinite(value) && value >= 0 && value <= 1,
+      )
+    )
+      throw new Error("Invalid clustering amount.");
+    clearFrame();
+    const copy = (points: Readonly<Record<string, FeaturePoint3D>>) =>
+      Object.fromEntries(Object.entries(points).map(([id, point]) => [id, { ...point }]));
+    transition = { ...input, from: copy(input.from), to: copy(input.to) };
+    elapsed = 0;
+    lastPaint = -Infinity;
+    target = input.target;
+    phase = "running";
+    if (ids.length === 0 || options.reducedMotion() || !options.requestFrame) {
+      finish();
+      return;
+    }
+    render(0);
+    if (!options.visible()) phase = "paused";
+    announce();
+    schedule();
+  }
+
+  return { start, pause, resume, finish, cancel, getState };
+}