@forgeax/engine-profiler 0.1.2

package/dist/model.d.ts

@@ -0,0 +1,44 @@
+import { type ProfileArtifactError } from './schema.js';
+import type { ProfileCapture, ProfilePhaseRecord, ProfileRecord, ProfileResult } from './types.js';
+export interface ProfileFrameModel {
+    readonly frameId: number;
+    readonly recordCount: number;
+    readonly phaseCount: number;
+    readonly skipCount: number;
+    readonly durationMicros: number;
+    readonly records: readonly ProfileRecord[];
+}
+export interface ProfilePhaseModel {
+    readonly source: ProfilePhaseRecord['source'];
+    readonly phase: string;
+    readonly parentSource?: ProfilePhaseRecord['source'];
+    readonly parentPhase?: string;
+    readonly count: number;
+    readonly skipCount: number;
+    readonly p95DurationMicros: number | null;
+}
+export interface ProfileSummaryModel {
+    readonly schemaVersion: ProfileCapture['schemaVersion'];
+    readonly captureId: string;
+    readonly timeUnit: ProfileCapture['timeUnit'];
+    readonly frameLimit: number;
+    readonly eventLimit: number;
+    readonly completeness: ProfileCapture['completeness'];
+    readonly frameRange: {
+        readonly first: number;
+        readonly last: number;
+    } | null;
+    readonly frameCount: number;
+    readonly recordCount: number;
+    readonly phaseCount: number;
+    readonly skipCount: number;
+    readonly p95DurationMicros: number | null;
+}
+export interface ProfileModel {
+    readonly summary: ProfileSummaryModel;
+    readonly completeness: ProfileCapture['completeness'];
+    readonly frames: readonly ProfileFrameModel[];
+    readonly phases: readonly ProfilePhaseModel[];
+}
+export declare function buildProfileModel(value: unknown): ProfileResult<ProfileModel, ProfileArtifactError>;
+//# sourceMappingURL=model.d.ts.map

package/dist/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../src/model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,oBAAoB,EAA0B,MAAM,aAAa,CAAC;AAChF,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEnG,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IAC9C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,kBAAkB,CAAC,QAAQ,CAAC,CAAC;IACrD,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,aAAa,EAAE,cAAc,CAAC,eAAe,CAAC,CAAC;IACxD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC,UAAU,CAAC,CAAC;IAC9C,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;IACtD,QAAQ,CAAC,UAAU,EAAE;QAAE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3C;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;IACtD,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;IAC9C,QAAQ,CAAC,MAAM,EAAE,SAAS,iBAAiB,EAAE,CAAC;CAC/C;AAgFD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,GACb,aAAa,CAAC,YAAY,EAAE,oBAAoB,CAAC,CAoCnD"}

package/dist/profiler.d.ts

@@ -0,0 +1,24 @@
+import { type ProfileClock } from './clock.js';
+import type { ProfilerError, ProfilerResult } from './errors.js';
+import type { RecorderPhaseCatalog } from './recorder.js';
+import { type RecorderLimits, type RecorderSession } from './recorder.js';
+import type { ProfileAllocationReport, ProfileCapture, ProfileSink } from './types.js';
+export interface ProfilerOptions {
+    readonly clock?: ProfileClock;
+    readonly sink?: ProfileSink;
+    readonly enabled?: boolean;
+    readonly phaseCatalog?: RecorderPhaseCatalog;
+    readonly allocationReport?: ProfileAllocationReport;
+}
+export type ProfilerCatalogSource = keyof RecorderPhaseCatalog;
+export interface Profiler {
+    registerPhaseCatalog(source: ProfilerCatalogSource, phases: readonly string[]): ProfilerResult<() => void>;
+    startCapture(limits: RecorderLimits): ProfilerResult<RecorderSession>;
+    activeCaptureId(): string | undefined;
+    activeSession(): RecorderSession | undefined;
+    latestCapture(): ProfileCapture | undefined;
+    readonly phaseCatalog: RecorderPhaseCatalog;
+}
+export declare function createProfiler(options?: ProfilerOptions): Profiler;
+export type { ProfileCapture, ProfilerError };
+//# sourceMappingURL=profiler.d.ts.map

package/dist/profiler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profiler.d.ts","sourceRoot":"","sources":["../src/profiler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,YAAY,CAAC;AACnE,OAAO,KAAK,EAAE,aAAa,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACjE,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAkB,KAAK,cAAc,EAAE,KAAK,eAAe,EAAE,MAAM,eAAe,CAAC;AAC1F,OAAO,KAAK,EAAE,uBAAuB,EAAE,cAAc,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAEvF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAC;IAC9B,QAAQ,CAAC,IAAI,CAAC,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAC;IAC7C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,uBAAuB,CAAC;CACrD;AAED,MAAM,MAAM,qBAAqB,GAAG,MAAM,oBAAoB,CAAC;AAE/D,MAAM,WAAW,QAAQ;IACvB,oBAAoB,CAClB,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB,cAAc,CAAC,MAAM,IAAI,CAAC,CAAC;IAC9B,YAAY,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAAC,eAAe,CAAC,CAAC;IACtE,eAAe,IAAI,MAAM,GAAG,SAAS,CAAC;IACtC,aAAa,IAAI,eAAe,GAAG,SAAS,CAAC;IAC7C,aAAa,IAAI,cAAc,GAAG,SAAS,CAAC;IAC5C,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;CAC7C;AAED,wBAAgB,cAAc,CAAC,OAAO,GAAE,eAAoB,GAAG,QAAQ,CAsGtE;AAsED,YAAY,EAAE,cAAc,EAAE,aAAa,EAAE,CAAC"}

package/dist/recorder.d.ts

@@ -0,0 +1,26 @@
+import type { ProfileClock } from './clock.js';
+import { type ProfilerResult } from './errors.js';
+import type { ProfileCapture, ProfilePhaseStart, ProfileSkipInput, ProfileSource } from './types.js';
+export interface RecorderLimits {
+    readonly frameLimit: number;
+    readonly eventLimit: number;
+    readonly detail?: ProfileDetail;
+}
+export type ProfileDetail = 'owner' | 'passes' | 'nested';
+export type RecorderPhaseCatalog = Readonly<Record<ProfileSource, readonly string[]>>;
+export interface RecorderSession {
+    readonly captureId: string;
+    readonly detail: ProfileDetail;
+    beginFrame(frameId: number): ProfilerResult<void>;
+    beginPhase(input: ProfilePhaseStart): ProfilerResult<void>;
+    beginPhase(source: ProfileSource, phase: string): ProfilerResult<void>;
+    endPhase(): ProfilerResult<void>;
+    recordSkip(input: ProfileSkipInput): ProfilerResult<void>;
+    endFrame(): ProfilerResult<void>;
+    finish(): ProfilerResult<ProfileCapture>;
+}
+export declare function validateRecorderLimits(limits: RecorderLimits): ProfilerResult<void>;
+export declare function createRecorder(captureId: string, limits: RecorderLimits, clock: ProfileClock, phaseCatalog: RecorderPhaseCatalog, allocationReport?: {
+    profilerEventObjectAllocations: number;
+}): ProfilerResult<RecorderSession>;
+//# sourceMappingURL=recorder.d.ts.map

package/dist/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAC/C,OAAO,EAAiB,KAAK,cAAc,EAAc,MAAM,aAAa,CAAC;AAC7E,OAAO,KAAK,EACV,cAAc,EACd,iBAAiB,EAEjB,gBAAgB,EAChB,aAAa,EACd,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,aAAa,CAAC;CACjC;AAED,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAE1D,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC,MAAM,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC,CAAC,CAAC;AAEtF,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAClD,UAAU,CAAC,KAAK,EAAE,iBAAiB,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAC3D,UAAU,CAAC,MAAM,EAAE,aAAa,EAAE,KAAK,EAAE,MAAM,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IACvE,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;IACjC,UAAU,CAAC,KAAK,EAAE,gBAAgB,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAC1D,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,IAAI,cAAc,CAAC,cAAc,CAAC,CAAC;CAC1C;AAgDD,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,cAAc,GAAG,cAAc,CAAC,IAAI,CAAC,CAKnF;AAgLD,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,MAAM,EAAE,cAAc,EACtB,KAAK,EAAE,YAAY,EACnB,YAAY,EAAE,oBAAoB,EAClC,gBAAgB,CAAC,EAAE;IAAE,8BAA8B,EAAE,MAAM,CAAA;CAAE,GAC5D,cAAc,CAAC,eAAe,CAAC,CAuJjC"}

package/dist/schema.d.ts

@@ -0,0 +1,13 @@
+import type { ProfileCapture } from './generated/profile-capture.js';
+import type { ProfileResult } from './types.js';
+export type ProfileArtifactError = {
+    readonly code: 'profile-artifact-invalid' | 'profile-artifact-incompatible';
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: {
+        readonly path: string;
+        readonly message: string;
+    };
+};
+export declare function validateProfileCapture(value: unknown): ProfileResult<ProfileCapture, ProfileArtifactError>;
+//# sourceMappingURL=schema.d.ts.map

package/dist/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAiB,MAAM,gCAAgC,CAAC;AACpF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhD,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,CAAC,IAAI,EAAE,0BAA0B,GAAG,+BAA+B,CAAC;IAC5E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CACtE,CAAC;AAsIF,wBAAgB,sBAAsB,CACpC,KAAK,EAAE,OAAO,GACb,aAAa,CAAC,cAAc,EAAE,oBAAoB,CAAC,CAkBrD"}

package/dist/tool-preview-profile.d.ts

@@ -0,0 +1,33 @@
+import { type ProfileCapture } from './index.js';
+export interface ToolPreviewProfileRef {
+    readonly kind: 'profile-capture';
+    readonly digest: string;
+    readonly uri: string;
+}
+export interface ToolPreviewProfileManifest {
+    readonly runId: string;
+    readonly captureId: string;
+    readonly profileDigest: string;
+}
+export type ToolPreviewProfileResult = {
+    readonly ok: true;
+    readonly value: {
+        readonly runId: string;
+        readonly captureId: string;
+        readonly profile: ProfileCapture;
+    };
+} | {
+    readonly ok: false;
+    readonly error: {
+        readonly code: string;
+        readonly expected: string;
+        readonly hint: string;
+        readonly detail: unknown;
+    };
+};
+export declare function consumeToolPreviewProfile(input: {
+    readonly manifest: ToolPreviewProfileManifest;
+    readonly profile: unknown;
+    readonly ref: ToolPreviewProfileRef;
+}): ToolPreviewProfileResult;
+//# sourceMappingURL=tool-preview-profile.d.ts.map

package/dist/tool-preview-profile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-preview-profile.d.ts","sourceRoot":"","sources":["../src/tool-preview-profile.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,cAAc,EAA0B,MAAM,YAAY,CAAC;AAEzE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED,MAAM,MAAM,wBAAwB,GAChC;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAC3B,QAAQ,CAAC,OAAO,EAAE,cAAc,CAAC;KAClC,CAAC;CACH,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;QACtB,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;KAC1B,CAAC;CACH,CAAC;AAEN,wBAAgB,yBAAyB,CAAC,KAAK,EAAE;IAC/C,QAAQ,CAAC,QAAQ,EAAE,0BAA0B,CAAC;IAC9C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,GAAG,EAAE,qBAAqB,CAAC;CACrC,GAAG,wBAAwB,CAiB3B"}

package/dist/types.d.ts

@@ -0,0 +1,44 @@
+import type { ProfileCapture, ProfileCompleteness, ProfilePhaseRecord, ProfileRecord, ProfileSkipRecord, ProfileSource } from './generated/profile-capture.js';
+export type { ProfileCapture, ProfileCompleteness, ProfilePhaseRecord, ProfileRecord, ProfileSkipRecord, ProfileSource, };
+export type ProfileResult<T, E> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly error: E;
+};
+export type ProfileSinkFailure = {
+    readonly code: string;
+    readonly expected?: string;
+    readonly hint?: string;
+    readonly detail?: {
+        readonly message?: string;
+    };
+};
+export type ProfileSinkWriteResult = {
+    readonly ok: true;
+    readonly value?: undefined;
+} | {
+    readonly ok: false;
+    readonly error: ProfileSinkFailure;
+};
+export interface ProfileSink {
+    write(capture: ProfileCapture): void | ProfileSinkWriteResult;
+}
+export interface ProfileAllocationReport {
+    profilerEventObjectAllocations: number;
+}
+export interface ProfileFrameToken {
+    readonly captureId: string;
+    readonly frameId: number;
+}
+export interface ProfilePhaseStart {
+    readonly source: ProfileSource;
+    readonly phase: string;
+}
+export interface ProfileSkipInput {
+    readonly source: ProfileSource;
+    readonly phase: string;
+    readonly reason: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,aAAa,EACd,MAAM,gCAAgC,CAAC;AAExC,YAAY,EACV,cAAc,EACd,mBAAmB,EACnB,kBAAkB,EAClB,aAAa,EACb,iBAAiB,EACjB,aAAa,GACd,CAAC;AAEF,MAAM,MAAM,aAAa,CAAC,CAAC,EAAE,CAAC,IAC1B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,GACxC;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAA;CAAE,CAAC;AAE9C,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE;QAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD,CAAC;AAEF,MAAM,MAAM,sBAAsB,GAC9B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,CAAC,EAAE,SAAS,CAAA;CAAE,GACjD;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,kBAAkB,CAAA;CAAE,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,sBAAsB,CAAC;CAC/D;AAED,MAAM,WAAW,uBAAuB;IACtC,8BAA8B,EAAE,MAAM,CAAC;CACxC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB"}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@forgeax/engine-profiler",
+  "version": "0.1.2",
+  "private": false,
+  "type": "module",
+  "license": "Apache-2.0",
+  "sideEffects": false,
+  "description": "CPU profile capture, bounded recording, and deterministic offline analysis for forgeax-engine.",
+  "bin": {
+    "forgeax-engine-profiler": "./bin/forgeax-engine-profiler.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs"
+    },
+    "./cli": {
+      "types": "./dist/cli.d.ts",
+      "import": "./dist/cli.mjs"
+    },
+    "./browser-user-timing": {
+      "types": "./dist/browser-user-timing.d.ts",
+      "import": "./dist/browser-user-timing.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "bin",
+    "dist",
+    "schema",
+    "src",
+    "scripts",
+    "README.md",
+    "LICENSE"
+  ],
+  "dependencies": {
+    "ajv": "^8.17.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0"
+  },
+  "forgeax": {
+    "metrics": {
+      "bundle-size": {
+        "enabled": true,
+        "path": "dist/index.mjs",
+        "compression": "gzip"
+      },
+      "fps": {
+        "enabled": false,
+        "reason": "library package without a canvas frame loop"
+      },
+      "bench": {
+        "enabled": false,
+        "reason": "performance gate runs through the package test:perf script"
+      },
+      "gate": {
+        "enabled": true,
+        "command": "pnpm --filter @forgeax/engine-profiler test:perf"
+      },
+      "spike-report": {
+        "enabled": false,
+        "reason": "not a spike package"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsup",
+    "cli": "node bin/forgeax-engine-profiler.mjs",
+    "test": "vitest run",
+    "smoke:consumer": "node scripts/consume-smoke.mjs",
+    "test:perf": "node ../../scripts/bench/profiler-overhead.mjs"
+  }
+}

package/schema/profile-capture.schema.json

@@ -0,0 +1,71 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://forgeax.dev/schemas/profile-capture-1.0.json",
+  "title": "ForgeaX ProfileCapture",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "captureId", "timeUnit", "frameLimit", "eventLimit", "phaseCatalog", "records", "completeness"],
+  "properties": {
+    "schemaVersion": { "const": "1.0" },
+    "captureId": { "type": "string", "pattern": "^capture-[0-9]{4,}$" },
+    "timeUnit": { "const": "microseconds" },
+    "frameLimit": { "$ref": "#/$defs/positiveSafeInteger" },
+    "eventLimit": { "$ref": "#/$defs/positiveSafeInteger" },
+    "phaseCatalog": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["app", "render"],
+      "properties": { "app": { "$ref": "#/$defs/phaseNames" }, "render": { "$ref": "#/$defs/phaseNames" } }
+    },
+    "records": { "type": "array", "items": { "$ref": "#/$defs/record" } },
+    "completeness": { "$ref": "#/$defs/completeness" }
+  },
+  "$defs": {
+    "positiveSafeInteger": { "type": "integer", "minimum": 1, "maximum": 9007199254740991 },
+    "nonNegativeSafeInteger": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 },
+    "phaseNames": { "type": "array", "items": { "type": "string", "minLength": 1 }, "uniqueItems": true },
+    "source": { "enum": ["app", "render"] },
+    "phaseRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "source", "frameId", "phase", "startMicros", "endMicros", "durationMicros"],
+      "properties": {
+        "kind": { "const": "phase" },
+        "source": { "$ref": "#/$defs/source" },
+        "frameId": { "$ref": "#/$defs/positiveSafeInteger" },
+        "phase": { "type": "string", "minLength": 1 },
+        "parentSource": { "$ref": "#/$defs/source" },
+        "parentPhase": { "type": "string", "minLength": 1 },
+        "startMicros": { "$ref": "#/$defs/nonNegativeSafeInteger" },
+        "endMicros": { "$ref": "#/$defs/nonNegativeSafeInteger" },
+        "durationMicros": { "$ref": "#/$defs/nonNegativeSafeInteger" }
+      }
+    },
+    "skipRecord": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["kind", "source", "frameId", "phase", "reason"],
+      "properties": {
+        "kind": { "const": "skip" },
+        "source": { "$ref": "#/$defs/source" },
+        "frameId": { "$ref": "#/$defs/positiveSafeInteger" },
+        "phase": { "type": "string", "minLength": 1 },
+        "reason": { "type": "string", "minLength": 1 }
+      }
+    },
+    "record": { "oneOf": [{ "$ref": "#/$defs/phaseRecord" }, { "$ref": "#/$defs/skipRecord" }] },
+    "completeness": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["status", "retainedEventCount", "droppedEventCount"],
+      "properties": {
+        "status": { "enum": ["complete", "partial", "overflow"] },
+        "retainedEventCount": { "$ref": "#/$defs/nonNegativeSafeInteger" },
+        "droppedEventCount": { "$ref": "#/$defs/nonNegativeSafeInteger" },
+        "incompleteReason": { "type": "string", "minLength": 1 },
+        "firstAffectedFrameId": { "$ref": "#/$defs/positiveSafeInteger" },
+        "lastAffectedFrameId": { "$ref": "#/$defs/positiveSafeInteger" }
+      }
+    }
+  }
+}

package/scripts/consume-smoke.mjs

@@ -0,0 +1,17 @@
+import { spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+
+const cliPath = fileURLToPath(new URL('../dist/cli.mjs', import.meta.url));
+const fixturePath = fileURLToPath(
+  new URL('../src/__tests__/fixtures/profile-capture/model-input.json', import.meta.url),
+);
+const result = spawnSync(process.execPath, [cliPath, 'summary', '--file', fixturePath], {
+  encoding: 'utf8',
+});
+
+if (result.status !== 0) {
+  process.stderr.write(result.stderr);
+  process.exitCode = result.status ?? 1;
+} else {
+  process.stdout.write(result.stdout);
+}

package/scripts/generate-profile-types.mjs

@@ -0,0 +1,75 @@
+import { readFileSync, writeFileSync } from 'node:fs';
+
+const packageRoot = new URL('../', import.meta.url);
+const schemaPath = new URL('./schema/profile-capture.schema.json', packageRoot);
+const outputPath = new URL('./src/generated/profile-capture.ts', packageRoot);
+const schema = JSON.parse(readFileSync(schemaPath, 'utf8'));
+const literalUnion = (values) => values.map((value) => `'${value}'`).join(' | ');
+const resolveDefinition = (reference) => schema.$defs[reference.slice('#/$defs/'.length)];
+const profileSource = literalUnion(schema.$defs.source.enum);
+const profileRecordKind = literalUnion(
+  schema.$defs.record.oneOf.map(
+    ({ $ref }) => resolveDefinition($ref).properties.kind.const,
+  ),
+);
+const profileCompletenessStatus = literalUnion(schema.$defs.completeness.properties.status.enum);
+
+const output = `// Generated by scripts/generate-profile-types.mjs. Do not edit.
+// Schema version: ${schema.properties.schemaVersion.const}
+
+export type ProfileSource = ${profileSource};
+export type ProfileRecordKind = ${profileRecordKind};
+export type ProfileCompletenessStatus = ${profileCompletenessStatus};
+
+export interface ProfilePhaseRecord {
+  readonly kind: 'phase';
+  readonly source: ProfileSource;
+  readonly frameId: number;
+  readonly phase: string;
+  readonly parentSource?: ProfileSource;
+  readonly parentPhase?: string;
+  readonly startMicros: number;
+  readonly endMicros: number;
+  readonly durationMicros: number;
+}
+
+export interface ProfileSkipRecord {
+  readonly kind: 'skip';
+  readonly source: ProfileSource;
+  readonly frameId: number;
+  readonly phase: string;
+  readonly reason: string;
+}
+
+export type ProfileRecord = ProfilePhaseRecord | ProfileSkipRecord;
+
+export interface ProfileCompleteness {
+  readonly status: ProfileCompletenessStatus;
+  readonly retainedEventCount: number;
+  readonly droppedEventCount: number;
+  readonly incompleteReason?: string;
+  readonly firstAffectedFrameId?: number;
+  readonly lastAffectedFrameId?: number;
+}
+
+export interface ProfileCapture {
+  readonly schemaVersion: '1.0';
+  readonly captureId: string;
+  readonly timeUnit: 'microseconds';
+  readonly frameLimit: number;
+  readonly eventLimit: number;
+  readonly phaseCatalog: Readonly<{ app: readonly string[]; render: readonly string[] }>;
+  readonly records: readonly ProfileRecord[];
+  readonly completeness: ProfileCompleteness;
+}
+`;
+
+if (process.argv.includes('--check')) {
+  const current = readFileSync(outputPath, 'utf8');
+  if (current !== output) {
+    process.stderr.write(`${outputPath.pathname} is stale\n`);
+    process.exitCode = 1;
+  }
+} else {
+  writeFileSync(outputPath, output);
+}

package/src/__tests__/browser-profile-detail-owner.test-d.ts

@@ -0,0 +1,26 @@
+import { readFileSync } from 'node:fs';
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type { ProfileDetail, RecorderSession } from '../index.js';
+
+type ExpectedProfileDetail = 'owner' | 'passes' | 'nested';
+const browserSource = readFileSync(new URL('../browser-user-timing.ts', import.meta.url), 'utf8');
+const recorderSource = readFileSync(new URL('../recorder.ts', import.meta.url), 'utf8');
+
+describe('browser ProfileDetail owner', () => {
+  it('preserves the public vocabulary and session detail projection', () => {
+    expectTypeOf<ProfileDetail>().toEqualTypeOf<ExpectedProfileDetail>();
+    expectTypeOf<RecorderSession['detail']>().toEqualTypeOf<ProfileDetail>();
+    expectTypeOf<ProfileDetail>().toEqualTypeOf<RecorderSession['detail']>();
+  });
+
+  it('derives the private browser view from the recorder owner', () => {
+    expect(browserSource).toContain(
+      "import type { ProfileDetail, RecorderSession } from './recorder.js';",
+    );
+    expect(browserSource).toContain('type BrowserProfileDetail = ProfileDetail;');
+    expect(browserSource).not.toContain(
+      "type BrowserProfileDetail = 'owner' | 'passes' | 'nested';",
+    );
+    expect(recorderSource).toContain("export type ProfileDetail = 'owner' | 'passes' | 'nested';");
+  });
+});

package/src/__tests__/browser-user-timing.test.ts

@@ -0,0 +1,127 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { createUserTimingProfiler } from '../browser-user-timing.js';
+import { runProfilerCli } from '../cli.js';
+import { buildProfileModel } from '../model.js';
+import { validateProfileCapture } from '../schema.js';
+import type { ProfileCapture, ProfileResult } from '../types.js';
+
+const DIAGNOSTICS_KEY = '__forgeaxFramePhaseDiagnostics';
+const APP_PHASES = ['frame-total', 'world-update-primary'] as const;
+const RENDER_PHASES = ['extract', 'record'] as const;
+
+function expectOk<T, E>(result: ProfileResult<T, E>): T {
+  expect(result.ok).toBe(true);
+  if (!result.ok) throw new Error('expected a successful profiler result');
+  return result.value;
+}
+
+function enableDiagnostics(detail: 'owner' | 'passes' | 'nested' = 'nested'): void {
+  (globalThis as Record<string, unknown>)[DIAGNOSTICS_KEY] = { enabled: true, detail };
+}
+
+function registerCatalogs(
+  profiler: NonNullable<ReturnType<typeof createUserTimingProfiler>>,
+): void {
+  expectOk(profiler.registerPhaseCatalog('app', APP_PHASES));
+  expectOk(profiler.registerPhaseCatalog('render', RENDER_PHASES));
+}
+
+function finishOneFrame(
+  profiler: NonNullable<ReturnType<typeof createUserTimingProfiler>>,
+): ProfileCapture {
+  const session = expectOk(profiler.startCapture({ frameLimit: 2, eventLimit: 8 }));
+  expectOk(session.beginFrame(1));
+  expectOk(session.beginPhase({ source: 'app', phase: 'frame-total' }));
+  expectOk(session.endPhase());
+  expectOk(session.beginPhase({ source: 'render', phase: 'record' }));
+  expectOk(session.endPhase());
+  expectOk(session.endFrame());
+  return expectOk(session.finish());
+}
+
+afterEach(() => {
+  Reflect.deleteProperty(globalThis, DIAGNOSTICS_KEY);
+  vi.unstubAllGlobals();
+});
+
+describe('browser User Timing profiler', () => {
+  it('emits a schema-valid default capture through model and CLI consumers', () => {
+    enableDiagnostics();
+    const profiler = createUserTimingProfiler();
+    expect(profiler).toBeDefined();
+    if (profiler === undefined) return;
+    registerCatalogs(profiler);
+
+    const capture = finishOneFrame(profiler);
+
+    expect(capture.captureId).toBe('capture-0001');
+    expect(capture.completeness).toEqual({
+      status: 'partial',
+      retainedEventCount: 0,
+      droppedEventCount: 0,
+      incompleteReason: 'user-timing-transport',
+    });
+    expect(validateProfileCapture(capture).ok).toBe(true);
+
+    const model = buildProfileModel(capture);
+    expect(model.ok).toBe(true);
+    if (!model.ok) return;
+    expect(model.value.summary.captureId).toBe('capture-0001');
+
+    const cli = runProfilerCli(['summary'], JSON.stringify(capture));
+    expect(cli.exitCode).toBe(0);
+    expect(JSON.parse(cli.stdout)).toMatchObject({ captureId: 'capture-0001' });
+  });
+
+  it('preserves valid caller IDs and derives the default for invalid IDs', () => {
+    enableDiagnostics('owner');
+    const valid = createUserTimingProfiler({ captureId: 'capture-1234' });
+    expect(valid).toBeDefined();
+    if (valid === undefined) return;
+    expect(finishOneFrame(valid).captureId).toBe('capture-1234');
+
+    const invalid = createUserTimingProfiler({ captureId: 'host-session' });
+    expect(invalid).toBeDefined();
+    if (invalid === undefined) return;
+    const capture = finishOneFrame(invalid);
+    expect(capture.captureId).toBe('capture-0001');
+    expect(validateProfileCapture(capture).ok).toBe(true);
+  });
+
+  it('keeps disabled creation inert and retains onPhaseEnd-only callbacks', () => {
+    const mark = vi.fn();
+    vi.stubGlobal('performance', { mark });
+
+    expect(createUserTimingProfiler()).toBeUndefined();
+    expect(mark).not.toHaveBeenCalled();
+
+    const onPhaseEnd = vi.fn();
+    const profiler = createUserTimingProfiler({ onPhaseEnd });
+    expect(profiler).toBeDefined();
+    if (profiler === undefined) return;
+    const capture = finishOneFrame(profiler);
+
+    expect(onPhaseEnd).toHaveBeenCalledWith({ source: 'app', phase: 'frame-total' });
+    expect(onPhaseEnd).toHaveBeenCalledWith({ source: 'render', phase: 'record' });
+    expect(mark).not.toHaveBeenCalled();
+    expect(validateProfileCapture(capture).ok).toBe(true);
+  });
+
+  it('supports repeated start and finish with one partial artifact per session', () => {
+    enableDiagnostics('passes');
+    const profiler = createUserTimingProfiler();
+    expect(profiler).toBeDefined();
+    if (profiler === undefined) return;
+
+    const first = expectOk(profiler.startCapture({ frameLimit: 1, eventLimit: 1 }));
+    const firstCapture = expectOk(first.finish());
+    const second = expectOk(profiler.startCapture({ frameLimit: 1, eventLimit: 1 }));
+    const secondCapture = expectOk(second.finish());
+
+    expect(firstCapture.captureId).toBe('capture-0001');
+    expect(secondCapture.captureId).toBe('capture-0001');
+    expect(profiler.latestCapture()).toBe(secondCapture);
+    expect(validateProfileCapture(firstCapture).ok).toBe(true);
+    expect(validateProfileCapture(secondCapture).ok).toBe(true);
+  });
+});