mirror of
https://github.com/nexu-io/open-design.git
synced 2026-06-01 03:14:35 +07:00
78ae6feb59
When the agent emits an HTML artifact with no `data-od-id` / `data-screen-label` annotations (a freeform PRD → HTML pass through a Claude-Code-compatible CLI without going through a skill, for example), the existing Inspect / Picker affordances no-oped silently: - The bridge's click handler walks up to <html>, finds nothing tagged, and bails before emitting `od:comment-target` — by design, since posting a synthetic id here would change save-to-source semantics for inspect overrides (the persisted CSS keys off the same elementId). - The host then sat at "Click any element with `data-od-id` to tune its style" — phrased as if the user just hadn't found the right element, when the page in fact had nothing matching at all. - Picker mode (Tweaks → Picker) had no hint at all. The bridge already broadcasts `od:comment-targets` with the full list on every mode toggle and DOM mutation, but the host's existing listener was gated on `boardMode` only — Inspect mode never learned the artifact's annotation count. Two surgical fixes: 1. `FileViewer.tsx`: a dedicated `od:comment-targets` listener that installs whenever Inspect OR Comments mode is active, mirroring the bridge's broadcast into `liveCommentTargets`. The comment-mode-only listener still owns its hover / click / pod events; this new listener only handles the targets list. 2. `FileViewer.tsx`: the inspect-empty-hint banner now dispatches on `liveCommentTargets.size === 0`. Empty: a clear "this artifact has no `data-od-id` annotations yet — ask the agent to add them" message that names the missing attribute. Populated: existing instructive copy. Mirrored across Inspect and Picker modes so the failure surface gives the same calibration signal in both. Tests: - `tests/runtime/srcdoc-bridge-empty-targets.test.ts` (3 cases): pin the bridge contract this fix depends on. Run the IIFE in jsdom and assert (a) `allTargets()` posts an empty list for unannotated DOM, (b) clicks on unannotated elements do NOT post `od:comment-target` (regression pin against future "synthetic id" fallbacks that would silently change save-to-source semantics), (c) clicks DO still resolve to an annotated ancestor when one exists. - `tests/components/FileViewer.inspect-empty-hint.test.tsx` (3 cases): pin the host dispatch — empty state in Inspect mode, the switch back to instructive copy when targets show up, and the mirrored affordance in Picker mode. Out of scope (flagged in the design comment so it isn't lost): - The follow-up scenario from #890 ("parent has data-od-id, target child does not → adjustments hit the parent") is a different bug that needs either synthetic-id fallback or a UI affordance to descend into the click target. Leaving that to a follow-up so this PR stays narrow. - i18n: the existing inspect-empty-hint copy is hardcoded English; rolling it into the 17-locale Dict is a separate cleanup.
151 lines
6.4 KiB
TypeScript
151 lines
6.4 KiB
TypeScript
// @vitest-environment node
|
|
|
|
import { describe, expect, it, vi } from 'vitest';
|
|
import { JSDOM } from 'jsdom';
|
|
import { buildSrcdoc } from '../../src/runtime/srcdoc';
|
|
|
|
// Behavioral coverage for nexu-io/open-design#890. The Examples / Tweaks
|
|
// preview iframe runs the bridge script generated by `buildSrcdoc`. When
|
|
// the agent emits an artifact without `data-od-id` / `data-screen-label`
|
|
// (e.g. a freeform PRD → HTML pass through a Claude-Code-compatible CLI
|
|
// without a skill), the bridge must:
|
|
//
|
|
// 1. Still post `od:comment-targets` with `targets: []` so the host
|
|
// can detect the empty-annotation state and surface a clearer
|
|
// hint than "Click any element with `data-od-id` …" — without
|
|
// this, FileViewer's `liveCommentTargets` map never updates and
|
|
// the hint banner sticks at its instructive-default state even
|
|
// though there's nothing to click.
|
|
// 2. Drop click events on unannotated elements without posting an
|
|
// `od:comment-target` — the click handler walks up to <html>,
|
|
// finds nothing tagged, and must bail. Posting a synthetic id
|
|
// here would change save-to-source semantics for inspect
|
|
// overrides (the persisted CSS keys off the same elementId), so
|
|
// this test pins the no-fallback contract.
|
|
//
|
|
// The host-side hint switch lives in `apps/web/src/components/FileViewer.tsx`
|
|
// (search for `inspect-empty-hint-no-targets`); these tests pin the
|
|
// signal it depends on.
|
|
|
|
function extractBridgeScript(srcdoc: string): string {
|
|
// The bridge is wrapped in `<script data-od-selection-bridge>(function(){…})()</script>`.
|
|
const match = srcdoc.match(
|
|
/<script data-od-selection-bridge>([\s\S]*?)<\/script>/,
|
|
);
|
|
if (!match || !match[1]) {
|
|
throw new Error('selection bridge script not found in srcdoc');
|
|
}
|
|
return match[1];
|
|
}
|
|
|
|
function setupBridgeDom(bodyHtml: string, mode: 'inspect' | 'comment') {
|
|
const srcdoc = buildSrcdoc(`<!doctype html><html><body>${bodyHtml}</body></html>`, {
|
|
inspectBridge: mode === 'inspect',
|
|
commentBridge: mode === 'comment',
|
|
});
|
|
const script = extractBridgeScript(srcdoc);
|
|
|
|
// Build a fresh JSDOM that mirrors the iframe runtime: `window.parent`
|
|
// is what the bridge calls into, and we spy on its postMessage to
|
|
// capture the messages it would emit to the host.
|
|
const dom = new JSDOM(`<!doctype html><html><body>${bodyHtml}</body></html>`, {
|
|
runScripts: 'outside-only',
|
|
pretendToBeVisual: true,
|
|
});
|
|
const win = dom.window;
|
|
const parentPostMessage = vi.fn();
|
|
// jsdom defaults `window.parent` to `window` itself for top-level
|
|
// documents; replace it with a stub that has a spied postMessage so
|
|
// we can observe what the bridge would send to the embedding host.
|
|
Object.defineProperty(win, 'parent', {
|
|
configurable: true,
|
|
value: { postMessage: parentPostMessage },
|
|
});
|
|
|
|
// Run the bridge IIFE inside the jsdom window so its `document` /
|
|
// `window` refer to our DOM. We don't use `runScripts: 'dangerously'`
|
|
// — the IIFE is our trusted source, evaluated by `Function` in the
|
|
// jsdom realm.
|
|
const evaluate = new win.Function(script);
|
|
evaluate.call(win);
|
|
|
|
return { dom, win, parentPostMessage };
|
|
}
|
|
|
|
describe('selection bridge — empty annotation surface (#890)', () => {
|
|
it('posts od:comment-targets with an empty list when the artifact has no annotated elements', async () => {
|
|
const { win, parentPostMessage } = setupBridgeDom(
|
|
// PRD-style mockup: real DOM, zero `data-od-id` / `data-screen-label`.
|
|
'<header><h1>Acme PRD</h1></header><main><section><p>Goals</p></section></main>',
|
|
'inspect',
|
|
);
|
|
|
|
// The bridge schedules the initial postTargets via setTimeout(0)
|
|
// after enabling the mode. Drain microtasks + the timer so the
|
|
// message lands before we assert.
|
|
await new Promise<void>((resolve) => win.setTimeout(resolve, 10));
|
|
|
|
const targetMessages = parentPostMessage.mock.calls
|
|
.map((call) => call[0])
|
|
.filter((message) => message?.type === 'od:comment-targets');
|
|
|
|
expect(targetMessages.length).toBeGreaterThan(0);
|
|
// Every targets-broadcast must be an empty list — there's nothing
|
|
// annotated to enumerate. If a future change starts inventing
|
|
// synthetic ids in `allTargets()`, this assertion fires before
|
|
// the host's empty-state hint silently disappears.
|
|
for (const message of targetMessages) {
|
|
expect(message.targets).toEqual([]);
|
|
}
|
|
});
|
|
|
|
it('does not post od:comment-target when the user clicks an unannotated element', async () => {
|
|
const { win, parentPostMessage } = setupBridgeDom(
|
|
'<header><h1 id="title">Acme PRD</h1></header>',
|
|
'inspect',
|
|
);
|
|
|
|
// Wait for bridge boot.
|
|
await new Promise<void>((resolve) => win.setTimeout(resolve, 10));
|
|
parentPostMessage.mockClear();
|
|
|
|
// Click directly on the <h1> — it has no `data-od-id` / `data-screen-label`,
|
|
// and no ancestor does either. The bridge's `closestTarget()` walks up
|
|
// to <html> and returns null; the click handler must bail before
|
|
// emitting a comment-target message.
|
|
const target = win.document.getElementById('title');
|
|
expect(target).not.toBeNull();
|
|
target!.dispatchEvent(
|
|
new win.MouseEvent('click', { bubbles: true, cancelable: true }),
|
|
);
|
|
|
|
const clickMessages = parentPostMessage.mock.calls
|
|
.map((call) => call[0])
|
|
.filter((message) => message?.type === 'od:comment-target');
|
|
expect(clickMessages).toEqual([]);
|
|
});
|
|
|
|
it('still posts od:comment-target when the click traverses up to an annotated ancestor', async () => {
|
|
// Sanity check / contract pin: the no-op behavior above is specific
|
|
// to the no-annotation case. When ANY ancestor carries `data-od-id`,
|
|
// the click must still resolve to that ancestor — this is the
|
|
// happy path the gallery has shipped since the bridge landed.
|
|
const { win, parentPostMessage } = setupBridgeDom(
|
|
'<main data-od-id="hero"><h1 id="title">Hero</h1></main>',
|
|
'inspect',
|
|
);
|
|
|
|
await new Promise<void>((resolve) => win.setTimeout(resolve, 10));
|
|
parentPostMessage.mockClear();
|
|
|
|
win.document.getElementById('title')!.dispatchEvent(
|
|
new win.MouseEvent('click', { bubbles: true, cancelable: true }),
|
|
);
|
|
|
|
const clickMessages = parentPostMessage.mock.calls
|
|
.map((call) => call[0])
|
|
.filter((message) => message?.type === 'od:comment-target');
|
|
expect(clickMessages).toHaveLength(1);
|
|
expect(clickMessages[0].elementId).toBe('hero');
|
|
});
|
|
});
|