@agent-native/core 0.90.1 → 0.90.2

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

@@ -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

@@ -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";
+}

package/corpus/templates/design/app/components/design/multi-screen/gradient-overlay-geometry.ts

@@ -0,0 +1,120 @@
+import type { GradientLinePoint, Point } from "./types";
+
+/**
+ * The CSS `linear-gradient()` line-length formula (CSS Images ¤3
+ * §linear-gradient-syntax): for a box of `width` x `height` and an angle
+ * measured clockwise from "up" (matching both this app's `GradientValue`
+ * angle convention and the CSS `<angle>` syntax `linear-gradient(Ndeg, ...)`
+ * already produces), the gradient line's half-length from the box center is
+ * `|width/2 * sin(angle)| + |height/2 * cos(angle)|` — the projection of the
+ * box's half-diagonal onto the gradient axis, so the line exactly spans the
+ * box from edge to edge (touching whichever corner is furthest along the
+ * axis) the same way a browser renders it.
+ */
+export function gradientLineEndpoints(
+  angleDeg: number,
+  width: number,
+  height: number,
+): { start: Point; end: Point } {
+  const rad = (angleDeg * Math.PI) / 180;
+  // Unit vector pointing from the gradient's start toward its end (0deg = up
+  // = -y, clockwise), matching AngleDial's "0 is north, clockwise" mapping.
+  const dx = Math.sin(rad);
+  const dy = -Math.cos(rad);
+  const halfLength = Math.abs((width / 2) * dx) + Math.abs((height / 2) * dy);
+  const center = { x: width / 2, y: height / 2 };
+  return {
+    start: { x: center.x - dx * halfLength, y: center.y - dy * halfLength },
+    end: { x: center.x + dx * halfLength, y: center.y + dy * halfLength },
+  };
+}
+
+/** Projects each stop's 0–100 `position` onto the gradient line's start/end
+ *  points (linear interpolation), for rendering a round marker per stop. */
+export function gradientStopPoints(
+  angleDeg: number,
+  width: number,
+  height: number,
+  stops: ReadonlyArray<{ position: number }>,
+): GradientLinePoint[] {
+  const { start, end } = gradientLineEndpoints(angleDeg, width, height);
+  return stops.map((stop) => {
+    const t = clampGradientT(stop.position / 100);
+    return {
+      x: start.x + (end.x - start.x) * t,
+      y: start.y + (end.y - start.y) * t,
+      position: stop.position,
+    };
+  });
+}
+
+function clampGradientT(t: number): number {
+  if (!Number.isFinite(t)) return 0;
+  return Math.max(0, Math.min(1, t));
+}
+
+/**
+ * Inverts a dragged endpoint handle back into an angle: given the box center
+ * and the new local point for whichever endpoint is being dragged (`which`),
+ * returns the angle (0-360, "up"-is-0 clockwise) whose gradient line passes
+ * through that point. Dragging the "start" handle points the axis the
+ * opposite way (the start is the *far* end of the line from that point's
+ * direction), so it adds 180° after resolving the raw pointer angle.
+ */
+export function angleFromDraggedEndpoint(
+  point: Point,
+  width: number,
+  height: number,
+  which: "start" | "end",
+): number {
+  const center = { x: width / 2, y: height / 2 };
+  const dx = point.x - center.x;
+  const dy = point.y - center.y;
+  if (dx === 0 && dy === 0) return 0;
+  // atan2 gives angle from east (+x), clockwise-positive in screen space
+  // (y-down); convert to this app's "0 is north, clockwise" convention by
+  // rotating the reference axis by +90deg, matching AngleDial's own mapping.
+  let deg = (Math.atan2(dy, dx) * 180) / Math.PI + 90;
+  if (which === "start") deg += 180;
+  deg = ((deg % 360) + 360) % 360;
+  return deg;
+}
+
+/**
+ * Inverts a dragged stop marker back into a 0–100 position: projects the
+ * dragged local point onto the (unbounded) gradient line through the box
+ * center at `angleDeg`, using the *current* line's start/end as the 0/100
+ * reference frame, then clamps to [0, 100]. This mirrors
+ * `GradientEditor`'s own `positionFromPointer`, which likewise projects the
+ * pointer onto the ramp bar's axis and clamps rather than rejecting
+ * off-axis drags — on canvas the equivalent "axis" is the gradient line
+ * itself, so a drag that strays perpendicular to the line still tracks the
+ * nearest point on it instead of doing nothing.
+ */
+export function stopPercentFromDraggedPoint(
+  point: Point,
+  angleDeg: number,
+  width: number,
+  height: number,
+): number {
+  const { start, end } = gradientLineEndpoints(angleDeg, width, height);
+  const lineDx = end.x - start.x;
+  const lineDy = end.y - start.y;
+  const lengthSquared = lineDx * lineDx + lineDy * lineDy;
+  if (lengthSquared === 0) return 0;
+  const t =
+    ((point.x - start.x) * lineDx + (point.y - start.y) * lineDy) /
+    lengthSquared;
+  return clampGradientT(t) * 100;
+}
+
+/** Converts a constant on-screen pixel radius (e.g. a hit-test tolerance
+ *  that should feel the same size regardless of zoom) into canvas px, the
+ *  space hitTestPenAnchor/hitTestPenHandle and PenPath geometry operate in.
+ *  `zoom` is the same 0-based-at-100 percentage used throughout this file
+ *  (100 = 1:1). Mirrors the `screenPx / (zoom / 100)` conversion already
+ *  used by the pen tool's close-hit-target radius. */
+export function screenPxToCanvasPx(screenPx: number, zoom: number): number {
+  const scale = zoom / 100;
+  return scale > 0 ? screenPx / scale : screenPx;
+}