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
@@ -0,0 +1,24 @@
+import type { ReactElement } from "react";
+
+/**
+ * The shape the **consuming** module publishes alongside its capability, restated here as this
+ * module's understanding of it. Ekklesia neither defines nor validates it: a contribution's input is
+ * a domain contract between two modules, versioned by the consumer's capability version, and the
+ * platform carries it as opaque JSON (ADR 0041).
+ */
+export interface SummaryInput {
+  readonly heading?: unknown;
+  readonly count?: unknown;
+}
+
+export function SummaryCard({ input }: { readonly input: SummaryInput }): ReactElement {
+  const heading = typeof input.heading === "string" ? input.heading : "Example";
+  const count = typeof input.count === "number" ? input.count : 0;
+
+  return (
+    <section className="summary-card" data-testid="summary-card">
+      <h2 className="summary-card__heading">{heading}</h2>
+      <p className="summary-card__count">{`${count} record(s)`}</p>
+    </section>
+  );
+}
@@ -0,0 +1,39 @@
+import { defineModuleContribution } from "@ekklesia/module-ui-sdk";
+import { createRoot, type Root } from "react-dom/client";
+import styles from "./styles.css";
+import { SummaryCard, type SummaryInput } from "./SummaryCard.js";
+
+/**
+ * A **browser contribution**: a renderer this module offers to a capability *another* module
+ * provides (ADR 0041).
+ *
+ * The manifest declares it as `example.summary-card`, targeting `example-host.summary-card`. That
+ * capability belongs to whichever module provides it — this module neither imports it nor knows
+ * anything about it beyond the id and the input shape that module published. If no installed module
+ * provides it within the declared range, the platform simply does not publish this artifact; nothing
+ * here has to notice.
+ *
+ * `pnpm build` compiles this file from the fixed source location the contribution id implies:
+ * `src/contributions/<local-name>/index.tsx`. Module authors configure no paths.
+ */
+export default defineModuleContribution({
+  id: "example.summary-card",
+  version: "1.0.0",
+  styles,
+  mount(container, context) {
+    const root: Root = createRoot(container);
+    // The consumer's input is opaque to the platform and typed by the *consumer's* published
+    // contract, not by Ekklesia. Validate it here rather than trusting its shape.
+    root.render(<SummaryCard input={context.input as SummaryInput} />);
+    return {
+      // Updating in place is what lets a long-running screen change content without restarting
+      // animations or reloading media on every tick.
+      update(input) {
+        root.render(<SummaryCard input={input as SummaryInput} />);
+      },
+      unmount() {
+        root.unmount();
+      },
+    };
+  },
+});
@@ -0,0 +1,27 @@
+/*
+ * A contribution's stylesheet works exactly like a module UI artifact's: compiled into the declared
+ * artifact as text and installed by the host into this renderer's own isolated root (ADR 0040). It
+ * therefore cannot restyle the consuming module's screen around it, and that module's rules cannot
+ * reach in here.
+ */
+
+.summary-card {
+  background: var(--ekklesia-background-surface);
+  border-radius: var(--ekklesia-radius-lg);
+  color: var(--ekklesia-text-primary);
+  display: grid;
+  font-family: var(--ekklesia-typography-family-sans);
+  gap: var(--ekklesia-spacing-xs);
+  padding: var(--ekklesia-spacing-lg);
+}
+
+.summary-card__heading {
+  font-size: var(--ekklesia-typography-size-heading-3);
+  font-weight: var(--ekklesia-typography-weight-bold);
+  margin: 0;
+}
+
+.summary-card__count {
+  color: var(--ekklesia-text-secondary);
+  margin: 0;
+}