Synchronize hosted Artifact selection with Collaboration

Traceability

• Spec ID: studio-artifact-surface-selection
• Status: Implemented
• Builds on: studio-agentic-artifact-interaction

Intent

Make the hosted Artifact itself a semantic selection surface. A Provider-owned opaque iframe may publish one address observation for the exact Artifact revision and surface binding that Studio mounted. Studio validates the frame source and identity, then resolves the address against the current interaction workspace before changing Collaboration state.

The event is an observation only. It carries no proposal continuation, decision identity, filesystem path, approval token, or mutation authority.

Acceptance Scenarios

• AC-1: The public Artifact contract defines a versioned hosted-selection event containing only Artifact id, exact revision, surface binding id, and a bounded semantic address.
• AC-2: ExternalHostedArtifactView accepts an event only from its mounted iframe and only when every identity field matches the current interaction-capable descriptor. Wrong revision, wrong binding, empty or oversized address, non-interactive Artifact, and unrelated window messages are ignored.
• AC-3: Collaboration resolves the published address against the current workspace targets. A valid Viewer selection updates the semantic target; unknown addresses cannot become proposal targets. Manual dropdown selection remains available and uses the same shared state.
• AC-4: Refreshing the same Artifact after Apply preserves the selected stable address when it remains present in the authoritative revision. A prepared or settled proposal is not silently retargeted by later iframe events.
• AC-5: The Draw.io hosted Viewer emits stable drawio:// addresses from explicit outline cell clicks. The real browser flow proves clicking a Viewer node updates Collaboration before steering, with zero document overflow and zero captured console/page error.

Non-goals

• Treating an iframe event as approval or write authority.
• Guessing semantic identity from coordinates or pixels.
• Generic canvas hit-testing, official draw.io internal event patching, hover synchronization, multi-selection, presence, or CRDT collaboration.
• Enabling interaction for Providers that do not advertise an interaction runtime.

Plan

1. Add the portable event contract and Host-side exact-binding validator.
2. Lift shared selection through Artifact View and Collaboration without moving proposal authority into the iframe.
3. Embed stable addresses in the Draw.io hosted document and publish them from explicit semantic outline clicks.
4. Add focused tests, real cross-repository Browser evidence, and current verification records before changing this spec to Implemented.

Evidence

• Core @qoder-ai/harness: Node 24 build and 20 files / 173 Vitest; dry-run pack 149051 B / 640903 B / 143 entries.
• @qoder-ai/harness-studio: Node 24 typecheck/build and 62 files / 491 Vitest; focused hosted-selection and interaction routes 2 files / 28 tests; dry-run pack 6968575 B / 37982755 B / 1146 entries.
• Focused oxlint and both repositories' git diff --check passed.
• Real in-app Browser against the cross-repository Studio Host clicked the Draw.io outline target Orders; Collaboration selected the exact drawio://complex-features.drawio/page/rich/cell/orders-swimlane address without using its dropdown. Approve once advanced b0340ff4…08ddf5 to 5666866e…a577c6, rendered Surface-selected Orders, retained the same stable address, and displayed authoritative readback evidence.
• 1440×900, 1024×768, and 390×844 screenshots were inspected in the Structurizr verification workspace at .verification/agentic-artifact-surface-selection-\{wide,compact,narrow\}.png; all had document/body scroll width equal to viewport width and the browser captured zero warning/error console entries.