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]>

packages/contracts/src/index.ts

@@ -2,6 +2,7 @@ export * from "./authorization.js";
 export * from "./identifiers.js";
 export * from "./identity.js";
 export * from "./module-configuration.js";
+export * from "./module-contribution.js";
 export * from "./module-database.js";
 export * from "./module-http.js";
 export * from "./module-lifecycle.js";

packages/contracts/src/module-contribution.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { capabilityIdSchema, packageRelativePathSchema } from "./identifiers.js";
+import { semanticVersionRangeSchema, semanticVersionSchema } from "./versions.js";
+
+/**
+ * A **browser contribution**: one module's compiled renderer, declared for a capability another
+ * module provides, and mounted by that other module inside a container it owns (ADR 0041).
+ *
+ * This is deliberately not a third UI role. `entrypoints.ui` and `entrypoints.display` are artifacts
+ * *the platform* mounts, in surfaces the platform owns. A contribution is mounted by a **consumer
+ * module**, at a moment and in a place only that module understands — a slot in its own layout —
+ * and the platform never renders one on its own.
+ *
+ * ## What the platform knows, and the complete list of it
+ *
+ * Identity, version, target capability, compatible range, and one compiled artifact. That is all,
+ * and the omissions are the point: nothing here says what the renderer draws, what shape its input
+ * has, when it should be mounted, or what any of it means. Core could not learn what a "slide" or a
+ * "timeline slot" is from this declaration, because the declaration cannot express it — the
+ * domain contract belongs entirely to the consumer's own versioned input.
+ *
+ * Inert, like every other manifest declaration: reading one causes no import, no evaluation, and no
+ * network or database access.
+ */
+
+/** `<module-id>.<local-name>` — exactly two segments. The prefix is checked against the declaring
+ * module in `moduleManifestSchema`, which is what makes a contribution id globally unique without a
+ * registry: module ids are already unique, so two modules cannot produce the same contribution id. */
+export const contributionIdSchema = z
+  .string()
+  .min(3)
+  .max(160)
+  .regex(
+    /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*\.[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/u,
+    "Must be <module-id>.<local-name>, both lowercase kebab-case.",
+  );
+
+export const moduleContributionDeclarationSchema = z
+  .object({
+    id: contributionIdSchema,
+    /** This contribution's own version, independent of the module's. A consumer sees it and a host
+     * verifies the artifact claims it, so a stale bundle is caught exactly as it is for a module
+     * UI artifact. */
+    version: semanticVersionSchema,
+    /** The capability this renderer plugs into — owned by whichever module provides it, never by
+     * the contributing module. */
+    capability: capabilityIdSchema,
+    /** The provider capability versions this renderer is compatible with. A provider outside this
+     * range makes the contribution unpublishable rather than mounted and broken. */
+    capabilityRange: semanticVersionRangeSchema,
+    /** The compiled browser artifact, resolved and validated during discovery exactly like every
+     * other declared entrypoint: package-relative, inside the package before and after symlink
+     * resolution, and a real `.js`/`.mjs` file. */
+    artifact: packageRelativePathSchema,
+    description: z.string().trim().min(1).max(240).optional(),
+  })
+  .strict();
+
+export type ModuleContributionDeclaration = z.output<typeof moduleContributionDeclarationSchema>;
+
+/** The local segment of a contribution id — the part after the declaring module's own id. Used by
+ * the canonical builder to locate the fixed source directory, so a module author configures no
+ * paths and cannot point the build somewhere else. */
+export function contributionLocalName(contributionId: string): string {
+  return contributionId.slice(contributionId.indexOf(".") + 1);
+}

packages/contracts/src/module-manifest.ts

@@ -11,6 +11,10 @@ import {
   type ModuleConfigurationDeclaration,
   moduleConfigurationDeclarationSchema,
 } from "./module-configuration.js";
+import {
+  type ModuleContributionDeclaration,
+  moduleContributionDeclarationSchema,
+} from "./module-contribution.js";
 import { semanticVersionRangeSchema, semanticVersionSchema } from "./versions.js";
 
 const moduleVersionMapSchema = z.record(moduleIdSchema, semanticVersionRangeSchema);
@@ -118,9 +122,9 @@ function reportDuplicates(
 }
 
 /**
- * The one manifest shape Core accepts. Version 5's strict `entrypoints` object rejects `display`, so
- * the static display declaration is an incompatible shape change and the canonical manifest moves
- * to `manifestVersion: 6` rather than silently reinterpreting version 5.
+ * The one manifest shape Core accepts. Version 6's strict top-level object rejects `contributions`,
+ * so the static browser-contribution declaration is an incompatible shape change and the canonical
+ * manifest moves to `manifestVersion: 7` rather than silently reinterpreting version 6.
  *
  * Configuration is declared **statically, in this inert document**, rather than registered by
  * executable module code, for one decisive reason: the platform validates a module's configuration
@@ -129,13 +133,14 @@ function reportDuplicates(
  * inside its own `start` hook. Discovery, `pnpm modules:validate`, and Doctor all read this without
  * importing a single line of module code, exactly as they always have.
  *
- * Version 5, and every other version, fails validation: there is no compatibility adapter, no
+ * Version 6, and every other version, fails validation: there is no compatibility adapter, no
  * automatic conversion, and no dual acceptance, exactly as version 1 was rejected by version 2
- * (ADR 0006), version 2 by version 3 (ADR 0014), and version 3 by version 4 (ADR 0021). One
- * manifest document can therefore never be read as two different versions. Upgrading a version 5
- * manifest is a one-character edit for a module that declares no display: the new field is optional.
+ * (ADR 0006), version 2 by version 3 (ADR 0014), version 3 by version 4 (ADR 0021), and version 5
+ * by version 6 (ADR 0033). One manifest document can therefore never be read as two different
+ * versions. Upgrading a version 6 manifest is a one-character edit for a module that contributes
+ * nothing: the new field defaults to empty.
  */
-export const MODULE_MANIFEST_VERSION = 6;
+export const MODULE_MANIFEST_VERSION = 7;
 
 export const moduleManifestSchema = z
   .object({
@@ -158,6 +163,10 @@ export const moduleManifestSchema = z
      * module code during discovery. A module that needs nothing configured omits the field. */
     configuration: z.array(moduleConfigurationDeclarationSchema).default(() => []),
     storage: moduleStorageSchema,
+    /** Compiled browser renderers this module offers to capabilities **other** modules provide
+     * (ADR 0041). Inert data: Core validates identity, compatibility, and the artifact path, and
+     * never learns what a contribution renders. A module that contributes nothing omits the field. */
+    contributions: z.array(moduleContributionDeclarationSchema).default(() => []),
     entrypoints: entrypointsSchema,
   })
   .strict()
@@ -200,6 +209,58 @@ export const moduleManifestSchema = z
       }
     });
 
+    reportDuplicates(
+      manifest.contributions.map((contribution) => contribution.id),
+      ["contributions"],
+      context,
+      "id",
+    );
+
+    const ownedCapabilityIds = new Set(manifest.capabilities.map((capability) => capability.id));
+    const contributionArtifacts = new Set<string>();
+    manifest.contributions.forEach((contribution, index) => {
+      // Namespacing is what makes a contribution id globally unique without a registry: module ids
+      // are already unique, so two modules can never produce the same contribution id.
+      if (!contribution.id.startsWith(`${manifest.id}.`)) {
+        context.addIssue({
+          code: "custom",
+          message: `Contribution identifiers owned by this module must begin with ${manifest.id}.`,
+          path: ["contributions", index, "id"],
+        });
+      }
+      // A contribution extends *another* module's capability. Targeting one this module already
+      // provides would be a module contributing to itself, which needs no platform mechanism at all
+      // and would make the compatibility check meaningless.
+      if (ownedCapabilityIds.has(contribution.capability)) {
+        context.addIssue({
+          code: "custom",
+          message: "A browser contribution must target a capability another module provides.",
+          path: ["contributions", index, "capability"],
+        });
+      }
+      if (
+        Object.entries(manifest.entrypoints).some(([entrypointName, configured]) =>
+          entrypointName === "display"
+            ? (configured as { artifact?: string } | undefined)?.artifact === contribution.artifact
+            : configured === contribution.artifact,
+        )
+      ) {
+        context.addIssue({
+          code: "custom",
+          message: "A contribution artifact must use a different path from every entrypoint.",
+          path: ["contributions", index, "artifact"],
+        });
+      }
+      if (contributionArtifacts.has(contribution.artifact)) {
+        context.addIssue({
+          code: "custom",
+          message: "Two contributions must not declare the same artifact path.",
+          path: ["contributions", index, "artifact"],
+        });
+      }
+      contributionArtifacts.add(contribution.artifact);
+    });
+
     manifest.permissions.forEach((permission, index) => {
       if (!permission.id.startsWith(`${manifest.id}.`)) {
         context.addIssue({
@@ -263,10 +324,9 @@ export const moduleManifestSchema = z
       }
     }
 
-    const ownedCapabilities = new Set(manifest.capabilities.map((capability) => capability.id));
     for (const dependencyKind of ["required", "optional"] as const) {
       for (const capability of Object.keys(manifest.dependencies.capabilities[dependencyKind])) {
-        if (ownedCapabilities.has(capability)) {
+        if (ownedCapabilityIds.has(capability)) {
           context.addIssue({
             code: "custom",
             message: "A module does not need to depend on a capability it owns.",
@@ -297,6 +357,9 @@ export function safeParseModuleManifest(input: unknown) {
 export type ModuleManifestInput = z.input<typeof moduleManifestSchema>;
 export type ModuleManifest = z.output<typeof moduleManifestSchema>;
 export type ModuleBucketDeclaration = z.output<typeof moduleBucketDeclarationSchema>;
+/** A module manifest's `contributions` array entry — the same `ModuleContributionDeclaration` shape
+ * Core's publication registry consumes (`packages/contracts/src/module-contribution.ts`). */
+export type ModuleManifestContributionDeclaration = ModuleContributionDeclaration;
 export type ModuleDisplayEntrypoint = z.output<typeof moduleDisplayEntrypointSchema>;
 /** A module manifest's `configuration` array entry — the same `ModuleConfigurationDeclaration` shape
  * Core's configuration resolver consumes (`packages/contracts/src/module-configuration.ts`), aliased