Events ​

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.

Interface · import type { Events } from '@holostep-configurators/runtime-client/contract'; · stable · since 2.0.0 · section 18. Events

Typed events. State events (those a commit causes) carry cause; input, camera, animation and overlay events have no commit behind them and carry none. Payloads are frozen snapshots of their commit; reads in a handler may be newer (cause.seq < session.seq). A payload may also predate a write you have since called: never merge a whole snapshot over newer app state (the setSceneModel example merges each commit's patch from 'committed', never its whole model). An equal write (one that resolves changed: false) fires nothing, except 'history:changed': an equal undo or redo fires it, because its history pointer moves (O9), and an equal write with undo: 'rebase' fires it when the flags change (O15). Subscribe with session.on(name, handler, { signal }).

Members ​

Member Kind Summary
committed property The commit feed: one entry per commit, after it is shown.
scene-model:changed property model carries no key material: merge its placement, enabled and group selections into your own document by nodeId; never save it as is.
assembly:changed property The connections changed in a commit: one event per commit whose connections differ from the previous commit's, whatever changed them (attach, detach, setSceneModel, applyPatch, undo, redo, a restore, a reload,…
material:selected property A global-material GroupNode's selection changed in a commit: material (a MaterialNode nodeId) is now selected in group.
history:changed property The undo state changed: the same fields as session.history.
click property A click or tap on the canvas.
hover property The part under a mouse or pen pointer changed; hit is null when it leaves.
drag:start property part is the dragged unit (a model's root, or a collection item); pose is its world pose.
drag:move property The pointer moved during a drag; pose is the unit's world pose as drawn for that move, after constrain (the proposal constrain received is DragMove.pose).
drag:end property pose is the last constrained world pose.
camera:control-start property The shopper started a pointer or touch gesture: orbiting, panning or a two-finger pinch.
camera:control-end property The shopper's pointer or touch gesture ended (never after a wheel; see 'camera:control-start').
camera:rest property The camera came to rest (after a move, damping or a gesture).
camera:changed property After a drawn frame that changed the camera; the state at subscription is the baseline.
anchors:moved property At most once per frame, after a drawn frame that moved an anchor or changed its visible.
hotspot:click property A hotspot badge was clicked, tapped, or pressed with Enter or Space (the button's click event); a pointer press counts only when released on the badge within the 'click' event's thresholds, so a sweep that starts on…
hotspot:hover property The badge under the pointer, else the badge with keyboard focus (:focus-visible), else null; it fires when that changes, so content you show on hover also shows on focus (WCAG 1.4.13).
animation:started property A clip that was neither playing nor paused started playing; a play that takes over a playing clip, or resumes a paused one, fires nothing.
animation:stopped property A playing or paused clip stopped before its end: by stop, reset, a play of an exclusive clip, a new asset version, or the removal of its node or item.
animation:finished property A clip reached the end of its play's direction (frame 0 for a reverse play), after its last play for loop: n; a loop: true clip never does.
ar:status property The AR launch state changed.
ar:modes property info().ar.modes or fileModes changed: 'webxr' joined once the probe answered after boot, a commit gave or took the product's public plain twin ('scene-viewer'), a document apply turned AR on or off, the…
xr:start property · labs Holostep's in-page AR or try-on showed its first picture: experience is 'place' (in-room AR) or 'try-on', presenter the viewer that shows it, named as ActivateARReport.mode and info().ar.modes name it: 'webxr'…
xr:end property · labs That XR session ended, durationMs after the tap: 'user' (the shopper closed it), 'error', 'background' (the page was hidden), 'destroy', 'fallback' (the shopper went on to the native AR viewer or the 3D view),…
xr:cta property · labs A call to action in AR (the in-page AR's button, the Quick Look banner): configuration is the scene model at the tap, with no key material.
resize property The element was resized; the aspect follows at once.
document:applied property A document layer was applied; the same report applyDocument resolves with.
problem property A Problem was recorded (also in info().problems).

Declaration ​

ts
export interface Events {
  'committed': {
    readonly cause: Cause;
    readonly label: string | null;
    readonly recorded: boolean;
    readonly patch: readonly JsonPatchOp[];
    readonly inverse: readonly JsonPatchOp[];
    readonly checkpoint: JsonValue | null;
  };
  'scene-model:changed': {
    readonly cause: Cause;
    readonly model: DeepReadonly<SceneModel>;
  };
  'assembly:changed': {
    readonly cause: Cause;
    readonly connections: readonly Connection[];
  };
  'material:selected': {
    readonly cause: Cause;
    readonly group: string;
    readonly material: string;
  };
  'history:changed': {
    readonly cause: Cause;
  } & Pick<History, 'canUndo' | 'canRedo' | 'undoLabel' | 'redoLabel' | 'depth'>;
  'click': {
    readonly at: ScreenPoint;
    readonly hit: Hit | null;
  };
  'hover': {
    readonly at: ScreenPoint;
    readonly hit: Hit | null;
  };
  'drag:start': {
    readonly part: Part<CommitOptions>;
    readonly pose: Pose;
    readonly pointerId: number;
  };
  'drag:move': {
    readonly part: Part<CommitOptions>;
    readonly pose: Pose;
    readonly at: ScreenPoint;
  };
  'drag:end': {
    readonly part: Part<CommitOptions>;
    readonly pose: Pose;
    readonly moved: boolean;
    readonly reason: 'released' | 'cancelled' | 'other';
    readonly cause: Cause | null;
    readonly op: OpId | null;
  };
  'camera:control-start': void;
  'camera:control-end': void;
  'camera:rest': {
    readonly state: CameraState;
  };
  'camera:changed': {
    readonly state: CameraState;
  };
  'anchors:moved': {
    readonly anchors: readonly AnchorPosition[];
  };
  'hotspot:click': {
    readonly hotspot: HotspotReference;
  };
  'hotspot:hover': {
    readonly hotspot: HotspotReference | null;
  };
  'animation:started': ClipRef;
  'animation:stopped': ClipRef;
  'animation:finished': ClipRef;
  'ar:status': {
    readonly status: 'disabled' | 'unsupported' | 'activating' | 'active' | 'error' | 'other';
    readonly place?: {
      readonly state: string;
      readonly hint: string;
    };
  };
  'ar:modes': {
    readonly modes: InfoReport['ar']['modes'];
  };
  'xr:start': {
    readonly presenter: 'webxr' | 'scene-viewer' | 'quick-look' | 'other';
    readonly experience: 'place' | 'try-on' | 'other';
  };
  'xr:end': {
    readonly reason: 'user' | 'error' | 'background' | 'destroy' | 'fallback' | 'other';
    readonly durationMs: number;
  };
  'xr:cta': {
    readonly action: 'add-to-cart' | 'back' | 'other';
    readonly configuration: DeepReadonly<SceneModel> | null;
  };
  'resize': {
    readonly width: number;
    readonly height: number;
  };
  'document:applied': ApplyReport;
  'problem': {
    readonly problem: Problem;
  };
}

Generic-API test (spec 3.1) ​

Rule Result
1. Neutral name pass: Events names no product
2. A precedent not recorded: no ledger row (coverage.json) names this member or its owner
3. Two apps, or labs pass: 21 apps (fleet cross-check: app-04c2774145, app-0c773a4ee3, app-37356bf09f, app-378d190f1b, app-4762caacdc, app-4fd23bc869, app-822bb9d6aa, app-8675b3225c and 13 more)
4. The cheaper fix first not recorded per member (Appendix B decides it per need)