@hyperframes/studio 0.7.21 → 0.7.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/studio",
-  "version": "0.7.21",
+  "version": "0.7.22",
   "description": "",
   "repository": {
     "type": "git",
@@ -46,11 +46,11 @@
     "gsap": "^3.13.0",
     "marked": "^14.1.4",
     "mediabunny": "^1.45.3",
-    "@hyperframes/parsers": "0.7.21",
-    "@hyperframes/player": "0.7.21",
-    "@hyperframes/studio-server": "0.7.21",
-    "@hyperframes/sdk": "0.7.21",
-    "@hyperframes/core": "0.7.21"
+    "@hyperframes/core": "0.7.22",
+    "@hyperframes/parsers": "0.7.22",
+    "@hyperframes/sdk": "0.7.22",
+    "@hyperframes/player": "0.7.22",
+    "@hyperframes/studio-server": "0.7.22"
   },
   "devDependencies": {
     "@types/react": "19",
@@ -65,7 +65,7 @@
     "vite": "^6.4.2",
     "vitest": "^3.2.4",
     "zustand": "^5.0.0",
-    "@hyperframes/producer": "0.7.21"
+    "@hyperframes/producer": "0.7.22"
   },
   "peerDependencies": {
     "react": "19",

package/src/App.tsx

@@ -36,10 +36,7 @@ import {
 import type { DomEditSelection } from "./components/editor/domEditing";
 import { StudioHeader } from "./components/StudioHeader";
 import { useGestureCommit } from "./hooks/useGestureCommit";
-import {
-  STUDIO_KEYFRAMES_ENABLED,
-  STUDIO_STORYBOARD_ENABLED,
-} from "./components/editor/manualEditingAvailability";
+import { STUDIO_KEYFRAMES_ENABLED } from "./components/editor/manualEditingAvailability";
 import { GestureTrailOverlay } from "./components/editor/GestureTrailOverlay";
 import { StudioLeftSidebar } from "./components/StudioLeftSidebar";
 import { StudioPreviewArea } from "./components/StudioPreviewArea";
@@ -65,7 +62,7 @@ type CanvasRect = { left: number; top: number; width: number; height: number };
 export function StudioApp() {
   const { projectId, resolving, waitingForServer } = useServerConnection();
   const initialUrlStateRef = useRef(readStudioUrlStateFromWindow());
-  const viewModeValue = useViewModeState(STUDIO_STORYBOARD_ENABLED);
+  const viewModeValue = useViewModeState();
 
   // sessionStorage-backed: fires once per tab, survives HMR remounts
   useEffect(() => {

package/src/components/StudioHeader.tsx

@@ -3,7 +3,6 @@ import { RotateCcw, RotateCw, Camera } from "../icons/SystemIcons";
 import {
   STUDIO_INSPECTOR_PANELS_ENABLED,
   STUDIO_MANUAL_EDITING_DISABLED_TITLE,
-  STUDIO_STORYBOARD_ENABLED,
 } from "./editor/manualEditingAvailability";
 import { getHistoryShortcutLabel } from "../utils/studioHelpers";
 import { useStudioShellContext } from "../contexts/StudioContext";
@@ -204,8 +203,8 @@ export function StudioHeader({
         </span>
         <span className="text-[11px] font-medium text-neutral-300">{projectId}</span>
       </div>
-      {/* Center: storyboard / preview toggle (flag-gated) */}
-      {STUDIO_STORYBOARD_ENABLED && <ViewModeToggle />}
+      {/* Center: storyboard / preview toggle */}
+      <ViewModeToggle />
       {/* Right: toolbar buttons */}
       <div className="flex items-center gap-1.5">
         <button

package/src/components/editor/PropertyPanel.tsx

@@ -14,11 +14,10 @@ import {
 import { MetricField, Section } from "./propertyPanelPrimitives";
 import { createTransformCommitHandlers } from "./propertyPanelTransformCommit";
 import { classifyPropertyGroup } from "@hyperframes/core/gsap-parser";
-import { isMediaElement, MediaSection } from "./propertyPanelMediaSection";
-import {
-  ColorGradingSection,
-  isColorGradingCapableElement,
-} from "./propertyPanelColorGradingSection";
+import { resolveEditingSections } from "@hyperframes/core/editing";
+import { MediaSection } from "./propertyPanelMediaSection";
+import { ColorGradingSection } from "./propertyPanelColorGradingSection";
+import { domEditSelectionToFacts } from "./domEditingLayers";
 import { TextSection, StyleSections } from "./propertyPanelSections";
 import { GsapAnimationSection } from "./GsapAnimationSection";
 import { PropertyPanel3dTransform } from "./propertyPanel3dTransform";
@@ -199,6 +198,10 @@ export const PropertyPanel = memo(function PropertyPanel({
   const manualRotationEditingDisabled = !element.capabilities.canApplyManualRotation;
   const sourceLabel = element.id ? `#${element.id}` : element.selector;
   const showEditableSections = element.capabilities.canEditStyles;
+  // Capabilities are already resolved on the selection; recompute only sections,
+  // feeding the live GSAP tween count (arrives on the gsapAnimations prop, not the
+  // selection) so the Timing section shows for pure-GSAP elements with no data-start.
+  const sections = resolveEditingSections(domEditSelectionToFacts(element, gsapAnimations.length));
   const manualOffset = readStudioPathOffset(element.element);
   const manualSize = readStudioBoxSize(element.element);
   const resolvedWidth =
@@ -339,7 +342,7 @@ export const PropertyPanel = memo(function PropertyPanel({
           onRemoveTextField={onRemoveTextField}
         />
 
-        {(element.dataAttributes.start != null || gsapAnimations.length > 0) && (
+        {sections.timing && (
           // Render whenever there's an authored clip range OR animations to infer
           // one from — a pure-GSAP element with no data-start still gets a Timing
           // range (TimingSection derives it from its tweens).
@@ -349,7 +352,7 @@ export const PropertyPanel = memo(function PropertyPanel({
             onSetAttribute={onSetAttribute}
           />
         )}
-        {isMediaElement(element) && (
+        {sections.media && (
           <MediaSection
             projectDir={projectDir}
             element={element}
@@ -360,7 +363,7 @@ export const PropertyPanel = memo(function PropertyPanel({
           />
         )}
 
-        {STUDIO_COLOR_GRADING_ENABLED && isColorGradingCapableElement(element) && (
+        {STUDIO_COLOR_GRADING_ENABLED && sections.colorGrading && (
           <ColorGradingSection
             key={[
               element.id ?? "",

package/src/components/editor/domEditingDom.ts

@@ -19,39 +19,10 @@ export function isHtmlElement(value: unknown): value is HTMLElement {
 
 // ─── Style parsing ────────────────────────────────────────────────────────────
 
-export function parsePx(value: string | undefined): number | null {
-  if (!value) return null;
-  const trimmed = value.trim();
-  if (!trimmed.endsWith("px")) return null;
-  const parsed = parseFloat(trimmed);
-  return Number.isFinite(parsed) ? parsed : null;
-}
-
-export function isIdentityTransform(value: string | undefined): boolean {
-  const transform = (value ?? "none").trim();
-  if (!transform || transform === "none") return true;
-
-  const matrix = transform.match(/^matrix\(([^)]+)\)$/i);
-  if (matrix) {
-    const values = matrix[1].split(",").map((part) => Number.parseFloat(part.trim()));
-    if (values.length !== 6 || values.some((part) => !Number.isFinite(part))) return false;
-    return (
-      Math.abs(values[0] - 1) < 0.0001 &&
-      Math.abs(values[1]) < 0.0001 &&
-      Math.abs(values[2]) < 0.0001 &&
-      Math.abs(values[3] - 1) < 0.0001 &&
-      Math.abs(values[4]) < 0.0001 &&
-      Math.abs(values[5]) < 0.0001
-    );
-  }
-
-  const matrix3d = transform.match(/^matrix3d\(([^)]+)\)$/i);
-  if (!matrix3d) return false;
-  const values = matrix3d[1].split(",").map((part) => Number.parseFloat(part.trim()));
-  if (values.length !== 16 || values.some((part) => !Number.isFinite(part))) return false;
-  const identity = [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1];
-  return values.every((part, index) => Math.abs(part - identity[index]) < 0.0001);
-}
+// Single source of truth lives in @hyperframes/core/editing so the studio
+// callers and the core resolver can't drift. Re-exported here to keep this
+// module's public surface (6 studio callers import parsePx from it).
+export { parsePx } from "@hyperframes/core/editing";
 
 export function isTextBearingTag(tagName: string): boolean {
   return ["div", "span", "p", "strong", "h1", "h2", "h3", "h4", "h5", "h6"].includes(tagName);

package/src/components/editor/domEditingLayers.ts

@@ -3,6 +3,11 @@
  * for dom editing.
  */
 import type { PatchOperation } from "../../utils/sourcePatcher";
+import {
+  resolveEditingAffordances,
+  resolveEditingSections,
+  type EditableElementFacts,
+} from "@hyperframes/core/editing";
 import { groupScopedLayerRoots, resolveGroupCapture } from "./domEditingGroups";
 import type {
   DomEditCapabilities,
@@ -21,9 +26,7 @@ import {
   getSelectorIndex,
   getSourceFileForElement,
   isHtmlElement,
-  isIdentityTransform,
   isTextBearingTag,
-  parsePx,
 } from "./domEditingDom";
 import {
   findElementForSelection,
@@ -171,12 +174,66 @@ export function buildDefaultDomEditTextField(base?: Partial<DomEditTextField>):
 
 // ─── Capabilities ────────────────────────────────────────────────────────────
 
-// fallow-ignore-next-line complexity
+/**
+ * Build the geometry/capability half of EditableElementFacts. Section inputs
+ * (text/timing/animation) are irrelevant to capability resolution, so they are
+ * zeroed here. Shared by the wrapper and the live-selection path so the two
+ * fact-construction sites can't disagree.
+ */
+function capabilityFacts(geometry: {
+  hasStableTarget: boolean;
+  tag: string;
+  inlineStyles: Record<string, string>;
+  computedStyles: Record<string, string>;
+  isCompositionHost: boolean;
+  isCompositionRoot: boolean;
+  isInsideLockedComposition: boolean;
+  isMasterView: boolean;
+  existsInSource: boolean;
+}): EditableElementFacts {
+  return {
+    ...geometry,
+    hasEditableText: false,
+    hasTimingStart: false,
+    animationCount: 0,
+  };
+}
+
+/**
+ * Build core EditableElementFacts from a fully-resolved DomEditSelection.
+ * `animationCount` is supplied by the caller because live GSAP tweens arrive on
+ * a separate channel (the PropertyPanel `gsapAnimations` prop), not on the
+ * selection — `selection.gsapAnimations` is never populated.
+ */
+export function domEditSelectionToFacts(
+  selection: DomEditSelection,
+  animationCount = selection.gsapAnimations?.length ?? 0,
+): EditableElementFacts {
+  return {
+    hasStableTarget: Boolean(selection.selector || selection.hfId),
+    tag: selection.tagName,
+    inlineStyles: selection.inlineStyles,
+    computedStyles: selection.computedStyles,
+    isCompositionHost: selection.isCompositionHost,
+    isCompositionRoot: false,
+    isInsideLockedComposition: selection.isInsideLockedComposition,
+    isMasterView: false,
+    existsInSource: true,
+    hasEditableText: selection.textFields.length > 0,
+    hasTimingStart: selection.dataAttributes.start != null,
+    animationCount,
+  };
+}
+
+/**
+ * Resolve DOM edit capabilities for a given element.
+ * Thin wrapper over core resolveEditingAffordances — kept for backward
+ * compatibility (tests and the barrel import this signature directly).
+ */
 export function resolveDomEditCapabilities(args: {
   selector?: string;
   hfId?: string;
   tagName?: string;
-  className?: string;
   inlineStyles: Record<string, string>;
   computedStyles: Record<string, string>;
   isCompositionHost: boolean;
@@ -185,92 +242,19 @@ export function resolveDomEditCapabilities(args: {
   isMasterView: boolean;
   existsInSource?: boolean;
 }): DomEditCapabilities {
-  if ((!args.selector && !args.hfId) || args.isInsideLockedComposition) {
-    return {
-      canSelect: !args.isInsideLockedComposition,
-      canEditStyles: false,
-      canMove: false,
-      canResize: false,
-      canApplyManualOffset: false,
-      canApplyManualSize: false,
-      canApplyManualRotation: false,
-      reasonIfDisabled: args.isInsideLockedComposition
-        ? "This element belongs to a locked composition."
-        : "Studio could not resolve a stable patch target for this element.",
-    };
-  }
-
-  if (args.existsInSource === false) {
-    return {
-      canSelect: true,
-      canEditStyles: false,
-      canMove: false,
-      canResize: false,
-      canApplyManualOffset: false,
-      canApplyManualSize: false,
-      canApplyManualRotation: false,
-      reasonIfDisabled: "This element is generated by a script and cannot be edited visually.",
-    };
-  }
-
-  if (args.isCompositionRoot) {
-    return {
-      canSelect: true,
-      canEditStyles: true,
-      canMove: false,
-      canResize: false,
-      canApplyManualOffset: false,
-      canApplyManualSize: false,
-      canApplyManualRotation: false,
-      reasonIfDisabled: "The root composition defines the preview bounds.",
-    };
-  }
-
-  const position = args.computedStyles.position;
-  const left = parsePx(args.inlineStyles.left) ?? parsePx(args.computedStyles.left);
-  const top = parsePx(args.inlineStyles.top) ?? parsePx(args.computedStyles.top);
-  const width = parsePx(args.inlineStyles.width) ?? parsePx(args.computedStyles.width);
-  const height = parsePx(args.inlineStyles.height) ?? parsePx(args.computedStyles.height);
-  const hasTransformDrivenGeometry = !isIdentityTransform(args.computedStyles.transform);
-
-  const canMove =
-    (position === "absolute" || position === "fixed") &&
-    left != null &&
-    top != null &&
-    !hasTransformDrivenGeometry;
-
-  const canResize = canMove && (width != null || height != null);
-  const canApplyManualGeometry = !args.isCompositionHost;
-  const canApplyManualOffset = canApplyManualGeometry;
-  const canApplyManualSize = canApplyManualGeometry;
-  const canApplyManualRotation = canApplyManualGeometry;
-  const reasonIfDisabled = canApplyManualGeometry
-    ? undefined
-    : "Select an internal layer to transform it.";
-
-  if (args.isCompositionHost && args.isMasterView) {
-    return {
-      canSelect: true,
-      canEditStyles: false,
-      canMove,
-      canResize,
-      canApplyManualOffset,
-      canApplyManualSize,
-      canApplyManualRotation,
-      reasonIfDisabled,
-    };
-  }
-
-  return {
-    canSelect: true,
-    canEditStyles: true,
-    canMove,
-    canResize,
-    canApplyManualOffset,
-    canApplyManualSize,
-    canApplyManualRotation,
-    reasonIfDisabled,
-  };
+  return resolveEditingAffordances(
+    capabilityFacts({
+      hasStableTarget: Boolean(args.selector || args.hfId),
+      tag: (args.tagName ?? "div").toLowerCase(),
+      inlineStyles: args.inlineStyles,
+      computedStyles: args.computedStyles,
+      isCompositionHost: args.isCompositionHost,
+      isCompositionRoot: args.isCompositionRoot ?? false,
+      isInsideLockedComposition: args.isInsideLockedComposition ?? false,
+      isMasterView: args.isMasterView,
+      existsInSource: args.existsInSource ?? true,
+    }),
+  ).capabilities;
 }
 
 // ─── Element label ────────────────────────────────────────────────────────────
@@ -354,19 +338,19 @@ export async function resolveDomEditSelection(
       if (selectorIndex != null) probeTarget.selectorIndex = selectorIndex;
       existsInSource = await probeSourceElement(options.projectId, sourceFile, probeTarget);
     }
-    const capabilities = resolveDomEditCapabilities({
-      selector,
-      hfId,
-      tagName: current.tagName.toLowerCase(),
-      className: current.className,
-      inlineStyles,
-      computedStyles,
-      isCompositionHost: Boolean(compositionSrc),
-      isCompositionRoot,
-      isInsideLockedComposition: isInsideLocked,
-      isMasterView: options.isMasterView,
-      existsInSource,
-    });
+    const capabilities = resolveEditingAffordances(
+      capabilityFacts({
+        hasStableTarget: Boolean(selector || hfId),
+        tag: current.tagName.toLowerCase(),
+        inlineStyles,
+        computedStyles,
+        isCompositionHost: Boolean(compositionSrc),
+        isCompositionRoot,
+        isInsideLockedComposition: isInsideLocked,
+        isMasterView: options.isMasterView,
+        existsInSource: existsInSource ?? true,
+      }),
+    ).capabilities;
     const rect = current.getBoundingClientRect();
 
     return {
@@ -554,11 +538,7 @@ export function getDomEditTargetKey(
 }
 
 export function isTextEditableSelection(selection: DomEditSelection): boolean {
-  return (
-    selection.textFields.length > 0 &&
-    !selection.isCompositionHost &&
-    !selection.isInsideLockedComposition
-  );
+  return resolveEditingSections(domEditSelectionToFacts(selection)).text;
 }
 
 // buildElementAgentPrompt is in domEditingAgentPrompt.ts

package/src/components/editor/manualEditingAvailability.ts

@@ -82,16 +82,6 @@ export const STUDIO_RAZOR_TOOL_ENABLED = resolveStudioBooleanEnvFlag(
   true,
 );
 
-// Storyboard view: a top-level, toggleable view that renders STORYBOARD.md as a
-// contact sheet of live HTML frame tiles, replacing the timeline/preview stage.
-// Opt-in / off by default until the experience is ready for broad exposure.
-//   VITE_STUDIO_ENABLE_STORYBOARD=1 npx hyperframes preview
-export const STUDIO_STORYBOARD_ENABLED = resolveStudioBooleanEnvFlag(
-  env,
-  ["VITE_STUDIO_ENABLE_STORYBOARD", "VITE_STUDIO_STORYBOARD_ENABLED"],
-  false,
-);
-
 export const STUDIO_PREVIEW_SELECTION_ENABLED = STUDIO_INSPECTOR_PANELS_ENABLED;
 
 // Stage 7 Step 3c: SDK cutover — routes inline-style ops through SDK dispatch

package/src/components/editor/propertyPanelColorGradingSection.tsx

@@ -50,10 +50,6 @@ interface RuntimeColorGradingStatus {
   message: string;
 }
 
-export function isColorGradingCapableElement(element: DomEditSelection): boolean {
-  return element.tagName === "video" || element.tagName === "img";
-}
-
 function readColorGradingFromElement(element: DomEditSelection): NormalizedHfColorGrading {
   const grading =
     normalizeHfColorGrading(element.dataAttributes[COLOR_GRADING_DATA_KEY]) ??

package/src/components/editor/propertyPanelMediaSection.tsx

@@ -10,12 +10,6 @@ import {
 } from "./propertyPanelHelpers";
 import { Section, SegmentedControl, SelectField, SliderControl } from "./propertyPanelPrimitives";
 
-const MEDIA_TAGS = new Set(["video", "audio"]);
-
-export function isMediaElement(element: DomEditSelection): boolean {
-  return MEDIA_TAGS.has(element.tagName);
-}
-
 export function MediaSection({
   projectDir,
   element,

package/src/contexts/ViewModeContext.tsx

@@ -44,14 +44,11 @@ export interface ViewModeValue {
 }
 
 /**
- * Owns the view-mode state. When `enabled` is false (storyboard flag off) the
- * mode is pinned to `timeline` and the URL is left untouched, so the feature is
- * fully inert until the flag is on.
+ * Owns the view-mode state — initial read from `?view=`, toggling, popstate sync.
+ * Storyboard mode is always available; no flag gating.
  */
-export function useViewModeState(enabled: boolean): ViewModeValue {
-  const [viewMode, setMode] = useState<StudioViewMode>(() =>
-    enabled ? readViewModeFromUrl() : "timeline",
-  );
+export function useViewModeState(): ViewModeValue {
+  const [viewMode, setMode] = useState<StudioViewMode>(() => readViewModeFromUrl());
 
   // Reflect genuine browser back/forward between history entries with a different
   // `?view=`. Note: our own writes use `replaceState` (below), which does NOT fire
@@ -60,23 +57,17 @@ export function useViewModeState(enabled: boolean): ViewModeValue {
   // the mount-time read); a scripted `pushState`/`replaceState` to `?view=` would not be
   // reflected here, by design.
   useEffect(() => {
-    if (!enabled) return;
     const onPopState = () => setMode(readViewModeFromUrl());
     window.addEventListener("popstate", onPopState);
     return () => window.removeEventListener("popstate", onPopState);
-  }, [enabled]);
+  }, []);
 
-  const setViewMode = useCallback(
-    (mode: StudioViewMode) => {
-      if (!enabled) return;
-      setMode(mode);
-      writeViewModeToUrl(mode);
-    },
-    [enabled],
-  );
+  const setViewMode = useCallback((mode: StudioViewMode) => {
+    setMode(mode);
+    writeViewModeToUrl(mode);
+  }, []);
 
-  const effectiveMode = enabled ? viewMode : "timeline";
-  return useMemo(() => ({ viewMode: effectiveMode, setViewMode }), [effectiveMode, setViewMode]);
+  return useMemo(() => ({ viewMode, setViewMode }), [viewMode, setViewMode]);
 }
 
 const ViewModeContext = createContext<ViewModeValue | null>(null);

package/src/hooks/useDomEditSession.ts

@@ -260,7 +260,9 @@ export function useDomEditSession({
     onTrySdkPersist: sdkSession
       ? (selection, operations, originalContent, targetPath, options) => {
           // Resolver shadow runs regardless of the cutover flag — decoupled tripwire.
-          runResolverShadow(sdkSession, selection.hfId, operations);
+          // Pass originalContent so the runtime-node filter can suppress hf-ids
+          // absent from source (script-created nodes the SDK can't model).
+          runResolverShadow(sdkSession, selection.hfId, operations, originalContent);
           return sdkCutoverPersist(
             selection,
             operations,

package/src/utils/sdkResolverShadow.test.ts

@@ -226,6 +226,53 @@ describe("C. Resolver-parity detection", () => {
     });
   });
 
+  it("C8 runtime-node filter: hfId absent from source → suppressed (not a resolver bug)", () => {
+    // The studio resolved a live-DOM element to an hf-id that the SDK session
+    // doesn't contain AND that never appears in the on-disk source — it's a
+    // node a composition <script> created at runtime (e.g. caption spans). Not
+    // a resolver divergence; suppress.
+    const session = { getElement: () => null, getElements: () => [] } as unknown as Parameters<
+      typeof sdkResolverShadowCheck
+    >[0];
+    const source = `<div data-hf-id="hf-static">no runtime id here</div>`;
+    const mismatches = sdkResolverShadowCheck(
+      session,
+      "hf-runtimeonly",
+      [{ type: "inline-style", property: "color", value: "red" }],
+      source,
+    );
+    expect(mismatches).toHaveLength(0);
+  });
+
+  it("C8 runtime-node filter: hfId PRESENT in source but missing from session → still flagged (real bug)", () => {
+    const session = { getElement: () => null, getElements: () => [] } as unknown as Parameters<
+      typeof sdkResolverShadowCheck
+    >[0];
+    const source = `<div data-hf-id="hf-realbug">in source, not in SDK session</div>`;
+    const mismatches = sdkResolverShadowCheck(
+      session,
+      "hf-realbug",
+      [{ type: "inline-style", property: "color", value: "red" }],
+      source,
+    );
+    expect(mismatches).toHaveLength(1);
+    expect(mismatches[0]?.kind).toBe("element_not_found");
+  });
+
+  it("C8 sourceHfIdCount: emitted element_not_found carries source occurrence count", async () => {
+    mockFlags.STUDIO_SDK_RESOLVER_SHADOW_ENABLED = true;
+    const session = { getElement: () => null, getElements: () => [] } as unknown as Composition;
+    // id present twice in source (duplicate-id ambiguity) but absent from session
+    const source = `<div data-hf-id="hf-dup">a</div><div data-hf-id="hf-dup">b</div>`;
+    runResolverShadow(
+      session,
+      "hf-dup",
+      [{ type: "inline-style", property: "color", value: "red" }],
+      source,
+    );
+    expect(lastShadow()?.sourceHfIdCount).toBe(2);
+  });
+
   it("C10: unmappable op type produces no mismatch (excluded, not flagged)", async () => {
     const session = await openComposition(BASE_HTML);
     // "unknown-op" is not in MAPPED_OP_TYPES, so it must be silently excluded.

package/src/utils/sdkResolverShadow.ts

@@ -82,6 +82,14 @@ type AttrMap = Record<string, string | null>;
  * Mirror resolveScoped here: exact scoped-path match, then canonical bare
  * match, then first bare match — the resolvability dispatch actually has.
  */
+// Count static `data-hf-id="<id>"` occurrences (both quote styles) in source.
+// Substring split, not regex — no escaping, and the id never contains a quote.
+function countHfIdInSource(source: string, id: string): number {
+  return (
+    source.split(`data-hf-id="${id}"`).length - 1 + (source.split(`data-hf-id='${id}'`).length - 1)
+  );
+}
+
 function resolveSnapshot(session: Composition, id: string): FlatEl | null {
   const els = session.getElements();
   const exact = els.find((el) => el.scopedId === id);
@@ -164,8 +172,17 @@ export function sdkResolverShadowCheck(
   session: Composition,
   hfId: string,
   ops: PatchOperation[],
+  sourceContent?: string,
 ): SdkResolverMismatch[] {
   if (!resolveSnapshot(session, hfId)) {
+    // Runtime-node filter: an hf-id absent from the on-disk source the SDK
+    // parsed was never in the static DOM — it belongs to an element a
+    // composition <script> creates at runtime (e.g. caption word/group spans),
+    // which the SDK session cannot model by design. That is NOT a resolver bug,
+    // so suppress it. An hf-id PRESENT in source but missing from the session IS
+    // a genuine resolver divergence (the v0.6.110 class) — keep emitting that.
+    // ponytail: substring match; biases toward keeping signal on a loose hit.
+    if (sourceContent !== undefined && !sourceContent.includes(hfId)) return [];
     return [{ kind: "element_not_found", hfId }];
   }
 
@@ -241,17 +258,30 @@ export function runResolverShadow(
   session: Composition,
   hfId: string | null | undefined,
   ops: PatchOperation[],
+  sourceContent?: string,
 ): void {
   if (!STUDIO_SDK_RESOLVER_SHADOW_ENABLED) return;
   if (!hfId) return;
   try {
-    const mismatches = sdkResolverShadowCheck(session, hfId, ops);
+    const mismatches = sdkResolverShadowCheck(session, hfId, ops, sourceContent);
     // Emit only on divergence — parity is silent, matching recordResolverParity
     // and recordAnimationResolverParity. Otherwise this fires a PostHog event on
     // every style/text/attr edit (the editor's chattiest path) at default-ON.
     if (mismatches.length === 0) return;
+    const isElementNotFound = mismatches.some((m) => m.kind === "element_not_found");
     trackStudioEvent("sdk_resolver_shadow", {
       hfId,
+      // sessionElementCount > 0 + element_not_found = runtime-only element;
+      // sessionElementCount === 0 = session is empty/broken (actionable).
+      sessionElementCount: session.getElements().length,
+      // Count of data-hf-id="<id>" occurrences in source for an emitted
+      // element_not_found (the runtime-node filter already dropped absent-from-
+      // source ids, so an emitted one is in source ≥1×). >1 = duplicate ids →
+      // resolver picked the wrong instance; =1 = single static node the SDK
+      // parse dropped (foreign-content exclusion / sub-comp inlining gap).
+      ...(isElementNotFound && sourceContent !== undefined
+        ? { sourceHfIdCount: countHfIdInSource(sourceContent, hfId) }
+        : {}),
       mismatchCount: mismatches.length,
       mismatches: JSON.stringify(redactMismatches(mismatches)),
     });
@@ -282,6 +312,7 @@ export function recordResolverParity(
     trackStudioEvent("sdk_resolver_shadow", {
       hfId,
       opLabel,
+      sessionElementCount: session.getElements().length,
       mismatchCount: 1,
       mismatches: JSON.stringify([
         { kind: "element_not_found", hfId } satisfies SdkResolverMismatch,
@@ -310,11 +341,13 @@ export function recordAnimationResolverParity(
   if (!STUDIO_SDK_RESOLVER_SHADOW_ENABLED) return;
   if (!session || !animationId) return;
   try {
-    const resolves = session.getElements().some((el) => el.animationIds.includes(animationId));
+    const elements = session.getElements();
+    const resolves = elements.some((el) => el.animationIds.includes(animationId));
     if (resolves) return; // SDK locates the animation — parity
     trackStudioEvent("sdk_resolver_shadow", {
       animationId,
       opLabel,
+      sessionElementCount: elements.length,
       mismatchCount: 1,
       mismatches: JSON.stringify([
         { kind: "animation_not_found", animationId } satisfies SdkResolverMismatch,