@iloveagents/foundry-web-ui 0.1.0 → 0.1.1

package/src/lib/__tests__/ag-ui-adapter.test.ts

@@ -15,6 +15,11 @@
 import { describe, expect, it, vi, beforeEach } from "vitest";
 import type { RunnerEvent } from "@iloveagents/foundry-agent";
 
+const appStoreMock = vi.hoisted(() => ({
+  agentState: { contextItems: [] as Array<Record<string, unknown>> },
+  consumedMessageIds: [] as string[],
+}));
+
 const runMock = vi.fn();
 const runnerMock = vi.fn().mockImplementation(() => ({
   threadId: "thread-1",
@@ -46,8 +51,10 @@ vi.mock("../app-store.ts", () => ({
   useAppStore: {
     getState: () => ({
       markThreadActive: () => {},
-      getAgentState: () => ({ contextItems: [] }),
-      consumeContextForMessage: () => {},
+      getAgentState: () => appStoreMock.agentState,
+      consumeContextForMessage: (messageId: string) => {
+        appStoreMock.consumedMessageIds.push(messageId);
+      },
     }),
   },
 }));
@@ -75,6 +82,8 @@ describe("AGUIAdapterSDK", () => {
   beforeEach(() => {
     runMock.mockReset();
     runnerMock.mockClear();
+    appStoreMock.agentState = { contextItems: [] };
+    appStoreMock.consumedMessageIds = [];
   });
 
   it("yields a terminal complete after a text-only run", async () => {
@@ -174,6 +183,37 @@ describe("AGUIAdapterSDK", () => {
 
     expect(out[out.length - 1].status).toEqual({ type: "complete", reason: "stop" });
   });
+
+  it("forwards app context items through the native AG-UI context field", async () => {
+    appStoreMock.agentState = {
+      contextItems: [
+        {
+          type: "ref",
+          refType: "block",
+          refId: "entity-1:block-2",
+          preview: "A selected table cell",
+          targetPath: "$.blocks[?(@.id=='block-2')].rows[0].cells[1]",
+          sourcePage: "/spaces/entity-1#block-block-2",
+        },
+      ],
+    };
+    runMock.mockImplementation(async function* (): AsyncGenerator<RunnerEvent> {});
+
+    const adapter = new AGUIAdapterSDK();
+    for await (const _ of adapter.run(makeRunInput())) {
+      // Drain the adapter.
+    }
+
+    expect(runMock).toHaveBeenCalledTimes(1);
+    expect(runMock.mock.calls[0][0].context).toEqual([
+      {
+        description:
+          "Selected block atom. Use targetPath as the exact edit target when the user asks to modify, rewrite, or transform selected content.",
+        value: JSON.stringify(appStoreMock.agentState.contextItems[0]),
+      },
+    ]);
+    expect(appStoreMock.consumedMessageIds).toEqual(["u-1"]);
+  });
 });
 
 interface ChatModelRunResultLike {

package/src/lib/__tests__/app-store.test.ts

@@ -54,6 +54,27 @@ const refItem = (refId = "entity-1:block-1", preview = "Introduction") => ({
   persistence: "persistent" as const,
 });
 
+const scopedRefItem = (
+  selectionScope: "block" | "text" | "atom",
+  preview = "Introduction",
+  targetPath?: string,
+) => ({
+  type: "ref" as const,
+  label: preview,
+  payload: {
+    kind: "ref" as const,
+    refType: "block",
+    refId: "entity-1:block-1",
+    preview,
+    meta: {
+      selectionScope,
+      ...(targetPath ? { targetPath } : {}),
+    },
+  },
+  sourcePage: "/spaces/entity-1#block-block-1",
+  persistence: selectionScope === "block" ? ("persistent" as const) : ("ephemeral" as const),
+});
+
 describe("app-store", () => {
   beforeEach(reset);
 
@@ -108,6 +129,27 @@ describe("app-store", () => {
       expect(store().contextItems).toHaveLength(1);
     });
 
+    it("allows scoped refs for the same block alongside the durable block ref", () => {
+      store().addContextItem(scopedRefItem("block", "Whole block"));
+      store().addContextItem(scopedRefItem("text", "Specific phrase"));
+      store().addContextItem(
+        scopedRefItem("atom", "Table cell", "$.blocks[?(@.id=='block-1')].rows[0].cells[0]"),
+      );
+      expect(store().contextItems).toHaveLength(3);
+    });
+
+    it("deduplicates scoped refs by their actual scope key", () => {
+      store().addContextItem(scopedRefItem("text", "Specific phrase"));
+      store().addContextItem(scopedRefItem("text", "Specific phrase"));
+      store().addContextItem(
+        scopedRefItem("atom", "Table cell", "$.blocks[?(@.id=='block-1')].rows[0].cells[0]"),
+      );
+      store().addContextItem(
+        scopedRefItem("atom", "Updated table cell", "$.blocks[?(@.id=='block-1')].rows[0].cells[0]"),
+      );
+      expect(store().contextItems).toHaveLength(2);
+    });
+
     it("allows ref items with different refIds", () => {
       store().addContextItem(refItem("e1:b1"));
       store().addContextItem(refItem("e1:b2"));

package/src/lib/__tests__/selection-context.test.ts

@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, it } from "vitest";
+import {
+  registerSelectionContextResolver,
+  resolveSelectionContext,
+  type SelectionContextResolver,
+} from "../selection-context.ts";
+
+const unregisters: Array<() => void> = [];
+
+function register(resolver: SelectionContextResolver) {
+  const unregister = registerSelectionContextResolver(resolver);
+  unregisters.push(unregister);
+  return unregister;
+}
+
+function input(text = "selected text") {
+  const node = document.createElement("span");
+  const range = document.createRange();
+  range.selectNodeContents(node);
+  return {
+    text,
+    anchorNode: node,
+    focusNode: node,
+    range,
+    sourcePage: "Current page",
+  };
+}
+
+describe("selection-context", () => {
+  afterEach(() => {
+    for (const unregister of unregisters.splice(0)) unregister();
+    document.body.innerHTML = "";
+  });
+
+  it("falls back to a plain text selection context", () => {
+    const resolved = resolveSelectionContext(input("hello"));
+
+    expect(resolved.item).toMatchObject({
+      type: "selection",
+      label: "hello",
+      payload: { kind: "text", text: "hello" },
+      persistence: "ephemeral",
+    });
+    expect(resolved.supportsModify).toBeUndefined();
+  });
+
+  it("lets modules resolve richer selection context and opt into Modify", () => {
+    register({
+      id: "test-rich-selection",
+      resolve: (selection) => ({
+        item: {
+          type: "ref",
+          label: `Field · ${selection.text}`,
+          payload: {
+            kind: "ref",
+            refType: "block",
+            refId: "entity:block",
+            preview: selection.text,
+            meta: { selectionScope: "atom", targetPath: "$.blocks[0].field" },
+          },
+          sourcePage: "/spaces/entity#block-block",
+          persistence: "ephemeral",
+        },
+        supportsModify: true,
+      }),
+    });
+
+    const resolved = resolveSelectionContext(input("cell"));
+
+    expect(resolved.item).toMatchObject({
+      type: "ref",
+      label: "Field · cell",
+      payload: {
+        kind: "ref",
+        refType: "block",
+        refId: "entity:block",
+        meta: { targetPath: "$.blocks[0].field" },
+      },
+    });
+    expect(resolved.supportsModify).toBe(true);
+  });
+
+  it("uses resolver priority before falling through to lower priority resolvers", () => {
+    register({
+      id: "low",
+      priority: 1,
+      resolve: (selection) => ({
+        item: {
+          type: "selection",
+          label: `low ${selection.text}`,
+          payload: { kind: "text", text: selection.text },
+          sourcePage: selection.sourcePage,
+          persistence: "ephemeral",
+        },
+      }),
+    });
+    register({
+      id: "high",
+      priority: 100,
+      resolve: (selection) => ({
+        item: {
+          type: "selection",
+          label: `high ${selection.text}`,
+          payload: { kind: "text", text: selection.text },
+          sourcePage: selection.sourcePage,
+          persistence: "ephemeral",
+        },
+      }),
+    });
+
+    expect(resolveSelectionContext(input("x")).item.label).toBe("high x");
+  });
+});
+

package/src/lib/ag-ui-adapter.ts

@@ -24,14 +24,14 @@ import type {
   TextMessagePart,
   ToolCallMessagePart,
 } from "@assistant-ui/react";
-import type { Message as AGUIMessage } from "@ag-ui/core";
+import type { Context, Message as AGUIMessage } from "@ag-ui/core";
 import {
   AGUIRunner,
   clientToolRegistry,
   streamingStatusStore,
 } from "@iloveagents/foundry-agent";
 import { tokenFetch } from "@iloveagents/foundry-agent/msal";
-import { useAppStore } from "./app-store.ts";
+import { useAppStore, type AgentStateProjection } from "./app-store.ts";
 import { useDevStore } from "./dev-store.ts";
 
 interface ToolCallSnapshot {
@@ -71,6 +71,7 @@ export class AGUIAdapterSDK implements ChatModelAdapter {
     // ephemeral context off the last user message.
     useAppStore.getState().markThreadActive();
     const appState = useAppStore.getState().getAgentState();
+    const context = buildAGUIContext(appState);
     const lastUserMsg = [...messages].reverse().find((m) => m.role === "user");
     if (lastUserMsg) {
       useAppStore.getState().consumeContextForMessage(lastUserMsg.id);
@@ -136,6 +137,7 @@ export class AGUIAdapterSDK implements ChatModelAdapter {
       for await (const event of this.runner.run({
         messages: aguiMessages,
         state: appState as unknown as Record<string, unknown>,
+        context,
         registry: clientToolRegistry.getState(),
         abortSignal,
       })) {
@@ -263,6 +265,46 @@ export class AGUIAdapterSDK implements ChatModelAdapter {
   }
 }
 
+function buildAGUIContext(appState: AgentStateProjection): Context[] {
+  return appState.contextItems.map((item, index) => ({
+    description: describeContextItem(item, index),
+    value: stringifyContextItem(item),
+  }));
+}
+
+function describeContextItem(item: Record<string, unknown>, index: number): string {
+  const type = typeof item.type === "string" ? item.type : "context";
+  const label = typeof item.label === "string" ? item.label : "";
+
+  if (type === "ref") {
+    const refType = typeof item.refType === "string" ? item.refType : "reference";
+    if (typeof item.targetPath === "string") {
+      return `Selected ${refType} atom. Use targetPath as the exact edit target when the user asks to modify, rewrite, or transform selected content.`;
+    }
+    return `Selected ${refType} reference. Use refId as the edit target when the user asks to modify, rewrite, or transform selected content.`;
+  }
+
+  if (type === "selection") {
+    return "Selected text from the current UI. Use it as the focus when the user asks about, rewrites, or modifies selected content.";
+  }
+
+  if (type === "page") {
+    return `Pinned page context${label ? `: ${label}` : ""}.`;
+  }
+
+  return `Context item ${index + 1}${label ? `: ${label}` : ""}.`;
+}
+
+function stringifyContextItem(item: Record<string, unknown>): string {
+  try {
+    return JSON.stringify(item);
+  } catch {
+    const type = typeof item.type === "string" ? item.type : "context";
+    const label = typeof item.label === "string" ? item.label : "";
+    return JSON.stringify({ type, label });
+  }
+}
+
 /**
  * Convert assistant-ui's `Message[]` into AG-UI's wire format.
  *

package/src/lib/app-store.ts

@@ -93,6 +93,21 @@ const DEFAULT_NAV_CONTEXT: NavContext = {
   contextInstructions: null,
 };
 
+function refDedupKey(payload: ReferencePayload): string {
+  const selectionScope =
+    typeof payload.meta?.selectionScope === "string" ? payload.meta.selectionScope : "block";
+  const targetPath =
+    typeof payload.meta?.targetPath === "string" ? payload.meta.targetPath : undefined;
+
+  if (selectionScope === "atom" && targetPath) {
+    return `${payload.refType}:${payload.refId}:atom:${targetPath}`;
+  }
+  if (selectionScope === "text") {
+    return `${payload.refType}:${payload.refId}:text:${payload.preview ?? ""}`;
+  }
+  return `${payload.refType}:${payload.refId}:block`;
+}
+
 interface AppState {
   // Thread state
   threadActive: boolean;
@@ -188,7 +203,7 @@ export const useAppStore = create<AppState>((set, get) => ({
       if (item.type === "ref" && existing.type === "ref") {
         const a = item.payload as ReferencePayload;
         const b = existing.payload as ReferencePayload;
-        return a.refId === b.refId;
+        return refDedupKey(a) === refDedupKey(b);
       }
       // selection / note: dedup by label + sourcePage
       return existing.label === item.label && existing.sourcePage === item.sourcePage;
@@ -270,6 +285,9 @@ export const useAppStore = create<AppState>((set, get) => ({
               refType: payload.refType,
               refId: payload.refId,
               preview: payload.preview?.slice(0, 100),
+              meta: payload.meta,
+              targetPath:
+                typeof payload.meta?.targetPath === "string" ? payload.meta.targetPath : undefined,
               sourcePage,
             };
           default:

package/src/lib/composer-submit-store.ts

@@ -0,0 +1,32 @@
+import { create } from "zustand";
+
+interface PendingComposerSubmit {
+  id: number;
+  text: string;
+}
+
+interface ComposerSubmitState {
+  pending: PendingComposerSubmit | null;
+  submit: (text: string) => void;
+  consume: (id: number) => void;
+}
+
+let nextSubmitId = 1;
+
+export const useComposerSubmitStore = create<ComposerSubmitState>((set) => ({
+  pending: null,
+  submit: (text) => {
+    const trimmed = text.trim();
+    if (!trimmed) return;
+    set({ pending: { id: nextSubmitId++, text: trimmed } });
+  },
+  consume: (id) =>
+    set((state) => ({
+      pending: state.pending?.id === id ? null : state.pending,
+    })),
+}));
+
+export function submitComposerText(text: string): void {
+  useComposerSubmitStore.getState().submit(text);
+}
+

package/src/lib/nav-config.ts

@@ -55,6 +55,11 @@ export interface NavItem {
   dimmed?: boolean;
   /** Small text badge after the label (e.g., "managed", "locked"). */
   badge?: string;
+  /** Small status dot after the label for quiet state hints such as pending review impact. */
+  statusDot?: {
+    tone?: "neutral" | "info" | "low-impact" | "medium-impact" | "high-impact" | "pending";
+    label?: string;
+  };
   /** Page description sent to the agent for context */
   description?: string;
   /** Arbitrary metadata sent to the agent (e.g., workspace IDs, entity types) */

package/src/lib/selection-context.ts

@@ -0,0 +1,65 @@
+import type { ContextItem } from "./app-store.ts";
+
+export type SelectionContextItem = Omit<ContextItem, "id" | "createdAt">;
+
+export interface SelectionContextInput {
+  text: string;
+  anchorNode: Node;
+  focusNode: Node | null;
+  range: Range;
+  sourcePage: string;
+}
+
+export interface SelectionContextResult {
+  item: SelectionContextItem;
+  supportsModify?: boolean;
+  formatModifyPrompt?: (prompt: string) => string;
+}
+
+export interface SelectionContextResolver {
+  id: string;
+  priority?: number;
+  resolve: (input: SelectionContextInput) => SelectionContextResult | null;
+}
+
+const resolvers = new Map<string, SelectionContextResolver>();
+
+function defaultSelectionContext(input: SelectionContextInput): SelectionContextResult {
+  return {
+    item: {
+      type: "selection",
+      label: input.text,
+      payload: { kind: "text", text: input.text },
+      sourcePage: input.sourcePage,
+      persistence: "ephemeral",
+    },
+  };
+}
+
+export function registerSelectionContextResolver(
+  resolver: SelectionContextResolver,
+): () => void {
+  resolvers.set(resolver.id, resolver);
+  return () => {
+    if (resolvers.get(resolver.id) === resolver) {
+      resolvers.delete(resolver.id);
+    }
+  };
+}
+
+export function resolveSelectionContext(input: SelectionContextInput): SelectionContextResult {
+  const sortedResolvers = [...resolvers.values()].sort(
+    (a, b) => (b.priority ?? 0) - (a.priority ?? 0),
+  );
+
+  for (const resolver of sortedResolvers) {
+    try {
+      const resolved = resolver.resolve(input);
+      if (resolved) return resolved;
+    } catch {
+      // A module resolver must never break the generic selection flow.
+    }
+  }
+
+  return defaultSelectionContext(input);
+}

package/src/ui/dropdown-menu.tsx

@@ -36,7 +36,11 @@ export const DropdownMenuItem = forwardRef<
   <DropdownMenuPrimitive.Item
     ref={ref}
     className={cn(
-      "relative flex cursor-default select-none items-center rounded-sm px-2 py-1.5 text-sm outline-none",
+      // ``gap-2`` is the same icon-to-text spacing the framework's
+      // Button primitive uses, so a ``<lucide-icon /> Label`` pattern
+      // inside any menu item renders consistently everywhere without
+      // the consumer needing to remember the override.
+      "relative flex cursor-default select-none items-center gap-2 rounded-sm px-2 py-1.5 text-sm outline-none",
       "transition-colors focus:bg-accent focus:text-accent-foreground",
       "data-[disabled]:pointer-events-none data-[disabled]:opacity-50",
       className,