@playfast/reform-profiler 1.0.1 → 1.1.0

package/package.json

@@ -1,25 +1,28 @@
 {
   "name": "@playfast/reform-profiler",
-  "playbook": "./playbook",
-  "version": "1.0.1",
-  "type": "module",
+  "version": "1.1.0",
   "description": "Performance profiler for reform scenes — a recording Instrumentation, Chrome DevTools trace export, terminal reports, and a React overlay. Dev builds get the real recorder; prod builds resolve to no-op stubs.",
   "keywords": [
-    "reform",
+    "devtools",
     "effect",
-    "profiler",
     "performance",
-    "devtools"
+    "profiler",
+    "reform"
   ],
+  "bugs": {
+    "url": "https://github.com/playfast/reform/issues"
+  },
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/playfast/reform.git",
     "directory": "packages/reform-profiler"
   },
-  "bugs": {
-    "url": "https://github.com/playfast/reform/issues"
-  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "type": "module",
   "sideEffects": false,
   "exports": {
     "./package.json": "./package.json",
@@ -33,10 +36,9 @@
     },
     "./recorder": "./src/index.ts"
   },
-  "files": [
-    "src",
-    "README.md"
-  ],
+  "publishConfig": {
+    "access": "public"
+  },
   "scripts": {
     "clean": "rm -rf dist .tsbuildinfo",
     "check": "tsc --noEmit",
@@ -48,8 +50,8 @@
     "lint:fix": "oxlint --fix src"
   },
   "peerDependencies": {
-    "effect": "*",
     "@playfast/reform": "*",
+    "effect": "*",
     "react": "^19.0.0"
   },
   "peerDependenciesMeta": {
@@ -57,7 +59,5 @@
       "optional": true
     }
   },
-  "publishConfig": {
-    "access": "public"
-  }
+  "playbook": "./playbook"
 }

package/src/index.ts

@@ -1,8 +1,3 @@
-// @playfast/reform-profiler — the REAL entry, resolved under the `development`
-// export condition (and unconditionally via `./recorder`, for tests and
-// headless scripts whose runner doesn't set dev conditions). Production
-// bundles resolve `.` to `./noop.ts` instead.
-
 export {
   makeProfiler,
   type ProfileKind,
@@ -12,7 +7,7 @@ export {
   type ProfileSnapshot,
   type ProfileStat,
 } from './recorder'
-export { type ProfiledScene, profileScene } from './profileScene'
+export { type CapturedProfiledScene, type ProfiledScene, profileScene } from './profileScene'
 export { type ChromeTrace, type ChromeTraceEvent, toChromeTrace, traceJson } from './trace'
 export { formatReport } from './report'
 export {

package/src/noop.ts

@@ -1,18 +1,11 @@
-import { noopInstrumentation, type Scene, type UiContract } from '@playfast/reform'
-import type { ProfiledScene } from './profileScene'
-import type {
-  ProfilerHandle,
-  ProfilerOptionsExternalApi,
-  ProfileSnapshot,
-} from './recorder'
+import { type CapturedScene, type Scene, type UiContract } from '@playfast/reform'
+import { noopInstrumentation } from '@playfast/reform/internal'
+import type { CapturedProfiledScene, ProfiledScene } from './profileScene'
+import type { ProfilerHandle, ProfilerOptionsExternalApi, ProfileSnapshot } from './recorder'
 import type { ProfilerRegistration } from './registry'
 import type { ChromeTrace } from './trace'
 
-// @playfast/reform-profiler — the PRODUCTION stub, resolved under the
-// `default` export condition. Same surface as `./index.ts`, zero recording:
-// `profileScene` hands the scene back untouched, every reader yields empty
-// data, and none of the recorder/trace/report machinery is reachable from a
-// prod bundle. Types re-export from the real modules (erased at runtime).
+// Production stub (`default` export condition): same surface, zero recording.
 
 export type {
   ProfileKind,
@@ -22,7 +15,7 @@ export type {
   ProfileSnapshot,
   ProfileStat,
 } from './recorder'
-export type { ProfiledScene } from './profileScene'
+export type { CapturedProfiledScene, ProfiledScene } from './profileScene'
 export type { ChromeTrace, ChromeTraceEvent } from './trace'
 export type { ProfilerRegistration } from './registry'
 
@@ -39,7 +32,6 @@ const emptySnapshot: ProfileSnapshot = {
   dropped: 0,
 }
 
-/** The shared inert handle every stub call hands back. */
 export const noopProfiler: ProfilerHandle = {
   ...noopInstrumentation,
   label: 'noop',
@@ -52,10 +44,45 @@ export const noopProfiler: ProfilerHandle = {
 export const makeProfiler = (_options: ProfilerOptionsExternalApi = {}): ProfilerHandle =>
   noopProfiler
 
-export const profileScene = <C extends UiContract, S extends ReadonlyArray<unknown>>(
+const profileCapturedScene = <
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  base: CapturedScene<C, S, Services, P, N, Identity>,
+): CapturedProfiledScene<C, S, Services, P, N, Identity> => ({
+  scene: base,
+  profiler: noopProfiler,
+})
+
+export function profileScene<
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  base: CapturedScene<C, S, Services, P, N, Identity>,
+  _options?: ProfilerOptionsExternalApi,
+): CapturedProfiledScene<C, S, Services, P, N, Identity>
+export function profileScene<C extends UiContract, S extends ReadonlyArray<unknown>>(
+  base: Scene<C, S>,
+  _options?: ProfilerOptionsExternalApi,
+): ProfiledScene<C, S>
+export function profileScene<C extends UiContract, S extends ReadonlyArray<unknown>>(
   base: Scene<C, S>,
   _options: ProfilerOptionsExternalApi = {},
-): ProfiledScene<C, S> => ({ scene: base, profiler: noopProfiler })
+): ProfiledScene<C, S> {
+  return base.capture<ProfiledScene<C, S>>(
+    <Services, P, N extends string, Identity>(
+      exactScene: CapturedScene<C, S, Services, P, N, Identity>,
+    ): ProfiledScene<C, S> => profileCapturedScene(exactScene),
+  )
+}
 
 const emptyTrace: ChromeTrace = { traceEvents: [], displayTimeUnit: 'ms' }
 
@@ -66,11 +93,15 @@ export const traceJson = (_profiler: ProfilerHandle): string =>
 
 export const formatReport = (_profiler: ProfilerHandle): string => ''
 
-export const registerProfiler = (_registration: ProfilerRegistration): (() => void) => () => {}
+export const registerProfiler =
+  (_registration: ProfilerRegistration): (() => void) =>
+  () => {}
 
 export const listProfilers = (): ReadonlyArray<ProfilerRegistration> => []
 
-export const subscribeProfilers = (_listener: () => void): (() => void) => () => {}
+export const subscribeProfilers =
+  (_listener: () => void): (() => void) =>
+  () => {}
 
 export const profilersVersion = (): number => 0
 

package/src/profileScene.ts

@@ -1,9 +1,9 @@
 import { Effect, Layer } from 'effect'
-import { profiledScene, type Scene, type UiContract } from '@playfast/reform'
+import { type CapturedScene, profiledScene, type Scene, type UiContract } from '@playfast/reform'
+import { type AnySceneCapture, type SceneCapture } from '@playfast/reform/internal'
 import { makeProfiler, type ProfilerHandle, type ProfilerOptionsExternalApi } from './recorder'
 import { registerProfiler } from './registry'
 
-/** A scene wired to record into `profiler`, plus the handle to read it back. */
 export interface ProfiledScene<
   C extends UiContract = UiContract,
   S extends ReadonlyArray<unknown> = ReadonlyArray<unknown>,
@@ -12,45 +12,94 @@ export interface ProfiledScene<
   readonly profiler: ProfilerHandle
 }
 
-/**
- * Opt a CLOSED scene into profiling: every engine hook (events, reducers,
- * states, calcs, queries, procedures) records into a fresh profiler, and hosts
- * (React `Compose`, the proof engine) pick it up for render spans via
- * `sceneInstrumentation`. The original scene is untouched — hand the returned
- * `scene` to `<Reform/>`, `drive`, or `makeAppRuntime`.
- *
- * The profiler registers in the overlay registry while a runtime built from
- * the scene is live (register on layer build, unregister on scope close), so
- * `<ReformProfiler/>` shows one tab per live profiled runtime.
- *
- * In a production build (`default` export condition) this module is replaced
- * by a passthrough stub — the scene comes back untouched and the handle is a
- * shared no-op.
- */
-export const profileScene = <C extends UiContract, S extends ReadonlyArray<unknown>>(
+export interface CapturedProfiledScene<
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+> extends ProfiledScene<C, S> {
+  readonly scene: CapturedScene<C, S, Services, P, N, Identity>
+}
+
+const makeLifecycle = (profiler: ProfilerHandle) =>
+  Layer.scopedDiscard(
+    Effect.acquireRelease(
+      Effect.sync(() => registerProfiler({ label: profiler.label, handle: profiler })),
+      (unregister) => Effect.sync(unregister),
+    ),
+  )
+
+const withLifecycle = <
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  base: CapturedScene<C, S, Services, P, N, Identity>,
+  lifecycle: ReturnType<typeof makeLifecycle>,
+): CapturedScene<C, S, Services, P, N, Identity> => {
+  const captured: CapturedScene<C, S, Services, P, N, Identity> = {
+    kind: 'Scene',
+    composition: base.composition,
+    // Lifecycle on the first provide layer tracks the runtime's build/dispose scope.
+    provide: base.provide.map((layer, index) =>
+      index === 0 ? Layer.merge(layer, lifecycle) : layer,
+    ),
+    ...(base.boot === undefined ? {} : { boot: base.boot }),
+    ...(base.instrumentation === undefined ? {} : { instrumentation: base.instrumentation }),
+    capture: <Result>(capture: SceneCapture<C, S, Result>): Result => capture(captured),
+    captureAny: <Result>(capture: AnySceneCapture<Result>): Result => capture(captured),
+  }
+  return captured
+}
+
+const profileCapturedScene = <
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  base: CapturedScene<C, S, Services, P, N, Identity>,
+  profiler: ProfilerHandle,
+  lifecycle: ReturnType<typeof makeLifecycle>,
+): CapturedProfiledScene<C, S, Services, P, N, Identity> => ({
+  scene: withLifecycle(profiledScene(base, profiler), lifecycle),
+  profiler,
+})
+
+export function profileScene<
+  C extends UiContract,
+  S extends ReadonlyArray<unknown>,
+  Services,
+  P,
+  N extends string,
+  Identity,
+>(
+  base: CapturedScene<C, S, Services, P, N, Identity>,
+  options?: ProfilerOptionsExternalApi,
+): CapturedProfiledScene<C, S, Services, P, N, Identity>
+export function profileScene<C extends UiContract, S extends ReadonlyArray<unknown>>(
+  base: Scene<C, S>,
+  options?: ProfilerOptionsExternalApi,
+): ProfiledScene<C, S>
+export function profileScene<C extends UiContract, S extends ReadonlyArray<unknown>>(
   base: Scene<C, S>,
   options: ProfilerOptionsExternalApi = {},
-): ProfiledScene<C, S> => {
+): ProfiledScene<C, S> {
   const profiler = makeProfiler({
     label: options.label ?? base.composition.manifest.title,
     ...(options.capacity !== undefined ? { capacity: options.capacity } : {}),
   })
-  const lifecycle = Layer.scopedDiscard(
-    Effect.acquireRelease(
-      Effect.sync(() => registerProfiler({ label: profiler.label, handle: profiler })),
-      (unregister) => Effect.sync(unregister),
-    ),
+  const lifecycle = makeLifecycle(profiler)
+  return base.capture<ProfiledScene<C, S>>(
+    <Services, P, N extends string, Identity>(
+      exactScene: CapturedScene<C, S, Services, P, N, Identity>,
+    ): ProfiledScene<C, S> => profileCapturedScene(exactScene, profiler, lifecycle),
   )
-  const wrapped = profiledScene(base, profiler)
-  return {
-    // The lifecycle layer rides the first provide layer (`merge` keeps its
-    // services), so registration follows the runtime's real build/dispose.
-    scene: {
-      ...wrapped,
-      provide: wrapped.provide.map((layer, index) =>
-        index === 0 ? Layer.merge(layer, lifecycle) : layer,
-      ),
-    },
-    profiler,
-  }
 }

package/src/profiler.test.ts

@@ -24,8 +24,6 @@ import { formatReport } from './report'
 
 const settle = (ms = 20) => new Promise((resolve) => setTimeout(resolve, ms))
 
-// ── recorder ──────────────────────────────────────────────────────────────────
-
 test('aggregates count and time per name, per kind', () => {
   const profiler = makeProfiler({ label: 'agg' })
   profiler.eventDispatched('Bumped', 'High')
@@ -53,7 +51,6 @@ test('the ring buffer wraps: newest records survive, aggregates keep the full ta
   const snapshot = profiler.snapshot()
   expect(snapshot.records.map((record) => record.name)).toEqual(['c', 'd', 'e', 'f'])
   expect(snapshot.dropped).toBe(2)
-  // Evicted records still count in the aggregates.
   expect(snapshot.events.size).toBe(6)
   expect(snapshot.events.get('a')?.count).toBe(1)
 })
@@ -87,8 +84,6 @@ test('subscribers are notified once per burst (coalesced)', async () => {
   expect(calls.count).toBe(1)
 })
 
-// ── trace export ──────────────────────────────────────────────────────────────
-
 test('toChromeTrace emits metadata lanes, X spans, and i instants', () => {
   const profiler = makeProfiler({ label: 'traced' })
   profiler.eventDispatched('Bumped', 'High')
@@ -112,8 +107,6 @@ test('toChromeTrace emits metadata lanes, X spans, and i instants', () => {
   expect(parsed).toEqual(trace)
 })
 
-// ── profileScene end-to-end over the headless app runtime ────────────────────
-
 class Count extends State.make('profiler-count', S.Number) {}
 class States extends StateGroup.make(Count) {}
 class Bumped extends Event.make('ProfilerBumped', S.Struct({})) {}
@@ -121,19 +114,25 @@ class Bump extends Reducer.make('ProfilerBump', { states: [Count], events: [Bump
 const BumpLive = Reducer.live(Bump, (n) => n + 1)
 
 class RootUi extends ui('ProfilerRoot')<{ props: { count: number } }>() {}
+
 class Root extends Composition.make('ProfilerRoot', {
   title: 'ProfilerRoot',
   states: [States],
   events: [Bumped],
   ui: RootUi,
-}) {}
+})<Root>() {}
 const RootLive = Composition.live(Root, function* () {
   const count = yield* StateGroup.select(States, 'profiler-count')
   return mount({ props: { count }, slots: {} })
 })
 
 const app = RootLive.pipe(
-  Layer.provideMerge(provide(RootUi, Ui.make(RootUi, () => null))),
+  Layer.provideMerge(
+    provide(
+      RootUi,
+      Ui.make(RootUi, () => null),
+    ),
+  ),
   Layer.provideMerge(
     Layer.mergeAll(BumpLive).pipe(
       Layer.provideMerge(Layer.mergeAll(Engine, StateGroup.live(States, { 'profiler-count': 0 }))),
@@ -168,7 +167,6 @@ test('profileScene records engine activity through makeAppRuntime and registers
   await settle()
   expect(listProfilers().map((entry) => entry.handle)).not.toContain(profiler)
 
-  // The base scene is untouched: no instrumentation carrier, nothing recorded.
   const before = profiler.snapshot().events.get('ProfilerBumped')?.count
   const plain = makeAppRuntime(baseScene)
   plain.dispatch('High', Event.construct(Bumped, {}))

package/src/react/index.ts

@@ -1,5 +1 @@
-// @playfast/reform-profiler/react — dev entry (`development` export condition).
-// The floating profiler panel plus the browser trace download. The prod build
-// resolves `./noop.ts` instead, so none of this reaches a production bundle.
-
 export { downloadTrace, ReformProfiler } from './overlay'

package/src/react/noop.ts

@@ -1,9 +1,6 @@
 import type { ReactNode } from 'react'
 import type { ProfilerHandle } from '../recorder'
 
-// @playfast/reform-profiler/react — the PRODUCTION stub (`default` export
-// condition). `<ReformProfiler/>` renders nothing; `downloadTrace` is inert.
-
 export const ReformProfiler = (): ReactNode => null
 
 export const downloadTrace = (_profiler: ProfilerHandle): void => {}

package/src/react/overlay.tsx

@@ -24,12 +24,7 @@ import {
   tabStyle,
 } from './styles'
 
-// <ReformProfiler/> — the dev overlay. Plain React + useSyncExternalStore, NOT
-// built on reform: the profiler must not profile itself. One floating panel per
-// page (singleton election through the registry), one tab per live profiled
-// runtime, per-kind aggregate tables, Chrome-trace export, clear.
-
-/** Save the profiler's Chrome DevTools trace as a `.json` download (browser only). */
+// Plain React (not reform) so the profiler does not profile itself.
 export const downloadTrace = (profiler: ProfilerHandle): void => {
   const blob = new Blob([traceJson(profiler)], { type: 'application/json' })
   const url = URL.createObjectURL(blob)
@@ -40,8 +35,6 @@ export const downloadTrace = (profiler: ProfilerHandle): void => {
   URL.revokeObjectURL(url)
 }
 
-// ── data shaping ─────────────────────────────────────────────────────────────
-
 interface Row {
   readonly name: string
   readonly stat: ProfileStat
@@ -62,7 +55,6 @@ const avgMs = (stat: ProfileStat): string =>
 interface SectionProps {
   readonly title: string
   readonly rows: ReadonlyArray<Row>
-  /** Timed sections get total/avg columns; instant sections only a count. */
   readonly timed: boolean
 }
 
@@ -105,7 +97,9 @@ const DroppedNote = ({ count }: DroppedNoteProps): ReactNode => {
   if (count === 0) {
     return null
   }
-  return <div style={{ color: palette.dim }}>({count} early records evicted from the ring buffer)</div>
+  return (
+    <div style={{ color: palette.dim }}>({count} early records evicted from the ring buffer)</div>
+  )
 }
 
 interface ProfilerBodyProps {
@@ -137,13 +131,6 @@ const ProfilerBody = ({ profiler }: ProfilerBodyProps): ReactNode => {
   )
 }
 
-// ── the overlay ──────────────────────────────────────────────────────────────
-
-/**
- * The profiler panel. Render it once anywhere in the page (outside `<Reform>` —
- * it is not a reform composition); it shows one tab per live `profileScene`d
- * runtime. Extra instances render nothing until the elected one unmounts.
- */
 export const ReformProfiler = (): ReactNode => {
   const owner = useRef({}).current
   const [claimed, setClaimed] = useState(false)

package/src/react/styles.ts

@@ -1,8 +1,5 @@
 import type { CSSProperties } from 'react'
 
-// Inline styles for the overlay panel — the profiler carries no CSS dependency
-// and must not disturb the host page (fixed position, own stacking context).
-
 interface Palette {
   readonly bg: string
   readonly panel: string

package/src/recorder.ts

@@ -1,14 +1,5 @@
-import { type Instrumentation, makeScheduler, type SpanEnd } from '@playfast/reform'
+import { type Instrumentation, makeScheduler, type SpanEnd } from '@playfast/reform/internal'
 
-// The recording Instrumentation. One profiler per profiled scene: every engine
-// hook appends a fixed-shape record into a ring buffer and folds it into a
-// per-name aggregate, then coalesces subscriber notifications through core's
-// microtask scheduler — so the overlay re-renders once per burst, not per event.
-// All hot-path work is synchronous and allocation-light (one record object, one
-// aggregate fold); the buffer is fixed-size so a long session cannot grow
-// memory unboundedly (old records are evicted, aggregates keep the full tally).
-
-/** What a record measures. `event`/`state` are instants; the rest are spans. */
 export type ProfileKind =
   | 'event'
   | 'reducer'
@@ -21,23 +12,17 @@ export type ProfileKind =
 
 export interface ProfileRecord {
   readonly kind: ProfileKind
-  /** The definition name — event tag, reducer/calc/query/procedure/composition name. */
   readonly name: string
-  /** Context: the trigger tag, `channel:tag`, priority, or frame event count. Empty when none. */
   readonly detail: string
-  /** Start in ms since the page/process time origin (`performance.now()`). */
   readonly start: number
-  /** Duration in ms; `0` for instant records. */
   readonly dur: number
 }
 
-/** Aggregate for one name within a kind. Instant kinds carry `totalMs: 0`. */
 export interface ProfileStat {
   readonly count: number
   readonly totalMs: number
 }
 
-/** A consistent copy of everything recorded so far. */
 export interface ProfileSnapshot {
   readonly events: ReadonlyMap<string, ProfileStat>
   readonly reducers: ReadonlyMap<string, ProfileStat>
@@ -47,33 +32,20 @@ export interface ProfileSnapshot {
   readonly procedures: ReadonlyMap<string, ProfileStat>
   readonly renders: ReadonlyMap<string, ProfileStat>
   readonly frames: ProfileStat
-  /** Raw records, oldest → newest, at most `capacity` of them. */
   readonly records: ReadonlyArray<ProfileRecord>
-  /** Records evicted by the ring buffer (aggregates still include them). */
   readonly dropped: number
 }
 
-// Boundary config object: optional fields are the public, JSON-like surface
-// (`ExternalApi` postfix exempts them from `no-optional-fields`).
 export interface ProfilerOptionsExternalApi {
-  /** Tab title in the overlay / report heading. Defaults to the scene's composition title. */
   readonly label?: string
-  /** Ring-buffer size in records (default 50,000). Aggregates are unaffected. */
   readonly capacity?: number
 }
 
-/**
- * The live profiler: a recording {@link Instrumentation} plus the read side the
- * overlay, trace export, and reports consume. `subscribe`/`getVersion` follow
- * the `useSyncExternalStore` contract (notifications microtask-coalesced).
- */
 export interface ProfilerHandle extends Instrumentation {
   readonly label: string
   readonly snapshot: () => ProfileSnapshot
-  /** Drop all records and aggregates (the overlay's Clear button). */
   readonly clear: () => void
   readonly subscribe: (listener: () => void) => () => void
-  /** Monotone change counter — bumped once per recorded entry and per `clear`. */
   readonly getVersion: () => number
 }
 
@@ -84,8 +56,7 @@ const DEFAULT_CAPACITY = 50_000
 export const makeProfiler = (options: ProfilerOptionsExternalApi = {}): ProfilerHandle => {
   const capacity = Math.max(1, options.capacity ?? DEFAULT_CAPACITY)
   const label = options.label ?? 'reform'
-  // Ring buffer: fixed slots + a monotone write counter (`written % capacity`
-  // is the next slot). In-place-mutated latch object, like the hosts' `status`.
+  // Fixed ring: written % capacity is next slot; aggregates keep full tally when records evict.
   const emptyBuffer = (): Array<ProfileRecord | undefined> =>
     Array.from({ length: capacity }, (): ProfileRecord | undefined => undefined)
   const cursor = { buffer: emptyBuffer(), written: 0, version: 0 }
@@ -122,8 +93,7 @@ export const makeProfiler = (options: ProfilerOptionsExternalApi = {}): Profiler
     readonly detail: string
   }
 
-  const instant = (site: Site): void =>
-    record({ ...site, start: performance.now(), dur: 0 })
+  const instant = (site: Site): void => record({ ...site, start: performance.now(), dur: 0 })
 
   const span = (site: Site): SpanEnd => {
     const start = performance.now()
@@ -168,7 +138,6 @@ export const makeProfiler = (options: ProfilerOptionsExternalApi = {}): Profiler
     },
     getVersion: () => cursor.version,
 
-    // ── Instrumentation ────────────────────────────────────────────────────
     eventDispatched: (tag, priority) => instant({ kind: 'event', name: tag, detail: priority }),
     reducerRun: (name, eventTag) => span({ kind: 'reducer', name, detail: eventTag }),
     stateUpdated: (name) => instant({ kind: 'state', name, detail: '' }),

package/src/registry.ts

@@ -1,10 +1,7 @@
 import { GlobalValue, Option } from 'effect'
 import type { ProfilerHandle } from './recorder'
 
-// Module-level registry of the profilers whose runtimes are currently live.
-// The overlay reads it to render one tab per profiled runtime; `profileScene`
-// registers on layer build and unregisters when the runtime's scope closes.
-// Kept in a `globalValue` so duplicated bundles / HMR share one registry.
+// globalValue so duplicated bundles / HMR share one registry.
 
 export interface ProfilerRegistration {
   readonly label: string
@@ -12,11 +9,13 @@ export interface ProfilerRegistration {
 }
 
 interface RegistryState {
-  /** Live registrations with a build refcount (StrictMode double-builds share one entry). */
-  readonly entries: Map<ProfilerHandle, { readonly registration: ProfilerRegistration; readonly count: number }>
+  // Refcount: StrictMode double-build shares one entry.
+  readonly entries: Map<
+    ProfilerHandle,
+    { readonly registration: ProfilerRegistration; readonly count: number }
+  >
   readonly listeners: Set<() => void>
   readonly version: { current: number }
-  /** The overlay instance currently elected to render the panel. */
   readonly overlay: { owner: Option.Option<object> }
 }
 
@@ -35,11 +34,6 @@ const notify = (): void => {
   ;[...state.listeners].forEach((listener) => listener())
 }
 
-/**
- * Register a live profiler. Refcounted by handle: the same profiler built twice
- * (React StrictMode) stays one tab, and disappears when the LAST build closes.
- * Returns the matching unregister.
- */
 export const registerProfiler = (registration: ProfilerRegistration): (() => void) => {
   const existing = state.entries.get(registration.handle)
   state.entries.set(registration.handle, {
@@ -63,11 +57,9 @@ export const registerProfiler = (registration: ProfilerRegistration): (() => voi
   }
 }
 
-/** The live registrations, in registration order. */
 export const listProfilers = (): ReadonlyArray<ProfilerRegistration> =>
   [...state.entries.values()].map((entry) => entry.registration)
 
-/** Subscribe to registry changes (register/unregister). Sync, rare. */
 export const subscribeProfilers = (listener: () => void): (() => void) => {
   state.listeners.add(listener)
   return () => {
@@ -75,14 +67,9 @@ export const subscribeProfilers = (listener: () => void): (() => void) => {
   }
 }
 
-/** Monotone registry change counter (`useSyncExternalStore` snapshot). */
 export const profilersVersion = (): number => state.version.current
 
-/**
- * Singleton election for the overlay panel: the first mounted `<ReformProfiler/>`
- * claims rendering; later instances render nothing. Returns true when `owner`
- * holds the claim (idempotent for the current claimant).
- */
+// First mounted overlay claims render; later instances no-op until claim released.
 export const claimOverlay = (owner: object): boolean => {
   if (Option.isNone(state.overlay.owner)) {
     state.overlay.owner = Option.some(owner)
@@ -91,7 +78,6 @@ export const claimOverlay = (owner: object): boolean => {
   return Option.contains(state.overlay.owner, owner)
 }
 
-/** Release the panel claim so the next mounted instance can take over. */
 export const releaseOverlay = (owner: object): void => {
   if (Option.contains(state.overlay.owner, owner)) {
     state.overlay.owner = Option.none()

package/src/report.ts

@@ -1,8 +1,5 @@
 import type { ProfilerHandle, ProfileStat } from './recorder'
 
-// Terminal report — the overlay's tables as aligned plain text, so a headless
-// drive script can `console.log(formatReport(profiler))` after a scenario.
-
 interface Row {
   readonly name: string
   readonly stat: ProfileStat
@@ -18,8 +15,6 @@ const sortedRows = (stats: ReadonlyMap<string, ProfileStat>): ReadonlyArray<Row>
 const MS_DECIMALS = 2
 const formatMs = (durationMs: number): string => durationMs.toFixed(MS_DECIMALS)
 
-// Fixed column widths: fit the 'count'/'total ms'/'avg ms' headers plus room
-// for six digits; the name column stretches to the longest name per section.
 const COUNT_WIDTH = 7
 const TOTAL_WIDTH = 9
 const AVG_WIDTH = 8
@@ -28,7 +23,6 @@ const ruleOverhead = '── '.length + ' '.length
 interface Section {
   readonly title: string
   readonly rows: ReadonlyArray<Row>
-  /** Timed sections get total/avg columns; instant sections only a count. */
   readonly timed: boolean
 }
 
@@ -53,7 +47,6 @@ const section = ({ title, rows, timed }: Section): ReadonlyArray<string> => {
   ]
 }
 
-/** The profile so far as aligned text tables, one section per non-empty kind. */
 export const formatReport = (profiler: ProfilerHandle): string => {
   const snapshot = profiler.snapshot()
   const frameRows: ReadonlyArray<Row> =

package/src/trace.ts

@@ -1,12 +1,5 @@
 import type { ProfileKind, ProfilerHandle } from './recorder'
 
-// Chrome DevTools trace export — the Trace Event Format (`ph:'X'` complete
-// events on named thread lanes, `ph:'i'` instants, `ph:'M'` metadata). The
-// output loads in the Chrome DevTools Performance panel ("Load profile…") and
-// in Perfetto. Platform-neutral: headless scripts `Bun.write('trace.json',
-// traceJson(profiler))`; the browser download button lives in the react entry.
-
-/** One Trace Event Format entry. Times are µs. */
 export type ChromeTraceEvent =
   | {
       readonly ph: 'X'
@@ -42,7 +35,6 @@ export interface ChromeTrace {
   readonly displayTimeUnit: 'ms'
 }
 
-// One thread lane per kind, so the Performance panel shows parallel tracks.
 const lanes: Record<ProfileKind, { readonly tid: number; readonly title: string }> = {
   frame: { tid: 1, title: 'frames' },
   event: { tid: 2, title: 'events' },
@@ -59,11 +51,17 @@ const instantKinds: ReadonlySet<ProfileKind> = new Set(['event', 'state'])
 const pid = 1
 const US_PER_MS = 1000
 
-/** Project the profiler's raw records into a Chrome DevTools trace object. */
 export const toChromeTrace = (profiler: ProfilerHandle): ChromeTrace => {
   const { records } = profiler.snapshot()
   const meta: ReadonlyArray<ChromeTraceEvent> = [
-    { ph: 'M', name: 'process_name', ts: 0, pid, tid: 0, args: { name: `reform: ${profiler.label}` } },
+    {
+      ph: 'M',
+      name: 'process_name',
+      ts: 0,
+      pid,
+      tid: 0,
+      args: { name: `reform: ${profiler.label}` },
+    },
     ...Object.values(lanes).map(
       (lane): ChromeTraceEvent => ({
         ph: 'M',
@@ -80,14 +78,23 @@ export const toChromeTrace = (profiler: ProfilerHandle): ChromeTrace => {
     const cat = record.kind
     const tid = lanes[record.kind].tid
     const args = record.detail === '' ? {} : { detail: record.detail }
+    const complete: ChromeTraceEvent = {
+      ph: 'X',
+      name: record.name,
+      cat,
+      ts: startUs,
+      dur: record.dur * US_PER_MS,
+      pid,
+      tid,
+      args,
+    }
     return instantKinds.has(record.kind)
       ? { ph: 'i', name: record.name, cat, ts: startUs, pid, tid, s: 't', args }
-      : { ph: 'X', name: record.name, cat, ts: startUs, dur: record.dur * US_PER_MS, pid, tid, args }
+      : complete
   })
   return { traceEvents: [...meta, ...body], displayTimeUnit: 'ms' }
 }
 
-/** `toChromeTrace` as a JSON string, ready to write to a `.json` file. */
 export const traceJson = (profiler: ProfilerHandle): string =>
   // oxlint-disable-next-line reform-rules/no-json-parse-stringify -- Trace Event Format is a foreign wire format consumed by Chrome DevTools/Perfetto, not Schema-typed data
   JSON.stringify(toChromeTrace(profiler))