test(sdk): p2 edge cases — setText no-text-node, override-remove non-existent, flush in smoke

- setText on element with no prior text node (firstTextIdx=-1 path)
- applyOverrideSet null removal on non-existent prop is a no-op (no throw)
- smoke persist test uses comp.flush() instead of setTimeout
- can() JSDoc clarifies Phase 3b false-return is intentional feature-detection

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

Author: vanceingalls

packages/sdk/src/engine/mutate.test.ts

@@ -140,6 +140,17 @@ describe("setText", () => {
     expect(serializeDocument(parsed)).toBe(before);
   });
 
+  it("creates text node when element has no existing text node", () => {
+    const parsed = parseMutable(
+      '<div data-hf-id="hf-s" data-hf-root><span data-hf-id="hf-empty"></span></div>',
+    );
+    const result = applyOp(parsed, { type: "setText", target: "hf-empty", value: "Added" });
+    const el = parsed.document.querySelector('[data-hf-id="hf-empty"]');
+    expect(el?.textContent).toBe("Added");
+    expect(result.forward[0]?.op).toBe("replace");
+    expect(result.forward[0]?.value).toBe("Added");
+  });
+
   it("override-set key maps correctly", () => {
     expect(pathToKey("/elements/hf-title/text")).toBe("hf-title.text");
   });

packages/sdk/src/session.test.ts

@@ -98,6 +98,15 @@ describe("override-set replay on open", () => {
     expect(comp.getElement("hf-title")?.inlineStyles["color"]).toBeUndefined();
   });
 
+  it("null removal override on non-existent property is a safe no-op", async () => {
+    // backgroundColor doesn't exist on hf-title in the base; removing it must not throw.
+    const comp = await openComposition(BASE_HTML, {
+      overrides: { "hf-title.style.backgroundColor": null },
+    });
+    expect(comp.getElement("hf-title")).not.toBeNull();
+    expect(comp.getElement("hf-title")?.inlineStyles["backgroundColor"]).toBeUndefined();
+  });
+
   it("getOverrides returns the set the session was opened with", async () => {
     const overrides = { "hf-title.style.color": "#e63946" };
     const comp = await openComposition(BASE_HTML, { overrides });

packages/sdk/src/smoke.test.ts

@@ -220,9 +220,7 @@ describe("persist adapter", () => {
 
     const comp = await openComposition(BASE_HTML, { persist: adapter });
     comp.setStyle("hf-title", { color: "#f00" });
-
-    // Give the persist queue a tick to flush
-    await new Promise((r) => setTimeout(r, 20));
+    await comp.flush();
 
     expect(writeSpy).toHaveBeenCalled();
     const [, content] = writeSpy.mock.calls[0] as [string, string];

packages/sdk/src/types.ts

@@ -233,7 +233,12 @@ export interface Composition {
   // ── Advanced / agent layer (F10 layer 2) ──────────────────────────────────
   dispatch(op: EditOp, opts?: { origin?: unknown }): void;
   batch(fn: () => void, opts?: { origin?: unknown }): void;
-  /** Dry-run validation — would dispatch(op) succeed? UI enablement, agent precondition checks. */
+  /**
+   * Dry-run validation — would dispatch(op) succeed?
+   * Returns false for: unknown element id, missing root, unimplemented Phase 3b ops, unknown op types.
+   * Use as a feature-detection gate: `if (!comp.can(op)) return;` — Phase 3b ops always return false
+   * until the parser-backed engine ships. This is intentional: silent no-op is worse than skipping.
+   */
   can(op: EditOp): boolean;
 
   // ── Events (one typed emitter — F10) ──────────────────────────────────────