@elabs-ai/components-process 4.1.0

package/src/abstraction-controls/abstraction-controls.tsx

@@ -0,0 +1,288 @@
+"use client";
+
+/**
+ * AbstractionControls — the two sliders every process-mining explorer opens with (RM-052,
+ * issue #227). Activities/paths abstraction is a VIEW filter, never a re-analysis
+ * (`abstractGraph`'s own contract — see `core/abstract-graph.ts`): dragging a slider hides
+ * nodes/edges, it never recomputes a statistic.
+ *
+ * Composed entirely from `@elabs-ai/components-ui` primitives — two `Slider`s, a `Switch`,
+ * a `Button` — plus the pure, framework-free `computeAutoAbstraction` heuristic. No local
+ * slider/switch/select is authored here (`pnpm process:reuse:check`).
+ *
+ * ## Controlled, not stateful
+ *
+ * This component owns no abstraction state of its own — `abstraction` is the current value,
+ * `onAbstractionChange` is how it asks for a new one. `useProcessExplorer` is the one place
+ * that actually holds the `useState` (see the compound-component "lift state into the
+ * provider" convention, `.claude/rules/component-api.md`).
+ *
+ * ## "Auto" reads the graph, not just the sliders
+ *
+ * The pre-abstraction activity total is derived, not passed as a separate prop:
+ * `graph.activities.length + hiddenCounts.activities` — the CURRENT (already-abstracted)
+ * graph's kept count plus what it currently hides always sums back to the full graph's
+ * activity count, so "Auto" needs no additional field on `useProcessExplorer`.
+ */
+import { forwardRef, useCallback, useId, type HTMLAttributes } from "react";
+import { Sparkles } from "lucide-react";
+import { Button, Label, Slider, Switch, useLocale } from "@elabs-ai/components-ui";
+import { cn } from "@elabs-ai/components-ui/lib/cn";
+import type { AbstractionOptions } from "../core/abstract-graph";
+import type { ProcessGraph } from "../core/types";
+import { computeAutoAbstraction } from "./auto-abstraction";
+
+const TICKS = [25, 50, 75, 100] as const;
+
+/**
+ * The range every tick's percent value is drawn from — the SAME `min`/`max` handed to both
+ * `Slider`s below (`min={SLIDER_MIN} max={SLIDER_MAX}`), so a tick's rail offset is always
+ * derived from the slider's own range rather than a second, independently hardcoded `0..100`
+ * (#355). Today they coincide numerically (percent === offset), but a future non-percent range
+ * stays correct because both read this one pair of constants.
+ */
+const SLIDER_MIN = 0;
+const SLIDER_MAX = 100;
+
+/** A tick's position along the rail, as a `0..100` offset — see {@link SLIDER_MIN}. */
+function tickOffsetPercent(percent: number): number {
+  return ((percent - SLIDER_MIN) / (SLIDER_MAX - SLIDER_MIN)) * 100;
+}
+
+/**
+ * How far above the "Auto" activities fraction the paths fraction is set — the roadmap's
+ * "paths % = 0.2 above the activities %" (RM-052 round 2, #227, F2 third piece). `abstractGraph`
+ * only considers an edge a candidate to keep once BOTH its endpoints survive the activities
+ * cut (`core/abstract-graph.ts`'s `candidateEdges` filter), so that candidate pool is already
+ * thinner than the full edge set once activities are cut — applying the SAME fraction to it
+ * would keep noticeably fewer edges than activities were kept. The offset compensates for
+ * that, without a second search over the real graph.
+ */
+const AUTO_PATHS_OFFSET = 0.2;
+
+function toPercent(fraction: number): number {
+  return Math.round(fraction * 100);
+}
+
+function fromPercent(percent: number): number {
+  return percent / 100;
+}
+
+export interface AbstractionControlsProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+  /** The current abstraction — both fractions, `invert`, and (read-only here) `keepConnected`. */
+  abstraction: AbstractionOptions;
+  /** Called with a PARTIAL patch — mirrors `useProcessExplorer`'s own `setAbstraction`. */
+  onAbstractionChange(next: Partial<AbstractionOptions>): void;
+  /** The CURRENT (already-abstracted) graph — only `activities.length` is read. */
+  graph: Pick<ProcessGraph, "activities">;
+  /** What the current abstraction hides, straight from `AbstractedGraph.hidden`. */
+  hiddenCounts: { activities: number; paths: number };
+  /** Node budget the "Auto" button searches for. Default `25`. */
+  autoMaxActivities?: number;
+  /** Accessible name for the control group. Default from locale. */
+  label?: string;
+}
+
+/**
+ * One clickable percentage tick — sets its slider directly rather than requiring a drag.
+ * Positioned on a `relative` rail (never spread by flexbox, #355): its centre sits at its own
+ * value's fraction of the rail, matching the `Slider` track's coordinate system directly below
+ * it. The interior ticks centre on their value (`-translate-x-1/2`); the `100%` tick right-aligns
+ * to the rail's own edge instead (`-translate-x-full`) so it is never clipped.
+ */
+function Tick({
+  percent,
+  active,
+  onSelect,
+}: {
+  percent: number;
+  active: boolean;
+  onSelect(percent: number): void;
+}) {
+  const offsetPercent = tickOffsetPercent(percent);
+  return (
+    <button
+      type="button"
+      data-slot="abstraction-controls-tick"
+      aria-pressed={active}
+      onClick={() => onSelect(percent)}
+      style={{ left: `${offsetPercent}%` }}
+      className={cn(
+        "focus-ring absolute top-0 rounded-sm text-meta text-muted-foreground transition-colors duration-fast ease-standard hover:text-foreground",
+        offsetPercent <= 0
+          ? "translate-x-0"
+          : offsetPercent >= 100
+            ? "-translate-x-full"
+            : "-translate-x-1/2",
+        active && "font-semibold text-foreground",
+      )}
+    >
+      {percent}%
+    </button>
+  );
+}
+
+export const AbstractionControls = forwardRef<HTMLDivElement, AbstractionControlsProps>(
+  function AbstractionControls(
+    {
+      abstraction,
+      onAbstractionChange,
+      graph,
+      hiddenCounts,
+      autoMaxActivities = 25,
+      label,
+      className,
+      ...props
+    },
+    ref,
+  ) {
+    const { t } = useLocale();
+    const activitiesId = useId();
+    const pathsId = useId();
+
+    const activitiesPercent = toPercent(abstraction.activities);
+    const pathsPercent = toPercent(abstraction.paths);
+
+    const setActivitiesPercent = useCallback(
+      (percent: number) => onAbstractionChange({ activities: fromPercent(percent) }),
+      [onAbstractionChange],
+    );
+    const setPathsPercent = useCallback(
+      (percent: number) => onAbstractionChange({ paths: fromPercent(percent) }),
+      [onAbstractionChange],
+    );
+
+    const handleAuto = useCallback(() => {
+      const totalActivities = graph.activities.length + hiddenCounts.activities;
+      const result = computeAutoAbstraction(totalActivities, {
+        maxActivities: autoMaxActivities,
+      });
+      onAbstractionChange({
+        activities: result.activities,
+        paths: Math.min(1, result.activities + AUTO_PATHS_OFFSET),
+      });
+    }, [graph.activities.length, hiddenCounts.activities, autoMaxActivities, onAbstractionChange]);
+
+    // Two independently-pluralized fragments, joined — `t()` selects its plural category
+    // from a single `count` var, so one activities count and one paths count cannot share
+    // a single PluralMessage. Composing two already-localized fragments is the standard
+    // way around that (see `resolveMessage` in locale-provider.tsx).
+    const hiddenSummary = `${t("process.abstractionControls.hiddenActivities", {
+      count: hiddenCounts.activities,
+    })} · ${t("process.abstractionControls.hiddenPaths", { count: hiddenCounts.paths })}`;
+
+    return (
+      <div
+        ref={ref}
+        data-slot="abstraction-controls"
+        role="group"
+        aria-label={label ?? t("process.abstractionControls.label")}
+        className={cn("flex flex-col gap-4", className)}
+        {...props}
+      >
+        <div
+          data-slot="abstraction-controls-activities"
+          role="group"
+          aria-labelledby={`${activitiesId}-label`}
+          className="flex flex-col gap-1.5"
+        >
+          <div className="flex items-center justify-between gap-2">
+            <Label id={`${activitiesId}-label`} htmlFor={activitiesId} className="text-body">
+              {t("process.abstractionControls.activities")}
+            </Label>
+            <span className="text-meta text-muted-foreground tabular-nums">
+              {activitiesPercent}%
+            </span>
+          </div>
+          <Slider
+            id={activitiesId}
+            min={SLIDER_MIN}
+            max={SLIDER_MAX}
+            step={1}
+            value={[activitiesPercent]}
+            onValueChange={([next]) => setActivitiesPercent(next ?? activitiesPercent)}
+            aria-label={t("process.abstractionControls.activities")}
+          />
+          <div className="relative h-4">
+            {TICKS.map((percent) => (
+              <Tick
+                key={percent}
+                percent={percent}
+                active={activitiesPercent === percent}
+                onSelect={setActivitiesPercent}
+              />
+            ))}
+          </div>
+        </div>
+
+        <div
+          data-slot="abstraction-controls-paths"
+          role="group"
+          aria-labelledby={`${pathsId}-label`}
+          className="flex flex-col gap-1.5"
+        >
+          <div className="flex items-center justify-between gap-2">
+            <Label id={`${pathsId}-label`} htmlFor={pathsId} className="text-body">
+              {t("process.abstractionControls.paths")}
+            </Label>
+            <span className="text-meta text-muted-foreground tabular-nums">{pathsPercent}%</span>
+          </div>
+          <Slider
+            id={pathsId}
+            min={SLIDER_MIN}
+            max={SLIDER_MAX}
+            step={1}
+            value={[pathsPercent]}
+            onValueChange={([next]) => setPathsPercent(next ?? pathsPercent)}
+            aria-label={t("process.abstractionControls.paths")}
+          />
+          <div className="relative h-4">
+            {TICKS.map((percent) => (
+              <Tick
+                key={percent}
+                percent={percent}
+                active={pathsPercent === percent}
+                onSelect={setPathsPercent}
+              />
+            ))}
+          </div>
+        </div>
+
+        <div
+          data-slot="abstraction-controls-footer"
+          className="flex items-center justify-between gap-3"
+        >
+          <div className="flex items-center gap-2">
+            <Switch
+              id={`${activitiesId}-invert`}
+              checked={abstraction.invert ?? false}
+              onCheckedChange={(checked) => onAbstractionChange({ invert: checked })}
+            />
+            <Label htmlFor={`${activitiesId}-invert`} className="text-body">
+              {t("process.abstractionControls.invert")}
+            </Label>
+          </div>
+          <Button
+            type="button"
+            variant="outline"
+            size="sm"
+            onClick={handleAuto}
+            data-slot="abstraction-controls-auto"
+          >
+            <Sparkles aria-hidden="true" />
+            {t("process.abstractionControls.auto")}
+          </Button>
+        </div>
+
+        <p
+          data-slot="abstraction-controls-hidden-summary"
+          role="status"
+          aria-live="polite"
+          className="text-meta text-muted-foreground"
+        >
+          {hiddenSummary}
+        </p>
+      </div>
+    );
+  },
+);

package/src/abstraction-controls/auto-abstraction.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, it } from "vitest";
+import { abstractGraph } from "../core/abstract-graph";
+import { generateSyntheticLog } from "../core/fixtures/synthetic-log";
+import { discoverGraph } from "../core/discover-graph";
+import type { ActivityStats, DurationStats, ProcessGraph, TransitionStats } from "../core/types";
+import { computeAutoAbstraction } from "./auto-abstraction";
+
+function keptCount(total: number, fraction: number): number {
+  return Math.max(1, Math.round(total * fraction));
+}
+
+const ZERO_DURATION: DurationStats = {
+  min: 0,
+  max: 0,
+  mean: 0,
+  median: 0,
+  p90: 0,
+  sum: 0,
+  trimmedMean: 0,
+};
+
+/**
+ * A single, unbranched activity chain — `size` activities, `size - 1` directly-follows
+ * edges, strictly decreasing frequency along the chain, NO skip/bypass paths, no loops.
+ * Neither shipped fixture reaches this module's own real >25-activity failure mode
+ * (`generateSyntheticLog`'s vocabulary is 11 activities; `generateBpi2012Subset`'s is 19),
+ * so this is a purpose-built minimal graph for it — mirrors the `largeGraph()` helper in
+ * `process-map.stories.tsx`, but WITHOUT that helper's skip-path edges, which is exactly
+ * the property this fixture needs: a bypass edge would let `abstractGraph`'s connectivity
+ * repair route AROUND a dropped activity instead of being forced to restore it.
+ */
+function chainGraph(size: number): ProcessGraph {
+  const ids = Array.from({ length: size }, (_, i) => `Step ${String(i + 1).padStart(2, "0")}`);
+  const activities: ActivityStats[] = ids.map((id, index) => ({
+    id,
+    label: id,
+    instances: size - index,
+    cases: size - index,
+    isStart: index === 0,
+    isEnd: index === size - 1,
+    duration: ZERO_DURATION,
+  }));
+  const transitions: TransitionStats[] = [];
+  for (let i = 0; i < ids.length - 1; i += 1) {
+    transitions.push({
+      source: ids[i]!,
+      target: ids[i + 1]!,
+      count: size - i,
+      caseCount: size - i,
+      duration: ZERO_DURATION,
+      isSelfLoop: false,
+      isBackEdge: false,
+    });
+  }
+  return {
+    activities,
+    transitions,
+    startActivities: { [ids[0]!]: size },
+    endActivities: { [ids[size - 1]!]: size },
+    totals: { cases: size, events: size * 2, variants: 1 },
+  };
+}
+
+describe("computeAutoAbstraction — the bound (terminates in at most maxSteps probes)", () => {
+  it("never exceeds maxSteps regardless of how large the graph is", () => {
+    const result = computeAutoAbstraction(1000, { maxActivities: 25, maxSteps: 8 });
+    expect(result.steps).toBeLessThanOrEqual(8);
+  });
+
+  it("a graph already within budget needs zero probes", () => {
+    const result = computeAutoAbstraction(10, { maxActivities: 25 });
+    expect(result).toEqual({ activities: 1, steps: 0 });
+  });
+
+  it("a graph too large even at the floor fraction needs exactly one probe", () => {
+    const result = computeAutoAbstraction(100_000, { maxActivities: 5, minFraction: 0.05 });
+    expect(result).toEqual({ activities: 0.05, steps: 1 });
+  });
+
+  it("is deterministic — the same count and options always return the same fraction", () => {
+    const first = computeAutoAbstraction(200, { maxActivities: 25 });
+    const second = computeAutoAbstraction(200, { maxActivities: 25 });
+    expect(second).toEqual(first);
+  });
+});
+
+describe("computeAutoAbstraction — the result actually fits the budget", () => {
+  it("the returned fraction keeps at most maxActivities, on a graph that needs the full search budget", () => {
+    // 200 activities, budget 25: the floor (5% -> 10 activities) fits, so the search runs
+    // its full 8 probes rather than short-circuiting on either edge case above.
+    const result = computeAutoAbstraction(200, { maxActivities: 25, maxSteps: 8 });
+    expect(result.steps).toBe(8);
+    expect(keptCount(200, result.activities)).toBeLessThanOrEqual(25);
+  });
+
+  it("converges toward the LARGEST fitting fraction, not the smallest (60-activity graph)", () => {
+    const coarse = computeAutoAbstraction(60, { maxActivities: 10, maxSteps: 2 });
+    const fine = computeAutoAbstraction(60, { maxActivities: 10, maxSteps: 8 });
+    expect(keptCount(60, coarse.activities)).toBeLessThanOrEqual(10);
+    expect(keptCount(60, fine.activities)).toBeLessThanOrEqual(10);
+    // More probes never do WORSE than fewer — the search only tightens toward the budget,
+    // it never wanders away from a fraction it already confirmed fits.
+    expect(fine.activities).toBeGreaterThanOrEqual(coarse.activities);
+    // And it isn't the degenerate "smallest fraction that fits" reading: the floor (0.05 ->
+    // 3 activities) is far below what an 8-step search settles on for a 10-activity budget.
+    expect(keptCount(60, fine.activities)).toBeGreaterThan(3);
+  });
+});
+
+describe("computeAutoAbstraction — a real, large fixture (the roadmap's 13 000-case log)", () => {
+  it("handles the 13k-case synthetic fixture's discovered graph without hanging or exceeding the bound", () => {
+    const log = generateSyntheticLog({ cases: 13_000, seed: 1 });
+    const graph = discoverGraph(log);
+    const result = computeAutoAbstraction(graph.activities.length, {
+      maxActivities: 25,
+      maxSteps: 8,
+    });
+    expect(result.steps).toBeLessThanOrEqual(8);
+    expect(keptCount(graph.activities.length, result.activities)).toBeLessThanOrEqual(25);
+    // The synthetic order-to-cash vocabulary is small (8 activities) — already inside any
+    // reasonable budget, so "Auto" is correctly a no-op here. This locks that no-op shape;
+    // it does NOT exercise the search against a graph that genuinely exceeds the budget —
+    // that is what the two describe blocks below are for.
+    expect(graph.activities.length).toBeLessThanOrEqual(25);
+    expect(result).toEqual({ activities: 1, steps: 0 });
+  });
+});
+
+describe("computeAutoAbstraction — a fixture that actually exceeds the budget (RM-052 round 2, #227, F2)", () => {
+  it("on a 30-activity chain, the naive prediction fits maxActivities exactly", () => {
+    // This is the module's own promise, restated against a real >25-activity graph rather
+    // than the always-under-budget fixture above. It is NOT a claim about `abstractGraph`'s
+    // real output — see the next describe block for why those two numbers diverge here.
+    const graph = chainGraph(30);
+    const result = computeAutoAbstraction(graph.activities.length, {
+      maxActivities: 10,
+      maxSteps: 8,
+    });
+    expect(keptCount(graph.activities.length, result.activities)).toBeLessThanOrEqual(10);
+  });
+});
+
+describe("computeAutoAbstraction — known limitation: connectivity repair can blow the naive budget (RM-052 round 2, #227, F2)", () => {
+  // `computeAutoAbstraction` predicts a fraction from activity COUNT alone; it has no
+  // visibility into the graph's TOPOLOGY. `abstractGraph`'s default `keepConnected: true`
+  // adds activities back to restore reachability to a start/end activity that truncation
+  // would otherwise strand. On a graph with no bypass edges — a strict chain, where every
+  // activity's only path to the end activity runs through every activity after it —
+  // dropping ANY suffix forces the entire remainder back in, so the real kept count can
+  // land far above what the naive prediction promised. This is a documented, accepted
+  // best-effort gap (see the module docblock), not a bug this test is asserting has been
+  // fixed — it locks the exact divergence so a future change to either `computeAutoAbstraction`
+  // or `abstractGraph`'s reconnection heuristic must consciously re-measure it.
+  it("keepConnected:true reconnects the whole chain — the real kept count blows past maxActivities", () => {
+    const graph = chainGraph(30);
+    const result = computeAutoAbstraction(graph.activities.length, {
+      maxActivities: 10,
+      maxSteps: 8,
+    });
+    expect(keptCount(graph.activities.length, result.activities)).toBeLessThanOrEqual(10);
+
+    const abstracted = abstractGraph(graph, {
+      activities: result.activities,
+      paths: 1,
+      keepConnected: true,
+    });
+
+    // The naive prediction said 10 activities would remain; connectivity repair on a
+    // graph with no bypass paths instead restores every activity in the chain.
+    expect(abstracted.activities.length).toBe(30);
+    expect(abstracted.activities.length).toBeGreaterThan(10);
+    expect(abstracted.hidden.activities).toBe(0);
+  });
+
+  it("keepConnected:false matches the naive prediction exactly — isolating connectivity repair as the sole cause", () => {
+    const graph = chainGraph(30);
+    const result = computeAutoAbstraction(graph.activities.length, {
+      maxActivities: 10,
+      maxSteps: 8,
+    });
+
+    const abstracted = abstractGraph(graph, {
+      activities: result.activities,
+      paths: 1,
+      keepConnected: false,
+    });
+
+    // With reconnection disabled, the real result matches this module's own naive mirror
+    // exactly — proving the divergence above comes SPECIFICALLY from `keepConnected`'s
+    // reachability repair, not from some more general inaccuracy in the heuristic.
+    expect(abstracted.activities.length).toBe(
+      keptCount(graph.activities.length, result.activities),
+    );
+    expect(abstracted.activities.length).toBeLessThanOrEqual(10);
+  });
+});

package/src/abstraction-controls/auto-abstraction.ts

@@ -0,0 +1,128 @@
+/**
+ * Auto abstraction heuristic — RM-052 (issue #227).
+ *
+ * The "Auto" button on {@link AbstractionControls} picks an activities fraction that fits
+ * a node budget, so a reader opens a busy graph and gets a readable one in one click
+ * instead of hand-dragging a slider. This module is pure and framework-free on purpose —
+ * it is a small, independently testable piece of judgment, not a UI concern.
+ *
+ * ## The heuristic
+ *
+ * "Smallest activities % whose graph fits the budget" is the phrase this feature is
+ * usually described by, but taken literally it is degenerate: a fraction near 0 always
+ * fits any budget, so the "smallest fraction" reading is trivially satisfied by hiding
+ * almost everything. What a reader actually wants from "Auto" is the OPPOSITE end of
+ * that: the LARGEST fraction — the most detail — that still fits the budget. This module
+ * implements that reading.
+ *
+ * ## Bounded and terminating, by construction
+ *
+ * The search is a fixed-iteration binary search over the fraction range `[minFraction,
+ * 1]` — `maxSteps` (default 8) iterations, no early-exit convergence check, no
+ * data-dependent loop bound. That makes termination a property of the `for` loop itself,
+ * not of the input: `computeAutoAbstraction` always does at most `maxSteps` probes of
+ * `keptAt(fraction)`, regardless of how many activities the graph has. See
+ * `auto-abstraction.test.ts` for the explicit bound assertion.
+ *
+ * ## Known limitation: this heuristic is topology-blind (RM-052 round 2, #227, F2)
+ *
+ * `keptActivityCount` predicts how many activities a fraction keeps from the COUNT alone —
+ * `round(total * fraction)`. It has no visibility into which activities `abstractGraph`
+ * would actually drop, or how they connect. `abstractGraph`'s default `keepConnected: true`
+ * adds activities back in to restore reachability to a start/end activity that truncation
+ * would otherwise strand — and on a graph with no bypass edges (a strict, unbranched chain,
+ * where every activity's only path to the end activity runs through every activity after
+ * it), dropping ANY suffix forces the ENTIRE remainder back in. The naive prediction and the
+ * real, reconnected result can then diverge by the graph's full size: a 30-activity chain
+ * with `maxActivities: 10` predicts a fraction that keeps 10 activities, but
+ * `abstractGraph(graph, { activities: fraction, keepConnected: true })` actually keeps all
+ * 30 — see `auto-abstraction.test.ts`'s "known limitation" describe block, which measures
+ * this exact case and isolates `keepConnected` as the sole cause (turning it off makes the
+ * real result match the naive prediction exactly).
+ *
+ * This is accepted as a best-effort gap, not fixed here: fixing it precisely would mean this
+ * module accepting a real `ProcessGraph` and searching against `abstractGraph`'s actual
+ * output rather than a plain count — a signature change that would also require updating
+ * `AbstractionControls`'s call site (`handleAuto`), which sits outside this round's write-set
+ * (RM-052-fix-brief.md / RM-052-tristate-decision.md §10). A future round that wants an exact
+ * search should route that signature change through `brand-ui-design-system-architect` (it
+ * changes this module's public contract) rather than patching around it here.
+ */
+export interface AutoAbstractionOptions {
+  /** Largest number of activities the resulting view should keep. Default `25`. */
+  maxActivities?: number;
+  /** Maximum fraction candidates probed before returning the best found so far. Default `8`. */
+  maxSteps?: number;
+  /** The smallest fraction ever offered — "Auto" never hides everything. Default `0.05`. */
+  minFraction?: number;
+}
+
+export interface AutoAbstractionResult {
+  /** The activities fraction to hand to `setAbstraction`. */
+  activities: number;
+  /** How many fraction candidates were actually probed — always `<= maxSteps`. */
+  steps: number;
+}
+
+const DEFAULT_MAX_ACTIVITIES = 25;
+const DEFAULT_MAX_STEPS = 8;
+const DEFAULT_MIN_FRACTION = 0.05;
+
+/**
+ * Mirrors `abstractGraph`'s own kept-activity count: `round(total * fraction)`, floored at
+ * one activity — `abstractGraph` never hides every activity, so this heuristic must not
+ * search for a fraction that would.
+ */
+function keptActivityCount(total: number, fraction: number): number {
+  return Math.max(1, Math.round(total * fraction));
+}
+
+/**
+ * Picks the activities fraction "Auto" applies, from a plain activity COUNT — not a graph.
+ * Paths are left to `abstractGraph`'s own connectivity repair, and duration/statistic
+ * fields never enter the search, so this heuristic's result cannot be perturbed by the
+ * discovery layer's own reservoir-sampling nondeterminism. Taking a count rather than a
+ * `ProcessGraph` also lets a caller pass the graph's PRE-abstraction total — e.g.
+ * `graph.activities.length + hiddenCounts.activities` — without building a throwaway array.
+ */
+export function computeAutoAbstraction(
+  totalActivities: number,
+  opts: AutoAbstractionOptions = {},
+): AutoAbstractionResult {
+  const maxActivities = opts.maxActivities ?? DEFAULT_MAX_ACTIVITIES;
+  const maxSteps = opts.maxSteps ?? DEFAULT_MAX_STEPS;
+  const minFraction = opts.minFraction ?? DEFAULT_MIN_FRACTION;
+  const total = totalActivities;
+
+  // Already within budget at full detail (or nothing to abstract) — nothing to search for.
+  if (total === 0 || keptActivityCount(total, 1) <= maxActivities) {
+    return { activities: 1, steps: 0 };
+  }
+
+  // Even the floor doesn't fit — hand back the floor. Still bounded (one probe), still
+  // the best answer this heuristic can offer for a graph this large.
+  if (keptActivityCount(total, minFraction) > maxActivities) {
+    return { activities: minFraction, steps: 1 };
+  }
+
+  let lo = minFraction; // largest fraction CONFIRMED to fit the budget so far
+  let hi = 1; // smallest fraction confirmed NOT to fit
+  let best = minFraction;
+
+  for (let step = 1; step <= maxSteps; step += 1) {
+    const mid = (lo + hi) / 2;
+    if (keptActivityCount(total, mid) <= maxActivities) {
+      best = mid;
+      lo = mid;
+    } else {
+      hi = mid;
+    }
+    if (step === maxSteps) {
+      return { activities: best, steps: step };
+    }
+  }
+
+  // Unreachable — maxSteps is always >= 1 when opts allow it — but keeps the function
+  // total for TypeScript's control-flow analysis.
+  return { activities: best, steps: maxSteps };
+}

package/src/abstraction-controls/index.ts

@@ -0,0 +1,4 @@
+export { AbstractionControls } from "./abstraction-controls";
+export type { AbstractionControlsProps } from "./abstraction-controls";
+export { computeAutoAbstraction } from "./auto-abstraction";
+export type { AutoAbstractionOptions, AutoAbstractionResult } from "./auto-abstraction";