@dailies-studio/shot-editor 0.1.0

package/src/stage/isolation.ts

@@ -0,0 +1,155 @@
+// Looking at one subtree, straight on.
+//
+// Isolation is an editor MODE, not a document state: nothing here is ever
+// written to a Doc3D and nothing reaches an export. What it needs is a camera
+// pose, and that pose is derived from the subtree itself rather than orbited to
+// by hand — "enter this card and see it flat" has exactly one right answer.
+//
+// ── WHY NOT THE WORKING CAMERA ───────────────────────────────────────────
+//
+// The working pane's camera is a spherical orbit rig: its `up` is reset to
+// world +y every frame (so it cannot roll) and its polar angle is clamped off
+// both poles (so it cannot look straight down). A card rolled 30 degrees and a
+// card lying flat are both perfectly ordinary, and neither can be framed by
+// that rig. So the pose is built here from the subtree's own basis instead.
+//
+// ── AND WHY ORTHOGRAPHIC ─────────────────────────────────────────────────
+//
+// Editing flat means no foreshortening: two children the same size have to
+// measure the same on screen, and a nudge has to move the same number of pixels
+// wherever it lands. A perspective camera at a derived distance is 1:1 only on
+// the plane it was derived for — which is the plane the subtree's ROOT sits in,
+// not the plane its children sit in once any of them has a z.
+//
+// The frustum is sized from the subtree's own bounds, measured in the ROOT's
+// frame, so entering a subtree frames it whatever the scene camera was doing.
+import { toLocal, worldStateAt } from "@dailies-studio/shot/doc";
+import type { Mat3, Scene3D, Vec3 } from "@dailies-studio/shot/doc";
+import type { Rational } from "@dailies-studio/engine";
+
+/** How much of the pane is margin around the framed subtree, per side. */
+export const ISOLATION_MARGIN = 0.12;
+
+/** A subtree with no extent still needs a frustum — a single zero-size layer is
+ *  a real document, and a zero-width ortho camera projects everything to NaN. */
+const MIN_HALF_EXTENT = 1;
+
+export interface IsolationFrame {
+  /** Where to look, in THREE world space. */
+  target: Vec3;
+  /** The subtree's own basis: column 2 is its normal, column 1 its up. */
+  rotation: Mat3;
+  /** Half-extents of the subtree's bounds IN ITS OWN FRAME, design px. */
+  halfWidth: number;
+  halfHeight: number;
+  /** Half-depth, for near/far. A flat subtree still gets a usable slab. */
+  halfDepth: number;
+}
+
+/**
+ * The pose and extent that frame `rootId`'s subtree head-on at a frame.
+ *
+ * The RESOLVED chain, not the authored one: an author entering a card whose
+ * parent is mid-rotation is looking at where it is now. Returns null when the
+ * layer is not in this scene, which is what "the isolation went stale" looks
+ * like from here.
+ */
+export function isolationFrame(
+  scene: Scene3D,
+  rootId: string,
+  subtree: ReadonlySet<string>,
+  sceneFrame: number,
+  fps: Rational,
+): IsolationFrame | null {
+  const root = scene.layersById[rootId];
+  if (root === undefined) return null;
+  const rootPose = worldStateAt(scene, rootId, sceneFrame, fps);
+
+  let minX = Infinity;
+  let maxX = -Infinity;
+  let minY = Infinity;
+  let maxY = -Infinity;
+  let minZ = Infinity;
+  let maxZ = -Infinity;
+  for (const id of subtree) {
+    const layer = scene.layersById[id];
+    if (layer === undefined) continue;
+    // Each member's centre in the ROOT's frame, with its own axis-aligned box
+    // around it. The box ignores the member's own tilt and roll, the same
+    // simplification `groupLayers` makes for the same reason: a rotation-aware
+    // hull would frame a rolled child looser than the box the author sees.
+    const local = toLocal(rootPose, worldStateAt(scene, id, sceneFrame, fps));
+    const [w, h] = layer.transform.size;
+    minX = Math.min(minX, local.position[0] - w / 2);
+    maxX = Math.max(maxX, local.position[0] + w / 2);
+    minY = Math.min(minY, local.position[1] - h / 2);
+    maxY = Math.max(maxY, local.position[1] + h / 2);
+    minZ = Math.min(minZ, local.position[2]);
+    maxZ = Math.max(maxZ, local.position[2]);
+  }
+  if (!Number.isFinite(minX)) return null;
+
+  // The bounds' CENTRE, not the root's origin: a group whose children all sit
+  // to one side would otherwise be framed off-centre, which is the state the
+  // grouping arithmetic exists to make impossible to author but which a
+  // hand-written document can still hold.
+  const centre: Vec3 = [(minX + maxX) / 2, (minY + maxY) / 2, (minZ + maxZ) / 2];
+  const world = worldOf(rootPose, centre);
+
+  return {
+    target: world,
+    rotation: rootPose.rotation,
+    halfWidth: Math.max(MIN_HALF_EXTENT, (maxX - minX) / 2),
+    halfHeight: Math.max(MIN_HALF_EXTENT, (maxY - minY) / 2),
+    halfDepth: Math.max(MIN_HALF_EXTENT, (maxZ - minZ) / 2),
+  };
+}
+
+/** A point in the root's DESIGN frame, out in three world space. Design +y is
+ *  down and +z is away, so both flip on the way through the one mapping. */
+function worldOf(pose: { position: Vec3; rotation: Mat3 }, local: Vec3): Vec3 {
+  const d: Vec3 = [local[0], -local[1], -local[2]];
+  return [
+    pose.position[0] + pose.rotation[0][0] * d[0] + pose.rotation[0][1] * d[1] + pose.rotation[0][2] * d[2],
+    pose.position[1] + pose.rotation[1][0] * d[0] + pose.rotation[1][1] * d[1] + pose.rotation[1][2] * d[2],
+    pose.position[2] + pose.rotation[2][0] * d[0] + pose.rotation[2][1] * d[1] + pose.rotation[2][2] * d[2],
+  ];
+}
+
+/**
+ * The orthographic half-extents that show the whole subtree in a pane of this
+ * aspect, with a margin.
+ *
+ * Both axes take the SAME scale — the larger of the two requirements — because
+ * an ortho camera with different x and y scales is a squashed picture, and the
+ * point of isolation is that a square measures square.
+ */
+export function isolationExtent(
+  frame: IsolationFrame,
+  aspect: number,
+): { halfWidth: number; halfHeight: number } {
+  const safe = Number.isFinite(aspect) && aspect > 0 ? aspect : 1;
+  const grow = 1 / (1 - 2 * ISOLATION_MARGIN);
+  const halfHeight = Math.max(frame.halfHeight, frame.halfWidth / safe) * grow;
+  return { halfWidth: halfHeight * safe, halfHeight };
+}
+
+/** Camera eye for an isolation frame: back along the subtree's own normal, far
+ *  enough that the ortho slab clears the deepest member either way. */
+export function isolationEye(frame: IsolationFrame): { eye: Vec3; up: Vec3; far: number } {
+  const normal: Vec3 = [frame.rotation[0][2], frame.rotation[1][2], frame.rotation[2][2]];
+  const up: Vec3 = [frame.rotation[0][1], frame.rotation[1][1], frame.rotation[2][1]];
+  // Distance is arbitrary for an orthographic projection, so it is chosen for
+  // the CLIP planes: far enough that nothing in the subtree is behind the eye,
+  // near enough that the depth range stays a sane number.
+  const back = frame.halfDepth * 4 + 1000;
+  return {
+    eye: [
+      frame.target[0] + normal[0] * back,
+      frame.target[1] + normal[1] * back,
+      frame.target[2] + normal[2] * back,
+    ],
+    up,
+    far: back * 2 + frame.halfDepth * 4,
+  };
+}

package/src/stage/main.tsx

@@ -0,0 +1,110 @@
+// Stage entry — served ONLY through the project's Vite (/shot-stage.html +
+// /@fs, package.json "./stage" export) so the three stack resolves to the
+// STUDIO's pinned copies and the project's asset route is same-origin; never
+// bundled into the chrome dist.
+//
+// INSTALL-BEFORE-PAINT (the canvas stage's posture): the chrome polls
+// `iframe.contentWindow.__shotStudio` on load and must never observe a
+// rendered-but-bridgeless stage, so the handle installs SYNCHRONOUSLY in
+// `boot()`. StageApp itself renders on the chrome's `connect()` — there is
+// nothing worth painting before a chrome exists, and the document arrives
+// immediately after.
+import { createRoot } from "react-dom/client";
+import { StageAssetsContext, StudioSurfaceContext } from "@dailies-studio/runtime";
+import type { StageAssetResolver } from "@dailies-studio/runtime";
+// The stage is its OWN document and inherits nothing from the chrome's
+// stylesheet, so it adopts the design tokens by importing them. tokens.css and
+// NOT styles.css: the palette is inert until referenced, while the widget rules
+// and the global box-sizing reset would repaint the author's own content
+// differently here than in the export — which is exactly the preview != runtime
+// split this whole lane refuses.
+import "@dailies-studio/ui/tokens.css";
+// Then THIS LANE's palette on top, because the overlays drawn over the stage
+// read --accent, --guide and --frame-border, and the house values are not the
+// ones the chrome around them is using. Without it the selection quad and the
+// tilt handles paint in the house rose while every control beside them is
+// blue — the overlays were never wrong, they were reading a token nobody had
+// overridden for this document. Same file the chrome imports; one definition.
+import "../shotTokens.css";
+import { createStageClient } from "./bridgeClient.js";
+import { StageApp } from "./StageApp.js";
+
+// WITHOUT THIS PROVIDER, IMAGE AND VIDEO LAYERS ARE BLANK. `useStageAssetResolver`
+// falls back to the bare content-addressed filename, which resolves against
+// /shot-stage.html and 404s — the dev server serves the asset store only at
+// /studio/assets/ (same origin here, since this iframe rides the project's
+// Vite). The harness hit this exact failure class before us; mirror its
+// resolver (cli/src/harnessRuntime.ts).
+const stageAssets: StageAssetResolver = (storePath) =>
+  "/studio/assets/" + encodeURIComponent(storePath);
+
+export function boot(): void {
+  if (window.__shotStudio) {
+    console.warn("[shot-editor stage] boot() called twice — ignoring");
+    return;
+  }
+  document.documentElement.style.height = "100%";
+  document.body.style.cssText = "margin:0;height:100%;overflow:hidden;background:#000";
+  const container = document.createElement("div");
+  container.style.cssText = "position:fixed;inset:0";
+  document.body.appendChild(container);
+
+  const client = createStageClient();
+  // Install BEFORE first paint, and before a render is even scheduled.
+  window.__shotStudio = client.bridge;
+
+  const root = createRoot(container);
+  client.setDisposer(() => {
+    root.unmount();
+    container.remove();
+    delete window.__shotStudio;
+  });
+
+  // First render on connect: `connect()` flips `connected`, so subscribing
+  // catches it whether the chrome connects on the next poll tick or already
+  // did between install and subscribe.
+  let rendered = false;
+  const renderOnConnect = (): void => {
+    if (rendered || !client.getState().connected) return;
+    rendered = true;
+    unsubscribe();
+    // THE STUDIO-SURFACE MARKER, on the ROOT and never on a branch (the
+    // harness's posture). This stage mounts the shot runtime with an explicit
+    // frame and no wall clock; anything that reads "no ambient clock" as "a
+    // real page" and arms an animation would be animating under the selection
+    // handles while a gesture reads live geometry off a moving target.
+    root.render(
+      <StudioSurfaceContext.Provider value={true}>
+        <StageAssetsContext.Provider value={stageAssets}>
+          <StageApp client={client} />
+        </StageAssetsContext.Provider>
+      </StudioSurfaceContext.Provider>,
+    );
+  };
+  const unsubscribe = client.subscribe(renderOnConnect);
+  renderOnConnect();
+  forwardShotDocChanged();
+}
+
+/**
+ * The server's "this shot changed under you" push, RELAYED to the chrome.
+ *
+ * THIS IFRAME IS THE ONLY HALF WITH AN HMR CLIENT. The server pushes over the
+ * Vite WS, but the chrome is served as a PREBUILT STATIC bundle from dist/ —
+ * Vite strips its `import.meta.hot` branch at build time, so a listener there
+ * would be dead in every shipped build. The stage is served through the
+ * project's Vite and has a live client, so it forwards: same-origin
+ * postMessage to the parent, which the chrome turns back into the event its
+ * handler already takes. Exactly the relay the canvas stage performs.
+ */
+function forwardShotDocChanged(): void {
+  const hot = typeof import.meta.hot?.on === "function" ? import.meta.hot : null;
+  if (hot === null || window.parent === window) return;
+  hot.on("studio:shot-doc-changed", (data: unknown) => {
+    try {
+      window.parent.postMessage({ type: "studio:shot-doc-changed", data }, location.origin);
+    } catch {
+      // A relay must never take the stage down.
+    }
+  });
+}