feat(sdk): stage 7 step 2 — setSelection API

[vanceingalls]

What

Adds session.setSelection(ids: string[]) to the SDK Composition API. Fires a selectionchange event on the session; does not create an undo entry or emit a patch.

Why

Studio needs to mirror canvas selection state into the SDK session so downstream consumers (agent context, inspector panels, future collaborative cursors) can read who is selected without polling the DOM. Selection is metadata, not content — it must not appear in the undo stack or trigger a persist write.

How

• setSelection stores the id array in session state and emits selectionchange
• No patch event, no history entry, no persist write
• session.getSelection() returns the current ids
• 11 unit tests covering: set/get round-trip, selectionchange fires, multiple calls replace not append, empty array clears, no patch event emitted

Test plan

• session.subcomp.test.ts / session.test.ts: all 11 selection tests pass
• Integration: useSdkSelectionSync (PR feat(studio): stage 7 step 1 — wire SDK session into Studio #1443) calls setSelection on every canvas selection change and the session reflects it correctly

[vanceingalls]

• feat(studio): stage 7 step 3c — sdk cutover for inline-style ops #1452
• feat(studio): stage 7 step 3b — SDK shadow dispatch parity mode #1450
• feat(sdk,studio): stage 7 step 3a — persistPath + SDK session reload-on-change #1449
• feat(studio): stage 7 step 1 — wire SDK session into Studio #1443
• feat(sdk): stage 7 step 2 — setSelection API #1442 👈 (View in Graphite)
• feat(sdk): stage 7 step 1 — http persist adapter #1441
• feat(sdk): stage 6 — sub-composition scoped ids (F9) #1434 : 1 other dependent PR (#1429 )
• feat(sdk): stage 5 — export adapter factories from package root #1432
• feat(sdk): stage 4 — canUndo/canRedo, removeElement GSAP cascade, override-set cleanup #1431
• feat(sdk): can() returns CanResult; T4 dispatch-boundary tests #1426
• fix(sdk): fs adapter flush() tracks in-flight writes; add to T13 contract suite #1425
• feat(sdk): file-backed fs adapter + setTiming GSAP-script sync; add sdk-playground #1423
• refactor(core): swap studio-api read path from recast to acorn parser (T6e) #1392
• feat(core): parse-parity suite for acorn parser (T6d) #1370 : 1 other dependent PR (#1379 )
• feat(core): acorn GSAP write path — magic-string offset-splice (T6c) #1369
• feat(core): acorn GSAP read path with T6b differential corpus tests #1368
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[james-russo-rames-d-jusso]

Verified at HEAD 88f067ef.

Stage 7 step 2 — setSelection API (+96/-0). Thin state-setter plus selectionchange dispatch, well-tested. Verdict: approve-with-concerns.

What's good

• Defensive copy on both input ([...ids]) and output (h([...this.currentSelection])) — listeners can't mutate internal state. Good.
• Explicit tests that setSelection does NOT push to undo stack (line 269) and does NOT emit a patch event (line 281). Exactly the determinism / replay-safety properties the stack needs for #1450's shadow-parity to work.
• selection() proxy snapshots ids at call time (line 261) — no stale-ref hazard.

Concerns

• No equality check before firing selectionchange (packages/sdk/src/session.ts:224-227). setSelection(["hf-title"]) followed by setSelection(["hf-title"]) fires selectionchange twice. Wired into Studio via #1443's useSdkSelectionSync, this becomes a real perf risk: any React render that recreates the domEditGroupSelections array (even with identical contents) re-fires the effect → re-fires setSelection → re-fires selectionchange → potentially re-renders subscribers. Cheap fix: shallow-compare before assigning and skip the dispatch if unchanged. Worth doing now before #1450 starts measuring shadow-parity dispatch counts.

• No de-dup of input ids. setSelection(["hf-title", "hf-title"]) stores duplicates verbatim. Probably fine, but #1426's CanResult dispatch-boundary checks iterate selection — duplicate ids = duplicate work. Worth a Array.from(new Set(ids)) on the way in, or an explicit "callers are responsible for de-dup" note in the jsdoc.

• No validation that ids exist in the composition. setSelection(["nonexistent-id"]) succeeds silently. Tolerant API choice (matches getSelection returning whatever was set), but means a typo from an agent caller silently selects nothing. Not blocking — tolerant-by-default is consistent with the rest of the SDK surface.

Nits

• jsdoc on setSelection (types.ts:256) says "Pass [] to clear" — true, but setSelection(["only-hf-id"]) also implicitly clears any prior selection. The "replace" semantic is in the first half of the sentence; consider tightening to "Replaces the current selection (use [] to clear)."

What I didn't verify

• Whether #1450's shadow-parity comparison includes selectionchange event counts — if it does, the no-equality-check concern is a likely false-positive source for shadow-parity drift.

Review by Rames D Jusso

[miguel-heygen]

CI blocked by the root oxfmt failure in #1423. setSelection implementation is clean.

Strengths:

• packages/sdk/src/session.ts setSelection — correctly fires a fresh copy of the array to each listener ([...this.currentSelection]), so a listener that mutates its argument doesn't corrupt the stored selection. The snapshot test verifies this.
• Tests cover: empty-array clear, multi-id set, event payload copy, unsubscribe stops firing, undo-stack isolation, patch-event isolation. Comprehensive for a 5-line implementation.

Important:

• packages/sdk/src/session.ts setSelection does not validate that the ids exist in the document. Passing ids for elements that don't exist silently sets the selection. For a debug/dev experience, a console.warn or CanResult-style validation when an id resolves to null would help authors catch typos. Not a blocker — callers may intentionally set selection before the document is populated.

Nit:

• packages/sdk/src/types.ts — setSelection is documented "Replace the current selection; fires selectionchange." Missing: "Pass [] to clear." (already on the impl comment but not the type doc — copy it there for IDE hover).

Verdict: APPROVE (pending #1423 oxfmt fix)
Reasoning: Correct, minimal, and well-tested. Selection does not affect undo stack or patch events — correct isolation.

— magi

[vanceingalls]

Thanks @james-russo-rames-d-jusso and @miguel-heygen.

Fixed:

• Equality check — setSelection now shallow-compares before firing selectionchange. Same ids (same order) = no-op. Tests added.
• De-dup — Array.from(new Set(ids)) applied on input. setSelection(["hf-title", "hf-title"]) stores and compares as ["hf-title"]. Test added for de-dup + de-dup-equals-stored no-fire.
• setSelection JSDoc — already says "Replaces the current selection (pass [] to clear)" in both types.ts and the method doc. Confirmed on current HEAD.

Not changed:

• No validation that ids exist — intentional tolerant API. Agents may set selection before the doc is populated. A console.warn on non-existent id would be noise for that common pattern.

[vanceingalls]

@james-russo-rames-d-jusso — all concerns addressed in post-review commits

• No equality check: setSelection now shallow-compares (length + element-wise) before firing selectionchange. Same ids in same order → no-op.
• No de-dup: Array.from(new Set(ids)) applied on input before comparison and assignment.
• No validation that ids exist: left intentionally tolerant (consistent with the rest of the SDK surface). Added a note in the jsdoc.
• jsdoc "replace" semantic: tightened to "Replaces the current selection ([] to clear)".

The base branch was changed.