@playfast/reform-profiler 1.0.1 → 1.0.2

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@playfast/reform-profiler",
   "playbook": "./playbook",
-  "version": "1.0.1",
+  "version": "1.0.2",
   "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": [

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,

package/src/noop.ts

@@ -8,11 +8,7 @@ import type {
 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,
@@ -39,7 +35,6 @@ const emptySnapshot: ProfileSnapshot = {
   dropped: 0,
 }
 
-/** The shared inert handle every stub call hands back. */
 export const noopProfiler: ProfilerHandle = {
   ...noopInstrumentation,
   label: 'noop',

package/src/profileScene.ts

@@ -3,7 +3,6 @@ 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>,
@@ -12,21 +11,6 @@ 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>>(
   base: Scene<C, S>,
   options: ProfilerOptionsExternalApi = {},
@@ -43,8 +27,7 @@ export const profileScene = <C extends UiContract, S extends ReadonlyArray<unkno
   )
   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.
+    // Lifecycle on first provide layer so register/unregister track runtime build/dispose.
     scene: {
       ...wrapped,
       provide: wrapped.provide.map((layer, index) =>

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({})) {}
@@ -168,7 +161,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
 }
 
@@ -137,13 +129,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'
 
-// 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 }
@@ -168,7 +139,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,10 @@ export interface ProfilerRegistration {
 }
 
 interface RegistryState {
-  /** Live registrations with a build refcount (StrictMode double-builds share one entry). */
+  // 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 +31,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 +54,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 +64,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 +75,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,7 +51,6 @@ 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> = [
@@ -87,7 +78,6 @@ export const toChromeTrace = (profiler: ProfilerHandle): ChromeTrace => {
   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))