@olonjs/cli 3.0.166 → 3.0.167

package/assets/src_tenant_alpha.sh

@@ -1817,9 +1817,9 @@ cat << 'END_OF_FILE_CONTENT' > "package.json"
     "@tiptap/extension-link": "^2.11.5",
     "@tiptap/react": "^2.11.5",
     "@tiptap/starter-kit": "^2.11.5",
-    "@olonjs/core": "^2.0.2",
-    "@olonjs/react": "^0.2.2",
-    "@olonjs/studio": "^0.2.2",
+    "@olonjs/core": "^2.0.3",
+    "@olonjs/react": "^0.2.3",
+    "@olonjs/studio": "^0.2.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.474.0",

package/assets/templates/alpha/src_tenant.sh

@@ -1817,9 +1817,9 @@ cat << 'END_OF_FILE_CONTENT' > "package.json"
     "@tiptap/extension-link": "^2.11.5",
     "@tiptap/react": "^2.11.5",
     "@tiptap/starter-kit": "^2.11.5",
-    "@olonjs/core": "^2.0.2",
-    "@olonjs/react": "^0.2.2",
-    "@olonjs/studio": "^0.2.2",
+    "@olonjs/core": "^2.0.3",
+    "@olonjs/react": "^0.2.3",
+    "@olonjs/studio": "^0.2.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.474.0",

package/assets/templates/next/src_tenant.sh

@@ -24,6 +24,8 @@ import { getFilePages } from '@/lib/loaders/getFilePages';
 import { getFileSiteBundle } from '@/lib/loaders/getFileSiteConfig';
 import { loadVisitorPageBundle } from '@/lib/loaders/loadVisitorPageBundle';
 import { resolveVisitorShell } from '@/lib/resolveVisitorShell';
+import { resolvePublicToolNames } from '@/lib/webmcp/resolvePublicToolNames';
+import { sectionPublicTools } from '@/lib/webmcp/toolRegistry';
 import { VisitorSection } from '@/lib/VisitorSection';
 
 export const dynamic = 'force-dynamic';
@@ -115,6 +117,7 @@ export default async function VisitorCatchAllPage({ params, searchParams }: Page
   const pageNum = Number(firstSearchValue(query.page) ?? '1') || 1;
   const shell = resolveVisitorShell(page, resolved.siteConfig ?? siteConfig);
   const sectionExtras = { authorId, page: pageNum, pathname };
+  const publicToolNames = resolvePublicToolNames(page.sections, sectionPublicTools as Record<string, readonly string[]>);
   const title = page.meta?.title ?? result.registrySlug;
   const description = typeof page.meta?.description === 'string' ? page.meta.description : '';
   const jsonLd = buildVisitorWebPageJsonLd({
@@ -125,7 +128,7 @@ export default async function VisitorCatchAllPage({ params, searchParams }: Page
 
   return (
     <>
-      <WebMcpVisitorRuntime />
+      <WebMcpVisitorRuntime toolNames={publicToolNames} />
       <link rel="mcp-manifest" href={buildPageManifestHref(requestSlug)} />
       <link rel="olon-contract" href={buildPageContractHref(requestSlug)} />
       <script
@@ -786,10 +789,11 @@ cat << 'END_OF_FILE_CONTENT' > "package.json"
     "dist:dna": "npm run dist"
   },
   "dependencies": {
-    "@olonjs/core": "^2.0.2",
-    "@olonjs/next": "^0.0.14",
-    "@olonjs/react": "^0.2.2",
-    "@olonjs/studio": "^0.2.2",
+    "@olonjs/core": "^2.0.3",
+    "@olonjs/next": "^0.0.15",
+    "@olonjs/react": "^0.2.3",
+    "@olonjs/sources": "^0.1.0",
+    "@olonjs/studio": "^0.2.3",
     "clsx": "^2.1.1",
     "lucide-react": "^0.474.0",
     "next": "^15.5.0",
@@ -797,14 +801,14 @@ cat << 'END_OF_FILE_CONTENT' > "package.json"
     "react-dom": "^19.0.0",
     "react-router-dom": "^6.29.0",
     "tailwind-merge": "^3.0.1",
-    "zod": "^4.6.0",
-    "@olonjs/sources": "^0.1.0"
+    "zod": "^4.6.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.0.0",
     "@types/node": "^22.13.1",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
+    "jsdom": "^26.1.0",
     "tailwindcss": "^4.0.0",
     "typescript": "^5.7.3",
     "vitest": "^3.0.0"
@@ -1538,6 +1542,7 @@ import { ComponentRegistry } from '@/lib/ComponentRegistry';
 import { iconMap } from '@/lib/IconResolver';
 import { SECTION_SCHEMAS } from '@/lib/schemas';
 import { buildEnabledWebMcpConfig } from '@/lib/webmcp/buildEnabledWebMcpConfig';
+import { adminToolExecutors, declaredAdminTools } from '@/lib/webmcp/toolRegistry';
 
 export type AdminStudioClientProps = {
   tenantId?: string;
@@ -1625,7 +1630,11 @@ export function AdminStudioClient({
       themeCss: { tenant: '' },
       iconRegistry: iconMap,
       addSection: addSectionConfig,
-      webmcp: buildEnabledWebMcpConfig(),
+      webmcp: {
+        ...buildEnabledWebMcpConfig(),
+        tools: declaredAdminTools,
+        toolExecutors: adminToolExecutors,
+      },
       persistence: {
         saveToFile,
         ...(coldSave ? { coldSave } : {}),
@@ -2653,6 +2662,7 @@ cat << 'END_OF_FILE_CONTENT' > "src/components/form-demo/index.ts"
 export { FormDemoView } from './View';
 export { FormDemoClient } from './FormDemoClient';
 export { FormDemoSchema, FormDemoSettingsSchema, FormDemoSubmissionSchema } from './schema';
+export { webmcpTools } from './webmcpTools';
 export type { FormDemoData, FormDemoSettings } from './types';
 
 END_OF_FILE_CONTENT
@@ -2680,6 +2690,173 @@ export const FormDemoSubmissionSchema = z.object({
   message: z.string().min(1).describe('Free-form message body'),
 });
 
+END_OF_FILE_CONTENT
+echo "Creating src/components/form-demo/submitFormLead.test.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/components/form-demo/submitFormLead.test.ts"
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const CLOUD_URL = 'https://cloud.example.com';
+const API_KEY = 'secret-key';
+
+async function loadSubmitFormLead() {
+  vi.resetModules();
+  vi.stubEnv('NEXT_PUBLIC_OLONJS_CLOUD_URL', CLOUD_URL);
+  vi.stubEnv('NEXT_PUBLIC_OLONJS_API_KEY', API_KEY);
+  return await import('./submitFormLead');
+}
+
+beforeEach(() => {
+  vi.stubGlobal('fetch', vi.fn());
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.unstubAllGlobals();
+});
+
+function mockFetchOk() {
+  const fetchMock = vi.mocked(fetch);
+  fetchMock.mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 }));
+  return fetchMock;
+}
+
+describe('submitFormLead', () => {
+  it('POSTs to {cloudUrl}/form/send with parity headers and full payload', async () => {
+    const { submitFormLead } = await loadSubmitFormLead();
+    const fetchMock = mockFetchOk();
+
+    const ctx = {
+      recipientEmail: 'lead@example.com',
+      sectionId: 'form-demo-1',
+      pageSlug: 'contatti',
+    };
+    const args = { name: 'Ada', email: 'ada@example.com', message: 'Ciao' };
+
+    await expect(submitFormLead(args, ctx)).resolves.toEqual({ ok: true });
+
+    const [url, init] = fetchMock.mock.calls[0] as [string, RequestInit];
+    expect(url).toBe(`${CLOUD_URL}/form/send`);
+    const headers = init.headers as Record<string, string>;
+    expect(headers.Authorization).toBe(`Bearer ${API_KEY}`);
+    expect(headers['Content-Type']).toBe('application/json');
+    expect(headers['Idempotency-Key']).toMatch(/^form-form-demo-1-\d+$/);
+    const payload = JSON.parse(init.body as string) as Record<string, unknown>;
+    expect(payload).toMatchObject({
+      name: 'Ada',
+      email: 'ada@example.com',
+      message: 'Ciao',
+      recipientEmail: 'lead@example.com',
+      page: 'contatti',
+      section: 'form-demo-1',
+      source: 'olon-webmcp',
+    });
+    expect(typeof payload.submittedAt).toBe('string');
+  });
+
+  it('uses the dev-declared path, normalizing slashes', async () => {
+    const { submitFormLead } = await loadSubmitFormLead();
+    const fetchMock = mockFetchOk();
+
+    await submitFormLead(
+      { name: 'A', email: 'a@b.c', message: 'm' },
+      { recipientEmail: '', sectionId: 's1', pageSlug: 'x', path: '/lead/submit/' },
+    );
+
+    expect((fetchMock.mock.calls[0] as [string])[0]).toBe(`${CLOUD_URL}/lead/submit`);
+  });
+
+  it('throws a readable error on a non-ok response', async () => {
+    const { submitFormLead } = await loadSubmitFormLead();
+    vi.mocked(fetch).mockResolvedValue(
+      new Response(JSON.stringify({ error: 'bad gateway' }), { status: 502 }),
+    );
+
+    await expect(
+      submitFormLead(
+        { name: 'A', email: 'a@b.c', message: 'm' },
+        { recipientEmail: '', sectionId: 's1', pageSlug: 'x' },
+      ),
+    ).rejects.toThrow(/bad gateway/);
+  });
+
+  it('throws an explicit error when the cloud env is not configured', async () => {
+    vi.resetModules();
+    vi.stubEnv('NEXT_PUBLIC_OLONJS_CLOUD_URL', '');
+    vi.stubEnv('NEXT_PUBLIC_OLONJS_API_KEY', '');
+    const { submitFormLead } = await import('./submitFormLead');
+
+    await expect(
+      submitFormLead(
+        { name: 'A', email: 'a@b.c', message: 'm' },
+        { recipientEmail: '', sectionId: 's1', pageSlug: 'x' },
+      ),
+    ).rejects.toThrow(/Cloud env not configured/);
+  });
+});
+
+END_OF_FILE_CONTENT
+echo "Creating src/components/form-demo/submitFormLead.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/components/form-demo/submitFormLead.ts"
+import { cloudPolicy } from '@/lib/env/tenantEnv';
+
+export interface SubmitFormArgs {
+  name: string;
+  email: string;
+  message: string;
+}
+
+export interface SubmitFormContext {
+  recipientEmail: string;
+  sectionId: string;
+  pageSlug: string;
+  /** The dev-declared endpoint path (the variable piece); default 'form/send'. */
+  path?: string;
+}
+
+/**
+ * Shared submit executor for form sections (spec 03-webmcp-tool-submit-plugin).
+ *
+ * Base URL always comes from the cloud env chain (`tenantEnv`/`cloudPolicy`);
+ * the dev declares only the variable path. Header parity with tenant-alpha's
+ * `useOlonForms` (Bearer + Idempotency-Key).
+ */
+export async function submitFormLead(
+  args: SubmitFormArgs,
+  ctx: SubmitFormContext,
+): Promise<{ ok: true }> {
+  const base = (cloudPolicy.apiUrl ?? '').replace(/\/$/, '');
+  if (!base || !cloudPolicy.apiKey) {
+    throw new Error('Cloud env not configured (NEXT_PUBLIC_OLONJS_*).');
+  }
+
+  const path = (ctx.path ?? 'form/send').replace(/^\/+|\/+$/g, '');
+  const endpoint = `${base}/${path}`;
+
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${cloudPolicy.apiKey}`,
+      'Content-Type': 'application/json',
+      'Idempotency-Key': `form-${ctx.sectionId}-${Date.now()}`,
+    },
+    body: JSON.stringify({
+      ...args,
+      recipientEmail: ctx.recipientEmail,
+      page: ctx.pageSlug,
+      section: ctx.sectionId,
+      source: 'olon-webmcp',
+      submittedAt: new Date().toISOString(),
+    }),
+  });
+
+  const body = (await response.json().catch(() => ({}))) as { error?: string };
+  if (!response.ok) {
+    throw new Error(body.error ?? `Submit failed (${response.status})`);
+  }
+
+  return { ok: true };
+}
+
 END_OF_FILE_CONTENT
 echo "Creating src/components/form-demo/types.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/components/form-demo/types.ts"
@@ -2689,6 +2866,27 @@ import { FormDemoSchema, FormDemoSettingsSchema } from './schema';
 export type FormDemoData = z.infer<typeof FormDemoSchema>;
 export type FormDemoSettings = z.infer<typeof FormDemoSettingsSchema>;
 
+END_OF_FILE_CONTENT
+echo "Creating src/components/form-demo/webmcpTools.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/components/form-demo/webmcpTools.ts"
+import type { WebMcpToolDef } from '@olonjs/core';
+import { FormDemoSubmissionSchema } from './schema';
+
+/**
+ * Public WebMCP tools declared by the form-demo capsule (spec 03).
+ * Serializable defs only — the executor is registered client-side in
+ * `src/lib/webmcp/submitFormTool.ts` (functions cannot cross the RSC boundary).
+ */
+export const webmcpTools: readonly WebMcpToolDef[] = [
+  {
+    name: 'submit-form',
+    description: 'Submit the contact form on this page (name, email, message).',
+    surface: 'public',
+    inputSchema: FormDemoSubmissionSchema.toJSONSchema() as Record<string, unknown>,
+    annotations: { consequentialHint: true },
+  },
+];
+
 END_OF_FILE_CONTENT
 mkdir -p "src/components/header"
 echo "Creating src/components/header/View.tsx..."
@@ -2963,16 +3161,38 @@ cat << 'END_OF_FILE_CONTENT' > "src/components/webmcp/WebMcpVisitorRuntime.tsx"
 'use client';
 
 import { useEffect } from 'react';
+import { registerWebMcpTool } from '@olonjs/core';
 import { bootstrapVisitorWebMcpRuntime } from '@/lib/webmcp/bootstrapVisitorWebMcpRuntime';
+// Side effect: registers the submit-form executor (spec 03). Client-only import.
+import '@/lib/webmcp/submitFormTool';
+import { visitorToolDefs } from '@/lib/webmcp/visitorToolDefs';
 
 /**
- * Client island: WebMCP imperative API on public pages (readResource / listTools empty).
- * Must not import @olonjs/studio.
+ * Client island: WebMCP imperative API on public pages.
+ * Installs the polyfill and registers the public tools enabled for the page
+ * (spec 02-webmcp-tool-public-runtime). Must not import @olonjs/studio.
+ *
+ * `toolNames` are computed server-side from the sections present on the page
+ * (functions cannot cross the RSC boundary — only names travel).
  */
-export function WebMcpVisitorRuntime() {
+export function WebMcpVisitorRuntime({ toolNames = [] }: { toolNames?: string[] }) {
   useEffect(() => {
     bootstrapVisitorWebMcpRuntime();
-  }, []);
+    const unregister = toolNames.map((name) => {
+      const def = visitorToolDefs[name];
+      if (!def) {
+        console.warn(`[WebMCP] visitor tool "${name}" has no executor definition.`);
+        return () => undefined;
+      }
+      return registerWebMcpTool({
+        ...def,
+        inputSchema: def.inputSchema ?? { type: 'object', additionalProperties: false, properties: {} },
+      });
+    });
+    return () => {
+      unregister.forEach((stop) => stop());
+    };
+  }, [toolNames]);
 
   return null;
 }
@@ -5966,6 +6186,66 @@ export function buildEnabledWebMcpConfig(namespace?: string): {
   };
 }
 
+END_OF_FILE_CONTENT
+echo "Creating src/lib/webmcp/resolvePublicToolNames.test.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/lib/webmcp/resolvePublicToolNames.test.ts"
+import { describe, expect, it } from 'vitest';
+import { resolvePublicToolNames } from './resolvePublicToolNames';
+
+const sectionPublicTools = {
+  'form-demo': ['submit-form'],
+  'shop-catalog': ['search-product', 'add-to-cart'],
+};
+
+describe('resolvePublicToolNames', () => {
+  it('returns the public tools of the sections present on the page, deduplicated, in page order', () => {
+    const sections = [
+      { type: 'form-demo' },
+      { type: 'hero' },
+      { type: 'form-demo' },
+      { type: 'shop-catalog' },
+    ];
+    expect(resolvePublicToolNames(sections, sectionPublicTools)).toEqual([
+      'submit-form',
+      'search-product',
+      'add-to-cart',
+    ]);
+  });
+
+  it('returns an empty list when no section declares tools', () => {
+    expect(resolvePublicToolNames([{ type: 'hero' }], sectionPublicTools)).toEqual([]);
+  });
+
+  it('returns an empty list for an empty page', () => {
+    expect(resolvePublicToolNames([], sectionPublicTools)).toEqual([]);
+  });
+
+  it('ignores tool names not present in the section map', () => {
+    expect(resolvePublicToolNames([{ type: 'footer' }], sectionPublicTools)).toEqual([]);
+  });
+});
+
+END_OF_FILE_CONTENT
+echo "Creating src/lib/webmcp/resolvePublicToolNames.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/lib/webmcp/resolvePublicToolNames.ts"
+/**
+ * Pure helper (spec 02-webmcp-tool-public-runtime): computes which public
+ * tool names are enabled for a page, from the section types present.
+ * Deduplicated, in page order.
+ */
+export function resolvePublicToolNames(
+  sections: ReadonlyArray<{ type: string }>,
+  sectionPublicTools: Record<string, readonly string[]>,
+): string[] {
+  const out: string[] = [];
+  for (const section of sections) {
+    for (const name of sectionPublicTools[section.type] ?? []) {
+      if (!out.includes(name)) out.push(name);
+    }
+  }
+  return out;
+}
+
 END_OF_FILE_CONTENT
 mkdir -p "src/lib/webmcp/runtime"
 echo "Creating src/lib/webmcp/runtime/agenticSurface.test.ts..."
@@ -6123,6 +6403,36 @@ describe('robots + sitemap', () => {
     expect(xml).toContain('<lastmod>2026-09-10T10:00:00Z</lastmod>');
   });
 });
+
+describe('declared public tools in runtime contracts', () => {
+  const surfaceInput = {
+    bundle,
+    schemas,
+    declaredTools: [
+      {
+        name: 'submit-form',
+        description: 'Submit the contact form',
+        surface: 'public',
+        inputSchema: { type: 'object', properties: {} },
+      },
+    ] as const,
+  };
+
+  it('emits declared tools with their surface in the page contract', () => {
+    const contract = buildRuntimePageContract({ ...surfaceInput, slug: 'home' });
+    const submit = contract!.tools.find((t) => t.name === 'submit-form');
+    expect(submit).toBeDefined();
+    expect((submit as { surface?: string }).surface).toBe('public');
+    expect(contract!.tools.map((t) => t.name)).toEqual(['update-section', 'save', 'submit-form']);
+  });
+
+  it('emits declared tools in the page manifest tools list with surface', () => {
+    const manifest = buildRuntimePageManifest({ ...surfaceInput, slug: 'home' });
+    const submit = manifest!.tools.find((t) => t.name === 'submit-form');
+    expect(submit).toBeDefined();
+    expect((submit as { surface?: string }).surface).toBe('public');
+  });
+});
 
 END_OF_FILE_CONTENT
 echo "Creating src/lib/webmcp/runtime/agenticSurface.ts..."
@@ -6141,6 +6451,7 @@ import {
   webmcp,
   type JsonPagesConfig,
   type PageConfig,
+  type WebMcpToolDef,
 } from '@olonjs/core';
 import type { PublicPageContentBundle } from '@olonjs/next/server';
 
@@ -6157,6 +6468,8 @@ export type RuntimeSurfaceInput = {
   bundle: PublicPageContentBundle;
   schemas: JsonPagesConfig['schemas'];
   submissionSchemas?: JsonPagesConfig['submissionSchemas'];
+  /** Tenant-declared tools (public surface), appended to the contract's built-ins. */
+  declaredTools?: readonly WebMcpToolDef[];
 };
 
 function joinSegments(segments: readonly string[]): string {
@@ -6245,6 +6558,7 @@ export function buildRuntimeSiteManifest(input: RuntimeSurfaceInput) {
     siteConfig: input.bundle.siteConfig,
     // Bundle carries SchemaLike; the manifest builder expects the Zod registry (same objects).
     collectionSchemas: input.bundle.collectionSchemas as never,
+    declaredTools: input.declaredTools,
   });
 }
 
@@ -6257,6 +6571,7 @@ export function buildRuntimePageManifest(input: RuntimeSurfaceInput & { slug: st
     schemas: input.schemas,
     submissionSchemas: input.submissionSchemas,
     siteConfig: input.bundle.siteConfig,
+    declaredTools: input.declaredTools,
   });
 }
 
@@ -6269,6 +6584,7 @@ export function buildRuntimePageContract(input: RuntimeSurfaceInput & { slug: st
     schemas: input.schemas,
     submissionSchemas: input.submissionSchemas,
     siteConfig: input.bundle.siteConfig,
+    declaredTools: input.declaredTools,
   });
 }
 
@@ -6287,6 +6603,7 @@ export function buildRuntimeLlmsTxt(input: RuntimeSurfaceInput): string {
     schemas: input.schemas,
     submissionSchemas: input.submissionSchemas,
     siteConfig: input.bundle.siteConfig,
+    declaredTools: input.declaredTools,
   });
 }
 
@@ -6396,6 +6713,7 @@ import { readServerCloudPolicy } from '@/lib/env/serverCloudPolicy';
 import { loadLocalPublicPageBundle } from '@/lib/loaders/loadLocalPublicPageBundle';
 import { loadPublicPageBundleForRequest } from '@/lib/loaders/loadPublicPageBundleForRequest';
 import { SECTION_SCHEMAS, SECTION_SUBMISSION_SCHEMAS } from '@/lib/schemas';
+import { declaredPublicTools } from '@/lib/webmcp/toolRegistry';
 import type { RuntimeSurfaceInput } from './agenticSurface';
 
 const schemas = SECTION_SCHEMAS as unknown as JsonPagesConfig['schemas'];
@@ -6418,7 +6736,7 @@ export async function loadRuntimeSurfaceForSlug(input: {
     apiUrl: policy.apiUrl,
     apiKey: policy.apiKey,
   });
-  return { bundle, schemas, submissionSchemas };
+  return { bundle, schemas, submissionSchemas, declaredTools: declaredPublicTools };
 }
 
 /**
@@ -6427,7 +6745,7 @@ export async function loadRuntimeSurfaceForSlug(input: {
  */
 export function loadRuntimeSurfaceForSite(): RuntimeSurfaceInput {
   const bundle = loadLocalPublicPageBundle(path.resolve(process.cwd()));
-  return { bundle, schemas, submissionSchemas };
+  return { bundle, schemas, submissionSchemas, declaredTools: declaredPublicTools };
 }
 
 /** Public base URL for absolute links (robots/sitemap). */
@@ -6487,6 +6805,236 @@ describe('next.config rewrites — runtime agentic surface', () => {
   });
 });
 
+END_OF_FILE_CONTENT
+echo "Creating src/lib/webmcp/submitFormTool.test.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/lib/webmcp/submitFormTool.test.ts"
+// @vitest-environment jsdom
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const CLOUD_URL = 'https://cloud.example.com';
+
+async function loadModules() {
+  vi.resetModules();
+  vi.stubEnv('NEXT_PUBLIC_OLONJS_CLOUD_URL', CLOUD_URL);
+  vi.stubEnv('NEXT_PUBLIC_OLONJS_API_KEY', 'k');
+  const [{ sectionPublicTools, declaredPublicTools }, { visitorToolDefs }] = await Promise.all([
+    import('@/lib/webmcp/toolRegistry'),
+    import('@/lib/webmcp/visitorToolDefs'),
+  ]);
+  // Same side-effect import the visitor island performs: registers the executor.
+  await import('@/lib/webmcp/submitFormTool');
+  return { sectionPublicTools, declaredPublicTools, visitorToolDefs };
+}
+
+beforeEach(() => {
+  vi.stubGlobal('fetch', vi.fn().mockResolvedValue(new Response(JSON.stringify({ ok: true }), { status: 200 })));
+});
+
+afterEach(() => {
+  vi.unstubAllEnvs();
+  vi.unstubAllGlobals();
+  document.body.innerHTML = '';
+});
+
+describe('submit-form tool wiring', () => {
+  it('maps form-demo to submit-form and declares the public tool def', async () => {
+    const { sectionPublicTools, declaredPublicTools } = await loadModules();
+    expect(sectionPublicTools['form-demo']).toEqual(['submit-form']);
+
+    const def = declaredPublicTools.find((t) => t.name === 'submit-form');
+    expect(def).toBeDefined();
+    expect(def!.surface).toBe('public');
+    expect(def!.inputSchema).toMatchObject({
+      type: 'object',
+      properties: { name: { type: 'string' }, email: { type: 'string' }, message: { type: 'string' } },
+    });
+  });
+
+  it('registers the executor and submits a valid payload to {cloudUrl}/form/send', async () => {
+    const { visitorToolDefs } = await loadModules();
+    document.body.innerHTML =
+      '<form id="form-demo" data-olon-recipient="lead@example.com"></form>';
+
+    const tool = visitorToolDefs['submit-form'];
+    expect(tool).toBeDefined();
+
+    await expect(
+      tool.execute({ name: 'Ada', email: 'ada@example.com', message: 'Ciao' }),
+    ).resolves.toEqual({ ok: true });
+
+    const [url, init] = vi.mocked(fetch).mock.calls[0] as [string, RequestInit];
+    expect(url).toBe(`${CLOUD_URL}/form/send`);
+    const payload = JSON.parse(init.body as string) as Record<string, unknown>;
+    expect(payload).toMatchObject({
+      recipientEmail: 'lead@example.com',
+      section: 'form-demo',
+      source: 'olon-webmcp',
+    });
+  });
+
+  it('rejects an invalid payload with a Zod validation error before any fetch', async () => {
+    const { visitorToolDefs } = await loadModules();
+    const tool = visitorToolDefs['submit-form'];
+
+    await expect(tool.execute({ name: '', email: 'not-an-email', message: '' })).rejects.toThrow();
+    expect(vi.mocked(fetch)).not.toHaveBeenCalled();
+  });
+});
+
+END_OF_FILE_CONTENT
+echo "Creating src/lib/webmcp/submitFormTool.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/lib/webmcp/submitFormTool.ts"
+import { FormDemoSubmissionSchema } from '@/components/form-demo/schema';
+import { submitFormLead, type SubmitFormArgs } from '@/components/form-demo/submitFormLead';
+import { webmcpTools } from '@/components/form-demo/webmcpTools';
+import { visitorToolDefs } from './visitorToolDefs';
+
+const submitFormDef = webmcpTools.find((tool) => tool.name === 'submit-form');
+if (!submitFormDef) {
+  throw new Error('[WebMCP] form-demo capsule must declare the submit-form tool.');
+}
+
+/**
+ * Client-side executor registration for submit-form (spec 03).
+ *
+ * Imported as a side effect ONLY by the visitor island — never by server code:
+ * the executor chain (`submitFormLead` → `tenantEnv` → `@olonjs/react`) is
+ * client-bound. Validation uses the section's submission schema (ADR-0002),
+ * the same shape agents see in `sectionSubmissionSchemas` of the page contract.
+ */
+visitorToolDefs['submit-form'] = {
+  ...submitFormDef,
+  execute: async (rawArgs: unknown) => {
+    const parsed = FormDemoSubmissionSchema.parse(rawArgs);
+    const form = document.querySelector<HTMLFormElement>('form[data-olon-recipient]');
+    const args = rawArgs as Record<string, unknown>;
+    const sectionId =
+      typeof args.sectionId === 'string' && args.sectionId.trim()
+        ? args.sectionId.trim()
+        : form?.id || 'form-demo';
+    return submitFormLead(parsed as SubmitFormArgs, {
+      recipientEmail: form?.dataset.olonRecipient ?? '',
+      sectionId,
+      pageSlug: window.location.pathname,
+      path: 'form/send',
+    });
+  },
+};
+
+END_OF_FILE_CONTENT
+echo "Creating src/lib/webmcp/toolRegistry.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/lib/webmcp/toolRegistry.ts"
+import type { WebMcpToolDef } from '@olonjs/core';
+import { webmcpTools as formDemoTools } from '@/components/form-demo';
+
+/**
+ * Tenant tool registry (spec 01-webmcp-tool-contract).
+ *
+ * Section capsules declare tools by exporting `webmcpTools` from their
+ * `index.ts`. Aggregate them here:
+ * - admin-surface defs + executors flow into the Studio island
+ *   (`AdminStudioClient` → `JsonPagesConfig.webmcp`);
+ * - public-surface tool names flow into the visitor page via
+ *   `sectionPublicTools` (module 02).
+ */
+
+/** Admin-surface tool defs registered in the Studio island. */
+export const declaredAdminTools: readonly WebMcpToolDef[] = [];
+
+/** Runtime executors for admin tools, keyed by tool name. */
+export const adminToolExecutors: Readonly<
+  Record<string, (args: unknown) => Promise<unknown> | unknown>
+> = {};
+
+/** Public tool names exposed per section type (consumed by module 02). */
+export const sectionPublicTools: Record<string, readonly string[]> = {
+  'form-demo': formDemoTools.map((tool) => tool.name),
+};
+
+/** Public-surface tool defs emitted in the runtime page contracts (module 02). */
+export const declaredPublicTools: readonly WebMcpToolDef[] = [...formDemoTools];
+
+END_OF_FILE_CONTENT
+echo "Creating src/lib/webmcp/visitorIsland.test.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/lib/webmcp/visitorIsland.test.ts"
+// @vitest-environment jsdom
+import { afterEach, describe, expect, it, vi } from 'vitest';
+import { act, createElement } from 'react';
+import { createRoot, type Root } from 'react-dom/client';
+import { WebMcpVisitorRuntime } from '@/components/webmcp/WebMcpVisitorRuntime';
+import { visitorToolDefs } from '@/lib/webmcp/visitorToolDefs';
+
+function protocol() {
+  return (document as unknown as {
+    modelContextProtocol: {
+      listTools: () => Array<{ name: string }>;
+      executeTool: (name: string, inputArgsJson: string) => Promise<string>;
+    };
+  }).modelContextProtocol;
+}
+
+let root: Root | null = null;
+let container: HTMLDivElement | null = null;
+
+afterEach(() => {
+  delete visitorToolDefs['test-tool'];
+  if (root) {
+    act(() => root!.unmount());
+    root = null;
+  }
+  container?.remove();
+  container = null;
+  const doc = document as unknown as { modelContext?: unknown; modelContextProtocol?: unknown };
+  delete doc.modelContext;
+  delete doc.modelContextProtocol;
+  const win = window as unknown as { __olonWebMcpTools__?: unknown; __olonWebMcpControllers__?: unknown };
+  delete win.__olonWebMcpTools__;
+  delete win.__olonWebMcpControllers__;
+  vi.restoreAllMocks();
+});
+
+function mount(toolNames: string[]) {
+  container = document.createElement('div');
+  document.body.appendChild(container);
+  root = createRoot(container);
+  act(() => {
+    root!.render(createElement(WebMcpVisitorRuntime, { toolNames }));
+  });
+}
+
+describe('WebMcpVisitorRuntime — public tool registration', () => {
+  it('registers the declared tools for the page and executes them', async () => {
+    visitorToolDefs['test-tool'] = {
+      name: 'test-tool',
+      description: 'Test tool',
+      surface: 'public',
+      inputSchema: { type: 'object', additionalProperties: false, properties: {} },
+      execute: async (args: unknown) => ({ ok: true, args }),
+    };
+
+    mount(['test-tool', 'unknown-tool']);
+
+    await vi.waitFor(() => {
+      expect(protocol().listTools().map((t) => t.name)).toContain('test-tool');
+    });
+
+    const result = await protocol().executeTool('test-tool', '{"q":1}');
+    expect(JSON.parse(result)).toEqual({ ok: true, args: { q: 1 } });
+
+    act(() => root!.unmount());
+    root = null;
+
+    await vi.waitFor(() => {
+      expect(protocol().listTools().map((t) => t.name)).not.toContain('test-tool');
+    });
+  });
+
+  it('does not register anything when the page has no tool names', () => {
+    mount([]);
+    expect(protocol().listTools()).toEqual([]);
+  });
+});
+
 END_OF_FILE_CONTENT
 echo "Creating src/lib/webmcp/visitorPageWebMcpWiring.test.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/webmcp/visitorPageWebMcpWiring.test.ts"
@@ -6506,6 +7054,28 @@ describe('visitor page WebMCP wiring', () => {
   });
 });
 
+END_OF_FILE_CONTENT
+echo "Creating src/lib/webmcp/visitorToolDefs.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/lib/webmcp/visitorToolDefs.ts"
+import type { WebMcpToolDef } from '@olonjs/core';
+
+export interface VisitorToolRegistration extends WebMcpToolDef {
+  /** Client-side executor — the dev's domain logic (fetch, route handler, external service). */
+  execute: (args: unknown) => Promise<unknown> | unknown;
+}
+
+/**
+ * Client-side registry of public tools: name → def with executor
+ * (spec 02-webmcp-tool-public-runtime).
+ *
+ * The RSC page passes only the enabled tool NAMES (functions cannot cross the
+ * RSC boundary); this registry resolves them to their executors at
+ * registration time in the visitor island.
+ *
+ * Section capsules register here — module 03 adds 'submit-form'.
+ */
+export const visitorToolDefs: Record<string, VisitorToolRegistration> = {};
+
 END_OF_FILE_CONTENT
 mkdir -p "src/sources"
 echo "Creating src/sources/catalogo.test.ts..."

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@olonjs/cli",
-  "version": "3.0.166",
+  "version": "3.0.167",
   "description": "The Sovereign CLI Engine for OlonJS.",
   "type": "module",
   "bin": {