@dailies-studio/shot-editor 0.1.0 → 0.2.0

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

@@ -0,0 +1,550 @@
+// The ONE paint control: solid, linear gradient or radial gradient, writing the
+// shot `Paint` union the rasterizer already reads.
+//
+// ── WHY THIS EXISTS ─────────────────────────────────────────────────────────
+//
+// `BackgroundPlane` has rendered linear and radial gradients for real since the
+// unify overhaul, and `paintStyle` (raster.ts) draws them for a layer fill too.
+// The chrome could not write either. Worse, both surfaces DESTROYED one: the
+// scene's Background row and the layer's Fill row were solid-only pickers whose
+// scrub and commit each wrote `{type: "solid", color}`, so a gradient authored
+// by MCP or by an agent died the first time an author touched the swatch, with
+// no undo affordance naming what was lost.
+//
+// ── WHY NOT `GradientValueEditor` FROM @dailies-studio/ui ───────────────────
+//
+// It exists, it is exported, and it is the wrong shape. It takes contract's
+// `GradientValue` (`{kind: "gradient", stops, space?, hueFixup?}`) and its
+// validator refuses anything whose `kind` is not `"gradient"` AND refuses any
+// extra key, so a shot `Paint` (`{type: "linear-gradient", angleDeg, stops}`)
+// handed to it renders an invalid badge and never opens. Adapting both ways is
+// more code than the rows below, and it would import two knobs that are DEAD
+// here: `space` and `hueFixup` describe an interpolation the shot lane does not
+// perform. `paintStyle` uses canvas `addColorStop`, which is plain sRGB, and
+// nothing in packages/shot reads either field. It also has no angle control, so
+// the one thing a linear gradient most needs would have to be written anyway.
+//
+// So: the stops list is authored directly in the shape the renderer reads, and
+// each stop keeps its own ColorField and At field.
+//
+// ── THE GRADIENT BAR, AND WHY ITS RAMP IS REPAINTED HERE ───────────────────
+//
+// Over the stop rows sits `GradientBar` from @dailies-studio/ui: the design's
+// 28px ramp with one draggable marker per stop. It draws the stops along one
+// axis from 0 to 1, NOT the paint's geometry, so the angle-convention drift
+// that kept a CSS preview of the whole fill out of this file does not arise:
+// there is no angle in it to get wrong.
+//
+// Two things about it are adapted rather than taken whole:
+//
+//   ITS RAMP IS OKLCH, THE CANVAS IS sRGB. The bar previews through contract's
+//     `gradientPreviewCss`, which interpolates in OKLCH, while `paintStyle`'s
+//     `addColorStop` blends plain sRGB. A ramp that brightens through the
+//     middle where the picture darkens is a preview lying about the picture,
+//     so the wrapper sets `--paint-ramp` to a plain CSS `linear-gradient` (sRGB
+//     by default, the canvas's space) and inspector-object.css paints it over
+//     the bar's own fill. The bar's markers, hit area and keyboard are its own.
+//   ITS VALUES MUST BE CONTRACT-VALID. Its algebra (composite.ts) refuses a
+//     stop that is not hex or a list that is not strictly ascending, and a shot
+//     `Paint` accepts both (style.ts `paintProblem` asks a stop for an `at` in
+//     0..1 and a colour `colourProblem` passes: any non-empty string but a CSS
+//     image, so a named colour is legal). The bar renders only over stops it can edit;
+//     the rows below it edit everything, so no paint loses a control.
+//
+// A bar drag is ONE scrub. The bar reports `onChange` per move and `onCommit`
+// at release, and a cancel restores the press stops through `onChange` with no
+// commit at all, so the scrub opens on the first `onChange`, closes with a
+// commit on `onCommit`, and closes WITHOUT one on the gesture's own abort
+// events (Escape, pointercancel, lost capture). A discrete bar edit (a press on
+// the empty ramp, a Delete, an arrow nudge) is `onChange` then `onCommit` in
+// one tick, which is the same bracket, and one undo entry either way.
+//
+// ── STORE-FREE, LIKE EVERY REUSABLE WIDGET IN THIS CHROME ──────────────────
+//
+// A scene background writes through `patchScene`; a layer fill writes through
+// `useSelectionWrite`. Neither is reachable from a shared component, and both
+// have to route through their own edit path so `routeSceneEdit` /
+// `routeLayerEdit` can turn the write into a keyframe when a track is armed.
+// So this takes handlers and holds no document state. What it does keep is view
+// state no document field records: which stop the bar has selected, and the
+// bar's open scrub between its first move and its release.
+import { useEffect, useRef, useState } from "react";
+import type { CSSProperties } from "react";
+import {
+  ColorField,
+  FieldLabels,
+  GradientBar,
+  IconMinus,
+  IconPlus,
+  InspectorRow,
+  MIN_GRADIENT_STOPS,
+  NumberField,
+  SegmentedControl,
+  tryParseHex,
+  useLocked,
+} from "@dailies-studio/ui";
+import { validateGradient } from "@dailies-studio/contract";
+import type { GradientStop } from "@dailies-studio/contract";
+import { formatHex } from "@dailies-studio/engine";
+import type { Paint } from "@dailies-studio/shot/doc";
+
+/** The three paint kinds as data, pinned to the schema's own union so a variant
+ *  added or renamed there is a compile error here rather than a segment that
+ *  writes a `type` the rasterizer falls through on. */
+const PAINT_TYPES = ["solid", "linear-gradient", "radial-gradient"] as const satisfies readonly Paint["type"][];
+
+const PAINT_LABELS: Record<Paint["type"], string> = {
+  solid: "Solid",
+  "linear-gradient": "Linear",
+  "radial-gradient": "Radial",
+};
+
+/** The events that end a bar drag WITHOUT a commit. Escape is read on the
+ *  window's capture phase because `startDrag` stops its propagation there
+ *  (after cancelling, so the restore has already arrived); the pointer events
+ *  in the bubble phase, so the marker's own handler has run first. */
+const ABORT_BUBBLE = ["pointerup", "pointercancel", "lostpointercapture"] as const;
+
+/** One control's edit, applied by the caller to EACH paint it writes. A whole
+ *  paint built from the lead would copy the lead's colour, stops and angle onto
+ *  every selected layer when the author changed one field. */
+export type PaintEdit = (prev: Paint) => Paint;
+
+export interface PaintRowsProps {
+  /** The lead paint, for display. */
+  value: Paint;
+  /** Every paint the rows write to, for the Mixed reads. Defaults to `value`. */
+  all?: readonly Paint[];
+  /** Every write, as an edit. The caller decides whether that lands on a scene
+   *  or on a selection, and whether it becomes a keyframe. */
+  onCommit: (edit: PaintEdit) => void;
+  /** The DRAG half. A ColorPicker's SV square, hue bar and alpha bar never call
+   *  `commit` while the pointer is down (ui/ColorPicker.tsx), so without these
+   *  the thumb moves and the document does not. */
+  onScrubStart: () => void;
+  onScrub: (edit: PaintEdit) => void;
+  onScrubEnd: (commit: boolean) => void;
+  /** Prefixes every control's accessible name, because two of these can be on
+   *  screen at once (a scene background and a layer fill). ACCESSIBLE NAMES
+   *  ONLY: what the type row READS is `label` below. */
+  ariaPrefix: string;
+  /**
+   * The VISIBLE label of the type row. "Type" unless the caller says otherwise,
+   * and `null` for none at all.
+   *
+   * The callers want different words because the row sits under different
+   * headings. The shot's rows sit under a section called "Shot" beside a Lens
+   * and a Duration, where a bare "Type" offering Solid/Linear/Radial names
+   * nothing it is the type OF, so `SceneSection` passes "Background".
+   * `FillSection`'s heading already says Fill, and the design draws its type
+   * row as a bare chip track with no label, so it passes `null`: labelling it
+   * read Fill / Type / Color straight down the rail, three lines for one control.
+   */
+  label?: string | null;
+  /** The keyframe diamond for the SOLID colour, when the caller has one, in
+   *  the colour's box. A gradient has no single colour and therefore no
+   *  diamond: `background.color` and `paint.fill.color` are colour tracks, and
+   *  the track table refuses them over a gradient for exactly that reason
+   *  (tracks.ts). */
+  solidTrailing?: React.ReactNode;
+  /**
+   * A solid's OPACITY row, editing the colour's alpha byte. Opt-in, because a
+   * scene background is the frame's ground and has nothing behind it for an
+   * alpha to show; a layer fill does. It writes the same colour the picker's
+   * alpha bar does, so it is one more door onto `color`, not a second field.
+   */
+  showOpacity?: boolean;
+  /** The Opacity box's accessories: the colour's diamond again (the alpha
+   *  byte of the same colour, keyed by the same track), without the expose
+   *  pin the colour's box already carries, because a pin publishes the whole
+   *  track and one per track is the rule (KeyframeDot). */
+  opacityTrailing?: React.ReactNode;
+  /** The paint holds no alpha (a scene background is opaque by contract): the
+   *  pickers hide their alpha bar and every colour they commit is `#rrggbb`. */
+  opaque?: boolean;
+}
+
+/**
+ * A colour committed over a selection whose ALPHAS differ, onto one layer's
+ * own colour (`lead` is the colour the field shows, the lead layer's).
+ *
+ * Whether the author meant to set the alpha is read off the alpha byte the
+ * field was showing. A commit that left it where it was (a hue or SV drag, a
+ * typed six-digit hex, which ColorField fills from that alpha) changed the
+ * RGB only, so each layer keeps its own alpha. A commit that moved it (a typed
+ * eight-digit hex, the picker's alpha bar or its A field) sets that alpha on
+ * every layer: keeping each layer's own there meant typing eight digits, the
+ * ColorField's one way to set both, could not set the alpha at all.
+ *
+ * ponytail: the commit carries a colour and not how it was made, so an
+ * eight-digit hex whose alpha equals the lead's reads as untouched and each
+ * layer keeps its own. The Opacity (or Alpha) field beside the colour reads
+ * Mixed and sets one alpha on all; a commit that says whether its alpha was
+ * typed is a ColorField change.
+ */
+export function colorOverMixedAlpha(committed: string, lead: string, own: string): string {
+  const next = tryParseHex(committed);
+  const mine = tryParseHex(own);
+  if (next === null || mine === null) return committed;
+  // An unreadable lead is alpha 1, ColorField's own fallback for six digits.
+  const shown = tryParseHex(lead)?.alpha ?? 1;
+  const byte = (alpha: number): number => Math.round(alpha * 255);
+  return byte(next.alpha) === byte(shown) ? formatHex({ ...next, alpha: mine.alpha }) : committed;
+}
+
+/** Can the bar edit these stops? Its algebra is contract's, so contract says. */
+function barCanEdit(stops: readonly GradientStop[]): boolean {
+  return stops.length >= MIN_GRADIENT_STOPS && validateGradient({ kind: "gradient", stops }) === null;
+}
+
+/** The ramp as the CANVAS blends it: plain sRGB, which is a CSS gradient's
+ *  default space. See the header for why the bar's own OKLCH fill is covered. */
+function srgbRamp(stops: readonly GradientStop[]): string {
+  return `linear-gradient(to right, ${stops.map((s) => `${s.color} ${s.at * 100}%`).join(", ")})`;
+}
+
+/**
+ * Where "+ Stop" puts a stop: the middle of the WIDEST gap, coloured as the
+ * canvas already paints that point, so adding one moves no pixel and the new
+ * marker lands where it can be seen and grabbed. Null when the stops are not
+ * hex (nothing to blend) or have no gap to split.
+ */
+function splitWidestGap(stops: readonly GradientStop[]): GradientStop[] | null {
+  let best = -1;
+  for (let i = 0; i + 1 < stops.length; i++) {
+    const gap = stops[i + 1]!.at - stops[i]!.at;
+    if (gap > 0 && (best < 0 || gap > stops[best + 1]!.at - stops[best]!.at)) best = i;
+  }
+  if (best < 0) return null;
+  const a = tryParseHex(stops[best]!.color);
+  const b = tryParseHex(stops[best + 1]!.color);
+  if (a === null || b === null) return null;
+  const mix = (x: number, y: number): number => (x + y) / 2;
+  const stop = {
+    at: mix(stops[best]!.at, stops[best + 1]!.at),
+    color: formatHex({ r: mix(a.r, b.r), g: mix(a.g, b.g), b: mix(a.b, b.b), alpha: mix(a.alpha, b.alpha) }),
+  };
+  return [...stops.slice(0, best + 1), stop, ...stops.slice(best + 1)];
+}
+
+export function PaintRows(props: PaintRowsProps) {
+  const { value, onCommit, onScrub, onScrubStart, onScrubEnd, ariaPrefix, label = "Type" } = props;
+  const all = props.all ?? [value];
+  const stops = value.type === "solid" ? [] : value.stops;
+  const [picked, setPicked] = useState(0);
+  const selected = Math.min(picked, Math.max(0, stops.length - 1));
+  // A VIEWER'S PANEL LOCKS EVERY VERB THAT WRITES. The widgets read the lock
+  // themselves; the stop verbs here are plain buttons, so they read it here.
+  const locked = useLocked();
+
+  // MIXED, per field. A selection whose TYPES differ shows the type row alone:
+  // no other row means the same thing on all of them.
+  const typeMixed = all.some((p) => p.type !== value.type);
+  const solidRgb = value.type === "solid" ? tryParseHex(value.color) : null;
+  const rgbOf = (p: Paint): string | null => {
+    const rgb = p.type === "solid" ? tryParseHex(p.color) : null;
+    return rgb === null ? null : `${rgb.r},${rgb.g},${rgb.b}`;
+  };
+  const colorMixed = all.some((p) => rgbOf(p) !== rgbOf(value));
+  const alphaMixed = all.some((p) => (p.type === "solid" ? tryParseHex(p.color)?.alpha : null) !== solidRgb?.alpha);
+  const angleMixed = all.some((p) => p.type !== "linear-gradient" || value.type !== "linear-gradient" || p.angleDeg !== value.angleDeg);
+  const stopsKey = JSON.stringify(stops);
+  const stopsMixed = all.some((p) => p.type === "solid" || JSON.stringify(p.stops) !== stopsKey);
+
+  /** A stops edit over each paint's OWN stops. The whole array is written: the
+   *  renderer reads the array, so a merged single stop would be left behind. */
+  const onStops = (edit: (stops: GradientStop[]) => GradientStop[]): PaintEdit =>
+    (prev) => (prev.type === "solid" ? prev : { ...prev, stops: edit(prev.stops) });
+
+  const setStop = (index: number, patch: Partial<GradientStop>): PaintEdit =>
+    onStops((own) => own.map((stop, i) => (i === index ? { ...stop, ...patch } : stop)));
+
+  // THE BAR'S SCRUB, open between its first `onChange` and its commit or
+  // abort. See the header. A ref, because the bracket spans pointer events
+  // and must not wait on a render.
+  const barScrub = useRef<((commit: boolean) => void) | null>(null);
+  const live = useRef(props);
+  live.current = props;
+  useEffect(() => () => barScrub.current?.(false), []);
+
+  const barChange = (next: GradientStop[]): void => {
+    if (barScrub.current === null) {
+      const onEscape = (e: KeyboardEvent): void => {
+        if (e.key === "Escape") end(false);
+      };
+      const onAbort = (): void => end(false);
+      const end = (commit: boolean): void => {
+        window.removeEventListener("keydown", onEscape, true);
+        for (const type of ABORT_BUBBLE) window.removeEventListener(type, onAbort);
+        barScrub.current = null;
+        live.current.onScrubEnd(commit);
+      };
+      window.addEventListener("keydown", onEscape, true);
+      for (const type of ABORT_BUBBLE) window.addEventListener(type, onAbort);
+      barScrub.current = end;
+      onScrubStart();
+    }
+    onScrub(onStops(() => next));
+  };
+
+  const barCommit = (next: GradientStop[]): void => {
+    if (barScrub.current !== null) barScrub.current(true);
+    else onCommit(onStops(() => next));
+  };
+
+  /** The alpha byte on each paint's OWN colour. */
+  const withAlpha = (pct: number): PaintEdit => (prev) => {
+    const rgb = prev.type === "solid" ? tryParseHex(prev.color) : null;
+    return rgb === null
+      ? prev
+      : { type: "solid", color: formatHex({ ...rgb, alpha: Math.min(1, Math.max(0, pct / 100)) }) };
+  };
+  /** A colour pick; where opacities differ, each paint keeps its own alpha
+   *  unless the pick moved the alpha the field shows (`colorOverMixedAlpha`). */
+  const solidColor = (color: string): PaintEdit => (prev) =>
+    prev.type !== "solid"
+      ? prev
+      : {
+          type: "solid",
+          color: alphaMixed && value.type === "solid" ? colorOverMixedAlpha(color, value.color, prev.color) : color,
+        };
+  const withAngle = (angleDeg: number): PaintEdit => (prev) =>
+    prev.type === "linear-gradient" ? { ...prev, angleDeg } : prev;
+
+  // The house segmented control, the one look every switch in the chrome
+  // shares (widgets.css): the chosen type is the flat tile, not an accent.
+  const typeRow = (
+    <SegmentedControl
+      ariaLabel={`${ariaPrefix} paint type`}
+      // An unmatched value is how a segmented control says Mixed.
+      value={typeMixed ? "" : value.type}
+      options={PAINT_TYPES.map((type) => ({ value: type, label: PAINT_LABELS[type] }))}
+      onChange={(next) => onCommit((prev) => convert(prev, next as Paint["type"]))}
+    />
+  );
+  const opaque = props.opaque === true;
+
+  return (
+    <>
+      {/* THE LABEL IS THE CALLER'S. "Background" over Solid/Linear/Radial in
+          the shot section, none at all under a heading that already names the
+          paint. The accessible name keeps its own longer spelling either way,
+          which is why it is a second prop and not this one. */}
+      {label === null ? <InspectorRow>{typeRow}</InspectorRow> : <InspectorRow label={label}>{typeRow}</InspectorRow>}
+
+      {typeMixed ? null : (
+      <>
+      {value.type === "solid" ? (
+        <InspectorRow>
+          <ColorField
+            value={value.color}
+            mixed={colorMixed}
+            ariaLabel={`${ariaPrefix} colour`}
+            {...(opaque ? { opaque: true } : {})}
+            trailing={props.solidTrailing}
+            scrub={{
+              start: onScrubStart,
+              move: (color) => onScrub(solidColor(String(color))),
+              end: onScrubEnd,
+            }}
+            commit={(color) => onCommit(solidColor(color))}
+          />
+        </InspectorRow>
+      ) : null}
+
+      {/* OPACITY IS THE ALPHA BYTE. Only over a colour the engine can read:
+          an unparseable string has no byte to set, and a field that wrote one
+          would replace the author's colour with a guess. It is keyed by the
+          colour's track, so its box carries the colour's diamond. */}
+      {value.type === "solid" && props.showOpacity === true && solidRgb !== null ? (
+        <InspectorRow>
+          <NumberField
+            value={Math.round(solidRgb.alpha * 100)}
+            mixed={alphaMixed}
+            label="Opacity"
+            ariaLabel={`${ariaPrefix} opacity`}
+            unit="%"
+            min={0}
+            max={100}
+            step={1}
+            trailing={props.opacityTrailing}
+            onScrubStart={onScrubStart}
+            onScrub={(pct) => onScrub(withAlpha(pct))}
+            onScrubEnd={onScrubEnd}
+            onCommit={(pct) => onCommit(withAlpha(pct))}
+          />
+        </InspectorRow>
+      ) : null}
+
+      {/* ANGLE IS LINEAR-ONLY. `paintStyle` builds a radial gradient from the
+          box centre outward, so there is no direction for an angle to name and
+          a field here would write a number nothing reads. */}
+      {value.type === "linear-gradient" ? (
+        <InspectorRow>
+          <NumberField
+            value={value.angleDeg}
+            mixed={angleMixed}
+            label="Angle"
+            ariaLabel={`${ariaPrefix} gradient angle`}
+            unit="°"
+            step={1}
+            // NO min/max, and no wrap. The axis is `cos`/`sin` of the angle, so
+            // 370 and 10 draw the same picture and clamping would only stop a
+            // drag from crossing the seam mid-gesture.
+            onScrubStart={onScrubStart}
+            onScrub={(angleDeg) => onScrub(withAngle(angleDeg))}
+            onScrubEnd={onScrubEnd}
+            onCommit={(angleDeg) => onCommit(withAngle(angleDeg))}
+          />
+        </InspectorRow>
+      ) : null}
+
+      {/* STOPS THAT DIFFER have no one list to show, so the stop controls
+          wait until the selection agrees. */}
+      {value.type !== "solid" && stopsMixed ? (
+        <p className="insp-note">The selected gradients have different stops.</p>
+      ) : null}
+
+      {value.type !== "solid" && !stopsMixed && barCanEdit(stops) ? (
+        <div className="paint-gradient" style={{ "--paint-ramp": srgbRamp(stops) } as CSSProperties}>
+          <GradientBar
+            stops={stops}
+            selected={selected}
+            onSelect={setPicked}
+            onChange={barChange}
+            onCommit={barCommit}
+            ariaLabel={`${ariaPrefix} gradient stops`}
+          />
+        </div>
+      ) : null}
+
+      {value.type !== "solid" && !stopsMixed
+        ? stops.map((stop, index) => (
+            <InspectorRow
+              // Index and not the stop's colour: two stops may share a colour,
+              // and a key that changes as the author drags a hue remounts the
+              // picker mid-gesture and drops the pointer capture.
+              key={index}
+              className={`paint-stop${index === selected ? " is-selected" : ""}`}
+              label={value.type === "radial-gradient" ? (index === 0 ? "Centre" : "Stop") : "Stop"}
+              trailing={
+                // Never below the minimum. One stop is a solid written the
+                // long way, and `paintStyle` on an EMPTY stops array draws
+                // nothing at all, which is a scene that renders as the clear
+                // colour with no control on screen explaining why.
+                //
+                // A VERB IN THE BOX, not a fourth diamond: the house accessory
+                // (`.insp-key`) at rest, the danger ink on hover (`is-danger`),
+                // and inside the stop's own box, so the row is as wide with it
+                // as without it.
+                stops.length > MIN_GRADIENT_STOPS ? (
+                  <button
+                    type="button"
+                    className="insp-key is-danger"
+                    title="Remove stop"
+                    aria-label={`Remove ${ariaPrefix} stop ${index + 1}`}
+                    disabled={locked}
+                    onClick={() => onCommit(onStops((own) => own.filter((_, i) => i !== index)))}
+                  >
+                    <IconMinus />
+                  </button>
+                ) : undefined
+              }
+            >
+              {/* A FIXED 28px BOX holding two values: the At field keeps its
+                  in-box prefix in every field-label mode, since a name above
+                  it would land inside the stop's own box. */}
+              <FieldLabels value="compact">
+                <ColorField
+                  value={stop.color}
+                  ariaLabel={`${ariaPrefix} stop ${index + 1} colour`}
+                  {...(opaque ? { opaque: true } : {})}
+                  scrub={{
+                    start: onScrubStart,
+                    move: (color) => onScrub(setStop(index, { color: String(color) })),
+                    end: onScrubEnd,
+                  }}
+                  commit={(color) => onCommit(setStop(index, { color }))}
+                />
+                <NumberField
+                  value={stop.at}
+                  label="At"
+                  ariaLabel={`${ariaPrefix} stop ${index + 1} position`}
+                  min={0}
+                  max={1}
+                  // A SNAP, not a speed: the drag and the arrow keys land on
+                  // twenty positions, a ramp an author can put where they
+                  // meant; 0.01 would be a hundred and land on none of them.
+                  // It is also the quantum this chrome already picked for its
+                  // other bounded 0..1 fields, the media crop's and
+                  // EffectsSection's amounts. The bar above is the fine
+                  // control.
+                  step={0.05}
+                  onScrubStart={onScrubStart}
+                  onScrub={(at) => onScrub(setStop(index, { at }))}
+                  onScrubEnd={onScrubEnd}
+                  onCommit={(at) => onCommit(setStop(index, { at }))}
+                />
+              </FieldLabels>
+            </InspectorRow>
+          ))
+        : null}
+
+      {value.type !== "solid" && !stopsMixed ? (
+        <InspectorRow className="paint-add-stop">
+          <button
+            type="button"
+            className="btn"
+            aria-label={`Add ${ariaPrefix} stop`}
+            disabled={locked}
+            // Adding a stop moves NO pixel: the author is opening a control,
+            // not asking for a change. It splits the widest gap at the colour
+            // the canvas already paints there, so the new marker is visible
+            // and grabbable on the bar. Over stops the engine cannot blend it
+            // falls back to appending at 1 in the last stop's colour, which
+            // is equally invisible, and dragging it left is the edit.
+            onClick={() => {
+              const split = splitWidestGap(stops);
+              if (split !== null) {
+                setPicked(split.findIndex((s, i) => s !== stops[i]));
+                onCommit(onStops(() => split));
+                return;
+              }
+              onCommit(onStops((own) => [...own, { at: 1, color: own[own.length - 1]?.color ?? "#ffffff" }]));
+            }}
+          >
+            <IconPlus />
+            Stop
+          </button>
+        </InspectorRow>
+      ) : null}
+      </>
+      )}
+    </>
+  );
+}
+
+/**
+ * The same paint as another type, keeping whatever survives the change.
+ *
+ * A type switch must not be a data-loss event the author cannot see coming, so
+ * a solid becomes a ramp that STARTS at its own colour, and a gradient becomes
+ * the solid of its first stop (which is what the old solid-only swatch already
+ * displayed for one, so the picture the author was looking at is the picture
+ * they get). The stops survive a linear/radial switch untouched, because both
+ * arms carry the identical array and only the geometry differs.
+ */
+export function convert(paint: Paint, type: Paint["type"]): Paint {
+  if (paint.type === type) return paint;
+  if (type === "solid") {
+    return { type: "solid", color: paint.type === "solid" ? paint.color : (paint.stops[0]?.color ?? "#000000") };
+  }
+  const stops =
+    paint.type === "solid"
+      ? [{ at: 0, color: paint.color }, { at: 1, color: "#000000" }]
+      : paint.stops.map((stop) => ({ ...stop }));
+  // `angleDeg` is not preserved across a round trip through radial, because a
+  // radial gradient has nowhere to keep it. 90 is a top-to-bottom ramp, which
+  // is the one every background in this lane has ever wanted.
+  return type === "linear-gradient" ? { type, angleDeg: 90, stops } : { type, stops };
+}