@wildo-ai/saas-website 1.1.1

package/src/__tests__/bundle-isolation.test.ts

@@ -0,0 +1,607 @@
+/**
+ * @wildo_source:part:start engine.client-bundle.discipline facet:layer:engine facet:family:bundle-boundary
+ *
+ * Browser-bundle boundary for `@wildo-ai/saas-website`.
+ *
+ * The entire `saas-website` source tree ships into a browser bundle
+ * (Astro SSG + React islands). Anything that lands here transitively
+ * pulls into the marketing-site customer bundle. This test walks the
+ * source closure starting from each public package entry and asserts
+ * that every bare-specifier import is on a tightly-scoped allow-list,
+ * and that no forbidden specifier (decorator-framework boot, backend
+ * libs, Node-only deps) ever appears.
+ *
+ * Walked entries (current package.json `exports`):
+ *   - `./src/index.ts`            — root barrel (React + schemas)
+ *   - `./src/companion-exports.ts` — React-free companion entry
+ *   - `./src/astro.ts`            — Astro adapter SSR/frontmatter
+ *                                   sub-entry. Pulls
+ *                                   `node:fs` / `node:path` for the
+ *                                   label-pack loader. MUST NOT pull
+ *                                   the `astro` runtime itself (that
+ *                                   lives only inside `.astro` files,
+ *                                   which Astro's compiler processes
+ *                                   separately) AND MUST NOT pull the
+ *                                   bridge-runtime island module
+ *                                   (split into `./astro-island` to
+ *                                   keep the client graph free of
+ *                                   `node:*` specifiers — Vite's
+ *                                   resolver runs before
+ *                                   tree-shaking and would hard-fail
+ *                                   on `__vite-browser-external`
+ *                                   otherwise).
+ *   - `./src/astro-island.ts`     — Astro adapter CLIENT-bundle
+ *                                   sub-entry.
+ *                                   Exposes only
+ *                                   `createWebsitePageBridgeIsland`.
+ *                                   MUST stay 100% bundle-clean
+ *                                   (no `node:*`, no SSR-tier
+ *                                   specifiers) — the SSR-tier
+ *                                   negative test below asserts that.
+ *   - `./src/config-loader.ts`    — Node-only entry that loads the
+ *                                   per-service `wildo.website.config.ts`
+ *                                   via `loadConfig` from
+ *                                   `@wildo-ai/platform-config-lib`
+ *                                   (jiti-backed, transitively pulls
+ *                                   `node:fs` / `node:path` /
+ *                                   `node:crypto`). Walked here so the
+ *                                   SSR-tier negative test below
+ *                                   proves `@wildo-ai/platform-config-lib`
+ *                                   reaches the closure ONLY through
+ *                                   this entry — never through
+ *                                   `index.ts`, `companion-exports.ts`,
+ *                                   or `astro-island.ts`.
+ *
+ * `./mdx.ts` is the marketing-blog adapter subpath. It is included in
+ * `ENTRY_FILES` below and pulls `@mdx-js/react`. The provider lives in the
+ * React-island closure (consumed transitively
+ * from a consumer's per-post `.astro` page), so the SSR-tier negative
+ * test does NOT apply to `@mdx-js/react` — the specifier is
+ * unconditionally allowed across all entries.
+ *
+ * **Why `.astro` files are NOT in the walked closure**: this test
+ * walks `.ts` / `.tsx` only — the import-collection regex assumes
+ * TypeScript module syntax. `.astro` files have their own frontmatter
+ * grammar (Astro's compiler handles them), and they live on the
+ * Astro-build-time side of the boundary, not the React-island side.
+ * The TypeScript helpers the `.astro` shell calls into (everything
+ * exported from `astro.ts`) ARE walked — that's where the boundary
+ * actually matters.
+ *
+ * **Client-bundle import discipline**
+ *   The single allowed door into `@wildo-ai/saas-models` is the
+ *   side-effect-free `/public-runtime` subpath. The root barrel
+ *   calls `initZodDecorators()` at module load and pulls
+ *   `reflect-metadata` + the `@wildo-ai/external-connectors-models`
+ *   graph + the full schema tree — none of which belongs in a marketing
+ *   bundle.
+ *
+ *   Same forbid applies to the ROOT barrel of
+ *   `@wildo-ai/presets-components-models` (boots the full preset +
+ *   component-metadata graph). Its `/public-runtime` SUBPATH is
+ *   explicitly ALLOWED for callers that need locale-tier symbols
+ *   beyond what `@wildo-ai/saas-models/public-runtime` re-exports
+ *   New browser-facing atoms follow the same pattern: expose a narrow public
+ *   runtime export rather than duplicating a type or importing a heavy root
+ *   package.
+ *
+ *   `@wildo-ai/zod-decorators` is allowed.
+ *   Importing the package alone is side-effect-free — the prototype
+ *   mutation only happens when a caller explicitly invokes
+ *   `initZodDecorators()`, which neither saas-website nor the
+ *   saas-models /public-runtime barrel does. Allowing the import
+ *   leaves room for build-time decorator-metadata reads on schemas
+ *   imported from /public-runtime (e.g. `WildoZodDecorators.getMetadata(...)`
+ *   in a future Astro build-time generator) without forcing those
+ *   call sites to live outside the walked closure.
+ *
+ *   `axios`, `jsonwebtoken`, `socket.io-client`, and
+ *   `reflect-metadata` are now ALLOWED. The website engine needs
+ *   them for SERVER-SIDE Astro middleware code paths (request
+ *   proxying, JWT verification, real-time push) that do NOT ship
+ *   to the browser island bundle. Adding them collapses this test
+ *   from a "bundle-bloat guard" to a "stack-creep guard": it still
+ *   catches `mongoose`, `inversify`, `express`, `pino`, `helmet`,
+ *   `argon2`, `bcrypt`, the heavy package root barrels of
+ *   `@wildo-ai/saas-models` / `@wildo-ai/presets-components-models`,
+ *   and any non-`/public-runtime` subpath of those — i.e. it
+ *   prevents the saas-app/backend stack from creeping into the
+ *   marketing engine — but it no longer guarantees by itself that
+ *   the React island bundle stays under a hard size budget. That
+ *   guarantee now lives upstream of this file: developer discipline
+ *   to keep heavy SSR-only deps out of files reachable from React
+ *   component code. A stricter entry-specific browser-size check may be added
+ *   later; this contract already prevents backend and framework bootstrap
+ *   imports from entering the website closure.
+ *
+ * Related public-runtime boundary tests prove the subpath itself is free of
+ * decorator-framework bootstrap. This test proves the website consumes that
+ * safe seam correctly.
+ */
+/** @wildo_source:part:end engine.client-bundle.discipline */
+
+import { readFileSync, existsSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { describe, expect, it } from 'vitest';
+
+const SRC_ROOT = resolve(__dirname, '..');
+
+const ENTRY_FILES: ReadonlyArray<string> = [
+  resolve(SRC_ROOT, 'index.ts'),
+  resolve(SRC_ROOT, 'companion-exports.ts'),
+  resolve(SRC_ROOT, 'astro.ts'),
+  /**
+   * The `bridge-runtime.tsx` factory is a
+   * client-bundle module (it ships into Astro's React island bundle).
+   * It MUST stay clear of `node:fs` / `node:path` even though those
+   * specifiers are allowed for `astro.ts` (the SSR/frontmatter sibling).
+   * Walking `astro-island.ts` as its own entry forces the closure
+   * across this module too — and the targeted negative test below
+   * already asserts no SSR-only specifier is reachable from any
+   * non-`astro.ts` entry.
+   */
+  resolve(SRC_ROOT, 'astro-island.ts'),
+  /**
+   * Node-only `wildo.website.config.ts` loader entry.
+   * Pulls `loadConfig` + `AppFrontendType` from
+   * `@wildo-ai/platform-config-lib` (which transitively imports
+   * `node:fs` / `node:path` / `node:crypto` / jiti). Walking it here
+   * lets the SSR-tier negative test below assert that
+   * `@wildo-ai/platform-config-lib` does NOT leak into the
+   * React-island closures rooted at `index.ts` / `companion-exports.ts`
+   * / `astro-island.ts`.
+   */
+  resolve(SRC_ROOT, 'config-loader.ts'),
+  /**
+   * Phase 7 (saas-website-mdx-blog-adapter.md) — the MDX/blog adapter
+   * subpath. Ships into the React-island bundle (consumer-side
+   * `.astro` post pages import `<BlogPost>` and render it with a
+   * `client:load` directive). Walked here so the global allow-list
+   * test catches any `node:*` regression inside `BlogPost.tsx` /
+   * `website-mdx-provider.tsx` / `blog-post-collection.config.ts`.
+   * Also walked as part of `REACT_ISLAND_ENTRIES` below so the
+   * SSR-tier negative test asserts `node:fs` / `node:path` / the
+   * `@wildo-ai/platform-config-lib` loader do NOT leak into the MDX
+   * adapter closure.
+   */
+  resolve(SRC_ROOT, 'mdx.ts'),
+];
+
+/**
+ * Specifiers that MUST NOT appear anywhere in the saas-website source
+ * closure. Any of these landing here would either drag in the saas-app
+ * runtime stack (inversify DI graph, the saas-frontend/backend libs,
+ * `@wildo-ai/external-connectors-models`) or pull a Node-only server
+ * library that the marketing engine has no use case for.
+ *
+ * Removed from the original FORBIDDEN set on 2026-04-19 (D12 same-day
+ * second revision) — see this file's preamble:
+ *   - `axios` (server-side middleware HTTP client),
+ *   - `jsonwebtoken` (middleware-side JWT verify),
+ *   - `socket.io-client` (real-time push),
+ *   - `reflect-metadata` (decorator metadata runtime).
+ * They moved to `ALLOWED_BARE_SPECIFIERS` below.
+ *
+ * The four root barrels (`saas-models`, `presets-components-models`,
+ * `saas-frontend-lib`, `saas-backend-lib`) stay forbidden — the
+ * `/public-runtime` subpaths of the first two are the only allowed
+ * doors (see `FORBIDDEN_PATTERNS` + `ALLOWED_BARE_SPECIFIERS`).
+ */
+const FORBIDDEN_SPECIFIERS: ReadonlySet<string> = new Set([
+  '@wildo-ai/saas-models',
+  '@wildo-ai/presets-components-models',
+  '@wildo-ai/saas-frontend-lib',
+  '@wildo-ai/saas-backend-lib',
+  '@wildo-ai/external-connectors-models',
+  'inversify',
+  'mongoose',
+  'express',
+  'pino',
+  'helmet',
+  'argon2',
+  'bcrypt',
+]);
+
+/**
+ * Subpath patterns equivalent to importing into a forbidden tree.
+ * Block any `@wildo-ai/saas-models/<x>` other than `/public-runtime`,
+ * any `@wildo-ai/presets-components-models/<x>` other than
+ * `/public-runtime`, and any deep import into the saas-frontend-lib /
+ * saas-backend-lib subpath surface.
+ */
+const FORBIDDEN_PATTERNS: ReadonlyArray<RegExp> = [
+  /^@wildo-ai\/saas-models\/(?!public-runtime$).+/,
+  /^@wildo-ai\/presets-components-models\/(?!public-runtime$).+/,
+  /^@wildo-ai\/saas-frontend-lib\//,
+  /^@wildo-ai\/saas-backend-lib\//,
+  /^~wildo-frontend-lib\//,
+  /^~wildo-backend-lib\//,
+];
+
+/**
+ * @wildo_source:part:start engine.client-bundle.allow-list facet:layer:engine facet:family:bundle-boundary
+ *
+ * Bare-specifier allow-list. Adding a new entry must be a deliberate decision
+ * and meet the same browser-boundary acceptance criteria:
+ *   (a) browser-safe (no Node-only API surface)
+ *   (b) does NOT transitively pull `reflect-metadata`, the saas-models
+ *       root barrel, the presets-components-models root barrel, or any
+ *       backend lib.
+ *
+ * Add a dependency only when a real application-facing import needs it, with
+ * this rationale updated alongside the import.
+ */
+const ALLOWED_BARE_SPECIFIERS: ReadonlySet<string> = new Set([
+  'react',
+  'zod',
+  '@wildo-ai/saas-models/public-runtime',
+  /**
+   * Narrow public-runtime seam exposing
+   * `AvailableLanguage` / `TextDirection` (and any future locale-tier
+   * atom) without booting the heavy `@wildo-ai/presets-components-models`
+   * root barrel. Consumers should prefer the
+   * `@wildo-ai/saas-models/public-runtime` re-export path so they see
+   * one door, but importing the presets `/public-runtime` subpath
+   * directly is allowed for symbols that aren't (yet) re-exported by
+   * saas-models. The root barrel of `@wildo-ai/presets-components-models`
+   * stays in `FORBIDDEN_SPECIFIERS`.
+   */
+  '@wildo-ai/presets-components-models/public-runtime',
+  /**
+   * Decorator package itself — importing it does NOT mutate Zod
+   * prototype (only an explicit `initZodDecorators()` call does), so
+   * it is bundle-safe to allow. Use cases include build-time
+   * decorator-metadata reads on schemas imported from
+   * `@wildo-ai/saas-models/public-runtime`. The dangerous side-effect
+   * (the actual prototype mutation done by saas-models's root barrel)
+   * is still blocked because the saas-models ROOT barrel sits in
+   * `FORBIDDEN_SPECIFIERS`.
+   */
+  '@wildo-ai/zod-decorators',
+  /**
+   * SSR / Astro-middleware tier. These four specifiers support server-side code paths
+   * the marketing engine genuinely needs:
+   *   - `axios` — outbound HTTP from Astro middleware (proxy to
+   *     the SaaS backend, contact-form forwarding, webhook fan-out).
+   *   - `jsonwebtoken` — verify cross-frontend handoff JWTs in
+   *     middleware before letting a request reach a logged-in surface.
+   *   - `socket.io-client` — real-time push (e.g. live preview / status
+   *     events from the SaaS app to the marketing site).
+   *   - `reflect-metadata` — decorator metadata runtime; required
+   *     by any future build-time consumer of `@wildo-ai/zod-decorators`
+   *     metadata (the import IS side-effecting — it mutates
+   *     `globalThis.Reflect`; that side effect is acceptable in an
+   *     SSR context but would still be objectionable in a React
+   *     island bundle).
+   * Allowing them here is a deliberate trade-off: this test no
+   * longer guarantees a hard browser-bundle size budget on its own.
+   * Application import discipline keeps the React-island side lean.
+   */
+  'axios',
+  'jsonwebtoken',
+  'socket.io-client',
+  'reflect-metadata',
+  /**
+   * SSR / Astro-build-time tier. The
+   * `astro.ts` sub-entry exposes the label-pack loader, which
+   * reads `<locale>.json` files from disk inside Astro's frontmatter
+   * (synchronous I/O is intentional — see `label-pack-loader.ts`
+   * preamble). Allowing the three `node:*` builtins below keeps the
+   * loader inside the walked closure (so it gets bundle-rule
+   * coverage) without leaking Node-only API into the React island
+   * side: `bridge-runtime.tsx` does not import any of them, and the
+   * test would catch a regression.
+   *
+   * `node:fs`   — synchronous file reads in the label-pack loader.
+   * `node:path` — `resolve()` for the per-locale path composition.
+   *
+   * Other `node:*` builtins are not allowed; if a future MDX
+   * loader needs `node:url` or similar, add it here with the same
+   * rationale comment + an actual import that lands at the same time.
+   */
+  'node:fs',
+  'node:path',
+  /**
+   * `@wildo-ai/platform-config-lib` is the home of
+   * `loadConfig<T>(...)` (jiti-backed) and `AppFrontendType`. The
+   * Node-only `config-loader.ts` entry uses both to discover and
+   * load the per-service `wildo.website.config.ts`. Adding the
+   * specifier here covers the bare-import; pinning it as
+   * SSR-only below proves it cannot reach the React-island closure.
+   *
+   * The transitive graph (`jiti`, `node:crypto`, the saas-models
+   * decorator framework via `WildoSaasConfig` type imports) is
+   * irrelevant to bundle weight on the React-island side because
+   * the dedicated subpath separation (`@wildo-ai/saas-website/config-loader`
+   * vs `@wildo-ai/saas-website`) keeps the consumer-side imports
+   * tree-shake-trivial: a marketing page bundle never reaches into
+   * `./config-loader`.
+   */
+  '@wildo-ai/platform-config-lib',
+  /**
+   * `@mdx-js/react` ships the `MDXProvider` React component the
+   * `<WebsiteMdxProvider>` wraps. It is browser-safe (the package's
+   * own `package.json` declares `"browser": …` entries; no `node:*`
+   * surface), tree-shake-friendly (single named export consumed),
+   * and a declared peer dependency of the website package.
+   *
+   * Allowed UNCONDITIONALLY (not pinned as SSR-only) because the
+   * provider lives in the React-island bundle by design — it scopes
+   * the consumer-supplied `mdxComponents` map for the duration of a
+   * blog-post render, which only happens client-side once Astro has
+   * hydrated the per-post island.
+   */
+  '@mdx-js/react',
+]);
+/** @wildo_source:part:end engine.client-bundle.allow-list */
+
+interface ImportFinding {
+  readonly fromFile: string;
+  readonly specifier: string;
+}
+
+function stripComments(source: string): string {
+  return source
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:])\/\/[^\n]*/g, '$1');
+}
+
+function collectImports(filePath: string): ReadonlyArray<ImportFinding> {
+  const source = stripComments(readFileSync(filePath, 'utf-8'));
+  const findings: ImportFinding[] = [];
+  const importRegex = /(?:from|import)\s*['"]([^'"]+)['"]/g;
+  let match: RegExpExecArray | null;
+  while ((match = importRegex.exec(source)) !== null) {
+    const specifier = match[1];
+    if (specifier !== undefined) findings.push({ fromFile: filePath, specifier });
+  }
+  return findings;
+}
+
+function isRelative(specifier: string): boolean {
+  return specifier.startsWith('./') || specifier.startsWith('../');
+}
+
+function resolveRelativeImport(fromFile: string, specifier: string): string {
+  const baseDir = dirname(fromFile);
+  const candidates = [
+    resolve(baseDir, `${specifier}.ts`),
+    resolve(baseDir, `${specifier}.tsx`),
+    resolve(baseDir, specifier, 'index.ts'),
+    resolve(baseDir, specifier, 'index.tsx'),
+    resolve(baseDir, specifier),
+  ];
+  for (const candidate of candidates) {
+    if (existsSync(candidate)) return candidate;
+  }
+  throw new Error(
+    `[saas-website bundle-isolation] Could not resolve "${specifier}" from "${fromFile}". ` +
+      `Tried: ${candidates.join(', ')}`,
+  );
+}
+
+function walkClosure(entries: ReadonlyArray<string>): {
+  readonly visited: ReadonlySet<string>;
+  readonly findings: ReadonlyArray<ImportFinding>;
+} {
+  const visited = new Set<string>();
+  const findings: ImportFinding[] = [];
+
+  function visit(filePath: string): void {
+    if (visited.has(filePath)) return;
+    visited.add(filePath);
+
+    const fileFindings = collectImports(filePath);
+    for (const finding of fileFindings) {
+      findings.push(finding);
+      if (isRelative(finding.specifier)) {
+        const resolved = resolveRelativeImport(finding.fromFile, finding.specifier);
+        visit(resolved);
+      }
+    }
+  }
+
+  for (const entry of entries) {
+    visit(entry);
+  }
+  return { visited, findings };
+}
+
+/**
+ * Per-entry closures — used by the SSR-tier negative test below to
+ * assert `node:fs` / `node:path` reach `astro.ts` ONLY (never the
+ * React-island closures rooted at `index.ts` or `companion-exports.ts`).
+ *
+ * The global allow-list (`ALLOWED_BARE_SPECIFIERS`) admits these two
+ * `node:*` builtins for the WHOLE walked closure — necessary because
+ * the same allow-list governs every entry. That loosening means a
+ * future refactor that imports the label-pack loader from `index.ts`
+ * would silently bloat the React-island bundle with Node-only code
+ * AND still pass the global allow-list test. The negative test here
+ * closes that door without giving up the convenience of a single
+ * allow-list.
+ */
+const SSR_ONLY_BARE_SPECIFIERS: ReadonlySet<string> = new Set([
+  'node:fs',
+  'node:path',
+  /**
+   * Step 7.5 — `@wildo-ai/platform-config-lib` reaches the closure
+   * ONLY through the Node-only `config-loader.ts` entry. The negative
+   * test below verifies it does NOT leak into the React-island
+   * closures rooted at `index.ts` / `companion-exports.ts` /
+   * `astro-island.ts`. The matching positive test also asserts the
+   * specifier IS reachable from at least one SSR-tier entry — when
+   * the day comes that nothing imports it, drop it from both this
+   * set AND `ALLOWED_BARE_SPECIFIERS` so the allow-list stays
+   * minimal.
+   */
+  '@wildo-ai/platform-config-lib',
+]);
+const ASTRO_ENTRY = resolve(SRC_ROOT, 'astro.ts');
+const CONFIG_LOADER_ENTRY = resolve(SRC_ROOT, 'config-loader.ts');
+const REACT_ISLAND_ENTRIES: ReadonlyArray<string> = [
+  resolve(SRC_ROOT, 'index.ts'),
+  resolve(SRC_ROOT, 'companion-exports.ts'),
+  /**
+   * Phase 5/6 split — `astro-island.ts` is the dedicated
+   * client-bundle subpath that exposes
+   * `createWebsitePageBridgeIsland`. Treating it as a "react-island
+   * entry" here makes the negative test below assert that
+   * `node:fs` / `node:path` do NOT leak through this entry — the
+   * whole point of carving the subpath out of `astro.ts`.
+   */
+  resolve(SRC_ROOT, 'astro-island.ts'),
+  /**
+   * Phase 7 — `mdx.ts` is a React-island sub-entry (consumer-side
+   * blog post pages mount `<BlogPost>` with `client:load`). Walking
+   * it here forces the SSR-tier negative test to assert that
+   * `node:fs` / `node:path` / `@wildo-ai/platform-config-lib` do
+   * NOT leak through the MDX adapter — the whole point of keeping
+   * the MDX surface separate from the Astro frontmatter helpers.
+   */
+  resolve(SRC_ROOT, 'mdx.ts'),
+];
+
+describe('saas-website — bundle-isolation boundary (D12)', () => {
+  const { visited, findings } = walkClosure(ENTRY_FILES);
+
+  it('every declared entry file exists', () => {
+    for (const entry of ENTRY_FILES) {
+      expect(existsSync(entry), `Missing entry: ${entry}`).toBe(true);
+    }
+  });
+
+  it('the closure visits at least every entry file', () => {
+    for (const entry of ENTRY_FILES) {
+      expect(visited.has(entry), `Closure did not visit entry: ${entry}`).toBe(true);
+    }
+  });
+
+  it.each([...FORBIDDEN_SPECIFIERS])(
+    'no file in the saas-website closure imports the forbidden specifier "%s"',
+    (forbidden) => {
+      const offenders = findings.filter((f) => f.specifier === forbidden);
+      expect(offenders, JSON.stringify(offenders, null, 2)).toEqual([]);
+    },
+  );
+
+  it('no file in the saas-website closure imports a forbidden subpath pattern', () => {
+    const offenders = findings.filter((f) =>
+      FORBIDDEN_PATTERNS.some((pattern) => pattern.test(f.specifier)),
+    );
+    expect(offenders, JSON.stringify(offenders, null, 2)).toEqual([]);
+  });
+
+  it('every bare-specifier import in the saas-website closure is on the allow-list', () => {
+    const bare = findings.filter(
+      (f) => !isRelative(f.specifier) && !FORBIDDEN_SPECIFIERS.has(f.specifier),
+    );
+    const unexpected = bare.filter((f) => !ALLOWED_BARE_SPECIFIERS.has(f.specifier));
+    expect(
+      unexpected,
+      `Unexpected bare specifier(s) in the saas-website source closure. Either:
+  (a) restructure to keep the import inside saas-website (mirror the symbol
+      locally if it is a small atom — engine packages are intentionally
+      self-contained on the client-bundle side), or
+  (b) carve the symbol out via the K-2 protocol in
+      saas-models-public-runtime.md and import it from
+      @wildo-ai/saas-models/public-runtime, or
+  (c) add the specifier to ALLOWED_BARE_SPECIFIERS in this test — but only
+      after verifying it is browser-safe AND does not transitively pull
+      reflect-metadata, the saas-models root barrel, the
+      presets-components-models root barrel, or any backend lib.
+Offenders: ${JSON.stringify(unexpected, null, 2)}`,
+    ).toEqual([]);
+  });
+
+  it.each([...SSR_ONLY_BARE_SPECIFIERS])(
+    'SSR-tier specifier "%s" reaches the closure ONLY through astro.ts (not index.ts / companion-exports.ts)',
+    (ssrOnly) => {
+      const reactIslandClosure = walkClosure(REACT_ISLAND_ENTRIES);
+      const leakedFindings = reactIslandClosure.findings.filter(
+        (f) => f.specifier === ssrOnly,
+      );
+      expect(
+        leakedFindings,
+        `[saas-website bundle-isolation] SSR-tier specifier "${ssrOnly}" leaked into ` +
+          `the React-island closure (reachable from index.ts or companion-exports.ts). ` +
+          `This means a Node-only API surface is now in the marketing-site browser ` +
+          `bundle. Move the offending import behind the astro.ts subpath OR mirror ` +
+          `the symbol locally without the Node dep. Offenders: ${JSON.stringify(leakedFindings, null, 2)}`,
+      ).toEqual([]);
+
+      // SSR-tier specifiers may legitimately reach the closure
+      // through EITHER the astro.ts SSR/frontmatter entry OR the
+      // Node-only config-loader.ts entry (both are server-side by
+      // construction; neither ships into the React-island bundle).
+      // The positive check here just asserts the specifier is
+      // actually used somewhere in the SSR-tier closure — when no
+      // SSR-tier consumer remains, drop the specifier from
+      // `ALLOWED_BARE_SPECIFIERS` AND `SSR_ONLY_BARE_SPECIFIERS` so
+      // the allow-list stays minimal.
+      const ssrTierClosure = walkClosure([ASTRO_ENTRY, CONFIG_LOADER_ENTRY]);
+      const reachedFromSsrTier = ssrTierClosure.findings.some(
+        (f) => f.specifier === ssrOnly,
+      );
+      expect(
+        reachedFromSsrTier,
+        `[saas-website bundle-isolation] SSR-tier specifier "${ssrOnly}" is on the ` +
+          `allow-list but NOT reachable from any SSR-tier entry (astro.ts, ` +
+          `config-loader.ts). If the import is gone, drop it from ` +
+          `ALLOWED_BARE_SPECIFIERS (and from SSR_ONLY_BARE_SPECIFIERS) so the ` +
+          `allow-list stays minimal.`,
+      ).toBe(true);
+    },
+  );
+
+  /**
+   * `@mdx-js/react` is a declared OPTIONAL peer — only sites that opt into
+   * the blog adapter install it. Vite resolves every `export *` graph
+   * BEFORE tree-shaking, so the moment any non-`mdx.ts` entry can reach
+   * the specifier, every landing-page-only consumer's build fails on the
+   * unresolved optional peer ("MDXProvider is not exported by
+   * __vite-optional-peer-dep:…"). This shipped once: `astro-island.ts`
+   * re-exported `./astro/blog-post-bridge` (which imports `../mdx/BlogPost`
+   * → `@mdx-js/react`) for one-subpath consumer convenience, and the first
+   * blog-less consumer could not build at all. The bridge now exports from
+   * `mdx.ts` — the entry whose consumers install the peer by definition.
+   */
+  it('the OPTIONAL blog peer "@mdx-js/react" reaches the closure ONLY through mdx.ts', () => {
+    const mdxEntry = resolve(SRC_ROOT, 'mdx.ts');
+    const nonBlogClosure = walkClosure(ENTRY_FILES.filter((entry) => entry !== mdxEntry));
+    const leaked = nonBlogClosure.findings.filter((f) => f.specifier === '@mdx-js/react');
+    expect(
+      leaked,
+      `[saas-website bundle-isolation] "@mdx-js/react" (an OPTIONAL peer) is reachable ` +
+        `from a non-mdx entry — every consumer of that entry now has to install the ` +
+        `peer or its build fails on the unresolved specifier. Move the offending ` +
+        `export behind the mdx.ts entry. Offenders: ${JSON.stringify(leaked, null, 2)}`,
+    ).toEqual([]);
+
+    // Positive half: the specifier must still be reachable from mdx.ts —
+    // a walker that reaches it from nowhere would pass the negative half
+    // while proving nothing (negative results require a positive probe).
+    const blogClosure = walkClosure([mdxEntry]);
+    expect(
+      blogClosure.findings.some((f) => f.specifier === '@mdx-js/react'),
+      '[saas-website bundle-isolation] "@mdx-js/react" is no longer reachable from ' +
+        'mdx.ts either — if the MDX adapter dropped the dependency, remove it from ' +
+        'ALLOWED_BARE_SPECIFIERS and delete this pin.',
+    ).toBe(true);
+  });
+
+  it('the public-runtime subpath is the ONLY door into saas-models', () => {
+    const saasModelsImports = findings.filter((f) =>
+      f.specifier.startsWith('@wildo-ai/saas-models'),
+    );
+    const wrongDoor = saasModelsImports.filter(
+      (f) => f.specifier !== '@wildo-ai/saas-models/public-runtime',
+    );
+    expect(
+      wrongDoor,
+      `Found ${wrongDoor.length} saas-models import(s) that bypass /public-runtime. ` +
+        `Repoint to '@wildo-ai/saas-models/public-runtime'. ` +
+        `Offenders: ${JSON.stringify(wrongDoor, null, 2)}`,
+    ).toEqual([]);
+  });
+});