@ifc-lite/viewer 1.17.6 → 1.19.0

package/src/store/slices/overlayCompositor.test.ts

@@ -0,0 +1,164 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Compositor reconciliation logic — unit-tested in isolation from React.
+ *
+ * The `useOverlayCompositor` hook's reconciliation loop (what-we-wrote vs.
+ * what-the-layers-want + user-isolation preservation) is extracted from
+ * the React shape so we can assert the delta math without a renderer.
+ */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { composeLayers, type OverlayLayer, type RGBA } from './overlaySlice.js';
+
+/** Same logic as `useOverlayCompositor`, without React. */
+function reconcile(args: {
+  prevContributedHidden: Map<number, boolean>;
+  prevContributedColors: Set<number>;
+  layers: Map<string, OverlayLayer>;
+  currentlyHidden: Set<number>;
+}): {
+  hideDelta: number[];
+  showDelta: number[];
+  nextColors: Map<number, RGBA> | 'clear' | 'unchanged';
+  nextContributedHidden: Map<number, boolean>;
+  nextContributedColors: Set<number>;
+} {
+  const { hiddenIds: nextHidden, colorOverrides: nextColors } = composeLayers(args.layers);
+
+  // Hidden delta — unhide only ids whose "was already hidden by user"
+  // bit is false (we own them).
+  const showDelta: number[] = [];
+  for (const [id, wasHidden] of args.prevContributedHidden) {
+    if (!nextHidden.has(id) && wasHidden === false) showDelta.push(id);
+  }
+  const hideDelta: number[] = [];
+  const nextContributedHidden = new Map<number, boolean>();
+  for (const id of nextHidden) {
+    if (args.prevContributedHidden.has(id)) {
+      nextContributedHidden.set(id, args.prevContributedHidden.get(id)!);
+    } else {
+      const wasHidden = args.currentlyHidden.has(id);
+      nextContributedHidden.set(id, wasHidden);
+      if (!wasHidden) hideDelta.push(id);
+    }
+  }
+
+  // Colours are all-or-nothing.
+  let nextColorsResult: Map<number, RGBA> | 'clear' | 'unchanged';
+  let nextContributedColors: Set<number>;
+  if (nextColors.size > 0) {
+    nextColorsResult = nextColors;
+    nextContributedColors = new Set(nextColors.keys());
+  } else if (args.prevContributedColors.size > 0) {
+    nextColorsResult = 'clear';
+    nextContributedColors = new Set();
+  } else {
+    nextColorsResult = 'unchanged';
+    nextContributedColors = new Set();
+  }
+
+  return {
+    hideDelta,
+    showDelta,
+    nextColors: nextColorsResult,
+    nextContributedHidden,
+    nextContributedColors,
+  };
+}
+
+const RED: RGBA = [1, 0, 0, 1];
+
+function mkLayer(id: string, priority: number, opts: {
+  hide?: Iterable<number>;
+  colour?: Iterable<[number, RGBA]>;
+} = {}): OverlayLayer {
+  return {
+    id,
+    priority,
+    hiddenIds: opts.hide ? new Set(opts.hide) : null,
+    colorOverrides: opts.colour ? new Map(opts.colour) : null,
+  };
+}
+
+describe('overlay compositor — reconciliation', () => {
+  it("preserves user's prior isolation — doesn't unhide ids the user had hidden first", () => {
+    // User had id 5 already hidden (via class filter, say). Animation
+    // layer then registers it too.
+    const r1 = reconcile({
+      prevContributedHidden: new Map(),
+      prevContributedColors: new Set(),
+      layers: new Map([['animation', mkLayer('animation', 100, { hide: [5] })]]),
+      currentlyHidden: new Set([5]), // user already hid this
+    });
+    // We don't re-hide (hideEntities would be a no-op anyway, but we
+    // track "was already hidden" = true so we don't unhide on teardown).
+    assert.deepStrictEqual(r1.hideDelta, []);
+    assert.strictEqual(r1.nextContributedHidden.get(5), true);
+
+    // Layer goes away — we must NOT unhide 5, the user still wants it hidden.
+    const r2 = reconcile({
+      prevContributedHidden: r1.nextContributedHidden,
+      prevContributedColors: new Set(),
+      layers: new Map(),
+      currentlyHidden: new Set([5]),
+    });
+    assert.deepStrictEqual(r2.showDelta, []);
+  });
+
+  it('colour overrides are full-replace — empty layers signal a clear exactly once', () => {
+    // Layer writes a colour; next tick layer is gone — we issue clear.
+    const r1 = reconcile({
+      prevContributedHidden: new Map(),
+      prevContributedColors: new Set(),
+      layers: new Map([['animation', mkLayer('animation', 100, { colour: [[5, RED]] })]]),
+      currentlyHidden: new Set(),
+    });
+    assert.notStrictEqual(r1.nextColors, 'clear');
+    assert.notStrictEqual(r1.nextColors, 'unchanged');
+
+    const r2 = reconcile({
+      prevContributedHidden: r1.nextContributedHidden,
+      prevContributedColors: r1.nextContributedColors,
+      layers: new Map(),
+      currentlyHidden: new Set(),
+    });
+    assert.strictEqual(r2.nextColors, 'clear');
+
+    // Subsequent reconcile with still-empty colours → 'unchanged' (no
+    // redundant clear).
+    const r3 = reconcile({
+      prevContributedHidden: r2.nextContributedHidden,
+      prevContributedColors: r2.nextContributedColors,
+      layers: new Map(),
+      currentlyHidden: new Set(),
+    });
+    assert.strictEqual(r3.nextColors, 'unchanged');
+  });
+
+  it('layer swap — adds new ids, removes dropped ids (owned only)', () => {
+    // Start: animation hides {1, 2}; user had 2 pre-hidden.
+    const r1 = reconcile({
+      prevContributedHidden: new Map(),
+      prevContributedColors: new Set(),
+      layers: new Map([['animation', mkLayer('animation', 100, { hide: [1, 2] })]]),
+      currentlyHidden: new Set([2]),
+    });
+    // Tick: layer now hides {2, 3}. Id 1 should be unhidden (we owned it).
+    // Id 2 stays hidden (user owns). Id 3 hides (new).
+    const r2 = reconcile({
+      prevContributedHidden: r1.nextContributedHidden,
+      prevContributedColors: new Set(),
+      layers: new Map([['animation', mkLayer('animation', 100, { hide: [2, 3] })]]),
+      currentlyHidden: new Set([1, 2]), // store state after r1's writes
+    });
+    assert.deepStrictEqual(r2.showDelta.sort((a, b) => a - b), [1]);
+    assert.deepStrictEqual(r2.hideDelta.sort((a, b) => a - b), [3]);
+    // After swap: id 2's ownership bit still says "user owns".
+    assert.strictEqual(r2.nextContributedHidden.get(2), true);
+    assert.strictEqual(r2.nextContributedHidden.get(3), false);
+  });
+});

package/src/store/slices/overlaySlice.test.ts

@@ -0,0 +1,93 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+import { describe, it } from 'node:test';
+import assert from 'node:assert';
+import { create } from 'zustand';
+import {
+  createOverlaySlice,
+  composeLayers,
+  type OverlaySlice,
+  type OverlayLayer,
+  type RGBA,
+} from './overlaySlice.js';
+
+const RED: RGBA = [1, 0, 0, 1];
+const GREEN: RGBA = [0, 1, 0, 1];
+const BLUE: RGBA = [0, 0, 1, 1];
+
+function mkLayer(id: string, priority: number, opts: {
+  hide?: Iterable<number>;
+  colour?: Iterable<[number, RGBA]>;
+} = {}): OverlayLayer {
+  return {
+    id,
+    priority,
+    hiddenIds: opts.hide ? new Set(opts.hide) : null,
+    colorOverrides: opts.colour ? new Map(opts.colour) : null,
+  };
+}
+
+describe('overlaySlice — composition', () => {
+  it('unions hiddenIds; higher-priority layer wins on colour collisions', () => {
+    // The two non-trivial algorithmic properties of the compositor in one
+    // test: union for visibility, priority-ordered overwrite for colour.
+    const layers = new Map<string, OverlayLayer>([
+      ['lens',      mkLayer('lens',      50,  { hide: [1],       colour: [[5, RED]] })],
+      ['animation', mkLayer('animation', 100, { hide: [2, 3],    colour: [[5, GREEN]] })],
+    ]);
+    const { hiddenIds, colorOverrides } = composeLayers(layers);
+    assert.deepStrictEqual(Array.from(hiddenIds).sort((a, b) => a - b), [1, 2, 3]);
+    assert.deepStrictEqual(colorOverrides.get(5), GREEN);
+  });
+
+  it('result is independent of Map insertion order', () => {
+    // Property test — we sort by priority internally, so whichever order
+    // the caller inserts layers the answer must match.
+    const ab = composeLayers(new Map<string, OverlayLayer>([
+      ['a', mkLayer('a', 100, { colour: [[1, RED]] })],
+      ['b', mkLayer('b', 200, { colour: [[1, BLUE]] })],
+    ]));
+    const ba = composeLayers(new Map<string, OverlayLayer>([
+      ['b', mkLayer('b', 200, { colour: [[1, BLUE]] })],
+      ['a', mkLayer('a', 100, { colour: [[1, RED]] })],
+    ]));
+    assert.deepStrictEqual(ab.colorOverrides.get(1), ba.colorOverrides.get(1));
+    assert.deepStrictEqual(ab.colorOverrides.get(1), BLUE);
+  });
+});
+
+describe('overlaySlice — store wiring', () => {
+  function bootOverlayStore() {
+    return create<OverlaySlice>()((...args) => ({
+      ...createOverlaySlice(...args),
+    }));
+  }
+
+  it('registerOverlayLayer upserts; removeOverlayLayer is idempotent', () => {
+    const store = bootOverlayStore();
+    store.getState().registerOverlayLayer(mkLayer('animation', 100, { hide: [1] }));
+    store.getState().registerOverlayLayer(mkLayer('animation', 100, { hide: [2] }));
+    assert.strictEqual(store.getState().overlayLayers.size, 1);
+    assert.deepStrictEqual(Array.from(store.getState().overlayLayers.get('animation')!.hiddenIds!), [2]);
+    store.getState().removeOverlayLayer('animation');
+    store.getState().removeOverlayLayer('animation'); // idempotent
+    store.getState().removeOverlayLayer('never-registered');
+    assert.strictEqual(store.getState().overlayLayers.size, 0);
+  });
+
+  it('Map identity changes on every mutation so shallow-compare subscribers fire', () => {
+    // Zustand default equality is Object.is — Maps compare by identity.
+    // If we mutated in place, Gantt / renderer subscribers would miss
+    // layer updates and the viewport would stop refreshing.
+    const store = bootOverlayStore();
+    const ref1 = store.getState().overlayLayers;
+    store.getState().registerOverlayLayer(mkLayer('animation', 100, { hide: [1] }));
+    const ref2 = store.getState().overlayLayers;
+    store.getState().removeOverlayLayer('animation');
+    const ref3 = store.getState().overlayLayers;
+    assert.notStrictEqual(ref1, ref2);
+    assert.notStrictEqual(ref2, ref3);
+  });
+});

package/src/store/slices/overlaySlice.ts

@@ -0,0 +1,151 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Overlay layer registry — P4 of the 4D refactor plan.
+ *
+ * Problem this solves: multiple subsystems (4D animation, Gantt selection,
+ * lens colouring, user isolation) all want to contribute visibility +
+ * colour overrides to the viewport. Before this slice each owner wrote
+ * directly into `visibilitySlice.hiddenEntities` / `dataSlice.pendingColorUpdates`
+ * and tracked "what I added" in a local ref so it could restore on unmount.
+ * That pattern was copy-pasted four times with subtly different ownership
+ * semantics — a ticking time bomb when a user 3D-click lands between two
+ * owners' writes and nobody knows who owns what.
+ *
+ * Now: each owner registers a named `OverlayLayer` with a priority. The
+ * slice composes all active layers (higher priority wins on collisions)
+ * and exposes the composite via selectors. Consumers subscribe to the
+ * composite and apply it to the renderer in one place.
+ *
+ * This PR migrates the animation owner. Gantt-selection, lens, and user-
+ * isolation continue to write directly for now — they'll move in a follow-up
+ * once the animation migration proves the contract.
+ */
+
+import type { StateCreator } from 'zustand';
+
+/**
+ * RGBA tuple — `[r, g, b, a]` in 0..1 floats. Matches the shape of
+ * `pendingColorUpdates` values in `dataSlice` and the animator palette
+ * so layers can pass colour values straight through without conversion.
+ */
+export type RGBA = [number, number, number, number];
+
+export interface OverlayLayer {
+  /** Stable id used to register / update / remove. e.g. 'animation'. */
+  id: string;
+  /**
+   * Higher priority wins on colour collisions and determines layering
+   * order. Convention (0-1000):
+   *   50   — lens (background colouring)
+   *   100  — animation
+   *   200  — gantt selection
+   *   300  — user isolation (visibility wins)
+   */
+  priority: number;
+  /**
+   * Local-space expressIds this layer wants hidden. `null` = no
+   * visibility contribution.
+   */
+  hiddenIds: Set<number> | null;
+  /**
+   * Per-expressId colour override. `null` or empty Map = no colour
+   * contribution. Keys are local expressIds (federation translation is
+   * the consumer's responsibility at the compose boundary).
+   */
+  colorOverrides: Map<number, RGBA> | null;
+}
+
+export interface OverlaySlice {
+  /**
+   * Active overlay layers keyed by id. Set-identity is replaced on
+   * every update so Zustand's shallow-compare fires for subscribers.
+   */
+  overlayLayers: Map<string, OverlayLayer>;
+
+  /**
+   * Register or replace a layer. Same-id calls overwrite — callers can
+   * treat this as the "upsert" primitive: write your layer's current
+   * desired state every render, the slice handles the rest.
+   */
+  registerOverlayLayer: (layer: OverlayLayer) => void;
+
+  /**
+   * Remove a layer by id. Idempotent — no-op when the id is unknown.
+   * Use on hook cleanup / feature toggle-off.
+   */
+  removeOverlayLayer: (id: string) => void;
+
+  /**
+   * Composite the current layers into flat `hiddenIds` + `colorOverrides`
+   * maps. `hiddenIds`: union of every layer's hiddenIds. `colorOverrides`:
+   * per-id the highest-priority layer's colour wins.
+   *
+   * Selector form so callers can memoize via `useViewerStore(computeComposite)`.
+   */
+  computeCompositeOverlay: () => {
+    hiddenIds: Set<number>;
+    colorOverrides: Map<number, RGBA>;
+  };
+}
+
+export const createOverlaySlice: StateCreator<OverlaySlice, [], [], OverlaySlice> = (set, get) => ({
+  overlayLayers: new Map(),
+
+  registerOverlayLayer: (layer) => {
+    set((s) => {
+      const next = new Map(s.overlayLayers);
+      next.set(layer.id, layer);
+      return { overlayLayers: next };
+    });
+  },
+
+  removeOverlayLayer: (id) => {
+    set((s) => {
+      if (!s.overlayLayers.has(id)) return {};
+      const next = new Map(s.overlayLayers);
+      next.delete(id);
+      return { overlayLayers: next };
+    });
+  },
+
+  computeCompositeOverlay: () => composeLayers(get().overlayLayers),
+});
+
+/**
+ * Pure compositor — exported so it can be unit-tested in isolation and
+ * consumed from places that don't have the store handle (e.g. an adapter
+ * that already has the raw layers Map).
+ *
+ * Algorithm:
+ *   1. `hiddenIds`: union of every layer's hiddenIds. No priority needed —
+ *      any layer saying "hide this" wins over any layer saying "show it"
+ *      (there's no such thing as an explicit "show" in this model; layers
+ *      contribute only hide + colour).
+ *   2. `colorOverrides`: sort layers by ascending priority and apply each
+ *      layer's colour map on top. The final pass's value wins on
+ *      collisions, so the highest-priority layer dictates the colour.
+ */
+export function composeLayers(layers: Map<string, OverlayLayer>): {
+  hiddenIds: Set<number>;
+  colorOverrides: Map<number, RGBA>;
+} {
+  const hiddenIds = new Set<number>();
+  const colorOverrides = new Map<number, RGBA>();
+  if (layers.size === 0) return { hiddenIds, colorOverrides };
+
+  // Ascending priority order — later layers overwrite earlier ones on
+  // colour collisions, so the higher-priority layer wins.
+  const sorted = Array.from(layers.values()).sort((a, b) => a.priority - b.priority);
+  for (const layer of sorted) {
+    if (layer.hiddenIds) {
+      for (const id of layer.hiddenIds) hiddenIds.add(id);
+    }
+    if (layer.colorOverrides) {
+      for (const [id, rgba] of layer.colorOverrides) colorOverrides.set(id, rgba);
+    }
+  }
+  return { hiddenIds, colorOverrides };
+}

package/src/store/slices/pinboardSlice.test.ts

@@ -41,7 +41,12 @@ describe('PinboardSlice', () => {
 
     state = {
       ...cross,
-      ...createPinboardSlice(setState, () => state, cross as any),
+      // The test mock's cross-slice shape is slightly looser than the
+      // real PinboardCrossSliceState (e.g. cameraCallbacks.getViewpoint
+      // returns null only), so the typed StateCreator can't accept the
+      // mock setState directly. Cast at the boundary — runtime shape
+      // is correct, just structurally narrower than the prod type.
+      ...createPinboardSlice(setState as any, (() => state) as any, cross as any),
     };
   });
 

package/src/store/slices/playbackSlice.ts

@@ -0,0 +1,128 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Playback state slice — drives the 4D / Gantt animation clock.
+ *
+ * Owns:
+ *   • the animation master toggle + play-state + cursor time
+ *   • playback rate + loop setting
+ *   • `animationSettings` (palette, style flags, ghosting, tinting)
+ *
+ * Extracted from the schedule slice so its ~70-lines worth of state +
+ * mutators don't crowd the schedule-domain logic. Reads
+ * `scheduleRange` from `scheduleSlice` via the combined store shape
+ * in `advancePlaybackBy`, but every other mutator is self-contained —
+ * so this slice can safely be subscribed-to in isolation by the
+ * render-tick rAF loop without pulling the full schedule data into
+ * a Zustand shallow-compare.
+ */
+
+import type { StateCreator } from 'zustand';
+import type { AnimationSettings } from '@/components/viewer/schedule/schedule-animator';
+import { DEFAULT_ANIMATION_SETTINGS } from '@/components/viewer/schedule/schedule-animator';
+import type { ScheduleTimeRange } from './scheduleSlice.js';
+
+export interface PlaybackSlice {
+  /** Animation master toggle — when false the viewer renders normally. */
+  animationEnabled: boolean;
+  /** Is the playback currently advancing? */
+  playbackIsPlaying: boolean;
+  /** Current playback time, epoch ms. */
+  playbackTime: number;
+  /** Playback rate in simulated-days-per-real-second. */
+  playbackSpeed: number;
+  /** When true, looping from end → start. */
+  playbackLoop: boolean;
+  /**
+   * Animation style + palette settings. See `schedule-animator.ts` for the
+   * phase / colour model. `minimal` keeps the original visibility-only
+   * behaviour; `phased` lights up the type-colour lifecycle.
+   */
+  animationSettings: AnimationSettings;
+
+  setAnimationEnabled: (enabled: boolean) => void;
+  /** Replace the full animation-settings object. */
+  setAnimationSettings: (settings: AnimationSettings) => void;
+  /** Shallow-merge patch — convenient for toolbar toggles. */
+  patchAnimationSettings: (patch: Partial<AnimationSettings>) => void;
+  /** Restore the built-in Synchro-style defaults. */
+  resetAnimationSettings: () => void;
+  playSchedule: () => void;
+  pauseSchedule: () => void;
+  togglePlaySchedule: () => void;
+  seekSchedule: (time: number) => void;
+  setPlaybackSpeed: (speed: number) => void;
+  setPlaybackLoop: (loop: boolean) => void;
+  advancePlaybackBy: (deltaMs: number) => void;
+}
+
+/**
+ * Cross-slice reads needed by the playback slice — the rAF advance
+ * loop clamps against the current `scheduleRange.end`. Declared
+ * explicitly rather than as a cast so the combined store keeps this
+ * field accessible at compile time too.
+ */
+interface PlaybackCrossSliceReads {
+  scheduleRange?: ScheduleTimeRange | null;
+}
+
+export const createPlaybackSlice: StateCreator<
+  PlaybackSlice & PlaybackCrossSliceReads,
+  [],
+  [],
+  PlaybackSlice
+> = (set, get) => ({
+  animationEnabled: false,
+  playbackIsPlaying: false,
+  playbackTime: 0,
+  playbackSpeed: 7, // 7 simulated days per real second by default
+  playbackLoop: true,
+  animationSettings: DEFAULT_ANIMATION_SETTINGS,
+
+  setAnimationEnabled: (animationEnabled) => set({ animationEnabled }),
+  setAnimationSettings: (animationSettings) => set({ animationSettings }),
+  patchAnimationSettings: (patch) => set((s) => ({
+    animationSettings: { ...s.animationSettings, ...patch },
+  })),
+  resetAnimationSettings: () => set({ animationSettings: DEFAULT_ANIMATION_SETTINGS }),
+  playSchedule: () => set({ playbackIsPlaying: true, animationEnabled: true }),
+  pauseSchedule: () => set({ playbackIsPlaying: false }),
+  togglePlaySchedule: () => set((s) => {
+    const next = !s.playbackIsPlaying;
+    return {
+      playbackIsPlaying: next,
+      animationEnabled: next ? true : s.animationEnabled,
+    };
+  }),
+  seekSchedule: (time) => set({ playbackTime: time }),
+  setPlaybackSpeed: (playbackSpeed) => set({ playbackSpeed }),
+  setPlaybackLoop: (playbackLoop) => set({ playbackLoop }),
+
+  advancePlaybackBy: (deltaMs) => {
+    const s = get();
+    if (!s.playbackIsPlaying || !s.scheduleRange) return;
+    // Clamp the wall-clock delta before scaling. rAF pauses when the tab is
+    // hidden, OS sleeps, or a breakpoint fires; the next frame fires with a
+    // multi-second delta. At the default 7 days/sec that would skip weeks of
+    // schedule in one step, either missing animation states or overshooting
+    // the end of non-looping playback.
+    const MAX_DELTA_MS = 100;
+    const clamped = Math.min(Math.max(deltaMs, 0), MAX_DELTA_MS);
+    // speed = simulated days / real second
+    //   → simulated ms = (deltaMs / 1000) * speed * 86_400_000
+    //                  = deltaMs * speed * 86_400
+    const simulated = clamped * s.playbackSpeed * 86_400;
+    let next = s.playbackTime + simulated;
+    if (next > s.scheduleRange.end) {
+      if (s.playbackLoop) {
+        next = s.scheduleRange.start;
+      } else {
+        set({ playbackTime: s.scheduleRange.end, playbackIsPlaying: false });
+        return;
+      }
+    }
+    set({ playbackTime: next });
+  },
+});

package/src/store/slices/pointCloudSlice.ts

@@ -0,0 +1,102 @@
+/* This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
+
+/**
+ * Point cloud rendering preferences.
+ *
+ * The renderer reads these via `usePointCloudSync`; UI components write
+ * them via the actions below. EDL is opt-in (default on) — costs ~5
+ * extra texture taps per pixel.
+ */
+
+import type { StateCreator } from 'zustand';
+
+export type PointColorModeUi = 'rgb' | 'classification' | 'intensity' | 'height' | 'fixed';
+export type PointSizeModeUi = 'fixed-px' | 'adaptive-world' | 'attenuated';
+
+export interface PointCloudSlice {
+  pointCloudColorMode: PointColorModeUi;
+  pointCloudFixedColor: [number, number, number, number];
+  /** Splat sizing strategy. Default: 'fixed-px' (sized by the px slider). */
+  pointCloudSizeMode: PointSizeModeUi;
+  /** Splat size in pixels (fixed/attenuated) or upper cap (attenuated). 1..20. */
+  pointCloudPointSize: number;
+  /** World-space splat radius in metres for adaptive/attenuated modes.
+   *  Typical scans: 0.005–0.05. Default 0.02. */
+  pointCloudWorldRadius: number;
+  /** Render splats as discs vs squares. Default true. */
+  pointCloudRoundShape: boolean;
+  /** Enable Eye-Dome Lighting post-pass. Default true. */
+  pointCloudEdlEnabled: boolean;
+  /** EDL strength multiplier. 0..3, default 1. */
+  pointCloudEdlStrength: number;
+  /**
+   * Best-effort count of point cloud assets currently uploaded to the
+   * renderer. Updated by ingest paths; UI uses it to show/hide the
+   * controls panel and the EDL post-pass.
+   */
+  pointCloudAssetCount: number;
+  setPointCloudColorMode: (mode: PointColorModeUi) => void;
+  setPointCloudFixedColor: (rgba: [number, number, number, number]) => void;
+  setPointCloudSizeMode: (mode: PointSizeModeUi) => void;
+  setPointCloudPointSize: (px: number) => void;
+  setPointCloudWorldRadius: (m: number) => void;
+  setPointCloudRoundShape: (enabled: boolean) => void;
+  setPointCloudEdlEnabled: (enabled: boolean) => void;
+  setPointCloudEdlStrength: (strength: number) => void;
+  setPointCloudAssetCount: (count: number) => void;
+  incrementPointCloudAssetCount: (n?: number) => void;
+}
+
+/**
+ * Single source of truth for the slice's runtime field defaults.
+ * Both the slice initializer and `resetViewerState` consume this so
+ * the two paths can't drift.
+ */
+export const POINT_CLOUD_DEFAULTS = {
+  // Fixed-px is the default so the size slider feels responsive on first
+  // contact. `attenuated` is nicer at extreme zooms but its "slider =
+  // upper cap" semantic confuses users at typical wide views because the
+  // projected world radius sits well below the cap.
+  pointCloudColorMode: 'rgb' as PointColorModeUi,
+  pointCloudFixedColor: [1, 1, 1, 1] as [number, number, number, number],
+  pointCloudSizeMode: 'fixed-px' as PointSizeModeUi,
+  pointCloudPointSize: 4,
+  pointCloudWorldRadius: 0.02,
+  pointCloudRoundShape: true,
+  pointCloudEdlEnabled: true,
+  pointCloudEdlStrength: 1,
+  pointCloudAssetCount: 0,
+} as const;
+
+export const createPointCloudSlice: StateCreator<PointCloudSlice, [], [], PointCloudSlice> = (set) => ({
+  ...POINT_CLOUD_DEFAULTS,
+  // Re-spread typed-array fields so consumers get fresh references
+  // instead of the readonly literal in POINT_CLOUD_DEFAULTS.
+  pointCloudFixedColor: [...POINT_CLOUD_DEFAULTS.pointCloudFixedColor] as [number, number, number, number],
+  setPointCloudColorMode: (mode) => set({ pointCloudColorMode: mode }),
+  setPointCloudFixedColor: (rgba) => set({ pointCloudFixedColor: rgba }),
+  setPointCloudSizeMode: (mode) => set({ pointCloudSizeMode: mode }),
+  // NaN/Infinity slip past Math.max+min unchanged ((NaN < x) === false),
+  // so guard with isFinite to keep invalid values out of GPU uniforms.
+  setPointCloudPointSize: (px) => set({
+    pointCloudPointSize: Number.isFinite(px) ? Math.max(1, Math.min(20, px)) : 4,
+  }),
+  setPointCloudWorldRadius: (m) => set({
+    pointCloudWorldRadius: Number.isFinite(m) ? Math.max(1e-4, m) : 0.02,
+  }),
+  setPointCloudRoundShape: (enabled) => set({ pointCloudRoundShape: enabled }),
+  setPointCloudEdlEnabled: (enabled) => set({ pointCloudEdlEnabled: enabled }),
+  setPointCloudEdlStrength: (strength) => set({
+    pointCloudEdlStrength: Number.isFinite(strength) ? Math.max(0, Math.min(3, strength)) : 1,
+  }),
+  setPointCloudAssetCount: (count) => set({
+    pointCloudAssetCount: Number.isFinite(count) ? Math.max(0, count) : 0,
+  }),
+  incrementPointCloudAssetCount: (n = 1) => set((s) => ({
+    pointCloudAssetCount: Number.isFinite(n)
+      ? Math.max(0, s.pointCloudAssetCount + n)
+      : s.pointCloudAssetCount,
+  })),
+});