@olonjs/cli 3.0.165 → 3.0.166

package/assets/templates/next/src_tenant.sh

@@ -19,11 +19,10 @@ import {
 import { loadVisitorPage } from '@olonjs/next/server';
 import { EmptyTenantView } from '@/components/empty-tenant';
 import { WebMcpVisitorRuntime } from '@/components/webmcp/WebMcpVisitorRuntime';
-import { CollectionRegistry } from '@/lib/CollectionRegistry';
 import { buildVisitorWebPageJsonLd } from '@/lib/buildVisitorWebPageJsonLd';
-import { getFileCollections } from '@/lib/loaders/getFileCollections';
 import { getFilePages } from '@/lib/loaders/getFilePages';
 import { getFileSiteBundle } from '@/lib/loaders/getFileSiteConfig';
+import { loadVisitorPageBundle } from '@/lib/loaders/loadVisitorPageBundle';
 import { resolveVisitorShell } from '@/lib/resolveVisitorShell';
 import { VisitorSection } from '@/lib/VisitorSection';
 
@@ -89,7 +88,10 @@ export default async function VisitorCatchAllPage({ params, searchParams }: Page
     notFound();
   }
 
-  const collections = getFileCollections();
+  const { collections, collectionSchemas } = await loadVisitorPageBundle({
+    page: result.page,
+    params: result.params,
+  });
   const { siteConfig, menuConfig, themeConfig } = getFileSiteBundle();
   const collectionContext = resolveCollectionContext(result.page, result.params, collections);
 
@@ -99,7 +101,7 @@ export default async function VisitorCatchAllPage({ params, searchParams }: Page
     themeConfig,
     menuConfig,
     collections,
-    collectionSchemas: CollectionRegistry as never,
+    collectionSchemas: collectionSchemas as never,
     collectionContext,
     refDocuments: {
       'menu.json': menuConfig,
@@ -213,27 +215,50 @@ mkdir -p "app/api/public-collection/[source]"
 mkdir -p "app/api/public-collection/[source]/[file]"
 echo "Creating app/api/public-collection/[source]/[file]/route.ts..."
 cat << 'END_OF_FILE_CONTENT' > "app/api/public-collection/[source]/[file]/route.ts"
-import { NextResponse } from 'next/server';
-import { resolvePublicCollectionDocument } from '@/lib/loaders/publishedContent';
-import { loadRuntimeSurfaceForSite } from '@/lib/webmcp/runtime/loadRuntimeSurface';
-
-export const dynamic = 'force-dynamic';
-
-/** GET /collections/{source}/{source}.json (rewrite) — collection document, runtime. */
-export async function GET(_request: Request, context: { params: Promise<{ source: string; file: string }> }) {
-  try {
-    const { source, file } = await context.params;
-    const { bundle } = loadRuntimeSurfaceForSite();
-    const doc = resolvePublicCollectionDocument(bundle, decodeURIComponent(source), decodeURIComponent(file));
-    if (!doc) return NextResponse.json({ error: 'Collection not found' }, { status: 404 });
-    return NextResponse.json(doc);
-  } catch (error) {
-    return NextResponse.json(
-      { error: error instanceof Error ? error.message : 'Collection JSON failed' },
-      { status: 500 },
-    );
-  }
-}
+import { NextResponse } from 'next/server';
+import { resolveCollectionSources } from '@olonjs/sources';
+import { resolvePublicCollectionDocument } from '@/lib/loaders/publishedContent';
+import { collectionSources } from '@/sources';
+import { loadRuntimeSurfaceForSite } from '@/lib/webmcp/runtime/loadRuntimeSurface';
+
+export const dynamic = 'force-dynamic';
+
+/**
+ * GET /collections/{source}/{source}.json (rewrite) — collection document, runtime.
+ *
+ * File-backed collections are read from the content bundle; EXTERNAL sources
+ * (ADR-0018) are projected on demand so the contract's `dataHref` resolves.
+ * Note: resolution here has no route params — parameterized sources should be
+ * resolved at the page level (see loadPublicPageBundleForRequest).
+ */
+export async function GET(_request: Request, context: { params: Promise<{ source: string; file: string }> }) {
+  try {
+    const { source, file } = await context.params;
+    const sourceName = decodeURIComponent(source);
+
+    if (sourceName in collectionSources) {
+      const resolved = await resolveCollectionSources({
+        sources: collectionSources as never,
+        needed: [sourceName],
+      });
+      const projected = resolved.collections[sourceName];
+      if (!projected) {
+        return NextResponse.json({ error: 'Collection not found' }, { status: 404 });
+      }
+      return NextResponse.json(projected);
+    }
+
+    const { bundle } = loadRuntimeSurfaceForSite();
+    const doc = resolvePublicCollectionDocument(bundle, sourceName, decodeURIComponent(file));
+    if (!doc) return NextResponse.json({ error: 'Collection not found' }, { status: 404 });
+    return NextResponse.json(doc);
+  } catch (error) {
+    return NextResponse.json(
+      { error: error instanceof Error ? error.message : 'Collection JSON failed' },
+      { status: 500 },
+    );
+  }
+}
 
 END_OF_FILE_CONTENT
 mkdir -p "app/api/public-config"
@@ -761,10 +786,10 @@ cat << 'END_OF_FILE_CONTENT' > "package.json"
     "dist:dna": "npm run dist"
   },
   "dependencies": {
-    "@olonjs/core": "^2.0.1",
-    "@olonjs/next": "^0.0.13",
-    "@olonjs/react": "^0.2.1",
-    "@olonjs/studio": "^0.2.1",
+    "@olonjs/core": "^2.0.2",
+    "@olonjs/next": "^0.0.14",
+    "@olonjs/react": "^0.2.2",
+    "@olonjs/studio": "^0.2.2",
     "clsx": "^2.1.1",
     "lucide-react": "^0.474.0",
     "next": "^15.5.0",
@@ -772,7 +797,8 @@ 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"
+    "zod": "^4.6.0",
+    "@olonjs/sources": "^0.1.0"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "^4.0.0",
@@ -1011,10 +1037,16 @@ const SCRIPT = path.join(__dirname, 'webmcp-feature-check.mjs');
 const PKG = path.join(ROOT, 'package.json');
 
 describe('next verify:webmcp script', () => {
-  it('probes document.modelContextProtocol (the surface ensureWebMcpRuntime assigns)', () => {
+  it('probes the native document.modelContext surface with polyfill fallback', () => {
     assert.ok(fs.existsSync(SCRIPT), `missing ${SCRIPT}`);
     const src = fs.readFileSync(SCRIPT, 'utf8');
+    // Native Chrome surface: document.modelContext.getTools() / executeTool(toolObject, argsObject).
+    assert.match(src, /document\.modelContext/);
+    assert.match(src, /await native\.getTools\(\)/);
+    assert.match(src, /native\.executeTool\(tool,/);
+    // Polyfill fallback (browsers without native WebMCP): listTools / executeTool(name, json).
     assert.match(src, /document\.modelContextProtocol/);
+    assert.match(src, /protocol\.executeTool\(/);
     // modelContextTesting is never assigned by the runtime — probing it is a false negative.
     assert.doesNotMatch(src, /modelContextTesting/);
     assert.doesNotMatch(src, /navigator\.modelContext/);
@@ -1031,302 +1063,351 @@ describe('next verify:webmcp script', () => {
 END_OF_FILE_CONTENT
 echo "Creating scripts/webmcp-feature-check.mjs..."
 cat << 'END_OF_FILE_CONTENT' > "scripts/webmcp-feature-check.mjs"
-import fs from 'fs/promises';
-import path from 'path';
-import { fileURLToPath } from 'url';
-import { createRequire } from 'module';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const rootDir = path.resolve(__dirname, '..');
-const baseUrl = process.env.WEBMCP_BASE_URL ?? 'http://127.0.0.1:3000';
-const UPDATE_TOOL_NAME = 'update-section';
-const SAVE_TOOL_NAME = 'save';
-
-function pageFilePathFromSlug(slug) {
-  return path.resolve(rootDir, 'src', 'data', 'pages', `${slug}.json`);
-}
-
-function adminUrlFromSlug(slug) {
-  return `${baseUrl}/admin${slug === 'home' ? '' : `/${slug}`}`;
-}
-
-function isStringSchema(schema) {
-  if (!schema || typeof schema !== 'object') return false;
-  if (schema.type === 'string') return true;
-  if (Array.isArray(schema.anyOf)) {
-    return schema.anyOf.some((entry) => entry && typeof entry === 'object' && entry.type === 'string');
-  }
-  return false;
-}
-
-function findTopLevelStringField(sectionSchema) {
-  const properties = sectionSchema?.properties;
-  if (!properties || typeof properties !== 'object') return null;
-  const preferred = ['title', 'sectionTitle', 'label', 'headline', 'name'];
-  for (const key of preferred) {
-    if (isStringSchema(properties[key])) return key;
-  }
-  for (const [key, value] of Object.entries(properties)) {
-    if (isStringSchema(value)) return key;
-  }
-  return null;
-}
-
-async function loadPlaywright() {
-  const require = createRequire(import.meta.url);
-  try {
-    return require('playwright');
-  } catch (error) {
-    const message = error instanceof Error ? error.message : String(error);
-    throw new Error(
-      `Playwright is required for WebMCP verification. Install it before running this script. Original error: ${message}`
-    );
-  }
-}
-
-async function readPageJson(slug) {
-  const pageFilePath = pageFilePathFromSlug(slug);
-  const raw = await fs.readFile(pageFilePath, 'utf8');
-  return { raw, json: JSON.parse(raw), pageFilePath };
-}
-
-async function waitFor(predicate, timeoutMs, label) {
-  const startedAt = Date.now();
-  for (;;) {
-    const result = await predicate();
-    if (result) return result;
-    if (Date.now() - startedAt > timeoutMs) {
-      throw new Error(`Timed out while waiting for ${label}.`);
-    }
-    await new Promise((resolve) => setTimeout(resolve, 150));
-  }
-}
-
-async function waitForFileFieldValue(slug, sectionId, fieldKey, expectedValue) {
-  await waitFor(async () => {
-    const { json } = await readPageJson(slug);
-    const section = Array.isArray(json.sections)
-      ? json.sections.find((item) => item?.id === sectionId)
-      : null;
-    return section?.data?.[fieldKey] === expectedValue;
-  }, 8_000, `file field "${fieldKey}" = "${expectedValue}"`);
-}
-
-async function ensureResponseOk(response, label) {
-  if (!response.ok) {
-    const text = await response.text();
-    throw new Error(`${label} failed with ${response.status}: ${text}`);
-  }
-  return response;
-}
-
-async function fetchJson(relativePath, label) {
-  const response = await ensureResponseOk(await fetch(`${baseUrl}${relativePath}`), label);
-  return response.json();
-}
-
-async function selectTarget() {
-  const siteIndex = await fetchJson('/mcp-manifest.json', 'Manifest index request');
-  const requestedSlug = typeof process.env.WEBMCP_TARGET_SLUG === 'string' && process.env.WEBMCP_TARGET_SLUG.trim()
-    ? process.env.WEBMCP_TARGET_SLUG.trim()
-    : null;
-
-  const candidatePages = requestedSlug
-    ? (siteIndex.pages ?? []).filter((page) => page?.slug === requestedSlug)
-    : (siteIndex.pages ?? []);
-
-  for (const pageEntry of candidatePages) {
-    if (!pageEntry?.slug || !pageEntry?.manifestHref || !pageEntry?.contractHref) continue;
-    const pageManifest = await fetchJson(pageEntry.manifestHref, `Page manifest request for ${pageEntry.slug}`);
-    const pageContract = await fetchJson(pageEntry.contractHref, `Page contract request for ${pageEntry.slug}`);
-    const localInstances = Array.isArray(pageContract.sectionInstances)
-      ? pageContract.sectionInstances.filter((section) => section?.scope === 'local')
-      : [];
-    const tools = Array.isArray(pageManifest.tools) ? pageManifest.tools : [];
-    // Manifest tools are page-level (`update-section`, `save`); targets come from the
-    // contract's local section instances + their schemas.
-    const updateTool = tools.find((tool) => tool?.name === UPDATE_TOOL_NAME);
-    const saveTool = tools.find((tool) => tool?.name === SAVE_TOOL_NAME);
-    if (!updateTool || !saveTool) continue;
-
-    for (const targetInstance of localInstances) {
-      const sectionType = targetInstance?.type;
-      if (!targetInstance?.id || typeof sectionType !== 'string') continue;
-      const targetFieldKey = findTopLevelStringField(pageContract.sectionSchemas?.[sectionType]);
-      if (!targetFieldKey) continue;
-      const pageState = await readPageJson(pageEntry.slug);
-      const section = Array.isArray(pageState.json.sections)
-        ? pageState.json.sections.find((item) => item?.id === targetInstance.id)
-        : null;
-      const originalValue = section?.data?.[targetFieldKey];
-      if (typeof originalValue !== 'string') continue;
-
-      return {
-        slug: pageEntry.slug,
-        manifestHref: pageEntry.manifestHref,
-        contractHref: pageEntry.contractHref,
-        toolName: UPDATE_TOOL_NAME,
-        saveToolName: SAVE_TOOL_NAME,
-        sectionId: targetInstance.id,
-        sectionType,
-        fieldKey: targetFieldKey,
-        originalValue,
-        originalState: pageState,
-      };
-    }
-  }
-
-  throw new Error(
-    requestedSlug
-      ? `No valid WebMCP verification target found for page "${requestedSlug}".`
-      : 'No valid WebMCP verification target found in manifest index.'
-  );
-}
-
-async function main() {
-  const { chromium } = await loadPlaywright();
-  const target = await selectTarget();
-  const nextValue = `${target.originalValue} WebMCP ${Date.now()}`;
-  const browser = await chromium.launch({ headless: true });
-  const page = await browser.newPage();
-  const consoleEvents = [];
-  let mutationApplied = false;
-
-  page.on('console', (message) => {
-    if (message.type() === 'error' || message.type() === 'warning') {
-      consoleEvents.push(`[console:${message.type()}] ${message.text()}`);
-    }
-  });
-  page.on('pageerror', (error) => {
-    consoleEvents.push(`[pageerror] ${error.message}`);
-  });
-
-  /** update-section mutates the Studio draft only; save persists. Returns raw update result. */
-  const runUpdateThenSave = async (value) => {
-    const rawUpdate = await page.evaluate(
-      async ({ toolName, slug, sectionId, sectionType, fieldKey, value: nextValue }) => {
-        const runtime = document.modelContextProtocol;
-        if (!runtime?.executeTool) {
-          throw new Error('document.modelContextProtocol.executeTool is unavailable.');
-        }
-        return runtime.executeTool(
-          toolName,
-          JSON.stringify({ slug, sectionId, sectionType, fieldKey, value: nextValue })
-        );
-      },
-      {
-        toolName: target.toolName,
-        slug: target.slug,
-        sectionId: target.sectionId,
-        sectionType: target.sectionType,
-        fieldKey: target.fieldKey,
-        value,
-      }
-    );
-    const parsedUpdate = JSON.parse(rawUpdate);
-    if (parsedUpdate?.isError) {
-      throw new Error(`WebMCP ${target.toolName} returned an error: ${rawUpdate}`);
-    }
-    const rawSave = await page.evaluate(
-      async ({ saveToolName }) => document.modelContextProtocol.executeTool(saveToolName, '{}'),
-      { saveToolName: target.saveToolName }
-    );
-    const parsedSave = JSON.parse(rawSave);
-    if (parsedSave?.isError) {
-      throw new Error(`WebMCP ${target.saveToolName} returned an error: ${rawSave}`);
-    }
-    return rawUpdate;
-  };
-
-  const restoreOriginal = async () => {
-    try {
-      await runUpdateThenSave(target.originalValue);
-      await waitForFileFieldValue(target.slug, target.sectionId, target.fieldKey, target.originalValue);
-    } catch {
-      await fs.writeFile(target.originalState.pageFilePath, target.originalState.raw, 'utf8');
-    }
-  };
-
-  try {
-    const pageManifest = await fetchJson(target.manifestHref, `Manifest request for ${target.slug}`);
-    if (!Array.isArray(pageManifest.tools) || !pageManifest.tools.some((tool) => tool?.name === target.toolName)) {
-      throw new Error(`Manifest does not expose ${target.toolName}.`);
-    }
-
-    const pageContract = await fetchJson(target.contractHref, `Page contract request for ${target.slug}`);
-    if (!Array.isArray(pageContract.tools) || !pageContract.tools.some((tool) => tool?.name === target.toolName)) {
-      throw new Error(`Page contract does not expose ${target.toolName}.`);
-    }
-
-    await page.goto(adminUrlFromSlug(target.slug), { waitUntil: 'networkidle' });
-
-    try {
-      await page.waitForFunction(
-        ({ manifestHref, contractHref }) => {
-          const manifestLink = document.head.querySelector('link[rel="mcp-manifest"]');
-          const contractLink = document.head.querySelector('link[rel="olon-contract"]');
-          return manifestLink?.getAttribute('href') === manifestHref
-            && contractLink?.getAttribute('href') === contractHref;
-        },
-        { manifestHref: target.manifestHref, contractHref: target.contractHref },
-        { timeout: 10_000 }
-      );
-    } catch (error) {
-      const diagnostics = await page.evaluate(() => ({
-        head: document.head.innerHTML,
-        bodyText: document.body.innerText,
-      }));
-      throw new Error(
-        [
-          error instanceof Error ? error.message : String(error),
-          `head=${diagnostics.head}`,
-          `body=${diagnostics.bodyText}`,
-          ...consoleEvents,
-        ].join('\n')
-      );
-    }
-
-    const toolNames = await page.evaluate(() => {
-      const runtime = document.modelContextProtocol;
-      return runtime?.listTools?.().map((tool) => tool.name) ?? [];
-    });
-    for (const required of [target.toolName, target.saveToolName]) {
-      if (!toolNames.includes(required)) {
-        throw new Error(`Runtime did not register ${required}. Found: ${toolNames.join(', ')}`);
-      }
-    }
-
-    mutationApplied = true;
-    await runUpdateThenSave(nextValue);
-    await waitForFileFieldValue(target.slug, target.sectionId, target.fieldKey, nextValue);
-    await page.frameLocator('iframe').getByText(nextValue, { exact: true }).waitFor({ state: 'attached' });
-
-    console.log(
-      JSON.stringify({
-        ok: true,
-        slug: target.slug,
-        manifestHref: target.manifestHref,
-        contractHref: target.contractHref,
-        toolName: target.toolName,
-        saveToolName: target.saveToolName,
-        sectionId: target.sectionId,
-        sectionType: target.sectionType,
-        fieldKey: target.fieldKey,
-        toolNames,
-      })
-    );
-  } finally {
-    if (mutationApplied) {
-      await restoreOriginal();
-    }
-    await browser.close();
-  }
-}
-
-main().catch((error) => {
-  console.error(error instanceof Error ? error.stack ?? error.message : String(error));
-  process.exit(1);
-});
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequire } from 'module';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, '..');
+const baseUrl = process.env.WEBMCP_BASE_URL ?? 'http://127.0.0.1:3000';
+const UPDATE_TOOL_NAME = 'update-section';
+const SAVE_TOOL_NAME = 'save';
+
+function pageFilePathFromSlug(slug) {
+  return path.resolve(rootDir, 'src', 'data', 'pages', `${slug}.json`);
+}
+
+function adminUrlFromSlug(slug) {
+  return `${baseUrl}/admin${slug === 'home' ? '' : `/${slug}`}`;
+}
+
+function isStringSchema(schema) {
+  if (!schema || typeof schema !== 'object') return false;
+  if (schema.type === 'string') return true;
+  if (Array.isArray(schema.anyOf)) {
+    return schema.anyOf.some((entry) => entry && typeof entry === 'object' && entry.type === 'string');
+  }
+  return false;
+}
+
+function findTopLevelStringField(sectionSchema) {
+  const properties = sectionSchema?.properties;
+  if (!properties || typeof properties !== 'object') return null;
+  const preferred = ['title', 'sectionTitle', 'label', 'headline', 'name'];
+  for (const key of preferred) {
+    if (isStringSchema(properties[key])) return key;
+  }
+  for (const [key, value] of Object.entries(properties)) {
+    if (isStringSchema(value)) return key;
+  }
+  return null;
+}
+
+async function loadPlaywright() {
+  const require = createRequire(import.meta.url);
+  try {
+    return require('playwright');
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Playwright is required for WebMCP verification. Install it before running this script. Original error: ${message}`
+    );
+  }
+}
+
+async function readPageJson(slug) {
+  const pageFilePath = pageFilePathFromSlug(slug);
+  const raw = await fs.readFile(pageFilePath, 'utf8');
+  return { raw, json: JSON.parse(raw), pageFilePath };
+}
+
+async function waitFor(predicate, timeoutMs, label) {
+  const startedAt = Date.now();
+  for (;;) {
+    const result = await predicate();
+    if (result) return result;
+    if (Date.now() - startedAt > timeoutMs) {
+      throw new Error(`Timed out while waiting for ${label}.`);
+    }
+    await new Promise((resolve) => setTimeout(resolve, 150));
+  }
+}
+
+async function waitForFileFieldValue(slug, sectionId, fieldKey, expectedValue) {
+  await waitFor(async () => {
+    const { json } = await readPageJson(slug);
+    const section = Array.isArray(json.sections)
+      ? json.sections.find((item) => item?.id === sectionId)
+      : null;
+    return section?.data?.[fieldKey] === expectedValue;
+  }, 8_000, `file field "${fieldKey}" = "${expectedValue}"`);
+}
+
+async function ensureResponseOk(response, label) {
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`${label} failed with ${response.status}: ${text}`);
+  }
+  return response;
+}
+
+async function fetchJson(relativePath, label) {
+  const response = await ensureResponseOk(await fetch(`${baseUrl}${relativePath}`), label);
+  return response.json();
+}
+
+async function selectTarget() {
+  const siteIndex = await fetchJson('/mcp-manifest.json', 'Manifest index request');
+  const requestedSlug = typeof process.env.WEBMCP_TARGET_SLUG === 'string' && process.env.WEBMCP_TARGET_SLUG.trim()
+    ? process.env.WEBMCP_TARGET_SLUG.trim()
+    : null;
+
+  const candidatePages = requestedSlug
+    ? (siteIndex.pages ?? []).filter((page) => page?.slug === requestedSlug)
+    : (siteIndex.pages ?? []);
+
+  for (const pageEntry of candidatePages) {
+    if (!pageEntry?.slug || !pageEntry?.manifestHref || !pageEntry?.contractHref) continue;
+    const pageManifest = await fetchJson(pageEntry.manifestHref, `Page manifest request for ${pageEntry.slug}`);
+    const pageContract = await fetchJson(pageEntry.contractHref, `Page contract request for ${pageEntry.slug}`);
+    const localInstances = Array.isArray(pageContract.sectionInstances)
+      ? pageContract.sectionInstances.filter((section) => section?.scope === 'local')
+      : [];
+    const tools = Array.isArray(pageManifest.tools) ? pageManifest.tools : [];
+    // Manifest tools are page-level (`update-section`, `save`); targets come from the
+    // contract's local section instances + their schemas.
+    const updateTool = tools.find((tool) => tool?.name === UPDATE_TOOL_NAME);
+    const saveTool = tools.find((tool) => tool?.name === SAVE_TOOL_NAME);
+    if (!updateTool || !saveTool) continue;
+
+    for (const targetInstance of localInstances) {
+      const sectionType = targetInstance?.type;
+      if (!targetInstance?.id || typeof sectionType !== 'string') continue;
+      const targetFieldKey = findTopLevelStringField(pageContract.sectionSchemas?.[sectionType]);
+      if (!targetFieldKey) continue;
+      const pageState = await readPageJson(pageEntry.slug);
+      const section = Array.isArray(pageState.json.sections)
+        ? pageState.json.sections.find((item) => item?.id === targetInstance.id)
+        : null;
+      const originalValue = section?.data?.[targetFieldKey];
+      if (typeof originalValue !== 'string') continue;
+
+      return {
+        slug: pageEntry.slug,
+        manifestHref: pageEntry.manifestHref,
+        contractHref: pageEntry.contractHref,
+        toolName: UPDATE_TOOL_NAME,
+        saveToolName: SAVE_TOOL_NAME,
+        sectionId: targetInstance.id,
+        sectionType,
+        fieldKey: targetFieldKey,
+        originalValue,
+        originalState: pageState,
+      };
+    }
+  }
+
+  throw new Error(
+    requestedSlug
+      ? `No valid WebMCP verification target found for page "${requestedSlug}".`
+      : 'No valid WebMCP verification target found in manifest index.'
+  );
+}
+
+async function main() {
+  const { chromium } = await loadPlaywright();
+  const target = await selectTarget();
+  const nextValue = `${target.originalValue} WebMCP ${Date.now()}`;
+  const browser = await chromium.launch({ headless: true });
+  const page = await browser.newPage();
+  const consoleEvents = [];
+  let mutationApplied = false;
+
+  page.on('console', (message) => {
+    if (message.type() === 'error' || message.type() === 'warning') {
+      consoleEvents.push(`[console:${message.type()}] ${message.text()}`);
+    }
+  });
+  page.on('pageerror', (error) => {
+    consoleEvents.push(`[pageerror] ${error.message}`);
+  });
+
+  /** update-section mutates the Studio draft only; save persists. Returns raw update result. */
+  const runUpdateThenSave = async (value) => {
+    const rawUpdate = await page.evaluate(
+      async ({ toolName, slug, sectionId, sectionType, fieldKey, value: nextValue }) => {
+        const args = { slug, sectionId, sectionType, fieldKey, value: nextValue };
+        const native = document.modelContext;
+        const protocol = document.modelContextProtocol;
+        // Native Chrome WebMCP: executeTool(toolObject, args) — the tool object
+        // comes from getTools(). Args format: plain object since Chrome 155;
+        // before that the native expects a JSON string (verified on Chrome 153).
+        if (native && typeof native.executeTool === 'function') {
+          const tools = await native.getTools();
+          const tool = tools.find((entry) => entry.name === toolName);
+          if (!tool) {
+            throw new Error(`Tool "${toolName}" not found in native getTools().`);
+          }
+          const chromeMajor = Number((navigator.userAgent.match(/Chrome\/(\d+)/) ?? [])[1] ?? 0);
+          const nativeArgs = chromeMajor >= 155 ? args : JSON.stringify(args);
+          const result = await native.executeTool(tool, nativeArgs);
+          if (result === null) {
+            throw new Error(`Tool "${toolName}" returned null (navigation).`);
+          }
+          return typeof result === 'string' ? result : JSON.stringify(result);
+        }
+        if (protocol && typeof protocol.executeTool === 'function') {
+          return protocol.executeTool(toolName, JSON.stringify(args));
+        }
+        throw new Error(
+          'WebMCP runtime unavailable: no document.modelContext (native) and no document.modelContextProtocol (polyfill).',
+        );
+      },
+      {
+        toolName: target.toolName,
+        slug: target.slug,
+        sectionId: target.sectionId,
+        sectionType: target.sectionType,
+        fieldKey: target.fieldKey,
+        value,
+      }
+    );
+    const parsedUpdate = JSON.parse(rawUpdate);
+    if (parsedUpdate?.isError) {
+      throw new Error(`WebMCP ${target.toolName} returned an error: ${rawUpdate}`);
+    }
+    const rawSave = await page.evaluate(
+      async ({ saveToolName }) => {
+        const native = document.modelContext;
+        const protocol = document.modelContextProtocol;
+        if (native && typeof native.executeTool === 'function') {
+          const tools = await native.getTools();
+          const tool = tools.find((entry) => entry.name === saveToolName);
+          if (!tool) {
+            throw new Error(`Tool "${saveToolName}" not found in native getTools().`);
+          }
+          const chromeMajor = Number((navigator.userAgent.match(/Chrome\/(\d+)/) ?? [])[1] ?? 0);
+          const nativeArgs = chromeMajor >= 155 ? {} : '{}';
+          const result = await native.executeTool(tool, nativeArgs);
+          if (result === null) {
+            throw new Error(`Tool "${saveToolName}" returned null (navigation).`);
+          }
+          return typeof result === 'string' ? result : JSON.stringify(result);
+        }
+        if (protocol && typeof protocol.executeTool === 'function') {
+          return protocol.executeTool(saveToolName, '{}');
+        }
+        throw new Error(
+          'WebMCP runtime unavailable: no document.modelContext (native) and no document.modelContextProtocol (polyfill).',
+        );
+      },
+      { saveToolName: target.saveToolName }
+    );
+    const parsedSave = JSON.parse(rawSave);
+    if (parsedSave?.isError) {
+      throw new Error(`WebMCP ${target.saveToolName} returned an error: ${rawSave}`);
+    }
+    return rawUpdate;
+  };
+
+  const restoreOriginal = async () => {
+    try {
+      await runUpdateThenSave(target.originalValue);
+      await waitForFileFieldValue(target.slug, target.sectionId, target.fieldKey, target.originalValue);
+    } catch {
+      await fs.writeFile(target.originalState.pageFilePath, target.originalState.raw, 'utf8');
+    }
+  };
+
+  try {
+    const pageManifest = await fetchJson(target.manifestHref, `Manifest request for ${target.slug}`);
+    if (!Array.isArray(pageManifest.tools) || !pageManifest.tools.some((tool) => tool?.name === target.toolName)) {
+      throw new Error(`Manifest does not expose ${target.toolName}.`);
+    }
+
+    const pageContract = await fetchJson(target.contractHref, `Page contract request for ${target.slug}`);
+    if (!Array.isArray(pageContract.tools) || !pageContract.tools.some((tool) => tool?.name === target.toolName)) {
+      throw new Error(`Page contract does not expose ${target.toolName}.`);
+    }
+
+    await page.goto(adminUrlFromSlug(target.slug), { waitUntil: 'networkidle' });
+
+    try {
+      await page.waitForFunction(
+        ({ manifestHref, contractHref }) => {
+          const manifestLink = document.head.querySelector('link[rel="mcp-manifest"]');
+          const contractLink = document.head.querySelector('link[rel="olon-contract"]');
+          return manifestLink?.getAttribute('href') === manifestHref
+            && contractLink?.getAttribute('href') === contractHref;
+        },
+        { manifestHref: target.manifestHref, contractHref: target.contractHref },
+        { timeout: 10_000 }
+      );
+    } catch (error) {
+      const diagnostics = await page.evaluate(() => ({
+        head: document.head.innerHTML,
+        bodyText: document.body.innerText,
+      }));
+      throw new Error(
+        [
+          error instanceof Error ? error.message : String(error),
+          `head=${diagnostics.head}`,
+          `body=${diagnostics.bodyText}`,
+          ...consoleEvents,
+        ].join('\n')
+      );
+    }
+
+    const toolNames = await page.evaluate(async () => {
+      const native = document.modelContext;
+      const protocol = document.modelContextProtocol;
+      if (native && typeof native.getTools === 'function') {
+        const tools = await native.getTools();
+        return tools.map((tool) => tool.name);
+      }
+      if (protocol && typeof protocol.listTools === 'function') {
+        return protocol.listTools().map((tool) => tool.name);
+      }
+      return [];
+    });
+    for (const required of [target.toolName, target.saveToolName]) {
+      if (!toolNames.includes(required)) {
+        throw new Error(`Runtime did not register ${required}. Found: ${toolNames.join(', ')}`);
+      }
+    }
+
+    mutationApplied = true;
+    await runUpdateThenSave(nextValue);
+    await waitForFileFieldValue(target.slug, target.sectionId, target.fieldKey, nextValue);
+    await page.frameLocator('iframe').getByText(nextValue, { exact: true }).waitFor({ state: 'attached' });
+
+    console.log(
+      JSON.stringify({
+        ok: true,
+        slug: target.slug,
+        manifestHref: target.manifestHref,
+        contractHref: target.contractHref,
+        toolName: target.toolName,
+        saveToolName: target.saveToolName,
+        sectionId: target.sectionId,
+        sectionType: target.sectionType,
+        fieldKey: target.fieldKey,
+        toolNames,
+      })
+    );
+  } finally {
+    if (mutationApplied) {
+      await restoreOriginal();
+    }
+    await browser.close();
+  }
+}
+
+main().catch((error) => {
+  console.error(error instanceof Error ? error.stack ?? error.message : String(error));
+  process.exit(1);
+});
 
 END_OF_FILE_CONTENT
 mkdir -p "src"
@@ -1396,6 +1477,43 @@ import { LibroSchema, LibriCollectionSchema } from './schema';
 export type Libro = z.infer<typeof LibroSchema>;
 export type LibriCollection = z.infer<typeof LibriCollectionSchema>;
 
+END_OF_FILE_CONTENT
+mkdir -p "src/collections/prodotti"
+echo "Creating src/collections/prodotti/index.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/collections/prodotti/index.ts"
+export { ProdottoSchema, ProdottiCollectionSchema } from './schema';
+export type { Prodotto, ProdottiCollection } from './types';
+
+END_OF_FILE_CONTENT
+echo "Creating src/collections/prodotti/schema.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/collections/prodotti/schema.ts"
+import { z } from 'zod';
+import { BaseCollectionItem } from '@olonjs/core';
+
+/**
+ * Demo collection whose source of truth is EXTERNAL (see src/sources/catalogo.ts).
+ * Same Zod item shape feeds the human list rendering (ui:* descriptors) and the
+ * agent contracts (JSON Schema emitted from this schema).
+ */
+export const ProdottoSchema = BaseCollectionItem.extend({
+  title: z.string().describe('ui:text'),
+  price: z.number().describe('ui:number'),
+  currency: z.string().default('EUR').describe('ui:text'),
+  description: z.string().optional().describe('ui:textarea'),
+  image: z.string().optional().describe('ui:text'),
+});
+
+export const ProdottiCollectionSchema = z.record(z.string(), ProdottoSchema);
+
+END_OF_FILE_CONTENT
+echo "Creating src/collections/prodotti/types.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/collections/prodotti/types.ts"
+import { z } from 'zod';
+import { ProdottoSchema, ProdottiCollectionSchema } from './schema';
+
+export type Prodotto = z.infer<typeof ProdottoSchema>;
+export type ProdottiCollection = z.infer<typeof ProdottiCollectionSchema>;
+
 END_OF_FILE_CONTENT
 mkdir -p "src/components"
 mkdir -p "src/components/admin"
@@ -2661,6 +2779,183 @@ import { HeaderSchema, HeaderSettingsSchema } from './schema';
 export type HeaderData = z.infer<typeof HeaderSchema>;
 export type HeaderSettings = z.infer<typeof HeaderSettingsSchema>;
 
+END_OF_FILE_CONTENT
+mkdir -p "src/components/prodotti-list"
+echo "Creating src/components/prodotti-list/View.tsx..."
+cat << 'END_OF_FILE_CONTENT' > "src/components/prodotti-list/View.tsx"
+import type { Prodotto } from '@/collections/prodotti';
+import type { ProdottiListData, ProdottiListSettings } from './types';
+
+type ProdottiListViewProps = {
+  data: ProdottiListData;
+  settings?: ProdottiListSettings;
+};
+
+function formatPrice(prodotto: Prodotto): string {
+  const amount = (prodotto.price / 100).toFixed(2);
+  return `${amount} ${prodotto.currency ?? 'EUR'}`;
+}
+
+function toProdotti(items: ProdottiListData['items']): Prodotto[] {
+  return Object.values(items ?? {}).sort((a, b) => a.title.localeCompare(b.title));
+}
+
+/**
+ * RSC-safe catalog list — data comes from a PROJECTED external source
+ * (src/sources/catalogo.ts). The View itself never fetches (CIP).
+ */
+export function ProdottiListView({ data }: ProdottiListViewProps) {
+  const prodotti = toProdotti(data.items);
+
+  return (
+    <section className="bg-background px-6 py-16 text-foreground">
+      <div className="mx-auto w-full max-w-5xl">
+        {data.eyebrow ? (
+          <p className="text-sm font-medium uppercase tracking-[0.18em] text-muted-foreground">
+            {data.eyebrow}
+          </p>
+        ) : null}
+        <h1 data-jp-field="title" className="mt-2 text-3xl font-semibold">
+          {data.title}
+        </h1>
+        {data.description ? (
+          <p data-jp-field="description" className="mt-3 max-w-2xl text-muted-foreground">
+            {data.description}
+          </p>
+        ) : null}
+
+        <ul className="mt-10 grid gap-6 sm:grid-cols-2 lg:grid-cols-3">
+          {prodotti.map((prodotto) => (
+            <li
+              key={prodotto.id}
+              data-jp-item-id={prodotto.id}
+              data-jp-item-field="items"
+              className="rounded-2xl border border-border bg-card p-6 shadow-sm"
+            >
+              <a
+                href={`/prodotti/${prodotto.id}`}
+                className="text-lg font-medium hover:underline"
+              >
+                {prodotto.title}
+              </a>
+              <p className="mt-2 text-sm text-muted-foreground">{formatPrice(prodotto)}</p>
+              {prodotto.description ? (
+                <p className="mt-3 text-sm text-muted-foreground">{prodotto.description}</p>
+              ) : null}
+            </li>
+          ))}
+        </ul>
+
+        {prodotti.length === 0 ? (
+          <p className="mt-10 text-muted-foreground">No products available.</p>
+        ) : null}
+      </div>
+    </section>
+  );
+}
+
+END_OF_FILE_CONTENT
+echo "Creating src/components/prodotti-list/index.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/components/prodotti-list/index.ts"
+export { ProdottiListView } from './View';
+export { ProdottiListSchema, ProdottiListSettingsSchema } from './schema';
+export type { ProdottiListData, ProdottiListSettings } from './types';
+
+END_OF_FILE_CONTENT
+echo "Creating src/components/prodotti-list/schema.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/components/prodotti-list/schema.ts"
+import { z } from 'zod';
+import { BaseSectionData } from '@olonjs/core';
+import { ProdottoSchema } from '@/collections/prodotti';
+
+export const ProdottiListSchema = BaseSectionData.extend({
+  eyebrow: z.string().optional().describe('ui:text'),
+  title: z.string().describe('ui:text'),
+  description: z.string().optional().describe('ui:textarea'),
+  items: z.record(z.string(), ProdottoSchema).describe('ui:collection-ref:catalogo'),
+});
+
+export const ProdottiListSettingsSchema = z.object({});
+
+END_OF_FILE_CONTENT
+echo "Creating src/components/prodotti-list/types.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/components/prodotti-list/types.ts"
+import type { z } from 'zod';
+import type { ProdottiListSchema, ProdottiListSettingsSchema } from './schema';
+
+export type ProdottiListData = z.infer<typeof ProdottiListSchema>;
+export type ProdottiListSettings = z.infer<typeof ProdottiListSettingsSchema>;
+
+END_OF_FILE_CONTENT
+mkdir -p "src/components/prodotto-detail"
+echo "Creating src/components/prodotto-detail/View.tsx..."
+cat << 'END_OF_FILE_CONTENT' > "src/components/prodotto-detail/View.tsx"
+import type { ProdottoDetailData, ProdottoDetailSettings } from './types';
+
+type ProdottoDetailViewProps = {
+  data: ProdottoDetailData;
+  settings?: ProdottoDetailSettings;
+};
+
+function formatPrice(price: number, currency?: string): string {
+  return `${(price / 100).toFixed(2)} ${currency ?? 'EUR'}`;
+}
+
+/** RSC-safe product detail — resolved from `collection:current` (projected source). */
+export function ProdottoDetailView({ data }: ProdottoDetailViewProps) {
+  const prodotto = data.item;
+
+  return (
+    <main className="min-h-screen bg-background px-6 py-16 text-foreground">
+      <article
+        data-jp-field="item"
+        data-jp-item-id={prodotto.id}
+        data-jp-item-field="item"
+        className="mx-auto w-full max-w-3xl rounded-2xl border border-border bg-card p-8 shadow-sm"
+      >
+        <a href="/prodotti" className="text-sm font-medium text-muted-foreground hover:text-foreground">
+          {data.backLabel}
+        </a>
+        <h1 className="mt-10 text-3xl font-semibold">{prodotto.title}</h1>
+        <p className="mt-3 text-lg">{formatPrice(prodotto.price, prodotto.currency)}</p>
+        {prodotto.description ? (
+          <p className="mt-6 text-muted-foreground">{prodotto.description}</p>
+        ) : null}
+      </article>
+    </main>
+  );
+}
+
+END_OF_FILE_CONTENT
+echo "Creating src/components/prodotto-detail/index.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/components/prodotto-detail/index.ts"
+export { ProdottoDetailView } from './View';
+export { ProdottoDetailSchema, ProdottoDetailSettingsSchema } from './schema';
+export type { ProdottoDetailData, ProdottoDetailSettings } from './types';
+
+END_OF_FILE_CONTENT
+echo "Creating src/components/prodotto-detail/schema.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/components/prodotto-detail/schema.ts"
+import { z } from 'zod';
+import { BaseSectionData } from '@olonjs/core';
+import { ProdottoSchema } from '@/collections/prodotti';
+
+export const ProdottoDetailSchema = BaseSectionData.extend({
+  item: ProdottoSchema.describe('ui:collection-ref'),
+  backLabel: z.string().default('Torna al catalogo').describe('ui:text'),
+});
+
+export const ProdottoDetailSettingsSchema = z.object({});
+
+END_OF_FILE_CONTENT
+echo "Creating src/components/prodotto-detail/types.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/components/prodotto-detail/types.ts"
+import type { z } from 'zod';
+import type { ProdottoDetailSchema, ProdottoDetailSettingsSchema } from './schema';
+
+export type ProdottoDetailData = z.infer<typeof ProdottoDetailSchema>;
+export type ProdottoDetailSettings = z.infer<typeof ProdottoDetailSettingsSchema>;
+
 END_OF_FILE_CONTENT
 mkdir -p "src/components/webmcp"
 echo "Creating src/components/webmcp/WebMcpVisitorRuntime.tsx..."
@@ -3062,8 +3357,8 @@ cat << 'END_OF_FILE_CONTENT' > "src/data/collections/libri/libri.json"
     "summary": "Fuga, destino e sogno si intrecciano in un romanzo sospeso tra reale e mitico."
   },
   "americanah": {
-    "id": "americanah",
-    "title": "Americanah",
+    "id": "americana",
+    "title": "Americana",
     "author": {
       "$ref": "../autori/autori.json#/chimamanda-ngozi-adichie"
     },
@@ -3134,6 +3429,10 @@ cat << 'END_OF_FILE_CONTENT' > "src/data/config/menu.json"
       "label": "Get started",
       "href": "#Getstarted"
     },
+    {
+      "label": "Prodotti",
+      "href": "/prodotti"
+    },
     {
       "label": "GitHub",
       "href": "https://github.com/olonjs/core"
@@ -3388,31 +3687,30 @@ mkdir -p "src/data/pages"
 mkdir -p "src/data/pages/authors"
 echo "Creating src/data/pages/authors.json..."
 cat << 'END_OF_FILE_CONTENT' > "src/data/pages/authors.json"
-{
-  "id": "authors-page",
-  "slug": "authors",
-  "meta": {
-    "title": "Authors",
-    "description": "Author directory powered by the autori collection."
-  },
-  "sections": [
-    {
-      "id": "authors-list-1",
-      "type": "authors-list",
-      "data": {
-        "anchorId": "authors",
-        "eyebrow": "Collection demo",
-        "title": "Authors",
-        "description": "A collection-backed directory of authors referenced by books.",
-        "items": {
-          "$ref": "../collections/autori/autori.json"
-        }
-      }
-    }
-  ],
-  "global-header": false
-}
-
+{
+  "id": "authors-page",
+  "slug": "authors",
+  "meta": {
+    "title": "Authors",
+    "description": "Author directory powered by the autori collection."
+  },
+  "sections": [
+    {
+      "id": "authors-list-1",
+      "type": "authors-list",
+      "data": {
+        "anchorId": "authors",
+        "eyebrow": "Collection demo",
+        "title": "Authors",
+        "description": "A collection-backed directory of authors referenced by books.",
+        "items": {
+          "$ref": "../collections/autori/autori.json"
+        }
+      }
+    }
+  ],
+  "global-header": false
+}
 END_OF_FILE_CONTENT
 mkdir -p "src/data/pages/authors/[authorId]"
 echo "Creating src/data/pages/authors/[authorId]/libri.json..."
@@ -3559,46 +3857,111 @@ cat << 'END_OF_FILE_CONTENT' > "src/data/pages/libri/[slug].json"
   "global-header": false
 }
 
+END_OF_FILE_CONTENT
+mkdir -p "src/data/pages/prodotti"
+echo "Creating src/data/pages/prodotti.json..."
+cat << 'END_OF_FILE_CONTENT' > "src/data/pages/prodotti.json"
+{
+  "id": "prodotti-page",
+  "slug": "prodotti",
+  "meta": {
+    "title": "Prodotti",
+    "description": "Catalogo proiettato da una sorgente esterna (demo @olonjs/sources)."
+  },
+  "sections": [
+    {
+      "id": "prodotti-list-1",
+      "type": "prodotti-list",
+      "data": {
+        "anchorId": "catalogo-prodotti",
+        "eyebrow": "Projected source demo",
+        "title": "Prodotti",
+        "description": "Catalogo letto da una sorgente esterna, validato con la sua Zod shape e proiettato nel contratto OlonJS.",
+        "items": {
+          "$ref": "../collections/catalogo/catalogo.json"
+        }
+      }
+    }
+  ],
+  "global-header": false
+}
+
+END_OF_FILE_CONTENT
+echo "Creating src/data/pages/prodotti/[slug].json..."
+cat << 'END_OF_FILE_CONTENT' > "src/data/pages/prodotti/[slug].json"
+{
+  "id": "prodotto-detail-page",
+  "slug": "prodotti/[slug]",
+  "meta": {
+    "title": "Dettaglio prodotto",
+    "description": "Pagina dinamica alimentata dalla sorgente esterna catalogo."
+  },
+  "sections": [
+    {
+      "id": "prodotto-detail-1",
+      "type": "prodotto-detail",
+      "data": {
+        "anchorId": "dettaglio-prodotto",
+        "item": {
+          "$ref": "collection:current"
+        },
+        "backLabel": "← Torna al catalogo"
+      }
+    }
+  ],
+  "collection": {
+    "source": "catalogo",
+    "paramKey": "slug"
+  },
+  "global-header": false
+}
+
 END_OF_FILE_CONTENT
 # SKIP: src/index.css is binary and cannot be embedded as text.
 mkdir -p "src/lib"
 echo "Creating src/lib/CollectionRegistry.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/CollectionRegistry.ts"
-import { AutoriCollectionSchema } from '@/collections/autori';
-import { LibriCollectionSchema } from '@/collections/libri';
-
-export const CollectionRegistry = {
-  autori: AutoriCollectionSchema,
-  libri: LibriCollectionSchema,
-} as const;
-
-export type CollectionType = keyof typeof CollectionRegistry;
+import { AutoriCollectionSchema } from '@/collections/autori';
+import { LibriCollectionSchema } from '@/collections/libri';
+import { ProdottiCollectionSchema } from '@/collections/prodotti';
+
+export const CollectionRegistry = {
+  autori: AutoriCollectionSchema,
+  libri: LibriCollectionSchema,
+  catalogo: ProdottiCollectionSchema,
+} as const;
+
+export type CollectionType = keyof typeof CollectionRegistry;
 
 END_OF_FILE_CONTENT
 echo "Creating src/lib/ComponentRegistry.tsx..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/ComponentRegistry.tsx"
-import type React from 'react';
-import type { SectionType } from '@/types';
-import type { SectionComponentPropsMap } from '@/types';
-import { AuthorsListView } from '@/components/authors-list';
-import { BookDetailView } from '@/components/book-detail';
-import { BooksListView } from '@/components/books-list';
-import { EmptyTenantView } from '@/components/empty-tenant';
-import { FooterView } from '@/components/footer';
-import { FormDemoView } from '@/components/form-demo';
-import { HeaderView } from '@/components/header';
-
-export const ComponentRegistry: {
-  [K in SectionType]: React.FC<SectionComponentPropsMap[K]>;
-} = {
-  'authors-list': AuthorsListView as React.FC<SectionComponentPropsMap['authors-list']>,
-  'book-detail': BookDetailView as React.FC<SectionComponentPropsMap['book-detail']>,
-  'books-list': BooksListView as React.FC<SectionComponentPropsMap['books-list']>,
-  'empty-tenant': EmptyTenantView as React.FC<SectionComponentPropsMap['empty-tenant']>,
-  footer: FooterView as React.FC<SectionComponentPropsMap['footer']>,
-  'form-demo': FormDemoView as React.FC<SectionComponentPropsMap['form-demo']>,
-  header: HeaderView as React.FC<SectionComponentPropsMap['header']>,
-};
+import type React from 'react';
+import type { SectionType } from '@/types';
+import type { SectionComponentPropsMap } from '@/types';
+import { AuthorsListView } from '@/components/authors-list';
+import { BookDetailView } from '@/components/book-detail';
+import { BooksListView } from '@/components/books-list';
+import { EmptyTenantView } from '@/components/empty-tenant';
+import { FooterView } from '@/components/footer';
+import { FormDemoView } from '@/components/form-demo';
+import { HeaderView } from '@/components/header';
+import { ProdottoDetailView } from '@/components/prodotto-detail';
+import { ProdottiListView } from '@/components/prodotti-list';
+
+export const ComponentRegistry: {
+  [K in SectionType]: React.FC<SectionComponentPropsMap[K]>;
+} = {
+  'authors-list': AuthorsListView as React.FC<SectionComponentPropsMap['authors-list']>,
+  'book-detail': BookDetailView as React.FC<SectionComponentPropsMap['book-detail']>,
+  'books-list': BooksListView as React.FC<SectionComponentPropsMap['books-list']>,
+  'empty-tenant': EmptyTenantView as React.FC<SectionComponentPropsMap['empty-tenant']>,
+  footer: FooterView as React.FC<SectionComponentPropsMap['footer']>,
+  'form-demo': FormDemoView as React.FC<SectionComponentPropsMap['form-demo']>,
+  header: HeaderView as React.FC<SectionComponentPropsMap['header']>,
+  'prodotti-list': ProdottiListView as React.FC<SectionComponentPropsMap['prodotti-list']>,
+  'prodotto-detail': ProdottoDetailView as React.FC<SectionComponentPropsMap['prodotto-detail']>,
+};
 
 END_OF_FILE_CONTENT
 echo "Creating src/lib/IconResolver.tsx..."
@@ -5152,13 +5515,57 @@ END_OF_FILE_CONTENT
 echo "Creating src/lib/loaders/loadPublicPageBundleForRequest.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/loaders/loadPublicPageBundleForRequest.ts"
 import type { PublicPageContentBundle } from '@olonjs/next/server';
+import { resolvePageMatchFromRegistry } from '@olonjs/core';
+import { collectCollectionSources, resolveCollectionSources } from '@olonjs/sources';
 import {
   buildServerApiCandidates,
   type ServerCloudBootSource,
 } from '@/lib/env/serverCloudPolicy';
+import { collectionSources } from '@/sources';
 import { loadLivePublicPageBundle } from './loadLivePublicPageBundle';
 import { loadLocalPublicPageBundle } from './loadLocalPublicPageBundle';
 
+/**
+ * Project external collection sources referenced by the requested slug's page
+ * (ADR-0018). Without this, page JSON endpoints would expose unresolved $refs.
+ */
+export async function withProjectedSources(
+  bundle: PublicPageContentBundle,
+  slug: string,
+  appRoot?: string,
+): Promise<PublicPageContentBundle> {
+  const match = resolvePageMatchFromRegistry(
+    bundle.pages as never,
+    slug
+  );
+  if (!match) return bundle;
+
+  const needed = collectCollectionSources(match.page).filter(
+    (name) => name in collectionSources
+  );
+  if (needed.length === 0) return bundle;
+
+  const resolved = await resolveCollectionSources({
+    sources: collectionSources as never,
+    needed,
+    params: match.params,
+  });
+
+  return {
+    ...bundle,
+    collections: {
+      ...(bundle.collections ?? {}),
+      ...(resolved.collections as NonNullable<PublicPageContentBundle['collections']>),
+    },
+    collectionSchemas: {
+      ...(bundle.collectionSchemas ?? {}),
+      ...(resolved.collectionSchemas as NonNullable<
+        PublicPageContentBundle['collectionSchemas']
+      >),
+    },
+  };
+}
+
 export type LoadPublicPageBundleForRequestInput = {
   bootSource: ServerCloudBootSource;
   slug: string;
@@ -5190,18 +5597,76 @@ export async function loadPublicPageBundleForRequest(
     if (!apiUrl || !apiKey) {
       throw new Error('Live public page JSON requires cloud API URL and key');
     }
-    return loadLivePublicPageBundle({
+    const liveBundle = await loadLivePublicPageBundle({
       slug: input.slug,
       apiBases: buildServerApiCandidates(apiUrl),
       apiKey,
       appRoot,
       fetchImpl: input.fetchImpl,
     });
+    return withProjectedSources(liveBundle, input.slug, appRoot);
   }
 
-  return loadLocalPublicPageBundle(appRoot);
+  const localBundle = await loadLocalPublicPageBundle(appRoot);
+  return withProjectedSources(localBundle, input.slug, appRoot);
 }
 
+END_OF_FILE_CONTENT
+echo "Creating src/lib/loaders/loadVisitorPageBundle.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/lib/loaders/loadVisitorPageBundle.ts"
+import type { JsonPagesConfig, PageConfig } from '@olonjs/core';
+import { collectCollectionSources, resolveCollectionSources } from '@olonjs/sources';
+import { CollectionRegistry } from '@/lib/CollectionRegistry';
+import { collectionSources } from '@/sources';
+import { getFileCollections } from './getFileCollections';
+
+export interface VisitorPageBundle {
+  collections: NonNullable<JsonPagesConfig['collections']>;
+  collectionSchemas: JsonPagesConfig['collectionSchemas'];
+  /** Provenance of the projected sources resolved for this route. */
+  sourceProvenance: Record<string, { fetchedAt: string; readOnly: boolean }>;
+}
+
+/**
+ * Load the per-route content bundle: file-backed collections plus the external
+ * sources this page needs (projected, validated, read-only).
+ *
+ * Sources are resolved ONLY when referenced by the page (ADR-0018 / spec
+ * external-collection-sources). Source names not registered as external
+ * sources are file-backed and skipped here.
+ */
+export async function loadVisitorPageBundle(input: {
+  page: PageConfig;
+  params: Record<string, string>;
+  appRoot?: string;
+}): Promise<VisitorPageBundle> {
+  const fileCollections = getFileCollections(input.appRoot) as NonNullable<
+    JsonPagesConfig['collections']
+  >;
+
+  const needed = collectCollectionSources(input.page).filter(
+    (name) => name in collectionSources
+  );
+
+  const resolved = await resolveCollectionSources({
+    sources: collectionSources as never,
+    needed,
+    params: input.params,
+  });
+
+  return {
+    collections: {
+      ...fileCollections,
+      ...(resolved.collections as NonNullable<JsonPagesConfig['collections']>),
+    },
+    collectionSchemas: {
+      ...(CollectionRegistry as JsonPagesConfig['collectionSchemas']),
+      ...(resolved.collectionSchemas as JsonPagesConfig['collectionSchemas']),
+    },
+    sourceProvenance: resolved.provenance,
+  };
+}
+
 END_OF_FILE_CONTENT
 echo "Creating src/lib/loaders/publishedContent.test.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/loaders/publishedContent.test.ts"
@@ -5347,45 +5812,49 @@ export function resolveVisitorShell(page: PageConfig, site: SiteConfig): Visitor
 END_OF_FILE_CONTENT
 echo "Creating src/lib/schemas.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/schemas.ts"
-import { AuthorsListSchema } from '@/components/authors-list';
-import { BookDetailSchema } from '@/components/book-detail';
-import { BooksListSchema } from '@/components/books-list';
-import { EmptyTenantSchema } from '@/components/empty-tenant';
-import { FooterSchema } from '@/components/footer';
-import { FormDemoSchema, FormDemoSubmissionSchema } from '@/components/form-demo';
-import { HeaderSchema } from '@/components/header';
-
-export const SECTION_SCHEMAS = {
-  'authors-list': AuthorsListSchema,
-  'book-detail': BookDetailSchema,
-  'books-list': BooksListSchema,
-  'empty-tenant': EmptyTenantSchema,
-  footer: FooterSchema,
-  'form-demo': FormDemoSchema,
-  header: HeaderSchema,
-} as const;
-
-/**
- * Registry of per-section-type submission schemas. Keys MUST match a key of
- * SECTION_SCHEMAS. A section type appearing here is declaring itself as
- * MCP-submittable: the Zod schema describes the payload accepted by the form.
- *
- * See ADR-0002 (docs/decisions/ADR-0002-form-submission-schemas.md).
- */
-export const SECTION_SUBMISSION_SCHEMAS = {
-  'form-demo': FormDemoSubmissionSchema,
-} as const;
-
-export type SectionType = keyof typeof SECTION_SCHEMAS;
-
-export {
-  BaseSectionData,
-  BaseArrayItem,
-  BaseCollectionItem,
-  BaseSectionSettingsSchema,
-  CtaSchema,
-  ImageSelectionSchema,
-} from '@olonjs/core';
+import { AuthorsListSchema } from '@/components/authors-list';
+import { BookDetailSchema } from '@/components/book-detail';
+import { BooksListSchema } from '@/components/books-list';
+import { EmptyTenantSchema } from '@/components/empty-tenant';
+import { FooterSchema } from '@/components/footer';
+import { FormDemoSchema, FormDemoSubmissionSchema } from '@/components/form-demo';
+import { HeaderSchema } from '@/components/header';
+import { ProdottoDetailSchema } from '@/components/prodotto-detail';
+import { ProdottiListSchema } from '@/components/prodotti-list';
+
+export const SECTION_SCHEMAS = {
+  'authors-list': AuthorsListSchema,
+  'book-detail': BookDetailSchema,
+  'books-list': BooksListSchema,
+  'empty-tenant': EmptyTenantSchema,
+  footer: FooterSchema,
+  'form-demo': FormDemoSchema,
+  header: HeaderSchema,
+  'prodotti-list': ProdottiListSchema,
+  'prodotto-detail': ProdottoDetailSchema,
+} as const;
+
+/**
+ * Registry of per-section-type submission schemas. Keys MUST match a key of
+ * SECTION_SCHEMAS. A section type appearing here is declaring itself as
+ * MCP-submittable: the Zod schema describes the payload accepted by the form.
+ *
+ * See ADR-0002 (docs/decisions/ADR-0002-form-submission-schemas.md).
+ */
+export const SECTION_SUBMISSION_SCHEMAS = {
+  'form-demo': FormDemoSubmissionSchema,
+} as const;
+
+export type SectionType = keyof typeof SECTION_SCHEMAS;
+
+export {
+  BaseSectionData,
+  BaseArrayItem,
+  BaseCollectionItem,
+  BaseSectionSettingsSchema,
+  CtaSchema,
+  ImageSelectionSchema,
+} from '@olonjs/core';
 
 END_OF_FILE_CONTENT
 echo "Creating src/lib/utils.ts..."
@@ -6037,55 +6506,194 @@ describe('visitor page WebMCP wiring', () => {
   });
 });
 
+END_OF_FILE_CONTENT
+mkdir -p "src/sources"
+echo "Creating src/sources/catalogo.test.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/sources/catalogo.test.ts"
+import { describe, expect, it } from 'vitest';
+import { runSourceConformance } from '@olonjs/sources';
+import { catalogoSource, fetchCatalogoFromExternalService } from './catalogo';
+
+describe('catalogo (demo external source)', () => {
+  it('passes the provider conformance suite', async () => {
+    await expect(runSourceConformance(catalogoSource)).resolves.toBeUndefined();
+  });
+
+  it('projects a deterministic document keyed by product id', async () => {
+    const document = await fetchCatalogoFromExternalService();
+
+    expect(Object.keys(document).sort()).toEqual([
+      '1984',
+      'dune',
+      'il-nome-della-rosa',
+      'neuromancer',
+    ]);
+    for (const [key, item] of Object.entries(document)) {
+      expect(item.id).toBe(key);
+    }
+  });
+
+  it('surfaces failures for fallback/breaker policy to consume', async () => {
+    await expect(fetchCatalogoFromExternalService({ fail: true })).rejects.toThrow(
+      /unavailable/
+    );
+  });
+});
+
+END_OF_FILE_CONTENT
+echo "Creating src/sources/catalogo.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/sources/catalogo.ts"
+import { z } from 'zod';
+import { defineCollectionSource, withCache } from '@olonjs/sources';
+import { ProdottoSchema, type Prodotto } from '@/collections/prodotti';
+
+/**
+ * Demo provider: a DETERMINISTIC, local stand-in for an external catalog
+ * service (no network — keeps dev, tests and CI hermetic). The real-world twin
+ * would be `src/sources/shopify.ts` implementing the same contract.
+ *
+ * The `shape` is the single declaration: it validates the projected document
+ * and feeds the agent contracts (`/schemas/collections/catalogo.schema.json`).
+ */
+
+const CATALOGO_FIXTURE: Record<string, Prodotto> = {
+  dune: {
+    id: 'dune',
+    title: 'Dune — Edizione illustrata',
+    price: 2490,
+    currency: 'EUR',
+    description: 'Arrakis, spezia e politica: il classico di Frank Herbert.',
+  },
+  '1984': {
+    id: '1984',
+    title: '1984',
+    price: 1490,
+    currency: 'EUR',
+    description: 'Il Grande Fratello e il controllo del linguaggio.',
+  },
+  neuromancer: {
+    id: 'neuromancer',
+    title: 'Neuromancer',
+    price: 1890,
+    currency: 'EUR',
+    description: 'Il romanzo che ha definito il cyberpunk.',
+  },
+  'il-nome-della-rosa': {
+    id: 'il-nome-della-rosa',
+    title: 'Il nome della rosa',
+    price: 2100,
+    currency: 'EUR',
+    description: 'Un giallo medievale tra biblioteche e potere.',
+  },
+};
+
+export interface ExternalCatalogServiceOptions {
+  /** Simulated latency in ms (default 0 — deterministic tests). */
+  latencyMs?: number;
+  /** Force a failure, to exercise fallback/breaker policy. */
+  fail?: boolean;
+  signal?: AbortSignal;
+}
+
+/** Stand-in for the external system of record (Shopify/PIM/…). */
+export async function fetchCatalogoFromExternalService(
+  options: ExternalCatalogServiceOptions = {}
+): Promise<Record<string, Prodotto>> {
+  const { latencyMs = 0, fail = false, signal } = options;
+
+  if (latencyMs > 0) {
+    await new Promise((resolve) => setTimeout(resolve, latencyMs));
+  }
+  if (signal?.aborted) throw new Error('The catalog request was aborted');
+  if (fail) throw new Error('External catalog service unavailable');
+
+  return JSON.parse(JSON.stringify(CATALOGO_FIXTURE)) as Record<string, Prodotto>;
+}
+
+export const catalogoSource = withCache(
+  defineCollectionSource({
+    shape: z.record(z.string(), ProdottoSchema),
+    resolve: async ({ signal }) => fetchCatalogoFromExternalService({ signal }),
+    readOnly: true,
+  }),
+  { ttlMs: 60_000, swrMs: 300_000 }
+);
+
+END_OF_FILE_CONTENT
+echo "Creating src/sources/index.ts..."
+cat << 'END_OF_FILE_CONTENT' > "src/sources/index.ts"
+import { catalogoSource } from './catalogo';
+
+/**
+ * Tenant source registry. Adding a provider is a one-line change here — no
+ * changes to @olonjs/core (ADR-0018). Sources not listed here are file-backed
+ * collections loaded from src/data/collections.
+ */
+export const collectionSources = {
+  catalogo: catalogoSource,
+} as const;
+
+export type CollectionSourceName = keyof typeof collectionSources;
+
 END_OF_FILE_CONTENT
 echo "Creating src/types.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/types.ts"
-import type { AuthorsListData, AuthorsListSettings } from '@/components/authors-list';
-import type { BookDetailData, BookDetailSettings } from '@/components/book-detail';
-import type { BooksListData, BooksListSettings } from '@/components/books-list';
-import type { EmptyTenantData, EmptyTenantSettings } from '@/components/empty-tenant';
-import type { FooterData, FooterSettings } from '@/components/footer';
-import type { FormDemoData, FormDemoSettings } from '@/components/form-demo';
-import type { HeaderData, HeaderSettings } from '@/components/header';
-import type { Autore } from '@/collections/autori';
-import type { Libro } from '@/collections/libri';
-
-export type SectionComponentPropsMap = {
-  'authors-list': { data: AuthorsListData; settings?: AuthorsListSettings };
-  'book-detail': { data: BookDetailData; settings?: BookDetailSettings };
-  'books-list': { data: BooksListData; settings?: BooksListSettings };
-  'empty-tenant': { data?: EmptyTenantData; settings?: EmptyTenantSettings };
-  footer: { data: FooterData; settings?: FooterSettings };
-  header: { data: HeaderData; settings?: HeaderSettings };
-  'form-demo': { data: FormDemoData; settings?: FormDemoSettings };
-};
-
-declare module '@olonjs/core' {
-  export interface SectionDataRegistry {
-    'authors-list': AuthorsListData;
-    'book-detail': BookDetailData;
-    'books-list': BooksListData;
-    'empty-tenant': EmptyTenantData;
-    footer: FooterData;
-    header: HeaderData;
-    'form-demo': FormDemoData;
-  }
-  export interface SectionSettingsRegistry {
-    'authors-list': AuthorsListSettings;
-    'book-detail': BookDetailSettings;
-    'books-list': BooksListSettings;
-    'empty-tenant': EmptyTenantSettings;
-    footer: FooterSettings;
-    header: HeaderSettings;
-    'form-demo': FormDemoSettings;
-  }
-  export interface CollectionItemRegistry {
-    autori: Autore;
-    libri: Libro;
-  }
-}
-
-export * from '@olonjs/core';
+import type { AuthorsListData, AuthorsListSettings } from '@/components/authors-list';
+import type { BookDetailData, BookDetailSettings } from '@/components/book-detail';
+import type { BooksListData, BooksListSettings } from '@/components/books-list';
+import type { EmptyTenantData, EmptyTenantSettings } from '@/components/empty-tenant';
+import type { FooterData, FooterSettings } from '@/components/footer';
+import type { FormDemoData, FormDemoSettings } from '@/components/form-demo';
+import type { HeaderData, HeaderSettings } from '@/components/header';
+import type { ProdottoDetailData, ProdottoDetailSettings } from '@/components/prodotto-detail';
+import type { ProdottiListData, ProdottiListSettings } from '@/components/prodotti-list';
+import type { Autore } from '@/collections/autori';
+import type { Libro } from '@/collections/libri';
+import type { Prodotto } from '@/collections/prodotti';
+
+export type SectionComponentPropsMap = {
+  'authors-list': { data: AuthorsListData; settings?: AuthorsListSettings };
+  'book-detail': { data: BookDetailData; settings?: BookDetailSettings };
+  'books-list': { data: BooksListData; settings?: BooksListSettings };
+  'empty-tenant': { data?: EmptyTenantData; settings?: EmptyTenantSettings };
+  footer: { data: FooterData; settings?: FooterSettings };
+  header: { data: HeaderData; settings?: HeaderSettings };
+  'form-demo': { data: FormDemoData; settings?: FormDemoSettings };
+  'prodotti-list': { data: ProdottiListData; settings?: ProdottiListSettings };
+  'prodotto-detail': { data: ProdottoDetailData; settings?: ProdottoDetailSettings };
+};
+
+declare module '@olonjs/core' {
+  export interface SectionDataRegistry {
+    'authors-list': AuthorsListData;
+    'book-detail': BookDetailData;
+    'books-list': BooksListData;
+    'empty-tenant': EmptyTenantData;
+    footer: FooterData;
+    header: HeaderData;
+    'form-demo': FormDemoData;
+    'prodotti-list': ProdottiListData;
+    'prodotto-detail': ProdottoDetailData;
+  }
+  export interface SectionSettingsRegistry {
+    'authors-list': AuthorsListSettings;
+    'book-detail': BookDetailSettings;
+    'books-list': BooksListSettings;
+    'empty-tenant': EmptyTenantSettings;
+    footer: FooterSettings;
+    header: HeaderSettings;
+    'form-demo': FormDemoSettings;
+    'prodotti-list': ProdottiListSettings;
+    'prodotto-detail': ProdottoDetailSettings;
+  }
+  export interface CollectionItemRegistry {
+    autori: Autore;
+    libri: Libro;
+    prodotti: Prodotto;
+  }
+}
+
+export * from '@olonjs/core';
 
 END_OF_FILE_CONTENT
 mkdir -p "templates"
@@ -7394,7 +8002,7 @@ export const ContactFormSchema = BaseSectionData.merge(WithFormRecipient).extend
 });
 export const ContactFormSubmissionSchema = z.object({
   name: z.string().min(1).describe('Full name'),
-  email: z.string().email().describe('Reply email'),
+  email: z.email().describe('Reply email'),
   message: z.string().min(1).describe('Message body'),
 });
 EOF
@@ -11368,6 +11976,8 @@ import type { TagPostsData, TagPostsSettings } from '@/components/tag-posts';
 import type { ContentBlockData, ContentBlockSettings } from '@/components/content-block';
 import type { StatsBandData, StatsBandSettings } from '@/components/stats-band';
 import type { CtaBannerData, CtaBannerSettings } from '@/components/cta-banner';
+import type { Post } from '@/collections/posts';
+import type { Tag } from '@/collections/tags';
 
 export type SectionComponentPropsMap = {
   'header': { data: HeaderData; settings: HeaderSettings };
@@ -11416,6 +12026,10 @@ declare module '@olonjs/core' {
     'stats-band': StatsBandSettings;
     'cta-banner': CtaBannerSettings;
   }
+  export interface CollectionItemRegistry {
+    posts: Post;
+    tags: Tag;
+  }
 }
 
 export * from '@olonjs/core';