feat: integrate canvas health check into tick function of CLM.

Author: feliopterix

AGENTS.md

@@ -60,20 +60,25 @@
 - The `dive-demo` orientation display example now uses a single `QuickView` canvas with `displayAxes: true`; the previous side-by-side comparison against a manually wired `OrientationDisplay` plugin is no longer the expected snapshot shape
 - `dive-demo` views that gate UI interactivity on `QuickView` readiness, such as `DiveSwitchCanvas` and `DiveTargetAnimation`, need to wait for a non-zero canvas layout plus a small initial delay before constructing `QuickView`; on CI `Linux + xvfb + llvmpipe`, starting too early leaves control buttons permanently disabled
 - In `dive-demo`, replacing the fixed QuickView startup sleep with a shared layout-driven wait helper (`ResizeObserver` plus animation-frame verification) keeps the initial load stable, but canvas-switch flows still need to yield one DOM frame after committing the active-panel state before calling `mainView.setCanvas(...)`
-- `DIVECanvasLifecycleManager` in `src/engine/canvas/` now owns canvas parent observation, renderable-layout bootstrapping, and steady-state resize propagation through one shared `setInterval(..., 16)` bootstrap loop plus one long-lived `ResizeObserver`
-- `DIVECanvasLifecycleManager` now starts its shared 16ms bootstrap lazily directly inside `waitForRenderableCanvas()`; the constructor and `setCanvas()` only reset state and do not start polling on their own
-- `DIVECanvasLifecycleManager.waitForRenderableCanvas()` now owns both bootstrap creation and waiting inline, and falls back to a direct ready-layout read once bootstrap has finished
+- `DIVECanvasLifecycleManager` in `src/engine/canvas/` is again the single owner of canvas readiness state: it keeps the waiter promises, resolves `waitForRenderableCanvas()`, and advances readiness via its own `tick()`
+- `DIVECanvasLifecycleManager.tick()` must early-return while the current canvas remains valid; only invalid, detached, or freshly swapped canvases should re-enter the two-sample stabilization path
+- `DIVECanvasLifecycleManager.tick()` should stay as a shallow entrypoint that does the dispose guard and then delegates the actual lifecycle progression to the private `_checkCanvasHealth()` helper for readability
+- `DIVEView.tick()` should always call `DIVECanvasLifecycleManager.tick()` before honoring the paused/render path so canvas readiness can continue progressing even while rendering is paused
 - `DIVECanvasLifecycleManager` keeps its layout/readiness helpers as private member methods instead of top-level module helpers, so the canvas lifecycle logic stays co-located inside the class
 - `DIVEView.init()`, `DIVERenderer.init()`, and `DIVEEnvironment.init()` should stay `async` and explicitly `await` their cached `_initPromise` values; this repo prefers the consistent async method shape over collapsing those branches to direct promise returns
-- `DIVECanvasLifecycleManager.waitForRenderableCanvas()` can take an optional `AbortSignal`; aborting now only resolves that individual waiter with `null` and removes the waiter listener, while the shared bootstrap interval continues for other callers
+- `DIVECanvasLifecycleManager.waitForRenderableCanvas()` can take an optional `AbortSignal`; aborting resolves only that individual waiter with `null`, while the CLM's shared readiness state keeps progressing through later `tick()` calls
 - `DIVEView` now uses an internal `AbortController` to invalidate pending init work on `dispose()` and `setCanvas()`; even with abort support, `renderer !== this._renderer` remains as the stale-renderer guard after awaited renderer initialization
 - `DIVERenderer` no longer owns DOM/canvas readiness logic; it only initializes WebGPU/environment state, swaps canvases, and handles render/resize calls
 - The old `DIVEResizeManager` compatibility layer has been removed entirely on v3; canvas ownership now lives directly between `DIVEView` and `DIVECanvasLifecycleManager`
 - `DIVEView.setCanvas()` must not force an immediate `onResize()` on the swapped canvas; the `DIVECanvasLifecycleManager` is the single source of truth for resize propagation
 - `DIVECanvasLifecycleManager.setCanvas()` must reset its cached width/height so an equally sized replacement canvas still emits the initial resize sync for the new renderer/camera pair
-- In `DIVECanvasLifecycleManager`, keep raw measurement in `_getCanvasLayout()`; the readiness-gated direct-layout reuse now lives inline in `waitForRenderableCanvas()` because it only has one caller
+- In `DIVECanvasLifecycleManager`, keep raw measurement in `_getCanvasLayout()` and the valid-layout fast path inside `waitForRenderableCanvas()`/`tick()`; there is no longer a separate public readiness accessor
 - `DIVEView` should pass a named `_handleCanvasResize` callback into `DIVECanvasLifecycleManager` instead of an inline lambda, so the renderer/camera resize orchestration stays explicit while the CLM remains decoupled
 - `DIVEView` invalidation branches after async init are best covered by disposing the view while `renderer.init()` is still pending and by invoking the `DIVECanvasLifecycleManager` resize callback directly to assert the `onResize` + immediate render path
-- `DIVECanvasLifecycleManager` coverage is easiest to keep at 100% with fake timers around the shared 16ms bootstrap poll, plus a few explicit private-path tests for aborted waiter signals and direct-layout fallbacks after bootstrap
+- `DIVECanvasLifecycleManager` keeps a single steady-state `ResizeObserver` on the canvas itself; parent changes are handled in `tick()` as validity invalidations rather than as observed resize events
+- `DIVEView` does not inject the clock into `DIVECanvasLifecycleManager`; only `DIVEView` itself is a `DIVETicker`, and `DIVE.startAsync()` must start the `DIVEClock` before awaiting `mainView.init()` so the CLM's internal `tick()` can progress inside the view loop
+- `DIVECanvasLifecycleManager` coverage is easiest to keep at 100% with explicit `tick()` advancement in tests, observer invalidation cases, and signal-based waiter success/stale-resolution assertions
 - In `View.test.ts`, the `waitForRenderableCanvas` mock should be explicitly typed as `Promise<DIVECanvasLayout | null>`; otherwise the stale `null` path triggers a TypeScript error on `mockResolvedValue(null)`
+- In `Dive.test.ts`, `mainView.init` is typed as a plain async method, so tests should narrow it with `vi.mocked(...)` before calling mock-only helpers like `mockRejectedValueOnce` or `mockImplementationOnce`
 - Full focused coverage for `CanvasLifecycleManager.ts` now needs explicit tests for parentless bootstrap polling, renderable-to-zero resets during stabilization, same-size canvas swaps, waiter-only aborts, and the private direct-layout fallback after bootstrap completion
+- Focused single-file coverage in this repo should use `vitest --coverage.include=<path>`; running one suite with the default global `src/**/*` coverage scope still enforces repo-wide thresholds and will fail even when the targeted file itself is at 100%

src/engine/Dive.ts

@@ -205,15 +205,31 @@ export class DIVE {
             return;
         }
 
-        if (!this.mainView.renderer.initialized) {
-            await this.mainView.init();
+        if (this.mainView.renderer.initialized) {
+            this._clock.start();
+        } else {
+            const initPromise = this.mainView.init();
+
+            queueMicrotask(() => {
+                if (!this._disposed) {
+                    this._clock.start();
+                }
+            });
+
+            try {
+                await initPromise;
+            } catch (error) {
+                this.dispose();
+                console.error(
+                    'DIVE.startAsync: Failed to initialize. Error:',
+                    error,
+                );
+            }
         }
 
         if (this._disposed) {
             return;
         }
-
-        this._clock.start();
     }
 
     public stop(): void {

src/engine/__test__/Dive.test.ts

@@ -24,7 +24,7 @@ vi.mock('../view/View.ts', async (importOriginal) => {
     const actual = await importOriginal<typeof import('../view/View.ts')>();
     return {
         ...actual,
-        DIVEView: vi.fn(function (this: any) {
+        DIVEView: vi.fn(function (this: any, _scene, _camera, _settings) {
             const renderer = {
                 initialized: false,
                 canvas: {
@@ -54,6 +54,7 @@ vi.mock('../view/View.ts', async (importOriginal) => {
                 },
             };
             this.canvas = renderer.canvas;
+            this.dispose = vi.fn();
             return this;
         }),
     };
@@ -232,6 +233,13 @@ describe('DIVE', () => {
         expect(dive).toBeDefined();
     });
 
+    it('should register the main view with the clock', () => {
+        const dive = new DIVE();
+
+        expect(dive.clock.addTicker).toHaveBeenCalledTimes(1);
+        expect(dive.clock.addTicker).toHaveBeenCalledWith(dive.mainView);
+    });
+
     it('should instantiate in development DIVE_NODE_ENV', () => {
         process.env.DIVE_NODE_ENV = 'development';
         const dive = new DIVE();
@@ -298,6 +306,10 @@ describe('DIVE', () => {
         const dive = new DIVE(settings);
         await waitForAsync();
         expect(dive['_orientationDisplay']).toBeDefined();
+        expect(dive.clock.addTicker).toHaveBeenCalledTimes(2);
+        expect(dive.clock.addTicker).toHaveBeenCalledWith(
+            dive['_orientationDisplay'],
+        );
     });
 
     it('should not initialize axis camera when displayAxes is false', () => {
@@ -359,12 +371,12 @@ describe('DIVE', () => {
             autoStart: false,
         });
 
-        dive.mainView.init.mockRejectedValueOnce(error);
+        vi.mocked(dive.mainView.init).mockRejectedValueOnce(error);
         dive.start();
         await waitForAsync();
 
         expect(errorSpy).toHaveBeenCalledWith(
-            'DIVE.start: Failed to initialize the WebGPU renderer.',
+            'DIVE.startAsync: Failed to initialize. Error:',
             error,
         );
     });
@@ -386,26 +398,26 @@ describe('DIVE', () => {
         expect(dive.clock.stop).toHaveBeenCalled();
     });
 
-    it('should not start the clock after dispose when renderer init resolves late', async () => {
+    it('should queue the clock start while renderer init is pending', async () => {
         const dive = new DIVE({
             autoStart: false,
         });
         let resolveInit: (() => void) | undefined;
 
-        dive.mainView.init.mockImplementationOnce(
+        vi.mocked(dive.mainView.init).mockImplementationOnce(
             () =>
                 new Promise<void>((resolve) => {
                     resolveInit = resolve;
                 }),
         );
 
         const pendingStart = dive.startAsync();
-        await dive.dispose();
+        await Promise.resolve();
+
+        expect(dive.clock.start).toHaveBeenCalledTimes(1);
 
         resolveInit?.();
         await pendingStart;
-
-        expect(dive.clock.start).not.toHaveBeenCalled();
     });
 
     it('should get the canvas', () => {

src/engine/canvas/CanvasLifecycleManager.ts

@@ -13,7 +13,7 @@ export class DIVECanvasLifecycleManager {
     private _height: number = 0;
     private _canvas: HTMLCanvasElement;
     private _disposed: boolean = false;
-    private _bootstrapInterval: ReturnType<typeof setInterval> | null = null;
+    private _isCanvasHealthy: boolean = false;
     private _observedParent: HTMLElement | null = null;
     private _pendingStableLayout: DIVECanvasLayout | null = null;
     private _bootstrapPromise: Promise<DIVECanvasLayout | null> | null = null;
@@ -30,18 +30,35 @@ export class DIVECanvasLifecycleManager {
         this._resizeObserver = new ResizeObserver((entries) => {
             const entry = entries[0];
             const { width, height } = entry.contentRect;
+
+            if (!this._hasRenderableSize(width, height)) {
+                this._width = width;
+                this._height = height;
+                this._invalidateCanvasHealth();
+                return;
+            }
+
             this._applyResize(width, height);
         });
     }
 
+    public tick(): void {
+        if (this._disposed) {
+            return;
+        }
+
+        this._checkCanvasHealth();
+    }
+
     public setCanvas(canvas: HTMLCanvasElement): void {
         this._canvas = canvas;
         this._width = 0;
         this._height = 0;
         this._resizeObserver.disconnect();
+        this._isCanvasHealthy = false;
         this._observedParent = null;
         this._pendingStableLayout = null;
-        this._completeBootstrap(null);
+        this._resolvePendingWaiters(null);
     }
 
     public async waitForRenderableCanvas(
@@ -53,76 +70,29 @@ export class DIVECanvasLifecycleManager {
         }
 
         if (
-            !this._bootstrapPromise &&
-            canvas === this._canvas &&
+            this._isCanvasHealthy &&
             canvas.parentElement !== null &&
-            this._observedParent === canvas.parentElement
+            canvas.parentElement === this._observedParent &&
+            this._hasRenderableSize(this._width, this._height)
         ) {
-            const layout = this._getCanvasLayout(canvas);
-
-            if (this._hasRenderableSize(layout.width, layout.height)) {
-                return layout;
-            }
+            return {
+                width: this._width,
+                height: this._height,
+            };
         }
 
         if (!this._bootstrapPromise) {
             this._bootstrapPromise = new Promise((resolve) => {
                 this._resolveBootstrap = resolve;
             });
-
-            this._bootstrapInterval = setInterval(() => {
-                if (this._disposed) {
-                    this._completeBootstrap(null);
-                    return;
-                }
-
-                const currentCanvas = this._canvas;
-                const parent = currentCanvas.parentElement;
-
-                if (!parent) {
-                    this._observedParent = null;
-                    this._pendingStableLayout = null;
-                    return;
-                }
-
-                if (parent !== this._observedParent) {
-                    this._observedParent = parent;
-                    this._pendingStableLayout = null;
-                }
-
-                const layout = this._getCanvasLayout(currentCanvas);
-
-                if (!this._hasRenderableSize(layout.width, layout.height)) {
-                    this._pendingStableLayout = null;
-                    return;
-                }
-
-                if (
-                    this._pendingStableLayout === null ||
-                    this._pendingStableLayout.width !== layout.width ||
-                    this._pendingStableLayout.height !== layout.height
-                ) {
-                    this._pendingStableLayout = layout;
-                    return;
-                }
-
-                this._resizeObserver.observe(currentCanvas);
-                this._resizeObserver.observe(parent);
-                this._applyResize(layout.width, layout.height);
-                this._completeBootstrap(layout);
-            }, 16);
         }
 
-        const bootstrapPromise = this._bootstrapPromise!;
+        const bootstrapPromise = this._bootstrapPromise;
 
         if (!signal) {
             return await bootstrapPromise;
         }
 
-        if (signal.aborted) {
-            return null;
-        }
-
         return await new Promise((resolve) => {
             const onAbort = (): void => {
                 signal.removeEventListener('abort', onAbort);
@@ -150,22 +120,64 @@ export class DIVECanvasLifecycleManager {
 
     public dispose(): void {
         this._disposed = true;
-        this._completeBootstrap(null);
+        this._isCanvasHealthy = false;
+        this._resolvePendingWaiters(null);
         this._resizeObserver.disconnect();
     }
 
-    private _applyResize(width: number, height: number): void {
-        if (width === this._width && height === this._height) {
+    private _checkCanvasHealth(): void {
+        const canvas = this._canvas;
+        const parent = canvas.parentElement;
+
+        if (this._isCanvasHealthy) {
+            if (
+                parent === this._observedParent &&
+                this._hasRenderableSize(this._width, this._height)
+            ) {
+                return;
+            }
+
+            this._invalidateCanvasHealth();
+        }
+
+        if (!parent) {
             return;
         }
 
-        this._width = width;
-        this._height = height;
+        if (parent !== this._observedParent) {
+            this._observedParent = parent;
+            this._pendingStableLayout = null;
+        }
+
+        const layout = this._getCanvasLayout(canvas);
 
-        if (!this._hasRenderableSize(width, height)) {
+        if (!this._hasRenderableSize(layout.width, layout.height)) {
+            this._pendingStableLayout = null;
             return;
         }
 
+        if (
+            this._pendingStableLayout === null ||
+            this._pendingStableLayout.width !== layout.width ||
+            this._pendingStableLayout.height !== layout.height
+        ) {
+            this._pendingStableLayout = layout;
+            return;
+        }
+
+        this._resizeObserver.observe(canvas);
+        this._applyResize(layout.width, layout.height);
+        this._isCanvasHealthy = true;
+        this._resolvePendingWaiters(layout);
+    }
+
+    private _applyResize(width: number, height: number): void {
+        if (width === this._width && height === this._height) {
+            return;
+        }
+
+        this._width = width;
+        this._height = height;
         this._onResize(width, height);
     }
 
@@ -185,12 +197,14 @@ export class DIVECanvasLifecycleManager {
         };
     }
 
-    private _completeBootstrap(layout: DIVECanvasLayout | null): void {
-        if (this._bootstrapInterval !== null) {
-            clearInterval(this._bootstrapInterval);
-            this._bootstrapInterval = null;
-        }
+    private _invalidateCanvasHealth(): void {
+        this._isCanvasHealthy = false;
+        this._observedParent = null;
+        this._pendingStableLayout = null;
+        this._resizeObserver.disconnect();
+    }
 
+    private _resolvePendingWaiters(layout: DIVECanvasLayout | null): void {
         this._pendingStableLayout = null;
 
         const resolveBootstrap = this._resolveBootstrap;