@panphora/clayjs 1.8.2 → 1.9.1

package/src/plugins/people.js

@@ -0,0 +1,424 @@
+/**
+ * people.js — who is editing, and who wrote what (spec §9, People).
+ *
+ *   clay.me                        { id, name, initials, color } or null
+ *   clay.people.get(id)            always a record; an unknown id is "Unknown person"
+ *   clay.people.list()             the people this document names
+ *   await clay.people.available()  the host's team for a picker, or null
+ *   clay.people.add(person)        record a person in the document; returns the record
+ *   clay.people.remove(id)         forget a person the document no longer names
+ *   clay.people.canRename()        true when my name was chosen in this browser
+ *   clay.people.rename(name)       change that name here and in this page
+ *   await clay.author(el, attr?)   stamp el with my id (asks my name once if needed)
+ *   event clay:people              the viewer, the team or the registry changed
+ *
+ * An id is attribution, never authorization: anyone who can edit the page can
+ * write any id. Names on screen prefer the host's live answer; the copy stored in
+ * the document changes only when that person next writes (author or add), so
+ * opening a page never changes its bytes.
+ */
+
+import { hostMeta, hostMetaOutcome } from "../core/host-meta.js";
+import { isEditMode } from "../core/is-edit-mode.js";
+
+const editing = () => (window.clay && "isEditMode" in window.clay ? !!window.clay.isEditMode : isEditMode);
+import { bevelDialog, dismissOf, keepFocusIn } from "../ui/bevel-dialog.js";
+import { bevelBox, bevelButton, bevelInput, bevelText } from "../ui/bevel-controls.js";
+import { resolveTheme } from "../ui/theme.js";
+
+const ID = /^[A-Za-z0-9_-]{8,64}$/;
+const STORE = "clay:people:me";
+const BOOT_WAIT_MS = 2000;
+const COLORS = 8;
+const MAX_NAME = 120;
+const EMAIL = /\S+@\S+\.\S+/;
+
+let host = { supports: false, me: null, members: null, unavailable: false };
+let outcome = null;
+let local;
+let cache = null;
+let asking = null;
+let askingRoot = null;
+let cancelAsking = null;
+let lastRegistry = "";
+
+function clean(person) {
+  if (!person || typeof person !== "object") return null;
+  const id = typeof person.id === "string" ? person.id : "";
+  const name = typeof person.name === "string" ? person.name.trim().replace(/\s+/g, " ") : "";
+  if (!ID.test(id) || !name || name.length > MAX_NAME || EMAIL.test(name)) return null;
+  return { id, name };
+}
+
+function initialsOf(name) {
+  const letters = name.split(" ").filter(Boolean).slice(0, 2).map((word) => Array.from(word)[0]);
+  return letters.join("").toUpperCase() || "?";
+}
+
+function colorOf(id) {
+  let hash = 0;
+  for (const ch of String(id)) hash = (hash * 31 + ch.codePointAt(0)) >>> 0;
+  return hash % COLORS;
+}
+
+function record({ id, name }) {
+  return Object.freeze({ id, name, initials: initialsOf(name), color: colorOf(id) });
+}
+
+function emit() {
+  document.dispatchEvent(new CustomEvent("clay:people", { detail: { me: currentMe() } }));
+}
+
+function registry() {
+  return document.querySelector("[clay-people]");
+}
+
+// Every registry counts: two editors whose first comments race can each create one, and a
+// merge may keep both.
+function entries() {
+  return [...document.querySelectorAll("[clay-people] data[value]")];
+}
+
+function saved() {
+  if (cache) return cache;
+  cache = new Map();
+  for (const el of entries()) {
+    const person = clean({ id: el.getAttribute("value"), name: el.textContent });
+    if (person && !cache.has(person.id)) cache.set(person.id, record(person));
+  }
+  return cache;
+}
+
+function readLocal() {
+  if (local === undefined) {
+    local = null;
+    try {
+      local = clean(JSON.parse(window.localStorage.getItem(STORE) || "null"));
+    } catch (_) {}
+  }
+  return local;
+}
+
+function writeLocal(person) {
+  local = person;
+  try {
+    window.localStorage.setItem(STORE, JSON.stringify(person));
+  } catch (_) {}
+}
+
+function mint() {
+  const bytes = new Uint8Array(16);
+  crypto.getRandomValues(bytes);
+  return btoa(String.fromCharCode(...bytes)).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// Only an editor is anyone: a read-only page has no me, so it shows no compose UI. The
+// host's answer wins when it names you. A host that failed to answer has not said you are
+// nobody, so no local name stands in for a known account. Otherwise (no discovery, a host
+// without people, or a guest it cannot name) an editor is whoever this browser says it is.
+export function currentMe() {
+  if (!editing()) return null;
+  if (host.me) return record(host.me);
+  // The host knows who you are but cannot say right now: not a reason to become whoever
+  // this browser last was.
+  if (host.unavailable) return null;
+  if (outcome !== "ok" && outcome !== "none") return null;
+  const mine = readLocal();
+  return mine ? record(mine) : null;
+}
+
+function applyMeta(meta) {
+  const nextOutcome = hostMetaOutcome(meta);
+  // Once the host has named people, a later answer that is not a capability document is a
+  // blip (a deploy, a proxy), not news that it forgot everyone: the last good answer stands.
+  if (nextOutcome !== "ok" && host.supports) return;
+  const people = meta.document?.people;
+  const supports = meta.extensions.includes("people") && !!people && typeof people === "object";
+  const next = {
+    supports,
+    me: supports ? clean(people.me) : null,
+    members: supports && Array.isArray(people.members) ? people.members.map(clean).filter(Boolean) : null,
+    unavailable: supports && people.unavailable === true,
+  };
+  const changed = nextOutcome !== outcome || JSON.stringify(next) !== JSON.stringify(host);
+  host = next;
+  outcome = nextOutcome;
+  if (changed) emit();
+}
+
+async function refresh(fresh) {
+  applyMeta(await hostMeta({ fresh }));
+}
+
+function get(id) {
+  const key = String(id ?? "");
+  const live = (host.me?.id === key && host.me) || host.members?.find((person) => person.id === key);
+  if (live) return record(live);
+  const mine = readLocal();
+  if (mine?.id === key) return record(mine);
+  return saved().get(key) || Object.freeze({ id: key, name: "Unknown person", initials: "?", color: colorOf(key) });
+}
+
+function list() {
+  return [...saved().keys()].map(get);
+}
+
+async function available() {
+  await refresh(outcome !== "none");
+  return host.members ? host.members.map(record) : null;
+}
+
+function add(person) {
+  const p = clean(person);
+  if (!p) throw new TypeError("clay.people.add: needs an id of 8 to 64 letters, digits, _ or -, and a name of 1 to 120 characters");
+  let root = registry();
+  if (!root) {
+    root = document.createElement("div");
+    root.setAttribute("clay-people", "");
+    root.hidden = true;
+    document.body.append(root);
+  }
+  const same = entries().filter((el) => el.getAttribute("value") === p.id);
+  if (same.length) {
+    if (same[0].textContent !== p.name) same[0].textContent = p.name;
+    for (const extra of same.slice(1)) extra.remove();
+  } else {
+    const el = document.createElement("data");
+    el.setAttribute("value", p.id);
+    el.textContent = p.name;
+    root.append(el);
+  }
+  cache = null;
+  return record(p);
+}
+
+// Forget a person the document no longer names, so their name stops travelling with it.
+function remove(id) {
+  const key = String(id ?? "");
+  for (const el of entries()) if (el.getAttribute("value") === key) el.remove();
+  cache = null;
+}
+
+// Only a name this browser chose can change here; a host's name is the host's to change.
+function canRename() {
+  return editing() && !host.me && (outcome === "ok" || outcome === "none") && !!readLocal() && !host.unavailable;
+}
+
+/**
+ * Change the name this browser uses, and this page's record of it. Other pages keep the
+ * old name until this person next writes there. Returns the new record.
+ */
+function rename(name) {
+  if (!canRename()) throw Object.assign(new Error("clay.people.rename: only a name chosen in this browser can be changed here"), { code: "not-renamable" });
+  const mine = readLocal();
+  const next = clean({ id: mine.id, name });
+  if (!next) throw new TypeError("clay.people.rename: needs a name of 1 to 120 characters that is not an email address");
+  writeLocal(next);
+  if (entries().some((el) => el.getAttribute("value") === next.id)) add(next);
+  emit();
+  return record(next);
+}
+
+function unavailable() {
+  return Object.assign(new Error("Can't reach the host to check who you are. Try again in a moment."), { code: "people-unavailable" });
+}
+
+/**
+ * Stamp `el` with the current person's id, recording them in the document.
+ * Resolves the person's record, or null when they cancel the name prompt.
+ * Rejects with code "people-unavailable" when the host failed to answer.
+ */
+export async function author(el, attr = "data-by") {
+  if (!window.clay?.isEditMode) throw new Error("clay.author: this page is not in edit mode");
+  if (!(el instanceof Element)) throw new TypeError("clay.author: needs an element");
+  // A host that names people can change who you are while the page is open (a sign-out,
+  // a rename in the app), so a stamp asks it again first. If it cannot answer now, nothing
+  // is stamped: the last answer might name someone who is no longer here.
+  if (host.supports) {
+    const meta = await hostMeta({ fresh: true });
+    const fresh = hostMetaOutcome(meta);
+    if (fresh === "none") throw Object.assign(new Error("This page lost its connection to the host. Reload it to keep editing."), { code: "people-unavailable" });
+    if (fresh !== "ok") throw unavailable();
+    applyMeta(meta);
+    if (host.unavailable) throw Object.assign(new Error("The app hosting this file can't name you right now. Check its Profile settings, then try again."), { code: "people-unavailable" });
+  } else if (outcome !== "ok" && outcome !== "none") {
+    await refresh(outcome === "failed");
+  }
+  if (outcome === "failed") throw unavailable();
+  let me = currentMe();
+  if (!me) {
+    const chosen = await askName();
+    if (!chosen) return null;
+    writeLocal(chosen);
+    me = record(chosen);
+    emit();
+  }
+  add(me);
+  el.setAttribute(attr, me.id);
+  return me;
+}
+
+function askName() {
+  if (asking && askingRoot?.isConnected) return asking;
+  if (asking) cancelAsking();
+  asking = new Promise((resolve) => {
+    const theme = resolveTheme();
+    const { root, overlay, panel, heading, body, footer, close } = bevelDialog({
+      zIndex: "2147483001", width: "420px", closable: true, titled: true, theme, surface: "people",
+    });
+    askingRoot = root;
+    cancelAsking = () => finish(null);
+    heading.textContent = "What name should appear on your changes?";
+    panel.setAttribute("aria-label", "Your name");
+
+    const input = bevelInput("input", { rules: ["display:block", "width:100%", "margin:0"], theme, parts: ["dialog.input", "people.input"] });
+    input.setAttribute("aria-label", "Your name");
+    input.maxLength = MAX_NAME;
+    input.autocomplete = "name";
+    const hint = bevelText("p", ["display:block", "margin:10px 0 0", "font-size:13px", "opacity:.8"],
+      "Saved in this browser. Everyone who can read this page will see it.", { theme, parts: ["dialog.hint", "people.hint"], role: "mutedText" });
+    const hintText = hint.textContent;
+    body.append(input, hint);
+
+    const known = list().slice(0, 8);
+    if (known.length) {
+      const label = bevelText("p", ["display:block", "margin:18px 0 8px", "font-size:13px"], "Or continue as someone already in this page:", { theme, parts: ["people.choiceLabel"], role: "mutedText" });
+      const row = bevelBox("div", ["display:flex", "flex-wrap:wrap", "gap:8px"], { theme, parts: ["people.choices"] });
+      for (const person of known) {
+        row.append(bevelButton(person.name, { small: true, onClick: () => finish({ id: person.id, name: person.name }), theme, parts: ["dialog.button", "people.button", "people.choice"], labelParts: ["dialog.buttonLabel", "people.buttonLabel"] }));
+      }
+      body.append(label, row);
+    }
+
+    const cancel = bevelButton("Cancel", { onClick: () => finish(null), theme, parts: ["dialog.button", "people.button"], labelParts: ["dialog.buttonLabel", "people.buttonLabel"] });
+    const ok = bevelButton("Continue", { variant: "primary", onClick: () => submit(), theme, parts: ["dialog.button", "people.button"], labelParts: ["dialog.buttonLabel", "people.buttonLabel"] });
+    footer.append(cancel, ok);
+
+    const submit = () => {
+      const name = input.value.trim().replace(/\s+/g, " ");
+      if (!name) {
+        input.focus();
+        return;
+      }
+      if (EMAIL.test(name)) {
+        hint.textContent = "Use a name, not an email address. Everyone who can read this page will see it.";
+        input.focus();
+        return;
+      }
+      finish({ id: mint(), name: name.slice(0, MAX_NAME) });
+    };
+    input.addEventListener("input", () => {
+      if (hint.textContent !== hintText) hint.textContent = hintText;
+    });
+
+    panel.addEventListener("submit", (event) => {
+      event.preventDefault();
+      submit();
+    });
+    close?.addEventListener("click", () => finish(null));
+    let pressedOnBackdrop = false;
+    overlay.addEventListener("mousedown", (event) => { pressedOnBackdrop = event.target === overlay; });
+    overlay.addEventListener("click", (event) => {
+      if (pressedOnBackdrop && event.target === overlay) finish(null);
+      pressedOnBackdrop = false;
+    });
+    const onKey = (event) => {
+      if (event.key === "Tab") {
+        event.stopPropagation();
+        keepFocusIn(panel, event);
+        return;
+      }
+      if (event.key === "Escape") {
+        event.preventDefault();
+        event.stopPropagation();
+        finish(null);
+      } else if (event.key === "Enter" && event.target === input) {
+        event.preventDefault();
+        event.stopPropagation();
+        submit();
+      }
+    };
+    document.addEventListener("keydown", onKey, true);
+
+    let done = false;
+    function finish(person) {
+      if (done) return;
+      done = true;
+      document.removeEventListener("keydown", onKey, true);
+      root.remove();
+      // Recorded before the next caller can look, so an author() in the same task finds a me
+      // instead of opening a second prompt.
+      if (person) writeLocal(person);
+      asking = null;
+      askingRoot = null;
+      cancelAsking = null;
+      resolve(person);
+    }
+    dismissOf.set(root, () => finish(null));
+
+    root.setAttribute("aria-hidden", "false");
+    modalHost().append(root);
+    input.focus();
+  });
+  return asking;
+}
+
+// A page's own modal <dialog> makes everything outside it inert, so the prompt goes inside
+// the topmost one, or it could not be clicked or typed into.
+function modalHost() {
+  const open = [...document.querySelectorAll("dialog[open]")].filter((d) => d.matches(":modal"));
+  return open[open.length - 1] || document.body;
+}
+
+function touchesRegistry(node) {
+  return node.nodeType === 1 && (node.matches("[clay-people]") || !!node.querySelector("[clay-people]"));
+}
+
+function registrySignature() {
+  return JSON.stringify([...saved().values()].map(({ id, name }) => [id, name]));
+}
+
+function observe() {
+  lastRegistry = registrySignature();
+  new MutationObserver((records) => {
+    for (const rec of records) {
+      const target = rec.target.nodeType === 1 ? rec.target : rec.target.parentElement;
+      // A removed clay-people attribute no longer matches the selector, so it is caught by name.
+      if (rec.attributeName === "clay-people" ||
+          target?.closest("[clay-people]") ||
+          [...rec.addedNodes].some(touchesRegistry) ||
+          [...rec.removedNodes].some(touchesRegistry)) {
+        cache = null;
+        // Only a real change is news; a listener that re-renders the registry must not loop.
+        const next = registrySignature();
+        if (next !== lastRegistry) {
+          lastRegistry = next;
+          emit();
+        }
+        return;
+      }
+    }
+  }).observe(document.body, { subtree: true, childList: true, characterData: true, attributes: true, attributeFilter: ["value", "clay-people"] });
+}
+
+async function init() {
+  observe();
+  // A reader is nobody and picks nobody, so a read-only page never asks the host.
+  if (!editing()) return;
+  window.addEventListener("storage", (event) => {
+    if (event.key !== STORE) return;
+    local = undefined;
+    emit();
+  });
+  document.addEventListener("visibilitychange", () => {
+    if (document.visibilityState === "visible" && outcome !== "none") refresh(true);
+  });
+  const first = refresh(false);
+  await Promise.race([first, new Promise((resolve) => setTimeout(resolve, BOOT_WAIT_MS))]);
+}
+
+export const people = Object.freeze({ get, list, available, add, remove, canRename, rename });
+
+export const ready = init();
+
+export default people;

package/src/plugins/sortable.js

@@ -17,9 +17,37 @@
 import { isEditMode } from "../core/is-edit-mode.js";
 import Mutation from "../lib/mutation.js";
 import { capabilitySelector } from "../lib/region-capabilities.js";
+import { onSnapshot } from "../core/snapshot.js";
 
 const EDITOR_UI_SELECTOR = capabilitySelector('history');
 
+// Sortable marks the picked-up item and its links and images draggable="false" on press, and
+// leaves style="" behind after a drag. Those attributes would be saved into the document, so a
+// mere click would change the file. Record them when an item is chosen and put them back after.
+const RUNTIME_ATTRS = ['draggable', 'style'];
+
+const pressed = new Set();
+
+function recordRuntimeAttrs(item) {
+  return [item, ...item.querySelectorAll('*')].map(el => [el, RUNTIME_ATTRS.map(name => el.getAttribute(name))]);
+}
+
+function restoreRuntimeAttrs(recorded) {
+  for (const [el, values] of recorded) {
+    RUNTIME_ATTRS.forEach((name, i) => {
+      const before = values[i];
+      const now = el.getAttribute(name);
+      if (now === before) return;
+      if (before === null) {
+        if (name === 'style' && now) return;
+        el.removeAttribute(name);
+      } else {
+        el.setAttribute(name, before);
+      }
+    });
+  }
+}
+
 function makeSortable(sortableElem, Sortable) {
   let options = {};
   const childSelector = /^(UL|OL)$/.test(sortableElem.tagName) ? 'li' : '*';
@@ -87,6 +115,27 @@ function makeSortable(sortableElem, Sortable) {
     sortableElem.dispatchEvent(new Event('input', { bubbles: true }));
   };
 
+  // Record on the capture phase, before Sortable's own press handler changes anything, and
+  // restore once the press ends: a plain click never fires Sortable's unchoose.
+  const ENDS = ['pointerup', 'pointercancel', 'dragend', 'drop'];
+  let recorded = null;
+  const restoreSoon = () => {
+    const pending = recorded;
+    recorded = null;
+    pressed.delete(pending);
+    ENDS.forEach(type => document.removeEventListener(type, restoreSoon, true));
+    if (pending) setTimeout(() => restoreRuntimeAttrs(pending), 0);
+  };
+  sortableElem.addEventListener('pointerdown', (event) => {
+    let item = event.target instanceof Element ? event.target : null;
+    while (item && item.parentElement !== sortableElem) item = item.parentElement;
+    if (!item || recorded) return;
+    recorded = recordRuntimeAttrs(item);
+    pressed.add(recorded);
+    ENDS.forEach(type => document.addEventListener(type, restoreSoon, true));
+  }, true);
+  options.onUnchoose = restoreSoon;
+
   Sortable.create(sortableElem, options);
 }
 
@@ -99,6 +148,25 @@ async function init() {
   const mod = await import('../vendor/Sortable.vendor.js');
   const Sortable = window.Sortable || mod.default;
 
+  // A save taken mid-drag would otherwise write Sortable's classes and attributes into the
+  // file. Strip them from the snapshot clone only, so the live drag carries on untouched.
+  onSnapshot((root, { original }) => {
+    for (const el of root.querySelectorAll("[sortable] .sortable-chosen, [sortable] .sortable-ghost, [sortable] .sortable-drag")) {
+      el.classList.remove("sortable-chosen", "sortable-ghost", "sortable-drag");
+      if (!el.classList.length) el.removeAttribute("class");
+    }
+    if (!pressed.size) return;
+    const before = new Map();
+    for (const recording of pressed) for (const [el, values] of recording) before.set(el, values);
+    for (const el of root.querySelectorAll("[sortable] *")) {
+      const values = before.get(original(el));
+      if (!values) continue;
+      RUNTIME_ATTRS.forEach((name, i) => {
+        if (values[i] === null) el.removeAttribute(name); else el.setAttribute(name, values[i]);
+      });
+    }
+  });
+
   // Set up sortable on page load
   document.querySelectorAll('[sortable]').forEach(el => makeSortable(el, Sortable));
 

package/src/plugins/upload.js

@@ -58,6 +58,12 @@ export async function upload(file, { onProgress, signal } = {}) {
     // core host, and embedding is what it should do.
     return result(false, "This host does not store uploaded files", "skipped", "unsupported");
   }
+  // The host stores files, but not for this caller on this document: the spec withholds the
+  // document's upload block by omission, and a client that finds none does not upload. Not
+  // "unsupported", because embedding instead would route around the host's own decision.
+  if (!meta.document?.upload) {
+    return result(false, "You can't add files to this document", "error", "forbidden");
+  }
 
   // The one local pre-check the spec asks for, and the only reason `maxBytes` is
   // published: refusing a 40 MB photo here costs nothing, and sending it to be

package/src/ui/bevel-controls.js

@@ -10,6 +10,7 @@
 // flip the text direction.
 import { style, make, set } from '../lib/hostile-css.js';
 import { RULES, MEDIA, FONT_SANS, TOKENS } from './bevel.js';
+import { themed, tokenRulesFor, partRules, markParts, floorRules } from './theme-parts.js';
 
 export const RUNTIME_ONLY = 'no-save no-watch no-snapshot';
 
@@ -81,12 +82,13 @@ function protectIcon(svg, size) {
   }
 }
 
-export function bevelButton(label, { variant = 'default', small = false, onClick = null, extra = [], labelExtra = [], onState = null } = {}) {
+export function bevelButton(label, { variant = 'default', small = false, onClick = null, extra = [], labelExtra = [], onState = null, theme = null, parts = [], labelParts = [] } = {}) {
   const v = VARIANT[variant] || VARIANT.default;
   const size = small ? SIZE.small : SIZE.normal;
   const reducedMotion = media('(prefers-reduced-motion: reduce)');
   const forced = media('(forced-colors: active)');
   const coarse = media('(pointer: coarse)');
+  const narrow = media('(max-width: 760px)');
   const flags = { hovered: false, pressed: false, focusVisible: false, disabled: false };
   const pinned = new Map();
 
@@ -96,6 +98,12 @@ export function bevelButton(label, { variant = 'default', small = false, onClick
   span.textContent = label;
   b.append(span);
 
+  const variantName = VARIANT[variant] ? variant : 'default';
+  const names = ['button', `button.${variantName}`, ...parts];
+  const labelNames = ['buttonLabel', ...labelParts];
+  markParts(b, theme, names);
+  markParts(span, theme, labelNames);
+
   function applyState() {
     const rules = [...RESET, 'box-sizing:border-box', ...v.rest, ...size];
     if (flags.disabled) {
@@ -107,13 +115,25 @@ export function bevelButton(label, { variant = 'default', small = false, onClick
     if (flags.focusVisible) rules.push(...RULES.focus);
     if (forced) rules.push(...MEDIA.forcedColors);
     if (coarse) rules.push(...MEDIA.coarseButton);
+    if (narrow) rules.push('min-height:44px');
     rules.push(...extra);
+    if (themed(theme)) {
+      const act = { hover: flags.hovered, active: flags.pressed, focus: flags.focusVisible, disabled: flags.disabled };
+      rules.push(...tokenRulesFor(theme, `button.${variantName}`, act), ...partRules(theme, names, act));
+      if (forced) rules.push(...MEDIA.forcedColors);
+      rules.push(...floorRules(rules, 'min-height', narrow ? 44 : coarse ? 40 : 0));
+    }
     for (const [prop, value] of pinned) rules.push(`${prop}:${value}`);
     restyle(b, rules);
     const labelRules = [...RESET, 'font:inherit', 'color:inherit', ...RULES.buttonLabel];
     if (flags.disabled) labelRules.push(...RULES.buttonDisabledLabel);
     else if (flags.pressed) labelRules.push(...(reducedMotion ? MEDIA.reducedMotion : RULES.buttonActiveLabel));
     labelRules.push(...labelExtra);
+    if (themed(theme)) {
+      const act = { hover: flags.hovered, active: flags.pressed, focus: flags.focusVisible, disabled: flags.disabled };
+      labelRules.push(...partRules(theme, labelNames, act));
+      if (flags.pressed && !flags.disabled && reducedMotion) labelRules.push(...MEDIA.reducedMotion);
+    }
     restyle(span, labelRules);
     onState?.({ ...flags });
   }
@@ -213,33 +233,67 @@ export function bevelCornerClose({ label = 'Close', onClick = null } = {}) {
 }
 
 // A plain runtime-only box: reset, then only the given rules. For structure inside a
-// surface (rows, stacks, backdrops) that carries no material of its own.
-export function bevelBox(tag, rules = []) {
-  return runtime(make(tag, [...RESET, 'box-sizing:border-box', ...rules]));
+// surface (rows, stacks, backdrops) that carries no material of its own. `role` names the
+// token declarations it takes, or null for parts only.
+export function bevelBox(tag, rules = [], { theme = null, parts = [], role = null } = {}) {
+  const el = runtime(make(tag, [...RESET, 'box-sizing:border-box', ...rules]));
+  if (themed(theme)) {
+    if (role) style(el, tokenRulesFor(theme, role, {}));
+    const names = [...(['text', 'mutedText', 'well'].includes(role) ? [role] : []), ...parts];
+    style(el, partRules(theme, names, {}));
+    markParts(el, theme, names);
+  }
+  return el;
 }
 
-export function bevelSurface(tag, rules = []) {
-  return runtime(make(tag, [...RESET, 'box-sizing:border-box', ...RULES.surface, `font:14px/1.5 ${FONT_SANS}`, ...rules]));
+// Rebuild a box's whole inline style: what a stateful control does on every change.
+export function restyleBox(el, rules) {
+  restyle(el, [...RESET, 'box-sizing:border-box', ...rules]);
 }
 
-export function bevelWell(rules = []) {
-  return runtime(make('div', [...RESET, 'display:block', 'box-sizing:border-box', `font:14px/1.5 ${FONT_SANS}`, `color:${TOKENS.ink}`, ...RULES.recess, ...rules]));
+export function bevelSurface(tag, rules = [], { theme = null, parts = [], role = 'surface' } = {}) {
+  const el = runtime(make(tag, [...RESET, 'box-sizing:border-box', ...RULES.surface, `font:14px/1.5 ${FONT_SANS}`, ...rules]));
+  if (themed(theme)) {
+    if (role) style(el, tokenRulesFor(theme, role, {}));
+    style(el, partRules(theme, parts, {}));
+    markParts(el, theme, parts);
+  }
+  return el;
 }
 
-export function bevelText(tag, rules = [], text) {
+export function bevelWell(rules = [], { theme = null, parts = [], role = 'well' } = {}) {
+  const el = runtime(make('div', [...RESET, 'display:block', 'box-sizing:border-box', `font:14px/1.5 ${FONT_SANS}`, `color:${TOKENS.ink}`, ...RULES.recess, ...rules]));
+  if (themed(theme)) {
+    if (role) style(el, tokenRulesFor(theme, role, {}));
+    const names = [...(['text', 'mutedText', 'well'].includes(role) ? [role] : []), ...parts];
+    style(el, partRules(theme, names, {}));
+    markParts(el, theme, names);
+  }
+  return el;
+}
+
+export function bevelText(tag, rules = [], text, { theme = null, parts = [], role = 'text' } = {}) {
   const el = runtime(make(tag, [...RESET, 'font:inherit', `color:${TOKENS.ink}`, ...rules]));
   if (text != null) el.textContent = text;
+  if (themed(theme)) {
+    if (role) style(el, tokenRulesFor(theme, role, {}));
+    const names = [...(['text', 'mutedText', 'well'].includes(role) ? [role] : []), ...parts];
+    style(el, partRules(theme, names, {}));
+    markParts(el, theme, names);
+  }
   return el;
 }
 
 // A text field in Bevel's input material, on an element that already exists (markup a
 // dialog wrote) or a new one. Focus and hover live in flags, as on a button. A
 // textarea keeps the height a person dragged it to across every repaint.
-export function paintInput(el, { rules = [] } = {}) {
+export function paintInput(el, { rules = [], theme = null, parts = [] } = {}) {
   const flags = { hovered: false, focused: false };
   const forced = media('(forced-colors: active)');
   const coarse = media('(pointer: coarse)');
   runtime(el);
+  const names = ['input', ...parts];
+  markParts(el, theme, names);
   function applyState() {
     const height = el.localName === 'textarea' ? el.style.getPropertyValue('height') : '';
     const list = [...RESET, 'box-sizing:border-box', ...RULES.input];
@@ -248,6 +302,12 @@ export function paintInput(el, { rules = [] } = {}) {
     if (forced) list.push(...MEDIA.forcedColors);
     list.push(...rules);
     if (coarse) list.push(...MEDIA.coarseInput);
+    if (themed(theme)) {
+      const act = { hover: flags.hovered && !el.disabled, focus: flags.focused, disabled: !!el.disabled };
+      list.push(...tokenRulesFor(theme, 'input', act), ...partRules(theme, names, act));
+      if (forced) list.push(...MEDIA.forcedColors);
+      if (coarse) list.push(...floorRules(list, 'font-size', 16));
+    }
     if (height) list.push(`height:${height}`);
     restyle(el, list);
   }