feat(sdk): add find({ composition }) filter — Stage 6 WS-C completion

Closes the last headless-testable Stage 6 gap (F9 workstream C).

`find({ composition: "hf-host" })` returns all scopedIds whose prefix
matches the given host id — i.e. every element mounted inside that
sub-composition, at any depth. Combinable with other FindQuery fields
(tag, text, name, track). 3 new contract tests in session.subcomp.test.ts.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: vanceingalls

packages/sdk/src/session.subcomp.test.ts

@@ -324,7 +324,49 @@ describe("override-set — scoped id keys", () => {
   });
 });
 
-// ─── 5. Scoped id stability across serialize ──────────────────────────────────
+// ─── 5. find({ composition }) filter ─────────────────────────────────────────
+
+describe("find({ composition })", () => {
+  it("returns elements inside the named host sub-composition", async () => {
+    const html = inlinedHtml(`
+      <div data-hf-id="hf-root" data-hf-root>
+        <div data-hf-id="hf-host" data-composition-file="sub.html">
+          <p data-hf-id="hf-leaf">inside</p>
+        </div>
+        <p data-hf-id="hf-outer">outside</p>
+      </div>
+    `);
+    const comp = await openComposition(html);
+    const ids = comp.find({ composition: "hf-host" });
+    expect(ids).toContain("hf-host/hf-leaf");
+    expect(ids).not.toContain("hf-outer");
+    expect(ids).not.toContain("hf-host"); // host itself is in parent scope
+  });
+
+  it("returns empty array for unknown host id", async () => {
+    const html = inlinedHtml(
+      `<div data-hf-id="hf-root" data-hf-root><p data-hf-id="hf-p">x</p></div>`,
+    );
+    const comp = await openComposition(html);
+    expect(comp.find({ composition: "hf-no-such" })).toEqual([]);
+  });
+
+  it("can combine composition filter with other query fields", async () => {
+    const html = inlinedHtml(`
+      <div data-hf-id="hf-root" data-hf-root>
+        <div data-hf-id="hf-host" data-composition-file="sub.html">
+          <p data-hf-id="hf-a">match</p>
+          <span data-hf-id="hf-b">no</span>
+        </div>
+      </div>
+    `);
+    const comp = await openComposition(html);
+    const ids = comp.find({ composition: "hf-host", tag: "p" });
+    expect(ids).toEqual(["hf-host/hf-a"]);
+  });
+});
+
+// ─── 6. Scoped id stability across serialize ──────────────────────────────────
 
 describe("scopedId stability across serialize/re-parse", () => {
   it("scopedId values are identical after serialize + re-open", async () => {

packages/sdk/src/session.ts

@@ -186,6 +186,7 @@ class CompositionImpl implements Composition {
           if (query.text && !el.text?.includes(query.text)) return false;
           if (query.name && el.attributes["data-name"] !== query.name) return false;
           if (query.track !== undefined && el.trackIndex !== query.track) return false;
+          if (query.composition && !el.scopedId.startsWith(`${query.composition}/`)) return false;
           return true;
         })
         .map((el) => el.scopedId)

packages/sdk/src/types.ts

@@ -186,6 +186,8 @@ export interface FindQuery {
   text?: string;
   name?: string;
   track?: number;
+  /** Filter to elements inside a specific sub-composition host (by host hf-id). */
+  composition?: string;
 }
 
 // ─── Typed method sugar (F10) ─────────────────────────────────────────────────