@forgeax/engine-profiler 0.1.2

package/dist/clock.d.ts

@@ -0,0 +1,5 @@
+export interface ProfileClock {
+    nowMicros(): number;
+}
+export declare function createProfileClock(readMicros?: () => number): ProfileClock;
+//# sourceMappingURL=clock.d.ts.map

package/dist/clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"clock.d.ts","sourceRoot":"","sources":["../src/clock.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,YAAY;IAC3B,SAAS,IAAI,MAAM,CAAC;CACrB;AAED,wBAAgB,kBAAkB,CAAC,UAAU,GAAE,MAAM,MAA0B,GAAG,YAAY,CAS7F"}

package/dist/compare.d.ts

@@ -0,0 +1,42 @@
+import { type ProfilePhaseModel, type ProfileSummaryModel } from './model.js';
+import type { ProfileArtifactError } from './schema.js';
+import type { ProfileCapture, ProfileResult } from './types.js';
+export interface ProfileComparisonPhaseIdentity {
+    readonly source: ProfilePhaseModel['source'];
+    readonly phase: string;
+    readonly parentSource?: ProfilePhaseModel['parentSource'];
+    readonly parentPhase?: string;
+}
+export interface ProfileComparisonPhaseFact {
+    readonly count: number;
+    readonly skipCount: number;
+    readonly p95DurationMicros: number | null;
+}
+export interface ProfileComparisonPhaseDelta {
+    readonly count?: number;
+    readonly skipCount?: number;
+    readonly p95DurationMicros?: number;
+}
+export interface ProfileComparisonPhaseRow {
+    readonly identity: ProfileComparisonPhaseIdentity;
+    readonly left?: ProfileComparisonPhaseFact;
+    readonly right?: ProfileComparisonPhaseFact;
+    readonly delta?: ProfileComparisonPhaseDelta;
+}
+export interface ProfileComparisonSide {
+    readonly summary: ProfileSummaryModel;
+    readonly completeness: ProfileCapture['completeness'];
+}
+export interface ProfileComparisonProjection {
+    readonly left: ProfileComparisonSide;
+    readonly right: ProfileComparisonSide;
+    readonly phases: readonly ProfileComparisonPhaseRow[];
+}
+export type ProfileComparisonError = ProfileArtifactError & {
+    readonly detail: ProfileArtifactError['detail'] & {
+        readonly side: 'left' | 'right';
+    };
+};
+/** Compares two imported ProfileCapture artifacts without mutating either input. */
+export declare function compareProfileCaptures(left: unknown, right: unknown): ProfileResult<ProfileComparisonProjection, ProfileComparisonError>;
+//# sourceMappingURL=compare.d.ts.map

package/dist/compare.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"compare.d.ts","sourceRoot":"","sources":["../src/compare.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,mBAAmB,EACzB,MAAM,YAAY,CAAC;AACpB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,KAAK,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAEhE,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC,QAAQ,CAAC,CAAC;IAC7C,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,iBAAiB,CAAC,cAAc,CAAC,CAAC;IAC1D,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,0BAA0B;IACzC,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,2BAA2B;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,QAAQ,EAAE,8BAA8B,CAAC;IAClD,QAAQ,CAAC,IAAI,CAAC,EAAE,0BAA0B,CAAC;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,0BAA0B,CAAC;IAC5C,QAAQ,CAAC,KAAK,CAAC,EAAE,2BAA2B,CAAC;CAC9C;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,OAAO,EAAE,mBAAmB,CAAC;IACtC,QAAQ,CAAC,YAAY,EAAE,cAAc,CAAC,cAAc,CAAC,CAAC;CACvD;AAED,MAAM,WAAW,2BAA2B;IAC1C,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,qBAAqB,CAAC;IACtC,QAAQ,CAAC,MAAM,EAAE,SAAS,yBAAyB,EAAE,CAAC;CACvD;AAED,MAAM,MAAM,sBAAsB,GAAG,oBAAoB,GAAG;IAC1D,QAAQ,CAAC,MAAM,EAAE,oBAAoB,CAAC,QAAQ,CAAC,GAAG;QAChD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;KACjC,CAAC;CACH,CAAC;AAgGF,oFAAoF;AACpF,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,OAAO,EACb,KAAK,EAAE,OAAO,GACb,aAAa,CAAC,2BAA2B,EAAE,sBAAsB,CAAC,CAQpE"}

package/dist/errors.d.ts

@@ -0,0 +1,64 @@
+import type { ProfileResult, ProfileSource } from './types.js';
+/** Structured profiler failure with a code-specific detail payload. */
+export type ProfilerError = {
+    readonly code: 'capture-boundary-invalid';
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: {
+        readonly frameLimit: unknown;
+        readonly eventLimit: unknown;
+    };
+} | {
+    readonly code: 'capture-already-active';
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: {
+        readonly captureId: string;
+    };
+} | {
+    readonly code: 'profiler-not-enabled';
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: {
+        readonly enabled: false;
+    };
+} | {
+    readonly code: 'phase-catalog-conflict';
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: {
+        readonly source: ProfileSource;
+        readonly expected: readonly string[];
+        readonly actual: readonly string[];
+    };
+} | {
+    readonly code: 'profile-source-failed';
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: {
+        readonly source: string;
+        readonly phase: string;
+        readonly frameId: number;
+    };
+} | {
+    readonly code: 'profile-sink-failed';
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: {
+        readonly message: string;
+    };
+} | {
+    readonly code: 'capture-state-invalid';
+    readonly expected: string;
+    readonly hint: string;
+    readonly detail: {
+        readonly operation: string;
+    };
+};
+/** Closed expected-failure vocabulary derived from the public profiler error owner. */
+export type ProfilerErrorCode = ProfilerError['code'];
+/** Result shape returned by profiler operations. */
+export type ProfilerResult<T> = ProfileResult<T, ProfilerError>;
+export declare function boundaryError(frameLimit: unknown, eventLimit: unknown): ProfilerError;
+export declare function stateError(operation: string): ProfilerError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE/D,uEAAuE;AACvE,MAAM,MAAM,aAAa,GACrB;IACE,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAC1C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;QAAC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC;CACjF,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,sBAAsB,CAAC;IACtC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,KAAK,CAAA;KAAE,CAAC;CAC9C,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,wBAAwB,CAAC;IACxC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;QAC/B,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;QACrC,QAAQ,CAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;KACpC,CAAC;CACH,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QACf,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;QACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;KAC1B,CAAC;CACH,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,qBAAqB,CAAC;IACrC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;CAC/C,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAC;IACvC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD,CAAC;AAEN,uFAAuF;AACvF,MAAM,MAAM,iBAAiB,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;AAEtD,oDAAoD;AACpD,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,aAAa,CAAC,CAAC,EAAE,aAAa,CAAC,CAAC;AAEhE,wBAAgB,aAAa,CAAC,UAAU,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,GAAG,aAAa,CAOrF;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,GAAG,aAAa,CAO3D"}

package/dist/generated/profile-capture.d.ts

@@ -0,0 +1,44 @@
+export type ProfileSource = 'app' | 'render';
+export type ProfileRecordKind = 'phase' | 'skip';
+export type ProfileCompletenessStatus = 'complete' | 'partial' | 'overflow';
+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;
+}
+//# sourceMappingURL=profile-capture.d.ts.map

package/dist/generated/profile-capture.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"profile-capture.d.ts","sourceRoot":"","sources":["../../src/generated/profile-capture.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG,KAAK,GAAG,QAAQ,CAAC;AAC7C,MAAM,MAAM,iBAAiB,GAAG,OAAO,GAAG,MAAM,CAAC;AACjD,MAAM,MAAM,yBAAyB,GAAG,UAAU,GAAG,SAAS,GAAG,UAAU,CAAC;AAE5E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,YAAY,CAAC,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,aAAa,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;AAEnE,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,MAAM,EAAE,yBAAyB,CAAC;IAC3C,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,oBAAoB,CAAC,EAAE,MAAM,CAAC;IACvC,QAAQ,CAAC,mBAAmB,CAAC,EAAE,MAAM,CAAC;CACvC;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,aAAa,EAAE,KAAK,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,cAAc,CAAC;IAClC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;QAAE,GAAG,EAAE,SAAS,MAAM,EAAE,CAAC;QAAC,MAAM,EAAE,SAAS,MAAM,EAAE,CAAA;KAAE,CAAC,CAAC;IACvF,QAAQ,CAAC,OAAO,EAAE,SAAS,aAAa,EAAE,CAAC;IAC3C,QAAQ,CAAC,YAAY,EAAE,mBAAmB,CAAC;CAC5C"}

package/dist/index.d.ts

@@ -0,0 +1,22 @@
+/** Creates the default monotonic microsecond clock. */
+/** Opt-in browser User Timing projection shared by editor and Play hosts. */
+export { createUserTimingProfiler, type UserTimingProfilerOptions, } from './browser-user-timing.js';
+export { createProfileClock } from './clock.js';
+export type { ProfileComparisonError, ProfileComparisonPhaseDelta, ProfileComparisonPhaseFact, ProfileComparisonPhaseIdentity, ProfileComparisonPhaseRow, ProfileComparisonProjection, ProfileComparisonSide, } from './compare.js';
+/** Compares two validated captures without adding policy or mutating either input. */
+export { compareProfileCaptures } from './compare.js';
+/** Structured expected-failure vocabulary for profiler operations. */
+export type { ProfilerError, ProfilerErrorCode } from './errors.js';
+export type { ProfileFrameModel, ProfileModel, ProfilePhaseModel, ProfileSummaryModel, } from './model.js';
+/** Projects a validated capture into offline frame and phase summaries. */
+export { buildProfileModel } from './model.js';
+/** Bounded CPU profiler capability; it is inert until a host passes it to App or Render. */
+export type { Profiler } from './profiler.js';
+/** Creates an opt-in bounded profiler with optional sink and allocation evidence. */
+export { createProfiler } from './profiler.js';
+export type { ProfileDetail, RecorderSession } from './recorder.js';
+/** Validates a persisted capture before model building or CLI-style analysis. */
+export { validateProfileCapture } from './schema.js';
+export { consumeToolPreviewProfile, type ToolPreviewProfileManifest, type ToolPreviewProfileRef, type ToolPreviewProfileResult, } from './tool-preview-profile.js';
+export type { ProfileAllocationReport, ProfileCapture, ProfileCompleteness, ProfileFrameToken, ProfilePhaseRecord, ProfileRecord, ProfileResult, ProfileSink, ProfileSkipRecord, ProfileSource, } from './types.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,uDAAuD;AAEvD,6EAA6E;AAC7E,OAAO,EACL,wBAAwB,EACxB,KAAK,yBAAyB,GAC/B,MAAM,0BAA0B,CAAC;AAClC,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,YAAY,EACV,sBAAsB,EACtB,2BAA2B,EAC3B,0BAA0B,EAC1B,8BAA8B,EAC9B,yBAAyB,EACzB,2BAA2B,EAC3B,qBAAqB,GACtB,MAAM,cAAc,CAAC;AACtB,sFAAsF;AACtF,OAAO,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AACtD,sEAAsE;AACtE,YAAY,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AACpE,YAAY,EACV,iBAAiB,EACjB,YAAY,EACZ,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AACpB,2EAA2E;AAC3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,YAAY,CAAC;AAC/C,4FAA4F;AAC5F,YAAY,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAC9C,qFAAqF;AACrF,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,YAAY,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACpE,iFAAiF;AACjF,OAAO,EAAE,sBAAsB,EAAE,MAAM,aAAa,CAAC;AACrD,OAAO,EACL,yBAAyB,EACzB,KAAK,0BAA0B,EAC/B,KAAK,qBAAqB,EAC1B,KAAK,wBAAwB,GAC9B,MAAM,2BAA2B,CAAC;AACnC,YAAY,EACV,uBAAuB,EACvB,cAAc,EACd,mBAAmB,EACnB,iBAAiB,EACjB,kBAAkB,EAClB,aAAa,EACb,aAAa,EACb,WAAW,EACX,iBAAiB,EACjB,aAAa,GACd,MAAM,YAAY,CAAC"}