shadow-claw 1.23.3 → 1.24.0

package/src/components/shadow-claw-a2ui/shadow-claw-a2ui.test.ts

@@ -1,5 +1,6 @@
 import { jest } from "@jest/globals";
 
+import { setDB } from "../../db/db.js";
 import { registerBasicFunctions } from "../../ui/a2ui/registries/basicFunctions.js";
 import { A2UI_BASIC_CATALOG_ID } from "../../ui/a2ui/types.js";
 import { applyDataModelPatches } from "../../ui/a2ui/utils/applyDataModelUpdate.js";
@@ -9,6 +10,7 @@ import { resolveJsonPointer } from "../../ui/a2ui/utils/resolveJsonPointer.js";
 import type { A2UICreateSurface } from "../../ui/a2ui/types.js";
 
 beforeAll(() => {
+  setDB({} as any);
   registerBasicFunctions();
 });
 
@@ -131,6 +133,25 @@ describe("applyDataModelPatches", () => {
 // getSurfaceId() is a pure accessor we use as observable output.
 // ---------------------------------------------------------------------------
 
+// Mock readGroupFileBytes for workspace media resolution
+jest.mock("../../storage/readGroupFileBytes.js", () => ({
+  readGroupFileBytes: jest.fn(
+    async (_db: any, _groupId: string, filePath: string) => {
+      if (filePath.includes("error")) {
+        throw new Error("File read error");
+      }
+      return new Uint8Array([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+    },
+  ),
+}));
+
+global.URL.createObjectURL = jest.fn(() => "http://localhost/mock-blob");
+global.URL.revokeObjectURL = jest.fn();
+if (typeof window !== "undefined") {
+  window.URL.createObjectURL = global.URL.createObjectURL;
+  window.URL.revokeObjectURL = global.URL.revokeObjectURL;
+}
+
 // Mock ShadowClawElement so we can instantiate without full browser lifecycle
 jest.mock("../shadow-claw-element.js", () => {
   class MockBase extends HTMLElement {
@@ -140,9 +161,12 @@ jest.mock("../shadow-claw-element.js", () => {
     constructor() {
       super();
       this.attachShadow({ mode: "open" });
+      const surface = document.createElement("div");
+      surface.className = "a2ui__surface";
       const root = document.createElement("div");
       root.className = "a2ui__root";
-      this.shadowRoot?.replaceChildren(root);
+      surface.appendChild(root);
+      this.shadowRoot?.replaceChildren(surface);
     }
 
     connectedCallback() {}
@@ -633,4 +657,1138 @@ describe("ShadowClawA2UI action dispatch", () => {
     expect((texts[2] as HTMLElement).textContent?.trim()).toBe("2025-12-17");
     expect((texts[3] as HTMLElement).textContent?.trim()).toBe("⛅");
   });
+
+  it("handles AudioPlayer, Video, and Image rendering and action handlers", async () => {
+    const el = document.createElement("shadow-claw-a2ui") as any;
+    el.groupId = "peer:01ktq6kh3bb9nf37a2wpeeb64v";
+    document.body.appendChild(el);
+
+    await (el as any).onTemplateReady;
+
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "createSurface",
+      surfaceId: "media-surface",
+      catalogId: A2UI_BASIC_CATALOG_ID,
+      components: [
+        {
+          id: "root",
+          component: "Column",
+          children: ["img-1", "vid-1", "btn-play", "btn-pause"],
+        },
+        {
+          id: "img-1",
+          component: "Image",
+          url: "photo.png",
+          alt: "A photo",
+        },
+        {
+          id: "vid-1",
+          component: "Video",
+          url: "clip.mp4",
+        },
+        {
+          id: "btn-play",
+          component: "Button",
+          label: "Play",
+          action: "playTrack",
+        },
+        {
+          id: "btn-pause",
+          component: "Button",
+          label: "Pause",
+          action: "pauseTrack",
+        },
+      ] as any,
+    });
+
+    const root = el.shadowRoot;
+    const img = root?.querySelector("img");
+    const video = root?.querySelector("video");
+    const buttons = root?.querySelectorAll("button") || [];
+
+    expect(img).not.toBeNull();
+    expect(video).not.toBeNull();
+    expect(buttons.length).toBeGreaterThan(0);
+
+    // Test deleteSurface
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "deleteSurface",
+      surfaceId: "media-surface",
+    });
+    expect(root?.querySelector(".a2ui__root")?.children.length).toBe(0);
+
+    document.body.removeChild(el);
+  });
+
+  it("handles actionResponse and callFunction envelopes", async () => {
+    const el = document.createElement("shadow-claw-a2ui") as any;
+    el.groupId = "peer:test-group";
+    document.body.appendChild(el);
+
+    await (el as any).onTemplateReady;
+
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "createSurface",
+      surfaceId: "interactive-surface",
+      catalogId: A2UI_BASIC_CATALOG_ID,
+      components: [
+        {
+          id: "root",
+          component: "Text",
+          text: {
+            path: "/user/name",
+          },
+        },
+      ] as any,
+      dataModel: {
+        user: { name: "Alice" },
+      },
+    });
+
+    const root = el.shadowRoot;
+    expect(root?.querySelector(".a2ui__text")?.textContent?.trim()).toBe(
+      "Alice",
+    );
+
+    // Apply actionResponse to update data model
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "actionResponse",
+      surfaceId: "interactive-surface",
+      responsePath: "/user/name",
+      value: "Bob",
+    });
+
+    expect(root?.querySelector(".a2ui__text")?.textContent?.trim()).toBe("Bob");
+
+    // Call function
+    let functionResponseDetail: any = null;
+    el.addEventListener("shadow-claw-a2ui-function-response", (evt: any) => {
+      functionResponseDetail = evt.detail;
+    });
+
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "callFunction",
+      surfaceId: "interactive-surface",
+      callId: "call-1",
+      call: {
+        call: "capitalize",
+        args: {
+          value: "world",
+        },
+      },
+    });
+
+    expect(functionResponseDetail).not.toBeNull();
+    expect(functionResponseDetail.response.value).toBe("World");
+
+    // Call function with error
+    let functionErrorDetail: any = null;
+    el.addEventListener("shadow-claw-a2ui-function-response", (evt: any) => {
+      functionErrorDetail = evt.detail;
+    });
+
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "callFunction",
+      surfaceId: "interactive-surface",
+      callId: "call-2",
+      call: {
+        call: "nonExistentFunction",
+        args: {},
+      },
+    });
+
+    expect(functionErrorDetail).not.toBeNull();
+    expect(functionErrorDetail.response.error).toContain(
+      "INVALID_FUNCTION_CALL",
+    );
+
+    document.body.removeChild(el);
+  });
+
+  it("handles play, playTrack, pause, pauseTrack, and closeModal actions locally", async () => {
+    const el = document.createElement("shadow-claw-a2ui") as any;
+    el.groupId = "peer:test-media";
+    document.body.appendChild(el);
+
+    await (el as any).onTemplateReady;
+
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "createSurface",
+      surfaceId: "actions-surface",
+      catalogId: A2UI_BASIC_CATALOG_ID,
+      components: [
+        {
+          id: "root",
+          component: "Column",
+          children: ["aud", "vid", "mod", "btn-play", "btn-pause", "btn-close"],
+        },
+        { id: "aud", component: "AudioPlayer", url: "track.mp3" },
+        { id: "vid", component: "Video", url: "clip.mp4" },
+        {
+          id: "mod",
+          component: "Modal",
+          trigger: "mod-btn",
+          content: "mod-txt",
+        },
+        { id: "mod-btn", component: "Text", text: "Open Modal" },
+        { id: "mod-txt", component: "Text", text: "Modal Body" },
+        {
+          id: "btn-play",
+          component: "Button",
+          text: "Play",
+          action: { event: { name: "playTrack" } },
+        },
+        {
+          id: "btn-pause",
+          component: "Button",
+          text: "Pause",
+          action: { id: "pauseTrack" },
+        },
+        {
+          id: "btn-close",
+          component: "Button",
+          text: "Close",
+          action: { event: { name: "closeModal" } },
+        },
+      ] as any,
+    });
+
+    const root = el.shadowRoot;
+    const audio = root.querySelector("audio");
+    const video = root.querySelector("video");
+    const modalOverlay = root.querySelector(".a2ui__modal-overlay");
+
+    // Mock play/pause on audio and video
+    audio.play = jest.fn<() => Promise<void>>().mockResolvedValue(undefined);
+    audio.pause = jest.fn();
+    video.play = jest.fn<() => Promise<void>>().mockResolvedValue(undefined);
+    video.pause = jest.fn();
+
+    // Find and click Play button
+    const buttons = Array.from(
+      root.querySelectorAll("button"),
+    ) as HTMLButtonElement[];
+    const playBtn = buttons.find((b) => b.textContent?.includes("Play"));
+    playBtn?.click();
+    expect(audio.play).toHaveBeenCalled();
+    expect(video.play).toHaveBeenCalled();
+
+    // Find and click Pause button
+    const pauseBtn = buttons.find((b) => b.textContent?.includes("Pause"));
+    pauseBtn?.click();
+    expect(audio.pause).toHaveBeenCalled();
+    expect(video.pause).toHaveBeenCalled();
+
+    // Open modal then test closeModal button
+    if (modalOverlay) {
+      modalOverlay.style.display = "block";
+    }
+    const closeBtn = buttons.find((b) => b.textContent?.includes("Close"));
+    closeBtn?.click();
+    if (modalOverlay) {
+      expect(modalOverlay.style.display).toBe("none");
+    }
+
+    document.body.removeChild(el);
+  });
+
+  it("resolves deferred workspace media to blob URLs for various extensions", async () => {
+    const el = document.createElement("shadow-claw-a2ui") as any;
+    el.groupId = "group:workspace-123";
+    document.body.appendChild(el);
+
+    await (el as any).onTemplateReady;
+
+    const extensions = [
+      "file.jpg",
+      "file.jpeg",
+      "file.png",
+      "file.gif",
+      "file.webp",
+      "file.svg",
+      "file.mp4",
+      "file.m4v",
+      "file.webm",
+      "file.mkv",
+      "file.mov",
+      "file.mp3",
+      "file.wav",
+      "file.flac",
+      "file.aac",
+      "file.m4a",
+    ];
+
+    const components: any[] = [
+      {
+        id: "root",
+        component: "Column",
+        children: extensions.map((_, i) => `media-${i}`),
+      },
+    ];
+
+    extensions.forEach((ext, i) => {
+      if (
+        ext.endsWith(".mp4") ||
+        ext.endsWith(".webm") ||
+        ext.endsWith(".mov") ||
+        ext.endsWith(".mkv") ||
+        ext.endsWith(".m4v")
+      ) {
+        components.push({
+          id: `media-${i}`,
+          component: "Video",
+          url: ext,
+          posterUrl: "poster.png",
+        });
+      } else if (
+        ext.endsWith(".mp3") ||
+        ext.endsWith(".wav") ||
+        ext.endsWith(".flac") ||
+        ext.endsWith(".aac") ||
+        ext.endsWith(".m4a")
+      ) {
+        components.push({
+          id: `media-${i}`,
+          component: "AudioPlayer",
+          url: ext,
+          description: `Audio ${ext}`,
+        });
+      } else {
+        components.push({
+          id: `media-${i}`,
+          component: "Image",
+          url: ext,
+          alt: `Image ${ext}`,
+        });
+      }
+    });
+
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "createSurface",
+      surfaceId: "all-media-surface",
+      catalogId: A2UI_BASIC_CATALOG_ID,
+      components,
+      dataModel: {},
+    });
+
+    // Also call render() override to test line coverage
+    await el.render();
+
+    // Allow promise resolution for blob conversion
+    await new Promise((r) => setTimeout(r, 50));
+
+    const images = el.shadowRoot.querySelectorAll("img");
+    expect(images.length).toBeGreaterThan(0);
+
+    // Test with error file
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "createSurface",
+      surfaceId: "error-media-surface",
+      catalogId: A2UI_BASIC_CATALOG_ID,
+      components: [
+        { id: "root", component: "Image", url: "error-image.jpg" },
+      ] as any,
+      dataModel: {},
+    });
+    await new Promise((r) => setTimeout(r, 50));
+
+    document.body.removeChild(el);
+  });
+
+  it("handles unknown component IDs and unknown component types gracefully", async () => {
+    const el = document.createElement("shadow-claw-a2ui") as any;
+    el.groupId = "peer:test";
+    document.body.appendChild(el);
+
+    await (el as any).onTemplateReady;
+
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "createSurface",
+      surfaceId: "unknown-surface",
+      catalogId: A2UI_BASIC_CATALOG_ID,
+      components: [
+        {
+          id: "root",
+          component: "Column",
+          children: ["missing-child", "unknown-type-child"],
+        },
+        { id: "unknown-type-child", component: "NonExistentComponentType" },
+      ] as any,
+      dataModel: {},
+    });
+
+    expect(warnSpy).toHaveBeenCalled();
+    warnSpy.mockRestore();
+
+    document.body.removeChild(el);
+  });
+});
+
+describe("Basic catalog components unit tests", () => {
+  const mockSurface = {
+    surfaceId: "s1",
+    components: {},
+    dataModel: {
+      isDone: true,
+      fruit: "apple",
+      fruits: ["apple", "banana"],
+      count: 25,
+      dateVal: "2025-05-15T10:30",
+      notes: "Some initial notes",
+      item: { name: "Scoped item" },
+    },
+    rootComponentId: "root",
+  };
+
+  it("CheckBox handles path, $dataModel, boolean, change events, and actions", async () => {
+    const updatePointer = jest.fn();
+    const dispatchAction = jest.fn();
+
+    // 1. Spec canonical path
+    const cb1 = (await import("./catalog/basic/checkbox.js")).renderCheckBox(
+      {
+        id: "cb1",
+        component: "CheckBox",
+        label: "Mark Done",
+        value: { path: "/isDone" },
+        action: { event: { name: "checkbox-toggle" } },
+      },
+      mockSurface,
+      { updateDataModelPointer: updatePointer, dispatchAction },
+    );
+    const input1 = cb1.querySelector("input")!;
+    expect(input1.checked).toBe(true);
+    input1.checked = false;
+    input1.dispatchEvent(new Event("change"));
+    expect(updatePointer).toHaveBeenCalledWith("/isDone", false);
+    expect(dispatchAction).toHaveBeenCalledWith("checkbox-toggle");
+
+    // 2. Deprecated $dataModel
+    const cb2 = (await import("./catalog/basic/checkbox.js")).renderCheckBox(
+      {
+        id: "cb2",
+        component: "CheckBox",
+        label: "Mark Done 2",
+        value: { $dataModel: "/isDone" },
+        action: { id: "legacy-action" } as any,
+      },
+      mockSurface,
+      { updateDataModelPointer: updatePointer, dispatchAction },
+    );
+    const input2 = cb2.querySelector("input")!;
+    input2.checked = true;
+    input2.dispatchEvent(new Event("change"));
+    expect(updatePointer).toHaveBeenCalledWith("/isDone", true);
+    expect(dispatchAction).toHaveBeenCalledWith("legacy-action");
+
+    // 3. Boolean static value
+    const cb3 = (await import("./catalog/basic/checkbox.js")).renderCheckBox(
+      {
+        id: "cb3",
+        component: "CheckBox",
+        label: "Static",
+        value: false,
+      },
+      mockSurface,
+      { updateDataModelPointer: updatePointer, dispatchAction },
+    );
+    expect(cb3.querySelector("input")!.checked).toBe(false);
+  });
+
+  it("ChoicePicker handles single and multiple selection with primitive and object options", async () => {
+    const updatePointer = jest.fn();
+
+    // 1. Single selection with path
+    const cp1 = (
+      await import("./catalog/basic/choice-picker.js")
+    ).renderChoicePicker(
+      {
+        id: "cp1",
+        component: "ChoicePicker",
+        options: [
+          { value: "apple", label: "Apple" },
+          { value: "orange", label: "Orange" },
+        ],
+        value: { path: "/fruit" },
+      },
+      mockSurface,
+      { updateDataModelPointer: updatePointer },
+    );
+    const radios = cp1.querySelectorAll<HTMLInputElement>(
+      "input[type='radio']",
+    );
+    expect(radios[0].checked).toBe(true);
+    expect(radios[1].checked).toBe(false);
+
+    radios[1].checked = true;
+    radios[1].dispatchEvent(new Event("change"));
+    expect(updatePointer).toHaveBeenCalledWith("/fruit", "orange");
+
+    // 2. Multiple selection with $dataModel and primitive options
+    const cp2 = (
+      await import("./catalog/basic/choice-picker.js")
+    ).renderChoicePicker(
+      {
+        id: "cp2",
+        component: "ChoicePicker",
+        variant: "multipleSelection",
+        options: ["apple", "banana", "grape"] as any,
+        value: { $dataModel: "/fruits" },
+      },
+      mockSurface,
+      { updateDataModelPointer: updatePointer },
+    );
+    const checkboxes = cp2.querySelectorAll<HTMLInputElement>(
+      "input[type='checkbox']",
+    );
+    expect(checkboxes.length).toBe(3);
+    expect(checkboxes[0].checked).toBe(true);
+    expect(checkboxes[1].checked).toBe(true);
+    expect(checkboxes[2].checked).toBe(false);
+
+    checkboxes[2].checked = true;
+    checkboxes[2].dispatchEvent(new Event("change"));
+    expect(updatePointer).toHaveBeenCalledWith("/fruits", [
+      "apple",
+      "banana",
+      "grape",
+    ]);
+  });
+
+  it("DateTimeInput handles date, time, datetime-local, and text formats", async () => {
+    const updatePointer = jest.fn();
+
+    // 1. datetime-local
+    const dt1 = (
+      await import("./catalog/basic/date-time-input.js")
+    ).renderDateTimeInput(
+      {
+        id: "dt1",
+        component: "DateTimeInput",
+        label: "Event Time",
+        enableDate: true,
+        enableTime: true,
+        value: { path: "/dateVal" },
+        min: "2025-01-01T00:00",
+        max: "2025-12-31T23:59",
+      },
+      mockSurface,
+      { updateDataModelPointer: updatePointer },
+    );
+    const input1 = dt1.querySelector("input")!;
+    expect(input1.type).toBe("datetime-local");
+    expect(input1.value).toBe("2025-05-15T10:30");
+    input1.value = "2025-06-01T12:00";
+    input1.dispatchEvent(new Event("input"));
+    expect(updatePointer).toHaveBeenCalledWith("/dateVal", "2025-06-01T12:00");
+
+    // 2. Date only with $dataModel
+    const dt2 = (
+      await import("./catalog/basic/date-time-input.js")
+    ).renderDateTimeInput(
+      {
+        id: "dt2",
+        component: "DateTimeInput",
+        enableDate: true,
+        value: { $dataModel: "/dateVal" },
+      },
+      mockSurface,
+      { updateDataModelPointer: updatePointer },
+    );
+    expect(dt2.querySelector("input")!.type).toBe("date");
+
+    // 3. Time only
+    const dt3 = (
+      await import("./catalog/basic/date-time-input.js")
+    ).renderDateTimeInput(
+      {
+        id: "dt3",
+        component: "DateTimeInput",
+        enableTime: true,
+        value: "14:30",
+      },
+      mockSurface,
+      { updateDataModelPointer: updatePointer },
+    );
+    expect(dt3.querySelector("input")!.type).toBe("time");
+    expect(dt3.querySelector("input")!.value).toBe("14:30");
+
+    // 4. Fallback text
+    const dt4 = (
+      await import("./catalog/basic/date-time-input.js")
+    ).renderDateTimeInput(
+      {
+        id: "dt4",
+        component: "DateTimeInput",
+      },
+      mockSurface,
+      { updateDataModelPointer: updatePointer },
+    );
+    expect(dt4.querySelector("input")!.type).toBe("text");
+  });
+
+  it("Slider handles number and dynamic string values, steps, min, max", async () => {
+    const updatePointer = jest.fn();
+
+    // 1. Path binding with steps
+    const s1 = (await import("./catalog/basic/slider.js")).renderSlider(
+      {
+        id: "s1",
+        component: "Slider",
+        label: "Volume",
+        min: 0,
+        max: 100,
+        steps: 5,
+        value: { path: "/count" },
+        weight: 1,
+      },
+      mockSurface,
+      { updateDataModelPointer: updatePointer },
+    );
+    const input1 = s1.querySelector("input")!;
+    expect(input1.min).toBe("0");
+    expect(input1.max).toBe("100");
+    expect(input1.step).toBe("5");
+    expect(input1.value).toBe("25");
+
+    input1.value = "30";
+    input1.dispatchEvent(new Event("input"));
+    expect(updatePointer).toHaveBeenCalledWith("/count", 30);
+
+    // 2. $dataModel binding
+    const s2 = (await import("./catalog/basic/slider.js")).renderSlider(
+      {
+        id: "s2",
+        component: "Slider",
+        value: { $dataModel: "/count" },
+      },
+      mockSurface,
+      { updateDataModelPointer: updatePointer },
+    );
+    const input2 = s2.querySelector("input")!;
+    input2.value = "40";
+    input2.dispatchEvent(new Event("input"));
+    expect(updatePointer).toHaveBeenCalledWith("/count", 40);
+
+    // 3. Static number value
+    const s3 = (await import("./catalog/basic/slider.js")).renderSlider(
+      {
+        id: "s3",
+        component: "Slider",
+        value: 75,
+      },
+      mockSurface,
+      { updateDataModelPointer: updatePointer },
+    );
+    expect(s3.querySelector("input")!.value).toBe("75");
+  });
+
+  it("TextField handles longText, number, obscured, patterns, and inputs", async () => {
+    const updateKey = jest.fn();
+
+    // 1. Long text (textarea)
+    const tf1 = (await import("./catalog/basic/text-field.js")).renderTextField(
+      {
+        id: "tf1",
+        component: "TextField",
+        label: "Notes",
+        variant: "longText",
+        value: { path: "/notes" },
+      },
+      mockSurface,
+      { updateDataModelKey: updateKey },
+    );
+    const textarea = tf1.querySelector("textarea")!;
+    expect(textarea).toBeTruthy();
+    expect(textarea.value).toBe("Some initial notes");
+    textarea.value = "Updated notes";
+    textarea.dispatchEvent(new Event("input"));
+    expect(updateKey).toHaveBeenCalled();
+
+    // 2. Obscured (password) with regex
+    const tf2 = (await import("./catalog/basic/text-field.js")).renderTextField(
+      {
+        id: "tf2",
+        component: "TextField",
+        label: "Password",
+        variant: "obscured",
+        validationRegexp: "^[0-9]{4}$",
+      },
+      mockSurface,
+      { updateDataModelKey: updateKey },
+    );
+    const input2 = tf2.querySelector("input")!;
+    expect(input2.type).toBe("password");
+    expect(input2.pattern).toBe("^[0-9]{4}$");
+
+    // 3. Number variant
+    const tf3 = (await import("./catalog/basic/text-field.js")).renderTextField(
+      {
+        id: "tf3",
+        component: "TextField",
+        label: "Age",
+        variant: "number",
+        value: "42",
+      },
+      mockSurface,
+      { updateDataModelKey: updateKey },
+    );
+    const input3 = tf3.querySelector("input")!;
+    expect(input3.type).toBe("number");
+    expect(input3.value).toBe("42");
+    input3.dispatchEvent(new Event("input"));
+    expect(updateKey).toHaveBeenCalled();
+  });
+
+  it("Button handles variants, checked state, child labels, and actions", async () => {
+    const dispatchAction = jest.fn();
+    const renderComponent = jest.fn((id: string) => {
+      const el = document.createElement("span");
+      el.textContent = `Child ${id}`;
+      return el;
+    });
+
+    // 1. Variant, checked, child component
+    const surfaceWithChild = {
+      ...mockSurface,
+      components: {
+        "btn-child": { id: "btn-child", component: "Text", text: "Submit" },
+      },
+    };
+    const b1 = (await import("./catalog/basic/button.js")).renderButton(
+      {
+        id: "b1",
+        component: "Button",
+        variant: "secondary",
+        checked: true,
+        child: "btn-child",
+        action: { event: { name: "submit-action" } },
+      },
+      surfaceWithChild as any,
+      { renderComponent, dispatchAction },
+    );
+    expect(b1.className).toContain("a2ui__button--secondary");
+    expect(b1.className).toContain("a2ui__button--checked");
+    expect(renderComponent).toHaveBeenCalledWith("btn-child");
+    b1.click();
+    expect(dispatchAction).toHaveBeenCalledWith("submit-action");
+
+    // 2. Fallback text, action with name property
+    const b2 = (await import("./catalog/basic/button.js")).renderButton(
+      {
+        id: "b2",
+        component: "Button",
+        text: "Fallback Text",
+        action: { name: "named-action" } as any,
+      } as any,
+      mockSurface,
+      { renderComponent, dispatchAction },
+    );
+    expect(b2.textContent).toBe("Fallback Text");
+    b2.click();
+    expect(dispatchAction).toHaveBeenCalledWith("named-action");
+  });
+
+  it("Modal handles trigger clicks, overlay backdrop click, and Escape key", async () => {
+    const attachModalOverlay = jest.fn();
+    const renderComponent = jest.fn((id: string) => {
+      const el = document.createElement("div");
+      el.className = id;
+      el.textContent = `Rendered ${id}`;
+      return el;
+    });
+
+    const m = (await import("./catalog/basic/modal.js")).renderModal(
+      {
+        id: "m1",
+        component: "Modal",
+        trigger: "trig-id",
+        content: "cont-id",
+        weight: 1,
+      },
+      mockSurface,
+      { renderComponent, attachModalOverlay },
+    );
+
+    expect(attachModalOverlay).toHaveBeenCalled();
+    const overlay = attachModalOverlay.mock.calls[0][0] as HTMLElement;
+    expect(overlay.style.display).toBe("none");
+
+    // Click trigger to open
+    const trigger = m.querySelector("div.trig-id") || m.children[0];
+    trigger.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    expect(overlay.style.display).toBe("block");
+    expect(overlay.querySelector(".cont-id")).toBeTruthy();
+
+    // Click backdrop to close
+    overlay.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    expect(overlay.style.display).toBe("none");
+
+    // Open again and press Escape to close
+    trigger.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    expect(overlay.style.display).toBe("block");
+    overlay.dispatchEvent(
+      new KeyboardEvent("keydown", { key: "Escape", bubbles: true }),
+    );
+    expect(overlay.style.display).toBe("none");
+
+    // Fallback trigger button
+    const mFallback = (await import("./catalog/basic/modal.js")).renderModal(
+      {
+        id: "m2",
+        component: "Modal",
+        trigger: "missing-trig",
+        content: "cont-id",
+      },
+      mockSurface,
+      { renderComponent: () => null, attachModalOverlay: () => {} },
+    );
+    expect(mFallback.querySelector("button")?.textContent).toBe("Open");
+  });
+
+  it("Tabs handles tab click switching and warns on missing tabs", async () => {
+    const renderComponent = jest.fn((id: string) => {
+      const el = document.createElement("div");
+      el.className = `content-${id}`;
+      return el;
+    });
+
+    const tabsComponent = (await import("./catalog/basic/tabs.js")).renderTabs(
+      {
+        id: "t1",
+        component: "Tabs",
+        tabs: [
+          { title: "Tab 1", child: "c1" },
+          { title: "Tab 2", child: "c2" },
+        ],
+        weight: 2,
+      },
+      mockSurface,
+      { renderComponent },
+    );
+
+    const headers =
+      tabsComponent.querySelectorAll<HTMLButtonElement>(".a2ui__tab-header");
+    expect(headers.length).toBe(2);
+    expect(headers[0].classList.contains("active")).toBe(true);
+
+    // Click tab 2
+    headers[1].click();
+    expect(headers[1].classList.contains("active")).toBe(true);
+    expect(headers[0].classList.contains("active")).toBe(false);
+    expect(tabsComponent.querySelector(".content-c2")).toBeTruthy();
+  });
+
+  it("Icon renders string name and path object", async () => {
+    // String name
+    const i1 = (await import("./catalog/basic/icon.js")).renderIcon(
+      {
+        id: "i1",
+        component: "Icon",
+        name: "star",
+        weight: 1,
+      },
+      mockSurface,
+    );
+    expect(i1.dataset.iconName).toBe("star");
+    expect(i1.textContent).toBe("star");
+
+    // Object path
+    const i2 = (await import("./catalog/basic/icon.js")).renderIcon(
+      {
+        id: "i2",
+        component: "Icon",
+        name: { path: "custom-icon.png" } as any,
+      },
+      mockSurface,
+    );
+    const img = i2.querySelector("img");
+    expect(img).toBeTruthy();
+    expect(img?.getAttribute("src")).toBe("custom-icon.png");
+  });
+
+  it("shared helpers: variantToTag and renderChildrenList", async () => {
+    const { variantToTag, renderChildrenList, applyWeight } =
+      await import("./catalog/basic/shared.js");
+
+    // variantToTag
+    expect(variantToTag("h1")).toBe("h1");
+    expect(variantToTag("h2")).toBe("h2");
+    expect(variantToTag("h3")).toBe("h3");
+    expect(variantToTag("h4")).toBe("h4");
+    expect(variantToTag("h5")).toBe("h5");
+    expect(variantToTag("body" as any)).toBe("span");
+
+    // applyWeight
+    const el = document.createElement("div");
+    applyWeight(el, 3);
+    expect(el.style.flexGrow).toBe("3");
+
+    // renderChildrenList with array of ids
+    const appended: HTMLElement[] = [];
+    const mockCtx = {
+      renderComponent: (id: string) => {
+        const d = document.createElement("div");
+        d.id = id;
+        return d;
+      },
+    };
+    renderChildrenList(["item-1", "item-2"], mockSurface, mockCtx, (c) =>
+      appended.push(c),
+    );
+    expect(appended.length).toBe(2);
+
+    // renderChildrenList with array of { id }
+    const appendedObj: HTMLElement[] = [];
+    renderChildrenList([{ id: "item-3" }] as any, mockSurface, mockCtx, (c) =>
+      appendedObj.push(c),
+    );
+    expect(appendedObj.length).toBe(1);
+
+    // renderChildrenList with template
+    const appendedTmpl: HTMLElement[] = [];
+    renderChildrenList(
+      { path: "/fruits", componentId: "fruit-item" },
+      mockSurface,
+      mockCtx,
+      (c) => appendedTmpl.push(c),
+    );
+    expect(appendedTmpl.length).toBe(2);
+  });
+
+  it("handles scoped /@item updates for nested form controls", async () => {
+    const el = document.createElement("shadow-claw-a2ui") as any;
+    el.groupId = "peer:scoped-test";
+    document.body.appendChild(el);
+
+    await (el as any).onTemplateReady;
+
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "createSurface",
+      surfaceId: "scoped-surface",
+      catalogId: A2UI_BASIC_CATALOG_ID,
+      components: [
+        {
+          id: "root",
+          component: "List",
+          children: {
+            path: "/todos",
+            componentId: "todo-item",
+          },
+        },
+        {
+          id: "todo-item",
+          component: "Column",
+          children: ["todo-tf", "todo-cb"],
+        },
+        {
+          id: "todo-tf",
+          component: "TextField",
+          label: "Title",
+          value: { path: "/@item/title" },
+        },
+        {
+          id: "todo-cb",
+          component: "CheckBox",
+          label: "Completed",
+          value: { path: "/@item/done" },
+        },
+      ] as any,
+      dataModel: {
+        todos: [
+          { title: "Buy groceries", done: false },
+          { title: "Walk dog", done: true },
+        ],
+      },
+    });
+
+    const root = el.shadowRoot;
+    const inputs = root.querySelectorAll(
+      "input[type='text'], input:not([type])",
+    );
+    const checkboxes = root.querySelectorAll("input[type='checkbox']");
+
+    expect(inputs.length).toBe(2);
+    expect(checkboxes.length).toBe(2);
+
+    // Edit first textfield
+    const tf0 = inputs[0] as HTMLInputElement;
+    tf0.value = "Buy organic groceries";
+    tf0.dispatchEvent(new Event("input"));
+
+    // Check first checkbox
+    const cb0 = checkboxes[0] as HTMLInputElement;
+    cb0.checked = true;
+    cb0.dispatchEvent(new Event("change"));
+
+    // Trigger action to verify dataModel has updated scoped item values
+    let receivedAction: any = null;
+    el.addEventListener("shadow-claw-a2ui-action", (e: any) => {
+      receivedAction = e.detail;
+    });
+
+    // Apply createSurface with sendDataModel: true
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "createSurface",
+      surfaceId: "send-dm-surface",
+      catalogId: A2UI_BASIC_CATALOG_ID,
+      sendDataModel: true,
+      components: [
+        {
+          id: "root",
+          component: "Button",
+          text: "Submit All",
+          action: { id: "submit-all" },
+        },
+      ] as any,
+      dataModel: { test: "val" },
+    });
+
+    const subBtn = el.shadowRoot.querySelector("button");
+    subBtn?.click();
+    expect(receivedAction).not.toBeNull();
+    expect(receivedAction.action.dataModel).toEqual({ test: "val" });
+
+    document.body.removeChild(el);
+  });
+
+  it("handles resolveMediaUrl and poster format edge cases", async () => {
+    const el = document.createElement("shadow-claw-a2ui") as any;
+    el.groupId = "group:test:colons";
+    document.body.appendChild(el);
+
+    await (el as any).onTemplateReady;
+
+    // Test multiple poster formats
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "createSurface",
+      surfaceId: "poster-surface",
+      catalogId: A2UI_BASIC_CATALOG_ID,
+      components: [
+        {
+          id: "root",
+          component: "Column",
+          children: [
+            "v1",
+            "v2",
+            "v3",
+            "img-external",
+            "img-data",
+            "img-file",
+            "img-already-files",
+            "img-empty",
+          ],
+        },
+        {
+          id: "v1",
+          component: "Video",
+          url: "v1.mp4",
+          posterUrl: "poster.gif",
+        },
+        {
+          id: "v2",
+          component: "Video",
+          url: "v2.mp4",
+          posterUrl: "poster.webp",
+        },
+        {
+          id: "v3",
+          component: "Video",
+          url: "v3.mp4",
+          posterUrl: "poster.jpeg",
+        },
+        {
+          id: "img-external",
+          component: "Image",
+          url: "https://example.com/ext.jpg",
+        },
+        {
+          id: "img-data",
+          component: "Image",
+          url: "data:image/png;base64,123",
+        },
+        { id: "img-file", component: "Image", url: "file:///local/image.png" },
+        {
+          id: "img-already-files",
+          component: "Image",
+          url: "/files/group-abc/image.png",
+        },
+        { id: "img-empty", component: "Image", url: "" },
+      ] as any,
+      dataModel: {},
+    });
+
+    await el.render();
+    await new Promise((r) => setTimeout(r, 50));
+
+    // Test with missing groupId
+    const warnSpy = jest.spyOn(console, "warn").mockImplementation(() => {});
+    el.groupId = "";
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "createSurface",
+      surfaceId: "no-group-surface",
+      catalogId: A2UI_BASIC_CATALOG_ID,
+      components: [{ id: "root", component: "Image", url: "image.png" }] as any,
+      dataModel: {},
+    });
+    expect(warnSpy).toHaveBeenCalled();
+    warnSpy.mockRestore();
+
+    // Test updateDataModel without value (delete/unset)
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "updateDataModel",
+      surfaceId: "no-group-surface",
+      path: "/someKey",
+    });
+
+    // Test actionResponse without responsePath
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "actionResponse",
+      surfaceId: "no-group-surface",
+      value: "ignored",
+    });
+
+    // Test envelopes with mismatched surfaceId
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "updateDataModel",
+      surfaceId: "wrong-id",
+      path: "/key",
+      value: 123,
+    });
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "actionResponse",
+      surfaceId: "wrong-id",
+      responsePath: "/key",
+      value: 123,
+    });
+    el.applyEnvelope({
+      version: "v1.0" as const,
+      type: "callFunction",
+      surfaceId: "wrong-id",
+      callId: "call-x",
+      call: { call: "capitalize", args: {} },
+    });
+
+    document.body.removeChild(el);
+  });
 });