@vincentt-xr/sdk 2.0.0-alpha.0 → 2.0.0-alpha.2

package/docs/api/face-attribute-expression.mdx

@@ -0,0 +1,87 @@
+---
+title: "Face Attribute Expression"
+description: "Image-based angry, disgust, fear, happy, neutral, sad, surprise, and unknown classification."
+sidebarTitle: "Face Attribute Expression"
+icon: "face-smile"
+---
+
+Face Attribute Expression classifies a 112×112 RGB face crop with the OpenCV
+MobileFaceNet INT8 model. It is independent from `FaceInfo.blendshapes`:
+blendshapes describe physical facial movement, while this API runs image
+inference.
+
+```tsx
+import { useFaceAttributeExpression, useFaceInfo } from "@vincentt-xr/sdk/tracking";
+
+function ExpressionLogic() {
+  const face = useFaceInfo();
+  const attribute = useFaceAttributeExpression(face, {
+    targetFps: 5,
+    minConfidence: 0.55,
+  });
+
+  if (attribute.status !== "ready") return null;
+  console.log(attribute.result.expression, attribute.result.confidence);
+  console.log(attribute.result.scores.happy);
+  return null;
+}
+```
+
+The hook must run inside `XRProvider` and `XRScene`. It reuses the session's
+tracker-input frame and caller-owned `FaceInfo`; it starts neither another
+camera nor another face detector. The model is lazy-loaded only after a face is
+available.
+
+## Result
+
+`status` is `idle`, `loading`, `ready`, or `error`. `result` is non-null when
+ready and contains:
+
+- `expression`: `angry`, `disgust`, `fear`, `happy`, `neutral`, `sad`,
+  `surprise`, or `unknown`.
+- `confidence`: the winning model probability in `[0, 1]`.
+- `scores`: probabilities for the seven model classes. It intentionally has no
+  `unknown` score because `unknown` is a threshold fallback, not a model class.
+
+A winning score below `minConfidence` returns `unknown`. It means the model ran
+but did not produce a confident classification.
+
+## Options
+
+| Option          | Default       | Meaning                                     |
+| --------------- | ------------- | ------------------------------------------- |
+| `active`        | `true`        | Pause expression inference when false       |
+| `targetFps`     | `5`           | Maximum classifier inference rate           |
+| `minConfidence` | `0.55`        | Threshold below which the result is unknown |
+| `modelUrl`      | SDK model URL | Override with an exact-contract ONNX model  |
+
+A custom model must accept float32 NCHW input `[1, 3, 112, 112]`: planar RGB,
+normalized to `[-1, 1]`. It must return seven logits in this exact order:
+`angry`, `disgust`, `fear`, `happy`, `neutral`, `sad`, `surprise`. A generic
+MobileFaceNet model is not necessarily compatible.
+
+The default validated model is approximately 1.36 MB and is fetched separately
+from the application bundle. Its bytes are SHA-384 verified before ONNX Runtime
+loads them. ONNX Runtime's WASM worker files load from a version-pinned CDN
+path matching the active `onnxruntime-web` runtime, so consumers do not need a
+Vite `?url` asset pipeline for the runtime. Those runtime files are fetched
+from jsDelivr without SDK-managed SRI because ONNX Runtime resolves its own WASM
+assets.
+
+The default ONNX Runtime backend uses threaded SIMD WASM when available. Deploy
+pages that use this hook with cross-origin isolation headers for best threaded
+performance:
+
+```http
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+```
+
+Without those headers, ONNX Runtime falls back to single-threaded WASM.
+
+Treat classifications as model estimates of visible facial expression—not
+ground-truth emotion, intent, identity, or mental state.
+
+Use the verified `/facial-movement-expression` page to inspect the live winning
+class and all seven probabilities. Its real-camera model flow, including every
+expression class, was verified on 26 July 2026.

package/docs/api/face-binding-anchors.mdx

@@ -0,0 +1,53 @@
+---
+title: "Face Binding Anchors"
+description: "Verified semantic face presets, custom face-local anchors, smoothing, and roll following."
+sidebarTitle: "Face Binding Anchors"
+icon: "locate-fixed"
+---
+
+Use `TrackingAnchor` to attach content to semantic face locations. Build editor
+dropdowns from `FACE_TARGETS`; do not copy landmark indices or invent target
+strings. Left and right use the tracked person's perspective.
+
+## Presets
+
+`face.center`, `face.forehead`, `face.noseTip`, `face.chin`, `face.leftEye`,
+`face.rightEye`, `face.leftEyeOuter`, `face.rightEyeOuter`, `face.leftCheek`,
+`face.rightCheek`, `face.mouthCenter`, `face.leftEarlobe`,
+`face.rightEarlobe`, and `face.custom` are supported.
+
+```tsx
+import { FaceTracker, TrackingAnchor } from "@vincentt-xr/sdk/tracking";
+
+<FaceTracker followFaceRoll>
+  <TrackingAnchor target="face.rightEarlobe" smoothing={15}>
+    <mesh />
+  </TrackingAnchor>
+</FaceTracker>;
+```
+
+Eye presets resolve composite eye centers; `*EyeOuter` presets are exact outer
+corners. Earlobes use the nearest stable face-oval landmarks because MediaPipe
+does not provide anatomical earlobe points.
+
+## Custom points
+
+For `face.custom`, pass `customAnchorPoint`. X and Y are clamped to `[-1, 1]`;
+the origin is face center, X runs from the person's left to right, Y runs from
+chin to forehead, and positive Z points toward the camera.
+
+```tsx
+<TrackingAnchor target="face.custom" customAnchorPoint={{ x: 0.7, y: 0.2, z: 0 }} smoothing={15}>
+  <mesh />
+</TrackingAnchor>
+```
+
+`smoothing > 0` uses the same One Euro filter for 2D and 3D bindings. Around
+`15` is a useful default; `0` snaps to each result. The filter resets on face
+loss and reacquisition. Rotation is not smoothed.
+
+For serialized 2D scenes, combine `ScreenTransform` and `TrackingAnchor` on a
+null parent, then place modular Screen Shape/Text/Image children beneath it.
+`followFaceRoll` controls whether the group tilts with head roll. The verified
+`/face-binding-anchors` example exposes every preset on the editable `rose null`
+while its hierarchy shows only that combined parent.

package/docs/api/face-effects.mdx

@@ -0,0 +1,19 @@
+---
+title: "Face Effects"
+description: "Overview of the face mesh, face painting, and face retouching docs."
+sidebarTitle: "Face Effects"
+icon: "sparkles"
+---
+
+This section is split into focused pages:
+
+- [Face Mesh](/api/face-mesh) for the base 3D face mesh, canonical renderer,
+  and face mesh material settings.
+- [Face Painting](/api/face-painting) for the composite shader variant used to
+  paint onto the live face mesh.
+- [Face Retouching](/api/face-retouching) for the legacy skin-retouch shader
+  and its controls.
+
+Use `@vincentt-xr/sdk/tracking` for trackers, `FaceInfo`, Face Actions, and the
+bare deforming `FaceMesh`. Use `@vincentt-xr/sdk/face-effects` for the modular
+face-effect surface.

package/docs/api/face-info.mdx

@@ -0,0 +1,112 @@
+---
+title: "FaceInfo"
+description: "Verified face pose, landmarks, bounds, scale, and expression data for effect logic."
+sidebarTitle: "FaceInfo"
+icon: "scan-face"
+---
+
+Use `FaceInfo` instead of reading raw MediaPipe results or copying landmark
+indices into effect logic.
+
+```tsx
+import { hasFaceExpression, useFaceInfo } from "@vincentt-xr/sdk/tracking";
+
+function FaceLogic() {
+  const face = useFaceInfo({ active: true });
+  if (!face) return null;
+
+  const mouthOpen = hasFaceExpression(face, "jawOpen");
+  const lookingLeft = face.pose.rotation.y > 0.2;
+  return <group visible={mouthOpen} rotation-y={lookingLeft ? 0.2 : 0} />;
+}
+```
+
+## Coordinate contract
+
+| Field           | Contract                                                  |
+| --------------- | --------------------------------------------------------- |
+| `index`         | Current result-array index, not a persistent identity     |
+| `landmarks`     | Normalized tracker-input coordinates with top-left origin |
+| `bounds`        | Bounds in the same normalized coordinate system           |
+| `pose.position` | Three.js world position                                   |
+| `pose.rotation` | Radians: pitch X (+up), yaw Y (+left), roll Z             |
+| `pose.scale`    | Smoothed uniform face-sizing heuristic                    |
+| `eyeDistance`   | Outer-eye distance in normalized coordinates              |
+| `blendshapes`   | Typed MediaPipe category scores in `[0, 1]`               |
+
+`useFaceInfo({ faceIndex })` reads one face. `useFaceInfos({ numFaces })` reads
+all current faces. Both share the SDK face model and support `active`,
+`numFaces`, `targetFps`, `throttleMs`, and `holdMs`.
+
+## Face detection lifecycle
+
+Use `useFaceDetection` when effect logic needs face presence, face count, or
+appearance/disappearance edges. It wraps the same shared `useFaceInfos` reader;
+it does not start another model or polling loop.
+
+```tsx
+const detection = useFaceDetection({ faceIndex: 0, numFaces: 5 });
+
+if (detection.justDetected) showEffect();
+if (detection.detected) updateEffect(detection.face);
+if (detection.justLost) hideEffect();
+```
+
+| Lifecycle node output | SDK result                             |
+| --------------------- | -------------------------------------- |
+| Begin                 | `justDetected` or `phase === "begin"`  |
+| Stay                  | `detected` or `phase === "stay"`       |
+| End                   | `justLost` or `phase === "end"`        |
+| None                  | `!detected` or `phase === "none"`      |
+| Face Count            | `faceCount`                            |
+| Which Face            | `faceIndex` option and selected `face` |
+
+The result also includes `faces`. The default `holdMs: 250` suppresses brief
+one-frame losses before `End`; pass `holdMs: 0` for immediate disappearance.
+Use the verified `/face-detection` page to test five face slots,
+Begin/Stay/End/None, selected-face presence, count, and edge history. Its
+real-camera lifecycle flow was verified on 26 July 2026.
+
+Use `FACE_BLENDSHAPE_NAMES`, `getFaceBlendshape`, and `hasFaceExpression` rather
+than guessing names or thresholds. The typed list includes `jawOpen`, blink,
+and eye-wide expressions.
+
+For semantic blink, brow, mouth, or head gestures, use the Face Actions API.
+Face Actions represent physical movement, not inferred expression. Use
+`useFaceAttributeExpression` when an effect needs image-based angry, disgust,
+fear, happy, neutral, sad, surprise, or unknown classification.
+`getFaceActionValue`, `hasFaceAction`, and `useFaceAction` own the action names,
+pose directions, thresholds, hysteresis, and hold timing. Keep raw blendshapes
+for custom continuous expressions that Face Actions do not cover.
+
+## Reusable face image crops
+
+Use `drawFaceCrop` when an image model or preview needs pixels for one detected
+face. It uses `FaceInfo.bounds`, expands by 20% by default, preserves the output
+pixel aspect ratio, clamps at image edges, and writes into caller-owned canvas
+storage.
+
+```ts
+import { drawFaceCrop } from "@vincentt-xr/sdk/tracking";
+
+const cropCanvas = document.createElement("canvas");
+drawFaceCrop({
+  source: video,
+  face,
+  canvas: cropCanvas,
+  outputSize: { width: 224, height: 224 },
+});
+```
+
+For non-face regions, import `drawNormalizedCrop` from the core package and
+pass any normalized `{ minX, minY, maxX, maxY }` bounds. Both functions return
+`false` when the source, bounds, output size, or 2D context is unusable. They do
+not allocate a canvas, start tracking, mirror pixels, or run inference.
+
+For existing low-level frame loops, import `getFaceInfo` and
+`createFaceInfoTarget` from `@vincentt-xr/sdk/low-level`, allocate the target
+once, and reuse it. For overlays, convert landmarks with
+`normalizedToScreenPixels`; do not mirror or cover-map tracker points again.
+
+The verified `/face-info` example displays all landmarks, live bounds, pose,
+eye distance, jaw-open state, and a 3D `Axes` gizmo using SDK components.

package/docs/api/face-mesh.mdx

@@ -0,0 +1,98 @@
+---
+title: "Face Mesh"
+description: "Base 3D face mesh rendering, canonical mesh support, and mesh deformation settings."
+sidebarTitle: "Face Mesh"
+icon: "scan-face"
+---
+
+Use `@vincentt-xr/sdk/tracking` for the bare deforming `FaceMesh`. Use
+`@vincentt-xr/sdk/face-effects` for the scene-object renderer, shared material
+settings, canonical renderer, and face warp utilities.
+
+## Bare FaceMesh
+
+```tsx
+import { FaceMesh, FaceTracker } from "@vincentt-xr/sdk/tracking";
+
+<FaceTracker>
+  <FaceMesh appearance={{ color: "#00e5ff", wireframe: true }} />
+</FaceTracker>;
+```
+
+## Scene-object FaceMeshRenderer
+
+Prefer `FaceMeshRenderer` for editor/runtime scene-object integrations. It owns
+face tracking internally through `FaceTracker`, reads live landmarks, deforms
+the canonical face mesh, and uses the shared FaceMesh material settings.
+
+```tsx
+import {
+  DEFAULT_FACE_MESH_RENDERER,
+  DEFAULT_FACE_MESH_TRANSFORM,
+  FACE_MESH_MATERIAL_TYPES,
+  FACE_MESH_SIDES,
+  type FaceMeshRendererSettings,
+} from "@vincentt-xr/sdk/face-effects";
+import {
+  createDefaultComponent,
+  createDefaultFaceMeshRendererSettings,
+} from "@vincentt-xr/sdk/scene-object";
+
+const objectId = "face-mesh";
+const transform = createDefaultComponent("Transform", objectId);
+transform.settings.position.y = DEFAULT_FACE_MESH_TRANSFORM.position.y;
+
+const faceMesh = createDefaultComponent("FaceMeshRenderer", objectId);
+faceMesh.settings = {
+  ...createDefaultFaceMeshRendererSettings(),
+  materialType: FACE_MESH_MATERIAL_TYPES.wireframe,
+  side: FACE_MESH_SIDES.double,
+  baseColor: "#00e5ff",
+  opacity: 0.82,
+} satisfies FaceMeshRendererSettings;
+```
+
+`DEFAULT_FACE_MESH_RENDERER` is the serialized renderer default.
+`mapFaceMeshRendererSettingsToProps(settings)` bridges serialized settings to
+`CanonicalFaceMeshRendererProps`. `resolveFaceMeshRendererSettings(current,
+patch)` is the edit-time source of truth: use it whenever material, shader,
+texture, blend, or mask state changes.
+
+FaceMesh `Transform` is intentionally not normal world-space `Transform3D`.
+`SceneObjectRenderer` passes an authored `Transform` into `FaceMeshRenderer`,
+and FaceMesh applies supported values in MediaPipe landmark space before camera
+projection. Supported values are position and uniform scale only. Rotation and
+non-uniform scale are ignored until the SDK has a real object-space face solve.
+Authored `position.y` is Y-up; MediaPipe image-space Y is down, so the renderer
+subtracts Y while adding X/Z. `DEFAULT_FACE_MESH_TRANSFORM.position.y` is
+`0.001` as a default authoring bias; set it to `0` to opt out.
+
+## Canonical Renderer
+
+`CanonicalFaceMeshRenderer` remains public for low-level experiments and
+backwards compatibility. New scene-object work should use `FaceMeshRenderer`.
+
+```tsx
+import { CanonicalFaceMeshRenderer, FACE_WARP_3D_PRESET } from "@vincentt-xr/sdk/face-effects";
+
+<CanonicalFaceMeshRenderer
+  materialType="shader"
+  shaderPreset="originalFace"
+  textureMap="none"
+  alphaMap="canonical"
+  faceWarp3D={FACE_WARP_3D_PRESET}
+/>;
+```
+
+`useCanonicalFaceMesh` loads and caches the canonical mesh.
+`parseCanonicalFaceModel` parses canonical-compatible OBJ text.
+`canonicalFaceTextureUrl`, `canonicalFaceTextureStyle2Url`, and
+`canonicalFaceAlphaMaskUrl` are SDK-hosted runtime texture defaults.
+
+## FaceWarp3D
+
+`FACE_WARP_3D_PRESET`, `DEFAULT_FACE_WARP_3D_SETTINGS`, and
+`FaceWarp3DSettings` cover face, forehead, cheek, eye, nose, mouth, jaw, and
+chin proportions with normalized values around zero. Use `faceWarp3D` on
+`CanonicalFaceMeshRenderer` or `FaceMeshRenderer` settings instead of writing a
+second landmark deformation path.

package/docs/api/face-painting.mdx

@@ -0,0 +1,33 @@
+---
+title: "Face Painting"
+description: "Composite shader face painting on the live 3D face mesh."
+sidebarTitle: "Face Painting"
+icon: "paintbrush"
+---
+
+Use `FaceMeshRenderer` with the `composite` shader preset when you want the
+live face mesh to act like a painted surface.
+
+```tsx
+import {
+  FACE_MESH_SHADER_PRESETS,
+  resolveFaceMeshRendererSettings,
+} from "@vincentt-xr/sdk/face-effects";
+
+const next = resolveFaceMeshRendererSettings(current, {
+  shaderPreset: FACE_MESH_SHADER_PRESETS.composite,
+});
+```
+
+Shader presets are `originalFace` and `composite`. Selecting `composite`
+applies the SDK composite defaults: canonical texture, hard-light blend,
+`blendOpacity: 0.85`, and `compositeShading: true`.
+
+`maskTextureSource` is `solid`, `gradient`, `imageUrl`, or `mediaUrl`. Solid and
+gradient masks use `maskColor`; URL sources use `maskSourceUrl`. `maskOpacity`
+is `0..1`. Use `supportsTexturePanel` and `supportsBlendMode` to decide which
+inspector controls to show for the active material state.
+
+Geometry visibility is grouped by FaceMesh part: left eye, right eye, mouth,
+and nose. Use `CANONICAL_FACE_MESH_GEOMETRY_SPECS` when an inspector needs the
+runtime group order instead of hardcoding another list.

package/docs/api/face-retouching.mdx

@@ -0,0 +1,73 @@
+---
+title: "Face Retouching"
+description: "Legacy skin-retouch shader, controls, and multi-face usage."
+sidebarTitle: "Face Retouching"
+icon: "sparkles"
+---
+
+Retouch exports the reusable legacy skin-retouch component and its SDK-owned
+control schema: `FaceRetouch`, `FaceRetouchControls`,
+`FACE_RETOUCH_DEFAULT_CONTROLS`, `FACE_RETOUCH_SETTINGS_FIELDS`,
+`resolveFaceRetouchControls`, and `patchFaceRetouchControls`.
+
+```tsx
+import {
+  FaceRetouch,
+  resolveFaceRetouchControls,
+  type FaceRetouchControls,
+} from "@vincentt-xr/sdk/face-effects";
+
+const controls = resolveFaceRetouchControls({
+  skinSmoothing: 0.55,
+  skinRealism: 0.62,
+  blemishReduction: 0.35,
+  previewMask: false,
+});
+
+<FaceRetouch {...controls} />;
+```
+
+Controls are intentionally minimal:
+
+| Control            | Range   | Effect                                   |
+| ------------------ | ------- | ---------------------------------------- |
+| `skinSmoothing`    | `0..1`  | Overall smoothing strength               |
+| `skinRealism`      | `0..1`  | Detail preservation after smoothing      |
+| `blemishReduction` | `0..1`  | Local red/dark/high-contrast spot repair |
+| `previewMask`      | boolean | Shows the landmark retouch mask          |
+
+Use `FACE_RETOUCH_SETTINGS_FIELDS` with the generic debug `SettingsPanel`
+instead of copying slider labels, ranges, or defaults into app pages. For
+examples, prefer the debug `FaceRetouchSettingsPanel` wrapper:
+
+```tsx
+import { FaceRetouchSettingsPanel } from "@vincentt-xr/sdk/debug-ui";
+
+<FaceRetouchSettingsPanel value={controls} onChange={setControls} />;
+```
+
+`clipMinX` and `clipMaxX` are optional horizontal UV clipping props in `0..1`
+space. They default to the full frame. The legacy compare demo uses
+`clipMinX={0.5}` so retouch only draws on the right half.
+
+For multiple people, render one `FaceRetouch` per person and pass `faceIndex`.
+`numFaces` defaults to `faceIndex + 1`, so `<FaceRetouch faceIndex={1} />`
+requests tracking for at least two faces. Multiple passes are transparent
+outside their own face mask, so they can be stacked over the same camera
+background.
+
+```tsx
+const faceCount = 2;
+
+{
+  Array.from({ length: faceCount }, (_, faceIndex) => (
+    <FaceRetouch
+      key={faceIndex}
+      {...controls}
+      faceIndex={faceIndex}
+      numFaces={faceCount}
+      renderOrder={-1000 + faceIndex}
+    />
+  ));
+}
+```

package/docs/api/material-render-state.mdx

@@ -0,0 +1,132 @@
+---
+title: "Material Render State API"
+description: "MeshRenderer material draw-state controls: depth, color mask, culling, blending, and polygon offset."
+sidebarTitle: "Material Render State"
+icon: "sliders"
+---
+
+Material render state lives on `MeshRendererSettings.material.renderState`.
+
+```ts
+import {
+  DEFAULT_MESH_RENDERER_RENDER_STATE,
+  normalizeMeshRendererRenderState,
+  type MeshRendererRenderState,
+} from "@vincentt-xr/sdk";
+```
+
+## Type definition
+
+```ts
+type MeshRendererRenderState = {
+  depthTest: boolean;
+  depthWrite: boolean;
+  depthFunc:
+    | "never"
+    | "less"
+    | "equal"
+    | "lessEqual"
+    | "greater"
+    | "notEqual"
+    | "greaterEqual"
+    | "always";
+  colorWrite: boolean;
+  colorMask: {
+    r: boolean;
+    g: boolean;
+    b: boolean;
+    a: boolean;
+  };
+  cullMode: "back" | "front" | "off";
+  blendMode: "normal" | "additive" | "subtractive" | "multiply" | "none";
+  polygonOffset: {
+    enabled: boolean;
+    factor: number;
+    units: number;
+  };
+};
+```
+
+## Defaults
+
+```ts
+const DEFAULT_MESH_RENDERER_RENDER_STATE = {
+  depthTest: true,
+  depthWrite: true,
+  depthFunc: "lessEqual",
+  colorWrite: true,
+  colorMask: { r: true, g: true, b: true, a: true },
+  cullMode: "back",
+  blendMode: "normal",
+  polygonOffset: { enabled: false, factor: 0, units: 0 },
+};
+```
+
+Use `normalizeMeshRendererRenderState(partial)` when reading serialized scenes
+that may omit nested defaults.
+
+## Usage
+
+```ts
+const meshRenderer = createDefaultComponent("MeshRenderer", object.id);
+
+meshRenderer.settings.material.renderState = {
+  depthTest: true,
+  depthWrite: false,
+  depthFunc: "lessEqual",
+  colorWrite: true,
+  colorMask: { r: true, g: false, b: false, a: true },
+  cullMode: "off",
+  blendMode: "additive",
+  polygonOffset: {
+    enabled: true,
+    factor: -1,
+    units: -1,
+  },
+};
+```
+
+## Field behavior
+
+| Field           | Behavior                                                                                |
+| --------------- | --------------------------------------------------------------------------------------- |
+| `depthTest`     | Enables/disables depth testing before drawing the material.                             |
+| `depthWrite`    | Enables/disables writing this material into the depth buffer.                           |
+| `depthFunc`     | Selects the depth comparison function.                                                  |
+| `colorWrite`    | All-channel color write gate.                                                           |
+| `colorMask`     | Per-channel RGBA color write gates.                                                     |
+| `cullMode`      | `"back"` renders front faces, `"front"` renders back faces, `"off"` renders both sides. |
+| `blendMode`     | Maps to Three.js built-in blending modes.                                               |
+| `polygonOffset` | Offsets depth to reduce z-fighting or tune layering.                                    |
+
+`colorMask` is not a plain Three.js material field. The SDK applies it as scoped
+WebGL draw state around each mesh render and restores the previous color mask
+after the object renders.
+
+## Asset-backed meshes
+
+When `MeshRendererSettings.assetUrl` is set, the GLTF scene is cloned and mesh
+materials are cloned before SDK material/render-state overrides are applied.
+This prevents two objects using the same asset URL from mutating the shared Drei
+GLTF cache.
+
+## Debug UI
+
+`MeshRendererSettingsPanel` exposes render-state controls:
+
+- Depth Test
+- Depth Write
+- Depth Function
+- Color Write
+- Mask R/G/B/A
+- Cull Mode
+- Blend Mode
+- Polygon Offset enabled/factor/units
+
+All edits should route back to the selected object's `MeshRenderer` component
+through `onComponentChange`.
+
+## Explicit non-goal
+
+`instanceCount` is not part of material render state. It belongs to mesh
+instancing and should be added as a separate mesh/rendering API when needed.