@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/stage/isolation.ts

@@ -23,9 +23,21 @@
 //
 // The frustum is sized from the subtree's own bounds, measured in the ROOT's
 // frame, so entering a subtree frames it whatever the scene camera was doing.
-import { toLocal, worldStateAt } from "@dailies-studio/shot/doc";
-import type { Mat3, Scene3D, Vec3 } from "@dailies-studio/shot/doc";
+import { effectiveTransform, layerAliveAt, layerChildren, toLocal, worldStateAt } from "@dailies-studio/shot/doc";
+import type { LayerLookup, Mat3, Vec3 } from "@dailies-studio/shot/doc";
 import type { Rational } from "@dailies-studio/engine";
+import type { PaneRect } from "./panes.js";
+
+/**
+ * Bind-pose box sizes by layer id, as the runtime measured them.
+ *
+ * A model is contain-fitted INTO its authored box (`applyFit`), so a model whose
+ * bind-pose aspect differs from that box occupies only part of it. Framing the
+ * box therefore frames empty air on two sides, which is most of why an isolated
+ * mesh read small. The stage collects these from `onMeshStats` and they never
+ * cross the bridge — this is a viewing decision, not a document one.
+ */
+export type MeshBounds = ReadonlyMap<string, readonly [number, number, number]>;
 
 /** How much of the pane is margin around the framed subtree, per side. */
 export const ISOLATION_MARGIN = 0.12;
@@ -34,6 +46,26 @@ export const ISOLATION_MARGIN = 0.12;
  *  a real document, and a zero-width ortho camera projects everything to NaN. */
 const MIN_HALF_EXTENT = 1;
 
+/**
+ * The COMPONENT CONTEXT's frame (unify P2): a definition's canvas is flat at
+ * the origin in its own basis, so its head-on frame is a literal — never a
+ * derivation off an instance (`isolationFrame` needs a scene and a placed
+ * root, and a def-first entry has neither).
+ */
+export function componentFrame(size: readonly [number, number]): IsolationFrame {
+  return {
+    target: [0, 0, 0],
+    rotation: [
+      [1, 0, 0],
+      [0, 1, 0],
+      [0, 0, 1],
+    ],
+    halfWidth: Math.max(MIN_HALF_EXTENT, size[0] / 2),
+    halfHeight: Math.max(MIN_HALF_EXTENT, size[1] / 2),
+    halfDepth: MIN_HALF_EXTENT,
+  };
+}
+
 export interface IsolationFrame {
   /** Where to look, in THREE world space. */
   target: Vec3;
@@ -53,58 +85,284 @@ export interface IsolationFrame {
  * parent is mid-rotation is looking at where it is now. Returns null when the
  * layer is not in this scene, which is what "the isolation went stale" looks
  * like from here.
+ *
+ * A bare `LayerLookup` and not a `Scene3D`, because a component DEFINITION is
+ * also a layer table and a mesh inside one deserves the same head-on frame a
+ * mesh in a scene gets. Nothing here ever read anything but `layersById`.
  */
 export function isolationFrame(
-  scene: Scene3D,
+  scene: LayerLookup,
   rootId: string,
   subtree: ReadonlySet<string>,
   sceneFrame: number,
   fps: Rational,
+  meshBounds?: MeshBounds,
+): IsolationFrame | null {
+  if (scene.layersById[rootId] === undefined) return null;
+  const rootPose = worldStateAt(scene, rootId, sceneFrame, fps);
+  const bounds = emptyBounds();
+  for (const id of subtree) addMember(bounds, scene, rootPose, id, sceneFrame, fps, meshBounds);
+  return frameOf(rootPose, bounds);
+}
+
+/** The most frames `isolationFrameOverLife` resolves the subtree at. */
+export const MAX_LIFE_SAMPLES = 240;
+
+/**
+ * The head-on frame that holds `rootId`'s subtree for its WHOLE life, seen from
+ * the root's pose at `anchorFrame`.
+ *
+ * ── WHY NOT THE FRAME AT THE PLAYHEAD ────────────────────────────────────
+ *
+ * The frame at one instant is the right size for that instant only. Fitted per
+ * frame during playback, the camera re-centred and re-zoomed on every frame, so
+ * anything that moved or scaled inside the subtree was cancelled out by the
+ * camera chasing it: the picture slid and pulsed while the subject stood still.
+ * Isolation is a place the author edits in, so its camera holds still and the
+ * motion plays inside it. That needs a box that already contains every pose.
+ *
+ * The basis is the root's pose at the ANCHOR (the frame the author entered on),
+ * not at each sample: a root that rotates over its life would otherwise give a
+ * union of boxes measured in different frames, which bounds nothing. Every
+ * member at every sample is measured in that one basis.
+ *
+ * Only what DRAWS is counted: a member outside its lifetime, hidden, or under a
+ * parent that is either, paints nothing at that frame, and framing where it
+ * would have been is empty margin. Ancestors ABOVE the root are not consulted:
+ * when one of them is dead the whole subtree is, and that frame adds nothing.
+ * Nothing drawing at any sample falls back to the anchor frame's own box, so a
+ * subtree that is never on screen still opens on something.
+ *
+ * ponytail: past `MAX_LIFE_SAMPLES` frames the life is sampled at an even
+ * stride, so an overshoot between two samples can poke past the box. The 12%
+ * margin absorbs any ordinary ease. Sample the track keys too if it ever clips.
+ */
+export function isolationFrameOverLife(
+  scene: LayerLookup,
+  rootId: string,
+  anchorFrame: number,
+  durationFrames: number,
+  fps: Rational,
+  meshBounds?: MeshBounds,
 ): IsolationFrame | null {
   const root = scene.layersById[rootId];
   if (root === undefined) return null;
-  const rootPose = worldStateAt(scene, rootId, sceneFrame, fps);
+  const rootPose = worldStateAt(scene, rootId, anchorFrame, fps);
+  const bounds = emptyBounds();
+  const end = Math.max(1, Math.floor(durationFrames));
+  const stride = Math.max(1, end / MAX_LIFE_SAMPLES);
+  for (let s = 0; s < end; s += stride) {
+    const frame = Math.floor(s);
+    // Depth-first from the root, carrying "every ancestor down here draws".
+    const visit = (id: string): void => {
+      const layer = scene.layersById[id];
+      if (layer === undefined || !layerAliveAt(layer, frame)) return;
+      addMember(bounds, scene, rootPose, id, frame, fps, meshBounds);
+      for (const child of layerChildren(layer)) visit(child);
+    };
+    visit(rootId);
+  }
+  return Number.isFinite(bounds.minX)
+    ? frameOf(rootPose, bounds)
+    : isolationFrame(scene, rootId, subtreeOf(scene, rootId), anchorFrame, fps, meshBounds);
+}
 
-  let minX = Infinity;
-  let maxX = -Infinity;
-  let minY = Infinity;
-  let maxY = -Infinity;
-  let minZ = Infinity;
-  let maxZ = -Infinity;
-  for (const id of subtree) {
+/** `rootId` and every layer under it, through the one child walk. */
+function subtreeOf(scene: LayerLookup, rootId: string): Set<string> {
+  const out = new Set<string>();
+  const visit = (id: string): void => {
     const layer = scene.layersById[id];
-    if (layer === undefined) continue;
-    // Each member's centre in the ROOT's frame, with its own axis-aligned box
-    // around it. The box ignores the member's own tilt and roll, the same
-    // simplification `groupLayers` makes for the same reason: a rotation-aware
-    // hull would frame a rolled child looser than the box the author sees.
-    const local = toLocal(rootPose, worldStateAt(scene, id, sceneFrame, fps));
-    const [w, h] = layer.transform.size;
-    minX = Math.min(minX, local.position[0] - w / 2);
-    maxX = Math.max(maxX, local.position[0] + w / 2);
-    minY = Math.min(minY, local.position[1] - h / 2);
-    maxY = Math.max(maxY, local.position[1] + h / 2);
-    minZ = Math.min(minZ, local.position[2]);
-    maxZ = Math.max(maxZ, local.position[2]);
-  }
-  if (!Number.isFinite(minX)) return null;
+    if (layer === undefined || out.has(id)) return;
+    out.add(id);
+    for (const child of layerChildren(layer)) visit(child);
+  };
+  visit(rootId);
+  return out;
+}
+
+interface Bounds {
+  minX: number;
+  maxX: number;
+  minY: number;
+  maxY: number;
+  minZ: number;
+  maxZ: number;
+}
+
+function emptyBounds(): Bounds {
+  return { minX: Infinity, maxX: -Infinity, minY: Infinity, maxY: -Infinity, minZ: Infinity, maxZ: -Infinity };
+}
 
+/** Grow `bounds` by one member's box at one frame, measured in `rootPose`. */
+function addMember(
+  bounds: Bounds,
+  scene: LayerLookup,
+  rootPose: ReturnType<typeof worldStateAt>,
+  id: string,
+  sceneFrame: number,
+  fps: Rational,
+  meshBounds: MeshBounds | undefined,
+): void {
+  const layer = scene.layersById[id];
+  if (layer === undefined) return;
+  // Each member's centre in the ROOT's frame, with its own axis-aligned box
+  // around it. The box ignores the member's own tilt and roll, the same
+  // simplification `groupLayers` makes for the same reason: a rotation-aware
+  // hull would frame a rolled child looser than the box the author sees.
+  const local = toLocal(rootPose, worldStateAt(scene, id, sceneFrame, fps));
+  // The EFFECTIVE size, not the authored one. `worldStateAt` already resolves
+  // the chain, so reading `layer.transform.size` beside it framed a box the
+  // layer no longer occupies the moment a size track scaled it.
+  const [w, h] = effectiveTransform(layer, sceneFrame, fps).size;
+  const box = occupiedBox(layer, w, h, meshBounds?.get(id));
+  bounds.minX = Math.min(bounds.minX, local.position[0] - box[0] / 2);
+  bounds.maxX = Math.max(bounds.maxX, local.position[0] + box[0] / 2);
+  bounds.minY = Math.min(bounds.minY, local.position[1] - box[1] / 2);
+  bounds.maxY = Math.max(bounds.maxY, local.position[1] + box[1] / 2);
+  bounds.minZ = Math.min(bounds.minZ, local.position[2] - box[2] / 2);
+  bounds.maxZ = Math.max(bounds.maxZ, local.position[2] + box[2] / 2);
+}
+
+function frameOf(rootPose: ReturnType<typeof worldStateAt>, b: Bounds): IsolationFrame | null {
+  if (!Number.isFinite(b.minX)) return null;
   // The bounds' CENTRE, not the root's origin: a group whose children all sit
   // to one side would otherwise be framed off-centre, which is the state the
   // grouping arithmetic exists to make impossible to author but which a
   // hand-written document can still hold.
-  const centre: Vec3 = [(minX + maxX) / 2, (minY + maxY) / 2, (minZ + maxZ) / 2];
-  const world = worldOf(rootPose, centre);
-
+  const centre: Vec3 = [(b.minX + b.maxX) / 2, (b.minY + b.maxY) / 2, (b.minZ + b.maxZ) / 2];
   return {
-    target: world,
+    target: worldOf(rootPose, centre),
     rotation: rootPose.rotation,
-    halfWidth: Math.max(MIN_HALF_EXTENT, (maxX - minX) / 2),
-    halfHeight: Math.max(MIN_HALF_EXTENT, (maxY - minY) / 2),
-    halfDepth: Math.max(MIN_HALF_EXTENT, (maxZ - minZ) / 2),
+    halfWidth: Math.max(MIN_HALF_EXTENT, (b.maxX - b.minX) / 2),
+    halfHeight: Math.max(MIN_HALF_EXTENT, (b.maxY - b.minY) / 2),
+    halfDepth: Math.max(MIN_HALF_EXTENT, (b.maxZ - b.minZ) / 2),
   };
 }
 
+/**
+ * THE head-on camera: everything a consumer needs to draw, measure or hand over
+ * a derived frame, from one derivation.
+ *
+ * ── WHY ONE FUNCTION AND NOT THREE CALLERS OF `isolationExtent` ─────────
+ *
+ * There were three: the camera `StageTools` installs, `paneScreenScale` (which
+ * every drag speed and every snap threshold is measured in), and the pose the
+ * orbit rig is seeded with on entry. Three derivations of one number is three
+ * chances to disagree, and the disagreement is invisible — a drag that runs an
+ * order of magnitude fast looks like a bad feel, not like a bug. `pxPerUnit` is
+ * that number, answered once.
+ */
+export interface HeadOnCamera {
+  /** Orthographic half-extents covering the WHOLE pane, in design px. */
+  halfWidth: number;
+  halfHeight: number;
+  near: number;
+  far: number;
+  eye: Vec3;
+  up: Vec3;
+  /** Where the camera looks: the subject, slid so it lands centred in the
+   *  VISIBLE box rather than in the pane. */
+  target: Vec3;
+  /** CSS px per design px. The one scale every consumer measures with. */
+  pxPerUnit: number;
+}
+
+/**
+ * Frame a subtree head-on inside a pane the chrome is partly covering.
+ *
+ * The subject is fitted to `visible`; the frustum is then grown to cover `pane`
+ * AT THE SAME SCALE, and the target slid so the subject sits in the middle of
+ * the hole. So the picture behind the chrome is simply extra: nothing is
+ * scaled to fit furniture, and nothing hides under it.
+ *
+ * Pass the same rect twice for the un-inset behaviour (the tests, and any
+ * caller that genuinely owns its whole pane).
+ */
+export function headOnCamera(
+  frame: IsolationFrame,
+  pane: PaneRect,
+  visible: PaneRect,
+): HeadOnCamera {
+  const box = visible.width > 0 && visible.height > 0 ? visible : pane;
+  const fitted = isolationExtent(frame, box.height === 0 ? 1 : box.width / box.height);
+  // The scale the fit implies, and the only place it is decided.
+  const pxPerUnit = fitted.halfHeight > 0 ? box.height / (2 * fitted.halfHeight) : 1;
+  const halfWidth = pane.width / (2 * pxPerUnit);
+  const halfHeight = pane.height / (2 * pxPerUnit);
+
+  // ── THE SLIDE ────────────────────────────────────────────────────────────
+  //
+  // A camera looks at the middle of its pane, so the subject lands there. Push
+  // the target the OTHER way by however far the visible box's centre is from
+  // the pane's, and the subject lands in the visible box's middle instead.
+  //
+  // The axes are the frame's OWN basis, so this works for a rolled or a
+  // face-down subject exactly as it does for a flat one: column 0 is screen
+  // right and column 1 is screen up (`worldOf` maps design +x to column 0).
+  // Pane y runs DOWN, world up runs UP, which is why the two signs differ.
+  const dx = (visible.x + visible.width / 2 - (pane.x + pane.width / 2)) / pxPerUnit;
+  const dy = (visible.y + visible.height / 2 - (pane.y + pane.height / 2)) / pxPerUnit;
+  const right: Vec3 = [frame.rotation[0][0], frame.rotation[1][0], frame.rotation[2][0]];
+  const { eye, up, far } = isolationEye(frame);
+  const target: Vec3 = [
+    frame.target[0] - right[0] * dx + up[0] * dy,
+    frame.target[1] - right[1] * dx + up[1] * dy,
+    frame.target[2] - right[2] * dx + up[2] * dy,
+  ];
+  // The eye rides the target. The slide is perpendicular to the view normal, so
+  // the depth slab `isolationEye` sized is unchanged by it.
+  return {
+    halfWidth,
+    halfHeight,
+    near: 0.1,
+    far,
+    eye: [
+      eye[0] + (target[0] - frame.target[0]),
+      eye[1] + (target[1] - frame.target[1]),
+      eye[2] + (target[2] - frame.target[2]),
+    ],
+    up,
+    target,
+    pxPerUnit,
+  };
+}
+
+/**
+ * What a layer actually FILLS of its authored box, as a `[w, h, d]` extent.
+ *
+ * For everything but a loaded model that is the box itself, flat. A model is a
+ * different story: `applyFit` (shot/mesh.tsx) contain-fits the bind-pose box
+ * into the authored one, so a tall model in a square box paints a tall sliver
+ * and the two side thirds are empty. This mirrors that arithmetic exactly —
+ * the same `min(w/bx, h/by)`, the same per-axis `stretch`, the same "z takes
+ * the smaller of the two" — so the camera frames the MODEL and not its crate.
+ *
+ * Depth comes back with it, which is the second thing the old box could not
+ * say: a flat subtree used to collapse to `MIN_HALF_EXTENT` and size the ortho
+ * slab off a guess.
+ *
+ * ponytail: a primitive reports no bounds and falls back to its authored box.
+ * That is right for authored shapes (a Rect IS its box) and slightly generous
+ * for a non-uniformly scaled primitive, whose `primitiveFrameScale` is uniform.
+ * Upgrade by consulting the primitive's own params if it ever reads loose.
+ */
+function occupiedBox(
+  layer: { kind: string; mesh?: { fit?: "fit" | "stretch" } },
+  w: number,
+  h: number,
+  bind: readonly [number, number, number] | undefined,
+): readonly [number, number, number] {
+  if (layer.kind !== "mesh" || bind === undefined) return [w, h, 0];
+  const [bx, by, bz] = bind;
+  // A degenerate axis is a flat or empty model; `applyFit` leaves it at scale 1
+  // rather than dividing by zero, and so must this.
+  if (!(bx > 0 && by > 0)) return [w, h, 0];
+  const uniform = Math.min(w / bx, h / by);
+  const sx = layer.mesh?.fit === "stretch" ? w / bx : uniform;
+  const sy = layer.mesh?.fit === "stretch" ? h / by : uniform;
+  return [bx * sx, by * sy, bz * Math.min(sx, sy)];
+}
+
 /** A point in the root's DESIGN frame, out in three world space. Design +y is
  *  down and +z is away, so both flip on the way through the one mapping. */
 function worldOf(pose: { position: Vec3; rotation: Mat3 }, local: Vec3): Vec3 {

package/src/stage/jsSelfProfiler.ts

@@ -0,0 +1,325 @@
+// Chrome's JS Self-Profiling API, exposed only to the explicit local
+// `?perf=profile` diagnostics page. The browser starts sampling in the
+// Profiler constructor, so keeping construction behind both URL and caller
+// gates is what makes normal editor, hosted, and export pages pay zero cost.
+
+export const JS_SELF_PROFILE_QUERY_VALUE = "profile";
+export const JS_SELF_PROFILE_SAMPLE_INTERVAL_MS = 5;
+export const JS_SELF_PROFILE_MAX_BUFFER_SIZE = 4_096;
+export const JS_SELF_PROFILE_CAPTURE_VERSION = 1;
+
+export interface JsProfilerFrame {
+  name: string;
+  resourceId?: number;
+  line?: number;
+  column?: number;
+}
+
+export interface JsProfilerStack {
+  frameId: number;
+  parentId?: number;
+}
+
+export interface JsProfilerSample {
+  timestamp: number;
+  stackId?: number;
+}
+
+export interface JsProfilerTrace {
+  resources: readonly string[];
+  frames: readonly JsProfilerFrame[];
+  stacks: readonly JsProfilerStack[];
+  samples: readonly JsProfilerSample[];
+}
+
+interface NativeProfiler extends EventTarget {
+  readonly sampleInterval: number;
+  readonly stopped: boolean;
+  stop(): Promise<JsProfilerTrace>;
+}
+
+export interface NativeProfilerConstructor {
+  new (options: { sampleInterval: number; maxBufferSize: number }): NativeProfiler;
+}
+
+export type JsSelfProfileRefusalCode =
+  | "unsupported"
+  | "not-allowed"
+  | "already-running"
+  | "not-running"
+  | "buffer-full"
+  | "invalid-trace"
+  | "empty-trace"
+  | "stop-failed";
+
+export interface JsSelfProfileRefusal {
+  ok: false;
+  code: JsSelfProfileRefusalCode;
+  message: string;
+}
+
+export interface JsSelfProfileStarted {
+  ok: true;
+  requestedSampleIntervalMs: number;
+  actualSampleIntervalMs: number;
+  maxBufferSize: number;
+  startedAt: number;
+}
+
+export interface JsSelfProfileCapture {
+  version: typeof JS_SELF_PROFILE_CAPTURE_VERSION;
+  requestedSampleIntervalMs: number;
+  actualSampleIntervalMs: number;
+  maxBufferSize: number;
+  startedAt: number;
+  stoppedAt: number;
+  sampleCount: number;
+  /** Serialized in the profiled realm before Playwright transports it. */
+  traceJson: string;
+}
+
+export type JsSelfProfileStartResult = JsSelfProfileStarted | JsSelfProfileRefusal;
+export type JsSelfProfileStopResult =
+  | { ok: true; capture: JsSelfProfileCapture }
+  | JsSelfProfileRefusal;
+
+export interface JsSelfProfilerController {
+  status(): {
+    enabled: true;
+    supported: boolean;
+    running: boolean;
+    message: string;
+  };
+  start(): JsSelfProfileStartResult;
+  stop(): Promise<JsSelfProfileStopResult>;
+}
+
+export interface JsSelfProfilerEnvironment {
+  readonly Profiler?: NativeProfilerConstructor;
+  now(): number;
+  stringify(value: unknown): string;
+}
+
+interface ActiveProfile {
+  profiler: NativeProfiler;
+  started: JsSelfProfileStarted;
+  bufferFull: boolean;
+  stopPromise: Promise<JsSelfProfileStopResult> | null;
+}
+
+export function isLoopbackHostname(hostname: string): boolean {
+  const host = hostname.replace(/^\[/, "").replace(/\]$/, "").toLowerCase();
+  return host === "localhost" || host === "::1" || /^127(?:\.\d{1,3}){3}$/.test(host);
+}
+
+/** Both conditions are mandatory. A copied hosted URL carrying the query does
+ * not install a profiler controller, even if its server accidentally emitted
+ * a permissive policy header. */
+export function isLocalJsSelfProfileOptIn(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    const values = parsed.searchParams.getAll("perf");
+    return (
+      isLoopbackHostname(parsed.hostname) &&
+      values.length === 1 &&
+      values[0] === JS_SELF_PROFILE_QUERY_VALUE
+    );
+  } catch {
+    return false;
+  }
+}
+
+export function browserJsSelfProfilerEnvironment(): JsSelfProfilerEnvironment {
+  const Profiler = (globalThis as typeof globalThis & { Profiler?: NativeProfilerConstructor })
+    .Profiler;
+  return {
+    ...(Profiler === undefined ? {} : { Profiler }),
+    now: () => performance.now(),
+    stringify: (value) => JSON.stringify(value),
+  };
+}
+
+/**
+ * Creating the controller is inert. `start()` is the sole constructor call,
+ * and the fixed interval/cap cannot be widened by a console caller or harness
+ * argument. One controller can run several sequential captures so fresh,
+ * repeat, and post-idle comparisons can reuse one warm page.
+ */
+export function createJsSelfProfilerController(
+  env: JsSelfProfilerEnvironment = browserJsSelfProfilerEnvironment(),
+): JsSelfProfilerController {
+  let active: ActiveProfile | null = null;
+
+  const refuse = (code: JsSelfProfileRefusalCode, message: string): JsSelfProfileRefusal => ({
+    ok: false,
+    code,
+    message,
+  });
+
+  const settle = (session: ActiveProfile): Promise<JsSelfProfileStopResult> => {
+    if (session.stopPromise !== null) return session.stopPromise;
+    session.stopPromise = (async () => {
+      // This is the capture boundary. Awaiting Chrome's stop result and
+      // validating/stringifying its trace are post-capture bookkeeping and
+      // must not extend the last frame cycle in the artifact.
+      const stoppedAt = env.now();
+      let trace: JsProfilerTrace;
+      try {
+        trace = await session.profiler.stop();
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return refuse(
+          session.bufferFull ? "buffer-full" : "stop-failed",
+          session.bufferFull
+            ? `JS self-profile sample buffer filled before capture completed (${detail})`
+            : `JS self-profile could not stop: ${detail}`,
+        );
+      }
+      if (!validTraceShape(trace)) {
+        return refuse("invalid-trace", "Chrome returned a malformed JS self-profile trace");
+      }
+      if (trace.samples.length > JS_SELF_PROFILE_MAX_BUFFER_SIZE) {
+        return refuse(
+          "invalid-trace",
+          `Chrome returned ${trace.samples.length} samples, above the ${JS_SELF_PROFILE_MAX_BUFFER_SIZE}-sample cap`,
+        );
+      }
+      if (
+        session.bufferFull ||
+        trace.samples.length === JS_SELF_PROFILE_MAX_BUFFER_SIZE
+      ) {
+        return refuse(
+          "buffer-full",
+          `JS self-profile reached its ${JS_SELF_PROFILE_MAX_BUFFER_SIZE}-sample cap before the requested frame window completed`,
+        );
+      }
+      if (trace.samples.length === 0) {
+        return refuse(
+          "empty-trace",
+          "Chrome returned no JS samples; refusing to report an unsupported capture as complete",
+        );
+      }
+      let traceJson: string;
+      try {
+        traceJson = env.stringify(trace);
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return refuse("invalid-trace", `JS self-profile trace is not serializable: ${detail}`);
+      }
+      return {
+        ok: true,
+        capture: {
+          version: JS_SELF_PROFILE_CAPTURE_VERSION,
+          requestedSampleIntervalMs: session.started.requestedSampleIntervalMs,
+          actualSampleIntervalMs: session.started.actualSampleIntervalMs,
+          maxBufferSize: session.started.maxBufferSize,
+          startedAt: session.started.startedAt,
+          stoppedAt,
+          sampleCount: trace.samples.length,
+          traceJson,
+        },
+      };
+    })();
+    return session.stopPromise;
+  };
+
+  return {
+    status() {
+      const supported = env.Profiler !== undefined;
+      return {
+        enabled: true,
+        supported,
+        running: active !== null,
+        message: supported
+          ? active === null
+            ? "JS self-profiling is ready"
+            : "JS self-profiling is running"
+          : "Chrome JS Self-Profiling is unavailable; use a Chromium build that exposes window.Profiler",
+      };
+    },
+    start() {
+      if (active !== null) {
+        return refuse("already-running", "a JS self-profile capture is already running");
+      }
+      const Profiler = env.Profiler;
+      if (Profiler === undefined) {
+        return refuse(
+          "unsupported",
+          "Chrome JS Self-Profiling is unavailable; use a Chromium build that exposes window.Profiler",
+        );
+      }
+      const startedAt = env.now();
+      let profiler: NativeProfiler;
+      try {
+        profiler = new Profiler({
+          sampleInterval: JS_SELF_PROFILE_SAMPLE_INTERVAL_MS,
+          maxBufferSize: JS_SELF_PROFILE_MAX_BUFFER_SIZE,
+        });
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        const denied =
+          (typeof DOMException !== "undefined" &&
+            error instanceof DOMException &&
+            error.name === "NotAllowedError") ||
+          /document policy|not allowed/i.test(detail);
+        return refuse(
+          denied ? "not-allowed" : "unsupported",
+          denied
+            ? `JS self-profiling was denied; reload the local stage with ?perf=profile and Document-Policy: js-profiling (${detail})`
+            : `Chrome JS Self-Profiling could not start: ${detail}`,
+        );
+      }
+      const actualSampleIntervalMs = profiler.sampleInterval;
+      if (!Number.isFinite(actualSampleIntervalMs) || actualSampleIntervalMs <= 0) {
+        void profiler.stop().catch(() => {});
+        return refuse(
+          "unsupported",
+          `Chrome reported an invalid JS self-profile interval (${String(actualSampleIntervalMs)})`,
+        );
+      }
+      const started: JsSelfProfileStarted = {
+        ok: true,
+        requestedSampleIntervalMs: JS_SELF_PROFILE_SAMPLE_INTERVAL_MS,
+        actualSampleIntervalMs,
+        maxBufferSize: JS_SELF_PROFILE_MAX_BUFFER_SIZE,
+        startedAt,
+      };
+      const session: ActiveProfile = {
+        profiler,
+        started,
+        bufferFull: false,
+        stopPromise: null,
+      };
+      profiler.addEventListener(
+        "samplebufferfull",
+        () => {
+          session.bufferFull = true;
+          void settle(session);
+        },
+        { once: true },
+      );
+      active = session;
+      return started;
+    },
+    async stop() {
+      const session = active;
+      if (session === null) {
+        return refuse("not-running", "no JS self-profile capture is running");
+      }
+      const result = await settle(session);
+      if (active === session) active = null;
+      return result;
+    },
+  };
+}
+
+function validTraceShape(trace: unknown): trace is JsProfilerTrace {
+  if (trace === null || typeof trace !== "object") return false;
+  const row = trace as Partial<JsProfilerTrace>;
+  return (
+    Array.isArray(row.resources) &&
+    Array.isArray(row.frames) &&
+    Array.isArray(row.stacks) &&
+    Array.isArray(row.samples)
+  );
+}