@1agh/maude 0.40.0 → 0.42.0

package/apps/studio/use-keyboard-discipline.tsx

@@ -6,19 +6,16 @@
  *             into the dev-server's own inputs (file tree filter, etc.)
  *             never collides.
  *
- *             Scope decision — arrow nudge applies to **artboards** only.
- *             User content inside artboards has no live-position channel
- *             (canvas surface is HTML; element positions are CSS-derived
- *             from the compiled JSX, not directly manipulable). Element
- *             nudge would require either an ephemeral CSS-transform overlay
- *             (cleaner) or a TSX rewrite channel (heavier). Out of scope
- *             for this wave — the artboard channel + dragBus.commitPositions
- *             already exists, so we leverage that and document the
- *             limitation here.
+ *             Arrow nudge applies to artboards AND to a single OUT-OF-FLOW
+ *             element (position:absolute/fixed) — the latter added in Task L1
+ *             once the `reposition-request` channel existed (the original
+ *             "no live-position channel" limitation is resolved for out-of-flow
+ *             elements: preview inline, commit the settle via reposition-request).
+ *             In-flow elements stay a no-op (nudge is ambiguous with no left/top).
  *
- *             Cmd+D duplicate is also deferred — same architectural reason
- *             (no duplicate channel). Esc is owned by the input-router's
- *             onEscape callback, so we don't duplicate it here.
+ *             Cmd+D duplicate (Task L3) + Cmd+Opt+C/V copy/paste-style (Task L4)
+ *             are handled here too, relayed to the parent shell. Esc is owned by
+ *             the input-router's onEscape callback, so we don't duplicate it.
  *
  *             Distance:
  *               • Arrow      → 1 world-unit step (DDR-028 world units, not
@@ -26,10 +23,10 @@
  *               • Shift+Arrow → 10 world-unit step.
  */
 
-import { useEffect } from 'react';
+import { useEffect, useRef } from 'react';
 
 import { useArtboardsContext, useDragStateContext } from './canvas-lib.tsx';
-import { scopedCdSelector, selectorIndex } from './dom-selection.ts';
+import { resolveSelectionEl, scopedCdSelector, selectorIndex } from './dom-selection.ts';
 import { isEditableTarget } from './input-router.tsx';
 import { type Selection, useSelectionSet } from './use-selection-set.tsx';
 
@@ -65,6 +62,16 @@ export function useKeyboardDiscipline(): void {
   const selSet = useSelectionSet();
   const artboardsCtx = useArtboardsContext();
   const dragBus = useDragStateContext();
+  // Element arrow-nudge burst (Task L1): accumulate left/top, preview inline, and
+  // commit once after a short pause (one undo per settle, not per keypress).
+  const nudgeRef = useRef<{
+    id: string;
+    beforeLeft: number;
+    beforeTop: number;
+    left: number;
+    top: number;
+    timer: ReturnType<typeof setTimeout>;
+  } | null>(null);
 
   useEffect(() => {
     if (typeof document === 'undefined') return;
@@ -101,10 +108,193 @@ export function useKeyboardDiscipline(): void {
         return;
       }
 
-      // Arrow nudge — artboards only (see file header for the why).
+      // Cmd/Ctrl+D → duplicate the single selected element (Task L3). Main-origin
+      // write, so post to the parent shell (pinned to the active canvas + undo).
+      // preventDefault so the browser doesn't bookmark the page.
+      if (isMeta && !e.altKey && !e.shiftKey && e.key.toLowerCase() === 'd') {
+        const one = selSet.selected.length === 1 ? selSet.selected[0] : null;
+        if (one?.id) {
+          e.preventDefault();
+          try {
+            window.parent.postMessage(
+              { dgn: 'duplicate-request', id: one.id, idIndex: one.index },
+              '*'
+            );
+          } catch {
+            /* detached / cross-origin */
+          }
+        }
+        return;
+      }
+
+      // Cmd/Ctrl+Opt+C / +V → copy-style / paste-style (Task L4). Copy captures the
+      // selection's authored appearance (shell-side); paste applies it to the
+      // currently selected element. The shell holds the clipboard + does the write.
+      if (isMeta && e.altKey && (e.key.toLowerCase() === 'c' || e.key.toLowerCase() === 'v')) {
+        const one = selSet.selected.length === 1 ? selSet.selected[0] : null;
+        if (one?.id) {
+          e.preventDefault();
+          try {
+            window.parent.postMessage(
+              e.key.toLowerCase() === 'c'
+                ? { dgn: 'copy-style' }
+                : { dgn: 'paste-style', id: one.id },
+              '*'
+            );
+          } catch {
+            /* detached / cross-origin */
+          }
+        }
+        return;
+      }
+
+      // Keyboard tree traversal (Task L2) — Enter = first child, Shift+Enter =
+      // parent, Tab / Shift+Tab = next / previous sibling. Mouse-free selection of
+      // the deeply-nested / overlapping elements the plan's predictability goal is
+      // about. Scoped to a single element selection + no meta modifier.
+      if (!isMeta && !e.altKey && (e.key === 'Enter' || e.key === 'Tab')) {
+        const one = selSet.selected.length === 1 ? selSet.selected[0] : null;
+        if (!one?.id) return;
+        const el = resolveSelectionEl(document, one) as HTMLElement | null;
+        if (!el) return;
+        let next: Element | null = null;
+        if (e.key === 'Enter' && !e.shiftKey) {
+          next = el.querySelector('[data-cd-id]'); // first descendant
+        } else if (e.key === 'Enter' && e.shiftKey) {
+          next = el.parentElement?.closest('[data-cd-id]') ?? null; // parent
+        } else if (e.key === 'Tab') {
+          // Next / previous stamped sibling in document order.
+          const forward = !e.shiftKey;
+          let s: Element | null = forward ? el.nextElementSibling : el.previousElementSibling;
+          while (s) {
+            if (s.hasAttribute('data-cd-id')) {
+              next = s;
+              break;
+            }
+            const inner = s.querySelector('[data-cd-id]');
+            if (inner) {
+              next = inner;
+              break;
+            }
+            s = forward ? s.nextElementSibling : s.previousElementSibling;
+          }
+        }
+        // Don't leave the artboard body (a parent hop past the artboard root).
+        if (next?.closest('.dc-artboard-body') && next.getAttribute('data-cd-id')) {
+          e.preventDefault();
+          const cdId = next.getAttribute('data-cd-id') as string;
+          const artboardId =
+            next.closest('[data-dc-screen]')?.getAttribute('data-dc-screen') ?? null;
+          const sel = scopedCdSelector(cdId, artboardId);
+          selSet.replace([
+            {
+              id: cdId,
+              selector: sel,
+              artboardId,
+              index: selectorIndex(document, sel, next),
+              tag: next.tagName.toLowerCase(),
+            },
+          ]);
+        } else if (e.key === 'Tab') {
+          // Swallow Tab even with no target, so focus doesn't jump out of the canvas.
+          e.preventDefault();
+        }
+        return;
+      }
+
+      // Delete / Backspace → request a source delete of the single selected
+      // element (feature-element-editing-robustness Stage I). The write is
+      // main-origin-only (DDR-054), so we POST the request to the parent shell,
+      // which performs it (pinned to the active canvas) + records undo. Guarded
+      // against text-editing focus above; skip modifier combos + non-single /
+      // artboard-only selections (whole-artboard delete is out of scope here).
+      if ((e.key === 'Delete' || e.key === 'Backspace') && !isMeta && !e.altKey) {
+        const one = selSet.selected.length === 1 ? selSet.selected[0] : null;
+        if (one?.id) {
+          e.preventDefault();
+          try {
+            // `index` is the DOM occurrence among same-cd-id nodes, which equals
+            // the reused-component usage index — so a shared-instance delete
+            // targets the right <Component/> usage (resolveUsageId, canvas-edit).
+            window.parent.postMessage(
+              { dgn: 'delete-request', id: one.id, idIndex: one.index },
+              '*'
+            );
+          } catch {
+            /* detached / cross-origin */
+          }
+        } else if (one?.artboardId && !one.id) {
+          // Whole-artboard delete — addressed by its `id` prop (no cd-id on the
+          // rendered <article>). Shell performs it main-origin-only + records undo.
+          e.preventDefault();
+          try {
+            window.parent.postMessage(
+              { dgn: 'delete-artboard-request', artboardId: one.artboardId },
+              '*'
+            );
+          } catch {
+            /* detached / cross-origin */
+          }
+        }
+        return;
+      }
+
       const delta = nudgeDelta({ key: e.key, shift: e.shiftKey });
       if (!delta) return;
       if (isMeta || e.altKey) return; // modifier combos reserved for future
+
+      // Arrow nudge — a single OUT-OF-FLOW element (position:absolute/fixed).
+      // In-flow elements are a no-op (nudging a flow element is ambiguous — it has
+      // no free left/top). Preview inline, commit the settle via reposition-request.
+      {
+        const one = selSet.selected.length === 1 ? selSet.selected[0] : null;
+        if (one?.id) {
+          const el = resolveSelectionEl(document, one) as HTMLElement | null;
+          if (!el) return;
+          const cs = getComputedStyle(el);
+          if (cs.position !== 'absolute' && cs.position !== 'fixed') return; // no-op
+          e.preventDefault();
+          const prev = nudgeRef.current?.id === one.id ? nudgeRef.current : null;
+          const curLeft = prev
+            ? prev.left
+            : Number.parseFloat(el.style.left) || Number.parseFloat(cs.left) || 0;
+          const curTop = prev
+            ? prev.top
+            : Number.parseFloat(el.style.top) || Number.parseFloat(cs.top) || 0;
+          const beforeLeft = prev ? prev.beforeLeft : curLeft;
+          const beforeTop = prev ? prev.beforeTop : curTop;
+          const left = curLeft + delta.dx;
+          const top = curTop + delta.dy;
+          el.style.left = `${left}px`;
+          el.style.top = `${top}px`;
+          if (prev) clearTimeout(prev.timer);
+          const id = one.id;
+          const timer = setTimeout(() => {
+            const s = nudgeRef.current;
+            nudgeRef.current = null;
+            if (!s) return;
+            try {
+              window.parent.postMessage(
+                {
+                  dgn: 'reposition-request',
+                  id: s.id,
+                  left: s.left,
+                  top: s.top,
+                  beforeLeft: s.beforeLeft,
+                  beforeTop: s.beforeTop,
+                },
+                '*'
+              );
+            } catch {
+              /* detached / cross-origin */
+            }
+          }, 350);
+          nudgeRef.current = { id, beforeLeft, beforeTop, left, top, timer };
+          return;
+        }
+      }
+
+      // Arrow nudge — artboards only (see file header for the why).
       if (!artboardsCtx || !dragBus) return;
 
       const artboardSelections = selSet.selected.filter((s) => !!s.artboardId && !s.id);

package/apps/studio/use-selection-set.tsx

@@ -60,6 +60,12 @@ export interface Selection {
   text?: string;
   dom_path?: string[];
   bounds?: { x: number; y: number; w: number; h: number } | null;
+  /** Stage D4 tail — WORLD-unit size (`offsetWidth`/`offsetHeight`, unaffected by
+   *  the `.dc-world` zoom transform, unlike `bounds` which is the SCREEN rect).
+   *  The Inspector's artboard-resize fields need the true JSX-authored size to
+   *  pre-fill correctly regardless of zoom. */
+  worldW?: number;
+  worldH?: number;
   html?: string;
   /** Phase 12.2 — authored inline-style values (knob pre-fill) + resolved computed (placeholder hint). */
   authored?: Record<string, string>;
@@ -70,6 +76,14 @@ export interface Selection {
   /** Phase 12.3 — custom HTML attributes on the element (data-, aria-, role, title…),
    *  so the panel reflects a custom attribute the user added via the escape hatch. */
   attrs?: Record<string, string>;
+  /** Stage M — the PARENT element's resolved `display` + `flex-direction`, captured
+   *  at selection time (the shell can't reach the cross-origin iframe to read them
+   *  later). Drives the Fixed/Hug/Fill sizing control: "Fill" is `flex-grow:1` on a
+   *  flex child's MAIN axis, `align-self:stretch` on its cross axis, else `100%`. Also
+   *  gates the flex-child (align-self / flex-grow…) rows so they don't show on a
+   *  block child. Absent for a detached node / no parent. */
+  parentDisplay?: string;
+  parentFlexDirection?: string;
 }
 
 interface SelectionSetValue {

package/apps/studio/use-spacing-handles.tsx

@@ -0,0 +1,388 @@
+/**
+ * @file       use-spacing-handles.tsx — Stage J (feature-element-editing-robustness)
+ * @scope      apps/studio/use-spacing-handles.tsx
+ * @purpose    On-canvas padding + gap drag. 4 small padding-edge handles (always,
+ *             for the single selected element) + one dot per flex gap (only when
+ *             the element is a flex/inline-flex container with ≥2 children).
+ *             Live preview via direct inline-style writes (mirrors
+ *             `use-element-resize.tsx`'s `applyPreview`); commit rides the SAME
+ *             `resize-request` lane the element-resize overlay already uses —
+ *             `padding-top/right/bottom/left`/`gap` were added to the shell's
+ *             `resizeElement` allowed-prop list, so this needed no new write
+ *             surface. A component-instance drag threads the Stage H3 occurrence
+ *             index the same way (`globalCdOccurrence`) so it stays local.
+ *
+ *             CSS-Grid gap editing is out of v1 scope — grid tracks are a
+ *             separate follow-up plan (`feature-grid-track-editor.md`, Stage M3).
+ */
+
+import { type ReactNode, useCallback, useEffect, useRef } from 'react';
+import { globalCdOccurrence, resolveSelectionEl } from './dom-selection.ts';
+import { isElementDragActive } from './drag-state.ts';
+import {
+  computeGapDrag,
+  computeGapMidpoints,
+  computePaddingDrag,
+  computePaddingLines,
+  flexMainAxis,
+  type PaddingSide,
+  paddingSideSet,
+} from './spacing-handles.ts';
+import { scaleFromMatrix } from './use-element-resize.tsx';
+import { useSelectionSet } from './use-selection-set.tsx';
+import { useToolMode } from './use-tool-mode.tsx';
+
+const SPACING_CSS = `
+.dc-spacing-handle {
+  position: fixed;
+  transform: translate(-50%, -50%);
+  /* Below the Stage-D resize handles (z-index 6) — at 0 padding a spacing
+     handle sits exactly on the border, where a resize mid-edge handle also
+     lives; the resize handle should win that hit-test tie. */
+  z-index: 4;
+  pointer-events: auto;
+  touch-action: none;
+  /* INV-2 — the idle-to-hover/dragging opacity bump (0.55/0.7 to 1, below) had
+     no transition, so the reduced-motion collapse further down was dead code
+     (nothing to collapse). Kept as a plain opacity transition, not a reveal/
+     unmount fade — this component still hard-toggles display to show/hide
+     the whole handle set (unlike the resize overlay's fade), so a handle is
+     grabbable the instant it appears, no half-visible window. */
+  transition: opacity 120ms cubic-bezier(0.4, 0, 0.2, 1);
+}
+.dc-spacing-handle--padding {
+  width: 10px;
+  height: 10px;
+  border-radius: 2px;
+  background: var(--maude-hud-accent, oklch(0.680 0.180 268));
+  border: 1px solid var(--maude-hud-accent-fg, oklch(0.180 0.030 268));
+  opacity: 0.55;
+}
+.dc-spacing-handle--padding:hover,
+.dc-spacing-handle--padding[data-dragging="true"] { opacity: 1; }
+.dc-spacing-handle--padding[data-side="top"],
+.dc-spacing-handle--padding[data-side="bottom"] { cursor: ns-resize; }
+.dc-spacing-handle--padding[data-side="left"],
+.dc-spacing-handle--padding[data-side="right"] { cursor: ew-resize; }
+.dc-spacing-handle--gap {
+  width: 8px;
+  height: 8px;
+  border-radius: 50%;
+  background: #FF24BD;
+  border: 1px solid rgba(255, 255, 255, 0.85);
+  opacity: 0.7;
+}
+.dc-spacing-handle--gap:hover,
+.dc-spacing-handle--gap[data-dragging="true"] { opacity: 1; }
+.dc-spacing-handle--gap[data-axis="x"] { cursor: ew-resize; }
+.dc-spacing-handle--gap[data-axis="y"] { cursor: ns-resize; }
+@media (prefers-reduced-motion: reduce) {
+  .dc-spacing-handle { transition-duration: 1ms; }
+}
+`.trim();
+
+function ensureSpacingStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('dc-spacing-css')) return;
+  const s = document.createElement('style');
+  s.id = 'dc-spacing-css';
+  s.textContent = SPACING_CSS;
+  document.head.appendChild(s);
+}
+
+function computedPx(cs: CSSStyleDeclaration, prop: string): number {
+  return Number.parseFloat(cs.getPropertyValue(prop)) || 0;
+}
+
+interface SpacingDrag {
+  pointerId: number;
+  kind: 'padding' | 'gap';
+  side: PaddingSide | null;
+  axis: 'x' | 'y';
+  el: HTMLElement;
+  cdId: string;
+  idIndex: number;
+  startClientX: number;
+  startClientY: number;
+  zoom: number;
+  startValue: number;
+  /** The single CSS property this drag writes — `padding-<side>` or `gap`. */
+  prop: string;
+  /** Inline value BEFORE the drag (`el.style.getPropertyValue(prop)` or null). */
+  before: string | null;
+  /** All 4 padding sides' inline values BEFORE the drag — for the Alt (pair) /
+   *  Alt+Shift (all) box-model modifiers (`paddingSideSet`), which can touch
+   *  sides OTHER than the one grabbed. Undefined for a gap drag. */
+  paddingBefore?: Record<PaddingSide, string | null>;
+}
+
+/** One touched property's before/after — the shape `resizeElement`'s multi-prop
+ *  `patch`/`before` objects already accept (Stage D3/L8 established this). */
+interface PropEntry {
+  prop: string;
+  before: string | null;
+}
+
+export function SpacingHandlesOverlay(): ReactNode {
+  ensureSpacingStyles();
+  const { selected } = useSelectionSet();
+  const { tool } = useToolMode();
+  const containerRef = useRef<HTMLDivElement | null>(null);
+  const rafRef = useRef<number | null>(null);
+  const dragRef = useRef<SpacingDrag | null>(null);
+  const lastCommitRef = useRef<{ el: HTMLElement; entries: PropEntry[] } | null>(null);
+
+  const one = selected.length === 1 ? selected[0] : null;
+  const cdId = one && typeof one.id === 'string' ? one.id : null;
+  const active = tool === 'move' && !!cdId;
+
+  // rAF loop — recompute + repaint every frame (pan/zoom/layout AND a live drag,
+  // since a gap drag reflows sibling children — re-deriving from the DOM each
+  // frame is simpler and more correct than hand-propagating the effect to every
+  // other gap handle).
+  useEffect(() => {
+    const c = containerRef.current;
+    if (!c) return;
+    const hideAll = () => {
+      for (const child of Array.from(c.children)) (child as HTMLElement).style.display = 'none';
+    };
+    if (!active || !one) {
+      hideAll();
+      return;
+    }
+    const tick = () => {
+      rafRef.current = null;
+      // Dogfood 2026-07-07 — a live ReorderDrag is the canvas's most DOM-churn-
+      // heavy gesture; skip this overlay's own getBoundingClientRect/
+      // getComputedStyle work while one is in flight (its handles are
+      // irrelevant mid-drag anyway — the drag has its own live-preview chrome).
+      if (isElementDragActive()) {
+        hideAll();
+        rafRef.current = requestAnimationFrame(tick);
+        return;
+      }
+      const el = resolveSelectionEl(document, one) as HTMLElement | null;
+      if (!el) {
+        hideAll();
+        rafRef.current = requestAnimationFrame(tick);
+        return;
+      }
+      const r = el.getBoundingClientRect();
+      if (r.width <= 0 && r.height <= 0) {
+        hideAll();
+        rafRef.current = requestAnimationFrame(tick);
+        return;
+      }
+      const cs = getComputedStyle(el);
+      const world = el.closest('.dc-world') as HTMLElement | null;
+      const zoom = world ? scaleFromMatrix(getComputedStyle(world).transform) : 1;
+      const padding = {
+        top: computedPx(cs, 'padding-top'),
+        right: computedPx(cs, 'padding-right'),
+        bottom: computedPx(cs, 'padding-bottom'),
+        left: computedPx(cs, 'padding-left'),
+      };
+      const lines = computePaddingLines(
+        { x: r.left, y: r.top, w: r.width, h: r.height },
+        padding,
+        zoom
+      );
+      const isFlex = cs.display === 'flex' || cs.display === 'inline-flex';
+      const axis = flexMainAxis(cs.flexDirection);
+      const gapPoints = isFlex
+        ? computeGapMidpoints(
+            Array.from(el.children).map((child) => {
+              const cr = (child as HTMLElement).getBoundingClientRect();
+              return { x: cr.left, y: cr.top, w: cr.width, h: cr.height };
+            }),
+            axis
+          )
+        : [];
+      const TOTAL = lines.length + gapPoints.length;
+      while (c.children.length < TOTAL) c.appendChild(document.createElement('div'));
+      while (c.children.length > TOTAL) c.lastChild && c.removeChild(c.lastChild);
+      let i = 0;
+      for (const line of lines) {
+        const h = c.children[i] as HTMLElement;
+        h.className = 'dc-spacing-handle dc-spacing-handle--padding';
+        h.dataset.side = line.side;
+        h.dataset.prop = `padding-${line.side}`;
+        h.dataset.axis = line.axis;
+        h.title = `padding-${line.side} · drag to scrub · alt = symmetric pair · alt+shift = all sides`;
+        h.style.display = 'block';
+        h.style.left = `${Math.round(line.x)}px`;
+        h.style.top = `${Math.round(line.y)}px`;
+        i++;
+      }
+      for (const pt of gapPoints) {
+        const h = c.children[i] as HTMLElement;
+        h.className = 'dc-spacing-handle dc-spacing-handle--gap';
+        h.dataset.side = '';
+        h.dataset.prop = 'gap';
+        h.title = 'gap · drag to scrub';
+        h.dataset.axis = axis;
+        h.style.display = 'block';
+        h.style.left = `${Math.round(pt.x)}px`;
+        h.style.top = `${Math.round(pt.y)}px`;
+        i++;
+      }
+      rafRef.current = requestAnimationFrame(tick);
+    };
+    rafRef.current = requestAnimationFrame(tick);
+    return () => {
+      if (rafRef.current != null) cancelAnimationFrame(rafRef.current);
+    };
+  }, [active, one]);
+
+  /** Commit one or more touched properties in a SINGLE `resize-request` — a
+   *  plain drag has one entry; an Alt (pair) / Alt+Shift (all sides) padding
+   *  drag has 2 or 4, all set to the SAME value (mirrors the CSS panel's own
+   *  `side()` scrub semantics — every touched side becomes the dragged value,
+   *  not each grown independently). */
+  const commit = useCallback((d: SpacingDrag, entries: PropEntry[], value: number) => {
+    if (!entries.length) return;
+    const after = `${value}px`;
+    lastCommitRef.current = { el: d.el, entries };
+    const patch: Record<string, string> = {};
+    const before: Record<string, string | null> = {};
+    for (const e of entries) {
+      patch[e.prop] = after;
+      before[e.prop] = e.before;
+    }
+    try {
+      window.parent.postMessage(
+        { dgn: 'resize-request', id: d.cdId, patch, before, idIndex: d.idIndex },
+        '*'
+      );
+    } catch {
+      /* detached / cross-origin teardown */
+    }
+  }, []);
+
+  useEffect(() => {
+    const c = containerRef.current;
+    if (!c) return;
+
+    const onDown = (e: PointerEvent) => {
+      const t = e.target as HTMLElement | null;
+      if (!t?.classList.contains('dc-spacing-handle')) return;
+      if (!one || typeof one.id !== 'string') return;
+      const el = resolveSelectionEl(document, one) as HTMLElement | null;
+      if (!el) return;
+      e.preventDefault();
+      e.stopPropagation();
+      const prop = t.dataset.prop || '';
+      const isGap = prop === 'gap';
+      const cs = getComputedStyle(el);
+      const world = el.closest('.dc-world') as HTMLElement | null;
+      const zoom = world ? scaleFromMatrix(getComputedStyle(world).transform) : 1;
+      const drag: SpacingDrag = {
+        pointerId: e.pointerId,
+        kind: isGap ? 'gap' : 'padding',
+        side: isGap ? null : ((t.dataset.side as PaddingSide) ?? null),
+        axis: (t.dataset.axis as 'x' | 'y') ?? 'x',
+        el,
+        cdId: one.id,
+        idIndex: globalCdOccurrence(document, one.id, el),
+        startClientX: e.clientX,
+        startClientY: e.clientY,
+        zoom: zoom > 0 ? zoom : 1,
+        startValue: computedPx(cs, prop),
+        prop,
+        before: el.style.getPropertyValue(prop) || null,
+        // Alt (pair) / Alt+Shift (all sides) can touch sides OTHER than the one
+        // grabbed — capture every side's PRE-drag inline value up front so a
+        // late modifier press still gets the correct undo `before`.
+        paddingBefore: isGap
+          ? undefined
+          : {
+              top: el.style.getPropertyValue('padding-top') || null,
+              right: el.style.getPropertyValue('padding-right') || null,
+              bottom: el.style.getPropertyValue('padding-bottom') || null,
+              left: el.style.getPropertyValue('padding-left') || null,
+            },
+      };
+      dragRef.current = drag;
+      t.dataset.dragging = 'true';
+      try {
+        t.setPointerCapture(e.pointerId);
+      } catch {
+        /* synthetic events may reject capture */
+      }
+    };
+
+    // Alt (pair) / Alt+Shift (all sides) — the CSS panel's own box-model scrub
+    // grammar, matched exactly (`paddingSideSet`). Gap has no "opposite side"
+    // concept, so modifiers only ever apply to a padding drag.
+    const touchedEntries = (d: SpacingDrag, ev: PointerEvent): PropEntry[] => {
+      if (d.kind === 'gap' || !d.paddingBefore) return [{ prop: d.prop, before: d.before }];
+      const sides = paddingSideSet(d.side ?? 'top', ev.altKey, ev.shiftKey);
+      return sides.map((s) => ({ prop: `padding-${s}`, before: d.paddingBefore?.[s] ?? null }));
+    };
+
+    const onMove = (e: PointerEvent) => {
+      const d = dragRef.current;
+      if (!d || e.pointerId !== d.pointerId) return;
+      e.preventDefault();
+      const dx = e.clientX - d.startClientX;
+      const dy = e.clientY - d.startClientY;
+      const next =
+        d.kind === 'gap'
+          ? computeGapDrag(d.axis, d.startValue, dx, dy, d.zoom)
+          : computePaddingDrag(d.side ?? 'top', d.startValue, dx, dy, d.zoom);
+      for (const entry of touchedEntries(d, e)) d.el.style.setProperty(entry.prop, `${next}px`);
+    };
+
+    const onUp = (e: PointerEvent) => {
+      const d = dragRef.current;
+      if (!d || e.pointerId !== d.pointerId) return;
+      dragRef.current = null;
+      const handle = containerRef.current?.querySelector<HTMLElement>(
+        `.dc-spacing-handle[data-prop="${d.prop}"][data-dragging="true"]`
+      );
+      if (handle) delete handle.dataset.dragging;
+      const dx = e.clientX - d.startClientX;
+      const dy = e.clientY - d.startClientY;
+      const next =
+        d.kind === 'gap'
+          ? computeGapDrag(d.axis, d.startValue, dx, dy, d.zoom)
+          : computePaddingDrag(d.side ?? 'top', d.startValue, dx, dy, d.zoom);
+      const entries = touchedEntries(d, e);
+      const after = `${next}px`;
+      const changed = entries.some((entry) => after !== (entry.before ?? `${d.startValue}px`));
+      if (!changed) return; // no-op guard
+      commit(d, entries, next);
+    };
+
+    // Restore the pre-drag inline value(s) if the shell reports the write
+    // failed (shares `resize-failed` with the element-resize overlay — both
+    // restore from their OWN lastCommitRef, so they don't collide).
+    const onFail = (e: MessageEvent) => {
+      const m = e.data as { dgn?: string } | null;
+      if (m?.dgn !== 'resize-failed') return;
+      if (e.source !== window.parent) return; // only the parent shell (DDR-054)
+      const last = lastCommitRef.current;
+      if (!last) return;
+      for (const entry of last.entries) {
+        if (entry.before == null) last.el.style.removeProperty(entry.prop);
+        else last.el.style.setProperty(entry.prop, entry.before);
+      }
+      lastCommitRef.current = null;
+    };
+
+    c.addEventListener('pointerdown', onDown);
+    window.addEventListener('pointermove', onMove);
+    window.addEventListener('pointerup', onUp);
+    window.addEventListener('pointercancel', onUp);
+    window.addEventListener('message', onFail);
+    return () => {
+      c.removeEventListener('pointerdown', onDown);
+      window.removeEventListener('pointermove', onMove);
+      window.removeEventListener('pointerup', onUp);
+      window.removeEventListener('pointercancel', onUp);
+      window.removeEventListener('message', onFail);
+    };
+  }, [one, commit]);
+
+  return <div ref={containerRef} aria-hidden="true" />;
+}