hyperframes 0.7.74 → 0.7.76

package/dist/cli.js

@@ -50,7 +50,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.7.74" : "0.0.0-dev";
+    VERSION = true ? "0.7.76" : "0.0.0-dev";
   }
 });
 
@@ -117756,11 +117756,11 @@ async function runCaptureStage(input2) {
       captureCfg
     );
     captureBeyondViewport = session.options.captureBeyondViewport;
-    if (probeSession) {
-      prepareCaptureSessionForReuse(session, framesDir, videoInjector);
-      probeSession = null;
-    }
     try {
+      if (probeSession) {
+        prepareCaptureSessionForReuse(session, framesDir, videoInjector);
+        probeSession = null;
+      }
       if (!session.isInitialized) {
         await initializeSession(session);
       } else if (process.env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true") {
@@ -125538,6 +125538,14 @@ function isExtractionCacheCompleteSentinelPath(path2) {
   const segments = path2.split("/");
   return segments.length === 3 && segments[0] === "video-frames" && segments[1] !== "" && segments[2] === EXTRACTION_CACHE_COMPLETE_SENTINEL;
 }
+function resolveExtractedVideoOutputDir(planDir, videoId) {
+  const videoRoot = resolve36(planDir, "video-frames");
+  const outputDir = resolve36(videoRoot, videoId);
+  if (outputDir === videoRoot || !outputDir.startsWith(`${videoRoot}${sep10}`)) {
+    throw new PlanV2IntegrityError(`unsafe extracted video id: ${JSON.stringify(videoId)}`);
+  }
+  return outputDir;
+}
 function artifactTargets(path2, videoDependencies) {
   if (path2 === PLAN_AUDIO_RELATIVE_PATH) return { chunks: [], assembler: true };
   if (path2 === "plan.json" || path2 === "meta/chunks.json" || path2 === "meta/encoder.json") {
@@ -125556,7 +125564,7 @@ function artifactTargets(path2, videoDependencies) {
 }
 function listVideoFramePaths(planV1Dir, videos) {
   return videos.extracted.map((video) => {
-    const outputDir = join68(planV1Dir, "video-frames", video.videoId);
+    const outputDir = resolveExtractedVideoOutputDir(planV1Dir, video.videoId);
     const frameNames = readdirSync19(outputDir).sort();
     const framePaths = /* @__PURE__ */ new Map();
     for (const frameName of frameNames) {
@@ -125670,6 +125678,14 @@ function parsePlanVideosJson(value) {
   });
   return { videos, extracted };
 }
+function materializeExtractedVideoDirectories(planDir) {
+  const videosPath = join68(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
+  if (!existsSync59(videosPath)) return;
+  const videos = parsePlanVideosJson(readJsonFile(videosPath, PLAN_VIDEOS_META_RELATIVE_PATH));
+  for (const video of videos.extracted) {
+    mkdirSync31(resolveExtractedVideoOutputDir(planDir, video.videoId), { recursive: true });
+  }
+}
 function parseChunkSlices(value) {
   if (!Array.isArray(value)) {
     throw new PlanV2IntegrityError("meta/chunks.json must be an array");
@@ -126077,6 +126093,7 @@ function materializePlanV2Target(planV2Dir, target, destinationDir) {
       mkdirSync31(dirname30(destinationPath), { recursive: true });
       copyFileSync8(sourcePath, destinationPath);
     }
+    if (target.role === "chunk") materializeExtractedVideoDirectories(tempDir);
     writeFileSync23(
       join68(tempDir, PLAN_V2_MATERIALIZATION_MARKER),
       canonicalJsonStringify({ manifest, target }),
@@ -126411,6 +126428,51 @@ var init_assemble = __esm({
 import { randomBytes as randomBytes2 } from "crypto";
 import { existsSync as existsSync61, mkdirSync as mkdirSync34, readFileSync as readFileSync36, readdirSync as readdirSync21, rmSync as rmSync23, writeFileSync as writeFileSync25 } from "fs";
 import { extname as extname15, join as join70 } from "path";
+async function createVerifiedDistributedCaptureSession(serverUrl, framesDir, captureOptions, cfg, dependencies = distributedCaptureSessionDependencies) {
+  const session = await dependencies.createCaptureSession(
+    serverUrl,
+    framesDir,
+    captureOptions,
+    null,
+    cfg
+  );
+  try {
+    await dependencies.assertSwiftShader(session.page, dependencies.readWebGlVendorInfo);
+    await dependencies.initializeSession(session);
+    return session;
+  } catch (error) {
+    await dependencies.closeCaptureSession(session).catch(() => {
+    });
+    throw error;
+  }
+}
+function createChunkVideoFrameInjectorFactory(frameLookup) {
+  return () => createVideoFrameInjector(frameLookup);
+}
+function isCaptureMode(value) {
+  return value === "beginframe" || value === "screenshot" || value === "drawelement";
+}
+function shouldRetryChunkCaptureWithScreenshot(error) {
+  const failure = classifyCaptureFailure(error);
+  if (failure.kind === "cancelled" || failure.kind === "memory_exhaustion") return false;
+  return /HeadlessExperimental\.beginFrame/i.test(failure.message) || /beginFrame probe timeout/i.test(failure.message) || /Another frame is pending|Frame still pending/i.test(failure.message);
+}
+async function runCaptureWithScreenshotFallback(input2) {
+  try {
+    return await input2.run(input2.forceScreenshot);
+  } catch (error) {
+    if (input2.forceScreenshot || !shouldRetryChunkCaptureWithScreenshot(error)) throw error;
+    input2.onFallback?.(error);
+    await input2.resetForScreenshotRetry();
+    return await input2.run(true);
+  }
+}
+async function beginFrameSessionNeedsScreenshotFallback(session, probe = probeBeginFrameLiveness) {
+  if (session.launchCaptureMode !== "beginframe") return false;
+  const timeoutMs = Number(process.env.PRODUCER_BEGINFRAME_PROBE_TIMEOUT_MS) > 0 ? Number(process.env.PRODUCER_BEGINFRAME_PROBE_TIMEOUT_MS) : 3e4;
+  const probeTick = Math.max(0, session.beginFrameTimeTicks - 5 * session.beginFrameIntervalMs);
+  return !await probe(session.page, timeoutMs, probeTick, session.beginFrameIntervalMs);
+}
 function rebuildExtractedFramesFromPlanDir(planDir, videos, indexMode = "dense-v1") {
   const result = [];
   for (const v2 of videos) {
@@ -126581,16 +126643,15 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       // the software-GPU clamp so buildChromeArgs includes BeginFrameControl.
       forceScreenshotExplicitlyOptedOut: !encoder.forceScreenshot
     };
-    const videoInjector = planVideos && planVideos.extracted.length > 0 ? createVideoFrameInjector(
-      createFrameLookupTable(
-        planVideos.videos,
-        rebuildExtractedFramesFromPlanDir(
-          planDir,
-          planVideos.extracted,
-          v2Manifest === null ? "dense-v1" : "sparse-v2"
-        )
+    const videoFrameLookup = planVideos && planVideos.extracted.length > 0 ? createFrameLookupTable(
+      planVideos.videos,
+      rebuildExtractedFramesFromPlanDir(
+        planDir,
+        planVideos.extracted,
+        v2Manifest === null ? "dense-v1" : "sparse-v2"
       )
     ) : null;
+    const createChunkVideoFrameInjector = createChunkVideoFrameInjectorFactory(videoFrameLookup);
     const videoCaptureBeyondViewport = resolveVideoCaptureBeyondViewport(
       planVideos?.videos.length ?? 0
     );
@@ -126634,61 +126695,142 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
     let encodeStageMs = 0;
     let captureMode;
     const capturePerfs = [];
+    const captureAttempts = [];
+    let forceScreenshotForChunk = encoder.forceScreenshot;
     try {
-      if (chunkWorkerCount === 1) {
+      if (chunkWorkerCount === 1 || !forceScreenshotForChunk) {
         const bootStarted = Date.now();
-        session = await createCaptureSession(fileServer.url, framesDir, captureOptions, null, cfg);
-        await assertSwiftShader(session.page, readWebGlVendorInfoFromCanvas);
-        await initializeSession(session);
+        session = await createVerifiedDistributedCaptureSession(
+          fileServer.url,
+          framesDir,
+          captureOptions,
+          cfg
+        );
         sessionBootMs = Date.now() - bootStarted;
+        const browserSelectedScreenshot = session.launchCaptureMode === "screenshot";
+        const beginFrameStalled = !browserSelectedScreenshot && await beginFrameSessionNeedsScreenshotFallback(session);
+        if (browserSelectedScreenshot) {
+          forceScreenshotForChunk = true;
+          log2.warn(
+            "[renderChunk] Browser capability probe selected screenshot capture for the entire chunk",
+            { chunkIndex }
+          );
+          if (chunkWorkerCount > 1) {
+            await closeCaptureSession(session);
+            session = null;
+          }
+        } else if (beginFrameStalled) {
+          forceScreenshotForChunk = true;
+          log2.warn(
+            "[renderChunk] BeginFrame liveness probe failed; using screenshot capture for the entire chunk",
+            { chunkIndex }
+          );
+          await closeCaptureSession(session).catch(() => {
+          });
+          session = null;
+          if (chunkWorkerCount === 1) {
+            const screenshotBootStarted = Date.now();
+            const screenshotCfg = {
+              ...cfg,
+              forceScreenshot: true,
+              forceScreenshotExplicitlyOptedOut: false
+            };
+            session = await createVerifiedDistributedCaptureSession(
+              fileServer.url,
+              framesDir,
+              captureOptions,
+              screenshotCfg
+            );
+            sessionBootMs += Date.now() - screenshotBootStarted;
+          }
+        } else if (chunkWorkerCount > 1) {
+          await closeCaptureSession(session);
+          session = null;
+        }
       }
       const captureStarted = Date.now();
-      const capturePlan = createCapturePlan({
-        workerCount: chunkWorkerCount,
-        forceScreenshot: encoder.forceScreenshot,
-        useStreamingEncode: false,
-        useLayeredComposite: false,
-        usePageSideCompositing: false,
-        hasHdrContent: false,
-        needsAlpha: plan2.dimensions.format !== "mp4"
-      });
-      if (capturePlan.kind !== "sdr_disk") {
-        throw new Error(`Distributed chunk requires sdr_disk plan; got ${capturePlan.kind}`);
-      }
-      await runCaptureStage({
-        fileServer,
-        workDir,
-        framesDir,
-        job,
-        totalFrames: framesInChunk,
-        cfg,
-        plan: capturePlan,
-        log: log2,
-        probeSession: session,
-        captureAttempts: [],
-        // This sink also records each worker's effective capture mode. That
-        // makes a BeginFrame → screenshot fallback observable to adapters and
-        // end-to-end smoke tests instead of existing only in stderr.
-        dedupPerfs: capturePerfs,
-        buildCaptureOptions: () => captureOptions,
-        createRenderVideoFrameInjector: () => videoInjector,
-        abortSignal: void 0,
-        assertNotAborted: () => {
+      captureMode = await runCaptureWithScreenshotFallback({
+        forceScreenshot: forceScreenshotForChunk,
+        // fallow-ignore-next-line complexity
+        run: async (forceScreenshot) => {
+          const captureCfg = cfg.forceScreenshot === forceScreenshot ? cfg : {
+            ...cfg,
+            forceScreenshot,
+            forceScreenshotExplicitlyOptedOut: !forceScreenshot
+          };
+          if (chunkWorkerCount === 1 && session === null) {
+            session = await createVerifiedDistributedCaptureSession(
+              fileServer.url,
+              framesDir,
+              captureOptions,
+              captureCfg
+            );
+          }
+          const capturePlan = createCapturePlan({
+            workerCount: chunkWorkerCount,
+            forceScreenshot,
+            useStreamingEncode: false,
+            useLayeredComposite: false,
+            usePageSideCompositing: false,
+            hasHdrContent: false,
+            needsAlpha: plan2.dimensions.format !== "mp4"
+          });
+          if (capturePlan.kind !== "sdr_disk") {
+            throw new Error(`Distributed chunk requires sdr_disk plan; got ${capturePlan.kind}`);
+          }
+          const captureSession = session;
+          session = null;
+          await runCaptureStage({
+            fileServer,
+            workDir,
+            framesDir,
+            job,
+            totalFrames: framesInChunk,
+            cfg: captureCfg,
+            plan: capturePlan,
+            log: log2,
+            probeSession: captureSession,
+            captureAttempts,
+            // This sink records each worker's effective capture mode so a
+            // fallback remains observable to adapters and smoke tests.
+            dedupPerfs: capturePerfs,
+            buildCaptureOptions: () => captureOptions,
+            createRenderVideoFrameInjector: createChunkVideoFrameInjector,
+            abortSignal: void 0,
+            assertNotAborted: () => {
+            },
+            frameRange: { startFrame: slice.startFrame, endFrame: slice.endFrame }
+          });
+          const observedModes = new Set(capturePerfs.map((perf) => perf.captureMode));
+          if (observedModes.size !== 1 || ![...observedModes].every(isCaptureMode)) {
+            throw new Error(
+              `[renderChunk] capture workers reported invalid or inconsistent modes: ${[...observedModes].join(",") || "<none>"}`
+            );
+          }
+          const [observedMode] = observedModes;
+          if (!observedMode || !isCaptureMode(observedMode)) {
+            throw new Error("[renderChunk] capture completed without an observed mode");
+          }
+          return observedMode;
+        },
+        resetForScreenshotRetry: () => {
+          rmSync23(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+          mkdirSync34(framesDir, { recursive: true });
+          capturePerfs.length = 0;
+          captureAttempts.length = 0;
+          job.framesRendered = 0;
         },
-        frameRange: { startFrame: slice.startFrame, endFrame: slice.endFrame }
+        onFallback: (error) => {
+          log2.warn(
+            "[renderChunk] BeginFrame capture failed; retrying the entire chunk once in screenshot mode",
+            {
+              chunkIndex,
+              error: error instanceof Error ? error.message : String(error)
+            }
+          );
+        }
       });
       captureStageMs = Date.now() - captureStarted;
-      session = null;
-      const observedModes = new Set(capturePerfs.map((perf) => perf.captureMode));
-      const validModes = /* @__PURE__ */ new Set(["beginframe", "screenshot", "drawelement"]);
-      if (observedModes.size !== 1 || ![...observedModes].every(
-        (mode) => validModes.has(mode)
-      )) {
-        throw new Error(
-          `[renderChunk] capture workers reported invalid or inconsistent modes: ${[...observedModes].join(",") || "<none>"}`
-        );
-      }
-      captureMode = [...observedModes][0];
       framesEncoded = framesInChunk;
       const isPngSequence = plan2.dimensions.format === "png-sequence";
       outputKind = isPngSequence ? "frame-dir" : "file";
@@ -126808,7 +126950,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
     envRestore.restore();
   }
 }
-var FFMPEG_VERSION_MISMATCH, PLAN_HASH_MISMATCH, MISSING_PLAN_ARTIFACT, CHUNK_INDEX_OUT_OF_RANGE, MISSING_RUNTIME_ENV_SNAPSHOT, LEGACY_DISTRIBUTED_VP9_CPU_USED, RenderChunkValidationError;
+var FFMPEG_VERSION_MISMATCH, PLAN_HASH_MISMATCH, MISSING_PLAN_ARTIFACT, CHUNK_INDEX_OUT_OF_RANGE, MISSING_RUNTIME_ENV_SNAPSHOT, LEGACY_DISTRIBUTED_VP9_CPU_USED, RenderChunkValidationError, distributedCaptureSessionDependencies;
 var init_renderChunk = __esm({
   "../producer/src/services/distributed/renderChunk.ts"() {
     "use strict";
@@ -126841,6 +126983,13 @@ var init_renderChunk = __esm({
         this.code = code;
       }
     };
+    distributedCaptureSessionDependencies = {
+      createCaptureSession,
+      assertSwiftShader,
+      initializeSession,
+      closeCaptureSession,
+      readWebGlVendorInfo: readWebGlVendorInfoFromCanvas
+    };
   }
 });
 
@@ -139638,13 +139787,63 @@ function hasEnoughRotationSamples(group) {
 function isActuallySpinning(group) {
   return maxAngleSpread(group.map((s2) => s2.angle)) > ROTATION_MIN_ANGLE_SPREAD_DEG;
 }
+function aabbForRotatedRect(elemW, elemH, angleDeg) {
+  const rad = angleDeg * Math.PI / 180;
+  const cosAbs = Math.abs(Math.cos(rad));
+  const sinAbs = Math.abs(Math.sin(rad));
+  return { w: elemW * cosAbs + elemH * sinAbs, h: elemW * sinAbs + elemH * cosAbs };
+}
+function unrotatedSizeFromSample(sample) {
+  const rad = sample.angle * Math.PI / 180;
+  const cosAbs = Math.abs(Math.cos(rad));
+  const sinAbs = Math.abs(Math.sin(rad));
+  const det = cosAbs * cosAbs - sinAbs * sinAbs;
+  if (Math.abs(det) < ROTATION_RIGID_ESTIMATE_MIN_DET) return null;
+  const elemW = (cosAbs * sample.w - sinAbs * sample.h) / det;
+  const elemH = (cosAbs * sample.h - sinAbs * sample.w) / det;
+  if (!(elemW > 0) || !(elemH > 0)) return null;
+  return { w: elemW, h: elemH };
+}
+function aabbMatchesSample(expected, sample) {
+  if (expected.w <= 0 || expected.h <= 0 || sample.w <= 0 || sample.h <= 0) return false;
+  return Math.max(expected.w, sample.w) / Math.min(expected.w, sample.w) <= ROTATION_RIGID_AABB_RATIO && Math.max(expected.h, sample.h) / Math.min(expected.h, sample.h) <= ROTATION_RIGID_AABB_RATIO;
+}
+function isSingularRotationAngle(angleDeg) {
+  const rad = angleDeg * Math.PI / 180;
+  const cosAbs = Math.abs(Math.cos(rad));
+  const sinAbs = Math.abs(Math.sin(rad));
+  return Math.abs(cosAbs * cosAbs - sinAbs * sinAbs) < ROTATION_RIGID_ESTIMATE_MIN_DET;
+}
+function isNearSquareAabb(sample) {
+  if (sample.w <= 0 || sample.h <= 0) return false;
+  return Math.max(sample.w, sample.h) / Math.min(sample.w, sample.h) <= ROTATION_RIGID_AABB_RATIO;
+}
+function fitsSingularPhaseRigidProjection(group) {
+  if (group.length === 0 || !group.every((s2) => isSingularRotationAngle(s2.angle))) return false;
+  if (!group.every(isNearSquareAabb)) return false;
+  const ref2 = group[0];
+  if (!ref2) return false;
+  return group.every((sample) => aabbMatchesSample({ w: ref2.w, h: ref2.h }, sample));
+}
+function fitsOneRigidRectangle(group) {
+  for (const ref2 of group) {
+    const size = unrotatedSizeFromSample(ref2);
+    if (!size) continue;
+    if (group.every(
+      (sample) => aabbMatchesSample(aabbForRotatedRect(size.w, size.h, sample.angle), sample)
+    )) {
+      return true;
+    }
+  }
+  return fitsSingularPhaseRigidProjection(group);
+}
 function isRotationSizeStable(group) {
-  const widths = group.map((s2) => s2.w);
-  const heights = group.map((s2) => s2.h);
-  const minWidth = Math.min(...widths);
-  const minHeight = Math.min(...heights);
-  if (minWidth <= 0 || minHeight <= 0) return false;
-  return Math.max(...widths) / minWidth <= ROTATION_MAX_SIZE_RATIO && Math.max(...heights) / minHeight <= ROTATION_MAX_SIZE_RATIO;
+  if (group.some((s2) => s2.w <= 0 || s2.h <= 0)) return false;
+  const longSides = group.map((s2) => Math.max(s2.w, s2.h));
+  const minLong = Math.min(...longSides);
+  if (minLong <= 0) return false;
+  if (Math.max(...longSides) / minLong > ROTATION_MAX_SIZE_RATIO) return false;
+  return fitsOneRigidRectangle(group);
 }
 function isSizableRotation(group) {
   return median(group.map((s2) => s2.w * s2.h)) >= ROTATION_MIN_MEDIAN_AREA_PX;
@@ -140205,7 +140404,7 @@ async function captureFindingCrops2(project, options, requests) {
   const module = await Promise.resolve().then(() => (init_checkBrowser(), checkBrowser_exports));
   return module.captureFindingCrops(project, options, requests);
 }
-var MOTION_FPS2, MOTION_MAX_SAMPLES2, ZERO_BBOX, FRAME_BREACH_FLOOR_PX, FRAME_BREACH_FLOOR_FRACTION, DEFAULT_CHECK_OPTIONS, OVERLAP_SAMPLE_FPS, OVERLAP_MAX_SAMPLES, SWEEP_STATIC_MIN_DURATION_SEC, ZERO_LAYOUT_RECT, ROTATION_MIN_SAMPLES, ROTATION_MIN_ANGLE_SPREAD_DEG, ROTATION_MAX_SIZE_RATIO, ROTATION_MIN_MEDIAN_AREA_PX, ROTATION_DRIFT_SIZE_FRACTION, ROTATION_DRIFT_VIEWPORT_FRACTION, INDICATOR_MIN_SAMPLES, INDICATOR_MIN_ANGLE_SPREAD_DEG, INDICATOR_MIN_HUB_CIRCLES, INDICATOR_MAX_FIT_RESIDUAL_FRACTION, INDICATOR_MAX_RIGID_LEN_VARIATION, INDICATOR_DRIFT_LENGTH_FRACTION, INDICATOR_MIN_HUB_PRESENCE_FRACTION, MAX_FINDING_CROPS, DEFAULT_DEPENDENCIES;
+var MOTION_FPS2, MOTION_MAX_SAMPLES2, ZERO_BBOX, FRAME_BREACH_FLOOR_PX, FRAME_BREACH_FLOOR_FRACTION, DEFAULT_CHECK_OPTIONS, OVERLAP_SAMPLE_FPS, OVERLAP_MAX_SAMPLES, SWEEP_STATIC_MIN_DURATION_SEC, ZERO_LAYOUT_RECT, ROTATION_MIN_SAMPLES, ROTATION_MIN_ANGLE_SPREAD_DEG, ROTATION_MAX_SIZE_RATIO, ROTATION_RIGID_AABB_RATIO, ROTATION_RIGID_ESTIMATE_MIN_DET, ROTATION_MIN_MEDIAN_AREA_PX, ROTATION_DRIFT_SIZE_FRACTION, ROTATION_DRIFT_VIEWPORT_FRACTION, INDICATOR_MIN_SAMPLES, INDICATOR_MIN_ANGLE_SPREAD_DEG, INDICATOR_MIN_HUB_CIRCLES, INDICATOR_MAX_FIT_RESIDUAL_FRACTION, INDICATOR_MAX_RIGID_LEN_VARIATION, INDICATOR_DRIFT_LENGTH_FRACTION, INDICATOR_MIN_HUB_PRESENCE_FRACTION, MAX_FINDING_CROPS, DEFAULT_DEPENDENCIES;
 var init_checkPipeline = __esm({
   "src/utils/checkPipeline.ts"() {
     "use strict";
@@ -140248,6 +140447,8 @@ var init_checkPipeline = __esm({
     ROTATION_MIN_SAMPLES = 3;
     ROTATION_MIN_ANGLE_SPREAD_DEG = 20;
     ROTATION_MAX_SIZE_RATIO = 1.6;
+    ROTATION_RIGID_AABB_RATIO = 1.15;
+    ROTATION_RIGID_ESTIMATE_MIN_DET = 0.15;
     ROTATION_MIN_MEDIAN_AREA_PX = 2500;
     ROTATION_DRIFT_SIZE_FRACTION = 0.1;
     ROTATION_DRIFT_VIEWPORT_FRACTION = 0.02;

package/dist/commands/layout-audit.browser.js

@@ -1198,6 +1198,7 @@
     return issues;
   }
 
+  // Soft prior only — the counterfactual attach test (below) is what makes detachment a finding.
   const CONNECTOR_NAME = /\b(conn(ector)?|arrow|edge|link|flow|wire)\b/i;
   const CONNECTOR_SKIP_CONTAINERS = "defs, marker, clipPath, mask, symbol, pattern";
 
@@ -1207,14 +1208,16 @@
     return `${element.id || ""} ${className}`;
   }
 
-  // Screen-space endpoints via the browser: getScreenCTM covers viewBox, preserveAspectRatio and group transforms.
-  function pathScreenEndpoints(svg, path) {
-    if (
-      typeof path.getTotalLength !== "function" ||
-      typeof path.getPointAtLength !== "function" ||
-      typeof path.getScreenCTM !== "function" ||
-      typeof svg.createSVGPoint !== "function"
-    ) {
+  function isConnectorPath(svg, path) {
+    if (path.hasAttribute("marker-start") || path.hasAttribute("marker-end")) return true;
+    return (
+      CONNECTOR_NAME.test(connectorNameFor(svg)) || CONNECTOR_NAME.test(connectorNameFor(path))
+    );
+  }
+
+  /** Raw `d`-space endpoints (no CTM) — the mapping authors use when they paste screen coords into `d`. */
+  function pathUserEndpoints(path) {
+    if (typeof path.getTotalLength !== "function" || typeof path.getPointAtLength !== "function") {
       return null;
     }
     let total;
@@ -1224,6 +1227,20 @@
       return null;
     }
     if (!Number.isFinite(total) || total <= 0) return null;
+    const start = path.getPointAtLength(0);
+    const end = path.getPointAtLength(total);
+    return { start: { x: start.x, y: start.y }, end: { x: end.x, y: end.y } };
+  }
+
+  // Screen endpoints via getScreenCTM (viewBox, preserveAspectRatio, group transforms).
+  function pathScreenEndpoints(svg, path, user) {
+    if (
+      !user ||
+      typeof path.getScreenCTM !== "function" ||
+      typeof svg.createSVGPoint !== "function"
+    ) {
+      return null;
+    }
     const matrix = path.getScreenCTM();
     if (!matrix) return null;
     const toScreen = (local) => {
@@ -1233,10 +1250,7 @@
       const mapped = point.matrixTransform(matrix);
       return { x: mapped.x, y: mapped.y };
     };
-    return {
-      start: toScreen(path.getPointAtLength(0)),
-      end: toScreen(path.getPointAtLength(total)),
-    };
+    return { start: toScreen(user.start), end: toScreen(user.end) };
   }
 
   function distanceToRect(point, rect) {
@@ -1246,6 +1260,7 @@
   }
 
   // Solid, compact elements a connector could plausibly anchor to.
+  // Both tiers keep `element` so attachment identity is stable across containment vs near-miss.
   function connectorAnchorRects(root, rootRect) {
     const compact = [];
     const painted = [];
@@ -1261,42 +1276,57 @@
       if (area < 400) continue;
       // Containment tier: large opaque targets only — a text-bearing wrapper contains its own diagram's endpoints.
       if (opaque && area <= rootArea * 0.6) painted.push({ rect, element });
-      if (area <= rootArea * 0.15) compact.push(rect);
+      if (area <= rootArea * 0.15) compact.push({ rect, element });
     }
     return { compact, painted };
   }
 
-  function isConnectorPath(svg, path) {
-    if (path.hasAttribute("marker-start") || path.hasAttribute("marker-end")) return true;
-    return (
-      CONNECTOR_NAME.test(connectorNameFor(svg)) || CONNECTOR_NAME.test(connectorNameFor(path))
-    );
-  }
-
-  // A connector whose BOTH endpoints land far from every anchorable element was drawn in the wrong frame.
-  // min over the two endpoints is intentional: a half-attached connector is a design choice, not frame drift.
+  // Flag only the documented bug: rendered endpoints miss, but user-space-as-screen would attach.
   function connectorDetachmentIssues(root, rootRect, time) {
     const issues = [];
     let anchors = null;
+    // Attach near-miss tolerance (screen px). Separate from the closed-glyph chord floor.
     const threshold = Math.max(32, Math.min(rootRect.width, rootRect.height) * 0.02);
+    const MIN_CONNECTOR_CHORD_PX = 8;
     for (const svg of Array.from(root.querySelectorAll("svg"))) {
       if (!isVisibleElement(svg) || hasAllowOverflowFlag(svg)) continue;
       for (const path of Array.from(svg.querySelectorAll("path"))) {
         if (path.closest(CONNECTOR_SKIP_CONTAINERS)) continue;
         if (!isConnectorPath(svg, path)) continue;
-        const endpoints = pathScreenEndpoints(svg, path);
-        if (!endpoints) continue;
+        const user = pathUserEndpoints(path);
+        const rendered = pathScreenEndpoints(svg, path, user);
+        if (!user || !rendered) continue;
+        // Closed/glyph paths collapse to one point — compare in screen px (not user units).
+        const renderedChord = Math.hypot(
+          rendered.end.x - rendered.start.x,
+          rendered.end.y - rendered.start.y,
+        );
+        if (renderedChord < MIN_CONNECTOR_CHORD_PX) continue;
         if (anchors === null) anchors = connectorAnchorRects(root, rootRect);
         if (anchors.compact.length < 2) return issues;
-        const attached = (point) =>
-          anchors.painted.some(
-            (anchor) => !anchor.element.contains(svg) && distanceToRect(point, anchor.rect) === 0,
-          ) || anchors.compact.some((rect) => distanceToRect(point, rect) <= threshold);
-        if (attached(endpoints.start) || attached(endpoints.end)) continue;
+        // Stable DOM identity across painted (inside) and compact (near-miss) tiers.
+        const attachmentKey = (point) => {
+          for (const anchor of anchors.painted) {
+            if (!anchor.element.contains(svg) && distanceToRect(point, anchor.rect) === 0) {
+              return anchor.element;
+            }
+          }
+          for (const anchor of anchors.compact) {
+            if (distanceToRect(point, anchor.rect) <= threshold) return anchor.element;
+          }
+          return null;
+        };
+        const attached = (point) => attachmentKey(point) !== null;
+        // Half-attached as drawn is allowed; only full render-miss proceeds.
+        if (attached(rendered.start) || attached(rendered.end)) continue;
+        // Paste-into-`d` bug: both raw endpoints land on distinct anchors as screen pixels.
+        const userStartKey = attachmentKey(user.start);
+        const userEndKey = attachmentKey(user.end);
+        if (!userStartKey || !userEndKey || userStartKey === userEndKey) continue;
         const gap = Math.round(
           Math.min(
-            Math.min(...anchors.compact.map((rect) => distanceToRect(endpoints.start, rect))),
-            Math.min(...anchors.compact.map((rect) => distanceToRect(endpoints.end, rect))),
+            Math.min(...anchors.compact.map((a) => distanceToRect(rendered.start, a.rect))),
+            Math.min(...anchors.compact.map((a) => distanceToRect(rendered.end, a.rect))),
           ),
         );
         issues.push({
@@ -1305,17 +1335,17 @@
           time,
           selector: selectorFor(path),
           containerSelector: selectorFor(svg),
-          message: `Connector path endpoints are ${gap}px from the nearest anchorable element — measured coordinates were likely drawn into an SVG with a different origin.`,
+          message: `Connector path endpoints render ${gap}px from the nearest anchorable element, but the path's user-space coordinates would attach if read as screen pixels — screen/viewport numbers were likely written into SVG \`d\` without inverting the CTM.`,
           rect: toRect({
-            left: Math.min(endpoints.start.x, endpoints.end.x),
-            top: Math.min(endpoints.start.y, endpoints.end.y),
-            right: Math.max(endpoints.start.x, endpoints.end.x),
-            bottom: Math.max(endpoints.start.y, endpoints.end.y),
-            width: Math.abs(endpoints.end.x - endpoints.start.x),
-            height: Math.abs(endpoints.end.y - endpoints.start.y),
+            left: Math.min(rendered.start.x, rendered.end.x),
+            top: Math.min(rendered.start.y, rendered.end.y),
+            right: Math.max(rendered.start.x, rendered.end.x),
+            bottom: Math.max(rendered.start.y, rendered.end.y),
+            width: Math.abs(rendered.end.x - rendered.start.x),
+            height: Math.abs(rendered.end.y - rendered.start.y),
           }),
           fixHint:
-            "Subtract the SVG's own rect when converting measured coordinates, and keep the SVG a direct child of the stage.",
+            "Convert measured screen coordinates into the SVG's user space (subtract the SVG rect / invert getScreenCTM) before writing path `d`, and keep the SVG a direct child of the stage.",
         });
       }
     }

package/dist/hyperframes-player.global.js

@@ -1,4 +1,4 @@
-"use strict";var HyperframesPlayer=(()=>{var J=Object.defineProperty;var Ge=Object.getOwnPropertyDescriptor;var qe=Object.getOwnPropertyNames;var Ye=Object.prototype.hasOwnProperty;var Xe=(i,e)=>{for(var t in e)J(i,t,{get:e[t],enumerable:!0})},Ze=(i,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of qe(e))!Ye.call(i,n)&&n!==t&&J(i,n,{get:()=>e[n],enumerable:!(r=Ge(e,n))||r.enumerable});return i};var Qe=i=>Ze(J({},"__esModule",{value:!0}),i);var Lt={};Xe(Lt,{HyperframesPlayer:()=>Q,SPEED_PRESETS:()=>te,formatSpeed:()=>N,formatTime:()=>$});function ye(i){return i.hasRuntime||i.runtimeInjected?!1:!!(i.hasNestedCompositions||i.hasTimelines&&i.attempts>=5)}function I(i){return typeof i=="object"&&i!==null}function Ee(i){return I(i)&&typeof i.getDuration=="function"}function Se(i){return I(i)&&typeof i.duration=="function"&&typeof i.time=="function"&&typeof i.seek=="function"&&typeof i.play=="function"&&typeof i.pause=="function"}var Je="https://cdn.jsdelivr.net/npm/@hyperframes/core@0.7.74/dist/hyperframe.runtime.iife.js";function D(i){if(i===null)return null;let e=Number.parseInt(i,10);return Number.isFinite(e)&&e>0?e:null}function Ke(i){let e=i?.querySelector("[data-composition-id][data-width][data-height]")??i?.querySelector("[data-width][data-height]");if(!e)return null;let t=D(e.getAttribute("data-width")),r=D(e.getAttribute("data-height"));return t!==null&&r!==null?{width:t,height:r}:null}var j=class{constructor(e,t){this._iframe=e;this._callbacks=t}_iframe;_callbacks;_interval=null;_runtimeInjected=!1;get runtimeInjected(){return this._runtimeInjected}start(){this.stop(),this._runtimeInjected=!1;let e=0;this._interval=setInterval(()=>{e++;try{let t=this._iframe.contentWindow;if(!t)return;let r=!!(t.__hf||t.__player),n=!!(t.__timelines&&Object.keys(t.__timelines).length>0),o=!!this._iframe.contentDocument?.querySelector("[data-composition-src]");if(ye({hasRuntime:r,hasTimelines:n,hasNestedCompositions:o,runtimeInjected:this._runtimeInjected,attempts:e})){this._injectRuntime();return}if(this._runtimeInjected&&!r)return;let s=this._resolvePlaybackDurationAdapter(t);if(s&&s.getDuration()>0){this.stop();let l=Ke(this._iframe.contentDocument);this._callbacks.onReady({duration:s.getDuration(),adapter:s,compositionSize:l});return}}catch{}e>=40&&(this.stop(),this._callbacks.onError("Composition timeline not found after 8s"))},200)}stop(){this._interval!==null&&(clearInterval(this._interval),this._interval=null)}resolveDirectTimelineAdapter(){try{let e=this._iframe.contentWindow;return e?this._resolveDirectTimelineAdapterFromWindow(e):null}catch{return null}}resolveDirectTimelineAdapterFromWindow(e){return this._resolveDirectTimelineAdapterFromWindow(e)}hasRuntimeBridge(e){return Reflect.get(e,"__hf")!==void 0||I(Reflect.get(e,"__player"))}_injectRuntime(){this._runtimeInjected=!0;try{let e=this._iframe.contentDocument;if(!e)return;let t=e.createElement("script");t.src=Je,(e.head||e.documentElement).appendChild(t),this._callbacks.onRuntimeInjected?.()}catch{}}_resolveDirectTimelineAdapterFromWindow(e){if(this.hasRuntimeBridge(e))return null;let t=Reflect.get(e,"__timelines");if(!I(t))return null;let r=Object.keys(t);if(r.length===0)return null;let n=this._iframe.contentDocument?.querySelector("[data-composition-id]")?.getAttribute("data-composition-id"),o=n&&n in t?n:r[r.length-1],s=t[o];return Se(s)?s:null}_resolvePlaybackDurationAdapter(e){let t=Reflect.get(e,"__player");if(Ee(t))return{kind:"runtime",getDuration:()=>t.getDuration()};let r=this._resolveDirectTimelineAdapterFromWindow(e);return r?{kind:"direct-timeline",timeline:r,getDuration:()=>r.duration()}:null}};var Te=`
+"use strict";var HyperframesPlayer=(()=>{var J=Object.defineProperty;var Ge=Object.getOwnPropertyDescriptor;var qe=Object.getOwnPropertyNames;var Ye=Object.prototype.hasOwnProperty;var Xe=(i,e)=>{for(var t in e)J(i,t,{get:e[t],enumerable:!0})},Ze=(i,e,t,r)=>{if(e&&typeof e=="object"||typeof e=="function")for(let n of qe(e))!Ye.call(i,n)&&n!==t&&J(i,n,{get:()=>e[n],enumerable:!(r=Ge(e,n))||r.enumerable});return i};var Qe=i=>Ze(J({},"__esModule",{value:!0}),i);var Lt={};Xe(Lt,{HyperframesPlayer:()=>Q,SPEED_PRESETS:()=>te,formatSpeed:()=>N,formatTime:()=>$});function ye(i){return i.hasRuntime||i.runtimeInjected?!1:!!(i.hasNestedCompositions||i.hasTimelines&&i.attempts>=5)}function I(i){return typeof i=="object"&&i!==null}function Ee(i){return I(i)&&typeof i.getDuration=="function"}function Se(i){return I(i)&&typeof i.duration=="function"&&typeof i.time=="function"&&typeof i.seek=="function"&&typeof i.play=="function"&&typeof i.pause=="function"}var Je="https://cdn.jsdelivr.net/npm/@hyperframes/core@0.7.76/dist/hyperframe.runtime.iife.js";function D(i){if(i===null)return null;let e=Number.parseInt(i,10);return Number.isFinite(e)&&e>0?e:null}function Ke(i){let e=i?.querySelector("[data-composition-id][data-width][data-height]")??i?.querySelector("[data-width][data-height]");if(!e)return null;let t=D(e.getAttribute("data-width")),r=D(e.getAttribute("data-height"));return t!==null&&r!==null?{width:t,height:r}:null}var j=class{constructor(e,t){this._iframe=e;this._callbacks=t}_iframe;_callbacks;_interval=null;_runtimeInjected=!1;get runtimeInjected(){return this._runtimeInjected}start(){this.stop(),this._runtimeInjected=!1;let e=0;this._interval=setInterval(()=>{e++;try{let t=this._iframe.contentWindow;if(!t)return;let r=!!(t.__hf||t.__player),n=!!(t.__timelines&&Object.keys(t.__timelines).length>0),o=!!this._iframe.contentDocument?.querySelector("[data-composition-src]");if(ye({hasRuntime:r,hasTimelines:n,hasNestedCompositions:o,runtimeInjected:this._runtimeInjected,attempts:e})){this._injectRuntime();return}if(this._runtimeInjected&&!r)return;let s=this._resolvePlaybackDurationAdapter(t);if(s&&s.getDuration()>0){this.stop();let l=Ke(this._iframe.contentDocument);this._callbacks.onReady({duration:s.getDuration(),adapter:s,compositionSize:l});return}}catch{}e>=40&&(this.stop(),this._callbacks.onError("Composition timeline not found after 8s"))},200)}stop(){this._interval!==null&&(clearInterval(this._interval),this._interval=null)}resolveDirectTimelineAdapter(){try{let e=this._iframe.contentWindow;return e?this._resolveDirectTimelineAdapterFromWindow(e):null}catch{return null}}resolveDirectTimelineAdapterFromWindow(e){return this._resolveDirectTimelineAdapterFromWindow(e)}hasRuntimeBridge(e){return Reflect.get(e,"__hf")!==void 0||I(Reflect.get(e,"__player"))}_injectRuntime(){this._runtimeInjected=!0;try{let e=this._iframe.contentDocument;if(!e)return;let t=e.createElement("script");t.src=Je,(e.head||e.documentElement).appendChild(t),this._callbacks.onRuntimeInjected?.()}catch{}}_resolveDirectTimelineAdapterFromWindow(e){if(this.hasRuntimeBridge(e))return null;let t=Reflect.get(e,"__timelines");if(!I(t))return null;let r=Object.keys(t);if(r.length===0)return null;let n=this._iframe.contentDocument?.querySelector("[data-composition-id]")?.getAttribute("data-composition-id"),o=n&&n in t?n:r[r.length-1],s=t[o];return Se(s)?s:null}_resolvePlaybackDurationAdapter(e){let t=Reflect.get(e,"__player");if(Ee(t))return{kind:"runtime",getDuration:()=>t.getDuration()};let r=this._resolveDirectTimelineAdapterFromWindow(e);return r?{kind:"direct-timeline",timeline:r,getDuration:()=>r.duration()}:null}};var Te=`
   :host {
     display: block;
     position: relative;