@kolkrabbi/kol-component 0.128.0 → 0.130.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kolkrabbi/kol-component",
-  "version": "0.128.0",
+  "version": "0.130.0",
   "description": "KOL design-system components — atoms through organisms, emitting canonical kol-* classes. Pairs with @kolkrabbi/kol-theme for styling.",
   "license": "MIT",
   "type": "module",
@@ -36,7 +36,7 @@
     "react-router-dom": "^6.0.0 || ^7.0.0"
   },
   "devDependencies": {
-    "@kolkrabbi/kol-icons": "^0.24.0"
+    "@kolkrabbi/kol-icons": "^0.25.0"
   },
   "files": [
     "src",

package/src/atoms/Input.jsx

@@ -9,7 +9,7 @@ import { glyphSize } from '../hooks/glyphLadders.js'
  *   variant="outline"          — bordered, transparent bg — THE secondary
  *                                treatment (2026-07-08 chrome law: one
  *                                secondary, always subordinate to filled)
- *   tone="inverse"             — the dark chip (`fg-absolute-24`) for a washed plane
+ *   tone="inverse"             — the dark chip (`fg-ab-24`) for a washed plane
  *                                (ControlToneInverse, 2026-08-27); same prop on ViewToggle · Dropdown
  *   variant="ghost"            — legacy alias, resolves to outline
  *   variant="property"         — the Figma property field (PropertyField,

package/src/atoms/ViewToggle.jsx

@@ -7,7 +7,7 @@ import { toneClass } from '../utilities/tone.js'
  *   variant="text"   — segmented bare buttons; active uses kol-control--filled,
  *                      inactive is bare text-meta with text-emphasis on hover.
  *   variant="icon"   — bordered chip-row container holding square icon
- *                      buttons. Active uses bg-fg-absolute-24.
+ *                      buttons. Active uses bg-fg-ab-24.
  *   variant="single" — single button binary toggle. Click flips between the
  *                      two `options` values. The button shows the *current*
  *                      option's label; active = on (kol-control--filled),
@@ -28,7 +28,7 @@ import { toneClass } from '../utilities/tone.js'
  * is the active … it would fit better on the light grey"): on a washed plane
  * (`pageWash`, `fg-04`) the default grey well reads as a second plate, so the
  * icon variant's two values swap — the well takes the dark chip
- * (`fg-absolute-24`), the active chip the `fg-16` ink wash (user, on the live
+ * (`fg-ab-24`), the active chip the `fg-16` ink wash (user, on the live
  * page: "just use bg-fg-16"), the inactive hover a lighter wash. Theme rules on `.kol-tone-inverse`
  * (kol-theme ≥0.78.0); the same prop on `Dropdown` and `Input`.
  */
@@ -84,10 +84,10 @@ const ViewToggle = ({
   const buttonClasses = (isActive) => {
     if (isIconVariant) {
       // Inset "well" pattern — container is bg-fg-04 (slight lift from page),
-      // active button uses bg-fg-absolute-24 (theme-invariant black, always
+      // active button uses bg-fg-ab-24 (theme-invariant black, always
       // darkens regardless of theme) so it reads as recessed/pressed.
       return `inline-flex items-center justify-center p-1.5 rounded transition-colors text-emphasis cursor-pointer ${
-        isActive ? 'bg-fg-absolute-24' : 'hover:bg-fg-absolute-08'
+        isActive ? 'bg-fg-ab-24' : 'hover:bg-fg-ab-08'
       }`
     }
     /* Active = filled chip. Inactive = bare-text on the shell base — no

package/src/index.js

@@ -134,6 +134,8 @@ export { default as SectionCards } from './organisms/SectionCards.jsx'
 export { default as SectionCta, default as CtaGlobal } from './organisms/SectionCta.jsx'
 export { default as SectionFaq } from './organisms/SectionFaq.jsx'
 export { default as LoaderOverlay } from './utilities/LoaderOverlay.jsx'
+/* dev chrome: name an element, agree on a cell, emit one sync line */
+export { default as QuadrantSync } from './utilities/QuadrantSync.jsx'
 export { default as MediaLibrary, MediaLibraryProvider, useMediaLibrary, MediaPicker, MediaBrowser } from './organisms/MediaLibrary.jsx'
 export { default as MediaTileGallery } from './organisms/MediaTileGallery.jsx'
 export { default as MediaViewer } from './organisms/MediaViewer.jsx'

package/src/molecules/AudioSheet.jsx

@@ -22,7 +22,7 @@ function useCover(src) {
  *
  *   cover  the same as VideoSheet — the artwork is the frame (`w-[min(78vh,100vw_-_10rem)]`,
  *          square), the bar floating over its bottom edge (inset 16, radius 12)
- *   sheet  the QuickTime window — a dark plate (`bg-fg-absolute-88`, `min(100vw − 10rem, 1000px)`),
+ *   sheet  the QuickTime window — a dark plate (`bg-fg-ab-88`, `min(100vw − 10rem, 1000px)`),
  *          the cover square left, `Time: mm:ss` beside it, the bar flush along the bottom
  *
  * Artwork = the file's embedded ID3 `APIC` cover (`readCover`); no cover → a light
@@ -39,14 +39,14 @@ export default function AudioSheet({ src, onDuration, variant = 'cover' }) {
   const audio = <audio ref={ref} src={src} autoPlay preload="metadata" {...handlers} />
   const art = cover
     ? <img src={cover} alt="" className="w-full h-full object-cover" />
-    : <div className="w-full h-full flex items-center justify-center bg-absolute-white text-fg-absolute-32"><Icon name="music-note" size={64} /></div>
+    : <div className="w-full h-full flex items-center justify-center bg-ab-white text-fg-ab-32"><Icon name="music-note" size={64} /></div>
 
   if (variant === 'sheet') return (
-    <div className="relative w-[min(100vw_-_10rem,1000px)] rounded overflow-hidden bg-fg-absolute-88">
+    <div className="relative w-[min(100vw_-_10rem,1000px)] rounded overflow-hidden bg-fg-ab-88">
       {audio}
       <div className="flex items-center gap-16 p-10 pb-24">
         <div className="w-[min(50vh,380px)] aspect-square shrink-0 overflow-hidden">{art}</div>
-        <span className="kol-mono-16 text-absolute-white"><span className="opacity-48">Time: </span><b className="opacity-80">{clock(bar.duration)}</b></span>
+        <span className="kol-mono-16 text-ab-white"><span className="opacity-48">Time: </span><b className="opacity-80">{clock(bar.duration)}</b></span>
       </div>
       <PlaybackBar {...bar} place="left-0 right-0 bottom-0" />
     </div>

package/src/molecules/ColorInputRow.jsx

@@ -116,7 +116,7 @@ export default function ColorInputRow({
       {chip('stretch')}
       <span
         aria-hidden="true"
-        className={`absolute inset-0 inline-flex items-center justify-center rounded-[var(--kol-radius-xs)] transition-opacity bg-fg-absolute-48 text-white pointer-events-none ${
+        className={`absolute inset-0 inline-flex items-center justify-center rounded-[var(--kol-radius-xs)] transition-opacity bg-fg-ab-48 text-white pointer-events-none ${
           locked ? 'opacity-100' : 'opacity-0 group-hover:opacity-100'
         }`}
       >

package/src/molecules/Dropdown.jsx

@@ -17,7 +17,7 @@ import { indicatorSize } from '../hooks/glyphLadders.js'
  *     same fill (one piece: no border, no gap, hairline divider inside)
  *   variant="grey"              — oq-12 filled trigger (opaque per the fill
  *                                 law); panel continues it
- *   tone="inverse"              — the dark chip (`fg-absolute-24`) for a washed
+ *   tone="inverse"              — the dark chip (`fg-ab-24`) for a washed
  *                                 plane, the panel continuing it (ControlToneInverse,
  *                                 kol-website 2026-08-27); same prop on ViewToggle · Input
  *   variant="outline"           — bordered trigger; open panel carries the

package/src/molecules/MediaCard.jsx

@@ -27,7 +27,7 @@ export function SelectIndicator({ on = false }) {
       style={
         on
           ? { background: 'var(--kol-surface-on-primary)', borderColor: 'var(--kol-surface-on-primary)' }
-          : { background: 'var(--kol-fg-absolute-16, rgba(0,0,0,0.15))', borderColor: 'var(--kol-fg-absolute-48, rgba(0,0,0,0.4))' }
+          : { background: 'var(--kol-fg-ab-16, rgba(0,0,0,0.15))', borderColor: 'var(--kol-fg-ab-48, rgba(0,0,0,0.4))' }
       }
       aria-hidden="true"
     >
@@ -76,7 +76,7 @@ export default function MediaCard({
         {selectMode ? (
           <span
             className="kol-frame-control kol-frame-control--top-left rounded p-1"
-            style={{ background: 'var(--kol-fg-absolute-12, rgba(0,0,0,0.4))', backdropFilter: 'blur(4px)' }}
+            style={{ background: 'var(--kol-fg-ab-12, rgba(0,0,0,0.4))', backdropFilter: 'blur(4px)' }}
           >
             <SelectIndicator on={selected} />
           </span>
@@ -85,8 +85,8 @@ export default function MediaCard({
             href={downloadHref}
             aria-label="Download"
             title="Download"
-            className="kol-frame-control inline-flex items-center justify-center w-8 h-8 rounded text-emphasis hover:bg-fg-absolute-24 transition-colors"
-            style={{ background: 'var(--kol-fg-absolute-12, rgba(0,0,0,0.4))', backdropFilter: 'blur(4px)' }}
+            className="kol-frame-control inline-flex items-center justify-center w-8 h-8 rounded text-emphasis hover:bg-fg-ab-24 transition-colors"
+            style={{ background: 'var(--kol-fg-ab-12, rgba(0,0,0,0.4))', backdropFilter: 'blur(4px)' }}
             onClick={(e) => e.stopPropagation()}
           >
             <Icon name="download" size={16} />

package/src/molecules/PlaybackBar.jsx

@@ -13,7 +13,7 @@ const RATES = [1, 1.5, 2]
 /**
  * PlaybackBar — the QuickTime bar, ruled against the reference (PlaybackBarAndAudioSheet,
  * kol-r2b2 2026-08-27; supersedes 0.107.0's strip): a frosted strip over media —
- * `bg-fg-absolute-48 backdrop-blur-xl`, **radius 12** (`rounded-xl`, the user's
+ * `bg-fg-ab-48 backdrop-blur-xl`, **radius 12** (`rounded-xl`, the user's
  * ruling on this surface — the 4px container law stands elsewhere), `h-16 px-8
  * gap-7` — white glyphs whatever the theme (`.kol-playback-bar`, kol-theme ≥0.75.0:
  * opacity .8, 1 on hover / focus-visible), the transport cluster (`skip-back-15` ·
@@ -44,7 +44,7 @@ export default function PlaybackBar({ playing, time, duration, rate = 1, onToggl
   const pop = usePopover({ open, onOpenChange: setOpen, placement: 'top' })
   const nextRate = RATES[(RATES.indexOf(rate) + 1) % RATES.length]
   return (
-    <div className={`kol-playback-bar absolute h-16 px-8 flex items-center gap-7 bg-fg-absolute-48 backdrop-blur-xl text-absolute-white ${place}`}>
+    <div className={`kol-playback-bar absolute h-16 px-8 flex items-center gap-7 bg-fg-ab-48 backdrop-blur-xl text-ab-white ${place}`}>
       <div className="flex items-center gap-5">
         <IconFrame name="skip-back-15" variant="ghost" size="sm" onClick={() => onSeek(time - 15)} aria-label="Back 15 seconds" />
         <IconFrame name={playing ? 'pause' : 'play'} variant="ghost" size="sm" onClick={onToggle} aria-label={playing ? 'Pause' : 'Play'} />

package/src/molecules/TiltBento.jsx

@@ -98,7 +98,7 @@ function Media({ src, poster, className }) {
  * @param {boolean}   alignRight     right-align the card (ms-auto) vs fill (size-full)
  * @param {boolean}   enableTilt     master tilt switch (default true)
  * @param {string}    titleClassName title classes — the family default is `kol-sans-heading-01
- *                                   text-absolute-white` (confirmed 2026-08-27; the fork's was
+ *                                   text-ab-white` (confirmed 2026-08-27; the fork's was
  *                                   heading-02 uppercase — a consumer wanting that passes it)
  * @param {string}    contentClassName inner content-box classes
  * @param {string}    imageClassName media fit/position classes
@@ -118,7 +118,7 @@ export default function TiltBento({
   overlayOpacity = 60,
   alignRight = false,
   enableTilt = true,
-  titleClassName = 'kol-sans-heading-01 text-absolute-white',
+  titleClassName = 'kol-sans-heading-01 text-ab-white',
   contentClassName = 'max-w-[384px]',
   imageClassName = 'object-cover object-center',
   contentStackClassName = 'relative z-20 h-full flex flex-col justify-start items-start gap-4 p-6 md:p-8',
@@ -173,8 +173,8 @@ export default function TiltBento({
             {/* kol-mono-14 — one rung above the mono-12 description, as the retired
               * fork drew it (TiltBentoVoiceAndDefaults, kol-website 2026-08-27: this
               * rode `kol-mono-text`, a class retired from the theme — zero rules emitted) */}
-            {subtitle && <p className={`kol-mono-14 text-absolute-white ${revealClass}`}>{subtitle}</p>}
-            {description && <p className={`kol-mono-12 text-absolute-white pb-6 ${revealClass}`}>{description}</p>}
+            {subtitle && <p className={`kol-mono-14 text-ab-white ${revealClass}`}>{subtitle}</p>}
+            {description && <p className={`kol-mono-12 text-ab-white pb-6 ${revealClass}`}>{description}</p>}
             {bodyContent}
             {href && (
               <div className={revealClass}>

package/src/organisms/MediaLibraryPages.jsx

@@ -192,7 +192,7 @@ function MediaInspector({ files, index, onClose, onPrev, onNext, mediaUrl, downl
   if (!o) return null
   const kind = kindOf(o)
   const poster = kind === 'video' ? posterFor(o.key, keySet) : null
-  const ARROW = 'fixed top-1/2 -translate-y-1/2 z-10 w-10 h-10 flex items-center justify-center rounded text-fg-48 hover:text-fg-default hover:bg-fg-absolute-24 transition-colors'
+  const ARROW = 'fixed top-1/2 -translate-y-1/2 z-10 w-10 h-10 flex items-center justify-center rounded text-fg-48 hover:text-fg-default hover:bg-fg-ab-24 transition-colors'
   return (
     <FullscreenOverlay open onClose={onClose} closeButton={false}>
       <button type="button" className={`${ARROW} left-6`} onClick={onPrev} disabled={files.length <= 1} aria-label="Previous"><Icon name="chevron-left" size={22} /></button>

package/src/organisms/SettingsPanel.jsx

@@ -150,10 +150,16 @@ export function LabeledControlSection({ label, divided = false, rowGap = 2, chil
 /** SettingsChoice — the row's one-of-N control: the DS Dropdown, sm · primary
  *  (SettingsPanelEyebrowAndDropdowns — user: "put the toggles inside a dropdown,
  *  because it's super messy like it is"). Options are values or `{ value, label }`;
- *  width is the call site's (`className="w-40"`). */
-export function SettingsChoice({ options = [], value, onChange, ariaLabel, className = '' }) {
+ *  width is the call site's (`className="w-40"`).
+ *
+ *  `tone` · `size` · `variant` pass through (kol-fxr 2026-08-28): they were
+ *  hardcoded, so a settings page ruled sunken could not be told — and kol-fxr
+ *  rebuilt this same Dropdown in a local `ChoiceRow`, which is the exact
+ *  duplication this component exists to prevent. A component that wraps another
+ *  has to forward the wrapped one's seams or it becomes a wall. */
+export function SettingsChoice({ options = [], value, onChange, ariaLabel, tone = 'default', size = 'sm', variant = 'primary', className = '' }) {
   const opts = options.map((o) => (o != null && typeof o === 'object' ? o : { value: o, label: String(o) }))
-  return <Dropdown size="sm" variant="primary" value={value} onChange={onChange} options={opts} className={`w-full ${className}`.trim()} aria-label={ariaLabel} />
+  return <Dropdown size={size} variant={variant} tone={tone} value={value} onChange={onChange} options={opts} className={`w-full ${className}`.trim()} aria-label={ariaLabel} />
 }
 
 /* THE CONTROL CHIP (SettingsPanelCompliance, user 2026-08-27: "WROOOONG" on the
@@ -173,13 +179,13 @@ export const chipCls = (on) => `${CHIP_CLS} ${on ? 'kol-control--filled' : 'text
  * @param {Function} onToggle (value) => void
  * @param {string} noun      the trigger's noun (default 'kinds')
  */
-export function SettingsMulti({ options = [], selected = [], onToggle, noun = 'kinds', className = '' }) {
+export function SettingsMulti({ options = [], selected = [], onToggle, noun = 'kinds', tone = 'default', size = 'sm', className = '' }) {
   const on = selected instanceof Set ? selected : new Set(selected)
   const opts = [
     { value: '__summary', label: `${on.size} of ${options.length} ${noun}` },
     ...options.map((o) => ({ value: o.value, label: `${on.has(o.value) ? '✓ ' : ''}${o.label ?? String(o.value)}` })),
   ]
-  return <Dropdown size="sm" variant="primary" value="__summary" options={opts} onChange={(v) => (v === '__summary' ? null : onToggle?.(v))} className={`w-full ${className}`.trim()} />
+  return <Dropdown size={size} variant="primary" tone={tone} value="__summary" options={opts} onChange={(v) => (v === '__summary' ? null : onToggle?.(v))} className={`w-full ${className}`.trim()} />
 }
 
 /**

package/src/organisms/sectionSurface.js

@@ -1,7 +1,7 @@
 /* ONE surface prop across the section family (SectionBackgroundProp, kol-website
  * 2026-08-27 — user: "ALL section family should pass bg as props"). A named
  * surface, `none`, or a raw utility / token string for the odd case
- * (`'bg-fg-absolute-16'`). Each section's default is what it painted before,
+ * (`'bg-fg-ab-16'`). Each section's default is what it painted before,
  * so nothing moves on the bump. `theme` keeps scoping ink; this is the paint. */
 export const SURFACES = {
   primary: 'bg-surface-primary',

package/src/utilities/QuadrantSync.jsx

@@ -0,0 +1,588 @@
+/**
+ * QuadrantSync — the pinpoint overlay.
+ *
+ * Dev chrome for agreeing on WHICH element is being discussed before anyone
+ * edits it. Draws a chess-style grid on a named node and emits one sync line —
+ * `StageModuleGroup @ 1440w · e8 → h7` — that both sides restate. Born from a
+ * real failure: ten messages to move one button, none of them wrong about CSS,
+ * all of them about different elements.
+ *
+ * The rule that outranks every other: **the grid goes on what the USER named.**
+ * Never redirected to a child or a parent. The owner is REPORTED, never
+ * substituted — a grab-handle that moves a whole group lives at group level,
+ * and quietly re-pointing the grid at a child answers a question nobody asked.
+ *
+ * Mark nodes with `data-handle="Name"` on divs that already exist — never a
+ * wrapper added for the tool's benefit. Optionally `data-source="@kolkrabbi/…"`
+ * so design-system ownership is a fact at selection time, not a discovery
+ * mid-edit.
+ *
+ * A cell is a FRACTION of the named element, which is why `e8` means the same
+ * relative place at 1440w and 760w and a pixel offset never does.
+ *
+ * Measures and positions over nodes from a fixed layer; it never wraps a node,
+ * so grid position tracks the RENDERED layout rather than the tree. Renders
+ * nothing when `enabled` is false — dev-only by default.
+ *
+ * @param {Object}   props
+ * @param {HTMLElement} props.root        Subtree to hunt handles in (default document.body)
+ * @param {string}   props.attr           Attribute naming a node (default 'data-handle')
+ * @param {string}   props.sourceAttr     Attribute naming a node's origin (default 'data-source')
+ * @param {Array}    props.bands          Breakpoint bands; the live one is READ from the window
+ * @param {Object}   props.defaultDivisions  `{ cols, rows }` before `square` is applied
+ * @param {string}   props.initialHandle  Handle name to select on mount
+ * @param {Function} props.onSyncLine     (line, parts) => void, fired when the line changes
+ * @param {string}   props.handleColor    Grid + outline color for the named node
+ * @param {string}   props.pageColor      Grid color for the page reference
+ * @param {boolean}  props.enabled        Render at all (default: off in production)
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react'
+
+/* ── coordinates ─────────────────────────────────────────────────────────
+ * Pure. No DOM writes. The invariant everything rests on: a cell is a
+ * fraction of the box, so the same relative point resolves to the same cell
+ * at any size.
+ */
+
+const LETTERS = 'abcdefghijklmnopqrstuvwxyz'
+export const MAX_COLS = 26
+export const MAX_ROWS = 100
+const SQUARE_TOLERANCE = 0.06
+
+const clamp = (v, lo, hi) => Math.max(lo, Math.min(hi, v))
+
+/** `a1` is TOP-LEFT — screen convention, not chess's bottom-left. */
+const cellLabel = (c, r) => LETTERS[c] + (r + 1)
+
+const rectOf = (el) => {
+  const r = el.getBoundingClientRect()
+  return { left: r.left, top: r.top, width: r.width, height: r.height, right: r.right, bottom: r.bottom }
+}
+
+/** Which cell of `box` holds the viewport point. Out-of-box points clamp. */
+function cellAt (box, px, py, cols, rows) {
+  return {
+    c: clamp(Math.floor(((px - box.left) / box.width) * cols), 0, cols - 1),
+    r: clamp(Math.floor(((py - box.top) / box.height) * rows), 0, rows - 1)
+  }
+}
+
+/** An element SPANS cells, it does not sit in one — `c1–f8`, or one label if it fits one cell. */
+function spanOf (child, parent, cols, rows) {
+  const a = cellAt(parent, child.left + 1, child.top + 1, cols, rows)
+  const b = cellAt(parent, child.right - 1, child.bottom - 1, cols, rows)
+  const s = cellLabel(a.c, a.r)
+  const e = cellLabel(b.c, b.r)
+  return s === e ? s : `${s}–${e}`
+}
+
+function cellAspect (box, cols, rows) {
+  if (!box || !box.width || !box.height) return null
+  const cw = box.width / cols
+  const ch = box.height / rows
+  const ratio = cw / ch
+  return { cw, ch, ratio, isSquare: Math.abs(ratio - 1) <= SQUARE_TOLERANCE }
+}
+
+/**
+ * Derive the second axis so cells come out square on THIS box.
+ *
+ * One-shot on purpose. Recomputing on every reflow would silently change what
+ * a coordinate means, which is the confusion this whole thing exists to remove.
+ * After a reflow the cells stretch into rectangles — expected, and fine.
+ *
+ * The axis caps can make a naive first pass unusable on an extreme box (a 5.7:1
+ * strip at 8 columns wants 1.4 rows), so re-anchor on the other axis and derive
+ * back through the cap.
+ */
+function squareDivisions (box, cols, rows) {
+  if (!box || !box.width || !box.height) return { cols, rows }
+  const ar = box.width / box.height
+  let c = clamp(cols, 1, MAX_COLS)
+  let r = Math.round(c / ar)
+
+  if (r < 2) {
+    r = 2
+    c = clamp(Math.round(r * ar), 1, MAX_COLS)
+    r = clamp(Math.round(c / ar), 1, MAX_ROWS)
+  } else if (r > MAX_ROWS) {
+    r = MAX_ROWS
+    c = clamp(Math.round(r * ar), 1, MAX_COLS)
+    r = clamp(Math.round(c / ar), 1, MAX_ROWS)
+  }
+  return { cols: c, rows: r }
+}
+
+/* ── the tree ─────────────────────────────────────────────────────────── */
+
+/** Nearest ancestor carrying a handle. A REPORT, never a redirect. */
+function ownerOf (el, attr) {
+  let p = el.parentElement
+  while (p && p !== document.body && !p.hasAttribute(attr)) p = p.parentElement
+  return p && p.hasAttribute(attr) ? p : null
+}
+
+function chainOf (el, attr) {
+  const names = []
+  let cur = ownerOf(el, attr)
+  while (cur) {
+    names.unshift(cur.getAttribute(attr))
+    cur = ownerOf(cur, attr)
+  }
+  return names
+}
+
+/** The owner's layout mode, and which axis it actually makes reachable. */
+function layoutOf (el) {
+  const cs = getComputedStyle(el)
+  if (cs.display === 'flex' || cs.display === 'inline-flex') {
+    const column = cs.flexDirection.startsWith('column')
+    return { mode: `flex ${column ? 'column' : 'row'}`, axis: column ? 'y' : 'x' }
+  }
+  if (cs.display === 'grid' || cs.display === 'inline-grid') return { mode: 'grid', axis: 'xy' }
+  return { mode: cs.display, axis: 'y' }
+}
+
+/* A cell says WHERE, never what CSS to change. When a cell is unreachable in
+ * the owner's mode, saying so is the feature — a diff that cannot work is worse
+ * than an honest no. */
+function reachability (layout) {
+  if (layout.axis === 'x') return 'Horizontal order reachable; vertical needs align/self.'
+  if (layout.axis === 'y') return "Vertical order reachable; horizontal needs the owner's layout mode changed."
+  return 'Both axes reachable via grid placement.'
+}
+
+/* ── breakpoint bands: read from the window, never chosen ─────────────── */
+
+export const DEFAULT_BANDS = [
+  { name: 'Mobile', min: 0, max: 559 },
+  { name: 'Tablet', min: 560, max: 859 },
+  { name: 'Laptop', min: 860, max: 1279 },
+  { name: 'Desktop', min: 1280, max: Infinity }
+]
+
+const bandFor = (w, bands) => bands.find((b) => w >= b.min && w <= b.max) || bands[bands.length - 1]
+
+/* ── the deliverable ──────────────────────────────────────────────────── */
+
+/** `StageModuleGroup @ 1440w · e8 → h7` */
+function formatSyncLine (handle, width, from, to) {
+  let s = `${handle} @ ${width}w`
+  if (from) {
+    s += ` · ${from}`
+    if (to) s += ` → ${to}`
+  }
+  return s
+}
+
+const IS_PROD = typeof process !== 'undefined' && process.env && process.env.NODE_ENV === 'production'
+
+export default function QuadrantSync ({
+  root = null,
+  attr = 'data-handle',
+  sourceAttr = 'data-source',
+  bands = DEFAULT_BANDS,
+  defaultDivisions = { cols: 8, rows: 8 },
+  initialHandle = '',
+  onSyncLine,
+  handleColor = 'var(--kol-accent-primary)',
+  pageColor = 'var(--kol-fg-40, color-mix(in srgb, var(--kol-surface-on-primary) 40%, transparent))',
+  enabled = !IS_PROD
+}) {
+  const [handle, setHandle] = useState(null)
+  const [cols, setCols] = useState(defaultDivisions.cols)
+  const [rows, setRows] = useState(defaultDivisions.rows)
+  const [fade, setFade] = useState(0.7)
+  const [showPage, setShowPage] = useState(false)
+  const [showHandle, setShowHandle] = useState(true)
+  const [showLabels, setShowLabels] = useState(true)
+  const [from, setFrom] = useState(null)
+  const [to, setTo] = useState(null)
+  const [settingsOpen, setSettingsOpen] = useState(false)
+  const [reportOpen, setReportOpen] = useState(false)
+  const [copied, setCopied] = useState(false)
+  const [width, setWidth] = useState(0)
+  const [, setTick] = useState(0)
+
+  const rootEl = root || (typeof document !== 'undefined' ? document.body : null)
+
+  /* re-measure whenever the world moves — the grid tracks the rendered layout */
+  useEffect(() => {
+    if (!enabled || typeof window === 'undefined') return undefined
+    const bump = () => {
+      setWidth(window.innerWidth)
+      setTick((t) => t + 1)
+    }
+    bump()
+    window.addEventListener('resize', bump)
+    window.addEventListener('scroll', bump, true)
+    const ro = typeof ResizeObserver !== 'undefined' ? new ResizeObserver(bump) : null
+    if (ro && rootEl) ro.observe(rootEl)
+    return () => {
+      window.removeEventListener('resize', bump)
+      window.removeEventListener('scroll', bump, true)
+      if (ro) ro.disconnect()
+    }
+  }, [enabled, rootEl])
+
+  /* click-to-name */
+  useEffect(() => {
+    if (!enabled || !rootEl) return undefined
+    const onClick = (e) => {
+      const t = e.target
+      if (!t || !t.closest || t.closest('[data-quadrant-chrome]')) return
+      const el = t.closest(`[${attr}]`)
+      if (!el) return
+      e.preventDefault()
+      e.stopPropagation()
+      setHandle(el)
+      setFrom(null)
+      setTo(null)
+    }
+    rootEl.addEventListener('click', onClick, true)
+    return () => rootEl.removeEventListener('click', onClick, true)
+  }, [enabled, rootEl, attr])
+
+  useEffect(() => {
+    if (!enabled || !initialHandle || handle || typeof document === 'undefined') return
+    const el = document.querySelector(`[${attr}="${initialHandle}"]`)
+    if (el) setHandle(el)
+  }, [enabled, initialHandle, handle, attr])
+
+  /* outline the handle and its owner, restoring whatever was there before */
+  useEffect(() => {
+    if (!enabled) return undefined
+    const own = handle ? ownerOf(handle, attr) : null
+    const prev = []
+    if (handle) {
+      prev.push([handle, handle.style.outline, handle.style.outlineOffset])
+      handle.style.outline = `2px solid ${handleColor}`
+      handle.style.outlineOffset = '1px'
+    }
+    if (own) {
+      prev.push([own, own.style.outline, own.style.outlineOffset])
+      own.style.outline = `2px dashed ${pageColor}`
+      own.style.outlineOffset = '5px'
+    }
+    return () => prev.forEach(([el, o, off]) => {
+      el.style.outline = o
+      el.style.outlineOffset = off
+    })
+  }, [enabled, handle, attr, handleColor, pageColor])
+
+  const owner = handle && enabled ? ownerOf(handle, attr) : null
+  const handleBox = handle && enabled ? rectOf(handle) : null
+  const rootBox = rootEl && enabled ? rectOf(rootEl) : null
+  const aspect = cellAspect(handleBox, cols, rows)
+
+  const syncLine = handle ? formatSyncLine(handle.getAttribute(attr), width, from, to) : null
+
+  useEffect(() => {
+    if (syncLine && onSyncLine) {
+      onSyncLine(syncLine, { handle: handle && handle.getAttribute(attr), width, from, to })
+    }
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [syncLine])
+
+  /** First click sets `from`, second sets `to`, third restarts. */
+  const choose = useCallback((id) => {
+    if (!from || to) { setFrom(id); setTo(null) } else if (id === from) setTo(null)
+    else setTo(id)
+  }, [from, to])
+
+  const applySquare = useCallback(() => {
+    if (!handleBox) return
+    const next = squareDivisions(handleBox, cols, rows)
+    setCols(next.cols)
+    setRows(next.rows)
+  }, [handleBox, cols, rows])
+
+  /* square once per newly-named element, so the grid STARTS square */
+  const squaredFor = useRef(null)
+  useEffect(() => {
+    if (!enabled || !handle) return
+    if (squaredFor.current === handle) return
+    squaredFor.current = handle
+    const next = squareDivisions(rectOf(handle), cols, rows)
+    setCols(next.cols)
+    setRows(next.rows)
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enabled, handle])
+
+  if (!enabled || typeof document === 'undefined') return null
+
+  const band = bandFor(width, bands)
+  const untreated = bands.filter((b) => b !== band).map((b) => b.name).join(' · ')
+  const labelsUsable = showLabels && cols <= 16 && rows <= 16
+  const anyGrid = showHandle || (showPage && handle !== rootEl)
+  const layout = owner ? layoutOf(owner) : null
+  const handleSource = handle ? handle.getAttribute(sourceAttr) || 'local' : null
+  const ownerSource = owner ? owner.getAttribute(sourceAttr) || 'local' : null
+  const BAR = 46
+
+  const renderGrid = (box, kind) => {
+    const live = kind === 'handle'
+    const cells = []
+    for (let r = 0; r < rows; r += 1) {
+      for (let c = 0; c < cols; c += 1) {
+        const id = cellLabel(c, r)
+        const picked = id === to ? 0.4 : id === from ? 0.22 : 0
+        cells.push(
+          <button
+            key={id}
+            type="button"
+            data-quadrant-chrome=""
+            aria-label={live ? `Cell ${id}` : undefined}
+            tabIndex={live ? 0 : -1}
+            onClick={live ? () => choose(id) : undefined}
+            className="absolute m-0 p-0 block text-left border-0"
+            style={{
+              left: `${(c / cols) * 100}%`,
+              top: `${(r / rows) * 100}%`,
+              width: `${100 / cols}%`,
+              height: `${100 / rows}%`,
+              borderRight: c === cols - 1 ? 'none' : '1px solid currentColor',
+              borderBottom: r === rows - 1 ? 'none' : '1px solid currentColor',
+              background: picked ? `color-mix(in srgb, currentColor ${picked * 100}%, transparent)` : 'transparent',
+              color: 'inherit',
+              cursor: live ? 'pointer' : 'default'
+            }}
+          >
+            {labelsUsable && (
+              <span
+                className="kol-helper-8 block"
+                style={{ padding: '2px 3px', fontWeight: picked ? 700 : 500 }}
+              >
+                {id}
+              </span>
+            )}
+          </button>
+        )
+      }
+    }
+    return (
+      <div
+        key={kind}
+        style={{
+          position: 'absolute',
+          left: box.left,
+          top: box.top,
+          width: box.width,
+          height: box.height,
+          color: live ? handleColor : pageColor,
+          opacity: live ? fade : fade * 0.32,
+          pointerEvents: live ? 'auto' : 'none'
+        }}
+      >
+        {live && <span style={{ position: 'absolute', inset: 0, border: '1px solid currentColor', pointerEvents: 'none' }} />}
+        {cells}
+      </div>
+    )
+  }
+
+  const q = (n, title, value, sub, subClass = 'text-fg-48') => (
+    <div>
+      <div className="kol-helper-8 text-fg-40" style={{ marginBottom: 5, letterSpacing: '0.12em' }}>
+        <span style={{ color: handleColor }}>{n}</span>{'  '}{title.toUpperCase()}
+      </div>
+      <div className="kol-mono-12 text-fg-96" style={{ overflowWrap: 'anywhere' }}>{value}</div>
+      {sub ? <div className={`kol-mono-10 ${subClass}`} style={{ marginTop: 3, overflowWrap: 'anywhere' }}>{sub}</div> : null}
+    </div>
+  )
+
+  return (
+    <div data-quadrant-chrome="" className="kol-quadrant-sync">
+      {/* ── overlays ── */}
+      <div style={{ position: 'fixed', inset: 0, pointerEvents: 'none', zIndex: 'var(--kol-z-nav, 1000)' }}>
+        {showPage && rootBox && handle !== rootEl ? renderGrid(rootBox, 'page') : null}
+        {showHandle && handleBox ? renderGrid(handleBox, 'handle') : null}
+      </div>
+
+      {/* ── settings: preferences only, never a report on the view ── */}
+      <aside
+        className="bg-surface-primary border border-fg-16"
+        style={{
+          position: 'fixed', top: 14, right: 14, width: 250, borderRadius: 4,
+          zIndex: 'var(--kol-z-tooltip, 300)'
+        }}
+      >
+        <div
+          className="flex items-center justify-between"
+          style={{ gap: 8, padding: '8px 10px', borderBottom: settingsOpen ? '1px solid var(--kol-border-default)' : 'none' }}
+        >
+          <span className="kol-helper-10 text-fg-40">GRID SETTINGS</span>
+          <button
+            type="button"
+            className="kol-helper-12 text-fg-64 border border-fg-16"
+            aria-expanded={settingsOpen}
+            aria-label={settingsOpen ? 'Close grid settings' : 'Open grid settings'}
+            onClick={() => setSettingsOpen((v) => !v)}
+            style={{ minWidth: 21, height: 19, borderRadius: 4, background: 'transparent', cursor: 'pointer' }}
+          >
+            {settingsOpen ? '–' : '+'}
+          </button>
+        </div>
+
+        {settingsOpen && (
+          <div className="flex flex-col" style={{ gap: 12, padding: '11px 10px 12px' }}>
+            <div>
+              <div className="kol-helper-8 text-fg-40" style={{ marginBottom: 6, letterSpacing: '0.11em' }}>DIVISIONS</div>
+              <div className="flex items-center" style={{ gap: 6 }}>
+                <input
+                  type="number" min={1} max={MAX_COLS} value={cols} aria-label="Columns"
+                  onChange={(e) => setCols(clamp(parseInt(e.target.value, 10) || 1, 1, MAX_COLS))}
+                  className="kol-mono-12 text-fg-96 bg-fg-04 border border-fg-16"
+                  style={{ width: 52, padding: '5px 6px', textAlign: 'center', borderRadius: 4 }}
+                />
+                <span className="kol-helper-10 text-fg-40">×</span>
+                <input
+                  type="number" min={1} max={MAX_ROWS} value={rows} aria-label="Rows"
+                  onChange={(e) => setRows(clamp(parseInt(e.target.value, 10) || 1, 1, MAX_ROWS))}
+                  className="kol-mono-12 text-fg-96 bg-fg-04 border border-fg-16"
+                  style={{ width: 52, padding: '5px 6px', textAlign: 'center', borderRadius: 4 }}
+                />
+                <button
+                  type="button" onClick={applySquare}
+                  title="Set divisions so cells come out square at the current size"
+                  className="kol-helper-10 text-fg-96 border border-fg-16"
+                  style={{ marginLeft: 'auto', padding: '5px 9px', borderRadius: 4, background: 'transparent', cursor: 'pointer' }}
+                >
+                  square
+                </button>
+              </div>
+              {aspect && (
+                <div className="kol-mono-10 text-fg-48" style={{ marginTop: 6 }}>
+                  Cell{' '}
+                  <span className="text-fg-96">{Math.round(aspect.cw)}×{Math.round(aspect.ch)}</span>{' · '}
+                  {aspect.isSquare
+                    ? <span style={{ color: 'var(--ui-success)' }}>square</span>
+                    : `${aspect.ratio.toFixed(2)}:1`}
+                </div>
+              )}
+            </div>
+
+            <div>
+              <label className="kol-helper-8 text-fg-40 block" htmlFor="kq-fade" style={{ marginBottom: 6, letterSpacing: '0.11em' }}>FADE</label>
+              <input
+                id="kq-fade" type="range" min={15} max={100} value={Math.round(fade * 100)}
+                onChange={(e) => setFade(Number(e.target.value) / 100)}
+                style={{ width: '100%', accentColor: handleColor, display: 'block' }}
+              />
+            </div>
+
+            {/* page sits above handle — the page is the parent */}
+            <div className="flex flex-col" style={{ gap: 7 }}>
+              <label className="kol-mono-12 text-fg-96 flex items-center" style={{ gap: 7, cursor: 'pointer', userSelect: 'none' }}>
+                <input type="checkbox" checked={showPage} onChange={(e) => setShowPage(e.target.checked)} style={{ accentColor: handleColor, width: 12, height: 12, margin: 0 }} />
+                <span style={{ width: 7, height: 7, borderRadius: 2, background: pageColor, flex: 'none' }} />
+                Page grid
+              </label>
+              <label className="kol-mono-12 text-fg-96 flex items-center" style={{ gap: 7, cursor: 'pointer', userSelect: 'none' }}>
+                <input type="checkbox" checked={showHandle} onChange={(e) => setShowHandle(e.target.checked)} style={{ accentColor: handleColor, width: 12, height: 12, margin: 0 }} />
+                <span style={{ width: 7, height: 7, borderRadius: 2, background: handleColor, flex: 'none' }} />
+                Handle grid
+              </label>
+              <div style={{ borderTop: '1px solid var(--kol-border-default)', margin: '2px 0 1px' }} />
+              <label
+                className="kol-mono-12 text-fg-96 flex items-center"
+                style={{ gap: 7, cursor: anyGrid ? 'pointer' : 'not-allowed', userSelect: 'none', opacity: anyGrid ? 1 : 0.38 }}
+              >
+                <input type="checkbox" checked={showLabels} disabled={!anyGrid} onChange={(e) => setShowLabels(e.target.checked)} style={{ accentColor: handleColor, width: 12, height: 12, margin: 0 }} />
+                Cell labels
+              </label>
+            </div>
+          </div>
+        )}
+      </aside>
+
+      {/* ── report: what is in view. a banner, not a setting ── */}
+      {reportOpen && (
+        <div
+          className="bg-surface-secondary border-t border-fg-16"
+          style={{
+            position: 'fixed', left: 0, right: 0, bottom: BAR, padding: '14px 18px',
+            display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(220px, 1fr))', gap: 22,
+            zIndex: 'var(--kol-z-tooltip, 300)'
+          }}
+        >
+          {q(1, 'Looking at', handle ? handle.getAttribute(attr) : '—',
+            <>{width}w · <span className="text-fg-96">{band.name}</span><br />Untreated: {untreated}</>)}
+          {q(2, 'Lives in',
+            handle ? [...chainOf(handle, attr), handle.getAttribute(attr)].join(' › ') : '—',
+            handle && owner ? <>Spans <span className="text-fg-96">{owner.getAttribute(attr)}:{spanOf(handleBox, rectOf(owner), cols, rows)}</span></> : null)}
+          {q(3, 'Owned by',
+            handle
+              ? <span className="kol-helper-10" style={{ padding: '1px 6px', borderRadius: 4, background: handleSource === 'local' ? 'color-mix(in srgb, var(--ui-success) 20%, transparent)' : 'color-mix(in srgb, var(--ui-warning) 20%, transparent)', color: handleSource === 'local' ? 'var(--ui-success)' : 'var(--ui-warning)' }}>{handleSource}</span>
+              : '—',
+            ownerSource && ownerSource !== 'local'
+              ? <>Owner ships from <span style={{ color: 'var(--ui-warning)' }}>{ownerSource}</span> — local shim now, DS ticket with the diff</>
+              : owner ? <>Owner <span style={{ color: 'var(--ui-success)' }}>{owner.getAttribute(attr)}</span> is local — editable here</> : null)}
+          {q(4, 'Change via',
+            owner && layout ? `${owner.getAttribute(attr)} · ${layout.mode}` : handle ? 'page root' : '—',
+            layout ? reachability(layout) : handle ? 'Nothing above it decides its position.' : null)}
+        </div>
+      )}
+
+      {/* ── the deliverable ── */}
+      <div
+        className="bg-surface-primary border-t border-fg-16 flex items-center"
+        style={{ position: 'fixed', left: 0, right: 0, bottom: 0, height: BAR, padding: '0 16px', gap: 13, zIndex: 'var(--kol-z-tooltip, 300)' }}
+      >
+        <span className="kol-helper-8 text-fg-40" style={{ letterSpacing: '0.14em', flex: 'none' }}>SYNC LINE</span>
+        <div className="kol-mono-14 text-fg-96" style={{ flex: '1 1 auto', minWidth: 0, overflowX: 'auto', whiteSpace: 'nowrap' }}>
+          {handle ? (
+            <>
+              <span style={{ color: handleColor }}>{handle.getAttribute(attr)}</span>
+              <span className="text-fg-40"> @ </span>
+              <span className="text-fg-64">{width}w</span>
+              {from ? (
+                <>
+                  <span className="text-fg-40"> · </span>{from}
+                  {to
+                    ? <><span className="text-fg-40"> → </span><span style={{ color: handleColor }}>{to}</span></>
+                    : <span className="text-fg-40"> → pick a destination</span>}
+                </>
+              ) : showHandle ? <span className="text-fg-40"> · pick a cell</span> : null}
+            </>
+          ) : <span className="text-fg-40">Click an element to name it.</span>}
+        </div>
+        <div className="flex" style={{ gap: 6, flex: 'none' }}>
+          <button
+            type="button" aria-expanded={reportOpen} onClick={() => setReportOpen((v) => !v)}
+            className="kol-helper-12 border border-fg-16"
+            style={{ padding: '6px 12px', borderRadius: 4, background: 'transparent', cursor: 'pointer', color: reportOpen ? handleColor : 'var(--kol-surface-on-primary)' }}
+          >
+            Report
+          </button>
+          <button
+            type="button"
+            onClick={() => { setHandle(null); setFrom(null); setTo(null) }}
+            className="kol-helper-12 text-fg-96 border border-fg-16"
+            style={{ padding: '6px 12px', borderRadius: 4, background: 'transparent', cursor: 'pointer' }}
+          >
+            Clear
+          </button>
+          <button
+            type="button" disabled={!syncLine}
+            onClick={() => {
+              if (!syncLine || !navigator.clipboard) return
+              navigator.clipboard.writeText(syncLine).catch(() => {}).then(() => {
+                setCopied(true)
+                window.setTimeout(() => setCopied(false), 1400)
+              })
+            }}
+            className="kol-helper-12"
+            style={{
+              padding: '6px 12px', borderRadius: 4, cursor: syncLine ? 'pointer' : 'default',
+              background: handleColor, color: 'var(--kol-accent-on-primary)',
+              border: `1px solid ${handleColor}`, opacity: syncLine ? 1 : 0.45
+            }}
+          >
+            {copied ? 'Copied' : 'Copy'}
+          </button>
+        </div>
+      </div>
+    </div>
+  )
+}