@dumiflex/wp-kit 0.0.0-stage → 0.4.0

package/src/tokens.ts

@@ -0,0 +1,56 @@
+// The CSS custom properties a kit piece may read.
+//
+// Most pieces also run on the ComfyUI canvas, whose colour sheet is the
+// extension's own (components/shared/theme.css), not src/theme/. Those pieces
+// read only SHARED_TOKENS, which every host defines, so a piece wears
+// whichever side's colours it sits on. The pieces in PAGE_PIECES only run on
+// pages that load src/theme/tokens.css (the manager, the community site, the
+// kit site), so they may read any name that sheet defines.
+// tokens.test.ts holds both rules.
+//
+// Add a shared name only once every host defines it (docs/tokens.md).
+
+export const SHARED_TOKENS = [
+  // Surfaces and text
+  "--wp-bg", "--wp-bg-1", "--wp-bg-2", "--wp-bg-3", "--wp-bg-4",
+  "--wp-text", "--wp-text-muted", "--wp-text-dim",
+  "--wp-border", "--wp-border-strong", "--wp-border-soft", "--wp-border-focus",
+  "--wp-overlay-bg", "--wp-row-hover", "--wp-input-shade", "--wp-scrollbar-thumb",
+  // Accent and states
+  "--wp-accent", "--wp-accent-glow", "--wp-accent-text", "--wp-accent-text-strong",
+  "--wp-accent-300", "--wp-accent-400", "--wp-accent-500", "--wp-accent-600", "--wp-accent-700", "--wp-accent-800",
+  "--wp-focus-ring", "--wp-on-accent", "--wp-on-media", "--wp-scrim",
+  "--wp-success", "--wp-warn", "--wp-danger", "--wp-info", "--wp-danger-text",
+  "--wp-error-border", "--wp-error-text",
+  "--wp-red", "--wp-red-bg", "--wp-green", "--wp-green-bg", "--wp-amber", "--wp-amber-bg",
+  "--wp-teal", "--wp-teal-bg", "--wp-violet", "--wp-violet-bg", "--wp-rose", "--wp-rose-bg",
+  // Kinds and variables
+  "--wp-kind-wildcard", "--wp-kind-fixed", "--wp-kind-combine", "--wp-kind-derivation", "--wp-kind-constraint",
+  "--wp-var-1", "--wp-var-2", "--wp-var-3", "--wp-var-4", "--wp-var-5", "--wp-var-6", "--wp-var-7", "--wp-var-8",
+  // Shape, depth and type
+  "--wp-radius-sm", "--wp-radius", "--wp-radius-md", "--wp-radius-lg", "--wp-radius-xl", "--wp-radius-cap",
+  "--wp-shadow-sm", "--wp-shadow", "--wp-shadow-md", "--wp-shadow-lg", "--wp-shadow-xl",
+  "--wp-font-sans", "--wp-font-mono",
+  "--wp-text-xs", "--wp-text-sm", "--wp-text-base", "--wp-text-md", "--wp-text-lg", "--wp-text-xl",
+  "--wp-space-0", "--wp-space-1", "--wp-space-2", "--wp-space-3", "--wp-space-4",
+  "--wp-space-5", "--wp-space-6", "--wp-space-7", "--wp-space-8",
+  "--wp-control-h-sm", "--wp-control-h-md", "--wp-control-h-lg",
+  // Motion
+  "--wp-motion-quick", "--wp-motion-hover", "--wp-motion-shimmer", "--wp-motion-fade", "--wp-motion-swap", "--wp-motion-flip",
+  "--wp-motion-curve-collapse", "--wp-motion-curve-flip", "--wp-motion-curve-linear",
+] as const;
+
+/** Read with a fallback (`var(--wp-bg-deep, var(--wp-bg))`) or kept for older
+ *  hosts; a host may leave these out. */
+export const OPTIONAL_TOKENS = ["--wp-bg-deep", "--wp-bg2"] as const;
+
+/** Set by the piece itself, on its own root, not by the host. */
+export const LOCAL_TOKENS = ["--wp-hsv-hue", "--wp-lm-t", "--wp-lm-x", "--wp-lm-r", "--wp-lm-s", "--wp-lm-o", "--wp-select-line-h", "--wp-list-row-depth", "--wp-list-row-icon", "--wp-chip-c", "--wp-field-h"] as const;
+
+/** Pieces that need a page with src/theme/ loaded (not the canvas). */
+export const PAGE_PIECES = [
+  "axis-color.ts", "kind-colour.ts", "matrix-axis.ts", "BundleMeta.vue", "ConstraintMatrixPreview.vue", "PostCard.vue", "TokenizedValue.vue",
+  "Button.vue", "Card.vue", "Checkbox.vue", "Chip.vue", "ChoiceCards.vue", "ColorPicker.vue", "ConfirmModal.vue",
+  "DataTable.vue", "Drawer.vue", "EmptyState.vue", "Field.vue", "Icon.vue", "IconPicker.vue", "Input.vue",
+  "ListFilter.vue", "Modal.vue", "RelativeDate.vue", "Select.vue", "Textarea.vue", "ToastHost.vue", "Toggle.vue",
+] as const;

package/src/tooltip.css

@@ -0,0 +1,43 @@
+/* The one shared tooltip element (tooltip.ts). Colours come from tokens both
+ * the canvas and the manager define, so it matches whichever side it is on. */
+@layer wp-extension {
+  .wp-tooltip {
+    position: fixed;
+    z-index: 10001;
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    max-width: 280px;
+    padding: 6px 10px;
+    border: 1px solid var(--wp-border-strong);
+    border-radius: var(--wp-radius);
+    background: var(--wp-bg-3);
+    color: var(--wp-text);
+    box-shadow: var(--wp-shadow-md);
+    font: 500 12px/1.4 var(--wp-font-sans);
+    pointer-events: none;
+    white-space: normal;
+    overflow-wrap: break-word;
+    opacity: 0;
+    visibility: hidden;
+    transition: opacity 90ms ease-out, visibility 0s linear 90ms;
+  }
+  .wp-tooltip[data-open] {
+    opacity: 1;
+    visibility: visible;
+    transition: opacity 90ms ease-out;
+  }
+  .wp-tooltip__kbd {
+    flex-shrink: 0;
+    padding: 1px 6px;
+    border: 1px solid var(--wp-border-strong);
+    border-radius: var(--wp-radius-sm);
+    background: var(--wp-bg-1);
+    color: var(--wp-text-muted);
+    font: 500 11px/16px var(--wp-font-mono);
+    white-space: nowrap;
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .wp-tooltip, .wp-tooltip[data-open] { transition: none; }
+  }
+}

package/src/tooltip.ts

@@ -0,0 +1,146 @@
+/**
+ * `v-tooltip`: a short hint shown on hover (after a short wait) and on
+ * keyboard focus, hidden on leave, blur or Escape. Use it instead of
+ * `title=`, which is slow, unstyled, never shows from the keyboard and is
+ * cut off on the canvas.
+ *
+ *   <Button v-tooltip="'Copy the prompt'" icon="pi-copy" aria-label="Copy" />
+ *   <span v-tooltip="{ text: 'Runs first', placement: 'right' }">…</span>
+ *   <Button v-tooltip="{ text: 'Copy to clipboard', kbd: 'Ctrl C' }" … />
+ *
+ * One tooltip element is shared by the whole page, so a thousand hints
+ * cost one node. State per element lives in a WeakMap (no expando keys).
+ */
+import type { Directive } from "vue";
+import { placeFloating, viewportSize, type Placement } from "./floating";
+import "./tooltip.css";
+
+export type TooltipValue =
+  | string
+  | null
+  | undefined
+  | {
+    text: string | null | undefined;
+    placement?: Placement | undefined;
+    /** A shortcut shown after the text, e.g. "Ctrl C". */
+    kbd?: string | undefined;
+  };
+
+interface State {
+  text: string;
+  kbd: string;
+  placement: Placement;
+  timer: number | undefined;
+  off: () => void;
+}
+
+const SHOW_DELAY = 450;
+/** Moving from one hint to the next within this window shows it at once. */
+const WARM_MS = 600;
+
+const states = new WeakMap<HTMLElement, State>();
+let tipEl: HTMLDivElement | null = null;
+let owner: HTMLElement | null = null;
+let lastHidden = 0;
+let uid = 0;
+
+function read(v: TooltipValue): { text: string; kbd: string; placement: Placement } {
+  if (v && typeof v === "object") return { text: v.text ?? "", kbd: v.kbd ?? "", placement: v.placement ?? "top" };
+  return { text: v ?? "", kbd: "", placement: "top" };
+}
+
+function tip(): HTMLDivElement {
+  if (tipEl && tipEl.isConnected) return tipEl;
+  tipEl = document.createElement("div");
+  tipEl.className = "wp-tooltip";
+  tipEl.id = `wp-tooltip-${++uid}`;
+  tipEl.setAttribute("role", "tooltip");
+  document.body.appendChild(tipEl);
+  return tipEl;
+}
+
+function show(el: HTMLElement): void {
+  const s = states.get(el);
+  if (!s || !s.text || !el.isConnected) return;
+  const t = tip();
+  t.textContent = s.text;
+  if (s.kbd) {
+    const k = document.createElement("kbd");
+    k.className = "wp-tooltip__kbd";
+    k.textContent = s.kbd;
+    t.append(" ", k);
+  }
+  t.dataset.open = "true";
+  owner = el;
+  const ids = (el.getAttribute("aria-describedby") ?? "").split(" ").filter(Boolean);
+  if (!ids.includes(t.id)) el.setAttribute("aria-describedby", [...ids, t.id].join(" "));
+  const at = placeFloating(el.getBoundingClientRect(), { width: t.offsetWidth, height: t.offsetHeight }, viewportSize(), {
+    placement: s.placement,
+  });
+  t.style.left = `${at.x}px`;
+  t.style.top = `${at.y}px`;
+  t.dataset.side = at.side;
+}
+
+function hide(el: HTMLElement): void {
+  const s = states.get(el);
+  if (s?.timer !== undefined) { window.clearTimeout(s.timer); s.timer = undefined; }
+  if (owner !== el) return;
+  owner = null;
+  lastHidden = Date.now();
+  if (tipEl) {
+    delete tipEl.dataset.open;
+    const ids = (el.getAttribute("aria-describedby") ?? "").split(" ").filter((i) => i && i !== tipEl?.id);
+    if (ids.length) el.setAttribute("aria-describedby", ids.join(" "));
+    else el.removeAttribute("aria-describedby");
+  }
+}
+
+function schedule(el: HTMLElement): void {
+  const s = states.get(el);
+  if (!s) return;
+  if (s.timer !== undefined) window.clearTimeout(s.timer);
+  const warm = owner !== null || Date.now() - lastHidden < WARM_MS;
+  if (warm) { show(el); return; }
+  s.timer = window.setTimeout(() => { s.timer = undefined; show(el); }, SHOW_DELAY);
+}
+
+export const vTooltip: Directive<HTMLElement, TooltipValue> = {
+  mounted(el, binding) {
+    const enter = (): void => schedule(el);
+    const leave = (): void => hide(el);
+    const focus = (): void => { if (el.matches(":focus-visible")) show(el); };
+    const key = (ev: KeyboardEvent): void => { if (ev.key === "Escape" && owner === el) hide(el); };
+    el.addEventListener("pointerenter", enter);
+    el.addEventListener("pointerleave", leave);
+    el.addEventListener("pointerdown", leave);
+    el.addEventListener("focusin", focus);
+    el.addEventListener("focusout", leave);
+    el.addEventListener("keydown", key);
+    states.set(el, {
+      ...read(binding.value),
+      timer: undefined,
+      off: () => {
+        el.removeEventListener("pointerenter", enter);
+        el.removeEventListener("pointerleave", leave);
+        el.removeEventListener("pointerdown", leave);
+        el.removeEventListener("focusin", focus);
+        el.removeEventListener("focusout", leave);
+        el.removeEventListener("keydown", key);
+      },
+    });
+  },
+  updated(el, binding) {
+    const s = states.get(el);
+    if (!s) return;
+    Object.assign(s, read(binding.value));
+    if (owner === el) { if (s.text) show(el); else hide(el); }
+  },
+  beforeUnmount(el) {
+    hide(el);
+    states.get(el)?.off();
+    states.delete(el);
+  },
+};
+
+export default vTooltip;

package/src/useDialogFocus.ts

@@ -0,0 +1,73 @@
+/**
+ * Focus handling every dialog-like panel needs (Modal, Drawer): while open,
+ * Escape calls `onEscape` and Tab stays inside the panel; on open, focus
+ * moves in (`initial`, else the first control, else the panel itself); on
+ * close, it goes back to where it was.
+ */
+import { nextTick, onBeforeUnmount, watch, type Ref } from "vue";
+
+export const FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]), '
+  + 'textarea:not([disabled]), [tabindex]:not([tabindex="-1"]), [contenteditable="true"]';
+
+export function focusablesIn(root: HTMLElement | null): HTMLElement[] {
+  return Array.from(root?.querySelectorAll<HTMLElement>(FOCUSABLE) ?? [])
+    .filter((el) => !el.closest("[hidden], [inert]"));
+}
+
+export interface DialogFocusOptions {
+  onEscape: () => void;
+  /** Where focus goes on open; defaults to the first control. */
+  initial?: (root: HTMLElement, controls: HTMLElement[]) => HTMLElement | null | undefined;
+  /** Keep Tab inside the panel (default). Off for a panel beside the page. */
+  trap?: () => boolean;
+}
+
+export function useDialogFocus(panel: Ref<HTMLElement | null>, isOpen: () => boolean, opts: DialogFocusOptions): void {
+  let returnTo: HTMLElement | null = null;
+
+  function onKeydown(e: KeyboardEvent): void {
+    if (e.key === "Escape") { opts.onEscape(); return; }
+    const root = panel.value;
+    if (e.key !== "Tab" || !root || opts.trap?.() === false) return;
+    const els = focusablesIn(root);
+    if (!els.length) { e.preventDefault(); root.focus(); return; }
+    const first = els[0];
+    const last = els[els.length - 1];
+    const at = document.activeElement;
+    const inside = at instanceof Node && root.contains(at);
+    if (e.shiftKey && (at === first || !inside)) { e.preventDefault(); last?.focus(); }
+    else if (!e.shiftKey && (at === last || !inside)) { e.preventDefault(); first?.focus(); }
+  }
+
+  async function opened(): Promise<void> {
+    returnTo = document.activeElement instanceof HTMLElement ? document.activeElement : null;
+    await nextTick();
+    const root = panel.value;
+    if (!root || root.contains(document.activeElement)) return;
+    const els = focusablesIn(root);
+    ((opts.initial ? opts.initial(root, els) : els[0]) ?? root).focus();
+  }
+
+  function closed(): void {
+    const el = returnTo;
+    returnTo = null;
+    if (el?.isConnected) el.focus();
+  }
+
+  watch(isOpen, (v, was) => {
+    if (typeof window === "undefined") return;
+    if (v) {
+      window.addEventListener("keydown", onKeydown);
+      void opened();
+    } else {
+      window.removeEventListener("keydown", onKeydown);
+      if (was) closed();
+    }
+  }, { immediate: true });
+
+  onBeforeUnmount(() => {
+    if (typeof window === "undefined") return;
+    window.removeEventListener("keydown", onKeydown);
+    if (isOpen()) closed();
+  });
+}

package/src/useGrowableField.ts

@@ -0,0 +1,357 @@
+/**
+ * The behaviour every capped, user-resizable text field in this project needs.
+ *
+ * Three components had grown their own copy of it — `RichTextInput`'s two
+ * hosts, the fixed-values `ValueRow`, the combine template — and the copies had
+ * already diverged: only one clears the resize grip, only one follows the grip
+ * off-screen, and the auto-grow in `ValueRow` silently fought the drag handle.
+ * One implementation, three fixes, no third copy.
+ *
+ * What it provides:
+ *
+ *   1. **Auto-grow that yields to the user.** The field sizes itself to its
+ *      content until the user drags the handle; from then on their height is
+ *      authoritative. Previously `height = scrollHeight` ran on every input and
+ *      external value change, so a manually collapsed box snapped straight back
+ *      open — which reads as "the drag sticks, then starts working".
+ *
+ *   2. **A "more below" flag.** A capped box looks identical whether it holds
+ *      its whole value or a third of it.
+ *
+ *   3. **Grip-follow.** Dragging a field taller than the space beneath it moves
+ *      the box, not the pointer, so the handle being held slides off-screen and
+ *      the drag goes blind. Scrolling by exactly the overshoot pins the bottom
+ *      edge to the viewport, keeping the grip under the cursor.
+ *
+ * DOM-only and framework-light: takes an element getter, returns plain
+ * functions plus one ref. Callers own their own `onMounted` / `watch`.
+ */
+import { onBeforeUnmount, ref, type Ref } from "vue";
+
+export interface GrowableField {
+  /** True while content extends past the visible bottom edge. */
+  hasMoreBelow: Ref<boolean>;
+  /** Re-measure the overflow flag. Cheap; call on scroll and input. */
+  updateOverflowHint: () => void;
+  /** Same, deferred a frame — use at mount, before layout has settled. */
+  scheduleOverflowHint: () => void;
+  /** Resize to fit content, UNLESS the user has taken manual control. */
+  autosize: () => void;
+  /** Begin observing: wires the resize observer for the hint + grip-follow. */
+  attach: () => void;
+  /** True once the user has dragged the handle. */
+  userResized: Ref<boolean>;
+  /** Bind to a grip element's `pointerdown`. Replaces `resize: vertical`,
+   *  which cannot be clamped from outside — see `startResize`. */
+  startResize: (ev: PointerEvent) => void;
+}
+
+/** Nearest ancestor that actually scrolls, or null when only the page does.
+ *  Walks computed `overflow-y` rather than trusting a class name — these
+ *  fields live in modals, pages and canvas widgets, each of which puts its
+ *  scroller somewhere different. */
+function scrollableAncestor(el: HTMLElement): HTMLElement | null {
+  let node = el.parentElement;
+  while (node && node !== document.body) {
+    const oy = getComputedStyle(node).overflowY;
+    if (oy === "auto" || oy === "scroll") return node;
+    node = node.parentElement;
+  }
+  return null;
+}
+
+/** Backstop floor for a field whose CSS declares no `min-height`. Enough to
+ *  keep one line and its padding visible, so a drag can always be undone. */
+const ABSOLUTE_MIN = 28;
+
+export function useGrowableField(
+  getEl: () => HTMLElement | null,
+  opts: { minHeight?: number } = {},
+): GrowableField {
+  const hasMoreBelow = ref(false);
+  const userResized = ref(false);
+
+  function updateOverflowHint(): void {
+    const el = getEl();
+    if (!el) return;
+    // 2px slack absorbs sub-pixel rounding at the exact bottom.
+    hasMoreBelow.value = el.scrollHeight - el.scrollTop - el.clientHeight > 2;
+  }
+
+  function scheduleOverflowHint(): void {
+    if (typeof requestAnimationFrame === "function") requestAnimationFrame(updateOverflowHint);
+    else updateOverflowHint();
+  }
+
+  function autosize(): void {
+    const el = getEl();
+    // The user's drag wins from the moment it happens. Re-running the fit
+    // after that is what made a collapsed box spring open again.
+    if (!el || userResized.value) return;
+    autoDriven = true;
+    el.style.height = "auto";
+    const next = Math.max(opts.minHeight ?? 0, el.scrollHeight);
+    el.style.height = `${next}px`;
+    lastHeight = next;
+    // Release on the next frame: the observer fires asynchronously, and
+    // clearing synchronously would let our own write look like a user drag.
+    if (typeof requestAnimationFrame === "function") {
+      requestAnimationFrame(() => { autoDriven = false; });
+    } else {
+      autoDriven = false;
+    }
+  }
+
+  /** Keep the grip under the cursor while the box grows past the fold.
+   *  Only ever scrolls DOWN, and only while the bottom is genuinely
+   *  off-screen — shrinking must not yank the view around.
+   *
+   *  Deliberately not `scrollIntoView`, which this project bans for scrolling
+   *  every ancestor rather than the one the user is working in. */
+  function followGrip(): void {
+    const el = getEl();
+    if (!el) return;
+    const margin = 8;
+    const rect = el.getBoundingClientRect();
+    const container = scrollableAncestor(el);
+    if (container) {
+      const cRect = container.getBoundingClientRect();
+      const overshoot = rect.bottom - (cRect.bottom - margin);
+      if (overshoot > 0) container.scrollTop += overshoot;
+      return;
+    }
+    const overshoot = rect.bottom - (window.innerHeight - margin);
+    if (overshoot > 0) window.scrollBy(0, overshoot);
+  }
+
+  let obs: ResizeObserver | null = null;
+  let lastHeight = 0;
+  /** Set while `autosize` is writing, so its own change is not mistaken for a
+   *  drag. Without it the first auto-fit would lock the field immediately. */
+  let autoDriven = false;
+  /** True between pointerdown on the field and the matching pointerup —
+   *  i.e. while the user may be holding the resize handle. */
+  let dragging = false;
+  let pending = false;
+  /** Set once the height cap has been dropped for a manual drag. */
+  let capLifted = false;
+  /** Pointer Y at the previous move — the drag is incremental, so only the
+   *  step between moves matters, never a captured origin. */
+  let lastPointerY = 0;
+  /** Floor read from CSS at drag start; CSS stays the source of truth. */
+  let minPx = 0;
+
+  /**
+   * Everything the observer wants to do, moved OUT of the observer.
+   *
+   * A ResizeObserver callback that reads layout and writes reactive state runs
+   * before paint, so doing it synchronously on every frame of a resize drag
+   * dirties layout inside the very callback the browser is using to report
+   * layout. Chrome throttles that (the "ResizeObserver loop" case) and stops
+   * delivering for a frame, which the user feels as the drag seizing up until
+   * they release and re-grab. Deferring to rAF leaves the callback trivial.
+   */
+  function flush(): void {
+    pending = false;
+    const el = getEl();
+    if (!el) return;
+    const h = el.getBoundingClientRect().height;
+    updateOverflowHint();
+    // A height change we did not author is the user on the drag handle.
+    if (!autoDriven && Math.abs(h - lastHeight) > 1) userResized.value = true;
+    // Follows LIVE, including mid-drag. Scrolling by the overshoot moves the
+    // element up by exactly that much, landing its bottom edge at the viewport
+    // edge — which is where the pointer already is, so the grip stays under the
+    // cursor. Deferring this to pointerup (an earlier attempt at the stall,
+    // which turned out to be the height cap) just made the field vanish off
+    // the bottom for the whole drag.
+    //
+    // Gated on `dragging`, which is what the name always implied. It exists to
+    // keep the GRIP under the CURSOR, and there is no grip being held unless a
+    // drag is in progress. Ungated it also ran on content-driven growth — so
+    // typing a long enough template scrolled the page out from under you — and
+    // it made this flush mutate scroll position, which moves the element the
+    // observer is measuring. A resize handler that can change its own input is
+    // the shape a runaway needs.
+    if (dragging && h > lastHeight) followGrip();
+    lastHeight = h;
+  }
+
+  function schedule(): void {
+    if (pending) return;
+    pending = true;
+    if (typeof requestAnimationFrame === "function") requestAnimationFrame(flush);
+    else flush();
+  }
+
+  /**
+   * Our own resize drag, replacing the native `resize: vertical`.
+   *
+   * The native resizer computes `startHeight + (pointerY - startY)` from an
+   * origin it captured at pointerdown, and it does NOT clamp to the element's
+   * own min/max. Drag past a limit and that sum keeps running while the
+   * rendered box stays pinned, so dragging back moves nothing until the
+   * invisible total walks all the way home. Measured: collapsing past a 34px
+   * floor then expanding cost 13 of 23 frames of completely dead travel. That
+   * is the "gets stuck, then starts working" report, and it bites exactly when
+   * the box reaches one line — which is also when the overflow fade returns,
+   * which is why the fade kept looking guilty.
+   *
+   * Nothing outside can fix it: rewriting `style.height` mid-drag is ignored,
+   * because the browser recomputes from its own captured origin every move.
+   * Clamping the RESULT does not help either — the accumulated input is the
+   * problem, so a clamped absolute drag measured the same 13 / 23.
+   *
+   * Applying each move's DELTA to the current height instead keeps no history
+   * to accumulate: the first pixel back off a limit moves the box. Same
+   * harness, same over-drag: 0 / 23.
+   */
+  function startResize(ev: PointerEvent): void {
+    const el = getEl();
+    if (!el) return;
+    ev.preventDefault();
+    dragging = true;
+    userResized.value = true;
+    lastPointerY = ev.clientY;
+
+    const cs = getComputedStyle(el);
+    // CSS stays the source of truth for the floor; the ceiling is deliberately
+    // released, because a deliberate drag is the user overriding a cap that
+    // exists only to bound AUTO-grow.
+    // `min-height: auto` (the default) parses to NaN, so a field that never
+    // declared one would get a floor of 0 and could be dragged away to a
+    // sliver. CSS stays authoritative when it says anything; ABSOLUTE_MIN is
+    // only the backstop for when it does not.
+    const declared = Number.parseFloat(cs.minHeight);
+    minPx = Number.isFinite(declared) && declared > 0 ? declared : ABSOLUTE_MIN;
+    if (!capLifted) {
+      el.style.height = `${el.getBoundingClientRect().height}px`;
+      el.style.maxHeight = "none";
+      capLifted = true;
+    }
+    /* No `setPointerCapture`.
+     *
+     * It reads like the right call and it is what stranded the drag. Capture
+     * retargets every subsequent pointer event to the grip — including
+     * `pointerup`. The editor re-renders while it resizes, and a captured
+     * element that gets replaced is detached: the `pointerup` is delivered to a
+     * node no longer in the tree, so it never bubbles to `window`, `dragging`
+     * stays true, and the box follows the cursor with no button held and no way
+     * to stop it. That is the reported symptom exactly.
+     *
+     * Capture bought nothing here anyway. The listeners below are on `window`,
+     * which sees the events regardless of what is under the cursor.
+     *
+     * CAPTURE PHASE on all three, so a `stopPropagation()` between the target
+     * and the window — ComfyUI's node layer does this to stop the canvas
+     * panning under a widget — cannot hide the end of the drag from us.
+     */
+    window.addEventListener("pointermove", onResizeMove, true);
+    window.addEventListener("pointerup", onPointerUp, true);
+    window.addEventListener("pointercancel", onPointerUp, true);
+    // A fresh press means the previous drag is over however it ended.
+    window.addEventListener("pointerdown", onPointerUp, true);
+    window.addEventListener("blur", onPointerUp);
+    window.addEventListener("keydown", onDragEscape, true);
+  }
+
+  /** Escape ends a drag. Cheap, and it is the key a stuck user presses. */
+  function onDragEscape(ev: KeyboardEvent): void {
+    if (ev.key === "Escape") onPointerUp();
+  }
+
+  function onResizeMove(ev: PointerEvent): void {
+    const el = getEl();
+    if (!el || !dragging) return;
+    // Self-heal. Every pointermove reports which buttons are down, so a move
+    // with none held means the pointerup was lost — whatever swallowed it —
+    // and the drag should already be over. Without this the field follows the
+    // cursor forever and no key or click can stop it, because nothing else in
+    // here ever clears `dragging`. Belt and braces on top of the listener
+    // changes above: those address the causes we found, this ends the state
+    // regardless of a cause we did not.
+    if (ev.buttons === 0) {
+      onPointerUp();
+      return;
+    }
+    const dy = ev.clientY - lastPointerY;
+    lastPointerY = ev.clientY;
+    const cur = el.getBoundingClientRect().height;
+    el.style.height = `${Math.max(minPx, cur + dy)}px`;
+  }
+
+  function onPointerUp(): void {
+    if (!dragging) return;
+    dragging = false;
+    // Re-arm for the next drag. `capLifted` guards a one-time "pin the current
+    // height, release the max-height cap" step, and leaving it set meant the
+    // release survived for the lifetime of the field while the explicit height
+    // that bounded it did not — `applyAtoms` replaces the host element on a
+    // rebuild, which drops the inline height but not this flag. The next drag
+    // then found an uncapped, unpinned box. Each drag now re-establishes both
+    // against the element that actually exists.
+    capLifted = false;
+    window.removeEventListener("pointermove", onResizeMove);
+    window.removeEventListener("pointerup", onPointerUp);
+    window.removeEventListener("pointercancel", onPointerUp);
+  }
+
+  /** Idempotent: callers re-attach when the element they own is REPLACED
+   *  rather than mutated (RichTextInput swaps its contenteditable host to
+   *  repair a browser-mangled DOM). Without the disconnect the old observer
+   *  would keep watching a detached node and leak, and the hint would go
+   *  permanently stale on the live one. */
+  function attach(): void {
+    obs?.disconnect();
+    obs = null;
+    const el = getEl();
+    if (!el) return;
+    lastHeight = el.getBoundingClientRect().height;
+
+    /* Re-measure once the webfonts land.
+     *
+     * These fields are typed in `--wp-font-mono`, a bundled webfont declared
+     * `font-display: swap` — so the first paint uses the system fallback
+     * (Consolas / Monaco) and the real face swaps in later. The two stacks
+     * have different metrics, so the `scrollHeight` measured at mount is taken
+     * against type that is about to be replaced.
+     *
+     * That is the "sometimes the bottom fade is wrong" report: on a cold load
+     * the hint is computed against the fallback and never recomputed, and on a
+     * warm cache the font is already there so it looks fine. Any later scroll,
+     * input or resize also fixes it by accident, which is what made it look
+     * intermittent rather than deterministic.
+     *
+     * `document.fonts.ready` resolves once, after all pending faces settle.
+     * Cheap, and a no-op where the font was already cached.
+     */
+    if (typeof document !== "undefined" && document.fonts?.ready) {
+      void document.fonts.ready.then(() => {
+        // The field may have unmounted during the load.
+        if (!getEl()) return;
+        updateOverflowHint();
+        autosize();
+      });
+    }
+
+    if (typeof ResizeObserver === "undefined") return;
+    obs = new ResizeObserver(schedule);
+    obs.observe(el);
+  }
+
+  onBeforeUnmount(() => {
+    obs?.disconnect();
+    obs = null;
+    onPointerUp();
+  });
+
+  return {
+    hasMoreBelow,
+    updateOverflowHint,
+    scheduleOverflowHint,
+    autosize,
+    attach,
+    userResized,
+    startResize,
+  };
+}