abstract-3d 3.1.2 → 4.0.0-beta.10

package/src/renderers/ifc/ifc.test.ts

@@ -8,21 +8,23 @@ import { render } from "./ifc.js";
 const red = { normal: "rgb(255, 0, 0)", opacity: 0.5 };
 const scene = (groups: Scene["groups"], relations?: Scene["relations"]): Scene => ({ size_deprecated: vec3Zero, groups, relations });
 const count = (ifc: string, entity: string): number => ifc.split(`=${entity}(`).length - 1;
-const ids = (s: string): ReadonlyArray<string> => Array.from(s.matchAll(/#(\d+)/g), (match) => match[1]);
+const ids = (s: string): ReadonlyArray<string> => Array.from(s.matchAll(/#(\d+)/g), (match) => match.at(1) ?? "");
 /** Random GlobalIds replaced, to compare files */
 const normalize = (ifc: string): string => ifc.replaceAll(/'[0-9A-Za-z_$]{22}'/g, "'guid'");
 
-const entities = (ifc: string): ReadonlyMap<string, string> => new Map(Array.from(ifc.matchAll(/^#(\d+)=(.*);$/gm), (match) => [match[1], match[2]]));
+/** By id; looked up by ids destructured from a list, so by possibly undefined ones */
+const entities = (ifc: string): ReadonlyMap<string | undefined, string> =>
+  new Map(Array.from(ifc.matchAll(/^#(\d+)=(.*);$/gm), (match) => [match.at(1), match.at(2) ?? ""]));
 
 /** The #id of the element or port named `name` */
-const named = (ifc: string, name: string): string => new RegExp(`^#(\\d+)=IFC\\w+\\('[^']{22}',#\\d+,'${name}',`, "m").exec(ifc)![1];
+const named = (ifc: string, name: string): string => new RegExp(`^#(\\d+)=IFC\\w+\\('[^']{22}',#\\d+,'${name}',`, "m").exec(ifc)?.at(1) ?? "";
 
 /** The layer of every face set and polyline of the element named `name`, in order */
 function elementLayers(ifc: string, name: string): ReadonlyArray<string | undefined> {
   const byId = entities(ifc);
   const layers = new Map(
-    Array.from(ifc.matchAll(/[=]IFCPRESENTATIONLAYERASSIGNMENT\('([^']*)',\$,\(([^)]*)\),\$\);/g)).flatMap(([, layer, items]) =>
-      ids(items).map((item) => [item, layer] as const)
+    Array.from(ifc.matchAll(/[=]IFCPRESENTATIONLAYERASSIGNMENT\('([^']*)',\$,\(([^)]*)\),\$\);/g)).flatMap((match) =>
+      ids(match.at(2) ?? "").map((item) => [item, match.at(1)] as const)
     )
   );
   // The element's owner history, placement and shape, the shape's representations and their context and items

package/src/renderers/index.ts

@@ -2,5 +2,6 @@ export * as Dxf from "./dxf/index.js";
 export * as Svg from "./svg/index.js";
 export * as Stl from "./stl/index.js";
 export * as React3Js from "./react/index.js";
+export * as Three from "./three/index.js";
 export * as Step from "./step/index.js";
 export * as Ifc from "./ifc/index.js";

package/src/renderers/react/index.ts

@@ -1,6 +1,3 @@
 export * from "./react.js";
-export * from "./react-types.js";
-export type { SceneMouseEvent } from "./react-scene.js";
-export type { CameraType, Camera, ControlsHelper } from "./react-camera.js";
-export type { MaterialState } from "./react-material.js";
-export { ERROR_IMG_KEY } from "./react-material.js";
+export type { CameraOptions as Camera, BufferZones, ControlsHelper, ControlsOptions, MaterialState, SceneEvent, Quality } from "../three/index.js";
+export { ERROR_IMG_KEY } from "../three/index.js";

package/src/renderers/react/react.tsx

@@ -1,187 +1,113 @@
-import { Html, type OrbitControlsProps } from "@react-three/drei";
-import { Canvas, type CanvasProps, type ThreeEvent } from "@react-three/fiber";
-import { EffectComposer, N8AO } from "@react-three/postprocessing";
-import React, { memo, useMemo } from "react";
-import type { Scene, View, Group, Relation } from "../../abstract-3d.js";
-import type { ControlsHelper, Camera, BufferZones } from "./react-camera.js";
-import { ReactCamera } from "./react-camera.js";
-import type { MaterialState } from "./react-material.js";
-import { ReactScene } from "./react-scene.js";
-import type { ReactPopover } from "./react-types.js";
+import React, { useEffect, useLayoutEffect, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import type { Group, Scene } from "../../abstract-3d.js";
+import type { ControlsHelper, MountedOverlay, Popover, Viewer as ThreeViewer, ViewerOptions } from "../three/index.js";
+import { createViewer, disposeViewer, updateViewer } from "../three/index.js";
 
-type ReactProps = {
-  readonly scene: Scene | undefined; // undefined to allow for simple early loadign the js when lazy loading the React3Js renderer
-  readonly selectedIds: Record<string, boolean> | undefined;
-  /**
-   * The ids of the relations whose shape is drawn to be clicked, e.g. where a component can be inserted. While defined, even when empty, only the
-   * groups whose material state is Accept can be clicked
-   */
-  readonly activeRelations?: ReadonlyArray<string> | undefined;
-  readonly activeComponents?: Record<string, MaterialState> | undefined;
-  readonly hoveredIdsExternal?: ReadonlyArray<string> | undefined;
-  readonly showDimensions?: boolean;
-  readonly popovers?: ReadonlyArray<ReactPopover>;
-  readonly useAnimations?: boolean;
-  readonly camera?: Camera;
-  readonly view?: View;
-  readonly useAlphaTest?: boolean;
+/**
+ * The three.js viewer as a React component: it creates and disposes the viewer, passes each group of props when they change, and portals popovers,
+ * tooltips and the fallback. The viewer's overlays carry ids, and their content is looked up in this render's props, so new content doesn't loop back
+ * through the viewer
+ */
+
+export type ReactPopover = Popover<React.ReactNode>;
+
+export type ViewerProps = Omit<ViewerOptions<React.ReactNode>, "hoveredIds" | "onOverlays" | "onLoad" | "gizmo"> & {
+  readonly scene: Scene | undefined;
+  readonly hoveredIdsExternal?: ReadonlyArray<string>;
+  /** A viewcube or axes gizmo */
   readonly controlsHelper?: ControlsHelper;
-  readonly canvasProps?: Omit<CanvasProps & React.RefAttributes<HTMLCanvasElement>, "children">;
-  readonly orbitContolsProps?: OrbitControlsProps & React.RefAttributes<unknown>;
-  readonly materialStateImages?: Record<string, string>;
-  readonly sceneFallback?: React.JSX.Element;
-  /**
-   * The scene's lights, rendered in the canvas instead of the default ambient and directional lights, e.g. an environment map for reflections and a
-   * key light. A constant element, as a new one each render re-renders the whole scene
-   */
-  readonly lights?: React.JSX.Element;
-  readonly useOldMode?: boolean;
-  readonly bufferZones?: BufferZones;
-  readonly fitPadding?: number;
-  readonly onClickGroup?: (
-    id: string | undefined,
-    rootData: Record<string, string> | undefined,
-    data: Record<string, string> | undefined,
-    e: ThreeEvent<MouseEvent>
-  ) => void;
-  readonly onHoverGroup?: (
-    id: string | undefined,
-    rootData: Record<string, string> | undefined,
-    data: Record<string, string> | undefined,
-    e: ThreeEvent<MouseEvent>
-  ) => void;
-  readonly onContextMenuGroup?: (
-    id: string,
-    rootData: Record<string, string> | undefined,
-    data: Record<string, string> | undefined,
-    left: number,
-    top: number,
-    e: ThreeEvent<MouseEvent>
-  ) => void;
-  readonly getTooltips?: (id: string) => ReadonlyArray<ReactPopover>;
-  readonly onClickRelation?: (relation: Relation, e: ThreeEvent<MouseEvent>) => void;
-  readonly createGroupKey?: (g: Group, idx: number, rootData: Record<string, string> | undefined, id: string) => string;
-  readonly createGroupId?: (g: Group) => string;
+  /** Shown while loading, and while there's no scene */
+  readonly sceneFallback?: React.ReactNode;
+  readonly className?: string;
+  readonly style?: React.CSSProperties;
 };
 
-export const render = memo(
-  ({
-    scene,
-    selectedIds,
-    useOldMode,
-    activeRelations,
-    activeComponents,
-    hoveredIdsExternal,
-    popovers: reactPopovers,
-    showDimensions = true,
-    useAnimations = false,
-    camera = { type: "Perspective" },
-    view = "front",
-    controlsHelper,
-    canvasProps,
-    orbitContolsProps,
-    materialStateImages,
-    sceneFallback,
-    lights,
-    useAlphaTest = true,
-    onClickGroup,
-    onHoverGroup,
-    onContextMenuGroup,
-    getTooltips,
-    onClickRelation,
-    createGroupKey,
-    createGroupId,
-    bufferZones,
-    fitPadding,
-  }: ReactProps): React.JSX.Element => {
-    const intensity = useOldMode ? 2 : 0.4;
-    const suspenseFallback = useMemo(() => <Html center>{sceneFallback ?? <></>}</Html>, [sceneFallback]);
-    return scene ? (
-      <Canvas dpr={[1, window.devicePixelRatio]} frameloop="demand" {...canvasProps}>
-        <React.Suspense fallback={suspenseFallback}>
-          <ReactCamera
-            bufferZones={bufferZones}
-            fitPadding={fitPadding}
-            scene={scene}
-            useAnimations={useAnimations}
-            camera={camera}
-            view={view}
-            controlsHelper={controlsHelper}
-            orbitContolsProps={orbitContolsProps}
-          />
-          {lights ?? (
-            <>
-              <ambientLight intensity={3.5} />
-              <directionalLight
-                position={[
-                  -(scene.center_deprecated?.x ?? 0) - 1.5 * scene.size_deprecated.x,
-                  -(scene.center_deprecated?.y ?? 0) + 1.5 * scene.size_deprecated.y,
-                  -(scene.center_deprecated?.z ?? 0),
-                ]}
-                intensity={intensity}
-              />
-              <directionalLight
-                position={[
-                  -(scene.center_deprecated?.x ?? 0),
-                  -(scene.center_deprecated?.y ?? 0) + 1 * scene.size_deprecated.y,
-                  -(scene.center_deprecated?.z ?? 0) + 1.5 * scene.size_deprecated.z,
-                ]}
-                intensity={intensity}
-              />
-              <directionalLight
-                position={[
-                  -(scene.center_deprecated?.x ?? 0) + 2 * scene.size_deprecated.x,
-                  -(scene.center_deprecated?.y ?? 0),
-                  -(scene.center_deprecated?.z ?? 0) + 1.5 * scene.size_deprecated.z,
-                ]}
-                intensity={intensity}
-              />
-              <directionalLight
-                position={[
-                  -(scene.center_deprecated?.x ?? 0) - 1.5 * scene.size_deprecated.x,
-                  -(scene.center_deprecated?.y ?? 0),
-                  -(scene.center_deprecated?.z ?? 0),
-                ]}
-                intensity={0.4}
-              />
-              <directionalLight
-                position={[
-                  -(scene.center_deprecated?.x ?? 0) + 1.5 * scene.size_deprecated.x,
-                  -(scene.center_deprecated?.y ?? 0),
-                  -(scene.center_deprecated?.z ?? 0),
-                ]}
-                intensity={0.4}
-              />
-            </>
-          )}
+export function Viewer(props: ViewerProps): React.JSX.Element {
+  const { scene, createGroupId, useAlphaTest, selectedIds, hoveredIdsExternal, onClickGroup, view, bufferZones, fitPadding, controls } = props;
+  const { lights, environmentIntensity, studio, groundShadow, shadows, quality, showDimensions, popovers, getTooltips } = props;
+  const { onHoverGroup, onContextMenuGroup, onClickRelation, onPointerMissed, sceneFallback, className, style } = props;
+  // Equal by value, so inline objects don't refit the camera, recreate the gizmo or rebuild the scene
+  const camera = useStableValue(props.camera);
+  const gizmo = useStableValue(props.controlsHelper);
+  const activeComponents = useStableValue(props.activeComponents);
+  const activeRelations = useStableValue(props.activeRelations);
+  const materialStateImages = useStableValue(props.materialStateImages);
+  const container = useRef<HTMLDivElement>(null);
+  const viewer = useRef<ThreeViewer<string> | undefined>(undefined);
+  const [overlays, setOverlays] = useState<ReadonlyArray<MountedOverlay<string>>>([]);
+  const [loaded, setLoaded] = useState(false);
+
+  useLayoutEffect(() => {
+    viewer.current = createViewer(container.current!, { onOverlays: setOverlays, onLoad: () => setLoaded(true) });
+    return () => disposeViewer(viewer.current!);
+  }, []);
+
+  // The latest createGroupId through a stable function, so an inline one doesn't rebuild the scene each render, as 3.x didn't; a new scene does
+  const latestGroupId = useRef(createGroupId);
+  useLayoutEffect(() => {
+    latestGroupId.current = createGroupId;
+  });
+  const [stableGroupId] = useState(
+    () =>
+      (g: Group): string =>
+        latestGroupId.current?.(g) ?? ""
+  );
+  useEffect(() => updateViewer(viewer.current!, { scene, createGroupId: stableGroupId }), [scene, stableGroupId]);
+  useEffect(
+    () => updateViewer(viewer.current!, { activeComponents, activeRelations, useAlphaTest, materialStateImages }),
+    [activeComponents, activeRelations, useAlphaTest, materialStateImages]
+  );
+  useEffect(
+    () => updateViewer(viewer.current!, { selectedIds, hoveredIds: hoveredIdsExternal, onClickGroup }),
+    [selectedIds, hoveredIdsExternal, onClickGroup]
+  );
+  useEffect(() => updateViewer(viewer.current!, { view, bufferZones, fitPadding, camera }), [view, bufferZones, fitPadding, camera]);
+  useEffect(() => updateViewer(viewer.current!, { controls }), [controls]);
+  useEffect(() => updateViewer(viewer.current!, { gizmo }), [gizmo]);
+  useEffect(() => updateViewer(viewer.current!, { lights, environmentIntensity, studio }), [lights, environmentIntensity, studio]);
+  useEffect(() => updateViewer(viewer.current!, { quality }), [quality]);
+  useEffect(() => updateViewer(viewer.current!, { showDimensions }), [showDimensions]);
+  useEffect(() => updateViewer(viewer.current!, { groundShadow, shadows }), [groundShadow, shadows]);
+  useEffect(
+    () =>
+      updateViewer(viewer.current!, {
+        popovers: popovers?.map((p) => ({ ...p, content: p.id })),
+        getTooltips: getTooltips && ((id) => getTooltips(id).map((t) => ({ ...t, content: id }))),
+      }),
+    [popovers, getTooltips]
+  );
+  useEffect(
+    () => updateViewer(viewer.current!, { onHoverGroup, onContextMenuGroup, onClickRelation, onPointerMissed }),
+    [onHoverGroup, onContextMenuGroup, onClickRelation, onPointerMissed]
+  );
+
+  return (
+    <div ref={container} className={className} style={{ position: "relative", width: "100%", height: "100%", overflow: "hidden", ...style }}>
+      {overlays.map((o) =>
+        createPortal(
+          o.key.startsWith("popover:")
+            ? popovers?.find((p) => p.id === o.content)?.content
+            : getTooltips?.(o.content).find((t) => `tooltip:${t.id}` === o.key)?.content,
+          o.element,
+          o.key
+        )
+      )}
+      {(!scene || !loaded) && sceneFallback !== undefined && (
+        <div style={{ position: "absolute", inset: 0, display: "flex", alignItems: "center", justifyContent: "center", pointerEvents: "none" }}>
+          {sceneFallback}
+        </div>
+      )}
+    </div>
+  );
+}
 
-          <ReactScene
-            scene={scene}
-            selectedIds={selectedIds}
-            activeRelations={activeRelations}
-            activeComponents={activeComponents}
-            showDimensions={showDimensions}
-            hoveredIdsExternal={hoveredIdsExternal}
-            reactPopovers={reactPopovers}
-            materialStateImages={materialStateImages}
-            onClickGroup={onClickGroup}
-            onHoverGroup={onHoverGroup}
-            onContextMenuGroup={onContextMenuGroup}
-            getTooltips={getTooltips}
-            onClickRelation={onClickRelation}
-            createGroupKey={createGroupKey}
-            createGroupId={createGroupId}
-            useAlphaTest={useAlphaTest}
-          />
-          {!useOldMode && (
-            <EffectComposer multisampling={8}>
-              <N8AO aoRadius={40} denoiseSamples={4} distanceFalloff={0.2} intensity={2} screenSpaceRadius halfRes />
-            </EffectComposer>
-          )}
-        </React.Suspense>
-      </Canvas>
-    ) : (
-      (sceneFallback ?? <></>)
-    );
+/** The previous value while the new one is equal by value */
+function useStableValue<T>(value: T): T {
+  const [stable, setStable] = useState(value);
+  const changed = JSON.stringify(value) !== JSON.stringify(stable);
+  if (changed) {
+    setStable(value);
   }
-);
+  return changed ? value : stable;
+}

package/src/renderers/three/appearance/appearance.test.ts

@@ -0,0 +1,153 @@
+import { Color, Vector4 } from "three";
+import { assert, describe, expect, it } from "vitest";
+import type { Material, Mesh } from "../../../abstract-3d.js";
+import { box, line, text, vec3, vec3Zero } from "../../../abstract-3d.js";
+import { shade } from "../../../utils.js";
+import type { Item, Style, Target } from "../compile/compile.js";
+import type { MaterialClass, PaintState } from "./appearance.js";
+import { getHighlight, getItemColor, getMaterialClass, getTargetStates, HOVERED, SELECTED } from "./appearance.js";
+
+const red = "rgb(255, 0, 0)";
+const select = "rgb(14,82,184)";
+const item = (mesh: Mesh, style: Style = "group", role: Item["role"] = "solid"): Item => ({
+  mesh,
+  role,
+  style,
+  matrix: undefined!,
+  target: 0,
+  data: undefined,
+  animation: undefined,
+});
+const solid = (material: Material, style: Style = "group"): Item => item(box(vec3(1, 1, 1), material), style);
+const group: Target = { kind: "group", id: "fan", root: 0, rootData: undefined };
+const relation: Target = { kind: "relation", relation: { id: "r", pos: vec3Zero } };
+const idle: PaintState = { relationsActive: false, dimensionsClickable: true };
+const round = (v: number): number => Math.round(v * 1e4) / 1e4;
+const rgba = (color: string, alpha = 1): ReadonlyArray<number> => [...new Color(color).toArray(), alpha].map(round);
+const classify = (i: Item, target: Target, state: Partial<PaintState> = {}): MaterialClass => {
+  const [targetState] = getTargetStates([target], { ...idle, ...state });
+  assert(targetState);
+  return getMaterialClass(i, targetState);
+};
+const paint = (i: Item, target: Target, partial: Partial<PaintState> = {}): ReadonlyArray<number> => {
+  const state = { ...idle, ...partial };
+  const [targetState] = getTargetStates([target], state);
+  assert(targetState);
+  return getItemColor(i, targetState, getHighlight(target, 0, state), new Vector4())
+    .toArray()
+    .map(round);
+};
+
+describe("getMaterialClass", () => {
+  it("lights solids, with the material's metalness, roughness and side", () => {
+    expect(classify(solid({ normal: red, metalness: 0.3, roughness: 0.7 }), group)).toEqual({
+      lit: true,
+      metalness: 0.3,
+      roughness: 0.7,
+      side: "double",
+      transparent: false,
+      castShadow: true,
+    });
+    expect(classify(solid({ normal: red, backfaceCulling: true }), group)).toMatchObject({ side: "front", metalness: 0, roughness: 1 });
+  });
+
+  it("casts shadows from opaque solids unless their material turns it off, e.g. for symbols", () => {
+    expect(classify(solid({ normal: red, castShadow: false }), group).castShadow).toBe(false);
+    expect(classify(solid({ normal: red, opacity: 0.5 }), group).castShadow).toBe(false);
+    expect(classify(solid({ normal: red }), group, { relationsActive: true }).castShadow).toBe(false);
+    expect(classify(solid({ normal: red }, "relation"), relation, { relationsActive: true }).castShadow).toBe(false);
+  });
+
+  it("gives solids of a type its finish, in one class whatever their metalness and roughness, unless a material state replaces it", () => {
+    const painted = classify(solid({ normal: red, type: "painted", metalness: 0.45, roughness: 0.4 }), group);
+    expect(painted).toMatchObject({ lit: true, type: "painted" });
+    expect(classify(solid({ normal: "rgb(0,0,255)", type: "painted", metalness: 0.9 }), group)).toEqual(painted);
+    expect(classify(solid({ normal: red, type: "painted" }), group, { activeComponents: { fan: "Accept" } }).type).toBeUndefined();
+  });
+
+  it("ignores a type that isn't a material type, e.g. a number from a database", () => {
+    const fromDatabase = { normal: red, metalness: 0.3, roughness: 0.7, type: 2 } as unknown as Material;
+    expect(classify(solid(fromDatabase), group)).toMatchObject({ metalness: 0.3, roughness: 0.7 });
+    expect(classify(solid(fromDatabase), group).type).toBeUndefined();
+  });
+
+  it("makes glass see-through unless its material has an opacity", () => {
+    expect(classify(solid({ normal: red, type: "glass" }), group).transparent).toBe(true);
+    expect(paint(solid({ normal: red, type: "glass" }), group)).toEqual(rgba(red, 0.25));
+    expect(classify(solid({ normal: red, type: "glass", opacity: 1 }), group).transparent).toBe(false);
+  });
+
+  it("makes translucent materials and disabled groups transparent", () => {
+    expect(classify(solid({ normal: red, opacity: 0.5 }), group).transparent).toBe(true);
+    expect(classify(solid({ normal: red }), group, { relationsActive: true }).transparent).toBe(true);
+    expect(classify(solid({ normal: red }), group, { relationsActive: true, activeComponents: { fan: "Accept" } }).transparent).toBe(false);
+  });
+
+  it("uses the material state's metalness and roughness", () => {
+    expect(classify(solid({ normal: red }), group, { activeComponents: { fan: "Error" } })).toMatchObject({ metalness: 0.5, roughness: 0.5 });
+  });
+
+  it("draws relations unlit on both sides, and their outlines on the back", () => {
+    expect(classify(solid({ normal: red }, "relation"), relation)).toMatchObject({ lit: false, side: "double", transparent: false });
+    expect(classify(solid({ normal: red }, "outline"), relation)).toMatchObject({ lit: false, side: "back" });
+  });
+});
+
+describe("getHighlight", () => {
+  it("combines hover by the pointer or by id with selection", () => {
+    expect(getHighlight(group, 0, idle)).toBe(0);
+    expect(getHighlight(group, 0, { ...idle, hoveredTarget: 1 })).toBe(0);
+    expect(getHighlight(group, 0, { ...idle, hoveredTarget: 0, selectedIds: { fan: true } })).toBe(HOVERED + SELECTED);
+    expect(getHighlight(group, 0, { ...idle, hoveredIds: new Set(["fan"]) })).toBe(HOVERED);
+  });
+});
+
+describe("getItemColor", () => {
+  it("is the material's color and opacity", () => {
+    expect(paint(solid({ normal: red, opacity: 0.5 }), group)).toEqual(rgba(red, 0.5));
+  });
+
+  it("darkens hovered groups, by the pointer or by id, and colors selected ones", () => {
+    expect(paint(solid({ normal: red }), group, { hoveredTarget: 0 })).toEqual(rgba(shade(-0.4, red)!));
+    expect(paint(solid({ normal: red }), group, { hoveredIds: new Set(["fan"]) })).toEqual(rgba(shade(-0.4, red)!));
+    expect(paint(solid({ normal: red }), group, { selectedIds: { fan: true } })).toEqual(rgba(select));
+    expect(paint(solid({ normal: red }), group, { selectedIds: { fan: true }, hoveredTarget: 0 })).toEqual(rgba(shade(-0.4, select)!));
+  });
+
+  it("ignores hover by id for groups without an id", () => {
+    expect(paint(solid({ normal: red }), { ...group, id: "" }, { hoveredIds: new Set([""]) })).toEqual(rgba(red));
+  });
+
+  it("colors groups by their material state and fades disabled ones", () => {
+    expect(paint(solid({ normal: red }), group, { activeComponents: { fan: "Accept" } })).toEqual(rgba("rgb(0,148,91)"));
+    expect(paint(solid({ normal: red, opacity: 0.8 }), group, { relationsActive: true })).toEqual(rgba(red, 0.1));
+  });
+
+  it("selects text in a dark blue", () => {
+    expect(paint(item(text(vec3Zero, "A", 1, { normal: red }), "group", "text"), group, { selectedIds: { fan: true } })).toEqual(
+      rgba("rgb(0, 26, 65)")
+    );
+  });
+
+  it("outlines relations in black, also while hovered", () => {
+    expect(paint(solid({ normal: "rgb(0,148,91)" }, "outline"), relation)).toEqual(rgba("rgb(0, 0, 0)"));
+    expect(paint(solid({ normal: "rgb(0,148,91)" }, "outline"), relation, { hoveredTarget: 0 })).toEqual(rgba("rgb(0, 0, 0)"));
+  });
+
+  it("keeps lines in their material's color", () => {
+    expect(paint(item(line(vec3Zero, vec3(1, 0, 0), 1, { normal: red }), "group", "line"), group, { selectedIds: { fan: true } })).toEqual(rgba(red));
+  });
+
+  it("highlights clickable dimensions when hovered or selected", () => {
+    const dimension: Target = { kind: "dimension", id: "fan" };
+    const d = solid({ normal: red }, "dimension");
+    expect(paint(d, dimension, { hoveredTarget: 0 })).toEqual(rgba(select));
+    expect(paint(d, dimension, { selectedIds: { fan: true } })).toEqual(rgba(select));
+    expect(paint(d, dimension, { selectedIds: { fan: true }, dimensionsClickable: false })).toEqual(rgba(red));
+    expect(paint(d, dimension, { selectedIds: { fan: true }, relationsActive: true })).toEqual(rgba(red));
+  });
+
+  it("darkens hovered relations", () => {
+    expect(paint(solid({ normal: red }, "relation"), relation, { hoveredTarget: 0 })).toEqual(rgba(shade(-0.4, red)!));
+  });
+});

package/src/renderers/three/appearance/appearance.ts

@@ -0,0 +1,150 @@
+import { Color, type Vector4 } from "three";
+import type { Material, MaterialType } from "../../../abstract-3d.js";
+import { materialTypes } from "../../../abstract-3d.js";
+import { shade } from "../../../utils.js";
+import type { Item, Target } from "../compile/compile.js";
+
+/** Material classes and per-instance colors of items, by the viewer's state, as the r3f renderer's materials */
+
+export type MaterialState = "Accept" | "Error" | "Warning";
+export const ERROR_IMG_KEY = "error";
+
+/** The state that decides material classes, so changing it rebuilds the scene */
+export type StructureState = {
+  readonly activeComponents?: Record<string, MaterialState>;
+  /** Relations are active, e.g. to pick one to insert a component on, so only the groups whose material state is Accept can be clicked */
+  readonly relationsActive: boolean;
+};
+
+/** A target's material state, and whether it's disabled: faded and not clickable while relations are active */
+export type TargetState = { readonly materialState?: MaterialState; readonly disabled: boolean };
+
+/** The state that only changes colors */
+export type PaintState = StructureState & {
+  readonly selectedIds?: Record<string, boolean>;
+  readonly hoveredIds?: ReadonlySet<string>;
+  /** The target under the pointer */
+  readonly hoveredTarget?: number;
+  readonly dimensionsClickable: boolean;
+};
+
+/** Items of one material class share a material, and are drawn in one batch */
+export type MaterialClass = {
+  readonly lit: boolean;
+  /** A physical finish of its own, instead of metalness and roughness */
+  readonly type?: MaterialType;
+  readonly metalness: number;
+  readonly roughness: number;
+  readonly side: "front" | "back" | "double";
+  readonly transparent: boolean;
+  /** Opaque solids whose material doesn't turn it off cast shadows */
+  readonly castShadow: boolean;
+};
+
+/** Bit flags of how a target is highlighted, so only targets whose highlight changed need a repaint */
+export const HOVERED = 1;
+export const SELECTED = 2;
+
+const disabledOpacity = 0.125;
+const selectColor = "rgb(14,82,184)";
+const textSelectColor = "rgb(0, 26, 65)";
+/** Of the inverted hull around a relation's boxes */
+const outlineColor = "rgb(0, 0, 0)";
+const stateMaterials: Record<MaterialState, Material> = {
+  Accept: { normal: "rgb(0,148,91)", metalness: 0.5, roughness: 0.5 },
+  Error: { normal: "#b82f3a", metalness: 0.5, roughness: 0.5 },
+  Warning: { normal: "rgb(240, 197, 48)", metalness: 0.5, roughness: 0.5 },
+};
+const unlit = { lit: false, metalness: 0, roughness: 1, transparent: false, castShadow: false } as const;
+/** Of glass without an opacity of its own */
+const glassOpacity = 0.25;
+
+export function getTargetStates(targets: ReadonlyArray<Target>, structure: StructureState): ReadonlyArray<TargetState> {
+  return targets.map((target) => {
+    const materialState = target.kind === "group" ? structure.activeComponents?.[target.id] : undefined;
+    return { materialState, disabled: target.kind === "group" && structure.relationsActive && materialState !== "Accept" };
+  });
+}
+
+export function getMaterialClass(item: Item, { materialState, disabled }: TargetState): MaterialClass {
+  const { material } = item.mesh;
+  switch (item.style) {
+    case "relation":
+      return { ...unlit, side: "double" };
+    case "outline":
+      return { ...unlit, side: "back" };
+    case "dimension":
+      return { ...unlit, side: "front", transparent: (material.opacity ?? 1) < 1 };
+    default: {
+      // A material state's color and finish replace the material's
+      const mat = materialState ? stateMaterials[materialState] : material;
+      // Only a known type, as data may have a type of its own, e.g. a number
+      const type = item.role === "solid" && materialTypes.includes(mat.type as MaterialType) ? mat.type : undefined;
+      return {
+        lit: item.role === "solid",
+        ...(type ? { type, metalness: 0, roughness: 0 } : { metalness: mat.metalness ?? 0, roughness: mat.roughness ?? 1 }),
+        side: item.role === "text" || material.backfaceCulling ? "front" : "double",
+        transparent: getOpacity(material) < 1 || disabled,
+        castShadow: item.role === "solid" && getOpacity(material) === 1 && !disabled && material.castShadow !== false,
+      };
+    }
+  }
+}
+
+export function getHighlight(target: Target, targetIndex: number, state: PaintState): number {
+  const hoveredByPointer = state.hoveredTarget === targetIndex;
+  switch (target.kind) {
+    case "relation":
+      return hoveredByPointer ? HOVERED : 0;
+    case "dimension":
+      return state.dimensionsClickable && !state.relationsActive && target.id !== undefined && (hoveredByPointer || !!state.selectedIds?.[target.id])
+        ? SELECTED
+        : 0;
+    default:
+      return (
+        (hoveredByPointer || (target.id !== "" && !!state.hoveredIds?.has(target.id)) ? HOVERED : 0) + (state.selectedIds?.[target.id] ? SELECTED : 0)
+      );
+  }
+}
+
+/** The item's linear color and opacity by its target's highlight, written to `out`; hovered colors are darkened */
+export function getItemColor(item: Item, { materialState, disabled }: TargetState, highlight: number, out: Vector4): Vector4 {
+  const { material } = item.mesh;
+  const hovered = highlight % SELECTED === HOVERED;
+  const selected = highlight >= SELECTED;
+  const opacity = getOpacity(material);
+  switch (item.style) {
+    case "relation":
+      return setColor(out, material.normal, hovered, 1);
+    case "outline":
+      return setColor(out, outlineColor, false, 1);
+    case "dimension":
+      return setColor(out, selected ? selectColor : material.normal, false, opacity);
+    default: {
+      const style = selected
+        ? item.role === "text"
+          ? textSelectColor
+          : selectColor
+        : materialState && item.role !== "image"
+          ? stateMaterials[materialState].normal
+          : material.normal;
+      return item.role === "line"
+        ? setColor(out, material.normal, false, 1)
+        : setColor(out, style, hovered, item.role === "solid" && disabled ? opacity * disabledOpacity : opacity);
+    }
+  }
+}
+
+/** Glass is mostly see-through unless its material says otherwise */
+function getOpacity(material: Material): number {
+  return material.opacity ?? (material.type === "glass" ? glassOpacity : 1);
+}
+
+const colors = new Map<string, Color>();
+
+function setColor(out: Vector4, style: string, hovered: boolean, opacity: number): Vector4 {
+  const key = hovered ? `hovered ${style}` : style;
+  const color = colors.get(key) ?? new Color(hovered ? (shade(-0.4, style) ?? style) : style);
+  colors.set(key, color);
+  return out.set(color.r, color.g, color.b, opacity);
+}