# Holostep configurator runtime: contract 2.0

> The engine-neutral API a Holostep configurator page uses through `@holostep-configurators/runtime-client`: boot a session, change the scene model, restyle parts, move the camera, drag, assemble, capture and export. The package wins over any note.

Contract 2.0.0 · package sha256 `a857eca95b35921109faf997094bb4192f12527d9d0fcd4be7e97f06425bad6e` · generated by `services/onsite-scripter/scripts/build-contract-docs.mjs`; do not edit.

"Spec section N" and the short ids in parentheses (O6, R4, ID8, K47, …) in these pages and in the runtime's messages name the design record a rule comes from. The record is not shipped, and the package is complete without it: read them as provenance, never as something to look up.

## Start here

- [llms.txt](llms.txt): the one file to give an AI agent: the one obvious way, the ten likeliest mistakes, imports, boot and every call path. Each page here is also served as Markdown: swap `.html` for `.md`.

- [index.json](index.json): the machine-readable index: the page layout, every code and every member's call path.

## Read next

- [Read this first](read-this-first.md): the table, the traps and the conventions (units, kinds of call, order, read classes, errors).
- [The full declaration](llms-full.txt): this file, then `configurator-runtime.d.ts`, `math.d.ts` and `testing.d.ts` byte for byte.
- [Migrating from 1.x](MIGRATION.md): every 1.x member, pattern and document key with its 2.0 recipe.
- [Examples by area](examples/README.md): spec section 5's compiled examples.
- [Check it headless](check-headless.md): confirm in a headless browser that the product is on screen, lit and framed before hand-off (the fake draws no pixels).
- [Accessibility](accessibility.md): view controls for keyboard and switch users, status messages, the view's name.

## API pages

### 1. Basics

- [Point2](api/Point2.md): A 2D point or size.
- [Point3](api/Point3.md): A 3D point, vector or size.
- [ReadonlyPoint3](api/ReadonlyPoint3.md): An out-only position, never accepted as input: `Readonly<Point3>`, as `Pose` reads `Readonly<Quat>`.
- [Quat](api/Quat.md): Unit quaternion.
- [ScreenPoint](api/ScreenPoint.md): A `Point2` in CSS px from the viewer element's top-left corner; y grows downwards.
- [ProjectedPoint](api/ProjectedPoint.md): A projected point.
- [Bounds](api/Bounds.md): Axis-aligned world bounds, metres.
- [Ray](api/Ray.md): A ray in world space.
- [Insets](api/Insets.md): CSS px.
- [HexColor](api/HexColor.md): '#rgb' or '#rrggbb', sRGB.
- [ColorValue](api/ColorValue.md): A HexColor, or linear Rec.709 components 0..1.
- [JsonPrimitive](api/JsonPrimitive.md): A JSON leaf value.
- [JsonValue](api/JsonValue.md): Any JSON value: what `state()`, the commit feed, `meta` and checkpoints hold.
- [Easing](api/Easing.md): The time curve of a tween (pose, camera): the CSS Easing Functions Level 1 curves.
- [DeepReadonly](api/DeepReadonly.md): A value you may read and must not change: every property and array is readonly, at every depth.
- [PoseInput](api/PoseInput.md): A pose to write, with at most one rotation: `rotationDeg` or `quaternion`, never both (a type error; an untyped call with both rejects HoloInputError…
- [Pose](api/Pose.md): A pose read.

### 2. Operations, reports, causes, problems

- [Actor](api/Actor.md): Who made a write.
- [OpId](api/OpId.md): Session-unique, increasing, assigned at the call.
- [Outcome](api/Outcome.md): Where an operation ended.
- [Reason](api/Reason.md): Why an operation did not commit.
- [ReportFields](api/ReportFields.md): The fields every Report has.
- [Report](api/Report.md): The one result of every write, discriminated by `outcome`.
- [TransactionReport](api/TransactionReport.md): A transaction's report.
- [Cause](api/Cause.md): What caused a commit.
- [ProblemCode](api/ProblemCode.md): Open set: handle codes you don't know.
- [Problem](api/Problem.md): Data, never an Error: safe to store, send and render.

### 3. Errors

- [InputErrorCode](api/InputErrorCode.md): What a HoloInputError reports.
- [HoloInputError](api/HoloInputError.md): Invalid input to a call; nothing ran.
- [HoloScopeError](api/HoloScopeError.md): A write through the wrong writer.
- [HoloTransactionClosedError](api/HoloTransactionClosedError.md): A write through a `tx` (or a handle obtained from it) after that transaction closed.
- [HoloAssetError](api/HoloAssetError.md): An imperative load failed.
- [HoloBusyError](api/HoloBusyError.md): The runtime cannot serve the call now.
- [HoloBootError](api/HoloBootError.md): `boot` could not start the renderer.

### 4. Boot

- [boot](api/boot.md): Starts a session in `el`.
- [BootOptions](api/BootOptions.md): What `boot` takes.
- [RuntimeContract](api/RuntimeContract.md): The compatibility facts of this runtime build.
- [RUNTIME_CONTRACT](api/RUNTIME_CONTRACT.md): This runtime's contract, also exported by the bootstrap so an app can check it before `boot`.
- [RUNTIME_VERSION](api/RUNTIME_VERSION.md): The runtime build's version, e.g. '2.0.3'.

### 5. Writers, transactions, session

- [CommitOptions](api/CommitOptions.md): The options of a commit.
- [CheckpointOption](api/CheckpointOption.md): Page state stored atomically with a recorded commit.
- [NoCommitOptions](api/NoCommitOptions.md): What a write through a `tx` accepts in place of the commit options: none of them.
- [RecordedOptions](api/RecordedOptions.md): Recorded writes through `session` also take `checkpoint`.
- [CameraCommitOptions](api/CameraCommitOptions.md): The commit options a camera write takes: `origin`, `actor` and `expectRevision`.
- [SignalOption](api/SignalOption.md): The cancel option every write takes, through `session` and through a `tx`; registrations and waits take it too.
- [WriteOptions](api/WriteOptions.md): The options of a plain write through `session`.
- [TransactionOptions](api/TransactionOptions.md): The options of `session.transaction`: the commit options, a checkpoint, a signal and two time limits.
- [SessionState](api/SessionState.md): Recorded state plus the look.
- [JsonPatchOp](api/JsonPatchOp.md): RFC 6902 over `SessionState`.
- [SceneModelOptions](api/SceneModelOptions.md): The member options of `setSceneModel`.
- [Writer](api/Writer.md): The write surface `Session` and `Tx` share.
- [Tx](api/Tx.md): A transaction's scoped writer.
- [BeforeCommitContext](api/BeforeCommitContext.md): What a `beforeCommit` function receives.
- [HistoryGroupOptions](api/HistoryGroupOptions.md): What `history.group` takes.
- [HistoryGroup](api/HistoryGroup.md): The handle `history.group()` returns.
- [History](api/History.md): Undo state and grouping.
- [FrameOptions](api/FrameOptions.md): What `onFrame` takes.
- [NotAsync](api/NotAsync.md): A callback's return type with Promises excluded, so an `async` callback fails to compile.
- [Session](api/Session.md): A configurator session.

### 6. Queries, rules and parts

- [Role](api/Role.md): product: the configured thing (fit, AR, export, dimensions, picking).
- [Query](api/Query.md): All fields are ANDed; an array of queries matches any of them.
- [PartState](api/PartState.md): What a write through `find()` (a rule) may change.
- [PartWriteOptions](api/PartWriteOptions.md): The member options of a rule write (`set` on `Parts` or a `Part`).
- [FollowOptions](api/FollowOptions.md): What `follow` takes.
- [PartActions](api/PartActions.md): The actions that exist on one part and on a set of parts.
- [Parts](api/Parts.md): A saved search.
- [Part](api/Part.md): One part of a loaded model or a collection.
- [Placement](api/Placement.md): Where and how an imperatively created part sits.
- [Hit](api/Hit.md): A hit, on the session's input (so its part takes commit options).

### 7. Collections and shapes

- [CollectionOptions](api/CollectionOptions.md): What `collection(name, options)` takes.
- [Collection](api/Collection.md): Content you create.
- [CollectionReport](api/CollectionReport.md): `updated`: keys of items changed in place.
- [CollectionSpec](api/CollectionSpec.md): JSON form of a collection's content.
- [ItemBase](api/ItemBase.md): The fields every collection item has.
- [ItemSpec](api/ItemSpec.md): One collection item: `ItemBase` plus one kind.
- [Outline2D](api/Outline2D.md): Outline segments in 2D.
- [ShapeRef](api/ShapeRef.md): How reads return a `mesh` shape: JSON, as an `ImageRef` is for an image, so `state()`, the feed's `patch` and `inverse`, undo steps and event payloads carry…
- [Shape](api/Shape.md): Built shapes.
- [LinesSpec](api/LinesSpec.md): A lines item: a polyline in item-local metres.
- [LabelSpec](api/LabelSpec.md): A label drawn in the scene (text or image on a quad facing the camera).
- [LightSpec](api/LightSpec.md): Light intensity: KHR_lights_punctual units ×1, relative and not photometric (a sun of 3 lights white to about 1).
- [ShadowSpec](api/ShadowSpec.md): The runtime owns the shadow map and its filter per quality tier (`info().renderer.tier`): high 2048 px, medium 1024 px, low 1024 px with a tighter filter…

### 8. Materials and textures

- [MaterialInput](api/MaterialInput.md): A MaterialSpec, however complete, merges field by field (RFC 7396) over what the part wears (authored maps such as baked AO stay).
- [MapSlot](api/MapSlot.md): The map slots of a material (glTF and KHR names).
- [TextureSlot](api/TextureSlot.md): A map slot: a texture; 'none' (no map, whatever is underneath); or null (remove your value and show what is underneath).
- [Wrap](api/Wrap.md): How a texture repeats outside 0..1.
- [TextureSampling](api/TextureSampling.md): How a texture is filtered.
- [TextureInput](api/TextureInput.md): A URL, or a texture with placement.
- [ImageRef](api/ImageRef.md): How reads return a texture you wrote as an `image`: JSON, so `state()`, the feed, `applyPatch` and `sceneHash` stay JSON.
- [TextureSpec](api/TextureSpec.md): At most one of `url` and `image`.
- [MaterialSpec](api/MaterialSpec.md): glTF 2.0 and KHR names.
- [MaterialPatch](api/MaterialPatch.md): A MaterialSpec as a JSON Merge Patch (RFC 7396): what a rule's `material` takes.
- [Material](api/Material.md): A material parts wear: one `Part.material` reads, or one `materials.create` makes.
- [Materials](api/Materials.md): Create reusable materials and read stored ones.

### 9. Stage

- [BackgroundSpec](api/BackgroundSpec.md): What is drawn behind the scene, in the colour pipeline.
- [StageSettings](api/StageSettings.md): Colour pipeline: shading is linear Rec.709 in a frame of at least half-float.
- [StageWriteOptions](api/StageWriteOptions.md): The member options of `stage.set`.
- [Stage](api/Stage.md): The stage: layered settings over the document's.
- [RuleSpec](api/RuleSpec.md): One persistent rule in JSON form: what `find(query).set(set)` creates.
- [SceneSpec](api/SceneSpec.md): The look as one JSON document: what `apply()` writes (`state().look` reads it back as a `LookState`).
- [LookState](api/LookState.md): The look as `state().look` reads it: a read, not `apply()`'s input, so every key is present and none means "unchanged".

### 10. Camera

- [CameraView](api/CameraView.md): Orbit view.
- [LookAtView](api/LookAtView.md): A view by eye point and target.
- [CameraState](api/CameraState.md): Observed: as of the last drawn frame (this frame's inside `onFrame({ phase: 'late' })`).
- [CameraLimits](api/CameraLimits.md): A JSON Merge Patch (RFC 7396) over your app limits, which lie over the document's.
- [CameraLens](api/CameraLens.md): The camera's lens.
- [CameraMoveOptions](api/CameraMoveOptions.md): The member options of a camera move.
- [Camera](api/Camera.md): Camera writes are look-only and never undo steps; of the commit options they take only `origin`, `actor` and `expectRevision` (`CameraCommitOptions`).

### 11. Input and drag

- [PickOptions](api/PickOptions.md): What `input.pick` takes.
- [RaycastOptions](api/RaycastOptions.md): What `input.raycast` takes.
- [DragMove](api/DragMove.md): One frame of a drag.
- [DragOptions](api/DragOptions.md): What `input.drag` takes.
- [Input](api/Input.md): Picking, raycasts and drags on the canvas.

### 12. Assembly

- [ConnectorRef](api/ConnectorRef.md): One connector of one placed node.
- [Connection](api/Connection.md): Stored top-level in `IConfigurator.connections`.
- [Connector](api/Connector.md): Authored facts plus derived world positions (computed on read).
- [AttachOptions](api/AttachOptions.md): The member options of `assembly.attach`.
- [AttachReport](api/AttachReport.md): `attached: false` comes with `outcome: 'refused'` and a `reason` of 'no-candidate', 'occupied', 'rejected' or 'not-loaded': the first that applies, in the…
- [Assembly](api/Assembly.md): Connectors and connections between placed models (spec section 6.12).

### 13. Overlays

- [HotspotBadge](api/HotspotBadge.md): A badge the runtime draws as a `<button>`.
- [HotspotReference](api/HotspotReference.md): Which badge an event is about.
- [AnchorSpec](api/AnchorSpec.md): A point the runtime tracks on screen for your own DOM.
- [AnchorOptions](api/AnchorOptions.md): What `overlays.anchors.set` takes.
- [AnchorPosition](api/AnchorPosition.md): Where an anchor is on screen now.
- [DimensionFormat](api/DimensionFormat.md): How rulers print a length: the number to `decimals` places, a space and `unit` ('120 cm'), as 1.x printed its unit.
- [DimensionOptions](api/DimensionOptions.md): What `overlays.dimensions` takes.
- [Overlays](api/Overlays.md): Screen overlays.

### 14. Animations

- [ClipRef](api/ClipRef.md): Which clip: where its GLB sits and its name.
- [ClipInfo](api/ClipInfo.md): One authored clip of a loaded model.
- [PlayOptions](api/PlayOptions.md): The member options of `animations.play`.
- [Animations](api/Animations.md): Clip writes are look-only and not in the write queue: outside a transaction each starts at once, so plays called in the same task start in the same frame.

### 15. Frame writer

- [Frame](api/Frame.md): The synchronous per-frame writer for `onFrame` and drag `constrain`.

### 16. Capture, export, AR

- [CaptureSpec](api/CaptureSpec.md): What `capture` takes.
- [CaptureResult](api/CaptureResult.md): What a capture returns.
- [ExportOptions](api/ExportOptions.md): What `export` takes.
- [ExportResult](api/ExportResult.md): What `export` returns.
- [ActivateAROptions](api/ActivateAROptions.md): What `activateAR` takes.
- [ActivateARReport](api/ActivateARReport.md): How an AR launch went.
- [TryOnKind](api/TryOnKind.md): The kind of try-on a product's rig is for: 'face' (glasses), 'foot' (shoes), 'wrist' (watches and bracelets), 'finger' (rings), 'ear' (earrings), 'head' (hats).
- [TryOnMode](api/TryOnMode.md): Where try-on runs: 'here' in this page, 'handoff' on another device, a phone that opens the hand-off's link (`TryOnReport.handoffUrl`).
- [TryOnUnavailable](api/TryOnUnavailable.md): Why try-on isn't available: 'not-enabled' (the account offers no try-on of this kind, or has not set its consent mode, which every kind needs; a page document…
- [TryOnAvailability](api/TryOnAvailability.md): `canTryOn()`'s answer for the product on screen, now.
- [TryOnOptions](api/TryOnOptions.md): What `tryOn` takes.
- [TryOnReport](api/TryOnReport.md): What `tryOn` resolves with once try-on closed or could not open.

### 17. Assets: describe, manifest, validation

- [AssetInfo](api/AssetInfo.md): The GLB a ModelNode shows.
- [ManifestPart](api/ManifestPart.md): One authored part.
- [ManifestSlot](api/ManifestSlot.md): One authored material slot.
- [ManifestConnector](api/ManifestConnector.md): Local frame of the GLB.
- [AssetManifest](api/AssetManifest.md): The per-GLB manifest (`asset.extras.holostep.manifest`, and the sidecar).
- [ModelDescription](api/ModelDescription.md): What `describe(node)` returns.
- [ValidationKind](api/ValidationKind.md): Open registry: later kinds ('product') are added without a breaking change.
- [ValidationResult](api/ValidationResult.md): What `validate` returns.
- [IssueCode](api/IssueCode.md): What an `Issue` reports: an `InputErrorCode`, a `checkAsset` check, or a value the stored format can't hold.
- [Issue](api/Issue.md): One failed check at a path: what `validate` and `checkAsset` return, and what a HoloInputError carries.

### 18. Events

- [Events](api/Events.md): Typed events.

### 19. Info and capabilities

- [InfoReport](api/InfoReport.md): A diagnostic snapshot (`session.info()`).
- [KnownCapability](api/KnownCapability.md): Capability ids, one per capability in the coverage ledger (`coverage.json`).
- [Capability](api/Capability.md): Open, so an app built against a newer contract can ask about ids this runtime lacks.

### 20. Labs

- [GeometryAttribute](api/GeometryAttribute.md): A vertex attribute `labs.geometry.read` can return.
- [GeometryData](api/GeometryData.md): Local space of the part (for a skinned mesh: its bind space).
- [GeometryWrite](api/GeometryWrite.md): New vertex data for `labs.geometry.write`: same vertex count and order as the part's.
- [SkinBinding](api/SkinBinding.md): Binds a collection mesh to a loaded model's skeleton.
- [DecalSpec](api/DecalSpec.md): A projected decal with depth.
- [FireSpec](api/FireSpec.md): Volumetric fire, as `labs.fire` draws it.
- [ShadingUniformType](api/ShadingUniformType.md): The type of a shading graph input.
- [ShadingNode](api/ShadingNode.md): A node output in a shading graph, typed by what it carries.
- [ShadingNodes](api/ShadingNodes.md): 2.0's node set, by MaterialX 1.38's node and input names (`stdlib_defs.mtlx`): `add`, `subtract`, `multiply`, `divide`, `power`, `absval`, `clamp`, `min`, …
- [ShadingOutputs](api/ShadingOutputs.md): The camelCased `gltf_pbr` inputs; omitted ones keep the material's.
- [ShadingValue](api/ShadingValue.md): What `Shading.set` takes for a uniform of type `T`: a number for 'float', a `Point2` for 'vector2', a `Point3` for 'vector3', a `ColorValue` or linear…
- [Shading](api/Shading.md): A shading graph, worn through `MaterialSpec.labs.shading`.
- [Labs](api/Labs.md): Members that serve one app or wrap an engine-shaped capability.

### 21. Stored data (vendored; replaces @holo/interfaces)

- [IPrice](api/IPrice.md): A stored price of a MaterialNode (the product envelope; the runtime never prices).
- [IGradientColorStop](api/IGradientColorStop.md): A stored gradient stop.
- [GradientDirection](api/GradientDirection.md): The direction of a stored gradient background.
- [IGradientBackground](api/IGradientBackground.md): A stored gradient background.
- [BackgroundValue](api/BackgroundValue.md): A stored background: a 0xRRGGBB number, null (no stored background), or a gradient.
- [IDefaultView](api/IDefaultView.md): Stored angles are degrees.
- [IGlobalMaterialListEntry](api/IGlobalMaterialListEntry.md): A stored binding of meshes to a global-material GroupNode.
- [IMagneticPlaneConfig](api/IMagneticPlaneConfig.md): A stored connector-plane config, matched to a connector plane by `meshName`.
- [IMagneticPlaneRule](api/IMagneticPlaneRule.md): A stored rule that gives a GroupNode's child models plane configs by mesh-name pattern.
- [IChildDefaults](api/IChildDefaults.md): Stored defaults a GroupNode gives its children.
- [IPresetNode](api/IPresetNode.md): One node's state in a stored preset.
- [IPreset](api/IPreset.md): A stored preset: a named set of node states.
- [IConfiguratorNode](api/IConfiguratorNode.md): The fields every stored node has.
- [IGroupNode](api/IGroupNode.md): A stored group: a choice among its children, or a global-material group (`globalMaterial: true`) that `select` writes.
- [IModelNode](api/IModelNode.md): Stored GLB node.
- [TextureChannel](api/TextureChannel.md): The texture channels of a stored MaterialNode (`{channel}TextureUrl`); `materialSpecFromNode` maps them to `MapSlot`s.
- [IMaterialNode](api/IMaterialNode.md): Stored MaterialNode (format unchanged).
- [ConfiguratorNode](api/ConfiguratorNode.md): Any stored node.
- [IConfigurator](api/IConfigurator.md): The stored configurator document.
- [SceneModel](api/SceneModel.md): What the runtime renders: the IConfigurator fields it reads.
- [ViewerDocumentJson](api/ViewerDocumentJson.md): The viewer document, version 2: the page's defaults for the typed members, as JSON.
- [ApplyReport](api/ApplyReport.md): The result of applying a document layer.

### 22. Pure helpers (root of the package; run in Node and the fake)

- [duplicateNodes](api/duplicateNodes.md): Copies nodes with new ids.
- [LegacyNode](api/LegacyNode.md): A node as old saves store it: `nodeId` may be missing or repeated.
- [LegacyDocument](api/LegacyDocument.md): A document as old saves store it.
- [normalizeNodeIds](api/normalizeNodeIds.md): Repairs old saves: mints missing ids, re-mints duplicates, remaps `defaultNodeId`, preset node ids, `globalMaterialList[].globalMaterial` and connections, and…
- [connectionsBasis](api/connectionsBasis.md): The basis fingerprint to store beside `connections`, as `IConfigurator.connectionsBasis`: sha256 (hex) of the canonical JSON (RFC 8785) of `nodeId`, `glbUrl`…
- [cameraViewFromStored](api/cameraViewFromStored.md): A stored `defaultView` (`IConfigurator.defaultView`, `SceneModel.defaultView`: degrees, named `azimuth`, `polar`, `radius`) as the `CameraView` `camera.set`…
- [materialSpecFromNode](api/materialSpecFromNode.md): Stored MaterialNode → partial MaterialSpec.
- [materialNodeFromSpec](api/materialNodeFromSpec.md): MaterialSpec → stored MaterialNode fields, applied over `base` (envelope, prices and `opt…` URLs kept).
- [validate](api/validate.md): Validates a value against the package's JSON Schemas.
- [CapabilityMembers](api/CapabilityMembers.md): The members each experimental capability id unlocks.
- [has](api/has.md): How app code reaches an experimental member: a type guard over `session.supports(id)`.
- [AssetContract](api/AssetContract.md): What an app needs from an asset.
- [checkAsset](api/checkAsset.md): The shared `check()`: the server stampers, Asset Library QA, the Blender helper and the runtime run this one function.

### 23. /math

- [math.Mat4](api/math.Mat4.md): A 4×4 affine matrix: 16 values, column-major (as glTF and `Shape.transform`).
- [math.vec3](api/math.vec3.md): 3D vectors and points.
- [math.quat](api/math.quat.md): Unit quaternions.
- [math.mat4](api/math.mat4-value.md): 4×4 matrices.
- [math.box3](api/math.box3.md): Axis-aligned boxes.
- [math.ray](api/math.ray.md): Rays.
- [math.plane](api/math.plane.md): Planes as `{ normal, constant }`: the points p with dot(normal, p) + constant = 0.
- [math.outline](api/math.outline.md): 2D outlines for shapes.
- [math.color](api/math.color.md): sRGB hex colours and linear components.
- [math.angle](api/math.angle.md): Angles.
- [math.projection](api/math.projection.md): Projection through a camera you describe, not the live one (`camera.project` projects through `camera.state` only): where points land in a capture before you…

### 24. /testing

- [testing.FakeModel](api/testing.FakeModel.md): A GLB as the fake knows it: its node tree, connectors, manifest, clips and load behaviour.
- [testing.FakeSessionOptions](api/testing.FakeSessionOptions.md): What `createFakeSession` takes.
- [testing.TraceEntry](api/testing.TraceEntry.md): One step of an operation through the states of spec section 6.2.
- [testing.FakeSession](api/testing.FakeSession.md): A `Session` that runs in Node with fake timers, plus controls for tests.
- [testing.createFakeSession](api/testing.createFakeSession.md): A fake session: the runtime's own implementation of the spec's section 6 tables, without a renderer.
- [testing.fakeModelFromGlb](api/testing.fakeModelFromGlb.md): A `FakeModel` read from a GLB with no browser, so a test drives the fake with the product it ships instead of a hand-written tree: `nodes` in the scene's…
- [testing.ManifestFromGlbOptions](api/testing.ManifestFromGlbOptions.md): What `manifestFromGlb` takes besides the bytes.
- [testing.manifestFromGlb](api/testing.manifestFromGlb.md): A GLB's manifest, read with no browser and no engine (Node 20 or later, or a page), for an author with a file and no human: its parts, slots, connector…

## Codes

### Problem codes (`ProblemCode`)

- [target-unmatched](problems/target-unmatched.md): 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); …
- [target-ambiguous](problems/target-ambiguous.md): A single-part member (`follow` target, `attachTo`) matched several parts; nothing applied.
- [asset-failed](problems/asset-failed.md): A GLB, texture or HDR failed in a declarative write; the write committed without it.
- [asset-degraded](problems/asset-degraded.md): 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`…
- [ready-timeout](problems/ready-timeout.md): Readiness expired: the commit shows with stand-ins or old looks until assets decode.
- [transaction-timeout](problems/transaction-timeout.md): A transaction made no progress for `timeoutMs`, or hit the hold cap; it rolled back.
- [write-after-close](problems/write-after-close.md): A write through a closed `tx` or its handles (HoloTransactionClosedError).
- [beforeCommit-threw](problems/beforeCommit-threw.md): A `beforeCommit` function threw, or was pending after 10 s; its writes were undone.
- [beforeCommit-slow](problems/beforeCommit-slow.md): 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](problems/connection-stale.md): A connection's planes no longer meet (0.5 mm, 0.5°); it was dropped.
- [handle-disposed](problems/handle-disposed.md): A disposed handle or removed part was used; nothing happened.
- [owner-disposed](problems/owner-disposed.md): 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…
- [unsupported-spec](problems/unsupported-spec.md): 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…
- [not-storable](problems/not-storable.md): 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…
- [space-not-storable](problems/space-not-storable.md): 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](problems/frame-needs-compile.md): A `Frame.material` value needs a new shader; it was skipped.
- [frame-budget](problems/frame-budget.md): 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,…
- [handler-threw](problems/handler-threw.md): An event handler or frame hook threw (a hook that throws 3 frames in a row is removed: 'hook-removed').
- [hook-removed](problems/hook-removed.md): 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…
- [handler-async](problems/handler-async.md): An event handler returned a Promise (an untyped call); it was not awaited.
- [handler-rejected](problems/handler-rejected.md): A Promise an event handler returned rejected.
- [engine-conflict](problems/engine-conflict.md): Another 3D engine instance on the page conflicts with the runtime's (`info().renderer.engineConflict`).
- [tenant-document-absent](problems/tenant-document-absent.md): No stored viewer-document layer for `configuratorId` (a 404; `info().document.layers` 'tenant'): the layers below apply.
- [tenant-document-unavailable](problems/tenant-document-unavailable.md): The stored viewer-document layer couldn't be fetched (any failure but a 404); the session runs with the layers below.
- [defaults-unavailable](problems/defaults-unavailable.md): The platform or account defaults couldn't be fetched; built-in defaults apply.
- [document-error](problems/document-error.md): A document layer has an invalid or version-1 key; `didYouMean` names its 2.0 home.
- [apply-failed](problems/apply-failed.md): 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`, …
- [sync-failed](problems/sync-failed.md): 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`…
- [host-disconnected](problems/host-disconnected.md): `el` left the document after `boot`, which freed the renderer for good (spec section 6.5).
- [render-lost](problems/render-lost.md): The view stopped drawing: the graphics context was lost and came back neither on its own nor on a fresh canvas.
- [host-unsized](problems/host-unsized.md): `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.
- [unknown-boot-option](problems/unknown-boot-option.md): `boot` got an option this contract doesn't have; it was ignored.
- [unknown-event](problems/unknown-event.md): `on()` got an event name that doesn't exist; it subscribed to nothing.
- [invalid-input](problems/invalid-input.md): A call rejected or threw HoloInputError; recorded so an unawaited one is never silent.
- [hotspot-id-taken](problems/hotspot-id-taken.md): Two hotspot badges share an `id`; the later one is skipped.
- [deprecated](problems/deprecated.md): Reserved for a labs member or value that will change; the strict fake throws on it.
- [not-permitted](problems/not-permitted.md): A gated capability this account may not use (`permits()` is false).
- [unknown-capability](problems/unknown-capability.md): `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…
- [connections-outdated](problems/connections-outdated.md): Stored connections whose `connectionsBasis` no longer matches their nodes: none restored.
- [read-while-queued](problems/read-while-queued.md): Strict fake only: code read a target that still had a write queued behind a transaction.

### Input-error codes (`InputErrorCode`)

- [invalid-input](input-errors/invalid-input.md): A value or combination the member refuses, e.g. a zero `PoseInput.scale` component.
- [missing-node-id](input-errors/missing-node-id.md): A node without a `nodeId` (spec section 6.9, ID9).
- [duplicate-node-id](input-errors/duplicate-node-id.md): Two nodes share a `nodeId` (ID9); `normalizeNodeIds` repairs an old save.
- [rotation-twice](input-errors/rotation-twice.md): An untyped pose or patch with both rotations, `rotationDeg` and `quaternion`.
- [unknown-field](input-errors/unknown-field.md): A field the spec or schema of the page's declared `contract` doesn't have, or an `applyPatch` node field path whose field the stored node format doesn't have and the node doesn't…
- [unknown-id](input-errors/unknown-id.md): An id that names nothing the member takes, e.g. a `select` group that is no global-material GroupNode, a view not in `camera.views`, an `ImageRef` or `ShapeRef` that is not live,…
- [option-in-transaction](input-errors/option-in-transaction.md): A commit option passed through a `tx` by an untyped call; always thrown at the call.
- [collection-role-mismatch](input-errors/collection-role-mismatch.md): `collection()` on a live name with another role.
- [collection-options-mismatch](input-errors/collection-options-mismatch.md): `collection()` on a live name with another `attachTo`.
- [duplicate-rule-id](input-errors/duplicate-rule-id.md): Two rules of one `apply()` `rules` list share an id (spec section 6.10, R3).
- [checkpoint-rejected](input-errors/checkpoint-rejected.md): Page state over 256 KB of canonical JSON (`CheckpointOption`).
- [capture-displayed-fixed](input-errors/capture-displayed-fixed.md): `source: 'displayed'` with a `view`, `size`, `pixelRatio` or a `background` other than 'scene'.
- [not-draggable](input-errors/not-draggable.md): `startDrag` on a unit that no live registration names.

### Issue codes (`IssueCode`)

- [element](issues/element.md): `checkAsset`: the manifest's `element` matches none of the contract's globs.
- [part](issues/part.md): `checkAsset`: a contract part is missing where `required`, or has another tag, or a slot that is neither its `slot` nor one of its `slots`.
- [slot](issues/slot.md): `checkAsset`: a contract slot the manifest lacks, or one without `uvMetres` where `realSize` asks for it.
- [connector](issues/connector.md): `checkAsset`: fewer connectors of a type than the contract's `count`.
- [animation](issues/animation.md): `checkAsset`: a contract clip name the asset lacks.
- [connector-name-collision](issues/connector-name-collision.md): `checkAsset`: two connector planes whose authored names clean to the same name (spec section 6.9, ID1).
- [connector-id](issues/connector-id.md): `checkAsset`: an `extras.holostep.connector.id` that contains ':' (ID1).
- [not-storable](issues/not-storable.md): `validate`: a value the stored format can't hold.
- [space-not-storable](issues/space-not-storable.md): `validate('configurator')`: `space: 'parent'` in a document meant to be saved.