@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/state/insert.ts

@@ -16,17 +16,36 @@
 // +y DOWN (see the header of @dailies-studio/shot's types.ts). The stage did the
 // conversion because it is the half that knows the pane's pixel size. Nothing
 // here divides by a zoom, and nothing here knows what a screen is.
-import { LAYER_KINDS, clampSize, pathBounds, pathToD, translatePath } from "@dailies-studio/shot/doc";
+import {
+  DEFAULT_ARROW_HEAD,
+  DEFAULT_HTML_CSS,
+  DEFAULT_HTML_MARKUP,
+  DEFAULT_PRIMITIVE_COLOR,
+  DEFAULT_TEXT_CONTENT,
+  DEFAULT_TEXT_STYLE,
+  SPLINE_POINT_ID_PREFIX,
+  LAYER_KINDS,
+  clampSize,
+  iconNodesToPathD,
+  pathBounds,
+  pathToD,
+  translatePath,
+} from "@dailies-studio/shot/doc";
 import type {
+  IconNode,
   InstanceContractRef,
   Layer3D,
   Layer3DKind,
+  MeshPrimitiveKind,
+  MeshPrimitive,
   Paint,
   PathData,
   Stroke,
-  TextStyle,
+  SplinePoint3D,
 } from "@dailies-studio/shot/doc";
-import type { Vec2, Vec3 } from "@dailies-studio/engine";
+import type { SplineCreateDraft } from "../bridgeTypes.js";
+import { parseHex } from "@dailies-studio/engine";
+import type { Value, Vec2, Vec3 } from "@dailies-studio/engine";
 import type { InsertTool } from "../tools.js";
 
 /**
@@ -70,35 +89,35 @@ export const DEFAULT_DEVICE_SIZE: Vec2 = [400, 800];
  *  resized to something a card actually wants. */
 export const DEFAULT_HTML_SIZE: Vec2 = [720, 360];
 
-/** An instance's box. Square, like a model's, and for the same reason: the
- *  component decides its own extent (the box is a placement and a `CompSize`,
- *  not a crop), so a rectangle here would make a claim about which way an
- *  arbitrary module is long. */
-export const DEFAULT_INSTANCE_SIZE: Vec2 = [480, 480];
+/** The colour a fresh paint opens on, for BOTH doors into one: the draw tools
+ *  here and the inspector's own "+ Fill" (`FillSection`). White on the
+ *  near-black a fresh scene opens on, because a default that draws nothing looks
+ *  exactly like a tool that did nothing. */
+export const DEFAULT_PAINT_COLOR = "#ffffff";
 
-/** What a drawn shape is filled with. White on the near-black a fresh scene
- *  opens on: a default that draws nothing looks exactly like a tool that did
- *  nothing. */
-export const DRAW_FILL: Paint = { type: "solid", color: "#ffffff" };
+/** What a drawn shape is filled with. */
+export const DRAW_FILL: Paint = { type: "solid", color: DEFAULT_PAINT_COLOR };
 
 /** …and what a drawn line, arrow or path is stroked with. A line layer with no
  *  stroke is not drawn at all (`drawStroke` is the only thing that draws one),
- *  so this is not a nicety. */
-export const DRAW_STROKE: Stroke = { color: "#ffffff", widthPx: 4, align: "center" };
-
-export const DRAW_TEXT_STYLE: TextStyle = {
-  fontFamily: "Inter, system-ui, sans-serif",
-  weight: 600,
-  sizePx: 64,
-  lineHeight: 1.2,
-  letterSpacingPx: 0,
-  align: "left",
+ *  so this is not a nicety.
+ *
+ *  4px, and deliberately NOT `StrokeSection`'s `DEFAULT_STROKE` (1px): this
+ *  stroke IS the drawn mark, while that one is a hairline added around a shape
+ *  that already draws. Two gestures, two widths. Do not merge them. */
+export const DRAW_STROKE: Stroke = {
   color: "#ffffff",
+  widthPx: 4,
+  align: "center",
 };
 
-/** The arrowhead, as a fraction of the box's larger side — the unit the schema
- *  uses, so it scales with the arrow instead of needing a second edit. */
-const ARROW_HEAD = 0.12;
+// The text style, the text content, the html snippet and the arrowhead ratio
+// USED to be declared here too, and the agent's `add_layer` had a byte-identical
+// copy of each. They now ship from `@dailies-studio/shot/doc` (`layerOps.ts`),
+// which is the only place either door should read them from. The fill and the
+// stroke above stay LOCAL on purpose: a drawn mark takes the author's own drag
+// and the agent has no drag to take, so those two genuinely differ per lane.
+// See layerOps.ts for which defaults were hoisted and which were not.
 
 /** Where the playhead is and how long its scene is: everything a new layer
  *  needs to land in TIME. */
@@ -107,6 +126,13 @@ export interface InsertContext {
   sceneFrame: number;
   /** The scene's own length, which is where a lifetime that starts late ends. */
   durationFrames: number;
+  /**
+   * The design point (scene px) a default-placed layer centres on: the centre
+   * of what the frame shows, so an Add lands in view under a panned or pushed
+   * camera (F54). Absent = the design origin, which is also the answer inside
+   * a definition, whose interior has no camera.
+   */
+  origin?: DrawPoint;
   /** For the kinds that name one. Absent for everything else. */
   asset?: string;
   /**
@@ -122,6 +148,27 @@ export interface InsertContext {
    * Absent = an image, which is what every caller before video existed meant.
    */
   assetKind?: "image" | "video";
+  /**
+   * width / height of the source the browser decoded, for the media arm.
+   *
+   * ── WHY THE GEOMETRY NEEDS IT ─────────────────────────────────────────
+   *
+   * Without it every dropped recording landed in the literal `DEFAULT_DRAW_SIZE`
+   * box at `fit: "fill"`, so a 16:9 screen capture arrived cropped to 3:2 with
+   * no affordance for getting its aspect back but typing numbers. A mockup tool
+   * whose first act is to crop the thing you gave it is not one.
+   *
+   * A NUMBER AND NOT THE PIXELS, because the box is design px and the source's
+   * own resolution is not: a 3840x2160 capture and a 1280x720 one want the same
+   * plate. Absent (or non-finite, or non-positive) reproduces the old geometry
+   * exactly, which is what a host with nothing to measure has to fall back to —
+   * jsdom decodes no media, and a real browser can still fail to.
+   *
+   * MEASURED IN THE STORE, never here: this file's contract is no document, no
+   * history, no asynchrony, no DOM, and that is what keeps `boxOf` provable by
+   * calling it.
+   */
+  sourceAspect?: number;
 }
 
 /**
@@ -158,7 +205,10 @@ interface DrawBox {
  * saved. The ceiling comes along for free, which is what a drag across a
  * zoomed-way-out pane needs.
  */
-function boxOf(points: readonly DrawPoint[]): DrawBox | null {
+function boxOf(
+  points: readonly DrawPoint[],
+  sourceAspect?: number,
+): DrawBox | null {
   const first = points[0];
   const last = points[points.length - 1];
   if (first === undefined || last === undefined) return null;
@@ -178,7 +228,10 @@ function boxOf(points: readonly DrawPoint[]): DrawBox | null {
   const rawW = maxX - minX;
   const rawH = maxY - minY;
   if (rawW <= 0 && rawH <= 0) {
-    const [w, h] = DEFAULT_DRAW_SIZE;
+    // A CLICK. The default box, re-shaped to the source's aspect at the SAME
+    // AREA, so a portrait capture and a landscape one land equally prominent
+    // rather than one of them dwarfing the other.
+    const [w, h] = defaultBoxFor(sourceAspect);
     return boxOf([
       [minX - w / 2, minY - h / 2],
       [minX + w / 2, minY + h / 2],
@@ -193,15 +246,64 @@ function boxOf(points: readonly DrawPoint[]): DrawBox | null {
     rawH > 0 ? (p[1] - minY) / rawH : 0.5,
   ];
 
+  // A REAL DRAG. The aspect is fitted INSIDE what the author drew and never
+  // grows past it: they expressed an extent, and honouring the source's shape
+  // must not be a licence to spill outside the rectangle they were looking at.
+  const [fitW, fitH] = fitAspect(rawW, rawH, sourceAspect);
+
   return {
     min: [minX, minY],
     position: [(minX + maxX) / 2, (minY + maxY) / 2, 0],
-    size: [clampSize(rawW), clampSize(rawH)],
+    size: [clampSize(fitW), clampSize(fitH)],
     from: frac(first),
     to: frac(last),
   };
 }
 
+/** A usable width/height ratio, or null. One gate for every caller, so "no
+ *  aspect", "NaN because the decode failed" and "0 because the element reported
+ *  nothing yet" all take the identical fallback path. */
+function usableAspect(sourceAspect: number | undefined): number | null {
+  return sourceAspect !== undefined &&
+    Number.isFinite(sourceAspect) &&
+    sourceAspect > 0
+    ? sourceAspect
+    : null;
+}
+
+/** The click box, at `DEFAULT_DRAW_SIZE`'s AREA and the source's shape. Without
+ *  an aspect it is `DEFAULT_DRAW_SIZE` itself, to the byte. */
+function defaultBoxFor(sourceAspect: number | undefined): Vec2 {
+  const aspect = usableAspect(sourceAspect);
+  const [w, h] = DEFAULT_DRAW_SIZE;
+  if (aspect === null) return [w, h];
+  const area = w * h;
+  const height = Math.sqrt(area / aspect);
+  return [height * aspect, height];
+}
+
+/** The largest box of `sourceAspect` that fits inside `w` x `h`. Without an
+ *  aspect the drawn box passes through untouched. */
+function fitAspect(
+  w: number,
+  h: number,
+  sourceAspect: number | undefined,
+): Vec2 {
+  const aspect = usableAspect(sourceAspect);
+  // A degenerate axis has no shape to honour: a horizontal line drag is floored
+  // by `clampSize` into a box the author never framed, and fitting an aspect
+  // into it would invent a height out of the floor.
+  if (aspect === null || w <= 0 || h <= 0) return [w, h];
+  return w / h > aspect ? [h * aspect, h] : [w, w / aspect];
+}
+
+/** Only the media arm has a source to honour. Every other tool draws exactly
+ *  the box it was given, and a stray `sourceAspect` on the context must not
+ *  quietly re-shape a rectangle or a device. */
+function aspectFor(tool: InsertTool, ctx: InsertContext): number | undefined {
+  return tool === "image" ? ctx.sourceAspect : undefined;
+}
+
 /**
  * THE INSERT MAP. Keyed on `InsertTool`, so a tool added to the table without
  * an answer here is a compile error rather than a button that does nothing.
@@ -211,17 +313,42 @@ function boxOf(points: readonly DrawPoint[]): DrawBox | null {
  */
 const INSERT: Record<
   InsertTool,
-  (box: DrawBox, points: readonly DrawPoint[], ctx: InsertContext) => NewLayer3D | null
+  (
+    box: DrawBox,
+    points: readonly DrawPoint[],
+    ctx: InsertContext,
+  ) => NewLayer3D | null
 > = {
-  rect: (box) => ({ kind: "rect", label: "Rect", ...common(box), paint: { fill: DRAW_FILL } }),
-  ellipse: (box) => ({ kind: "ellipse", label: "Ellipse", ...common(box), paint: { fill: DRAW_FILL } }),
-  text: (box) => ({
-    kind: "text",
-    label: "Text",
+  rect: (box) => ({
+    kind: "rect",
+    label: "Rect",
+    ...common(box),
+    paint: { fill: DRAW_FILL },
+  }),
+  ellipse: (box) => ({
+    kind: "ellipse",
+    label: "Ellipse",
     ...common(box),
-    paint: {},
-    text: { content: "Text", style: DRAW_TEXT_STYLE },
+    paint: { fill: DRAW_FILL },
   }),
+  // A CLICK makes an auto-width box (`TextBox`), as in Figma: its left edge on
+  // the click, centred on it vertically, at a size estimated here and measured
+  // exactly by the stage once it draws. A DRAG makes a fixed box that wraps
+  // inside the dragged width.
+  text: (box, points) => {
+    const [x, y] = points[0]!;
+    const click = points.every((p) => p[0] === x && p[1] === y);
+    const style = DEFAULT_TEXT_STYLE;
+    const w = Math.ceil(DEFAULT_TEXT_CONTENT.length * style.sizePx * 0.6);
+    const h = style.sizePx * style.lineHeight;
+    return {
+      kind: "text",
+      label: "Text",
+      ...common(click ? { ...box, position: [x + w / 2, y, 0], size: [w, h] } : box),
+      paint: {},
+      text: { content: DEFAULT_TEXT_CONTENT, style, ...(click ? { box: "auto" as const } : {}) },
+    };
+  },
   // ONE ARM, TWO KINDS. `image` and `video` are one pipeline everywhere it
   // matters — the runtime collapses both to {asset, fit, crop} and draws them
   // through one plane — so the Frame tool draws one box and the file the author
@@ -232,7 +359,13 @@ const INSERT: Record<
     // "fill" and not "fit", for both: the author drew the box they want
     // covered, and letterboxing it would leave the drawn rectangle half empty.
     if (ctx.assetKind !== "video") {
-      return { kind: "image", label: "Image", ...common(box), paint: {}, image: { asset: ctx.asset, fit: "fill" } };
+      return {
+        kind: "image",
+        label: "Image",
+        ...common(box),
+        paint: {},
+        image: { asset: ctx.asset, fit: "fill" },
+      };
     }
     // THE SOURCE STARTS WHERE THE LAYER DOES. `withLifetime` puts the layer's
     // `in` at the playhead, and a video whose source clock still began at scene
@@ -247,7 +380,11 @@ const INSERT: Record<
       label: "Video",
       ...common(box),
       paint: {},
-      video: { asset: ctx.asset, fit: "fill", ...(start > 0 ? { offsetFrames: start } : {}) },
+      video: {
+        asset: ctx.asset,
+        fit: "fill",
+        ...(start > 0 ? { offsetFrames: start } : {}),
+      },
     };
   },
   line: (box) => ({
@@ -262,7 +399,7 @@ const INSERT: Record<
     label: "Arrow",
     ...common(box),
     paint: { stroke: DRAW_STROKE },
-    arrow: { from: box.from, to: box.to, head: ARROW_HEAD },
+    arrow: { from: box.from, to: box.to, head: DEFAULT_ARROW_HEAD },
   }),
   path: (box, points) => ({
     kind: "path",
@@ -278,7 +415,7 @@ const INSERT: Record<
 };
 
 /** The fields every drawn layer fills in the same way. */
-function common(box: DrawBox): { transform: Layer3D["transform"]; blocks: [] } {
+function common(box: DrawBox): { transform: Layer3D["transform"] } {
   return {
     transform: {
       position: [box.position[0], box.position[1], box.position[2]],
@@ -287,7 +424,6 @@ function common(box: DrawBox): { transform: Layer3D["transform"]; blocks: [] } {
       rollDeg: 0,
       opacity: 1,
     },
-    blocks: [],
   };
 }
 
@@ -295,7 +431,12 @@ function common(box: DrawBox): { transform: Layer3D["transform"]; blocks: [] } {
  *  a document written twice from the same drag is byte-identical. */
 function polyline(points: readonly DrawPoint[], min: Vec2): string {
   const n = (v: number): string => String(Math.round(v * 100) / 100);
-  return points.map((p, i) => `${i === 0 ? "M" : "L"} ${n(p[0] - min[0])} ${n(p[1] - min[1])}`).join(" ");
+  return points
+    .map(
+      (p, i) =>
+        `${i === 0 ? "M" : "L"} ${n(p[0] - min[0])} ${n(p[1] - min[1])}`,
+    )
+    .join(" ");
 }
 
 /**
@@ -315,7 +456,10 @@ export function layerFromDraw(
   // already two identical ones, so this is the only arity worth stating.
   if (tool === "path" && dedupe(points).length < 2) return null;
   const cleaned = tool === "path" ? dedupe(points) : points;
-  const box = boxOf(cleaned);
+  // The aspect reaches `boxOf` and nothing else: it is a GEOMETRY input, so it
+  // belongs where the box is decided rather than in the media arm, which would
+  // then be re-deriving a position and a size the box already computed.
+  const box = boxOf(cleaned, aspectFor(tool, ctx));
   if (box === null) return null;
   const layer = INSERT[tool](box, cleaned, ctx);
   return layer === null ? null : withLifetime(layer, ctx);
@@ -337,7 +481,10 @@ export function layerFromDraw(
  * origin into `d` and break `pathToD(points) === d` the moment the document was
  * opened.
  */
-export function penLayer(data: PathData, ctx: InsertContext): NewLayer3D | null {
+export function penLayer(
+  data: PathData,
+  ctx: InsertContext,
+): NewLayer3D | null {
   if (data.points.length < 2) return null;
   const bounds = pathBounds(data);
   const box = boxOf([
@@ -355,7 +502,11 @@ export function penLayer(data: PathData, ctx: InsertContext): NewLayer3D | null
       // author was drawing, and a filled shape appearing on close would be a
       // second edit they did not make. The inspector adds one in a click.
       paint: { stroke: DRAW_STROKE },
-      path: { d: pathToD(local), viewBox: [box.size[0], box.size[1]], points: local },
+      path: {
+        d: pathToD(local),
+        viewBox: [box.size[0], box.size[1]],
+        points: local,
+      },
     },
     ctx,
   );
@@ -367,25 +518,153 @@ export function meshLayer(asset: string, ctx: InsertContext): NewLayer3D {
     {
       kind: "mesh",
       label: "Model",
-      transform: centred(DEFAULT_MESH_SIZE),
+      transform: centred(DEFAULT_MESH_SIZE, ctx),
       // Inert on a mesh — the look is `mesh.shading`, not a Canvas2D fill.
       paint: {},
-      blocks: [],
       mesh: { asset },
     },
     ctx,
   );
 }
 
+/** A shape's box. Square like a model's: every primitive derives its radii
+ *  from the box, and a square makes no claim about which way a shape is long. */
+export const DEFAULT_SHAPE_SIZE: Vec2 = [300, 300];
+
+/**
+ * A parametric shape (schema v11), from the ADD menu.
+ *
+ * TOON BY DEFAULT, which is this factory's one real decision: an unlit
+ * flat-colour solid has no visible form — the silhouette is all there is — so
+ * a fresh box would read as a rounded rectangle until the author found the
+ * shading row. The default colour is authored INTO the document rather than
+ * left to the runtime's fallback, so the inspector's colour well shows the
+ * value the stage is actually drawing.
+ */
+export function shapeLayer(
+  kind: MeshPrimitiveKind,
+  ctx: InsertContext,
+): NewLayer3D {
+  return withLifetime(
+    {
+      kind: "mesh",
+      label: kind.charAt(0).toUpperCase() + kind.slice(1),
+      transform: centred(DEFAULT_SHAPE_SIZE, ctx),
+      // Inert on a mesh — the look is colour + shading, not a Canvas2D fill.
+      paint: {},
+      mesh: {
+        primitive: primitiveForKind(kind),
+        color: DEFAULT_PRIMITIVE_COLOR,
+        shading: { mode: "toon" },
+      },
+    },
+    ctx,
+  );
+}
+
+/** A complete valid primitive for an Add-menu insert or an inspector kind
+ *  switch. Structural spline defaults cannot be represented by `{kind}`. */
+export function primitiveForKind(kind: MeshPrimitiveKind): MeshPrimitive {
+  if (kind === "spline") {
+    return {
+      kind,
+      frameSize: [300, 300],
+      points: [
+        {
+          id: `${SPLINE_POINT_ID_PREFIX}0`,
+          p: [-150, 60, 0],
+          out: [-50, -60, 0],
+        },
+        { id: `${SPLINE_POINT_ID_PREFIX}1`, p: [150, -60, 0], in: [50, 60, 0] },
+      ],
+      basis: "bezier",
+      profile: { kind: "tube", radiusPx: 8 },
+      caps: "round",
+    };
+  }
+  return { kind } as MeshPrimitive;
+}
+
+/** Normalize a stage-authored world-space draft into one local spline layer. */
+export function splineLayer(
+  draft: SplineCreateDraft,
+  ctx: InsertContext,
+): NewLayer3D | null {
+  if (draft.points.length < (draft.closed ? 3 : 2)) return null;
+  const values = draft.points.flatMap((point) =>
+    [point.p, point.in, point.out].filter(isVec3),
+  );
+  if (values.length === 0) return null;
+  const min: Vec3 = [Infinity, Infinity, Infinity];
+  const max: Vec3 = [-Infinity, -Infinity, -Infinity];
+  for (const value of values) {
+    for (let axis = 0; axis < 3; axis += 1) {
+      min[axis] = Math.min(min[axis]!, value[axis]!);
+      max[axis] = Math.max(max[axis]!, value[axis]!);
+    }
+  }
+  if (![...min, ...max].every(Number.isFinite)) return null;
+  const centre: Vec3 = [
+    (min[0] + max[0]) / 2,
+    (min[1] + max[1]) / 2,
+    (min[2] + max[2]) / 2,
+  ];
+  const size: Vec2 = [clampSize(max[0] - min[0]), clampSize(max[1] - min[1])];
+  const local = (value: readonly [number, number, number]): Vec3 => [
+    value[0] - centre[0],
+    value[1] - centre[1],
+    value[2] - centre[2],
+  ];
+  const points: SplinePoint3D[] = draft.points.map((point, index) => ({
+    id: `${SPLINE_POINT_ID_PREFIX}${index}`,
+    p: local(point.p),
+    ...(point.in === undefined ? {} : { in: local(point.in) }),
+    ...(point.out === undefined ? {} : { out: local(point.out) }),
+  }));
+  return withLifetime(
+    {
+      kind: "mesh",
+      label: "Spline",
+      transform: {
+        position: centre,
+        size,
+        tilt: [0, 0],
+        rollDeg: 0,
+        opacity: 1,
+      },
+      paint: {},
+      mesh: {
+        primitive: {
+          kind: "spline",
+          frameSize: [size[0], size[1]],
+          points,
+          basis: draft.basis,
+          ...(draft.closed ? { closed: true } : {}),
+          profile: { kind: "tube", radiusPx: 8 },
+          caps: "round",
+        },
+        color: DEFAULT_PRIMITIVE_COLOR,
+        shading: { mode: "toon" },
+      },
+    },
+    ctx,
+  );
+}
+
+function isVec3(value: Vec3 | undefined): value is Vec3 {
+  return (
+    value !== undefined && value.length === 3 && value.every(Number.isFinite)
+  );
+}
+
 /** A device slab, from the ADD menu. */
 export function deviceLayer(preset: string, ctx: InsertContext): NewLayer3D {
   return withLifetime(
     {
       kind: "device",
       label: preset.charAt(0).toUpperCase() + preset.slice(1),
-      transform: centred(DEFAULT_DEVICE_SIZE),
+      transform: centred(DEFAULT_DEVICE_SIZE, ctx),
       paint: {},
-      blocks: [],
       device: { preset, children: [] },
     },
     ctx,
@@ -408,15 +687,9 @@ export function htmlLayer(ctx: InsertContext): NewLayer3D {
     {
       kind: "html",
       label: "Html",
-      transform: centred(DEFAULT_HTML_SIZE),
+      transform: centred(DEFAULT_HTML_SIZE, ctx),
       paint: {},
-      blocks: [],
-      html: {
-        markup: `<div class="root"><span>Html</span></div>`,
-        css:
-          ".root{width:100%;height:100%;display:flex;align-items:center;justify-content:center;" +
-          "font:600 64px Inter,system-ui,sans-serif;color:#fff}",
-      },
+      html: { markup: DEFAULT_HTML_MARKUP, css: DEFAULT_HTML_CSS },
     },
     ctx,
   );
@@ -429,32 +702,113 @@ export function htmlLayer(ctx: InsertContext): NewLayer3D {
  * hash it was bound at, and the contract itself when the registry says a
  * generated file could not import it. That is what makes a later source edit
  * show up as DRIFT the author resolves, instead of silently re-typing props
- * authored against the old shape. `props` starts EMPTY — every unset key takes
- * the contract's own default through `buildProps`, and baking defaults in at
- * insert time would freeze them against later edits to the component itself.
+ * authored against the old shape. `props` seeds the instance's own values;
+ * every unset key takes the contract's default through `buildProps`, and
+ * baking defaults in at insert time would freeze them against later edits to
+ * the component itself.
+ *
+ * ONE SIZE, `frame`: the whole frame. A shipped component composes against its
+ * box and its card thumbnail shows it on a whole frame, so what is clicked is
+ * what lands, from every door (F51, F58).
  */
 export function instanceLayer(
   component: string,
   label: string,
   binding: { contractHash?: string; contract?: InstanceContractRef },
+  props: Readonly<Record<string, Value>>,
+  frame: Vec2,
   ctx: InsertContext,
 ): NewLayer3D {
   return withLifetime(
     {
       kind: "instance",
       label,
-      transform: centred(DEFAULT_INSTANCE_SIZE),
+      transform: centred(frame, ctx),
       // Inert on an instance, as on a mesh: the component paints itself.
       paint: {},
-      blocks: [],
-      instance: { component, props: {}, ...binding },
+      instance: { component, props: { ...props }, ...binding },
+    },
+    ctx,
+  );
+}
+
+/** An icon's box. Square, like the 24×24 grid it is drawn on. */
+export const ICON_SIZE = 96;
+
+/** The two inks an icon is drawn in: light on a dark Shot, dark on a light
+ *  one. */
+export const ICON_INK = { light: "#f5f5f5", dark: "#111111" } as const;
+
+/**
+ * The ink that reads on `background`: its mean relative luminance (sRGB
+ * weights, linearised) against 0.18, where black and white ink contrast
+ * equally. A gradient averages its stops.
+ * A colour that does not parse counts as dark, the scene's own default.
+ */
+export function inkFor(background: Paint): string {
+  const colors = background.type === "solid" ? [background.color] : background.stops.map((s) => s.color);
+  const lin = (c: number): number => (c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4);
+  let sum = 0;
+  for (const color of colors) {
+    try {
+      const { r, g, b } = parseHex(color);
+      sum += 0.2126 * lin(r) + 0.7152 * lin(g) + 0.0722 * lin(b);
+    } catch {
+      /* not a hex: counted as black */
+    }
+  }
+  return colors.length > 0 && sum / colors.length > 0.18 ? ICON_INK.dark : ICON_INK.light;
+}
+
+/** The name "Use as background" gives the ground it places. */
+export const BACKGROUND_LABEL = "Background";
+
+/**
+ * The ground "Use as background" placed in this Shot, or null: the back root
+ * layer, locked and named Background. Locked layers skip stage picks, so the
+ * Shot inspector's door selects it by this.
+ */
+export function backgroundLayerOf(scene: { layers: readonly string[]; layersById: Readonly<Record<string, Layer3D>> } | undefined): string | null {
+  const id = scene?.layers[0];
+  const layer = id === undefined ? undefined : scene?.layersById[id];
+  return layer !== undefined && layer.locked === true && layer.label === BACKGROUND_LABEL ? layer.id : null;
+}
+
+/**
+ * A Lucide icon as a PATH layer: editable, recolourable and keyframable, never
+ * an image. Lucide draws a 2px stroke on a 24px grid with round ends and no
+ * fill, and the stroke width here is that 2px scaled to the box (8px on 96),
+ * so the layer looks like the tile the author clicked.
+ */
+export function iconLayer(
+  name: string,
+  nodes: readonly IconNode[],
+  ink: string,
+  ctx: InsertContext,
+): NewLayer3D {
+  return withLifetime(
+    {
+      kind: "path",
+      label: name,
+      transform: centred([ICON_SIZE, ICON_SIZE], ctx),
+      paint: {
+        stroke: { color: ink, widthPx: (2 * ICON_SIZE) / 24, align: "center", cap: "round", join: "round" },
+      },
+      path: { d: iconNodesToPathD(nodes), viewBox: [24, 24] },
     },
     ctx,
   );
 }
 
-function centred(size: Vec2): Layer3D["transform"] {
-  return { position: [0, 0, 0], size: [size[0], size[1]], tilt: [0, 0], rollDeg: 0, opacity: 1 };
+function centred(size: Vec2, ctx: InsertContext): Layer3D["transform"] {
+  const [x, y] = ctx.origin ?? [0, 0];
+  return {
+    position: [x, y, 0],
+    size: [size[0], size[1]],
+    tilt: [0, 0],
+    rollDeg: 0,
+    opacity: 1,
+  };
 }
 
 /**
@@ -470,10 +824,33 @@ function centred(size: Vec2): Layer3D["transform"] {
  * Same placement, one fewer thing to maintain.
  */
 function withLifetime(layer: NewLayer3D, ctx: InsertContext): NewLayer3D {
+  const life = lifetimeFor(ctx);
+  return life === undefined
+    ? layer
+    : ({ ...layer, lifetime: life } as NewLayer3D);
+}
+
+/**
+ * The rule above, as a value, for the one create that does not build its
+ * layer here.
+ *
+ * `placeComponent` goes through `componentOps.addComponentInstance`, which
+ * assembles its own instance, so it could not wrap itself in `withLifetime`
+ * and for a long time did not land at the playhead at all: the rail's `+` on a
+ * definition made a whole-scene instance while the `+` one list below it, on a
+ * code component, landed under the clock. Two adjacent buttons, two answers to
+ * "when does this start". Exported so there is one.
+ *
+ * `undefined` at frame 0 for the reason above: absent already means the whole
+ * scene, and it keeps meaning that when the scene is later trimmed.
+ */
+export function lifetimeFor(
+  ctx: InsertContext,
+): { in: number; out: number } | undefined {
   const start = startFrameOf(ctx);
   const end = Math.trunc(ctx.durationFrames);
-  if (start <= 0 || end <= start) return layer;
-  return { ...layer, lifetime: { in: start, out: end } } as NewLayer3D;
+  if (start <= 0 || end <= start) return undefined;
+  return { in: start, out: end };
 }
 
 /** The scene frame a new layer lands on. ONE function because TWO things read