@dailies-studio/shot-editor 0.1.0 → 0.2.0

package/src/panels/studio/ThisUsePanel.tsx

@@ -0,0 +1,679 @@
+// THIS USE (C4): one place that uses a component, and only what it changed.
+//
+// A use is named by its key (`cardUseKey`, `layerUseKey`), so every surface
+// that shows one passes the same key to the same store verbs:
+//
+//   ThisUsePanel   the whole panel: the head, then every prop of the master
+//                  with a blue dot on the ones this use changed. The
+//                  Components right panel shows it for the use picked in Every
+//                  use, and the board's card sheet shows it for a card.
+//   ThisUseBlock   the head alone, over the Studio inspector's own prop rows
+//                  for a selected component or instance layer.
+//   ComponentOriginPanel
+//                  the Components right panel when a Shot door opened the
+//                  component (C7): this use's panel, then where it sits in
+//                  that Shot and the master's other uses.
+//   InTheStudioBlock
+//                  the Studio inspector's way into Components for a selected
+//                  component or instance layer.
+//
+// Writes go through `setUseProp` (one undo step, equal-to-master stores
+// nothing), `resetComponentUse` (Reset all to master) and
+// `detachComponentUse`. A code component's contract is loaded here, since its
+// props and their defaults come from it.
+//
+// THE ROW IS `UsePropRow`, and the Studio inspector's override rows for a
+// placed Studio-made component (ComponentSection) are this same row: one use's
+// prop is one control wherever it is shown, written by one rule
+// (`writeUseValue`).
+import { useEffect, useMemo, useRef } from "react";
+import type { ReactNode } from "react";
+import { PropRow, useLocked } from "@dailies-studio/ui";
+import type { PropControlAsset, ScrubHandlers } from "@dailies-studio/ui";
+import {
+  appliedOverride,
+  defDurationFrames,
+  homeOf,
+  instanceExportOf,
+  isDefId,
+  type ComponentDef3D,
+  type ComponentUse,
+  type ExposedProp3D,
+} from "@dailies-studio/shot/doc";
+import { controlLabel, orderSpecs, type ControlSpec } from "@dailies-studio/contract";
+import { framesToSeconds, type Value } from "@dailies-studio/engine";
+import { COMPONENT_ICON } from "../../icons.js";
+import { useShotEditor, useStore } from "../../state/context.js";
+import type { ComponentUpdateRemoved, ComponentsOrigin, ComponentsSelection } from "../../state/types.js";
+import {
+  BUILTIN_NO_MASTER,
+  changeLabel,
+  contractOfUse,
+  copyUpdateOf,
+  detachRefusal,
+  isBuiltinComponent,
+  layerUseKey,
+  masterValueOf,
+  propLabelOf,
+  sameUseValue,
+  shotLabel,
+  useByKey,
+  useKeyOf,
+  usePropRefusal,
+  useRowText,
+  usesOfSubject,
+  useTitle,
+  workspaceRowOf,
+  writeUseValue,
+} from "../../state/workspace.js";
+import { clock, formatDuration, lifespanOf } from "../timeline/model.js";
+import { useScrub } from "../inspector/useDocWrite.js";
+import { exposedRowOf, masterRowValue, outsideRangeOf, projectAssetsOf, propEditOf, shownPropValue } from "../inspector/propValue.js";
+import type { ExposedRow } from "../inspector/propValue.js";
+
+/** The master a use links to, as Components selects it. */
+function masterOf(use: ComponentUse): ComponentsSelection | null {
+  if (use.def !== undefined) return { kind: "studio", def: use.def };
+  return use.component === undefined ? null : { kind: "code", module: use.component };
+}
+
+/** The use a key names in the open document, live. */
+function useUse(useKey: string): ComponentUse | null {
+  const doc = useShotEditor((s) => s.doc);
+  const contracts = useShotEditor((s) => s.contracts);
+  return useMemo(() => (doc === null ? null : useByKey(doc, useKey, contracts)), [doc, useKey, contracts]);
+}
+
+/** A code use's contract, loaded once per module. */
+function useContractOf(use: ComponentUse | null): void {
+  const store = useStore();
+  const module = use?.component ?? null;
+  useEffect(() => {
+    if (module !== null) void store.loadContract(module);
+  }, [store, module]);
+}
+
+/** "Phone 3D" and the master's version this use follows: the copy's own
+ *  version for a copied definition, else the workspace's latest. */
+function useMasterFacts(use: ComponentUse | null): { name: string; version: number | null } {
+  const doc = useShotEditor((s) => s.doc);
+  const library = useShotEditor((s) => s.library);
+  const list = useShotEditor((s) => s.workspaceComponents);
+  if (use === null || doc === null) return { name: "", version: null };
+  const sel = masterOf(use);
+  const row = workspaceRowOf(list, doc.id, sel);
+  if (use.def !== undefined) {
+    const def = doc.components?.[use.def];
+    return { name: def?.name ?? "Component", version: def?.origin?.version ?? row?.version ?? null };
+  }
+  const id = use.component ?? "";
+  return { name: library.find((r) => r.id === id)?.name ?? instanceExportOf(id), version: row?.version ?? null };
+}
+
+/**
+ * The head: "This use", where it is, what it links to, Edit master and
+ * Detach, and Update when the copy's source has a newer version.
+ */
+export function ThisUseBlock(props: { useKey: string; resetAll?: boolean; note?: string }) {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const readOnly = useShotEditor((s) => s.readOnly);
+  const use = useUse(props.useKey);
+  const facts = useMasterFacts(use);
+  // A built-in ships inside a package: nothing to open, so no Edit master.
+  const builtin = useShotEditor((s) => isBuiltinComponent(s.library, use?.component));
+  useContractOf(use);
+  if (doc === null || use === null) return null;
+  const sel = masterOf(use);
+  // A code component and a board card cannot be detached. The button says so
+  // before it is pressed (the house refusal: dimmed, still pressable, its
+  // title and its press give the reason), in the store's own words.
+  const refused = detachRefusal(use, props.useKey);
+  return (
+    <div className="this-use-head" data-testid="this-use-head">
+      <div className="this-use-titles">
+        <span className="this-use-caps">This use</span>
+        <span className="this-use-title" data-testid="this-use-title">
+          {useTitle(doc, use)}
+        </span>
+        <span className="this-use-linked" data-testid="this-use-linked">
+          Linked to {facts.name} master{facts.version === null ? "" : ` v${facts.version}`}
+        </span>
+      </div>
+      {props.note === undefined ? null : (
+        <p className="this-use-help" data-testid="this-use-note">
+          {props.note}
+        </p>
+      )}
+      {/* The house row of buttons (`.insp-buttons`): 28px house buttons that
+          share the row by their words, as every verb row in the inspector. */}
+      <div className="insp-buttons">
+        <button
+          type="button"
+          className="btn"
+          data-testid="this-use-edit-master"
+          disabled={sel === null || builtin}
+          title={builtin ? BUILTIN_NO_MASTER : "Edit the master. Props without a dot follow the change."}
+          onClick={() => {
+            if (sel !== null) void store.editComponentMaster(sel);
+          }}
+        >
+          Edit master
+        </button>
+        <button
+          type="button"
+          className="btn"
+          data-testid="this-use-detach"
+          disabled={readOnly}
+          {...(refused !== null ? { "aria-disabled": true } : {})}
+          title={refused ?? "Make this use its own copy. It stops following the master."}
+          onClick={() => store.detachComponentUse(props.useKey)}
+        >
+          Detach
+        </button>
+      </div>
+      {props.resetAll === true ? (
+        <button
+          type="button"
+          className="this-use-reset-all is-inline"
+          data-testid="this-use-reset-all"
+          disabled={readOnly || use.overrides.length === 0}
+          onClick={() => store.resetComponentUse(props.useKey)}
+        >
+          Reset all to master
+        </button>
+      ) : null}
+      {use.def === undefined ? null : <UpdateAvailable defId={use.def} />}
+    </div>
+  );
+}
+
+/**
+ * "Update available · vN" for a copied definition whose source moved on: the
+ * workspace's latest for a `cpt_` copy, the Community listing's for a `cml-`
+ * one. A code component never has one (it is live everywhere). Before an
+ * update that drops props a use changed, the list of them, then Update
+ * anyway or Cancel. A Community update always asks first, with the same
+ * list read from the listing: the server writes it, so after it comes the
+ * list again with Revert update until the next change.
+ */
+export function UpdateAvailable(props: { defId: string }) {
+  const store = useStore();
+  const def = useShotEditor((s) => s.doc?.components?.[props.defId]);
+  const list = useShotEditor((s) => s.workspaceComponents);
+  const listings = useShotEditor((s) => s.componentListingUpdates);
+  const pending = useShotEditor((s) => (s.componentUpdate?.defId === props.defId ? s.componentUpdate : null));
+  const applied = useShotEditor((s) => (s.componentUpdated?.defId === props.defId ? s.componentUpdated : null));
+  const canRevert = useShotEditor((s) => s.componentUpdated !== null && s.doc === s.componentUpdated.after && !s.readOnly);
+  const readOnly = useShotEditor((s) => s.readOnly);
+  const source = def?.origin?.source ?? null;
+  useEffect(() => {
+    if (source === null) return;
+    if (store.getState().workspaceComponents === null) void store.refreshWorkspaceComponents();
+    void store.refreshListingUpdates();
+  }, [store, source]);
+  const update = copyUpdateOf(def, list, listings);
+  if (update === null && applied === null) return null;
+  return (
+    <div className="this-use-update" data-testid="this-use-update">
+      {update === null ? null : (
+        <div className="this-use-update-row">
+          <span className="use-chip" data-testid="this-use-update-chip">
+            Update available · v{update.version}
+          </span>
+          <button
+            type="button"
+            className="use-update-button"
+            data-testid="this-use-update-apply"
+            disabled={readOnly || pending !== null}
+            onClick={() => void store.updateComponentCopy(props.defId)}
+          >
+            Update
+          </button>
+        </div>
+      )}
+      {pending === null ? null : (
+        <div className="this-use-update-confirm" data-testid="this-use-update-confirm">
+          {pending.community ? (
+            <p className="this-use-help" data-testid="this-use-update-note">
+              The server writes v{pending.version} into this Project, so Undo may not take it back. Revert update can,
+              until your next change.
+              {pending.removed === null
+                ? ` Changes with no prop in v${pending.version} are kept aside and listed after.`
+                : pending.removed.length === 0
+                  ? ""
+                  : ` These changes have no prop in v${pending.version} and are kept aside, not applied:`}
+            </p>
+          ) : (
+            <p className="this-use-help" data-testid="this-use-update-note">
+              v{pending.version} has no prop for some changes these uses made. They are kept aside, not applied:
+            </p>
+          )}
+          {pending.removed === null || pending.removed.length === 0 ? null : <RemovedList removed={pending.removed} />}
+          <div className="insp-buttons">
+            <button
+              type="button"
+              className="use-update-button"
+              data-testid="this-use-update-confirm-apply"
+              onClick={() => void store.updateComponentCopy(props.defId, true)}
+            >
+              {pending.removed === null || pending.removed.length === 0 ? "Update" : "Update anyway"}
+            </button>
+            <button
+              type="button"
+              className="btn"
+              data-testid="this-use-update-cancel"
+              onClick={() => store.cancelComponentUpdate()}
+            >
+              Cancel
+            </button>
+          </div>
+        </div>
+      )}
+      {applied === null ? null : (
+        <div className="this-use-update-confirm" data-testid="this-use-updated">
+          <p className="this-use-help" data-testid="this-use-updated-note">
+            Updated to v{applied.version}.
+            {applied.removed.length === 0 ? "" : " These changes have no prop in it and are kept aside, not applied:"}
+          </p>
+          {applied.removed.length === 0 ? null : <RemovedList removed={applied.removed} />}
+          <div className="insp-buttons">
+            {canRevert ? (
+              <button
+                type="button"
+                className="use-update-button"
+                data-testid="this-use-update-revert"
+                onClick={() => store.revertComponentUpdate()}
+              >
+                Revert update
+              </button>
+            ) : null}
+            <button
+              type="button"
+              className="btn"
+              data-testid="this-use-updated-done"
+              onClick={() => store.cancelComponentUpdate()}
+            >
+              Done
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}
+
+function RemovedList(props: { removed: readonly ComponentUpdateRemoved[] }) {
+  return (
+    <ul className="this-use-removed">
+      {props.removed.map((r) => (
+        <li key={r.where} data-testid="this-use-removed">
+          <span className="this-use-removed-where">{r.where}</span>
+          <span className="this-use-removed-keys">{r.keys.join(", ")}</span>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/** One prop of a master, as a use's row draws it. A definition's carries the
+ *  exposed record and the definition, which a stored override is read
+ *  against (`appliedOverride`: its `renamedFrom` keys, its target). */
+interface MasterProp extends ExposedRow {
+  exposed?: { prop: ExposedProp3D; def: ComponentDef3D };
+}
+
+/** The master's props, as rows: a definition's exposed props, each from what
+ *  it drives (`exposedRowOf`), or a code component's contract keys in its own
+ *  order (the live contract, else a placed layer's snapshot), every kind
+ *  listed (a slot or an event reads "set in code", as it does in the Studio).
+ *  Null while a code component's contract is not in reach. */
+function useMasterProps(use: ComponentUse | null): MasterProp[] | null {
+  const doc = useShotEditor((s) => s.doc);
+  const contracts = useShotEditor((s) => s.contracts);
+  return useMemo(() => {
+    if (use === null || doc === null) return [];
+    if (use.def !== undefined) {
+      const def = doc.components?.[use.def];
+      if (def === undefined) return [];
+      return def.exposed.map((prop) => ({ ...exposedRowOf(prop, def, doc.materials, contracts), exposed: { prop, def } }));
+    }
+    const contract = contractOfUse(doc, contracts, use);
+    if (contract === null) return null;
+    return orderSpecs(contract).map((spec) => ({ spec, opaqueColor: false, undescribed: false }));
+  }, [use, doc, contracts]);
+}
+
+/** What one use stores for one prop that reaches the screen: a definition's
+ *  override as the renderer writes it (`appliedOverride`: under a
+ *  `renamedFrom` key too, and nothing for a value it quarantines, whose row
+ *  follows the master as the usage index counts it), or a code use's prop. */
+function storedOf(use: ComponentUse, prop: MasterProp): Value | undefined {
+  return prop.exposed !== undefined
+    ? appliedOverride(prop.exposed.def, prop.exposed.prop, use.values)?.value
+    : use.values[prop.spec.key];
+}
+
+/**
+ * THE WHOLE PANEL: the head, then every prop of the master. A prop this use
+ * changed wears the blue dot and its own Reset; the rest follow the master.
+ */
+export function ThisUsePanel(props: { useKey: string; note?: string; propsLabel?: string; children?: ReactNode }) {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const contracts = useShotEditor((s) => s.contracts);
+  const readOnly = useShotEditor((s) => s.readOnly);
+  const use = useUse(props.useKey);
+  const masterProps = useMasterProps(use);
+  const assetTable = doc?.assets;
+  const assets = useMemo(() => projectAssetsOf(assetTable), [assetTable]);
+  // A contract never arrives for a component the registry no longer has: once
+  // the registry has answered without it, the panel says so rather than
+  // reading for ever.
+  const unlisted = useShotEditor(
+    (s) => s.libraryLoaded && use?.component !== undefined && !s.library.some((r) => r.id === use.component),
+  );
+  if (use === null || doc === null) {
+    return (
+      <section className="this-use" data-testid="this-use">
+        <p className="insp-empty" data-testid="this-use-gone">
+          This use is gone. It was deleted or detached.
+        </p>
+      </section>
+    );
+  }
+  return (
+    <section className="this-use" data-testid="this-use" aria-label="This use">
+      <ThisUseBlock useKey={props.useKey} {...(props.note === undefined ? {} : { note: props.note })} />
+      <div className="this-use-props">
+        <div className="this-use-props-head">
+          <span className="this-use-caps">{props.propsLabel ?? "Props"}</span>
+          <button
+            type="button"
+            className="this-use-reset-all"
+            data-testid="this-use-reset-all"
+            disabled={readOnly || use.overrides.length === 0}
+            onClick={() => store.resetComponentUse(props.useKey)}
+          >
+            Reset all to master
+          </button>
+        </div>
+        {masterProps === null ? (
+          <p className="insp-empty" data-testid="this-use-props-unread">
+            {unlisted
+              ? "This component is not in the project's registry, so its props cannot be read."
+              : "Reading its props…"}
+          </p>
+        ) : masterProps.length === 0 ? (
+          <p className="insp-empty">This component has no props.</p>
+        ) : (
+          masterProps.map((prop) => (
+            <UsePropRow
+              key={prop.spec.key}
+              useKey={props.useKey}
+              row={prop}
+              stored={storedOf(use, prop)}
+              master={masterValueOf(doc, contracts, use, prop.spec.key)}
+              assets={assets}
+            />
+          ))
+        )}
+        <p className="this-use-help">Blue dot: changed here only. Props without a dot follow the master when you edit it.</p>
+      </div>
+      {props.children}
+    </section>
+  );
+}
+
+/**
+ * C7: the right panel while a Shot door's component is on Preview. This use
+ * first (its props change this Shot only), then where the layer sits in the
+ * Shot, read-only (moving and timing it is the Studio's job), then the
+ * master's other uses.
+ */
+export function ComponentOriginPanel(props: { origin: ComponentsOrigin }) {
+  const { origin } = props;
+  return (
+    <ThisUsePanel useKey={origin.useKey} note="Changes here apply to this Shot only." propsLabel="Props · this use">
+      <InTheShot useKey={origin.useKey} />
+      <OtherUses origin={origin} />
+    </ThisUsePanel>
+  );
+}
+
+/** "Placed at" and "On screen" for the layer a use names. */
+function InTheShot(props: { useKey: string }) {
+  const doc = useShotEditor((s) => s.doc);
+  const use = useUse(props.useKey);
+  if (doc === null || use === null || use.layerId === undefined) return null;
+  const container = use.sceneId ?? use.inDef ?? null;
+  const layer = container === null ? undefined : homeOf(doc, container)?.layersById[use.layerId];
+  if (container === null || layer === undefined) return null;
+  const def = isDefId(container) ? doc.components?.[container] : undefined;
+  const length = def !== undefined ? defDurationFrames(def) : (doc.scenesById[container]?.durationFrames ?? 1);
+  const life = lifespanOf(layer, length);
+  const [x, y, z] = layer.transform.position;
+  const round = (n: number): number => Math.round(n);
+  return (
+    <div className="this-use-props" data-testid="origin-in-the-shot">
+      <div className="this-use-props-head">
+        <span className="this-use-caps">In the Shot</span>
+      </div>
+      <dl className="origin-facts">
+        <dt>Placed at</dt>
+        <dd data-testid="origin-placed-at">
+          {round(x)}, {round(y)}, {round(z)}
+        </dd>
+        <dt>On screen</dt>
+        <dd data-testid="origin-on-screen">
+          {clock(life.in, doc.fps)} to {clock(life.out, doc.fps)} ·{" "}
+          {formatDuration(framesToSeconds(life.out - life.in, doc.fps))}
+        </dd>
+      </dl>
+      <p className="this-use-help">Move and time it in the Studio after Back to Shot.</p>
+    </div>
+  );
+}
+
+/** The master's other uses in this document, with what each changed. */
+function OtherUses(props: { origin: ComponentsOrigin }) {
+  const doc = useShotEditor((s) => s.doc);
+  const contracts = useShotEditor((s) => s.contracts);
+  const { sel, useKey } = props.origin;
+  const others = useMemo(
+    () => (doc === null ? [] : usesOfSubject(doc, sel, contracts).filter((u) => useKeyOf(u) !== useKey)),
+    [doc, sel, contracts, useKey],
+  );
+  if (doc === null) return null;
+  const master: Pick<ComponentUse, "def" | "component"> = sel.kind === "studio" ? { def: sel.def } : { component: sel.module };
+  const labelOf = (key: string): string => propLabelOf(doc, contracts, master, key);
+  return (
+    <div className="this-use-props" data-testid="origin-other-uses">
+      <div className="this-use-props-head">
+        <span className="this-use-caps">Other uses</span>
+      </div>
+      {others.length === 0 ? (
+        <p className="insp-empty">Only used here.</p>
+      ) : (
+        <ul className="origin-uses">
+          {others.map((u) => {
+            const text = useRowText(doc, u);
+            return (
+              <li key={useKeyOf(u)} className="origin-use" data-testid="origin-other-use">
+                <span className="origin-use-title">{text.title}</span>
+                <span className="origin-use-changes">{changeLabel(u, labelOf)}</span>
+              </li>
+            );
+          })}
+        </ul>
+      )}
+    </div>
+  );
+}
+
+/**
+ * THE STUDIO'S WAY INTO COMPONENTS for one selected component or instance
+ * layer: it opens that component standalone, on Preview, with Back to Shot
+ * (`openComponentContext`, the double-click's verb).
+ */
+export function InTheStudioBlock(props: { sceneId: string; layerId: string }) {
+  const store = useStore();
+  const doc = useShotEditor((s) => s.doc);
+  const use = useUse(layerUseKey(props.sceneId, props.layerId));
+  const facts = useMasterFacts(use);
+  const builtin = useShotEditor((s) => isBuiltinComponent(s.library, use?.component));
+  if (doc === null || use === null) return null;
+  return (
+    <div className="in-the-studio" data-testid="in-the-studio">
+      <span className="this-use-caps">In the Studio · {shotLabel(doc, props.sceneId)}</span>
+      <div className="in-the-studio-row">
+        <span className="in-the-studio-icon" aria-hidden="true">
+          {COMPONENT_ICON}
+        </span>
+        <span className="in-the-studio-name" data-testid="in-the-studio-name">
+          {facts.name}
+        </span>
+      </div>
+      <button
+        type="button"
+        className="in-the-studio-open"
+        data-testid="open-in-components"
+        disabled={builtin}
+        title={builtin ? BUILTIN_NO_MASTER : "See it alone in Components"}
+        onClick={() => void store.openComponentContext(props.layerId)}
+      >
+        Open in Components →
+      </button>
+      <p className="this-use-help">Or double-click it on the stage. Both land here.</p>
+    </div>
+  );
+}
+
+/** What an animated prop's row says, read-only. */
+const ANIMATED_HERE = "Animated in the Shot: edit it there";
+
+/**
+ * A use's DRAG, through the same rule as its commit (`writeUseValue`), inside
+ * the store's scrub bracket, so the whole gesture is one undo step. A refusal
+ * (a locked layer, a value the prop cannot hold) writes nothing and is said
+ * ONCE, at the release, rather than per pointer event or not at all: a thumb
+ * that moved while the document did not, with no reason given, read as a
+ * broken control.
+ */
+function useUseScrub(useKey: string, spec: ControlSpec, fallback: unknown): ScrubHandlers {
+  const store = useStore();
+  const refusal = useRef<string | null>(null);
+  const scrub = useScrub((doc, raw) => {
+    const edit = propEditOf(spec, raw, fallback);
+    if (edit.kind === "refused") {
+      refusal.current = edit.reason;
+      return doc;
+    }
+    const out = writeUseValue(doc, store.getState().contracts, useKey, spec.key, edit.kind === "set" ? edit.value : null);
+    refusal.current = out.refusal;
+    return out.doc;
+  });
+  return {
+    ...scrub,
+    end: (commit) => {
+      scrub.end(commit);
+      if (commit && refusal.current !== null) store.reportError(refusal.current);
+      refusal.current = null;
+    },
+  };
+}
+
+/**
+ * ONE PROP OF ONE USE: the master's value until this use changes it, then the
+ * blue dot and its own Reset. The board's component sheet, Components' THIS
+ * USE and the Studio inspector's override rows for a placed Studio-made
+ * component (ComponentSection) all draw this row.
+ *
+ * READ-ONLY, with the reason, for a prop the use cannot change here: an
+ * animated instance prop (only its keyframes change it, in the Shot), and a
+ * prop nothing in reach can describe (`ExposedRow.undescribed`).
+ */
+export function UsePropRow(props: {
+  useKey: string;
+  row: ExposedRow;
+  /** What the use stores for the prop that reaches the screen (`storedOf`:
+   *  read through `renamedFrom`, a quarantined value read as none). */
+  stored: Value | undefined;
+  /** The master's value (`masterValueOf`): what the use follows while it
+   *  stores nothing, and what a value equal to it is stored as. */
+  master: Value | undefined;
+  assets: readonly PropControlAsset[];
+}) {
+  const { useKey, row, stored, master } = props;
+  const { spec } = row;
+  const store = useStore();
+  const locked = useLocked();
+  const label = controlLabel(spec);
+  const animated = useShotEditor((s) => (s.doc === null ? null : usePropRefusal(s.doc, useKey, spec.key, label)));
+  // What the row shows while the use stores nothing: the master's value, what
+  // this use draws then (`masterRowValue`), so an inherited row reads what is
+  // on screen even after the master's field was edited on its own layer.
+  const fallback = masterRowValue(spec, master);
+  const changed = stored !== undefined && !(master !== undefined && sameUseValue(stored, master, spec.kind));
+  const scrub = useUseScrub(useKey, spec, fallback);
+  const commit = (raw: unknown): void => {
+    const edit = propEditOf(spec, raw, fallback);
+    if (edit.kind === "refused") store.reportError(edit.reason);
+    else store.setUseProp(useKey, spec.key, edit.kind === "set" ? edit.value : null);
+  };
+  const readOnly = animated !== null || row.undescribed;
+  // A stored value outside a range the component narrowed (or a hand edit
+  // put there), said under the row with the verb that brings it inside.
+  // Not while the row is read-only: an animated prop's keyframes are its
+  // value, and an undescribed one has no range to speak of.
+  const outside = readOnly ? null : outsideRangeOf(spec, stored);
+  return (
+    <PropRow
+      spec={spec}
+      value={shownPropValue(spec, stored ?? fallback)}
+      commit={commit}
+      scrub={scrub}
+      changed={changed}
+      inherited={stored === undefined}
+      // A stored value is an opinion even when it matches the master, and
+      // only a clear makes the use follow the master's next edit. An animated
+      // prop's clear is refused by the write itself, so it offers none.
+      {...(stored !== undefined && animated === null
+        ? {
+            reset: {
+              onReset: () => store.setUseProp(useKey, spec.key, null),
+              title: "Follow the master again",
+              props: { "data-testid": `this-use-reset-${spec.key}` },
+            },
+          }
+        : {})}
+      {...(readOnly ? { readOnly: true } : {})}
+      {...(animated !== null ? { keyed: true } : {})}
+      {...(row.opaqueColor ? { opaqueColor: true } : {})}
+      notice={
+        outside === null ? undefined : (
+          <>
+            <span>{outside.words}</span>
+            <div className="insp-buttons">
+              <button
+                type="button"
+                className="btn"
+                disabled={locked}
+                data-testid={`this-use-inside-${spec.key}`}
+                title={outside.title}
+                onClick={() => store.setUseProp(useKey, spec.key, outside.inside)}
+              >
+                Bring inside
+              </button>
+            </div>
+          </>
+        )
+      }
+      assets={props.assets}
+      rowProps={{
+        "data-testid": `this-use-prop-${spec.key}`,
+        title: animated !== null ? ANIMATED_HERE : changed ? "Changed here only" : "Follows the master",
+      }}
+    />
+  );
+}