@volter/editor-core 0.5.57

package/src/components/AssetEditorShell.tsx

@@ -0,0 +1,216 @@
+/**
+ * The asset document shell — the frame an open asset lives in, and NOTHING
+ * about how it is inspected.
+ *
+ * "What is an asset in three.js but a hierarchical group of other three.js
+ * assets" (owner, 2026-08-07). An asset document is the three paradigm scoped
+ * to a SUBTREE — Unity's prefab-isolation mode: same viewport, same hierarchy,
+ * same inspector box, only the root changed. So the ordinary inspector rides
+ * over an asset document exactly as it rides over the scene: the same box in
+ * the same corner, draggable, minimizable, expandable to the same column, with
+ * the same per-surface preference (`inspection/display.ts` resolves it for the
+ * `asset-lab` surface like any other). This shell renders none of it.
+ *
+ * What it owns is the two things that make the document a SUBJECT PRODUCER:
+ *
+ *  - it activates the asset-editor context, which is what makes the active
+ *    inspection surface `asset-lab` (`inspection/active-surface.ts`);
+ *  - it registers the document's SELECTION CONTEXT and publishes the
+ *    document's own subject description (`inspection/document-subject.ts`).
+ *
+ * The selection context is the load-bearing half, and every asset document
+ * registers one even with nothing to select. Registering it is how a document
+ * says "I am the subject": without it the Inspector falls back to the shared
+ * entity selection, and an image viewer would show whatever was picked in the
+ * scene before it was opened. A document with live authoring of its own (the
+ * Object3D editor) passes `selection` and its picked part flows through; a
+ * document without passes nothing and gets `{adapter: null, nodeId: null}`,
+ * which resolves to its own identity floor.
+ *
+ * The identity row is where that floor lives: even a document with no sections
+ * at all says what it is, what kind it is, and where it came from — and no
+ * section of its own stands in for that row, because identity is a property of
+ * the SUBJECT (`inspection/model.ts`).
+ */
+
+import { type ReactNode, useEffect, useRef } from 'react';
+import { activateAssetEditorContext } from '../asset-editor-context';
+import { publishDocumentInspectionSubject } from '../inspection/document-subject';
+import type { InspectionSection } from '../inspection/model';
+import type { NullInspectionSubject } from '../inspection/null-subject';
+import {
+  registerWorkspaceDocumentSelection,
+  type WorkspaceDocumentSelection,
+} from '../workspace-document-registry';
+
+/** What a document with no authoring of its own selects: itself. */
+const DOCUMENT_IS_THE_SUBJECT: WorkspaceDocumentSelection = { adapter: null, nodeId: null };
+
+/**
+ * The part of a document subject whose change can alter the Inspector's
+ * structure. Function identities deliberately stay out of this key: render
+ * functions and field IO are read through `descriptionRef` below, so a parent
+ * render updates them without feeding the Inspector's own notification back
+ * into another publication.
+ */
+function subjectPublicationKey(subject: NullInspectionSubject): string {
+  return JSON.stringify({
+    id: subject.id,
+    title: subject.title,
+    hint: subject.hint,
+    kindLabel: subject.kindLabel,
+    note: subject.note,
+    sections: subject.sections.map((section) => ({
+      id: section.id,
+      title: section.title,
+      order: section.order,
+      description: section.description,
+      defaultOpen: section.defaultOpen,
+      testId: section.testId,
+      keepMounted: section.keepMounted,
+      railGroup: section.railGroup,
+      bodyKind: section.body.kind,
+    })),
+    quickActions: subject.quickActions?.map((action) => ({
+      id: action.id,
+      title: action.title,
+      label: action.label,
+      placement: action.placement,
+      pressed: action.pressed,
+      disabled: action.disabled,
+    })),
+  });
+}
+
+/**
+ * The three optional props below are spelled `?: T | undefined` rather than
+ * `?: T`, because `AssetEditorShell` PASSES ITS OWN THROUGH: under
+ * `exactOptionalPropertyTypes` an explicit `undefined` is not the same as an
+ * absent key, so `sections={sections}` on a shell whose own `sections` is
+ * optional is a type error against `?: T`. Undefined is a value this component
+ * genuinely handles (`sections ?? []`, `status &&`, `selection?.()`) — the
+ * widened type says that, where a conditional spread at the one call site would
+ * only hide it.
+ */
+interface AssetEditorSubjectProps {
+  documentId: string;
+  active?: boolean;
+  type: string;
+  title: string;
+  /** This document's own inspection sections, for the subject it publishes
+   *  when nothing inside it is picked. Identity (name/kind/provenance) is
+   *  composed from `title`/`type`/`status` — a document always has one, even
+   *  with no sections at all. */
+  sections?: readonly InspectionSection[] | undefined;
+  status?: string | undefined;
+  /** What is picked INSIDE this document, for a document with authoring of
+   *  its own. Read on demand (the registry calls it), so it may close over
+   *  live state that changes without re-registering. */
+  selection?: (() => WorkspaceDocumentSelection | null) | undefined;
+}
+
+/**
+ * The non-visual half of an Asset Lab document. Kept separate from the frame
+ * so project-owned contribution UIs can publish the standard subject without
+ * sending React elements across the project/editor runtime boundary.
+ */
+export function AssetEditorSubject({
+  documentId,
+  active = true,
+  type,
+  title,
+  sections,
+  status,
+  selection,
+}: AssetEditorSubjectProps) {
+  useEffect(() => {
+    if (!active) return;
+    return activateAssetEditorContext({
+      documentId,
+      title,
+      type,
+      ...(status ? { status } : {}),
+    });
+  }, [active, documentId, status, title, type]);
+
+  // ONE owner for this document's selection context (the registry keys by
+  // document id, so a second registrant would silently displace the first and
+  // take the entry with it on unmount). The ref keeps the registration stable
+  // while the provider it delegates to is free to change every render.
+  const selectionRef = useRef(selection);
+  selectionRef.current = selection;
+  useEffect(() => {
+    if (!active) return;
+    return registerWorkspaceDocumentSelection(
+      documentId,
+      () => selectionRef.current?.() ?? DOCUMENT_IS_THE_SUBJECT,
+    );
+  }, [active, documentId]);
+
+  // The document's subject DESCRIPTION — identity plus its own sections, in
+  // the same shape every surface's `describeSubject(null)` answer takes.
+  // The latest description is read on demand, so section IO closures remain
+  // live without publishing on every render. Publishing itself notifies the
+  // Inspector; doing it after every Inspector-driven parent render creates a
+  // notification -> render -> publication loop and React eventually throws
+  // "Maximum update depth exceeded" when an Object3D prefab opens.
+  const description: NullInspectionSubject = {
+    id: documentId,
+    title,
+    // `kindLabel` is what earns the composed identity ROW, and a document
+    // always names its kind: an Asset Lab document IS a thing with a name, a
+    // type and a provenance.
+    kindLabel: type,
+    ...(status ? { note: { text: status, testId: 'asset-editor-status' } } : {}),
+    sections: sections ?? [],
+  };
+  const descriptionRef = useRef(description);
+  descriptionRef.current = description;
+  const publicationKey = subjectPublicationKey(description);
+  useEffect(() => {
+    if (!active) return;
+    return publishDocumentInspectionSubject(documentId, () => descriptionRef.current);
+  }, [active, documentId, publicationKey]);
+
+  return null;
+}
+
+export function AssetEditorShell({
+  documentId,
+  active = true,
+  type,
+  title,
+  sections,
+  status,
+  fill = false,
+  selection,
+  children,
+}: AssetEditorSubjectProps & {
+  /** The child owns the whole viewport box and clips itself (a 3D canvas),
+   *  rather than flowing and scrolling inside it. */
+  fill?: boolean;
+  children: ReactNode;
+}) {
+  return (
+    <section
+      className="vgai-asset-editor"
+      data-testid={`asset-editor:${type}`}
+      aria-label={`${title} Asset Editor`}
+    >
+      <AssetEditorSubject
+        documentId={documentId}
+        active={active}
+        type={type}
+        title={title}
+        sections={sections}
+        status={status}
+        selection={selection}
+      />
+      <main
+        className={`vgai-asset-editor__viewport${fill ? ' vgai-asset-editor__viewport--fill' : ''}`}
+      >
+        {children}
+      </main>
+    </section>
+  );
+}

package/src/components/AssetInspectorToolSection.tsx

@@ -0,0 +1,124 @@
+import type {
+  ToolAssetInspectorAction,
+  ToolAssetInspectorContributionProps,
+  ToolContributionAsset,
+} from '@volter/editor-sdk/contributions';
+import { EditorIcon, editorIcons, groupLabelStyle } from '@volter/editor-sdk/widgets';
+import { type ComponentType, useCallback, useEffect, useRef, useSyncExternalStore } from 'react';
+import { accountVersion, contributionAccount, subscribeAccount } from '../account';
+import { clearAssetInspectorActions, setAssetInspectorActions } from '../asset-inspector-actions';
+import {
+  assetSelectionVersion,
+  getSelectedAsset,
+  subscribeAssetSelection,
+} from '../asset-selection';
+import { notify } from '../editor-notifications';
+import { beginPageWork } from '../play-boot-phase';
+import type { ProjectToolCatalogEntry } from '../project-tools';
+import {
+  subscribeToolContributionPlay,
+  toolContributionPlay,
+  toolContributionPlayKey,
+} from '../tool-contribution-play';
+import { getToolContributionClient } from '../tool-loader';
+import { toolContributionSurfaces } from './ToolContributionSurfaces';
+import { ToolErrorBoundary } from './ToolHost';
+
+function selectedAsset(): ToolContributionAsset | null {
+  const asset = getSelectedAsset();
+  if (!asset) return null;
+  return {
+    path: asset.path,
+    name: asset.name,
+    kind: asset.kind,
+    origin: asset.origin ?? 'project',
+    ...(asset.sourcePath ? { sourcePath: asset.sourcePath } : {}),
+  };
+}
+
+/** Publish this section's verbs while it is mounted, and forget them when it
+ *  goes away — a list that outlived its section would be a verb the human
+ *  can no longer see (`asset-inspector-actions.ts`). */
+function useAssetInspectorActions(
+  id: string,
+  assetPath: string | null,
+): (actions: readonly ToolAssetInspectorAction[]) => void {
+  useEffect(() => () => clearAssetInspectorActions(id), [id]);
+  return useCallback(
+    (actions: readonly ToolAssetInspectorAction[]) => {
+      if (assetPath === null) return;
+      setAssetInspectorActions(id, assetPath, actions);
+    },
+    [id, assetPath],
+  );
+}
+
+export function AssetInspectorToolSection({
+  id,
+  title,
+  file,
+  tool,
+  Component,
+}: {
+  id: string;
+  title: string;
+  file: string;
+  tool?: ProjectToolCatalogEntry | undefined;
+  Component: ComponentType<ToolAssetInspectorContributionProps>;
+}) {
+  useSyncExternalStore(subscribeAssetSelection, assetSelectionVersion);
+  useSyncExternalStore(subscribeAccount, accountVersion, accountVersion);
+  useSyncExternalStore(
+    subscribeToolContributionPlay,
+    toolContributionPlayKey,
+    toolContributionPlayKey,
+  );
+  const asset = selectedAsset();
+  const setActions = useAssetInspectorActions(id, asset?.path ?? null);
+  // The same two host doors ToolHost hands every other contribution: a
+  // notice card keyed by title, and the main-thread work announcement. This
+  // section assembled its own props and had neither, so a model probe that
+  // spun the page for 45 s stalled every command with no phase named
+  // (2026-09-06).
+  const endWorkRef = useRef<(() => void) | null>(null);
+  const work = useCallback((label: string | null) => {
+    endWorkRef.current?.();
+    endWorkRef.current =
+      label === null ? null : beginPageWork(`building ${label.replace(/^building /, '')}`);
+  }, []);
+  useEffect(() => () => endWorkRef.current?.(), []);
+  const notifyCard = useCallback(
+    (notice: { tone: 'info' | 'warning' | 'error'; title: string; detail?: string }) =>
+      notify({
+        ...notice,
+        id: `contribution:${id}:${notice.title}`,
+        ...(notice.tone === 'warning' ? { fades: true } : {}),
+      }),
+    [id],
+  );
+  return (
+    <div
+      data-testid={`asset-inspector-tool-${id}`}
+      style={{ padding: 8, borderTop: '1px solid var(--vgai-structural-divider)', marginTop: 4 }}
+    >
+      <div style={{ ...groupLabelStyle, marginBottom: 4 }}>
+        <EditorIcon icon={editorIcons.tool.extension} tone="muted" style={{ marginRight: 4 }} />
+        {title}
+      </div>
+      <ToolErrorBoundary file={file}>
+        <Component
+          {...(tool ? { tool } : {})}
+          contributionId={id.slice(id.lastIndexOf(':') + 1)}
+          client={getToolContributionClient()}
+          surfaces={toolContributionSurfaces}
+          account={contributionAccount()}
+          play={toolContributionPlay()}
+          asset={asset}
+          setActions={setActions}
+          notify={notifyCard}
+          work={work}
+        />
+      </ToolErrorBoundary>
+    </div>
+  );
+}

package/src/components/BoardRulers.tsx

@@ -0,0 +1,354 @@
+/**
+ * RULERS + PERSISTENT GUIDES on the DOM component board (design ledger:
+ * snapping/guides). Figma's gesture grammar: drag OFF the top ruler to place
+ * a horizontal guide, off the left ruler for a vertical one; drag a guide to
+ * move it; drop it back on its ruler (or double-click it) to delete. Guides
+ * live in BOARD coordinates and persist per project+document
+ * (`board-guides.ts`); rendering maps them through the live pan/zoom.
+ */
+
+import { THEME } from '@volter/editor-sdk/widgets';
+import { type ReactElement, useEffect, useRef, useState, useSyncExternalStore } from 'react';
+import {
+  activeBreakpoint,
+  setActiveBreakpoint,
+  subscribeBreakpoint,
+} from '../authoring/breakpoint-state';
+import { getRootPan, subscribeRootPan } from '../authoring/world-pan-state';
+import {
+  addBoardGuide,
+  type BoardGuide,
+  boardGuides,
+  moveBoardGuide,
+  registerBoardGuideTransform,
+  removeBoardGuide,
+  subscribeBoardGuides,
+} from './board-guides';
+
+const RULER = 16;
+const GUIDE_COLOR = 'rgba(255, 82, 82, 0.9)';
+const RULER_BG = 'rgba(18, 22, 26, 0.92)';
+const TICK_COLOR = 'rgba(255, 255, 255, 0.28)';
+
+/** A round tick step that keeps labels ~≥60px apart at the current zoom. */
+function tickStep(zoom: number): number {
+  const steps = [10, 25, 50, 100, 250, 500, 1000, 2500, 5000];
+  return steps.find((s) => s * zoom >= 60) ?? 10000;
+}
+
+function formatTick(v: number): string {
+  return Math.abs(v) >= 1000 ? `${v / 1000}k` : String(v);
+}
+
+interface DragState {
+  kind: 'place' | 'move';
+  axis: BoardGuide['axis'];
+  id: string | null;
+  /** Container-local pointer coordinate along the guide's axis. */
+  at: number;
+}
+
+export function BoardRulers({
+  docId,
+  containerRef,
+}: {
+  docId: string;
+  containerRef: React.RefObject<HTMLDivElement | null>;
+}): ReactElement {
+  const view = useSyncExternalStore(subscribeRootPan, getRootPan);
+  const guides = useSyncExternalStore(subscribeBoardGuides, () => boardGuides(docId));
+  const [drag, setDrag] = useState<DragState | null>(null);
+  const layerRef = useRef<HTMLDivElement | null>(null);
+
+  // Register the live board transform so gesture overlays can convert guide
+  // coordinates into their own space (see board-guides.ts). Re-measured on
+  // every pan/zoom/guide change; a pure window resize between pans can leave
+  // it briefly stale, which only softens snapping — never breaks a write.
+  useEffect(() => {
+    const el = containerRef.current;
+    if (!el) return;
+    const rect = el.getBoundingClientRect();
+    registerBoardGuideTransform(docId, {
+      originX: rect.left,
+      originY: rect.top,
+      panX: view.x,
+      panY: view.y,
+      zoom: view.zoom,
+    });
+    return () => registerBoardGuideTransform(docId, null);
+  }, [docId, containerRef, view.x, view.y, view.zoom]);
+
+  const toBoard = (local: number, axis: BoardGuide['axis']): number =>
+    Math.round((local - (axis === 'x' ? view.x : view.y)) / view.zoom);
+  const toLocal = (value: number, axis: BoardGuide['axis']): number =>
+    (axis === 'x' ? view.x : view.y) + value * view.zoom;
+
+  const localPoint = (e: { clientX: number; clientY: number }): { x: number; y: number } => {
+    const rect = containerRef.current?.getBoundingClientRect();
+    return rect ? { x: e.clientX - rect.left, y: e.clientY - rect.top } : { x: 0, y: 0 };
+  };
+
+  const beginPlace = (axis: BoardGuide['axis']) => (e: React.PointerEvent) => {
+    e.preventDefault();
+    (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+    const p = localPoint(e);
+    setDrag({ kind: 'place', axis, id: null, at: axis === 'x' ? p.x : p.y });
+  };
+
+  const beginMove = (guide: BoardGuide) => (e: React.PointerEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    (e.currentTarget as HTMLElement).setPointerCapture(e.pointerId);
+    const p = localPoint(e);
+    setDrag({ kind: 'move', axis: guide.axis, id: guide.id, at: guide.axis === 'x' ? p.x : p.y });
+  };
+
+  const onDragMove = (e: React.PointerEvent): void => {
+    if (!drag) return;
+    const p = localPoint(e);
+    const at = drag.axis === 'x' ? p.x : p.y;
+    setDrag({ ...drag, at });
+    if (drag.kind === 'move' && drag.id) moveBoardGuide(docId, drag.id, toBoard(at, drag.axis));
+  };
+
+  const onDragEnd = (e: React.PointerEvent): void => {
+    if (!drag) return;
+    const p = localPoint(e);
+    const at = drag.axis === 'x' ? p.x : p.y;
+    const overRuler = at <= RULER;
+    if (drag.kind === 'place') {
+      if (!overRuler) addBoardGuide(docId, drag.axis, toBoard(at, drag.axis));
+    } else if (drag.id) {
+      if (overRuler) removeBoardGuide(docId, drag.id);
+      else moveBoardGuide(docId, drag.id, toBoard(at, drag.axis));
+    }
+    setDrag(null);
+  };
+
+  // Visible tick range along one axis.
+  const ticks = (axis: BoardGuide['axis']): number[] => {
+    const el = containerRef.current;
+    const extent = el ? (axis === 'x' ? el.clientWidth : el.clientHeight) : 0;
+    const step = tickStep(view.zoom);
+    const first = Math.ceil(toBoard(RULER, axis) / step) * step;
+    const last = toBoard(extent, axis);
+    const out: number[] = [];
+    for (let v = first; v <= last && out.length < 200; v += step) out.push(v);
+    return out;
+  };
+
+  const rulerStyle: React.CSSProperties = {
+    position: 'absolute',
+    background: RULER_BG,
+    zIndex: 61,
+    userSelect: 'none',
+    touchAction: 'none',
+    overflow: 'hidden',
+  };
+
+  return (
+    <div
+      ref={layerRef}
+      data-testid="board-rulers"
+      style={{ position: 'absolute', inset: 0, pointerEvents: 'none', zIndex: 60 }}
+      onPointerMove={onDragMove}
+      onPointerUp={onDragEnd}
+    >
+      {/* Placed guides. */}
+      {guides.map((guide) => {
+        const local = toLocal(guide.value, guide.axis);
+        const vertical = guide.axis === 'x';
+        return (
+          <div
+            key={guide.id}
+            data-testid={`board-guide-${guide.axis}-${guide.value}`}
+            title={`${guide.axis} = ${guide.value} — drag to move, drop on the ruler or double-click to remove`}
+            onPointerDown={beginMove(guide)}
+            onPointerMove={onDragMove}
+            onPointerUp={onDragEnd}
+            onDoubleClick={() => removeBoardGuide(docId, guide.id)}
+            style={{
+              position: 'absolute',
+              pointerEvents: 'auto',
+              cursor: vertical ? 'col-resize' : 'row-resize',
+              zIndex: 60,
+              ...(vertical
+                ? { left: local - 2, top: 0, bottom: 0, width: 5 }
+                : { top: local - 2, left: 0, right: 0, height: 5 }),
+            }}
+          >
+            <div
+              style={{
+                position: 'absolute',
+                background: GUIDE_COLOR,
+                ...(vertical
+                  ? { left: 2, top: 0, bottom: 0, width: 1 }
+                  : { top: 2, left: 0, right: 0, height: 1 }),
+              }}
+            />
+          </div>
+        );
+      })}
+      {/* Placement/move preview line. */}
+      {drag && (
+        <div
+          style={{
+            position: 'absolute',
+            background: GUIDE_COLOR,
+            zIndex: 62,
+            ...(drag.axis === 'x'
+              ? { left: drag.at, top: 0, bottom: 0, width: 1 }
+              : { top: drag.at, left: 0, right: 0, height: 1 }),
+          }}
+        >
+          <span
+            style={{
+              position: 'absolute',
+              ...(drag.axis === 'x' ? { top: RULER + 4, left: 4 } : { left: RULER + 4, top: 4 }),
+              fontSize: 9,
+              fontFamily: 'ui-monospace, monospace',
+              color: GUIDE_COLOR,
+              background: RULER_BG,
+              padding: '1px 3px',
+              borderRadius: 3,
+              whiteSpace: 'nowrap',
+            }}
+          >
+            {toBoard(drag.at, drag.axis)}
+          </span>
+        </div>
+      )}
+      {/* Top ruler — places HORIZONTAL guides? No: Figma grammar — the top
+          ruler measures X, and dragging DOWN from it places a horizontal
+          guide; the left ruler measures Y and places vertical guides. We
+          follow the measurement axis for ticks and Figma's pull direction
+          for placement. */}
+      <div
+        data-testid="board-ruler-top"
+        onPointerDown={beginPlace('y')}
+        style={{
+          ...rulerStyle,
+          top: 0,
+          left: RULER,
+          right: 0,
+          height: RULER,
+          cursor: 'row-resize',
+          pointerEvents: 'auto',
+        }}
+      >
+        {ticks('x').map((v) => (
+          <span
+            key={v}
+            style={{
+              position: 'absolute',
+              left: toLocal(v, 'x'),
+              bottom: 0,
+              borderLeft: `1px solid ${TICK_COLOR}`,
+              height: 5,
+            }}
+          >
+            <span
+              style={{
+                position: 'absolute',
+                left: 2,
+                bottom: 3,
+                fontSize: 8,
+                color: TICK_COLOR,
+                fontFamily: 'ui-monospace, monospace',
+              }}
+            >
+              {formatTick(v)}
+            </span>
+          </span>
+        ))}
+      </div>
+      {/* Left ruler. */}
+      <div
+        data-testid="board-ruler-left"
+        onPointerDown={beginPlace('x')}
+        style={{
+          ...rulerStyle,
+          top: RULER,
+          left: 0,
+          bottom: 0,
+          width: RULER,
+          cursor: 'col-resize',
+          pointerEvents: 'auto',
+        }}
+      >
+        {ticks('y').map((v) => (
+          <span
+            key={v}
+            style={{
+              position: 'absolute',
+              top: toLocal(v, 'y'),
+              right: 0,
+              borderTop: `1px solid ${TICK_COLOR}`,
+              width: 5,
+            }}
+          >
+            <span
+              style={{
+                position: 'absolute',
+                top: 1,
+                right: 3,
+                fontSize: 8,
+                color: TICK_COLOR,
+                fontFamily: 'ui-monospace, monospace',
+                writingMode: 'vertical-rl',
+              }}
+            >
+              {formatTick(v)}
+            </span>
+          </span>
+        ))}
+      </div>
+      <BreakpointArmedPill />
+      {/* Corner square. */}
+      <div
+        style={{
+          ...rulerStyle,
+          top: 0,
+          left: 0,
+          width: RULER,
+          height: RULER,
+          borderRight: `1px solid ${THEME.border}`,
+          borderBottom: `1px solid ${THEME.border}`,
+        }}
+      />
+    </div>
+  );
+}
+
+/** The armed-BREAKPOINT cue on the board itself (blind-walk friction: the
+ *  breakpoint select is sticky, and with the inspector scrolled elsewhere the
+ *  only sign that edits were scoped — and frames were previewing narrow —
+ *  was a dropdown nobody was looking at). One pill, click to disarm. */
+function BreakpointArmedPill(): ReactElement | null {
+  const bp = useSyncExternalStore(subscribeBreakpoint, activeBreakpoint);
+  if (!bp) return null;
+  return (
+    <button
+      type="button"
+      data-testid="board-breakpoint-pill"
+      title="Style edits are scoped to this breakpoint — click to return to Base"
+      onClick={() => setActiveBreakpoint(null)}
+      style={{
+        position: 'absolute',
+        top: RULER + 8,
+        right: 12,
+        zIndex: 62,
+        pointerEvents: 'auto',
+        background: 'rgba(18, 22, 26, 0.92)',
+        color: THEME.accent,
+        border: `1px solid ${THEME.accent}`,
+        borderRadius: 999,
+        fontSize: 10,
+        padding: '3px 10px',
+        cursor: 'pointer',
+      }}
+    >
+      @ {bp} · editing this breakpoint — click to clear
+    </button>
+  );
+}