feat(ui): add bounded adapter foundations

deno.json

@@ -87,6 +87,7 @@
     "./context": "./src/react/context/index.tsx",
     "./fonts": "./src/react/fonts/index.ts",
     "./ui": "./src/react/components/ui/index.ts",
+    "./ui/adapter": "./src/react/components/ui/adapter/contract.ts",
     "./ui/icons": "./src/react/components/ui/icons/index.ts",
     "./chat": "./src/chat/index.ts",
     "./chat/ag-ui": "./src/chat/ag-ui.ts",
@@ -195,6 +196,7 @@
     "veryfront/react/components/chat": "./src/react/components/chat/index.ts",
     "veryfront/components/chat": "./src/react/components/chat/index.ts",
     "veryfront/ui": "./src/react/components/ui/index.ts",
+    "veryfront/ui/adapter": "./src/react/components/ui/adapter/contract.ts",
     "veryfront/ui/icons": "./src/react/components/ui/icons/index.ts",
     "veryfront/react/components/ui": "./src/react/components/ui/index.ts",
     "veryfront/components/ui": "./src/react/components/ui/index.ts",

scripts/build/npm-package-metadata.test.ts

@@ -25,6 +25,16 @@ Deno.test("exports agent skill helpers as a public package subpath", async () =>
   assertEquals(imports["veryfront/skill"], "./src/skill/index.ts");
 });
 
+Deno.test("exports the UI adapter contract as a public package subpath", async () => {
+  const denoConfig = JSON.parse(await Deno.readTextFile("deno.json"));
+  const exports = denoConfig.exports as Record<string, string>;
+  const imports = denoConfig.imports as Record<string, string>;
+  const contract = "./src/react/components/ui/adapter/contract.ts";
+
+  assertEquals(exports["./ui/adapter"], contract);
+  assertEquals(imports["veryfront/ui/adapter"], contract);
+});
+
 Deno.test("exports CLI framework dependencies as public package subpaths", async () => {
   const denoConfig = JSON.parse(await Deno.readTextFile("deno.json"));
   const exports = denoConfig.exports as Record<string, string>;

scripts/docs/generate-api-reference.test.ts

@@ -53,6 +53,7 @@ describe("generate-api-reference", () => {
       const providerReference = await Deno.readTextFile(
         `${outputDir}/veryfront/provider.md`,
       );
+      const providerTypes = await Deno.readTextFile("src/provider/types.ts");
       assertEquals(
         rootReference.includes(
           "\nConfiguration, server bootstrap, routing, data fetching, and input validation.\n\n## Import",
@@ -69,6 +70,11 @@ describe("generate-api-reference", () => {
         uiReference,
         "| `AppShellProps` | Props accepted by `AppShell`. |",
       );
+      assertStringIncludes(
+        uiReference,
+        'import type { DisclosureParts, DisclosureProps, MultipleToggleGroupRootProps } from "veryfront/ui/adapter";',
+        "type-only deep exports must use a copyable type import",
+      );
       assertStringIncludes(
         routerReference,
         "| Name | Description | Source |",
@@ -78,9 +84,15 @@ describe("generate-api-reference", () => {
         "| `RuntimeMetadata` |  | [source](https://github.com/veryfront/veryfront-code/blob/main/src/provider/types.ts#L1) |",
         "first-line declarations must keep a source anchor",
       );
+      const generateResultIndex = providerTypes.split("\n").findIndex((line) =>
+        line.startsWith("export interface ModelRuntimeGenerateResult")
+      );
+      assertEquals(generateResultIndex >= 0, true, "test declaration must exist");
       assertStringIncludes(
         providerReference,
-        "| `ModelRuntimeGenerateResult` |  | [source](https://github.com/veryfront/veryfront-code/blob/main/src/provider/types.ts#L8) |",
+        `| \`ModelRuntimeGenerateResult\` |  | [source](https://github.com/veryfront/veryfront-code/blob/main/src/provider/types.ts#L${
+          generateResultIndex + 1
+        }) |`,
         "Deno's one-based locations must stay one-based in GitHub anchors",
       );
       // Alias re-exports must resolve to their target's JSDoc description and a

scripts/docs/generate-api-reference.ts

@@ -2576,9 +2576,11 @@ function generateMD(
       }
       lines.push("```ts");
       const sample = pickDeepImportSample(di.exports);
-      if (sample.length > 0) {
+      if (sample.names.length > 0) {
         lines.push(
-          `import { ${sample.join(", ")} } from "${di.deep.importPath}";`,
+          `import${sample.typeOnly ? " type" : ""} { ${
+            sample.names.join(", ")
+          } } from "${di.deep.importPath}";`,
         );
       } else {
         lines.push(`import "${di.deep.importPath}";`);
@@ -2614,14 +2616,22 @@ function generateMD(
   return lines.join("\n");
 }
 
-function pickDeepImportSample(exports: CategorizedExports): string[] {
-  const all = [
+function pickDeepImportSample(
+  exports: CategorizedExports,
+): { names: string[]; typeOnly: boolean } {
+  const runtime = [
     ...exports.functions,
     ...exports.components,
     ...exports.classes,
     ...exports.constants,
   ].map((e) => e.name);
-  return all.slice(0, 3);
+  if (runtime.length > 0) {
+    return { names: runtime.slice(0, 3), typeOnly: false };
+  }
+  return {
+    names: exports.types.map((entry) => entry.name).slice(0, 3),
+    typeOnly: true,
+  };
 }
 
 function sourceCell(summary: ExportSummary): string {