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]>
2026-08-27 07:47:10 -05:00
parent 07835b7b56
commit c444ff570b
79 changed files with 3317 additions and 137 deletions
@@ -34,7 +34,7 @@ async function createModulesDirectory(): Promise<string> {

 function manifestFor(id: string): Record<string, unknown> {
  return {
-    manifestVersion: 6,
+    manifestVersion: 7,
    id,
    name: `${id} module`,
    version: "0.1.0",
@@ -957,3 +957,179 @@ describe("module discovery", () => {
    });
  });
 });
+
+/**
+ * A contribution artifact is resolved through the identical loop as every other compiled entrypoint
+ * (ADR 0041), so it inherits every protection `entrypoints.ui` already had rather than receiving a
+ * second, weaker implementation of them.
+ */
+describe("browser contribution artifact resolution", () => {
+  function contributingManifest(overrides: Record<string, unknown> = {}): Record<string, unknown> {
+    return {
+      ...manifestFor("announcements"),
+      contributions: [
+        {
+          id: "announcements.signage-slide",
+          version: "1.0.0",
+          capability: "signage.slide-renderer",
+          capabilityRange: "^1.0.0",
+          artifact: "./dist/contributions/signage-slide/index.js",
+          ...overrides,
+        },
+      ],
+    };
+  }
+
+  it("resolves a declared contribution to a canonical path inside the package", async () => {
+    const modulesDirectory = await createModulesDirectory();
+    await createModule(modulesDirectory, "announcements", {
+      extraFiles: { "dist/contributions/signage-slide/index.js": "export default {};" },
+      manifest: contributingManifest(),
+    });
+
+    const modules = await discoverModules({
+      moduleSdkVersion: "0.1.0",
+      modulesDirectory,
+      platformVersion: "0.1.0",
+    });
+
+    const contribution = modules[0]?.contributions[0];
+    expect(contribution).toMatchObject({
+      capability: "signage.slide-renderer",
+      capabilityRange: "^1.0.0",
+      id: "announcements.signage-slide",
+      version: "1.0.0",
+    });
+    expect(contribution?.artifactPath.endsWith("dist/contributions/signage-slide/index.js")).toBe(
+      true,
+    );
+    expect(path.isAbsolute(contribution?.artifactPath ?? "")).toBe(true);
+  });
+
+  it("reports an empty contribution list for a module that contributes nothing", async () => {
+    const modulesDirectory = await createModulesDirectory();
+    await createModule(modulesDirectory, "calendar");
+
+    const modules = await discoverModules({
+      moduleSdkVersion: "0.1.0",
+      modulesDirectory,
+      platformVersion: "0.1.0",
+    });
+
+    expect(modules[0]?.contributions).toEqual([]);
+  });
+
+  it("rejects a missing contribution artifact", async () => {
+    const modulesDirectory = await createModulesDirectory();
+    await createModule(modulesDirectory, "announcements", { manifest: contributingManifest() });
+
+    await expect(
+      discoverModules({
+        moduleSdkVersion: "0.1.0",
+        modulesDirectory,
+        platformVersion: "0.1.0",
+      }),
+    ).rejects.toMatchObject({
+      issues: expect.arrayContaining([
+        expect.objectContaining({ code: "MODULE_ENTRYPOINT_MISSING" }),
+      ]),
+    });
+  });
+
+  it("rejects a contribution artifact that is not compiled JavaScript", async () => {
+    const modulesDirectory = await createModulesDirectory();
+    await createModule(modulesDirectory, "announcements", {
+      extraFiles: { "src/contributions/signage-slide/index.tsx": "export default {};" },
+      manifest: contributingManifest({ artifact: "./src/contributions/signage-slide/index.tsx" }),
+    });
+
+    await expect(
+      discoverModules({
+        moduleSdkVersion: "0.1.0",
+        modulesDirectory,
+        platformVersion: "0.1.0",
+      }),
+    ).rejects.toMatchObject({
+      issues: expect.arrayContaining([
+        expect.objectContaining({ code: "MODULE_ENTRYPOINT_INVALID" }),
+      ]),
+    });
+  });
+
+  it("rejects a contribution artifact that escapes the package through a link", async () => {
+    const modulesDirectory = await createModulesDirectory();
+    const outside = await createModulesDirectory();
+    await writeFile(path.join(outside, "elsewhere.js"), "export default {};");
+    await createModule(modulesDirectory, "announcements", {
+      manifest: contributingManifest(),
+    });
+    await mkdir(path.join(modulesDirectory, "announcements/dist/contributions/signage-slide"), {
+      recursive: true,
+    });
+    await symlink(
+      path.join(outside, "elsewhere.js"),
+      path.join(modulesDirectory, "announcements/dist/contributions/signage-slide/index.js"),
+    );
+
+    await expect(
+      discoverModules({
+        moduleSdkVersion: "0.1.0",
+        modulesDirectory,
+        platformVersion: "0.1.0",
+      }),
+    ).rejects.toMatchObject({
+      issues: expect.arrayContaining([
+        expect.objectContaining({
+          code: "MODULE_ENTRYPOINT_INVALID",
+          path: "contributions.0.artifact",
+        }),
+      ]),
+    });
+  });
+
+  it("rejects two contributions that resolve through a link to the same file", async () => {
+    const modulesDirectory = await createModulesDirectory();
+    const manifest = {
+      ...manifestFor("announcements"),
+      contributions: [
+        {
+          id: "announcements.first",
+          version: "1.0.0",
+          capability: "signage.slide-renderer",
+          capabilityRange: "^1.0.0",
+          artifact: "./dist/contributions/first/index.js",
+        },
+        {
+          id: "announcements.second",
+          version: "1.0.0",
+          capability: "signage.slide-renderer",
+          capabilityRange: "^1.0.0",
+          artifact: "./dist/contributions/second/index.js",
+        },
+      ],
+    };
+    await createModule(modulesDirectory, "announcements", {
+      extraFiles: { "dist/contributions/first/index.js": "export default {};" },
+      manifest,
+    });
+    await mkdir(path.join(modulesDirectory, "announcements/dist/contributions/second"), {
+      recursive: true,
+    });
+    await symlink(
+      path.join(modulesDirectory, "announcements/dist/contributions/first/index.js"),
+      path.join(modulesDirectory, "announcements/dist/contributions/second/index.js"),
+    );
+
+    await expect(
+      discoverModules({
+        moduleSdkVersion: "0.1.0",
+        modulesDirectory,
+        platformVersion: "0.1.0",
+      }),
+    ).rejects.toMatchObject({
+      issues: expect.arrayContaining([
+        expect.objectContaining({ code: "MODULE_ENTRYPOINT_INVALID", path: "contributions" }),
+      ]),
+    });
+  });
+});