@luxonis/depthai-viewer-common 3.7.4 → 3.7.6

package/REFACTOR_HANDOFF.md

@@ -0,0 +1,969 @@
+# REFACTOR_HANDOFF.md
+
+## Update Protocol
+
+Every agent must update this file after each completed logical change set and before ending a session.
+
+Required fields to keep current:
+
+- branch
+- latest commit for the completed checkpoint
+- what changed
+- validation run
+- known open risks
+- exact next task
+
+## Current Status
+
+- Date: 2026-05-23
+- Branch: `performance/hitching-improvements`
+- Phase: Phase 5 package/runtime cleanup in progress
+- Latest completed checkpoint: remove unsafe compressed-input shedding from H.264/H.265 live decode
+- Latest commit for this checkpoint: pending commit for the current checkpoint
+
+## What Was Completed
+
+- `trace7.json` changed the direction again: after transport batching and latest-frame coalescing, the dominant remaining app-side cost was still in the shared image presentation path rather than in app-specific React layout.
+- The meaningful app-side spikes were still repeated `raw-image-decoder.worker` callbacks around 20-35 ms, while both raw and encoded streams eventually converged on the same `foxglove.RawImage` panel path.
+- Reworked `src/panels/image/ImageCanvasRenderer.tsx` so common live formats no longer go through the CPU raw-image decode worker before display:
+  - added a dedicated WebGL canvas path for `nv12`, `yuv420p` / `I420`, `rgb8`, `bgr8i`, `rgba8`, `bgra8`, and `mono8`
+  - kept the previous worker-decoder path as fallback for unsupported formats such as Bayer, `mono16`, and odd-stride cases
+  - kept annotation overlay rendering on the separate 2D overlay canvas
+  - kept latest-frame-only behavior and rAF-gated draw scheduling around the new presenter
+- Added `src/panels/image/webgl-image-renderer.ts` to upload planar or packed image buffers directly to WebGL textures and do color conversion in shaders instead of in `raw-image-decoder.worker`.
+- This specifically removes the hottest repeated CPU loop for the common shared path used by both raw camera streams and encoded H.264/H.265 frames once they are represented as `foxglove.RawImage`.
+- User retest after this change reported that raw-stream hitching is now minimal instead of obvious/periodic, which is the strongest manual confirmation so far that the shared image presentation path was a real part of the problem.
+- Exact files changed for this checkpoint:
+  - `src/panels/image/ImageCanvasRenderer.tsx`
+  - `src/panels/image/webgl-image-renderer.ts`
+- Follow-up browser findings changed the working diagnosis: the hitch is not encoded-only. Raw streams still lag periodically, and raw gets materially worse when H.264 is enabled beside it.
+- That points to shared decode/presentation contention plus hot-path CPU/GC churn, not only inter-frame codec behavior.
+- Reduced cross-topic contention in `src/messaging/message-handler.ts` by giving image topics dedicated deserialization workers while keeping non-image traffic on the bounded shared pool.
+- Reduced stale panel-side decode work in `src/panels/image/ImageCanvasRenderer.tsx` by making raw-image conversion single-flight latest-frame-only instead of continuing to decode superseded frames.
+- Removed deep `estimateObjectSize()` walks from hot decode outputs where the exact payload byte size is already known:
+  - `src/messaging/deserialization/video/color.ts`
+  - `src/messaging/deserialization/video/depth.ts`
+  - `src/messaging/deserialization/video/depth-to-pointcloud.ts`
+  - `src/messaging/deserialization/video/rgbd-to-pointcloud.ts`
+  - `src/messaging/deserialization/video/mono.ts`
+  - `src/messaging/deserialization/pointcloud/point-cloud.ts`
+  - `src/connection/foxglove-connection.ts`
+- Added `getKnownMessageSizeInBytes()` in `src/messaging/message-event.ts` so the connection layer can avoid recursive size estimation for typed-array-backed messages even on fallback paths.
+- Reduced RAW16 decode copies from two full-frame clones to one by cloning the depth-preview buffer up front in `src/messaging/decode-core.ts` and reusing the original decoded bytes for the point-cloud sync artifact in `src/messaging/deserialization/video/depth-to-pointcloud.ts`.
+- Validation for this checkpoint:
+  - `npm run build:visualizer-protobuf`
+  - `npm run build:common`
+  - `npm run build:visualizer`
+  - `npm run build:viewer`
+- Root cause identified for the recurring encoded-stream hitch shared by `packages/visualizer` and `packages/depthai-viewer/frontend`:
+  arbitrary compressed H.264/H.265 frames were being dropped whenever `VideoDecoder.decodeQueueSize >= 3`.
+- That input-drop policy lived in:
+  - `src/messaging/deserialization/video/h264.ts`
+  - `src/messaging/deserialization/video/h265.ts`
+- For inter-frame codecs this is unsafe because losing compressed delta/reference frames can stall visible output until the next keyframe, which matches the reported roughly-5-second cadence.
+- Removed compressed-input shedding from the live H.264/H.265 decode path in:
+  - `src/messaging/deserialization/video/h264.ts`
+  - `src/messaging/deserialization/video/h265.ts`
+- Current behavior now keeps the safer decoded-output coalescing only: `queuedOutputFrame` replacement still keeps only the latest decoded frame when output processing is behind, but compressed H.264/H.265 chunks are no longer dropped before decode based on `VideoDecoder.decodeQueueSize`.
+- This change was prompted by visible browser artifacting and stale macroblocks during live playback, which are more consistent with missing inter-frame references than with the native `renderableBitmap` presentation fast path.
+- Added opt-in diagnostics behind runtime query params `?streamDiagnostics=1`, `?visualizerDiagnostics=1`, or `?diagnostics=1`.
+- Added new shared diagnostics helper `src/messaging/stream-diagnostics.ts` and instrumented:
+  - encoded ingress cadence / payload size / queue depth
+  - backpressure observations at decoder queue pressure
+  - decoded-output replacement count
+  - worker-side decode-to-output latency using worker-local `performance.now()`
+  - image render cadence / long render frames in `src/panels/image/ImageCanvasRenderer.tsx`
+- Extended runtime config bootstrap in `src/utils/runtime-config.ts` so diagnostics can be enabled without app-specific code changes.
+- Exact files changed for this checkpoint:
+  - `src/messaging/deserialization/video/h264.ts`
+  - `src/messaging/deserialization/video/h265.ts`
+  - `src/messaging/stream-diagnostics.ts`
+  - `src/panels/image/ImageCanvasRenderer.tsx`
+  - `src/utils/runtime-config.ts`
+- Updated `src/panels/pointcloud/PointCloudCanvasRenderer.tsx` so the standalone point-cloud renderer always clears to a white background instead of switching between theme-dependent dark/light colors.
+- Stabilized encoded image delivery end-to-end by keeping live topic subscriptions stable, preserving FIFO ordering for encoded-capable image topics (`encodedFrame` and encoded `imageFrame`), and surfacing decode-path failures instead of silently dropping frames.
+- Hardened the encoded video decode pipeline by treating `FrameType.UNKNOWN` as a recoverable keyframe case, adding native-to-I420 fallback when `createImageBitmap(frame)` fails, suppressing the recoverable initial H.264/H.265 keyframe error until a usable keyframe arrives, and removing the internal double-transfer that was causing detached-buffer failures on encoded streams.
+- Fixed raw/depth image ownership and layout issues by honoring the actual raw image stride for formats like `BGR888i`, and cloning `RAW16` buffers where depth preview and point-cloud sync artifacts share the same source bytes so depth previews no longer lose access to their data.
+- Removed the temporary encoded-stream debugging/instrumentation that was added during investigation, including cross-thread debug plumbing and decode-path metadata that was no longer needed once the stream issues were resolved.
+- Added focused validation for this work by extending `src/messaging/decoder-fixtures.ts` with a stride-backed `BGR888i` case, and kept macOS protobuf generation working via the portable `sed` handling in `protobuf-gen.sh`.
+- Fixed `src/components/Panel.tsx` so annotation-disabled panels no longer trigger a self-sustaining render loop.
+- Replaced inline `[]` default props for `annotationTopics` / `extraAnnotationTopics` with stable shared empty-array defaults.
+- Changed the detections effect to avoid calling `setDetections()` when the computed detections array is already unchanged.
+- This directly addresses the remaining React production error `#185` on `PointCloudPanel`, because that panel sets `disableAnnotations` and previously hit `setDetections([])` on every render through unstable effect dependencies.
+- Fixed the local error-boundary reset behavior so it no longer compares `children` identity on every update.
+- Added an explicit `resetKey` prop to `src/components/ErrorBoundary.tsx` and switched `src/components/Panel.tsx` to reset the boundary only when the stable panel topic changes.
+- This prevents a persistent render exception from turning into a `Maximum update depth exceeded` loop in production (`Minified React error #185`) while preserving deliberate boundary reset behavior for panel swaps.
+- Removed `src/protobuf.generated/*.ts` from the git index so generated protobuf output is no longer tracked by the repository.
+- Removed `src/output.css` from git tracking and added an explicit `.gitignore` entry because Tailwind rebuilds that file locally.
+- Confirmed no extra protobuf ignore rule was needed because `**/protobuf.generated` was already ignored; the issue there was legacy tracked files, not missing ignore coverage.
+- Fixed `protobuf-gen.sh` so `protoc` resolves `protoc-gen-ts_proto` from the repository root instead of using the stale `../../node_modules/.bin/...` path after `pushd ./~proto`.
+- Added an explicit executable check for the resolved `ts-proto` plugin and a clearer failure message when dependencies are not installed.
+- Created `AGENTS.md` with architecture findings, compatibility constraints, and agent workflow rules.
+- Created `REFACTOR_PLAN.md` with phased refactor plan.
+- Created `REFACTOR_HANDOFF.md` as the running handoff ledger.
+- Extracted shared decoder orchestration from `src/messaging/deserialization.worker.ts` into `src/messaging/decode-core.ts`.
+- Added `src/messaging/decoder-harness.ts` so future fixture tests can invoke decoder logic directly without going through the worker entrypoint.
+- Kept `deserialization.worker.ts` as a thin Comlink wrapper over the extracted decode core.
+- Added `src/messaging/decoder-fixtures.ts` with built-in synthetic fixture cases for:
+  - raw color image frames
+  - IMU data
+  - colored point clouds
+  - image detections
+  - custom image annotations
+- Added focused assertions around current emitted behavior rather than only raw deep snapshots.
+- Added local decoder runtime primitives so the deserialization subtree no longer imports Foxglove runtime helpers for:
+  - message event typing
+  - parse/time helpers
+  - object size estimation
+- Updated the decoder subtree to consume those local primitives instead of `@foxglove/studio-base` runtime modules.
+- Made the depth worker pool lazy so importing decoder modules no longer immediately requires `Worker`.
+- Added a repository-native fixture entrypoint:
+  - `scripts/run-decoder-fixtures.mjs`
+  - `yarn fixtures:decode`
+- Replaced the root package-manager workflow with npm:
+  - added `package-lock.json`
+  - added `.npmrc` with `legacy-peer-deps=true` so the current dependency graph resolves under npm
+  - removed `.yarn/`, `.yarnrc.yml`, and `yarn.lock`
+  - updated `package.json` scripts and package-manager metadata to npm
+  - updated active docs and agent notes to use npm commands
+- Replaced the copied formatter/linter setup with a repo-local Biome workflow:
+  - added `@biomejs/biome`
+  - added a package-local `biome.json` tuned for this repo’s JS/TS/JSON scope
+  - excluded generated Tailwind output and the Tailwind input stylesheet from Biome checks
+  - disabled Biome rules that were a poor fit for the current React/canvas patterns:
+    - `useExhaustiveDependencies`
+    - `noStaticElementInteractions`
+    - `useKeyWithClickEvents`
+    - `noAccumulatingSpread`
+  - removed the old legacy lint/format config files and compatibility tsconfig
+  - updated npm scripts to:
+    - `npm run lint`
+    - `npm run lint:fix`
+    - `npm run format`
+  - updated GitHub workflows to use npm and run Biome instead of the old Yarn/legacy lint flow
+  - applied one repository-wide Biome write pass and fixed the remaining manual diagnostics so `biome check` is now clean
+- Added `lefthook` as the repo hook manager and configured [lefthook.yml](/home/davidfencl/Documents/Work/depthai-visualizer-lib/lefthook.yml) with a `pre-commit` hook that runs:
+  - `npx biome check --write --no-errors-on-unmatched --files-ignore-unknown=true {staged_files}`
+  - with `stage_fixed: true` so rewritten staged files are re-added automatically
+- Added `prepare: "lefthook install"` to `package.json` so hook installation happens automatically on `npm install`
+- Removed the dead Jest toolchain from package metadata:
+  - `jest`
+  - `jest-environment-jsdom`
+  - `@types/jest`
+- Regenerated `package-lock.json` without the Jest dependency tree. The removal required `npm install --ignore-scripts` in the sandbox because the repo-level `prepare` hook tries to rewrite `.git/hooks`.
+- Pruned additional dead package/tooling dependencies that are no longer referenced by source, scripts, CI, or build config:
+  - `@actions/core`
+  - `@actions/exec`
+  - `@actions/tool-cache`
+  - `@octokit/rest`
+  - `@babel/plugin-proposal-explicit-resource-management`
+  - `@types/surma__rollup-plugin-off-main-thread`
+  - `@wasm-tool/rollup-plugin-rust`
+  - `babel-plugin-transform-import-meta`
+  - `cross-env`
+  - `depcheck`
+  - `license-checker`
+  - `rimraf`
+  - `semver`
+  - `ts-unused-exports`
+  - `webpack`
+  - `webpack-cli`
+  - `webpack-dev-server`
+  - `webpack-hot-middleware`
+- Regenerated `package-lock.json` after that prune with `npm install --ignore-scripts` to avoid sandbox-only `prepare` hook failures while still pruning the resolved tree correctly.
+- Raised the declared Node.js engine floor in `package.json` from `>=16` to `>=22`.
+- Aligned the pull-request GitHub workflow to Node 22 explicitly by updating `.github/workflows/pull-request.yml` to `actions/setup-node@v4` with `node-version: "22"`.
+- Bumped package version metadata from `3.1.14` to `4.0.0-rc.1` in:
+  - `package.json`
+  - `package-lock.json`
+- Refreshed a conservative same-major dependency slice across runtime and build tooling, including current-version updates for:
+  - `@bufbuild/protobuf`
+  - `@luxonis/ui-components`
+  - `@luxonis/ui-utils`
+  - `comlink`
+  - legacy formatter bridge packages
+  - `react-icons`
+  - `react-syntax-highlighter`
+  - `uuidv7`
+  - `react` / `react-dom`
+  - `@babel/core`
+  - `@babel/plugin-proposal-explicit-resource-management`
+  - `@babel/preset-env`
+  - `@babel/preset-typescript`
+  - `@tailwindcss/cli`
+  - `@types/dom-webcodecs`
+  - `@types/react`
+  - `@webgpu/types`
+  - `babel-plugin-transform-import-meta`
+  - legacy lint integration packages
+  - `rollup`
+  - `rollup-plugin-string-import`
+  - `semver`
+  - `tailwindcss`
+  - `ts-proto`
+  - `tslib`
+  - `webpack`
+  - `webpack-hot-middleware`
+- The refreshed `@types/dom-webcodecs` package exposed a compile-time MJPEG typing regression.
+- Fixed that by:
+  - making `src/messaging/deserialization/video/mjpeg.ts` use an explicit `ImageDecoder` constructor lookup instead of relying on an ambient global symbol declaration
+  - making the MJPEG payload shape explicit across native and i420 branches
+  - correcting `src/utils/compatibility.ts` so `ensureWebCodecsSupported()` actually checks the real WebCodecs constructor on `globalThis`
+- Removed the last direct MUI dependency from source code by replacing `useTheme()` in `src/panels/pointcloud/PointCloudCanvasRenderer.tsx` with a local browser theme-mode hook:
+  - added `src/utils/use-theme-mode.ts`
+  - the point-cloud renderer now tracks theme changes through common DOM theme attributes/classes and `prefers-color-scheme`
+- Removed direct package/runtime dependency declarations for:
+  - `@mui/icons-material`
+  - `@mui/material`
+  - `@mui/system`
+  - `@emotion/react`
+  - `@emotion/styled`
+- Removed the corresponding stale Rollup externals from `rollup.config.js`.
+- Updated `three` from `0.156.1` to `0.184.0`.
+- Kept explicit `@types/three`, but updated it to the matching `0.184.0` line after verifying that the current TypeScript/module-resolution setup still needs it for clean type resolution of both `three` and `three/examples/jsm/controls/OrbitControls.js`.
+- Relaxed a few floating-point fixture tolerances to match actual emitted values in runnable execution.
+- Expanded Node-safe fixture coverage with:
+  - uncolored point clouds
+  - spatial image detections
+- Recorded the browser-only runtime constraint in `AGENTS.md` and `REFACTOR_PLAN.md` so future agents do not overfit validation to Node.
+- Added a browser-runtime fixture suite and entrypoint for worker-backed decoder paths:
+  - `src/messaging/browser-decoder-fixtures.ts`
+  - `src/browser-decoder-fixtures-entry.ts`
+  - `scripts/browser-decoder-fixtures.html`
+- Added browser fixture coverage for:
+  - raw depth preview plus sync point-cloud artifact
+  - RGBD depth preview plus colored point-cloud emission
+- Replaced one-worker-per-topic decode fanout with a bounded shared decoder worker pool in `src/messaging/message-handler.ts`.
+- Switched decode worker dispatch to explicit transferable buffer handoff instead of plain Comlink value passing for the message payload.
+- Removed per-message `ConfigStore` serialization across Comlink by pushing connection config into decoder workers once during worker initialization.
+- Reduced repeated decode-settings parsing by caching raw `localStorage` values and only re-parsing when same-tab values actually change.
+- Removed O(n) point-cloud sync cleanup in `src/utils/poitcloud-sync.ts` by replacing repeated array shifting with indexed queue compaction.
+- Removed repeated `localStorage` parsing on the legacy point-cloud conversion path by caching neural camera intrinsics in `src/connection/foxglove-connection.ts`.
+- Removed repeated `localStorage` reads from `DepthToPointcloudWorkerPool` batch dispatch and replaced processed-frame queue shifting with indexed compaction in `src/messaging/deserialization/pointcloud/poitcloudPoolManager.ts`.
+- Switched the point-cloud worker contract to explicit transferable typed-array handoff on both input and output in:
+  - `src/messaging/deserialization/pointcloud/pointcloudFromDepth.worker.ts`
+  - `src/messaging/deserialization/pointcloud/poitcloudPoolManager.ts`
+  - `src/messaging/deserialization/video/rgbd-to-pointcloud.ts`
+- Added local helper modules:
+  - `src/utils/async.ts`
+  - `src/utils/time.ts`
+- Updated `src/connection/foxglove-connection.ts` to use local debounce/time/object-size helpers and local message-event typing instead of Foxglove helper imports.
+- Updated `src/utils/frame-store.ts` to store local `VisualizerMessageEvent` values instead of Foxglove Studio event types.
+- Added `src/utils/comlink-wrap.ts` as a local Comlink worker wrapper.
+- Updated:
+  - `src/messaging/message-handler.ts`
+  - `src/messaging/deserialization.worker.ts`
+  - `src/messaging/deserialization/pointcloud/poitcloudPoolManager.ts`
+  to use the local Comlink wrapper and local `VisualizerMessageEvent` typing instead of Foxglove worker/event helpers.
+- Added local `fromMicros()` to `src/utils/time.ts`.
+- Updated:
+  - `src/messaging/deserialization/video/h264.ts`
+  - `src/messaging/deserialization/video/h265.ts`
+  to use the local time helper instead of `@foxglove/rostime`.
+- Added `src/utils/player-types.ts` as a local player-state/type surface for the internal connection/context layer.
+- Updated:
+  - `src/connection/foxglove-connection.ts`
+  - `src/connection/connection.ts`
+  - `src/context/VisualizerContext.tsx`
+  - `src/context/MessagePipelineProvider.tsx`
+  to use local player types internally, with explicit adaptation at the Foxglove `MessagePipelineProvider` boundary.
+- Replaced the Foxglove `MessagePipeline` implementation with a Luxonis-owned local pipeline store and hooks:
+  - `src/context/message-pipeline-types.ts`
+  - `src/context/message-pipeline-order-tracker.ts`
+  - `src/context/message-pipeline-store.ts`
+  - `src/context/pause-frame.ts`
+- Updated `src/context/MessagePipelineProvider.tsx` to use the local store while still exposing a Foxglove-compatible context shape to legacy panels through `ContextInternal`.
+- Updated `src/context/VisualizerContext.tsx` and `src/messaging/utils.ts` to use the local pipeline hooks instead of Foxglove `useMessagePipeline` / `useMessageReducer`.
+- Added local panel-shell components:
+  - `src/components/EmptyState.tsx`
+  - `src/components/ErrorBoundary.tsx`
+  - `src/components/RemountOnValueChange.tsx`
+- Updated `src/components/Panel.tsx` to use those local components instead of Foxglove UI helpers.
+- Updated `src/components/PanelLayout.tsx` to use a local flex layout instead of Foxglove `Stack`.
+- Updated `src/context/VisualizerContext.tsx` to use the local `ErrorBoundary`.
+- Added local panel/runtime boundary helpers:
+  - `src/panels/panel-renderer.ts`
+  - `src/panels/pointcloud-camera.ts`
+- Updated `src/components/Panel.tsx`, `src/panels/ImagePanel.tsx`, and `src/panels/PointCloudPanel.tsx` so public panel props no longer import the Foxglove `Renderer` type.
+- Updated `src/panels/PointCloudPanel.tsx` to use local point-cloud camera defaults instead of importing them from Foxglove `ThreeDeeRender`.
+- Updated `src/context/MessagePipelineProvider.tsx` to use local player/problem types only; the remaining Foxglove dependency there is now just `ContextInternal`.
+- Added a local browser-only image rendering stack under `src/panels/image/`:
+  - `raw-image-decoder.ts`
+  - `raw-image-decoder.worker.ts`
+  - `worker-image-decoder.ts`
+  - `annotation-overlay.ts`
+  - `ImageCanvasRenderer.tsx`
+- Replaced the Foxglove `Image` panel usage in `src/panels/ImagePanel.tsx` with a local canvas-based image host.
+- Added a browser-native encoded-video presentation fast path:
+  - `src/messaging/deserialization/video/h264.ts`
+  - `src/messaging/deserialization/video/h265.ts`
+  - `src/messaging/message-event.ts`
+  - `src/panels/image/ImageCanvasRenderer.tsx`
+- H.264/H.265 decode workers now attach a transferred `ImageBitmap` to emitted `foxglove.RawImage` events for normal image topics while keeping the raw-image payload fields intact.
+- The local image panel now renders those transferred bitmaps directly instead of sending encoded-video-origin raw images through the second worker-based RGBA decode step.
+- Bitmap lifetime is now explicitly closed on replacement and unmount in `ImageCanvasRenderer.tsx` to avoid leaks during high-rate streams.
+- Encoded H.264/H.265 worker callbacks now transfer the raw payload `ArrayBuffer` alongside any attached `ImageBitmap` instead of structured-cloning the raw image bytes back to the main thread.
+- `src/connection/foxglove-connection.ts` now reuses decoder-supplied `event.sizeInBytes` when present instead of re-running `estimateObjectSize(event.message)` on every decoded frame before enqueueing it into the local pipeline.
+- Removed the legacy per-player-state renderDone/pauseFrame synchronization gate from:
+  - `src/context/MessagePipelineProvider.tsx`
+  - `src/context/message-pipeline-store.ts`
+- The local pipeline now dispatches player-state updates directly instead of creating a timeout/promise handshake for every frame even though no current code path uses `pauseFrame()`.
+- Added `stripRenderableBitmapFromEvent()` in `src/messaging/message-event.ts`.
+- `src/utils/frame-store.ts` and `src/context/message-pipeline-store.ts` now strip `renderableBitmap` before storing decoded image events in long-lived caches.
+- Live subscribers still receive the browser-native bitmap fast path on current messages, but main-thread caches no longer retain `ImageBitmap` objects across frames.
+- Added `createCachedEventSnapshot()` in `src/messaging/message-event.ts`.
+- `FrameStore` and the pipeline `lastMessageEventByTopic` cache now also replace `foxglove.RawImage.message.data` with an empty `Uint8Array` in cached snapshots, so old video-frame buffers are not retained between updates.
+- Browser trace analysis of `trace1.json` showed two renderer main-thread spikes about 5 seconds apart. The spikes resolved to repeated `clearInterval` / `setInterval` churn and React work around the local panel metrics hooks.
+- Updated:
+  - `src/components/measure-event-loop-delay.tsx`
+  - `src/components/measure-render-delay.tsx`
+- Both hooks now keep one stable interval instead of recreating timers on every state update.
+- `createRenderDelaySampler()` also no longer allocates and clears a growing `frameDelays` array every frame; it now tracks running count/sum in refs.
+- Browser trace analysis of `trace2.json` still showed periodic main-thread spikes and repeated timer/layout activity in the toolbar/metrics path after the first hook cleanup.
+- Added:
+  - `src/components/shared-interval.ts`
+  - `src/components/use-element-width.ts`
+- Updated:
+  - `src/components/PanelToolbar.tsx`
+  - `src/components/measure-event-loop-delay.tsx`
+- Panel toolbar metrics and connection metric polling now share one page-level interval instead of creating per-panel timers.
+- Frontend delay sampling is now a shared `useSyncExternalStore`-backed sampler, which restores the FE delay readout without reintroducing timer churn per panel.
+- Toolbar compact/full and resolution behavior now use `ResizeObserver` width tracking instead of reading `offsetWidth`/`clientWidth` inside render-driven effects.
+- Browser trace analysis of `trace3.json` still showed the same periodic main-thread `FunctionCall` spikes at the same bundle callsite as `trace2.json`, so the underlying hitch was unchanged by the toolbar polling cleanup.
+- The active working tree also contained an uncommitted `requestAnimationFrame` rewrite of `FoxgloveConnection.emitState()`. That change was not part of any checkpoint and was removed from the runtime path before further hitch analysis.
+- Updated `src/components/measure-event-loop-delay.tsx` again so the FE delay readout now samples from the shared 500ms UI tick directly, instead of relying on the earlier `useSyncExternalStore` sampler variant.
+- Removed the legacy `MessageOrderTracker` pipeline layer entirely:
+  - deleted `src/context/message-pipeline-order-tracker.ts`
+  - simplified `src/context/MessagePipelineProvider.tsx` so player-state updates are forwarded directly into the local pipeline store without per-batch message-order/drift scans or warning timers
+- Clamped the frontend delay metric to non-negative values in `src/components/measure-event-loop-delay.tsx` so scheduling jitter no longer reports impossible negative delays.
+- Removed the Frontend Delay metric from `src/components/PanelToolbar.tsx` for now so it no longer adds diagnostic noise while the H.264 hitch investigation continues.
+- Reduced per-frame main-thread allocation pressure in the player-state and cache path:
+  - `src/messaging/message-event.ts` now returns original event/message references when no `renderableBitmap` stripping is needed, instead of cloning every cached event unconditionally
+  - cached raw-image events no longer allocate synthetic empty `Uint8Array` payloads
+  - `src/connection/foxglove-connection.ts` now caches topic definitions incrementally with `trackTopic()` instead of rebuilding `Object.values(this.topics)` on every emit
+  - `FoxgloveConnection.emitState()` now reuses shared empty `progress`, `topicStats`, and `datatypes` containers instead of allocating fresh ones on every player-state update
+- Narrowed the live frame payload that flows through the central pipeline store:
+  - `src/context/MessagePipelineProvider.tsx` now strips live `activeData.messages` out of the public `PlayerState` and forwards those events separately to the store
+  - `src/context/message-pipeline-store.ts` now builds `messageEventsBySubscriberId` from that separate internal message payload instead of reading live frame arrays back off public `playerState`
+- Result: panels still receive current frame events through `messageEventsBySubscriberId`, but the broader `playerState` object no longer carries every decoded frame buffer through the whole Zustand/React surface.
+- Reworked the image panel hot path so live image frames no longer drive React state updates:
+  - `src/context/MessagePipelineProvider.tsx` now exposes the local store API
+  - `src/messaging/utils.ts` now provides `useMessageSubscription()` for imperative subscriber callbacks without rerendering the component on every message batch
+  - `src/panels/image/ImageCanvasRenderer.tsx` now handles image-frame and annotation messages through refs plus direct canvas scheduling instead of `useMessageReducer()` state churn
+  - decoded images/bitmaps are stored in refs and drawn via scheduled canvas work, while React state is only used for coarse UI state like resize and “waiting for frames”
+- Verified that `renderDelay` is dead in the current UI:
+  - `ImagePanel` and `PointCloudPanel` computed it via `createRenderDelaySampler()`
+  - `Panel` threaded it into `PanelToolbar`
+  - `PanelToolbar` typed it but did not read it
+- Removed that dead periodic rerender path:
+  - deleted `src/components/measure-render-delay.tsx`
+  - removed `createRenderDelaySampler()` usage from `src/panels/ImagePanel.tsx` and `src/panels/PointCloudPanel.tsx`
+  - removed `renderDelay` from `src/components/Panel.tsx` and `src/components/PanelToolbar.tsx`
+- Reduced `PanelToolbar` / `PanelToolbarMetrics` shared metrics tick interval from `500ms` to `1000ms` as a low-risk reduction in always-on toolbar churn while preserving visible stats updates.
+- The new image host:
+  - subscribes directly to `foxglove.RawImage` and `foxglove.ImageAnnotations` through the local message pipeline
+  - decodes browser image frames in a dedicated worker
+  - draws images into a canvas with local annotation overlay rendering
+  - preserves panel click/cursor callbacks and panel render metrics hooks
+- Fixed a render-loop regression in `src/panels/image/ImageCanvasRenderer.tsx` by memoizing the `topics` array passed into `useMessageReducer`, so the message-pipeline subscription effect no longer re-subscribes on every render.
+- Fixed a second render-loop regression in `src/panels/image/ImageCanvasRenderer.tsx` by removing unstable callback props from effect dependencies on the draw/registration path. The image host now keeps the latest callbacks in refs instead of treating parent callback identity changes as redraw triggers.
+- Updated the local image host visuals to use a white background and lighter empty-state text.
+- Fixed `src/panels/image/annotation-overlay.ts` so annotation point types are rendered as discrete points instead of being treated as connected paths. Line list, line strip, and line loop are now handled explicitly by schema type.
+- Fixed image render FPS reporting in `src/panels/image/ImageCanvasRenderer.tsx` so `frameRenderedEvent` is emitted only when a new decoded image revision is presented, not on annotation-only redraws.
+- Updated `AGENTS.md` and `REFACTOR_PLAN.md` to track a real browser-runtime issue: periodic video hitching roughly every 5 seconds on encoded H.264/H.265 streams, currently suspected to involve the encoded-video decode path until profiling proves otherwise.
+- Updated `src/messaging/deserialization/video/h264.ts` and `src/messaging/deserialization/video/h265.ts` to stop marking every `EncodedVideoChunk` as a keyframe when the source is `EncodedFrame`; `I` frames now map to `"key"` and `P/B` frames map to `"delta"`.
+- Replaced the previous hard decoder reset on large decode backlog with bounded frame dropping. When the `VideoDecoder.decodeQueueSize` crosses the new threshold, incoming encoded frames are dropped instead of resetting the decoder and forcing a keyframe reacquire cycle.
+- Kept the fallback `ImgFrame` bitstream path conservative by still treating it as keyframe-only input because that message type does not expose explicit frame-type metadata.
+- Updated the encoded-video output path to use a latest-frame policy while expensive `VideoFrame.copyTo()` / repack work is in progress. H.264/H.265 now serialize output-frame conversion per topic and drop superseded decoded frames instead of allowing async output processing to pile up.
+- Replaced `estimateObjectSize()` on the H.264/H.265 decoded image hot path with direct `Uint8Array.byteLength` accounting.
+- Added a native `NV12` fast path for regular encoded H.264/H.265 image topics. When `VideoDecoder` outputs uncropped `NV12`, the pipeline now emits that buffer directly as `foxglove.RawImage` with stride metadata instead of repacking it to `yuv420p`.
+- Kept RGBD encoded color extraction on the older I420-compatible path by explicitly requesting `outputMode: "i420"` there, so point-cloud generation semantics remain unchanged while normal image streams get the lighter decode path.
+- Updated `src/messaging/deserialization/video/h264.ts` and `src/messaging/deserialization/video/h265.ts` so the normal `outputMode: "native"` path no longer calls `VideoFrame.copyTo()` just to populate `foxglove.RawImage.data`.
+- Regular encoded H.264/H.265 image topics now transfer only `ImageBitmap` plus image metadata to the main thread, while preserving raw-plane extraction on the explicit RGBD `outputMode: "i420"` path.
+- Decoder events on that native path now keep `sizeInBytes` from `VideoFrame.allocationSize()` so throughput metrics still reflect decoded frame weight even though the live raw-image payload is no longer materialized.
+- Analyzed the new 20-second `trace5.json` capture from the simpler Visualizer app with only one H.264 stream active.
+- Trace finding: the hitch still reproduces without consuming-app complexity, and the renderer main thread no longer shows a single 5-second JS spike. Instead, `raw-image-decoder.worker` is still doing roughly 3-5 ms of `HandlePostMessage` / `FunctionCall` work on nearly every frame.
+- That worker activity should have disappeared on the `ImageBitmap` fast path, so the remaining likely bug was the worker-to-main-thread callback transport rather than decode itself.
+- Replaced the decoder worker callback delivery path with an explicit `MessagePort` transfer channel:
+  - `src/messaging/deserialization.worker.ts`
+  - `src/messaging/message-handler.ts`
+  - `src/messaging/message-event.ts`
+- Decoder workers now post decoded events back to the main thread through a dedicated port with explicit transferables for `Uint8Array` payload buffers and `ImageBitmap`.
+- This removes reliance on the previous proxied Comlink callback for decoded-frame delivery, which was the most likely place `renderableBitmap` was being lost before the image panel subscription saw the live message.
+- Analyzed `trace6.json` after the explicit `MessagePort` transport change.
+- Trace finding: the hitch still reproduces, and `raw-image-decoder.worker` remains hot on nearly every H.264 frame. The expensive fallback path therefore still runs in the image panel even after the worker transport change.
+- Added targeted encoded-image diagnostics to log bitmap presence at each hop:
+  - `src/messaging/encoded-image-diagnostics.ts`
+- Extended encoded-image diagnostics so `foxglove.RawImage` events can carry:
+  - `renderableBitmapExpected`
+  - `renderableBitmapModeUsed`
+  - `decodePathSource`
+- Annotated decode outputs in `src/messaging/decode-core.ts` and added `src/messaging/decode-path-diagnostics.ts` so live `foxglove.RawImage` events report which deserialization branch produced them.
+- Browser console diagnostics showed the topic labeled `H.264 Stream` is actually arriving through `encodedFrame:JPEG`, with no `renderableBitmap` attached and no H.264/H.265 output-mode metadata present.
+- Updated `src/messaging/deserialization/video/rgbd-to-pointcloud.ts` so encoded RGBD color extraction uses a synthetic decoder topic key (`::rgbd-color-extract`) and explicitly requests planar output for JPEG as well as H.264/H.265.
+- Reworked `src/messaging/deserialization/video/mjpeg.ts` to support two output modes:
+  - default `native` mode now emits transferred `ImageBitmap` plus metadata for normal image topics
+  - explicit `i420` mode preserves the old planar `yuv420p` extraction path for RGBD point-cloud color input
+- MJPEG decoded events now use transferables for both raw buffers and `ImageBitmap`, matching the encoded H.264/H.265 fast-path contract.
+- Investigated all periodic timers reachable from `lib/src` during normal streaming.
+- Confirmed the only app-owned repeating timers on the renderer main thread were:
+  - `src/connection/foxglove-connection.ts` via eager `RateLimiter` construction
+  - `src/messaging/rate-limiter.ts` at `1000ms`
+  - `src/messaging/event-loop-delay-sampler.ts` at `500ms`
+- Confirmed `PanelToolbar` metrics removal does not affect that path because `FoxgloveConnection` instantiated the polling rate limiter before any panel-specific UI logic ran.
+- Confirmed the current `RateLimiter` implementation was effectively inert:
+  - `src/connection/foxglove-connection.ts` kept `rateLimitModCoefficient` at `1` in normal runtime
+  - `src/messaging/rate-limiter.ts` never raised `isFlagUp` from its initial `false` state, so the modulo coefficient callback could not transition from `1` to a throttled value
+- Added a local raw-image pixel decoder module for the internal image panel:
+  - `src/panels/image/raw-image-pixel-decoders.ts`
+- Updated `src/panels/image/raw-image-decoder.ts` to use the local decoder module instead of `@foxglove/den/image`.
+- Result: `lib/src` no longer imports `@foxglove/den/image`; the remaining `@foxglove/*` imports are now concentrated in the transport/context shell and the legacy point-cloud renderer boundary.
+- Changed the Phase 1 plan direction for localization/bundle size:
+  - removed the `PanelLayout` call into Foxglove `initI18n()`
+  - added local no-op stubs for `i18next`, `react-i18next`, and `i18next-browser-languagedetector`
+  - wired both TypeScript path resolution and Rollup aliasing to those stubs
+- Result: the library no longer bundles real localization runtime packages; UI text on surviving Foxglove-derived surfaces may now fall back to raw translation keys, which is acceptable for this refactor direction.
+- Removed the last direct import of the Foxglove English translation table from the reachable renderer path:
+  - `packages/studio-base/src/panels/ThreeDeeRender/t3D.ts` now accepts a plain string key instead of importing `@foxglove/studio-base/i18n/en` for `keyof typeof threeDee`
+- Fixed `lib/protobuf-gen.sh` so the `protobufName` post-processing step is idempotent:
+  - existing `export const protobufName = ...` lines are deleted before the name is appended
+  - cleaned the currently generated protobuf modules back to one `protobufName` export each
+- Result: `yarn fixtures:decode` and `yarn build` are both usable again after the earlier duplicate-export corruption.
+- Removed the remaining inert rate-limiter logic from `src/connection/foxglove-connection.ts`:
+  - deleted `rateLimitModCoefficient`
+  - deleted `rateLimitCounter`
+  - removed the dominant-message skip branch from `onMessagePacket()`
+  - removed `isMessageTypeDominant()`
+- Replaced the imported Foxglove `CurrentLayoutProvider` in `src/context/VisualizerContext.tsx` with a local minimal provider:
+  - added `src/context/MinimalCurrentLayoutProvider.tsx`
+  - removed the `@foxglove/studio-base/providers/CurrentLayoutProvider` runtime import from the library shell
+  - removed `EventsProvider` from the reachable Visualizer shell
+- Result: one heavier Foxglove provider implementation is no longer in the library’s live context path; the current point-cloud/Image panel shell still validates against the slimmer local layout context.
+- Updated `lib/rollup.config.js` so external dependency handling matches package subpaths instead of only exact package ids.
+- Result: the previous unresolved-dependency warning class is gone from `yarn build`; those runtime deps now resolve as intentional externals instead of noisy unresolved imports.
+- Added a targeted Rollup `onwarn` filter for ignored `"use client"` module directives.
+- Result: `yarn build` output is now reduced to the remaining actionable warning classes rather than hundreds of inert third-party module-directive warnings.
+- Result: the connection hot path no longer carries dead per-packet throttling bookkeeping or skip logic that never activated in real runtime.
+- Removed the dead Foxglove font CSS imports from `packages/studio-base/src/components/CssBaseline.tsx`, which eliminates the unresolved `@foxglove/studio-base/styles/assets/*.woff2` warning class from `yarn build`.
+- Converted MUI/theme-only imports in:
+  - `packages/theme/src/palette.ts`
+  - `packages/theme/src/createMuiTheme.ts`
+  - `packages/theme/src/typography.ts`
+  to `import type`, which removes the previous Rollup `Missing exports` / `Unused external imports` warnings caused by treating types as runtime imports.
+- Added explicit dependency declarations in `lib/package.json` for modules that the current build reaches transitively through Foxglove/Luxonis UI layers, so the package no longer relies on those as accidental undeclared externals.
+- Added `preventAssignment: true` to the Rollup `replace()` plugin config to clear that plugin warning.
+- Removed the eager `RateLimiter` instantiation from `src/connection/foxglove-connection.ts`.
+- Deleted the now-unused timer-backed modules:
+  - `src/messaging/rate-limiter.ts`
+  - `src/messaging/event-loop-delay-sampler.ts`
+- Post-change timer inventory for `setInterval()` in `lib/src` is now limited to:
+  - `src/components/shared-interval.ts`, which is tied to mounted UI metrics consumers rather than connection startup
+  - `src/connection/webrtc/comms-proxy.ts`, which is a 5-minute token refresh path specific to WebRTC comms
+- Analyzed `trace9.json` after the rate-limiter removal on a one-panel H.264 run.
+- Trace finding: the old timer hypothesis is no longer the main issue.
+  - `TimerFire` on `CrRendererMain` is now small overall and no longer explains the visible hitch pattern.
+  - `raw-image-decoder.worker` is effectively idle, so the previous fallback decode path is no longer the dominant cost either.
+  - The remaining hot path is live `MessagePort` delivery into:
+    - `src/messaging/message-handler.ts`
+    - `src/connection/foxglove-connection.ts`
+    - `src/context/MessagePipelineProvider.tsx`
+    - `src/context/message-pipeline-store.ts`
+    - `src/messaging/utils.ts`
+    - `src/panels/image/ImageCanvasRenderer.tsx`
+  - The periodic spikes visible in the trace line up more with GC/allocation cleanup than with a repeating app-owned timer callback.
+- Added a live message-subscription controller to `src/context/MessagePipelineProvider.tsx`.
+- Updated `src/messaging/utils.ts` so `useMessageSubscription()` now uses that live controller instead of subscribing through the Zustand `messageEventsBySubscriberId` path.
+- Result: `ImageCanvasRenderer` now receives current-frame image/annotation batches directly from the listener path without registering as a store subscriber and without forcing per-frame `messageEventsBySubscriberId` churn for the image panel.
+- Preserved mount-time preload behavior by replaying cached last-topic events from the pipeline store when a live subscriber attaches.
+- Removed temporary encoded-image diagnostics from the hot path:
+  - `src/messaging/message-handler.ts`
+  - `src/messaging/deserialization.worker.ts`
+  - `src/panels/image/ImageCanvasRenderer.tsx`
+  - deleted `src/messaging/encoded-image-diagnostics.ts`
+- Added direct connection-owned live frame dispatch in `src/connection/foxglove-connection.ts` and gated `messageEvents` publication in `src/context/MessagePipelineProvider.tsx` so one-panel live image streaming can bypass per-frame `PlayerState`/store churn when no store-based message subscribers are present.
+- Updated `src/panels/image/ImageCanvasRenderer.tsx` to remove a few remaining per-frame React/annotation allocations from the hot draw path.
+- Analyzed `trace13.json` after the pipeline/store bypass work.
+- Trace finding: renderer-main costs dropped materially and the old timer theory is effectively dead.
+  - `HandlePostMessage` and image-panel callback costs both fell again versus `trace12.json`.
+  - No meaningful timer, major GC, or layout/paint spikes remained on `CrRendererMain`.
+  - The visible symptom therefore no longer lined up with a renderer-main periodic timer stall inside `lib/`.
+- Broadened the investigation from renderer-main timers to end-to-end live frame cadence.
+- Updated `src/messaging/deserialization.worker.ts` so `handleMessageToDecode()` resolves when decode work actually completes.
+- Updated `src/messaging/message-handler.ts` with a per-topic latest-frame dispatch policy for image messages:
+  - only one image decode per topic may be in flight
+  - a newer pending image packet replaces an older unsent one while the worker is busy
+  - non-image messages keep the existing direct dispatch behavior
+- Analyzed `trace15.json` after the worker-dispatch coalescing change.
+- Trace finding: renderer-main stayed in the improved low-cost state, but dedicated worker activity still looked like bursty encoded-frame catch-up rather than a new main-thread hotspot.
+  - `HandlePostMessage` / `FunctionCall` on `CrRendererMain` stayed below the earlier `trace12.json` totals.
+  - The remaining heavy work clustered on dedicated/background decode threads.
+- Reduced `VideoDecoder` backlog depth for live encoded streams in:
+  - `src/messaging/deserialization/video/h264.ts`
+  - `src/messaging/deserialization/video/h265.ts`
+- H.264/H.265 now start dropping earlier when `decodeQueueSize` backs up, reducing the chance that WebCodecs accumulates a long burst of decoded frames before the latest-frame policy can discard stale output.
+- Reviewed the image/annotation synchronization path after the continued hitch reports.
+- Finding: there is no local image-panel logic in `lib/` that waits for a matching annotation timestamp before presenting an image frame.
+  - `src/panels/image/ImageCanvasRenderer.tsx` always renders the latest image immediately and overlays whichever annotation payloads are currently cached by topic.
+  - The only explicit wait helper in the local pipeline is `src/context/pause-frame.ts`, but the local message pipeline store exposes a no-op `pauseFrame()` and the image panel does not use it.
+  - The timestamp-matching sync utility in `src/utils/poitcloud-sync.ts` is specific to point-cloud/RGBD flows, not plain H.264 image presentation.
+- Tightened annotation consumption in `src/panels/image/ImageCanvasRenderer.tsx` so the panel subscribes only to currently enabled annotation topics instead of subscribing to all annotation topics up front.
+- Result: disabled extra annotation topics no longer deliver messages or schedule redraws for the image panel, which removes one more nonessential per-frame/per-annotation path during normal streaming.
+- Added `src/utils/runtime-config.ts` as a Luxonis-owned shared runtime-config surface for browser-only config values read from `localStorage`.
+- Moved duplicated runtime parsing/caching logic into that helper for:
+  - `neuralCameraIntrinsics`
+  - `stereoDepthMaxValue`
+  - `perspective`
+- Updated these callers to use the shared runtime-config helper instead of reimplementing their own `localStorage` parsing and cache state:
+  - `src/messaging/message-handler.ts`
+  - `src/connection/foxglove-connection.ts`
+  - `src/messaging/deserialization/pointcloud/poitcloudPoolManager.ts`
+  - `src/panels/PointCloudPanel.tsx`
+- Result: Phase 1 now has a single internal place for the active browser runtime decode/render settings that were previously scattered across multiple subsystems.
+- Replaced the old class-based `ConfigStore` singleton in `src/utils/config-store.ts` with a plain package-local module API:
+  - config types/defaults
+  - `normalizeConnectionConfig()`
+  - `createConnectionConfigState()`
+- Updated these callers to use the plain config API instead of the mutable singleton class:
+  - `src/connection/connection.ts`
+  - `src/messaging/message-handler.ts`
+  - `src/messaging/deserialization.worker.ts`
+  - `src/messaging/decode-core.ts`
+  - `src/messaging/decoder-harness.ts`
+- Result: the remaining connection-config path is now explicit data/functions rather than a hidden class singleton shared across the package.
+- Added `VisualizerRawImage` to `src/messaging/message-event.ts` as a local visualizer-owned raw-image shape for internal decode/render flows.
+- Kept `ExtendedRawImage` as a local extension of that new type, so existing image presentation behavior and extra fields stay unchanged.
+- Updated internal raw-image producers/consumers to use the local type instead of importing Foxglove `RawImage`:
+  - `src/messaging/deserialization/video/mono.ts`
+  - `src/messaging/deserialization/video/depth.ts`
+  - `src/messaging/deserialization/video/rgbd-to-pointcloud.ts`
+  - `src/messaging/deserialization/video/h264.ts`
+  - `src/messaging/deserialization/video/h265.ts`
+- Result: the internal raw-image path no longer depends on Foxglove schema types just to describe local message objects.
+- Added `VisualizerPointCloud` and related local point/pose helper types to `src/messaging/message-event.ts`.
+- Updated internal point-cloud producers/aliases to use the local visualizer-owned point-cloud shape instead of importing Foxglove `PointCloud` as an internal type:
+  - `src/messaging/deserialization/pointcloud/point-cloud.ts`
+  - `src/messaging/deserialization/video/depth.ts`
+  - `src/messaging/deserialization/video/depth-to-pointcloud.ts`
+- Result: the internal point-cloud decode path no longer depends on Foxglove schema types just to describe local point-cloud message objects.
+- Added local visualizer-owned annotation shape types to `src/messaging/message-event.ts`:
+  - `VisualizerImageAnnotations`
+  - `VisualizerPointsAnnotation`
+  - `VisualizerTextAnnotation`
+  - `VisualizerCircleAnnotation`
+  - `VisualizerColor`
+- Updated internal annotation producers/consumers to use those local shapes instead of Foxglove `ImageAnnotations` object types:
+  - `src/messaging/deserialization/detections/detection.ts`
+  - `src/messaging/deserialization/detections/custom.ts`
+  - `src/panels/image/ImageCanvasRenderer.tsx`
+  - `src/panels/image/annotation-overlay.ts`
+- Kept `PointsAnnotationType` enum imports for now so emitted/rendered semantics remain unchanged while removing the heavier object-shape coupling.
+- Result: the internal annotation path no longer depends on Foxglove schema object types just to describe local annotation messages.
+- Added `src/messaging/schema-constants.ts` for local schema-compatible constants used by emitted message objects.
+- Moved point-cloud field datatype constants off the Foxglove schema enum and onto local `VisualizerNumericType` constants in:
+  - `src/messaging/deserialization/pointcloud/point-cloud.ts`
+  - `src/messaging/deserialization/video/depth-to-pointcloud.ts`
+  - `src/messaging/deserialization/video/rgbd-to-pointcloud.ts`
+- Result: internal point-cloud message construction no longer imports Foxglove `NumericType` just to assign field datatype numbers.
+- Extended `src/messaging/schema-constants.ts` with a local `VisualizerPointsAnnotationType` compatibility enum using the installed Foxglove schema values:
+  - `UNKNOWN = 0`
+  - `POINTS = 1`
+  - `LINE_LOOP = 2`
+  - `LINE_STRIP = 3`
+  - `LINE_LIST = 4`
+- Replaced the remaining internal `PointsAnnotationType` imports in:
+  - `src/messaging/deserialization/detections/detection.ts`
+  - `src/messaging/deserialization/detections/custom.ts`
+  - `src/panels/image/annotation-overlay.ts`
+  - `src/messaging/decoder-fixtures.ts`
+- Result: internal annotation production, rendering, and fixture assertions no longer depend on the Foxglove schema enum directly.
+
+## Hitch Investigation Summary
+
+- The original renderer-main timer hypothesis has been substantially mitigated and is not the best restart point for future debugging.
+- Confirmed app-owned repeating timers reachable during normal streaming were:
+  - `src/messaging/rate-limiter.ts`
+  - `src/messaging/event-loop-delay-sampler.ts`
+  - `src/components/shared-interval.ts`
+  - `src/connection/webrtc/comms-proxy.ts`
+- Removed the eager connection-owned timer path by deleting:
+  - `src/messaging/rate-limiter.ts`
+  - `src/messaging/event-loop-delay-sampler.ts`
+  and by removing the corresponding eager usage from `src/connection/foxglove-connection.ts`.
+- The hitch persisted after removing those timers, so they were not the sole cause.
+- Subsequent traces shifted the remaining hot path into live message delivery and image presentation:
+  - `src/messaging/message-handler.ts`
+  - `src/connection/foxglove-connection.ts`
+  - `src/context/MessagePipelineProvider.tsx`
+  - `src/context/message-pipeline-store.ts`
+  - `src/messaging/utils.ts`
+  - `src/panels/image/ImageCanvasRenderer.tsx`
+- Mitigations implemented during the investigation:
+  - bypassed Zustand `messageEventsBySubscriberId` churn for live image-panel subscriptions
+  - added direct connection-owned live frame dispatch
+  - stopped publishing per-frame `PlayerState` updates when no store-based subscribers need them
+  - removed temporary encoded-image diagnostics from the hot path
+  - trimmed per-frame allocations in `ImageCanvasRenderer`
+  - added per-topic latest-frame dispatch in `src/messaging/message-handler.ts`
+  - reduced H.264/H.265 `VideoDecoder.decodeQueueSize` backlog threshold from `12` to `3`
+  - limited image panels to enabled annotation-topic subscriptions only
+- `trace8.json` changed the next focus again:
+  - the old roughly-5-second hitch pattern no longer showed up as a dominant periodic renderer-main spike
+  - the remaining top app-owned cost on `CrRendererMain` was steady `HandlePostMessage` / callback churn, not `FireAnimationFrame`, React commit, or decode worker compute
+  - the hottest non-extension main-thread bundle region mapped back to the local message pipeline / decoded-message delivery path rather than the WebGL image renderer
+- Implemented after `trace8.json`:
+  - replaced one-decoded-event-per-post delivery with worker-side batched decoded-message delivery in:
+    - `src/messaging/deserialization.worker.ts`
+    - `src/messaging/message-handler.ts`
+    - `src/messaging/message-event.ts`
+  - decoded events are now coalesced to latest-per-topic for image-like schemas before crossing the `MessagePort`, and superseded `renderableBitmap` objects are closed on the worker side
+  - transport batching and decoded-event flushing had already been moved off `setTimeout(0)` / `requestAnimationFrame` onto microtasks, so the new batch delivery stacks on top of that lower-latency path
+- Browser follow-up after the decoded-message batching change:
+  - the user reported the visible hitching appeared to be gone
+  - the remaining symptom shifted to bursty H.264 cadence rather than obvious UI stalls
+- Implemented after that report:
+  - restored real compressed-input shedding for normal native H.264/H.265 image playback in:
+    - `src/messaging/deserialization/video/h264.ts`
+    - `src/messaging/deserialization/video/h265.ts`
+  - once `VideoDecoder.decodeQueueSize` is already at the shallow backlog limit, native image playback now drops backed-up `delta` frames instead of decoding them late and presenting catch-up bursts
+  - conservative `outputMode: "i420"` paths used for RGBD / point-cloud extraction still do not shed compressed frames
+- Later traces (`trace13`, `trace15`, `trace16`) showed materially lower renderer-main costs and no dominant app-owned periodic timer spike.
+- Annotation synchronization was checked explicitly and ruled out for plain image display:
+  - `src/panels/image/ImageCanvasRenderer.tsx` does not wait for timestamp-matched annotations before presenting the latest image
+  - `src/context/pause-frame.ts` is not used by the local image path
+  - `src/utils/poitcloud-sync.ts` applies to point-cloud/RGBD synchronization, not plain H.264 image panels
+- Current conclusion:
+  - the renderer-main timer theory is largely dead
+  - the previous visible hitch was likely dominated by decoded-message delivery/task churn on the main thread
+  - after batching that path away, the remaining encoded-video risk moved to decode pacing / catch-up cadence
+  - future hitch work should resume from that point instead of re-running the earlier timer investigation
+
+## Validation Run
+
+- 2026-05-07 hitch-follow-up validation:
+  - `npm exec -- tsc -p tsconfig.json --noEmit`
+  - `npm run build:visualizer-protobuf`
+  - repeated after:
+    - decoded-message worker batching
+    - native H.264/H.265 delta-frame shedding
+- Build results:
+  - targeted visualizer package typecheck passed
+  - `build:visualizer-protobuf` passed after both follow-up changes
+  - remaining output was limited to existing non-failing warnings:
+    - Rollup `"this" has been rewritten to "undefined"`
+    - existing circular dependency warning around `Panel.tsx`
+    - OMT worker-format warning
+- Trace status for this session:
+  - `trace8.json` was captured and inspected locally with ad hoc Node scripts against:
+    - `CrRendererMain`
+    - dedicated worker threads
+    - top `FunctionCall` / `HandlePostMessage` callsites in the built Visualizer bundle
+  - no new post-fix browser trace was captured from this terminal-only environment after the batching and delta-shedding changes
+- Browser traces captured during this investigation include:
+  - `trace7.json`
+  - `trace8.json`
+  - `trace9.json`
+  - `trace10.json`
+  - `trace11.json`
+  - `trace12.json`
+  - `trace13.json`
+  - `trace15.json`
+  - `trace16.json`
+
+## Known Open Risks
+
+- The new WebGL fast path only covers the common packed and YUV live formats. Unsupported formats still use the old worker decode path and may still hitch independently.
+- The packed-format WebGL path currently requires row stride to be pixel-aligned (`step % bytesPerPixel === 0`). Padded packed formats that are not pixel-aligned still fall back to CPU conversion.
+- This session did not record a fresh browser trace after the decoded-message batching change or the follow-on delta-frame shedding change, so the final browser confirmation still needs manual repro with `?streamDiagnostics=1` on:
+  - Visualizer H.264
+  - Viewer H.264
+  - raw-image baseline
+  - H.265 if available
+- If decode throughput is truly lower than ingress for a given device/browser, the new native-path delta shedding may trade the old hitch for visible temporal sparsity or motion burstiness. That is an intentional low-latency tradeoff, but live browser validation is still required.
+- `outputMode: "i420"` paths still do not shed compressed frames, so RGBD / point-cloud extraction may retain different burst behavior from plain image playback under the same source stream.
+- Diagnostics currently focus on the encoded image path and image-panel render cadence. They do not yet enumerate every repeating timer in the app shells automatically.
+- This fixes the concrete `Panel`-level update loop for annotation-disabled panels. If the point-cloud panel still fails after this, the remaining issue is likely a separate render exception in the point-cloud renderer rather than another generic React depth loop from the wrapper.
+- This fixes the boundary reset loop itself, but the original render exception that first trips the panel boundary may still exist elsewhere; if the fallback still appears, the next step is to capture the non-minified error from the underlying panel renderer.
+- Generated protobuf files and Tailwind output are now intentionally untracked, so clean builds in fresh clones depend on running `npm run gen:proto` and `npm run tailwind` before steps that expect those generated artifacts to exist on disk.
+- Full `npm run gen:proto` was not executed in this session because the protobuf download step requires network access; the plugin-path fix is validated locally but not end-to-end against GitHub fetches here.
+- The generator still depends on external `protoc`, `curl`, and `jq` binaries being installed in the caller environment.
+- Browser-runtime validation is still needed if hitch work resumes; the encoded-video hitch remains unresolved.
+- Browser-runtime validation is still needed if hitch work resumes; the original hitch may be substantially improved, but the remaining H.264 pacing behavior is not yet characterized with a new clean trace.
+- `src/components/shared-interval.ts` remains an active renderer-main interval when UI metrics consumers are mounted, though it should be excluded by the reported "no toolbar metrics" reproduction.
+- The store still caches `lastMessageEventByTopic` for all live messages, so some per-frame allocation remains even after bypassing `messageEventsBySubscriberId` for the image panel.
+- The remaining symptom may now be dominated by browser/runtime video decode cadence, decode-queue policy, or `VideoDecoder` recovery behavior rather than a clearly removable `lib/` timer or store hot path.
+- This annotation-subscription reduction only helps if the repro stream advertises annotation topics; it does not explain hitching on a pure image-only stream with no annotation traffic.
+- The hitch investigation produced several useful mitigations and dead-end eliminations, but not a full fix.
+- Browser trace artifacts collected during the hitch investigation were removed from the repo root after the findings were summarized here.
+- Rewrote `feat/visualizer-v4` history to purge committed browser trace artifacts from reachable history so the branch can be pushed again.
+- Created backup branch `backup/feat-visualizer-v4-before-trace-purge` before the history rewrite.
+- Connection/runtime configuration is cleaner now, and decode/point-cloud settings have an explicit exported package API through `setRuntimeConfig()` / `getRuntimeConfig()` / `resetRuntimeConfig()`.
+- Legacy `localStorage` keys for `neuralCameraIntrinsics`, `stereoDepthMaxValue`, and `perspective` are now only a bootstrap compatibility fallback when the runtime-config module first loads.
+- Foxglove schema object/type coupling on the image and point-cloud decode/render path is now much smaller, but other Foxglove schema/runtime dependencies still remain elsewhere in the package.
+- The bundle no longer needs live localization runtime packages, but the legacy Foxglove-derived point-cloud/context code still imports some translation tables and key helpers, so bundle-size cleanup is not complete yet.
+- The narrow localization-specific cleanup is close to exhausted. The remaining bundle weight is now mostly structural Foxglove-derived UI/runtime code, not translation runtime or translation-table payloads.
+- `npm run build` succeeds, but existing Rollup warnings still indicate unresolved dependency and asset-alias debt in the broader Foxglove-derived build path.
+- The legacy rate limiter is now an explicit cleanup candidate, not just a diagnostic finding. If no active runtime contract turns up during implementation, it should be removed rather than carried forward.
+- The easy build-warning cleanup is largely exhausted too. The remaining unresolved-dependency warnings did not disappear after making package metadata explicit, which points to Rollup/workspace resolution behavior or deliberate externalization decisions rather than simple undeclared-package debt.
+- `src/` no longer imports `@foxglove/studio-base`, `@foxglove/studio`, or `@foxglove/ws-protocol`.
+- The package now builds from repo root and no longer depends on the removed `packages/` workspace tree or old Rollup resolver hints.
+- Package metadata is cleaner, but third-party published ESM surfaces still influence which modules must stay explicit Rollup externals even when `src/` no longer imports them directly.
+- Browser-runtime validation is still needed if hitch work resumes; the encoded-video hitch remains unresolved.
+- Browser-runtime validation is still needed if hitch work resumes; the remaining issue may now be "bursty but current" playback instead of hard hitching.
+- `debugLogs` support now uses the explicit runtime-config API too. The old `connectionConfig` storage shape is only read once as a compatibility bootstrap.
+- Runtime-config change propagation is now live for existing deserialization workers too; toggling `debugLogs` through `setRuntimeConfig()` updates already-created worker instances instead of only affecting future ones.
+- After the conservative dependency refresh, the remaining outdated packages are mostly major-version or broader ecosystem moves rather than easy same-major bumps:
+  - MUI 5 -> 9
+  - Three 0.156 -> 0.184
+  - Zustand 4 -> 5
+  - legacy lint stack major updates
+  - TypeScript 5 -> 6
+  - Panda CSS replaced by Tailwind CSS and shared UI packages
+  - Webpack dev tooling major updates
+- `@luxonis/ui-components` and `@luxonis/ui-utils` are now the shared UI layer for the workspace, and the root package no longer directly depends on MUI or Emotion for its own source/runtime path.
+
+## Exact Next Task
+
+- Re-run the encoded-stream repro matrix on the latest build in a browser with `?streamDiagnostics=1`:
+  - Visualizer H.264
+  - Viewer H.264
+  - H.265 if available
+  - compare against raw-image baseline
+- Capture a fresh Chrome Performance trace after the decoded-message batching change and the native delta-frame shedding change.
+- Confirm whether:
+  - the previous visible hitch pattern is still gone
+  - main-thread `HandlePostMessage` volume is materially lower than `trace8`
+  - the new remaining symptom is bursty decode pacing rather than renderer-main overload
+- If playback is still bursty, inspect stream diagnostics and the trace for:
+  - sustained `VideoDecoder.decodeQueueSize` growth
+  - repeated delta-frame dropping without timely keyframe recovery
+  - differences between native image playback and RGBD `i420` extraction behavior
+- If another code round is needed after that trace, the next likely lever is tuning native H.264/H.265 backlog shedding policy:
+  - lower the backlog threshold from `3` to `2` for plain image topics only
+  - or make shedding adaptive by observed queue growth instead of one fixed threshold
+
+## Baseline Findings
+
+- `lib/` is not fully self-contained yet, but it no longer builds or type-checks against `../packages/studio-base/src`, `../packages/theme`, or Rollup `../packages` resolution hints.
+- Both `ImagePanel` and `PointCloudPanel` still depend on Foxglove rendering internals.
+- `VisualizerContext` still recreates a trimmed Foxglove Studio runtime with several stubbed providers.
+- Decode architecture currently uses:
+  - transport worker
+  - adapter
+  - one deserialization worker per topic
+  - nested depth and point-cloud worker pools
+- Supported input schemas currently include:
+  - `EncodedFrame`
+  - `ImgFrame`
+  - `ImgDetections`
+  - `ImageAnnotations`
+  - `SpatialImgDetections`
+  - `IMUData`
+  - `PointCloudData`
+  - `RGBDData`
+
+## Known Hotspots
+
+- Per-topic decoder workers plus nested worker pools create high thread count and likely extra buffer copies.
+- H.264/H.265 decode paths repack buffers per frame.
+- `estimateObjectSize()` is called on hot paths.
+- Annotation toggles remount whole Foxglove panels.
+- Message pipeline is effectively single-flight under render pressure.
+- Point-cloud worker pool is mostly serialized despite multiple workers.
+- Point-cloud sync queue uses O(n) cleanup.
+- Rate-limiting behavior appears partially broken.
+
+## Baseline Validation
+
+Command run:
+
+```bash
+yarn tsc -p tsconfig.json --noEmit
+```
+
+Current result:
+
+- Passes.
+
+Other notes:
+
+- No library-owned tests or fixture harness were found in `lib/`.
+- The previous branch-local `runtime-config-storage.ts` WIP was removed and no longer affects the baseline.
+
+## Validation For Latest Checkpoint
+
+Commands run:
+
+```bash
+yarn tsc -p tsconfig.json --noEmit
+yarn fixtures:decode
+```
+
+Current result:
+
+- `yarn fixtures:decode` succeeds and all current built-in fixtures pass:
+  - raw color image frame
+  - IMU data
+  - colored point cloud
+  - uncolored point cloud
+  - image detections
+  - spatial image detections
+  - custom image annotations
+- `yarn tsc -p tsconfig.json --noEmit` passes.
+- The fixture runner still emits Node loader warnings because it currently uses `ts-node/esm` with `--experimental-specifier-resolution=node`.
+- The fixture runner is intentionally limited to browser-independent decode behavior. Browser-native paths still need browser-runtime validation.
+- Browser-runtime validation now has a checked-in entrypoint, but it was not executed in this session because the current environment does not provide a browser.
+- The local panel-shell cleanup preserved the same fixture results and the branch still type-checks cleanly.
+- The panel-facing renderer/camera/type cleanup preserved the same fixture results and the branch still type-checks cleanly.
+- The local image panel host preserved the same fixture results and the branch still type-checks cleanly.
+- The local image panel host subscription-loop fix preserved clean TypeScript validation.
+- The local image panel callback-loop fix preserved clean TypeScript validation.
+- The local image panel visual and metric alignment cleanup preserved clean TypeScript validation and fixture results.
+- The encoded-video queue stabilization change preserves clean TypeScript validation. Browser-runtime hitch behavior still needs direct validation because current checked-in fixtures do not yet cover H.264/H.265 sample playback.
+- The encoded-video output scheduling change also preserves clean TypeScript validation. Browser-runtime hitch behavior still still needs direct validation.
+- The native `NV12` fast path preserves clean TypeScript validation. Browser-runtime hitch behavior still needs direct validation.
+- The new encoded-video `ImageBitmap` fast path preserves clean TypeScript validation. Browser-runtime hitch behavior still still needs direct validation because this environment cannot run the browser stream.
+- The encoded-video payload-transfer cleanup preserves clean TypeScript validation. Browser-runtime hitch behavior still needs direct validation because this environment cannot run the browser stream.
+- The decoded-message size reuse cleanup preserves clean TypeScript validation. Browser-runtime hitch behavior still needs direct validation because this environment cannot run the browser stream.
+- The local pipeline dispatch simplification preserves clean TypeScript validation. Browser-runtime hitch behavior still needs direct validation because this environment cannot run the browser stream.
+- The cached-frame resource trimming preserves clean TypeScript validation. Browser-runtime hitch behavior still needs direct validation because this environment cannot run the browser stream.
+- The cached raw-image payload trimming preserves clean TypeScript validation. Browser-runtime hitch behavior still needs direct validation because this environment cannot run the browser stream.
+- The panel metrics hook stabilization preserves clean TypeScript validation. Browser-runtime hitch behavior still needs direct validation because this environment cannot run the browser stream.
+- The panel toolbar sampling consolidation preserves clean TypeScript validation and fixture results. Browser-runtime hitch behavior and FE delay readout still need direct validation because this environment cannot run the browser stream.
+- The frontend delay sampling restoration preserves clean TypeScript validation and fixture results. Browser-runtime validation is still required to confirm that the FE delay readout is visible again and to continue isolating the unchanged H.264 hitch.
+- The pipeline order-tracking removal preserves clean TypeScript validation and fixture results. Browser-runtime validation is still required to determine whether removing this legacy per-batch scan changes the remaining H.264 hitch pattern.
+- Hiding the Frontend Delay metric preserves clean TypeScript validation. The H.264 hitch remains unresolved.
+- The pipeline/frame snapshot allocation cleanup preserves clean TypeScript validation and fixture results. Browser-runtime validation is still required to see whether reducing this allocation churn changes the H.264 hitch or GC profile.
+- The narrowed live-frame propagation preserves clean TypeScript validation and fixture results. Browser-runtime validation is still required to see whether reducing the breadth of live frame state propagation changes the H.264 hitch or GC profile.
+- The imperative image-panel draw path preserves clean TypeScript validation and fixture results. Browser-runtime validation is now required to see whether removing per-frame React state churn from `ImageCanvasRenderer` changes the H.264 hitch pattern.
+- The dead render-delay cleanup preserves clean TypeScript validation and fixture results. Browser-runtime validation is still required to see whether removing this confirmed periodic React state churn reduces the scheduler-driven hitch pattern.
+- The native encoded-video no-raw-bytes experiment preserves clean TypeScript validation and current Node-safe fixture results. Browser-runtime validation is still required to determine whether removing worker-side `VideoFrame.copyTo()` from normal H.264/H.265 image topics materially changes the 5-second hitch profile.
+- The explicit decoded-message `MessagePort` transport preserves clean TypeScript validation and current Node-safe fixture results. Browser-runtime validation is now required to confirm that encoded image topics actually arrive at `ImageCanvasRenderer` with `renderableBitmap` intact and that the `raw-image-decoder.worker` per-frame activity disappears from the next trace.
+- The encoded-image bitmap-hop diagnostics preserve clean TypeScript validation and current Node-safe fixture results. Browser-runtime validation is now required to collect the new `[bitmap-path]` logs and identify the exact hop where `renderableBitmap` is lost.
+- The encoded-image subscription stabilization does not introduce new TypeScript diagnostics in the touched files. A focused `npm exec -- tsc -p libraries/depthai-visualizer-lib/tsconfig.json --noEmit` run still fails on pre-existing `ArrayBufferLike` / `ImageData` typing issues in `src/connection/communicator.ts` and `src/panels/image/worker-image-decoder.ts`, so browser/runtime confirmation is still needed for this checkpoint.
+- `npm run -w=@luxonis/visualizer-protobuf build` now succeeds on macOS after the protobuf `sed` fix, and the emitted `dist/` bundle contains both the encoded-frame FIFO queue change and the native-to-I420 fallback path.
+- `npm run -w=@luxonis/visualizer-protobuf build` still succeeds after the `imageFrame` FIFO extension and async decode-error surfacing changes.
+- The per-frame encoded output-mode fix preserves clean TypeScript validation and current Node-safe fixture results. Browser-runtime validation is now required to confirm that normal H.264 image topics start reporting `expected=true` / actual bitmap presence instead of falling straight into the `yuv420p` raw decode path.
+- Verified after the branch-history rewrite that `feat/visualizer-v4` no longer contains reachable `trace*.json` blobs, including the previous >100MB files that blocked pushing.
+- The local raw-image decoder replacement preserves clean TypeScript validation and current Node-safe fixture results while removing the last `@foxglove/den/image` dependency from `lib/src`.
+- The localization stub pass preserves clean TypeScript validation and current Node-safe fixture results.
+- The direct translation-table removal preserves clean TypeScript validation and current Node-safe fixture results.
+- The protobuf generator idempotence fix restores clean validation across:
+  - `yarn tsc -p tsconfig.json --noEmit`
+  - `yarn fixtures:decode`
+  - `yarn build`
+- `yarn build` now completes successfully, but still emits existing Rollup warnings about unresolved third-party dependencies, unresolved Foxglove font asset URLs, circular dependencies, and MUI export mismatches.
+- The remaining rate-limiter removal preserves clean validation across:
+  - `yarn tsc -p tsconfig.json --noEmit`
+  - `yarn fixtures:decode`
+  - `yarn build`
+- Build output remains successful with the same pre-existing Rollup warnings; the rate-limiter removal did not introduce any new warning class or validation failure.
+- The follow-on build-warning cleanup also preserves clean validation across:
+  - `yarn build`
+- Build improvements confirmed in this slice:
+  - the unresolved Foxglove font asset warnings are gone
+  - the previous theme-package `Missing exports` / `Unused external imports` warnings are gone
+- The local Visualizer shell slimming preserves clean validation across:
+  - `yarn tsc -p tsconfig.json --noEmit`
+  - `yarn fixtures:decode`
+  - `yarn build`
+- The local visualizer shell context replacement preserves clean validation across:
+  - `yarn tsc -p tsconfig.json --noEmit`
+  - `yarn build`
+- The follow-on build cleanup removed dead `@foxglove/studio-base` aliases, the unused `camera-controls` dependency, and the last `../packages/theme` / `../packages` resolver hints while preserving clean validation across:
+  - `yarn tsc -p tsconfig.json --noEmit`
+  - `yarn build`
+- The WebSocket/WebRTC transport layer now uses a local `foxglove-ws-types.ts` contract for opcodes and message/service/channel shapes; only `FoxgloveClient` remains as a direct `@foxglove/ws-protocol` import. This preserves clean validation across:
+  - `yarn tsc -p tsconfig.json --noEmit`
+  - `yarn build`
+- The WebSocket worker now depends on a local `foxglove-client-adapter.ts` interface instead of importing `FoxgloveClient` directly. The direct package boundary is reduced to that one adapter file, and validation remains clean across:
+  - `yarn tsc -p tsconfig.json --noEmit`
+  - `yarn build`
+- The external-subpath Rollup cleanup preserves clean validation across:
+  - `yarn tsc -p tsconfig.json --noEmit`
+  - `yarn build`
+- The `"use client"` warning-filter cleanup preserves clean validation across:
+  - `yarn tsc -p tsconfig.json --noEmit`
+  - `yarn build`
+- Remaining build warnings are now primarily:
+  - `this` rewrite notices from third-party packages
+  - existing circular-dependency notices
+  - the OMT browser-support warning
+- Restored the intended native encoded-image fast path so live `native` decode now prefers `createImageBitmap(frame)` before falling back to transferable planar payloads:
+  - `src/messaging/deserialization/video/h264.ts`
+  - `src/messaging/deserialization/video/h265.ts`
+  - `src/messaging/deserialization/video/mjpeg.ts`
+- This makes the existing `renderableBitmap` event contract live again for H.264, H.265, and MJPEG instead of leaving that path as dead scaffolding while still preserving the current planar fallback paths for RGBD and browsers where bitmap extraction fails.
+- Replaced the coarse encoded-stream browser gate with target-specific runtime capability checks in `src/messaging/decode-core.ts` and `src/utils/encoding.ts`:
+  - video-backed encoded streams now require actual `VideoDecoder` and `EncodedVideoChunk` support
+  - JPEG-backed encoded streams now require actual `ImageDecoder` support
+  - secure-context enforcement remains unchanged
+- Validation for this checkpoint:
+  - `npm run build:visualizer-protobuf`
+  - build passed
+  - remaining warnings were unchanged: third-party `this` rewrite notices, existing circular dependencies, and the OMT browser-support warning
+- Removed legacy storage bootstrap from `libraries/depthai-visualizer-lib/src/utils/runtime-config.ts` so the library no longer reads `localStorage` on module import to discover decode/runtime settings.
+- Kept `VisualizerConnection` focused on connection concerns only by removing the temporary runtime-config constructor bridge from `libraries/depthai-visualizer-lib/src/connection/connection.ts`; the explicit visualizer runtime API remains `setRuntimeConfig()` / `getRuntimeConfig()`.
+- Added `packages/common/src/providers/VisualizerRuntimeConfigProvider.tsx` as the new app-owned boundary for visualizer runtime state. That provider:
+  - owns the React state for visualizer runtime config
+  - synchronizes it into `@luxonis/visualizer-protobuf` through `setRuntimeConfig()`
+  - keeps `stereoDepthMaxValue` persistence in the app layer for compatibility instead of in the published library
+- Updated `packages/common/src/components/DepthAIContext.tsx` so npm consumers can pass an explicit `visualizerRuntimeConfig` into the provider boundary when embedding the shared entrypoint.
+- Updated `packages/depthai-viewer/frontend/src/providers/ViewerProviders.tsx` so Viewer now initializes the shared provider explicitly at app startup.
+- Updated `packages/depthai-viewer/frontend/src/components/MaximumDepthDistanceSlider.tsx` so the depth-distance UI reads and writes provider-owned runtime config instead of talking to `localStorage` directly.
+- Removed the temporary compatibility hydration from `packages/common/src/dai-connection/connection.ts`; runtime config is now no longer smuggled through connection construction.
+- Validation for this checkpoint:
+  - `npm run build:visualizer-protobuf`
+  - build passed
+  - remaining warnings were unchanged: third-party `this` rewrite notices, existing circular dependencies, and the OMT browser-support warning
+
+## Next Recommended Task
+
+Defer the browser hitch investigation until the final performance pass, per current branch plan.
+
+Concrete next step:
+
+- use this build to validate whether encoded-stream artifacting is resolved without regressing decode latency
+- after that, use the same revision as the baseline for the final benchmark run and the final browser hitch repro pass
+- if artifacting remains, inspect `imageFrame` `BITSTREAM` metadata assumptions versus `encodedFrame` `FrameType` handling before changing presentation code
+
+## Open Risks
+
+- Refactoring without fixtures will likely break compatibility accidentally because some current behavior is implicit and some internal artifacts masquerade as Foxglove schema outputs.
+- Build/package cleanup will be risky until Foxglove source aliasing is removed incrementally.
+- The new harness can call shared decode logic directly, but some decoder paths still schedule delayed work with timers, so fixture design will need explicit settling/flush behavior for those cases.
+- The current fixture runner depends on `ts-node/esm` loader behavior and emits experimental/deprecation warnings under Node.
+- Video-codec-backed fixtures may be environment-sensitive because `VideoDecoder` and worker support depend on runtime capabilities.
+- Browser-only runtime assumptions are part of the product contract, so future refactors should not remove browser APIs just to satisfy Node execution.
+- The current browser fixture entrypoint depends on a successful build producing `dist/browser-decoder-fixtures-entry.js`; that build now succeeds again, but encoded browser-runtime coverage is still missing.
+- The new bounded worker pool hashes topics to workers, so per-topic decoder state is no longer isolated by dedicated worker process. Future changes must preserve topic-keyed decoder state inside each shared worker.
+- The visualizer library no longer bootstraps runtime decode settings from `localStorage`; app-owned persistence now lives behind `packages/common/src/providers/VisualizerRuntimeConfigProvider.tsx`, and only `stereoDepthMaxValue` is still persisted for compatibility.
+- The legacy non-RGBD point-cloud path is still architecturally separate from the newer RGBD worker path, so there is still duplication left even after the queue/storage cleanup.
+- Browser fixture coverage still does not exercise the new transfer-oriented point-cloud worker paths in a real browser runtime.
+- Player-facing state/types in the connection layer still depend on Foxglove player interfaces, so deeper de-Foxgloving there will need a deliberate compatibility decision rather than a blind helper swap.
+- Connection/context code now uses a local player-type and message-pipeline implementation internally, but `src/context/MessagePipelineProvider.tsx` still provides a Foxglove-compatible context shape through `ContextInternal` so the legacy Foxglove panels can continue working.
+- `npm run fixtures:decode` still relies on `ts-node/esm` loader behavior and emits experimental/deprecation warnings, so the fast Node-safe fixture runner is not yet fully modernized even though it is now package-local.
+- `ImagePanel` is now local, but `PointCloudPanel` still depends on Foxglove `ThreeDeeRender`, so the `ContextInternal` compatibility layer cannot be dropped yet.
+- The next meaningful slimming step is no longer a small provider swap; replacing the Foxglove `ThreeDeeRender` panel wrapper will require a deliberate local adapter for the subset of `BuiltinPanelExtensionContext` that the renderer actually uses.
+- The new local image host still depends on browser runtime validation because Node fixtures only cover decode semantics, not canvas/worker presentation behavior.
+- Native encoded delivery now prefers `renderableBitmap` again, so panels that rely on cached last-frame snapshots still intentionally lose that bitmap on snapshot stripping and may need a subsequent live frame after mount.
+- Encoded-stream capability gating now reflects constructor availability instead of browser branding, but actual per-codec support still depends on runtime `configure()` success and browser codec support.
+- `imageFrame` `BITSTREAM` payloads still do not carry `EncodedFrame.FrameType`, so that path is still inferred as keyframe-only by the current H.264/H.265 helper logic and may need separate treatment if artifacts persist after removing compressed-input shedding.
+- Encoded H.264/H.265 browser playback may still hitch if the remaining cost is in worker-side `copyTo()` / `createImageBitmap()` cadence or GOP/keyframe variability rather than cross-thread copies and panel decode.
+- The hitch investigation is paused, not resolved. Latest traces reduced the renderer-main timer theory substantially, but encoded-video pacing and presentation cadence are still open browser-runtime risks.
+- The new per-image-topic worker routing trades worker-count for isolation. If many image topics are active simultaneously, worker proliferation may become the next limit and should be checked against real multi-stream traces.
+- Cached snapshots for native encoded image topics still intentionally strip `renderableBitmap`, so a panel that mounts after the last frame and receives no subsequent live frame still cannot paint from cache alone.
+- The branch history was rewritten to purge trace artifacts, so the next push must use `git push --force-with-lease origin feat/visualizer-v4`.
+
+## Template For Next Update
+
+Replace the sections above with current values and keep this structure:
+
+- Date
+- Branch
+- Phase
+- Latest completed checkpoint
+- Latest commit for this checkpoint
+- What was completed
+- Validation
+- Open risks
+- Exact next task