npm - @agent-native/core - Versions diffs - 0.88.0 → 0.90.2 - Mend

@agent-native/core 0.88.0 → 0.90.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (1866) hide show

package/corpus/templates/design/app/components/design/multi-screen/board-surface-html.ts ADDED Viewed

@@ -0,0 +1,220 @@
+export function hasBoardSurfaceContent(html: string | undefined) {
+  if (!html) return false;
+  const bodyMatch = html.match(/<body\b[^>]*>([\s\S]*?)<\/body>/i);
+  const content = bodyMatch?.[1] ?? html;
+  return content.replace(/<!--[\s\S]*?-->/g, "").trim().length > 0;
+}
+const BOARD_SURFACE_RENDER_STYLE = `<style data-agent-native-board-surface-render>html,body{background:transparent!important;background-color:transparent!important;background-image:none!important;}body{margin:0!important;position:relative;overflow:visible;}body>:not([data-agent-native-node-id]):not(style):not(script),body>[data-agent-native-node-id]:not([data-an-primitive]):not([data-agent-native-preserve-styles="true"]):has([data-agent-native-node-id]),body>[data-agent-native-node-id="body"],body>[data-agent-native-node-id="Body"],body>[data-agent-native-layer-name="body"],body>[data-agent-native-layer-name="Body"],body>[data-agent-native-layer-name="<body>"]{background:transparent!important;background-color:transparent!important;background-image:none!important;box-shadow:none!important;}[data-agent-native-board-backdrop-candidate="true"]{display:none!important;pointer-events:none!important;}</style>`;
+export const BOARD_SURFACE_BACKGROUND = "hsl(0 0% 10%)";
+const BOARD_SURFACE_BACKDROP_MIN_EDGE_PX = 2400;
+const BOARD_SURFACE_BACKDROP_MIN_AREA_PX = 8_000_000;
+const HTML_VOID_TAGS = new Set([
+  "area",
+  "base",
+  "br",
+  "col",
+  "embed",
+  "hr",
+  "img",
+  "input",
+  "link",
+  "meta",
+  "param",
+  "source",
+  "track",
+  "wbr",
+]);
+const HTML_TAG_RE = /<!--[\s\S]*?-->|<\/?([a-zA-Z][\w:-]*)([^<>]*?)\/?>/g;
+function getHtmlAttributeValue(tag: string, name: string) {
+  const match = tag.match(
+    new RegExp(
+      `\\s${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s"'=<>]+))`,
+      "i",
+    ),
+  );
+  return match?.[1] ?? match?.[2] ?? match?.[3] ?? "";
+}
+function getCssDeclarationValue(style: string, name: string) {
+  const match = style.match(
+    new RegExp(`(?:^|;)\\s*${name}\\s*:\\s*([^;]+)`, "i"),
+  );
+  return match?.[1]?.trim() ?? "";
+}
+function getCssPixelValue(style: string, name: string) {
+  const value = getCssDeclarationValue(style, name);
+  const match = value.match(/^(-?\d+(?:\.\d+)?)px$/i);
+  if (!match?.[1]) return null;
+  const parsed = Number(match[1]);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+function parseCssColor(value: string) {
+  const trimmed = value.trim().toLowerCase();
+  if (!trimmed || trimmed === "transparent") return null;
+  const rgb = trimmed.match(
+    /^rgba?\(\s*(\d+(?:\.\d+)?)\s*,\s*(\d+(?:\.\d+)?)\s*,\s*(\d+(?:\.\d+)?)(?:\s*,\s*(\d+(?:\.\d+)?))?\s*\)$/,
+  );
+  if (rgb?.[1] && rgb[2] && rgb[3]) {
+    const alpha = rgb[4] === undefined ? 1 : Number(rgb[4]);
+    if (alpha <= 0) return null;
+    return [Number(rgb[1]), Number(rgb[2]), Number(rgb[3])] as const;
+  }
+  const hex = trimmed.match(/^#([0-9a-f]{3}|[0-9a-f]{6})$/i);
+  if (!hex?.[1]) return null;
+  const raw = hex[1];
+  const full =
+    raw.length === 3
+      ? raw
+          .split("")
+          .map((part) => part + part)
+          .join("")
+      : raw;
+  return [
+    Number.parseInt(full.slice(0, 2), 16),
+    Number.parseInt(full.slice(2, 4), 16),
+    Number.parseInt(full.slice(4, 6), 16),
+  ] as const;
+}
+function isNeutralBackdropColor(value: string) {
+  const color = parseCssColor(value);
+  if (!color) return false;
+  const max = Math.max(...color);
+  const min = Math.min(...color);
+  return min >= 180 && max - min <= 24;
+}
+function isAccidentalBoardBackdropTag(tag: string) {
+  if (
+    getHtmlAttributeValue(tag, "data-agent-native-board-backdrop-candidate")
+  ) {
+    return false;
+  }
+  const primitive = getHtmlAttributeValue(
+    tag,
+    "data-an-primitive",
+  ).toLowerCase();
+  if (primitive !== "rectangle" && primitive !== "rect") return false;
+  const style = getHtmlAttributeValue(tag, "style");
+  if (!style) return false;
+  const width = getCssPixelValue(style, "width");
+  const height = getCssPixelValue(style, "height");
+  if (width === null || height === null) return false;
+  if (
+    width < BOARD_SURFACE_BACKDROP_MIN_EDGE_PX ||
+    height < BOARD_SURFACE_BACKDROP_MIN_EDGE_PX ||
+    width * height < BOARD_SURFACE_BACKDROP_MIN_AREA_PX
+  ) {
+    return false;
+  }
+  const background =
+    getCssDeclarationValue(style, "background-color") ||
+    getCssDeclarationValue(style, "background");
+  return isNeutralBackdropColor(background);
+}
+function markAccidentalBoardBackdropCandidates(html: string) {
+  return html.replace(HTML_TAG_RE, (tag: string, tagName?: string) => {
+    if (!tagName || tag.startsWith("</")) return tag;
+    if (!isAccidentalBoardBackdropTag(tag)) return tag;
+    return tag.replace(
+      /\/?>$/,
+      (ending) => ` data-agent-native-board-backdrop-candidate="true"${ending}`,
+    );
+  });
+}
+function findLastHtmlStackTagIndex(
+  stack: Array<{ tagName: string; nodeId: string }>,
+  tagName: string,
+) {
+  for (let i = stack.length - 1; i >= 0; i--) {
+    if (stack[i]?.tagName === tagName) return i;
+  }
+  return -1;
+}
+function getCurrentLayerParentNodeId(
+  stack: Array<{ tagName: string; nodeId: string }>,
+) {
+  for (let i = stack.length - 1; i >= 0; i--) {
+    const nodeId = stack[i]?.nodeId;
+    if (nodeId) return nodeId;
+  }
+  return "body";
+}
+export function getBoardSurfaceRenderContent(html: string) {
+  if (!html) return html;
+  const renderHtml = markAccidentalBoardBackdropCandidates(html);
+  if (renderHtml.includes("data-agent-native-board-surface-render")) {
+    return renderHtml;
+  }
+  if (/<\/head>/i.test(html)) {
+    return renderHtml.replace(
+      /<\/head>/i,
+      `${BOARD_SURFACE_RENDER_STYLE}</head>`,
+    );
+  }
+  if (/<body\b/i.test(html)) {
+    return renderHtml.replace(/<body\b/i, `${BOARD_SURFACE_RENDER_STYLE}<body`);
+  }
+  return `${BOARD_SURFACE_RENDER_STYLE}${renderHtml}`;
+}
+/** Simple djb2-xor string hash, used to build cheap cache keys elsewhere in
+ *  the multi-screen canvas (board content signatures, primitive-parse cache
+ *  keys, etc). */
+export function hashString(s: string): string {
+  let h = 5381;
+  for (let i = 0; i < s.length; i++) {
+    // h = h * 33 ^ charCode  (djb2 xor variant)
+    h = ((h << 5) + h) ^ s.charCodeAt(i);
+    h = h >>> 0; // keep as unsigned 32-bit
+  }
+  return h.toString(16);
+}
+export function getBoardContentLayerSignature(html: string) {
+  const layers: string[] = [];
+  const stack: Array<{ tagName: string; nodeId: string }> = [];
+  const childCountsByParent = new Map<string, number>();
+  for (const match of html.matchAll(HTML_TAG_RE)) {
+    const token = match[0];
+    const tagName = match[1]?.toLowerCase();
+    if (!tagName) continue;
+    if (token.startsWith("</")) {
+      const index = findLastHtmlStackTagIndex(stack, tagName);
+      if (index >= 0) stack.splice(index);
+      continue;
+    }
+    const nodeId = getHtmlAttributeValue(token, "data-agent-native-node-id");
+    if (nodeId) {
+      const parentNodeId = getCurrentLayerParentNodeId(stack);
+      const childIndex = childCountsByParent.get(parentNodeId) ?? 0;
+      childCountsByParent.set(parentNodeId, childIndex + 1);
+      layers.push(`${nodeId}<${parentNodeId}#${childIndex}`);
+    }
+    const selfClosing = token.endsWith("/>") || HTML_VOID_TAGS.has(tagName);
+    if (!selfClosing) stack.push({ tagName, nodeId });
+  }
+  return `${layers.length}:${hashString(layers.join("\n"))}`;
+}
+export function getBoardContentKey(args: {
+  boardFileId: string;
+  boardFileContent: string;
+  boardIsActive: boolean;
+}) {
+  return `${args.boardFileId}:surface`;
+}

package/corpus/templates/design/app/components/design/multi-screen/chrome-transitions.ts ADDED Viewed

@@ -0,0 +1,35 @@
+// During a zoom gesture the constant-size selection chrome is frozen (we don't
+// re-render); on commit it recomputes to its fixed screen size. These transitions
+// are enabled only for that brief settle, so normal selection, resize, and
+// screen-switch geometry stays pinned to the frame.
+export const CHROME_SETTLE_MS = 150;
+const CHROME_OPACITY_TRANSITION = "opacity 150ms ease-out";
+const CHROME_BORDER_SETTLE_TRANSITION = `inset ${CHROME_SETTLE_MS}ms ease-out, border-width ${CHROME_SETTLE_MS}ms ease-out, border-radius ${CHROME_SETTLE_MS}ms ease-out, ${CHROME_OPACITY_TRANSITION}`;
+const SELECTION_BOX_SETTLE_TRANSITION = `border-width ${CHROME_SETTLE_MS}ms ease-out, border-radius ${CHROME_SETTLE_MS}ms ease-out, ${CHROME_OPACITY_TRANSITION}`;
+const CHROME_HANDLE_SETTLE_TRANSITION = `width ${CHROME_SETTLE_MS}ms ease-out, height ${CHROME_SETTLE_MS}ms ease-out, border-width ${CHROME_SETTLE_MS}ms ease-out, top ${CHROME_SETTLE_MS}ms ease-out, bottom ${CHROME_SETTLE_MS}ms ease-out, left ${CHROME_SETTLE_MS}ms ease-out, right ${CHROME_SETTLE_MS}ms ease-out, ${CHROME_OPACITY_TRANSITION}`;
+// Frame header (name + "Full view" button) is counter-scaled via
+// transform to stay a fixed screen size; ease that scale on zoom-settle. opacity
+// is included so the button's hover-fade (transition-opacity) keeps working.
+const CHROME_LABEL_SETTLE_TRANSITION = `transform ${CHROME_SETTLE_MS}ms ease-out, ${CHROME_OPACITY_TRANSITION}`;
+export function getChromeBorderTransition(chromeSettling: boolean) {
+  return chromeSettling
+    ? CHROME_BORDER_SETTLE_TRANSITION
+    : CHROME_OPACITY_TRANSITION;
+}
+export function getSelectionBoxTransition(chromeSettling: boolean) {
+  return chromeSettling ? SELECTION_BOX_SETTLE_TRANSITION : "none";
+}
+export function getChromeHandleTransition(chromeSettling: boolean) {
+  return chromeSettling
+    ? CHROME_HANDLE_SETTLE_TRANSITION
+    : CHROME_OPACITY_TRANSITION;
+}
+export function getChromeLabelTransition(chromeSettling: boolean) {
+  return chromeSettling
+    ? CHROME_LABEL_SETTLE_TRANSITION
+    : CHROME_OPACITY_TRANSITION;
+}

package/corpus/templates/design/app/components/design/multi-screen/cross-screen-drop.ts ADDED Viewed

@@ -0,0 +1,134 @@
+import type { CSSProperties } from "react";
+import { SURFACE_PADDING } from "../MultiScreenCanvas";
+import type { PortableStyleSnapshot } from "../types";
+import type {
+  CrossScreenDropAxis,
+  CrossScreenDropGuide,
+  CrossScreenDropMode,
+  CrossScreenDropPlacement,
+  CrossScreenHitTestAnchorRect,
+  CrossScreenHitTestResult,
+  FrameGeometry,
+  Point,
+} from "./types";
+export function isFinitePoint(value: unknown): value is Point {
+  if (!value || typeof value !== "object") return false;
+  const point = value as Record<string, unknown>;
+  return Number.isFinite(point.x) && Number.isFinite(point.y);
+}
+export function isPortableStyleSnapshot(
+  value: unknown,
+): value is PortableStyleSnapshot {
+  if (!value || typeof value !== "object") return false;
+  const snapshot = value as Record<string, unknown>;
+  return snapshot.version === 1 && Array.isArray(snapshot.nodes);
+}
+export function isCrossScreenDropPlacement(
+  value: unknown,
+): value is CrossScreenDropPlacement {
+  return value === "before" || value === "after" || value === "inside";
+}
+export function isCrossScreenDropAxis(
+  value: unknown,
+): value is CrossScreenDropAxis {
+  return value === "x" || value === "y";
+}
+export function isCrossScreenDropMode(
+  value: unknown,
+): value is CrossScreenDropMode {
+  return value === "flow-insert" || value === "absolute-container";
+}
+export function isCrossScreenHitTestAnchorRect(
+  value: unknown,
+): value is CrossScreenHitTestAnchorRect {
+  if (!value || typeof value !== "object") return false;
+  const rect = value as Record<string, unknown>;
+  return (
+    Number.isFinite(rect.left) &&
+    Number.isFinite(rect.top) &&
+    Number.isFinite(rect.width) &&
+    Number.isFinite(rect.height)
+  );
+}
+export function getCrossScreenDropGuideForHitTest(args: {
+  hit: CrossScreenHitTestResult;
+  targetGeometry: FrameGeometry;
+  targetMetadata: { width: number; height: number };
+}): CrossScreenDropGuide | null {
+  const rect = args.hit.anchorRect;
+  if (!rect) return null;
+  const placement = args.hit.placement ?? "inside";
+  const axis = args.hit.axis ?? "y";
+  const scaleX =
+    args.targetGeometry.width / Math.max(1, args.targetMetadata.width);
+  const scaleY =
+    args.targetGeometry.height / Math.max(1, args.targetMetadata.height);
+  return {
+    placement,
+    axis,
+    boardRect: {
+      x: args.targetGeometry.x + rect.left * scaleX,
+      y: args.targetGeometry.y + rect.top * scaleY,
+      width: Math.max(1, rect.width * scaleX),
+      height: Math.max(1, rect.height * scaleY),
+    },
+  };
+}
+export function getCrossScreenDropGuideStyle(args: {
+  guide: CrossScreenDropGuide;
+  pan: Point;
+  scale: number;
+}): CSSProperties {
+  const { boardRect, placement, axis } = args.guide;
+  const left = args.pan.x + (SURFACE_PADDING + boardRect.x) * args.scale;
+  const top = args.pan.y + (SURFACE_PADDING + boardRect.y) * args.scale;
+  const width = Math.max(1, boardRect.width * args.scale);
+  const height = Math.max(1, boardRect.height * args.scale);
+  if (placement === "inside") {
+    return {
+      left,
+      top,
+      width,
+      height,
+      border: "2px solid var(--design-editor-accent-color)",
+      background:
+        "color-mix(in srgb, var(--design-editor-accent-color) 14%, transparent)",
+      borderRadius: 2,
+      boxShadow: "none",
+    };
+  }
+  if (axis === "x") {
+    const x = placement === "before" ? left : left + width;
+    return {
+      left: x - 1,
+      top,
+      width: 2,
+      height: Math.max(8, height),
+      background: "var(--design-editor-accent-color)",
+      borderRadius: 999,
+      boxShadow: "0 0 0 1px var(--design-editor-accent-color)",
+    };
+  }
+  const y = placement === "before" ? top : top + height;
+  return {
+    left,
+    top: y - 1,
+    width: Math.max(8, width),
+    height: 2,
+    background: "var(--design-editor-accent-color)",
+    borderRadius: 999,
+    boxShadow: "0 0 0 1px var(--design-editor-accent-color)",
+  };
+}

package/corpus/templates/design/app/components/design/multi-screen/culling.ts ADDED Viewed

@@ -0,0 +1,185 @@
+import { getRotatedFrameAABB } from "@shared/canvas-math";
+import { SURFACE_PADDING } from "../MultiScreenCanvas";
+import type { FrameGeometry, Point } from "./types";
+// ── Overview viewport culling (PF22) ────────────────────────────────────────
+//
+// Boards with 100+ screens used to render every screen as a full live iframe
+// regardless of whether it was anywhere near the visible viewport. This is a
+// deliberately conservative culling scheme:
+//
+// - Visibility is computed from the *committed* pan/zoom React state (`pan`,
+//   `canvasZoom`), never from the imperative per-gesture-frame transform
+//   (zoomRef/panRef, mutated by applyViewToDom every wheel/pinch tick — see
+//   its comment). Recomputing this per gesture frame would mean re-rendering
+//   React during a gesture, exactly what applyViewToDom/scheduleViewCommit
+//   were built to avoid.
+// - A generous overscan margin keeps screens "live" well before they
+//   physically enter the viewport, so a settled-but-about-to-pan-into-view
+//   screen (the debounced commit lags real cursor position by up to
+//   ~120ms — see scheduleViewCommit) is already mounted by the time it's
+//   reachable.
+// - Two tiers, see computeScreenCullTier: a screen that has never intersected
+//   the overscanned viewport this session renders a lightweight placeholder;
+//   once visible it mounts real content and never goes back to a placeholder
+//   — it only ever gets hidden (Tier B), never unmounted, since iframes lose
+//   all internal state (scroll position, form input, Alpine/JS state) on
+//   unmount.
+/** Escape hatch: flip to `false` to fully disable culling in one line if a
+ *  regression appears — every screen goes back to always rendering full
+ *  content, matching pre-culling behavior exactly. */
+export const OVERVIEW_CULLING_ENABLED = true;
+/** How many viewport widths/heights of margin to add around the visible
+ *  surface, in each direction, before a screen counts as "culled". Generous
+ *  on purpose: the mission calls for >=1.5x, so screens scrolling into view
+ *  during an in-flight gesture are already live before the debounced
+ *  ~120ms view-commit (see scheduleViewCommit) catches up and this
+ *  recomputes. */
+export const OVERVIEW_CULLING_OVERSCAN_FACTOR = 1.5;
+export type ScreenCullTier =
+  /** Full content (iframe/DesignCanvas) is mounted and rendered normally. */
+  | "visible"
+  /** Has been visible before this session; content stays mounted (iframes
+   *  never unmount — see the module doc above) but is skipped from paint via
+   *  visibility/content-visibility, not display:none or will-change. */
+  | "culled"
+  /** Has never been visible this session; renders a lightweight placeholder
+   *  with no iframe/content node at all. */
+  | "placeholder";
+/** The world-space (canvas-space) rectangle currently visible inside the
+ *  pannable surface, expanded by `overscanFactor` viewport-widths/heights in
+ *  every direction. Built from the *committed* pan/zoom state, matching the
+ *  same `translate(pan) scale(zoom/100)` transform applyViewToDom applies to
+ *  the world layer — see getOverscannedViewportCanvasBounds's callers. */
+export interface OverscannedViewportBounds {
+  left: number;
+  top: number;
+  right: number;
+  bottom: number;
+}
+/** Computes the overscanned world-space viewport rect for culling purposes.
+ *  `surfaceSize` is the pannable surface's own on-screen size (the
+ *  `surfaceRef` element's content box, in screen px); `pan`/`zoomPercent` are
+ *  the committed (not per-gesture-frame) pan/zoom values. Screens are placed
+ *  in world space with `SURFACE_PADDING` added to their raw x/y (see Screen's
+ *  wrapper style), so this returns bounds already in that same
+ *  `SURFACE_PADDING`-relative space — compare directly against
+ *  `geometry.x`/`geometry.y`-based frame bounds, no further offset needed.
+ *  Returns `null` when the surface has no measured size yet (e.g. before the
+ *  first layout pass) — callers should treat that as "cannot determine
+ *  visibility yet" and fall back to treating everything as visible. */
+export function getOverscannedViewportCanvasBounds(
+  surfaceSize: { width: number; height: number },
+  pan: Point,
+  zoomPercent: number,
+  overscanFactor: number = OVERVIEW_CULLING_OVERSCAN_FACTOR,
+): OverscannedViewportBounds | null {
+  if (surfaceSize.width <= 0 || surfaceSize.height <= 0) return null;
+  const scale = zoomPercent / 100;
+  if (!(scale > 0)) return null;
+  // Visible world-space rect: screen-space [0, surfaceSize] maps back through
+  // the world transform (`screenPoint = pan + worldPoint * scale`) to
+  // `worldPoint = (screenPoint - pan) / scale`. This mirrors
+  // screenToCanvasPoint's own inverse-transform math but is kept local here
+  // (rather than imported) since it operates on the *committed* pan/zoom
+  // React state specifically, not the live gesture pan/zoom.
+  const visibleLeft = -pan.x / scale;
+  const visibleTop = -pan.y / scale;
+  const visibleWidth = surfaceSize.width / scale;
+  const visibleHeight = surfaceSize.height / scale;
+  const overscanX = visibleWidth * overscanFactor;
+  const overscanY = visibleHeight * overscanFactor;
+  return {
+    left: visibleLeft - overscanX - SURFACE_PADDING,
+    top: visibleTop - overscanY - SURFACE_PADDING,
+    right: visibleLeft + visibleWidth + overscanX - SURFACE_PADDING,
+    bottom: visibleTop + visibleHeight + overscanY - SURFACE_PADDING,
+  };
+}
+/** True when `geometry`'s (rotation-aware) bounds intersect the overscanned
+ *  viewport rect at all — i.e. the screen is not fully outside it. Uses
+ *  `getRotatedFrameAABB` so a rotated frame's actual on-screen footprint is
+ *  tested, not its unrotated local rect. */
+export function isFrameWithinOverscannedViewport(
+  geometry: FrameGeometry,
+  viewport: OverscannedViewportBounds,
+): boolean {
+  const bounds = getRotatedFrameAABB(geometry);
+  return (
+    bounds.right >= viewport.left &&
+    bounds.left <= viewport.right &&
+    bounds.bottom >= viewport.top &&
+    bounds.top <= viewport.bottom
+  );
+}
+/**
+ * Item 4 — frame-tool/preset new-screen placement guard. A degenerate camera
+ * (corrupted/extreme pan+zoom — see item 5's camera-restore fix) makes
+ * getCanvasPoint's screen-to-world conversion blow up (dividing by a near-
+ * zero zoom scale), so a click-to-place or drag-to-draw frame gesture can
+ * compute world coordinates in the tens of thousands (observed: ±65536-ish)
+ * instead of landing near what the user actually clicked. Clamps the
+ * proposed geometry's origin to sit within `viewport` (the current
+ * OverscannedViewportBounds with overscanFactor 0, i.e. the exact visible
+ * world-rect) — centering it there when the proposed origin falls outside —
+ * so a bad camera can never fling a new screen to infinity. Only the origin
+ * is clamped (not width/height): the frame tool's own min/default size rules
+ * already bound those, and centering a same-sized frame preserves the
+ * gesture's intended dimensions.
+ */
+export function clampFrameGeometryToViewport(
+  geometry: FrameGeometry,
+  viewport: OverscannedViewportBounds | null,
+): FrameGeometry {
+  if (!viewport) return geometry;
+  const viewportWidth = viewport.right - viewport.left;
+  const viewportHeight = viewport.bottom - viewport.top;
+  if (!(viewportWidth > 0) || !(viewportHeight > 0)) return geometry;
+  const isWithin = isFrameWithinOverscannedViewport(geometry, viewport);
+  if (isWithin) return geometry;
+  return {
+    ...geometry,
+    x: viewport.left + (viewportWidth - geometry.width) / 2,
+    y: viewport.top + (viewportHeight - geometry.height) / 2,
+  };
+}
+/** Resolves the culling tier for a single screen. `alwaysVisible` covers the
+ *  mission's "always treated as visible" overrides: the active/board screen
+ *  and anything in the current selection, regardless of position — Figma
+ *  itself never culls the object you're actively editing or have selected,
+ *  and keeping these paths iframe-backed avoids any risk of interrupting
+ *  in-progress edits/bridge state on the screen the user is looking at.
+ *  `viewport` is `null` when surface size isn't known yet (initial layout) —
+ *  treated as visible so nothing is incorrectly culled before we can measure.
+ *  `hasBeenVisible` should reflect whether this screen id has *ever* been
+ *  visible this session (see the hasBeenVisibleRef Set in MultiScreenCanvas):
+ *  once true, a screen can only be "visible" or "culled", never regress to
+ *  "placeholder". */
+export function computeScreenCullTier({
+  geometry,
+  viewport,
+  alwaysVisible,
+  hasBeenVisible,
+}: {
+  geometry: FrameGeometry;
+  viewport: OverscannedViewportBounds | null;
+  alwaysVisible: boolean;
+  hasBeenVisible: boolean;
+}): ScreenCullTier {
+  if (!OVERVIEW_CULLING_ENABLED) return "visible";
+  const isWithinViewport =
+    alwaysVisible ||
+    !viewport ||
+    isFrameWithinOverscannedViewport(geometry, viewport);
+  if (isWithinViewport) return "visible";
+  return hasBeenVisible ? "culled" : "placeholder";
+}