@dailies-studio/shot-editor 0.1.0 → 0.2.0

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

@@ -0,0 +1,235 @@
+// A layer riding a spline: which spline, how far along, and how it turns.
+//
+// EVERY ROW READS ITS OWN SCALAR across the selection, one `useSelectionValue`
+// per field (ClonerSection's shape), and shows Mixed where the layers
+// disagree. The rows used to read the FIRST layer's follow and show its
+// progress, offset and bank as if the selection shared them, while every
+// write fanned out to all of them. A layer in the selection that follows
+// nothing reads `undefined`, which disagrees with any value: honest, because
+// a write finds nothing on that layer to land on either.
+import {
+  Combobox,
+  InspectorRow,
+  InspectorSection,
+  NumberField,
+  SegmentedControl,
+  useLocked,
+  wordOptions,
+} from "@dailies-studio/ui";
+import {
+  SPLINE_DOMAINS,
+  SPLINE_FORWARD_AXES,
+  SPLINE_ORIENTATIONS,
+  meshPrimitiveOf,
+  // The path table's bounds, read by `FollowNumber` below instead of restated
+  // here: `numberRange` is what the keyframe gate clamps against, so a second
+  // copy in the chrome is a pill that offers a number the diamond then refuses.
+  trackablePath,
+} from "@dailies-studio/shot/doc";
+import type {
+  Layer3D,
+  SplineDomain,
+  SplineFollow,
+  SplineForwardAxis,
+  SplineOrientation,
+} from "@dailies-studio/shot/doc";
+import { useShotEditor } from "../../../state/context.js";
+import { useSelectedLayers, useSelectionScrub, useSelectionValue, useSelectionWrite } from "../useDocWrite.js";
+import { KeyframeDot } from "../KeyframeDot.js";
+import { splineSourceIsSafe } from "../../../state/splineRefs.js";
+
+/** How a widget with no `mixed` of its own says Mixed: an empty value selects
+ *  no segment, and a combobox shows its placeholder over it. */
+const NO_VALUE = "";
+const MIXED = "Mixed";
+
+export function SplineFollowSection() {
+  const write = useSelectionWrite();
+  const layers = useSelectedLayers();
+  const doc = useShotEditor((state) => state.doc);
+  const sceneId = useShotEditor((state) => state.sceneId);
+  const editingDef = useShotEditor((state) => state.editingDef);
+  // Add follow and Remove follow are plain buttons, so they read a viewer's
+  // lock here; every row is a widget that reads it itself.
+  const locked = useLocked();
+  // One scalar per row, read before any early return (they are hooks).
+  const spline = useSelectionValue((layer) => layer.splineFollow?.spline);
+  const domain = useSelectionValue((layer) => followOf(layer, (f) => f.domain ?? "full"));
+  const orientation = useSelectionValue((layer) => followOf(layer, (f) => f.orientation ?? "path"));
+  const forwardAxis = useSelectionValue((layer) => followOf(layer, (f) => f.forwardAxis ?? "+x"));
+  const progress = useSelectionValue((layer) => followOf(layer, (f) => f.progress ?? 0));
+  const progressOffset = useSelectionValue((layer) => followOf(layer, (f) => f.progressOffset ?? 0));
+  const bank = useSelectionValue((layer) => followOf(layer, (f) => f.bankDeg ?? 0));
+  if (layers.length === 0 || doc === null) return null;
+  const home = editingDef === null
+    ? (sceneId === null ? undefined : doc.scenesById[sceneId])
+    : doc.components?.[editingDef];
+  const selected = new Set(layers.map((layer) => layer.id));
+  const splines = Object.values(home?.layersById ?? {})
+    .filter((layer) =>
+      layer.kind === "mesh" &&
+      meshPrimitiveOf(layer.mesh)?.kind === "spline" &&
+      !selected.has(layer.id) &&
+      splineSourceIsSafe(home?.layersById ?? {}, [...selected], layer.id, "follow"),
+    )
+    .map((layer) => ({ value: layer.id, label: layer.label }));
+  // The LEAD's follow decides whether there is a follow to edit at all; each
+  // row then reads its own field across the whole selection.
+  const follow = layers[0]?.splineFollow;
+  const clonerDistributionOwnsPath = layers.some(
+    (layer) => layer.kind === "cloner" && layer.cloner.mode.kind === "spline",
+  );
+  const patch = (build: (current: SplineFollow | undefined) => SplineFollow | undefined): void =>
+    write((layer) => withFollow(layer, build));
+  const set = <K extends keyof SplineFollow>(key: K, value: SplineFollow[K]): void =>
+    patch((current) => current === undefined ? undefined : { ...current, [key]: value });
+
+  // Nothing to follow and nothing following: the section would be one
+  // disabled button, so it withholds itself (see `sectionsFor`).
+  if (follow === undefined && splines.length === 0 && !clonerDistributionOwnsPath) return null;
+  if (follow === undefined) {
+    return (
+      <InspectorSection className="insp-object" title="Spline follow" persistKey="shot:spline-follow">
+        <InspectorRow label="Path">
+          <button
+            type="button"
+            className="btn"
+            disabled={locked || splines[0] === undefined || clonerDistributionOwnsPath}
+            title={
+              clonerDistributionOwnsPath
+                ? "A cloner cannot use spline follow and spline distribution together"
+                : undefined
+            }
+            onClick={() => {
+              const first = splines[0]?.value;
+              // A layer that already follows keeps its own follow.
+              if (first !== undefined) patch((current) => current ?? { spline: first, progress: 0, orientation: "path" });
+            }}
+          >
+            {clonerDistributionOwnsPath
+              ? "Spline distribution active"
+              : splines.length === 0
+                ? "No spline available"
+                : "Add follow"}
+          </button>
+        </InspectorRow>
+      </InspectorSection>
+    );
+  }
+
+  const targetOptions = splines.some((option) => option.value === follow.spline)
+    ? splines
+    : [{ value: follow.spline, label: home?.layersById[follow.spline]?.label ?? follow.spline }, ...splines];
+  return (
+    <InspectorSection className="insp-object" title="Spline follow" persistKey="shot:spline-follow">
+      <InspectorRow label="Path">
+        <Combobox
+          options={targetOptions}
+          value={spline.mixed ? NO_VALUE : follow.spline}
+          ariaLabel="Follow spline"
+          placeholder={spline.mixed ? MIXED : "Choose spline"}
+          onChange={(next) => set("spline", next)}
+        />
+      </InspectorRow>
+      <InspectorRow label="Domain">
+        <SegmentedControl
+          ariaLabel="Follow domain"
+          value={domain.mixed ? NO_VALUE : (follow.domain ?? "full")}
+          options={wordOptions(SPLINE_DOMAINS)}
+          onChange={(next) => set("domain", next as SplineDomain)}
+        />
+      </InspectorRow>
+      <FollowNumber path="splineFollow.progress" label="Progress" value={follow.progress ?? 0} mixed={progress.mixed} step={0.01} edit={(f, value) => ({ ...f, progress: value })} />
+      <FollowNumber path="splineFollow.progressOffset" label="Offset" value={follow.progressOffset ?? 0} mixed={progressOffset.mixed} step={0.01} edit={(f, value) => ({ ...f, progressOffset: value })} />
+      <InspectorRow label="Orient">
+        <SegmentedControl
+          ariaLabel="Follow orientation"
+          value={orientation.mixed ? NO_VALUE : (follow.orientation ?? "path")}
+          options={wordOptions(SPLINE_ORIENTATIONS)}
+          onChange={(next) => set("orientation", next as SplineOrientation)}
+        />
+      </InspectorRow>
+      {(follow.orientation ?? "path") === "path" ? (
+        <>
+          <InspectorRow label="Forward">
+            <Combobox
+              options={SPLINE_FORWARD_AXES.map((value) => ({ value, label: value.toUpperCase() }))}
+              value={forwardAxis.mixed ? NO_VALUE : (follow.forwardAxis ?? "+x")}
+              ariaLabel="Follow forward axis"
+              placeholder={forwardAxis.mixed ? MIXED : "Axis"}
+              onChange={(next) => set("forwardAxis", next as SplineForwardAxis)}
+            />
+          </InspectorRow>
+          <FollowNumber path="splineFollow.bankDeg" label="Bank" value={follow.bankDeg ?? 0} mixed={bank.mixed} step={1} unit="°" edit={(f, value) => ({ ...f, bankDeg: value })} />
+        </>
+      ) : null}
+      <InspectorRow>
+        <button type="button" className="btn" disabled={locked} onClick={() => patch(() => undefined)}>
+          Remove follow
+        </button>
+      </InspectorRow>
+    </InspectorSection>
+  );
+}
+
+/** One follow field as a scalar, or undefined for a layer that follows
+ *  nothing, so the selection read stays a primitive. */
+function followOf<T>(layer: Layer3D, read: (follow: SplineFollow) => T): T | undefined {
+  return layer.splineFollow === undefined ? undefined : read(layer.splineFollow);
+}
+
+/** The ONE follow edit, so a drag's move and its release land the same
+ *  document. Clearing deletes the key rather than writing `undefined`. */
+function withFollow(layer: Layer3D, build: (current: SplineFollow | undefined) => SplineFollow | undefined): Layer3D {
+  const next = build(layer.splineFollow);
+  if (next === undefined) {
+    if (layer.splineFollow === undefined) return layer;
+    const { splineFollow: _drop, ...rest } = layer;
+    return rest as Layer3D;
+  }
+  return { ...layer, splineFollow: next } as Layer3D;
+}
+
+/** A row whose HARD limits default to the path table's own `numberRange`, the
+ *  rule `MeshNumber` (MeshSection) states in full. An explicit `min`/`max`
+ *  still wins, for a chrome limit that is deliberately tighter. Its typed
+ *  value and its drag are one builder (`edit`) over each layer's own follow,
+ *  and a layer that follows nothing is left alone by both. */
+function FollowNumber({ label, value, mixed, unit, min, max, step, path, edit }: {
+  label: string;
+  value: number;
+  mixed: boolean;
+  path: string;
+  unit?: string;
+  min?: number;
+  max?: number;
+  step: number;
+  edit: (follow: SplineFollow, value: number) => SplineFollow;
+}) {
+  const write = useSelectionWrite();
+  const build = (layer: Layer3D, next: number): Layer3D =>
+    withFollow(layer, (current) => (current === undefined ? undefined : edit(current, next)));
+  const scrub = useSelectionScrub((layer, raw) => build(layer, Number(raw)));
+  const tabled = trackablePath(path)?.numberRange;
+  const lo = min ?? tabled?.min;
+  const hi = max ?? tabled?.max;
+  return (
+    <InspectorRow>
+      <NumberField
+        value={value}
+        mixed={mixed}
+        label={label}
+        ariaLabel={label}
+        {...(unit === undefined ? {} : { unit })}
+        {...(lo === undefined ? {} : { min: lo })}
+        {...(hi === undefined ? {} : { max: hi })}
+        step={step}
+        trailing={<KeyframeDot path={path} label={label} />}
+        onCommit={(next) => write((layer) => build(layer, next))}
+        onScrubStart={scrub.start}
+        onScrub={scrub.move}
+        onScrubEnd={scrub.end}
+      />
+    </InspectorRow>
+  );
+}

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

@@ -1,70 +1,175 @@
-import { ColorPicker, InspectorRow, InspectorSection, NumberField, SegmentedControl } from "@dailies-studio/ui";
-import type { Stroke } from "@dailies-studio/shot/doc";
-import { NO_SCRUB, useSelectionValue, useSelectionWrite } from "../useDocWrite.js";
+// The stroke: a header switch, Width and Alpha as a pair, the colour row, and
+// Align. Paper's Stroke card puts the pair first: Width is what an outline is
+// tuned by, and the colour row under it reads as Fill's does.
+//
+// ── THE SWITCH IS `Stroke.hidden`, NOT ADD/REMOVE ──────────────────────
+//
+// The section used to carry a `+`/`-` action that added a default stroke or
+// deleted the key. Deleting threw away the width, colour, align and dash, so
+// "turn the outline off for a moment" cost the author the outline. Schema v36
+// gave the stroke a `hidden` flag every renderer reads through `drawnStroke`,
+// and the switch writes only that flag:
+//
+//   - Off writes `hidden: true` on every selected layer that HAS a stroke. A
+//     layer with none is left alone: hiding a stroke nobody drew would add a
+//     document key with no picture behind it.
+//   - On deletes the `hidden` key rather than writing `false`, so off then on
+//     is the same bytes as before, and a layer with no stroke gets the 1px
+//     default (what the old `+` did).
+//
+// A selection whose strokes disagree reads Mixed, and the click turns every
+// layer on: "on for all" is the action a half-lit set asks for, and the one
+// policy every inspector switch keeps.
+//
+// ── ALPHA IS THE COLOUR'S ALPHA BYTE ───────────────────────────────────
+//
+// There is no `Stroke.alpha`. A second alpha would multiply with the colour's,
+// so the picker's alpha bar and this field would each show a number that is not
+// what is drawn. The field edits `#rrggbbaa` in place, per layer, keeping each
+// layer's own RGB, and is keyed through the `paint.stroke.color` track, so its
+// box carries THAT diamond, the colour row's, and Width's box its own: one
+// diamond for the pair keyed the width alone, beside an Alpha it did not key.
+// The colour row's box keeps the track's one expose pin. Over a colour the
+// engine cannot read it is disabled: there is no byte to set.
+//
+// ── CAP AND JOIN (schema v39) ──────────────────────────────────────────
+//
+// Two segmented rows after Align, in Align's row style. An absent field shows
+// what the raster DRAWS for it (`capOf`/`joinOf`): a path layer's butt, every
+// other stroked kind's round. Hidden while any text layer is selected: a text
+// layer's stroke outlines its plate, a closed box with no ends to cap.
+import {
+  ColorField,
+  InspectorRow,
+  InspectorSection,
+  NumberField,
+  SegmentedControl,
+  Toggle,
+  tryParseHex,
+} from "@dailies-studio/ui";
+import { formatHex } from "@dailies-studio/engine";
+import { KeyframeDot } from "../KeyframeDot.js";
+import type { Layer3D, Stroke } from "@dailies-studio/shot/doc";
+import { STROKE_CAPS, STROKE_JOINS } from "@dailies-studio/shot/doc";
+import { useSelectionScrub, useSelectionValue, useSelectionWrite } from "../useDocWrite.js";
+import { colorOverMixedAlpha } from "./PaintRows.js";
 
+/** 1px, and deliberately NOT insert.ts's `DRAW_STROKE` (4px): this is the
+ *  hairline outline added around a shape that already draws, while that one IS
+ *  the drawn mark of the line, arrow and path tools. Do not merge them. */
 const DEFAULT_STROKE: Stroke = { color: "#ffffff", widthPx: 1, align: "center" };
 
 export function StrokeSection() {
   const write = useSelectionWrite();
-  const present = useSelectionValue((layer) => layer.paint.stroke !== undefined);
+  const drawn = useSelectionValue((layer) => layer.paint.stroke !== undefined && layer.paint.stroke.hidden !== true);
   const color = useSelectionValue((layer) => layer.paint.stroke?.color ?? DEFAULT_STROKE.color);
+  // The colour row shows six digits, the RGB: Mixed is asked of THAT, and the
+  // alpha byte has its own field (and its own Mixed) beside the width.
+  const rgb = useSelectionValue((layer) => rgbKey(layer.paint.stroke?.color ?? DEFAULT_STROKE.color));
   const width = useSelectionValue((layer) => layer.paint.stroke?.widthPx ?? DEFAULT_STROKE.widthPx);
+  const alpha = useSelectionValue((layer) => alphaPct(layer.paint.stroke?.color ?? DEFAULT_STROKE.color));
   const align = useSelectionValue((layer) => layer.paint.stroke?.align ?? DEFAULT_STROKE.align);
+  const cap = useSelectionValue(capOf);
+  const join = useSelectionValue(joinOf);
+  const text = useSelectionValue((layer) => layer.kind === "text");
+  const on = drawn.value === true && !drawn.mixed;
+  // A colour pick keeps each layer's OWN alpha where the alphas differ, as the
+  // fill's does: a six-digit hex typed over a selection whose opacities
+  // disagree would otherwise copy the lead's alpha onto every stroke. A pick
+  // that moved the alpha the field shows (eight digits, the alpha bar) sets it
+  // on all of them (`colorOverMixedAlpha`).
+  const withColor = (layer: Layer3D, hex: string): Layer3D =>
+    withStroke(layer, {
+      color: alpha.mixed
+        ? colorOverMixedAlpha(hex, color.value ?? DEFAULT_STROKE.color, layer.paint.stroke?.color ?? DEFAULT_STROKE.color)
+        : hex,
+    });
 
-  const patch = (next: Partial<Stroke>): void =>
-    write((layer) => ({
-      ...layer,
-      paint: { ...layer.paint, stroke: { ...DEFAULT_STROKE, ...layer.paint.stroke, ...next } },
-    }));
+  // THE DRAG HALF, for the controls that HAVE a drag. The picker's three bars
+  // and the two fields' labels report through `scrub.move` and never call
+  // `commit` while the pointer is down: with the commit half alone the thumb
+  // moved and the document did not.
+  const colorScrub = useSelectionScrub((layer, raw) => withColor(layer, String(raw)));
+  const widthScrub = useSelectionScrub((layer, raw) => withStroke(layer, { widthPx: Number(raw) }));
+  const alphaScrub = useSelectionScrub((layer, raw) => withAlpha(layer, Number(raw)));
+
+  const patch = (next: Partial<Stroke>): void => write((layer) => withStroke(layer, next));
 
   return (
     <InspectorSection
       title="Stroke"
+      className="insp-object"
       persistKey="shot:stroke"
       action={
-        <button
-          type="button"
-          className="section-action"
-          title={present.value === true ? "Remove stroke" : "Add stroke"}
-          onClick={() =>
-            present.value === true
-              ? write((layer) => ({ ...layer, paint: withoutStroke(layer.paint) }))
-              : patch({})
-          }
-        >
-          {present.value === true ? "−" : "+"}
-        </button>
+        <Toggle
+          className="insp-stroke-switch"
+          checked={on}
+          mixed={drawn.mixed}
+          ariaLabel="Stroke"
+          onChange={(next) => write((layer) => (next ? shown(layer) : hidden(layer)))}
+        />
       }
     >
-      {present.value === true ? (
+      {/* Rows while ANY selected stroke draws, so a half-lit selection can
+          still be edited; an all-off selection shows the switch alone. */}
+      {drawn.value === true || drawn.mixed ? (
         <>
-          <InspectorRow label="Color">
-            <ColorPicker
-              value={color.value ?? DEFAULT_STROKE.color}
-              ariaLabel="Stroke colour"
-              scrub={NO_SCRUB}
-              commit={(hex) => patch({ color: hex })}
-            />
+          <InspectorRow>
+            <div className="insp-vec">
+              <NumberField
+                value={width.value ?? 1}
+                mixed={width.mixed}
+                label="Width"
+                ariaLabel="Stroke width"
+                unit="px"
+                min={0}
+                // A negative width is not a stroke; there is no upper limit.
+                step={0.5}
+                trailing={<KeyframeDot path="paint.stroke.widthPx" />}
+                onCommit={(next) => patch({ widthPx: next })}
+                onScrubStart={widthScrub.start}
+                onScrub={widthScrub.move}
+                onScrubEnd={widthScrub.end}
+              />
+              <NumberField
+                value={alpha.value ?? 100}
+                mixed={alpha.mixed}
+                disabled={alpha.value === null}
+                label="Alpha"
+                ariaLabel="Stroke alpha"
+                unit="%"
+                min={0}
+                max={100}
+                step={1}
+                trailing={<KeyframeDot path="paint.stroke.color" pin={false} />}
+                onCommit={(pct) => write((layer) => withAlpha(layer, pct))}
+                onScrubStart={alphaScrub.start}
+                onScrub={alphaScrub.move}
+                onScrubEnd={alphaScrub.end}
+              />
+            </div>
           </InspectorRow>
           <InspectorRow>
-            <NumberField
-              value={width.value ?? 1}
-              mixed={width.mixed}
-              label="Width"
-              ariaLabel="Stroke width"
-              unit="px"
-              min={0}
-              step={0.5}
-              onCommit={(next) => patch({ widthPx: next })}
+            <ColorField
+              value={color.value ?? DEFAULT_STROKE.color}
+              mixed={rgb.mixed}
+              ariaLabel="Stroke colour"
+              scrub={colorScrub}
+              commit={(hex) => write((layer) => withColor(layer, hex))}
+              trailing={<KeyframeDot path="paint.stroke.color" />}
             />
           </InspectorRow>
           <InspectorRow label="Align">
             {/* Canvas2D only CENTRES a stroke, so inside and outside are a
-                half-width inset either way — raster.ts does that, and the three
+                half-width inset either way; raster.ts does that, and the three
                 options are honest because the raster honours all three. */}
             <SegmentedControl
               ariaLabel="Stroke align"
-              value={align.value ?? "center"}
+              /* A disagreeing selection selects NOTHING rather than showing the
+                 first layer's choice as if the others shared it: the control
+                 has no `mixed` prop, and an unmatched value is exactly how it
+                 renders "none of these". */
+              value={align.mixed ? "" : (align.value ?? "center")}
               options={[
                 { value: "inside", label: "In" },
                 { value: "center", label: "Mid" },
@@ -73,13 +178,93 @@ export function StrokeSection() {
               onChange={(next) => patch({ align: next as Stroke["align"] })}
             />
           </InspectorRow>
+          {text.value === false && !text.mixed ? (
+            <>
+              <InspectorRow label="Cap">
+                <SegmentedControl
+                  ariaLabel="Stroke cap"
+                  value={cap.mixed ? "" : (cap.value ?? "")}
+                  options={STROKE_CAPS.map((value) => ({ value, label: titleCase(value) }))}
+                  onChange={(next) => patch({ cap: next as NonNullable<Stroke["cap"]> })}
+                />
+              </InspectorRow>
+              <InspectorRow label="Join">
+                <SegmentedControl
+                  ariaLabel="Stroke join"
+                  value={join.mixed ? "" : (join.value ?? "")}
+                  options={STROKE_JOINS.map((value) => ({ value, label: titleCase(value) }))}
+                  onChange={(next) => patch({ join: next as NonNullable<Stroke["join"]> })}
+                />
+              </InspectorRow>
+            </>
+          ) : null}
         </>
       ) : null}
     </InspectorSection>
   );
 }
 
-function withoutStroke(paint: { stroke?: Stroke }): typeof paint {
-  const { stroke: _drop, ...rest } = paint;
-  return rest;
+/** The cap the raster draws: an absent field is butt on a path layer and
+ *  round on every other stroked kind (raster.ts `drawStroke`). */
+export function capOf(layer: Layer3D): NonNullable<Stroke["cap"]> {
+  return layer.paint.stroke?.cap ?? (layer.kind === "path" ? "butt" : "round");
+}
+
+/** The join the raster draws: absent is Canvas2D's miter on every kind. The
+ *  stage's analytic rect draws the same corner (shapePlane.ts `JOIN_CODE`). */
+export function joinOf(layer: Layer3D): NonNullable<Stroke["join"]> {
+  return layer.paint.stroke?.join ?? "miter";
+}
+
+function titleCase(word: string): string {
+  return word.charAt(0).toUpperCase() + word.slice(1);
+}
+
+/** The colour's alpha as a whole percent, or null when the engine cannot read
+ *  the colour. A number, so the selection read stays a primitive. */
+function alphaPct(color: string): number | null {
+  const rgb = tryParseHex(color);
+  return rgb === null ? null : Math.round(rgb.alpha * 100);
+}
+
+/** The colour's RGB as one string, its alpha left out: what the colour row
+ *  shows and compares. A colour the engine cannot read is its own text. */
+function rgbKey(color: string): string {
+  const rgb = tryParseHex(color);
+  return rgb === null ? color : `${rgb.r},${rgb.g},${rgb.b}`;
+}
+
+/** The ONE stroke edit, so a drag's move and its release land the same
+ *  document: two spellings could disagree, and the release would then appear to
+ *  undo the drag. Spread from the default because the stroke may be absent. */
+function withStroke(layer: Layer3D, next: Partial<Stroke>): Layer3D {
+  return {
+    ...layer,
+    paint: { ...layer.paint, stroke: { ...DEFAULT_STROKE, ...layer.paint.stroke, ...next } },
+  };
+}
+
+/** Set this layer's alpha byte, keeping its own RGB. An unreadable colour is
+ *  left as it is rather than replaced with a guess. */
+function withAlpha(layer: Layer3D, pct: number): Layer3D {
+  const rgb = tryParseHex(layer.paint.stroke?.color ?? DEFAULT_STROKE.color);
+  if (rgb === null) return layer;
+  return withStroke(layer, { color: formatHex({ ...rgb, alpha: Math.min(1, Math.max(0, pct / 100)) }) });
+}
+
+/** On: the key is DELETED, not set false, and the stroke's own keys are spread
+ *  without the default in front, so off then on is byte-identical whatever key
+ *  order the document had. No stroke at all gets the default. */
+function shown(layer: Layer3D): Layer3D {
+  const current = layer.paint.stroke;
+  if (current === undefined) return withStroke(layer, {});
+  const { hidden: _drop, ...stroke } = current;
+  return { ...layer, paint: { ...layer.paint, stroke } };
+}
+
+/** Off: kept and flagged, nothing else touched. A layer with no stroke has
+ *  nothing to hide. */
+function hidden(layer: Layer3D): Layer3D {
+  const current = layer.paint.stroke;
+  return current === undefined ? layer : { ...layer, paint: { ...layer.paint, stroke: { ...current, hidden: true } } };
 }

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

@@ -0,0 +1,57 @@
+// TEMPLATE FIELD (schema v50): whether a person who starts from this Project
+// swaps this layer for their own, and what the field asks for ("Screenshot",
+// "Headline", "Logo"). Only text, image and video list it (layout.ts), and it
+// describes ONE layer, so a selection of two withholds it.
+//
+// Both rows write through the store's `setLayerSwap`: one undo step each, a
+// viewer's `VIEW_ONLY`, a locked layer's refusal and the op's own (a name past
+// `SWAP_LABEL_MAX`) in the error line. The name row stays on screen while the
+// field is off, so its hint says what a name looks like, and naming the field
+// is also how it turns on.
+import { InspectorRow, InspectorSection, TextField, Toggle } from "@dailies-studio/ui";
+import { SWAP_LABEL_MAX } from "@dailies-studio/shot/doc";
+import type { Layer3D, SwapKind } from "@dailies-studio/shot/doc";
+import { useStore } from "../../../state/context.js";
+import { useSelectedLayers } from "../useDocWrite.js";
+
+/** What a field of each kind usually asks for: the empty name's hint. */
+export const SWAP_PLACEHOLDER: Record<SwapKind, string> = {
+  text: "Headline",
+  image: "Screenshot",
+  video: "Product video",
+};
+
+/** The name a field takes when it is switched on: the layer's own label on
+ *  one line, clipped to `SWAP_LABEL_MAX`, else its kind's hint. */
+export function defaultSwapLabel(layer: Layer3D): string {
+  const own = layer.label.replace(/\p{Cc}+/gu, " ").trim().slice(0, SWAP_LABEL_MAX).trim();
+  return own === "" ? SWAP_PLACEHOLDER[layer.kind as SwapKind] : own;
+}
+
+export function TemplateFieldSection() {
+  const store = useStore();
+  const layers = useSelectedLayers();
+  const layer = layers.length === 1 ? layers[0] : undefined;
+  if (layer === undefined) return null;
+  const label = layer.swap?.label;
+  return (
+    <InspectorSection className="insp-object" title="Template field" persistKey="shot:template-field">
+      <InspectorRow label="Swappable" labelTitle="People who start from this template swap this layer for their own">
+        <Toggle
+          checked={label !== undefined}
+          ariaLabel="Swappable"
+          onChange={(on) => store.setLayerSwap(layer.id, on ? defaultSwapLabel(layer) : null)}
+        />
+      </InspectorRow>
+      <InspectorRow label="Name">
+        <TextField
+          value={label ?? ""}
+          placeholder={SWAP_PLACEHOLDER[layer.kind as SwapKind]}
+          ariaLabel="Name, what the template field asks for"
+          // Blank clears the field, as switching it off does.
+          onCommit={(next) => store.setLayerSwap(layer.id, next)}
+        />
+      </InspectorRow>
+    </InspectorSection>
+  );
+}