@dailies-studio/shot-editor 0.1.0

package/src/state/insert.ts

@@ -0,0 +1,507 @@
+// WHAT A DRAWN LAYER IS. One pure function from (tool, design points) to a
+// layer, and the insert map every creating tool has to answer in.
+//
+// ── WHY IT IS NOT IN THE STORE ──────────────────────────────────────────
+//
+// Everything here is arithmetic and defaults: no document, no history, no
+// asynchrony, no DOM. That makes the part with actual geometry in it testable
+// by calling it, which matters because the two facts worth pinning — a drag
+// from bottom-right to top-left gives the SAME box as the reverse, and the
+// endpoints of a line survive that normalisation as fractions — are exactly the
+// ones a store test would have to reach through a fake stage to see.
+//
+// ── THE COORDINATE CONTRACT ─────────────────────────────────────────────
+//
+// Points arrive in the schema's own space: design px from the CANVAS CENTRE,
+// +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 type {
+  InstanceContractRef,
+  Layer3D,
+  Layer3DKind,
+  Paint,
+  PathData,
+  Stroke,
+  TextStyle,
+} from "@dailies-studio/shot/doc";
+import type { Vec2, Vec3 } from "@dailies-studio/engine";
+import type { InsertTool } from "../tools.js";
+
+/**
+ * A layer before `addLayer` gives it an id and a paint order.
+ *
+ * DISTRIBUTED over the union, unlike `Omit<Layer3D, …>`, which is not: `Omit`
+ * of a union keeps only the keys every member shares, so that spelling would
+ * quietly drop `text`, `line` and every other content block and let this file
+ * build a text layer with no text in it.
+ */
+export type NewLayer3D = {
+  [K in Layer3DKind]: Omit<Extract<Layer3D, { kind: K }>, "id" | "order">;
+}[Layer3DKind];
+
+/** Design px from the canvas centre. */
+export type DrawPoint = readonly [number, number];
+
+/**
+ * The box a click gets, in design px.
+ *
+ * One size for every tool rather than a table of them, because a click is not
+ * an expression of intent about size — it is "put one here" — and the author's
+ * next gesture on a freshly selected layer is a resize either way.
+ */
+export const DEFAULT_DRAW_SIZE: Vec2 = [240, 160];
+
+/** A model's box. Square, because `fit` preserves the model's own proportions
+ *  inside it and a square makes no claim about which way the model is long. */
+export const DEFAULT_MESH_SIZE: Vec2 = [480, 480];
+
+/**
+ * A device's box. Portrait, and the height is a CHOICE this file has to make:
+ * a preset carries ratios of the WIDTH only and deliberately no aspect (see
+ * devicePresets.ts), so there is no registry answer to inherit.
+ */
+export const DEFAULT_DEVICE_SIZE: Vec2 = [400, 800];
+
+/** A snippet's box. Landscape and generous: the box IS the layout viewport for
+ *  an html layer — a percentage width inside it resolves against this — so a
+ *  square default would make every first snippet reflow the moment it is
+ *  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];
+
+/** 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" };
+
+/** …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",
+  color: "#ffffff",
+};
+
+/** 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;
+
+/** Where the playhead is and how long its scene is: everything a new layer
+ *  needs to land in TIME. */
+export interface InsertContext {
+  /** SCENE-LOCAL frame under the playhead. */
+  sceneFrame: number;
+  /** The scene's own length, which is where a lifetime that starts late ends. */
+  durationFrames: number;
+  /** For the kinds that name one. Absent for everything else. */
+  asset?: string;
+  /**
+   * WHICH media the asset turned out to be, as the SERVER sniffed it.
+   *
+   * The Frame tool draws ONE box and the file decides what fills it, so the
+   * `image` arm below is the only one that forks on something outside the
+   * geometry. It is the store's kind and never a browser MIME guess: the sniff
+   * is the stored filename's extension, which is the same answer
+   * `validateShotDoc` and the exporter will get, and a client-side guess that
+   * disagreed would mint a layer kind the document cannot back.
+   *
+   * Absent = an image, which is what every caller before video existed meant.
+   */
+  assetKind?: "image" | "video";
+}
+
+/**
+ * A drag, normalised into the box it describes.
+ *
+ * `from`/`to` are the drag's own ends as FRACTIONS of that box, which is what
+ * survives the normalisation: the box is direction-free by construction (it is
+ * a min/max), and a line drawn up-left has to keep pointing up-left.
+ */
+interface DrawBox {
+  /** Top-left corner, design px. Only the path builder needs it. */
+  min: Vec2;
+  /** Centre, which is what `Transform3D.position` means. */
+  position: Vec3;
+  size: Vec2;
+  from: Vec2;
+  to: Vec2;
+}
+
+/**
+ * The box N points describe.
+ *
+ * A CLICK — every point identical, which is also how the stage reports a drag
+ * that never passed its travel threshold — is rewritten as a drag of the
+ * default size centred on it, and then falls through the ordinary path. That is
+ * one branch here instead of one in every insert below: a clicked rect gets its
+ * default box and a clicked line gets a diagonal across the same box, with no
+ * tool having to answer "and what if it was a click".
+ *
+ * Each axis goes through `clampSize`, the SAME clamp a resize gesture uses. A
+ * perfectly horizontal line drag has a zero-height bounding box, and
+ * `validateShotDoc` refuses a non-positive size — so without the floor the most
+ * ordinary line an author can draw would produce a document that cannot be
+ * 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 {
+  const first = points[0];
+  const last = points[points.length - 1];
+  if (first === undefined || last === undefined) return null;
+
+  let minX = Infinity;
+  let minY = Infinity;
+  let maxX = -Infinity;
+  let maxY = -Infinity;
+  for (const [x, y] of points) {
+    if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
+    minX = Math.min(minX, x);
+    maxX = Math.max(maxX, x);
+    minY = Math.min(minY, y);
+    maxY = Math.max(maxY, y);
+  }
+
+  const rawW = maxX - minX;
+  const rawH = maxY - minY;
+  if (rawW <= 0 && rawH <= 0) {
+    const [w, h] = DEFAULT_DRAW_SIZE;
+    return boxOf([
+      [minX - w / 2, minY - h / 2],
+      [minX + w / 2, minY + h / 2],
+    ]);
+  }
+
+  // The fraction is taken against the RAW span, never the floored one: a
+  // degenerate axis has no meaningful fraction, and 0.5 puts the endpoint on
+  // the box's centre line, which is where a horizontal line actually is.
+  const frac = (p: DrawPoint): Vec2 => [
+    rawW > 0 ? (p[0] - minX) / rawW : 0.5,
+    rawH > 0 ? (p[1] - minY) / rawH : 0.5,
+  ];
+
+  return {
+    min: [minX, minY],
+    position: [(minX + maxX) / 2, (minY + maxY) / 2, 0],
+    size: [clampSize(rawW), clampSize(rawH)],
+    from: frac(first),
+    to: frac(last),
+  };
+}
+
+/**
+ * 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.
+ *
+ * A builder returns null when it cannot make a layer it would be honest about —
+ * only `image` can, and only for want of an asset.
+ */
+const INSERT: Record<
+  InsertTool,
+  (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",
+    ...common(box),
+    paint: {},
+    text: { content: "Text", style: DRAW_TEXT_STYLE },
+  }),
+  // 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
+  // picks decides which kind it becomes. Both wire kinds stay: merging them is
+  // a schema break for zero runtime gain.
+  image: (box, _points, ctx) => {
+    if (ctx.asset === undefined) return null;
+    // "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" } };
+    }
+    // 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
+    // frame 0 would open already that many frames in — a clip dropped at frame
+    // 50 showing its 50th frame first, which reads as a corrupt asset rather
+    // than as a placement. Written only when it is non-zero, and CONDITIONALLY
+    // SPREAD rather than assigned: absent already means 0, and under
+    // exactOptionalPropertyTypes `offsetFrames: undefined` is a key.
+    const start = startFrameOf(ctx);
+    return {
+      kind: "video",
+      label: "Video",
+      ...common(box),
+      paint: {},
+      video: { asset: ctx.asset, fit: "fill", ...(start > 0 ? { offsetFrames: start } : {}) },
+    };
+  },
+  line: (box) => ({
+    kind: "line",
+    label: "Line",
+    ...common(box),
+    paint: { stroke: DRAW_STROKE },
+    line: { from: box.from, to: box.to },
+  }),
+  arrow: (box) => ({
+    kind: "arrow",
+    label: "Arrow",
+    ...common(box),
+    paint: { stroke: DRAW_STROKE },
+    arrow: { from: box.from, to: box.to, head: ARROW_HEAD },
+  }),
+  path: (box, points) => ({
+    kind: "path",
+    label: "Path",
+    ...common(box),
+    paint: { stroke: DRAW_STROKE },
+    // BOX-RELATIVE, with the viewBox set to the box's own size, so the two
+    // scales the rasterizer computes (`w / vw`, `h / vh`) are 1 until the
+    // author resizes the layer — and then the artwork stretches with the box,
+    // which is what a path layer's box means.
+    path: { d: polyline(points, box.min), viewBox: [box.size[0], box.size[1]] },
+  }),
+};
+
+/** The fields every drawn layer fills in the same way. */
+function common(box: DrawBox): { transform: Layer3D["transform"]; blocks: [] } {
+  return {
+    transform: {
+      position: [box.position[0], box.position[1], box.position[2]],
+      size: [box.size[0], box.size[1]],
+      tilt: [0, 0],
+      rollDeg: 0,
+      opacity: 1,
+    },
+    blocks: [],
+  };
+}
+
+/** `M`/`L` over the points, relative to the box's top-left corner. Rounded, so
+ *  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(" ");
+}
+
+/**
+ * The layer a draw gesture asks for, or null when the points cannot make one.
+ *
+ * Null is the honest answer for a cancelled pen (no points), a pen with a
+ * single point (a path needs a segment) and an image whose upload has not
+ * landed — refusing to insert beats inserting something the author then has to
+ * find and delete.
+ */
+export function layerFromDraw(
+  tool: InsertTool,
+  points: readonly DrawPoint[],
+  ctx: InsertContext,
+): NewLayer3D | null {
+  // The pen's own minimum. Every other tool takes two points and a click is
+  // 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);
+  if (box === null) return null;
+  const layer = INSERT[tool](box, cleaned, ctx);
+  return layer === null ? null : withLifetime(layer, ctx);
+}
+
+/**
+ * The layer the PEN commits: anchors, handles, and the printed `d` that must
+ * agree with them.
+ *
+ * Separate from `layerFromDraw` because the pen no longer draws a polyline.
+ * `INSERT.path` stays for the callers that still hand over bare points (the
+ * bridge's `onDraw` lane), and this is the one that carries curves.
+ *
+ * THE ORDER MATTERS. Bounds first, INCLUDING the handles — `pathBounds` takes
+ * control points precisely so a curve that bulges past its anchors is not
+ * clipped by its own box. Then translate into box-local coordinates, so the
+ * viewBox starts at 0,0 like every other path layer's. Then print, LAST, from
+ * the translated model: printing before the translate would bake the old
+ * origin into `d` and break `pathToD(points) === d` the moment the document was
+ * opened.
+ */
+export function penLayer(data: PathData, ctx: InsertContext): NewLayer3D | null {
+  if (data.points.length < 2) return null;
+  const bounds = pathBounds(data);
+  const box = boxOf([
+    [bounds.x, bounds.y],
+    [bounds.x + bounds.w, bounds.y + bounds.h],
+  ]);
+  if (box === null) return null;
+  const local = translatePath(data, -bounds.x, -bounds.y);
+  return withLifetime(
+    {
+      kind: "path",
+      label: "Path",
+      ...common(box),
+      // A closed path still gets no default fill: the pen's stroke is what the
+      // 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 },
+    },
+    ctx,
+  );
+}
+
+/** A model layer, from the ADD menu. */
+export function meshLayer(asset: string, ctx: InsertContext): NewLayer3D {
+  return withLifetime(
+    {
+      kind: "mesh",
+      label: "Model",
+      transform: centred(DEFAULT_MESH_SIZE),
+      // Inert on a mesh — the look is `mesh.shading`, not a Canvas2D fill.
+      paint: {},
+      blocks: [],
+      mesh: { asset },
+    },
+    ctx,
+  );
+}
+
+/** 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),
+      paint: {},
+      blocks: [],
+      device: { preset, children: [] },
+    },
+    ctx,
+  );
+}
+
+/**
+ * An html snippet, from the ADD menu.
+ *
+ * The default RENDERS, which is the rule every factory here follows and the one
+ * that matters most for this kind: a snippet that starts empty draws an empty
+ * plane, and an author has no way to tell that apart from a snippet that failed
+ * to parse. Starting with something on screen makes the difference visible.
+ *
+ * XHTML from the first character — void tags self-closed, CSS in `css` — so the
+ * thing an author edits is already shaped like the thing that has to be saved.
+ */
+export function htmlLayer(ctx: InsertContext): NewLayer3D {
+  return withLifetime(
+    {
+      kind: "html",
+      label: "Html",
+      transform: centred(DEFAULT_HTML_SIZE),
+      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}",
+      },
+    },
+    ctx,
+  );
+}
+
+/**
+ * A contracted component, from the ADD menu.
+ *
+ * The BINDING is recorded here and only here: the component id, the contract
+ * 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.
+ */
+export function instanceLayer(
+  component: string,
+  label: string,
+  binding: { contractHash?: string; contract?: InstanceContractRef },
+  ctx: InsertContext,
+): NewLayer3D {
+  return withLifetime(
+    {
+      kind: "instance",
+      label,
+      transform: centred(DEFAULT_INSTANCE_SIZE),
+      // Inert on an instance, as on a mesh: the component paints itself.
+      paint: {},
+      blocks: [],
+      instance: { component, props: {}, ...binding },
+    },
+    ctx,
+  );
+}
+
+function centred(size: Vec2): Layer3D["transform"] {
+  return { position: [0, 0, 0], size: [size[0], size[1]], tilt: [0, 0], rollDeg: 0, opacity: 1 };
+}
+
+/**
+ * NEW LAYERS START AT THE PLAYHEAD, which for a layer means its LIFETIME.
+ *
+ * The same rule After Effects has, and the one every other create in this
+ * chrome already follows. A layer drawn at frame 40 that silently existed from
+ * frame 0 would be a layer the author has to go and re-time by hand every time.
+ *
+ * At frame 0 the lifetime is left ABSENT rather than written as {0, duration}.
+ * Absent already means "the whole scene", and it keeps meaning that when the
+ * scene is later trimmed — an explicit pair would have to be dragged to follow.
+ * Same placement, one fewer thing to maintain.
+ */
+function withLifetime(layer: NewLayer3D, ctx: InsertContext): NewLayer3D {
+  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;
+}
+
+/** The scene frame a new layer lands on. ONE function because TWO things read
+ *  it — the lifetime's `in` above and a dropped video's `offsetFrames` — and a
+ *  clip whose source clock started at a different frame from its own lifetime
+ *  is a clip that opens part-way through. */
+function startFrameOf(ctx: InsertContext): number {
+  return Math.max(0, Math.trunc(ctx.sceneFrame));
+}
+
+/** Consecutive duplicates dropped. The pen's double-click commit lands its
+ *  second press on the same point as the first, so without this every
+ *  double-click would leave a zero-length segment in the `d`. */
+function dedupe(points: readonly DrawPoint[]): readonly DrawPoint[] {
+  return points.filter((p, i) => {
+    const prev = points[i - 1];
+    return prev === undefined || prev[0] !== p[0] || prev[1] !== p[1];
+  });
+}
+
+/**
+ * Is this layer kind in the schema's vocabulary at runtime?
+ *
+ * WIDENED TO STRING on purpose. `LAYER_KINDS.includes("mesh")` against the
+ * literal tuple is a TYPE error the day the kind is removed, which is a build
+ * nobody can ship — so the menu could not degrade, it could only fail to
+ * compile. This is what lets the ADD menu drop an entry instead.
+ */
+export function hasLayerKind(kind: string): boolean {
+  return (LAYER_KINDS as readonly string[]).includes(kind);
+}