History.group ​

Contract 2.0.0 · package sha256 a857eca95b35921109faf997094bb4192f12527d9d0fcd4be7e97f06425bad6e · generated from configurator-runtime.d.ts by services/onsite-scripter/scripts/build-contract-docs.mjs; edit the source, not this file.

Method of History · stable · since 2.0.0 · called as session.history.group

group(options?: HistoryGroupOptions): HistoryGroup;

Opens a group (immediate): every write called until commit() that makes an undo step (a recorded change, or a labelled look write) is part of one undo step, also one that commits after it (a gesture's last write still loading), unless an undo, a redo, a rebase or a step, each made by a write called after the group ended (or by the undo() or redo() that ended it), changed history first; then that write is its own step (spec section 6.1, O14). Groups do not nest: opening one commits the open one. It never holds the display and never rolls back. It ends by commit(), a call of undo() or redo() (which then undoes or redoes its whole step), a 'shopper' write's call while an 'assistant' group is open (whatever that write's outcome, an equal tap or a write still loading included; it is its own step), timeoutMs or its signal (spec section 6.1, O9, O14). Not for: all-or-nothing changes, which are transaction().

Options ​

Through Session:

Abort (signal) ​

This call is neither a write, a registration, a wait nor a creator (SignalOption.signal, the kinds of call).

Cancels this call; the member's JSDoc says what an abort does.

Example ​

Imports: values (has, validate, the Holo*Error classes, the pure helpers) from @holostep-configurators/runtime-client, types from @holostep-configurators/runtime-client/contract, /math and /testing names from those entries; boot from the runtime module the root's loadRuntimeAtFloor resolves to. A type your page defines is your app's: declare it there, never import it from the package.

Compiled under the contract's strict settings (examples/declaration/05-History.group.ts):

import type { JsonPatchOp, Session } from '@holostep-configurators/runtime-client/contract';
declare const session: Session;
declare const signal: AbortSignal;
// One assistant turn: one undo step, and it stops as soon as the shopper acts.
type Step =
  | { kind: 'select'; group: string; material: string }
  | { kind: 'patch'; patch: JsonPatchOp[] };
export async function assistantTurn(steps: readonly Step[]): Promise<string> {
  const turn = session.history.group({ label: 'Assistant', actor: 'assistant', signal });
  let rev = session.revision;
  try {
    for (const step of steps) {
      // actor comes from the group
      const guard = { expectGroup: turn, expectRevision: rev, origin: 'assistant' };
      const r = step.kind === 'select'
        ? await session.select(step.group, step.material, guard)
        : await session.applyPatch(step.patch, guard);
      // 'conflict': the shopper acted (the group ended) or the revision moved;
      // 'busy': a write is pending.
      if (r.outcome !== 'committed') return `stopped: ${r.outcome} ${r.reason ?? ''}`;
      rev = r.revision;                                    // the turn's own commit moved it
    }
    return 'done';
  } finally {
    turn.commit();                                         // idempotent
  }
}

Generic-API test (spec 3.1) ​