@weasel-js/labkit 1.1.0 → 1.3.0-pre.0

package/src/instrument/SineWave.smoke.test.tsx

@@ -1,6 +1,7 @@
 import { render } from '@testing-library/react';
 import type { ReactElement } from 'react';
 import { describe, expect, it, vi } from 'vitest';
+import { DEFAULT_VIEW } from '../state/view';
 import { defineInstrument } from './defineInstrument';
 import type { RenderContext } from './types';
 import { validateConfigSchema } from './validateConfigSchema';
@@ -85,7 +86,14 @@ describe('SineWave instrument smoke test', () => {
       config: SineWaveInstrument.defaultConfig(),
       setState: vi.fn(),
       setConfig: vi.fn(),
-      trial: { id: 'w', zoom: 1, setZoom: vi.fn() },
+      trial: {
+        id: 'w',
+        view: DEFAULT_VIEW,
+        setView: vi.fn(),
+        zoom: 1,
+        setZoom: vi.fn(),
+        activeToolId: null,
+      },
       emit: vi.fn(),
     };
     const { container } = render(SineWaveInstrument.render(ctx) as ReactElement);

package/src/instrument/defineInstrument.test.ts

@@ -1,9 +1,11 @@
 import { describe, expect, expectTypeOf, it } from 'vitest';
+import { f } from '../config/builder';
+import type { ConfigOf } from '../config/types';
 import { defineInstrument } from './defineInstrument';
 import type { Instrument } from './types';
 
 describe('defineInstrument', () => {
-  it('returns the same object reference passed in', () => {
+  it('returns a legacy spec by reference', () => {
     const spec: Instrument<{ n: number }, { x: number }> = {
       name: 'Test',
       defaultConfig: () => ({ x: 1 }),
@@ -24,4 +26,39 @@ describe('defineInstrument', () => {
     expectTypeOf(inst.defaultConfig()).toEqualTypeOf<{ flag: boolean }>();
     expectTypeOf(inst.initialState({ flag: true })).toEqualTypeOf<{ count: number }>();
   });
+
+  it('synthesizes defaultConfig from a builder schema', () => {
+    const inst = defineInstrument({
+      name: 'Schema',
+      config: f.schema({ showGrid: f.boolean(true), cellSize: f.number(20) }),
+      initialState: () => ({}),
+      render: () => null,
+    });
+    expect(inst.defaultConfig()).toEqual({ showGrid: true, cellSize: 20 });
+  });
+
+  it('infers TC from the schema', () => {
+    const config = f.schema({ showGrid: f.boolean(true), mode: f.enum('fast', ['fast', 'slow']) });
+    const inst = defineInstrument<{ n: number }, ConfigOf<typeof config>>({
+      name: 'Schema',
+      config,
+      initialState: () => ({ n: 0 }),
+      render: () => null,
+    });
+    expectTypeOf(inst.defaultConfig()).toEqualTypeOf<{
+      showGrid: boolean;
+      mode: 'fast' | 'slow';
+    }>();
+  });
+
+  it('leaves an explicit defaultConfig alone even alongside a schema', () => {
+    const inst = defineInstrument({
+      name: 'Both',
+      config: f.schema({ a: f.number(1) }),
+      defaultConfig: () => ({ a: 99 }),
+      initialState: () => ({}),
+      render: () => null,
+    });
+    expect(inst.defaultConfig()).toEqual({ a: 99 });
+  });
 });

package/src/instrument/defineInstrument.ts

@@ -1,7 +1,34 @@
+import type { ConfigSchema } from '../config/types';
 import type { Instrument } from './types';
 
-/** Identity at runtime; exists so an instrument's state and config types are
- *  inferred from the spec rather than having to be written out. */
-export function defineInstrument<TS, TC>(spec: Instrument<TS, TC>): Instrument<TS, TC> {
-  return spec;
+/** An instrument as it is written: either the legacy `defaultConfig` (plus an
+ *  optional `configSchema`), or a `config` schema that supplies both. */
+export type InstrumentSpec<TS, TC, TItem = unknown> =
+  | Instrument<TS, TC, TItem>
+  | (Omit<Instrument<TS, TC, TItem>, 'defaultConfig'> & { config: ConfigSchema<TC> });
+
+/**
+ * Normalizes an instrument spec, and infers its state and config types from
+ * the literal rather than making them be written out.
+ *
+ * A spec declaring `config` gets its `defaultConfig` synthesized from the
+ * schema, so nothing downstream branches on which way the config was
+ * declared. A spec written the legacy way is returned unchanged, by
+ * reference.
+ *
+ * Resolving the schema into controls does not happen here: rules are
+ * lab-scoped and this runs at module load. `useConfigSchema` does that.
+ *
+ * TypeScript infers all three type arguments or none, so a call that names
+ * `TS` and `TC` leaves `TItem` at `unknown` and a job's `onItem` needs a cast.
+ * Name the item type too, or pass no type arguments at all.
+ */
+export function defineInstrument<TS, TC, TItem = unknown>(
+  spec: InstrumentSpec<TS, TC, TItem>,
+): Instrument<TS, TC, TItem> {
+  if (spec.config && !('defaultConfig' in spec && spec.defaultConfig)) {
+    const schema = spec.config;
+    return { ...spec, defaultConfig: () => schema.defaults() } as Instrument<TS, TC, TItem>;
+  }
+  return spec as Instrument<TS, TC, TItem>;
 }

package/src/instrument/index.ts

@@ -1,3 +1,4 @@
+export type { ToolCapability, TrialTool } from '../tools/types';
 export { defineInstrument } from './defineInstrument';
 export type {
   CanvasCapability,

package/src/instrument/types.ts

@@ -1,5 +1,9 @@
 import type { ReactNode } from 'react';
+import type { TrialContribution } from '../chrome/types';
+import type { ConfigSchema } from '../config/types';
 import type { ConfigField } from '../controls/types';
+import type { JobCapability, JobHandle } from '../job/types';
+import type { ToolCapability } from '../tools/types';
 
 /** What an instrument's `render` is handed: its state and config, the setters
  *  for both, the trial it is mounted in, and a way to emit named events. */
@@ -10,10 +14,21 @@ export interface RenderContext<TS = unknown, TC = unknown> {
   setConfig: (key: keyof TC, value: unknown) => void;
   trial: {
     id: string;
+    /** The trial's view, in whatever shape this instrument chose. labkit persists
+     *  it and restores it on Reset without ever reading into it. */
+    view: unknown;
+    setView: (next: unknown) => void;
+    /** 2D convenience over `view`. Reads 1 and writes nothing when the trial holds
+     *  a view that is not the 2D one. */
     zoom: number;
     setZoom: (z: number) => void;
+    /** Resolved active tool: this trial's slot, or the lab's. Null when neither
+     *  holds one. */
+    activeToolId: string | null;
   };
   emit: (event: string) => void;
+  /** Present only when the instrument declares a `job`. */
+  job?: JobHandle;
 }
 
 /** One 2D canvas layer of an instrument, drawn in declaration order.
@@ -31,12 +46,18 @@ export interface CanvasLayer<TS = unknown, TC = unknown> {
 export interface CanvasCapability<TS = unknown, TC = unknown> {
   layers: CanvasLayer<TS, TC>[];
   initialView?: { zoom: number; pan: { x: number; y: number } };
+  /** Widens `usePanZoom`'s default clamp; the opening zoom stays reachable
+   *  regardless of these. */
+  minZoom?: number;
+  maxZoom?: number;
 }
 
 /** Declares which of an instrument's layers the trial should offer
  *  show/hide controls for. */
 export interface LayerCapability {
-  ids: string[];
+  /** In list order. A bare string is a layer id that doubles as its own label;
+   *  give a descriptor instead to label a layer or mark it `alwaysOn`. */
+  ids: readonly (string | LayerDescriptor)[];
 }
 
 /** Declares that an instrument accepts items dragged from a palette: what the
@@ -82,10 +103,16 @@ export type DragFeedback = { ok: boolean; reason?: string };
  * a canvas, a layer list, palette drag-and-drop, undo. Declaring a capability
  * is what makes the trial provide the corresponding chrome.
  */
-export interface Instrument<TS = unknown, TC = unknown> {
+export interface Instrument<TS = unknown, TC = unknown, TItem = unknown> {
   name: string;
   defaultConfig: () => TC;
   initialState: (config: TC) => TS;
+  /** The instrument's config, declared once: values, types and controls.
+   *  Supplying this makes `defaultConfig` optional — `defineInstrument`
+   *  synthesizes it. Prefer it over `defaultConfig` + `configSchema`. */
+  config?: ConfigSchema<TC>;
+  /** @deprecated Declare `config` instead; this repeats what `TC` already
+   *  says and nothing holds the two to one answer. */
   configSchema?: () => ConfigField[];
   /** The instrument's DOM. With `canvas`, this renders as an overlay above the
    *  layers rather than instead of them; return `null` for canvas only. */
@@ -97,10 +124,18 @@ export interface Instrument<TS = unknown, TC = unknown> {
   layers?: LayerCapability;
   dragDrop?: DragDropCapability<TS, TC>;
   undo?: UndoCapability;
+  /** Tools this instrument offers. Declaring them gives the trial a palette
+   *  region and its own tool slot. */
+  tools?: ToolCapability;
+  /** Chrome this instrument contributes beyond what its capabilities imply. */
+  chrome?: TrialContribution[];
+  /** Work too slow to do during a render. The runtime starts it, aborts it on
+   *  unmount and on a `key` change, and renders progress into the trial. */
+  job?: JobCapability<TS, TC, TItem>;
 }
 
 /** Instruments as a lab receives them. `any` rather than `unknown` because
  *  parameter contravariance keeps a `defineInstrument<TS, TC>` result out of
  *  an `Instrument<unknown, unknown>[]`; it is contained to this alias. */
 // biome-ignore lint/suspicious/noExplicitAny: see above
-export type InstrumentList = readonly Instrument<any, any>[];
+export type InstrumentList = readonly Instrument<any, any, any>[]; // eslint-disable-line @typescript-eslint/no-explicit-any -- contravariant TC; see above

package/src/instrument/validateConfigSchema.test.ts

@@ -21,12 +21,22 @@ describe('validateConfigSchema', () => {
     expect(r.errors).toContain('Duplicate config key: "a"');
   });
 
-  it('flags unknown field type', () => {
+  it('accepts an unknown field type — a lab may supply its renderer', () => {
     const fields = [
-      { key: 'x', label: 'X', type: 'mystery', default: 1 },
+      { key: 'x', label: 'X', type: 'vector2', default: 1 },
     ] as unknown as ConfigField[];
     const r = validateConfigSchema(fields);
-    expect(r.errors).toContain('Unknown field type: "mystery" on key "x"');
+    expect(r.valid).toBe(true);
+    expect(r.errors).toEqual([]);
+  });
+
+  it('still checks keys and labels on an unknown field type', () => {
+    const fields = [
+      { key: '', label: '', type: 'vector2', default: 1 },
+    ] as unknown as ConfigField[];
+    const r = validateConfigSchema(fields);
+    expect(r.errors).toContain('Field has empty key');
+    expect(r.errors).toContain('Field "" has empty label');
   });
 
   it('flags slider min >= max', () => {

package/src/instrument/validateConfigSchema.ts

@@ -1,4 +1,4 @@
-import type { ConfigField, ConfigFieldType } from '../controls/types';
+import type { ConfigField } from '../controls/types';
 
 /** Whether a config schema is usable, and every problem found rather than
  *  just the first. */
@@ -7,11 +7,13 @@ export interface ValidationResult {
   errors: string[];
 }
 
-const KNOWN_TYPES: ConfigFieldType[] = ['slider', 'checkbox', 'select', 'number', 'text', 'color'];
-
 /** Check a config schema for the mistakes that would otherwise surface as a
- *  silently broken control: empty or duplicate keys, unknown field types, and
- *  fields whose own constraints do not hold. */
+ *  silently broken control: empty or duplicate keys, and fields whose own
+ *  constraints do not hold.
+ *
+ *  An unrecognized type is not an error — a lab supplies controls for its own
+ *  kinds through `ControlPanel`'s `renderers`, and this cannot see them. Such
+ *  a field simply has no constraints to check here. */
 export function validateConfigSchema(fields: ConfigField[]): ValidationResult {
   const errors: string[] = [];
   const seenKeys = new Set<string>();
@@ -29,11 +31,6 @@ export function validateConfigSchema(fields: ConfigField[]): ValidationResult {
       errors.push(`Field "${field.key}" has empty label`);
     }
 
-    if (!KNOWN_TYPES.includes(field.type)) {
-      errors.push(`Unknown field type: "${field.type}" on key "${field.key}"`);
-      continue;
-    }
-
     if (field.type === 'slider') {
       if (!Number.isFinite(field.default)) {
         errors.push(`Field "${field.key}": default must be a finite number`);

package/src/job/index.ts

@@ -0,0 +1,3 @@
+export type { JobCapability, JobEvent, JobFailure, JobHandle, JobStatus } from './types';
+export type { UseJobOptions } from './useJob';
+export { useJob } from './useJob';

package/src/job/types.ts

@@ -0,0 +1,47 @@
+/** What a running job reports as it goes. `total` may arrive at any point and may
+ *  arrive more than once; a job that cannot count up front simply never sends it.
+ *
+ *  `failed` is a first-class event rather than a thrown error because these
+ *  failures are per item: a run with two failed items is a partial success, and
+ *  its other items are worth showing. */
+export type JobEvent<T> =
+  | { kind: 'total'; total: number }
+  | { kind: 'item'; item: T }
+  | { kind: 'failed'; index: number; error: string };
+
+/** Where a job is. `idle` before its first run and after a cancel; `done` when the
+ *  iterable finished, whether or not items failed along the way. */
+export type JobStatus = 'idle' | 'running' | 'done' | 'error';
+
+/** Declares that an instrument has work too slow to do during a render: what to
+ *  run, when to re-run it, and how each result folds into state. */
+export interface JobCapability<TS = unknown, TC = unknown, TItem = unknown> {
+  /** Re-run whenever this value changes, compared element-wise. A job with no
+   *  `key` runs only when something calls `start()`. */
+  key?: (config: TC, state: TS) => readonly unknown[];
+  /** Start on mount and on every `key` change. Default false. */
+  auto?: boolean;
+  run: (args: { config: TC; state: TS; signal: AbortSignal }) => AsyncIterable<JobEvent<TItem>>;
+  /** Fold one result into state. Called once per `item` event, in arrival order. */
+  onItem: (item: TItem, state: TS) => TS;
+}
+
+/** One item that failed, and why. */
+export interface JobFailure {
+  index: number;
+  error: string;
+}
+
+/** What `RenderContext.job` exposes. Present only when the instrument declares the
+ *  capability; `undefined` otherwise. */
+export interface JobHandle {
+  status: JobStatus;
+  done: number;
+  /** Null until the job reports a total, and forever if it never does. */
+  total: number | null;
+  failures: readonly JobFailure[];
+  /** The error that ended the run, when `status` is `'error'`. */
+  error: string | null;
+  start: () => void;
+  cancel: () => void;
+}

package/src/job/useJob.test.tsx

@@ -0,0 +1,210 @@
+import { act, render, waitFor } from '@testing-library/react';
+import { useState } from 'react';
+import { describe, expect, it, vi } from 'vitest';
+import type { JobCapability, JobEvent, JobHandle } from './types';
+import { useJob } from './useJob';
+
+interface State {
+  items: number[];
+}
+interface Config {
+  n: number;
+}
+
+/** Yields 0..n-1, pausing between each so a test can cancel mid-run. */
+async function* counter(
+  n: number,
+  signal: AbortSignal,
+  failAt?: number,
+): AsyncGenerator<JobEvent<number>> {
+  yield { kind: 'total', total: n };
+  for (let i = 0; i < n; i++) {
+    await new Promise((r) => setTimeout(r, 2));
+    if (signal.aborted) return;
+    if (i === failAt) {
+      yield { kind: 'failed', index: i, error: 'frame died' };
+      continue;
+    }
+    yield { kind: 'item', item: i };
+  }
+}
+
+const capability = (failAt?: number): JobCapability<State, Config, number> => ({
+  run: ({ config, signal }) => counter(config.n, signal, failAt),
+  onItem: (item, state) => ({ items: [...state.items, item] }),
+});
+
+interface HarnessProps {
+  capability: JobCapability<State, Config, number>;
+  config: Config;
+  onHandle: (h: JobHandle, s: State) => void;
+}
+
+function Harness({ capability: cap, config, onHandle }: HarnessProps) {
+  const [state, setState] = useState<State>({ items: [] });
+  const job = useJob({ capability: cap, config, state, setState });
+  onHandle(job, state);
+  return null;
+}
+
+describe('useJob', () => {
+  it('folds each item into state and counts progress', async () => {
+    const seen: { handle: JobHandle | null; state: State } = { handle: null, state: { items: [] } };
+    render(
+      <Harness
+        capability={capability()}
+        config={{ n: 3 }}
+        onHandle={(h, s) => {
+          seen.handle = h;
+          seen.state = s;
+        }}
+      />,
+    );
+    act(() => seen.handle?.start());
+    await waitFor(() => expect(seen.handle?.status).toBe('done'));
+    expect(seen.state.items).toEqual([0, 1, 2]);
+    expect(seen.handle?.done).toBe(3);
+    expect(seen.handle?.total).toBe(3);
+  });
+
+  it('counts a failed item without ending the run', async () => {
+    const seen: { handle: JobHandle | null; state: State } = { handle: null, state: { items: [] } };
+    render(
+      <Harness
+        capability={capability(1)}
+        config={{ n: 3 }}
+        onHandle={(h, s) => {
+          seen.handle = h;
+          seen.state = s;
+        }}
+      />,
+    );
+    act(() => seen.handle?.start());
+    await waitFor(() => expect(seen.handle?.status).toBe('done'));
+    expect(seen.state.items).toEqual([0, 2]);
+    expect(seen.handle?.failures).toEqual([{ index: 1, error: 'frame died' }]);
+    expect(seen.handle?.done).toBe(2);
+  });
+
+  it('stops folding results once cancelled', async () => {
+    const seen: { handle: JobHandle | null; state: State } = { handle: null, state: { items: [] } };
+    render(
+      <Harness
+        capability={capability()}
+        config={{ n: 50 }}
+        onHandle={(h, s) => {
+          seen.handle = h;
+          seen.state = s;
+        }}
+      />,
+    );
+    act(() => seen.handle?.start());
+    await waitFor(() => expect(seen.handle?.status).toBe('running'));
+    act(() => seen.handle?.cancel());
+    const atCancel = seen.state.items.length;
+    await new Promise((r) => setTimeout(r, 30));
+    expect(seen.state.items.length).toBe(atCancel);
+    expect(seen.handle?.status).toBe('idle');
+  });
+
+  it('discards results from a run its key superseded', async () => {
+    const withKey: JobCapability<State, Config, number> = {
+      ...capability(),
+      key: (config) => [config.n],
+      auto: true,
+    };
+    const seen: { handle: JobHandle | null; state: State } = { handle: null, state: { items: [] } };
+    const { rerender } = render(
+      <Harness
+        capability={withKey}
+        config={{ n: 40 }}
+        onHandle={(h, s) => {
+          seen.handle = h;
+          seen.state = s;
+        }}
+      />,
+    );
+    await waitFor(() => expect(seen.handle?.status).toBe('running'));
+
+    rerender(
+      <Harness
+        capability={withKey}
+        config={{ n: 2 }}
+        onHandle={(h, s) => {
+          seen.handle = h;
+          seen.state = s;
+        }}
+      />,
+    );
+    await waitFor(() => expect(seen.handle?.status).toBe('done'));
+
+    // The superseded 40-item run cannot have contributed: the winner yields two.
+    expect(seen.state.items).toEqual([0, 1]);
+  });
+
+  it('aborts on unmount', async () => {
+    const aborted = vi.fn();
+    const watching: JobCapability<State, Config, number> = {
+      run: ({ signal }) => {
+        signal.addEventListener('abort', aborted);
+        return counter(50, signal);
+      },
+      onItem: (item, state) => ({ items: [...state.items, item] }),
+    };
+    const seen: { handle: JobHandle | null; state: State } = { handle: null, state: { items: [] } };
+    const { unmount } = render(
+      <Harness
+        capability={watching}
+        config={{ n: 50 }}
+        onHandle={(h) => {
+          seen.handle = h;
+        }}
+      />,
+    );
+    act(() => seen.handle?.start());
+    await waitFor(() => expect(seen.handle?.status).toBe('running'));
+    unmount();
+    expect(aborted).toHaveBeenCalled();
+  });
+
+  it('reports a thrown error without losing the items already folded', async () => {
+    const throwing: JobCapability<State, Config, number> = {
+      run: async function* () {
+        yield { kind: 'item', item: 7 };
+        await new Promise((r) => setTimeout(r, 1));
+        throw new Error('the baker died');
+      },
+      onItem: (item, state) => ({ items: [...state.items, item] }),
+    };
+    const seen: { handle: JobHandle | null; state: State } = { handle: null, state: { items: [] } };
+    render(
+      <Harness
+        capability={throwing}
+        config={{ n: 1 }}
+        onHandle={(h, s) => {
+          seen.handle = h;
+          seen.state = s;
+        }}
+      />,
+    );
+    act(() => seen.handle?.start());
+    await waitFor(() => expect(seen.handle?.status).toBe('error'));
+    expect(seen.handle?.error).toMatch(/the baker died/);
+    expect(seen.state.items).toEqual([7]);
+  });
+
+  it('does not start on its own without auto', async () => {
+    const seen: { handle: JobHandle | null; state: State } = { handle: null, state: { items: [] } };
+    render(
+      <Harness
+        capability={{ ...capability(), key: (c) => [c.n] }}
+        config={{ n: 3 }}
+        onHandle={(h) => {
+          seen.handle = h;
+        }}
+      />,
+    );
+    await new Promise((r) => setTimeout(r, 20));
+    expect(seen.handle?.status).toBe('idle');
+  });
+});

package/src/job/useJob.ts

@@ -0,0 +1,134 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import type { JobCapability, JobFailure, JobHandle, JobStatus } from './types';
+
+export interface UseJobOptions<TS, TC, TItem> {
+  capability: JobCapability<TS, TC, TItem>;
+  config: TC;
+  state: TS;
+  setState: (next: TS | ((prev: TS) => TS)) => void;
+}
+
+interface Progress {
+  status: JobStatus;
+  done: number;
+  total: number | null;
+  failures: JobFailure[];
+  error: string | null;
+}
+
+const IDLE: Progress = { status: 'idle', done: 0, total: null, failures: [], error: null };
+
+function sameKey(a: readonly unknown[] | null, b: readonly unknown[] | null): boolean {
+  if (a === null || b === null) return a === b;
+  return a.length === b.length && a.every((v, i) => Object.is(v, b[i]));
+}
+
+export function useJob<TS, TC, TItem>({
+  capability,
+  config,
+  state,
+  setState,
+}: UseJobOptions<TS, TC, TItem>): JobHandle {
+  const [progress, setProgress] = useState<Progress>(IDLE);
+
+  // A run is identified by a token. Every result checks its token before touching
+  // state, so a superseded run finishes harmlessly instead of racing the winner.
+  const token = useRef(0);
+  const abort = useRef<AbortController | null>(null);
+
+  // Read through refs: `run` is called once per run and must see the values as of
+  // that moment rather than re-subscribing on every render.
+  const capRef = useRef(capability);
+  capRef.current = capability;
+  const configRef = useRef(config);
+  configRef.current = config;
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const setStateRef = useRef(setState);
+  setStateRef.current = setState;
+
+  const cancel = useCallback(() => {
+    token.current += 1;
+    abort.current?.abort();
+    abort.current = null;
+    setProgress(IDLE);
+  }, []);
+
+  const start = useCallback(() => {
+    token.current += 1;
+    const mine = token.current;
+    abort.current?.abort();
+    const controller = new AbortController();
+    abort.current = controller;
+    setProgress({ ...IDLE, status: 'running' });
+
+    void (async () => {
+      try {
+        const iterable = capRef.current.run({
+          config: configRef.current,
+          state: stateRef.current,
+          signal: controller.signal,
+        });
+        for await (const event of iterable) {
+          if (token.current !== mine) return;
+          if (event.kind === 'total') {
+            setProgress((p) => ({ ...p, total: event.total }));
+          } else if (event.kind === 'failed') {
+            setProgress((p) => ({
+              ...p,
+              failures: [...p.failures, { index: event.index, error: event.error }],
+            }));
+          } else {
+            const fold = capRef.current.onItem;
+            const item = event.item;
+            setStateRef.current((prev) => fold(item, prev));
+            setProgress((p) => ({ ...p, done: p.done + 1 }));
+          }
+        }
+        if (token.current !== mine) return;
+        setProgress((p) => ({ ...p, status: 'done' }));
+      } catch (err) {
+        if (token.current !== mine) return;
+        setProgress((p) => ({
+          ...p,
+          status: 'error',
+          error: err instanceof Error ? err.message : String(err),
+        }));
+      }
+    })();
+  }, []);
+
+  // Re-run when the declared key changes. `auto` covers the first mount too.
+  const lastKey = useRef<readonly unknown[] | null>(null);
+  const started = useRef(false);
+  const auto = capability.auto === true;
+  const key = capability.key ? capability.key(config, state) : null;
+  // `key` is compared element-wise inside; depending on the array identity here
+  // would restart the job on every render.
+  useEffect(() => {
+    if (!auto) return;
+    if (started.current && sameKey(lastKey.current, key)) return;
+    lastKey.current = key;
+    started.current = true;
+    start();
+  }, [auto, key, start]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  useEffect(
+    () => () => {
+      token.current += 1;
+      abort.current?.abort();
+      abort.current = null;
+    },
+    [],
+  );
+
+  return {
+    status: progress.status,
+    done: progress.done,
+    total: progress.total,
+    failures: progress.failures,
+    error: progress.error,
+    start,
+    cancel,
+  };
+}