@octanejs/devtools 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dominic Gannaway
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,49 @@
+# @octanejs/devtools
+
+Live Octane runtime diagnostics for the [TanStack Devtools](https://tanstack.com/devtools)
+panel — a Components tab showing the mounted component tree and per-node state,
+streamed over `@tanstack/devtools-event-client` from a dev-only runtime hook.
+
+## Installation
+
+```bash
+pnpm add @octanejs/devtools
+```
+
+## Usage
+
+```tsx
+import { TanStackDevtools } from '@octanejs/tanstack-devtools';
+import { octaneDevtools } from '@octanejs/devtools';
+
+function App() @{
+  <>
+    <TanStackDevtools plugins={[octaneDevtools()]} />
+    <MyApp />
+  </>
+}
+```
+
+Enable the runtime hook in dev with `octane({ devtools: true })` in your Vite
+config — production builds tree-shake the hook away entirely.
+
+The Components tab shows the live component tree, and on selecting a node: its
+hook cells (state/reducer/ref/memo-or-callback), context values, and effect
+count. It's read-only in v1 — selecting a node never mutates app state.
+
+The Profiler tab ranks components by self time (renders, self/max/queue ms,
+dominant cause) and lists recent commits (mount/update, self ms, causes).
+
+The Transitions & Suspense tab shows the live pending-transition count and
+each Suspense boundary's state (init/pending/resolved/caught), with a
+"(resolved once)" marker once a boundary has shown its primary content.
+
+The Performance-model tab is an aggregate "what's slow" view over the same
+profiler data as the Profiler tab: slowest mounts by self time, queue-delay
+hotspots, and a recent commit self-time trend.
+
+Only include the devtools in development, e.g. behind an `import.meta.env.DEV`
+check or via `lazy()`.
+
+See [`docs/devtools.md`](../../docs/devtools.md) for the full setup guide,
+guarantees, and known caveats.

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@octanejs/devtools",
+  "version": "0.0.1",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "octane": {
+    "hookSlots": {
+      "manual": [
+        "src"
+      ]
+    }
+  },
+  "description": "Octane DevTools — a TanStack Devtools plugin exposing live Octane runtime diagnostics (component tree, state, profiler).",
+  "author": {
+    "name": "Dominic Gannaway",
+    "email": "dg@domgan.com"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/octanejs/octane.git",
+    "directory": "packages/devtools"
+  },
+  "main": "src/index.ts",
+  "module": "src/index.ts",
+  "types": "src/index.ts",
+  "sideEffects": false,
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "dependencies": {
+    "@tanstack/devtools": "0.12.5",
+    "@tanstack/devtools-event-client": "0.5.0"
+  },
+  "peerDependencies": {
+    "octane": "0.1.13"
+  },
+  "devDependencies": {
+    "@tanstack/devtools-event-bus": "0.4.2",
+    "@testing-library/jest-dom": "^6.9.1",
+    "vitest": "^4.1.10",
+    "octane": "0.1.13",
+    "@octanejs/testing-library": "0.1.10"
+  },
+  "scripts": {
+    "test": "vitest run"
+  }
+}

package/src/bridge.ts

@@ -0,0 +1,182 @@
+import {
+	OctaneDevtoolsEventClient,
+	type NodeDetail,
+	type ProfileEventWire,
+	type ProfileSnapshot,
+	type TransitionSnapshot,
+	type WireTreeNode,
+} from './client';
+
+interface RuntimeHook {
+	version: number;
+	getTree(): WireTreeNode[];
+	inspect(id: number): NodeDetail | null;
+	subscribe(listener: () => void): () => void;
+	getTransitionState(): TransitionSnapshot;
+}
+
+function getHook(): RuntimeHook | undefined {
+	return (globalThis as unknown as { __OCTANE_DEVTOOLS__?: RuntimeHook }).__OCTANE_DEVTOOLS__;
+}
+
+// Structural shape of the profile-build global (installed by `octane/profiling`).
+// Read via the global rather than imported so devtools stays decoupled from the
+// profiling package and testable with a plain fake.
+interface ProfilerGlobal {
+	summary(): Array<Record<string, unknown>>;
+	getEvents(): Array<Record<string, unknown>>;
+}
+
+function getProfiler(): ProfilerGlobal | undefined {
+	return (globalThis as unknown as { __OCTANE_PROFILER__?: ProfilerGlobal }).__OCTANE_PROFILER__;
+}
+
+// The DevTools panel is itself an Octane tree, so the profiler records ITS
+// components too. Filter them out of everything we report: it's noise (you're
+// profiling your app, not the inspector) and, critically, it stops the panel's
+// own re-renders from perpetually changing the profile snapshot — which, with
+// the dedupe below, lets the live view settle when the app is idle.
+const DEVTOOLS_OWN_COMPONENTS = new Set([
+	'OctanePanel',
+	'ComponentsTab',
+	'ProfilerTab',
+	'TransitionsTab',
+	'PerfModelTab',
+	'TreeRow',
+	'DevtoolsPortal',
+	'TanStackDevtools',
+]);
+
+function pruneTree(nodes: WireTreeNode[]): WireTreeNode[] {
+	return nodes
+		.filter((n) => !DEVTOOLS_OWN_COMPONENTS.has(n.name))
+		.map((n) => ({ ...n, children: pruneTree(n.children) }));
+}
+
+function toSnapshot(profiler: ProfilerGlobal): ProfileSnapshot {
+	const summaries = profiler
+		.summary()
+		.filter((s) => !DEVTOOLS_OWN_COMPONENTS.has(String(s.component)))
+		.map((s) => ({
+			componentId: String(s.componentId),
+			component: String(s.component),
+			file: String(s.file),
+			attempts: Number(s.attempts) || 0,
+			completed: Number(s.completed) || 0,
+			suspended: Number(s.suspended) || 0,
+			errored: Number(s.errored) || 0,
+			bails: Number(s.bails) || 0,
+			totalSelfTime: Number(s.totalSelfTime) || 0,
+			maxInclusiveTime: Number(s.maxInclusiveTime) || 0,
+			averageSelfTime: Number(s.averageSelfTime) || 0,
+			averageQueueDelay: Number(s.averageQueueDelay) || 0,
+			dominantCause: (s.dominantCause as string | null) ?? null,
+		}));
+	const recentEvents = profiler
+		.getEvents()
+		.filter((e) => !DEVTOOLS_OWN_COMPONENTS.has(String(e.component)))
+		.slice(-100)
+		.map((e) => ({
+			component: String(e.component),
+			phase: (e.phase === 'update' ? 'update' : 'mount') as ProfileEventWire['phase'],
+			outcome: String(e.outcome) as ProfileEventWire['outcome'],
+			selfDuration: Number(e.selfDuration) || 0,
+			duration: Number(e.duration) || 0,
+			queueDelay: Number(e.queueDelay) || 0,
+			causes: Array.isArray(e.causes)
+				? (e.causes as Array<{ type?: unknown }>).map((c) => String(c.type ?? '')).filter(Boolean)
+				: [],
+		}));
+	return { summaries, recentEvents };
+}
+
+/**
+ * Wire the runtime hook to the event bus. Emits a coalesced `tree` snapshot once
+ * per scheduler flush; answers `inspect-request` with `inspect` (lazy detail — only
+ * the selected node is serialized). Returns a stop function. No-op if the runtime
+ * devtools hook is not installed (e.g. a non-profile build).
+ */
+export function startBridge(
+	client: OctaneDevtoolsEventClient = new OctaneDevtoolsEventClient(),
+): () => void {
+	const hook = getHook();
+	if (!hook) return () => {};
+
+	// The panel is itself an Octane tree in the SAME runtime it observes, so an
+	// emit → panel re-render → flush → emit cycle would spin the CPU. Two guards
+	// tame it into a bounded, mostly-idle live view (as React DevTools does):
+	//   1. Throttle: at most one emit per MIN_INTERVAL_MS (leading + trailing).
+	//   2. Dedupe: skip an event whose serialized payload is unchanged, so tree
+	//      and transition stop emitting entirely once the app goes idle.
+	const MIN_INTERVAL_MS = 400;
+	let lastEmitAt = 0;
+	let trailing: ReturnType<typeof setTimeout> | null = null;
+	let lastTree = '';
+	let lastProfile = '';
+	let lastTransition = '';
+
+	const emitNow = () => {
+		if (trailing !== null) {
+			clearTimeout(trailing);
+			trailing = null;
+		}
+		lastEmitAt = Date.now();
+		const nodes = pruneTree(hook.getTree());
+		const treeJson = JSON.stringify(nodes);
+		if (treeJson !== lastTree) {
+			lastTree = treeJson;
+			client.emit('tree', { nodes });
+		}
+		const profiler = getProfiler();
+		if (profiler) {
+			const snapshot = toSnapshot(profiler);
+			const profileJson = JSON.stringify(snapshot);
+			if (profileJson !== lastProfile) {
+				lastProfile = profileJson;
+				client.emit('profile', snapshot);
+			}
+		}
+		if (typeof hook.getTransitionState === 'function') {
+			const transition = hook.getTransitionState();
+			const transitionJson = JSON.stringify(transition);
+			if (transitionJson !== lastTransition) {
+				lastTransition = transitionJson;
+				client.emit('transition', transition);
+			}
+		}
+	};
+
+	const schedule = () => {
+		if (trailing !== null) return;
+		const since = Date.now() - lastEmitAt;
+		if (since >= MIN_INTERVAL_MS) emitNow();
+		else trailing = setTimeout(emitNow, MIN_INTERVAL_MS - since);
+	};
+
+	const offFlush = hook.subscribe(schedule);
+
+	const offRequest = client.on('inspect-request', (e) => {
+		const detail = hook.inspect(e.payload.id);
+		if (detail) client.emit('inspect', detail);
+	});
+
+	// The panel asks for a fresh snapshot when it mounts; force a full re-emit
+	// (reset the dedupe caches) so its tabs populate even if nothing changed
+	// since the last emit.
+	const offRefresh = client.on('refresh', () => {
+		lastTree = '';
+		lastProfile = '';
+		lastTransition = '';
+		emitNow();
+	});
+
+	// Initial snapshot so a panel opened after mount sees current state.
+	emitNow();
+
+	return () => {
+		offFlush();
+		offRequest();
+		offRefresh();
+		if (trailing !== null) clearTimeout(trailing);
+	};
+}

package/src/client.ts

@@ -0,0 +1,84 @@
+import { EventClient } from '@tanstack/devtools-event-client';
+
+export const PLUGIN_ID = 'octane';
+
+// --- Wire types (the serialized contract; decoupled from runtime in-memory types) ---
+export interface WireTreeNode {
+	id: number;
+	name: string;
+	kind: string;
+	children: WireTreeNode[];
+}
+export interface TreeSnapshot {
+	nodes: WireTreeNode[];
+}
+export interface WireHookCell {
+	kind: string;
+	value: unknown;
+}
+export interface NodeDetail {
+	id: number;
+	name: string;
+	hooks: WireHookCell[];
+	context: Array<{ name: string; value: unknown }>;
+	effectCount: number;
+}
+export interface InspectRequest {
+	id: number;
+}
+export interface ProfileSummaryWire {
+	componentId: string;
+	component: string;
+	file: string;
+	attempts: number;
+	completed: number;
+	suspended: number;
+	errored: number;
+	bails: number;
+	totalSelfTime: number;
+	maxInclusiveTime: number;
+	averageSelfTime: number;
+	averageQueueDelay: number;
+	dominantCause: string | null;
+}
+export interface ProfileEventWire {
+	component: string;
+	phase: 'mount' | 'update';
+	outcome: 'completed' | 'suspended' | 'errored' | 'bailout';
+	selfDuration: number;
+	duration: number;
+	queueDelay: number;
+	causes: string[]; // cause.type values, flattened for display
+}
+export interface ProfileSnapshot {
+	summaries: ProfileSummaryWire[];
+	recentEvents: ProfileEventWire[];
+}
+export interface BoundaryWire {
+	id: number;
+	branch: number;
+	state: 'init' | 'catch' | 'resolved' | 'pending';
+	hasResolved: boolean;
+	label: string;
+}
+export interface TransitionSnapshot {
+	pendingCount: number;
+	boundaries: BoundaryWire[];
+}
+
+type OctaneDevtoolsEventMap = {
+	tree: TreeSnapshot;
+	inspect: NodeDetail;
+	'inspect-request': InspectRequest;
+	profile: ProfileSnapshot;
+	transition: TransitionSnapshot;
+	// Panel → bridge: "send me a fresh snapshot now" (emitted when the panel
+	// mounts, so tabs populate regardless of subscribe-vs-first-flush timing).
+	refresh: Record<string, never>;
+};
+
+export class OctaneDevtoolsEventClient extends EventClient<OctaneDevtoolsEventMap> {
+	constructor() {
+		super({ pluginId: PLUGIN_ID });
+	}
+}

package/src/index.ts

@@ -0,0 +1,35 @@
+/** @jsxImportSource octane */
+'use client';
+
+import { createElement } from 'octane';
+import { OctaneDevtoolsEventClient } from './client';
+import { startBridge } from './bridge';
+import { OctanePanel } from './panel/OctanePanel.tsrx';
+
+export { OctaneDevtoolsEventClient } from './client';
+export { startBridge } from './bridge';
+export { ComponentsTab } from './panel/ComponentsTab.tsrx';
+export { ProfilerTab } from './panel/ProfilerTab.tsrx';
+export { TransitionsTab } from './panel/TransitionsTab.tsrx';
+export { PerfModelTab } from './panel/PerfModelTab.tsrx';
+export { OctanePanel } from './panel/OctanePanel.tsrx';
+export type { TreeSnapshot, NodeDetail, WireTreeNode } from './client';
+
+/**
+ * A TanStack Devtools plugin exposing live Octane runtime diagnostics. Add it to
+ * `<TanStackDevtools plugins={[octaneDevtools()]} />`. Starts the app-side bridge
+ * on first render; the bridge is a no-op unless the app was built with devtools
+ * enabled (`octane({ devtools: true })`).
+ */
+export function octaneDevtools() {
+	const client = new OctaneDevtoolsEventClient();
+	let stop: (() => void) | null = null;
+	return {
+		id: 'octane',
+		name: 'Octane',
+		render: () => {
+			if (stop === null) stop = startBridge(client);
+			return createElement(OctanePanel, { client });
+		},
+	};
+}

package/src/panel/ComponentsTab.tsrx

@@ -0,0 +1,100 @@
+// The Components tab: subscribes to the app-side bridge's `tree`/`inspect` events
+// (startBridge) and renders the live component tree plus a selected-node state
+// inspector. Read-only — selecting a node only asks the app to describe it
+// (`inspect-request`); it never mutates app state (see docs/devtools.md P1 scope).
+import { useEffect, useState } from 'octane';
+import type { OctaneNode } from 'octane';
+import { OctaneDevtoolsEventClient, type NodeDetail, type WireTreeNode } from '../client';
+
+function TreeRow(props: {
+	node: WireTreeNode;
+	onSelect: (id: number) => void;
+	selected: number | null;
+}) @{
+	<div>
+		<button
+			class={['odt-tree-row', props.selected === props.node.id && 'odt-selected']}
+			onClick={() => props.onSelect(props.node.id)}
+		>
+			<span
+				class={['odt-kind', props.node.kind === 'root' && 'odt-kind-root']}
+			>{props.node.kind}</span>
+			<span>{props.node.name}</span>
+		</button>
+		@if (props.node.children.length > 0) {
+			<div class="odt-child">
+				@for (const child of props.node.children; key child.id) {
+					<TreeRow node={child} onSelect={props.onSelect} selected={props.selected} />
+				}
+			</div>
+		}
+	</div>
+}
+
+export function ComponentsTab(props: { client: OctaneDevtoolsEventClient }): OctaneNode {
+	const { client } = props;
+	const [nodes, setNodes] = useState<WireTreeNode[]>([]);
+	const [selected, setSelected] = useState<number | null>(null);
+	const [detail, setDetail] = useState<NodeDetail | null>(null);
+
+	useEffect(() => {
+		const offTree = client.on('tree', (e) => setNodes(e.payload.nodes));
+		const offInspect = client.on('inspect', (e) => setDetail(e.payload));
+		return () => {
+			offTree();
+			offInspect();
+		};
+	});
+
+	const onSelect = (id: number) => {
+		setSelected(id);
+		client.emit('inspect-request', { id });
+	};
+
+	return <div class="odt-split">
+		<div class="odt-col odt-col-tree">
+			<div class="odt-h">Component tree</div>
+			@if (nodes.length === 0) {
+				<div class="odt-empty">No mounted roots yet.</div>
+			} @else {
+				@for (const node of nodes; key node.id) {
+					<TreeRow node={node} onSelect={onSelect} selected={selected} />
+				}
+			}
+		</div>
+		<div class="odt-col">
+			@if (detail) {
+				<div>
+					<div class="odt-node-name">
+						{detail.name}
+						<span class="odt-badge">{detail.effectCount} effects</span>
+					</div>
+					<div class="odt-h">Hooks</div>
+					@if (detail.hooks.length === 0) {
+						<div class="odt-empty odt-muted">No tracked hooks.</div>
+					} @else {
+						@for (const cell of detail.hooks; index i) {
+							<div class="odt-kv">
+								<span class="odt-kv-key">{cell.kind}</span>
+								<span class="odt-kv-val"> {JSON.stringify(cell.value)}</span>
+							</div>
+						}
+					}
+					@if (detail.context.length > 0) {
+						<>
+							<div class="odt-h">Context</div>
+							@for (const c of detail.context; index i) {
+								<div class="odt-kv">
+									<span class="odt-kv-key">{c.name}</span>
+									<span class="odt-kv-val"> {JSON.stringify(c.value)}</span>
+								</div>
+							}
+						</>
+					}
+				</div>
+			} @else {
+				<div class="odt-empty">Select a component.</div>
+			}
+		</div>
+	</div>;
+}

package/src/panel/ComponentsTab.tsrx.d.ts

@@ -0,0 +1,6 @@
+// Declaration companion for ComponentsTab.tsrx.
+import type { OctaneDevtoolsEventClient } from '../client';
+
+export declare function ComponentsTab(props: { client: OctaneDevtoolsEventClient }): unknown;
+
+export {};

package/src/panel/OctanePanel.tsrx

@@ -0,0 +1,62 @@
+// The tab shell hosting the Components (P1), Profiler (P2), Transitions (P3),
+// and Performance-model (P4) tabs. This is the plugin's top-level render()
+// node — see ../index.ts. It injects the Octane-branded panel stylesheet once
+// and asks the bridge for a fresh snapshot on mount so tabs populate immediately.
+import { useEffect, useState } from 'octane';
+import type { OctaneNode } from 'octane';
+import { OctaneDevtoolsEventClient } from '../client';
+import { ComponentsTab } from './ComponentsTab.tsrx';
+import { ProfilerTab } from './ProfilerTab.tsrx';
+import { TransitionsTab } from './TransitionsTab.tsrx';
+import { PerfModelTab } from './PerfModelTab.tsrx';
+import { OCTANE_DEVTOOLS_CSS, OCTANE_DEVTOOLS_STYLE_ID } from './styles';
+
+type Tab = 'components' | 'profiler' | 'transitions' | 'performance';
+
+const TABS: Array<{ id: Tab; label: string }> = [
+	{ id: 'components', label: 'Components' },
+	{ id: 'profiler', label: 'Profiler' },
+	{ id: 'transitions', label: 'Transitions & Suspense' },
+	{ id: 'performance', label: 'Performance' },
+];
+
+export function OctanePanel(props: { client: OctaneDevtoolsEventClient }): OctaneNode {
+	const { client } = props;
+	const [tab, setTab] = useState<Tab>('components');
+
+	useEffect(() => {
+		// The panel is portaled into the TanStack DevTools host, so site CSS never
+		// reaches it — inject our own Octane-branded stylesheet once.
+		if (typeof document !== 'undefined' && !document.getElementById(OCTANE_DEVTOOLS_STYLE_ID)) {
+			const el = document.createElement('style');
+			el.id = OCTANE_DEVTOOLS_STYLE_ID;
+			el.textContent = OCTANE_DEVTOOLS_CSS;
+			document.head.appendChild(el);
+		}
+		// Pull a current snapshot so tabs show data on open, not only after the
+		// next scheduler flush.
+		client.emit('refresh', {});
+	});
+
+	return <div class="odt-root">
+		<div class="odt-tabs">
+			@for (const t of TABS; key t.id) {
+				<button
+					class={['odt-tab', tab === t.id && 'odt-tab-active']}
+					onClick={() => setTab(t.id)}
+				>{t.label}</button>
+			}
+		</div>
+		<div class="odt-body">
+			@if (tab === 'components') {
+				<ComponentsTab client={client} />
+			} @else if (tab === 'profiler') {
+				<ProfilerTab client={client} />
+			} @else if (tab === 'transitions') {
+				<TransitionsTab client={client} />
+			} @else {
+				<PerfModelTab client={client} />
+			}
+		</div>
+	</div>;
+}

package/src/panel/OctanePanel.tsrx.d.ts

@@ -0,0 +1,6 @@
+// Declaration companion for OctanePanel.tsrx.
+import type { OctaneDevtoolsEventClient } from '../client';
+
+export declare function OctanePanel(props: { client: OctaneDevtoolsEventClient }): unknown;
+
+export {};

package/src/panel/PerfModelTab.tsrx

@@ -0,0 +1,92 @@
+// The Performance-model tab: derives aggregate "what's slow" views from the SAME
+// `profile` event the Profiler tab already consumes — no new event, bridge path, or
+// runtime probe. Where the Profiler tab shows a per-commit table, this tab shows
+// ranked aggregates: slowest mounts by self time, queue-delay hotspots, and a recent
+// commit self-time trend.
+import { useEffect, useMemo, useState } from 'octane';
+import type { OctaneNode } from 'octane';
+import { OctaneDevtoolsEventClient, type ProfileSnapshot } from '../client';
+
+function fmt(ms: number): string {
+	return (Math.round(ms * 10) / 10).toString();
+}
+
+export function PerfModelTab(props: { client: OctaneDevtoolsEventClient }): OctaneNode {
+	const { client } = props;
+	const [snapshot, setSnapshot] = useState<ProfileSnapshot | null>(null);
+
+	useEffect(() => {
+		const off = client.on('profile', (e) => setSnapshot(e.payload));
+		return () => off();
+	});
+
+	// Aggregate views derived from the profile snapshot.
+	const slowestMounts = useMemo(() => {
+		if (snapshot === null) return [];
+		const mounts = snapshot.recentEvents.filter((e) => e.phase === 'mount');
+		return mounts.sort((a, b) => b.selfDuration - a.selfDuration).slice(0, 5);
+	}, [snapshot]);
+
+	// Excludes components already surfaced by the mounts list above — the two
+	// aggregate lists highlight distinct signals (heavy initial renders vs.
+	// scheduling delay), not the same component twice.
+	const queueHotspots = useMemo(() => {
+		if (snapshot === null) return [];
+		const alreadyShown = new Set(slowestMounts.map((e) => e.component));
+		const others = snapshot.summaries.filter((s) => !alreadyShown.has(s.component));
+		return others.sort((a, b) => b.averageQueueDelay - a.averageQueueDelay).slice(0, 5);
+	}, [snapshot, slowestMounts]);
+
+	const maxSelf = useMemo(() => {
+		if (snapshot === null) return 1;
+		return Math.max(1, ...snapshot.recentEvents.map((e) => e.selfDuration));
+	}, [snapshot]);
+
+	return <div>
+		@if (snapshot === null || snapshot.summaries.length === 0) {
+			<div class="odt-empty">No performance data yet — interact with the app.</div>
+		} @else {
+			<>
+				<div class="odt-h">Slowest mounts (self time)</div>
+				@if (slowestMounts.length === 0) {
+					<div class="odt-empty odt-muted">No mounts recorded yet.</div>
+				} @else {
+					@for (const e of slowestMounts; index i) {
+						<div class="odt-commit-row">
+							<span class="odt-name-cell">{e.component}</span>
+							<span
+								class="odt-bar"
+								style={{ width: `${Math.max(6, (e.selfDuration / maxSelf) * 120)}px` }}
+							></span>
+							<span class="odt-num">{fmt(e.selfDuration)}ms</span>
+						</div>
+					}
+				}
+				<div class="odt-h">Queue-delay hotspots</div>
+				@if (queueHotspots.length === 0) {
+					<div class="odt-empty odt-muted">No additional hotspots.</div>
+				} @else {
+					@for (const s of queueHotspots; index i) {
+						<div class="odt-commit-row">
+							<span class="odt-name-cell">{s.component}</span>
+							<span class="odt-muted">{fmt(s.averageQueueDelay)}ms avg queue</span>
+						</div>
+					}
+				}
+				<div class="odt-h">Recent commit self-time</div>
+				<div style={{ display: 'flex', alignItems: 'flex-end', gap: '2px', height: '30px' }}>
+					@for (const ev of snapshot.recentEvents; index i) {
+						<span
+							class="odt-bar"
+							title={`${ev.component}: ${fmt(ev.selfDuration)}ms`}
+							style={{
+								width: '7px',
+								height: `${Math.min(28, Math.max(2, (ev.selfDuration / maxSelf) * 28))}px`,
+							}}
+						></span>
+					}
+				</div>
+			</>
+		}
+	</div>;
+}

package/src/panel/PerfModelTab.tsrx.d.ts

@@ -0,0 +1,6 @@
+// Declaration companion for PerfModelTab.tsrx.
+import type { OctaneDevtoolsEventClient } from '../client';
+
+export declare function PerfModelTab(props: { client: OctaneDevtoolsEventClient }): unknown;
+
+export {};

package/src/panel/ProfilerTab.tsrx

@@ -0,0 +1,66 @@
+// The Profiler tab: subscribes to the app-side bridge's `profile` event (startBridge,
+// which reads globalThis.__OCTANE_PROFILER__ per flush) and renders a ranked
+// self-time table plus a recent-commits list. Absent a profiler global on the app
+// side, no `profile` event ever arrives and the tab stays in its empty state.
+import { useEffect, useState } from 'octane';
+import type { OctaneNode } from 'octane';
+import { OctaneDevtoolsEventClient, type ProfileSnapshot } from '../client';
+
+function fmt(ms: number): string {
+	return (Math.round(ms * 10) / 10).toString();
+}
+
+export function ProfilerTab(props: { client: OctaneDevtoolsEventClient }): OctaneNode {
+	const { client } = props;
+	const [snapshot, setSnapshot] = useState<ProfileSnapshot | null>(null);
+
+	useEffect(() => {
+		const off = client.on('profile', (e) => setSnapshot(e.payload));
+		return () => off();
+	});
+
+	return <div>
+		@if (snapshot === null || snapshot.summaries.length === 0) {
+			<div class="odt-empty">No profiling data yet — interact with the app.</div>
+		} @else {
+			<>
+				<div class="odt-h">Slowest components (self time)</div>
+				<table class="odt-table">
+					<thead>
+						<tr>
+							<th>Component</th>
+							<th class="odt-num">Renders</th>
+							<th class="odt-num">Self ms</th>
+							<th class="odt-num">Max ms</th>
+							<th class="odt-num">Queue ms</th>
+							<th>Cause</th>
+						</tr>
+					</thead>
+					<tbody>
+						@for (const s of snapshot.summaries; index i) {
+							<tr>
+								<td class="odt-name-cell">{s.component}</td>
+								<td class="odt-num">{s.attempts}</td>
+								<td class="odt-num">{fmt(s.totalSelfTime)}</td>
+								<td class="odt-num">{fmt(s.maxInclusiveTime)}</td>
+								<td class="odt-num">{fmt(s.averageQueueDelay)}</td>
+								<td class="odt-muted">{(s.dominantCause ?? '-') as string}</td>
+							</tr>
+						}
+					</tbody>
+				</table>
+				<div class="odt-h">Recent commits</div>
+				@for (const ev of snapshot.recentEvents; index i) {
+					<div class="odt-commit-row">
+						{ev.component}
+						·
+						{ev.phase}
+						·
+						{fmt(ev.selfDuration)}ms ·
+						{ev.causes.join(',') || ev.outcome}
+					</div>
+				}
+			</>
+		}
+	</div>;
+}

package/src/panel/ProfilerTab.tsrx.d.ts

@@ -0,0 +1,6 @@
+// Declaration companion for ProfilerTab.tsrx.
+import type { OctaneDevtoolsEventClient } from '../client';
+
+export declare function ProfilerTab(props: { client: OctaneDevtoolsEventClient }): unknown;
+
+export {};

package/src/panel/TransitionsTab.tsrx

@@ -0,0 +1,43 @@
+// The Transitions & Suspense tab: subscribes to the app-side bridge's `transition`
+// event (startBridge, which reads the devtools hook's getTransitionState() per
+// flush) and renders the live pending-transition count plus each Suspense boundary's
+// state. Absent a subscriber-observed hook on the app side, no `transition` event
+// ever arrives and the tab stays in its empty state.
+import { useEffect, useState } from 'octane';
+import type { OctaneNode } from 'octane';
+import { OctaneDevtoolsEventClient, type BoundaryWire, type TransitionSnapshot } from '../client';
+
+function stateClass(b: BoundaryWire): string {
+	if (b.state === 'pending') return 'odt-state odt-state-pending';
+	if (b.state === 'resolved') return 'odt-state odt-state-resolved';
+	if (b.state === 'catch') return 'odt-state odt-state-catch';
+	return 'odt-state odt-state-init';
+}
+
+export function TransitionsTab(props: { client: OctaneDevtoolsEventClient }): OctaneNode {
+	const { client } = props;
+	const [snapshot, setSnapshot] = useState<TransitionSnapshot>({ pendingCount: 0, boundaries: [] });
+
+	useEffect(() => {
+		const off = client.on('transition', (e) => setSnapshot(e.payload));
+		return () => off();
+	});
+
+	return <div>
+		<div class="odt-stat">Pending transitions: {snapshot.pendingCount}</div>
+		<div class="odt-h">Suspense boundaries</div>
+		@if (snapshot.boundaries.length === 0) {
+			<div class="odt-empty">No Suspense boundaries.</div>
+		} @else {
+			@for (const b of snapshot.boundaries; index i) {
+				<div class="odt-boundary">
+					<span class={stateClass(b)}>{b.state}</span>
+					<span>{b.label}</span>
+					@if (b.hasResolved && b.state !== 'resolved') {
+						<span class="odt-muted">resolved once</span>
+					}
+				</div>
+			}
+		}
+	</div>;
+}

package/src/panel/TransitionsTab.tsrx.d.ts

@@ -0,0 +1,6 @@
+// Declaration companion for TransitionsTab.tsrx.
+import type { OctaneDevtoolsEventClient } from '../client';
+
+export declare function TransitionsTab(props: { client: OctaneDevtoolsEventClient }): unknown;
+
+export {};

package/src/panel/styles.ts

@@ -0,0 +1,329 @@
+// Self-contained Octane-branded stylesheet for the DevTools panel. The panel is
+// portaled into the TanStack DevTools host, so the website's `:root` custom
+// properties are not reliably in scope — we inject our own tokens + rules once,
+// namespaced under `.odt-` to avoid collisions with the host. Palette + fonts
+// mirror the Octane website (docs/website/src/routes/__root.tsrx): coral accent
+// #ff415a on dark slate, Inter for UI, SF Mono for values.
+
+export const OCTANE_DEVTOOLS_STYLE_ID = 'octane-devtools-styles';
+
+export const OCTANE_DEVTOOLS_CSS = `
+.odt-root {
+	--odt-bg: #23272f;
+	--odt-panel: #2b3138;
+	--odt-code: #16181d;
+	--odt-text: #f4eee8;
+	--odt-body: #d5d9e0;
+	--odt-sec: #99a1b3;
+	--odt-accent: #ff415a;
+	--odt-accent2: #ff5d72;
+	--odt-on-accent: #16181d;
+	--odt-border: rgba(255, 255, 255, 0.1);
+	--odt-border-strong: rgba(255, 255, 255, 0.22);
+	--odt-surface: rgba(255, 255, 255, 0.06);
+	--odt-subtle: rgba(255, 255, 255, 0.03);
+	--odt-inset: rgba(22, 24, 29, 0.55);
+	--odt-success: #8ae8ae;
+	--odt-warn: #ffc56d;
+	--odt-danger: #ff8797;
+	--odt-mono: 'SF Mono', SFMono-Regular, ui-monospace, Menlo, Consolas, monospace;
+	display: flex;
+	flex-direction: column;
+	height: 100%;
+	min-height: 0;
+	background: var(--odt-bg);
+	color: var(--odt-body);
+	font-family: Inter, system-ui, -apple-system, 'Segoe UI', Roboto, sans-serif;
+	font-size: 12px;
+	line-height: 1.45;
+}
+.odt-tabs {
+	display: flex;
+	flex-wrap: nowrap;
+	align-items: center;
+	gap: 2px;
+	padding: 0 10px;
+	background: var(--odt-panel);
+	border-bottom: 1px solid var(--odt-border);
+	/* Fixed height + flex-basis so the bar can never grow to fill the column
+	   (the host's flex context resolves an auto basis unpredictably here). */
+	flex: 0 0 42px;
+	height: 42px;
+	box-sizing: border-box;
+}
+.odt-tab {
+	appearance: none;
+	border: 0;
+	background: transparent;
+	color: var(--odt-sec);
+	font: inherit;
+	font-weight: 600;
+	letter-spacing: 0.01em;
+	padding: 8px 13px;
+	border-radius: 8px 8px 0 0;
+	cursor: pointer;
+	position: relative;
+	flex: 0 0 auto;
+	align-self: center;
+	height: auto;
+	line-height: 1.3;
+	white-space: nowrap;
+	transition: color 0.12s ease, background 0.12s ease;
+}
+.odt-tab:hover {
+	color: var(--odt-text);
+	background: var(--odt-surface);
+}
+.odt-tab.odt-tab-active {
+	color: var(--odt-text);
+}
+.odt-tab.odt-tab-active::after {
+	content: '';
+	position: absolute;
+	left: 10px;
+	right: 10px;
+	bottom: -1px;
+	height: 2px;
+	border-radius: 2px 2px 0 0;
+	background: var(--odt-accent);
+	box-shadow: 0 0 10px rgba(255, 65, 90, 0.55);
+}
+.odt-body {
+	flex: 1 1 0;
+	min-height: 0;
+	overflow: auto;
+	padding: 12px 14px;
+}
+.odt-split {
+	display: flex;
+	gap: 12px;
+	height: 100%;
+	min-height: 0;
+}
+.odt-col {
+	flex: 1 1 0;
+	min-width: 0;
+	overflow: auto;
+}
+.odt-col-tree {
+	flex: 0 0 46%;
+	border-right: 1px solid var(--odt-border);
+	padding-right: 12px;
+}
+.odt-h {
+	margin: 0 0 8px;
+	font-size: 10px;
+	font-weight: 700;
+	text-transform: uppercase;
+	letter-spacing: 0.08em;
+	color: var(--odt-sec);
+}
+.odt-h + .odt-h {
+	margin-top: 14px;
+}
+.odt-empty {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+	color: var(--odt-sec);
+	font-style: normal;
+	padding: 10px 2px;
+}
+.odt-empty::before {
+	content: '';
+	width: 7px;
+	height: 7px;
+	border-radius: 50%;
+	background: var(--odt-accent);
+	opacity: 0.65;
+	flex: 0 0 auto;
+}
+/* Component tree */
+.odt-tree-row {
+	appearance: none;
+	border: 0;
+	width: 100%;
+	text-align: left;
+	background: transparent;
+	color: var(--odt-body);
+	font-family: var(--odt-mono);
+	font-size: 11.5px;
+	padding: 3px 6px;
+	border-radius: 6px;
+	cursor: pointer;
+	display: flex;
+	align-items: center;
+	gap: 6px;
+	transition: background 0.1s ease, color 0.1s ease;
+}
+.odt-tree-row:hover {
+	background: var(--odt-surface);
+	color: var(--odt-text);
+}
+.odt-tree-row.odt-selected {
+	background: rgba(255, 65, 90, 0.16);
+	color: var(--odt-text);
+	box-shadow: inset 2px 0 0 var(--odt-accent);
+}
+.odt-kind {
+	font-size: 9px;
+	font-weight: 700;
+	text-transform: uppercase;
+	letter-spacing: 0.04em;
+	color: var(--odt-sec);
+	background: var(--odt-surface);
+	border-radius: 4px;
+	padding: 1px 5px;
+	flex: 0 0 auto;
+}
+.odt-kind-root {
+	color: var(--odt-on-accent);
+	background: var(--odt-accent);
+}
+.odt-child {
+	margin-left: 12px;
+	border-left: 1px solid var(--odt-border);
+	padding-left: 4px;
+}
+/* Inspector */
+.odt-node-name {
+	margin: 0 0 10px;
+	font-family: var(--odt-mono);
+	font-size: 13px;
+	font-weight: 600;
+	color: var(--odt-text);
+}
+.odt-badge {
+	display: inline-block;
+	font-size: 10px;
+	font-weight: 600;
+	color: var(--odt-sec);
+	background: var(--odt-surface);
+	border: 1px solid var(--odt-border);
+	border-radius: 999px;
+	padding: 1px 8px;
+	margin-left: 8px;
+}
+.odt-kv {
+	font-family: var(--odt-mono);
+	font-size: 11.5px;
+	background: var(--odt-inset);
+	border: 1px solid var(--odt-border);
+	border-radius: 7px;
+	padding: 6px 9px;
+	margin-bottom: 5px;
+	overflow-x: auto;
+	white-space: pre;
+}
+.odt-kv-key {
+	color: var(--odt-accent2);
+	font-weight: 600;
+}
+.odt-kv-val {
+	color: var(--odt-body);
+}
+/* Tables (profiler / performance) */
+.odt-table {
+	width: 100%;
+	border-collapse: collapse;
+	font-family: var(--odt-mono);
+	font-size: 11px;
+	margin-bottom: 14px;
+}
+.odt-table th {
+	text-align: left;
+	font-weight: 600;
+	color: var(--odt-sec);
+	border-bottom: 1px solid var(--odt-border-strong);
+	padding: 4px 8px;
+	position: sticky;
+	top: 0;
+	background: var(--odt-bg);
+}
+.odt-table td {
+	padding: 3px 8px;
+	border-bottom: 1px solid var(--odt-subtle);
+	color: var(--odt-body);
+}
+.odt-table tr:hover td {
+	background: var(--odt-surface);
+}
+.odt-num {
+	text-align: right;
+	font-variant-numeric: tabular-nums;
+	color: var(--odt-text);
+}
+.odt-name-cell {
+	color: var(--odt-text);
+	font-weight: 600;
+}
+.odt-bar {
+	display: inline-block;
+	height: 6px;
+	border-radius: 3px;
+	background: linear-gradient(90deg, var(--odt-accent), var(--odt-accent2));
+	vertical-align: middle;
+}
+.odt-commit-row {
+	display: flex;
+	align-items: center;
+	gap: 8px;
+	font-family: var(--odt-mono);
+	font-size: 11px;
+	padding: 2px 0;
+	color: var(--odt-body);
+}
+/* Transitions & Suspense */
+.odt-stat {
+	font-family: var(--odt-mono);
+	font-size: 14px;
+	font-weight: 600;
+	color: var(--odt-accent2);
+	margin-bottom: 14px;
+	padding: 8px 10px;
+	background: var(--odt-inset);
+	border: 1px solid var(--odt-border);
+	border-radius: 8px;
+}
+.odt-boundary {
+	display: flex;
+	align-items: center;
+	gap: 9px;
+	padding: 6px 8px;
+	border: 1px solid var(--odt-border);
+	border-radius: 8px;
+	background: var(--odt-subtle);
+	margin-bottom: 5px;
+	font-family: var(--odt-mono);
+	font-size: 11.5px;
+	color: var(--odt-text);
+}
+.odt-state {
+	font-size: 9.5px;
+	font-weight: 700;
+	text-transform: uppercase;
+	letter-spacing: 0.05em;
+	border-radius: 999px;
+	padding: 2px 8px;
+	flex: 0 0 auto;
+}
+.odt-state-pending {
+	color: #3a2c00;
+	background: var(--odt-warn);
+}
+.odt-state-resolved {
+	color: #05321a;
+	background: var(--odt-success);
+}
+.odt-state-catch {
+	color: #3a0510;
+	background: var(--odt-danger);
+}
+.odt-state-init {
+	color: var(--odt-body);
+	background: var(--odt-surface);
+}
+.odt-muted {
+	color: var(--odt-sec);
+}
+`;