Skip to content

Next Gen STEP AP242 Native-ish BREP Geometric Modeling Kernel

Add persistent themed viewport selector

Yuechen Lidf14283edec7
diff --git a/aetheris.client/src/App.css b/aetheris.client/src/App.css
index 1f127737..f8958196 100644
--- a/aetheris.client/src/App.css
+++ b/aetheris.client/src/App.css
@@ -238,6 +238,35 @@
background: #272521;
}
+.viewport-theme-select {
+ display: inline-flex;
+ align-items: center;
+ gap: 0.45rem;
+ padding-left: 0.25rem;
+ color: var(--shell-text-secondary);
+ font-size: 0.65rem;
+ font-weight: 700;
+ letter-spacing: 0.11em;
+}
+
+.viewport-theme-select select {
+ min-width: 8.4rem;
+ border: 1px solid var(--shell-border);
+ border-radius: 3px;
+ background: color-mix(in srgb, var(--shell-elevated) 92%, transparent);
+ color: var(--shell-text-primary);
+ padding: 0.38rem 1.8rem 0.38rem 0.55rem;
+ font: inherit;
+ font-size: 0.72rem;
+ letter-spacing: 0.04em;
+ cursor: pointer;
+}
+
+.viewport-theme-select select:focus-visible {
+ outline: 2px solid var(--shell-accent);
+ outline-offset: 2px;
+}
+
.viewport-segmented__button {
min-height: 26px;
border: 0;
diff --git a/aetheris.client/src/App.tsx b/aetheris.client/src/App.tsx
index 1b0a9901..2070caef 100644
--- a/aetheris.client/src/App.tsx
+++ b/aetheris.client/src/App.tsx
@@ -51,7 +51,11 @@ import {
import { resolvePublishedBrepEntity } from "./viewer/semanticInspection";
import { documentMachine, documentPhase } from "./application/documentMachine";
import { shellThemeCssVariables } from "./theme/shellTheme";
-import { viewportThemeById, VIEWPORT_THEMES, type ViewportTheme } from "./viewer/viewportTheme";
+import { viewportThemeById, VIEWPORT_THEMES, type ViewportThemeId } from "./viewer/viewportTheme";
+import {
+ loadViewportThemePreference,
+ saveViewportThemePreference,
+} from "./viewer/viewportThemePreference";
type RequestStatus = "idle" | "loading" | "success" | "error";
type BooleanOperationUi = "Union" | "Subtract" | "Intersect";
@@ -170,7 +174,9 @@ function App() {
}),
);
const [activeTab, setActiveTab] = useState<TopLevelTab>("viewer");
- const [viewportThemeId, setViewportThemeId] = useState<ViewportTheme["id"]>("atelier");
+ const [viewportThemeId, setViewportThemeId] = useState<ViewportThemeId>(
+ loadViewportThemePreference,
+ );
const [documentId, setDocumentId] = useState<string | null>(null);
const [bodyIds, setBodyIds] = useState<string[]>([]);
const [occurrences, setOccurrences] = useState<BodyOccurrenceSummaryDto[]>([]);
@@ -220,6 +226,7 @@ function App() {
const [isPmiVisible, setIsPmiVisible] = useState(true);
const startupStepClaimed = useRef(false);
const viewportTheme = useMemo(() => viewportThemeById(viewportThemeId), [viewportThemeId]);
+ useEffect(() => saveViewportThemePreference(viewportThemeId), [viewportThemeId]);
const shellThemeVariables = useMemo(() => shellThemeCssVariables() as CSSProperties, []);
const lifecyclePhase = documentPhase(documentLifecycleState);
@@ -1034,21 +1041,21 @@ function App() {
COORD
</button>
<span className="viewport-controls__divider" aria-hidden="true" />
- {VIEWPORT_THEMES.map((candidate) => (
- <button
- key={candidate.id}
- type="button"
- className={
- viewportThemeId === candidate.id
- ? "viewport-segmented__button is-active"
- : "viewport-segmented__button"
- }
- onClick={() => setViewportThemeId(candidate.id)}
- aria-pressed={viewportThemeId === candidate.id}
+ <label className="viewport-theme-select">
+ <span>THEME</span>
+ <select
+ aria-label="Viewport theme"
+ value={viewportThemeId}
+ onChange={(event) => setViewportThemeId(event.target.value as ViewportThemeId)}
+ title={viewportTheme.description}
>
- {candidate.label.toUpperCase()}
- </button>
- ))}
+ {VIEWPORT_THEMES.map((candidate) => (
+ <option key={candidate.id} value={candidate.id}>
+ {candidate.label}
+ </option>
+ ))}
+ </select>
+ </label>
</div>
<AetherisViewport
displayScene={displayScene.displayScene}
diff --git a/aetheris.client/src/__tests__/App.test.tsx b/aetheris.client/src/__tests__/App.test.tsx
index 3ec893a7..266ee2af 100644
--- a/aetheris.client/src/__tests__/App.test.tsx
+++ b/aetheris.client/src/__tests__/App.test.tsx
@@ -124,7 +124,9 @@ describe("App STEP file upload flow", () => {
it("switches the complete viewport theme without changing shell geography", () => {
render(<App />);
expect(screen.getByTestId("viewer-viewport").getAttribute("data-theme")).toBe("atelier");
- fireEvent.click(screen.getByRole("button", { name: "MONUMENT" }));
+ fireEvent.change(screen.getByRole("combobox", { name: "Viewport theme" }), {
+ target: { value: "monument" },
+ });
expect(screen.getByTestId("viewer-viewport").getAttribute("data-theme")).toBe("monument");
expect(screen.getByRole("tab", { name: /STEP 242 Viewer/i })).toBeTruthy();
});
diff --git a/aetheris.client/src/__tests__/viewportTheme.test.ts b/aetheris.client/src/__tests__/viewportTheme.test.ts
index 501c476f..8e0462b2 100644
--- a/aetheris.client/src/__tests__/viewportTheme.test.ts
+++ b/aetheris.client/src/__tests__/viewportTheme.test.ts
@@ -2,6 +2,9 @@ import { describe, expect, it } from "vitest";
import {
ATELIER_VIEWPORT_THEME,
MONUMENT_VIEWPORT_THEME,
+ VIEWPORT_THEME_IDS,
+ VIEWPORT_THEME_REGISTRY,
+ VIEWPORT_THEMES,
viewportThemeById,
} from "../viewer/viewportTheme";
@@ -17,4 +20,23 @@ describe("viewport themes", () => {
ATELIER_VIEWPORT_THEME.cameraPresentation,
);
});
+
+ it("registers every curated theme exactly once", () => {
+ expect(VIEWPORT_THEMES.map((theme) => theme.id)).toEqual(VIEWPORT_THEME_IDS);
+ expect(new Set(VIEWPORT_THEMES.map((theme) => theme.id)).size).toBe(VIEWPORT_THEMES.length);
+ expect(VIEWPORT_THEME_REGISTRY.size).toBe(VIEWPORT_THEME_IDS.length);
+ });
+
+ it("falls back to Atelier for missing or corrupt IDs", () => {
+ expect(viewportThemeById("not-a-theme")).toBe(ATELIER_VIEWPORT_THEME);
+ expect(viewportThemeById(null)).toBe(ATELIER_VIEWPORT_THEME);
+ });
+
+ it("keeps every theme static by default and selection-readable", () => {
+ for (const theme of VIEWPORT_THEMES) {
+ expect(theme.animated).toBe(false);
+ expect(theme.edgeStyle.selectedWidth).toBeGreaterThan(theme.edgeStyle.width);
+ expect(theme.annotation.selected).not.toBe(theme.annotation.background);
+ }
+ });
});
diff --git a/aetheris.client/src/__tests__/viewportThemePreference.test.ts b/aetheris.client/src/__tests__/viewportThemePreference.test.ts
new file mode 100644
index 00000000..dfeee7c0
--- /dev/null
+++ b/aetheris.client/src/__tests__/viewportThemePreference.test.ts
@@ -0,0 +1,34 @@
+import { describe, expect, it } from "vitest";
+import {
+ loadViewportThemePreference,
+ saveViewportThemePreference,
+ VIEWPORT_THEME_STORAGE_KEY,
+} from "../viewer/viewportThemePreference";
+
+function memoryStorage(seed?: string): Storage {
+ const values = new Map<string, string>();
+ if (seed) values.set(VIEWPORT_THEME_STORAGE_KEY, seed);
+ return {
+ get length() {
+ return values.size;
+ },
+ clear: () => values.clear(),
+ getItem: (key) => values.get(key) ?? null,
+ key: (index) => [...values.keys()][index] ?? null,
+ removeItem: (key) => values.delete(key),
+ setItem: (key, value) => values.set(key, value),
+ };
+}
+
+describe("viewport theme preference", () => {
+ it("uses a valid gallery query before persisted preference", () => {
+ expect(loadViewportThemePreference("?theme=sirius", memoryStorage("mars"))).toBe("sirius");
+ });
+
+ it("persists valid selections and rejects corrupt storage", () => {
+ const storage = memoryStorage("broken");
+ expect(loadViewportThemePreference("", storage)).toBe("atelier");
+ saveViewportThemePreference("aeons", storage);
+ expect(loadViewportThemePreference("", storage)).toBe("aeons");
+ });
+});
diff --git a/aetheris.client/src/viewer/AetherisViewport.tsx b/aetheris.client/src/viewer/AetherisViewport.tsx
index 53fb8217..2576a261 100644
--- a/aetheris.client/src/viewer/AetherisViewport.tsx
+++ b/aetheris.client/src/viewer/AetherisViewport.tsx
@@ -31,6 +31,7 @@ import { CadmataOverlay, type CadmataLayerVisibility } from "./CadmataOverlay";
import type { CadmataVisualizationArtifact } from "./conceptVisualization";
import { ATELIER_VIEWPORT_THEME, type ViewportTheme } from "./viewportTheme";
import { PmiAnnotationLayer } from "./PmiAnnotationLayer";
+import { ThemeBackground } from "./ThemeBackground";
function intersectGround(origin: Vector3, direction: Vector3, y: number): Vector3 | null {
if (Math.abs(direction.y) < 1e-6) return null;
@@ -212,6 +213,8 @@ declare global {
triangles?: number;
geometries?: number;
textures?: number;
+ shaderPrograms?: number;
+ themeId?: string;
gridLineCount?: number;
gridDrawCalls?: number;
gridAllocatedBytes?: number;
@@ -253,6 +256,7 @@ function ViewportPerformanceProbe({ resetKey }: { resetKey: unknown }) {
triangles: gl.info.render.triangles,
geometries: gl.info.memory.geometries,
textures: gl.info.memory.textures,
+ shaderPrograms: gl.info.programs?.length ?? 0,
});
}
});
@@ -591,11 +595,12 @@ export function AetherisViewport({
}}
>
<color attach="background" args={[theme.sceneBackground]} />
+ <ThemeBackground theme={theme} />
{theme.fog.enabled ? (
<fog attach="fog" args={[theme.fog.color, theme.fog.near, theme.fog.far]} />
) : null}
<RendererConfiguration theme={theme} />
- <ViewportPerformanceProbe resetKey={displayScene} />
+ <ViewportPerformanceProbe resetKey={`${theme.id}:${displayScene?.renderables.length ?? 0}`} />
<ambientLight intensity={theme.lights.ambient} />
<hemisphereLight
args={[
@@ -610,6 +615,11 @@ export function AetherisViewport({
intensity={theme.lights.keyIntensity}
castShadow={theme.shadowStyle.enabled}
/>
+ <directionalLight
+ position={[...theme.lights.rimPosition]}
+ color={theme.lights.rimColor}
+ intensity={theme.lights.rimIntensity}
+ />
<directionalLight
position={[...theme.lights.fillPosition]}
color={theme.lights.fillColor}
@@ -617,7 +627,7 @@ export function AetherisViewport({
/>
<FitCameraToScene displayScene={displayScene} />
<FitCameraToAssembly packet={assemblyPacket} />
- {showGrid ? <AdaptiveLogGrid theme={theme} /> : null}
+ {showGrid && theme.gridStyle.enabled ? <AdaptiveLogGrid theme={theme} /> : null}
{showAxisGuide ? <AxisGuide theme={theme} /> : null}
{displayScene?.renderables.flatMap((renderable) =>
matchKind(renderable, {
@@ -674,6 +684,7 @@ export function AetherisViewport({
layers={cadmataLayers}
selectedIds={selectedCadmataIds}
onSelect={onCadmataSelect}
+ theme={theme}
/>
) : null}
<PmiAnnotationLayer
diff --git a/aetheris.client/src/viewer/CadmataOverlay.tsx b/aetheris.client/src/viewer/CadmataOverlay.tsx
index afb4c52d..2a6f90cd 100644
--- a/aetheris.client/src/viewer/CadmataOverlay.tsx
+++ b/aetheris.client/src/viewer/CadmataOverlay.tsx
@@ -7,15 +7,8 @@ import type {
CadmataLayer,
CadmataVisualizationArtifact,
} from "./conceptVisualization";
+import type { ViewportTheme } from "./viewportTheme";
-export const CADMATA_PALETTE = {
- concept: "#6ea6b8",
- profile: "#4db6ac",
- compose: "#b48748",
- selection: "#ffbf47",
- ancestor: "#77a7d9",
- diagnostic: "#e05d5d",
-} as const;
export type CadmataLayerVisibility = Record<CadmataLayer, boolean>;
export const DEFAULT_CADMATA_LAYERS: CadmataLayerVisibility = {
material: true,
@@ -32,25 +25,27 @@ export const DEFAULT_CADMATA_LAYERS: CadmataLayerVisibility = {
diagnostics: true,
};
-function colorFor(entity: CadmataEntity, selected: boolean) {
- if (selected) return CADMATA_PALETTE.selection;
+function colorFor(entity: CadmataEntity, selected: boolean, theme: ViewportTheme) {
+ if (selected) return theme.overlay.selection;
if (entity.layer === "profileGuides" || entity.layer === "profileLoops")
- return CADMATA_PALETTE.profile;
- if (entity.layer === "composeRegions") return CADMATA_PALETTE.compose;
- if (entity.layer === "diagnostics") return CADMATA_PALETTE.diagnostic;
- return CADMATA_PALETTE.concept;
+ return theme.overlay.profile;
+ if (entity.layer === "composeRegions") return theme.overlay.compose;
+ if (entity.layer === "diagnostics") return theme.overlay.diagnostic;
+ return theme.overlay.concept;
}
function OverlayEntity({
entity,
selected,
onSelect,
+ theme,
}: {
entity: CadmataEntity;
selected: boolean;
onSelect: (id: string) => void;
+ theme: ViewportTheme;
}) {
const geometry = entity.geometry;
- const color = colorFor(entity, selected);
+ const color = colorFor(entity, selected, theme);
const points = useMemo(
() =>
geometry?.type === "polyline"
@@ -135,11 +130,13 @@ export function CadmataOverlay({
layers,
selectedIds,
onSelect,
+ theme,
}: {
artifact: CadmataVisualizationArtifact | null;
layers: CadmataLayerVisibility;
selectedIds: Set<string>;
onSelect: (id: string) => void;
+ theme: ViewportTheme;
}) {
if (!artifact) return null;
return (
@@ -152,6 +149,7 @@ export function CadmataOverlay({
entity={entity}
selected={selectedIds.has(entity.stableId)}
onSelect={onSelect}
+ theme={theme}
/>
))}
</group>
diff --git a/aetheris.client/src/viewer/ThemeBackground.tsx b/aetheris.client/src/viewer/ThemeBackground.tsx
new file mode 100644
index 00000000..0999e422
--- /dev/null
+++ b/aetheris.client/src/viewer/ThemeBackground.tsx
@@ -0,0 +1,168 @@
+import { useFrame, useThree } from "@react-three/fiber";
+import { useEffect, useMemo } from "react";
+import { ShaderMaterial, Vector2 } from "three";
+import type { ViewportTheme } from "./viewportTheme";
+
+const vertexShader = /* glsl */ `
+ void main() {
+ gl_Position = vec4(position.xy, 1.0, 1.0);
+ }
+`;
+
+const fragmentShader = /* glsl */ `
+ precision highp float;
+ uniform vec2 uResolution;
+ uniform float uMode;
+ uniform float uIntensity;
+ uniform float uVignette;
+ uniform float uBloom;
+
+ float hash21(vec2 p) {
+ p = fract(p * vec2(123.34, 456.21));
+ p += dot(p, p + 45.32);
+ return fract(p.x * p.y);
+ }
+
+ float noise21(vec2 p) {
+ vec2 i = floor(p);
+ vec2 f = fract(p);
+ f = f * f * (3.0 - 2.0 * f);
+ return mix(mix(hash21(i), hash21(i + vec2(1.0, 0.0)), f.x),
+ mix(hash21(i + vec2(0.0, 1.0)), hash21(i + 1.0), f.x), f.y);
+ }
+
+ float stars(vec2 uv, float density) {
+ vec2 cell = floor(uv * uResolution / 2.5);
+ float h = hash21(cell);
+ float spark = smoothstep(1.0 - density, 1.0, h);
+ return spark * (0.35 + 0.65 * hash21(cell + 17.1));
+ }
+
+ float ring(vec2 p, float radius, float width) {
+ return exp(-abs(length(p) - radius) / width);
+ }
+
+ vec3 mars(vec2 uv, vec2 p) {
+ float horizon = smoothstep(-0.42, 0.2, p.y);
+ vec3 color = mix(vec3(0.045, 0.012, 0.009), vec3(0.31, 0.075, 0.035), horizon);
+ color += vec3(0.36, 0.09, 0.025) * exp(-abs(p.y + 0.18) * 9.0);
+ vec2 sunP = p - vec2(-0.58, 0.28);
+ float sun = 1.0 - smoothstep(0.055, 0.07, length(sunP));
+ float halo = exp(-length(sunP) * 5.0);
+ color += vec3(1.0, 0.37, 0.10) * (sun * 1.5 + halo * 0.38);
+ float strataNoise = noise21(vec2(p.x * 2.1, p.y * 4.0));
+ float strata = pow(0.5 + 0.5 * sin((p.y + strataNoise * 0.07) * 95.0), 14.0);
+ color += vec3(0.42, 0.11, 0.035) * strata * smoothstep(0.15, -0.75, p.y) * 0.32;
+ float dust = stars(uv * vec2(1.0, 0.75), 0.0028);
+ color += vec3(0.8, 0.3, 0.12) * dust * 0.32;
+ return color;
+ }
+
+ vec3 sirius(vec2 uv, vec2 p) {
+ vec3 color = mix(vec3(0.001, 0.004, 0.018), vec3(0.006, 0.028, 0.075), uv.y);
+ color += vec3(0.35, 0.62, 1.0) * stars(uv, 0.0035);
+ vec2 q = p - vec2(0.62, 0.34);
+ float r = length(q);
+ float core = exp(-r * 38.0);
+ float halo = exp(-r * 7.0);
+ float rays = exp(-abs(q.x) * 70.0) + exp(-abs(q.y) * 90.0);
+ rays += exp(-abs(q.x + q.y) * 100.0) * 0.28 + exp(-abs(q.x - q.y) * 100.0) * 0.28;
+ color += vec3(0.58, 0.78, 1.0) * halo * (0.35 + uBloom);
+ color += vec3(0.9, 0.97, 1.0) * (core * 2.4 + rays * exp(-r * 5.0) * 0.25);
+ float orbit = ring(q * vec2(1.0, 1.55), 0.34, 0.0025);
+ color += vec3(0.2, 0.5, 0.9) * orbit * 0.22;
+ return color;
+ }
+
+ vec3 singularity(vec2 uv, vec2 p) {
+ // Deliberately off-axis so the engineering silhouette never disappears into the event horizon.
+ vec2 q = p - vec2(1.02, 0.08);
+ q.y *= 1.65;
+ float r = length(q);
+ float a = atan(q.y, q.x);
+ vec3 color = vec3(0.0005, 0.0002, 0.0015);
+ float warped = pow(0.5 + 0.5 * sin(log(r + 0.018) * 34.0 + a * 3.0), 10.0);
+ color += mix(vec3(0.25, 0.018, 0.18), vec3(1.0, 0.35, 0.055), smoothstep(-0.6, 0.8, sin(a)))
+ * warped * smoothstep(0.72, 0.11, r) * 0.52;
+ float accretion = exp(-abs(r - 0.205) * 62.0);
+ float hot = exp(-abs(r - 0.205) * 155.0);
+ color += vec3(0.95, 0.18, 0.045) * accretion * (0.55 + uBloom);
+ color += vec3(1.0, 0.82, 0.45) * hot * 1.25;
+ float lens = ring(q, 0.31, 0.004) + ring(q, 0.42, 0.003) * 0.35;
+ color += vec3(0.45, 0.18, 0.7) * lens * 0.35;
+ color *= smoothstep(0.145, 0.19, r);
+ return color;
+ }
+
+ vec3 aeons(vec2 uv, vec2 p) {
+ vec3 color = mix(vec3(0.006, 0.003, 0.018), vec3(0.035, 0.015, 0.065), uv.y);
+ color += vec3(0.45, 0.36, 0.16) * stars(uv, 0.0024) * 0.62;
+ vec2 q = p - vec2(-0.52, -0.38);
+ float r = length(q);
+ float haze = exp(-abs(r - 0.78) * 5.0);
+ color += vec3(0.18, 0.09, 0.28) * haze * 0.25;
+ float arcs = ring(q, 0.69, 0.0025) + ring(q, 0.83, 0.003) * 0.65 + ring(q, 1.04, 0.002) * 0.45;
+ color += vec3(0.68, 0.48, 0.17) * arcs * 0.48;
+ vec2 g = p - vec2(0.58, 0.24);
+ float spokes = pow(abs(sin(atan(g.y, g.x) * 9.0)), 70.0) * smoothstep(0.62, 0.08, length(g));
+ color += vec3(0.38, 0.27, 0.11) * spokes * 0.18;
+ color += vec3(0.16, 0.08, 0.26) * exp(-length(p - vec2(0.0, 0.35)) * 2.2) * 0.3;
+ return color;
+ }
+
+ void main() {
+ vec2 uv = gl_FragCoord.xy / max(uResolution, vec2(1.0));
+ vec2 p = uv * 2.0 - 1.0;
+ p.x *= uResolution.x / max(uResolution.y, 1.0);
+ vec3 color = vec3(0.0);
+ if (uMode < 1.5) color = mars(uv, p);
+ else if (uMode < 2.5) color = sirius(uv, p);
+ else if (uMode < 3.5) color = singularity(uv, p);
+ else color = aeons(uv, p);
+ float edge = smoothstep(1.35, 0.25, length(uv - 0.5));
+ color *= mix(1.0, edge, uVignette);
+ gl_FragColor = vec4(color * uIntensity, 1.0);
+ }
+`;
+
+const shaderMode: Record<Exclude<ViewportTheme["background"]["kind"], "flat">, number> = {
+ mars: 1,
+ sirius: 2,
+ singularity: 3,
+ aeons: 4,
+};
+
+export function ThemeBackground({ theme }: { theme: ViewportTheme }) {
+ const { size } = useThree();
+ const kind = theme.background.kind;
+ const material = useMemo(() => {
+ if (kind === "flat") return null;
+ return new ShaderMaterial({
+ vertexShader,
+ fragmentShader,
+ depthTest: false,
+ depthWrite: false,
+ uniforms: {
+ uResolution: { value: new Vector2(1, 1) },
+ uMode: { value: shaderMode[kind] },
+ uIntensity: { value: theme.background.intensity },
+ uVignette: { value: theme.postProcess.vignette },
+ uBloom: { value: theme.postProcess.bloom },
+ },
+ });
+ }, [kind, theme.background.intensity, theme.postProcess.bloom, theme.postProcess.vignette]);
+
+ useEffect(() => () => material?.dispose(), [material]);
+ useFrame(({ gl }) => {
+ material?.uniforms.uResolution.value.set(
+ size.width * gl.getPixelRatio(),
+ size.height * gl.getPixelRatio(),
+ );
+ });
+ if (!material) return null;
+ return (
+ <mesh material={material} renderOrder={-1000} frustumCulled={false} raycast={() => null}>
+ <planeGeometry args={[2, 2]} />
+ </mesh>
+ );
+}
diff --git a/aetheris.client/src/viewer/viewportTheme.ts b/aetheris.client/src/viewer/viewportTheme.ts
index 8e7dd0ef..a5c1f5e5 100644
--- a/aetheris.client/src/viewer/viewportTheme.ts
+++ b/aetheris.client/src/viewer/viewportTheme.ts
@@ -1,11 +1,33 @@
+export const VIEWPORT_THEME_IDS = [
+ "atelier",
+ "monument",
+ "mars",
+ "sirius",
+ "singularity",
+ "aeons",
+] as const;
+
+export type ViewportThemeId = (typeof VIEWPORT_THEME_IDS)[number];
+
export interface ViewportTheme {
- id: "atelier" | "monument";
+ id: ViewportThemeId;
label: string;
+ description: string;
+ category: "workbench" | "architectural" | "planetary" | "stellar" | "cosmic";
+ animated: boolean;
+ performanceClass: "balanced" | "high";
sceneBackground: string;
+ background: {
+ kind: "flat" | "mars" | "sirius" | "singularity" | "aeons";
+ fallback: string;
+ accent: string;
+ intensity: number;
+ };
objectMaterial: { color: string; roughness: number; metalness: number };
selectedMaterial: { color: string; emissive: string; emissiveIntensity: number };
edgeStyle: { color: string; width: number; selectedColor: string; selectedWidth: number };
gridStyle: {
+ enabled: boolean;
minorColor: string;
majorColor: string;
minorOpacity: number;
@@ -27,11 +49,19 @@ export interface ViewportTheme {
fillColor: string;
fillIntensity: number;
fillPosition: readonly [number, number, number];
+ rimColor: string;
+ rimIntensity: number;
+ rimPosition: readonly [number, number, number];
};
shadowStyle: { enabled: boolean; opacity: number };
environment: { toneMappingExposure: number };
fog: { enabled: boolean; color: string; near: number; far: number };
- postProcess: { outline: boolean; colorGrade: "neutral" | "pastel" };
+ postProcess: {
+ outline: boolean;
+ colorGrade: "neutral" | "pastel" | "rust" | "cold" | "high-contrast" | "antique";
+ vignette: number;
+ bloom: number;
+ };
cameraPresentation: { position: readonly [number, number, number]; zoom: number };
axis: { x: string; y: string; z: string; label: string };
annotation: {
@@ -42,16 +72,30 @@ export interface ViewportTheme {
dimension: string;
selected: string;
};
+ overlay: {
+ concept: string;
+ profile: string;
+ compose: string;
+ selection: string;
+ ancestor: string;
+ diagnostic: string;
+ };
}
export const ATELIER_VIEWPORT_THEME: ViewportTheme = {
id: "atelier",
label: "Atelier",
+ description: "Dark graphite workbench with neutral task lighting and crisp technical edges.",
+ category: "workbench",
+ animated: false,
+ performanceClass: "balanced",
sceneBackground: "#252725",
+ background: { kind: "flat", fallback: "#252725", accent: "#62645f", intensity: 0.2 },
objectMaterial: { color: "#bbb7aa", roughness: 0.72, metalness: 0.03 },
selectedMaterial: { color: "#d4bd76", emissive: "#574719", emissiveIntensity: 0.16 },
edgeStyle: { color: "#24231f", width: 1.2, selectedColor: "#f0cf68", selectedWidth: 3 },
gridStyle: {
+ enabled: true,
minorColor: "#76766f",
majorColor: "#aaa69a",
minorOpacity: 0.18,
@@ -73,11 +117,14 @@ export const ATELIER_VIEWPORT_THEME: ViewportTheme = {
fillColor: "#a9bac0",
fillIntensity: 0.48,
fillPosition: [7, 3, -5],
+ rimColor: "#a9bac0",
+ rimIntensity: 0,
+ rimPosition: [0, 2, -8],
},
shadowStyle: { enabled: false, opacity: 0.18 },
environment: { toneMappingExposure: 1.05 },
fog: { enabled: false, color: "#252725", near: 30, far: 120 },
- postProcess: { outline: false, colorGrade: "neutral" },
+ postProcess: { outline: false, colorGrade: "neutral", vignette: 0, bloom: 0 },
cameraPresentation: { position: [6, 6, 6], zoom: 90 },
axis: { x: "#a46757", y: "#6f8b64", z: "#b39b62", label: "#cbc7ba" },
annotation: {
@@ -88,13 +135,24 @@ export const ATELIER_VIEWPORT_THEME: ViewportTheme = {
dimension: "#f0cf68",
selected: "#ffffff",
},
+ overlay: {
+ concept: "#6ea6b8",
+ profile: "#4db6ac",
+ compose: "#b48748",
+ selection: "#ffbf47",
+ ancestor: "#77a7d9",
+ diagnostic: "#e05d5d",
+ },
};
export const MONUMENT_VIEWPORT_THEME: ViewportTheme = {
...ATELIER_VIEWPORT_THEME,
id: "monument",
label: "Monument",
+ description: "Pastel architectural model on pale stone, softly lit like a quiet gallery plinth.",
+ category: "architectural",
sceneBackground: "#d9cfbd",
+ background: { kind: "flat", fallback: "#d9cfbd", accent: "#f6ead2", intensity: 0.2 },
objectMaterial: { color: "#d98978", roughness: 0.9, metalness: 0 },
selectedMaterial: { color: "#f4d86e", emissive: "#704b20", emissiveIntensity: 0.1 },
edgeStyle: { color: "#725d57", width: 1, selectedColor: "#3d756f", selectedWidth: 3.2 },
@@ -117,7 +175,7 @@ export const MONUMENT_VIEWPORT_THEME: ViewportTheme = {
},
environment: { toneMappingExposure: 1.12 },
fog: { enabled: true, color: "#d9cfbd", near: 34, far: 115 },
- postProcess: { outline: false, colorGrade: "pastel" },
+ postProcess: { outline: false, colorGrade: "pastel", vignette: 0.05, bloom: 0 },
axis: { x: "#a2535c", y: "#528378", z: "#9e7d45", label: "#5f554c" },
annotation: {
text: "#302b26",
@@ -129,8 +187,250 @@ export const MONUMENT_VIEWPORT_THEME: ViewportTheme = {
},
};
-export const VIEWPORT_THEMES = [ATELIER_VIEWPORT_THEME, MONUMENT_VIEWPORT_THEME] as const;
+const MARS_VIEWPORT_THEME: ViewportTheme = {
+ ...ATELIER_VIEWPORT_THEME,
+ id: "mars",
+ label: "Mars",
+ description: "Oxidized survey plate under a low sun, with dust strata and a burnt-iron horizon.",
+ category: "planetary",
+ performanceClass: "balanced",
+ sceneBackground: "#180c0a",
+ background: { kind: "mars", fallback: "#180c0a", accent: "#ff8b43", intensity: 1 },
+ objectMaterial: { color: "#8f7564", roughness: 0.67, metalness: 0.24 },
+ selectedMaterial: { color: "#ffd08a", emissive: "#8e2f0b", emissiveIntensity: 0.42 },
+ edgeStyle: { color: "#21100c", width: 1.25, selectedColor: "#fff0b5", selectedWidth: 3.3 },
+ gridStyle: {
+ ...ATELIER_VIEWPORT_THEME.gridStyle,
+ minorColor: "#743322",
+ majorColor: "#d36738",
+ minorOpacity: 0.08,
+ majorOpacity: 0.22,
+ },
+ lights: {
+ ...ATELIER_VIEWPORT_THEME.lights,
+ ambient: 0.035,
+ hemisphereSky: "#d56a38",
+ hemisphereGround: "#160704",
+ hemisphereIntensity: 0.45,
+ keyColor: "#ffb15d",
+ keyIntensity: 3.3,
+ keyPosition: [-9, 2.4, 4],
+ fillColor: "#5c1b13",
+ fillIntensity: 0.36,
+ fillPosition: [5, 4, -6],
+ rimColor: "#ff5b24",
+ rimIntensity: 0.75,
+ rimPosition: [4, 1, -8],
+ },
+ environment: { toneMappingExposure: 0.96 },
+ fog: { enabled: true, color: "#35150f", near: 35, far: 105 },
+ postProcess: { outline: false, colorGrade: "rust", vignette: 0.44, bloom: 0.12 },
+ axis: { x: "#ff8a54", y: "#b4a15d", z: "#d85c37", label: "#ffd2aa" },
+ annotation: {
+ ...ATELIER_VIEWPORT_THEME.annotation,
+ background: "#24100be8",
+ leader: "#ef9c62",
+ datum: "#76c6ce",
+ dimension: "#ffc06c",
+ },
+ overlay: {
+ ...ATELIER_VIEWPORT_THEME.overlay,
+ concept: "#85c9d2",
+ profile: "#ffd36f",
+ compose: "#ff8452",
+ selection: "#ffffff",
+ },
+};
+
+const SIRIUS_VIEWPORT_THEME: ViewportTheme = {
+ ...ATELIER_VIEWPORT_THEME,
+ id: "sirius",
+ label: "Sirius",
+ description:
+ "Precision hardware caught in the cold spectral halo of an impossible blue-white star.",
+ category: "stellar",
+ performanceClass: "balanced",
+ sceneBackground: "#01040d",
+ background: { kind: "sirius", fallback: "#01040d", accent: "#b9ddff", intensity: 1 },
+ objectMaterial: { color: "#a8b5c3", roughness: 0.27, metalness: 0.67 },
+ selectedMaterial: { color: "#fff4b5", emissive: "#3487d8", emissiveIntensity: 0.58 },
+ edgeStyle: { color: "#071524", width: 1.05, selectedColor: "#ffffff", selectedWidth: 3.4 },
+ gridStyle: {
+ ...ATELIER_VIEWPORT_THEME.gridStyle,
+ minorColor: "#1d4c78",
+ majorColor: "#85bce8",
+ minorOpacity: 0.06,
+ majorOpacity: 0.16,
+ },
+ lights: {
+ ...ATELIER_VIEWPORT_THEME.lights,
+ ambient: 0.025,
+ hemisphereSky: "#a8d7ff",
+ hemisphereGround: "#020716",
+ hemisphereIntensity: 0.58,
+ keyColor: "#edf8ff",
+ keyIntensity: 4.2,
+ keyPosition: [-7, 8, 5],
+ fillColor: "#164d9b",
+ fillIntensity: 0.72,
+ fillPosition: [7, 2, -5],
+ rimColor: "#7ec8ff",
+ rimIntensity: 1.65,
+ rimPosition: [2, 4, -9],
+ },
+ environment: { toneMappingExposure: 1.16 },
+ fog: { enabled: true, color: "#020716", near: 42, far: 145 },
+ postProcess: { outline: false, colorGrade: "cold", vignette: 0.5, bloom: 0.34 },
+ axis: { x: "#d86f8d", y: "#79d8c0", z: "#7ebeff", label: "#dceeff" },
+ annotation: {
+ ...ATELIER_VIEWPORT_THEME.annotation,
+ background: "#020817e8",
+ leader: "#9bd3ff",
+ datum: "#65e6d0",
+ dimension: "#f3da81",
+ },
+ overlay: {
+ ...ATELIER_VIEWPORT_THEME.overlay,
+ concept: "#72d8ff",
+ profile: "#65e6d0",
+ compose: "#d7b7ff",
+ selection: "#fff3a0",
+ },
+};
+
+const SINGULARITY_VIEWPORT_THEME: ViewportTheme = {
+ ...ATELIER_VIEWPORT_THEME,
+ id: "singularity",
+ label: "Singularity",
+ description:
+ "Severe gravitational composition: black center, lensed polar bands, and controlled accretion light.",
+ category: "cosmic",
+ performanceClass: "high",
+ sceneBackground: "#000000",
+ background: { kind: "singularity", fallback: "#000000", accent: "#ffb460", intensity: 1 },
+ objectMaterial: { color: "#77777d", roughness: 0.31, metalness: 0.78 },
+ selectedMaterial: { color: "#ffffff", emissive: "#ff7838", emissiveIntensity: 0.7 },
+ edgeStyle: { color: "#050507", width: 1.15, selectedColor: "#ffd7a6", selectedWidth: 3.6 },
+ gridStyle: {
+ ...ATELIER_VIEWPORT_THEME.gridStyle,
+ enabled: false,
+ minorColor: "#402345",
+ majorColor: "#be6a55",
+ minorOpacity: 0.03,
+ majorOpacity: 0.08,
+ },
+ lights: {
+ ...ATELIER_VIEWPORT_THEME.lights,
+ ambient: 0.012,
+ hemisphereSky: "#8d7ca0",
+ hemisphereGround: "#000000",
+ hemisphereIntensity: 0.32,
+ keyColor: "#fff0d0",
+ keyIntensity: 3.7,
+ keyPosition: [-8, 6, 3],
+ fillColor: "#37104d",
+ fillIntensity: 0.7,
+ fillPosition: [7, 0, 4],
+ rimColor: "#ff6b35",
+ rimIntensity: 2.15,
+ rimPosition: [3, 3, -9],
+ },
+ environment: { toneMappingExposure: 0.92 },
+ fog: { enabled: true, color: "#000000", near: 38, far: 128 },
+ postProcess: { outline: false, colorGrade: "high-contrast", vignette: 0.7, bloom: 0.38 },
+ axis: { x: "#e8765a", y: "#9b76b7", z: "#efb771", label: "#e5ddd7" },
+ annotation: {
+ ...ATELIER_VIEWPORT_THEME.annotation,
+ background: "#050307ed",
+ leader: "#e7b193",
+ datum: "#bc8de5",
+ dimension: "#ffb46b",
+ },
+ overlay: {
+ ...ATELIER_VIEWPORT_THEME.overlay,
+ concept: "#b08eea",
+ profile: "#ff9c68",
+ compose: "#e2b06e",
+ selection: "#ffffff",
+ },
+};
+
+const AEONS_VIEWPORT_THEME: ViewportTheme = {
+ ...ATELIER_VIEWPORT_THEME,
+ id: "aeons",
+ label: "Aeons",
+ description:
+ "A quiet ancient-future observatory of immense arcs, muted gold, violet depth, and stellar haze.",
+ category: "cosmic",
+ performanceClass: "high",
+ sceneBackground: "#05030b",
+ background: { kind: "aeons", fallback: "#05030b", accent: "#c8a85d", intensity: 1 },
+ objectMaterial: { color: "#77716a", roughness: 0.48, metalness: 0.58 },
+ selectedMaterial: { color: "#e8d49a", emissive: "#80672b", emissiveIntensity: 0.52 },
+ edgeStyle: { color: "#15101d", width: 1.1, selectedColor: "#f7e2a2", selectedWidth: 3.4 },
+ gridStyle: {
+ ...ATELIER_VIEWPORT_THEME.gridStyle,
+ minorColor: "#3b294f",
+ majorColor: "#947642",
+ minorOpacity: 0.035,
+ majorOpacity: 0.13,
+ majorStep: 10,
+ },
+ lights: {
+ ...ATELIER_VIEWPORT_THEME.lights,
+ ambient: 0.025,
+ hemisphereSky: "#4c3868",
+ hemisphereGround: "#050208",
+ hemisphereIntensity: 0.5,
+ keyColor: "#ead69f",
+ keyIntensity: 2.5,
+ keyPosition: [-7, 9, 6],
+ fillColor: "#382251",
+ fillIntensity: 0.74,
+ fillPosition: [8, 3, -4],
+ rimColor: "#b8964f",
+ rimIntensity: 1.2,
+ rimPosition: [1, 5, -9],
+ },
+ environment: { toneMappingExposure: 1.02 },
+ fog: { enabled: true, color: "#090512", near: 36, far: 132 },
+ postProcess: { outline: false, colorGrade: "antique", vignette: 0.56, bloom: 0.2 },
+ axis: { x: "#b36f73", y: "#759886", z: "#bd9c55", label: "#d9cba8" },
+ annotation: {
+ ...ATELIER_VIEWPORT_THEME.annotation,
+ background: "#090611ec",
+ leader: "#baa56f",
+ datum: "#8fbcb1",
+ dimension: "#ddbf72",
+ },
+ overlay: {
+ ...ATELIER_VIEWPORT_THEME.overlay,
+ concept: "#9d90c9",
+ profile: "#a7c6ad",
+ compose: "#c9a85d",
+ selection: "#fff0aa",
+ },
+};
+
+export const VIEWPORT_THEMES: readonly ViewportTheme[] = [
+ ATELIER_VIEWPORT_THEME,
+ MONUMENT_VIEWPORT_THEME,
+ MARS_VIEWPORT_THEME,
+ SIRIUS_VIEWPORT_THEME,
+ SINGULARITY_VIEWPORT_THEME,
+ AEONS_VIEWPORT_THEME,
+];
+
+export const VIEWPORT_THEME_REGISTRY: ReadonlyMap<ViewportThemeId, ViewportTheme> = new Map(
+ VIEWPORT_THEMES.map((theme) => [theme.id, theme]),
+);
+
+export function isViewportThemeId(value: unknown): value is ViewportThemeId {
+ return typeof value === "string" && VIEWPORT_THEME_REGISTRY.has(value as ViewportThemeId);
+}
-export function viewportThemeById(id: ViewportTheme["id"]): ViewportTheme {
- return VIEWPORT_THEMES.find((theme) => theme.id === id) ?? ATELIER_VIEWPORT_THEME;
+export function viewportThemeById(id: unknown): ViewportTheme {
+ return isViewportThemeId(id)
+ ? (VIEWPORT_THEME_REGISTRY.get(id) ?? ATELIER_VIEWPORT_THEME)
+ : ATELIER_VIEWPORT_THEME;
}
diff --git a/aetheris.client/src/viewer/viewportThemePreference.ts b/aetheris.client/src/viewer/viewportThemePreference.ts
new file mode 100644
index 00000000..b6d7ff0b
--- /dev/null
+++ b/aetheris.client/src/viewer/viewportThemePreference.ts
@@ -0,0 +1,28 @@
+import { isViewportThemeId, type ViewportThemeId } from "./viewportTheme";
+
+export const VIEWPORT_THEME_STORAGE_KEY = "cadmata.viewport-theme";
+
+export function loadViewportThemePreference(
+ locationSearch = typeof window === "undefined" ? "" : window.location.search,
+ storage = typeof window === "undefined" ? null : window.localStorage,
+): ViewportThemeId {
+ const queryTheme = new URLSearchParams(locationSearch).get("theme");
+ if (isViewportThemeId(queryTheme)) return queryTheme;
+ try {
+ const stored = storage?.getItem(VIEWPORT_THEME_STORAGE_KEY);
+ return isViewportThemeId(stored) ? stored : "atelier";
+ } catch {
+ return "atelier";
+ }
+}
+
+export function saveViewportThemePreference(
+ themeId: ViewportThemeId,
+ storage = typeof window === "undefined" ? null : window.localStorage,
+) {
+ try {
+ storage?.setItem(VIEWPORT_THEME_STORAGE_KEY, themeId);
+ } catch {
+ // Storage may be disabled; theme switching remains session-local.
+ }
+}
diff --git a/docs/cadmata/artifacts/themes-m3/README.md b/docs/cadmata/artifacts/themes-m3/README.md
new file mode 100644
index 00000000..bb11402f
--- /dev/null
+++ b/docs/cadmata/artifacts/themes-m3/README.md
@@ -0,0 +1,22 @@
+# P2-CADMATA-THEMES-M3 evidence
+
+All gallery images are real WebGL captures from the same `TemplateBlockPair` assembly, fitted camera, selected occurrence, and browser application window. No generated or external background images are present.
+
+| Theme | Screenshot |
+| --- | --- |
+| Atelier | [atelier-template-block-pair.png](atelier-template-block-pair.png) |
+| Monument | [monument-template-block-pair.png](monument-template-block-pair.png) |
+| Mars | [mars-template-block-pair.png](mars-template-block-pair.png) |
+| Sirius | [sirius-template-block-pair.png](sirius-template-block-pair.png) |
+| Singularity | [singularity-template-block-pair.png](singularity-template-block-pair.png) |
+| Aeons | [aeons-template-block-pair.png](aeons-template-block-pair.png) |
+
+The gallery capture harness is the ordinary viewer plus `?perf&theme=<id>`. The query selects a deterministic initial theme, renderer instrumentation records the comparison, and the native selector permits live same-model comparison without adding a separate rendering path.
+
+Supporting evidence:
+
+- [theme-audit.md](theme-audit.md)
+- [theme-registry.md](theme-registry.md)
+- [theme-design-notes.md](theme-design-notes.md)
+- [performance.md](performance.md)
+- [validation-report.md](validation-report.md)
diff --git a/docs/cadmata/artifacts/themes-m3/aeons-template-block-pair.png b/docs/cadmata/artifacts/themes-m3/aeons-template-block-pair.png
new file mode 100644
index 00000000..d30bf998
Binary files /dev/null and b/docs/cadmata/artifacts/themes-m3/aeons-template-block-pair.png differ
diff --git a/docs/cadmata/artifacts/themes-m3/atelier-template-block-pair.png b/docs/cadmata/artifacts/themes-m3/atelier-template-block-pair.png
new file mode 100644
index 00000000..b175c4a9
Binary files /dev/null and b/docs/cadmata/artifacts/themes-m3/atelier-template-block-pair.png differ
diff --git a/docs/cadmata/artifacts/themes-m3/mars-template-block-pair.png b/docs/cadmata/artifacts/themes-m3/mars-template-block-pair.png
new file mode 100644
index 00000000..b95f7d4a
Binary files /dev/null and b/docs/cadmata/artifacts/themes-m3/mars-template-block-pair.png differ
diff --git a/docs/cadmata/artifacts/themes-m3/monument-template-block-pair.png b/docs/cadmata/artifacts/themes-m3/monument-template-block-pair.png
new file mode 100644
index 00000000..272f1178
Binary files /dev/null and b/docs/cadmata/artifacts/themes-m3/monument-template-block-pair.png differ
diff --git a/docs/cadmata/artifacts/themes-m3/performance.md b/docs/cadmata/artifacts/themes-m3/performance.md
new file mode 100644
index 00000000..2fc8f923
--- /dev/null
+++ b/docs/cadmata/artifacts/themes-m3/performance.md
@@ -0,0 +1,14 @@
+# Theme performance evidence
+
+Measured on the development machine in the in-app Chromium browser at a consistent 1157 × 1216 application window using `fixtures/AssemblyM1/template-block-pair.firmament`, the same fitted orthographic camera, one selected occurrence, and the `?perf` renderer probe. Values are approximate 120–150-frame samples after switching.
+
+| Theme | Average frame | Approx. FPS | Draw calls | Triangles | Geometries | Textures | Shader programs |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| Atelier | 7.01 ms | 142.7 | 30 | 64 | 30 | 2 | 4 |
+| Monument | 7.17 ms | 139.4 | 30 | 64 | 30 | 2 | 5 |
+| Mars | 6.93 ms | 144.3 | 31 | 66 | 31 | 2 | 6 |
+| Sirius | 7.08 ms | 141.2 | 31 | 66 | 31 | 2 | 6 |
+| Singularity | 6.94 ms | 144.0 | 27 | 66 | 27 | 2 | 5 |
+| Aeons | 7.12 ms | 140.5 | 31 | 66 | 31 | 2 | 6 |
+
+The procedural layer costs one draw call and two triangles. Singularity disables four adaptive-grid draws, so its total draw count is below baseline. No theme added textures. Browser diagnostics contained no WebGL or shader compilation errors; the only warning was Three.js's upstream `Clock` deprecation from the existing renderer stack.
diff --git a/docs/cadmata/artifacts/themes-m3/singularity-template-block-pair.png b/docs/cadmata/artifacts/themes-m3/singularity-template-block-pair.png
new file mode 100644
index 00000000..de46f0b3
Binary files /dev/null and b/docs/cadmata/artifacts/themes-m3/singularity-template-block-pair.png differ
diff --git a/docs/cadmata/artifacts/themes-m3/sirius-template-block-pair.png b/docs/cadmata/artifacts/themes-m3/sirius-template-block-pair.png
new file mode 100644
index 00000000..30fa5529
Binary files /dev/null and b/docs/cadmata/artifacts/themes-m3/sirius-template-block-pair.png differ
diff --git a/docs/cadmata/artifacts/themes-m3/theme-audit.md b/docs/cadmata/artifacts/themes-m3/theme-audit.md
new file mode 100644
index 00000000..69e61a3d
--- /dev/null
+++ b/docs/cadmata/artifacts/themes-m3/theme-audit.md
@@ -0,0 +1,21 @@
+# P2-CADMATA-THEMES-M3 theme audit
+
+## Previous architecture
+
+- `App.tsx` owned an in-memory `"atelier" | "monument"` theme ID and rendered one segmented button per theme. Selection, document, assembly, Mate, PMI, and display state were independent React state.
+- `viewportTheme.ts` already provided a useful typed descriptor for background color, standard material, selected material, line edges, logarithmic grid, two directional lights plus ambient/hemisphere light, shadows, exposure, fog, camera presentation, axes, and annotations.
+- `AetherisViewport.tsx` was the React/R3F boundary. It created one orthographic `Canvas`, fitted the camera only when scene/assembly bounds changed, and created `MeshStandardMaterial` presentation instances without mutating display geometry.
+- Renderer color management was explicit: `SRGBColorSpace`, `ACESFilmicToneMapping`, and per-theme exposure. The canvas was opaque with a Three.js scene background.
+- Face material and line-edge treatment were shared infrastructure. Theme-specific data lived in two descriptors; renderer wiring was shared.
+- The adaptive logarithmic grid was shared and camera-aware, but it could only be recolored—not disabled per theme.
+- CAD edges used drei `Line`; selected faces swapped presentation material; selected edges swapped width/color. Assembly occurrences reused definition face patches under immutable world matrices.
+- PMI used Drei `Html` callouts and leader lines with descriptor colors. Compiler overlays used a separate hardcoded `CADMATA_PALETTE`, so they did not adapt to light/cosmic worlds.
+- There was no post-processing dependency, environment map, HDRI, texture-backed background, shader seam, registry map, persistence, or reduced-motion concern. Performance instrumentation already exposed frame time, renderer calls/triangles/memory, and logarithmic-grid allocations under `?perf`.
+
+## Extraction decisions
+
+- Retain the single descriptor and existing renderer boundary; expand it with metadata, background kind, rim light, grid enablement, effects intent, and semantic-overlay palette.
+- Add one bounded full-screen procedural background component rather than scattering per-theme scene switches or introducing a shader graph.
+- Replace the theme button expansion point with a registry-driven native dropdown.
+- Reuse existing selection/material/PMI paths and make their colors theme-aware. Do not touch display packet, tessellation, assembly, semantic, export, or camera-fit code.
+- Keep post-processing dependency-free. Background-only vignette/glow supplies composition without affecting CAD depth, picking, or annotation sharpness.
diff --git a/docs/cadmata/artifacts/themes-m3/theme-design-notes.md b/docs/cadmata/artifacts/themes-m3/theme-design-notes.md
new file mode 100644
index 00000000..ff2149d7
--- /dev/null
+++ b/docs/cadmata/artifacts/themes-m3/theme-design-notes.md
@@ -0,0 +1,27 @@
+# Theme design notes
+
+## Atelier
+
+Graphite workbench, warm/cool neutral task light, matte stock, dark high-readability edges, restrained technical grid. Preserved as the engineering default.
+
+## Monument
+
+Pale stone/paper gallery, warm sky and pastel fill, salmon architectural material, soft fog, quiet brown grid. Preserved as the light presentation alternative.
+
+## Mars
+
+Oxidized geological plate with an analytic low sun, burnt atmospheric horizon, contour-like dust strata, and deterministic sparse particulate points. A grazing orange key and ember rim create brutalist survey-equipment silhouettes; moderately rough metal keeps the part physical.
+
+## Sirius
+
+Deep blue-black stellar field with a blue-white analytic star, spectral halo, restrained diffraction rays, tiny deterministic stars, and one orbital trace. A hard white key, cold rim, and lower-roughness metal make CAD read as precision instrumentation without coating the UI in cyan.
+
+## Singularity
+
+The most severe theme: an off-axis black disk, incandescent accretion ring, logarithmic polar bands, and controlled lens rings. The focal point is placed beside the model so it cannot erase the engineering silhouette. Warm energy rim and low ambient response leave selected surfaces and edges legible. The ground grid is suppressed.
+
+## Aeons
+
+Deep violet observatory with enormous gold arcs, sparse star haze, diagrammatic radial spokes, and a subdued volumetric gradient. Muted gold metal and a large soft violet/gold rig make the assembly feel like an ancient machine without literal glyphs or fantasy decoration.
+
+No additional themes were added: the four requested worlds already cover the strongest distinct directions, and a palette-swap extra would dilute the gallery.
diff --git a/docs/cadmata/artifacts/themes-m3/theme-registry.md b/docs/cadmata/artifacts/themes-m3/theme-registry.md
new file mode 100644
index 00000000..f88991bf
--- /dev/null
+++ b/docs/cadmata/artifacts/themes-m3/theme-registry.md
@@ -0,0 +1,12 @@
+# Theme registry evidence
+
+| ID | Name | Category | Animated | Performance | Grid |
+| --- | --- | --- | --- | --- | --- |
+| `atelier` | Atelier | workbench | no | balanced | adaptive logarithmic |
+| `monument` | Monument | architectural | no | balanced | adaptive logarithmic |
+| `mars` | Mars | planetary | no | balanced | low-opacity technical field |
+| `sirius` | Sirius | stellar | no | balanced | sparse cold technical field |
+| `singularity` | Singularity | cosmic | no | high | disabled |
+| `aeons` | Aeons | cosmic | no | high | faint large-step field |
+
+The ordered gallery and lookup map are derived from the same six descriptors. Tests assert order/completeness, uniqueness, valid lookup, invalid-ID fallback, static-by-default behavior, and selected-edge/annotation contrast.
diff --git a/docs/cadmata/artifacts/themes-m3/validation-report.md b/docs/cadmata/artifacts/themes-m3/validation-report.md
new file mode 100644
index 00000000..2b80d7de
--- /dev/null
+++ b/docs/cadmata/artifacts/themes-m3/validation-report.md
@@ -0,0 +1,48 @@
+# P2-CADMATA-THEMES-M3 validation report
+
+## Automated validation
+
+- `tspack --version`: `v0.1.8`.
+- `tspack sync`: passed.
+- `tspack check`: passed with the repository's acknowledged lifecycle-script inventory and existing multi-version lockfile diagnostics; no dependency was added by this milestone.
+- `tspack check --format`: passed after `tspack format` fixed three milestone files.
+- `tspack run typecheck`: passed.
+- `tspack run test`: 14 files, 75 tests passed.
+- `tspack run build`: passed; production Three.js chunk 724.48 kB, inside the existing 750 kB project budget.
+- `tspack run lint`: passed.
+- `dotnet build Aetheris.slnx -f net10.0 --no-restore /m:1`: passed, 0 warnings and 0 errors.
+- `dotnet test Aetheris.Server.Tests/Aetheris.Server.Tests.csproj -f net10.0 --no-restore /m:1`: 53 passed, 0 failed.
+- `git diff --check`: passed.
+
+## Rendered assembly QA
+
+Fixture: `fixtures/AssemblyM1/template-block-pair.firmament` loaded through the real Cadmata startup/assembly display path.
+
+- Same two-definition/two-occurrence assembly and fitted orthographic camera captured under all six themes.
+- Selecting `Fixed` in the product tree produced `active-row`; that exact selection remained active through all six immediate theme switches.
+- Direct canvas selection after orbit/pan/zoom selected `Moving` in the product tree, confirming shader backgrounds do not intercept pointer events.
+- Orbit, Shift-drag pan, wheel zoom, direct mesh selection, product-tree selection, and theme switching completed without browser errors.
+- Mate `Seat` remained `valid`; tolerance stack `TemplateFitTransition` remained `PASS` at 2 mm [2, 2].
+- Draw calls, triangle counts, and geometry counts changed only by the decorative full-screen plane and theme grid policy. Engineering occurrence transforms and semantic identity did not change.
+
+## Selection, semantic overlay, and PMI QA
+
+Fixture: `pmi-projected-hole-diameter`, loaded through the real Cadmata fixture endpoint and R3F/HTML annotation path.
+
+- Both `DATUM A` and `⌀8 mm +0.05 mm/-0.02 mm A` callouts were present under Atelier, Monument, Mars, Sirius, Singularity, and Aeons.
+- Dark worlds used opaque/near-opaque dark callout backgrounds with white selected text; Monument used pale paper with black selected text.
+- Theme overlay palettes supply separate concept, profile, compose, selection, ancestor, and diagnostic accents.
+- Selected face material and selected edge width/color remain stronger than normal presentation in every descriptor.
+
+## Renderer and fallback QA
+
+- Output color space remained sRGB; ACES filmic tone mapping and exposure are explicit per theme.
+- No WebGL or shader compilation errors appeared in browser diagnostics. The only warning was the existing upstream Three.js `Clock` deprecation.
+- Procedural backgrounds use no textures and write no depth. The opaque scene clear remains behind the shader as a graceful failure fallback.
+- All procedural themes are static by default, satisfying reduced-motion without a separate animation branch.
+
+## Remaining visual limitations
+
+- Background glow and vignette are shader-local composition effects, not depth-aware post-processing; CAD highlights do not bloom into screen space.
+- The current orthographic viewer has no shadow-catching plinth, so Monument remains a soft architectural presentation rather than a physically grounded studio render.
+- Evidence uses the native TemplateBlockPair assembly and projected-PMI fixture. Imported OCCT assembly semantics are covered by existing server paths/tests but were not recaptured for every theme in this milestone.
diff --git a/docs/cadmata/themes.md b/docs/cadmata/themes.md
new file mode 100644
index 00000000..49cf4d39
--- /dev/null
+++ b/docs/cadmata/themes.md
@@ -0,0 +1,55 @@
+# Cadmata viewport themes
+
+Cadmata viewport themes are presentation-only renderer configurations. Switching a theme does not rebuild display packets, tessellation, assembly occurrences, semantic selections, Mates, PMI, transforms, or camera fit. `App` owns the selected theme ID; `AetherisViewport` consumes the resolved descriptor.
+
+## Registry and descriptors
+
+`aetheris.client/src/viewer/viewportTheme.ts` defines `ViewportTheme`, the ordered `VIEWPORT_THEMES` gallery, and the deterministic `VIEWPORT_THEME_REGISTRY`. A descriptor owns:
+
+- metadata (`id`, label, description, category, animation, performance class);
+- renderer background fallback, explicit ACES exposure, fog, and restrained effects recipe;
+- object and selected material response;
+- edge, adaptive logarithmic grid, axes, selection overlay, and PMI colors;
+- ambient, hemisphere, key, fill, and rim lighting.
+
+The six curated themes are:
+
+| Theme | Intent | Background | Presentation |
+| --- | --- | --- | --- |
+| Atelier | Industrial engineering workbench | Graphite clear | Neutral task light, matte stock, crisp dark edges |
+| Monument | Architectural gallery model | Pale stone clear | Pastel material, soft warm light, quiet grid |
+| Mars | Oxidized planetary survey plate | Analytic dust horizon, low sun, strata, sparse particulate field | Burnt iron, grazing orange key, deep red shadow |
+| Sirius | Cold-spectrum stellar product render | Deterministic starfield, blue-white halo, diffraction rays, orbital trace | Metallic precision finish, hard white key, blue rim |
+| Singularity | Severe cosmic graphics plate | Off-axis event horizon, accretion ring, logarithmic polar bands, lens rings | High-contrast metal, warm energy rim, grid suppressed |
+| Aeons | Ancient-future observatory | Violet star haze, immense concentric arcs, mathematical spokes | Muted gold metal, monument-scale rim, faint technical grid |
+
+No generated images, HDRIs, stock textures, or external art packs are used.
+
+## Procedural background seam
+
+`ThemeBackground.tsx` is a bounded, non-selectable full-screen shader layer. One deterministic WebGL-compatible fragment program contains the four curated procedural worlds and is selected by a numeric theme mode. It uses analytic gradients, hashes, interpolated noise, polar distance fields, logarithmic bands, diffraction lines, and concentric-ring SDFs. The shader writes no depth, cannot intercept raycasts, renders before CAD, and leaves `scene.background` as a failure fallback.
+
+Effects described as bloom or vignette are deliberately implemented inside the background composition. Cadmata has no post-processing dependency and this milestone does not add a full-frame effect chain that could soften edges, alter picking, or obscure PMI. The geometry remains under normal Three.js depth testing and ACES filmic tone mapping.
+
+All themes are static by default. This makes still frames deterministic, avoids gratuitous motion during inspection, and inherently honors reduced-motion preferences. If animation is added later, gate the time uniform with `prefers-reduced-motion` and keep the static shader path authoritative.
+
+## Theme selector and persistence
+
+The viewport toolbar contains a labeled native `<select>`, populated directly from the registry. It exposes the current selection, switches immediately without a scene reload, supports normal keyboard navigation and focus-visible styling, and stores the ID under `cadmata.viewport-theme` in `localStorage`. A valid `?theme=<id>` query overrides storage for repeatable gallery capture; invalid IDs fall back to Atelier.
+
+MachinaLayout continues to own shell/workspace regions. The selector remains in the existing Machina viewport region; Three.js/R3F remains the 3D scene authority.
+
+## Adding a theme
+
+1. Add a stable lowercase ID to `VIEWPORT_THEME_IDS`.
+2. Add one complete descriptor to `VIEWPORT_THEMES`. Reuse a nearby theme only as a base and explicitly override its visual identity.
+3. If a flat background is insufficient, add one bounded mode to `ThemeBackground`; do not add selectable scene geometry or a generic shader graph.
+4. Give selected edges, assembly selection, semantic overlays, datum labels, and PMI callouts explicit high-contrast colors.
+5. Decide whether the adaptive grid belongs in the composition; set `gridStyle.enabled` accordingly.
+6. Add registry/fallback tests and capture the same model/camera gallery frame with `?perf&theme=<id>`.
+
+## Performance and fallback
+
+The four procedural themes add one full-screen draw call, two triangles, one geometry, and normally one shader program. Singularity disables the adaptive grid and is therefore cheaper in draw calls despite its denser fragment work. The renderer keeps an opaque clear fallback color behind every shader. A shader compile/runtime failure therefore removes atmosphere, not CAD geometry.
+
+Representative measurements and screenshots live in `docs/cadmata/artifacts/themes-m3/`.