@dailies-studio/shot-editor 0.1.0

package/src/panels/inspector/design/HtmlSection.tsx

@@ -0,0 +1,50 @@
+// Only for HTML layers, and absent otherwise — the same rule every section in
+// this folder follows.
+//
+// TWO FIELDS AND NOT ONE, because the split is a correctness rule rather than a
+// layout preference: a snippet is parsed as XML, where an unescaped `a > b`
+// inside a `<style>` element is a fatal error. Carrying the CSS separately is
+// what lets `serializeHtmlSvg` wrap it in CDATA — see HtmlLayer3D.
+//
+// The fields commit on BLUR, which `TextField` already owns. That is the right
+// granularity here and not a compromise: every commit re-serializes the snippet,
+// re-decodes it through an SVG image and re-rasters the layer, so a per-keystroke
+// commit would put a decode on the critical path of every character typed.
+import { InspectorRow, InspectorSection, TextField } from "@dailies-studio/ui";
+import type { HtmlLayer3D, Layer3D } from "@dailies-studio/shot/doc";
+import { useSelectedLayers, useSelectionValue, useSelectionWrite } from "../useDocWrite.js";
+
+export function HtmlSection() {
+  const write = useSelectionWrite();
+  const layers = useSelectedLayers();
+  const anyHtml = layers.some((l) => l.kind === "html");
+  const markup = useSelectionValue((layer) => (layer.kind === "html" ? layer.html.markup : undefined));
+  const css = useSelectionValue((layer) => (layer.kind === "html" ? (layer.html.css ?? "") : undefined));
+  if (!anyHtml || markup.value === undefined) return null;
+
+  const patch = (next: Partial<HtmlLayer3D["html"]>): void =>
+    write((layer) => (layer.kind === "html" ? ({ ...layer, html: { ...layer.html, ...next } } as Layer3D) : layer));
+
+  return (
+    <InspectorSection title="Html" persistKey="shot:html">
+      <InspectorRow label="Markup">
+        <TextField
+          value={markup.value}
+          multiline
+          ariaLabel="Html markup"
+          placeholder="<div>…</div>"
+          onCommit={(next) => patch({ markup: next })}
+        />
+      </InspectorRow>
+      <InspectorRow label="CSS">
+        <TextField
+          value={css.value ?? ""}
+          multiline
+          ariaLabel="Html css"
+          placeholder=".root { … }"
+          onCommit={(next) => patch({ css: next })}
+        />
+      </InspectorRow>
+    </InspectorSection>
+  );
+}

package/src/panels/inspector/design/InstanceSection.tsx

@@ -0,0 +1,302 @@
+// Only for INSTANCE layers, and absent otherwise — the rule every other
+// kind-specific section here follows.
+//
+// ROWS COME FROM THE CONTRACT, NEVER FROM THE STORED VALUES. The widget for a
+// prop is decided by its ControlSpec through the shared `PropControl` cluster,
+// the same dispatch the motion editor's InstanceSection and the canvas editor's
+// EmbedSection use — so a colour prop gets a swatch and an enum gets its
+// options here for exactly the reason it does there. Deriving rows from
+// `instance.props` instead would show only props somebody had already changed,
+// with no kinds, no ranges and no labels.
+//
+// WHICH contract: the LIVE one from the registry when the project still has the
+// component, falling back to the `{source:"snapshot"}` contract the document
+// itself carries. The inspector is an authoring surface — it should offer what
+// the component accepts NOW — while the snapshot keeps a component that has
+// left the project editable rather than dead.
+//
+// ── QUARANTINE, WHICH IS THE POINT OF THE WHOLE SECTION ─────────────────
+//
+// A stored prop whose contract key has gone is NOT dropped and NOT hidden. The
+// rename/orphan planner (`instancePropPlan`, which is
+// `resolveTracksAgainstContract` underneath) classifies it, and it gets its own
+// row above the contract rows: the value it is holding, what it was keyed on,
+// and the two things an author can do about it. Both documented real-world
+// versions of the alternative are silent data loss — Figma text properties
+// resetting on publish, After Effects expression controls vanishing with their
+// keyframes — so the value survives every save, every rebind and every reload
+// until an author deletes it on purpose.
+//
+// DEFAULTS ARE NOT WRITTEN. A prop with no stored value shows the spec's
+// default and stores nothing; `buildProps` supplies it at render time. Baking
+// defaults in at insert time would freeze them against later edits to the
+// component itself.
+import { useEffect, useState } from "react";
+import {
+  instanceContractDrift,
+  instancePropPlan,
+  orphanedPropKeys,
+} from "@dailies-studio/shot/doc";
+import type { Contract, ControlSpec } from "@dailies-studio/contract";
+import type { Value } from "@dailies-studio/engine";
+import { InspectorRow, InspectorSection, NumberField, PropControl } from "@dailies-studio/ui";
+import { useShotEditor, useStore } from "../../../state/context.js";
+import { NO_SCRUB, useSelectedLayers } from "../useDocWrite.js";
+
+/** Contract kinds whose values are engine `Value`s and can therefore live in
+ *  `instance.props`. Everything else is composite (curve/gradient — those ride
+ *  an encoded string, which IS a Value) or not a value at all (slot/event). */
+const VALUE_KINDS = new Set([
+  "number",
+  "string",
+  "color",
+  "boolean",
+  "enum",
+  "asset",
+  "vec2",
+  "vec3",
+  "quaternion",
+  "curve",
+  "gradient",
+]);
+
+/** Contract order, then key — the motion inspector's `orderedSpecs` rule. */
+function orderedSpecs(contract: Contract): ControlSpec[] {
+  return Object.values(contract.keys).sort((a, b) => {
+    const ao = a.order ?? Number.MAX_SAFE_INTEGER;
+    const bo = b.order ?? Number.MAX_SAFE_INTEGER;
+    return ao !== bo ? ao - bo : a.key.localeCompare(b.key);
+  });
+}
+
+/** PropControl hands back whatever its widget produced; only engine Values may
+ *  be stored. Anything else is refused rather than written, because the next
+ *  save would refuse the document. */
+function asValue(raw: unknown): Value | null {
+  if (typeof raw === "number" && Number.isFinite(raw)) return raw;
+  if (typeof raw === "string" || typeof raw === "boolean") return raw;
+  if (
+    Array.isArray(raw) &&
+    (raw.length === 2 || raw.length === 3 || raw.length === 4) &&
+    raw.every((n) => typeof n === "number" && Number.isFinite(n))
+  ) {
+    return raw as Value;
+  }
+  return null;
+}
+
+export function InstanceSection() {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const contracts = useShotEditor((s) => s.contracts);
+  const library = useShotEditor((s) => s.library);
+  const libraryLoaded = useShotEditor((s) => s.libraryLoaded);
+  const libraryError = useShotEditor((s) => s.libraryError);
+  const layers = useSelectedLayers();
+  const [rebinding, setRebinding] = useState(false);
+  const [rebindError, setRebindError] = useState<string | null>(null);
+
+  // ONE layer at a time, deliberately. An instance's props belong to one
+  // component's contract, so a fan-out across a mixed selection would write
+  // keys the other layers' components never had.
+  const layer = layers.length === 1 && layers[0]?.kind === "instance" ? layers[0] : null;
+  const componentId = layer?.instance.component ?? null;
+
+  // Hooks stay unconditional (the section mounts for every selection and
+  // self-gates on kind).
+  useEffect(() => {
+    if (componentId === null) return;
+    void store.loadContract(componentId);
+    if (!store.getState().libraryLoaded) void store.refreshLibrary();
+  }, [store, componentId]);
+
+  if (doc === null || layer === null || componentId === null) return null;
+
+  const row = library.find((r) => r.id === componentId);
+  const ref = layer.instance.contract;
+  const snapshot: Contract | null = ref?.source === "snapshot" ? ref.contract : null;
+  const live = contracts[componentId];
+  const contract = live ?? snapshot;
+  // Judged only once the registry has ANSWERED — and "answered" means a
+  // successful fetch, not merely "loading finished". A FAILED fetch also ends
+  // with an empty list, and reporting every instance as an unknown component
+  // over a transient network failure would tell the author to delete work.
+  const drift = libraryLoaded
+    ? instanceContractDrift(doc, (id) => {
+        const r = library.find((c) => c.id === id);
+        const c = contracts[id];
+        return r === undefined || c === undefined
+          ? null
+          : { availability: r.contractAvailability ?? "inferred", contract: c };
+      }).filter((d) => d.layerId === layer.id)
+    : [];
+  const missing = libraryLoaded && row === undefined;
+
+  const specs = contract === null || contract === undefined ? [] : orderedSpecs(contract);
+  // The quarantine list. Against the LIVE contract when there is one: a key is
+  // only orphaned relative to what the component accepts today.
+  const orphans =
+    live === undefined ? [] : orphanedPropKeys(instancePropPlan(layer.instance.props, snapshot ?? live, live));
+
+  return (
+    <InspectorSection title="Component" persistKey="shot:instance">
+      <InspectorRow label="Module">
+        <span className="insp-fixed" title={componentId}>
+          {row?.name ?? componentId}
+        </span>
+      </InspectorRow>
+
+      {/* mo1's "Play" on an instance, and the reason it is a NUMBER rather than
+          a button: retriggering a module is an offset, not state, so it stays a
+          pure function of the frame and an out-of-order export samples the same
+          pose a scrub does. Negative holds the module at its own frame 0 until
+          the scene catches up. */}
+      <InspectorRow label="Clock">
+        <NumberField
+          value={layer.instance.clockOffsetFrames ?? 0}
+          ariaLabel="Instance clock offset"
+          unit="f"
+          step={1}
+          onCommit={(next) => store.setInstanceClockOffset(layer.id, next)}
+        />
+      </InspectorRow>
+
+      {libraryError !== null && (
+        <div className="insp-inline-error">
+          {`The component registry could not be read (${libraryError}) — this instance cannot be checked.`}
+        </div>
+      )}
+
+      {missing && (
+        <div className="insp-notice is-warn">
+          {`${componentId} is not in the component registry. The generated scene's import will not ` +
+            `resolve and the save will be refused until the component is back or the layer is removed.`}
+        </div>
+      )}
+
+      {drift.length > 0 && (
+        <div className="insp-notice is-warn">
+          {drift.map((d) => (
+            <span key={d.code}>{d.message}</span>
+          ))}
+          {/* The ONE action drift offers, and it is never automatic. Re-binding
+              is a statement that the component's CURRENT contract is the one
+              this instance means; the planner moves every renamed key's value
+              and leaves every orphan exactly where it is. */}
+          <button
+            className="btn"
+            disabled={rebinding}
+            data-instance-rebind={layer.id}
+            title="Re-record this instance's contract hash and source from the project's current component, following any renames"
+            onClick={() => {
+              setRebinding(true);
+              void store.rebindInstance(layer.id).then((err) => {
+                setRebinding(false);
+                setRebindError(err);
+              });
+            }}
+          >
+            Accept current contract
+          </button>
+        </div>
+      )}
+      {rebindError !== null && <div className="insp-inline-error">{rebindError}</div>}
+
+      {orphans.map((key) => (
+        <div key={`orphan:${key}`} className="insp-notice is-warn" data-instance-orphan={key}>
+          {`"${key}" is not a prop of this component any more. Its value is kept here and is not ` +
+            `passed to the component — nothing was deleted.`}
+          <button
+            className="btn"
+            data-instance-drop={key}
+            title={`Delete the stored value for "${key}". This is the only thing that ever removes it.`}
+            onClick={() => store.clearInstanceProp(layer.id, key)}
+          >
+            Discard
+          </button>
+        </div>
+      ))}
+
+      {contract === null || contract === undefined ? (
+        <div className="insp-notice">
+          No contract available for this component — its props cannot be edited here.
+        </div>
+      ) : (
+        <>
+          {live === undefined && snapshot !== null && (
+            <div className="insp-notice">
+              Showing the contract snapshot recorded with this layer (the project&apos;s copy is not
+              loaded).
+            </div>
+          )}
+          {specs.length === 0 && <div className="insp-notice">This component has no props.</div>}
+          {specs.map((spec) => (
+            <InstancePropRow
+              key={spec.key}
+              layerId={layer.id}
+              spec={spec}
+              value={layer.instance.props[spec.key]}
+            />
+          ))}
+        </>
+      )}
+    </InspectorSection>
+  );
+}
+
+function InstancePropRow(props: { layerId: string; spec: ControlSpec; value: Value | undefined }) {
+  const { layerId, spec } = props;
+  const store = useStore();
+  const [error, setError] = useState<string | null>(null);
+  // An unset prop shows (and edits from) the spec's default — the value the
+  // runtime's `buildProps` will supply — without ever storing it. `slot` and
+  // `event` carry no default at all, hence the presence check.
+  const value = props.value ?? ("default" in spec ? spec.default : undefined);
+  const storable = VALUE_KINDS.has(spec.kind);
+  const inherited = props.value === undefined;
+
+  const commit = (raw: unknown): void => {
+    const next = asValue(raw);
+    if (next === null) {
+      setError("instance props hold engine values only (number, string, boolean, vec2/3/4)");
+      return;
+    }
+    setError(null);
+    store.setInstanceProp(layerId, spec.key, next);
+  };
+
+  return (
+    <div className={`insp-prop${inherited ? " is-inherited" : ""}`}>
+      <div className="insp-row">
+        {spec.kind !== "number" && (
+          <span className="insp-label" title={spec.description ?? spec.key}>
+            {spec.label ?? spec.key}
+          </span>
+        )}
+        <div className="insp-control">
+          {storable ? (
+            <PropControl spec={spec} value={value} commit={commit} scrub={NO_SCRUB} />
+          ) : (
+            <span
+              className="badge"
+              title={`"${spec.kind}" values are not engine Values, so they cannot be stored on an instance — set this prop inside the component itself.`}
+            >
+              {spec.kind} — not editable on an instance
+            </span>
+          )}
+          {!inherited && (
+            <button
+              className="btn"
+              data-instance-reset={spec.key}
+              title={`Clear the stored value for "${spec.label ?? spec.key}" and fall back to the component's default.`}
+              onClick={() => store.clearInstanceProp(layerId, spec.key)}
+            >
+              Reset
+            </button>
+          )}
+        </div>
+      </div>
+      {error !== null && <div className="insp-inline-error">{error}</div>}
+    </div>
+  );
+}

package/src/panels/inspector/design/MediaSection.tsx

@@ -0,0 +1,251 @@
+// Only for IMAGE and VIDEO layers, and absent otherwise — the same rule
+// MeshSection and TypographySection follow, for the same reason: a media
+// section over a rectangle is six controls that write nothing.
+//
+// ── ONE SECTION FOR 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
+// controls they share are authored once here, and the two fields that differ —
+// `alt` on an image, `offsetFrames` on a video — are rows that only their own
+// kind renders rather than a second section.
+//
+// ── WHY THIS SECTION HAD TO EXIST ───────────────────────────────────────
+//
+// `fit`, `crop`, `alt` and `offsetFrames` were all reachable ONLY through an
+// MCP call. A document can therefore hold a crop or a source offset that the
+// author cannot see, let alone undo, from the chrome that wrote the layer.
+import {
+  InspectorRow,
+  InspectorSection,
+  NumberField,
+  PropertyGrid,
+  SegmentedControl,
+  TextField,
+} from "@dailies-studio/ui";
+import type { Crop, ImageLayer3D, Layer3D, LayerFit, VideoLayer3D } from "@dailies-studio/shot/doc";
+import { useSelectedLayers, useSelectionValue, useSelectionWrite } from "../useDocWrite.js";
+
+/**
+ * The two content blocks as ONE shape.
+ *
+ * An intersection rather than a union: every field is either shared or optional
+ * on both sides, so one mapper can carry a write to whichever block the layer
+ * has, and the per-kind fields are gated by the ROW that offers them instead of
+ * by a second block type and a second mapper.
+ */
+type MediaBlock = ImageLayer3D["image"] & VideoLayer3D["video"];
+
+/** The fits, as data. `satisfies` pins them to the schema's own union, so a fit
+ *  renamed there is a compile error here rather than a segment that writes a
+ *  value the rasterizer ignores. */
+const FITS = ["fill", "fit", "stretch"] as const satisfies readonly LayerFit[];
+
+/** What `+` adds: the identity crop. Adding one must not move a pixel — the
+ *  author is opening the control, not asking for a change — and "the whole
+ *  source" is exactly what an absent crop already means. */
+const FULL_CROP: Crop = { x: 0, y: 0, w: 1, h: 1 };
+
+export function MediaSection() {
+  const write = useSelectionWrite();
+  const layers = useSelectedLayers();
+  const media = useSelectionValue((layer) => mediaOf(layer));
+  // The first media layer in the selection, which is what the title names and
+  // what the per-kind rows are chosen by. Read from the LIST rather than from
+  // `media.value` (which is the first SELECTED layer's, media or not), so a
+  // rect clicked before an image does not empty the section.
+  const subject = layers.find(isMedia);
+  if (subject === undefined) return null;
+  const block = mediaOf(subject);
+  if (block === undefined) return null;
+
+  /** Every write goes through one mapper, KIND-GUARDED INSIDE IT: the seam fans
+   *  out over the whole selection, and a rect has no `fit` to set.
+   *
+   *  `only` narrows that fan-out further, and the per-kind rows MUST use it.
+   *  The rows are chosen by the first media layer in the selection, but the
+   *  write reaches every one of them — so with an image and a video selected
+   *  together, the image's Alt row would otherwise write `alt` into the video
+   *  block and the video's Start row would write `offsetFrames` into the image.
+   *  `MediaBlock` is the intersection of the two, which makes both foreign keys
+   *  type-legal, and `validateShotDoc` is deliberately not stricter than the
+   *  resolver, so nothing downstream refuses them. They surface much later, as
+   *  an excess-property error in the generated `satisfies Doc3D` literal. */
+  const patch = (next: (media: MediaBlock) => MediaBlock, only?: "image" | "video"): void =>
+    write((layer) =>
+      layer.kind === "image" && only !== "video"
+        ? { ...layer, image: next(layer.image) }
+        : layer.kind === "video" && only !== "image"
+          ? { ...layer, video: next(layer.video) }
+          : layer,
+    );
+
+  const setCrop = (key: keyof Crop, value: number): void =>
+    patch((m) => ({ ...m, crop: { ...(m.crop ?? FULL_CROP), [key]: clamp01(value) } }));
+
+  const crop = block.crop;
+
+  return (
+    <InspectorSection
+      title={subject.kind === "video" ? "Video" : "Image"}
+      persistKey="shot:media"
+      action={
+        <button
+          type="button"
+          className="section-action"
+          title={crop === undefined ? "Add crop" : "Remove crop"}
+          onClick={() =>
+            patch((m) => (m.crop === undefined ? { ...m, crop: FULL_CROP } : without(m, "crop")))
+          }
+        >
+          {crop === undefined ? "+" : "−"}
+        </button>
+      }
+    >
+      <InspectorRow label="Fit">
+        <SegmentedControl
+          ariaLabel="Media fit"
+          value={block.fit}
+          options={FITS.map((fit) => ({ value: fit, label: fit }))}
+          onChange={(next) => patch((m) => ({ ...m, fit: next as LayerFit }))}
+        />
+      </InspectorRow>
+
+      {/* Fractions of the SOURCE, not of the box, and y counts DOWN from the
+          top row the way a screenshot's own pixels are numbered — media.ts owns
+          the flip into uv space, so these are the numbers a design tool would
+          report for the same rectangle. */}
+      {crop !== undefined ? (
+        <PropertyGrid>
+          <InspectorRow>
+            <NumberField
+              value={crop.x}
+              mixed={media.mixed}
+              label="X"
+              ariaLabel="Crop x"
+              min={0}
+              max={1}
+              step={0.01}
+              onCommit={(next) => setCrop("x", next)}
+            />
+          </InspectorRow>
+          <InspectorRow>
+            <NumberField
+              value={crop.y}
+              mixed={media.mixed}
+              label="Y"
+              ariaLabel="Crop y"
+              min={0}
+              max={1}
+              step={0.01}
+              onCommit={(next) => setCrop("y", next)}
+            />
+          </InspectorRow>
+          <InspectorRow>
+            <NumberField
+              value={crop.w}
+              mixed={media.mixed}
+              label="W"
+              ariaLabel="Crop width"
+              min={0}
+              max={1}
+              step={0.01}
+              onCommit={(next) => setCrop("w", next)}
+            />
+          </InspectorRow>
+          <InspectorRow>
+            <NumberField
+              value={crop.h}
+              mixed={media.mixed}
+              label="H"
+              ariaLabel="Crop height"
+              min={0}
+              max={1}
+              step={0.01}
+              onCommit={(next) => setCrop("h", next)}
+            />
+          </InspectorRow>
+        </PropertyGrid>
+      ) : null}
+
+      {subject.kind === "image" ? (
+        <InspectorRow label="Alt">
+          <TextField
+            value={block.alt ?? ""}
+            ariaLabel="Alt text"
+            onCommit={(next) =>
+              patch((m) => {
+                const trimmed = next.trim();
+                // `alt: ""` is a described image whose description is empty,
+                // which assistive tech reads differently from an undescribed
+                // one. Absent is what "nothing to say" actually spells.
+                return trimmed === "" ? without(m, "alt") : { ...m, alt: trimmed };
+              }, "image")
+            }
+          />
+        </InspectorRow>
+      ) : null}
+
+      {subject.kind === "video" ? (
+        // PLACEMENT, NOT A TRIM. This is the scene frame the source's own t=0
+        // lands on, so every frame before it holds the source's FIRST frame and
+        // nothing is cut off the head. Audio's identically-named `offsetFrames`
+        // is the other thing — a trim into the source — and confusing the two
+        // is why the label says "starts at" rather than "start".
+        <InspectorRow label="Starts at" labelTitle="The scene frame this clip's first frame lands on — a delay, never a trim into the source">
+          <NumberField
+            value={block.offsetFrames ?? 0}
+            mixed={media.mixed}
+            ariaLabel="Video start frame"
+            unit="f"
+            step={1}
+            // NO `min`. NumberField clamps against it on every commit path —
+            // typing, the stepper and the drag — so `min={0}` would turn the
+            // one value this feature exists to preserve into 0 the first time
+            // the author touched the field, and the `frames === 0` branch below
+            // would then DELETE it, jumping the footage. A negative offset is
+            // what `splitScene` produces for a clip already playing at the cut,
+            // and it is untypeable, so erasing one is unrecoverable.
+            //
+            // 0 DELETES the key: absent already means "starts at frame 0", and
+            // an explicit 0 is a second way to say the same thing that codegen
+            // then prints. `Math.round` covers the only bound the save gate
+            // actually holds — the value must be an integer.
+            onCommit={(next) => {
+              const frames = Math.round(next);
+              patch(
+                (m) => (frames === 0 ? without(m, "offsetFrames") : { ...m, offsetFrames: frames }),
+                "video",
+              );
+            }}
+          />
+        </InspectorRow>
+      ) : null}
+    </InspectorSection>
+  );
+}
+
+function isMedia(layer: Layer3D): boolean {
+  return layer.kind === "image" || layer.kind === "video";
+}
+
+function mediaOf(layer: Layer3D): MediaBlock | undefined {
+  if (layer.kind === "image") return layer.image;
+  if (layer.kind === "video") return layer.video;
+  return undefined;
+}
+
+/** Drop one optional key, rather than setting it to `undefined`. Under
+ *  exactOptionalPropertyTypes those are different values, and codegen prints
+ *  the block by key order — a present-but-undefined key is a key. */
+function without(media: MediaBlock, key: "crop" | "alt" | "offsetFrames"): MediaBlock {
+  const { [key]: _drop, ...rest } = media;
+  return rest;
+}
+
+/** A crop is a fraction of the source. Past 0..1 it samples nothing, and
+ *  `cropUv` clamps anyway — so the field clamps too rather than storing a
+ *  number the renderer silently disagrees with. */
+function clamp01(value: number): number {
+  return Math.max(0, Math.min(1, value));
+}