@1agh/maude 0.19.0 → 0.20.0

package/plugins/design/dev-server/marquee-overlay.tsx

@@ -0,0 +1,282 @@
+/**
+ * @file       marquee-overlay.tsx — T26 (Wave 3)
+ * @scope      plugins/design/dev-server/marquee-overlay.tsx
+ * @purpose    Element-level marquee selection. Drag from empty padding inside
+ *             an artboard body (NOT on top of a `[data-cd-id]` element) to
+ *             lasso multiple stamped elements. Aseprite modifier vocabulary:
+ *             bare = replace, Shift = add, Alt = subtract, Shift+Alt =
+ *             intersect. Modifier state re-read at pointerup so the user can
+ *             flip mid-drag.
+ *
+ *             Co-exists with `artboard-marquee.tsx` — that overlay triggers
+ *             when pointerdown lands OUTSIDE any artboard (empty world);
+ *             this overlay triggers when pointerdown lands INSIDE an artboard
+ *             body on padding (no cd-id under cursor). The two are mutually
+ *             exclusive by start position.
+ *
+ *             Renders the marquee rect per DDR-046 rev 2:
+ *                 1 px solid accent + 8 % accent fill
+ *             (same idiom as artboard marquee — active gesture is solid +
+ *             tinted; dashed reserved for persistent group bbox.)
+ */
+
+import { useEffect, useRef } from 'react';
+
+import { DRAG_THRESHOLD_PX } from './input-router.tsx';
+import { type Selection, useSelectionSet } from './use-selection-set.tsx';
+import { useToolMode } from './use-tool-mode.tsx';
+
+const ELEM_MARQUEE_CSS = `
+.dc-cv-elem-marquee {
+  position: fixed;
+  pointer-events: none;
+  z-index: 5;
+  border: 1px solid var(--accent, #0d99ff);
+  background: color-mix(in oklab, var(--accent, #0d99ff) 8%, transparent);
+  display: none;
+}
+`.trim();
+
+function ensureMarqueeStyles(): void {
+  if (typeof document === 'undefined') return;
+  if (document.getElementById('dc-cv-elem-marquee-css')) return;
+  const s = document.createElement('style');
+  s.id = 'dc-cv-elem-marquee-css';
+  s.textContent = ELEM_MARQUEE_CSS;
+  document.head.appendChild(s);
+}
+
+// Skip the same chrome / overlay surfaces as artboard-marquee — the user is
+// interacting with floating UI, not the world.
+function isChromeTarget(t: EventTarget | null): boolean {
+  if (!t || !(t as Element).closest) return true;
+  const el = t as Element;
+  if (
+    el.closest(
+      '.dc-mm, .dc-zoom-tb, .dc-tool-palette, .dc-context-menu, .dc-cv-halo, .dc-cv-group-bbox, .cm-composer, .cm-thread, .cm-mention-popup, .cm-pin, .dc-annot-svg, .dc-annot-ctx, .dc-tp-popover, .dc-annot-resize-handle, .dc-multi-artboard-tb, .dc-elem-ctx-tb, .dc-cv-eq-spacing-layer'
+    )
+  ) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Walk from `hit` upward and decide if the pointerdown landed on "empty body
+ * padding" (no `[data-cd-id]` encountered before reaching `.dc-artboard-body`).
+ * Returns the body element when yes; null when the pointerdown should not
+ * start an element marquee.
+ */
+function resolveBodyOrNull(hit: Element): Element | null {
+  let cur: Element | null = hit;
+  while (cur) {
+    if (cur.hasAttribute?.('data-cd-id')) return null; // on user content
+    if ((cur as HTMLElement).classList?.contains('dc-artboard-body')) return cur;
+    cur = cur.parentElement;
+  }
+  return null;
+}
+
+/**
+ * Mode resolved from the current modifier state. Re-read at pointerup so a
+ * user can flip mid-drag — e.g. start without modifiers, press Shift before
+ * releasing, the gesture commits as `add` instead of `replace`.
+ */
+type Mode = 'replace' | 'add' | 'subtract' | 'intersect';
+
+function modeOf(e: { shiftKey: boolean; altKey: boolean }): Mode {
+  if (e.shiftKey && e.altKey) return 'intersect';
+  if (e.shiftKey) return 'add';
+  if (e.altKey) return 'subtract';
+  return 'replace';
+}
+
+/**
+ * Build a minimal `Selection` from a `[data-cd-id]` element — just the fields
+ * downstream consumers actually read for bulk marquee hits. The rich shape
+ * (html, dom_path, text) is only enriched when a single click sets focus
+ * through `hoverTargetToSelection`.
+ */
+function elementToSelection(el: Element, bodyAncestor: Element): Selection | null {
+  const cdId = el.getAttribute('data-cd-id');
+  if (!cdId) return null;
+  const artboardEl = bodyAncestor.closest('[data-dc-screen]');
+  const artboardId = artboardEl?.getAttribute('data-dc-screen') ?? null;
+  const rect = (el as HTMLElement).getBoundingClientRect();
+  return {
+    id: cdId,
+    selector: `[data-cd-id="${cdId}"]`,
+    artboardId,
+    tag: el.tagName.toLowerCase(),
+    classes: (el.getAttribute('class') ?? '')
+      .trim()
+      .split(/\s+/)
+      .filter((c) => c && !c.startsWith('dgn-') && !c.startsWith('dc-cv-'))
+      .join(' '),
+    bounds: {
+      x: Math.round(rect.left),
+      y: Math.round(rect.top),
+      w: Math.round(rect.width),
+      h: Math.round(rect.height),
+    },
+  };
+}
+
+function rectsIntersect(
+  a: { left: number; top: number; right: number; bottom: number },
+  b: { left: number; top: number; right: number; bottom: number }
+): boolean {
+  if (a.right < b.left || a.left > b.right) return false;
+  if (a.bottom < b.top || a.top > b.bottom) return false;
+  return true;
+}
+
+export function ElementMarqueeOverlay() {
+  ensureMarqueeStyles();
+  const selSet = useSelectionSet();
+  const { tool } = useToolMode();
+  const overlayRef = useRef<HTMLDivElement | null>(null);
+  const stateRef = useRef<{
+    pointerId: number;
+    startX: number;
+    startY: number;
+    crossed: boolean;
+    bodyEl: Element;
+    /** Snapshot of `selSet.selected` at gesture start — needed for subtract /
+     *  intersect / add to compute deltas against the original set. */
+    startSet: Selection[];
+  } | null>(null);
+
+  useEffect(() => {
+    if (tool !== 'move') return;
+    if (typeof document === 'undefined') return;
+
+    const onDown = (e: PointerEvent) => {
+      if (e.button !== 0) return;
+      // Cmd / Ctrl reserved for single-element select (Cmd-click). Never start
+      // an element marquee when those are held — that gesture means "select
+      // the single element under cursor."
+      if (e.metaKey || e.ctrlKey) return;
+      const target = e.target as Element | null;
+      if (!target || isChromeTarget(target)) return;
+      const bodyEl = resolveBodyOrNull(target);
+      if (!bodyEl) return; // either over user content or outside any artboard
+      stateRef.current = {
+        pointerId: e.pointerId,
+        startX: e.clientX,
+        startY: e.clientY,
+        crossed: false,
+        bodyEl,
+        startSet: selSet.selected.slice(),
+      };
+    };
+
+    const onMove = (e: PointerEvent) => {
+      const s = stateRef.current;
+      if (!s || e.pointerId !== s.pointerId) return;
+      const dx = e.clientX - s.startX;
+      const dy = e.clientY - s.startY;
+      if (!s.crossed) {
+        if (Math.hypot(dx, dy) < DRAG_THRESHOLD_PX) return;
+        s.crossed = true;
+      }
+      const div = overlayRef.current;
+      if (!div) return;
+      const left = Math.min(s.startX, e.clientX);
+      const top = Math.min(s.startY, e.clientY);
+      div.style.display = 'block';
+      div.style.left = `${left}px`;
+      div.style.top = `${top}px`;
+      div.style.width = `${Math.abs(dx)}px`;
+      div.style.height = `${Math.abs(dy)}px`;
+    };
+
+    const finish = (e: PointerEvent) => {
+      const s = stateRef.current;
+      if (!s || e.pointerId !== s.pointerId) return;
+      stateRef.current = null;
+      const div = overlayRef.current;
+      if (div) div.style.display = 'none';
+      if (!s.crossed) return;
+
+      const left = Math.min(s.startX, e.clientX);
+      const top = Math.min(s.startY, e.clientY);
+      const right = Math.max(s.startX, e.clientX);
+      const bottom = Math.max(s.startY, e.clientY);
+      const marqueeBox = { left, top, right, bottom };
+
+      // Intersect against every stamped element inside the originating
+      // artboard body. Scoping to the start body is intentional — drags
+      // that extend across artboards still only capture from the artboard
+      // the gesture started in. Cross-artboard marquee is an unimplemented
+      // affordance (no peer tool ships it; users rely on multi-artboard
+      // distribute + per-artboard marquees).
+      const stamped = s.bodyEl.querySelectorAll('[data-cd-id]');
+      const hits: Selection[] = [];
+      for (const el of stamped) {
+        const b = (el as HTMLElement).getBoundingClientRect();
+        if (b.width === 0 && b.height === 0) continue;
+        if (!rectsIntersect(marqueeBox, b)) continue;
+        const sel = elementToSelection(el, s.bodyEl);
+        if (sel) hits.push(sel);
+      }
+
+      const mode = modeOf(e);
+      applyMarqueeMode(selSet, mode, s.startSet, hits);
+    };
+
+    document.addEventListener('pointerdown', onDown, true);
+    document.addEventListener('pointermove', onMove);
+    document.addEventListener('pointerup', finish);
+    document.addEventListener('pointercancel', finish);
+    return () => {
+      document.removeEventListener('pointerdown', onDown, true);
+      document.removeEventListener('pointermove', onMove);
+      document.removeEventListener('pointerup', finish);
+      document.removeEventListener('pointercancel', finish);
+    };
+  }, [tool, selSet]);
+
+  return <div ref={overlayRef} className="dc-cv-elem-marquee" aria-hidden="true" />;
+}
+
+/**
+ * Apply marquee hits to `selSet` per Aseprite modifier semantics. Pulled out
+ * of the hook for unit-test reachability.
+ */
+export function applyMarqueeMode(
+  selSet: {
+    replace: (s: Selection | Selection[]) => void;
+    add: (s: Selection | Selection[]) => void;
+  },
+  mode: Mode,
+  startSet: Selection[],
+  hits: Selection[]
+): void {
+  if (mode === 'replace') {
+    if (hits.length === 0) return; // empty marquee preserves selection
+    selSet.replace(hits);
+    return;
+  }
+  if (mode === 'add') {
+    if (hits.length === 0) return;
+    selSet.add(hits);
+    return;
+  }
+  if (mode === 'subtract') {
+    const keyOf = (x: Selection) => (x.id ? `id:${x.id}` : `sel:${x.selector}`);
+    const removeKeys = new Set(hits.map(keyOf));
+    const next = startSet.filter((x) => !removeKeys.has(keyOf(x)));
+    selSet.replace(next);
+    return;
+  }
+  // intersect
+  const keyOf = (x: Selection) => (x.id ? `id:${x.id}` : `sel:${x.selector}`);
+  const hitKeys = new Set(hits.map(keyOf));
+  const next = startSet.filter((x) => hitKeys.has(keyOf(x)));
+  selSet.replace(next);
+}
+
+// Re-export for tests.
+export { modeOf };
+export type { Mode };

package/plugins/design/dev-server/runtime-bundle.ts

@@ -53,6 +53,13 @@ export const RUNTIME_PACKAGES = [
   // (DDR-024 deferred path) and any high-end designer-tool overlays a canvas
   // wants to draw via WebGL.
   'pixi.js',
+  // Phase 3.7 / DDR-049 — Motion One (motion/react) is the canonical motion
+  // library for the canvas-lib + handoff pipeline. Externalised here so the
+  // canvas-lib motion helpers (<MotionDemo>, etc.) resolve through the same
+  // importmap path; consumers of /design:handoff still see a "motion" peer
+  // dep declaration on the registry-item.json output.
+  'motion',
+  'motion/react',
 ] as const;
 
 export type RuntimePackage = (typeof RUNTIME_PACKAGES)[number];

package/plugins/design/dev-server/server.mjs

@@ -78,7 +78,28 @@ function loadConfig() {
     console.error(`  warn: ${CONFIG_PATH} is not valid JSON: ${e.message}. Using defaults.`);
     return { ...DEFAULT_CONFIG, _source: 'defaults (config invalid)' };
   }
-  return { ...DEFAULT_CONFIG, ...parsed, _source: '.design/config.json' };
+  return normalizeDesignSystems({ ...DEFAULT_CONFIG, ...parsed, _source: '.design/config.json' });
+}
+
+/**
+ * Mirror of context.ts `normalizeDesignSystems` for the legacy Node entry.
+ * Auto-derives per-DS `tokensCssRel = <entry.path>/colors_and_type.css` when
+ * missing so the System view can find tokens regardless of multi-DS layout.
+ * DDR-048. Keep in lock-step with the .ts version until DDR-009 retires this.
+ */
+function normalizeDesignSystems(cfg) {
+  if (!cfg.designSystems?.length) return cfg;
+  const designSystems = cfg.designSystems.map((entry) => {
+    const p = String(entry.path).replace(/^\/+|\/+$/g, '');
+    return {
+      ...entry,
+      path: p,
+      tokensCssRel:
+        (entry.tokensCssRel ?? '').toString().replace(/^\/+/, '') ||
+        path.posix.join(p, 'colors_and_type.css'),
+    };
+  });
+  return { ...cfg, designSystems };
 }
 
 const CFG = loadConfig();
@@ -962,9 +983,22 @@ function parseTokens(css) {
   return tokens;
 }
 
-async function buildSystemData() {
-  const sysAbs = path.join(DESIGN_ROOT, SYSTEM_DIR_REL);
-  const sysRel = path.posix.join(DESIGN_REL, SYSTEM_DIR_REL);
+/**
+ * Build the System view payload. When `dsName` is set, scope to that DS entry
+ * (per-DS tokens + per-DS preview/ui_kits gallery). Returns null when the
+ * name is set but not registered in `CFG.designSystems` so the caller can
+ * 404 instead of silently falling back to shell defaults. DDR-048.
+ */
+async function buildSystemData(dsName) {
+  let dsEntry = null;
+  if (dsName) {
+    dsEntry = (CFG.designSystems || []).find((d) => d.name === dsName) || null;
+    if (!dsEntry) return null;
+  }
+
+  const scopedSystemRel = dsEntry ? dsEntry.path : SYSTEM_DIR_REL;
+  const sysAbs = path.join(DESIGN_ROOT, scopedSystemRel);
+  const sysRel = path.posix.join(DESIGN_REL, scopedSystemRel);
 
   // README — try canonical locations (designRoot/README.md, system/README.md, system/<project>/README.md)
   let readme = null, readmePath = null;
@@ -986,11 +1020,13 @@ async function buildSystemData() {
     } catch {}
   }
 
-  // Tokens
+  // Tokens — per-DS path wins; top-level CFG.tokensCssRel is the fallback
+  // for legacy single-DS configs that don't declare `designSystems[]`.
+  const tokensCssRel = (dsEntry && dsEntry.tokensCssRel) || CFG.tokensCssRel;
   let tokens = [];
   let tokensPath = null;
   try {
-    const tokensAbs = path.join(DESIGN_ROOT, CFG.tokensCssRel);
+    const tokensAbs = path.join(DESIGN_ROOT, tokensCssRel);
     const css = await fs.readFile(tokensAbs, 'utf8');
     tokens = parseTokens(css);
     tokensPath = path.relative(REPO_ROOT, tokensAbs);
@@ -1005,14 +1041,19 @@ async function buildSystemData() {
     // Look one level deep — system/<project>/<folderName>/...
     const matches = [];
     try {
-      const subs = await fs.readdir(sysAbs, { withFileTypes: true });
-      for (const s of subs) {
-        if (!s.isDirectory()) continue;
-        const candidate = path.join(sysAbs, s.name, folderName);
-        try {
-          const stat = await fs.stat(candidate);
-          if (stat.isDirectory()) matches.push({ abs: candidate, rel: path.posix.join(sysRel, s.name, folderName) });
-        } catch {}
+      // When scoped to one DS (sysAbs IS the DS folder), only check the
+      // DS-relative `<folderName>` subdir. Scanning sub-dirs here would
+      // misread the DS's own `preview/` as a sibling DS root.
+      if (!dsEntry) {
+        const subs = await fs.readdir(sysAbs, { withFileTypes: true });
+        for (const s of subs) {
+          if (!s.isDirectory()) continue;
+          const candidate = path.join(sysAbs, s.name, folderName);
+          try {
+            const stat = await fs.stat(candidate);
+            if (stat.isDirectory()) matches.push({ abs: candidate, rel: path.posix.join(sysRel, s.name, folderName) });
+          } catch {}
+        }
       }
       // Also accept top-level system/<folderName>/
       try {
@@ -1037,10 +1078,27 @@ async function buildSystemData() {
   const previewGallery = await galleryFor('preview');
   const uiKitsGallery  = await galleryFor('ui_kits');
 
+  const availableDesignSystems = (CFG.designSystems || []).map((d) => ({
+    name: d.name,
+    path: d.path,
+    description: d.description || null,
+  }));
+
   return {
     project: CFG.name,
     designRoot: DESIGN_REL,
     systemDir: sysRel,
+    ds: dsEntry
+      ? {
+          name: dsEntry.name,
+          path: dsEntry.path,
+          description: dsEntry.description || null,
+          rootClass: dsEntry.rootClass || null,
+          themeDefault: dsEntry.themeDefault || null,
+        }
+      : null,
+    availableDesignSystems,
+    defaultDesignSystem: CFG.defaultDesignSystem || availableDesignSystems[0]?.name || null,
     readme,
     readmePath,
     tokens,
@@ -1048,8 +1106,8 @@ async function buildSystemData() {
     tokensPath,
     previewGallery,
     uiKitsGallery,
-    rootClass: CFG.rootClass,
-    themeDefault: CFG.themeDefault,
+    rootClass: (dsEntry && dsEntry.rootClass) || CFG.rootClass,
+    themeDefault: (dsEntry && dsEntry.themeDefault) || CFG.themeDefault,
     teamAccentDefault: CFG.teamAccentDefault,
   };
 }
@@ -1105,8 +1163,16 @@ const server = http.createServer(async (req, res) => {
       res.end(JSON.stringify(data));
       return;
     }
-    if (reqPath === '/_system-data') {
-      const data = await buildSystemData();
+    if (reqPath === '/_system-data' || reqPath.startsWith('/_system-data?')) {
+      // DDR-048 — `?ds=<name>` scopes to one DS; omitted = legacy unscoped.
+      const sysUrl = new URL(reqPath, 'http://x');
+      const dsName = sysUrl.searchParams.get('ds');
+      const data = await buildSystemData(dsName);
+      if (data === null) {
+        res.writeHead(404, { 'Content-Type': MIME['.json'], 'Cache-Control': 'no-store' });
+        res.end(JSON.stringify({ error: 'unknown design system', ds: dsName }));
+        return;
+      }
       res.writeHead(200, { 'Content-Type': MIME['.json'], 'Cache-Control': 'no-store' });
       res.end(JSON.stringify(data));
       return;

package/plugins/design/dev-server/test/annotation-strokes-command.test.ts

@@ -0,0 +1,149 @@
+import { describe, expect, mock, test } from 'bun:test';
+
+import type { PenStroke, RectStroke, Stroke } from '../annotations-layer.tsx';
+import { createAnnotationStrokesCommand } from '../commands/annotation-strokes-command.ts';
+
+const pen1: PenStroke = {
+  id: 'pen-1',
+  tool: 'pen',
+  color: '#000',
+  width: 2,
+  points: [
+    [0, 0],
+    [10, 10],
+  ],
+};
+
+const pen2: PenStroke = {
+  id: 'pen-2',
+  tool: 'pen',
+  color: '#f00',
+  width: 4,
+  points: [[20, 20]],
+};
+
+const rect1: RectStroke = {
+  id: 'rect-1',
+  tool: 'rect',
+  color: '#000',
+  width: 2,
+  x: 0,
+  y: 0,
+  w: 50,
+  h: 30,
+  fill: null,
+};
+
+describe('createAnnotationStrokesCommand', () => {
+  test('do() PUTs the AFTER set', async () => {
+    const putFn = mock(() => Promise.resolve());
+    const cmd = createAnnotationStrokesCommand({
+      before: [],
+      after: [pen1],
+      putFn,
+    });
+    await cmd.do();
+    expect(putFn).toHaveBeenCalledTimes(1);
+    expect(putFn.mock.calls[0]?.[0]).toEqual([pen1]);
+  });
+
+  test('undo() PUTs the BEFORE set', async () => {
+    const putFn = mock(() => Promise.resolve());
+    const cmd = createAnnotationStrokesCommand({
+      before: [pen1],
+      after: [pen1, pen2],
+      putFn,
+    });
+    await cmd.undo();
+    expect(putFn).toHaveBeenCalledTimes(1);
+    expect(putFn.mock.calls[0]?.[0]).toEqual([pen1]);
+  });
+
+  test('round-trip — add stroke then undo restores empty', async () => {
+    const calls: Stroke[][] = [];
+    const putFn: (next: readonly Stroke[]) => Promise<void> = (next) => {
+      calls.push([...next]);
+      return Promise.resolve();
+    };
+    const cmd = createAnnotationStrokesCommand({
+      before: [],
+      after: [pen1],
+      putFn,
+    });
+    await cmd.do();
+    await cmd.undo();
+    await cmd.do(); // redo
+    expect(calls).toEqual([[pen1], [], [pen1]]);
+  });
+
+  test('eraser path — before has stroke, after is empty', async () => {
+    const putFn = mock(() => Promise.resolve());
+    const cmd = createAnnotationStrokesCommand({
+      before: [pen1],
+      after: [],
+      putFn,
+    });
+    expect(cmd.label).toBe('erase 1 stroke');
+    await cmd.do();
+    expect(putFn.mock.calls[0]?.[0]).toEqual([]);
+    await cmd.undo();
+    expect(putFn.mock.calls[1]?.[0]).toEqual([pen1]);
+  });
+
+  test('default label — add 2 strokes', () => {
+    const cmd = createAnnotationStrokesCommand({
+      before: [pen1],
+      after: [pen1, pen2, rect1],
+      putFn: () => {},
+    });
+    expect(cmd.label).toBe('add 2 strokes');
+  });
+
+  test('default label — same-count edit', () => {
+    const cmd = createAnnotationStrokesCommand({
+      before: [pen1],
+      after: [{ ...pen1, color: '#f00' }],
+      putFn: () => {},
+    });
+    expect(cmd.label).toBe('edit 1 stroke');
+  });
+
+  test('snapshots are deep-cloned — mutating source after construction does not poison', async () => {
+    // Use locally-owned strokes so the test's mutation only affects the
+    // source arrays, never the module-scope `pen1`/`pen2` shared with other
+    // tests.
+    const localPen: PenStroke = {
+      id: 'local',
+      tool: 'pen',
+      color: '#000',
+      width: 1,
+      points: [
+        [1, 1],
+        [2, 2],
+      ],
+    };
+    const localPenAfter: PenStroke = {
+      id: 'local-after',
+      tool: 'pen',
+      color: '#111',
+      width: 1,
+      points: [[3, 3]],
+    };
+    const sourceBefore: Stroke[] = [localPen];
+    const sourceAfter: Stroke[] = [localPen, localPenAfter];
+    const putFn = mock(() => Promise.resolve());
+    const cmd = createAnnotationStrokesCommand({
+      before: sourceBefore,
+      after: sourceAfter,
+      putFn,
+    });
+    // Mutate source arrays after construction — replace entries entirely so
+    // we don't reach through into shared sub-arrays.
+    sourceAfter[0] = { ...localPen, color: '#POISONED' };
+    sourceBefore.length = 0;
+    await cmd.do();
+    expect(putFn.mock.calls[0]?.[0]).toEqual([localPen, localPenAfter]);
+    await cmd.undo();
+    expect(putFn.mock.calls[1]?.[0]).toEqual([localPen]);
+  });
+});

package/plugins/design/dev-server/test/annotations-layer.test.ts

@@ -20,6 +20,7 @@ import {
   penPathD,
   rid,
   strokeHitTest,
+  strokesShallowEqual,
   strokesToSvg,
 } from '../annotations-layer.tsx';
 
@@ -417,3 +418,46 @@ describe('annotations-layer / strokes round-trip is stable for arrays', () => {
     expect(strokesToSvg(sample)).toBe(strokesToSvg(sample));
   });
 });
+
+describe('annotations-layer / strokesShallowEqual (drag no-op gate)', () => {
+  const pen: PenStroke = {
+    id: 'p',
+    tool: 'pen',
+    color: '#000',
+    width: 2,
+    points: [[0, 0]],
+  };
+  const rect: RectStroke = {
+    id: 'r',
+    tool: 'rect',
+    color: '#000',
+    width: 2,
+    x: 0,
+    y: 0,
+    w: 10,
+    h: 10,
+    fill: null,
+  };
+
+  test('same reference → true', () => {
+    const arr = [pen, rect];
+    expect(strokesShallowEqual(arr, arr)).toBe(true);
+  });
+
+  test('different references but same entries (same order) → true', () => {
+    expect(strokesShallowEqual([pen, rect], [pen, rect])).toBe(true);
+  });
+
+  test('different entry reference at any slot → false', () => {
+    const penClone: PenStroke = { ...pen };
+    expect(strokesShallowEqual([pen, rect], [penClone, rect])).toBe(false);
+  });
+
+  test('different length → false', () => {
+    expect(strokesShallowEqual([pen], [pen, rect])).toBe(false);
+  });
+
+  test('empty arrays → true', () => {
+    expect(strokesShallowEqual([], [])).toBe(true);
+  });
+});