ProblemCode · Holostep runtime 2.0

ProblemCode

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.

Type · import type { ProblemCode } from '@holostep-configurators/runtime-client/contract'; · stable · since 2.0.0 · section 2. Operations, reports, causes, problems

Open set: handle codes you don't know. Each code has a docs page (Problem.docs) with its fix. Problems are data: they never throw, on the strict fake too, which fails no test by itself: a test asserts on problems() (empty, or exactly the codes it expects). Codes are kebab-case, except the two that start with the member they report on, spelled as that member is: 'beforeCommit-threw' and 'beforeCommit-slow' (not 'before-commit-…'). Compare against this union, never a guessed spelling.

Problem codes

Code	Summary
`'target-unmatched'`	A query matched nothing, or a placed model's `globalMaterialList` `meshName` matches none of its meshes but is close to one (a typo; once, at the commit that places the model); `didYouMean` names close authored names.
`'target-ambiguous'`	A single-part member (`follow` target, `attachTo`) matched several parts; nothing applied.
`'asset-failed'`	A GLB, texture or HDR failed in a declarative write; the write committed without it.
`'asset-degraded'`	A preferred asset failed to fetch, decrypt or parse and a fallback was drawn instead: a `.holo`'s plain twin (`url` the `.holo`, spec section 8.5), or `glbUrl` after `optGlbUrl` failed (`url` the `optGlbUrl`, spec section 6.4).
`'ready-timeout'`	Readiness expired: the commit shows with stand-ins or old looks until assets decode.
`'transaction-timeout'`	A transaction made no progress for `timeoutMs`, or hit the hold cap; it rolled back.
`'write-after-close'`	A write through a closed `tx` or its handles (HoloTransactionClosedError).
`'beforeCommit-threw'`	A `beforeCommit` function threw, or was pending after 10 s; its writes were undone.
`'beforeCommit-slow'`	A `beforeCommit` function averaged over about 5 ms across its last 10 commits; recorded at most once per function per 10 s, with the count and the mean in `message`.
`'connection-stale'`	A connection's planes no longer meet (0.5 mm, 0.5°); it was dropped. `message` has the gap.
`'handle-disposed'`	A disposed handle or removed part was used; nothing happened.
`'owner-disposed'`	Undo or redo skipped a change made by an owner that is disposed: listed in that undo's or redo's `problems`, `path` the owner's address (`/look/collections/{name}` for a collection).
`'unsupported-spec'`	A value this runtime or device can't apply (a UV channel, `sizeM` without `uvMetres`, a shading node, a linked light past the limit, a material `ref` no `apply()` defines), or an unknown spec field from a page whose declared `contract` is newer than this runtime's (spec section 3.4); it was ignored. Also `CameraLimits.gestures: 'cooperative'` under an ancestor of `el` whose `touch-action` excludes `pan-y`: its touch half can't apply there (`path` '/camera/limits/gestures').
`'not-storable'`	Reserved: a value the stored format can't hold is an `Issue` of `validate` and an `unstorable` entry of `materialNodeFromSpec` (`IssueCode` 'not-storable'), never a Problem in 2.0.0; a branch on it as a Problem never runs.
`'space-not-storable'`	Reserved: `space: 'parent'` in a document meant to be saved is an `Issue` of `validate('configurator')` (`IssueCode` 'space-not-storable'), never a Problem in 2.0.0.
`'frame-needs-compile'`	A `Frame.material` value needs a new shader; it was skipped. Recorded at most once per hook, material and field per 10 s, with the count in `message`.
`'frame-budget'`	Frame hooks together averaged over 3 ms per frame across the last 60 drawn frames, or a `constrain` over 1 ms across its last 60 calls; recorded at most once per 10 s for each, with the count and the mean in `message`.
`'handler-threw'`	An event handler or frame hook threw (a hook that throws 3 frames in a row is removed: 'hook-removed').
`'hook-removed'`	A frame hook threw on 3 frames in a row and the runtime removed it: recorded once, right after that third 'handler-threw', with `path` 'onFrame' and the function's `name`, when it has one, in `message`; never again for that hook. Its disposer then does nothing; call `onFrame` again to run it.
`'handler-async'`	An event handler returned a Promise (an untyped call); it was not awaited.
`'handler-rejected'`	A Promise an event handler returned rejected.
`'engine-conflict'`	Another 3D engine instance on the page conflicts with the runtime's (`info().renderer.engineConflict`).
`'tenant-document-absent'`	No stored viewer-document layer for `configuratorId` (a 404; `info().document.layers` 'tenant'): the layers below apply. Never the scene model's source.
`'tenant-document-unavailable'`	The stored viewer-document layer couldn't be fetched (any failure but a 404); the session runs with the layers below.
`'defaults-unavailable'`	The platform or account defaults couldn't be fetched; built-in defaults apply.
`'document-error'`	A document layer has an invalid or version-1 key; `didYouMean` names its 2.0 home.
`'apply-failed'`	The runtime failed while applying a document layer, not for a bad key ('document-error'): one entry with `layer` and no `path` in `ApplyReport.problems` (`applyDocument`, `'document:applied'`); at boot, in `info().problems`.
`'sync-failed'`	An internal failure while the runtime applied a state write, recorded or look-only (`setSceneModel`, `undo`, `Collection.set`, `stage.set`, `attach`, a rule), through `session` or a `tx`, before its commit point: it, or the transaction holding it, rolled back with reason 'internal-error'; or while it applied a commit the runtime makes itself (a `commit: 'runtime'` drag's, a 'restore'), which rolls back, carries that commit's `op` (a drag's also its unit's `node`, the `op` its 'drag:end' carried) and releases a held drop pose; or when a member's on-demand code failed to load, for a write or a synchronous call that waited for it (spec section 6.3).
`'host-disconnected'`	`el` left the document after `boot`, which freed the renderer for good (spec section 6.5). Recorded once, at the first later call other than `destroy()` and the terminal calls, so an unmount that removes the DOM and then destroys records nothing. Pending and later Promise-returning calls reject AbortError; boot `el` again for a new session.
`'render-lost'`	The view stopped drawing: the graphics context was lost and came back neither on its own nor on a fresh canvas. The stage stays blank until the page reloads; offer a reload.
`'host-unsized'`	`el` has no size to draw at: under 64 CSS px on a side, or not rendered (display: none on it or an ancestor), at the first drawn frame or a resize; once until it has a size again. A `div` with no CSS height is not unsized: it takes the view's default 2:1 shape (`BootOptions.el`). Give `el` a CSS size for the shape you want, and show it.
`'unknown-boot-option'`	`boot` got an option this contract doesn't have; it was ignored.
`'unknown-event'`	`on()` got an event name that doesn't exist; it subscribed to nothing.
`'invalid-input'`	A call rejected or threw HoloInputError; recorded so an unawaited one is never silent.
`'hotspot-id-taken'`	Two hotspot badges share an `id`; the later one is skipped.
`'deprecated'`	Reserved for a labs member or value that will change; the strict fake throws on it. No 2.0.0 member is deprecated, so no 2.0.0 call records it.
`'not-permitted'`	A gated capability this account may not use (`permits()` is false).
`'unknown-capability'`	`supports()` got an id not in this runtime's `KnownCapability`, once per id per session; `didYouMean` names a 1.4 id's 2.0 id (none when the member is always present), else close known ids.
`'connections-outdated'`	Stored connections whose `connectionsBasis` no longer matches their nodes: none restored.
`'read-while-queued'`	Strict fake only: code read a target that still had a write queued behind a transaction.

Code

Summary

'target-unmatched'

A query matched nothing, or a placed model's globalMaterialList meshName matches none of its meshes but is close to one (a typo; once, at the commit that places the model); didYouMean names close authored names.

'target-ambiguous'

A single-part member (follow target, attachTo) matched several parts; nothing applied.

'asset-failed'

A GLB, texture or HDR failed in a declarative write; the write committed without it.

'asset-degraded'

A preferred asset failed to fetch, decrypt or parse and a fallback was drawn instead: a .holo's plain twin (url the .holo, spec section 8.5), or glbUrl after optGlbUrl failed (url the optGlbUrl, spec section 6.4).

'ready-timeout'

Readiness expired: the commit shows with stand-ins or old looks until assets decode.

'transaction-timeout'

A transaction made no progress for timeoutMs, or hit the hold cap; it rolled back.

'write-after-close'

A write through a closed tx or its handles (HoloTransactionClosedError).

'beforeCommit-threw'

A beforeCommit function threw, or was pending after 10 s; its writes were undone.

'beforeCommit-slow'

A beforeCommit function averaged over about 5 ms across its last 10 commits; recorded at most once per function per 10 s, with the count and the mean in message.

'connection-stale'

A connection's planes no longer meet (0.5 mm, 0.5°); it was dropped. message has the gap.

'handle-disposed'

A disposed handle or removed part was used; nothing happened.

'owner-disposed'

Undo or redo skipped a change made by an owner that is disposed: listed in that undo's or redo's problems, path the owner's address (/look/collections/{name} for a collection).

'unsupported-spec'

A value this runtime or device can't apply (a UV channel, sizeM without uvMetres, a shading node, a linked light past the limit, a material ref no apply() defines), or an unknown spec field from a page whose declared contract is newer than this runtime's (spec section 3.4); it was ignored. Also CameraLimits.gestures: 'cooperative' under an ancestor of el whose touch-action excludes pan-y: its touch half can't apply there (path '/camera/limits/gestures').

'not-storable'

Reserved: a value the stored format can't hold is an Issue of validate and an unstorable entry of materialNodeFromSpec (IssueCode 'not-storable'), never a Problem in 2.0.0; a branch on it as a Problem never runs.

'space-not-storable'

Reserved: space: 'parent' in a document meant to be saved is an Issue of validate('configurator') (IssueCode 'space-not-storable'), never a Problem in 2.0.0.

'frame-needs-compile'

A Frame.material value needs a new shader; it was skipped. Recorded at most once per hook, material and field per 10 s, with the count in message.

'frame-budget'

Frame hooks together averaged over 3 ms per frame across the last 60 drawn frames, or a constrain over 1 ms across its last 60 calls; recorded at most once per 10 s for each, with the count and the mean in message.

'handler-threw'

An event handler or frame hook threw (a hook that throws 3 frames in a row is removed: 'hook-removed').

'hook-removed'

A frame hook threw on 3 frames in a row and the runtime removed it: recorded once, right after that third 'handler-threw', with path 'onFrame' and the function's name, when it has one, in message; never again for that hook. Its disposer then does nothing; call onFrame again to run it.

'handler-async'

An event handler returned a Promise (an untyped call); it was not awaited.

'handler-rejected'

A Promise an event handler returned rejected.

'engine-conflict'

Another 3D engine instance on the page conflicts with the runtime's (info().renderer.engineConflict).

'tenant-document-absent'

No stored viewer-document layer for configuratorId (a 404; info().document.layers 'tenant'): the layers below apply. Never the scene model's source.

'tenant-document-unavailable'

The stored viewer-document layer couldn't be fetched (any failure but a 404); the session runs with the layers below.

'defaults-unavailable'

The platform or account defaults couldn't be fetched; built-in defaults apply.

'document-error'

A document layer has an invalid or version-1 key; didYouMean names its 2.0 home.

'apply-failed'

The runtime failed while applying a document layer, not for a bad key ('document-error'): one entry with layer and no path in ApplyReport.problems (applyDocument, 'document:applied'); at boot, in info().problems.

'sync-failed'

An internal failure while the runtime applied a state write, recorded or look-only (setSceneModel, undo, Collection.set, stage.set, attach, a rule), through session or a tx, before its commit point: it, or the transaction holding it, rolled back with reason 'internal-error'; or while it applied a commit the runtime makes itself (a commit: 'runtime' drag's, a 'restore'), which rolls back, carries that commit's op (a drag's also its unit's node, the op its 'drag:end' carried) and releases a held drop pose; or when a member's on-demand code failed to load, for a write or a synchronous call that waited for it (spec section 6.3).

'host-disconnected'

el left the document after boot, which freed the renderer for good (spec section 6.5). Recorded once, at the first later call other than destroy() and the terminal calls, so an unmount that removes the DOM and then destroys records nothing. Pending and later Promise-returning calls reject AbortError; boot el again for a new session.

'render-lost'

The view stopped drawing: the graphics context was lost and came back neither on its own nor on a fresh canvas. The stage stays blank until the page reloads; offer a reload.

'host-unsized'

el has no size to draw at: under 64 CSS px on a side, or not rendered (display: none on it or an ancestor), at the first drawn frame or a resize; once until it has a size again. A div with no CSS height is not unsized: it takes the view's default 2:1 shape (BootOptions.el). Give el a CSS size for the shape you want, and show it.

'unknown-boot-option'

boot got an option this contract doesn't have; it was ignored.

'unknown-event'

on() got an event name that doesn't exist; it subscribed to nothing.

'invalid-input'

A call rejected or threw HoloInputError; recorded so an unawaited one is never silent.

'hotspot-id-taken'

Two hotspot badges share an id; the later one is skipped.

'deprecated'

Reserved for a labs member or value that will change; the strict fake throws on it. No 2.0.0 member is deprecated, so no 2.0.0 call records it.

'not-permitted'

A gated capability this account may not use (permits() is false).

'unknown-capability'

supports() got an id not in this runtime's KnownCapability, once per id per session; didYouMean names a 1.4 id's 2.0 id (none when the member is always present), else close known ids.

'connections-outdated'

Stored connections whose connectionsBasis no longer matches their nodes: none restored.

'read-while-queued'

Strict fake only: code read a target that still had a write queued behind a transaction.

Declaration

export type ProblemCode = 'target-unmatched' | 'target-ambiguous' | 'asset-failed' | 'asset-degraded' | 'ready-timeout' | 'transaction-timeout' | 'write-after-close' | 'beforeCommit-threw' | 'beforeCommit-slow' | 'connection-stale' | 'handle-disposed' | 'owner-disposed' | 'unsupported-spec' | 'not-storable' | 'space-not-storable' | 'frame-needs-compile' | 'frame-budget' | 'handler-threw' | 'hook-removed' | 'handler-async' | 'handler-rejected' | 'engine-conflict' | 'tenant-document-absent' | 'tenant-document-unavailable' | 'defaults-unavailable' | 'document-error' | 'apply-failed' | 'sync-failed' | 'host-disconnected' | 'render-lost' | 'host-unsized' | 'unknown-boot-option' | 'unknown-event' | 'invalid-input' | 'hotspot-id-taken' | 'deprecated' | 'not-permitted' | 'unknown-capability' | 'connections-outdated' | 'read-while-queued' | 'other';

Generic-API test (spec 3.1)

Rule	Result
1. Neutral name	pass: `ProblemCode` names no product
2. A precedent	pass: HTMLCanvasElement webglcontextlost (row `G51`)
3. Two apps, or labs	pass: 3 apps (ledger: app-4762caacdc, app-e3b47169bc, app-f9a32142f1)
4. The cheaper fix first	decided per need in Appendix B: rows `G51` at tier stable (a member only where no rule, data, asset or app code serves the need)

Rule

Result

1. Neutral name

pass: ProblemCode names no product

2. A precedent

pass: HTMLCanvasElement webglcontextlost (row G51)

3. Two apps, or labs

pass: 3 apps (ledger: app-4762caacdc, app-e3b47169bc, app-f9a32142f1)

4. The cheaper fix first

decided per need in Appendix B: rows G51 at tier stable (a member only where no rule, data, asset or app code serves the need)

ProblemCode ​

Problem codes ​

Declaration ​

Generic-API test (spec 3.1) ​

`ProblemCode`

Problem codes

Declaration

Generic-API test (spec 3.1)