feat: let one module contribute a browser renderer to another's capability

The platform has had a complete story for one module using another's
*backend* since ADR 0006 — capabilities, versioned ranges, provider
registration. It has had none at all for one module using another's *browser*
code, and every workaround is wrong in a way that matters: a consumer cannot
import a peer module, it cannot re-implement a renderer for a domain it does
not own, and a second `entrypoints` role would put the platform in charge of
deciding when a slot inside someone else's screen should be filled.

Add a generic browser contribution. `manifestVersion: 7` declares one:
namespaced id, its own version, a target capability, a compatible range, and
one artifact. That is the complete list, and the omissions are the decision —
no payload schema, slot, ordering, or rendering hint exists anywhere, so Core
cannot learn what a slide is because the declaration cannot express it.

Discovery resolves a contribution artifact through the *identical* loop every
other compiled entrypoint uses, inheriting the path, containment, symlink,
extension, and file-kind checks rather than getting a weaker copy of them. The
registry publishes one only when another eligible module provides the target
capability within the declared range; otherwise it is absent rather than
mounted and broken. `apps/api` serves it as a sibling of the artifact and
display routes, with the same policy: three lookup keys, one exact match, one
already-validated path, and one indistinguishable 404 for unknown, undeclared,
stale, and incompatible alike.

A consumer discovers through the host, never through a URL. Its descriptor
carries identity, version, and capability; the URL stays server-side and is
resolved exactly as `api.request("records")` is. A module can only ever see
contributions aimed at a capability it itself provides, and cannot name its
way to anything else — a mount for a withheld id fails without fetching.

The consumer owns the domain contract entirely. Input is opaque JSON, checked
structurally so a Date, a function, a cycle, or `undefined` fails at the
boundary rather than vanishing somewhere far from the mistake, and checked for
nothing else. A contributed renderer receives its own id and that input: no
API client, realtime, principal, configuration, database, storage, or
credential. Loading one grants its module nothing.

The contribution ABI is versioned separately from the module UI ABI, because
the two have different shapes and lifecycles and coupling them would force
every module to rebuild whenever either moved. It supports asynchronous
readiness, update-without-remount (a screen that remounted per tick would
restart animations and reload media), deterministic cleanup in a `finally`,
and sanitized failure that never carries the consumer's domain data. Each
renderer mounts in its own isolated root with its own stylesheet.

The template now declares a contribution, so `pnpm build` exercises the whole
authoring path, and the shell suite drives the full relationship — one module
discovering, mounting, updating, and unmounting another's React renderer with
neither importing the other.

Co-Authored-By: Claude Opus 5 <[email protected]>

core/src/modules/discovery.ts

@@ -57,6 +57,19 @@ export interface ModuleDiscoveryIssue {
   readonly path?: string;
 }
 
+/**
+ * One declared browser contribution, with its artifact resolved and validated exactly like every
+ * other compiled entrypoint (ADR 0041). Discovery never imports or evaluates it, and never learns
+ * what it renders.
+ */
+export interface ResolvedModuleContribution {
+  readonly id: string;
+  readonly version: string;
+  readonly capability: string;
+  readonly capabilityRange: string;
+  readonly artifactPath: string;
+}
+
 export interface ResolvedModuleEntrypoints {
   readonly server: string;
   readonly schema?: string;
@@ -92,6 +105,9 @@ export type ReadonlyModuleManifest = DeepReadonly<ModuleManifest>;
 
 export interface DiscoveredModule {
   readonly directory: string;
+  /** Declared browser contributions, in manifest order, each resolved to a canonical artifact path
+   * inside this module package. Empty for a module that contributes nothing. */
+  readonly contributions: readonly ResolvedModuleContribution[];
   readonly entrypoints: ResolvedModuleEntrypoints;
   readonly manifest: ReadonlyModuleManifest;
   readonly manifestPath: string;
@@ -110,6 +126,7 @@ interface ModulePackageData {
 }
 
 interface ModuleCandidate {
+  contributions: readonly ResolvedModuleContribution[];
   directory: string;
   directoryName: string;
   entrypoints: ResolvedModuleEntrypoints;
@@ -257,13 +274,19 @@ function validatePackageData(
   return { name, version };
 }
 
+interface ResolvedModuleArtifacts {
+  readonly contributions: readonly ResolvedModuleContribution[];
+  readonly entrypoints: ResolvedModuleEntrypoints;
+}
+
 async function resolveEntrypoints(
   moduleDirectory: string,
   directoryName: string,
   manifest: ModuleManifest,
   issues: ModuleDiscoveryIssue[],
-): Promise<ResolvedModuleEntrypoints | undefined> {
+): Promise<ResolvedModuleArtifacts | undefined> {
   const resolved: Partial<Record<keyof ModuleManifest["entrypoints"], string>> = {};
+  const resolvedContributions = new Map<string, string>();
   const canonicalModuleDirectory = await realpath(moduleDirectory);
   const { display, ...ordinaryEntrypoints } = manifest.entrypoints;
   const ordinaryConfiguredEntrypoints = Object.entries(ordinaryEntrypoints)
@@ -273,6 +296,15 @@ async function resolveEntrypoints(
       issuePath: `entrypoints.${entrypointName}`,
       relativeEntrypoint,
     }));
+  // A contribution artifact is resolved through the identical loop as every other compiled
+  // entrypoint, deliberately: the path, symlink, containment, extension, and file-kind protections
+  // are one implementation, so a contribution can never quietly receive weaker checks than
+  // `entrypoints.ui` (ADR 0041).
+  const configuredContributions = manifest.contributions.map((contribution, index) => ({
+    entrypointName: `contribution:${contribution.id}`,
+    issuePath: `contributions.${index}.artifact`,
+    relativeEntrypoint: contribution.artifact,
+  }));
   const configuredEntrypoints = [
     ...ordinaryConfiguredEntrypoints,
     ...(display === undefined
@@ -284,6 +316,7 @@ async function resolveEntrypoints(
             relativeEntrypoint: display.artifact,
           },
         ]),
+    ...configuredContributions,
   ];
   let entrypointCollision = false;
 
@@ -361,7 +394,14 @@ async function resolveEntrypoints(
         });
         continue;
       }
-      resolved[entrypointName as keyof ModuleManifest["entrypoints"]] = canonicalEntrypoint;
+      if (entrypointName.startsWith("contribution:")) {
+        resolvedContributions.set(
+          entrypointName.slice("contribution:".length),
+          canonicalEntrypoint,
+        );
+      } else {
+        resolved[entrypointName as keyof ModuleManifest["entrypoints"]] = canonicalEntrypoint;
+      }
     } catch (error) {
       const code = errorCode(error);
       issues.push({
@@ -394,11 +434,46 @@ async function resolveEntrypoints(
     }
   }
 
-  if (!resolved.server || entrypointCollision) {
+  // A contribution artifact must be its own file. Two declarations resolving to one path — through
+  // a link, since the manifest already rejects two identical declared paths — would make one
+  // contribution silently serve another's bytes, and the loader's identity check would then reject
+  // whichever one lost.
+  const canonicalContributionPaths = new Map<string, string>();
+  for (const [contributionId, canonicalPath] of resolvedContributions) {
+    const claimedBy = canonicalContributionPaths.get(canonicalPath);
+    if (claimedBy !== undefined || Object.values(resolved).includes(canonicalPath)) {
+      entrypointCollision = true;
+      issues.push({
+        code: "MODULE_ENTRYPOINT_INVALID",
+        message: `contribution ${contributionId} must not resolve to the same file as ${claimedBy ?? "another entrypoint"}.`,
+        moduleDirectory: directoryName,
+        moduleId: manifest.id,
+        path: "contributions",
+      });
+      continue;
+    }
+    canonicalContributionPaths.set(canonicalPath, contributionId);
+  }
+
+  if (
+    !resolved.server ||
+    entrypointCollision ||
+    resolvedContributions.size !== manifest.contributions.length
+  ) {
     return undefined;
   }
 
-  return {
+  const contributions = manifest.contributions.map((contribution) =>
+    Object.freeze({
+      artifactPath: resolvedContributions.get(contribution.id) as string,
+      capability: contribution.capability,
+      capabilityRange: contribution.capabilityRange,
+      id: contribution.id,
+      version: contribution.version,
+    }),
+  );
+
+  const entrypoints: ResolvedModuleEntrypoints = {
     server: resolved.server,
     ...(resolved.schema ? { schema: resolved.schema } : {}),
     ...(resolved.migrations ? { migrations: resolved.migrations } : {}),
@@ -413,6 +488,8 @@ async function resolveEntrypoints(
         }
       : {}),
   };
+
+  return { contributions: Object.freeze(contributions), entrypoints };
 }
 
 async function scanModuleDirectory(
@@ -510,15 +587,16 @@ async function scanModuleDirectory(
     });
   }
 
-  const entrypoints = await resolveEntrypoints(moduleDirectory, directoryName, manifest, issues);
-  if (!entrypoints) {
+  const artifacts = await resolveEntrypoints(moduleDirectory, directoryName, manifest, issues);
+  if (!artifacts) {
     return undefined;
   }
 
   return {
+    contributions: artifacts.contributions,
     directory: canonicalModuleDirectory,
     directoryName,
-    entrypoints,
+    entrypoints: artifacts.entrypoints,
     manifest,
     manifestPath: canonicalManifestPath,
     packageName: packageData.name,