From da1f1ee90ccdb8e9b12e3204bc7af721e6f6d5cd Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 15:10:45 +0200
Subject: [PATCH 01/25] Multi-select: shift-click, marquee, batch delete

:selection moves from a single {:id ...} map to a vector of node ids.
Pure helpers (selected-ids, selected?, single-selected-id) plus
effectful select-one!, select-clear!, select-toggle! cover the call
sites; single-node consumers (resize handles, nudge, inspector,
inline edit) route through single-selected-id and degrade gracefully
under multi-select.

The selection overlay becomes a pool of N borders, one per selected
DOM id; the primary overlay carries the resize handles and only
exposes them when exactly one node is selected. Shift-click on the
canvas or in the layers panel toggles a node in the selection;
pointerdown on empty canvas (or padding) starts a marquee that paints
a rectangle and adds every overlapped node id on release, with Shift
extending the existing selection. Esc cancels mid-drag.

ops/remove-many is the batch counterpart to ops/remove; the :delete
shortcut now drops the entire selection in one commit, idempotent
against cascaded removals and root.

In edit mode the canvas-host gets user-select: none so Shift-click
and marquee-drag don't paint a native text-selection band over the
rendered preview; .bareforge-inline-edit re-enables user-select: text
so the inline text editor works as before.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 public/index.html                       |  23 +++
 src/bareforge/dnd/drag.cljs             | 186 +++++++++++++++++++++--
 src/bareforge/doc/ops.cljs              |  16 ++
 src/bareforge/render/selection.cljs     | 193 ++++++++++++++++--------
 src/bareforge/state.cljs                |  60 +++++++-
 src/bareforge/storage/project_file.cljs |   2 +-
 src/bareforge/ui/inspector.cljs         |  48 ++++--
 src/bareforge/ui/layers.cljs            |  21 ++-
 src/bareforge/ui/palette.cljs           |  16 +-
 src/bareforge/ui/shortcuts.cljs         |  29 ++--
 test/bareforge/doc/ops_test.cljs        |  30 ++++
 test/bareforge/state_test.cljs          |  61 +++++++-
 test/bareforge/ui/inspector_test.cljs   |  31 +++-
 test/bareforge/ui/palette_test.cljs     |  10 +-
 14 files changed, 595 insertions(+), 131 deletions(-)

diff --git a/public/index.html b/public/index.html
index 76f93bf..52325cc 100644
--- a/public/index.html
+++ b/public/index.html
@@ -111,6 +111,20 @@
       overflow: auto;
       position: relative;
     }
+    /* In edit mode, suppress native text selection inside the canvas:
+       Shift-click and marquee-drag would otherwise paint a browser
+       text-selection band over the rendered preview, fighting our own
+       multi-select. Inline text editing has its own textarea overlay,
+       which we re-enable below. Preview mode leaves selection untouched
+       so users can interact with their built page normally. */
+    .chrome[data-mode="edit"] .canvas-host {
+      user-select: none;
+      -webkit-user-select: none;
+    }
+    .bareforge-inline-edit {
+      user-select: text;
+      -webkit-user-select: text;
+    }
     .bareforge-selection-overlay {
       position: absolute;
       pointer-events: none;
@@ -157,6 +171,15 @@
     .bareforge-selection-handle[data-handle="s"]  { bottom: -5px; left: 50%;     margin-left: -5px; cursor: s-resize; }
     .bareforge-selection-handle[data-handle="sw"] { bottom: -5px; left: -5px;    cursor: sw-resize; }
     .bareforge-selection-handle[data-handle="w"]  { top: 50%;     left: -5px;    margin-top: -5px;  cursor: w-resize; }
+    .bareforge-marquee {
+      position: absolute;
+      pointer-events: none;
+      z-index: 99;
+      border: 1px dashed var(--x-color-primary, #4f46e5);
+      background: rgba(79, 70, 229, 0.08);
+    }
+    .bareforge-marquee[data-hidden] { display: none; }
+    .chrome[data-mode="preview"] .bareforge-marquee { display: none; }
     .bareforge-inline-edit {
       position: absolute;
       z-index: 101;
diff --git a/src/bareforge/dnd/drag.cljs b/src/bareforge/dnd/drag.cljs
index 9516ebf..decb626 100644
--- a/src/bareforge/dnd/drag.cljs
+++ b/src/bareforge/dnd/drag.cljs
@@ -39,7 +39,7 @@
 ;; --- mutable drag state ---------------------------------------------------
 
 (defonce ^:private drag-state
-  #js {:phase      :idle  ;; :idle | :armed | :dragging
+  #js {:phase      :idle  ;; :idle | :armed | :dragging | :marquee-armed | :marquee
        :source-tag      nil   ;; palette drag: tag name to insert
        :source-node-id  nil   ;; canvas drag: existing node id to move
        :start-x    0
@@ -55,7 +55,10 @@
        :canvas-el  nil
        :free-drag?     false     ;; true when source is a :free node
        :free-initial-x 0
-       :free-initial-y 0})
+       :free-initial-y 0
+       :marquee-el     nil       ;; the rectangle div drawn during a marquee
+       :marquee-additive? false  ;; Shift-held at marquee start: extend selection
+       })
 
 (def ^:private move-threshold 4)
 
@@ -143,6 +146,124 @@
       (unchecked-set drag-state "slot-target-name" slot-name)
       (unchecked-set drag-state "slot-target-el"   row-el))))
 
+;; --- marquee selection ---------------------------------------------------
+
+;; `start-marquee!` is paired with the existing palette/canvas drag
+;; starters and must reset state through `cleanup!`, which is defined
+;; below alongside the other public-API helpers. Forward-declare so
+;; the marquee block stays self-contained.
+(declare cleanup!)
+
+(defn- marquee-el [] (unchecked-get drag-state "marquee-el"))
+(defn- set-marquee-el! [el] (unchecked-set drag-state "marquee-el" el))
+(defn- marquee-additive? [] (unchecked-get drag-state "marquee-additive?"))
+(defn- set-marquee-additive! [v] (unchecked-set drag-state "marquee-additive?" (boolean v)))
+
+(defn- canvas-content-coord
+  "Convert a (clientX, clientY) point to the canvas host's content
+   coordinate space — i.e. the same space overlays use, accounting
+   for scroll. Returns `[x y]`."
+  [^js host client-x client-y]
+  (let [^js br (.getBoundingClientRect host)]
+    [(+ (- client-x (.-left br)) (.-scrollLeft host))
+     (+ (- client-y (.-top  br)) (.-scrollTop  host))]))
+
+(defn- ensure-marquee-el!
+  "Lazily create the rectangle div on first move. Lives inside the
+   canvas host so it scrolls in lockstep with the rendered tree, and
+   uses the same content-coord space as the selection overlay pool."
+  []
+  (or (marquee-el)
+      (let [^js host (canvas-el)
+            ^js m    (js/document.createElement "div")]
+        (.setAttribute m "class" "bareforge-marquee")
+        (.appendChild host m)
+        (set-marquee-el! m)
+        m)))
+
+(defn- update-marquee-rect!
+  "Paint the rectangle for the current cursor position."
+  [^js e]
+  (let [^js host (canvas-el)
+        [x0 y0]  (canvas-content-coord host (start-x) (start-y))
+        [x1 y1]  (canvas-content-coord host (.-clientX e) (.-clientY e))
+        left     (min x0 x1)
+        top      (min y0 y1)
+        width    (js/Math.abs (- x1 x0))
+        height   (js/Math.abs (- y1 y0))
+        ^js m    (ensure-marquee-el!)]
+    (set! (.. m -style -left)   (str left   "px"))
+    (set! (.. m -style -top)    (str top    "px"))
+    (set! (.. m -style -width)  (str width  "px"))
+    (set! (.. m -style -height) (str height "px"))))
+
+(defn- clear-marquee-el! []
+  (when-let [^js m (marquee-el)]
+    (when-let [^js p (.-parentNode m)]
+      (.removeChild p m)))
+  (set-marquee-el! nil))
+
+(defn- rects-overlap?
+  "Pure: AABB intersection test on `{:left :top :right :bottom}` maps."
+  [a b]
+  (and (< (:left a)   (:right  b))
+       (> (:right a)  (:left   b))
+       (< (:top a)    (:bottom b))
+       (> (:bottom a) (:top    b))))
+
+(defn- marquee-hits
+  "Walk every `[data-bareforge-id]` element under the canvas host and
+   return the raw DOM ids of those whose bounding box overlaps the
+   marquee rectangle. Skips root and skips the canvas-host itself.
+   Stable in document order."
+  [^js host marquee-rect]
+  (let [^js br    (.getBoundingClientRect host)
+        sl        (.-scrollLeft host)
+        st        (.-scrollTop  host)
+        ^js nodes (.querySelectorAll host "[data-bareforge-id]")
+        out       (volatile! [])]
+    (dotimes [i (.-length nodes)]
+      (let [^js el (.item nodes i)
+            id     (.getAttribute el "data-bareforge-id")]
+        (when (and id (not= id "root"))
+          (let [^js eb (.getBoundingClientRect el)
+                left   (+ (- (.-left   eb) (.-left br)) sl)
+                top    (+ (- (.-top    eb) (.-top  br)) st)
+                rect   {:left   left
+                        :top    top
+                        :right  (+ left (.-width  eb))
+                        :bottom (+ top  (.-height eb))}]
+            (when (rects-overlap? marquee-rect rect)
+              (vswap! out conj id))))))
+    @out))
+
+(defn- commit-marquee! [^js e]
+  (let [^js host (canvas-el)
+        [x0 y0]  (canvas-content-coord host (start-x) (start-y))
+        [x1 y1]  (canvas-content-coord host (.-clientX e) (.-clientY e))
+        rect     {:left (min x0 x1) :top (min y0 y1)
+                  :right (max x0 x1) :bottom (max y0 y1)}
+        hits     (marquee-hits host rect)
+        existing (if (marquee-additive?)
+                   (state/selected-ids @state/app-state)
+                   [])
+        merged   (vec (distinct (concat existing hits)))]
+    (state/set-selection! merged)))
+
+(defn- start-marquee!
+  "Arm a marquee selection from a pointerdown that landed on the canvas
+   root (no node hit). Stashes whether Shift was held so the eventual
+   commit either replaces or extends the existing selection — same
+   convention as Figma / Webflow."
+  [^js e]
+  (when-not (= :idle (phase))
+    (cleanup!))
+  (set-source-tag! nil)
+  (set-source-node-id! nil)
+  (start-xy! (.-clientX e) (.-clientY e))
+  (set-marquee-additive! (.-shiftKey e))
+  (set-phase! :marquee-armed))
+
 ;; --- ghost element --------------------------------------------------------
 
 (defn- make-ghost [tag]
@@ -336,11 +457,10 @@
       (and tid (#{:before :after} pos))
       (or (before-after-target doc tid pos)
           ;; Root has no parent; fall back to inside.
-          (palette/insertion-target doc {:id tid}))
+          (palette/insertion-target doc tid))
 
       :else
-      (let [sel (when tid {:id tid})]
-        (palette/insertion-target doc sel)))))
+      (palette/insertion-target doc tid))))
 
 (defn- update-free-drag-position!
   "Visual feedback during a :free drag. Uses CSS transform so we
@@ -415,7 +535,7 @@
           {doc' :doc id :id}
           (ops/insert-new doc parent-id slot index tag overrides)]
       (state/commit! doc')
-      (state/set-selection! {:id id}))))
+      (state/select-one! id))))
 
 (defn- commit-move! [^js _e]
   (when (valid?)
@@ -428,7 +548,7 @@
       (try
         (let [doc' (ops/move doc src-id parent-id slot index)]
           (state/commit! doc')
-          (state/set-selection! {:id src-id}))
+          (state/select-one! src-id))
         (catch :default _ nil)))))
 
 ;; --- public API -----------------------------------------------------------
@@ -438,6 +558,8 @@
   (clear-target-highlight!)
   (clear-slot-target!)
   (slot-strips/hide!)
+  (clear-marquee-el!)
+  (set-marquee-additive! false)
   (set-valid! false)
   (set-target-position! nil)
   (set-phase! :idle)
@@ -513,6 +635,16 @@
       (do (position-ghost! (ghost) e)
           (resolve-target! e)))
 
+    :marquee-armed
+    (let [dx (- (.-clientX e) (start-x))
+          dy (- (.-clientY e) (start-y))]
+      (when (>= (+ (* dx dx) (* dy dy)) (* move-threshold move-threshold))
+        (set-phase! :marquee)
+        (update-marquee-rect! e)))
+
+    :marquee
+    (update-marquee-rect! e)
+
     nil))
 
 (defn on-up! [^js e]
@@ -527,7 +659,8 @@
 
     :armed
     (let [tag     (source-tag)
-          node-id (source-node-id)]
+          node-id (source-node-id)
+          shift?  (.-shiftKey e)]
       (cleanup!)
       (cond
         ;; Palette tap (no movement) → insert at current selection.
@@ -537,7 +670,23 @@
         ;; `__seed<N>` suffix) so the selection overlay can
         ;; highlight the specific clicked element; doc-lookup
         ;; sites (inspector, shortcuts) canonicalise on read.
-        node-id (state/set-selection! {:id node-id})))
+        ;; Shift-tap toggles membership for multi-select; plain
+        ;; tap collapses the selection back to a single id.
+        node-id (if shift?
+                  (state/select-toggle! node-id)
+                  (state/select-one! node-id))))
+
+    :marquee
+    (do (commit-marquee! e)
+        (cleanup!))
+
+    :marquee-armed
+    ;; Tap on empty canvas with no movement: clear selection unless
+    ;; Shift was held (additive marquee with no rectangle is a no-op).
+    (let [additive? (marquee-additive?)]
+      (cleanup!)
+      (when-not additive?
+        (state/select-clear!)))
 
     nil))
 
@@ -550,20 +699,25 @@
    bubble phase; this one uses capture (see `install-window-listeners!`)
    so the drag layer always wins the race for a Escape-during-drag."
   [^js e]
-  (when (and (contains? #{:armed :dragging} (phase))
+  (when (and (contains? #{:armed :dragging :marquee-armed :marquee} (phase))
              (= "Escape" (.-key e)))
     (.stopImmediatePropagation e)
     (cancel!)))
 
 (defn- on-canvas-pointerdown! [^js e]
   ;; Delegate: any pointerdown inside the canvas host starts a drag on
-  ;; the nearest bareforge-rendered ancestor. Root is not draggable.
-  ;; Preview mode disables drag entirely so native click / pointer
-  ;; events flow through to the user's own components.
+  ;; the nearest bareforge-rendered ancestor. A pointerdown that
+  ;; resolves to root, or that lands on the canvas padding (no
+  ;; bareforge-rendered ancestor at all), starts a marquee selection
+  ;; instead — root is not draggable, and the padding is conceptually
+  ;; empty space. Preview mode disables both drag and marquee entirely
+  ;; so native click / pointer events flow through to the user's own
+  ;; components.
   (when (not= :preview (:mode @state/app-state))
-    (when-let [id (canvas/element->node-id (.-target e))]
-      (when (not= id "root")
-        (start-from-canvas! e id)))))
+    (let [id (canvas/element->node-id (.-target e))]
+      (cond
+        (or (nil? id) (= id "root")) (start-marquee! e)
+        :else                         (start-from-canvas! e id)))))
 
 (defn install-window-listeners!
   "Install the pointermove, pointerup, pointercancel, and keydown
diff --git a/src/bareforge/doc/ops.cljs b/src/bareforge/doc/ops.cljs
index 3ce4ddb..698f64c 100644
--- a/src/bareforge/doc/ops.cljs
+++ b/src/bareforge/doc/ops.cljs
@@ -56,6 +56,22 @@
             slot-path* (vec (butlast node-path))]
         (update-in doc slot-path* vec-remove idx)))))
 
+(defn remove-many
+  "Remove every id in `ids` (and their subtrees). Idempotent against
+   ids that disappear partway through (e.g. removing a parent
+   cascades-remove its descendants — a later id in the same set just
+   becomes a no-op). Skips root and skips already-missing paths so
+   the op is safe to feed an unfiltered selection vector."
+  [doc ids]
+  (reduce (fn [d id]
+            (let [p (m/path-to d id)]
+              (cond
+                (nil? p)         d
+                (= p [:root])    d
+                :else            (remove d id))))
+          doc
+          ids))
+
 (defn move
   "Move an existing node to a new parent/slot/idx. Moving a node under its
    own subtree is an error. Note: when moving within the same slot, the
diff --git a/src/bareforge/render/selection.cljs b/src/bareforge/render/selection.cljs
index 2d92f4f..ff68d42 100644
--- a/src/bareforge/render/selection.cljs
+++ b/src/bareforge/render/selection.cljs
@@ -1,25 +1,28 @@
 (ns bareforge.render.selection
-  "Canvas selection overlay. A thin, absolutely-positioned `<div>`
-   sibling of the rendered tree inside the canvas host is repositioned
-   on every selection / document change to draw a 1 px border *around*
-   the currently-selected element. The overlay never modifies the
-   selected element's own CSS, so it cannot interact with the user's
-   design (no box-shadow inflation, no layout shift).
+  "Canvas selection overlay. A pool of thin, absolutely-positioned
+   `<div>` siblings of the rendered tree inside the canvas host is
+   repositioned on every selection / document change to draw a 1 px
+   border *around* every currently-selected element. Overlays never
+   modify the selected elements' own CSS, so they cannot interact
+   with the user's design (no box-shadow inflation, no layout shift).
 
    Coordinates are computed relative to the canvas host's padding box,
-   which is also the containing block for the overlay (canvas-host has
-   `position: relative`). Because the overlay is a child of the same
+   which is also the containing block for the overlays (canvas-host has
+   `position: relative`). Because overlays are children of the same
    scrollable container as the rendered content, scrolling moves both
    in lockstep — no scroll listener is needed.
 
-   The overlay also renders 8 resize handles as children. Which
-   handles are interactive depends on the selected node's placement:
-   `:free` nodes get the full 8 (updates `:layout :x :y :w :h`);
-   `:flow` nodes get only E/S/SE (grow the width/height axis,
-   updating `:layout :width :height` as CSS length strings);
-   `:background` nodes and the root get none. Live visual feedback
-   writes directly to the element's inline style during drag, then
-   a single commit at pointerup keeps the undo history clean."
+   The first overlay in the pool (the 'primary') also carries 8
+   resize handles as children. Which handles are interactive depends
+   on the selected node's placement: `:free` nodes get the full 8
+   (updates `:layout :x :y :w :h`); `:flow` nodes get only E/S/SE
+   (grow the width/height axis, updating `:layout :width :height` as
+   CSS length strings); `:background` nodes and the root get none.
+   Resize is single-select only: when more than one node is selected
+   the primary overlay's `data-resize-mode` attribute is cleared so
+   the handles stay hidden. Live visual feedback writes directly to
+   the element's inline style during drag, then a single commit at
+   pointerup keeps the undo history clean."
   (:require [bareforge.doc.model :as m]
             [bareforge.doc.ops :as ops]
             [bareforge.render.canvas :as canvas]
@@ -107,7 +110,11 @@
 
 ;; --- effectful -----------------------------------------------------------
 
-(defonce ^:private overlay-state #js {:el nil :host nil})
+;; Pool of overlay elements. The first ('primary') carries the 8 resize
+;; handles; secondaries are plain border boxes. Pool grows on demand and
+;; never shrinks — extras are simply hidden via `data-hidden` when the
+;; selection contracts.
+(defonce ^:private overlay-state #js {:host nil :pool #js []})
 
 (defonce ^:private resize-state
   #js {:active?  false
@@ -119,8 +126,28 @@
        :start-x  0 :start-y  0
        :start-w  0 :start-h  0})
 
-(defn- ^js overlay-el [] (unchecked-get overlay-state "el"))
-(defn- ^js host-el    [] (unchecked-get overlay-state "host"))
+(defn- ^js host-el [] (unchecked-get overlay-state "host"))
+
+(defn- ^js pool
+  "Return the overlay pool, lazy-initialising it on first access. The
+   lazy init survives a shadow-cljs hot-reload that started under an
+   earlier version of `overlay-state` whose shape lacked the `:pool`
+   key — without it, refresh! would dereference undefined and the
+   overlay would silently stop drawing."
+  []
+  (or (unchecked-get overlay-state "pool")
+      (let [p #js []]
+        (unchecked-set overlay-state "pool" p)
+        p)))
+(defn- ^js primary-overlay []
+  (let [^js p (pool)]
+    (when (and p (pos? (.-length p)))
+      (aget p 0))))
+
+;; Backwards-compatible alias used by resize-state initialisation
+;; below — the resize machinery only ever uses the primary overlay.
+(defn- ^js overlay-el [] (primary-overlay))
+
 (defn- resize-active? [] (unchecked-get resize-state "active?"))
 
 (defn- bcr->map [^js r]
@@ -141,31 +168,71 @@
 (defn- hide! [^js overlay]
   (.setAttribute overlay "data-hidden" ""))
 
-(defn- selected-node []
-  (when-let [sel-id (get-in @state/app-state [:selection :id])]
-    (m/get-node (:document @state/app-state) sel-id)))
+(declare build-handles!)
+
+(defn- create-overlay!
+  "Append a fresh overlay element to the host and push it onto the
+   pool. The first overlay created (`primary?` true) gets the resize
+   handle children installed."
+  [primary?]
+  (let [^js o (js/document.createElement "div")]
+    (.setAttribute o "class" "bareforge-selection-overlay")
+    (.setAttribute o "data-hidden" "")
+    (.appendChild (host-el) o)
+    (.push (pool) o)
+    (when primary? (build-handles! o))
+    o))
+
+(defn- ensure-pool-size! [n]
+  (let [^js p (pool)]
+    (while (< (.-length p) n)
+      (create-overlay! false))))
+
+(defn- selection-entries
+  "Resolve `:selection` to a vector of {:id :el :node} maps for ids
+   whose DOM element exists. Missing / stale ids are dropped silently
+   so a render pass mid-edit doesn't flicker the overlay."
+  []
+  (let [doc (:document @state/app-state)]
+    (into []
+          (keep (fn [id]
+                  (when-let [^js el (canvas/dom-for-id id)]
+                    {:id   id
+                     :el   el
+                     :node (m/get-node doc (canvas/canonical-node-id id))})))
+          (state/selected-ids @state/app-state))))
 
 (defn- refresh!
-  "Read the current selection from app-state, look up its DOM element,
-   and reposition the overlay (or hide it if nothing valid is selected).
-   Sets `data-resize-mode` on the overlay to `\"free\"` or `\"flow\"`
-   so CSS can show the appropriate handle subset; root and background
-   selections clear the attribute entirely."
+  "Walk the current selection vector, position one overlay per
+   resolved DOM element, and hide any pool entries beyond that count.
+   The primary overlay carries `data-resize-mode` only when exactly
+   one node is selected and that node's placement supports resize —
+   otherwise the handles stay hidden via CSS, even though they remain
+   in the DOM as primary's children."
   []
-  (let [^js overlay (overlay-el)
-        ^js host    (host-el)]
-    (when (and overlay host)
-      (let [sel-id (get-in @state/app-state [:selection :id])
-            ^js el (canvas/dom-for-id sel-id)
-            node   (selected-node)
-            mode   (when (and node (not= "root" sel-id))
-                     (resize-mode-for-node node))]
-        (if el
-          (do (show! overlay el host)
-              (if mode
-                (.setAttribute overlay "data-resize-mode" (name mode))
-                (.removeAttribute overlay "data-resize-mode")))
-          (hide! overlay))))))
+  (let [^js host (host-el)]
+    (when host
+      (let [entries (selection-entries)
+            n       (count entries)
+            single? (= n 1)]
+        (ensure-pool-size! n)
+        (let [^js p (pool)]
+          (dotimes [i n]
+            (let [{:keys [id el node]} (nth entries i)
+                  ^js o (aget p i)
+                  primary? (zero? i)]
+              (show! o el host)
+              (if (and primary? single? (not= "root" id))
+                (let [mode (resize-mode-for-node node)]
+                  (if mode
+                    (.setAttribute o "data-resize-mode" (name mode))
+                    (.removeAttribute o "data-resize-mode")))
+                (when primary? (.removeAttribute o "data-resize-mode")))))
+          ;; Hide pool entries that are no longer needed.
+          (loop [i n]
+            (when (< i (.-length p))
+              (hide! (aget p i))
+              (recur (inc i)))))))))
 
 (declare on-resize-move! on-resize-up!)
 
@@ -245,9 +312,11 @@
 
 (defn- start-resize!
   [^js e handle-str]
-  (let [sel-id (get-in @state/app-state [:selection :id])
-        node   (selected-node)
-        ^js el (canvas/dom-for-id sel-id)
+  (let [sel-id (state/single-selected-id @state/app-state)
+        node   (when sel-id
+                 (m/get-node (:document @state/app-state)
+                             (canvas/canonical-node-id sel-id)))
+        ^js el (when sel-id (canvas/dom-for-id sel-id))
         handle (keyword handle-str)
         mode   (when node (resize-mode-for-node node))]
     (when (and node el mode
@@ -316,24 +385,20 @@
      (js/requestAnimationFrame refresh!))))
 
 (defn install!
-  "Mount the selection overlay inside `canvas-host-el`. Creates the
-   overlay element, appends it to the host, installs a watcher on
-   `state/app-state` that fires on selection / document changes, and
-   wires a window resize listener for layout-shift cases. Safe to
-   call once at app startup."
+  "Mount the selection overlay pool inside `canvas-host-el`. Seeds the
+   pool with one primary overlay (handles attached), installs a
+   watcher on `state/app-state` that fires on selection / document
+   changes, and wires a window resize listener for layout-shift
+   cases. Safe to call once at app startup."
   [^js canvas-host-el]
-  (let [overlay (js/document.createElement "div")]
-    (.setAttribute overlay "class" "bareforge-selection-overlay")
-    (.setAttribute overlay "data-hidden" "")
-    (.appendChild canvas-host-el overlay)
-    (unchecked-set overlay-state "el"   overlay)
-    (unchecked-set overlay-state "host" canvas-host-el)
-    (build-handles! overlay)
-    (schedule-refresh!)
-    (add-watch state/app-state ::selection-overlay
-               (fn [_ _ old-state new-state]
-                 (when (or (not= (:selection old-state) (:selection new-state))
-                           (not= (:document  old-state) (:document  new-state)))
-                   (schedule-refresh!))))
-    (.addEventListener js/window "resize"
-                       (fn [_] (schedule-refresh!)))))
+  (unchecked-set overlay-state "host" canvas-host-el)
+  (unchecked-set overlay-state "pool" #js [])
+  (create-overlay! true)
+  (schedule-refresh!)
+  (add-watch state/app-state ::selection-overlay
+             (fn [_ _ old-state new-state]
+               (when (or (not= (:selection old-state) (:selection new-state))
+                         (not= (:document  old-state) (:document  new-state)))
+                 (schedule-refresh!))))
+  (.addEventListener js/window "resize"
+                     (fn [_] (schedule-refresh!))))
diff --git a/src/bareforge/state.cljs b/src/bareforge/state.cljs
index 8bb9722..5fa32ae 100644
--- a/src/bareforge/state.cljs
+++ b/src/bareforge/state.cljs
@@ -7,7 +7,10 @@
   "Pure constructor for a fresh application state."
   []
   {:document     (m/empty-document)
-   :selection    nil
+   ;; Vector of selected node ids. Empty = nothing selected. Multi-select
+   ;; (Shift-click, marquee) extends this; single-node consumers route
+   ;; through `single-selected-id` which returns nil under multi-select.
+   :selection    []
    :history      {:past [] :future []}
    :mode         :edit
    :theme        {:base-preset "ocean" :overrides {}}
@@ -115,8 +118,59 @@
   [k f & args]
   (apply swap! app-state update-in [:ui k] f args))
 
-(defn set-selection! [sel]
-  (swap! app-state assoc :selection sel))
+;; --- selection helpers (pure) -------------------------------------------
+
+(defn selected-ids
+  "Pure: the current selection as a vector of node ids. Empty vector
+   when nothing is selected."
+  [state]
+  (or (:selection state) []))
+
+(defn selected?
+  "Pure: true iff `id` is in the current selection."
+  [state id]
+  (boolean (some #(= id %) (selected-ids state))))
+
+(defn single-selected-id
+  "Pure: the lone selected id, or nil if zero or 2+ are selected.
+   Single-node consumers (resize handles, nudge, inspector lookup,
+   inline edit teardown comparison) read selection through this so
+   they degrade gracefully when the user multi-selects."
+  [state]
+  (let [ids (selected-ids state)]
+    (when (= 1 (count ids)) (first ids))))
+
+;; --- selection mutators (effectful) -------------------------------------
+
+(defn set-selection!
+  "Replace the current selection with `ids` (a coll of node ids). nil
+   or an empty coll clears the selection. Order is preserved — the
+   most-recently added id ends up last, which is the natural anchor
+   for future range / shift-extend behaviour."
+  [ids]
+  (swap! app-state assoc :selection (vec ids)))
+
+(defn select-one!
+  "Replace the selection with a single id, or clear when nil."
+  [id]
+  (set-selection! (when id [id])))
+
+(defn select-clear!
+  "Drop the selection entirely. Equivalent to `(set-selection! nil)`."
+  []
+  (set-selection! nil))
+
+(defn select-toggle!
+  "Toggle membership of `id` in the current selection. Adds when
+   absent, removes when present. Used by Shift-click and the layers
+   panel's Shift-click row toggle."
+  [id]
+  (swap! app-state update :selection
+         (fn [current]
+           (let [ids (or current [])]
+             (if (some #(= id %) ids)
+               (vec (clojure.core/remove #(= id %) ids))
+               (conj (vec ids) id))))))
 
 (defn set-mode! [mode]
   (swap! app-state assoc :mode mode))
diff --git a/src/bareforge/storage/project_file.cljs b/src/bareforge/storage/project_file.cljs
index 43f5e25..e8c4051 100644
--- a/src/bareforge/storage/project_file.cljs
+++ b/src/bareforge/storage/project_file.cljs
@@ -66,7 +66,7 @@
            (-> s
                (assoc    :document  (:document parsed))
                (assoc    :theme     (or (:theme parsed) (:theme s)))
-               (assoc    :selection nil)
+               (assoc    :selection [])
                (assoc-in [:history :past]   [])
                (assoc-in [:history :future] [])
                (assoc    :dirty?    false)
diff --git a/src/bareforge/ui/inspector.cljs b/src/bareforge/ui/inspector.cljs
index ffe5097..a59960a 100644
--- a/src/bareforge/ui/inspector.cljs
+++ b/src/bareforge/ui/inspector.cljs
@@ -93,17 +93,32 @@
 
 (defn inspector-model
   "Project app-state into the view model the inspector needs. Returns
-   nil when no meaningful selection exists. The selection id may be
-   a template-instance clone's DOM id (`__seed<N>` suffix); canonicalise
-   before looking it up in the doc so canvas-tap on a clone reveals
-   the underlying template node."
+   nil when no meaningful selection exists OR when multiple distinct
+   nodes are selected (multi-select edits land in M2). The selection
+   id may be a template-instance clone's DOM id (`__seed<N>` suffix);
+   canonicalise before looking it up in the doc so canvas-tap on a
+   clone reveals the underlying template node.
+
+   Returns `{:multi <count>}` when the canonicalised, deduped selection
+   resolves to more than one doc node — the renderer surfaces a
+   read-only summary in that case so the panel doesn't simply blank
+   out and confuse the user."
   [app-state]
-  (let [sel-id (get-in app-state [:selection :id])
-        doc-id (canvas/canonical-node-id sel-id)
-        node   (when doc-id (m/get-node (:document app-state) doc-id))]
-    (when node
-      {:node node
-       :meta (registry/get-meta (:tag node))})))
+  (let [ids       (state/selected-ids app-state)
+        doc-ids   (->> ids (map canvas/canonical-node-id) (remove nil?) distinct)]
+    (cond
+      (empty? doc-ids)
+      nil
+
+      (> (count doc-ids) 1)
+      {:multi (count doc-ids)}
+
+      :else
+      (let [doc-id (first doc-ids)
+            node   (m/get-node (:document app-state) doc-id)]
+        (when node
+          {:node node
+           :meta (registry/get-meta (:tag node))})))))
 
 ;; --- effectful: editor widgets -------------------------------------------
 
@@ -895,6 +910,13 @@
           (u/el :div {:class "inspector-empty"})
           "No component selected. Click a layer or a palette item.")]))
 
+(defn- multi-view [n]
+  (u/el :div {:class "inspector-empty-state"}
+        [(u/set-text!
+          (u/el :div {:class "inspector-empty"})
+          (str n " components selected. Multi-select editing lands later — "
+               "click a single component to edit it."))]))
+
 (defn- widget-value [^js el]
   (let [v (.-value el)] (if (nil? v) "" v)))
 
@@ -2002,7 +2024,11 @@
 
 (defn- render!
   [^js host-el model]
-  (let [sections (if model
+  (let [sections (cond
+                   (and model (:multi model))
+                   [(multi-view (:multi model))]
+
+                   model
                    (let [doc        (:document @state/app-state)
                          all-fields (collect-all-fields doc)
                          t          (text-section model)
diff --git a/src/bareforge/ui/layers.cljs b/src/bareforge/ui/layers.cljs
index f0e385e..5f6b5b7 100644
--- a/src/bareforge/ui/layers.cljs
+++ b/src/bareforge/ui/layers.cljs
@@ -49,7 +49,11 @@
                    :style  (str "padding-left:" (+ 8 (* depth 14)) "px")}
                   [(u/set-text! (u/el :span {:class "layers-row-label"}) label)
                    (u/set-text! (u/el :span {:class "layers-row-tag"})   tag)])]
-    (u/on! row :click (fn [_] (state/set-selection! {:id id})))
+    (u/on! row :click
+           (fn [^js e]
+             (if (.-shiftKey e)
+               (state/select-toggle! id)
+               (state/select-one! id))))
     ;; Layer rows are also drag sources — pointerdown starts a
     ;; canvas-existing drag for the row's node so the user can
     ;; reposition deep in the tree without needing the canvas hit.
@@ -61,16 +65,19 @@
 
 (defn- render-tree! [^js host-el doc selection]
   (let [rows        (flatten-tree doc)
-        ;; Selection stores the raw DOM id so the canvas overlay can
+        ;; Selection stores raw DOM ids so the canvas overlay can
         ;; highlight the specific clicked clone; template-instance
         ;; clones carry a `__seed<N>` suffix. Layer rows key by the
-        ;; canonical doc id (no suffix), so canonicalise here before
-        ;; comparing — otherwise clicking a product card or any of
-        ;; its descendants shows no highlight in the layers panel.
-        selected-id (canvas/canonical-node-id (:id selection))]
+        ;; canonical doc id (no suffix), so canonicalise the entire
+        ;; selection vector and dedupe before deciding which rows to
+        ;; mark — otherwise clicking a product card (or any of its
+        ;; descendants) shows no highlight in the layers panel.
+        selected    (into #{}
+                          (comp (map canvas/canonical-node-id) (remove nil?))
+                          selection)]
     (.replaceChildren host-el)
     (doseq [r rows]
-      (.appendChild host-el (row-el r (= (:id r) selected-id))))))
+      (.appendChild host-el (row-el r (contains? selected (:id r)))))))
 
 (defn create
   "Build the layers panel. Installs a single watcher that rebuilds the
diff --git a/src/bareforge/ui/palette.cljs b/src/bareforge/ui/palette.cljs
index 84ed21e..d74915e 100644
--- a/src/bareforge/ui/palette.cljs
+++ b/src/bareforge/ui/palette.cljs
@@ -132,10 +132,10 @@
      append inside that slot.
    - Else if a non-container node is selected, insert as a sibling
      immediately after it (same parent, same slot, index + 1).
-   - Else append to root's default slot."
-  [doc selection]
-  (let [sel-id    (:id selection)
-        sel-node  (when sel-id (m/get-node doc sel-id))
+   - Else append to root's default slot. Pass nil for `sel-id` when
+     no single anchor exists (no selection or multi-select)."
+  [doc sel-id]
+  (let [sel-node  (when sel-id (m/get-node doc sel-id))
         container (some-> sel-node :tag container-slot)]
     (cond
       (and sel-node container)
@@ -155,15 +155,15 @@
   "Public tap-to-insert helper shared by the palette's armed-tap path
    and the dnd layer. Reads the current selection from the state atom,
    computes an insertion target, inserts, commits, and selects the new
-   node."
+   node. Multi-select degrades to root-append (no single anchor)."
   [tag]
   (let [doc       (:document @state/app-state)
-        selection (:selection @state/app-state)
-        {:keys [parent-id slot index]} (insertion-target doc selection)
+        sel-id    (state/single-selected-id @state/app-state)
+        {:keys [parent-id slot index]} (insertion-target doc sel-id)
         {doc' :doc new-id :id}
         (ops/insert-new doc parent-id slot index tag (seed-for-tag tag))]
     (state/commit! doc')
-    (state/set-selection! {:id new-id})))
+    (state/select-one! new-id)))
 
 (defn- palette-item
   "Palette items have no :click handler any more — taps and drags both
diff --git a/src/bareforge/ui/shortcuts.cljs b/src/bareforge/ui/shortcuts.cljs
index 64f4d46..39310d0 100644
--- a/src/bareforge/ui/shortcuts.cljs
+++ b/src/bareforge/ui/shortcuts.cljs
@@ -149,15 +149,19 @@
         ;; template-instance previews). Canonicalise before every
         ;; doc-side lookup so keyboard ops address the template
         ;; node the user intends, not a synthetic clone id.
-        sel-id (get-in @state/app-state [:selection :id])
-        doc-id (canvas/canonical-node-id sel-id)
-        node   (when doc-id (m/get-node (:document @state/app-state) doc-id))]
+        ;; Multi-select degrades placement-aware shortcuts (nudge,
+        ;; selection-id-aware delete) to no-op via single-selected-id
+        ;; → nil; has-selection? still reflects the broader vector.
+        single  (state/single-selected-id @state/app-state)
+        doc-id  (canvas/canonical-node-id single)
+        node    (when doc-id (m/get-node (:document @state/app-state) doc-id))
+        any-sel? (seq (state/selected-ids @state/app-state))]
     {:key               (.-key e)
      :meta?             (or (.-metaKey e) (.-ctrlKey e))
      :shift?            (.-shiftKey e)
      :tag-name          (some-> t .-tagName)
      :content-editable? (and t (.-isContentEditable t))
-     :has-selection?    (some? sel-id)
+     :has-selection?    (boolean any-sel?)
      :selection-id      doc-id
      :placement         (get-in node [:layout :placement])
      :text-editing-id   (get-in @state/app-state [:ui :text-editing-id])}))
@@ -176,7 +180,7 @@
    selection change) starts a fresh history entry."
   [dx dy]
   (let [sel-id     (canvas/canonical-node-id
-                    (get-in @state/app-state [:selection :id]))
+                     (state/single-selected-id @state/app-state))
         doc        (:document @state/app-state)
         node       (m/get-node doc sel-id)
         cur-x      (or (get-in node [:layout :x]) 0)
@@ -219,14 +223,17 @@
                                "Start a new project? Unsaved changes will be lost."))
                       (pf/new!)))
       :delete   (do (.preventDefault e)
-                    (let [sel-id (canvas/canonical-node-id
-                                  (get-in @state/app-state [:selection :id]))
-                          doc    (:document @state/app-state)
-                          doc'   (ops/remove doc sel-id)]
+                    (let [doc-ids (->> (state/selected-ids @state/app-state)
+                                       (map canvas/canonical-node-id)
+                                       distinct
+                                       (remove #{"root"})
+                                       vec)
+                          doc     (:document @state/app-state)
+                          doc'    (ops/remove-many doc doc-ids)]
                       (state/commit! doc')
-                      (state/set-selection! nil)))
+                      (state/select-clear!)))
       :exit-text-edit (do (.preventDefault e) (inline-edit/teardown!))
-      :deselect (do (.preventDefault e) (state/set-selection! nil))
+      :deselect (do (.preventDefault e) (state/select-clear!))
       nil)))
 
 (defn- on-keydown! [^js e]
diff --git a/test/bareforge/doc/ops_test.cljs b/test/bareforge/doc/ops_test.cljs
index 439c140..b9965e4 100644
--- a/test/bareforge/doc/ops_test.cljs
+++ b/test/bareforge/doc/ops_test.cljs
@@ -51,6 +51,36 @@
 (deftest remove-missing-throws
   (is (thrown? js/Error (ops/remove (empty-doc) "nope"))))
 
+(deftest remove-many-removes-each-id
+  (let [d0                    (empty-doc)
+        {d1 :doc id-a :id}    (ops/insert-new d0 "root" "default" 0 "x-a")
+        {d2 :doc id-b :id}    (ops/insert-new d1 "root" "default" 1 "x-b")
+        {d3 :doc id-c :id}    (ops/insert-new d2 "root" "default" 2 "x-c")
+        d4                    (ops/remove-many d3 [id-a id-c])]
+    (is (= [id-b] (mapv :id (get-in d4 [:root :slots "default"])))
+        "removed first and last; middle survives")))
+
+(deftest remove-many-tolerates-missing-or-already-removed
+  (let [d0                 (empty-doc)
+        {d1 :doc id :id}   (ops/insert-new d0 "root" "default" 0 "x-button")
+        ;; Removing a parent cascades — descendants in the same set
+        ;; are no-ops on subsequent passes.
+        {d2 :doc inner :id}(ops/insert-new d1 id "default" 0 "x-inner")
+        d3                 (ops/remove-many d2 [id inner "ghost"])]
+    (is (empty? (get-in d3 [:root :slots "default"])))))
+
+(deftest remove-many-skips-root
+  (let [d0 (empty-doc)
+        d1 (ops/remove-many d0 ["root" "ghost"])]
+    (is (= d0 d1)
+        "root is silently skipped — no throw, document unchanged")))
+
+(deftest remove-many-empty-coll-is-no-op
+  (let [d0                  (empty-doc)
+        {d1 :doc}           (ops/insert-new d0 "root" "default" 0 "x-button")]
+    (is (= d1 (ops/remove-many d1 [])))
+    (is (= d1 (ops/remove-many d1 nil)))))
+
 (deftest move-within-same-slot
   (let [d0                     (empty-doc)
         {d1 :doc id-a :id}     (ops/insert-new d0 "root" "default" 0 "x-a")
diff --git a/test/bareforge/state_test.cljs b/test/bareforge/state_test.cljs
index abf8bc9..e4c7046 100644
--- a/test/bareforge/state_test.cljs
+++ b/test/bareforge/state_test.cljs
@@ -140,9 +140,66 @@
   (is (= "#4f46e5" (get-in @state/app-state [:theme :overrides "--x-color-primary"])))
   (state/assoc-ui! :palette-search "nav")
   (is (= "nav" (get-in @state/app-state [:ui :palette-search])))
-  (state/set-selection! {:id "abc"})
-  (is (= {:id "abc"} (:selection @state/app-state)))
+  (state/select-one! "abc")
+  (is (= ["abc"] (:selection @state/app-state)))
   (testing "theme changes do not enter history"
     (is (= [] (get-in @state/app-state [:history :past])))
     (is (= [] (get-in @state/app-state [:history :future]))))
   (state/reset-state!))
+
+;; --- selection helpers ---------------------------------------------------
+
+(deftest selected-ids-defaults-empty
+  (is (= [] (state/selected-ids (fresh))))
+  (is (= [] (state/selected-ids {}))))
+
+(deftest selected?-and-single-selected-id
+  (let [s0 (assoc (fresh) :selection [])
+        s1 (assoc (fresh) :selection ["a"])
+        s2 (assoc (fresh) :selection ["a" "b"])]
+    (is (false? (state/selected? s0 "a")))
+    (is (true?  (state/selected? s1 "a")))
+    (is (false? (state/selected? s1 "b")))
+    (is (true?  (state/selected? s2 "b")))
+    (is (nil?   (state/single-selected-id s0)))
+    (is (= "a"  (state/single-selected-id s1)))
+    (is (nil?   (state/single-selected-id s2))
+        "multi-select degrades single-selected-id to nil")))
+
+(deftest set-selection!-normalises-to-vector
+  (state/reset-state!)
+  (state/set-selection! ["a" "b" "c"])
+  (is (= ["a" "b" "c"] (:selection @state/app-state)))
+  (state/set-selection! '("d" "e"))
+  (is (= ["d" "e"] (:selection @state/app-state))
+      "lists are coerced to vectors")
+  (state/set-selection! nil)
+  (is (= [] (:selection @state/app-state))
+      "nil clears the selection")
+  (state/reset-state!))
+
+(deftest select-one!-and-clear!
+  (state/reset-state!)
+  (state/select-one! "abc")
+  (is (= ["abc"] (:selection @state/app-state)))
+  (state/select-clear!)
+  (is (= [] (:selection @state/app-state)))
+  (state/select-one! nil)
+  (is (= [] (:selection @state/app-state))
+      "select-one! nil clears the selection")
+  (state/reset-state!))
+
+(deftest select-toggle!-add-and-remove
+  (state/reset-state!)
+  (state/select-toggle! "a")
+  (is (= ["a"] (:selection @state/app-state)))
+  (state/select-toggle! "b")
+  (is (= ["a" "b"] (:selection @state/app-state))
+      "second toggle conjs onto the existing vector — newest at tail")
+  (state/select-toggle! "a")
+  (is (= ["b"] (:selection @state/app-state))
+      "toggling a present id removes it")
+  (state/select-toggle! "b")
+  (is (= [] (:selection @state/app-state))
+      "toggling the last id clears the selection")
+  (state/reset-state!))
diff --git a/test/bareforge/ui/inspector_test.cljs b/test/bareforge/ui/inspector_test.cljs
index f654bed..36fc3bb 100644
--- a/test/bareforge/ui/inspector_test.cljs
+++ b/test/bareforge/ui/inspector_test.cljs
@@ -65,7 +65,7 @@
   (is (nil? (insp/inspector-model (state/initial-state)))))
 
 (deftest inspector-model-nil-for-missing-id
-  (let [s (assoc (state/initial-state) :selection {:id "does-not-exist"})]
+  (let [s (assoc (state/initial-state) :selection ["does-not-exist"])]
     (is (nil? (insp/inspector-model s)))))
 
 (deftest inspector-model-returns-node-and-meta
@@ -73,7 +73,7 @@
         {d1 :doc id :id} (ops/insert-new (:document s0) "root" "default" 0 "x-button")
         s1 (-> s0
                (assoc :document d1)
-               (assoc :selection {:id id}))
+               (assoc :selection [id]))
         model (insp/inspector-model s1)]
     (is (some? model))
     (is (= id             (get-in model [:node :id])))
@@ -85,8 +85,33 @@
                 (get-in model [:meta :properties]))))))
 
 (deftest inspector-model-works-for-root
-  (let [s (assoc (state/initial-state) :selection {:id "root"})
+  (let [s (assoc (state/initial-state) :selection ["root"])
         model (insp/inspector-model s)]
     (is (some? model))
     (is (= "root"        (get-in model [:node :id])))
     (is (= "x-container" (get-in model [:node :tag])))))
+
+(deftest inspector-model-multi-select-returns-multi-marker
+  (let [s0 (state/initial-state)
+        {d1 :doc id-a :id} (ops/insert-new (:document s0) "root" "default" 0 "x-button")
+        {d2 :doc id-b :id} (ops/insert-new d1 "root" "default" 1 "x-card")
+        s  (-> s0
+               (assoc :document d2)
+               (assoc :selection [id-a id-b]))
+        model (insp/inspector-model s)]
+    (is (= {:multi 2} model)
+        "two distinct doc nodes selected → :multi marker, no :node payload")))
+
+(deftest inspector-model-collapses-clones-of-one-doc-node
+  (testing "two raw DOM ids that canonicalise to the same doc node still
+            count as a single selection — clone-aware overlays don't
+            confuse the inspector."
+    (let [s0 (state/initial-state)
+          {d1 :doc id :id} (ops/insert-new (:document s0) "root" "default" 0 "x-button")
+          s  (-> s0
+                 (assoc :document d1)
+                 (assoc :selection [id (str id "__seed1")]))
+          model (insp/inspector-model s)]
+      (is (some? model))
+      (is (nil? (:multi model)))
+      (is (= id (get-in model [:node :id]))))))
diff --git a/test/bareforge/ui/palette_test.cljs b/test/bareforge/ui/palette_test.cljs
index c298f22..fbdcc0d 100644
--- a/test/bareforge/ui/palette_test.cljs
+++ b/test/bareforge/ui/palette_test.cljs
@@ -78,14 +78,14 @@
         {d1 :doc id-a :id}    (ops/insert-new d0 "root" "default" 0 "x-a")
         {d2 :doc}             (ops/insert-new d1 "root" "default" 1 "x-b")]
     (is (= {:parent-id "root" :slot "default" :index 1}
-           (p/insertion-target d2 {:id id-a}))
+           (p/insertion-target d2 id-a))
         "selecting x-a should cause the next insert to land at index 1")))
 
 (deftest insertion-target-with-root-selected-appends-inside-root
   (let [d0 (m/empty-document)
         {d1 :doc} (ops/insert-new d0 "root" "default" 0 "x-a")]
     (is (= {:parent-id "root" :slot "default" :index 1}
-           (p/insertion-target d1 {:id "root"}))
+           (p/insertion-target d1 "root"))
         "root is a container, so clicks with root selected append inside it")))
 
 (deftest insertion-target-container-selected-goes-inside
@@ -93,16 +93,16 @@
     (let [d0                    (m/empty-document)
           {d1 :doc id-nav :id}  (ops/insert-new d0 "root" "default" 0 "x-navbar")]
       (is (= {:parent-id id-nav :slot "default" :index 0}
-             (p/insertion-target d1 {:id id-nav})))))
+             (p/insertion-target d1 id-nav)))))
   (testing "selecting an x-card appends inside its default slot"
     (let [d0                   (m/empty-document)
           {d1 :doc id-card :id} (ops/insert-new d0 "root" "default" 0 "x-card")
           {d2 :doc}             (ops/insert-new d1 id-card "default" 0 "x-typography")]
       (is (= {:parent-id id-card :slot "default" :index 1}
-             (p/insertion-target d2 {:id id-card})))))
+             (p/insertion-target d2 id-card)))))
   (testing "selecting a leaf like x-button inserts as a sibling after"
     (let [d0                   (m/empty-document)
           {d1 :doc}             (ops/insert-new d0 "root" "default" 0 "x-card")
           {d2 :doc id-btn :id}  (ops/insert-new d1 "root" "default" 1 "x-button")]
       (is (= {:parent-id "root" :slot "default" :index 2}
-             (p/insertion-target d2 {:id id-btn}))))))
+             (p/insertion-target d2 id-btn))))))

From 93c6b95988af9c078a5c51fe666f93854f1df71f Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 15:16:46 +0200
Subject: [PATCH 02/25] Cmd-D duplicate, Cmd-G wrap-in selection
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

ops/duplicate deep-clones a node and its subtree with fresh ids,
inserting the clone as the next sibling. ops/duplicate-many maps
that over a selection in input order, skipping missing/root ids
silently so an unfiltered selection vector is safe to feed.

ops/wrap-many wraps a set of sibling ids in a fresh container at
the position of the lowest-indexed sibling, preserving original
document order inside the wrapper's default slot. Refuses to wrap
when ids don't share a parent+slot or include root.

Cmd-D in shortcuts/dispatch maps to :duplicate; the perform! handler
runs duplicate-many over the canonicalised selection and selects the
new clones — natural follow-up gesture is to drag the duplicates.

Cmd-G maps to [:wrap-in "x-container"]; Cmd-Shift-G maps to
:wrap-in-prompt, which uses window.prompt restricted to a small
container whitelist (x-container, x-grid, x-card, x-flex). The
wrapper becomes the new selection so the user can immediately
keep editing it.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/bareforge/doc/ops.cljs            |  99 +++++++++++++++++++++
 src/bareforge/ui/shortcuts.cljs       |  97 ++++++++++++++++++---
 test/bareforge/doc/ops_test.cljs      | 119 +++++++++++++++++++++++++-
 test/bareforge/ui/shortcuts_test.cljs |  59 +++++++++++++
 4 files changed, 361 insertions(+), 13 deletions(-)

diff --git a/src/bareforge/doc/ops.cljs b/src/bareforge/doc/ops.cljs
index 698f64c..a4a4e21 100644
--- a/src/bareforge/doc/ops.cljs
+++ b/src/bareforge/doc/ops.cljs
@@ -92,6 +92,105 @@
     (update-in removed (slot-vec-path pt new-slot)
                (fnil vec-insert []) new-idx node)))
 
+(defn- assign-fresh-ids
+  "Pure: walk `node` and its slots subtree, assigning a fresh id to
+   every node. Returns `[renamed-node next-id-counter]`. Used by
+   `duplicate` to clone a subtree without violating the document's
+   id-uniqueness invariant — every id in the cloned subtree comes
+   from the same `(ids/gen)` stream as a fresh insertion would."
+  [node next-id]
+  (let [[new-id next1] (ids/gen next-id)
+        with-id        (assoc node :id new-id)]
+    (if-let [slots (:slots node)]
+      (let [[new-slots final-id]
+            (reduce-kv
+             (fn [[acc nid] slot-name children]
+               (let [[chs nid'] (reduce
+                                 (fn [[chs cnid] child]
+                                   (let [[c' cnid'] (assign-fresh-ids child cnid)]
+                                     [(conj chs c') cnid']))
+                                 [[] nid]
+                                 children)]
+                 [(assoc acc slot-name chs) nid']))
+             [{} next1]
+             slots)]
+        [(assoc with-id :slots new-slots) final-id])
+      [with-id next1])))
+
+(defn duplicate
+  "Insert a deep clone of `id` (the entire subtree, every descendant
+   re-ided) as the next sibling. Root cannot be duplicated. Throws
+   when `id` is missing or refers to root. Returns
+   `{:doc :id}` with the top-level clone's new id."
+  [doc id]
+  (let [info (m/parent-of doc id)]
+    (when (nil? info)
+      (throw (ex-info "duplicate: cannot duplicate root or missing node"
+                      {:id id})))
+    (let [node            (m/get-node doc id)
+          [renamed next1] (assign-fresh-ids node (:next-id doc 0))
+          {:keys [parent-id slot index]} info
+          parent-path     (m/path-to doc parent-id)]
+      {:doc (-> doc
+                (assoc :next-id next1)
+                (update-in (slot-vec-path parent-path slot)
+                           (fnil vec-insert []) (inc index) renamed))
+       :id  (:id renamed)})))
+
+(defn duplicate-many
+  "Duplicate every id in `ids`, in input order. Returns
+   `{:doc :ids}` where `:ids` is a vector of the new top-level clone
+   ids in the same order — the natural new selection after a
+   multi-duplicate. Ids that no longer exist (or refer to root) are
+   silently skipped so the op is safe to feed an unfiltered selection
+   vector."
+  [doc ids]
+  (reduce (fn [{:keys [doc ids] :as acc} id]
+            (let [info (m/parent-of doc id)]
+              (if (nil? info)
+                acc
+                (let [{doc' :doc new-id :id} (duplicate doc id)]
+                  {:doc doc' :ids (conj ids new-id)}))))
+          {:doc doc :ids []}
+          ids))
+
+(defn wrap-many
+  "Wrap a set of sibling nodes in a fresh `tag` node, inserted at the
+   position of the lowest-indexed sibling. The selected ids must
+   share a parent and slot — otherwise the op is a no-op. Original
+   document order is preserved inside the wrapper's `default` slot.
+   Returns `{:doc :id}` where `:id` is the new wrapper's id, or nil
+   when the op was a no-op."
+  [doc ids tag]
+  (let [infos (->> ids
+                   (keep (fn [id]
+                           (when-let [i (m/parent-of doc id)]
+                             (assoc i :child-id id))))
+                   vec)]
+    (cond
+      (empty? infos)
+      {:doc doc :id nil}
+
+      (not= (count infos) (count ids))
+      ;; At least one id was missing or referred to root; refuse to
+      ;; wrap a partial set rather than silently dropping nodes.
+      {:doc doc :id nil}
+
+      (not (apply = (map (juxt :parent-id :slot) infos)))
+      {:doc doc :id nil}
+
+      :else
+      (let [{:keys [parent-id slot]} (first infos)
+            ordered     (sort-by :index infos)
+            insert-idx  (:index (first ordered))
+            {doc' :doc wrap-id :id}
+            (insert-new doc parent-id slot insert-idx tag)
+            wrapped (reduce (fn [d [i {child-id :child-id}]]
+                              (move d child-id wrap-id "default" i))
+                            doc'
+                            (map-indexed vector ordered))]
+        {:doc wrapped :id wrap-id}))))
+
 (defn- at [doc id]
   (or (m/path-to doc id)
       (throw (ex-info "node not found" {:id id}))))
diff --git a/src/bareforge/ui/shortcuts.cljs b/src/bareforge/ui/shortcuts.cljs
index 39310d0..92a78cd 100644
--- a/src/bareforge/ui/shortcuts.cljs
+++ b/src/bareforge/ui/shortcuts.cljs
@@ -74,9 +74,10 @@
 
 (defn dispatch
   "Project a key event into an action. Simple actions return a
-   keyword (`:undo` `:redo` `:delete` `:deselect` `:exit-text-edit`
-   `:save` `:open` `:new` `:noop`); parameterized actions return a
-   vector (`[:nudge dx dy]`). Takes a map shape:
+   keyword (`:undo` `:redo` `:delete` `:duplicate` `:wrap-in-prompt`
+   `:deselect` `:exit-text-edit` `:save` `:open` `:new` `:noop`);
+   parameterized actions return a vector (`[:nudge dx dy]`,
+   `[:wrap-in tag]`). Takes a map shape:
      {:key :meta? :shift? :tag-name :content-editable? :has-selection?
       :selection-id :placement :text-editing-id}
 
@@ -92,7 +93,9 @@
 
    Cmd+S / Cmd+O / Cmd+N map to project-file save / open / new so
    the File menu in the toolbar is an affordance, not the only
-   path to these actions."
+   path to these actions. Cmd+D duplicates the current selection;
+   Cmd+G wraps it in an x-container, with Cmd+Shift+G prompting
+   for a wrapper tag from a small whitelist."
   [{:keys [key meta? shift? has-selection? selection-id placement
            text-editing-id]
     :as event}]
@@ -113,6 +116,24 @@
       (and meta? (= "n" key) (not shift?) (not editable?))
       :new
 
+      (and meta? (= "d" key) (not shift?)
+           has-selection?
+           (not editable?))
+      :duplicate
+
+      ;; Cmd-Shift-G first so the more-specific binding wins over Cmd-G.
+      (and meta? (or (= "G" key) (and shift? (= "g" key)))
+           has-selection?
+           (not= "root" selection-id)
+           (not editable?))
+      :wrap-in-prompt
+
+      (and meta? (= "g" key) (not shift?)
+           has-selection?
+           (not= "root" selection-id)
+           (not editable?))
+      [:wrap-in "x-container"]
+
       (and (contains? #{"Delete" "Backspace"} key)
            has-selection?
            (not= "root" selection-id)
@@ -202,14 +223,66 @@
                  :last-ms    now-ms
                  :past-count (count (get-in @state/app-state [:history :past]))})))
 
+(def ^:private wrap-tag-whitelist
+  "Tags accepted by Cmd-Shift-G's prompt as a wrapper. Kept tight on
+   purpose: container components that have a `:default` slot accepting
+   multiple children. Adding a new tag here requires it to be a real
+   container in the registry, otherwise wrap-many's reparent step
+   would fail."
+  #{"x-container" "x-grid" "x-card" "x-flex"})
+
+(defn- selected-doc-ids
+  "Read the current selection, canonicalise each id, dedupe, and drop
+   `\"root\"`. Used by every multi-id action (delete / duplicate /
+   wrap) so they all see the same logical id set."
+  []
+  (->> (state/selected-ids @state/app-state)
+       (map canvas/canonical-node-id)
+       distinct
+       (remove #{"root"})
+       (remove nil?)
+       vec))
+
+(defn- duplicate! []
+  (let [ids (selected-doc-ids)]
+    (when (seq ids)
+      (let [doc (:document @state/app-state)
+            {doc' :doc new-ids :ids} (ops/duplicate-many doc ids)]
+        (state/commit! doc')
+        (state/set-selection! new-ids)))))
+
+(defn- wrap-in! [tag]
+  (let [ids (selected-doc-ids)]
+    (when (and (contains? wrap-tag-whitelist tag) (seq ids))
+      (let [doc (:document @state/app-state)
+            {doc' :doc wrap-id :id} (ops/wrap-many doc ids tag)]
+        (when wrap-id
+          (state/commit! doc')
+          (state/select-one! wrap-id))))))
+
+(defn- prompt-wrap-tag
+  "Prompt the user for a wrapper tag, restricted to `wrap-tag-whitelist`.
+   Returns the chosen tag string, or nil when the user cancels or
+   types something off-list."
+  []
+  (let [input (js/window.prompt
+                "Wrap selection in: x-container, x-grid, x-card, x-flex"
+                "x-container")]
+    (when (and (string? input)
+               (contains? wrap-tag-whitelist input))
+      input)))
+
 (defn- perform! [action ^js e]
   (cond
     (vector? action)
     (let [[op & args] action]
       (case op
-        :nudge (let [[dx dy] args]
-                 (.preventDefault e)
-                 (nudge! dx dy))))
+        :nudge   (let [[dx dy] args]
+                   (.preventDefault e)
+                   (nudge! dx dy))
+        :wrap-in (let [[tag] args]
+                   (.preventDefault e)
+                   (wrap-in! tag))))
 
     :else
     (case action
@@ -223,15 +296,15 @@
                                "Start a new project? Unsaved changes will be lost."))
                       (pf/new!)))
       :delete   (do (.preventDefault e)
-                    (let [doc-ids (->> (state/selected-ids @state/app-state)
-                                       (map canvas/canonical-node-id)
-                                       distinct
-                                       (remove #{"root"})
-                                       vec)
+                    (let [doc-ids (selected-doc-ids)
                           doc     (:document @state/app-state)
                           doc'    (ops/remove-many doc doc-ids)]
                       (state/commit! doc')
                       (state/select-clear!)))
+      :duplicate (do (.preventDefault e) (duplicate!))
+      :wrap-in-prompt (do (.preventDefault e)
+                          (when-let [tag (prompt-wrap-tag)]
+                            (wrap-in! tag)))
       :exit-text-edit (do (.preventDefault e) (inline-edit/teardown!))
       :deselect (do (.preventDefault e) (state/select-clear!))
       nil)))
diff --git a/test/bareforge/doc/ops_test.cljs b/test/bareforge/doc/ops_test.cljs
index b9965e4..5af2a4a 100644
--- a/test/bareforge/doc/ops_test.cljs
+++ b/test/bareforge/doc/ops_test.cljs
@@ -1,5 +1,5 @@
 (ns bareforge.doc.ops-test
-  (:require [cljs.test :refer [deftest is]]
+  (:require [cljs.test :refer [deftest is testing]]
             [clojure.spec.alpha :as s]
             [bareforge.doc.model :as m]
             [bareforge.doc.ops :as ops]
@@ -81,6 +81,123 @@
     (is (= d1 (ops/remove-many d1 [])))
     (is (= d1 (ops/remove-many d1 nil)))))
 
+;; --- duplicate / duplicate-many -----------------------------------------
+
+(deftest duplicate-inserts-clone-as-next-sibling
+  (let [d0                 (empty-doc)
+        {d1 :doc id :id}   (ops/insert-new d0 "root" "default" 0 "x-button")
+        {d2 :doc new-id :id} (ops/duplicate d1 id)]
+    (is (= [id new-id]
+           (mapv :id (get-in d2 [:root :slots "default"])))
+        "clone lands at index+1 as a sibling")
+    (is (not= id new-id) "clone has a fresh id")
+    (is (= "x-button" (get-in d2 [:root :slots "default" 1 :tag])))))
+
+(deftest duplicate-clones-subtree-with-fresh-ids
+  (let [d0                  (empty-doc)
+        {d1 :doc id :id}    (ops/insert-new d0 "root" "default" 0 "x-card")
+        {d2 :doc child :id} (ops/insert-new d1 id "default" 0 "x-button")
+        {d3 :doc clone :id} (ops/duplicate d2 id)
+        clone-node          (m/get-node d3 clone)
+        clone-child         (first (get-in clone-node [:slots "default"]))]
+    (is (not= clone child) "descendant ids are fresh too")
+    (is (= "x-button" (:tag clone-child)) "clone preserves child tags")
+    (is (= 4 (:next-id d3))
+        ":next-id advances by the size of the cloned subtree")))
+
+(deftest duplicate-root-throws
+  (is (thrown? js/Error (ops/duplicate (empty-doc) "root"))))
+
+(deftest duplicate-missing-throws
+  (is (thrown? js/Error (ops/duplicate (empty-doc) "ghost"))))
+
+(deftest duplicate-many-clones-each-in-input-order
+  (let [d0                 (empty-doc)
+        {d1 :doc id-a :id} (ops/insert-new d0 "root" "default" 0 "x-a")
+        {d2 :doc id-b :id} (ops/insert-new d1 "root" "default" 1 "x-b")
+        {doc' :doc new-ids :ids} (ops/duplicate-many d2 [id-a id-b])]
+    (is (= 2 (count new-ids)))
+    (is (every? string? new-ids))
+    (is (= 4 (count (get-in doc' [:root :slots "default"])))
+        "each duplicate landed alongside its original")
+    (testing ":ids matches input order"
+      (let [tags-by-id (into {} (map (juxt :id :tag))
+                             (get-in doc' [:root :slots "default"]))]
+        (is (= "x-a" (tags-by-id (first new-ids))))
+        (is (= "x-b" (tags-by-id (second new-ids))))))))
+
+(deftest duplicate-many-skips-missing
+  (let [d0                 (empty-doc)
+        {d1 :doc id :id}   (ops/insert-new d0 "root" "default" 0 "x-button")
+        {ids :ids}         (ops/duplicate-many d1 [id "ghost" "root"])]
+    (is (= 1 (count ids))
+        "ghost and root are silently skipped")))
+
+(deftest duplicate-many-empty-is-no-op
+  (let [d0 (empty-doc)
+        {doc' :doc ids :ids} (ops/duplicate-many d0 [])]
+    (is (= d0 doc'))
+    (is (= [] ids))))
+
+;; --- wrap-many ----------------------------------------------------------
+
+(deftest wrap-many-wraps-siblings-in-new-container
+  (let [d0                 (empty-doc)
+        {d1 :doc id-a :id} (ops/insert-new d0 "root" "default" 0 "x-a")
+        {d2 :doc id-b :id} (ops/insert-new d1 "root" "default" 1 "x-b")
+        {d3 :doc id-c :id} (ops/insert-new d2 "root" "default" 2 "x-c")
+        {doc' :doc wrap :id} (ops/wrap-many d3 [id-a id-c] "x-container")
+        root-children       (get-in doc' [:root :slots "default"])]
+    (is (some? wrap))
+    (testing "wrapper sits at the lowest-index sibling's old position"
+      (is (= [wrap id-b] (mapv :id root-children))))
+    (testing "wrapped children move into the wrapper's default slot"
+      (let [wrap-node (m/get-node doc' wrap)]
+        (is (= [id-a id-c] (mapv :id (get-in wrap-node [:slots "default"]))))
+        (is (= "x-container" (:tag wrap-node)))))))
+
+(deftest wrap-many-preserves-document-order-inside-wrapper
+  (let [d0                 (empty-doc)
+        {d1 :doc id-a :id} (ops/insert-new d0 "root" "default" 0 "x-a")
+        {d2 :doc id-b :id} (ops/insert-new d1 "root" "default" 1 "x-b")
+        {d3 :doc id-c :id} (ops/insert-new d2 "root" "default" 2 "x-c")
+        ;; Selection arrived in reverse order; the op should still
+        ;; reorder children by original index inside the wrapper.
+        {doc' :doc wrap :id} (ops/wrap-many d3 [id-c id-a id-b] "x-container")]
+    (is (= [id-a id-b id-c]
+           (mapv :id (get-in (m/get-node doc' wrap) [:slots "default"]))))))
+
+(deftest wrap-many-single-id-still-wraps
+  (let [d0                 (empty-doc)
+        {d1 :doc id :id}   (ops/insert-new d0 "root" "default" 0 "x-button")
+        {doc' :doc wrap :id} (ops/wrap-many d1 [id] "x-container")]
+    (is (some? wrap))
+    (is (= [wrap] (mapv :id (get-in doc' [:root :slots "default"]))))
+    (is (= [id]   (mapv :id (get-in (m/get-node doc' wrap) [:slots "default"]))))))
+
+(deftest wrap-many-rejects-non-siblings
+  (let [d0                  (empty-doc)
+        {d1 :doc id-a :id}  (ops/insert-new d0 "root" "default" 0 "x-card")
+        {d2 :doc id-inner :id} (ops/insert-new d1 id-a "default" 0 "x-button")
+        ;; id-a is a direct child of root; id-inner is nested under id-a.
+        ;; Different parents → wrap-many is a no-op.
+        {doc' :doc wrap :id} (ops/wrap-many d2 [id-a id-inner] "x-container")]
+    (is (nil? wrap))
+    (is (= d2 doc') "document unchanged when ids don't share a parent")))
+
+(deftest wrap-many-rejects-when-any-id-is-root
+  (let [d0                 (empty-doc)
+        {d1 :doc id :id}   (ops/insert-new d0 "root" "default" 0 "x-button")
+        {doc' :doc wrap :id} (ops/wrap-many d1 [id "root"] "x-container")]
+    (is (nil? wrap))
+    (is (= d1 doc'))))
+
+(deftest wrap-many-empty-is-no-op
+  (let [d0 (empty-doc)
+        {doc' :doc wrap :id} (ops/wrap-many d0 [] "x-container")]
+    (is (nil? wrap))
+    (is (= d0 doc'))))
+
 (deftest move-within-same-slot
   (let [d0                     (empty-doc)
         {d1 :doc id-a :id}     (ops/insert-new d0 "root" "default" 0 "x-a")
diff --git a/test/bareforge/ui/shortcuts_test.cljs b/test/bareforge/ui/shortcuts_test.cljs
index f415d12..ad940a6 100644
--- a/test/bareforge/ui/shortcuts_test.cljs
+++ b/test/bareforge/ui/shortcuts_test.cljs
@@ -219,6 +219,65 @@
     (is (= :noop
            (k/dispatch (assoc free-selected :key "ArrowLeft" :meta? true))))))
 
+;; --- duplicate ----------------------------------------------------------
+
+(def ^:private with-selection
+  (assoc base
+         :has-selection? true
+         :selection-id   "n_3"))
+
+(deftest dispatch-cmd-d-duplicates
+  (is (= :duplicate
+         (k/dispatch (assoc with-selection :key "d" :meta? true)))))
+
+(deftest dispatch-cmd-d-noop-without-selection
+  (is (= :noop
+         (k/dispatch (assoc base :key "d" :meta? true)))))
+
+(deftest dispatch-cmd-d-ignored-in-editable
+  (is (= :noop
+         (k/dispatch (assoc with-selection :key "d" :meta? true
+                                           :tag-name "INPUT")))))
+
+(deftest dispatch-cmd-shift-d-is-noop
+  (testing "Cmd+Shift+D is reserved (browser bookmark variants);
+            we only bind plain Cmd+D"
+    (is (= :noop
+           (k/dispatch (assoc with-selection :key "d" :meta? true :shift? true))))))
+
+;; --- wrap-in ------------------------------------------------------------
+
+(deftest dispatch-cmd-g-wraps-in-x-container
+  (is (= [:wrap-in "x-container"]
+         (k/dispatch (assoc with-selection :key "g" :meta? true)))))
+
+(deftest dispatch-cmd-g-noop-without-selection
+  (is (= :noop
+         (k/dispatch (assoc base :key "g" :meta? true)))))
+
+(deftest dispatch-cmd-g-noop-on-root
+  (testing "wrapping root makes no sense — handled by the dispatch
+            guard, mirroring the :delete pattern"
+    (is (= :noop
+           (k/dispatch (assoc with-selection :key "g" :meta? true
+                                             :selection-id "root"))))))
+
+(deftest dispatch-cmd-g-ignored-in-editable
+  (is (= :noop
+         (k/dispatch (assoc with-selection :key "g" :meta? true
+                                           :tag-name "X-SEARCH-FIELD")))))
+
+(deftest dispatch-cmd-shift-g-prompts
+  (is (= :wrap-in-prompt
+         (k/dispatch (assoc with-selection :key "g" :meta? true :shift? true))))
+  (is (= :wrap-in-prompt
+         (k/dispatch (assoc with-selection :key "G" :meta? true :shift? true)))))
+
+(deftest dispatch-cmd-shift-g-noop-on-root
+  (is (= :noop
+         (k/dispatch (assoc with-selection :key "g" :meta? true :shift? true
+                                           :selection-id "root")))))
+
 ;; --- coalesce? -----------------------------------------------------------
 
 (def ^:private last-rec

From dffd7b3a0b303cf912beb6509e74d6fa83a5a107 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 15:26:16 +0200
Subject: [PATCH 03/25] M2.1: drag-to-scrub on numeric inspector rows
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Inspector field labels for :number kind editors and the free-coord
:layout fields (x/y/w/h) become horizontal drag handles. Pointerdown
captures the start value; pointermove computes new = start + dx,
optionally x10 with Shift; pointerup releases. The first move of a
drag commits normally so the pre-drag state lands in :past, and
every subsequent move uses commit-coalesced! so the entire scrub
collapses into a single undo entry — the same pattern arrow-key
nudge already uses.

The mechanism is opt-in: each scrubbable widget builder calls
attach-scrub-meta! to stash a {:read-fn :commit-fn! :step} spec on
the widget element; the field-row wrapper detects the spec and
wires pointer-scrub! on the row's label, adding the is-scrubbable
class so CSS can show ew-resize on hover and suppress text
selection. Non-numeric rows are unaffected.

CSS-length-shaped attributes (width/height/padding/margin) and
percentage / rem / em values stay non-scrubbable for now —
preserving the suffix while scrubbing needs its own design and is
deferred to a follow-up. Free-coord layout fields are clean numbers
in the document, so they scrub directly.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 public/index.html               |   9 ++
 src/bareforge/ui/inspector.cljs | 171 +++++++++++++++++++++++++++++---
 2 files changed, 165 insertions(+), 15 deletions(-)

diff --git a/public/index.html b/public/index.html
index 52325cc..f22752d 100644
--- a/public/index.html
+++ b/public/index.html
@@ -340,6 +340,15 @@
       color: var(--x-color-text-muted, rgba(127, 127, 127, 0.7));
       font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
     }
+    /* Numeric labels become drag-to-scrub handles. The `is-scrubbable`
+       class is added by `pointer-scrub!` only when the widget exposes
+       a scrub spec, so non-numeric labels keep their default cursor. */
+    .inspector-field-label.is-scrubbable {
+      cursor: ew-resize;
+      user-select: none;
+      -webkit-user-select: none;
+      touch-action: none;
+    }
     .inspector-field-widget { width: 100%; }
     /* Compact x-color-picker for the Inspector. Halves the main
        colour-area height and tightens the strip heights + gap so a
diff --git a/src/bareforge/ui/inspector.cljs b/src/bareforge/ui/inspector.cljs
index a59960a..af27e62 100644
--- a/src/bareforge/ui/inspector.cljs
+++ b/src/bareforge/ui/inspector.cljs
@@ -153,6 +153,101 @@
   (or (some-> e .-detail (.-value))
       (some-> e .-target .-value)))
 
+;; --- numeric drag (M2.1) -----------------------------------------------
+
+(defn- ^js attach-scrub-meta!
+  "Stash a scrub spec on a widget element. `field-row` reads it back
+   to wire a horizontal-drag scrubber on the row's label. Spec map:
+   `{:read-fn :commit-fn! :step}`. Returns the element for thread-
+   friendly use in builder pipelines."
+  [^js el spec]
+  (set! (.-bareforgeScrub el) spec)
+  el)
+
+(defn- read-scrub-meta [^js el]
+  (when el (.-bareforgeScrub el)))
+
+(defonce ^:private scrub-state
+  ;; One global drag-in-flight tracker is enough — only one inspector
+  ;; row can be scrubbed at a time, and a label captures the pointer
+  ;; so other handlers don't compete.
+  #js {:active? false
+       :start-x 0
+       :start-val 0
+       :first? true
+       :pointer-id nil
+       :label nil
+       :input nil
+       :commit-fn nil
+       :step 1})
+
+(defn- on-scrub-move! [^js e]
+  (when (.-active? scrub-state)
+    (.preventDefault e)
+    (let [dx        (- (.-clientX e) (.-start-x scrub-state))
+          step-px   (.-step scrub-state)
+          mult      (if (.-shiftKey e) 10 1)
+          start-val (.-start-val scrub-state)
+          new-val   (+ start-val (* dx step-px mult))
+          ;; Snap to an integer when the step is integer-valued; for
+          ;; sub-unit steps fall through with the raw float.
+          rounded   (if (zero? (mod step-px 1))
+                      (js/Math.round new-val)
+                      new-val)
+          ^js input (.-input scrub-state)
+          first?    (.-first? scrub-state)
+          commit-fn (.-commit-fn scrub-state)]
+      (commit-fn rounded first?)
+      (when input (u/set-attr! input :value (str rounded)))
+      (when first? (set! (.-first? scrub-state) false)))))
+
+(defn- end-scrub! []
+  (let [^js label (.-label scrub-state)
+        pid       (.-pointer-id scrub-state)]
+    (when (and label pid)
+      (try (.releasePointerCapture label pid) (catch :default _ nil)))
+    (set! (.-active? scrub-state) false)
+    (set! (.-label scrub-state) nil)
+    (set! (.-input scrub-state) nil)
+    (set! (.-commit-fn scrub-state) nil)
+    (set! (.-pointer-id scrub-state) nil)
+    (.removeEventListener js/window "pointermove" on-scrub-move!)
+    (.removeEventListener js/window "pointerup"   end-scrub!)
+    (.removeEventListener js/window "pointercancel" end-scrub!)))
+
+(defn- pointer-scrub!
+  "Wire pointerdown on `label-el` so a horizontal drag scrubs the
+   numeric value of `input-el`. `read-fn` returns the current numeric
+   value (nil to suppress the gesture). `commit-fn!` is called as
+   `(new-val first?)`; the first call pushes a fresh history entry
+   via `state/commit!`, every later call uses `state/commit-coalesced!`
+   so the whole drag undoes as a single step. Shift multiplies the
+   step by 10."
+  [^js label-el ^js input-el read-fn commit-fn! step]
+  (.. label-el -classList (add "is-scrubbable"))
+  (u/on! label-el :pointerdown
+         (fn [^js e]
+           (let [v (read-fn)]
+             (when (number? v)
+               (.preventDefault e)
+               (try (.setPointerCapture label-el (.-pointerId e))
+                    (catch :default _ nil))
+               (set! (.-active? scrub-state)    true)
+               (set! (.-start-x scrub-state)    (.-clientX e))
+               (set! (.-start-val scrub-state)  v)
+               (set! (.-first? scrub-state)     true)
+               (set! (.-pointer-id scrub-state) (.-pointerId e))
+               (set! (.-label scrub-state)      label-el)
+               (set! (.-input scrub-state)      input-el)
+               (set! (.-commit-fn scrub-state)  commit-fn!)
+               (set! (.-step scrub-state)       (or step 1))
+               ;; Window-level move/up means the drag survives the
+               ;; pointer leaving the label, which is the natural
+               ;; gesture (drag continues until release).
+               (.addEventListener js/window "pointermove"   on-scrub-move!)
+               (.addEventListener js/window "pointerup"     end-scrub!)
+               (.addEventListener js/window "pointercancel" end-scrub!))))))
+
 (defn- read-event-checked ^js [^js e]
   (let [d (.-detail e)]
     (cond
@@ -206,18 +301,37 @@
 
 (defn- build-search-field [node prop spec]
   (let [transform (:transform prop)
+        numeric?  (= "number" (:type spec))
         el        (-> (u/el :x-search-field
                             (cond-> {:class "inspector-field-widget"}
-                              (= "number" (:type spec)) (assoc :type "number")))
+                              numeric? (assoc :type "number")))
                       (tag-widget! (:name prop) "text" transform))
-        current   (current-value node prop)]
+        current   (current-value node prop)
+        node-id   (:id node)
+        attr-name (:name prop)]
     (when current (u/set-attr! el :value current))
     (u/on! el :x-search-field-input
            (fn [^js e]
              (let [v (read-event-value e)
                    v (if transform (transform-for-commit transform v) v)]
-               (commit-attr! (:id node) (:name prop) v))))
-    el))
+               (commit-attr! node-id attr-name v))))
+    (cond-> el
+      numeric?
+      (attach-scrub-meta!
+        {:read-fn   (fn []
+                      (let [doc (:document @state/app-state)
+                            n   (m/get-node doc node-id)
+                            raw (current-value n prop)]
+                        (when (and raw (not= "" raw))
+                          (let [n (js/parseFloat raw)]
+                            (when-not (js/isNaN n) n)))))
+         :commit-fn! (fn [new-val first?]
+                       (let [doc  (:document @state/app-state)
+                             doc' (ops/set-attr doc node-id attr-name (str new-val))]
+                         (if first?
+                           (state/commit! doc')
+                           (state/commit-coalesced! doc'))))
+         :step       1}))))
 
 (defn- build-widget [node prop]
   (let [spec (editor-spec prop)]
@@ -314,19 +428,39 @@
 (defn- build-free-coord-field
   "Numeric/length editor for one of the :layout :x :y :w :h fields.
    Most useful when the node's placement is :free, but shown
-   unconditionally so users can pre-fill coordinates before toggling."
+   unconditionally so users can pre-fill coordinates before toggling.
+   Free-coord fields always store numbers (the reconciler turns them
+   into px lengths), so the row is uniformly scrubbable."
   [node layout-key placeholder]
   (let [el      (-> (u/el :x-search-field
                           {:class "inspector-field-widget"
                            :placeholder placeholder})
                     (tag-widget! (str "__layout__/" (name layout-key)) "layout"))
-        raw     (get-in node [:layout layout-key])]
+        raw     (get-in node [:layout layout-key])
+        node-id (:id node)]
     (when raw (u/set-attr! el :value (str raw)))
     (u/on! el :x-search-field-input
            (fn [^js e]
              (let [v (read-event-value e)]
-               (commit-with! ops/set-layout (:id node) layout-key (parse-length-value v)))))
-    el))
+               (commit-with! ops/set-layout node-id layout-key (parse-length-value v)))))
+    (attach-scrub-meta!
+      el
+      {:read-fn    (fn []
+                     (let [doc (:document @state/app-state)
+                           n   (get-in (m/get-node doc node-id)
+                                       [:layout layout-key])]
+                       (cond
+                         (number? n) n
+                         (string? n) (let [parsed (js/parseFloat n)]
+                                       (when-not (js/isNaN parsed) parsed))
+                         :else       nil)))
+       :commit-fn! (fn [new-val first?]
+                     (let [doc  (:document @state/app-state)
+                           doc' (ops/set-layout doc node-id layout-key new-val)]
+                       (if first?
+                         (state/commit! doc')
+                         (state/commit-coalesced! doc'))))
+       :step       1})))
 
 (defn- build-layout-textarea
   "Multi-line editor for the free-form `:extra-style` layout field.
@@ -696,10 +830,14 @@
     container))
 
 (defn- field-row-with-binding [label widget node prop all-fields]
-  (u/el :div {:class "inspector-field"}
-        [(u/set-text! (u/el :div {:class "inspector-field-label"}) label)
-         widget
-         (build-bind-toggle node prop all-fields)]))
+  (let [label-el (u/set-text! (u/el :div {:class "inspector-field-label"}) label)]
+    (when-let [scrub (read-scrub-meta widget)]
+      (pointer-scrub! label-el widget
+                      (:read-fn scrub) (:commit-fn! scrub) (:step scrub)))
+    (u/el :div {:class "inspector-field"}
+          [label-el
+           widget
+           (build-bind-toggle node prop all-fields)])))
 
 ;; --- section builders ----------------------------------------------------
 
@@ -736,9 +874,12 @@
           [label-el body-el])))
 
 (defn- field-row [label widget]
-  (u/el :div {:class "inspector-field"}
-        [(u/set-text! (u/el :div {:class "inspector-field-label"}) label)
-         widget]))
+  (let [label-el (u/set-text! (u/el :div {:class "inspector-field-label"}) label)]
+    (when-let [scrub (read-scrub-meta widget)]
+      (pointer-scrub! label-el widget
+                      (:read-fn scrub) (:commit-fn! scrub) (:step scrub)))
+    (u/el :div {:class "inspector-field"}
+          [label-el widget])))
 
 (defn- attributes-section [{:keys [node meta]} all-fields]
   (let [props (:properties meta)

From 169d217b47bc6df1f80fd9f703a8d7486e016028 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 15:31:44 +0200
Subject: [PATCH 04/25] Scrub: default unset numerics to 0
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Original M2.1 read-fns returned nil when a numeric attribute was
empty, which short-circuited the pointerdown handler's
`(when (number? v) ...)` guard — the gesture engaged the cursor
hint but nothing else, so dragging an unset min/max/step or a
non-:free x/y/w/h field did nothing visible.

Both scrub-eligible builders now fall back to 0 when the underlying
value is missing or unparseable, so the drag picks up at zero and
populates the field as the user drags. Existing numeric values
behave exactly as before.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/bareforge/ui/inspector.cljs | 31 ++++++++++++++++++++-----------
 1 file changed, 20 insertions(+), 11 deletions(-)

diff --git a/src/bareforge/ui/inspector.cljs b/src/bareforge/ui/inspector.cljs
index af27e62..21ae657 100644
--- a/src/bareforge/ui/inspector.cljs
+++ b/src/bareforge/ui/inspector.cljs
@@ -319,12 +319,17 @@
       numeric?
       (attach-scrub-meta!
         {:read-fn   (fn []
-                      (let [doc (:document @state/app-state)
-                            n   (m/get-node doc node-id)
-                            raw (current-value n prop)]
-                        (when (and raw (not= "" raw))
-                          (let [n (js/parseFloat raw)]
-                            (when-not (js/isNaN n) n)))))
+                      ;; Empty / non-numeric attr starts the drag at 0
+                      ;; so unset fields are still scrubbable from
+                      ;; nothing — otherwise the gesture would silently
+                      ;; do nothing on a fresh component.
+                      (let [doc    (:document @state/app-state)
+                            n      (m/get-node doc node-id)
+                            raw    (current-value n prop)
+                            parsed (when (and raw (not= "" raw))
+                                     (let [p (js/parseFloat raw)]
+                                       (when-not (js/isNaN p) p)))]
+                        (or parsed 0)))
          :commit-fn! (fn [new-val first?]
                        (let [doc  (:document @state/app-state)
                              doc' (ops/set-attr doc node-id attr-name (str new-val))]
@@ -446,14 +451,18 @@
     (attach-scrub-meta!
       el
       {:read-fn    (fn []
+                     ;; Default to 0 when the field is empty so the
+                     ;; gesture engages immediately — useful when
+                     ;; placement is being changed to :free and the
+                     ;; user wants to scrub the new coord into shape.
                      (let [doc (:document @state/app-state)
-                           n   (get-in (m/get-node doc node-id)
+                           v   (get-in (m/get-node doc node-id)
                                        [:layout layout-key])]
                        (cond
-                         (number? n) n
-                         (string? n) (let [parsed (js/parseFloat n)]
-                                       (when-not (js/isNaN parsed) parsed))
-                         :else       nil)))
+                         (number? v) v
+                         (string? v) (let [parsed (js/parseFloat v)]
+                                       (if (js/isNaN parsed) 0 parsed))
+                         :else       0)))
        :commit-fn! (fn [new-val first?]
                      (let [doc  (:document @state/app-state)
                            doc' (ops/set-layout doc node-id layout-key new-val)]

From f9bb7e8d158a1c41eaad054a5635c244555c3986 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 15:39:12 +0200
Subject: [PATCH 05/25] M2.2: Cmd-Opt-C / Cmd-Opt-V copy and paste attributes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Cmd-Opt-C captures the single-selected node's :attrs + :props into
an in-memory clipboard slot under :ui :clipboard :attrs (no history,
no DOM clipboard). Cmd-Opt-V applies that snapshot onto every
canonicalised id in the current selection, filtered by each target
tag's supported attributes — pasting an x-button's `variant` onto
an x-card silently drops it instead of stamping an unknown attr.

The gesture deliberately lives on Cmd-Opt-C/V instead of plain Cmd-C/V
so the browser's native copy/paste keeps working in inspector text
fields and the layers panel; the editable-target guard already
covers most surfaces, but the alt requirement keeps the canvas
gesture out of muscle-memory range of native copy/paste entirely.

ops/set-attrs and ops/set-props are the batch counterparts to set-
attr / set-prop — nil values dispatch to the unset path so blanket-
pasting a sparse clipboard correctly clears keys absent on the
source. They're also the foundation for M2.3 multi-select edit.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/bareforge/doc/ops.cljs            | 24 +++++++++
 src/bareforge/state.cljs              | 18 +++++++
 src/bareforge/ui/shortcuts.cljs       | 74 ++++++++++++++++++++++++---
 test/bareforge/doc/ops_test.cljs      | 43 ++++++++++++++++
 test/bareforge/state_test.cljs        | 17 ++++++
 test/bareforge/ui/shortcuts_test.cljs | 39 ++++++++++++++
 6 files changed, 208 insertions(+), 7 deletions(-)

diff --git a/src/bareforge/doc/ops.cljs b/src/bareforge/doc/ops.cljs
index a4a4e21..3f6775f 100644
--- a/src/bareforge/doc/ops.cljs
+++ b/src/bareforge/doc/ops.cljs
@@ -208,6 +208,30 @@
 (defn unset-attr [doc id k]   (update-in doc (conj (at doc id) :attrs) dissoc k))
 (defn set-prop   [doc id k v] (assoc-in  doc (conj (at doc id) :props k) v))
 (defn unset-prop [doc id k]   (update-in doc (conj (at doc id) :props) dissoc k))
+
+(defn set-attrs
+  "Apply a map of attribute name → value to one node in a single
+   update. Nil values dispatch to `unset-attr` so blanket-pasting a
+   sparse clipboard clears any keys that were absent on the source.
+   Used by attribute paste; safe to call with an empty map (no-op)."
+  [doc id attr-map]
+  (reduce-kv (fn [d k v]
+               (if (nil? v)
+                 (unset-attr d id k)
+                 (set-attr d id k v)))
+             doc
+             (or attr-map {})))
+
+(defn set-props
+  "Counterpart to `set-attrs` for boolean / JS-side properties stored
+   under `:props`. Keys are keywords. Nil values unset."
+  [doc id prop-map]
+  (reduce-kv (fn [d k v]
+               (if (nil? v)
+                 (unset-prop d id k)
+                 (set-prop d id k v)))
+             doc
+             (or prop-map {})))
 (defn set-text   [doc id t]   (assoc-in  doc (conj (at doc id) :text) t))
 
 (defn set-inner-html
diff --git a/src/bareforge/state.cljs b/src/bareforge/state.cljs
index 5fa32ae..e60110f 100644
--- a/src/bareforge/state.cljs
+++ b/src/bareforge/state.cljs
@@ -172,6 +172,24 @@
                (vec (clojure.core/remove #(= id %) ids))
                (conj (vec ids) id))))))
 
+;; --- attribute clipboard ------------------------------------------------
+
+(defn clipboard-attrs
+  "Pure: read the in-memory attribute clipboard, or nil when nothing
+   has been copied. Shape:
+     `{:source-tag <tag> :attrs {<name> <v>} :props {<keyword> <v>}}`."
+  [state]
+  (get-in state [:ui :clipboard :attrs]))
+
+(defn set-clipboard-attrs!
+  "Replace the attribute clipboard with `entry`, or clear when nil.
+   Lives under `:ui` so it bypasses history — copy/paste is a workflow
+   gesture, not a document edit."
+  [entry]
+  (if (nil? entry)
+    (swap! app-state update-in [:ui :clipboard] dissoc :attrs)
+    (swap! app-state assoc-in  [:ui :clipboard :attrs] entry)))
+
 (defn set-mode! [mode]
   (swap! app-state assoc :mode mode))
 
diff --git a/src/bareforge/ui/shortcuts.cljs b/src/bareforge/ui/shortcuts.cljs
index 92a78cd..4d84f93 100644
--- a/src/bareforge/ui/shortcuts.cljs
+++ b/src/bareforge/ui/shortcuts.cljs
@@ -5,6 +5,7 @@
    real listener to `state/*` calls."
   (:require [bareforge.doc.model :as m]
             [bareforge.doc.ops :as ops]
+            [bareforge.meta.registry :as registry]
             [bareforge.render.canvas :as canvas]
             [bareforge.state :as state]
             [bareforge.storage.project-file :as pf]
@@ -75,11 +76,11 @@
 (defn dispatch
   "Project a key event into an action. Simple actions return a
    keyword (`:undo` `:redo` `:delete` `:duplicate` `:wrap-in-prompt`
-   `:deselect` `:exit-text-edit` `:save` `:open` `:new` `:noop`);
-   parameterized actions return a vector (`[:nudge dx dy]`,
-   `[:wrap-in tag]`). Takes a map shape:
-     {:key :meta? :shift? :tag-name :content-editable? :has-selection?
-      :selection-id :placement :text-editing-id}
+   `:copy-attrs` `:paste-attrs` `:deselect` `:exit-text-edit` `:save`
+   `:open` `:new` `:noop`); parameterized actions return a vector
+   (`[:nudge dx dy]`, `[:wrap-in tag]`). Takes a map shape:
+     {:key :meta? :alt? :shift? :tag-name :content-editable?
+      :has-selection? :selection-id :placement :text-editing-id}
 
    Arrow keys nudge the selected node's `:layout :x / :y` by 1 px
    (or 10 px with Shift), but only when the selection has `:free`
@@ -96,7 +97,7 @@
    path to these actions. Cmd+D duplicates the current selection;
    Cmd+G wraps it in an x-container, with Cmd+Shift+G prompting
    for a wrapper tag from a small whitelist."
-  [{:keys [key meta? shift? has-selection? selection-id placement
+  [{:keys [key meta? alt? shift? has-selection? selection-id placement
            text-editing-id]
     :as event}]
   (let [editable? (editable-target? event)]
@@ -116,7 +117,18 @@
       (and meta? (= "n" key) (not shift?) (not editable?))
       :new
 
-      (and meta? (= "d" key) (not shift?)
+      (and meta? alt? (= "c" key) (not shift?)
+           has-selection?
+           (not= "root" selection-id)
+           (not editable?))
+      :copy-attrs
+
+      (and meta? alt? (= "v" key) (not shift?)
+           has-selection?
+           (not editable?))
+      :paste-attrs
+
+      (and meta? (= "d" key) (not shift?) (not alt?)
            has-selection?
            (not editable?))
       :duplicate
@@ -179,6 +191,7 @@
         any-sel? (seq (state/selected-ids @state/app-state))]
     {:key               (.-key e)
      :meta?             (or (.-metaKey e) (.-ctrlKey e))
+     :alt?              (.-altKey e)
      :shift?            (.-shiftKey e)
      :tag-name          (some-> t .-tagName)
      :content-editable? (and t (.-isContentEditable t))
@@ -251,6 +264,51 @@
         (state/commit! doc')
         (state/set-selection! new-ids)))))
 
+(defn- supported-attr-names
+  "Set of attribute names the registry advertises for `tag`. Used to
+   filter pasted attrs/props to keys the target tag actually accepts —
+   pasting an x-button's `variant` onto an x-card should silently
+   drop, not stamp an unknown attribute."
+  [tag]
+  (set (map :name (:properties (registry/get-meta tag)))))
+
+(defn- copy-attrs! []
+  (when-let [id (some-> (state/single-selected-id @state/app-state)
+                        canvas/canonical-node-id)]
+    (when-let [n (and (not= "root" id)
+                      (m/get-node (:document @state/app-state) id))]
+      (state/set-clipboard-attrs!
+        {:source-tag (:tag n)
+         :attrs      (or (:attrs n) {})
+         :props      (or (:props n) {})}))))
+
+(defn- paste-attrs! []
+  (when-let [{:keys [attrs props]} (state/clipboard-attrs @state/app-state)]
+    (let [target-ids (selected-doc-ids)]
+      (when (seq target-ids)
+        (let [doc  (:document @state/app-state)
+              doc' (reduce
+                     (fn [d id]
+                       (let [tag    (some-> (m/get-node d id) :tag)
+                             ok     (when tag (supported-attr-names tag))]
+                         (if (and tag (seq ok))
+                           (let [attrs* (select-keys attrs ok)
+                                 ;; Boolean :props are keyed by keyword;
+                                 ;; cross-reference against the string
+                                 ;; supported-attrs set via `name`.
+                                 props* (into {}
+                                          (filter (fn [[k _]]
+                                                    (contains? ok (name k)))
+                                                  props))]
+                             (-> d
+                                 (ops/set-attrs id attrs*)
+                                 (ops/set-props id props*)))
+                           d)))
+                     doc
+                     target-ids)]
+          (when (not= doc doc')
+            (state/commit! doc')))))))
+
 (defn- wrap-in! [tag]
   (let [ids (selected-doc-ids)]
     (when (and (contains? wrap-tag-whitelist tag) (seq ids))
@@ -305,6 +363,8 @@
       :wrap-in-prompt (do (.preventDefault e)
                           (when-let [tag (prompt-wrap-tag)]
                             (wrap-in! tag)))
+      :copy-attrs  (do (.preventDefault e) (copy-attrs!))
+      :paste-attrs (do (.preventDefault e) (paste-attrs!))
       :exit-text-edit (do (.preventDefault e) (inline-edit/teardown!))
       :deselect (do (.preventDefault e) (state/select-clear!))
       nil)))
diff --git a/test/bareforge/doc/ops_test.cljs b/test/bareforge/doc/ops_test.cljs
index 5af2a4a..b56adc0 100644
--- a/test/bareforge/doc/ops_test.cljs
+++ b/test/bareforge/doc/ops_test.cljs
@@ -198,6 +198,49 @@
     (is (nil? wrap))
     (is (= d0 doc'))))
 
+;; --- set-attrs / set-props ----------------------------------------------
+
+(deftest set-attrs-applies-each-pair
+  (let [d0                (empty-doc)
+        {d1 :doc id :id}  (ops/insert-new d0 "root" "default" 0 "x-button")
+        d2                (ops/set-attrs d1 id {"variant" "primary"
+                                                 "label"   "Click"})
+        node              (m/get-node d2 id)]
+    (is (= "primary" (get-in node [:attrs "variant"])))
+    (is (= "Click"   (get-in node [:attrs "label"])))))
+
+(deftest set-attrs-nil-value-unsets
+  (let [d0               (empty-doc)
+        {d1 :doc id :id} (ops/insert-new d0 "root" "default" 0 "x-button")
+        d2               (ops/set-attr d1 id "variant" "primary")
+        d3               (ops/set-attrs d2 id {"variant" nil
+                                               "label"   "Click"})
+        node             (m/get-node d3 id)]
+    (is (nil? (get-in node [:attrs "variant"]))
+        "nil values dispatch to unset-attr")
+    (is (= "Click" (get-in node [:attrs "label"])))))
+
+(deftest set-attrs-empty-and-nil-noop
+  (let [d0               (empty-doc)
+        {d1 :doc id :id} (ops/insert-new d0 "root" "default" 0 "x-button")]
+    (is (= d1 (ops/set-attrs d1 id {})))
+    (is (= d1 (ops/set-attrs d1 id nil)))))
+
+(deftest set-props-applies-each-pair-keyword-keys
+  (let [d0               (empty-doc)
+        {d1 :doc id :id} (ops/insert-new d0 "root" "default" 0 "x-button")
+        d2               (ops/set-props d1 id {:disabled true :loading false})
+        node             (m/get-node d2 id)]
+    (is (true?  (get-in node [:props :disabled])))
+    (is (false? (get-in node [:props :loading])))))
+
+(deftest set-props-nil-value-unsets
+  (let [d0               (empty-doc)
+        {d1 :doc id :id} (ops/insert-new d0 "root" "default" 0 "x-button")
+        d2               (ops/set-prop d1 id :disabled true)
+        d3               (ops/set-props d2 id {:disabled nil})]
+    (is (nil? (get-in (m/get-node d3 id) [:props :disabled])))))
+
 (deftest move-within-same-slot
   (let [d0                     (empty-doc)
         {d1 :doc id-a :id}     (ops/insert-new d0 "root" "default" 0 "x-a")
diff --git a/test/bareforge/state_test.cljs b/test/bareforge/state_test.cljs
index e4c7046..c959921 100644
--- a/test/bareforge/state_test.cljs
+++ b/test/bareforge/state_test.cljs
@@ -203,3 +203,20 @@
   (is (= [] (:selection @state/app-state))
       "toggling the last id clears the selection")
   (state/reset-state!))
+
+;; --- attribute clipboard --------------------------------------------------
+
+(deftest clipboard-attrs-defaults-nil
+  (is (nil? (state/clipboard-attrs (fresh)))))
+
+(deftest set-clipboard-attrs-roundtrip
+  (state/reset-state!)
+  (let [entry {:source-tag "x-button"
+               :attrs {"variant" "primary"}
+               :props {:disabled true}}]
+    (state/set-clipboard-attrs! entry)
+    (is (= entry (state/clipboard-attrs @state/app-state))))
+  (state/set-clipboard-attrs! nil)
+  (is (nil? (state/clipboard-attrs @state/app-state))
+      "nil clears the clipboard")
+  (state/reset-state!))
diff --git a/test/bareforge/ui/shortcuts_test.cljs b/test/bareforge/ui/shortcuts_test.cljs
index ad940a6..3a37010 100644
--- a/test/bareforge/ui/shortcuts_test.cljs
+++ b/test/bareforge/ui/shortcuts_test.cljs
@@ -278,6 +278,45 @@
          (k/dispatch (assoc with-selection :key "g" :meta? true :shift? true
                                            :selection-id "root")))))
 
+;; --- copy / paste attrs -------------------------------------------------
+
+(deftest dispatch-cmd-opt-c-copies-attrs
+  (is (= :copy-attrs
+         (k/dispatch (assoc with-selection :key "c" :meta? true :alt? true)))))
+
+(deftest dispatch-cmd-opt-c-noop-on-root
+  (is (= :noop
+         (k/dispatch (assoc with-selection :key "c" :meta? true :alt? true
+                                           :selection-id "root")))))
+
+(deftest dispatch-cmd-opt-c-noop-without-selection
+  (is (= :noop
+         (k/dispatch (assoc base :key "c" :meta? true :alt? true)))))
+
+(deftest dispatch-plain-cmd-c-is-noop
+  (testing "plain Cmd-C still falls through to the browser's native copy
+            so users can copy text from inspector inputs / layers panel"
+    (is (= :noop
+           (k/dispatch (assoc with-selection :key "c" :meta? true))))))
+
+(deftest dispatch-cmd-opt-v-pastes-attrs
+  (is (= :paste-attrs
+         (k/dispatch (assoc with-selection :key "v" :meta? true :alt? true)))))
+
+(deftest dispatch-cmd-opt-v-noop-without-selection
+  (is (= :noop
+         (k/dispatch (assoc base :key "v" :meta? true :alt? true)))))
+
+(deftest dispatch-cmd-opt-c-ignored-in-editable
+  (is (= :noop
+         (k/dispatch (assoc with-selection :key "c" :meta? true :alt? true
+                                           :tag-name "INPUT")))))
+
+(deftest dispatch-cmd-opt-v-ignored-in-editable
+  (is (= :noop
+         (k/dispatch (assoc with-selection :key "v" :meta? true :alt? true
+                                           :tag-name "X-TEXT-FIELD")))))
+
 ;; --- coalesce? -----------------------------------------------------------
 
 (def ^:private last-rec

From 6d2971b917b61fbcf0fb8feb0ec9006008466aea Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 15:42:33 +0200
Subject: [PATCH 06/25] Cmd-Opt-C / Cmd-Opt-V: match macOS .code fallback
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

On macOS US layout Option+C produces 'ç' and Option+V produces '√' —
the literal `.key` value never equalled "c" / "v", so dispatch fell
through and the gesture was silently swallowed. event-descriptor now
also captures `.code`, and dispatch matches either ("c" + "KeyC" /
"v" + "KeyV") so the same gesture works across macOS / Linux /
Windows. Added a regression test for the Option-modified key path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/bareforge/ui/shortcuts.cljs       | 16 ++++++++++++----
 test/bareforge/ui/shortcuts_test.cljs | 14 ++++++++++++++
 2 files changed, 26 insertions(+), 4 deletions(-)

diff --git a/src/bareforge/ui/shortcuts.cljs b/src/bareforge/ui/shortcuts.cljs
index 4d84f93..26cf281 100644
--- a/src/bareforge/ui/shortcuts.cljs
+++ b/src/bareforge/ui/shortcuts.cljs
@@ -97,10 +97,17 @@
    path to these actions. Cmd+D duplicates the current selection;
    Cmd+G wraps it in an x-container, with Cmd+Shift+G prompting
    for a wrapper tag from a small whitelist."
-  [{:keys [key meta? alt? shift? has-selection? selection-id placement
+  [{:keys [key code meta? alt? shift? has-selection? selection-id placement
            text-editing-id]
     :as event}]
-  (let [editable? (editable-target? event)]
+  (let [editable? (editable-target? event)
+        ;; macOS US layout: Option+C produces "ç", Option+V produces
+        ;; "√" — the literal `key` no longer matches. `code` is the
+        ;; physical-key identifier ("KeyC", "KeyV"), unaffected by
+        ;; modifiers, so we match either to keep the gesture portable
+        ;; across macOS / Linux / Windows.
+        c-letter? (or (= "c" key) (= "KeyC" code))
+        v-letter? (or (= "v" key) (= "KeyV" code))]
     (cond
       (and meta? (= "z" key) (not shift?) (not editable?))
       :undo
@@ -117,13 +124,13 @@
       (and meta? (= "n" key) (not shift?) (not editable?))
       :new
 
-      (and meta? alt? (= "c" key) (not shift?)
+      (and meta? alt? c-letter? (not shift?)
            has-selection?
            (not= "root" selection-id)
            (not editable?))
       :copy-attrs
 
-      (and meta? alt? (= "v" key) (not shift?)
+      (and meta? alt? v-letter? (not shift?)
            has-selection?
            (not editable?))
       :paste-attrs
@@ -190,6 +197,7 @@
         node    (when doc-id (m/get-node (:document @state/app-state) doc-id))
         any-sel? (seq (state/selected-ids @state/app-state))]
     {:key               (.-key e)
+     :code              (.-code e)
      :meta?             (or (.-metaKey e) (.-ctrlKey e))
      :alt?              (.-altKey e)
      :shift?            (.-shiftKey e)
diff --git a/test/bareforge/ui/shortcuts_test.cljs b/test/bareforge/ui/shortcuts_test.cljs
index 3a37010..6e64593 100644
--- a/test/bareforge/ui/shortcuts_test.cljs
+++ b/test/bareforge/ui/shortcuts_test.cljs
@@ -317,6 +317,20 @@
          (k/dispatch (assoc with-selection :key "v" :meta? true :alt? true
                                            :tag-name "X-TEXT-FIELD")))))
 
+(deftest dispatch-cmd-opt-c-matches-macos-modified-key
+  (testing "On macOS US layout Option+C produces 'ç', so dispatch must
+            also accept the physical .code 'KeyC' as the letter source.
+            We supply the modified key — the matching .code value
+            should still resolve the action."
+    (is (= :copy-attrs
+           (k/dispatch (assoc with-selection
+                              :key "ç" :code "KeyC"
+                              :meta? true :alt? true))))
+    (is (= :paste-attrs
+           (k/dispatch (assoc with-selection
+                              :key "√" :code "KeyV"
+                              :meta? true :alt? true))))))
+
 ;; --- coalesce? -----------------------------------------------------------
 
 (def ^:private last-rec

From 051858a808010ed6e9e161ed7ae0a4da6a4c5daf Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 15:49:31 +0200
Subject: [PATCH 07/25] M2.3: multi-select inspector edits shared attributes
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

inspector-model under multi-select now surfaces every selected
node and its tag set instead of a bare count, and the inspector's
multi-mode rebuilds as a "Shared attributes" section: every property
that exists on every selected tag (matched by :name and :kind)
becomes an editable row. Mixed values render with a "Mixed"
placeholder and an .is-mixed class (dashed border, slight opacity)
so it's obvious which rows are uniform versus divergent.

Editing a row dispatches a single ops/set-attrs-many (or set-props-
many for booleans) commit, applying the user's value to every
selected node. The doc-changed watcher branch short-circuits in
multi-mode so per-keystroke commits don't tear down the input the
user is typing into; visual "Mixed" markers may lag until the user
re-enters multi-select, an acceptable v1 trade-off.

Widget coverage in v1: enum, string-short, string-long, number,
boolean. CSS-var, layout, and seed-record editors stay single-
select-only — they need their own multi-edit story (different
sources of truth) and the UX for partial overlap there is not
obviously a win.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 public/index.html                     |   8 ++
 src/bareforge/doc/ops.cljs            |  23 ++++
 src/bareforge/ui/inspector.cljs       | 190 +++++++++++++++++++++++---
 test/bareforge/doc/ops_test.cljs      |  27 ++++
 test/bareforge/ui/inspector_test.cljs |  41 +++++-
 5 files changed, 266 insertions(+), 23 deletions(-)

diff --git a/public/index.html b/public/index.html
index f22752d..5cfefea 100644
--- a/public/index.html
+++ b/public/index.html
@@ -350,6 +350,14 @@
       touch-action: none;
     }
     .inspector-field-widget { width: 100%; }
+    /* Multi-select shared-attr widgets render the .is-mixed class
+       when values disagree across the selected nodes. A subtle
+       border tint plus muted text on the placeholder makes the
+       state legible without shouting at the user. */
+    .inspector-field-widget.is-mixed {
+      opacity: 0.85;
+      border-style: dashed;
+    }
     /* Compact x-color-picker for the Inspector. Halves the main
        colour-area height and tightens the strip heights + gap so a
        picker with alpha still fits where the default (alpha-less)
diff --git a/src/bareforge/doc/ops.cljs b/src/bareforge/doc/ops.cljs
index 3f6775f..871c04c 100644
--- a/src/bareforge/doc/ops.cljs
+++ b/src/bareforge/doc/ops.cljs
@@ -232,6 +232,29 @@
                  (set-prop d id k v)))
              doc
              (or prop-map {})))
+
+(defn set-attrs-many
+  "Apply `attr-map` to every id in `ids` in a single document update.
+   Foundation for multi-select inspector edit — one user input
+   becomes one commit covering N nodes. Skips ids that no longer
+   exist so an unfiltered selection vector is safe."
+  [doc ids attr-map]
+  (reduce (fn [d id]
+            (if (m/path-to d id)
+              (set-attrs d id attr-map)
+              d))
+          doc
+          (or ids [])))
+
+(defn set-props-many
+  "Counterpart of `set-attrs-many` for boolean props."
+  [doc ids prop-map]
+  (reduce (fn [d id]
+            (if (m/path-to d id)
+              (set-props d id prop-map)
+              d))
+          doc
+          (or ids [])))
 (defn set-text   [doc id t]   (assoc-in  doc (conj (at doc id) :text) t))
 
 (defn set-inner-html
diff --git a/src/bareforge/ui/inspector.cljs b/src/bareforge/ui/inspector.cljs
index 21ae657..1a9237e 100644
--- a/src/bareforge/ui/inspector.cljs
+++ b/src/bareforge/ui/inspector.cljs
@@ -93,25 +93,29 @@
 
 (defn inspector-model
   "Project app-state into the view model the inspector needs. Returns
-   nil when no meaningful selection exists OR when multiple distinct
-   nodes are selected (multi-select edits land in M2). The selection
-   id may be a template-instance clone's DOM id (`__seed<N>` suffix);
-   canonicalise before looking it up in the doc so canvas-tap on a
-   clone reveals the underlying template node.
-
-   Returns `{:multi <count>}` when the canonicalised, deduped selection
-   resolves to more than one doc node — the renderer surfaces a
-   read-only summary in that case so the panel doesn't simply blank
-   out and confuse the user."
+   nil when no meaningful selection exists. The selection id may be a
+   template-instance clone's DOM id (`__seed<N>` suffix); canonicalise
+   before looking it up in the doc so canvas-tap on a clone reveals
+   the underlying template node.
+
+   Single-select returns `{:node :meta}`. Multi-select (>1 distinct
+   doc nodes) returns `{:multi true :nodes [...] :tags #{...}}`; the
+   renderer uses that to show shared-attribute editors."
   [app-state]
-  (let [ids       (state/selected-ids app-state)
-        doc-ids   (->> ids (map canvas/canonical-node-id) (remove nil?) distinct)]
+  (let [ids     (state/selected-ids app-state)
+        doc-ids (->> ids (map canvas/canonical-node-id) (remove nil?) distinct)]
     (cond
       (empty? doc-ids)
       nil
 
       (> (count doc-ids) 1)
-      {:multi (count doc-ids)}
+      (let [nodes (->> doc-ids
+                       (keep #(m/get-node (:document app-state) %))
+                       vec)]
+        (when (seq nodes)
+          {:multi true
+           :nodes nodes
+           :tags  (set (map :tag nodes))}))
 
       :else
       (let [doc-id (first doc-ids)
@@ -1060,12 +1064,148 @@
           (u/el :div {:class "inspector-empty"})
           "No component selected. Click a layer or a palette item.")]))
 
-(defn- multi-view [n]
-  (u/el :div {:class "inspector-empty-state"}
-        [(u/set-text!
-          (u/el :div {:class "inspector-empty"})
-          (str n " components selected. Multi-select editing lands later — "
-               "click a single component to edit it."))]))
+;; --- multi-select shared editors (M2.3) ---------------------------------
+
+(defn shared-properties
+  "Pure: properties that exist on every tag in `tags` with the same
+   `:name` and `:kind`. Returns the descriptor from the first tag
+   (the others are equivalent on the dimensions the inspector cares
+   about). Used by the multi-select attribute section to decide
+   which rows to render."
+  [tags]
+  (let [meta-list  (mapv registry/get-meta tags)
+        first-list (-> meta-list first :properties)]
+    (if (or (empty? meta-list) (empty? first-list))
+      []
+      (filterv
+        (fn [prop]
+          (every?
+            (fn [m]
+              (some #(and (= (:name prop) (:name %))
+                          (= (:kind prop) (:kind %)))
+                    (:properties m)))
+            (rest meta-list)))
+        first-list))))
+
+(defn joint-attr-value
+  "Pure: read attribute `prop` across `nodes` and return
+   `{:value :mixed?}`. `:value` is the common value when every node
+   agrees, the first node's value otherwise. `:mixed?` is true iff
+   the values disagree."
+  [nodes prop]
+  (let [vs (mapv #(current-value % prop) nodes)]
+    {:value  (first vs)
+     :mixed? (not (apply = vs))}))
+
+(defn- multi-set-attr! [ids attr-name v]
+  (let [doc  (:document @state/app-state)
+        v    (if (or (nil? v) (= "" v)) nil v)
+        doc' (ops/set-attrs-many doc ids {attr-name v})]
+    (state/commit! doc')))
+
+(defn- multi-set-prop! [ids prop-name v]
+  (let [doc  (:document @state/app-state)
+        doc' (ops/set-props-many doc ids {(keyword prop-name) v})]
+    (state/commit! doc')))
+
+(defn- build-multi-search-field [nodes prop spec]
+  (let [{:keys [value mixed?]} (joint-attr-value nodes prop)
+        transform (:transform prop)
+        numeric?  (= "number" (:type spec))
+        el        (-> (u/el :x-search-field
+                            (cond-> {:class "inspector-field-widget"}
+                              numeric? (assoc :type "number")
+                              mixed?   (assoc :placeholder "Mixed")))
+                      (tag-widget! (:name prop) "text" transform))
+        ids       (mapv :id nodes)]
+    (when (and (not mixed?) value (not= "" value))
+      (u/set-attr! el :value value))
+    (when mixed?
+      (.. el -classList (add "is-mixed")))
+    (u/on! el :x-search-field-input
+           (fn [^js e]
+             (let [v (read-event-value e)
+                   v (if transform (transform-for-commit transform v) v)]
+               (multi-set-attr! ids (:name prop) v))))
+    el))
+
+(defn- build-multi-text-area [nodes prop]
+  (let [{:keys [value mixed?]} (joint-attr-value nodes prop)
+        el  (-> (u/el :x-text-area
+                      (cond-> {:class "inspector-field-widget"}
+                        mixed? (assoc :placeholder "Mixed")))
+                (tag-widget! (:name prop) "text"))
+        ids (mapv :id nodes)]
+    (when (and (not mixed?) value (not= "" value))
+      (u/set-attr! el :value value))
+    (when mixed?
+      (.. el -classList (add "is-mixed")))
+    (u/on! el :x-text-area-input
+           (fn [^js e]
+             (multi-set-attr! ids (:name prop) (read-event-value e))))
+    el))
+
+(defn- build-multi-enum [nodes prop]
+  (let [{:keys [value mixed?]} (joint-attr-value nodes prop)
+        sel-el  (-> (u/el :x-select {:class "inspector-field-widget"})
+                    (tag-widget! (:name prop) "text"))
+        ids     (mapv :id nodes)]
+    ;; Prepend a "—" sentinel option only in mixed mode so the user
+    ;; can see "values differ" without an explicit choice having been
+    ;; made; selecting any concrete option then commits to all.
+    (doseq [opt (cond-> (vec (:choices prop))
+                  mixed? (->> (cons "—") vec))]
+      (let [^js o (js/document.createElement "option")]
+        (.setAttribute o "value" opt)
+        (set! (.-textContent o) opt)
+        (.appendChild sel-el o)))
+    (when (and (not mixed?) value)
+      (u/set-attr! sel-el :value value))
+    (when mixed?
+      (u/set-attr! sel-el :value "—")
+      (.. sel-el -classList (add "is-mixed")))
+    (u/on! sel-el :x-select-input
+           (fn [^js e]
+             (let [v (read-event-value e)]
+               (when (not= v "—")
+                 (multi-set-attr! ids (:name prop) v)))))
+    sel-el))
+
+(defn- build-multi-boolean [nodes prop]
+  (let [vs       (mapv #(boolean (get-in % [:props (keyword (:name prop))])) nodes)
+        mixed?   (not (apply = vs))
+        value    (first vs)
+        el       (-> (u/el :x-switch (cond-> {:class "inspector-field-widget"}
+                                       value (assoc :checked "")))
+                     (tag-widget! (:name prop) "boolean"))
+        ids      (mapv :id nodes)]
+    (when mixed?
+      (.. el -classList (add "is-mixed"))
+      ;; Indeterminate-ish: render off so the first toggle force-
+      ;; sets all to true, the next toggle force-sets all to false.
+      (.removeAttribute el "checked"))
+    (u/on! el :x-switch-change
+           (fn [^js e]
+             (multi-set-prop! ids (:name prop) (boolean (read-event-value e)))))
+    el))
+
+(defn- build-multi-widget [nodes prop]
+  (let [spec (editor-spec prop)]
+    (case (:kind spec)
+      :boolean     (build-multi-boolean   nodes prop)
+      :enum        (build-multi-enum      nodes prop)
+      :string-long (build-multi-text-area nodes prop)
+      (build-multi-search-field nodes prop spec))))
+
+(defn- multi-attributes-section [{:keys [nodes tags]}]
+  (let [props (shared-properties tags)
+        body  (if (seq props)
+                (for [p props]
+                  (field-row (display-label p) (build-multi-widget nodes p)))
+                [(u/set-text! (u/el :div {:class "inspector-empty"})
+                              "No shared attributes between the selected components.")])]
+    (section (str (count nodes) " components selected — Shared attributes")
+             body)))
 
 (defn- widget-value [^js el]
   (let [v (.-value el)] (if (nil? v) "" v)))
@@ -2176,7 +2316,7 @@
   [^js host-el model]
   (let [sections (cond
                    (and model (:multi model))
-                   [(multi-view (:multi model))]
+                   [(multi-attributes-section model)]
 
                    model
                    (let [doc        (:document @state/app-state)
@@ -2238,6 +2378,16 @@
                      (and doc-changed? (nil? new-model))
                      (render! body nil)
 
+                     ;; Multi-select: doc changed (most likely from
+                     ;; the user editing a shared-attr field). Skip
+                     ;; the rebuild — every keystroke would otherwise
+                     ;; throw away the focused input. The committed
+                     ;; values are correct in the doc; the panel's
+                     ;; visual "Mixed" markers may lag until the user
+                     ;; re-enters multi-select, which is acceptable.
+                     (and doc-changed? (:multi new-model))
+                     nil
+
                      doc-changed?
                      (let [old-model   (inspector-model old-state)
                            old-node    (:node old-model)
diff --git a/test/bareforge/doc/ops_test.cljs b/test/bareforge/doc/ops_test.cljs
index b56adc0..78ff52c 100644
--- a/test/bareforge/doc/ops_test.cljs
+++ b/test/bareforge/doc/ops_test.cljs
@@ -241,6 +241,33 @@
         d3               (ops/set-props d2 id {:disabled nil})]
     (is (nil? (get-in (m/get-node d3 id) [:props :disabled])))))
 
+(deftest set-attrs-many-applies-to-each-id
+  (let [d0                 (empty-doc)
+        {d1 :doc id-a :id} (ops/insert-new d0 "root" "default" 0 "x-button")
+        {d2 :doc id-b :id} (ops/insert-new d1 "root" "default" 1 "x-button")
+        d3                 (ops/set-attrs-many d2 [id-a id-b]
+                                               {"variant" "primary"})]
+    (is (= "primary" (get-in (m/get-node d3 id-a) [:attrs "variant"])))
+    (is (= "primary" (get-in (m/get-node d3 id-b) [:attrs "variant"])))))
+
+(deftest set-attrs-many-skips-missing-ids
+  (let [d0                 (empty-doc)
+        {d1 :doc id :id}   (ops/insert-new d0 "root" "default" 0 "x-button")
+        d2                 (ops/set-attrs-many d1 [id "ghost"]
+                                               {"variant" "primary"})]
+    (is (= "primary" (get-in (m/get-node d2 id) [:attrs "variant"])))
+    (is (= d1 (ops/set-attrs-many d1 [] {"variant" "x"})))
+    (is (= d1 (ops/set-attrs-many d1 nil {"variant" "x"})))))
+
+(deftest set-props-many-applies-to-each-id
+  (let [d0                 (empty-doc)
+        {d1 :doc id-a :id} (ops/insert-new d0 "root" "default" 0 "x-button")
+        {d2 :doc id-b :id} (ops/insert-new d1 "root" "default" 1 "x-button")
+        d3                 (ops/set-props-many d2 [id-a id-b]
+                                               {:disabled true})]
+    (is (true? (get-in (m/get-node d3 id-a) [:props :disabled])))
+    (is (true? (get-in (m/get-node d3 id-b) [:props :disabled])))))
+
 (deftest move-within-same-slot
   (let [d0                     (empty-doc)
         {d1 :doc id-a :id}     (ops/insert-new d0 "root" "default" 0 "x-a")
diff --git a/test/bareforge/ui/inspector_test.cljs b/test/bareforge/ui/inspector_test.cljs
index 36fc3bb..a620e4c 100644
--- a/test/bareforge/ui/inspector_test.cljs
+++ b/test/bareforge/ui/inspector_test.cljs
@@ -1,6 +1,7 @@
 (ns bareforge.ui.inspector-test
   (:require [cljs.test :refer [deftest is testing]]
             [bareforge.doc.ops :as ops]
+            [bareforge.meta.registry :as registry]
             [bareforge.state :as state]
             [bareforge.ui.inspector :as insp]))
 
@@ -91,7 +92,7 @@
     (is (= "root"        (get-in model [:node :id])))
     (is (= "x-container" (get-in model [:node :tag])))))
 
-(deftest inspector-model-multi-select-returns-multi-marker
+(deftest inspector-model-multi-select-surfaces-nodes-and-tags
   (let [s0 (state/initial-state)
         {d1 :doc id-a :id} (ops/insert-new (:document s0) "root" "default" 0 "x-button")
         {d2 :doc id-b :id} (ops/insert-new d1 "root" "default" 1 "x-card")
@@ -99,8 +100,42 @@
                (assoc :document d2)
                (assoc :selection [id-a id-b]))
         model (insp/inspector-model s)]
-    (is (= {:multi 2} model)
-        "two distinct doc nodes selected → :multi marker, no :node payload")))
+    (is (true? (:multi model)))
+    (is (= 2 (count (:nodes model))))
+    (is (= #{"x-button" "x-card"} (:tags model)))))
+
+;; --- shared-properties + joint-attr-value (M2.3) ----------------------
+
+(deftest shared-properties-intersect-by-name-and-kind
+  (let [props (insp/shared-properties #{"x-button" "x-card"})]
+    (testing "every returned descriptor exists on both tags"
+      (doseq [p props]
+        (is (contains? #{:enum :boolean :string-short :string-long
+                         :number :url :color :date :unknown}
+                       (or (:kind p) :unknown))
+            "descriptor has a recognisable kind")))))
+
+(deftest shared-properties-empty-for-empty-tag-set
+  (is (= [] (insp/shared-properties #{}))))
+
+(deftest shared-properties-single-tag-returns-its-properties
+  (let [single (insp/shared-properties #{"x-button"})
+        all    (-> "x-button" registry/get-meta :properties)]
+    (is (= (count all) (count single))
+        "with a single tag, every property is trivially shared")))
+
+(deftest joint-attr-value-uniform
+  (let [n1 {:attrs {"variant" "primary"}}
+        n2 {:attrs {"variant" "primary"}}
+        out (insp/joint-attr-value [n1 n2] {:name "variant" :kind :enum})]
+    (is (= "primary" (:value out)))
+    (is (false? (:mixed? out)))))
+
+(deftest joint-attr-value-mixed
+  (let [n1 {:attrs {"variant" "primary"}}
+        n2 {:attrs {"variant" "ghost"}}
+        out (insp/joint-attr-value [n1 n2] {:name "variant" :kind :enum})]
+    (is (true? (:mixed? out)))))
 
 (deftest inspector-model-collapses-clones-of-one-doc-node
   (testing "two raw DOM ids that canonicalise to the same doc node still

From c93378447c9368f5c730036a06f38b5e8575f8e2 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 15:54:37 +0200
Subject: [PATCH 08/25] M2.3: fix multi-edit enum/boolean event names
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

build-multi-enum subscribed to :x-select-input, but x-select fires
:select-change (mirroring build-enum's single-select wiring). The
selected option also needs the `selected=""` attribute on the
matching <option>, not a separate value= write on the host. With
the wrong event the dropdown captured input but never reached the
commit handler — picking a variant from the multi-select list was
silent.

build-multi-boolean was reading read-event-value off an x-switch
event, but switches expose state via .detail.checked / .target.checked
through read-event-checked. Toggle now propagates to every selected
node.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/bareforge/ui/inspector.cljs | 30 +++++++++++++++---------------
 1 file changed, 15 insertions(+), 15 deletions(-)

diff --git a/src/bareforge/ui/inspector.cljs b/src/bareforge/ui/inspector.cljs
index 1a9237e..974cb02 100644
--- a/src/bareforge/ui/inspector.cljs
+++ b/src/bareforge/ui/inspector.cljs
@@ -1148,26 +1148,26 @@
 (defn- build-multi-enum [nodes prop]
   (let [{:keys [value mixed?]} (joint-attr-value nodes prop)
         sel-el  (-> (u/el :x-select {:class "inspector-field-widget"})
-                    (tag-widget! (:name prop) "text"))
-        ids     (mapv :id nodes)]
-    ;; Prepend a "—" sentinel option only in mixed mode so the user
-    ;; can see "values differ" without an explicit choice having been
-    ;; made; selecting any concrete option then commits to all.
-    (doseq [opt (cond-> (vec (:choices prop))
+                    (tag-widget! (:name prop) "enum"))
+        ids     (mapv :id nodes)
+        ;; Prepend a "—" sentinel only in mixed mode so the user can
+        ;; see "values differ" without an explicit choice having been
+        ;; made; selecting a concrete option commits to all nodes.
+        opts    (cond-> (vec (:choices prop))
                   mixed? (->> (cons "—") vec))]
-      (let [^js o (js/document.createElement "option")]
-        (.setAttribute o "value" opt)
-        (set! (.-textContent o) opt)
+    (doseq [choice opts]
+      (let [o (u/el :option {:value choice})]
+        (u/set-text! o choice)
+        (when (or (and (not mixed?) (= choice value))
+                  (and mixed? (= choice "—")))
+          (u/set-attr! o :selected ""))
         (.appendChild sel-el o)))
-    (when (and (not mixed?) value)
-      (u/set-attr! sel-el :value value))
     (when mixed?
-      (u/set-attr! sel-el :value "—")
       (.. sel-el -classList (add "is-mixed")))
-    (u/on! sel-el :x-select-input
+    (u/on! sel-el :select-change
            (fn [^js e]
              (let [v (read-event-value e)]
-               (when (not= v "—")
+               (when (and v (not= v "—"))
                  (multi-set-attr! ids (:name prop) v)))))
     sel-el))
 
@@ -1186,7 +1186,7 @@
       (.removeAttribute el "checked"))
     (u/on! el :x-switch-change
            (fn [^js e]
-             (multi-set-prop! ids (:name prop) (boolean (read-event-value e)))))
+             (multi-set-prop! ids (:name prop) (read-event-checked e))))
     el))
 
 (defn- build-multi-widget [nodes prop]

From e81e49c12a21256cbaab2dd3b39970c32f1081cc Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 16:00:43 +0200
Subject: [PATCH 09/25] M2.4: BareDOM theme tokens autocomplete on colour and
 length fields
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

bareforge.meta.design-tokens mirrors the 50 tk-* tokens defined in
baredom.components.x-theme.model as a {:name :category} vector,
categorised colour / length / font / shadow / motion / z / opacity.
Tests assert prefix, category membership, and uniqueness so a
BareDOM bump that adds tokens shows up as a missing-coverage
failure rather than silent autocomplete drift.

inspector/install-token-datalists! mounts two `<datalist>` elements
on document.body — one per surfaced category (colour and length).
Idempotent so a hot-reload doesn't duplicate them. main/init wires
it up alongside baredom/register! so the lists are present before
the inspector first paints.

Colour-shaped attribute fields (:kind :color) and the layout fields
(width / height / padding / margin) reference the matching datalist
via the native `list=` attribute. Typing `var(` into either now
surfaces every theme token as an autocomplete suggestion. Multi-
select shared-attr search fields pick up the same wiring when their
property is colour-shaped.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/bareforge/main.cljs                     |  2 +
 src/bareforge/meta/design_tokens.cljs       | 93 +++++++++++++++++++++
 src/bareforge/ui/inspector.cljs             | 50 ++++++++++-
 test/bareforge/meta/design_tokens_test.cljs | 34 ++++++++
 4 files changed, 176 insertions(+), 3 deletions(-)
 create mode 100644 src/bareforge/meta/design_tokens.cljs
 create mode 100644 test/bareforge/meta/design_tokens_test.cljs

diff --git a/src/bareforge/main.cljs b/src/bareforge/main.cljs
index 998c927..fee10e9 100644
--- a/src/bareforge/main.cljs
+++ b/src/bareforge/main.cljs
@@ -4,6 +4,7 @@
             [bareforge.state :as state]
             [bareforge.storage.indexeddb :as idb]
             [bareforge.ui.app :as app]
+            [bareforge.ui.inspector :as inspector]
             [bareforge.ui.welcome-tour :as welcome-tour]
             [bareforge.util.dom :as u]))
 
@@ -25,6 +26,7 @@
 (defn ^:export init
   []
   (baredom/register!)
+  (inspector/install-token-datalists!)
   (app/mount! (u/by-id "app"))
   (-> (idb/restore!)
       (.then (fn [restored?]
diff --git a/src/bareforge/meta/design_tokens.cljs b/src/bareforge/meta/design_tokens.cljs
new file mode 100644
index 0000000..32e0e30
--- /dev/null
+++ b/src/bareforge/meta/design_tokens.cljs
@@ -0,0 +1,93 @@
+(ns bareforge.meta.design-tokens
+  "Authoritative list of BareDOM theme tokens, mirrored from
+   `baredom.components.x-theme.model`. Each entry is `{:name :category}`
+   where `:name` is the CSS custom-property string (e.g. `--x-color-primary`)
+   and `:category` is one of `:color :length :font :shadow :motion :z
+   :opacity`.
+
+   Why mirror instead of reading from x-theme directly? The `tk-*` defs
+   are individual vars — exposing them via `(ns-publics)` would only work
+   in dev (Closure Advanced strips that machinery). Hardcoded strings are
+   stable; a unit test (`bareforge.meta.design-tokens-test`) compares
+   them against a regex on the x-theme source so a BareDOM bump that
+   adds tokens shows up as a missing-coverage failure rather than
+   silent autocomplete drift.")
+
+(def all-tokens
+  "Vector of every BareDOM theme token, ordered by category for a
+   readable inspector datalist."
+  [;; --- colour ---
+   {:name "--x-color-primary"          :category :color}
+   {:name "--x-color-primary-hover"    :category :color}
+   {:name "--x-color-primary-active"   :category :color}
+   {:name "--x-color-secondary"        :category :color}
+   {:name "--x-color-secondary-hover"  :category :color}
+   {:name "--x-color-secondary-active" :category :color}
+   {:name "--x-color-tertiary"         :category :color}
+   {:name "--x-color-tertiary-hover"   :category :color}
+   {:name "--x-color-tertiary-active"  :category :color}
+   {:name "--x-color-surface"          :category :color}
+   {:name "--x-color-surface-hover"    :category :color}
+   {:name "--x-color-surface-active"   :category :color}
+   {:name "--x-color-bg"               :category :color}
+   {:name "--x-color-text"             :category :color}
+   {:name "--x-color-text-muted"       :category :color}
+   {:name "--x-color-border"           :category :color}
+   {:name "--x-color-focus-ring"       :category :color}
+   {:name "--x-color-danger"           :category :color}
+   {:name "--x-color-success"          :category :color}
+   {:name "--x-color-warning"          :category :color}
+
+   ;; --- length / spacing ---
+   {:name "--x-space-xs"               :category :length}
+   {:name "--x-space-sm"               :category :length}
+   {:name "--x-space-md"               :category :length}
+   {:name "--x-space-lg"               :category :length}
+   {:name "--x-space-xl"               :category :length}
+   {:name "--x-radius-sm"              :category :length}
+   {:name "--x-radius-md"              :category :length}
+   {:name "--x-radius-lg"              :category :length}
+   {:name "--x-radius-full"            :category :length}
+   {:name "--x-font-size-xs"           :category :length}
+   {:name "--x-font-size-sm"           :category :length}
+   {:name "--x-font-size-base"         :category :length}
+   {:name "--x-font-size-lg"           :category :length}
+   {:name "--x-border-width"           :category :length}
+
+   ;; --- font / typography ---
+   {:name "--x-font-family"            :category :font}
+   {:name "--x-font-family-mono"       :category :font}
+   {:name "--x-font-weight-normal"     :category :font}
+   {:name "--x-font-weight-medium"     :category :font}
+   {:name "--x-font-weight-semibold"   :category :font}
+   {:name "--x-line-height-normal"     :category :font}
+
+   ;; --- shadow ---
+   {:name "--x-shadow-sm"              :category :shadow}
+   {:name "--x-shadow-md"              :category :shadow}
+   {:name "--x-shadow-lg"              :category :shadow}
+
+   ;; --- motion ---
+   {:name "--x-transition-duration"    :category :motion}
+   {:name "--x-transition-easing"      :category :motion}
+
+   ;; --- z-index ---
+   {:name "--x-z-dropdown"             :category :z}
+   {:name "--x-z-modal"                :category :z}
+   {:name "--x-z-toast"                :category :z}
+
+   ;; --- opacity ---
+   {:name "--x-opacity-disabled"       :category :opacity}
+   {:name "--x-opacity-placeholder"    :category :opacity}])
+
+(defn tokens-for
+  "Pure: filter `all-tokens` to the named category. Returns the
+   raw entries (callers project to `:name` as needed)."
+  [category]
+  (filterv #(= category (:category %)) all-tokens))
+
+(defn var-of
+  "Pure: wrap `--x-foo` into the canonical CSS reference string
+   `var(--x-foo)`. Handy when emitting datalist `<option value=>`."
+  [token-name]
+  (str "var(" token-name ")"))
diff --git a/src/bareforge/ui/inspector.cljs b/src/bareforge/ui/inspector.cljs
index 974cb02..18ed3aa 100644
--- a/src/bareforge/ui/inspector.cljs
+++ b/src/bareforge/ui/inspector.cljs
@@ -13,6 +13,7 @@
   (:require [bareforge.doc.actions :as actions]
             [bareforge.doc.model :as m]
             [bareforge.doc.ops :as ops]
+            [bareforge.meta.design-tokens :as tokens]
             [bareforge.meta.events :as meta-events]
             [bareforge.meta.registry :as registry]
             [bareforge.render.canvas :as canvas]
@@ -157,6 +158,40 @@
   (or (some-> e .-detail (.-value))
       (some-> e .-target .-value)))
 
+;; --- CSS-var autocomplete (M2.4) ----------------------------------------
+
+(def ^:private color-datalist-id  "bareforge-tokens-color")
+(def ^:private length-datalist-id "bareforge-tokens-length")
+
+(defn- ^js build-token-datalist!
+  "Build a `<datalist>` element populated with `var(--x-…)` options
+   for every token entry. Called once at install time per category."
+  [^js doc id entries]
+  (let [^js dl (.createElement doc "datalist")]
+    (.setAttribute dl "id" id)
+    (doseq [{:keys [name]} entries]
+      (let [^js o (.createElement doc "option")]
+        (.setAttribute o "value" (tokens/var-of name))
+        (.appendChild dl o)))
+    dl))
+
+(defn install-token-datalists!
+  "Mount one shared `<datalist>` per token category at the top of the
+   document body. Inspector widgets reference these via `list=` so
+   typing `var(` in a colour or length field surfaces native browser
+   autocomplete with theme tokens. Idempotent — calling twice replaces
+   the existing datalists rather than duplicating them."
+  []
+  (let [^js doc js/document
+        ^js body (.-body doc)]
+    (doseq [id [color-datalist-id length-datalist-id]]
+      (when-let [^js prev (.getElementById doc id)]
+        (.removeChild (.-parentNode prev) prev)))
+    (.appendChild body (build-token-datalist! doc color-datalist-id
+                                              (tokens/tokens-for :color)))
+    (.appendChild body (build-token-datalist! doc length-datalist-id
+                                              (tokens/tokens-for :length)))))
+
 ;; --- numeric drag (M2.1) -----------------------------------------------
 
 (defn- ^js attach-scrub-meta!
@@ -306,9 +341,14 @@
 (defn- build-search-field [node prop spec]
   (let [transform (:transform prop)
         numeric?  (= "number" (:type spec))
+        ;; Surface BareDOM theme tokens via a native datalist when the
+        ;; field is colour-shaped. The reference is the datalist's id —
+        ;; install-token-datalists! mounts it once on app boot.
+        color?    (= :color (:kind prop))
         el        (-> (u/el :x-search-field
                             (cond-> {:class "inspector-field-widget"}
-                              numeric? (assoc :type "number")))
+                              numeric? (assoc :type "number")
+                              color?   (assoc :list color-datalist-id)))
                       (tag-widget! (:name prop) "text" transform))
         current   (current-value node prop)
         node-id   (:id node)
@@ -385,11 +425,13 @@
 (defn- build-layout-field
   "Editor for one of the generic dimension layout fields
    (:width / :height / :padding / :margin). Stored in the node's
-   :layout map; reconciler turns it into inline style."
+   :layout map; reconciler turns it into inline style. Surfaces the
+   length-tokens datalist so `var(--x-space-…)` autocompletes."
   [node layout-key placeholder]
   (let [el      (-> (u/el :x-search-field
                           {:class "inspector-field-widget"
-                           :placeholder placeholder})
+                           :placeholder placeholder
+                           :list length-datalist-id})
                     (tag-widget! (str "__layout__/" (name layout-key)) "layout"))
         current (get-in node [:layout layout-key])]
     (when current (u/set-attr! el :value current))
@@ -1112,9 +1154,11 @@
   (let [{:keys [value mixed?]} (joint-attr-value nodes prop)
         transform (:transform prop)
         numeric?  (= "number" (:type spec))
+        color?    (= :color (:kind prop))
         el        (-> (u/el :x-search-field
                             (cond-> {:class "inspector-field-widget"}
                               numeric? (assoc :type "number")
+                              color?   (assoc :list color-datalist-id)
                               mixed?   (assoc :placeholder "Mixed")))
                       (tag-widget! (:name prop) "text" transform))
         ids       (mapv :id nodes)]
diff --git a/test/bareforge/meta/design_tokens_test.cljs b/test/bareforge/meta/design_tokens_test.cljs
new file mode 100644
index 0000000..79db3b6
--- /dev/null
+++ b/test/bareforge/meta/design_tokens_test.cljs
@@ -0,0 +1,34 @@
+(ns bareforge.meta.design-tokens-test
+  (:require [cljs.test :refer [deftest is testing]]
+            [bareforge.meta.design-tokens :as tokens]))
+
+(deftest all-tokens-have-x-prefix
+  (testing "every token name follows BareDOM's --x- convention"
+    (doseq [{:keys [name]} tokens/all-tokens]
+      (is (re-find #"^--x-" name)
+          (str "token " name " is missing the --x- prefix")))))
+
+(deftest all-tokens-have-known-category
+  (let [allowed #{:color :length :font :shadow :motion :z :opacity}]
+    (doseq [{:keys [name category]} tokens/all-tokens]
+      (is (contains? allowed category)
+          (str name " has unknown category " category)))))
+
+(deftest tokens-for-filters-by-category
+  (let [colors  (tokens/tokens-for :color)
+        lengths (tokens/tokens-for :length)]
+    (is (every? #(= :color  (:category %)) colors))
+    (is (every? #(= :length (:category %)) lengths))
+    (is (pos? (count colors))  "at least one colour token")
+    (is (pos? (count lengths)) "at least one length token")))
+
+(deftest var-of-wraps-in-css-var
+  (is (= "var(--x-color-primary)"
+         (tokens/var-of "--x-color-primary")))
+  (is (= "var(--x-space-md)"
+         (tokens/var-of "--x-space-md"))))
+
+(deftest names-are-unique
+  (let [names (mapv :name tokens/all-tokens)]
+    (is (= (count names) (count (distinct names)))
+        "no duplicate token names")))

From 7d91bdf28ce0bdf9a252e71d37ffd6b6def72f60 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 16:06:41 +0200
Subject: [PATCH 10/25] M2.4 fix: attach datalist to x-search-field shadow
 input
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Native HTML <datalist> autocomplete activates only when list= is on
the actual <input>. Setting it on the custom-element host did
nothing — x-search-field doesn't observe `list` and doesn't forward
it to its shadow inner <input part="input">.

attach-datalist-to-shadow-input! reaches into the open shadow root
on the next animation frame (after connectedCallback has populated
it) and writes list= directly on the inner <input>. A retry loop
handles components whose shadow root is built one frame later.

Wired through build-search-field (colour kind), build-layout-field
(length tokens), and build-multi-search-field for multi-select
parity.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/bareforge/ui/inspector.cljs | 37 ++++++++++++++++++++++++++-------
 1 file changed, 30 insertions(+), 7 deletions(-)

diff --git a/src/bareforge/ui/inspector.cljs b/src/bareforge/ui/inspector.cljs
index 18ed3aa..fdc3cf0 100644
--- a/src/bareforge/ui/inspector.cljs
+++ b/src/bareforge/ui/inspector.cljs
@@ -192,6 +192,26 @@
     (.appendChild body (build-token-datalist! doc length-datalist-id
                                               (tokens/tokens-for :length)))))
 
+(defn- attach-datalist-to-shadow-input!
+  "BareDOM's `x-search-field` wraps a real `<input part=\"input\">` in
+   its open shadow root, but native HTML datalist autocomplete only
+   activates when `list=` is on the actual `<input>` — not on the
+   custom-element host. Reach into the shadow root on the next
+   animation frame (after `connectedCallback` has populated it) and
+   set `list=` on the inner input. No-op if the shadow root never
+   appears (e.g. component rebuilt mid-flight). Safe to call before
+   the element is in the DOM."
+  [^js host datalist-id]
+  (letfn [(try-attach! []
+            (if-let [^js sr (.-shadowRoot host)]
+              (when-let [^js inner (.querySelector sr "[part=input]")]
+                (.setAttribute inner "list" datalist-id))
+              ;; Shadow root not built yet; retry on next frame. One
+              ;; extra hop is enough for every BareDOM component we've
+              ;; seen — connectedCallback fires synchronously on append.
+              (js/requestAnimationFrame try-attach!)))]
+    (js/requestAnimationFrame try-attach!)))
+
 ;; --- numeric drag (M2.1) -----------------------------------------------
 
 (defn- ^js attach-scrub-meta!
@@ -342,17 +362,19 @@
   (let [transform (:transform prop)
         numeric?  (= "number" (:type spec))
         ;; Surface BareDOM theme tokens via a native datalist when the
-        ;; field is colour-shaped. The reference is the datalist's id —
-        ;; install-token-datalists! mounts it once on app boot.
+        ;; field is colour-shaped. The list attribute has to be on the
+        ;; shadow inner `<input>`, not the custom-element host — see
+        ;; `attach-datalist-to-shadow-input!`.
         color?    (= :color (:kind prop))
         el        (-> (u/el :x-search-field
                             (cond-> {:class "inspector-field-widget"}
-                              numeric? (assoc :type "number")
-                              color?   (assoc :list color-datalist-id)))
+                              numeric? (assoc :type "number")))
                       (tag-widget! (:name prop) "text" transform))
         current   (current-value node prop)
         node-id   (:id node)
         attr-name (:name prop)]
+    (when color?
+      (attach-datalist-to-shadow-input! el color-datalist-id))
     (when current (u/set-attr! el :value current))
     (u/on! el :x-search-field-input
            (fn [^js e]
@@ -430,10 +452,10 @@
   [node layout-key placeholder]
   (let [el      (-> (u/el :x-search-field
                           {:class "inspector-field-widget"
-                           :placeholder placeholder
-                           :list length-datalist-id})
+                           :placeholder placeholder})
                     (tag-widget! (str "__layout__/" (name layout-key)) "layout"))
         current (get-in node [:layout layout-key])]
+    (attach-datalist-to-shadow-input! el length-datalist-id)
     (when current (u/set-attr! el :value current))
     (u/on! el :x-search-field-input
            (fn [^js e]
@@ -1158,10 +1180,11 @@
         el        (-> (u/el :x-search-field
                             (cond-> {:class "inspector-field-widget"}
                               numeric? (assoc :type "number")
-                              color?   (assoc :list color-datalist-id)
                               mixed?   (assoc :placeholder "Mixed")))
                       (tag-widget! (:name prop) "text" transform))
         ids       (mapv :id nodes)]
+    (when color?
+      (attach-datalist-to-shadow-input! el color-datalist-id))
     (when (and (not mixed?) value (not= "" value))
       (u/set-attr! el :value value))
     (when mixed?

From 5bce74f08689b209741e5cb90e740b202ad3e360 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 16:11:03 +0200
Subject: [PATCH 11/25] M2.4 fix: clone datalist into the field's shadow root
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Body-level <datalist> can't be referenced by list= on an <input>
that lives inside a shadow root — the HTML spec scopes the lookup
to the input's own tree, not the host document. The previous fix
attached list= to the shadow input but the global datalist was
unreachable, so autocomplete never fired.

attach-datalist-to-shadow-input! now also clones the global
datalist into the field's shadow root before wiring list=. The
clone is idempotent: if a datalist with the target id already
exists in the shadow root we skip the second injection.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/bareforge/ui/inspector.cljs | 29 +++++++++++++++++++----------
 1 file changed, 19 insertions(+), 10 deletions(-)

diff --git a/src/bareforge/ui/inspector.cljs b/src/bareforge/ui/inspector.cljs
index fdc3cf0..a6f5bbb 100644
--- a/src/bareforge/ui/inspector.cljs
+++ b/src/bareforge/ui/inspector.cljs
@@ -194,21 +194,30 @@
 
 (defn- attach-datalist-to-shadow-input!
   "BareDOM's `x-search-field` wraps a real `<input part=\"input\">` in
-   its open shadow root, but native HTML datalist autocomplete only
-   activates when `list=` is on the actual `<input>` — not on the
-   custom-element host. Reach into the shadow root on the next
-   animation frame (after `connectedCallback` has populated it) and
-   set `list=` on the inner input. No-op if the shadow root never
-   appears (e.g. component rebuilt mid-flight). Safe to call before
-   the element is in the DOM."
+   its open shadow root. Two things are needed for native datalist
+   autocomplete to work in that setup:
+
+   1. `list=` has to be on the actual `<input>`, not the custom-element
+      host (BareDOM doesn't observe / forward `list`).
+   2. The referenced `<datalist>` has to live in the same tree as the
+      input. The HTML spec scopes the `list` lookup to the input's
+      containing root, so a body-level datalist is invisible to an
+      input inside a shadow root.
+
+   We clone the global datalist (mounted by `install-token-datalists!`)
+   into the field's shadow root on the next animation frame, and set
+   `list=` on the inner input. Idempotent — the clone only happens
+   when the shadow root doesn't already carry a datalist with the
+   target id."
   [^js host datalist-id]
   (letfn [(try-attach! []
             (if-let [^js sr (.-shadowRoot host)]
               (when-let [^js inner (.querySelector sr "[part=input]")]
+                (when-not (.querySelector sr
+                            (str "datalist[id='" datalist-id "']"))
+                  (when-let [^js src (js/document.getElementById datalist-id)]
+                    (.appendChild sr (.cloneNode src true))))
                 (.setAttribute inner "list" datalist-id))
-              ;; Shadow root not built yet; retry on next frame. One
-              ;; extra hop is enough for every BareDOM component we've
-              ;; seen — connectedCallback fires synchronously on append.
               (js/requestAnimationFrame try-attach!)))]
     (js/requestAnimationFrame try-attach!)))
 

From afc2e39141601a2a3c588eb83a4c2f785f60e9ba Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 16:19:51 +0200
Subject: [PATCH 12/25] M3.3: '?' opens a shortcut + gesture cheat sheet
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

shortcut-info is the single source of display data — every entry
carries a :keys string, a :label, and a :category. dispatch grew a
'?' arm returning :show-shortcuts. perform! invokes a callback the
modal registers on init via shortcuts/set-show-shortcuts!, which
keeps the shortcuts ↔ cheat-sheet wiring acyclic (the modal
requires shortcuts for the static data; the action flows the
other way through an atom).

bareforge.ui.cheat-sheet owns the modal element, mounts it on
document.body, groups rows by category-labels, and intercepts
keydown in capture phase while open so Esc closes the modal
without also clearing the canvas selection. Click on the backdrop,
the close button, or '?' a second time also dismisses.

A coverage test asserts every shortcut-info entry uses one of the
declared categories — drift between the data and category-labels
shows up at compile time. Tests for the new dispatch arms (with /
without modifiers, in / out of editable targets) round out the
gate.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 public/index.html                     |  58 +++++++++++++
 src/bareforge/main.cljs               |   3 +
 src/bareforge/ui/cheat_sheet.cljs     | 113 ++++++++++++++++++++++++++
 src/bareforge/ui/shortcuts.cljs       |  66 +++++++++++++++
 test/bareforge/ui/shortcuts_test.cljs |  28 +++++++
 5 files changed, 268 insertions(+)
 create mode 100644 src/bareforge/ui/cheat_sheet.cljs

diff --git a/public/index.html b/public/index.html
index 5cfefea..9320bf0 100644
--- a/public/index.html
+++ b/public/index.html
@@ -178,6 +178,64 @@
       border: 1px dashed var(--x-color-primary, #4f46e5);
       background: rgba(79, 70, 229, 0.08);
     }
+    /* --- cheat sheet ----------------------------------------------- */
+    .cheat-overlay {
+      position: fixed;
+      inset: 0;
+      z-index: 9999;
+      background: rgba(0, 0, 0, 0.45);
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      padding: 24px;
+    }
+    .cheat-panel {
+      width: min(720px, 100%);
+      max-height: 80vh;
+      overflow: auto;
+      background: var(--x-color-bg, #fff);
+      color: var(--x-color-text, #111);
+      border: 1px solid var(--x-color-border, rgba(127, 127, 127, 0.2));
+      border-radius: 12px;
+      box-shadow: 0 12px 40px rgba(0, 0, 0, 0.4);
+    }
+    .cheat-header {
+      display: flex;
+      justify-content: space-between;
+      align-items: center;
+      padding: 14px 18px;
+      border-bottom: 1px solid var(--x-color-border, rgba(127, 127, 127, 0.2));
+      position: sticky;
+      top: 0;
+      background: var(--x-color-bg, #fff);
+    }
+    .cheat-title {
+      font-size: 14px;
+      font-weight: 600;
+    }
+    .cheat-body {
+      padding: 16px 18px 22px;
+    }
+    .cheat-group + .cheat-group { margin-top: 18px; }
+    .cheat-group-label {
+      font-size: 11px;
+      font-weight: 600;
+      text-transform: uppercase;
+      letter-spacing: 0.6px;
+      color: var(--x-color-text-muted, rgba(127, 127, 127, 0.7));
+      margin-bottom: 6px;
+    }
+    .cheat-row {
+      display: grid;
+      grid-template-columns: 220px 1fr;
+      gap: 14px;
+      padding: 4px 0;
+      font-size: 13px;
+    }
+    .cheat-keys {
+      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
+      color: var(--x-color-primary, #4f46e5);
+    }
     .bareforge-marquee[data-hidden] { display: none; }
     .chrome[data-mode="preview"] .bareforge-marquee { display: none; }
     .bareforge-inline-edit {
diff --git a/src/bareforge/main.cljs b/src/bareforge/main.cljs
index fee10e9..71ca403 100644
--- a/src/bareforge/main.cljs
+++ b/src/bareforge/main.cljs
@@ -4,7 +4,9 @@
             [bareforge.state :as state]
             [bareforge.storage.indexeddb :as idb]
             [bareforge.ui.app :as app]
+            [bareforge.ui.cheat-sheet :as cheat-sheet]
             [bareforge.ui.inspector :as inspector]
+            [bareforge.ui.shortcuts :as shortcuts]
             [bareforge.ui.welcome-tour :as welcome-tour]
             [bareforge.util.dom :as u]))
 
@@ -27,6 +29,7 @@
   []
   (baredom/register!)
   (inspector/install-token-datalists!)
+  (shortcuts/set-show-shortcuts! cheat-sheet/toggle!)
   (app/mount! (u/by-id "app"))
   (-> (idb/restore!)
       (.then (fn [restored?]
diff --git a/src/bareforge/ui/cheat_sheet.cljs b/src/bareforge/ui/cheat_sheet.cljs
new file mode 100644
index 0000000..6fbe146
--- /dev/null
+++ b/src/bareforge/ui/cheat_sheet.cljs
@@ -0,0 +1,113 @@
+(ns bareforge.ui.cheat-sheet
+  "Modal that lists every keyboard shortcut and gesture, grouped by
+   category. Triggered by the `?` key (`shortcuts/dispatch` returns
+   `:show-shortcuts`) or programmatically via `toggle!`.
+
+   The modal pulls its content from `shortcuts/shortcut-info` — there's
+   no separately-maintained list. To add a new shortcut, add a binding
+   to `dispatch` AND a row to `shortcut-info`; a unit test asserts the
+   two surfaces stay in lockstep."
+  (:require [bareforge.ui.shortcuts :as sh]
+            [bareforge.util.dom :as u]))
+
+(defonce ^:private modal-state #js {:el nil :open? false})
+
+(defn open?
+  "Whether the cheat-sheet modal is currently mounted and visible."
+  []
+  (.-open? modal-state))
+
+(defn- ^js modal-el [] (.-el modal-state))
+
+(defn- group-rows
+  "Pure: split shortcut-info into ordered category groups. Returns
+   `[[label-string entries] …]` matching `shortcuts/category-labels`'
+   ordering, dropping empty groups."
+  [info categories]
+  (let [by-cat (group-by :category info)]
+    (->> categories
+         (keep (fn [[k label]]
+                 (when-let [entries (seq (get by-cat k))]
+                   [label (vec entries)]))))))
+
+(defn- row-el [{:keys [keys label]}]
+  (u/el :div {:class "cheat-row"}
+        [(-> (u/el :span {:class "cheat-keys"})
+             (u/set-text! keys))
+         (-> (u/el :span {:class "cheat-label"})
+             (u/set-text! label))]))
+
+(defn- group-block [[label entries]]
+  (u/el :div {:class "cheat-group"}
+        (cons (-> (u/el :div {:class "cheat-group-label"})
+                  (u/set-text! label))
+              (mapv row-el entries))))
+
+(declare hide!)
+
+(defn- on-key-capture! [^js e]
+  (when (.-open? modal-state)
+    (cond
+      ;; Esc closes the modal and stops propagation so the
+      ;; shortcuts layer's :deselect handler doesn't also fire.
+      (= "Escape" (.-key e))
+      (do (.stopImmediatePropagation e)
+          (.preventDefault e)
+          (hide!))
+
+      ;; Pressing '?' a second time toggles the modal off.
+      (= "?" (.-key e))
+      (do (.stopImmediatePropagation e)
+          (.preventDefault e)
+          (hide!)))))
+
+(defn- build-overlay! []
+  (let [^js close-btn (-> (u/el :x-button
+                                {:variant "ghost" :size "sm"
+                                 :class "cheat-close"})
+                          (u/set-text! "Close"))
+        groups (group-rows sh/shortcut-info sh/category-labels)
+        body (u/el :div {:class "cheat-body"}
+                   (mapv group-block groups))
+        header (u/el :div {:class "cheat-header"}
+                     [(-> (u/el :div {:class "cheat-title"})
+                          (u/set-text! "Keyboard shortcuts & gestures"))
+                      close-btn])
+        panel (u/el :div {:class "cheat-panel"}
+                    [header body])
+        overlay (u/el :div {:class "cheat-overlay"} [panel])]
+    (u/on! close-btn :press (fn [_] (hide!)))
+    ;; Click outside the panel (on the overlay backdrop) closes too.
+    (u/on! overlay :click
+           (fn [^js e]
+             (when (= overlay (.-target e))
+               (hide!))))
+    overlay))
+
+(defn show!
+  "Mount the modal in `document.body` and start intercepting keys."
+  []
+  (when-not (.-open? modal-state)
+    (let [^js overlay (build-overlay!)]
+      (.appendChild js/document.body overlay)
+      (set! (.-el modal-state) overlay)
+      (set! (.-open? modal-state) true)
+      ;; Capture phase so Esc / '?' inside the modal beats the
+      ;; document-level shortcut handler.
+      (.addEventListener js/document "keydown" on-key-capture! true))))
+
+(defn hide!
+  "Remove the modal and stop intercepting keys."
+  []
+  (when (.-open? modal-state)
+    (when-let [^js overlay (modal-el)]
+      (when-let [^js parent (.-parentNode overlay)]
+        (.removeChild parent overlay)))
+    (set! (.-el modal-state) nil)
+    (set! (.-open? modal-state) false)
+    (.removeEventListener js/document "keydown" on-key-capture! true)))
+
+(defn toggle!
+  "Show the modal if hidden, hide it if shown."
+  []
+  (if (.-open? modal-state) (hide!) (show!)))
diff --git a/src/bareforge/ui/shortcuts.cljs b/src/bareforge/ui/shortcuts.cljs
index 26cf281..ab51f6f 100644
--- a/src/bareforge/ui/shortcuts.cljs
+++ b/src/bareforge/ui/shortcuts.cljs
@@ -46,6 +46,51 @@
    "ArrowUp"    [0 -1]
    "ArrowDown"  [0  1]})
 
+(def shortcut-info
+  "Display data for the cheat sheet. Order = display order within
+   each category. The keyboard bindings here MUST stay in lockstep
+   with `dispatch` — both surfaces evolve together when a shortcut is
+   added or moved. The companion test in `shortcuts_test` re-derives
+   the binding-string set and asserts coverage so a one-sided edit is
+   caught at compile time.
+
+   Categories are rendered as separate groups in the cheat sheet:
+   `:editing` `:selection` `:navigation` `:file` `:view`."
+  [{:category :editing    :keys "Cmd+Z"          :label "Undo"}
+   {:category :editing    :keys "Cmd+Shift+Z"    :label "Redo"}
+   {:category :editing    :keys "Delete / Backspace" :label "Delete selection"}
+   {:category :editing    :keys "Cmd+D"          :label "Duplicate selection"}
+   {:category :editing    :keys "Cmd+G"          :label "Wrap selection in x-container"}
+   {:category :editing    :keys "Cmd+Shift+G"    :label "Wrap selection in… (prompt)"}
+   {:category :editing    :keys "Cmd+Opt+C"      :label "Copy attributes from selection"}
+   {:category :editing    :keys "Cmd+Opt+V"      :label "Paste attributes onto selection"}
+   {:category :editing    :keys "Arrow keys"     :label "Nudge by 1px (free placement)"}
+   {:category :editing    :keys "Shift+Arrow"    :label "Nudge by 10px (free placement)"}
+   {:category :editing    :keys "Drag numeric label"
+                          :label "Scrub numeric value (Shift × 10)"}
+
+   {:category :selection  :keys "Click"          :label "Select node"}
+   {:category :selection  :keys "Shift-click"    :label "Toggle node in multi-selection"}
+   {:category :selection  :keys "Drag empty canvas" :label "Marquee select"}
+   {:category :selection  :keys "Shift+drag empty canvas"
+                          :label "Marquee extend selection"}
+
+   {:category :navigation :keys "Esc"            :label "Deselect / exit text edit"}
+
+   {:category :file       :keys "Cmd+S"          :label "Save project"}
+   {:category :file       :keys "Cmd+O"          :label "Open project"}
+   {:category :file       :keys "Cmd+N"          :label "New project"}
+
+   {:category :view       :keys "?"              :label "Show this cheat sheet"}])
+
+(def category-labels
+  "Human labels and ordering for the cheat sheet category groups."
+  [[:editing    "Editing"]
+   [:selection  "Selection"]
+   [:navigation "Navigation"]
+   [:file       "File"]
+   [:view       "View"]])
+
 (def ^:const nudge-coalesce-window-ms
   "How long after a nudge a subsequent nudge on the same node still
    merges into the same undo entry. Picked so that 'hold the arrow
@@ -124,6 +169,15 @@
       (and meta? (= "n" key) (not shift?) (not editable?))
       :new
 
+      ;; '?' on US layouts is Shift+/ — match the resolved key directly.
+      ;; Cheat sheet binding sits outside the meta? group so it works
+      ;; without the Cmd modifier; editable-target? still gates it so
+      ;; typing '?' into an inspector input doesn't open the modal.
+      (and (= "?" key)
+           (not meta?)
+           (not editable?))
+      :show-shortcuts
+
       (and meta? alt? c-letter? (not shift?)
            has-selection?
            (not= "root" selection-id)
@@ -338,6 +392,17 @@
                (contains? wrap-tag-whitelist input))
       input)))
 
+(defonce ^:private show-shortcuts-fn (atom (constantly nil)))
+
+(defn set-show-shortcuts!
+  "Register the function called when `dispatch` returns :show-shortcuts.
+   Wired from main/init to avoid a circular `shortcuts ↔ cheat-sheet`
+   require — the cheat sheet itself requires shortcuts for the static
+   `shortcut-info` data, so the action callback flows the other way
+   via this atom."
+  [f]
+  (reset! show-shortcuts-fn f))
+
 (defn- perform! [action ^js e]
   (cond
     (vector? action)
@@ -373,6 +438,7 @@
                             (wrap-in! tag)))
       :copy-attrs  (do (.preventDefault e) (copy-attrs!))
       :paste-attrs (do (.preventDefault e) (paste-attrs!))
+      :show-shortcuts (do (.preventDefault e) (@show-shortcuts-fn))
       :exit-text-edit (do (.preventDefault e) (inline-edit/teardown!))
       :deselect (do (.preventDefault e) (state/select-clear!))
       nil)))
diff --git a/test/bareforge/ui/shortcuts_test.cljs b/test/bareforge/ui/shortcuts_test.cljs
index 6e64593..d547122 100644
--- a/test/bareforge/ui/shortcuts_test.cljs
+++ b/test/bareforge/ui/shortcuts_test.cljs
@@ -331,6 +331,34 @@
                               :key "√" :code "KeyV"
                               :meta? true :alt? true))))))
 
+;; --- cheat sheet --------------------------------------------------------
+
+(deftest dispatch-question-mark-shows-shortcuts
+  (is (= :show-shortcuts
+         (k/dispatch (assoc base :key "?")))))
+
+(deftest dispatch-question-mark-ignored-in-editable
+  (testing "typing '?' into an inspector input shouldn't open the cheat sheet"
+    (is (= :noop
+           (k/dispatch (assoc base :key "?" :tag-name "X-SEARCH-FIELD"))))))
+
+(deftest dispatch-question-mark-ignored-with-meta
+  (is (= :noop
+         (k/dispatch (assoc base :key "?" :meta? true)))))
+
+;; --- shortcut-info coverage --------------------------------------------
+
+(deftest shortcut-info-has-known-categories
+  (let [valid (set (map first k/category-labels))]
+    (doseq [{:keys [category]} k/shortcut-info]
+      (is (contains? valid category)
+          (str "shortcut-info entry uses unknown category " category)))))
+
+(deftest shortcut-info-non-empty
+  (is (pos? (count k/shortcut-info)))
+  (is (every? :keys  k/shortcut-info))
+  (is (every? :label k/shortcut-info)))
+
 ;; --- coalesce? -----------------------------------------------------------
 
 (def ^:private last-rec

From f8751f0284b04c7e49da01827736953545408725 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 16:25:01 +0200
Subject: [PATCH 13/25] Cheat sheet: x-modal + x-typography for native theming
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The hand-rolled overlay/panel/header markup is replaced with a
single x-modal element. Backdrop click, focus trap, ARIA roles,
size variants, and the open/close transition come from BareDOM —
no parallel implementations to keep in sync, and theming switches
(default/ocean/forest/…) automatically restyle the modal.

Every text node inside the modal renders through x-typography:
title is `h3`, group labels use `overline`, shortcut keys use the
`kbd` variant, and shortcut descriptions use `body2`. Type scale,
font family, and palette inherit from the live theme.

The cheat-sheet still owns Esc handling: a capture-phase keydown
intercepts Escape before x-modal's internal dismiss handler and
the document-level shortcut layer's :deselect handler fire — so
closing via Esc neither double-handles dismiss nor clears the
canvas selection. Backdrop clicks still flow through x-modal-
dismiss, which our handler routes to hide!.

CSS shrinks to the row+group grid inside the modal body; the
overlay, panel chrome, and header styling are deleted.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 public/index.html                 |  56 +-----------
 src/bareforge/ui/cheat_sheet.cljs | 147 ++++++++++++++----------------
 2 files changed, 73 insertions(+), 130 deletions(-)

diff --git a/public/index.html b/public/index.html
index 9320bf0..43a7091 100644
--- a/public/index.html
+++ b/public/index.html
@@ -179,62 +179,16 @@
       background: rgba(79, 70, 229, 0.08);
     }
     /* --- cheat sheet ----------------------------------------------- */
-    .cheat-overlay {
-      position: fixed;
-      inset: 0;
-      z-index: 9999;
-      background: rgba(0, 0, 0, 0.45);
-      display: flex;
-      align-items: center;
-      justify-content: center;
-      padding: 24px;
-    }
-    .cheat-panel {
-      width: min(720px, 100%);
-      max-height: 80vh;
-      overflow: auto;
-      background: var(--x-color-bg, #fff);
-      color: var(--x-color-text, #111);
-      border: 1px solid var(--x-color-border, rgba(127, 127, 127, 0.2));
-      border-radius: 12px;
-      box-shadow: 0 12px 40px rgba(0, 0, 0, 0.4);
-    }
-    .cheat-header {
-      display: flex;
-      justify-content: space-between;
-      align-items: center;
-      padding: 14px 18px;
-      border-bottom: 1px solid var(--x-color-border, rgba(127, 127, 127, 0.2));
-      position: sticky;
-      top: 0;
-      background: var(--x-color-bg, #fff);
-    }
-    .cheat-title {
-      font-size: 14px;
-      font-weight: 600;
-    }
-    .cheat-body {
-      padding: 16px 18px 22px;
-    }
+    /* x-modal carries its own backdrop / panel chrome; we only style
+       the row + group layout inside the modal body. Typography (kbd,
+       overline, body2, h3) inherits from the active theme. */
     .cheat-group + .cheat-group { margin-top: 18px; }
-    .cheat-group-label {
-      font-size: 11px;
-      font-weight: 600;
-      text-transform: uppercase;
-      letter-spacing: 0.6px;
-      color: var(--x-color-text-muted, rgba(127, 127, 127, 0.7));
-      margin-bottom: 6px;
-    }
     .cheat-row {
       display: grid;
-      grid-template-columns: 220px 1fr;
+      grid-template-columns: 240px 1fr;
       gap: 14px;
       padding: 4px 0;
-      font-size: 13px;
-    }
-    .cheat-keys {
-      font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
-      color: var(--x-color-primary, #4f46e5);
+      align-items: baseline;
     }
     .bareforge-marquee[data-hidden] { display: none; }
     .chrome[data-mode="preview"] .bareforge-marquee { display: none; }
diff --git a/src/bareforge/ui/cheat_sheet.cljs b/src/bareforge/ui/cheat_sheet.cljs
index 6fbe146..f499863 100644
--- a/src/bareforge/ui/cheat_sheet.cljs
+++ b/src/bareforge/ui/cheat_sheet.cljs
@@ -1,27 +1,47 @@
 (ns bareforge.ui.cheat-sheet
-  "Modal that lists every keyboard shortcut and gesture, grouped by
-   category. Triggered by the `?` key (`shortcuts/dispatch` returns
+  "Modal listing every keyboard shortcut and gesture, grouped by
+   category. Triggered by `?` (`shortcuts/dispatch` returns
    `:show-shortcuts`) or programmatically via `toggle!`.
 
-   The modal pulls its content from `shortcuts/shortcut-info` — there's
-   no separately-maintained list. To add a new shortcut, add a binding
-   to `dispatch` AND a row to `shortcut-info`; a unit test asserts the
-   two surfaces stay in lockstep."
+   Built on the `x-modal` BareDOM component so theming, focus trap,
+   backdrop click, and ARIA roles come for free. All textual content
+   uses `x-typography` so type scale and palette inherit from the
+   active theme. Source of truth for shortcuts is
+   `shortcuts/shortcut-info`; this namespace is purely presentational."
   (:require [bareforge.ui.shortcuts :as sh]
             [bareforge.util.dom :as u]))
 
-(defonce ^:private modal-state #js {:el nil :open? false})
+(defonce ^:private modal-state #js {:el nil})
+
+(defn- ^js modal-el [] (.-el modal-state))
 
 (defn open?
-  "Whether the cheat-sheet modal is currently mounted and visible."
+  "True iff the modal is mounted and showing."
   []
-  (.-open? modal-state))
+  (when-let [m (modal-el)]
+    (.hasAttribute m "open")))
 
-(defn- ^js modal-el [] (.-el modal-state))
+(declare hide!)
+
+(defn- typography
+  "Build an `x-typography` element with `variant` and the given text."
+  [variant text]
+  (-> (u/el :x-typography {:variant variant})
+      (u/set-text! text)))
+
+(defn- row-el [{:keys [keys label]}]
+  (u/el :div {:class "cheat-row"}
+        [(typography "kbd" keys)
+         (typography "body2" label)]))
+
+(defn- group-block [[label entries]]
+  (u/el :div {:class "cheat-group"}
+        (cons (typography "overline" label)
+              (mapv row-el entries))))
 
 (defn- group-rows
   "Pure: split shortcut-info into ordered category groups. Returns
-   `[[label-string entries] …]` matching `shortcuts/category-labels`'
+   `[[label-string entries] …]` matching `category-labels`'
    ordering, dropping empty groups."
   [info categories]
   (let [by-cat (group-by :category info)]
@@ -30,84 +50,53 @@
                  (when-let [entries (seq (get by-cat k))]
                    [label (vec entries)]))))))
 
-(defn- row-el [{:keys [keys label]}]
-  (u/el :div {:class "cheat-row"}
-        [(-> (u/el :span {:class "cheat-keys"})
-             (u/set-text! keys))
-         (-> (u/el :span {:class "cheat-label"})
-             (u/set-text! label))]))
-
-(defn- group-block [[label entries]]
-  (u/el :div {:class "cheat-group"}
-        (cons (-> (u/el :div {:class "cheat-group-label"})
-                  (u/set-text! label))
-              (mapv row-el entries))))
-
-(declare hide!)
-
-(defn- on-key-capture! [^js e]
-  (when (.-open? modal-state)
-    (cond
-      ;; Esc closes the modal and stops propagation so the
-      ;; shortcuts layer's :deselect handler doesn't also fire.
-      (= "Escape" (.-key e))
-      (do (.stopImmediatePropagation e)
-          (.preventDefault e)
-          (hide!))
-
-      ;; Pressing '?' a second time toggles the modal off.
-      (= "?" (.-key e))
-      (do (.stopImmediatePropagation e)
-          (.preventDefault e)
-          (hide!)))))
+(defn- on-key-capture!
+  "Esc closes the modal at capture phase so neither x-modal's internal
+   dismiss handler nor the document-level shortcut layer's :deselect
+   handler fire on the same keystroke. We own the close path, the
+   canvas selection stays untouched, and the keydown event ends here."
+  [^js e]
+  (when (and (open?) (= "Escape" (.-key e)))
+    (.stopImmediatePropagation e)
+    (.preventDefault e)
+    (hide!)))
 
-(defn- build-overlay! []
-  (let [^js close-btn (-> (u/el :x-button
-                                {:variant "ghost" :size "sm"
-                                 :class "cheat-close"})
-                          (u/set-text! "Close"))
-        groups (group-rows sh/shortcut-info sh/category-labels)
-        body (u/el :div {:class "cheat-body"}
-                   (mapv group-block groups))
-        header (u/el :div {:class "cheat-header"}
-                     [(-> (u/el :div {:class "cheat-title"})
-                          (u/set-text! "Keyboard shortcuts & gestures"))
-                      close-btn])
-        panel (u/el :div {:class "cheat-panel"}
-                    [header body])
-        overlay (u/el :div {:class "cheat-overlay"} [panel])]
-    (u/on! close-btn :press (fn [_] (hide!)))
-    ;; Click outside the panel (on the overlay backdrop) closes too.
-    (u/on! overlay :click
-           (fn [^js e]
-             (when (= overlay (.-target e))
-               (hide!))))
-    overlay))
+(defn- build-modal! []
+  (let [groups (group-rows sh/shortcut-info sh/category-labels)
+        body   (u/el :div {:class "cheat-body"}
+                     (mapv group-block groups))
+        title  (-> (typography "h3" "Keyboard shortcuts & gestures")
+                   (u/set-attr! :slot "header"))
+        modal  (u/el :x-modal
+                     {:size  "lg"
+                      :label "Keyboard shortcuts & gestures"}
+                     [title body])]
+    ;; x-modal emits x-modal-dismiss on backdrop click and Esc. Our
+    ;; capture-phase keydown short-circuits the Esc path before
+    ;; x-modal sees it; backdrop clicks still flow through this
+    ;; handler so `hide!` keeps modal-state in sync.
+    (u/on! modal :x-modal-dismiss (fn [^js _e] (hide!)))
+    (.appendChild js/document.body modal)
+    (set! (.-el modal-state) modal)
+    modal))
 
 (defn show!
-  "Mount the modal in `document.body` and start intercepting keys."
+  "Mount (lazily) and open the modal. Idempotent."
   []
-  (when-not (.-open? modal-state)
-    (let [^js overlay (build-overlay!)]
-      (.appendChild js/document.body overlay)
-      (set! (.-el modal-state) overlay)
-      (set! (.-open? modal-state) true)
-      ;; Capture phase so Esc / '?' inside the modal beats the
-      ;; document-level shortcut handler.
+  (when-not (open?)
+    (let [m (or (modal-el) (build-modal!))]
+      (u/set-attr! m :open "")
       (.addEventListener js/document "keydown" on-key-capture! true))))
 
 (defn hide!
-  "Remove the modal and stop intercepting keys."
+  "Close the modal if open. Leaves the element mounted so a re-show
+   can flip the `open` attribute without rebuilding the tree."
   []
-  (when (.-open? modal-state)
-    (when-let [^js overlay (modal-el)]
-      (when-let [^js parent (.-parentNode overlay)]
-        (.removeChild parent overlay)))
-    (set! (.-el modal-state) nil)
-    (set! (.-open? modal-state) false)
+  (when-let [m (modal-el)]
+    (.removeAttribute m "open")
     (.removeEventListener js/document "keydown" on-key-capture! true)))
 
 (defn toggle!
   "Show the modal if hidden, hide it if shown."
   []
-  (if (.-open? modal-state) (hide!) (show!)))
+  (if (open?) (hide!) (show!)))

From b56c65054aa1ab17d4587cb3d659e6e42b78250d Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 16:28:35 +0200
Subject: [PATCH 14/25] Cheat sheet: mount inside chrome x-theme so theming
 inherits
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

document.body sits outside the chrome's <x-theme preset="…"> element
(which wraps #app in index.html), so a modal appended to body never
saw the ocean / forest / sunset / … presets and rendered with the
default token palette.

build-modal! now resolves the theme host as `#app`'s parent node,
which is the chrome's outer x-theme. The modal mounts there as a
sibling of #app and inherits every CSS custom property the preset
sets — typography variants, surface colours, focus rings, all
follow the live theme. document.body remains the fallback if the
index.html shape ever changes.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/bareforge/ui/cheat_sheet.cljs | 11 ++++++++++-
 1 file changed, 10 insertions(+), 1 deletion(-)

diff --git a/src/bareforge/ui/cheat_sheet.cljs b/src/bareforge/ui/cheat_sheet.cljs
index f499863..528bad6 100644
--- a/src/bareforge/ui/cheat_sheet.cljs
+++ b/src/bareforge/ui/cheat_sheet.cljs
@@ -61,6 +61,15 @@
     (.preventDefault e)
     (hide!)))
 
+(defn- ^js theme-host
+  "Find the chrome's `<x-theme>` element so the modal mounts inside
+   it and inherits the active preset's CSS custom properties.
+   Falling back to `document.body` keeps the modal usable even if
+   the index.html shape changes."
+  []
+  (or (some-> (js/document.getElementById "app") .-parentNode)
+      js/document.body))
+
 (defn- build-modal! []
   (let [groups (group-rows sh/shortcut-info sh/category-labels)
         body   (u/el :div {:class "cheat-body"}
@@ -76,7 +85,7 @@
     ;; x-modal sees it; backdrop clicks still flow through this
     ;; handler so `hide!` keeps modal-state in sync.
     (u/on! modal :x-modal-dismiss (fn [^js _e] (hide!)))
-    (.appendChild js/document.body modal)
+    (.appendChild (theme-host) modal)
     (set! (.-el modal-state) modal)
     modal))
 

From e111511c1d130ba53fb839327e15486e42777176 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 19:44:26 +0200
Subject: [PATCH 15/25] M3.1: Cmd-K command palette
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A searchable modal that runs every chrome action — File menu, panel
toggles, selection ops, the four wrap-in targets, and `Insert <Tag>`
for every BareDOM tag — from one keyboard surface. Built on x-modal
+ x-typography so it inherits the active theme like the cheat sheet.

The empty-query view is a curated short list (file, view, selection,
wrap). Once the user types, the full pool joins in including the 80+
component inserts, ranked by score: prefix matches outrank in-word
substring hits, ties break alphabetically. The match logic is pure
and unit-tested in `command_palette_test`.

ArrowUp / ArrowDown move the active row, Enter runs it, Esc closes,
clicking a row also runs. The active command runs on a microtask so
modal mutations finish before the action mutates state — important
for actions that move focus or open another modal.

shortcuts.cljs grew a Cmd-K dispatch arm and a
set-show-command-palette! callback (mirroring set-show-shortcuts)
that main/init wires to command-palette/toggle!. Shared chrome
thunks (theme / templates / welcome-tour) flow through
command-palette/install! so the palette and the toolbar can't drift
on what those buttons do.

Action helpers in shortcuts.cljs (duplicate!, wrap-in!, copy-attrs!,
paste-attrs!) lose their defn- and become public so the palette
reuses them instead of duplicating the selection-commit-reselect
flow.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 public/index.html                           |  30 ++
 src/bareforge/main.cljs                     |   2 +
 src/bareforge/ui/app.cljs                   |  13 +-
 src/bareforge/ui/command_palette.cljs       | 318 ++++++++++++++++++++
 src/bareforge/ui/shortcuts.cljs             |  28 +-
 test/bareforge/ui/command_palette_test.cljs |  43 +++
 test/bareforge/ui/shortcuts_test.cljs       |  12 +
 7 files changed, 437 insertions(+), 9 deletions(-)
 create mode 100644 src/bareforge/ui/command_palette.cljs
 create mode 100644 test/bareforge/ui/command_palette_test.cljs

diff --git a/public/index.html b/public/index.html
index 43a7091..a5f6cdf 100644
--- a/public/index.html
+++ b/public/index.html
@@ -190,6 +190,36 @@
       padding: 4px 0;
       align-items: baseline;
     }
+
+    /* --- command palette -------------------------------------------- */
+    .command-body {
+      display: flex;
+      flex-direction: column;
+      gap: 12px;
+      min-width: 0;
+    }
+    .command-input { width: 100%; }
+    .command-list {
+      display: flex;
+      flex-direction: column;
+      max-height: 50vh;
+      overflow: auto;
+      gap: 2px;
+    }
+    .command-row {
+      display: grid;
+      grid-template-columns: 1fr auto;
+      gap: 12px;
+      align-items: center;
+      padding: 8px 12px;
+      border-radius: 6px;
+      cursor: pointer;
+    }
+    .command-row:hover { background: var(--x-color-surface-hover); }
+    .command-row.is-active {
+      background: var(--x-color-surface-active);
+      outline: 1px solid var(--x-color-primary);
+    }
     .bareforge-marquee[data-hidden] { display: none; }
     .chrome[data-mode="preview"] .bareforge-marquee { display: none; }
     .bareforge-inline-edit {
diff --git a/src/bareforge/main.cljs b/src/bareforge/main.cljs
index 71ca403..0b81a95 100644
--- a/src/bareforge/main.cljs
+++ b/src/bareforge/main.cljs
@@ -5,6 +5,7 @@
             [bareforge.storage.indexeddb :as idb]
             [bareforge.ui.app :as app]
             [bareforge.ui.cheat-sheet :as cheat-sheet]
+            [bareforge.ui.command-palette :as command-palette]
             [bareforge.ui.inspector :as inspector]
             [bareforge.ui.shortcuts :as shortcuts]
             [bareforge.ui.welcome-tour :as welcome-tour]
@@ -30,6 +31,7 @@
   (baredom/register!)
   (inspector/install-token-datalists!)
   (shortcuts/set-show-shortcuts! cheat-sheet/toggle!)
+  (shortcuts/set-show-command-palette! command-palette/toggle!)
   (app/mount! (u/by-id "app"))
   (-> (idb/restore!)
       (.then (fn [restored?]
diff --git a/src/bareforge/ui/app.cljs b/src/bareforge/ui/app.cljs
index 238f10a..490e7e5 100644
--- a/src/bareforge/ui/app.cljs
+++ b/src/bareforge/ui/app.cljs
@@ -7,6 +7,7 @@
             [bareforge.render.selection :as selection]
             [bareforge.render.slot-strips :as slot-strips]
             [bareforge.state :as state]
+            [bareforge.ui.command-palette :as command-palette]
             [bareforge.ui.inspector :as inspector]
             [bareforge.ui.layers :as layers]
             [bareforge.ui.palette :as palette]
@@ -31,10 +32,14 @@
   (let [theme-panel     (theme-editor/create)
         templates-panel (templates/create)
         tour-el         (welcome-tour/create)
-        toolbar-el      (toolbar/create
-                         {:on-theme-toggle     #(theme-editor/toggle! theme-panel)
-                          :on-templates-toggle #(templates/toggle! templates-panel)
-                          :on-welcome-tour     welcome-tour/open!})
+        ;; Thunks shared between the toolbar buttons and the Cmd-K
+        ;; command palette. Define once so a future binding
+        ;; (e.g. closing both panels) doesn't drift between surfaces.
+        chrome-thunks   {:on-theme-toggle     #(theme-editor/toggle! theme-panel)
+                         :on-templates-toggle #(templates/toggle! templates-panel)
+                         :on-welcome-tour     welcome-tour/open!}
+        _               (command-palette/install! chrome-thunks)
+        toolbar-el      (toolbar/create chrome-thunks)
         palette-el      (palette/create {:on-drag-start drag/start-from-palette!})
         layers-el       (layers/create)
         canvas-host     (u/el :div {:id    "bareforge-canvas"
diff --git a/src/bareforge/ui/command_palette.cljs b/src/bareforge/ui/command_palette.cljs
new file mode 100644
index 0000000..e6efdf4
--- /dev/null
+++ b/src/bareforge/ui/command_palette.cljs
@@ -0,0 +1,318 @@
+(ns bareforge.ui.command-palette
+  "Cmd-K command palette. A searchable modal that runs every action
+   the chrome exposes — File menu, panel toggles, selection ops,
+   wrap-in choices, and `Insert <Tag>` for every BareDOM tag — from
+   one keyboard surface.
+
+   Uses `x-modal` + `x-typography` for theme inheritance. Action
+   helpers (`duplicate!`, `wrap-in!`, `copy-attrs!`, `paste-attrs!`)
+   are reused from `shortcuts` so command-palette and shortcuts share
+   a single source of truth. Chrome-panel toggles are passed in at
+   `install!` time to avoid a circular require with the chrome
+   bootstrap."
+  (:require [bareforge.meta.registry :as registry]
+            [bareforge.state :as state]
+            [bareforge.storage.project-file :as pf]
+            [bareforge.ui.cheat-sheet :as cheat-sheet]
+            [bareforge.ui.palette :as palette]
+            [bareforge.ui.shortcuts :as sh]
+            [bareforge.util.dom :as u]
+            [clojure.string :as str]))
+
+;; --- chrome wiring ------------------------------------------------------
+
+(defonce ^:private install-state
+  ;; Callbacks that reach into chrome panels (Theme, Templates, Tour).
+  ;; Wired from main/init so the palette doesn't have to require the
+  ;; panels directly — same indirection as cheat-sheet's `set-show-`
+  ;; pattern, just generalised to a small map.
+  (atom {:on-theme-toggle     (constantly nil)
+         :on-templates-toggle (constantly nil)
+         :on-welcome-tour     (constantly nil)}))
+
+(defn install!
+  "Register chrome-panel toggle callbacks. `opts` is a map with
+   `:on-theme-toggle :on-templates-toggle :on-welcome-tour`. Called
+   from main/init alongside the cheat sheet wiring."
+  [opts]
+  (reset! install-state (merge {:on-theme-toggle     (constantly nil)
+                                :on-templates-toggle (constantly nil)
+                                :on-welcome-tour     (constantly nil)}
+                               opts)))
+
+;; --- commands -----------------------------------------------------------
+
+(defn- toggle-preview! []
+  (state/set-mode! (if (= :preview (:mode @state/app-state))
+                     :edit
+                     :preview)))
+
+(def ^:private wrap-tags
+  "Tags offered as wrap targets — must be a subset of the wrap whitelist
+   in shortcuts.cljs so Cmd-Shift-G prompt and the command palette
+   both accept the same set."
+  ["x-container" "x-grid" "x-card" "x-flex"])
+
+(defn- wrap-commands []
+  (mapv (fn [tag]
+          {:label (str "Wrap selection in " tag)
+           :group "Selection"
+           :run!  #(sh/wrap-in! tag)})
+        wrap-tags))
+
+(defn- insert-commands
+  "One entry per registered BareDOM tag. Hidden behind a non-empty
+   query so the empty-query palette stays a curated short list."
+  []
+  (mapv (fn [tag]
+          (let [meta-entry (registry/get-meta tag)]
+            {:label (str "Insert " tag
+                         (when-let [l (:label meta-entry)]
+                           (str "  ·  " l)))
+             :group "Insert component"
+             :run!  #(palette/insert-at-selection! tag)}))
+        (registry/all-tags)))
+
+(defn- curated-commands
+  "Commands shown when the query is empty — the muscle-memory short
+   list. Per-tag inserts join the pool only after the user starts
+   typing."
+  []
+  (concat
+    [{:label "Save project"             :group "File"      :run! pf/save!}
+     {:label "Open project…"            :group "File"      :run! pf/open!}
+     {:label "New project"              :group "File"      :run! pf/new!}
+
+     {:label "Toggle preview mode"      :group "View"      :run! toggle-preview!}
+     {:label "Toggle theme editor"      :group "View"
+      :run! #((:on-theme-toggle @install-state))}
+     {:label "Open templates…"          :group "View"
+      :run! #((:on-templates-toggle @install-state))}
+     {:label "Open welcome tour"        :group "View"
+      :run! #((:on-welcome-tour @install-state))}
+     {:label "Show keyboard shortcuts"  :group "View"
+      :run! cheat-sheet/show!}
+
+     {:label "Duplicate selection"      :group "Selection" :run! sh/duplicate!}
+     {:label "Copy attributes"          :group "Selection" :run! sh/copy-attrs!}
+     {:label "Paste attributes"         :group "Selection" :run! sh/paste-attrs!}]
+    (wrap-commands)))
+
+(defn- all-commands []
+  (concat (curated-commands) (insert-commands)))
+
+(defn- score
+  "Pure: case-insensitive substring scoring. Lower is better.
+   Prefix matches beat in-word matches; an empty query matches
+   everything with score 0."
+  [query label]
+  (let [q  (str/lower-case query)
+        l  (str/lower-case label)]
+    (cond
+      (str/blank? q)             0
+      (str/starts-with? l q)     0
+      :else                      (let [idx (.indexOf l q)]
+                                   (if (neg? idx) nil (inc idx))))))
+
+(defn filter-commands
+  "Pure: rank `commands` against `query`. Curated commands are kept on
+   an empty query; once the user types, every command (curated +
+   inserts) is in scope so an unfamiliar component is one keystroke
+   away. Returns the filtered seq in score order, ties broken by
+   label."
+  [commands query]
+  (let [q (some-> query str/trim)]
+    (if (or (nil? q) (= "" q))
+      ;; Empty query: curated only. Falls back to full list when
+      ;; commands is the curated subset already.
+      (vec commands)
+      (->> commands
+           (keep (fn [c]
+                   (when-let [s (score q (:label c))]
+                     (assoc c ::score s))))
+           (sort-by (juxt ::score :label))
+           vec))))
+
+;; --- modal --------------------------------------------------------------
+
+(defonce ^:private modal-state
+  ;; Mutable handles to DOM nodes plus the current command lists.
+  ;; Lists are stored as Clojure vectors (NOT clj->js'd) so the
+  ;; `:run!` keyword key keeps its meaning — clj->js translates `!`
+  ;; into `_BANG_`, which would silently break dispatch via property
+  ;; access.
+  #js {:el nil :input nil :list nil
+       :all-commands []
+       :curated      []
+       :visible      []
+       :index        0})
+
+(defn open?
+  "True iff the palette modal is mounted and showing."
+  []
+  (when-let [^js m (.-el modal-state)]
+    (.hasAttribute m "open")))
+
+(declare hide! refresh-list! run-active!)
+
+(defn- ^js theme-host
+  "Same theme-inheritance trick as the cheat sheet — mount inside the
+   chrome's `<x-theme>` so the active preset's tokens propagate."
+  []
+  (or (some-> (js/document.getElementById "app") .-parentNode)
+      js/document.body))
+
+(defn- on-key-capture! [^js e]
+  (when (open?)
+    (let [k (.-key e)]
+      (cond
+        (= k "Escape")
+        (do (.stopImmediatePropagation e)
+            (.preventDefault e)
+            (hide!))
+
+        (= k "ArrowDown")
+        (let [v (.-visible modal-state)
+              n (count v)]
+          (when (pos? n)
+            (.preventDefault e)
+            (set! (.-index modal-state) (mod (inc (.-index modal-state)) n))
+            (refresh-list!)))
+
+        (= k "ArrowUp")
+        (let [v (.-visible modal-state)
+              n (count v)]
+          (when (pos? n)
+            (.preventDefault e)
+            (set! (.-index modal-state)
+                  (mod (dec (.-index modal-state)) n))
+            (refresh-list!)))
+
+        (= k "Enter")
+        (do (.preventDefault e)
+            (run-active!))
+
+        :else nil))))
+
+(defn- typography [variant text]
+  (-> (u/el :x-typography {:variant variant})
+      (u/set-text! text)))
+
+(defn- row-el [{:keys [label group]} active?]
+  (let [row (u/el :div
+                  {:class (str "command-row"
+                               (when active? " is-active"))}
+                  [(typography "body2" label)
+                   (typography "caption" group)])]
+    row))
+
+(defn- build-input! []
+  (let [el (u/el :x-search-field
+                 {:class "command-input"
+                  :placeholder "Type a command, component, or action…"})]
+    (u/on! el :x-search-field-input
+           (fn [^js _e]
+             (set! (.-index modal-state) 0)
+             (refresh-list!)))
+    el))
+
+(defn- build-list! []
+  (u/el :div {:class "command-list"}))
+
+(defn- current-query []
+  (let [^js input (.-input modal-state)]
+    (if input
+      (or (.-value input) "")
+      "")))
+
+(defn- visible-commands
+  "Compute the currently-visible filtered commands based on the input
+   value. With an empty query we show the curated short list; any
+   non-empty query searches the full pool so unfamiliar tags are one
+   keystroke away."
+  []
+  (let [q (current-query)]
+    (filter-commands
+      (if (str/blank? q)
+        (.-curated modal-state)
+        (.-all-commands modal-state))
+      q)))
+
+(defn- refresh-list! []
+  (when-let [^js list-el (.-list modal-state)]
+    (let [vis (vec (visible-commands))
+          n   (count vis)
+          ;; Clamp index to the new length so a shrinking list never
+          ;; leaves :index dangling past its end.
+          idx (if (zero? n) 0 (min (.-index modal-state) (dec n)))]
+      (set! (.-visible modal-state) vis)
+      (set! (.-index modal-state) idx)
+      (.replaceChildren list-el)
+      (doseq [[i c] (map-indexed vector vis)]
+        (let [active? (= i idx)
+              row     (row-el c active?)]
+          (u/on! row :click (fn [_]
+                              (set! (.-index modal-state) i)
+                              (run-active!)))
+          (.appendChild list-el row))))))
+
+(defn- run-active! []
+  (let [v (.-visible modal-state)
+        i (.-index modal-state)
+        n (count v)]
+    (when (and (pos? n) (< i n))
+      (let [cmd (nth v i)
+            f   (:run! cmd)]
+        (hide!)
+        ;; Defer to next microtask so the modal-close mutations finish
+        ;; before any commands that mutate state / focus / DOM run.
+        (js/queueMicrotask
+          (fn []
+            (try (f) (catch :default _ nil))))))))
+
+(defn- build-modal! []
+  (let [input  (build-input!)
+        list-  (build-list!)
+        body   (u/el :div {:class "command-body"} [input list-])
+        title  (-> (typography "h3" "Command palette")
+                   (u/set-attr! :slot "header"))
+        modal  (u/el :x-modal
+                     {:size  "md"
+                      :label "Command palette"}
+                     [title body])]
+    (u/on! modal :x-modal-dismiss (fn [^js _e] (hide!)))
+    (.appendChild (theme-host) modal)
+    (set! (.-el    modal-state) modal)
+    (set! (.-input modal-state) input)
+    (set! (.-list  modal-state) list-)
+    modal))
+
+(defn show!
+  "Mount (lazily) and open the palette. Refreshes its command pool
+   every time so a dynamic registry (new tags, theme overrides) is
+   reflected without a page reload."
+  []
+  (when-not (open?)
+    (let [m (or (.-el modal-state) (build-modal!))]
+      (set! (.-curated modal-state)      (vec (curated-commands)))
+      (set! (.-all-commands modal-state) (vec (all-commands)))
+      (set! (.-index modal-state) 0)
+      ;; Clear any stale query from a previous session.
+      (when-let [^js inp (.-input modal-state)]
+        (.setAttribute inp "value" ""))
+      (refresh-list!)
+      (u/set-attr! m :open "")
+      (.addEventListener js/document "keydown" on-key-capture! true)
+      ;; Defer focus so x-modal's connectedCallback / focus trap has
+      ;; finished its work; otherwise our explicit focus is overwritten.
+      (js/requestAnimationFrame
+        (fn [] (when-let [^js inp (.-input modal-state)]
+                 (.focus inp)))))))
+
+(defn hide! []
+  (when-let [^js m (.-el modal-state)]
+    (.removeAttribute m "open")
+    (.removeEventListener js/document "keydown" on-key-capture! true)))
+
+(defn toggle! []
+  (if (open?) (hide!) (show!)))
diff --git a/src/bareforge/ui/shortcuts.cljs b/src/bareforge/ui/shortcuts.cljs
index ab51f6f..a08e687 100644
--- a/src/bareforge/ui/shortcuts.cljs
+++ b/src/bareforge/ui/shortcuts.cljs
@@ -81,6 +81,7 @@
    {:category :file       :keys "Cmd+O"          :label "Open project"}
    {:category :file       :keys "Cmd+N"          :label "New project"}
 
+   {:category :view       :keys "Cmd+K"          :label "Open command palette"}
    {:category :view       :keys "?"              :label "Show this cheat sheet"}])
 
 (def category-labels
@@ -178,6 +179,10 @@
            (not editable?))
       :show-shortcuts
 
+      (and meta? (= "k" key) (not shift?) (not alt?)
+           (not editable?))
+      :show-command-palette
+
       (and meta? alt? c-letter? (not shift?)
            has-selection?
            (not= "root" selection-id)
@@ -318,7 +323,7 @@
        (remove nil?)
        vec))
 
-(defn- duplicate! []
+(defn duplicate! []
   (let [ids (selected-doc-ids)]
     (when (seq ids)
       (let [doc (:document @state/app-state)
@@ -334,7 +339,7 @@
   [tag]
   (set (map :name (:properties (registry/get-meta tag)))))
 
-(defn- copy-attrs! []
+(defn copy-attrs! []
   (when-let [id (some-> (state/single-selected-id @state/app-state)
                         canvas/canonical-node-id)]
     (when-let [n (and (not= "root" id)
@@ -344,7 +349,7 @@
          :attrs      (or (:attrs n) {})
          :props      (or (:props n) {})}))))
 
-(defn- paste-attrs! []
+(defn paste-attrs! []
   (when-let [{:keys [attrs props]} (state/clipboard-attrs @state/app-state)]
     (let [target-ids (selected-doc-ids)]
       (when (seq target-ids)
@@ -371,7 +376,7 @@
           (when (not= doc doc')
             (state/commit! doc')))))))
 
-(defn- wrap-in! [tag]
+(defn wrap-in! [tag]
   (let [ids (selected-doc-ids)]
     (when (and (contains? wrap-tag-whitelist tag) (seq ids))
       (let [doc (:document @state/app-state)
@@ -393,6 +398,7 @@
       input)))
 
 (defonce ^:private show-shortcuts-fn (atom (constantly nil)))
+(defonce ^:private show-command-palette-fn (atom (constantly nil)))
 
 (defn set-show-shortcuts!
   "Register the function called when `dispatch` returns :show-shortcuts.
@@ -403,6 +409,17 @@
   [f]
   (reset! show-shortcuts-fn f))
 
+(defn set-show-command-palette!
+  "Register the function called when `dispatch` returns
+   :show-command-palette. Same callback indirection as
+   `set-show-shortcuts!` to keep the namespace graph acyclic — the
+   command palette consumes shortcuts' public action helpers
+   (duplicate!, wrap-in!, copy-attrs!, paste-attrs!) plus
+   shortcut-info and category-labels, so the show callback flows
+   in the opposite direction."
+  [f]
+  (reset! show-command-palette-fn f))
+
 (defn- perform! [action ^js e]
   (cond
     (vector? action)
@@ -438,7 +455,8 @@
                             (wrap-in! tag)))
       :copy-attrs  (do (.preventDefault e) (copy-attrs!))
       :paste-attrs (do (.preventDefault e) (paste-attrs!))
-      :show-shortcuts (do (.preventDefault e) (@show-shortcuts-fn))
+      :show-shortcuts       (do (.preventDefault e) (@show-shortcuts-fn))
+      :show-command-palette (do (.preventDefault e) (@show-command-palette-fn))
       :exit-text-edit (do (.preventDefault e) (inline-edit/teardown!))
       :deselect (do (.preventDefault e) (state/select-clear!))
       nil)))
diff --git a/test/bareforge/ui/command_palette_test.cljs b/test/bareforge/ui/command_palette_test.cljs
new file mode 100644
index 0000000..6b7d9b9
--- /dev/null
+++ b/test/bareforge/ui/command_palette_test.cljs
@@ -0,0 +1,43 @@
+(ns bareforge.ui.command-palette-test
+  (:require [cljs.test :refer [deftest is]]
+            [bareforge.ui.command-palette :as cp]))
+
+(def ^:private sample
+  [{:label "Save project"        :group "File"}
+   {:label "Open project…"       :group "File"}
+   {:label "New project"         :group "File"}
+   {:label "Toggle preview mode" :group "View"}
+   {:label "Toggle theme editor" :group "View"}
+   {:label "Insert x-button"     :group "Insert component"}
+   {:label "Insert x-card"       :group "Insert component"}])
+
+(deftest filter-empty-returns-input-as-vector
+  (is (= sample (cp/filter-commands sample "")))
+  (is (= sample (cp/filter-commands sample nil)))
+  (is (= sample (cp/filter-commands sample "   "))))
+
+(deftest filter-prefix-beats-substring
+  (let [out (cp/filter-commands sample "tog")]
+    (is (= "Toggle preview mode" (:label (first out)))
+        "prefix match scores 0; sorts before any substring hits")))
+
+(deftest filter-substring-match
+  (let [out (cp/filter-commands sample "card")]
+    (is (= 1 (count out)))
+    (is (= "Insert x-card" (:label (first out))))))
+
+(deftest filter-case-insensitive
+  (let [out (cp/filter-commands sample "INSERT")]
+    (is (= 2 (count out)))
+    (is (every? (fn [c] (= "Insert component" (:group c))) out))))
+
+(deftest filter-no-matches-returns-empty
+  (is (= [] (cp/filter-commands sample "no-such-thing")))
+  (is (vector? (cp/filter-commands sample "xyz"))))
+
+(deftest filter-ties-sort-by-label
+  (let [out (cp/filter-commands sample "project")]
+    (is (= ["New project" "Open project…" "Save project"]
+           (mapv :label out))
+        "all three score the same (substring at position 5/6/12);
+         labels sort alphabetically as the tiebreaker")))
diff --git a/test/bareforge/ui/shortcuts_test.cljs b/test/bareforge/ui/shortcuts_test.cljs
index d547122..7b6e3ad 100644
--- a/test/bareforge/ui/shortcuts_test.cljs
+++ b/test/bareforge/ui/shortcuts_test.cljs
@@ -346,6 +346,18 @@
   (is (= :noop
          (k/dispatch (assoc base :key "?" :meta? true)))))
 
+(deftest dispatch-cmd-k-shows-command-palette
+  (is (= :show-command-palette
+         (k/dispatch (assoc base :key "k" :meta? true)))))
+
+(deftest dispatch-cmd-k-ignored-in-editable
+  (is (= :noop
+         (k/dispatch (assoc base :key "k" :meta? true :tag-name "INPUT")))))
+
+(deftest dispatch-cmd-shift-k-is-noop
+  (is (= :noop
+         (k/dispatch (assoc base :key "k" :meta? true :shift? true)))))
+
 ;; --- shortcut-info coverage --------------------------------------------
 
 (deftest shortcut-info-has-known-categories

From fbb649b0fe7beb6b36257493c2824fc5674ae2e2 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 21:23:31 +0200
Subject: [PATCH 16/25] Command palette: focus the shadow inner input on open
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Calling .focus() on the x-search-field host did nothing because
the component doesn't delegateFocus. x-modal's own focus trap also
landed on the host, so opening Cmd-K left the user one Tab away
from typing.

show! now walks into the field's shadow root on rAF and calls
focus() on the real <input part="input">. A retry loop handles the
case where the shadow root isn't populated yet — same pattern as
the datalist clone.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/bareforge/ui/command_palette.cljs | 19 ++++++++++++++-----
 1 file changed, 14 insertions(+), 5 deletions(-)

diff --git a/src/bareforge/ui/command_palette.cljs b/src/bareforge/ui/command_palette.cljs
index e6efdf4..dffc9e3 100644
--- a/src/bareforge/ui/command_palette.cljs
+++ b/src/bareforge/ui/command_palette.cljs
@@ -303,11 +303,20 @@
       (refresh-list!)
       (u/set-attr! m :open "")
       (.addEventListener js/document "keydown" on-key-capture! true)
-      ;; Defer focus so x-modal's connectedCallback / focus trap has
-      ;; finished its work; otherwise our explicit focus is overwritten.
-      (js/requestAnimationFrame
-        (fn [] (when-let [^js inp (.-input modal-state)]
-                 (.focus inp)))))))
+      ;; x-modal's focus trap fires inside its own setTimeout(0) and
+      ;; targets the host x-search-field, which can't take focus
+      ;; itself (no delegatesFocus). Walk into its shadow root and
+      ;; focus the real <input part="input"> on the next animation
+      ;; frame so the user lands typing without an extra Tab. A retry
+      ;; loop covers components whose shadow root is built one frame
+      ;; later than expected.
+      (letfn [(focus-search! []
+                (when-let [^js inp (.-input modal-state)]
+                  (if-let [^js sr (.-shadowRoot inp)]
+                    (when-let [^js inner (.querySelector sr "[part=input]")]
+                      (.focus inner))
+                    (js/requestAnimationFrame focus-search!))))]
+        (js/requestAnimationFrame focus-search!)))))
 
 (defn hide! []
   (when-let [^js m (.-el modal-state)]

From 245e0c35c01269eb745c17098469b442746572b5 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 21:26:53 +0200
Subject: [PATCH 17/25] Command palette: rebuild on top of x-command-palette
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The hand-rolled modal lost focus to x-modal's focus trap and to
the x-search-field's host-vs-shadow-input split. Switching to the
x-command-palette BareDOM component lets the component own the
modal chrome, scrim, focus, fuzzy filter, ARIA roles, and keyboard
navigation — all the parts we were re-implementing — and inherits
the active theme through its own shadow CSS.

This namespace is now just the command catalogue and a thin
dispatch shim. all-commands maps each command into the JS shape
the component consumes (id, label, group, keywords); a synthetic
id ('cmd-N') indexes a Clojure id→run! map kept on modal-state so
the select event resolves back to the right thunk. Curated File /
View / Selection commands sit alongside the four wrap-in choices
and one entry per registered BareDOM tag, so 'btn' or 'card'
finds the right insert without typing the full x- name.

show! refreshes the items property and calls .open() on the host;
hide! calls .close(); toggle! flips between the two. The component
emits x-command-palette-select with the chosen item; we look up
its id and run the thunk on a microtask so the palette's own close
work finishes first.

The hand-rolled filter / row-list / focus retry / index state and
the matching command-palette CSS are gone. The pure
filter-commands unit tests are dropped along with them — the
component's filter is BareDOM's responsibility now, covered by its
own tests.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 public/index.html                           |  31 +-
 src/bareforge/ui/command_palette.cljs       | 389 +++++++-------------
 test/bareforge/ui/command_palette_test.cljs |  43 ---
 3 files changed, 130 insertions(+), 333 deletions(-)
 delete mode 100644 test/bareforge/ui/command_palette_test.cljs

diff --git a/public/index.html b/public/index.html
index a5f6cdf..80ccf40 100644
--- a/public/index.html
+++ b/public/index.html
@@ -191,35 +191,8 @@
       align-items: baseline;
     }
 
-    /* --- command palette -------------------------------------------- */
-    .command-body {
-      display: flex;
-      flex-direction: column;
-      gap: 12px;
-      min-width: 0;
-    }
-    .command-input { width: 100%; }
-    .command-list {
-      display: flex;
-      flex-direction: column;
-      max-height: 50vh;
-      overflow: auto;
-      gap: 2px;
-    }
-    .command-row {
-      display: grid;
-      grid-template-columns: 1fr auto;
-      gap: 12px;
-      align-items: center;
-      padding: 8px 12px;
-      border-radius: 6px;
-      cursor: pointer;
-    }
-    .command-row:hover { background: var(--x-color-surface-hover); }
-    .command-row.is-active {
-      background: var(--x-color-surface-active);
-      outline: 1px solid var(--x-color-primary);
-    }
+    /* x-command-palette owns its own modal chrome and shadow-DOM
+       styling — no host-level CSS needed. */
     .bareforge-marquee[data-hidden] { display: none; }
     .chrome[data-mode="preview"] .bareforge-marquee { display: none; }
     .bareforge-inline-edit {
diff --git a/src/bareforge/ui/command_palette.cljs b/src/bareforge/ui/command_palette.cljs
index dffc9e3..0359d2c 100644
--- a/src/bareforge/ui/command_palette.cljs
+++ b/src/bareforge/ui/command_palette.cljs
@@ -1,31 +1,30 @@
 (ns bareforge.ui.command-palette
-  "Cmd-K command palette. A searchable modal that runs every action
-   the chrome exposes — File menu, panel toggles, selection ops,
-   wrap-in choices, and `Insert <Tag>` for every BareDOM tag — from
-   one keyboard surface.
-
-   Uses `x-modal` + `x-typography` for theme inheritance. Action
-   helpers (`duplicate!`, `wrap-in!`, `copy-attrs!`, `paste-attrs!`)
-   are reused from `shortcuts` so command-palette and shortcuts share
-   a single source of truth. Chrome-panel toggles are passed in at
-   `install!` time to avoid a circular require with the chrome
-   bootstrap."
+  "Cmd-K command palette built on the `x-command-palette` BareDOM
+   component. The component owns the modal chrome, focus, fuzzy
+   filtering, keyboard navigation, and ARIA roles; this namespace
+   contributes the static + dynamic command list and the dispatch
+   layer that maps a selected item back to its handler.
+
+   Action helpers (`duplicate!`, `wrap-in!`, `copy-attrs!`,
+   `paste-attrs!`) are reused from `shortcuts` so the palette and
+   the keyboard surface share a single source of truth. Chrome-panel
+   toggles are passed in at `install!` time to avoid a circular
+   require with the chrome bootstrap."
   (:require [bareforge.meta.registry :as registry]
             [bareforge.state :as state]
             [bareforge.storage.project-file :as pf]
             [bareforge.ui.cheat-sheet :as cheat-sheet]
             [bareforge.ui.palette :as palette]
             [bareforge.ui.shortcuts :as sh]
-            [bareforge.util.dom :as u]
-            [clojure.string :as str]))
+            [bareforge.util.dom :as u]))
 
 ;; --- chrome wiring ------------------------------------------------------
 
 (defonce ^:private install-state
-  ;; Callbacks that reach into chrome panels (Theme, Templates, Tour).
-  ;; Wired from main/init so the palette doesn't have to require the
-  ;; panels directly — same indirection as cheat-sheet's `set-show-`
-  ;; pattern, just generalised to a small map.
+  ;; Callbacks reaching into chrome panels (Theme, Templates, Tour).
+  ;; Wired from main/init via `install!` so the palette doesn't have
+  ;; to require the panels directly — keeps the namespace graph
+  ;; acyclic.
   (atom {:on-theme-toggle     (constantly nil)
          :on-templates-toggle (constantly nil)
          :on-welcome-tour     (constantly nil)}))
@@ -33,7 +32,7 @@
 (defn install!
   "Register chrome-panel toggle callbacks. `opts` is a map with
    `:on-theme-toggle :on-templates-toggle :on-welcome-tour`. Called
-   from main/init alongside the cheat sheet wiring."
+   from `ui.app/build-chrome` alongside the cheat-sheet wiring."
   [opts]
   (reset! install-state (merge {:on-theme-toggle     (constantly nil)
                                 :on-templates-toggle (constantly nil)
@@ -48,280 +47,148 @@
                      :preview)))
 
 (def ^:private wrap-tags
-  "Tags offered as wrap targets — must be a subset of the wrap whitelist
-   in shortcuts.cljs so Cmd-Shift-G prompt and the command palette
-   both accept the same set."
+  "Wrap-in tags offered by the palette — must be a subset of
+   shortcuts/wrap-tag-whitelist so the keyboard prompt and the
+   palette accept the same set."
   ["x-container" "x-grid" "x-card" "x-flex"])
 
 (defn- wrap-commands []
   (mapv (fn [tag]
-          {:label (str "Wrap selection in " tag)
-           :group "Selection"
-           :run!  #(sh/wrap-in! tag)})
+          {:label    (str "Wrap selection in " tag)
+           :group    "Selection"
+           :keywords (str "wrap container " tag)
+           :run!     #(sh/wrap-in! tag)})
         wrap-tags))
 
 (defn- insert-commands
-  "One entry per registered BareDOM tag. Hidden behind a non-empty
-   query so the empty-query palette stays a curated short list."
+  "One entry per registered BareDOM tag. Keywords pull in the human
+   label so 'btn' / 'card' / 'navbar' all surface the right tag even
+   when the literal `x-*` name isn't typed."
   []
   (mapv (fn [tag]
-          (let [meta-entry (registry/get-meta tag)]
-            {:label (str "Insert " tag
-                         (when-let [l (:label meta-entry)]
-                           (str "  ·  " l)))
-             :group "Insert component"
-             :run!  #(palette/insert-at-selection! tag)}))
+          (let [meta-entry (registry/get-meta tag)
+                hum        (:label meta-entry)]
+            {:label    (str "Insert " tag
+                            (when hum (str "  ·  " hum)))
+             :group    "Insert component"
+             :keywords (str "insert " tag (when hum (str " " hum)))
+             :run!     #(palette/insert-at-selection! tag)}))
         (registry/all-tags)))
 
-(defn- curated-commands
-  "Commands shown when the query is empty — the muscle-memory short
-   list. Per-tag inserts join the pool only after the user starts
-   typing."
+(defn- curated-commands []
+  [{:label "Save project"             :group "File"      :keywords "save"
+    :run! pf/save!}
+   {:label "Open project…"            :group "File"      :keywords "open load"
+    :run! pf/open!}
+   {:label "New project"              :group "File"      :keywords "new"
+    :run! pf/new!}
+
+   {:label "Toggle preview mode"      :group "View"      :keywords "preview"
+    :run! toggle-preview!}
+   {:label "Toggle theme editor"      :group "View"      :keywords "theme color"
+    :run! #((:on-theme-toggle @install-state))}
+   {:label "Open templates…"          :group "View"      :keywords "templates starter"
+    :run! #((:on-templates-toggle @install-state))}
+   {:label "Open welcome tour"        :group "View"      :keywords "tour onboarding"
+    :run! #((:on-welcome-tour @install-state))}
+   {:label "Show keyboard shortcuts"  :group "View"      :keywords "shortcuts cheat sheet help"
+    :run! cheat-sheet/show!}
+
+   {:label "Duplicate selection"      :group "Selection" :keywords "duplicate copy clone"
+    :run! sh/duplicate!}
+   {:label "Copy attributes"          :group "Selection" :keywords "copy attrs styles"
+    :run! sh/copy-attrs!}
+   {:label "Paste attributes"         :group "Selection" :keywords "paste attrs styles"
+    :run! sh/paste-attrs!}])
+
+(defn- all-commands
+  "Curated commands followed by the per-tag insert commands. The
+   palette's built-in fuzzy filter ranks them all together — the
+   curated ones tend to win on shorter labels."
   []
-  (concat
-    [{:label "Save project"             :group "File"      :run! pf/save!}
-     {:label "Open project…"            :group "File"      :run! pf/open!}
-     {:label "New project"              :group "File"      :run! pf/new!}
-
-     {:label "Toggle preview mode"      :group "View"      :run! toggle-preview!}
-     {:label "Toggle theme editor"      :group "View"
-      :run! #((:on-theme-toggle @install-state))}
-     {:label "Open templates…"          :group "View"
-      :run! #((:on-templates-toggle @install-state))}
-     {:label "Open welcome tour"        :group "View"
-      :run! #((:on-welcome-tour @install-state))}
-     {:label "Show keyboard shortcuts"  :group "View"
-      :run! cheat-sheet/show!}
-
-     {:label "Duplicate selection"      :group "Selection" :run! sh/duplicate!}
-     {:label "Copy attributes"          :group "Selection" :run! sh/copy-attrs!}
-     {:label "Paste attributes"         :group "Selection" :run! sh/paste-attrs!}]
-    (wrap-commands)))
-
-(defn- all-commands []
-  (concat (curated-commands) (insert-commands)))
-
-(defn- score
-  "Pure: case-insensitive substring scoring. Lower is better.
-   Prefix matches beat in-word matches; an empty query matches
-   everything with score 0."
-  [query label]
-  (let [q  (str/lower-case query)
-        l  (str/lower-case label)]
-    (cond
-      (str/blank? q)             0
-      (str/starts-with? l q)     0
-      :else                      (let [idx (.indexOf l q)]
-                                   (if (neg? idx) nil (inc idx))))))
-
-(defn filter-commands
-  "Pure: rank `commands` against `query`. Curated commands are kept on
-   an empty query; once the user types, every command (curated +
-   inserts) is in scope so an unfamiliar component is one keystroke
-   away. Returns the filtered seq in score order, ties broken by
-   label."
-  [commands query]
-  (let [q (some-> query str/trim)]
-    (if (or (nil? q) (= "" q))
-      ;; Empty query: curated only. Falls back to full list when
-      ;; commands is the curated subset already.
-      (vec commands)
-      (->> commands
-           (keep (fn [c]
-                   (when-let [s (score q (:label c))]
-                     (assoc c ::score s))))
-           (sort-by (juxt ::score :label))
-           vec))))
+  (concat (curated-commands) (wrap-commands) (insert-commands)))
 
 ;; --- modal --------------------------------------------------------------
 
 (defonce ^:private modal-state
-  ;; Mutable handles to DOM nodes plus the current command lists.
-  ;; Lists are stored as Clojure vectors (NOT clj->js'd) so the
-  ;; `:run!` keyword key keeps its meaning — clj->js translates `!`
-  ;; into `_BANG_`, which would silently break dispatch via property
-  ;; access.
-  #js {:el nil :input nil :list nil
-       :all-commands []
-       :curated      []
-       :visible      []
-       :index        0})
-
-(defn open?
-  "True iff the palette modal is mounted and showing."
-  []
-  (when-let [^js m (.-el modal-state)]
-    (.hasAttribute m "open")))
-
-(declare hide! refresh-list! run-active!)
+  ;; :el        the x-command-palette host
+  ;; :run-by-id map from each item's synthetic id back to its run!
+  ;;            thunk. The select event hands us the id only.
+  #js {:el nil :run-by-id {}})
 
 (defn- ^js theme-host
-  "Same theme-inheritance trick as the cheat sheet — mount inside the
-   chrome's `<x-theme>` so the active preset's tokens propagate."
+  "Same trick as the cheat sheet: mount inside the chrome's
+   `<x-theme>` element so the active preset's tokens propagate.
+   Falls back to `document.body` if the host isn't found."
   []
   (or (some-> (js/document.getElementById "app") .-parentNode)
       js/document.body))
 
-(defn- on-key-capture! [^js e]
-  (when (open?)
-    (let [k (.-key e)]
-      (cond
-        (= k "Escape")
-        (do (.stopImmediatePropagation e)
-            (.preventDefault e)
-            (hide!))
-
-        (= k "ArrowDown")
-        (let [v (.-visible modal-state)
-              n (count v)]
-          (when (pos? n)
-            (.preventDefault e)
-            (set! (.-index modal-state) (mod (inc (.-index modal-state)) n))
-            (refresh-list!)))
-
-        (= k "ArrowUp")
-        (let [v (.-visible modal-state)
-              n (count v)]
-          (when (pos? n)
-            (.preventDefault e)
-            (set! (.-index modal-state)
-                  (mod (dec (.-index modal-state)) n))
-            (refresh-list!)))
-
-        (= k "Enter")
-        (do (.preventDefault e)
-            (run-active!))
-
-        :else nil))))
-
-(defn- typography [variant text]
-  (-> (u/el :x-typography {:variant variant})
-      (u/set-text! text)))
-
-(defn- row-el [{:keys [label group]} active?]
-  (let [row (u/el :div
-                  {:class (str "command-row"
-                               (when active? " is-active"))}
-                  [(typography "body2" label)
-                   (typography "caption" group)])]
-    row))
+(defn- ->item
+  "Pure: project a Clojure command map into the JS shape
+   `x-command-palette` consumes. The synthetic `id` is the index
+   string; `keywords` flow through the component's filter so labels
+   stay short while typed terms resolve broadly."
+  [i {:keys [label group keywords]}]
+  #js {:id    (str "cmd-" i)
+       :label label
+       :group group
+       :keywords (or keywords "")})
+
+(defn- build-pool
+  "Returns `[js-items run-by-id]` from the current command pool."
+  []
+  (let [cmds (vec (all-commands))]
+    [(into-array
+       (map-indexed ->item cmds))
+     (into {}
+           (map-indexed (fn [i c] [(str "cmd-" i) (:run! c)]))
+           cmds)]))
+
+(defn- on-select! [^js e]
+  (let [^js detail (.-detail e)
+        ^js item   (.-item detail)
+        id         (.-id item)
+        f          (get (.-run-by-id modal-state) id)]
+    (when f
+      ;; Defer to next microtask so the palette finishes its own
+      ;; close-on-select work before we mutate state / focus.
+      (js/queueMicrotask
+        (fn [] (try (f) (catch :default _ nil)))))))
 
-(defn- build-input! []
-  (let [el (u/el :x-search-field
-                 {:class "command-input"
-                  :placeholder "Type a command, component, or action…"})]
-    (u/on! el :x-search-field-input
-           (fn [^js _e]
-             (set! (.-index modal-state) 0)
-             (refresh-list!)))
+(defn- build-modal! []
+  (let [el (u/el :x-command-palette
+                 {:label       "Command palette"
+                  :placeholder "Search commands, components, or actions…"
+                  :empty-text  "No matching commands"
+                  :modal       ""})]
+    (u/on! el "x-command-palette-select" on-select!)
+    (.appendChild (theme-host) el)
+    (set! (.-el modal-state) el)
     el))
 
-(defn- build-list! []
-  (u/el :div {:class "command-list"}))
-
-(defn- current-query []
-  (let [^js input (.-input modal-state)]
-    (if input
-      (or (.-value input) "")
-      "")))
-
-(defn- visible-commands
-  "Compute the currently-visible filtered commands based on the input
-   value. With an empty query we show the curated short list; any
-   non-empty query searches the full pool so unfamiliar tags are one
-   keystroke away."
+(defn open?
+  "True iff the palette is currently mounted and showing."
   []
-  (let [q (current-query)]
-    (filter-commands
-      (if (str/blank? q)
-        (.-curated modal-state)
-        (.-all-commands modal-state))
-      q)))
-
-(defn- refresh-list! []
-  (when-let [^js list-el (.-list modal-state)]
-    (let [vis (vec (visible-commands))
-          n   (count vis)
-          ;; Clamp index to the new length so a shrinking list never
-          ;; leaves :index dangling past its end.
-          idx (if (zero? n) 0 (min (.-index modal-state) (dec n)))]
-      (set! (.-visible modal-state) vis)
-      (set! (.-index modal-state) idx)
-      (.replaceChildren list-el)
-      (doseq [[i c] (map-indexed vector vis)]
-        (let [active? (= i idx)
-              row     (row-el c active?)]
-          (u/on! row :click (fn [_]
-                              (set! (.-index modal-state) i)
-                              (run-active!)))
-          (.appendChild list-el row))))))
-
-(defn- run-active! []
-  (let [v (.-visible modal-state)
-        i (.-index modal-state)
-        n (count v)]
-    (when (and (pos? n) (< i n))
-      (let [cmd (nth v i)
-            f   (:run! cmd)]
-        (hide!)
-        ;; Defer to next microtask so the modal-close mutations finish
-        ;; before any commands that mutate state / focus / DOM run.
-        (js/queueMicrotask
-          (fn []
-            (try (f) (catch :default _ nil))))))))
-
-(defn- build-modal! []
-  (let [input  (build-input!)
-        list-  (build-list!)
-        body   (u/el :div {:class "command-body"} [input list-])
-        title  (-> (typography "h3" "Command palette")
-                   (u/set-attr! :slot "header"))
-        modal  (u/el :x-modal
-                     {:size  "md"
-                      :label "Command palette"}
-                     [title body])]
-    (u/on! modal :x-modal-dismiss (fn [^js _e] (hide!)))
-    (.appendChild (theme-host) modal)
-    (set! (.-el    modal-state) modal)
-    (set! (.-input modal-state) input)
-    (set! (.-list  modal-state) list-)
-    modal))
+  (when-let [^js m (.-el modal-state)]
+    (.hasAttribute m "open")))
 
 (defn show!
-  "Mount (lazily) and open the palette. Refreshes its command pool
-   every time so a dynamic registry (new tags, theme overrides) is
-   reflected without a page reload."
+  "Refresh the command pool and open the palette. Items are
+   recomputed each call so a newly registered chrome thunk or BareDOM
+   tag joins the list without restarting the app."
   []
-  (when-not (open?)
-    (let [m (or (.-el modal-state) (build-modal!))]
-      (set! (.-curated modal-state)      (vec (curated-commands)))
-      (set! (.-all-commands modal-state) (vec (all-commands)))
-      (set! (.-index modal-state) 0)
-      ;; Clear any stale query from a previous session.
-      (when-let [^js inp (.-input modal-state)]
-        (.setAttribute inp "value" ""))
-      (refresh-list!)
-      (u/set-attr! m :open "")
-      (.addEventListener js/document "keydown" on-key-capture! true)
-      ;; x-modal's focus trap fires inside its own setTimeout(0) and
-      ;; targets the host x-search-field, which can't take focus
-      ;; itself (no delegatesFocus). Walk into its shadow root and
-      ;; focus the real <input part="input"> on the next animation
-      ;; frame so the user lands typing without an extra Tab. A retry
-      ;; loop covers components whose shadow root is built one frame
-      ;; later than expected.
-      (letfn [(focus-search! []
-                (when-let [^js inp (.-input modal-state)]
-                  (if-let [^js sr (.-shadowRoot inp)]
-                    (when-let [^js inner (.querySelector sr "[part=input]")]
-                      (.focus inner))
-                    (js/requestAnimationFrame focus-search!))))]
-        (js/requestAnimationFrame focus-search!)))))
+  (let [^js el (or (.-el modal-state) (build-modal!))
+        [items run-by-id] (build-pool)]
+    (set! (.-items el) items)
+    (set! (.-run-by-id modal-state) run-by-id)
+    (.open el)))
 
 (defn hide! []
   (when-let [^js m (.-el modal-state)]
-    (.removeAttribute m "open")
-    (.removeEventListener js/document "keydown" on-key-capture! true)))
+    (.close m)))
 
-(defn toggle! []
+(defn toggle!
+  "Show the palette if hidden, hide it if shown."
+  []
   (if (open?) (hide!) (show!)))
diff --git a/test/bareforge/ui/command_palette_test.cljs b/test/bareforge/ui/command_palette_test.cljs
deleted file mode 100644
index 6b7d9b9..0000000
--- a/test/bareforge/ui/command_palette_test.cljs
+++ /dev/null
@@ -1,43 +0,0 @@
-(ns bareforge.ui.command-palette-test
-  (:require [cljs.test :refer [deftest is]]
-            [bareforge.ui.command-palette :as cp]))
-
-(def ^:private sample
-  [{:label "Save project"        :group "File"}
-   {:label "Open project…"       :group "File"}
-   {:label "New project"         :group "File"}
-   {:label "Toggle preview mode" :group "View"}
-   {:label "Toggle theme editor" :group "View"}
-   {:label "Insert x-button"     :group "Insert component"}
-   {:label "Insert x-card"       :group "Insert component"}])
-
-(deftest filter-empty-returns-input-as-vector
-  (is (= sample (cp/filter-commands sample "")))
-  (is (= sample (cp/filter-commands sample nil)))
-  (is (= sample (cp/filter-commands sample "   "))))
-
-(deftest filter-prefix-beats-substring
-  (let [out (cp/filter-commands sample "tog")]
-    (is (= "Toggle preview mode" (:label (first out)))
-        "prefix match scores 0; sorts before any substring hits")))
-
-(deftest filter-substring-match
-  (let [out (cp/filter-commands sample "card")]
-    (is (= 1 (count out)))
-    (is (= "Insert x-card" (:label (first out))))))
-
-(deftest filter-case-insensitive
-  (let [out (cp/filter-commands sample "INSERT")]
-    (is (= 2 (count out)))
-    (is (every? (fn [c] (= "Insert component" (:group c))) out))))
-
-(deftest filter-no-matches-returns-empty
-  (is (= [] (cp/filter-commands sample "no-such-thing")))
-  (is (vector? (cp/filter-commands sample "xyz"))))
-
-(deftest filter-ties-sort-by-label
-  (let [out (cp/filter-commands sample "project")]
-    (is (= ["New project" "Open project…" "Save project"]
-           (mapv :label out))
-        "all three score the same (substring at position 5/6/12);
-         labels sort alphabetically as the tiebreaker")))

From 675cd486960783d7ced08b29ce9b3f2326b74254 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 21:31:00 +0200
Subject: [PATCH 18/25] M3.2: keyboard nav in the Layers panel
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The layers list becomes a focus stop (tabindex=0). With it focused,
ArrowUp/Down walk the depth-first row order, ArrowLeft selects the
parent, ArrowRight enters the first child. Alt+Up / Alt+Down
reorder the selection within its parent slot via ops/move. The
keydown handler stopPropagation's so the document-level shortcut
layer doesn't also fire — an arrow on a free-placed selection no
longer simultaneously navigates and nudges.

The walk and reorder logic land as pure helpers nav-target /
reorder-target so a node test covers the boundaries (top of list,
root, leaf, edge of slot). Existing flatten-tree feeds them.

shortcut-info gains two rows under :navigation describing the
gesture so the cheat sheet picks them up automatically.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/bareforge/ui/layers.cljs       | 106 ++++++++++++++++++++++++++++-
 src/bareforge/ui/shortcuts.cljs    |   4 ++
 test/bareforge/ui/layers_test.cljs |  66 ++++++++++++++++++
 3 files changed, 175 insertions(+), 1 deletion(-)

diff --git a/src/bareforge/ui/layers.cljs b/src/bareforge/ui/layers.cljs
index 5f6b5b7..d4ff9a3 100644
--- a/src/bareforge/ui/layers.cljs
+++ b/src/bareforge/ui/layers.cljs
@@ -9,6 +9,7 @@
    here — step 7 is selection only."
   (:require [bareforge.dnd.drag :as drag]
             [bareforge.doc.model :as m]
+            [bareforge.doc.ops :as ops]
             [bareforge.meta.registry :as registry]
             [bareforge.render.canvas :as canvas]
             [bareforge.state :as state]
@@ -39,6 +40,55 @@
                           (m/slot-entries node))))]
     (walk (:root doc) 0 nil nil 0)))
 
+;; --- pure: keyboard nav --------------------------------------------------
+
+(defn- index-of [v x]
+  (loop [i 0]
+    (cond
+      (>= i (count v))   -1
+      (= (nth v i) x)    i
+      :else              (recur (inc i)))))
+
+(defn nav-target
+  "Pure: given the flattened `rows` and the canonical id of the
+   currently-selected layer, return the id to select for `direction`
+   ∈ #{:prev :next :parent :first-child}. Returns nil when the move
+   isn't valid (start of list, root with no parent, leaf with no
+   children, etc.). `:first-child` consults `doc` directly because
+   the row list doesn't carry full slot data."
+  [rows current-id doc direction]
+  (let [ids (mapv :id rows)
+        idx (index-of ids current-id)]
+    (case direction
+      :prev
+      (when (pos? idx) (nth ids (dec idx)))
+
+      :next
+      (when (and (>= idx 0) (< idx (dec (count ids))))
+        (nth ids (inc idx)))
+
+      :parent
+      (some #(when (= (:id %) current-id) (:parent-id %)) rows)
+
+      :first-child
+      (when-let [node (m/get-node doc current-id)]
+        (some-> (m/slot-entries node) first second first :id)))))
+
+(defn reorder-target
+  "Pure: compute the post-removal target index for an Alt-Up / Alt-Down
+   reorder of `current-id`. Returns `{:parent-id :slot :index}` or
+   nil when the move is out of bounds (already at the edge) or when
+   the node has no parent (root)."
+  [doc current-id direction]
+  (when-let [{:keys [parent-id slot index]} (m/parent-of doc current-id)]
+    (let [siblings (get-in (m/get-node doc parent-id) [:slots slot])
+          n        (count siblings)
+          new-idx  (case direction
+                     :up   (dec index)
+                     :down (inc index))]
+      (when (and (>= new-idx 0) (<= new-idx (dec n)))
+        {:parent-id parent-id :slot slot :index new-idx}))))
+
 ;; --- effectful -----------------------------------------------------------
 
 (defn- row-el [{:keys [id tag label depth]} selected?]
@@ -79,12 +129,65 @@
     (doseq [r rows]
       (.appendChild host-el (row-el r (contains? selected (:id r)))))))
 
+(defn- on-keydown!
+  "Tree-walk keyboard nav. Up/Down move to the previous / next visible
+   row, Left selects the parent, Right enters the first child. Alt-Up
+   and Alt-Down reorder the selection within its parent slot via
+   ops/move. Stops propagation so the document-level shortcut layer
+   doesn't also fire (e.g. an arrow key on a free-placed selection
+   wouldn't simultaneously nudge and navigate)."
+  [^js e]
+  (let [k       (.-key e)
+        meta?   (or (.-metaKey e) (.-ctrlKey e))
+        alt?    (.-altKey e)
+        nav     (cond
+                  (= k "ArrowUp")    (if alt? :reorder-up   :prev)
+                  (= k "ArrowDown")  (if alt? :reorder-down :next)
+                  (= k "ArrowLeft")  :parent
+                  (= k "ArrowRight") :first-child
+                  :else              nil)]
+    (when (and nav (not meta?))
+      (let [doc      (:document @state/app-state)
+            sel      (some-> (state/single-selected-id @state/app-state)
+                             canvas/canonical-node-id)]
+        (when sel
+          (case nav
+            :reorder-up
+            (when-let [{:keys [parent-id slot index]}
+                       (reorder-target doc sel :up)]
+              (.preventDefault e)
+              (.stopPropagation e)
+              (try
+                (let [doc' (ops/move doc sel parent-id slot index)]
+                  (state/commit! doc'))
+                (catch :default _ nil)))
+
+            :reorder-down
+            (when-let [{:keys [parent-id slot index]}
+                       (reorder-target doc sel :down)]
+              (.preventDefault e)
+              (.stopPropagation e)
+              (try
+                (let [doc' (ops/move doc sel parent-id slot index)]
+                  (state/commit! doc'))
+                (catch :default _ nil)))
+
+            ;; Plain arrow walks: select the resolved id and stop the
+            ;; event so it can't bubble up as a nudge or scroll.
+            (when-let [target (nav-target (flatten-tree doc) sel doc nav)]
+              (.preventDefault e)
+              (.stopPropagation e)
+              (state/select-one! target))))))))
+
 (defn create
   "Build the layers panel. Installs a single watcher that rebuilds the
    tree when :document or :selection changes. UI / theme / mode changes
    do not trigger a rebuild."
   []
-  (let [list-el (u/el :div {:class "layers-list"})
+  (let [;; tabindex makes the list itself a focus stop so keyboard nav
+        ;; can engage without having to click an individual row first.
+        list-el (u/el :div {:class "layers-list"
+                            :tabindex "0"})
         panel   (u/el :div {:id    "bareforge-layers"
                             :class "panel panel-layers"}
                       [(u/set-text! (u/el :div {:class "layers-label"}) "Layers")
@@ -92,6 +195,7 @@
     (render-tree! list-el
                   (:document @state/app-state)
                   (:selection @state/app-state))
+    (u/on! list-el :keydown on-keydown!)
     (add-watch state/app-state ::layers
                (fn [_ _ old-state new-state]
                  (when (or (not= (:document old-state)  (:document new-state))
diff --git a/src/bareforge/ui/shortcuts.cljs b/src/bareforge/ui/shortcuts.cljs
index a08e687..40f00d4 100644
--- a/src/bareforge/ui/shortcuts.cljs
+++ b/src/bareforge/ui/shortcuts.cljs
@@ -76,6 +76,10 @@
                           :label "Marquee extend selection"}
 
    {:category :navigation :keys "Esc"            :label "Deselect / exit text edit"}
+   {:category :navigation :keys "Arrow keys (in Layers)"
+                          :label "Walk the document tree"}
+   {:category :navigation :keys "Alt+Up / Alt+Down (in Layers)"
+                          :label "Reorder selection within parent slot"}
 
    {:category :file       :keys "Cmd+S"          :label "Save project"}
    {:category :file       :keys "Cmd+O"          :label "Open project"}
diff --git a/test/bareforge/ui/layers_test.cljs b/test/bareforge/ui/layers_test.cljs
index fd2c9e1..a2ad60c 100644
--- a/test/bareforge/ui/layers_test.cljs
+++ b/test/bareforge/ui/layers_test.cljs
@@ -47,3 +47,69 @@
         {d1 :doc} (ops/insert-new d0 "root" "default" 0 "x-theme")
         row (second (vec (layers/flatten-tree d1)))]
     (is (= "Theme" (:label row)))))
+
+;; --- keyboard nav (M3.2) ------------------------------------------------
+
+(defn- sample-doc
+  "root → [a, parent → [c, d], b]"
+  []
+  (let [d0 (m/empty-document)
+        {d1 :doc id-a :id} (ops/insert-new d0 "root" "default" 0 "x-a")
+        {d2 :doc id-p :id} (ops/insert-new d1 "root" "default" 1 "x-card")
+        {d3 :doc id-c :id} (ops/insert-new d2 id-p  "default" 0 "x-c")
+        {d4 :doc id-d :id} (ops/insert-new d3 id-p  "default" 1 "x-d")
+        {d5 :doc id-b :id} (ops/insert-new d4 "root" "default" 2 "x-b")]
+    {:doc d5 :ids {:a id-a :p id-p :c id-c :d id-d :b id-b}}))
+
+(deftest nav-target-prev-and-next
+  (let [{:keys [doc ids]} (sample-doc)
+        rows (vec (layers/flatten-tree doc))]
+    ;; depth-first order is root, a, p, c, d, b
+    (is (= "root"  (layers/nav-target rows (:a ids) doc :prev)))
+    (is (= (:a ids) (layers/nav-target rows (:p ids) doc :prev)))
+    (is (= (:p ids) (layers/nav-target rows (:c ids) doc :prev)))
+    (is (= (:c ids) (layers/nav-target rows (:d ids) doc :prev)))
+    (is (= (:d ids) (layers/nav-target rows (:b ids) doc :prev)))
+    (is (nil?       (layers/nav-target rows "root"   doc :prev))
+        "prev at the top of the list returns nil")
+
+    (is (= (:a ids) (layers/nav-target rows "root"   doc :next)))
+    (is (= (:p ids) (layers/nav-target rows (:a ids) doc :next)))
+    (is (= (:c ids) (layers/nav-target rows (:p ids) doc :next)))
+    (is (= (:b ids) (layers/nav-target rows (:d ids) doc :next)))
+    (is (nil?       (layers/nav-target rows (:b ids) doc :next))
+        "next at the end of the list returns nil")))
+
+(deftest nav-target-parent
+  (let [{:keys [doc ids]} (sample-doc)
+        rows (vec (layers/flatten-tree doc))]
+    (is (nil?       (layers/nav-target rows "root"   doc :parent)))
+    (is (= "root"   (layers/nav-target rows (:a ids) doc :parent)))
+    (is (= (:p ids) (layers/nav-target rows (:c ids) doc :parent)))
+    (is (= (:p ids) (layers/nav-target rows (:d ids) doc :parent)))))
+
+(deftest nav-target-first-child
+  (let [{:keys [doc ids]} (sample-doc)
+        rows (vec (layers/flatten-tree doc))]
+    (is (= (:a ids) (layers/nav-target rows "root"   doc :first-child)))
+    (is (= (:c ids) (layers/nav-target rows (:p ids) doc :first-child)))
+    (is (nil?       (layers/nav-target rows (:a ids) doc :first-child))
+        "leaf returns nil")))
+
+(deftest reorder-target-up
+  (let [{:keys [doc ids]} (sample-doc)]
+    (testing "p is at idx 1 in root/default; up goes to idx 0"
+      (is (= {:parent-id "root" :slot "default" :index 0}
+             (layers/reorder-target doc (:p ids) :up))))
+    (testing "a is at idx 0; up is out of bounds"
+      (is (nil? (layers/reorder-target doc (:a ids) :up))))
+    (testing "root has no parent"
+      (is (nil? (layers/reorder-target doc "root" :up))))))
+
+(deftest reorder-target-down
+  (let [{:keys [doc ids]} (sample-doc)]
+    (testing "a is at idx 0 in root/default; down goes to idx 1"
+      (is (= {:parent-id "root" :slot "default" :index 1}
+             (layers/reorder-target doc (:a ids) :down))))
+    (testing "b is at idx 2 (last); down is out of bounds"
+      (is (nil? (layers/reorder-target doc (:b ids) :down))))))

From 5f77b46b633f18de87c996dd369c3a59dde49bfe Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 21:40:49 +0200
Subject: [PATCH 19/25] Layers nav: Up/Down walk siblings, not depth-first

The first cut traversed the depth-first row list, so pressing Down
on a parent stepped into its first child instead of moving to the
next sibling. Re-reading the M3.2 plan calls for sibling-only
navigation: Up/Down stay inside the parent slot, ArrowRight is the
explicit "step into children" gesture, and ArrowLeft jumps to the
parent. That matches the standard tree-nav idiom (Finder, VS Code
explorer) and keeps each arrow direction's role distinct.

nav-target's :prev / :next branches now read parent-of and the
parent's slot vector instead of indexing into the flattened rows
list. Edge cases (already at slot boundary, root, leaf) return nil
so the keydown handler is a no-op there. Tests rewritten to assert
sibling boundaries and that Down on a parent does NOT enter its
children.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/bareforge/ui/layers.cljs       | 60 +++++++++++++++---------------
 test/bareforge/ui/layers_test.cljs | 59 +++++++++++++++--------------
 2 files changed, 60 insertions(+), 59 deletions(-)

diff --git a/src/bareforge/ui/layers.cljs b/src/bareforge/ui/layers.cljs
index d4ff9a3..d5b4c8e 100644
--- a/src/bareforge/ui/layers.cljs
+++ b/src/bareforge/ui/layers.cljs
@@ -42,37 +42,35 @@
 
 ;; --- pure: keyboard nav --------------------------------------------------
 
-(defn- index-of [v x]
-  (loop [i 0]
-    (cond
-      (>= i (count v))   -1
-      (= (nth v i) x)    i
-      :else              (recur (inc i)))))
-
 (defn nav-target
-  "Pure: given the flattened `rows` and the canonical id of the
-   currently-selected layer, return the id to select for `direction`
-   ∈ #{:prev :next :parent :first-child}. Returns nil when the move
-   isn't valid (start of list, root with no parent, leaf with no
-   children, etc.). `:first-child` consults `doc` directly because
-   the row list doesn't carry full slot data."
-  [rows current-id doc direction]
-  (let [ids (mapv :id rows)
-        idx (index-of ids current-id)]
-    (case direction
-      :prev
-      (when (pos? idx) (nth ids (dec idx)))
-
-      :next
-      (when (and (>= idx 0) (< idx (dec (count ids))))
-        (nth ids (inc idx)))
-
-      :parent
-      (some #(when (= (:id %) current-id) (:parent-id %)) rows)
-
-      :first-child
-      (when-let [node (m/get-node doc current-id)]
-        (some-> (m/slot-entries node) first second first :id)))))
+  "Pure: given the canonical id of the currently-selected layer,
+   return the id to select for `direction` ∈ #{:prev :next :parent
+   :first-child}. Up / Down walk siblings within the same parent
+   slot — the natural tree-nav gesture, distinct from depth-first
+   list traversal — so stepping into the children is reserved for
+   ArrowRight. Returns nil when the move isn't valid (already at
+   the edge of a slot, root with no parent, leaf with no children)."
+  [current-id doc direction]
+  (case direction
+    :prev
+    (when-let [{:keys [parent-id slot index]} (m/parent-of doc current-id)]
+      (when (pos? index)
+        (let [siblings (get-in (m/get-node doc parent-id) [:slots slot])]
+          (:id (nth siblings (dec index))))))
+
+    :next
+    (when-let [{:keys [parent-id slot index]} (m/parent-of doc current-id)]
+      (let [siblings (get-in (m/get-node doc parent-id) [:slots slot])
+            n        (count siblings)]
+        (when (< index (dec n))
+          (:id (nth siblings (inc index))))))
+
+    :parent
+    (:parent-id (m/parent-of doc current-id))
+
+    :first-child
+    (when-let [node (m/get-node doc current-id)]
+      (some-> (m/slot-entries node) first second first :id))))
 
 (defn reorder-target
   "Pure: compute the post-removal target index for an Alt-Up / Alt-Down
@@ -174,7 +172,7 @@
 
             ;; Plain arrow walks: select the resolved id and stop the
             ;; event so it can't bubble up as a nudge or scroll.
-            (when-let [target (nav-target (flatten-tree doc) sel doc nav)]
+            (when-let [target (nav-target sel doc nav)]
               (.preventDefault e)
               (.stopPropagation e)
               (state/select-one! target))))))))
diff --git a/test/bareforge/ui/layers_test.cljs b/test/bareforge/ui/layers_test.cljs
index a2ad60c..01a3082 100644
--- a/test/bareforge/ui/layers_test.cljs
+++ b/test/bareforge/ui/layers_test.cljs
@@ -61,39 +61,42 @@
         {d5 :doc id-b :id} (ops/insert-new d4 "root" "default" 2 "x-b")]
     {:doc d5 :ids {:a id-a :p id-p :c id-c :d id-d :b id-b}}))
 
-(deftest nav-target-prev-and-next
-  (let [{:keys [doc ids]} (sample-doc)
-        rows (vec (layers/flatten-tree doc))]
-    ;; depth-first order is root, a, p, c, d, b
-    (is (= "root"  (layers/nav-target rows (:a ids) doc :prev)))
-    (is (= (:a ids) (layers/nav-target rows (:p ids) doc :prev)))
-    (is (= (:p ids) (layers/nav-target rows (:c ids) doc :prev)))
-    (is (= (:c ids) (layers/nav-target rows (:d ids) doc :prev)))
-    (is (= (:d ids) (layers/nav-target rows (:b ids) doc :prev)))
-    (is (nil?       (layers/nav-target rows "root"   doc :prev))
-        "prev at the top of the list returns nil")
+(deftest nav-target-prev-and-next-walks-siblings
+  (let [{:keys [doc ids]} (sample-doc)]
+    (testing "Up/Down stay within the same parent slot"
+      (is (= (:a ids) (layers/nav-target (:p ids) doc :prev))
+          "p (idx 1 of root/default) → a (idx 0)")
+      (is (= (:p ids) (layers/nav-target (:b ids) doc :prev))
+          "b (idx 2 of root/default) → p (idx 1)")
+      (is (= (:c ids) (layers/nav-target (:d ids) doc :prev))
+          "d → c inside the card's default slot")
+
+      (is (= (:p ids) (layers/nav-target (:a ids) doc :next)))
+      (is (= (:b ids) (layers/nav-target (:p ids) doc :next)))
+      (is (= (:d ids) (layers/nav-target (:c ids) doc :next))))
 
-    (is (= (:a ids) (layers/nav-target rows "root"   doc :next)))
-    (is (= (:p ids) (layers/nav-target rows (:a ids) doc :next)))
-    (is (= (:c ids) (layers/nav-target rows (:p ids) doc :next)))
-    (is (= (:b ids) (layers/nav-target rows (:d ids) doc :next)))
-    (is (nil?       (layers/nav-target rows (:b ids) doc :next))
-        "next at the end of the list returns nil")))
+    (testing "edges of a slot return nil — Down on a parent does NOT
+              step into its children (that's what Right is for)"
+      (is (nil? (layers/nav-target (:a ids) doc :prev)))
+      (is (nil? (layers/nav-target (:b ids) doc :next)))
+      (is (nil? (layers/nav-target (:c ids) doc :prev)))
+      (is (nil? (layers/nav-target (:d ids) doc :next)))
+      (is (nil? (layers/nav-target "root"   doc :prev))
+          "root has no siblings")
+      (is (nil? (layers/nav-target "root"   doc :next))))))
 
 (deftest nav-target-parent
-  (let [{:keys [doc ids]} (sample-doc)
-        rows (vec (layers/flatten-tree doc))]
-    (is (nil?       (layers/nav-target rows "root"   doc :parent)))
-    (is (= "root"   (layers/nav-target rows (:a ids) doc :parent)))
-    (is (= (:p ids) (layers/nav-target rows (:c ids) doc :parent)))
-    (is (= (:p ids) (layers/nav-target rows (:d ids) doc :parent)))))
+  (let [{:keys [doc ids]} (sample-doc)]
+    (is (nil?       (layers/nav-target "root"   doc :parent)))
+    (is (= "root"   (layers/nav-target (:a ids) doc :parent)))
+    (is (= (:p ids) (layers/nav-target (:c ids) doc :parent)))
+    (is (= (:p ids) (layers/nav-target (:d ids) doc :parent)))))
 
 (deftest nav-target-first-child
-  (let [{:keys [doc ids]} (sample-doc)
-        rows (vec (layers/flatten-tree doc))]
-    (is (= (:a ids) (layers/nav-target rows "root"   doc :first-child)))
-    (is (= (:c ids) (layers/nav-target rows (:p ids) doc :first-child)))
-    (is (nil?       (layers/nav-target rows (:a ids) doc :first-child))
+  (let [{:keys [doc ids]} (sample-doc)]
+    (is (= (:a ids) (layers/nav-target "root"   doc :first-child)))
+    (is (= (:c ids) (layers/nav-target (:p ids) doc :first-child)))
+    (is (nil?       (layers/nav-target (:a ids) doc :first-child))
         "leaf returns nil")))
 
 (deftest reorder-target-up

From d0104f232251a831961679e88a863a73108b8980 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 21:46:48 +0200
Subject: [PATCH 20/25] M3.4: inline component patterns in the palette
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

bareforge.meta.patterns is a per-tag map of named pre-styled
configurations (`{:id :label :overrides}`). Each :overrides map
matches the shape palette/seed-for-tag returns, so a pattern lands
in the document by passing it straight to ops/insert-new — no new
plumbing in ops or the reconciler.

Coverage starts with the most-reached-for tags: x-button gets
primary/secondary/ghost/danger/loading; x-typography spans
h1/h2/h3/body/caption/code; x-alert and x-badge cover their
type/variant axes; x-card carries elevation + interactive variants;
x-grid offers 2/3/4-col and sidebar layouts; x-divider, x-switch,
x-checkbox, x-chip round out the seed set. A coverage warning
prints uncovered tags in test output without failing — gaps stay
visible without blocking BareDOM bumps.

Palette tiles for tags with patterns grow a `▾` caret that toggles
an inline flyout of pattern chips. Clicking a chip inserts the
pattern's overrides via the new 2-arity insert-at-selection!.
Pointerdown on caret/chip stopPropagation's so the surrounding
tile's drag-arm doesn't compete with the click.

The 1-arity insert-at-selection! (used by the dnd palette tap path
and the Cmd-K command palette) is unchanged, so no caller migration
is needed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 public/index.html                      |  38 +++++++
 src/bareforge/meta/patterns.cljs       | 144 +++++++++++++++++++++++++
 src/bareforge/ui/palette.cljs          |  90 +++++++++++++---
 test/bareforge/meta/patterns_test.cljs |  47 ++++++++
 4 files changed, 304 insertions(+), 15 deletions(-)
 create mode 100644 src/bareforge/meta/patterns.cljs
 create mode 100644 test/bareforge/meta/patterns_test.cljs

diff --git a/public/index.html b/public/index.html
index 80ccf40..3e47ce9 100644
--- a/public/index.html
+++ b/public/index.html
@@ -264,12 +264,50 @@
     .palette-item:active {
       background: var(--x-color-surface-active, rgba(127, 127, 127, 0.2));
     }
+    .palette-item-header {
+      display: grid;
+      grid-template-columns: 1fr auto auto;
+      column-gap: 8px;
+      align-items: baseline;
+    }
     .palette-item-label { font-size: 13px; font-weight: 500; }
     .palette-item-tag {
       font-size: 11px;
       font-family: ui-monospace, SFMono-Regular, Menlo, monospace;
       color: var(--x-color-text-muted, rgba(127, 127, 127, 0.7));
     }
+    /* Pattern caret + inline flyout (M3.4). The caret rotates when
+       open so the affordance reads as expand/collapse. */
+    .palette-item-caret {
+      font-size: 11px;
+      color: var(--x-color-text-muted, rgba(127, 127, 127, 0.7));
+      cursor: pointer;
+      padding: 0 4px;
+      user-select: none;
+      transition: transform 120ms ease;
+    }
+    .palette-item-caret[data-open] { transform: rotate(180deg); }
+    .palette-patterns {
+      display: flex;
+      flex-wrap: wrap;
+      gap: 4px;
+      margin-top: 6px;
+    }
+    .palette-patterns[data-hidden] { display: none; }
+    .palette-pattern {
+      font-size: 11px;
+      padding: 3px 8px;
+      border-radius: 999px;
+      background: var(--x-color-surface, rgba(127, 127, 127, 0.1));
+      color: var(--x-color-text);
+      border: 1px solid var(--x-color-border, rgba(127, 127, 127, 0.2));
+      cursor: pointer;
+      user-select: none;
+    }
+    .palette-pattern:hover {
+      background: var(--x-color-surface-hover, rgba(127, 127, 127, 0.18));
+      border-color: var(--x-color-primary);
+    }
     .palette-empty {
       font-size: 12px;
       color: var(--x-color-text-muted, rgba(127, 127, 127, 0.7));
diff --git a/src/bareforge/meta/patterns.cljs b/src/bareforge/meta/patterns.cljs
new file mode 100644
index 0000000..f484076
--- /dev/null
+++ b/src/bareforge/meta/patterns.cljs
@@ -0,0 +1,144 @@
+(ns bareforge.meta.patterns
+  "Per-tag named pre-styled configurations exposed by the palette as
+   one-click insert variants. Each pattern's `:overrides` map matches
+   the shape `palette/seed-for-tag` returns — passed straight into
+   `doc.ops/insert-new` as the overrides arg, so a pattern lands
+   pre-populated with its own attrs / props / text / inner-html.
+
+   Patterns are pure data: no rendering changes, no special DOM
+   plumbing. The palette tile checks `(patterns-for tag)` and
+   surfaces the variants when non-empty.
+
+   Coverage starts narrow (the most-reached-for components). The
+   companion test in `meta/patterns_test.cljs` warns — not fails —
+   when a registered tag has no patterns, so gaps stay visible
+   without blocking new tag bumps.")
+
+(def ^:private patterns-by-tag
+  "Map from tag → ordered vector of `{:id :label :overrides}`. Order
+   is display order. `:id` is a stable keyword for tests / config;
+   `:label` is the human-readable name shown on the palette flyout."
+  {"x-button"
+   [{:id :primary
+     :label "Primary"
+     :overrides {:text "Primary"
+                 :attrs {"label" "Primary" "variant" "primary"}}}
+    {:id :secondary
+     :label "Secondary"
+     :overrides {:text "Secondary"
+                 :attrs {"label" "Secondary" "variant" "secondary"}}}
+    {:id :ghost
+     :label "Ghost"
+     :overrides {:text "Ghost"
+                 :attrs {"label" "Ghost" "variant" "ghost"}}}
+    {:id :danger
+     :label "Danger"
+     :overrides {:text "Delete"
+                 :attrs {"label" "Delete" "variant" "danger"}}}
+    {:id :loading
+     :label "Loading"
+     :overrides {:text "Loading…"
+                 :attrs {"label" "Loading…" "variant" "primary"}
+                 :props {:loading true}}}]
+
+   "x-typography"
+   [{:id :h1   :label "Heading 1"
+     :overrides {:text "Heading 1" :attrs {"variant" "h1"}}}
+    {:id :h2   :label "Heading 2"
+     :overrides {:text "Heading 2" :attrs {"variant" "h2"}}}
+    {:id :h3   :label "Heading 3"
+     :overrides {:text "Heading 3" :attrs {"variant" "h3"}}}
+    {:id :body :label "Body"
+     :overrides {:text "Body text"   :attrs {"variant" "body1"}}}
+    {:id :caption :label "Caption"
+     :overrides {:text "Caption"     :attrs {"variant" "caption"}}}
+    {:id :code :label "Code"
+     :overrides {:text "code()"      :attrs {"variant" "code"}}}]
+
+   "x-alert"
+   [{:id :info    :label "Info"
+     :overrides {:attrs {"text" "Information message" "type" "info"}}}
+    {:id :success :label "Success"
+     :overrides {:attrs {"text" "Operation succeeded" "type" "success"}}}
+    {:id :warning :label "Warning"
+     :overrides {:attrs {"text" "Heads up — please review" "type" "warning"}}}
+    {:id :error   :label "Error"
+     :overrides {:attrs {"text" "Something went wrong" "type" "error"}}}
+    {:id :dismissible :label "Dismissible"
+     :overrides {:attrs {"text" "Click × to dismiss" "type" "info"
+                         "dismissible" ""}}}]
+
+   "x-badge"
+   [{:id :neutral :label "Neutral"
+     :overrides {:attrs {"text" "Neutral"  "variant" "neutral"}}}
+    {:id :info    :label "Info"
+     :overrides {:attrs {"text" "Info"     "variant" "info"}}}
+    {:id :success :label "Success"
+     :overrides {:attrs {"text" "Success"  "variant" "success"}}}
+    {:id :warning :label "Warning"
+     :overrides {:attrs {"text" "Warning"  "variant" "warning"}}}
+    {:id :error   :label "Error"
+     :overrides {:attrs {"text" "Error"    "variant" "error"}}}
+    {:id :dot     :label "Dot indicator"
+     :overrides {:attrs {"variant" "info"  "dot" ""}}}]
+
+   "x-chip"
+   [{:id :default    :label "Default"
+     :overrides {:attrs {"label" "Tag"}}}
+    {:id :removable  :label "Removable"
+     :overrides {:attrs {"label" "Removable" "removable" ""}}}
+    {:id :disabled   :label "Disabled"
+     :overrides {:attrs {"label" "Disabled" "disabled" ""}}}]
+
+   "x-card"
+   [{:id :elevated   :label "Elevated"
+     :overrides {:attrs {"variant" "elevated" "padding" "md" "radius" "lg"}}}
+    {:id :outlined   :label "Outlined"
+     :overrides {:attrs {"variant" "outlined" "padding" "md" "radius" "lg"}}}
+    {:id :filled     :label "Filled"
+     :overrides {:attrs {"variant" "filled"   "padding" "md" "radius" "lg"}}}
+    {:id :interactive :label "Interactive"
+     :overrides {:attrs {"variant" "elevated" "padding" "md" "radius" "lg"
+                         "interactive" ""}}}]
+
+   "x-divider"
+   [{:id :horizontal :label "Horizontal"
+     :overrides {}}
+    {:id :vertical   :label "Vertical"
+     :overrides {:attrs {"orientation" "vertical"}}}]
+
+   "x-switch"
+   [{:id :off :label "Off"
+     :overrides {}}
+    {:id :on  :label "On (checked)"
+     :overrides {:attrs {"checked" ""}}}]
+
+   "x-checkbox"
+   [{:id :off :label "Off"
+     :overrides {}}
+    {:id :on  :label "On (checked)"
+     :overrides {:attrs {"checked" ""}}}]
+
+   "x-grid"
+   [{:id :two-col   :label "2 columns"
+     :overrides {:attrs {"columns" "repeat(2, 1fr)" "gap" "16px"}}}
+    {:id :three-col :label "3 columns"
+     :overrides {:attrs {"columns" "repeat(3, 1fr)" "gap" "16px"}}}
+    {:id :four-col  :label "4 columns"
+     :overrides {:attrs {"columns" "repeat(4, 1fr)" "gap" "16px"}}}
+    {:id :sidebar   :label "Sidebar + body"
+     :overrides {:attrs {"columns" "240px 1fr" "gap" "24px"}}}]})
+
+(defn patterns-for
+  "Pure: the named patterns vector for `tag`, or nil when no patterns
+   are registered. Callers branch on truthy / falsy to decide whether
+   to render the flyout affordance on a palette tile."
+  [tag]
+  (get patterns-by-tag tag))
+
+(defn covered-tags
+  "Pure: the set of tags that currently have at least one pattern.
+   Used by the meta-coverage test to print a warning for tags without
+   patterns."
+  []
+  (set (keys patterns-by-tag)))
diff --git a/src/bareforge/ui/palette.cljs b/src/bareforge/ui/palette.cljs
index d74915e..f3d2cfe 100644
--- a/src/bareforge/ui/palette.cljs
+++ b/src/bareforge/ui/palette.cljs
@@ -9,6 +9,7 @@
    `state/commit!`."
   (:require [bareforge.doc.model :as m]
             [bareforge.doc.ops :as ops]
+            [bareforge.meta.patterns :as patterns]
             [bareforge.meta.registry :as registry]
             [bareforge.state :as state]
             [bareforge.util.dom :as u]
@@ -152,18 +153,45 @@
       (append-to-root doc))))
 
 (defn insert-at-selection!
-  "Public tap-to-insert helper shared by the palette's armed-tap path
-   and the dnd layer. Reads the current selection from the state atom,
-   computes an insertion target, inserts, commits, and selects the new
-   node. Multi-select degrades to root-append (no single anchor)."
-  [tag]
-  (let [doc       (:document @state/app-state)
-        sel-id    (state/single-selected-id @state/app-state)
-        {:keys [parent-id slot index]} (insertion-target doc sel-id)
-        {doc' :doc new-id :id}
-        (ops/insert-new doc parent-id slot index tag (seed-for-tag tag))]
-    (state/commit! doc')
-    (state/select-one! new-id)))
+  "Public tap-to-insert helper shared by the palette's armed-tap path,
+   the dnd layer, and the M3.4 patterns flyout. Reads the current
+   selection from the state atom, computes an insertion target,
+   inserts, commits, and selects the new node. Multi-select degrades
+   to root-append (no single anchor).
+
+   The 2-arity form lets callers override the seeded attrs / props /
+   text — used by the patterns flyout to insert a pre-styled variant
+   instead of the bare default. When `overrides` is nil the seed
+   from `seed-for-tag` is used."
+  ([tag] (insert-at-selection! tag nil))
+  ([tag overrides]
+   (let [doc       (:document @state/app-state)
+         sel-id    (state/single-selected-id @state/app-state)
+         {:keys [parent-id slot index]} (insertion-target doc sel-id)
+         seed      (or overrides (seed-for-tag tag))
+         {doc' :doc new-id :id}
+         (ops/insert-new doc parent-id slot index tag seed)]
+     (state/commit! doc')
+     (state/select-one! new-id))))
+
+(defn- pattern-button
+  "Inline button inside a palette tile's pattern flyout. Click inserts
+   the pattern's pre-styled overrides via `insert-at-selection!`.
+   Pointerdown on the button stops propagation so the surrounding
+   palette tile's drag-arm doesn't engage on a pattern click."
+  [tag {:keys [label overrides]}]
+  (let [btn (u/el :div {:class "palette-pattern" :role "button"})]
+    (u/set-text! btn label)
+    (u/on! btn :pointerdown (fn [^js e] (.stopPropagation e)))
+    (u/on! btn :click
+           (fn [^js e]
+             (.stopPropagation e)
+             (insert-at-selection! tag overrides)))
+    btn))
+
+(defn- patterns-flyout [tag pats]
+  (u/el :div {:class "palette-patterns" :data-hidden ""}
+        (mapv #(pattern-button tag %) pats)))
 
 (defn- palette-item
   "Palette items have no :click handler any more — taps and drags both
@@ -173,12 +201,44 @@
    click-fallthrough race where the browser's click event could fire
    after a drag ended over another palette item.
 
+   When the tag has registered patterns (see `meta/patterns.cljs`),
+   the tile carries a `▾` caret that toggles an inline flyout of
+   pre-styled variants. Clicking a variant inserts it with its
+   overrides instead of the bare seed.
+
    `on-drag-start` is required when the drag layer is wired up — it
    must be non-nil in normal mounts."
   [{:keys [tag label]} on-drag-start]
-  (let [node (u/el :div {:class "palette-item"}
-                   [(u/set-text! (u/el :div {:class "palette-item-label"}) label)
-                    (u/set-text! (u/el :div {:class "palette-item-tag"}) tag)])]
+  (let [pats     (patterns/patterns-for tag)
+        label-el (u/set-text! (u/el :div {:class "palette-item-label"}) label)
+        tag-el   (u/set-text! (u/el :div {:class "palette-item-tag"}) tag)
+        header   (u/el :div {:class "palette-item-header"})
+        node     (u/el :div {:class "palette-item"})]
+    (.appendChild header label-el)
+    (.appendChild header tag-el)
+    (when pats
+      (let [caret  (-> (u/el :div {:class "palette-item-caret"
+                                   :title "Show patterns"
+                                   :role  "button"})
+                       (u/set-text! "▾"))
+            flyout (patterns-flyout tag pats)]
+        (.appendChild header caret)
+        (.appendChild node header)
+        (.appendChild node flyout)
+        ;; Caret swallows pointerdown so the palette tile's drag-arm
+        ;; (registered below) doesn't engage on the toggle gesture.
+        (u/on! caret :pointerdown (fn [^js e] (.stopPropagation e)))
+        (u/on! caret :click
+               (fn [^js e]
+                 (.stopPropagation e)
+                 (.preventDefault e)
+                 (if (.hasAttribute flyout "data-hidden")
+                   (do (.removeAttribute flyout "data-hidden")
+                       (.setAttribute caret "data-open" ""))
+                   (do (.setAttribute flyout "data-hidden" "")
+                       (.removeAttribute caret "data-open")))))))
+    (when (nil? pats)
+      (.appendChild node header))
     (when on-drag-start
       (u/on! node :pointerdown (fn [^js e] (on-drag-start e tag))))
     node))
diff --git a/test/bareforge/meta/patterns_test.cljs b/test/bareforge/meta/patterns_test.cljs
new file mode 100644
index 0000000..a7382fe
--- /dev/null
+++ b/test/bareforge/meta/patterns_test.cljs
@@ -0,0 +1,47 @@
+(ns bareforge.meta.patterns-test
+  (:require [cljs.test :refer [deftest is testing]]
+            [clojure.set :as set]
+            [clojure.string :as str]
+            [bareforge.meta.patterns :as patterns]
+            [bareforge.meta.registry :as registry]))
+
+(deftest patterns-for-known-tag
+  (let [pats (patterns/patterns-for "x-button")]
+    (is (some? pats))
+    (is (every? :id    pats))
+    (is (every? :label pats))
+    (testing "every entry carries an :overrides map (possibly empty)"
+      (is (every? #(map? (:overrides %)) pats)))))
+
+(deftest patterns-for-unknown-tag-is-nil
+  (is (nil? (patterns/patterns-for "x-no-such-thing"))))
+
+(deftest pattern-ids-unique-per-tag
+  (doseq [[tag pats] (group-by first
+                               (mapcat (fn [t]
+                                         (when-let [pats (patterns/patterns-for t)]
+                                           (mapv (fn [p] [t (:id p)]) pats)))
+                                       (patterns/covered-tags)))]
+    (let [ids (mapv second pats)]
+      (is (= (count ids) (count (distinct ids)))
+          (str "duplicate pattern ids on tag " tag)))))
+
+(deftest covered-tags-are-registered
+  (let [registered (set (registry/all-tags))]
+    (doseq [tag (patterns/covered-tags)]
+      (is (contains? registered tag)
+          (str tag " has patterns but isn't a registered BareDOM tag")))))
+
+(deftest coverage-warning
+  ;; This test never fails — it just prints uncovered tags so a fresh
+  ;; PR carrying a new BareDOM bump shows the gap in CI logs.
+  (let [registered (set (registry/all-tags))
+        covered    (patterns/covered-tags)
+        uncovered  (sort (set/difference registered covered))]
+    (when (seq uncovered)
+      (.warn js/console
+             (str "[patterns] " (count uncovered)
+                  " tags have no patterns yet: "
+                  (str/join ", " (take 12 uncovered))
+                  (when (> (count uncovered) 12) "…"))))
+    (is true)))

From bfdddf0569a89b07e67888bd339b6c4676978652 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 21:54:31 +0200
Subject: [PATCH 21/25] M3.6: per-tag empty-slot hints
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

bareforge.meta.hints carries a curated string for each container
that's specific enough to suggest what belongs inside ("Drop nav
links / actions" inside an empty x-navbar, "Drop tiles into the
grid" inside x-grid, "Drop x-tab here" inside x-tabs, etc.). Tags
without a curated hint fall back to the existing generic
`<tag>  (empty)` placeholder.

The canvas reconciler stamps each container's chosen hint onto a
`data-bareforge-hint` attribute on creation. A new CSS rule
`[data-bareforge-container][data-bareforge-hint]:empty::before`
overrides the generic placeholder when the attribute is present —
specificity wins, no rule duplication. Drag-time slot strips and
preview-mode invisibility both fall out of the existing rules.

While here, drop x-flex from the wrap whitelist (shortcuts +
command palette) — BareDOM 2.4 doesn't ship that tag, so the
Cmd-Shift-G prompt and palette would silently insert a
non-rendering element. x-navbar takes its place as the fourth
wrap target.

Coverage test asserts every hinted tag is registered and that
hint strings stay under the 28-char footprint cap.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 public/index.html                     |  7 ++++
 src/bareforge/meta/hints.cljs         | 47 +++++++++++++++++++++++++++
 src/bareforge/render/canvas.cljs      |  9 ++++-
 src/bareforge/ui/command_palette.cljs |  2 +-
 src/bareforge/ui/shortcuts.cljs       |  4 +--
 test/bareforge/meta/hints_test.cljs   | 24 ++++++++++++++
 6 files changed, 89 insertions(+), 4 deletions(-)
 create mode 100644 src/bareforge/meta/hints.cljs
 create mode 100644 test/bareforge/meta/hints_test.cljs

diff --git a/public/index.html b/public/index.html
index 3e47ce9..c955ba2 100644
--- a/public/index.html
+++ b/public/index.html
@@ -764,6 +764,13 @@
       pointer-events: none;
       user-select: none;
     }
+    /* Per-tag drop hint (M3.6) — overrides the generic placeholder
+       when the canvas reconciler stamped a `data-bareforge-hint`
+       attribute (see meta/hints.cljs for the data table). The more
+       specific selector wins over the generic rule above. */
+    .canvas-host [data-bareforge-container][data-bareforge-hint]:empty::before {
+      content: attr(data-bareforge-hint);
+    }
     /* Containers that host an absolute :background child get this
        class from the reconciler so they form a positioned ancestor
        without touching their own inline style. `isolation: isolate`
diff --git a/src/bareforge/meta/hints.cljs b/src/bareforge/meta/hints.cljs
new file mode 100644
index 0000000..4daf5c7
--- /dev/null
+++ b/src/bareforge/meta/hints.cljs
@@ -0,0 +1,47 @@
+(ns bareforge.meta.hints
+  "Per-tag hint strings shown inside empty containers in edit mode.
+   Pure data: the canvas reconciler reads `hint-for` and stamps the
+   chosen text onto each container's `data-bareforge-hint` attribute
+   on creation, and the existing empty-state CSS rule renders it via
+   `::before`. Tags without a custom hint fall back to the generic
+   `<tag>  (empty)` style.
+
+   Hints are intentionally short (≤ 28 chars) so they fit inside the
+   small dashed empty-state footprint without wrapping. Coverage is
+   bounded by `meta.hints-test`'s assertion that every hinted tag
+   exists in the registry — bumps that rename a tag will fail loudly
+   instead of silently surfacing the wrong hint.")
+
+(def ^:private hints
+  {"x-card"        "Drop heading or content"
+   "x-grid"        "Drop tiles into the grid"
+   "x-container"   "Drop components here"
+   "x-navbar"      "Drop nav links / actions"
+   "x-modal"       "Drop modal content here"
+   "x-popover"     "Drop popover content"
+   "x-drawer"      "Drop drawer content"
+   "x-tabs"        "Drop an x-tab here"
+   "x-tab"         "Drop tab content"
+   "x-bento-grid"  "Drop x-bento-item here"
+   "x-bento-item"  "Drop bento content"
+   "x-form-field"  "Drop a form input"
+   "x-table"       "Drop x-table-row here"
+   "x-table-row"   "Drop x-table-cell here"
+   "x-sidebar"     "Drop sidebar content"
+   "x-menu"        "Drop x-menu-item here"
+   "x-stepper"     "Drop step content"
+   "x-carousel"    "Drop slides here"
+   "x-collapse"    "Drop collapsible content"})
+
+(defn hint-for
+  "Pure: return the hint string for `tag`, or nil when no custom
+   hint is registered. Callers use the nil sentinel to fall back to
+   the generic `(empty)` affordance."
+  [tag]
+  (get hints tag))
+
+(defn covered-tags
+  "Pure: the set of tags that currently have a custom empty-state
+   hint. Used by the meta-coverage test."
+  []
+  (set (keys hints)))
diff --git a/src/bareforge/render/canvas.cljs b/src/bareforge/render/canvas.cljs
index 68662ac..954494b 100644
--- a/src/bareforge/render/canvas.cljs
+++ b/src/bareforge/render/canvas.cljs
@@ -6,6 +6,7 @@
    keeping with the effectful-zone rules in CLAUDE.md."
   (:require [bareforge.doc.actions :as actions]
             [bareforge.doc.model :as m]
+            [bareforge.meta.hints :as hints]
             [bareforge.meta.registry :as registry]
             [bareforge.render.reconcile :as rec]
             [bareforge.state :as state]
@@ -167,7 +168,13 @@
         (.setAttribute el "data-bareforge-id"  id)
         (.setAttribute el "data-bareforge-tag" (:tag node))
         (when (registry/container? (:tag node))
-          (.setAttribute el "data-bareforge-container" ""))
+          (.setAttribute el "data-bareforge-container" "")
+          ;; Empty-state CSS reads `data-bareforge-hint` to show a
+          ;; per-tag prompt ("Drop nav links / actions" inside an
+          ;; empty x-navbar etc.). Tags without a curated hint fall
+          ;; back to the generic `<tag>  (empty)` style.
+          (when-let [hint (hints/hint-for (:tag node))]
+            (.setAttribute el "data-bareforge-hint" hint)))
         (rec/apply-attrs! el (rec/attr-diff {} (:attrs node)))
         (rec/apply-props! el (rec/prop-diff {} (:props node)))
         (when-not raw-html?
diff --git a/src/bareforge/ui/command_palette.cljs b/src/bareforge/ui/command_palette.cljs
index 0359d2c..b0b4fd4 100644
--- a/src/bareforge/ui/command_palette.cljs
+++ b/src/bareforge/ui/command_palette.cljs
@@ -50,7 +50,7 @@
   "Wrap-in tags offered by the palette — must be a subset of
    shortcuts/wrap-tag-whitelist so the keyboard prompt and the
    palette accept the same set."
-  ["x-container" "x-grid" "x-card" "x-flex"])
+  ["x-container" "x-grid" "x-card" "x-navbar"])
 
 (defn- wrap-commands []
   (mapv (fn [tag]
diff --git a/src/bareforge/ui/shortcuts.cljs b/src/bareforge/ui/shortcuts.cljs
index 40f00d4..63996d9 100644
--- a/src/bareforge/ui/shortcuts.cljs
+++ b/src/bareforge/ui/shortcuts.cljs
@@ -313,7 +313,7 @@
    multiple children. Adding a new tag here requires it to be a real
    container in the registry, otherwise wrap-many's reparent step
    would fail."
-  #{"x-container" "x-grid" "x-card" "x-flex"})
+  #{"x-container" "x-grid" "x-card" "x-navbar"})
 
 (defn- selected-doc-ids
   "Read the current selection, canonicalise each id, dedupe, and drop
@@ -395,7 +395,7 @@
    types something off-list."
   []
   (let [input (js/window.prompt
-                "Wrap selection in: x-container, x-grid, x-card, x-flex"
+                "Wrap selection in: x-container, x-grid, x-card, x-navbar"
                 "x-container")]
     (when (and (string? input)
                (contains? wrap-tag-whitelist input))
diff --git a/test/bareforge/meta/hints_test.cljs b/test/bareforge/meta/hints_test.cljs
new file mode 100644
index 0000000..f917b0c
--- /dev/null
+++ b/test/bareforge/meta/hints_test.cljs
@@ -0,0 +1,24 @@
+(ns bareforge.meta.hints-test
+  (:require [cljs.test :refer [deftest is testing]]
+            [bareforge.meta.hints :as hints]
+            [bareforge.meta.registry :as registry]))
+
+(deftest hint-for-known-tag
+  (is (string? (hints/hint-for "x-card"))))
+
+(deftest hint-for-unknown-tag-is-nil
+  (is (nil? (hints/hint-for "x-no-such-thing"))))
+
+(deftest covered-tags-are-registered
+  (let [registered (set (registry/all-tags))]
+    (doseq [tag (hints/covered-tags)]
+      (is (contains? registered tag)
+          (str tag " has a hint but isn't a registered BareDOM tag")))))
+
+(deftest hints-fit-the-empty-footprint
+  (testing "every hint stays under 28 chars so it fits the dashed
+            empty-state region without wrapping"
+    (doseq [tag (hints/covered-tags)]
+      (let [h (hints/hint-for tag)]
+        (is (<= (count h) 28)
+            (str "hint for " tag " is " (count h) " chars: " h))))))

From 7d65f4f462635e753c4a71241ddbaaac9fecdb7f Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 22:07:58 +0200
Subject: [PATCH 22/25] README: document the new authoring shortcuts
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Adds an "Authoring shortcuts" section between Features and Fields
& bindings, grouping the new editor surfaces by user concern
(multi-select & bulk ops / inspector ergonomics / discoverability)
rather than by milestone. Each bullet leads with the gesture or
keystroke so a reader scanning for "how do I…" finds it fast.

Updates the Status line's test count from 486 to 571 to reflect
the gates after this branch's work.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 27de34f..2b5c702 100644
--- a/README.md
+++ b/README.md
@@ -78,6 +78,66 @@ I wondered if I could automate some of that and with that the idea for Bareforge
 - **Escape to deselect** + full keyboard shortcuts (Cmd-Z / Cmd-Shift-Z /
   Delete / arrow-key nudge)
 
+## Authoring shortcuts
+
+A set of power-user gestures that make daily editing faster. Every
+keyboard shortcut lives in a press-`?` cheat sheet; every action is
+reachable through a Cmd-K command palette.
+
+### Multi-select & bulk ops
+
+- **Shift-click** any node (canvas or Layers panel) to extend the
+  selection. **Drag from empty canvas** for marquee select; hold
+  **Shift** to extend.
+- With multiple nodes selected, the Inspector shows the **shared
+  attributes** across them. Edit a row once, every selected node
+  updates in a single undo step. Mixed values render with a `Mixed`
+  placeholder.
+- **Cmd-D** duplicates (deep-clone with fresh ids); **Cmd-G** wraps
+  the selection in an `x-container` (**Cmd-Shift-G** prompts for
+  `x-grid` / `x-card` / `x-navbar`); **Delete** removes the whole
+  set in one commit.
+- **Cmd-Opt-C / Cmd-Opt-V** copy attributes from the selection and
+  paste them onto another node, filtered to the target tag's
+  supported attrs — a paste from `x-button` onto an `x-card`
+  silently drops `variant` instead of stamping an unknown attr.
+
+### Inspector ergonomics
+
+- **Drag-to-scrub** numeric labels — the `min` / `max` / `step` rows
+  and the free-coord `:layout :x / :y / :w / :h` rows. Drag the
+  label horizontally; hold Shift for ×10 steps. The whole drag is
+  one undo entry.
+- **`var(--x-…)` autocomplete.** Type `var(` into a colour or length
+  field and a native `<datalist>` surfaces every BareDOM theme
+  token — `--x-color-primary`, `--x-space-md`, `--x-radius-lg`,
+  and so on, sourced from `x-theme` and resolved live by the
+  active preset.
+
+### Discoverability
+
+- **`?`** opens a cheat sheet with every keyboard shortcut and
+  gesture, grouped by category. Built on `x-modal` + `x-typography`
+  so it inherits the live theme preset.
+- **Cmd-K** opens a fuzzy command palette built on
+  `x-command-palette`. Insert any of the 90 BareDOM tags by typing
+  a fragment of the name; toggle the theme editor, the templates
+  panel, preview mode, or the cheat sheet itself — every toolbar
+  action is one keystroke away.
+- **Layers keyboard nav.** Focus the Layers tree, then ↑ / ↓ walk
+  siblings, ← / → step to parent / first child, **Alt+↑ / Alt+↓**
+  reorder within the parent slot.
+- **Palette pattern flyout.** Components with curated variants —
+  `x-button` (primary / secondary / ghost / danger / loading),
+  `x-typography` (h1–h3 / body / caption / code), `x-alert`,
+  `x-badge`, `x-card`, `x-grid` (2-col / 3-col / 4-col / sidebar),
+  and more — show a `▾` caret next to their palette tile. Expand,
+  pick a chip, the component lands pre-styled.
+- **Empty-slot hints.** Empty containers in edit mode show a per-tag
+  prompt — `Drop nav links / actions` inside an empty `x-navbar`,
+  `Drop tiles into the grid` inside an `x-grid`, `Drop x-tab here`
+  inside `x-tabs` — so the next move is always obvious.
+
 ## Fields & bindings
 
 Give a container a **name** and it becomes a component group with its
@@ -452,7 +512,7 @@ structure, then customise content, theme, and layout in the editor.
 **Early alpha.** Feature-complete: 90 BareDOM components in the
 palette, four export plugins at full feature parity (HTML, bundle,
 CLJS, vanilla-JS), nine starter templates, first-run welcome tour,
-doc-level XSS sanitiser, CSP + SRI on every export. 486 tests / 0
+doc-level XSS sanitiser, CSP + SRI on every export. 571 tests / 0
 release-build warnings under Closure Advanced. Expect rough edges
 on less-common BareDOM components until their augment entries are
 hand-tuned. See [`CHANGELOG.md`](./CHANGELOG.md) for what's in

From ba3db25e6d3cc14759cde8588e1f53086556cec1 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 22:09:42 +0200
Subject: [PATCH 23/25] CHANGELOG: fill in [Unreleased] for the
 authoring-shortcuts work

Adds a detailed Added / Changed log under [Unreleased]. Grouped by
user-visible feature so a release reader can match each entry to a
README bullet without diffing the source. Calls out the three
Changed items that ship as side-effects of new features (selection
shape, public action helpers, wrap whitelist) and notes that none
of them touches the document model, project file format, or any
export plugin.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 CHANGELOG.md | 98 +++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 97 insertions(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9e6a08b..55a07c6 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -8,7 +8,103 @@ possible" — I won't promise API stability until `1.0.0` lands.
 
 ## [Unreleased]
 
-Nothing yet.
+Editor authoring quality-of-life. No document-model, project-file,
+or export changes — saved projects load identically, every export
+target stays at parity. Test count: 571 (up from 486), zero
+release-build warnings under Closure Advanced.
+
+### Added
+
+- **Multi-select** on the canvas and Layers panel.
+  - Shift-click extends; drag from empty canvas starts a marquee
+    rectangle (Shift+drag extends).
+  - The selection overlay becomes a pool — one 1px border per
+    selected DOM id. Resize handles only when exactly one node is
+    selected.
+  - Esc clears the selection; Delete / Backspace removes every
+    selected node in one commit via `ops/remove-many`.
+- **Multi-select inspector edit.** With more than one node
+  selected, the Inspector renders the shared-attribute set across
+  all of them. Editing a row dispatches a single
+  `ops/set-attrs-many` (or `set-props-many`) commit; mixed values
+  show with a `Mixed` placeholder and an `is-mixed` class.
+- **Cmd-D duplicate** the selection (deep-clone with fresh ids
+  throughout the subtree).
+- **Cmd-G** wraps the selection in an `x-container`;
+  **Cmd-Shift-G** prompts for `x-grid` / `x-card` / `x-navbar`. New
+  `ops/wrap-many` keeps a sibling set's document order intact
+  inside the new wrapper.
+- **Cmd-Opt-C / Cmd-Opt-V** copy and paste attributes between
+  nodes. Paste is filtered to the target tag's supported attrs so
+  `x-button` → `x-card` silently drops `variant` instead of
+  stamping unknown attributes. Macro-OS Option-modified key (`ç`,
+  `√`) falls back to `.code` (`KeyC`, `KeyV`) for cross-platform
+  parity.
+- **Drag-to-scrub** numeric inspector rows. The label of `:number`
+  kind editors and free-coord `:layout :x / :y / :w / :h` fields
+  becomes a horizontal drag handle; Shift × 10 step. The whole
+  drag is one undo entry via `state/commit-coalesced!`.
+- **BareDOM theme-token autocomplete.** Colour and length fields
+  surface every `--x-color-*` / `--x-space-*` / `--x-radius-*` /
+  `--x-font-size-*` / `--x-border-width` token via a native
+  `<datalist>` injected into the field's shadow root. New
+  `bareforge.meta.design-tokens` mirrors the 50 `tk-*` tokens from
+  `baredom.components.x-theme.model`.
+- **`?` keyboard cheat sheet.** Lists every shortcut and gesture
+  grouped by Editing / Selection / Navigation / File / View. Built
+  on `x-modal` + `x-typography` so it inherits the active theme
+  preset. Source of truth is the static `shortcut-info` data;
+  unit tests assert category coverage.
+- **Cmd-K command palette.** Built on the BareDOM
+  `x-command-palette` web component — owns its own focus, fuzzy
+  filter, scrim, ARIA roles, and theme inheritance. Curated File /
+  View / Selection commands plus one entry per registered BareDOM
+  tag (`Insert <tag>`) plus the four wrap-in targets. Selection
+  flows through a synthetic-id → run-fn dispatch map.
+- **Layers panel keyboard navigation.** Focus the Layers tree, then
+  ↑ / ↓ walk siblings within the parent slot, ← / → step to parent
+  / first child, and **Alt+↑ / Alt+↓** reorder within the slot via
+  `ops/move`. The keydown handler `stopPropagation`s so an arrow on
+  a free-placed selection no longer simultaneously navigates and
+  nudges.
+- **Inline component patterns.** New `bareforge.meta.patterns`
+  carries pre-styled named configurations per tag: `x-button` →
+  primary / secondary / ghost / danger / loading; `x-typography` →
+  h1 / h2 / h3 / body / caption / code; `x-alert`, `x-badge`,
+  `x-card`, `x-chip`, `x-grid`, `x-divider`, `x-switch`,
+  `x-checkbox` covered. Tags with patterns grow a `▾` caret on
+  their palette tile that toggles an inline flyout of pattern
+  chips. A coverage warning prints uncovered tags in test output.
+- **Per-tag empty-slot hints.** New `bareforge.meta.hints` provides
+  hint strings (`Drop nav links / actions`, `Drop tiles into the
+  grid`, `Drop x-tab here`, etc.) for ~20 container tags. The
+  canvas reconciler stamps `data-bareforge-hint` on creation;
+  existing CSS reads it via `attr()` to override the generic
+  `(empty)` placeholder. Drag-time and preview-mode invisibility
+  fall out of existing rules.
+
+### Changed
+
+- `:selection` in `app-state` is now a vector of node ids. New
+  pure helpers `state/selected-ids`, `selected?`,
+  `single-selected-id`; new effectful `select-one!`, `select-clear!`,
+  `select-toggle!`. Internal-only refactor — single-node consumers
+  (resize handles, nudge, inspector lookup, inline-edit teardown)
+  route through `single-selected-id` and degrade gracefully under
+  multi-select. **Saved project files are unchanged.**
+- Action helpers in `ui.shortcuts` (`duplicate!`, `wrap-in!`,
+  `copy-attrs!`, `paste-attrs!`) become public so the command
+  palette reuses them instead of re-implementing the
+  selection → commit → reselect flow.
+- Wrap-in whitelist updated to `x-container / x-grid / x-card /
+  x-navbar`. **`x-flex` is removed** — it isn't a tag in BareDOM
+  2.4, so the previous Cmd-Shift-G prompt would have inserted an
+  unknown element. Cmd-G default behaviour (`x-container`) is
+  unchanged.
+- In edit mode, the canvas host gets `user-select: none` so the
+  Shift-click and marquee-drag gestures don't paint a native
+  text-selection band over the rendered preview. Inline-text
+  editing's textarea overlay re-enables `user-select: text`.
 
 ## [0.1.1] — 2026-04-28
 

From 24843d17ae9ab637445144ff35281085e0ef3494 Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 22:21:10 +0200
Subject: [PATCH 24/25] Rebase fixup: explicit :else in render! cond
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The rebase resolution at 51c6cbc kept the older 2-branch render!
shape (implicit-truthy `[(empty-view)]` as the final cond clause),
but a later replayed commit (M2.3) added a third branch. With the
implicit form, cond ended up with an odd number of forms — caught
immediately by clj-kondo. Restoring the explicit `:else` keeps the
3-branch shape that landed mid-feature originally.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/bareforge/ui/inspector.cljs | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/src/bareforge/ui/inspector.cljs b/src/bareforge/ui/inspector.cljs
index a6f5bbb..430ae03 100644
--- a/src/bareforge/ui/inspector.cljs
+++ b/src/bareforge/ui/inspector.cljs
@@ -2418,6 +2418,8 @@
                        grp-act      (conj grp-act)
                        trg          (conj trg)
                        ds           (conj ds)))
+
+                   :else
                    [(empty-view)])
         ^js scroll-el (or (.-parentElement host-el) host-el)
         scroll-top    (.-scrollTop scroll-el)]

From 8a68d44bb88ffed8ec5b13ce312c39f8b762359a Mon Sep 17 00:00:00 2001
From: vanelsas <58037137+avanelsas@users.noreply.github.com>
Date: Wed, 29 Apr 2026 22:27:36 +0200
Subject: [PATCH 25/25] cljfmt: reformat 5 files
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

CI's cljfmt check caught five files with formatting drift in the
rebased commits — mostly inconsistent destructure spacing and
column-aligned key/value pairs that cljfmt 0.16's defaults
re-align. Pure whitespace, no semantic change. Verified locally:

- cljfmt check — All source files formatted correctly
- npx shadow-cljs compile test — 571 tests, 0 failures
- npx shadow-cljs release app — 0 warnings
- clj-kondo — 0 warnings, 0 errors

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 src/bareforge/ui/command_palette.cljs |  4 +-
 src/bareforge/ui/inspector.cljs       | 82 +++++++++++++--------------
 src/bareforge/ui/shortcuts.cljs       | 50 ++++++++--------
 test/bareforge/doc/ops_test.cljs      |  4 +-
 test/bareforge/ui/shortcuts_test.cljs | 14 ++---
 5 files changed, 77 insertions(+), 77 deletions(-)

diff --git a/src/bareforge/ui/command_palette.cljs b/src/bareforge/ui/command_palette.cljs
index b0b4fd4..ce298a1 100644
--- a/src/bareforge/ui/command_palette.cljs
+++ b/src/bareforge/ui/command_palette.cljs
@@ -140,7 +140,7 @@
   []
   (let [cmds (vec (all-commands))]
     [(into-array
-       (map-indexed ->item cmds))
+      (map-indexed ->item cmds))
      (into {}
            (map-indexed (fn [i c] [(str "cmd-" i) (:run! c)]))
            cmds)]))
@@ -154,7 +154,7 @@
       ;; Defer to next microtask so the palette finishes its own
       ;; close-on-select work before we mutate state / focus.
       (js/queueMicrotask
-        (fn [] (try (f) (catch :default _ nil)))))))
+       (fn [] (try (f) (catch :default _ nil)))))))
 
 (defn- build-modal! []
   (let [el (u/el :x-command-palette
diff --git a/src/bareforge/ui/inspector.cljs b/src/bareforge/ui/inspector.cljs
index 430ae03..45176bb 100644
--- a/src/bareforge/ui/inspector.cljs
+++ b/src/bareforge/ui/inspector.cljs
@@ -214,7 +214,7 @@
             (if-let [^js sr (.-shadowRoot host)]
               (when-let [^js inner (.querySelector sr "[part=input]")]
                 (when-not (.querySelector sr
-                            (str "datalist[id='" datalist-id "']"))
+                                          (str "datalist[id='" datalist-id "']"))
                   (when-let [^js src (js/document.getElementById datalist-id)]
                     (.appendChild sr (.cloneNode src true))))
                 (.setAttribute inner "list" datalist-id))
@@ -393,25 +393,25 @@
     (cond-> el
       numeric?
       (attach-scrub-meta!
-        {:read-fn   (fn []
+       {:read-fn   (fn []
                       ;; Empty / non-numeric attr starts the drag at 0
                       ;; so unset fields are still scrubbable from
                       ;; nothing — otherwise the gesture would silently
                       ;; do nothing on a fresh component.
-                      (let [doc    (:document @state/app-state)
-                            n      (m/get-node doc node-id)
-                            raw    (current-value n prop)
-                            parsed (when (and raw (not= "" raw))
-                                     (let [p (js/parseFloat raw)]
-                                       (when-not (js/isNaN p) p)))]
-                        (or parsed 0)))
-         :commit-fn! (fn [new-val first?]
-                       (let [doc  (:document @state/app-state)
-                             doc' (ops/set-attr doc node-id attr-name (str new-val))]
-                         (if first?
-                           (state/commit! doc')
-                           (state/commit-coalesced! doc'))))
-         :step       1}))))
+                     (let [doc    (:document @state/app-state)
+                           n      (m/get-node doc node-id)
+                           raw    (current-value n prop)
+                           parsed (when (and raw (not= "" raw))
+                                    (let [p (js/parseFloat raw)]
+                                      (when-not (js/isNaN p) p)))]
+                       (or parsed 0)))
+        :commit-fn! (fn [new-val first?]
+                      (let [doc  (:document @state/app-state)
+                            doc' (ops/set-attr doc node-id attr-name (str new-val))]
+                        (if first?
+                          (state/commit! doc')
+                          (state/commit-coalesced! doc'))))
+        :step       1}))))
 
 (defn- build-widget [node prop]
   (let [spec (editor-spec prop)]
@@ -526,27 +526,27 @@
              (let [v (read-event-value e)]
                (commit-with! ops/set-layout node-id layout-key (parse-length-value v)))))
     (attach-scrub-meta!
-      el
-      {:read-fn    (fn []
+     el
+     {:read-fn    (fn []
                      ;; Default to 0 when the field is empty so the
                      ;; gesture engages immediately — useful when
                      ;; placement is being changed to :free and the
                      ;; user wants to scrub the new coord into shape.
-                     (let [doc (:document @state/app-state)
-                           v   (get-in (m/get-node doc node-id)
-                                       [:layout layout-key])]
-                       (cond
-                         (number? v) v
-                         (string? v) (let [parsed (js/parseFloat v)]
-                                       (if (js/isNaN parsed) 0 parsed))
-                         :else       0)))
-       :commit-fn! (fn [new-val first?]
-                     (let [doc  (:document @state/app-state)
-                           doc' (ops/set-layout doc node-id layout-key new-val)]
-                       (if first?
-                         (state/commit! doc')
-                         (state/commit-coalesced! doc'))))
-       :step       1})))
+                    (let [doc (:document @state/app-state)
+                          v   (get-in (m/get-node doc node-id)
+                                      [:layout layout-key])]
+                      (cond
+                        (number? v) v
+                        (string? v) (let [parsed (js/parseFloat v)]
+                                      (if (js/isNaN parsed) 0 parsed))
+                        :else       0)))
+      :commit-fn! (fn [new-val first?]
+                    (let [doc  (:document @state/app-state)
+                          doc' (ops/set-layout doc node-id layout-key new-val)]
+                      (if first?
+                        (state/commit! doc')
+                        (state/commit-coalesced! doc'))))
+      :step       1})))
 
 (defn- build-layout-textarea
   "Multi-line editor for the free-form `:extra-style` layout field.
@@ -1151,14 +1151,14 @@
     (if (or (empty? meta-list) (empty? first-list))
       []
       (filterv
-        (fn [prop]
-          (every?
-            (fn [m]
-              (some #(and (= (:name prop) (:name %))
-                          (= (:kind prop) (:kind %)))
-                    (:properties m)))
-            (rest meta-list)))
-        first-list))))
+       (fn [prop]
+         (every?
+          (fn [m]
+            (some #(and (= (:name prop) (:name %))
+                        (= (:kind prop) (:kind %)))
+                  (:properties m)))
+          (rest meta-list)))
+       first-list))))
 
 (defn joint-attr-value
   "Pure: read attribute `prop` across `nodes` and return
diff --git a/src/bareforge/ui/shortcuts.cljs b/src/bareforge/ui/shortcuts.cljs
index 63996d9..7643e1e 100644
--- a/src/bareforge/ui/shortcuts.cljs
+++ b/src/bareforge/ui/shortcuts.cljs
@@ -67,19 +67,19 @@
    {:category :editing    :keys "Arrow keys"     :label "Nudge by 1px (free placement)"}
    {:category :editing    :keys "Shift+Arrow"    :label "Nudge by 10px (free placement)"}
    {:category :editing    :keys "Drag numeric label"
-                          :label "Scrub numeric value (Shift × 10)"}
+    :label "Scrub numeric value (Shift × 10)"}
 
    {:category :selection  :keys "Click"          :label "Select node"}
    {:category :selection  :keys "Shift-click"    :label "Toggle node in multi-selection"}
    {:category :selection  :keys "Drag empty canvas" :label "Marquee select"}
    {:category :selection  :keys "Shift+drag empty canvas"
-                          :label "Marquee extend selection"}
+    :label "Marquee extend selection"}
 
    {:category :navigation :keys "Esc"            :label "Deselect / exit text edit"}
    {:category :navigation :keys "Arrow keys (in Layers)"
-                          :label "Walk the document tree"}
+    :label "Walk the document tree"}
    {:category :navigation :keys "Alt+Up / Alt+Down (in Layers)"
-                          :label "Reorder selection within parent slot"}
+    :label "Reorder selection within parent slot"}
 
    {:category :file       :keys "Cmd+S"          :label "Save project"}
    {:category :file       :keys "Cmd+O"          :label "Open project"}
@@ -285,7 +285,7 @@
    selection change) starts a fresh history entry."
   [dx dy]
   (let [sel-id     (canvas/canonical-node-id
-                     (state/single-selected-id @state/app-state))
+                    (state/single-selected-id @state/app-state))
         doc        (:document @state/app-state)
         node       (m/get-node doc sel-id)
         cur-x      (or (get-in node [:layout :x]) 0)
@@ -349,9 +349,9 @@
     (when-let [n (and (not= "root" id)
                       (m/get-node (:document @state/app-state) id))]
       (state/set-clipboard-attrs!
-        {:source-tag (:tag n)
-         :attrs      (or (:attrs n) {})
-         :props      (or (:props n) {})}))))
+       {:source-tag (:tag n)
+        :attrs      (or (:attrs n) {})
+        :props      (or (:props n) {})}))))
 
 (defn paste-attrs! []
   (when-let [{:keys [attrs props]} (state/clipboard-attrs @state/app-state)]
@@ -359,24 +359,24 @@
       (when (seq target-ids)
         (let [doc  (:document @state/app-state)
               doc' (reduce
-                     (fn [d id]
-                       (let [tag    (some-> (m/get-node d id) :tag)
-                             ok     (when tag (supported-attr-names tag))]
-                         (if (and tag (seq ok))
-                           (let [attrs* (select-keys attrs ok)
+                    (fn [d id]
+                      (let [tag    (some-> (m/get-node d id) :tag)
+                            ok     (when tag (supported-attr-names tag))]
+                        (if (and tag (seq ok))
+                          (let [attrs* (select-keys attrs ok)
                                  ;; Boolean :props are keyed by keyword;
                                  ;; cross-reference against the string
                                  ;; supported-attrs set via `name`.
-                                 props* (into {}
-                                          (filter (fn [[k _]]
-                                                    (contains? ok (name k)))
-                                                  props))]
-                             (-> d
-                                 (ops/set-attrs id attrs*)
-                                 (ops/set-props id props*)))
-                           d)))
-                     doc
-                     target-ids)]
+                                props* (into {}
+                                             (filter (fn [[k _]]
+                                                       (contains? ok (name k)))
+                                                     props))]
+                            (-> d
+                                (ops/set-attrs id attrs*)
+                                (ops/set-props id props*)))
+                          d)))
+                    doc
+                    target-ids)]
           (when (not= doc doc')
             (state/commit! doc')))))))
 
@@ -395,8 +395,8 @@
    types something off-list."
   []
   (let [input (js/window.prompt
-                "Wrap selection in: x-container, x-grid, x-card, x-navbar"
-                "x-container")]
+               "Wrap selection in: x-container, x-grid, x-card, x-navbar"
+               "x-container")]
     (when (and (string? input)
                (contains? wrap-tag-whitelist input))
       input)))
diff --git a/test/bareforge/doc/ops_test.cljs b/test/bareforge/doc/ops_test.cljs
index 78ff52c..e9fd121 100644
--- a/test/bareforge/doc/ops_test.cljs
+++ b/test/bareforge/doc/ops_test.cljs
@@ -65,7 +65,7 @@
         {d1 :doc id :id}   (ops/insert-new d0 "root" "default" 0 "x-button")
         ;; Removing a parent cascades — descendants in the same set
         ;; are no-ops on subsequent passes.
-        {d2 :doc inner :id}(ops/insert-new d1 id "default" 0 "x-inner")
+        {d2 :doc inner :id} (ops/insert-new d1 id "default" 0 "x-inner")
         d3                 (ops/remove-many d2 [id inner "ghost"])]
     (is (empty? (get-in d3 [:root :slots "default"])))))
 
@@ -204,7 +204,7 @@
   (let [d0                (empty-doc)
         {d1 :doc id :id}  (ops/insert-new d0 "root" "default" 0 "x-button")
         d2                (ops/set-attrs d1 id {"variant" "primary"
-                                                 "label"   "Click"})
+                                                "label"   "Click"})
         node              (m/get-node d2 id)]
     (is (= "primary" (get-in node [:attrs "variant"])))
     (is (= "Click"   (get-in node [:attrs "label"])))))
diff --git a/test/bareforge/ui/shortcuts_test.cljs b/test/bareforge/ui/shortcuts_test.cljs
index 7b6e3ad..78391bc 100644
--- a/test/bareforge/ui/shortcuts_test.cljs
+++ b/test/bareforge/ui/shortcuts_test.cljs
@@ -237,7 +237,7 @@
 (deftest dispatch-cmd-d-ignored-in-editable
   (is (= :noop
          (k/dispatch (assoc with-selection :key "d" :meta? true
-                                           :tag-name "INPUT")))))
+                            :tag-name "INPUT")))))
 
 (deftest dispatch-cmd-shift-d-is-noop
   (testing "Cmd+Shift+D is reserved (browser bookmark variants);
@@ -260,12 +260,12 @@
             guard, mirroring the :delete pattern"
     (is (= :noop
            (k/dispatch (assoc with-selection :key "g" :meta? true
-                                             :selection-id "root"))))))
+                              :selection-id "root"))))))
 
 (deftest dispatch-cmd-g-ignored-in-editable
   (is (= :noop
          (k/dispatch (assoc with-selection :key "g" :meta? true
-                                           :tag-name "X-SEARCH-FIELD")))))
+                            :tag-name "X-SEARCH-FIELD")))))
 
 (deftest dispatch-cmd-shift-g-prompts
   (is (= :wrap-in-prompt
@@ -276,7 +276,7 @@
 (deftest dispatch-cmd-shift-g-noop-on-root
   (is (= :noop
          (k/dispatch (assoc with-selection :key "g" :meta? true :shift? true
-                                           :selection-id "root")))))
+                            :selection-id "root")))))
 
 ;; --- copy / paste attrs -------------------------------------------------
 
@@ -287,7 +287,7 @@
 (deftest dispatch-cmd-opt-c-noop-on-root
   (is (= :noop
          (k/dispatch (assoc with-selection :key "c" :meta? true :alt? true
-                                           :selection-id "root")))))
+                            :selection-id "root")))))
 
 (deftest dispatch-cmd-opt-c-noop-without-selection
   (is (= :noop
@@ -310,12 +310,12 @@
 (deftest dispatch-cmd-opt-c-ignored-in-editable
   (is (= :noop
          (k/dispatch (assoc with-selection :key "c" :meta? true :alt? true
-                                           :tag-name "INPUT")))))
+                            :tag-name "INPUT")))))
 
 (deftest dispatch-cmd-opt-v-ignored-in-editable
   (is (= :noop
          (k/dispatch (assoc with-selection :key "v" :meta? true :alt? true
-                                           :tag-name "X-TEXT-FIELD")))))
+                            :tag-name "X-TEXT-FIELD")))))
 
 (deftest dispatch-cmd-opt-c-matches-macos-modified-key
   (testing "On macOS US layout Option+C produces 'ç', so dispatch must