feat(module): the bundle skeleton (phase 3, slice 0)

The first real module. It registers nothing, deliberately: what slice 0 proves
is the delivery path itself, end to end, before a single UO file moves into it.

Server half: module.json, an entry point that takes (ctx, api) and registers
nothing, a test suite built on a fake ctx, and scripts/checkImports.js -- the
MODULE_API.md §5.1 boundary check. Client half: the Vite library build, four
shims re-exporting react / react-dom/client / react-router-dom / jsx-runtime
from window.__rg, an entry that verifies each is identity-equal to core's copy,
and scripts/checkExternals.js. 29 server tests, 9 client tests, both new.

Verified against a real core: the module loads, mounts its zero routes, runs to
`started`, and is published by /api/v1/public/modules. Its chunk serves from
the entry's directory with `Cache-Control: no-cache` while the module's server
source, module.json and package.json all 404. In Chrome, under the enforced
`script-src 'self'`, the chunk evaluates and reports all four shared
dependencies OK, with zero CSP reports and no console errors.

Three findings, each of which had produced a green build that was wrong.

MODULE_API.md §3.6 shows `external` alongside the aliases and they do not
compose. Rollup asks `external` BEFORE Vite's alias resolver runs, so a
specifier in both is marked external and never aliased -- the chunk then ships
bare `import "react"`, which no browser can resolve without an import map, and
CSP forbids one. Built cleanly and emitted exactly that; checkExternals caught
it. So: alias only, `external` empty, and vite.config.js grows a resolution-time
guard that fails the build if a shared dependency resolves into node_modules.

That guard was wrong twice before it worked. Written against Rollup's `load`
hook it never ran -- `load` is first-wins and an earlier plugin had already
claimed the module -- so a deliberately-broken alias produced a 24 kB chunk with
react-router welded in, and a green build. And its forbidden-package list was
derived from the alias list "so the two cannot disagree", which meant deleting
an alias also deleted the guard against what that alias prevented. It states the
contract now, and a test asserts the aliases stay inside it.

checkImports failed on its own documentation the first time it ran: the comment
naming require("../../etc/passwd") as an example of what to catch, and index.js
explaining why the module must never require("express"). A boundary check that
cannot survive being described is one people stop writing comments around. It
strips comments and template literals with a character walk rather than a
regexp, because a URL in a string contains a comment opener and a comment
contains quotes -- and it has its own test suite, since a check never shown to
fail is a check nobody knows the state of.

Co-Authored-By: Claude <noreply@anthropic.com>

client/test/build.test.js

@@ -0,0 +1,106 @@
+// What can be checked about the client half without a browser.
+//
+// Not much, and being honest about that is the point: the client half's real
+// failures are timing and resolution, and neither has a shape a DOM-less test
+// runner can see. MODULE_API.md §7.7's four-step browser smoke is what actually
+// proves this half works, and it is re-run whenever this seam changes.
+//
+// What IS testable here is the configuration that decides resolution — and one
+// of these tests exists because the trap it guards cost the Phase 1 spike real
+// time: Vite's object-form `resolve.alias` does PREFIX matching, so a `react`
+// key silently also rewrites `react/jsx-runtime`. An anchored regexp in the
+// array form cannot. That is a property of the config, and a test can hold it.
+
+import test from 'node:test'
+import assert from 'node:assert'
+import fs from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const HERE = path.dirname(fileURLToPath(import.meta.url))
+const CLIENT = path.resolve(HERE, '..')
+
+const configModule = await import('../vite.config.js')
+const config = configModule.default
+const { SHARED, SHARED_PACKAGES: guardedPackages } = configModule
+
+test('every alias is an anchored regexp, never a bare prefix string', () => {
+  const aliases = config.resolve.alias
+  assert.ok(Array.isArray(aliases), 'alias must use the ARRAY form — the object form prefix-matches')
+  for (const { find } of aliases) {
+    assert.ok(find instanceof RegExp, `alias "${find}" is a string; a string prefix-matches`)
+    assert.ok(find.source.startsWith('^') && find.source.endsWith('$'), `alias ${find} is not anchored`)
+  }
+})
+
+test('react and react/jsx-runtime resolve to different shims', () => {
+  // The exact collision the object form causes. Asserted on the outcome rather
+  // than on the config's shape, so it keeps holding however the config is
+  // rewritten.
+  const resolve = (specifier) =>
+    config.resolve.alias.find(({ find }) => find.test(specifier))?.replacement
+  assert.ok(resolve('react'))
+  assert.ok(resolve('react/jsx-runtime'))
+  assert.notStrictEqual(resolve('react'), resolve('react/jsx-runtime'))
+})
+
+test('every shared dependency is aliased', () => {
+  for (const specifier of ['react', 'react/jsx-runtime', 'react-dom', 'react-dom/client', 'react-router-dom']) {
+    assert.ok(
+      config.resolve.alias.some(({ find }) => find.test(specifier)),
+      `${specifier} is not aliased — it would be bundled, giving the page a second copy`,
+    )
+  }
+})
+
+test('rollup external stays empty — it preempts the aliases rather than backing them up', () => {
+  // Rollup asks `external` BEFORE Vite's alias resolver runs, so a specifier
+  // listed in both is marked external and never aliased. The chunk then ships
+  // bare `import 'react'`, which no browser can resolve without an import map
+  // and CSP forbids one. §3.6 shows both; they do not compose.
+  assert.deepStrictEqual(config.build.rollupOptions.external, [])
+})
+
+test('the not-bundled guard covers every shared specifier and is not derived from them', () => {
+  // The direction of this dependency is the finding. Deriving the forbidden
+  // package list FROM the alias list means deleting an alias also deletes the
+  // guard against what that alias prevented — which is precisely when the guard
+  // is needed. So the guard states the contract, and this asserts the aliases
+  // stay inside it.
+  const packages = new Set(guardedPackages)
+  for (const { specifier } of SHARED) {
+    const pkg = specifier.startsWith('@') ? specifier.split('/').slice(0, 2).join('/') : specifier.split('/')[0]
+    assert.ok(packages.has(pkg), `${pkg} is aliased but not guarded against being bundled`)
+  }
+})
+
+test('every alias points at a shim file that exists', () => {
+  for (const { find, replacement } of config.resolve.alias) {
+    assert.ok(fs.existsSync(replacement), `alias ${find} points at a missing file: ${replacement}`)
+  }
+})
+
+test('the build emits one unhashed entry.js, which is what module.json names', () => {
+  assert.deepStrictEqual(config.build.lib.formats, ['es'])
+  assert.strictEqual(config.build.lib.fileName(), 'entry.js')
+  const manifest = JSON.parse(fs.readFileSync(path.resolve(CLIENT, '..', 'module.json'), 'utf8'))
+  assert.strictEqual(manifest.client.entry, 'client/dist/entry.js')
+  assert.strictEqual(config.build.outDir, 'dist')
+})
+
+test('modulePreload polyfilling stays off — an inline bootstrap is refused under CSP', () => {
+  assert.strictEqual(config.build.modulePreload.polyfill, false)
+})
+
+test('every shim reads from window.__rg and imports nothing', () => {
+  const dir = path.join(CLIENT, 'src', 'shim')
+  const shims = fs.readdirSync(dir)
+  assert.ok(shims.length >= 4)
+  for (const file of shims) {
+    const source = fs.readFileSync(path.join(dir, file), 'utf8')
+    assert.match(source, /window\.__rg/, `${file} does not read the global`)
+    // A shim that imported anything would be a shim with a dependency to
+    // resolve, which is the problem it exists to remove.
+    assert.doesNotMatch(source, /^\s*import\s/m, `${file} imports something`)
+  }
+})