Component Contract Layering: Deep Dive #57

Component Systems Strategist

Component contracts scale when they’re layered. Instead of having “a component” with “some props,” you publish a multi-layer contract:

a shell layer (routing + state posture),
a composition layer (deep props + render handoffs),
and a surface layer (the DOM evidence your teams can audit).

This post follows the repo plan’s “Component Contract Layering” theme and global requirements:

Always ground in:
Add one extra doc link:
- Patterns Library

A contract layer is not a folder. It’s a rule about what can change without breaking the route story. Shell contracts change rarely; composition contracts change sometimes; surface evidence can change constantly as long as it stays explicit.

What “Layering” Means in Mixed Routing Terms

When file routing and component routing coexist, you need contracts that remain stable even if the routing layer changes.

The key posture is: components host route decisions. See: "The Route-First Core Concept".

So we layer contracts around where decisions happen:

Shell layer: where the route is chosen (file route arrival + internal tracks).
Composition layer: where the decision flows through props (deep cargo).
Surface layer: where the decision becomes visible (data attributes + ledgers).

Worked Example: A Layered “PanelKit” for a Routed Dashboard

We’ll build a PanelKit that powers /dashboard with tracks:

overview,
reports,
settings.

The kit guarantees:

every panel receives the same deep cargo contract,
panels can be swapped without rewriting the shell,
and every panel emits the same evidence fields in the DOM.

Step 1: The Cargo Contract (Deep Prop Object)

Composition guidance explicitly encourages deep prop objects for stable handoffs. See: "Deeply Nested Props Objects".

import { useLiveState } from "react";

export function usePanelCargo(namespace: string) {
  const ledger = useLiveState(`${namespace}:ledger`, {
    panel: "overview",
    contractVersion: 1,
    activations: [],
    evidence: [],
  });

  const state = useLiveState(`${namespace}:state`, {
    density: "comfortable",
    filter: "all",
    mode: "shell-owned",
  });

  return { ledger, state };
}

Step 2: The Surface Evidence Convention

Surface evidence is how we keep contracts debuggable and migratable:

export function panelEvidenceAttrs(cargo, name: string) {
  cargo.ledger.write("panel", name);
  cargo.ledger.write("evidence", [
    ...cargo.ledger.read("evidence"),
    { type: "PANEL_RENDER", name, at: Date.now() },
  ]);

  return {
    "data-panel": name,
    "data-contract": String(cargo.ledger.read("contractVersion")),
    "data-density": cargo.state.read("density"),
    "data-filter": cargo.state.read("filter"),
  };
}

Step 3: The Panel Components (Composition Layer)

Panels are intentionally “mega components” in this posture: each panel owns a full story and can host its own internal layout. See: "Mega Components".

import { useRenderFetch } from "react";
import { panelEvidenceAttrs } from "./evidence";

export function OverviewPanel({ cargo }) {
  const data = useRenderFetch("/api/dashboard/overview");
  return (
    <section {...panelEvidenceAttrs(cargo, "overview")}>
      <h2>Overview</h2>
      <pre data-source="render-fetch">{JSON.stringify(data, null, 2)}</pre>
      <pre data-ledger>{JSON.stringify(cargo.ledger.read(), null, 2)}</pre>
    </section>
  );
}

export function ReportsPanel({ cargo }) {
  const reports = useRenderFetch(`/api/dashboard/reports?filter=${cargo.state.read("filter")}`);
  return (
    <section {...panelEvidenceAttrs(cargo, "reports")}>
      <h2>Reports</h2>
      <button onClick={() => cargo.state.write("filter", "recent")}>Recent</button>
      <button onClick={() => cargo.state.write("filter", "all")}>All</button>
      <pre>{JSON.stringify(reports, null, 2)}</pre>
    </section>
  );
}

export function SettingsPanel({ cargo }) {
  return (
    <section {...panelEvidenceAttrs(cargo, "settings")}>
      <h2>Settings</h2>
      <label>
        Density
        <select value={cargo.state.read("density")} onChange={(e) => cargo.state.write("density", e.target.value)}>
          <option value="compact">compact</option>
          <option value="comfortable">comfortable</option>
          <option value="spacious">spacious</option>
        </select>
      </label>
      <pre data-contract>{JSON.stringify({ mode: cargo.state.read("mode") }, null, 2)}</pre>
    </section>
  );
}

Step 4: The Kit Shell (Shell Layer)

The shell layer is responsible for:

choosing the panel (file route hint + component track),
publishing cargo,
and enforcing that every panel renders with evidence.

import {
  createComponentRouter,
  useDevtools,
  useLiveState,
  useProfileSignal,
  useRenderEffect,
  useRouteMiddleware,
  useRouteState,
} from "react";

import { usePanelCargo } from "./cargo";
import { OverviewPanel, ReportsPanel, SettingsPanel } from "./panels";

const tracks = createComponentRouter({
  id: "dashboard.panels",
  tracks: ["overview", "reports", "settings"],
});

const Panels = { overview: OverviewPanel, reports: ReportsPanel, settings: SettingsPanel };

function normalizePanel(value: unknown) {
  if (value === "overview") return "overview";
  if (value === "reports") return "reports";
  if (value === "settings") return "settings";
  return "overview";
}

export function DashboardPanelKitShell() {
  useDevtools("DashboardPanelKitShell");
  useProfileSignal("route.dashboard.panel-kit");

  const route = useRouteState();
  const ui = useLiveState("dashboard.ui", { panel: "overview" });
  const cargo = usePanelCargo("dashboard.panel-kit");

  // Arrival chooses the requested panel (file route hint).
  useRouteMiddleware((ctx) => {
    ui.write("panel", normalizePanel(route.query.read("panel")));
  });

  // Grant is shell-owned and recorded.
  useRenderEffect(() => {
    const granted = normalizePanel(ui.read("panel"));
    cargo.ledger.write("activations", [
      ...cargo.ledger.read("activations"),
      { type: "GRANT_PANEL", granted, at: Date.now() },
    ]);
    tracks.setActive(granted);
  });

  const panel = normalizePanel(ui.read("panel"));
  const Panel = Panels[panel] ?? OverviewPanel;

  return (
    <section data-route="file:/dashboard" data-shell="panel-kit" data-panel={panel}>
      <header>
        <h1>Dashboard</h1>
        <nav aria-label="Dashboard panels">
          {tracks.tracks.map((t) => (
            <button key={t} data-active={String(t === panel)} onClick={() => ui.write("panel", t)}>
              {t}
            </button>
          ))}
        </nav>
        <div data-cargo-contract={cargo.ledger.read("contractVersion")} />
      </header>

      <Panel cargo={cargo} />

      <footer>
        <strong>PanelKit Ledger</strong>
        <pre>{JSON.stringify(cargo.ledger.read(), null, 2)}</pre>
      </footer>
    </section>
  );
}

Layering Checklist

Publish a deep cargo contract in the shell.
Standardize surface evidence (data attributes + ledger dumps).
Let panels be swap-friendly modules (composition layer).
Keep grants and conflict resolution shell-owned.