Writer.select ​

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 Writer · inherited by Tx, Session, testing.FakeSession · stable · since 2.0.0 · called as session.select

select(group: string, material: string, options?: RecordedOptions<C> & SignalOption): Promise<Report>;

Selects material (a MaterialNode nodeId) in the global-material GroupNode group (its nodeId): recorded, priced and saved. Merging and in the write queue: never superseded, so it commits as its own undo step even while a sync loads. The parts it changes crossfade over the document's materials.fadeMs as its layers resolve it (420 ms when no layer sets it), after the commit point. Outcome: 'committed' at its commit point, after its loads; through a tx, 'staged' once the assets it names have loaded (asset failures: problems). Behind an open transaction it settles only when that transaction closes (a stalled one at its timeoutMs (10 s by default), one holding the display within 14 s of its hold, later while it still loads): show the value you wrote. 'rolled-back' with reason 'internal-error' when applying it failed inside the runtime (through a tx, it then rejects AbortError and the transaction resolves 'rolled-back'; spec section 6.4). Errors: rejects HoloInputError 'unknown-id' when group is not a global-material GroupNode (a variant GroupNode's nodeId included) or material is not one of its MaterialNodes at the call. One that was there at the call and is gone at its turn in the queue (a rollback or an earlier commit removed it) refuses with reason 'conflict' and changes nothing (spec section 6.4). A select whose group dresses no mesh still commits: it reports matched 1 and no Problem, and the price and the recorded choice change while the look does not. The cause is the scene model's: a globalMaterialList meshName close to one of its model's mesh names (a typo) was recorded once, when that model was placed, as 'target-unmatched' in info().problems with didYouMean; a group no placed model names records nothing, as 1.x. A page that must know checks the meshes itself: session.find({ node, name: meshName }).list().length. Not for: a look-only preview, which is a rule: find(q).set({ material: { materialNodeId } }); a variant GroupNode's selected child, which is applyPatch replacing /model/node/{id}/defaultNodeId, or setSceneModel.

Options ​

Through Session:

Through Tx:

Refused here (typed never, so passing one fails to compile): actor, checkpoint, dryRun, expectGroup, expectRevision, origin, supersede, undo.

Abort (signal) ​

This call is a write (SignalOption.signal, the kinds of call).

A write: before the commit point it rolls back and rejects AbortError; after it, no effect, except that a running camera move stops where the last frame drew it (CameraMoveOptions).

Through a tx the commit point is the transaction's: aborting a write still loading rejects AbortError and stages nothing (catch it: unobserved, it rolls the transaction back, spec section 6.1, O6); aborting one already staged unstages it, its paths keeping the latest other write to them as after a failed savepoint (O7), and its Promise stays resolved 'staged'.

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-Writer.select.ts):

import type { Session } from '@holostep-configurators/runtime-client/contract';
declare const session: Session;
declare const signal: AbortSignal;
declare const fabricGroup: string;                         // the GroupNode's nodeId
declare const label: { text: string };
export async function pickFabric(materialNodeId: string, name: string): Promise<void> {
  const before = label.text;
  label.text = name;                                       // show the value you wrote, at once
  try {
    // May be queued behind a transaction: never read it back before this settles.
    const r = await session.select(fabricGroup, materialNodeId, {
      actor: 'shopper', origin: 'swatch',
    });
    if (r.outcome === 'refused') label.text = before;      // gone at its turn: 'conflict'
  } catch (error) {
    label.text = before;                                   // invalid input or abort: nothing ran
    throw error;
  }
}

Related ​

From ViewerDocumentJson.materials.fadeMs:

The crossfade of a selection change (select, undo, redo, setSceneModel), ms, as 1.x's viewer.transition: the outgoing and incoming base colours (baseColor times its map, or baseColor alone without one) blend in linear colour space, and so do the roughness maps, metallic, roughness, normalScale and the environment intensity, each map sampled at its own placement (uv, scale or sizeM, offset, rotationDeg); other fields switch at the swap. Each changed part fades from what it drew, and a part outside the change keeps its look, also when it already wears the incoming material. A part's first material and a part the same commit loads never fade. select still resolves at its commit point; idle() waits for the fade, and a capture draws its target (spec section 6.8); through a tx it starts when the commit is shown. 0 swaps in one frame. Counts as 0 under reduced motion (spec section 6.2). A change during the fade takes over as PartWriteOptions.fadeMs says (spec section 6.3).

Generic-API test (spec 3.1) ​