@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/storyboard/ComponentStage.tsx

@@ -0,0 +1,235 @@
+// THE ONE LIVE COMPONENT PREVIEW: the inspector lead of a selected component
+// card, drawn by the SHOT STAGE, framed exactly as a Shot frames it.
+//
+// The stage itself (the second `/shot-stage.html`, the hosted epoch, the
+// loop, the live budget and the poster) is `StagePreview`. This file builds
+// the ONE-INSTANCE document it draws: the Project's size, fps and assets, one
+// Shot, one instance layer the size of the frame. Nothing is saved.
+//
+// LOOPING, OR THE CARD'S FRAME. The preview loops over the component's length,
+// at the Project's fps. A card that names a frame (the inspector's Frame row)
+// shows that frame and holds it.
+//
+// IN BUDGET BY THE CARD'S ID, so a card that already holds that slot shares it
+// rather than taking a second, and the poster is keyed by the component, its
+// content hash and the card's props (posterCache.ts).
+//
+// A CODE COMPONENT OR A STUDIO DEFINITION. A card naming `def` draws a slim
+// document of that definition's closure (`defClosureOf`), placed once with
+// the card's props as its overrides, so an edit elsewhere in the Project
+// never reloads the preview.
+import { useMemo, useState } from "react";
+import type { ReactNode } from "react";
+import { canonicalJSON, fnv1a64 } from "@dailies-studio/contract";
+import type { Contract, EmbedContractRef } from "@dailies-studio/contract";
+import {
+  addComponentInstance,
+  componentPreviewDoc,
+  defClosureOf,
+  defDurationFrames,
+  previewBaseDoc,
+  previewBindingOf,
+} from "@dailies-studio/shot/doc";
+import type { DefClosure, Doc3D, ReferenceItem3D } from "@dailies-studio/shot/doc";
+import { brandBackdrop } from "../../bridgeTypes.js";
+import type { ShotComponentBackground } from "../../bridgeTypes.js";
+import { posterKey } from "./posterCache.js";
+import { StagePreview } from "./StagePreview.js";
+
+type ComponentCard = Extract<ReferenceItem3D, { type: "component" }>;
+
+/** How long a preview loops when the catalog names no length: two seconds. */
+export const DEFAULT_LOOP_SECONDS = 2;
+
+/**
+ * The one-instance document the preview stage draws. Pure, so the suite pins
+ * it without a stage.
+ *
+ * The CARD'S RAW PROPS, never harness-resolved paths: the stage maps an
+ * asset-kind value through `doc.assets` itself, so the Project's asset table
+ * rides along. The contract rides as the binding an instance layer would get
+ * (`contractBinding`), because without one the stage spreads raw contract
+ * keys as React prop names.
+ */
+export function cardStageDoc(
+  doc: Pick<Doc3D, "size" | "fps" | "assets">,
+  item: ComponentCard,
+  binding: EmbedContractRef | undefined,
+  lengthFrames: number,
+  backdrop?: string,
+): Doc3D {
+  // The shot package's builder, which `preview_component` draws too.
+  return componentPreviewDoc(
+    doc,
+    { component: item.component ?? "", label: item.label, props: item.props, binding },
+    lengthFrames,
+    backdrop,
+  );
+}
+
+/**
+ * The one-instance document for a STUDIO DEFINITION's card: the closure's
+ * definitions, assets and material graphs, one placement of the definition at
+ * 1:1 in the middle of the Project's frame, the card's props as its
+ * overrides. Pure, like `cardStageDoc`. Null when the placement is refused.
+ */
+export function defStageDoc(
+  doc: Pick<Doc3D, "size" | "fps">,
+  closure: DefClosure,
+  props: ComponentCard["props"],
+  lengthFrames: number,
+  backdrop?: string,
+): Doc3D | null {
+  const { sized, sceneId } = previewBaseDoc({ size: doc.size, fps: doc.fps, assets: closure.assets }, lengthFrames, backdrop);
+  const withDefs: Doc3D = {
+    ...sized,
+    components: { ...closure.nested, [closure.def.id]: closure.def },
+    ...(Object.keys(closure.materials).length === 0 ? {} : { materials: closure.materials }),
+  };
+  const placed = addComponentInstance(withDefs, sceneId, closure.def.id);
+  if (placed.instanceId === null) return null;
+  const scene = placed.doc.scenesById[sceneId]!;
+  const layer = scene.layersById[placed.instanceId];
+  if (layer?.kind !== "component") return null;
+  return {
+    ...placed.doc,
+    scenesById: {
+      ...placed.doc.scenesById,
+      [sceneId]: {
+        ...scene,
+        layersById: { ...scene.layersById, [layer.id]: { ...layer, component: { ...layer.component, overrides: props } } },
+      },
+    },
+  };
+}
+
+/** A closure's content as a hash: what the poster key and the stage document
+ *  follow, so an unrelated edit leaves both alone. */
+export function closureHash(closure: DefClosure | null): string {
+  if (closure === null) return "none";
+  try {
+    return fnv1a64(canonicalJSON(closure));
+  } catch {
+    return fnv1a64(JSON.stringify(closure));
+  }
+}
+
+/** Closures and their hashes, per document revision: a doc is immutable, so
+ *  every card and the sheet that render one revision walk and hash each
+ *  definition once, and the revision's entries go with it. */
+const closures = new WeakMap<Doc3D, Map<string, { closure: DefClosure | null; hash: string }>>();
+
+/** `defClosureOf` and its `closureHash`, memoized per document revision. */
+export function closureFor(doc: Doc3D, defId: string): { closure: DefClosure | null; hash: string } {
+  let byDef = closures.get(doc);
+  if (byDef === undefined) {
+    byDef = new Map();
+    closures.set(doc, byDef);
+  }
+  let hit = byDef.get(defId);
+  if (hit === undefined) {
+    const closure = defClosureOf(doc, defId);
+    hit = { closure, hash: closureHash(closure) };
+    byDef.set(defId, hit);
+  }
+  return hit;
+}
+
+/** `value` as it was the last time `key` changed: derived state held across
+ *  renders the React way (a set during render). */
+function useStableBy<T>(value: T, key: string): T {
+  const [held, setHeld] = useState({ key, value });
+  if (held.key !== key) {
+    setHeld({ key, value });
+    return value;
+  }
+  return held.value;
+}
+
+/**
+ * The preview's ground as a colour (bridge v45): dark is the desk token,
+ * light the paper token, brand the Project's first brand colour or else dark.
+ * Read off the chrome's own tokens, since the card document is a plain Shot.
+ */
+export function cardBackdrop(background: ShotComponentBackground, doc: Pick<Doc3D, "resources"> | null): string {
+  const token = (name: string, fallback: string): string =>
+    typeof document === "undefined"
+      ? fallback
+      : getComputedStyle(document.documentElement).getPropertyValue(name).trim() || fallback;
+  const desk = token("--surface-sunken", "#080808");
+  if (background === "light") return token("--paper-97", "#f5f5f8");
+  if (background === "brand") return brandBackdrop(doc) ?? desk;
+  return desk;
+}
+
+/**
+ * THE BINDING A PLACED INSTANCE WOULD CARRY, `store.bindingFor`'s rule: the
+ * server's availability decides import or snapshot. Null when there is no
+ * contract, or when it cannot be frozen (a snapshot refuses a contract whose
+ * hashes do not describe its keys): the preview then draws with raw props
+ * rather than throwing inside a render and taking the inspector down.
+ */
+export function contractBinding(
+  contract: Contract | undefined,
+  availability: "sibling" | "colocated" | "inferred" | undefined,
+): EmbedContractRef | undefined {
+  return contract === undefined ? undefined : previewBindingOf({ availability: availability ?? "inferred", contract });
+}
+
+export function ComponentStage(props: {
+  doc: Doc3D;
+  item: ComponentCard;
+  contract: Contract | undefined;
+  /** The registry row's verdict: import the contract, or freeze it. */
+  availability: "sibling" | "colocated" | "inferred" | undefined;
+  /** The shipped item's length, when the catalog says; else two seconds. */
+  lengthFrames: number | undefined;
+  /** The ground behind the component (bridge v45). Omitted keeps the Shot's. */
+  background?: ShotComponentBackground;
+  /** Loops over this many frames instead of the component's length. */
+  loopFrames?: number;
+  /** Whether the stage may go live. False shows the poster (default true). */
+  live?: boolean;
+  /** What shows while the stage is not live and no poster is cached yet. */
+  fallback?: ReactNode;
+}) {
+  const { doc, item, contract, availability } = props;
+  const fps = doc.fps.num / doc.fps.den;
+  // A STUDIO DEFINITION'S closure, held while its content is the same.
+  const defId = item.component === undefined ? item.def : undefined;
+  const own = defId === undefined ? null : closureFor(doc, defId);
+  const freshClosure = own?.closure ?? null;
+  const contentHash = own === null ? (contract?.contractHash ?? item.contractHash ?? "none") : own.hash;
+  const closure = useStableBy(freshClosure, contentHash);
+  const ownLength = closure === null ? props.lengthFrames : defDurationFrames(closure.def);
+  const length = Math.max(1, Math.round(props.loopFrames ?? ownLength ?? DEFAULT_LOOP_SECONDS * fps));
+  const backdrop = props.background === undefined ? undefined : cardBackdrop(props.background, doc);
+  const binding = useMemo(() => contractBinding(contract, availability), [contract, availability]);
+  // KEYED ON WHAT THE CARD DOCUMENT READS, never on `doc` itself: every edit
+  // anywhere in the Project is a new `doc`, and a new stage document reloads
+  // the preview.
+  const { width, height } = doc.size;
+  const { num, den } = doc.fps;
+  const assets = doc.assets;
+  const stageDoc = useMemo(
+    () =>
+      closure !== null
+        ? defStageDoc({ size: { width, height }, fps: { num, den } }, closure, item.props, length, backdrop)
+        : cardStageDoc({ size: { width, height }, fps: { num, den }, assets }, item, binding, length, backdrop),
+    [width, height, num, den, assets, item, closure, binding, length, backdrop],
+  );
+  const size = useMemo(() => ({ width, height }), [width, height]);
+  return (
+    <StagePreview
+      doc={stageDoc}
+      size={size}
+      lengthFrames={length}
+      {...(item.frame === undefined ? {} : { frame: item.frame })}
+      {...(props.live === undefined ? {} : { live: props.live })}
+      slotKey={item.id}
+      posterKey={posterKey(item.component ?? item.def ?? item.id, contentHash, item.props)}
+      title={`Preview of ${item.label}`}
+      fallback={props.fallback}
+    />
+  );
+}

package/src/panels/storyboard/MiniSketch.tsx

@@ -0,0 +1,173 @@
+// A SKETCH, SMALL (Paper SB1 card pictures, SB2 strip thumbs, the Brief's
+// thumbs): the board's shot cards and any thumbnail of a sketch. It only
+// draws: no selection, no handles, no pointer.
+//
+// THE STAGE'S PICTURE FIRST. Its caller passes `picture`, the sketch as the
+// still stage draws it (state/stillThumbs.ts, `useSketchThumbs`: brand font,
+// components and all, the same picture the agent's screenshot_shot
+// `{sketch}` returns). Once it is ready it fills the box. Until then, and when
+// it failed, the sketch is drawn in the DOM, below.
+//
+// ONE BOX, ANY WIDTH. Items sit in percentages of the Project's size (layer
+// units: design px, origin at the centre, +y down), and type sizes in `cqw`
+// of the box, so the same markup is right at 128 or at 346 wide and nothing
+// measures. Back to front, as stored: a later item draws on top.
+//
+//   ref     an image card's picture (`useImageThumb`), a video's poster, a
+//           component's name tile, or "Missing" for a card that is gone
+//   text    the words at their role's size (`SKETCH_TEXT_SIZE`)
+//   box     the light sketch fill with its edge, dark, or the accent; the
+//           label in its corner
+//   arrow   one SVG line with an open head, its label over the head
+import type { CSSProperties } from "react";
+import { SKETCH_TEXT_SIZE, sketchCardOf } from "@dailies-studio/shot/doc";
+import type { Doc3D, SketchItem3D, SketchRef3D, StoryboardSketch3D } from "@dailies-studio/shot/doc";
+import { useImageThumb } from "../../state/imageThumbs.js";
+import type { StillThumb } from "../../state/stillThumbs.js";
+import { MediaPoster } from "./ReferencePreview.js";
+
+const assetUrl = (path: string): string => `/studio/assets/${encodeURIComponent(path)}`;
+
+/** A box label's size, design px: the stage's label size (sketch.ts). */
+const LABEL_SIZE = 24;
+/** The open head's arm, design px. */
+const ARROW_HEAD = 36;
+
+export function MiniSketch(props: {
+  doc: Doc3D;
+  sketch: StoryboardSketch3D;
+  /** The longest side the pictures inside are fetched for, CSS px. */
+  width: number;
+  className?: string;
+  /** The sketch as the still stage draws it; shown once ready. */
+  picture?: StillThumb | null;
+}) {
+  const { doc, sketch } = props;
+  const { width: w, height: h } = doc.size;
+  const arrows = sketch.items.filter((item) => item.kind === "arrow");
+  const box = {
+    className: `mini-sketch${props.className === undefined ? "" : ` ${props.className}`}`,
+    "data-ground": sketch.ground ?? "paper",
+    "data-testid": "mini-sketch",
+    style: { aspectRatio: `${w} / ${h}` },
+    "aria-hidden": true,
+  } as const;
+  if (props.picture?.status === "ready") {
+    return (
+      <div {...box} data-picture="stage">
+        <img className="mini-sketch-picture" src={props.picture.url} alt="" draggable={false} />
+      </div>
+    );
+  }
+  return (
+    <div {...box} data-picture="dom">
+      {sketch.items.map((item) =>
+        item.kind === "arrow" ? null : <MiniItem key={item.id} doc={doc} item={item} width={props.width} />,
+      )}
+      {arrows.length === 0 ? null : (
+        <svg className="mini-sketch-arrows" viewBox={`${-w / 2} ${-h / 2} ${w} ${h}`} preserveAspectRatio="none">
+          {arrows.map((item) => (item.kind === "arrow" ? <path key={item.id} d={arrowPath(item.from, item.to)} /> : null))}
+        </svg>
+      )}
+      {arrows.map((item) =>
+        item.kind !== "arrow" || item.label === undefined ? null : (
+          <span key={`${item.id}-label`} className="mini-sketch-label is-arrow" style={labelAt(doc, item.to)}>
+            {item.label}
+          </span>
+        ),
+      )}
+    </div>
+  );
+}
+
+/** The arrow's line and its open head, in design px. */
+export function arrowPath(from: readonly [number, number], to: readonly [number, number]): string {
+  const angle = Math.atan2(to[1] - from[1], to[0] - from[0]);
+  const arm = (turn: number): string =>
+    `${to[0] - ARROW_HEAD * Math.cos(angle + turn)} ${to[1] - ARROW_HEAD * Math.sin(angle + turn)}`;
+  return `M ${from[0]} ${from[1]} L ${to[0]} ${to[1]} M ${arm(Math.PI / 6)} L ${to[0]} ${to[1]} L ${arm(-Math.PI / 6)}`;
+}
+
+/** An item's box as percentages of the sketch: position is its centre. */
+export function boxStyle(doc: Doc3D, position: readonly [number, number], size: readonly [number, number]): CSSProperties {
+  const { width: w, height: h } = doc.size;
+  return {
+    left: `${((position[0] - size[0] / 2) / w + 0.5) * 100}%`,
+    top: `${((position[1] - size[1] / 2) / h + 0.5) * 100}%`,
+    width: `${(size[0] / w) * 100}%`,
+    height: `${(size[1] / h) * 100}%`,
+  };
+}
+
+/** Type of `px` design px, as a share of the box's width. */
+const typeSize = (doc: Doc3D, px: number): string => `${(px / doc.size.width) * 100}cqw`;
+
+/** An arrow's label, centred over its head. */
+const labelAt = (doc: Doc3D, to: readonly [number, number]): CSSProperties => ({
+  left: `${(to[0] / doc.size.width + 0.5) * 100}%`,
+  top: `${((to[1] - 40) / doc.size.height + 0.5) * 100}%`,
+  fontSize: typeSize(doc, LABEL_SIZE),
+});
+
+function MiniItem({ doc, item, width }: { doc: Doc3D; item: Exclude<SketchItem3D, { kind: "arrow" }>; width: number }) {
+  const box = boxStyle(doc, item.position, item.size);
+  if (item.kind === "text") {
+    return (
+      <span
+        className={`mini-sketch-text is-${item.role}`}
+        data-align={item.align ?? "start"}
+        style={{ ...box, fontSize: typeSize(doc, SKETCH_TEXT_SIZE[item.role]) }}
+      >
+        {item.text}
+      </span>
+    );
+  }
+  if (item.kind === "box") {
+    return (
+      <span className="mini-sketch-box" data-tone={item.tone ?? "light"} style={box}>
+        {item.label === undefined ? null : (
+          <span className="mini-sketch-label" style={{ fontSize: typeSize(doc, LABEL_SIZE) }}>
+            {item.label}
+          </span>
+        )}
+      </span>
+    );
+  }
+  return <MiniRef doc={doc} item={item} style={box} px={(item.size[0] / doc.size.width) * width} />;
+}
+
+function MiniRef({ doc, item, style, px }: { doc: Doc3D; item: SketchRef3D; style: CSSProperties; px: number }) {
+  const card = sketchCardOf(doc, item);
+  const asset = card?.type === "asset" ? doc.assets[card.asset] : undefined;
+  const image = asset?.kind === "image" ? asset : undefined;
+  const thumb = useImageThumb(image === undefined ? "" : assetUrl(image.path), image?.hash ?? "", px);
+  const fit = item.fit ?? "cover";
+  if (image !== undefined) {
+    return (
+      <span className="mini-sketch-ref" style={style}>
+        {thumb === null ? null : <img src={thumb} alt="" draggable={false} style={{ objectFit: fit }} />}
+      </span>
+    );
+  }
+  if (asset?.kind === "video" && card?.type === "asset") {
+    const at = card.frame === undefined ? null : (card.frame * doc.fps.den) / doc.fps.num;
+    return (
+      <span className="mini-sketch-ref" style={style}>
+        <MediaPoster className="mini-sketch-media" src={assetUrl(asset.path)} atSeconds={at} />
+      </span>
+    );
+  }
+  const name =
+    card === undefined
+      ? "Missing"
+      : card.type === "component"
+        ? ((card.def === undefined ? undefined : doc.components?.[card.def]?.name) ?? card.label)
+        : card.label;
+  return (
+    <span className={`mini-sketch-ref is-tile${card === undefined ? " is-missing" : ""}`} style={style}>
+      <span className="mini-sketch-label" style={{ fontSize: typeSize(doc, LABEL_SIZE) }}>
+        {name}
+      </span>
+    </span>
+  );
+}

package/src/panels/storyboard/PartPicker.tsx

@@ -0,0 +1,64 @@
+// ATTACHED TO WHICH PART: the one control a Group, a card and the card's own
+// chip on the canvas all need, in one place.
+//
+// A COMBOBOX, by the house line written at `scene/TransitionSection.tsx`: four
+// options or fewer is a segmented control, a list that grows wants the filter
+// box. Parts are author-created and unbounded, and their labels are unbounded
+// prose in a 252px row.
+//
+// It replaced `<select className="insp-select">`, and that class matched NO
+// rule anywhere in the repo, so the element fell back to user-agent styling
+// with three visible consequences: the OS dropdown arrow instead of the
+// painted chevron (`.select { appearance: none }`), no `max-width: 100%`, and
+// no `min-width: 0` from the in-pill flattener. A native select's automatic
+// minimum size is its longest option, so one long part label pushed the whole
+// inspector into a horizontal scrollbar. The comment over `.select` in
+// `shot-editor/styles.css` is that same failure's earlier postmortem.
+//
+// An UNKNOWN part id is shown rather than silently read as "none": a document
+// can name a part this board no longer has, and a picker that displayed the
+// placeholder would rewrite the binding on the next unrelated edit. Same
+// courtesy `TransitionSection` pays an unknown preset.
+import { Combobox } from "@dailies-studio/ui";
+import type { ComboboxOption } from "@dailies-studio/ui";
+import type { StoryboardPart3D } from "@dailies-studio/shot/doc";
+
+/** The empty value IS "no part". `Combobox` shows the placeholder for it, so
+ *  the trigger reads the none-label without a sentinel id that could ever be
+ *  mistaken for one. */
+const NONE = "";
+
+export function PartPicker(props: {
+  parts: readonly StoryboardPart3D[];
+  value: string | null;
+  /** What "no part" is called here: a group becomes plain, a card unassigned.
+   *  Choosing it IS the unlink, which is why no menu puts an Unlink button
+   *  beside a picker whose empty value already says so. */
+  noneLabel: string;
+  ariaLabel: string;
+  onChange: (part: string | null) => void;
+  /** Open on mount and take focus: for the card chip, which SWAPS itself for
+   *  this control on a press and would otherwise drop focus to `<body>`. */
+  autoOpen?: boolean;
+  /** Dismissed without choosing, so a swapping caller can put its own control
+   *  back rather than leaving a closed picker in its place. */
+  onClose?: () => void;
+}) {
+  const known = props.value !== null && props.parts.some((part) => part.id === props.value);
+  const options: ComboboxOption[] = [
+    { value: NONE, label: props.noneLabel },
+    ...props.parts.map((part) => ({ value: part.id, label: part.label })),
+    ...(props.value !== null && !known ? [{ value: props.value, label: `${props.value} (unknown)` }] : []),
+  ];
+  return (
+    <Combobox
+      options={options}
+      value={props.value ?? NONE}
+      ariaLabel={props.ariaLabel}
+      placeholder={props.noneLabel}
+      onChange={(value) => props.onChange(value === NONE ? null : value)}
+      {...(props.autoOpen === undefined ? {} : { autoOpen: props.autoOpen })}
+      {...(props.onClose === undefined ? {} : { onClose: props.onClose })}
+    />
+  );
+}