@1agh/maude 0.39.1 → 0.41.0

package/apps/studio/test/comments-overlay.test.ts

@@ -0,0 +1,117 @@
+// comments-overlay — pure helpers covering the two comment-anchoring bugs in
+// .ai/logs/rca/issue-comment-anchor-drift-and-popup-edge-clamp.md:
+//
+//   1. `resolveCommentTarget` — a stale `data-cd-id` selector (post-rewrite
+//      renumbering, DDR-019) must not be trusted when it resolves to an
+//      element of the wrong tag; it must fall back to the structural matcher,
+//      and return null (not a wrong element) when the target is truly gone.
+//   2. `placeNearPoint` — the composer/thread popup must flip to whichever
+//      side of the anchor actually fits the viewport, instead of always
+//      growing down-right and clipping off-screen near a canvas edge.
+//
+// Needs a live DOM for (1) — register happy-dom for THIS file only, like
+// annotations-roundtrip.test.ts.
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+
+beforeAll(() => {
+  GlobalRegistrator.register();
+});
+afterAll(() => {
+  GlobalRegistrator.unregister();
+});
+
+import { placeNearPoint, resolveCommentTarget } from '../comments-overlay.tsx';
+
+describe('resolveCommentTarget', () => {
+  test('trusts a direct data-cd-id hit when the tag matches', () => {
+    document.body.innerHTML = `
+      <div data-dc-screen="art1">
+        <button class="cta" data-cd-id="aaa11111">Buy now</button>
+      </div>
+    `;
+    const el = resolveCommentTarget({
+      selector: '[data-dc-screen="art1"] [data-cd-id="aaa11111"]',
+      tag: 'button',
+      classes: 'cta',
+      dom_path: ['html', 'body', 'div[data-dc-screen="art1"]', 'button.cta'],
+    });
+    expect(el?.getAttribute('data-cd-id')).toBe('aaa11111');
+  });
+
+  test('falls back to the structural match when the id now belongs to a different tag', () => {
+    // Renumbering: "aaa11111" now sits on an unrelated <div>; the button the
+    // comment was anchored to kept its structure but got a fresh id.
+    document.body.innerHTML = `
+      <div data-dc-screen="art1">
+        <div data-cd-id="aaa11111" class="decoy">Wrong element now has the old id</div>
+        <section class="hero">
+          <button class="cta" data-cd-id="zzz99999">Buy now</button>
+        </section>
+      </div>
+    `;
+    const el = resolveCommentTarget({
+      selector: '[data-dc-screen="art1"] [data-cd-id="aaa11111"]',
+      tag: 'button',
+      classes: 'cta',
+      dom_path: ['html', 'body', 'div[data-dc-screen="art1"]', 'section.hero', 'button.cta'],
+    });
+    expect(el?.getAttribute('data-cd-id')).toBe('zzz99999');
+  });
+
+  test('returns null (not a wrong element) when the target has genuinely been removed', () => {
+    document.body.innerHTML = `
+      <div data-dc-screen="art1">
+        <p>The button that used to be here is gone.</p>
+      </div>
+    `;
+    const el = resolveCommentTarget({
+      selector: '[data-dc-screen="art1"] [data-cd-id="aaa11111"]',
+      tag: 'button',
+      classes: 'cta',
+      dom_path: ['html', 'body', 'div[data-dc-screen="art1"]', 'button.cta'],
+    });
+    expect(el).toBeNull();
+  });
+});
+
+describe('placeNearPoint', () => {
+  beforeAll(() => {
+    window.innerWidth = 1000;
+    window.innerHeight = 800;
+  });
+
+  test('keeps the default down-right placement when there is room', () => {
+    const placed = placeNearPoint({ x: 100, y: 100 }, { w: 300, h: 200 });
+    expect(placed).toEqual({ x: 100, y: 100 });
+  });
+
+  test('flips to the left of the anchor when the card would overflow the right edge', () => {
+    const placed = placeNearPoint({ x: 900, y: 100 }, { w: 300, h: 200 });
+    // 900 + 300 = 1200 > 1000 → flip: 900 - 300 = 600, which has room (>= margin).
+    expect(placed.x).toBe(600);
+  });
+
+  test('flips above the anchor when the card would overflow the bottom edge', () => {
+    const placed = placeNearPoint({ x: 100, y: 700 }, { w: 300, h: 200 });
+    // 700 + 200 = 900 > 800 → flip: 700 - 200 = 500, which has room.
+    expect(placed.y).toBe(500);
+  });
+
+  test('flips both axes when the anchor sits in a corner (near right AND bottom edge)', () => {
+    const placed = placeNearPoint({ x: 950, y: 750 }, { w: 300, h: 200 });
+    // Flipped x (950-300=650) has room, so it flips rather than clamps.
+    expect(placed.x).toBe(650);
+    // Flipped y (750-200=550) has room too.
+    expect(placed.y).toBe(550);
+  });
+
+  test('clamps inward when even the flipped position would go negative', () => {
+    const placed = placeNearPoint({ x: 50, y: 50 }, { w: 2000, h: 2000 });
+    // Card wider/taller than the viewport in both directions — neither the
+    // default nor the flip fits, so it clamps to the margin-in-from-edge spot.
+    expect(placed.x).toBe(8);
+    expect(placed.y).toBe(8);
+  });
+});

package/apps/studio/test/config-reload.test.ts

@@ -0,0 +1,230 @@
+// Config hot-reload — `/design:setup-ds` rewrites `.design/config.json`
+// mid-session; the server must re-read it so a newly added canvas group
+// (`system`) reaches /_index-data and scaffolded DS files show in the tree.
+// reloadConfig mutates ctx.cfg IN PLACE so every `const { cfg } = ctx`
+// capture sees the fresh values.
+// RCA: .ai/logs/rca/issue-ds-scaffold-files-not-in-filetree-stale-config.md
+
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, mkdtempSync, rmSync, unlinkSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+import { type Context, createBus, reloadConfig } from '../context.ts';
+
+/** The pre-scaffold e2e fixture shape — UI-only group, no design systems. */
+const BOOT_CONFIG = {
+  name: 'e2e-fixture',
+  designRoot: '.design',
+  canvasGroups: [{ label: 'UI kit', path: 'ui' }],
+  designSystems: [],
+};
+
+/** What /design:setup-ds writes: system group + DS entry + tokens path. */
+const SCAFFOLDED_CONFIG = {
+  ...BOOT_CONFIG,
+  tokensCssRel: 'system/kanban-glass/colors_and_type.css',
+  canvasGroups: [
+    { label: 'Design system', path: 'system' },
+    { label: 'UI kit', path: 'ui' },
+  ],
+  designSystems: [{ name: 'kanban-glass', path: 'system/kanban-glass' }],
+  defaultDesignSystem: 'kanban-glass',
+};
+
+function sandbox(): { root: string; designRoot: string } {
+  const root = mkdtempSync(join(tmpdir(), 'cfg-reload-test-'));
+  const designRoot = join(root, '.design');
+  mkdirSync(designRoot, { recursive: true });
+  writeFileSync(join(designRoot, 'config.json'), JSON.stringify(BOOT_CONFIG, null, 2));
+  return { root, designRoot };
+}
+
+/** Mirrors what createContext builds at boot from BOOT_CONFIG. */
+function mkCtx(root: string, designRoot: string): Context {
+  return {
+    cfg: {
+      name: 'e2e-fixture',
+      projectLabel: null,
+      designRoot: '.design',
+      canvasGroups: [{ label: 'UI kit', path: 'ui' }],
+      designSystems: [],
+      rootClass: 'app',
+      themeDefault: 'dark',
+      tokensCssRel: 'system/colors_and_type.css',
+      teamAccentDefault: null,
+      handoffTargets: [],
+      newCanvasDir: 'ui',
+      newComponentDir: 'ui/components',
+      _source: '.design/config.json',
+    },
+    projectLabel: 'e2e-fixture Design',
+    paths: {
+      repoRoot: root,
+      designRel: '.design',
+      designRoot,
+      serverInfoFile: join(designRoot, '_server.json'),
+      activeFile: join(designRoot, '_active.json'),
+      commentsDir: join(designRoot, '_comments'),
+      canvasStateDir: join(designRoot, '_canvas-state'),
+      historyDir: join(designRoot, '_history'),
+      tokensUrlRel: '.design/system/colors_and_type.css',
+      systemDirRel: 'system',
+    },
+    bus: createBus(),
+  };
+}
+
+describe('reloadConfig', () => {
+  test('a group added on disk reaches a boot-time captured cfg reference (the bug)', () => {
+    const { root, designRoot } = sandbox();
+    const ctx = mkCtx(root, designRoot);
+    // What every module factory holds: the object reference, captured at boot.
+    const captured = ctx.cfg;
+    try {
+      writeFileSync(join(designRoot, 'config.json'), JSON.stringify(SCAFFOLDED_CONFIG, null, 2));
+      expect(reloadConfig(ctx)).toBe(true);
+      // The capture sees the scaffolded groups — no restart needed.
+      expect(captured.canvasGroups.map((g) => g.path)).toEqual(['system', 'ui']);
+      expect(captured.designSystems?.[0]?.name).toBe('kanban-glass');
+      // normalizeDesignSystems runs on reload too (derived per-DS tokens path).
+      expect(captured.designSystems?.[0]?.tokensCssRel).toBe(
+        'system/kanban-glass/colors_and_type.css'
+      );
+      expect(captured.defaultDesignSystem).toBe('kanban-glass');
+      // Derived paths recompute in place.
+      expect(ctx.paths.tokensUrlRel).toBe('.design/system/kanban-glass/colors_and_type.css');
+      expect(ctx.paths.systemDirRel).toBe('system');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('an unchanged config reports false (no spurious nudges)', () => {
+    const { root, designRoot } = sandbox();
+    const ctx = mkCtx(root, designRoot);
+    try {
+      reloadConfig(ctx); // sync ctx.cfg to the on-disk file once
+      expect(reloadConfig(ctx)).toBe(false);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('invalid JSON mid-edit keeps the running config', () => {
+    const { root, designRoot } = sandbox();
+    const ctx = mkCtx(root, designRoot);
+    try {
+      writeFileSync(join(designRoot, 'config.json'), '{ "name": "half-writ');
+      expect(reloadConfig(ctx)).toBe(false);
+      expect(ctx.cfg.name).toBe('e2e-fixture');
+      expect(ctx.cfg.canvasGroups.map((g) => g.path)).toEqual(['ui']);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('a deleted config keeps the running config (no downgrade to defaults)', () => {
+    const { root, designRoot } = sandbox();
+    const ctx = mkCtx(root, designRoot);
+    try {
+      unlinkSync(join(designRoot, 'config.json'));
+      expect(reloadConfig(ctx)).toBe(false);
+      expect(ctx.cfg.name).toBe('e2e-fixture');
+      expect(ctx.cfg._source).toBe('.design/config.json');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('designRoot is not hot-reloadable — kept, rest of the change applies', () => {
+    const { root, designRoot } = sandbox();
+    const ctx = mkCtx(root, designRoot);
+    try {
+      writeFileSync(
+        join(designRoot, 'config.json'),
+        JSON.stringify({ ...BOOT_CONFIG, name: 'renamed', designRoot: 'designs' }, null, 2)
+      );
+      expect(reloadConfig(ctx)).toBe(true);
+      expect(ctx.cfg.name).toBe('renamed');
+      expect(ctx.cfg.designRoot).toBe('.design');
+      expect(ctx.paths.designRel).toBe('.design');
+      expect(ctx.projectLabel).toBe('renamed Design');
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('linkedHub is boot-pinned — a live add is ignored, the rest applies', () => {
+    const { root, designRoot } = sandbox();
+    const ctx = mkCtx(root, designRoot);
+    try {
+      writeFileSync(
+        join(designRoot, 'config.json'),
+        JSON.stringify(
+          {
+            ...BOOT_CONFIG,
+            name: 'renamed',
+            linkedHub: { url: 'wss://evil.example', linkedAt: 1, syncTsx: true },
+          },
+          null,
+          2
+        )
+      );
+      expect(reloadConfig(ctx)).toBe(true);
+      expect(ctx.cfg.name).toBe('renamed');
+      expect(ctx.cfg.linkedHub).toBeUndefined();
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('design-root escapes are clamped: bad group dropped, bad tokensCssRel reset', () => {
+    const { root, designRoot } = sandbox();
+    const ctx = mkCtx(root, designRoot);
+    try {
+      writeFileSync(
+        join(designRoot, 'config.json'),
+        JSON.stringify(
+          {
+            ...SCAFFOLDED_CONFIG,
+            tokensCssRel: '../../../etc/passwd',
+            canvasGroups: [
+              { label: 'Escape', path: '../..' },
+              { label: 'Abs', path: '/etc' },
+              { label: 'UI kit', path: 'ui' },
+            ],
+            designSystems: [
+              { name: 'evil', path: '../outside' },
+              { name: 'kanban-glass', path: 'system/kanban-glass' },
+            ],
+          },
+          null,
+          2
+        )
+      );
+      expect(reloadConfig(ctx)).toBe(true);
+      expect(ctx.cfg.canvasGroups.map((g) => g.path)).toEqual(['ui']);
+      expect(ctx.cfg.tokensCssRel).toBe('system/colors_and_type.css');
+      expect(ctx.cfg.designSystems?.map((d) => d.name)).toEqual(['kanban-glass']);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+
+  test('a config.json created after a defaults boot applies', () => {
+    const { root, designRoot } = sandbox();
+    const ctx = mkCtx(root, designRoot);
+    // Simulate a boot without config.json (createContext fell back to defaults).
+    unlinkSync(join(designRoot, 'config.json'));
+    ctx.cfg._source = 'defaults';
+    try {
+      writeFileSync(join(designRoot, 'config.json'), JSON.stringify(SCAFFOLDED_CONFIG, null, 2));
+      expect(reloadConfig(ctx)).toBe(true);
+      expect(ctx.cfg._source).toBe('.design/config.json');
+      expect(ctx.cfg.canvasGroups.map((g) => g.path)).toEqual(['system', 'ui']);
+    } finally {
+      rmSync(root, { recursive: true, force: true });
+    }
+  });
+});

package/apps/studio/test/dns-rebinding-guard.test.ts

@@ -0,0 +1,74 @@
+// DNS-rebinding guard on the main-origin source-write/read family.
+//
+// The dev-server binds 127.0.0.1, but `sameOriginWrite` is a *reflective* Origin
+// check — after a DNS-rebind (`evil.example → 127.0.0.1`) the browser sends
+// `Origin: http://evil.example:<port>` AND `Host: evil.example:<port>`, so both
+// sides of the origin comparison are attacker-controlled and equal → CSRF passes.
+// Every source-write/read route now also requires a loopback `Host` (the same
+// `isLoopbackHost` guard the /_api/git/* routes already carry). A real browser
+// always sends `Host: localhost|127.0.0.1:<port>` → passes; a rebound foreign
+// hostname → 403. Regression guard for the /flow:done DDR-150 attacker finding.
+
+import { describe, expect, test } from 'bun:test';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { bootServer, killProc, makeSandbox, nextPort } from './_helpers.ts';
+
+describe('DNS-rebinding guard — source-write/read family requires a loopback Host', () => {
+  test('rebound Host 403s writes + reads; a loopback Host passes the guard', async () => {
+    const { root, designRoot } = makeSandbox();
+    mkdirSync(join(designRoot, 'ui'), { recursive: true });
+    writeFileSync(join(designRoot, 'ui', 'C.tsx'), 'export default function C(){return <main/>}\n');
+
+    const port = nextPort();
+    const proc = await bootServer(root, port);
+    try {
+      const base = `http://localhost:${port}`;
+      // A rebound page: its Host header is the attacker's rebound hostname.
+      const evilHost = `evil.example:${port}`;
+
+      // WRITE route (POST) — the loopback guard fires (before the op runs).
+      const wEvil = await fetch(`${base}/_api/toggle-hide`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', host: evilHost },
+        body: JSON.stringify({ canvas: 'ui/C.tsx', stableId: 'x' }),
+      });
+      expect(wEvil.status).toBe(403);
+
+      // A second write route, to prove it's the whole family, not one endpoint.
+      const wEvil2 = await fetch(`${base}/_api/edit-text`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json', host: evilHost },
+        body: JSON.stringify({ canvas: 'ui/C.tsx', id: 'x', text: 'y' }),
+      });
+      expect(wEvil2.status).toBe(403);
+
+      // READ routes (GET) — a rebound same-origin page could otherwise CORS-read
+      // raw project source; the guard 403s them too.
+      const rEvil = await fetch(`${base}/_api/canvas-source?file=ui/C.tsx`, {
+        headers: { host: evilHost },
+      });
+      expect(rEvil.status).toBe(403);
+      const rEvil2 = await fetch(`${base}/_api/comp-clips?canvas=ui/C.tsx`, {
+        headers: { host: evilHost },
+      });
+      expect(rEvil2.status).toBe(403);
+
+      // A real browser (loopback Host) is NOT rejected by the rebind guard — the
+      // source read succeeds (200). Proves the guard doesn't false-positive on
+      // the legitimate local request every real user makes.
+      const rOk = await fetch(`${base}/_api/canvas-source?file=ui/C.tsx`, {
+        headers: { host: `localhost:${port}` },
+      });
+      expect(rOk.status).toBe(200);
+      // 127.0.0.1 Host is equally valid (the printed URL variant).
+      const rOk2 = await fetch(`${base}/_api/canvas-source?file=ui/C.tsx`, {
+        headers: { host: `127.0.0.1:${port}` },
+      });
+      expect(rOk2.status).toBe(200);
+    } finally {
+      await killProc(proc);
+    }
+  });
+});

package/apps/studio/test/dom-selection.test.ts

@@ -0,0 +1,130 @@
+// dom-selection — resolveByDomPath, the structural fallback comments-overlay
+// (and future consumers) reach for when a stored `data-cd-id` selector no
+// longer identifies the intended element. This is the DDR-019 renumbering
+// scenario: a canvas rewrite (/design:edit regenerating JSX) shifts every
+// subsequent element's positional id within a component, so the id can end up
+// on an unrelated element, or on none at all. See
+// .ai/logs/rca/issue-comment-anchor-drift-and-popup-edge-clamp.md.
+//
+// Needs a live DOM (querySelectorAll / getAttribute walk) — register happy-dom
+// for THIS file only, like annotations-roundtrip.test.ts.
+
+import { afterAll, beforeAll, describe, expect, test } from 'bun:test';
+import { GlobalRegistrator } from '@happy-dom/global-registrator';
+
+beforeAll(() => {
+  GlobalRegistrator.register();
+});
+afterAll(() => {
+  GlobalRegistrator.unregister();
+});
+
+import { resolveByDomPath } from '../dom-selection.ts';
+
+function setArtboard(html: string): void {
+  document.body.innerHTML = `<div data-dc-screen="art1">${html}</div>`;
+}
+
+describe('resolveByDomPath', () => {
+  test('finds the structurally-matching element when a same-id decoy has the wrong tag', () => {
+    // Simulates the renumbering bug: the stored data-cd-id ("bbb22222") now
+    // belongs to an unrelated <div>, while the ORIGINAL <button> the comment
+    // was anchored to survives under a different id ("ccc33333"). The
+    // fallback must find the button by structure, not by the stale id.
+    setArtboard(`
+      <div data-cd-id="bbb22222" class="decoy">Wrong element now has the old id</div>
+      <section class="hero">
+        <button class="cta primary" data-cd-id="ccc33333">Buy now</button>
+      </section>
+    `);
+    const found = resolveByDomPath(document, {
+      artboardId: 'art1',
+      tag: 'button',
+      classes: 'cta primary',
+      dom_path: [
+        'html',
+        'body',
+        'div[data-dc-screen="art1"]',
+        'section.hero',
+        'button.cta.primary',
+      ],
+    });
+    expect(found).not.toBeNull();
+    expect(found?.getAttribute('data-cd-id')).toBe('ccc33333');
+  });
+
+  test('prefers the candidate with the longer matching ancestor suffix over a shallower same-tag sibling', () => {
+    setArtboard(`
+      <button class="cta primary" data-cd-id="aaa11111">Outer decoy button</button>
+      <section class="hero">
+        <button class="cta primary" data-cd-id="bbb22222">Nested target</button>
+      </section>
+    `);
+    const found = resolveByDomPath(document, {
+      artboardId: 'art1',
+      tag: 'button',
+      classes: 'cta primary',
+      dom_path: [
+        'html',
+        'body',
+        'div[data-dc-screen="art1"]',
+        'section.hero',
+        'button.cta.primary',
+      ],
+    });
+    expect(found?.getAttribute('data-cd-id')).toBe('bbb22222');
+  });
+
+  test('returns null when no element in the artboard shares the stored tag', () => {
+    setArtboard(`<div data-cd-id="aaa11111" class="cta primary">Not a button</div>`);
+    const found = resolveByDomPath(document, {
+      artboardId: 'art1',
+      tag: 'button',
+      classes: 'cta primary',
+      dom_path: ['html', 'body', 'div[data-dc-screen="art1"]', 'button.cta.primary'],
+    });
+    expect(found).toBeNull();
+  });
+
+  test('returns null with no dom_path or no tag (nothing to match against)', () => {
+    setArtboard(`<button class="cta primary" data-cd-id="aaa11111">Buy now</button>`);
+    expect(
+      resolveByDomPath(document, { artboardId: 'art1', tag: 'button', classes: 'cta primary' })
+    ).toBeNull();
+    expect(
+      resolveByDomPath(document, {
+        artboardId: 'art1',
+        classes: 'cta primary',
+        dom_path: ['button.cta.primary'],
+      })
+    ).toBeNull();
+  });
+
+  test('scopes the search to the given artboard — a matching element in a different artboard is ignored', () => {
+    document.body.innerHTML = `
+      <div data-dc-screen="art1">
+        <button class="cta primary" data-cd-id="aaa11111">Art1 button</button>
+      </div>
+      <div data-dc-screen="art2">
+        <section class="hero">
+          <button class="cta primary" data-cd-id="bbb22222">Art2 button</button>
+        </section>
+      </div>
+    `;
+    const found = resolveByDomPath(document, {
+      artboardId: 'art1',
+      tag: 'button',
+      classes: 'cta primary',
+      dom_path: [
+        'html',
+        'body',
+        'div[data-dc-screen="art2"]',
+        'section.hero',
+        'button.cta.primary',
+      ],
+    });
+    // The art2 button structurally matches perfectly, but art1 is the requested
+    // scope — the only art1 candidate is a shallower, shorter-suffix match.
+    expect(found?.getAttribute('data-cd-id')).toBe('aaa11111');
+  });
+});

package/apps/studio/test/edit-css-occurrence.test.ts

@@ -0,0 +1,81 @@
+// canvas-edit.ts — Stage H3 (feature-element-editing-robustness). A whole-
+// component-instance move/resize passes a DOM-occurrence index into edit-css so
+// `applyEdit` routes the write to that instance's `<Component/>` USAGE (local to
+// the dragged instance) instead of the shared inner definition (global). The knob
+// / paste-style paths pass NO occurrence, so inner-shared-element styling stays
+// global-and-labeled — the H2 badge is the answer there (the chosen model).
+// Positional ids are round-tripped through transpileCanvasSource like the sibling
+// structural test, so the arithmetic stays in lockstep with the pipeline.
+
+import { describe, expect, test } from 'bun:test';
+
+import { applyEdit } from '../canvas-edit.ts';
+import { transpileCanvasSource } from '../canvas-pipeline.ts';
+
+const CANVAS = '/abs/Canvas.tsx';
+
+/** Map data-cd-id by element-type name (first occurrence), like canvas-edit.test.ts. */
+function idsOf(source: string): Record<string, string> {
+  const { withIds } = transpileCanvasSource(CANVAS, source);
+  const out: Record<string, string> = {};
+  for (const m of withIds.matchAll(/<(\w+)([^>]*?)data-cd-id="([0-9a-f]{8})"/g)) {
+    if (!out[m[1] as string]) out[m[1] as string] = m[3] as string;
+  }
+  return out;
+}
+
+const SHARED = [
+  'function Card() { return <article>card</article>; }',
+  'function Demo() {',
+  '  return (',
+  '    <section>',
+  '      <Card />',
+  '      <Card />',
+  '      <Card />',
+  '    </section>',
+  '  );',
+  '}',
+].join('\n');
+
+describe('canvas-edit / applyEdit — Stage H3 occurrence routing', () => {
+  test('with an occurrence, a style edit routes to that <Component/> usage (local)', () => {
+    // The inner <article> id is shared across all three <Card/> usages.
+    const innerId = idsOf(SHARED).article as string;
+    const out = applyEdit(CANVAS, SHARED, innerId, 'style.left', '"40px"', 1); // 2nd instance
+    // The 2nd (index 1) <Card/> usage gains the inline style; the shared inner
+    // <article> definition is untouched, so the other two instances don't move.
+    expect(out.source).toContain('<Card style={{ left: "40px" }}');
+    expect(out.source.match(/<Card \/>/g)?.length).toBe(2);
+    expect(out.source).toContain('<article>card</article>');
+  });
+
+  test('without an occurrence, the same edit stays on the shared inner element (global)', () => {
+    const innerId = idsOf(SHARED).article as string;
+    const out = applyEdit(CANVAS, SHARED, innerId, 'style.left', '"40px"');
+    // No occurrence → knob / paste-style behavior: the write lands on the inner
+    // <article>, changing every rendered instance (the "inner styling is global"
+    // model the H2 badge labels).
+    expect(out.source).toContain('<article style={{ left: "40px" }}>card</article>');
+    expect(out.source).not.toContain('<Card style=');
+  });
+
+  test('a normal (non-instance) element ignores the occurrence (no-op remap)', () => {
+    const src = 'function Demo() { return <div>x</div>; }';
+    const id = idsOf(src).div as string;
+    const out = applyEdit(CANVAS, src, id, 'style.padding', '14', 3);
+    expect(out.source).toContain('<div style={{ padding: 14 }}>x</div>');
+  });
+
+  test('an element in a single-usage component ignores the occurrence (not splittable)', () => {
+    const src = [
+      'function Card() { return <article>card</article>; }',
+      'function Demo() { return <section><Card /></section>; }',
+    ].join('\n');
+    const innerId = idsOf(src).article as string;
+    // One usage → resolveUsageId returns the inner id (can't split) — the edit
+    // lands on <article>, never fabricates a phantom usage index.
+    const out = applyEdit(CANVAS, src, innerId, 'style.left', '"40px"', 0);
+    expect(out.source).toContain('<article style={{ left: "40px" }}>card</article>');
+    expect(out.source).not.toContain('<Card style=');
+  });
+});