@playfast/reform-profiler 1.0.1

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@playfast/reform-profiler",
+  "playbook": "./playbook",
+  "version": "1.0.1",
+  "type": "module",
+  "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",
+    "effect",
+    "profiler",
+    "performance",
+    "devtools"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/playfast/reform.git",
+    "directory": "packages/reform-profiler"
+  },
+  "bugs": {
+    "url": "https://github.com/playfast/reform/issues"
+  },
+  "sideEffects": false,
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "development": "./src/index.ts",
+      "default": "./src/noop.ts"
+    },
+    "./react": {
+      "development": "./src/react/index.ts",
+      "default": "./src/react/noop.ts"
+    },
+    "./recorder": "./src/index.ts"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "clean": "rm -rf dist .tsbuildinfo",
+    "check": "tsc --noEmit",
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "coverage": "vitest run --coverage",
+    "lint": "oxlint src",
+    "lint:fix": "oxlint --fix src"
+  },
+  "peerDependencies": {
+    "effect": "*",
+    "@playfast/reform": "*",
+    "react": "^19.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/index.ts

@@ -0,0 +1,26 @@
+// @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,
+  type ProfileRecord,
+  type ProfilerHandle,
+  type ProfilerOptionsExternalApi,
+  type ProfileSnapshot,
+  type ProfileStat,
+} from './recorder'
+export { type ProfiledScene, profileScene } from './profileScene'
+export { type ChromeTrace, type ChromeTraceEvent, toChromeTrace, traceJson } from './trace'
+export { formatReport } from './report'
+export {
+  claimOverlay,
+  listProfilers,
+  type ProfilerRegistration,
+  profilersVersion,
+  registerProfiler,
+  releaseOverlay,
+  subscribeProfilers,
+} from './registry'

package/src/noop.ts

@@ -0,0 +1,79 @@
+import { noopInstrumentation, type Scene, type UiContract } from '@playfast/reform'
+import type { 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).
+
+export type {
+  ProfileKind,
+  ProfileRecord,
+  ProfilerHandle,
+  ProfilerOptionsExternalApi,
+  ProfileSnapshot,
+  ProfileStat,
+} from './recorder'
+export type { ProfiledScene } from './profileScene'
+export type { ChromeTrace, ChromeTraceEvent } from './trace'
+export type { ProfilerRegistration } from './registry'
+
+const emptySnapshot: ProfileSnapshot = {
+  events: new Map(),
+  reducers: new Map(),
+  states: new Map(),
+  calcs: new Map(),
+  queries: new Map(),
+  procedures: new Map(),
+  renders: new Map(),
+  frames: { count: 0, totalMs: 0 },
+  records: [],
+  dropped: 0,
+}
+
+/** The shared inert handle every stub call hands back. */
+export const noopProfiler: ProfilerHandle = {
+  ...noopInstrumentation,
+  label: 'noop',
+  snapshot: () => emptySnapshot,
+  clear: () => {},
+  subscribe: () => () => {},
+  getVersion: () => 0,
+}
+
+export const makeProfiler = (_options: ProfilerOptionsExternalApi = {}): ProfilerHandle =>
+  noopProfiler
+
+export const profileScene = <C extends UiContract, S extends ReadonlyArray<unknown>>(
+  base: Scene<C, S>,
+  _options: ProfilerOptionsExternalApi = {},
+): ProfiledScene<C, S> => ({ scene: base, profiler: noopProfiler })
+
+const emptyTrace: ChromeTrace = { traceEvents: [], displayTimeUnit: 'ms' }
+
+export const toChromeTrace = (_profiler: ProfilerHandle): ChromeTrace => emptyTrace
+
+export const traceJson = (_profiler: ProfilerHandle): string =>
+  '{"traceEvents":[],"displayTimeUnit":"ms"}'
+
+export const formatReport = (_profiler: ProfilerHandle): string => ''
+
+export const registerProfiler = (_registration: ProfilerRegistration): (() => void) => () => {}
+
+export const listProfilers = (): ReadonlyArray<ProfilerRegistration> => []
+
+export const subscribeProfilers = (_listener: () => void): (() => void) => () => {}
+
+export const profilersVersion = (): number => 0
+
+export const claimOverlay = (_owner: object): boolean => false
+
+export const releaseOverlay = (_owner: object): void => {}

package/src/profileScene.ts

@@ -0,0 +1,56 @@
+import { Effect, Layer } from 'effect'
+import { profiledScene, type Scene, type UiContract } from '@playfast/reform'
+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>,
+> {
+  readonly scene: Scene<C, S>
+  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>>(
+  base: Scene<C, S>,
+  options: ProfilerOptionsExternalApi = {},
+): 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 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

@@ -0,0 +1,178 @@
+import { Schema as S } from 'effect'
+import { expect, test } from 'vitest'
+import {
+  Composition,
+  Event,
+  Engine,
+  makeAppRuntime,
+  mount,
+  provide,
+  Reducer,
+  scene,
+  sceneInstrumentation,
+  State,
+  StateGroup,
+  Ui,
+  ui,
+} from '@playfast/reform'
+import { Layer } from 'effect'
+import { makeProfiler } from './recorder'
+import { profileScene } from './profileScene'
+import { listProfilers } from './registry'
+import { toChromeTrace, traceJson } from './trace'
+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')
+  profiler.eventDispatched('Bumped', 'Normal')
+  profiler.eventDispatched('Reset', 'High')
+  profiler.reducerRun('fold', 'Bumped')()
+  profiler.reducerRun('fold', 'Bumped')()
+  profiler.stateUpdated('count')
+
+  const snapshot = profiler.snapshot()
+  expect(snapshot.events.get('Bumped')?.count).toBe(2)
+  expect(snapshot.events.get('Reset')?.count).toBe(1)
+  expect(snapshot.reducers.get('fold')?.count).toBe(2)
+  expect(snapshot.reducers.get('fold')?.totalMs).toBeGreaterThanOrEqual(0)
+  expect(snapshot.states.get('count')?.count).toBe(1)
+  expect(snapshot.records.length).toBe(6)
+  expect(snapshot.dropped).toBe(0)
+})
+
+test('the ring buffer wraps: newest records survive, aggregates keep the full tally', () => {
+  const profiler = makeProfiler({ capacity: 4 })
+  const tags = ['a', 'b', 'c', 'd', 'e', 'f']
+  tags.forEach((tag) => profiler.eventDispatched(tag, 'Normal'))
+
+  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)
+})
+
+test('clear drops records, aggregates, and bumps the version', () => {
+  const profiler = makeProfiler()
+  profiler.eventDispatched('x', 'High')
+  const before = profiler.getVersion()
+  profiler.clear()
+  expect(profiler.getVersion()).toBeGreaterThan(before)
+  const snapshot = profiler.snapshot()
+  expect(snapshot.records).toEqual([])
+  expect(snapshot.events.size).toBe(0)
+  expect(snapshot.dropped).toBe(0)
+})
+
+test('subscribers are notified once per burst (coalesced)', async () => {
+  const profiler = makeProfiler()
+  const calls = { count: 0 }
+  const unsubscribe = profiler.subscribe(() => {
+    calls.count += 1
+  })
+  profiler.eventDispatched('a', 'High')
+  profiler.eventDispatched('b', 'High')
+  profiler.eventDispatched('c', 'High')
+  await settle(0)
+  expect(calls.count).toBe(1)
+  unsubscribe()
+  profiler.eventDispatched('d', 'High')
+  await settle(0)
+  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')
+  profiler.reducerRun('fold', 'Bumped')()
+
+  const trace = toChromeTrace(profiler)
+  const meta = trace.traceEvents.filter((event) => event.ph === 'M')
+  expect(meta.some((event) => event.name === 'process_name')).toBe(true)
+  expect(meta.filter((event) => event.name === 'thread_name').length).toBe(8)
+
+  const instant = trace.traceEvents.find((event) => event.ph === 'i')
+  expect(instant?.name).toBe('Bumped')
+  const span = trace.traceEvents.find((event) => event.ph === 'X')
+  expect(span?.name).toBe('fold')
+  if (span?.ph === 'X') {
+    expect(span.dur).toBeGreaterThanOrEqual(0)
+    expect(typeof span.ts).toBe('number')
+  }
+
+  const parsed: unknown = JSON.parse(traceJson(profiler))
+  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({})) {}
+class Bump extends Reducer.make('ProfilerBump', { states: [Count], events: [Bumped] }) {}
+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,
+}) {}
+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(
+    Layer.mergeAll(BumpLive).pipe(
+      Layer.provideMerge(Layer.mergeAll(Engine, StateGroup.live(States, { 'profiler-count': 0 }))),
+    ),
+  ),
+)
+const baseScene = scene(Root, { provide: [app], boot: [Event.construct(Bumped, {})] })
+
+test('profileScene records engine activity through makeAppRuntime and registers while live', async () => {
+  const { scene: profiled, profiler } = profileScene(baseScene)
+  expect(sceneInstrumentation(profiled)).toBe(profiler)
+  expect(profiler.label).toBe('ProfilerRoot')
+
+  const runtime = makeAppRuntime(profiled)
+  expect(listProfilers().map((entry) => entry.handle)).toContain(profiler)
+
+  runtime.boot()
+  runtime.dispatch('High', Event.construct(Bumped, {}))
+  await settle()
+
+  const snapshot = profiler.snapshot()
+  expect(snapshot.events.get('ProfilerBumped')?.count).toBe(2)
+  expect(snapshot.reducers.get('ProfilerBump')?.count).toBe(2)
+  expect(snapshot.states.get('profiler-count')?.count).toBe(2)
+  expect(snapshot.frames.count).toBeGreaterThanOrEqual(1)
+
+  const report = formatReport(profiler)
+  expect(report).toContain('ProfilerRoot')
+  expect(report).toContain('ProfilerBump')
+
+  runtime.dispose()
+  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, {}))
+  await settle()
+  expect(profiler.snapshot().events.get('ProfilerBumped')?.count).toBe(before)
+  plain.dispose()
+})

package/src/react/index.ts

@@ -0,0 +1,5 @@
+// @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

@@ -0,0 +1,9 @@
+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

@@ -0,0 +1,215 @@
+import type { ReactNode } from 'react'
+import { useCallback, useEffect, useRef, useState, useSyncExternalStore } from 'react'
+import type { ProfilerHandle, ProfileStat } from '../recorder'
+import {
+  claimOverlay,
+  listProfilers,
+  profilersVersion,
+  releaseOverlay,
+  subscribeProfilers,
+} from '../registry'
+import { traceJson } from '../trace'
+import {
+  bodyStyle,
+  buttonStyle,
+  cellStyle,
+  headerStyle,
+  nameCellStyle,
+  palette,
+  panelStyle,
+  pillStyle,
+  rootStyle,
+  sectionTitleStyle,
+  tableStyle,
+  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). */
+export const downloadTrace = (profiler: ProfilerHandle): void => {
+  const blob = new Blob([traceJson(profiler)], { type: 'application/json' })
+  const url = URL.createObjectURL(blob)
+  const anchor = document.createElement('a')
+  anchor.href = url
+  anchor.download = `reform-trace-${profiler.label}.json`
+  anchor.click()
+  URL.revokeObjectURL(url)
+}
+
+// ── data shaping ─────────────────────────────────────────────────────────────
+
+interface Row {
+  readonly name: string
+  readonly stat: ProfileStat
+}
+
+const sortedRows = (stats: ReadonlyMap<string, ProfileStat>): ReadonlyArray<Row> =>
+  [...stats.entries()]
+    .map(([name, stat]): Row => ({ name, stat }))
+    .toSorted(
+      (left, right) => right.stat.totalMs - left.stat.totalMs || right.stat.count - left.stat.count,
+    )
+
+const MS_DECIMALS = 2
+const formatMs = (durationMs: number): string => durationMs.toFixed(MS_DECIMALS)
+const avgMs = (stat: ProfileStat): string =>
+  formatMs(stat.count === 0 ? 0 : stat.totalMs / stat.count)
+
+interface SectionProps {
+  readonly title: string
+  readonly rows: ReadonlyArray<Row>
+  /** Timed sections get total/avg columns; instant sections only a count. */
+  readonly timed: boolean
+}
+
+const Section = ({ title, rows, timed }: SectionProps): ReactNode => {
+  if (rows.length === 0) {
+    return null
+  }
+  return (
+    <div>
+      <div style={sectionTitleStyle}>{title}</div>
+      <table style={tableStyle}>
+        <thead>
+          <tr>
+            <th style={nameCellStyle}>name</th>
+            <th style={cellStyle}>count</th>
+            {timed ? <th style={cellStyle}>total ms</th> : null}
+            {timed ? <th style={cellStyle}>avg ms</th> : null}
+          </tr>
+        </thead>
+        <tbody>
+          {rows.map((row) => (
+            <tr key={row.name}>
+              <td style={nameCellStyle}>{row.name}</td>
+              <td style={cellStyle}>{row.stat.count}</td>
+              {timed ? <td style={cellStyle}>{formatMs(row.stat.totalMs)}</td> : null}
+              {timed ? <td style={cellStyle}>{avgMs(row.stat)}</td> : null}
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </div>
+  )
+}
+
+interface DroppedNoteProps {
+  readonly count: number
+}
+
+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>
+}
+
+interface ProfilerBodyProps {
+  readonly profiler: ProfilerHandle
+}
+
+const ProfilerBody = ({ profiler }: ProfilerBodyProps): ReactNode => {
+  const subscribe = useCallback(
+    (onStoreChange: () => void) => profiler.subscribe(onStoreChange),
+    [profiler],
+  )
+  const getVersion = useCallback(() => profiler.getVersion(), [profiler])
+  useSyncExternalStore(subscribe, getVersion, getVersion)
+  const snapshot = profiler.snapshot()
+  const frameRows: ReadonlyArray<Row> =
+    snapshot.frames.count === 0 ? [] : [{ name: 'frame', stat: snapshot.frames }]
+  return (
+    <div style={bodyStyle}>
+      <Section title="Renders" rows={sortedRows(snapshot.renders)} timed={true} />
+      <Section title="Events" rows={sortedRows(snapshot.events)} timed={false} />
+      <Section title="Reducers" rows={sortedRows(snapshot.reducers)} timed={true} />
+      <Section title="State updates" rows={sortedRows(snapshot.states)} timed={false} />
+      <Section title="Calcs" rows={sortedRows(snapshot.calcs)} timed={true} />
+      <Section title="Queries" rows={sortedRows(snapshot.queries)} timed={true} />
+      <Section title="Procedures" rows={sortedRows(snapshot.procedures)} timed={true} />
+      <Section title="Frames" rows={frameRows} timed={true} />
+      <DroppedNote count={snapshot.dropped} />
+    </div>
+  )
+}
+
+// ── 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)
+  useEffect(() => {
+    setClaimed(claimOverlay(owner))
+    const unsubscribe = subscribeProfilers(() => setClaimed(claimOverlay(owner)))
+    return () => {
+      unsubscribe()
+      releaseOverlay(owner)
+    }
+  }, [owner])
+
+  const registryVersion = useSyncExternalStore(
+    subscribeProfilers,
+    profilersVersion,
+    profilersVersion,
+  )
+  const registrations = listProfilers()
+  const [expanded, setExpanded] = useState(false)
+  const [tab, setTab] = useState(0)
+  void registryVersion
+
+  if (!claimed || registrations.length === 0) {
+    return null
+  }
+  const selected = registrations[Math.min(tab, registrations.length - 1)]
+  if (selected === undefined) {
+    return null
+  }
+  if (!expanded) {
+    return (
+      <div style={rootStyle}>
+        <button type="button" style={pillStyle} onClick={() => setExpanded(true)}>
+          ⚡ reform profiler
+        </button>
+      </div>
+    )
+  }
+  return (
+    <div style={rootStyle}>
+      <div style={panelStyle}>
+        <div style={headerStyle}>
+          <span style={{ color: palette.accent, fontWeight: 600 }}>⚡ reform</span>
+          {registrations.map((registration, index) => (
+            <button
+              key={registration.label + String(index)}
+              type="button"
+              style={tabStyle(registration === selected)}
+              onClick={() => setTab(index)}
+            >
+              {registration.label}
+            </button>
+          ))}
+          <span style={{ flex: 1 }} />
+          <button type="button" style={buttonStyle} onClick={() => downloadTrace(selected.handle)}>
+            export
+          </button>
+          <button type="button" style={buttonStyle} onClick={() => selected.handle.clear()}>
+            clear
+          </button>
+          <button type="button" style={buttonStyle} onClick={() => setExpanded(false)}>
+            ×
+          </button>
+        </div>
+        <ProfilerBody profiler={selected.handle} />
+      </div>
+    </div>
+  )
+}

package/src/react/styles.ts

@@ -0,0 +1,115 @@
+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
+  readonly border: string
+  readonly text: string
+  readonly dim: string
+  readonly accent: string
+}
+
+export const palette: Palette = {
+  bg: '#16181d',
+  panel: '#1d2026',
+  border: '#31353d',
+  text: '#d7dae0',
+  dim: '#8a8f98',
+  accent: '#e8a33d',
+}
+
+export const rootStyle: CSSProperties = {
+  position: 'fixed',
+  right: 12,
+  bottom: 12,
+  zIndex: 2147483000,
+  fontFamily: 'ui-monospace, SFMono-Regular, Menlo, monospace',
+  fontSize: 11,
+  lineHeight: 1.5,
+  color: palette.text,
+}
+
+export const pillStyle: CSSProperties = {
+  background: palette.bg,
+  border: `1px solid ${palette.border}`,
+  borderRadius: 999,
+  padding: '4px 12px',
+  cursor: 'pointer',
+  color: palette.accent,
+  fontSize: 11,
+  fontFamily: 'inherit',
+}
+
+export const panelStyle: CSSProperties = {
+  background: palette.bg,
+  border: `1px solid ${palette.border}`,
+  borderRadius: 8,
+  width: 420,
+  maxHeight: '60vh',
+  display: 'flex',
+  flexDirection: 'column',
+  overflow: 'hidden',
+  boxShadow: '0 8px 24px rgba(0,0,0,0.5)',
+}
+
+export const headerStyle: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 8,
+  padding: '6px 10px',
+  borderBottom: `1px solid ${palette.border}`,
+  background: palette.panel,
+}
+
+export const buttonStyle: CSSProperties = {
+  background: 'transparent',
+  border: `1px solid ${palette.border}`,
+  borderRadius: 4,
+  color: palette.text,
+  padding: '1px 8px',
+  cursor: 'pointer',
+  fontSize: 11,
+  fontFamily: 'inherit',
+}
+
+export const tabStyle = (active: boolean): CSSProperties => ({
+  ...buttonStyle,
+  borderColor: active ? palette.accent : palette.border,
+  color: active ? palette.accent : palette.dim,
+})
+
+export const bodyStyle: CSSProperties = {
+  overflowY: 'auto',
+  padding: '4px 10px 10px',
+}
+
+export const tableStyle: CSSProperties = {
+  width: '100%',
+  borderCollapse: 'collapse',
+  marginBottom: 8,
+}
+
+export const cellStyle: CSSProperties = {
+  padding: '1px 6px 1px 0',
+  textAlign: 'right',
+  whiteSpace: 'nowrap',
+  color: palette.dim,
+}
+
+export const nameCellStyle: CSSProperties = {
+  ...cellStyle,
+  textAlign: 'left',
+  width: '100%',
+  color: palette.text,
+  overflowWrap: 'anywhere',
+  whiteSpace: 'normal',
+}
+
+export const sectionTitleStyle: CSSProperties = {
+  color: palette.accent,
+  margin: '8px 0 2px',
+  fontWeight: 600,
+}

package/src/recorder.ts

@@ -0,0 +1,182 @@
+import { type Instrumentation, makeScheduler, type SpanEnd } from '@playfast/reform'
+
+// 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'
+  | 'state'
+  | 'calc'
+  | 'query'
+  | 'procedure'
+  | 'render'
+  | 'frame'
+
+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>
+  readonly states: ReadonlyMap<string, ProfileStat>
+  readonly calcs: ReadonlyMap<string, ProfileStat>
+  readonly queries: ReadonlyMap<string, ProfileStat>
+  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
+}
+
+const zeroStat: ProfileStat = { count: 0, totalMs: 0 }
+
+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`.
+  const emptyBuffer = (): Array<ProfileRecord | undefined> =>
+    Array.from({ length: capacity }, (): ProfileRecord | undefined => undefined)
+  const cursor = { buffer: emptyBuffer(), written: 0, version: 0 }
+  const stats: Record<ProfileKind, Map<string, ProfileStat>> = {
+    event: new Map(),
+    reducer: new Map(),
+    state: new Map(),
+    calc: new Map(),
+    query: new Map(),
+    procedure: new Map(),
+    render: new Map(),
+    frame: new Map(),
+  }
+
+  const listeners = new Set<() => void>()
+  const scheduler = makeScheduler()
+  const notify = (): void => {
+    cursor.version += 1
+    scheduler.schedule(listeners)
+  }
+
+  const record = (entry: ProfileRecord): void => {
+    cursor.buffer[cursor.written % capacity] = entry
+    cursor.written += 1
+    const bucket = stats[entry.kind]
+    const prev = bucket.get(entry.name) ?? zeroStat
+    bucket.set(entry.name, { count: prev.count + 1, totalMs: prev.totalMs + entry.dur })
+    notify()
+  }
+
+  interface Site {
+    readonly kind: ProfileKind
+    readonly name: string
+    readonly detail: string
+  }
+
+  const instant = (site: Site): void =>
+    record({ ...site, start: performance.now(), dur: 0 })
+
+  const span = (site: Site): SpanEnd => {
+    const start = performance.now()
+    return () => record({ ...site, start, dur: performance.now() - start })
+  }
+
+  const snapshot = (): ProfileSnapshot => {
+    const size = Math.min(cursor.written, capacity)
+    const first = cursor.written - size
+    const records = Array.from(
+      { length: size },
+      (_, index) => cursor.buffer[(first + index) % capacity],
+    ).filter((candidate): candidate is ProfileRecord => candidate !== undefined)
+    return {
+      events: new Map(stats.event),
+      reducers: new Map(stats.reducer),
+      states: new Map(stats.state),
+      calcs: new Map(stats.calc),
+      queries: new Map(stats.query),
+      procedures: new Map(stats.procedure),
+      renders: new Map(stats.render),
+      frames: stats.frame.get('frame') ?? zeroStat,
+      records,
+      dropped: first,
+    }
+  }
+
+  return {
+    label,
+    snapshot,
+    clear: () => {
+      cursor.buffer = emptyBuffer()
+      cursor.written = 0
+      Object.values(stats).forEach((bucket) => bucket.clear())
+      notify()
+    },
+    subscribe: (listener) => {
+      listeners.add(listener)
+      return () => {
+        listeners.delete(listener)
+      }
+    },
+    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: '' }),
+    calcRecomputed: (name) => span({ kind: 'calc', name, detail: '' }),
+    queryRun: (name) => span({ kind: 'query', name, detail: '' }),
+    procedureRun: (name, channel, eventTag) =>
+      span({ kind: 'procedure', name, detail: `${channel}:${eventTag}` }),
+    uiRendered: (composition) => span({ kind: 'render', name: composition, detail: '' }),
+    frame: (eventCount) => span({ kind: 'frame', name: 'frame', detail: String(eventCount) }),
+  }
+}

package/src/registry.ts

@@ -0,0 +1,100 @@
+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.
+
+export interface ProfilerRegistration {
+  readonly label: string
+  readonly handle: ProfilerHandle
+}
+
+interface RegistryState {
+  /** Live registrations with a build refcount (StrictMode double-builds share 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> }
+}
+
+const state: RegistryState = GlobalValue.globalValue(
+  Symbol.for('reform-profiler/registry'),
+  (): RegistryState => ({
+    entries: new Map(),
+    listeners: new Set(),
+    version: { current: 0 },
+    overlay: { owner: Option.none() },
+  }),
+)
+
+const notify = (): void => {
+  state.version.current += 1
+  ;[...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, {
+    registration,
+    count: existing === undefined ? 1 : existing.count + 1,
+  })
+  if (existing === undefined) {
+    notify()
+  }
+  return () => {
+    const current = state.entries.get(registration.handle)
+    if (current === undefined) {
+      return
+    }
+    if (current.count <= 1) {
+      state.entries.delete(registration.handle)
+      notify()
+    } else {
+      state.entries.set(registration.handle, { ...current, count: current.count - 1 })
+    }
+  }
+}
+
+/** 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 () => {
+    state.listeners.delete(listener)
+  }
+}
+
+/** 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).
+ */
+export const claimOverlay = (owner: object): boolean => {
+  if (Option.isNone(state.overlay.owner)) {
+    state.overlay.owner = Option.some(owner)
+    return true
+  }
+  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()
+    notify()
+  }
+}

package/src/report.ts

@@ -0,0 +1,78 @@
+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
+}
+
+const sortedRows = (stats: ReadonlyMap<string, ProfileStat>): ReadonlyArray<Row> =>
+  [...stats.entries()]
+    .map(([name, stat]): Row => ({ name, stat }))
+    .toSorted(
+      (left, right) => right.stat.totalMs - left.stat.totalMs || right.stat.count - left.stat.count,
+    )
+
+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
+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
+}
+
+const section = ({ title, rows, timed }: Section): ReadonlyArray<string> => {
+  if (rows.length === 0) {
+    return []
+  }
+  const nameWidth = Math.max('name'.length, ...rows.map((row) => row.name.length))
+  const header = timed
+    ? `${'name'.padEnd(nameWidth)}  ${'count'.padStart(COUNT_WIDTH)}  ${'total ms'.padStart(TOTAL_WIDTH)}  ${'avg ms'.padStart(AVG_WIDTH)}`
+    : `${'name'.padEnd(nameWidth)}  ${'count'.padStart(COUNT_WIDTH)}`
+  const lines = rows.map((row) =>
+    timed
+      ? `${row.name.padEnd(nameWidth)}  ${String(row.stat.count).padStart(COUNT_WIDTH)}  ${formatMs(row.stat.totalMs).padStart(TOTAL_WIDTH)}  ${formatMs(row.stat.count === 0 ? 0 : row.stat.totalMs / row.stat.count).padStart(AVG_WIDTH)}`
+      : `${row.name.padEnd(nameWidth)}  ${String(row.stat.count).padStart(COUNT_WIDTH)}`,
+  )
+  return [
+    `── ${title} ${'─'.repeat(Math.max(0, header.length - title.length - ruleOverhead))}`,
+    header,
+    ...lines,
+    '',
+  ]
+}
+
+/** 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> =
+    snapshot.frames.count === 0 ? [] : [{ name: 'frame', stat: snapshot.frames }]
+  const dropped =
+    snapshot.dropped === 0
+      ? []
+      : [`(${snapshot.dropped} early records evicted from the ring buffer)`, '']
+  return [
+    `reform profile — ${profiler.label}`,
+    '',
+    ...section({ title: 'Events', rows: sortedRows(snapshot.events), timed: false }),
+    ...section({ title: 'Reducers', rows: sortedRows(snapshot.reducers), timed: true }),
+    ...section({ title: 'State updates', rows: sortedRows(snapshot.states), timed: false }),
+    ...section({ title: 'Calcs', rows: sortedRows(snapshot.calcs), timed: true }),
+    ...section({ title: 'Queries', rows: sortedRows(snapshot.queries), timed: true }),
+    ...section({ title: 'Procedures', rows: sortedRows(snapshot.procedures), timed: true }),
+    ...section({ title: 'Renders', rows: sortedRows(snapshot.renders), timed: true }),
+    ...section({ title: 'Frames', rows: frameRows, timed: true }),
+    ...dropped,
+  ].join('\n')
+}

package/src/trace.ts

@@ -0,0 +1,93 @@
+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'
+      readonly name: string
+      readonly cat: string
+      readonly ts: number
+      readonly dur: number
+      readonly pid: number
+      readonly tid: number
+      readonly args: Readonly<Record<string, string>>
+    }
+  | {
+      readonly ph: 'i'
+      readonly name: string
+      readonly cat: string
+      readonly ts: number
+      readonly pid: number
+      readonly tid: number
+      readonly s: 't'
+      readonly args: Readonly<Record<string, string>>
+    }
+  | {
+      readonly ph: 'M'
+      readonly name: 'process_name' | 'thread_name'
+      readonly ts: 0
+      readonly pid: number
+      readonly tid: number
+      readonly args: { readonly name: string }
+    }
+
+export interface ChromeTrace {
+  readonly traceEvents: ReadonlyArray<ChromeTraceEvent>
+  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' },
+  reducer: { tid: 3, title: 'reducers' },
+  state: { tid: 4, title: 'state updates' },
+  calc: { tid: 5, title: 'calcs' },
+  query: { tid: 6, title: 'queries' },
+  procedure: { tid: 7, title: 'procedures' },
+  render: { tid: 8, title: 'renders' },
+}
+
+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}` } },
+    ...Object.values(lanes).map(
+      (lane): ChromeTraceEvent => ({
+        ph: 'M',
+        name: 'thread_name',
+        ts: 0,
+        pid,
+        tid: lane.tid,
+        args: { name: lane.title },
+      }),
+    ),
+  ]
+  const body = records.map((record): ChromeTraceEvent => {
+    const startUs = record.start * US_PER_MS
+    const cat = record.kind
+    const tid = lanes[record.kind].tid
+    const args = record.detail === '' ? {} : { detail: record.detail }
+    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 }
+  })
+  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))