@dailies-studio/shot-editor 0.1.0 → 0.2.0

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

@@ -1,37 +1,197 @@
 // Only for TEXT layers, and absent otherwise — a typography section over a
-// rectangle is four controls that write nothing.
+// rectangle is four controls that write nothing. That gate is `layout.ts`'s
+// table now, not this file's: both sections here used to re-decide it, and a
+// second opinion in the component is the duplication the table removes. The
+// `layer.kind !== "text"` guards on the WRITE helpers below stay, because a
+// mixed selection reaches them by the union rule and a rect must be left alone.
 //
 // `verticalAlign` is offered here and is HONOURED, unlike in the 2D lane where
 // it is declared-and-inert: this lane owns the text box, so top/middle/bottom
 // is one offset in the rasterizer rather than a change to a layout model.
-import { ColorPicker, InspectorRow, InspectorSection, NumberField, SegmentedControl, TextField } from "@dailies-studio/ui";
-import { DEFAULT_TEXT_STAGGER } from "@dailies-studio/shot/doc";
-import type { TextStagger, TextStyle } from "@dailies-studio/shot/doc";
-import type { Layer3D, TextLayer3D } from "@dailies-studio/shot/doc";
-import { NO_SCRUB, useSelectedLayers, useSelectionValue, useSelectionWrite } from "../useDocWrite.js";
+//
+// EVERY READ IS A SCALAR, one per row. This file used to read the whole
+// `TextStyle` object once and take every field off it, and `useSelectionValue`
+// compares with `Object.is`: the object was mixed by identity for every
+// multi-selection, so the rows showed the FIRST layer's values as if the
+// selection agreed on them. One read per row is also what lets each widget
+// carry its own "Mixed".
+//
+// THE FONT ROWS read what the family can draw (`selectionFontFacts`, over the
+// lazily loaded catalog and workspace list) and write only through the
+// store's font verbs, which fetch the face first and write once it lands.
+import { useEffect, useMemo, useRef, useState } from "react";
+import type { Ref } from "react";
+import {
+  ColorField,
+  Combobox,
+  IconItalic,
+  InspectorRow,
+  InspectorSection,
+  NumberField,
+  SegmentedControl,
+  TextField,
+  useLocked,
+} from "@dailies-studio/ui";
+import { ExposeDot } from "../ExposeDot.js";
+import { KeyframeDot } from "../KeyframeDot.js";
+import type { ScrubHandlers } from "@dailies-studio/ui";
+import {
+  fixedTextBox,
+  glyphEngineRefusals,
+  isGenericFontFamily,
+  primaryFontFamily,
+  textStyleForRole,
+} from "@dailies-studio/shot/doc";
+import type { TextEngine, TextRole, TextStyle } from "@dailies-studio/shot/doc";
+import type { Layer3D, Paint, TextLayer3D } from "@dailies-studio/shot/doc";
+import { loadGoogleFontRanges } from "../../../fonts/googleFonts.js";
+import { useShotEditor, useStore } from "../../../state/context.js";
+import { selectionFontFacts } from "../../../state/fonts.js";
+import type { LayerFontFacts } from "../../../state/fonts.js";
+import { requestFontPicker } from "../../fonts/pickerRequest.js";
+import { useSelectedLayers, useSelectionScrub, useSelectionValue, useSelectionWrite } from "../useDocWrite.js";
+import { FontField } from "./FontField.js";
+import { PaintRows, type PaintEdit } from "./PaintRows.js";
+
+/** Shown when the selection disagrees, in the two widgets that have no `mixed`
+ *  prop of their own. `SegmentedControl` renders an unmatched value as "none of
+ *  these selected", which is the same statement in its own vocabulary. */
+const MIXED_PLACEHOLDER = "Mixed";
+const NO_SEGMENT = "";
+const TEXT_ROLE_OPTIONS: { value: TextRole; label: string; title: string }[] = [
+  { value: "display", label: "Disp", title: "Display" },
+  { value: "displayMedium", label: "Mid", title: "Display medium" },
+  { value: "body", label: "Body", title: "Body" },
+  { value: "emphasis", label: "Emph", title: "Emphasis" },
+];
+
+/** None / Underline / Strike. `undefined` is the stored absence, and the
+ *  control needs a value it can compare, so absence reads as the empty string
+ *  and writing it writes `undefined` back. Both engines draw all three.
+ *
+ *  A ONE-LETTER segment says its word to a screen reader and to the pointer
+ *  (`ariaLabel`, `title`): "U" announced as "U" names nothing. */
+const DECORATION_OPTIONS = [
+  { value: "", label: "None" },
+  { value: "underline", label: "U", ariaLabel: "Underline", title: "Underline" },
+  { value: "line-through", label: "S", ariaLabel: "Strikethrough", title: "Strikethrough" },
+];
+const VERTICAL_OPTIONS = [
+  { value: "top", label: "T", ariaLabel: "Top", title: "Top" },
+  { value: "middle", label: "M", ariaLabel: "Middle", title: "Middle" },
+  { value: "bottom", label: "B", ariaLabel: "Bottom", title: "Bottom" },
+];
+
+type StyleNumber = "sizePx" | "lineHeight" | "letterSpacingPx";
+
+/** What the selected text's family can draw (state/fonts.ts). */
+type SelectionFontFacts = LayerFontFacts | { kind: "mixed" } | null;
+
+const WEIGHT_NAMES: Readonly<Record<number, string>> = {
+  100: "Thin",
+  200: "Extra Light",
+  300: "Light",
+  400: "Regular",
+  500: "Medium",
+  600: "Semi Bold",
+  700: "Bold",
+  800: "Extra Bold",
+  900: "Black",
+};
+
+/** "Semi Bold 600". A weight with no name (450) reads as its number. */
+function weightLabel(weight: number): string {
+  const name = WEIGHT_NAMES[weight];
+  return name === undefined ? String(weight) : `${name} ${weight}`;
+}
 
 export function TypographySection() {
+  const store = useStore();
   const write = useSelectionWrite();
+  // kind gate removed: see layout.ts
+  const content = useSelectionValue((layer) => (layer.kind === "text" ? layer.text.content : undefined));
+  // The font rows read the TEXT layers alone, as the font verbs write them:
+  // a rect beside a text layer has no family to disagree with.
   const layers = useSelectedLayers();
-  const anyText = layers.some((l) => l.kind === "text");
-  const style = useSelectionValue((layer) => (layer.kind === "text" ? layer.text.style : undefined));
-  const content = useSelectionValue((layer) => (layer.kind === "text" ? layer.text.content : ""));
-  if (!anyText || style.value === undefined) return null;
-
-  const patchStyle = (next: Partial<TextStyle>): void =>
-    write((layer) =>
-      layer.kind === "text"
-        ? ({ ...layer, text: { ...layer.text, style: { ...layer.text.style, ...next } } } as Layer3D)
-        : layer,
-    );
+  const texts = useMemo(() => layers.filter((layer): layer is TextLayer3D => layer.kind === "text"), [layers]);
+  const assets = useShotEditor((s) => s.doc?.assets);
+  const catalog = useShotEditor((s) => s.fontCatalog);
+  const workspace = useShotEditor((s) => s.workspaceFonts?.fonts ?? null);
+  const facts = useMemo(
+    () => selectionFontFacts(texts, assets ?? {}, catalog, workspace),
+    [texts, assets, catalog, workspace],
+  );
+  // The primary family, so `Inter` and `"Inter", sans-serif` are one family.
+  const families = texts.map((layer) => primaryFontFamily(layer.text.style.fontFamily));
+  const family = families[0] ?? "";
+  // LAZY, and only for text: the catalog while a layer waits on it (a
+  // catalog copy, or a machine font that Self-host may name), the workspace
+  // list once (a workspace copy reads as a plain file until it lands). A load
+  // that fails stays failed until the next mount: the effect runs on these
+  // flags, not on every render.
+  const needsCatalog = facts?.kind === "loading";
+  const needsWorkspace = texts.length > 0 && workspace === null;
+  useEffect(() => {
+    if (needsCatalog) void store.loadFontCatalog();
+  }, [store, needsCatalog]);
+  useEffect(() => {
+    if (needsWorkspace) void store.loadWorkspaceFonts();
+  }, [store, needsWorkspace]);
+  const align = useSelectionValue((layer) => readStyle(layer)?.align);
+  // Absent MEANS "top" (types.ts), so the default is applied inside the read
+  // and a layer that stores it explicitly agrees with one that does not. The
+  // undefined that survives is the one that says "not a text layer".
+  const verticalAlign = useSelectionValue((layer) => {
+    const style = readStyle(layer);
+    return style === undefined ? undefined : (style.verticalAlign ?? "top");
+  });
+  const decoration = useSelectionValue((layer) => {
+    const style = readStyle(layer);
+    return style === undefined ? undefined : (style.decoration ?? "");
+  });
+  // Absent MEANS canvas and always will (schema v30), so the default is
+  // applied in the read: a layer that stores "canvas" and one that stores
+  // nothing must show the same segment.
+  const engine = useSelectionValue((layer) =>
+    layer.kind === "text" ? (layer.text.engine ?? "canvas") : undefined,
+  );
+  // WHY the glyph segment is unavailable, in the validator's own words. Only
+  // the first is shown: a control has one line of room, and an author fixes
+  // these one at a time anyway.
+  const glyphBlocked = useSelectionValue((layer) =>
+    layer.kind === "text" ? (glyphEngineRefusals(layer)[0]?.message ?? "") : undefined,
+  );
+  // Absent MEANS fixed (schema v38), so the default is applied in the read.
+  const box = useSelectionValue((layer) => (layer.kind === "text" ? (layer.text.box ?? "fixed") : undefined));
+  const size = useStyleNumber("sizePx");
+  const lineHeight = useStyleNumber("lineHeight");
+  const letterSpacing = useStyleNumber("letterSpacingPx");
+  const role = useSelectionValue(textRoleOf);
+
+  const patchStyle = (next: Partial<TextStyle>): void => write((layer) => withStyle(layer, next));
 
-  const s = style.value;
   return (
-    <InspectorSection title="Text" persistKey="shot:text">
-      <InspectorRow label="Content">
+    <InspectorSection className="insp-object" title="Text" persistKey="shot:text">
+      {/* THE ONE HIGH-VALUE PATH WITH NO DIAMOND, so it mounts the pin itself.
+          `text.content` is not in `TRACKABLE_PATHS` — a string has no
+          in-between and the table refuses it by name — yet it is the field a
+          reusable component publishes first: one Title definition placed five
+          times with five headlines is the whole reason exposed props exist.
+          The kind is stated rather than looked up, because there is no table
+          row here to look it up from. A GROWING box, so the row aligns to its
+          start: the label stays level with the first line and the pin sits
+          at the box's top right, not centred on a paragraph. */}
+      <InspectorRow
+        label="Content"
+        align="start"
+        trailing={<ExposeDot path="text.content" label="Content" kind="string" />}
+      >
         <TextField
-          value={content.value ?? ""}
+          value={content.mixed ? "" : (content.value ?? "")}
+          {...(content.mixed ? { placeholder: MIXED_PLACEHOLDER } : {})}
           ariaLabel="Text content"
+          // A textarea keeps "\n": Enter breaks the line, blur commits.
+          multiline
           onCommit={(next) =>
             write((layer) =>
               layer.kind === "text" ? ({ ...layer, text: { ...layer.text, content: next } } as Layer3D) : layer,
@@ -39,132 +199,541 @@ export function TypographySection() {
           }
         />
       </InspectorRow>
+      {/* No typed family any more: the picker's search is how a family is
+          named, and every pick goes through the store's one apply path. */}
       <InspectorRow label="Font">
-        <TextField value={s.fontFamily} ariaLabel="Font family" onCommit={(next) => patchStyle({ fontFamily: next })} />
+        <FontField value={family} mixed={families.some((f) => f !== family)} />
       </InspectorRow>
-      <InspectorRow>
-        <NumberField value={s.sizePx} label="Size" ariaLabel="Font size" unit="px" min={1} step={1} onCommit={(v) => patchStyle({ sizePx: v })} />
+      {facts?.kind === "machine" ? <MachineFontNote family={facts.family} selfHost={facts.selfHost?.family ?? null} /> : null}
+      {/* Role writes its weight with the rest of the role in one edit, and
+          the store's `followFontWeights` then swaps the files to match. */}
+      <InspectorRow label="Role">
+        <SegmentedControl
+          ariaLabel="Text role"
+          value={role.mixed ? NO_SEGMENT : (role.value ?? NO_SEGMENT)}
+          options={TEXT_ROLE_OPTIONS}
+          onChange={(next) => write((layer) => withRole(layer, next as TextRole))}
+        />
       </InspectorRow>
+      {/* "Size", not the table's "Text size": the section is already called Text,
+          and a tooltip that disagreed with the pill beside it reads as a second
+          property. */}
       <InspectorRow>
-        <NumberField value={s.weight} label="Weight" ariaLabel="Font weight" min={100} max={900} step={100} onCommit={(v) => patchStyle({ weight: v })} />
+        <NumberField
+          value={size.value ?? 16}
+          mixed={size.mixed}
+          label="Size"
+          ariaLabel="Font size"
+          unit="px"
+          min={1}
+          // 1px is the smallest type that is type at all.
+          step={1}
+          trailing={<KeyframeDot path="text.style.sizePx" label="Size" />}
+          onCommit={size.commit}
+          onScrubStart={size.scrub.start}
+          onScrub={size.scrub.move}
+          onScrubEnd={size.scrub.end}
+        />
       </InspectorRow>
-      <InspectorRow>
-        <NumberField value={s.lineHeight} label="Line" ariaLabel="Line height" step={0.05} min={0.5} onCommit={(v) => patchStyle({ lineHeight: v })} />
+      <WeightRow texts={texts} facts={facts} />
+      {/* Auto width grows with the text and never wraps; Fixed wraps inside
+          its width. Fixed keeps the measured size, so the switch moves
+          nothing on screen. */}
+      <InspectorRow label="Box">
+        <SegmentedControl
+          ariaLabel="Text box"
+          value={box.mixed ? NO_SEGMENT : (box.value ?? "fixed")}
+          options={[
+            { value: "auto", label: "Auto width" },
+            { value: "fixed", label: "Fixed" },
+          ]}
+          onChange={(next) =>
+            write((layer) =>
+              next === "fixed"
+                ? fixedTextBox(layer)
+                : layer.kind === "text"
+                  ? ({ ...layer, text: { ...layer.text, box: "auto" } } as Layer3D)
+                  : layer,
+            )
+          }
+        />
       </InspectorRow>
+      {/* No colour row here: the glyph colour is the Fill section's (F20),
+          which this layer always shows, and a second row was a second
+          diamond over the one `text.style.color` track. */}
       <InspectorRow>
-        <NumberField value={s.letterSpacingPx} label="Letter" ariaLabel="Letter spacing" unit="px" step={0.1} onCommit={(v) => patchStyle({ letterSpacingPx: v })} />
+        <NumberField
+          value={lineHeight.value ?? 1.2}
+          mixed={lineHeight.mixed}
+          label="Line"
+          ariaLabel="Line height"
+          title="Line height (multiplier)"
+          step={0.05}
+          min={0.5}
+          // Below 0.5 the lines overlap into mush.
+          trailing={<KeyframeDot path="text.style.lineHeight" />}
+          onCommit={lineHeight.commit}
+          onScrubStart={lineHeight.scrub.start}
+          onScrub={lineHeight.scrub.move}
+          onScrubEnd={lineHeight.scrub.end}
+        />
       </InspectorRow>
-      <InspectorRow label="Color">
-        <ColorPicker value={s.color} ariaLabel="Text colour" scrub={NO_SCRUB} commit={(hex) => patchStyle({ color: hex })} />
+      <InspectorRow>
+        <NumberField
+          value={letterSpacing.value ?? 0}
+          mixed={letterSpacing.mixed}
+          label="Letter"
+          ariaLabel="Letter spacing"
+          unit="px"
+          step={0.1}
+          trailing={<KeyframeDot path="text.style.letterSpacingPx" />}
+          onCommit={letterSpacing.commit}
+          onScrubStart={letterSpacing.scrub.start}
+          onScrub={letterSpacing.scrub.move}
+          onScrubEnd={letterSpacing.scrub.end}
+        />
       </InspectorRow>
+      {/* JUSTIFY IS GLYPH-ONLY, and that is a capability rather than a
+          preference: the Canvas2D path has always drawn `justify` as `left`,
+          because `measureText` gives no way to distribute the slack a line
+          leaves without re-shaping it by hand. Offering the segment on a
+          canvas layer would offer a setting that does nothing. */}
       <InspectorRow label="Align">
         <SegmentedControl
           ariaLabel="Text align"
-          value={s.align}
+          value={align.mixed ? NO_SEGMENT : (align.value ?? "left")}
           options={[
-            { value: "left", label: "L" },
-            { value: "center", label: "C" },
-            { value: "right", label: "R" },
+            { value: "left", label: "L", ariaLabel: "Left", title: "Left" },
+            { value: "center", label: "C", ariaLabel: "Centre", title: "Centre" },
+            { value: "right", label: "R", ariaLabel: "Right", title: "Right" },
+            {
+              value: "justify",
+              label: "J",
+              ariaLabel: "Justify",
+              title:
+                engine.value === "glyph"
+                  ? "Justify"
+                  : "Justify needs the Glyph engine: the Canvas engine draws it as Left",
+              disabled: engine.mixed || engine.value !== "glyph",
+            },
           ]}
           onChange={(next) => patchStyle({ align: next as TextStyle["align"] })}
         />
       </InspectorRow>
+      <InspectorRow label="Decoration">
+        <SegmentedControl
+          ariaLabel="Text decoration"
+          value={decoration.mixed ? NO_SEGMENT : (decoration.value ?? "")}
+          options={DECORATION_OPTIONS}
+          onChange={(next) => write((layer) => withDecoration(layer, next))}
+        />
+      </InspectorRow>
       <InspectorRow label="Vertical">
         <SegmentedControl
           ariaLabel="Vertical align"
-          value={s.verticalAlign ?? "top"}
+          value={verticalAlign.mixed ? NO_SEGMENT : (verticalAlign.value ?? "top")}
+          options={VERTICAL_OPTIONS}
+          onChange={(next) => patchStyle({ verticalAlign: next as NonNullable<TextStyle["verticalAlign"]> })}
+        />
+      </InspectorRow>
+      {/* LAST, because it is the rarest edit and the one with consequences:
+          switching a layer to Glyph changes which engine draws it, and the
+          disabled reason is the validator's own sentence so the control and
+          the save gate can never disagree. */}
+      <InspectorRow label="Engine">
+        <SegmentedControl
+          ariaLabel="Text engine"
+          value={engine.mixed ? NO_SEGMENT : (engine.value ?? "canvas")}
           options={[
-            { value: "top", label: "T" },
-            { value: "middle", label: "M" },
-            { value: "bottom", label: "B" },
+            { value: "canvas", label: "Canvas" },
+            {
+              value: "glyph",
+              label: "Glyph",
+              title: glyphBlocked.mixed
+                ? "Some of these layers cannot use the Glyph engine"
+                : (glyphBlocked.value ?? "") === ""
+                  ? "Glyph: outlines from a project font, drawn on the GPU"
+                  : (glyphBlocked.value ?? ""),
+              disabled: glyphBlocked.mixed || (glyphBlocked.value ?? "") !== "",
+            },
           ]}
-          onChange={(next) => patchStyle({ verticalAlign: next as NonNullable<TextStyle["verticalAlign"]> })}
+          onChange={(next) =>
+            write((layer) =>
+              layer.kind === "text"
+                ? ({ ...layer, text: { ...layer.text, engine: next as TextEngine } } as Layer3D)
+                : layer,
+            )
+          }
         />
       </InspectorRow>
     </InspectorSection>
   );
 }
 
+/** The one value the selected text layers share, or Mixed. */
+function agreed<T>(values: readonly T[]): { value: T | undefined; mixed: boolean } {
+  const value = values[0];
+  return { value, mixed: values.some((v) => v !== value) };
+}
+
 /**
- * The SHAPE of a per-unit stagger, which is a property of the text rather than
- * of any one block — see `TextStagger` for why it cannot live on the block.
+ * WEIGHT, with Italic in its box's accessory lane. ONE labelled 28px pill in
+ * every state and both FieldLabels modes, only the control inside it changing,
+ * so nothing moves when the catalog lands and Italic is never remounted:
+ * - a catalog or workspace family with named weights: a menu of exactly
+ *   those ("Bold 700"), one entry when it has one;
+ * - a variable family: a number clamped to its axis, typed to 1 and stepped
+ *   by 100;
+ * - anything else (an uploaded file, a machine font, loading, Mixed): 100 to
+ *   900 by 100, as before.
+ * The number field takes no `label` of its own: under "named" it would draw
+ * its name above the box, a line the menu does not have.
+ * Every commit is `setFontWeight`, which fetches the face first, so a
+ * workspace family read as a plain file while its list loads still follows.
  *
- * Its own section rather than four more rows under Text: it is inert until a
- * `stagger` block exists on the layer, so it deserves to be collapsed away for
- * the layers that never animate.
+ * THE MENU WAITS FOR A FOCUSED NUMBER TO BLUR. A load that lands while the
+ * author types in the number (the catalog, the workspace list) would swap it
+ * for the menu, unmounting the input with its draft and dropping focus on
+ * <body>, where the next Backspace deletes the layer. The number holds its
+ * place until focus leaves it; its blur commits the draft as always, then
+ * the menu takes the slot. Focus is read on `document`, after React's own
+ * blur handler has committed.
  *
- * Every field writes a WHOLE record spread from the default, so the first edit
- * materialises what "absent means the default" already meant. Reading does the
- * same, so the fields show the real starting values instead of blanks.
+ * A DRAG previews through the inspector's scrub lane and commits nothing
+ * there. A move writes `weight` alone, which fetches nothing (the store
+ * follows files only on a commit), and that is safe to show: a variable file
+ * draws every weight on its axis, and a plain file draws whatever weight it
+ * is given. The release cancels the scrub and hands the last value to
+ * `setFontWeight`, the one undo step.
  */
-export function TextStaggerSection() {
-  const write = useSelectionWrite();
-  const layers = useSelectedLayers();
-  const anyText = layers.some((l) => l.kind === "text");
-  const stagger = useSelectionValue((layer) =>
-    layer.kind === "text" ? (layer.text.stagger ?? DEFAULT_TEXT_STAGGER) : undefined,
-  );
-  if (!anyText || stagger.value === undefined) return null;
-
-  const patch = (next: Partial<TextStagger>): void =>
-    write((layer) =>
-      layer.kind === "text"
-        ? ({
-            ...layer,
-            text: { ...layer.text, stagger: { ...DEFAULT_TEXT_STAGGER, ...layer.text.stagger, ...next } },
-          } as Layer3D)
-        : layer,
+function WeightRow(props: { texts: readonly TextLayer3D[]; facts: SelectionFontFacts }) {
+  const store = useStore();
+  const { facts } = props;
+  const weight = agreed(props.texts.map((layer) => layer.text.style.weight));
+  const scrub = useSelectionScrub((layer, raw) => withStyle(layer, { weight: Number(raw) }));
+  const dragged = useRef<number | null>(null);
+  const commit = (next: number): void => void store.setFontWeight(next);
+  const family = facts?.kind === "catalog" || facts?.kind === "workspace" ? facts : null;
+  const axis = family?.axis ?? null;
+  // A variable Google family's commit plans its faces with the subset ranges,
+  // a chunk nothing loads before a pick. Cold, the release that cancels the
+  // scrub would show the old weight for that round trip. A failure here is
+  // the commit's to retry and report.
+  const warmRanges = family?.kind === "catalog" && axis !== null;
+  useEffect(() => {
+    if (warmRanges) loadGoogleFontRanges().catch(() => {});
+  }, [warmRanges]);
+  // The Italic key is the row's one element this file holds; the row's one
+  // input is the number's (the menu's search is portaled away).
+  const italic = useRef<HTMLButtonElement>(null);
+  const [typing, setTyping] = useState(false);
+  useEffect(() => {
+    const inNumber = (node: EventTarget | null): boolean => {
+      const row = italic.current?.closest(".insp-prop");
+      return row != null && node instanceof HTMLInputElement && row.contains(node);
+    };
+    const onIn = (e: FocusEvent): void => setTyping(inNumber(e.target));
+    const onOut = (e: FocusEvent): void => setTyping(inNumber(e.relatedTarget));
+    document.addEventListener("focusin", onIn);
+    document.addEventListener("focusout", onOut);
+    return () => {
+      document.removeEventListener("focusin", onIn);
+      document.removeEventListener("focusout", onOut);
+    };
+  }, []);
+  let control;
+  if (family !== null && axis === null && family.weights.length > 0 && !typing) {
+    // A stored weight the family has no file for (a Role's 500 on 400 and
+    // 700) is still what the document holds, so the trigger names it.
+    const listed = !weight.mixed && weight.value !== undefined && family.weights.includes(weight.value);
+    control = (
+      <Combobox
+        ariaLabel="Font weight"
+        options={family.weights.map((w) => ({ value: String(w), label: weightLabel(w) }))}
+        value={listed ? String(weight.value) : ""}
+        placeholder={weight.mixed ? MIXED_PLACEHOLDER : weightLabel(weight.value ?? 400)}
+        onChange={(next) => commit(Number(next))}
+      />
     );
+  } else {
+    control = (
+      <NumberField
+        value={weight.value ?? 400}
+        mixed={weight.mixed}
+        ariaLabel="Font weight"
+        min={axis?.[0] ?? 100}
+        max={axis?.[1] ?? 900}
+        {...(axis === null ? { step: 100 } : { step: 1, nudge: 100 })}
+        onCommit={commit}
+        onScrubStart={() => {
+          dragged.current = null;
+          scrub.start();
+        }}
+        onScrub={(next) => {
+          dragged.current = next;
+          scrub.move(next);
+        }}
+        onScrubEnd={(ok) => {
+          scrub.end(false);
+          const last = dragged.current;
+          dragged.current = null;
+          if (ok && last !== null) commit(last);
+        }}
+      />
+    );
+  }
+  return (
+    <InspectorRow label="Weight" trailing={<ItalicKey ref={italic} texts={props.texts} facts={facts} />}>
+      {control}
+    </InspectorRow>
+  );
+}
 
-  const g = stagger.value;
+/**
+ * ITALIC, a verb in the Weight box's lane: pressed while the text is italic,
+ * Mixed while the layers disagree (a press makes every one italic, the house
+ * switch policy), and refused with the reason when the family has no italic
+ * (`aria-disabled`, still pressable so the press can say why). Disabled under
+ * `LockedControls`. `setFontStyle` fetches the face first.
+ */
+function ItalicKey(props: { ref: Ref<HTMLButtonElement>; texts: readonly TextLayer3D[]; facts: SelectionFontFacts }) {
+  const store = useStore();
+  const locked = useLocked();
+  const { facts } = props;
+  const italic = agreed(props.texts.map((layer) => layer.text.style.fontStyle === "italic"));
+  const pressed = italic.mixed ? "mixed" : italic.value === true;
+  const missing =
+    pressed !== true && (facts?.kind === "catalog" || facts?.kind === "workspace") && !facts.italic
+      ? `${facts.family} has no italic style.`
+      : null;
   return (
-    <InspectorSection title="Stagger" persistKey="shot:textStagger">
-      <InspectorRow label="Unit">
-        <SegmentedControl
-          ariaLabel="Stagger unit"
-          value={g.unit}
-          options={[
-            { value: "char", label: "Char" },
-            { value: "word", label: "Word" },
-            { value: "line", label: "Line" },
-          ]}
-          onChange={(next) => patch({ unit: next as TextStagger["unit"] })}
-        />
-      </InspectorRow>
-      <InspectorRow>
-        <NumberField
-          value={g.spread}
-          label="Spread"
-          ariaLabel="Stagger spread"
-          min={0}
-          max={1}
-          step={0.05}
-          onCommit={(v) => patch({ spread: v })}
-        />
-      </InspectorRow>
-      <InspectorRow>
-        <NumberField
-          value={g.risePx}
-          label="Rise"
-          ariaLabel="Stagger rise"
-          unit="px"
-          step={1}
-          onCommit={(v) => patch({ risePx: v })}
-        />
-      </InspectorRow>
-      <InspectorRow>
-        <NumberField
-          value={g.fadeFrom}
-          label="Fade from"
-          ariaLabel="Stagger fade from"
-          min={0}
-          max={1}
-          step={0.05}
-          onCommit={(v) => patch({ fadeFrom: v })}
+    <button
+      ref={props.ref}
+      type="button"
+      className="insp-key is-toggle"
+      aria-label="Italic"
+      aria-pressed={pressed}
+      title={missing ?? "Italic"}
+      {...(missing === null ? {} : { "aria-disabled": true })}
+      disabled={locked}
+      onClick={() => {
+        if (missing !== null) store.reportError(missing);
+        else void store.setFontStyle(pressed === true ? "normal" : "italic");
+      }}
+    >
+      <IconItalic />
+    </button>
+  );
+}
+
+/**
+ * A canvas text layer with no font file draws whatever the computer has
+ * (`drawsMachineFont`), so the note says so under the Font row, with the one
+ * way out: the catalog's copy when Google Fonts has the family, else the
+ * picker's upload view. A generic keyword (`sans-serif`) opens the picker's
+ * list instead, since no file is that family.
+ *
+ * SELF-HOST REMOVES THE NOTE: once the copy lands the layer has a file. So a
+ * press made from the verb hands focus to the Font row's trigger, the field
+ * the note sits under (its previous sibling), unless focus moved on while the
+ * file downloaded.
+ */
+function MachineFontNote(props: { family: string; selfHost: string | null }) {
+  const store = useStore();
+  const locked = useLocked();
+  // A generic keyword (`sans-serif`) names no font a file could be: every
+  // computer has its own, so the way out is choosing one.
+  const generic = isGenericFontFamily(props.family);
+  const selfHost = async (verb: HTMLButtonElement): Promise<void> => {
+    const trigger = verb.closest(".insp-notice")?.previousElementSibling?.querySelector<HTMLElement>("button");
+    const held = document.activeElement === verb;
+    const outcome = await store.selfHostFont();
+    const now = document.activeElement;
+    if (outcome.status === "applied" && held && (now === verb || now === null || now === document.body)) {
+      trigger?.focus();
+    }
+  };
+  return (
+    <div className="insp-notice is-warn" data-testid="machine-font-note">
+      {generic
+        ? `This text draws the computer's own ${props.family} font. Viewers, renders and exports may draw a different one.`
+        : `Only this computer has ${props.family}. Viewers, renders and exports may draw another font.`}
+      <div className="insp-buttons">
+        {generic ? (
+          <button type="button" className="btn" disabled={locked} onClick={() => requestFontPicker("list")}>
+            Choose a font
+          </button>
+        ) : props.selfHost !== null ? (
+          <button type="button" className="btn" disabled={locked} onClick={(e) => void selfHost(e.currentTarget)}>
+            {`Self-host ${props.selfHost}`}
+          </button>
+        ) : (
+          <button type="button" className="btn" disabled={locked} onClick={() => requestFontPicker("upload")}>
+            Upload font file
+          </button>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * A text layer's Fill is what its GLYPHS are painted with (F20), the way Figma
+ * and Framer read it. `paint.fill` on text is the plate behind the words, so
+ * `FillSection` titles itself "Background" there. Over a mixed selection this
+ * one says "Text fill", so the two never share a name.
+ *
+ * The layer fill's own rows (`PaintRows`), over the one paint the glyphs show:
+ * Solid is `text.style.color`, and Linear or Radial is `text.style.fill`
+ * (schema v47), written by `withTextPaint` so the document holds one or the
+ * other. Two cases keep the plain colour row, each saying why, because the
+ * save gate refuses a gradient there: a keyed colour (a `text.style.color`
+ * track beside a fill is a second writer) and the Glyph engine.
+ */
+export function TextFillSection() {
+  const layers = useSelectedLayers();
+  const write = useSelectionWrite();
+  const texts = layers.filter((layer): layer is TextLayer3D => layer.kind === "text");
+  // Each layer's OWN paint as painted, so a multi-selection edit changes one
+  // field per layer and never copies the lead's paint onto the rest.
+  const painted = new Map(texts.map((layer) => [layer.id, textPaintOf(layer)]));
+  const edited = (layer: Layer3D, edit: PaintEdit): Layer3D =>
+    layer.kind === "text" ? withTextPaint(layer, edit(painted.get(layer.id) ?? textPaintOf(layer))) : layer;
+  const scrub = useSelectionScrub((layer, raw) => edited(layer, raw as PaintEdit));
+  const blocked = texts.some((layer) => layer.tracks?.["text.style.color"] !== undefined)
+    ? "Remove the colour keys to fill the text with a gradient."
+    : texts.some((layer) => layer.text.engine === "glyph")
+      ? "Gradient text needs the Canvas engine."
+      : null;
+  const lead = texts[0];
+  return (
+    <InspectorSection
+      className="insp-object"
+      title={layers.every((layer) => layer.kind === "text") ? "Fill" : "Text fill"}
+      persistKey="shot:textFill"
+    >
+      {blocked !== null || lead === undefined ? (
+        <>
+          <TextColorRow />
+          {blocked !== null ? <p className="insp-note">{blocked}</p> : null}
+        </>
+      ) : (
+        <PaintRows
+          // NO `key`, for `FillSection`'s reason: a remount mid-drag drops the
+          // picker's pointer capture.
+          value={textPaintOf(lead)}
+          all={texts.map(textPaintOf)}
+          ariaPrefix="Text"
+          label={null}
+          solidTrailing={<KeyframeDot path="text.style.color" />}
+          onScrubStart={scrub.start}
+          onScrub={(edit) => scrub.move(edit)}
+          onScrubEnd={scrub.end}
+          onCommit={(edit) => write((layer) => edited(layer, edit))}
         />
-      </InspectorRow>
+      )}
     </InspectorSection>
   );
 }
 
-void ({} as TextLayer3D);
+/** The one paint a text layer's glyphs show: its gradient fill, else its
+ *  colour as a solid. */
+function textPaintOf(layer: TextLayer3D): Paint {
+  return layer.text.style.fill ?? { type: "solid", color: layer.text.style.color };
+}
+
+/** The ONE text paint edit, so a drag's move and its release land the same
+ *  document. A solid writes `color` and drops `fill`; a gradient writes
+ *  `fill` and keeps `color`, which a later switch back to Solid replaces. */
+function withTextPaint(layer: TextLayer3D, paint: Paint): Layer3D {
+  const { fill: _drop, ...style } = layer.text.style;
+  return {
+    ...layer,
+    text: { ...layer.text, style: paint.type === "solid" ? { ...style, color: paint.color } : { ...style, fill: paint } },
+  };
+}
+
+/** `text.style.color`: the glyph colour, the Fill section's one row, its
+ *  diamond inside the field. */
+function TextColorRow() {
+  const write = useSelectionWrite();
+  const color = useSelectionValue((layer) => readStyle(layer)?.color);
+  // THE DRAG HALF: the picker's SV square, hue bar and alpha bar all report
+  // through `scrub.move` and never `commit` while the pointer is down.
+  const scrub = useSelectionScrub((layer, raw) => withStyle(layer, { color: String(raw) }));
+  return (
+    <InspectorRow>
+      <ColorField
+        value={color.value ?? "#ffffff"}
+        mixed={color.mixed}
+        ariaLabel="Text colour"
+        scrub={scrub}
+        commit={(hex) => write((layer) => withStyle(layer, { color: hex }))}
+        trailing={<KeyframeDot path="text.style.color" />}
+      />
+    </InspectorRow>
+  );
+}
+
+interface NumberRow {
+  value: number | undefined;
+  mixed: boolean;
+  commit: (value: number) => void;
+  scrub: ScrubHandlers;
+}
+
+/** One numeric style field: the scalar it READS, the typed value it COMMITS and
+ *  the label drag it SCRUBS, so a row is one call rather than three. */
+function useStyleNumber(field: StyleNumber): NumberRow {
+  const write = useSelectionWrite();
+  const { value, mixed } = useSelectionValue((layer) => readStyle(layer)?.[field]);
+  const scrub = useSelectionScrub((layer, raw) => withStyle(layer, { [field]: Number(raw) }));
+  return { value, mixed, commit: (next) => write((layer) => withStyle(layer, { [field]: next })), scrub };
+}
+
+function readStyle(layer: Layer3D): TextStyle | undefined {
+  return layer.kind === "text" ? layer.text.style : undefined;
+}
+
+/** Infer a role only while every persisted metric agrees with it. An authored
+ *  custom style remains intentionally unmatched rather than acquiring a label
+ *  the document does not store. */
+function textRoleOf(layer: Layer3D): TextRole | undefined {
+  const style = readStyle(layer);
+  if (style === undefined) return undefined;
+  return TEXT_ROLE_OPTIONS.find(({ value }) => {
+    const role = textStyleForRole(value, style.sizePx);
+    return (
+      style.weight === role.weight &&
+      style.lineHeight === role.lineHeight &&
+      Math.abs(style.letterSpacingPx - role.letterSpacingPx) < 1e-9
+    );
+  })?.value;
+}
+
+/** Decoration is the one style field the control can set back to ABSENT, and
+ *  absent is not `undefined`: under `exactOptionalPropertyTypes` a spread of
+ *  `{ decoration: undefined }` is a different document from one with no key,
+ *  and the schema holds no key. So it is deleted rather than assigned. */
+function withDecoration(layer: Layer3D, next: string): Layer3D {
+  if (layer.kind !== "text") return layer;
+  if (next === "") {
+    const { decoration: _dropped, ...style } = layer.text.style;
+    return { ...layer, text: { ...layer.text, style } } as Layer3D;
+  }
+  return withStyle(layer, { decoration: next as NonNullable<TextStyle["decoration"]> });
+}
+
+/** The ONE style edit, so a drag's move and its release land the same document.
+ *  A non-text layer in the selection is left alone rather than grown a `text`
+ *  member it has no meaning for. */
+function withStyle(layer: Layer3D, next: Partial<TextStyle>): Layer3D {
+  if (layer.kind !== "text") return layer;
+  return { ...layer, text: { ...layer.text, style: { ...layer.text.style, ...next } } } as Layer3D;
+}
+
+/** Apply a role as raw values and preserve each selected layer's own size. */
+function withRole(layer: Layer3D, role: TextRole): Layer3D {
+  if (layer.kind !== "text") return layer;
+  return withStyle(layer, textStyleForRole(role, layer.text.style.sizePx));
+}