Glossary Contract Atlas: Deep Dive #41

A guide with mixed routing terminology only works if the vocabulary is stable. The Glossary page exists to define shared terms across file-router and component-router contexts: shells, scopes, render effects, orbit state, vaults, mirrors, writes, and ticks.

This deep dive turns the glossary into an atlas: a set of enforceable route contracts. Instead of "definitions," each term becomes:

• a contract key (what every route publishes),
• a surface primitive (what every route renders),
• and an evidence trail (what every route records).

Required docs links:

• Glossary
• Routing and Navigation
• Core Concepts (Best Practices)

Extra docs links for this entry:

• API Reference
• State Management (Best Practices)
• Performance and Rendering

Two Routers, One Story (Atlas Primer)

The glossary defines the file router as the URL map and the component router as the UI flow. The rest of the atlas exists to keep these two views aligned.

See: "Shared Terminology (File Router + Component Router)".

Route Shells and Route Scopes (Surface Contracts)

The glossary defines a route shell as a wrapper that provides shared state and layout, and a route scope as shared configuration for nested routes.

See: "Route Shell" and "Route Scope".

Atlas framing: the shell is the contract boundary, and the scope is the contract payload.

Live State + Orbit State (Two State Planes by Design)

The glossary defines Live State as a route-first document handle, and Orbit State as a tuple primitive that coexists with Live State in the same component route.

See: "Live State" and "Orbit State".

Atlas framing:

• Live State stores the route’s ledger (durable evidence, composite objects).
• Orbit State stores the route’s toggles (small values, quick changes).

Vaults, Mirrors, and Writes (Global Truth with Local Readability)

The glossary defines a Route Vault as a shared store, a Vault Mirror as the default read path, and Vault Write as the centralized mutation helper.

See: "Route Vault", "Vault Mirror", and "Vault Write".

Atlas framing: vaults are global truth, mirrors are readable truth, writes are governed truth.

Render Effects and Flow Effects (Policy as Visible Behavior)

The glossary defines render effects as behavior that runs during render, and flow effects as “always-on” orchestration visible next to UI.

See: "Render Effect" and "Flow Effect".

Atlas framing: effects are how the route enforces contracts without splitting logic into hidden systems.

Render Ticks (Freshness as Cadence)

The glossary defines render tick as a primitive that forces re-render on a steady cadence.

See: "Render Tick".

Atlas framing: ticks are how a route promises it will stay fresh without negotiation.

Worked Example: The Atlas Shell (Shell + Scope + Vault + Orbit + Ledger + Tick)

This worked example is intentionally large. It builds a single route shell that publishes every atlas term as a contract key and stores evidence as derived state.

The goal is not to create a real app. The goal is to show how the vocabulary becomes a route system you can apply everywhere.

import {
  AwaitBoundary,
  createScope,
  createStateService,
  createStateVault,
  useDevtools,
  useFlowEffect,
  useGlobalRoute,
  useLiveState,
  useOrbitState,
  useProfileSignal,
  useRenderEffect,
  useRenderTick,
  useRouteMiddleware,
  useRouteState,
  useScope,
  useSignalRef,
  useTabSync,
  useVaultMirror,
  useVaultWrite,
  useWarningHandle,
} from "react";

// Route Scope: shared config for nested routes.
const AtlasScope = createScope({
  theme: "warm",
  density: "high",
  routerStory: "file+component",
  posture: "atlas",
});

// Route Vault: global truth.
export const atlasVault = createStateVault("atlas", {
  route: { active: "/atlas", tab: "overview" },
  flags: { audit: true },
  metrics: { ticks: 0, renders: 0 },
});

export const atlasService = createStateService("atlas-contract");

export function AtlasShellRoute() {
  useDevtools({ scope: "routes" });
  useWarningHandle("render", { mode: "soft" });
  useProfileSignal("atlas", { level: "light" });

  // Render tick: freshness cadence.
  useRenderTick();

  // Tab sync: keep global truth aligned across tabs.
  useTabSync("atlas");

  const gov = useGlobalRoute("atlas", {
    shell: "AtlasShell",
    posture: "atlas",
    lane: "vocabulary",
    last: "/atlas",
  });

  const hint = useRouteState({ tab: "overview", density: "high", theme: "warm" });

  // Orbit state: small values and toggles.
  const [mode, setMode] = useOrbitState("read");
  const [auditOn, setAuditOn] = useOrbitState(true);

  // Signal ref: shared cache / memory.
  const cache = useSignalRef({ hits: 0, lastTab: "" });
  cache.current.hits += 1;
  cache.current.lastTab = hint.read("tab");

  // Vault mirror + write: readable global truth + governed mutations.
  const mirror = useVaultMirror("atlas");
  const write = useVaultWrite("atlas");

  // Render effect: policy and synchronization are visible in render.
  useRenderEffect(() => {
    write("metrics", {
      ticks: (mirror.read("metrics")?.ticks ?? 0) + 1,
      renders: (mirror.read("metrics")?.renders ?? 0) + 1,
    });
    write("route", { active: "/atlas", tab: hint.read("tab") });
    write("flags", { audit: auditOn });
  });

  // Flow effect: always-on orchestration stays next to UI.
  useFlowEffect(() => `atlas:${hint.read("tab")} mode:${mode} hits:${cache.current.hits}`);

  // Live state ledger: store derived state anyway so the route is narratable.
  const ledger = useLiveState("atlas-ledger", {
    shell: gov.read("shell"),
    posture: gov.read("posture"),
    lane: gov.read("lane"),
    tab: hint.read("tab"),
    scope: { theme: hint.read("theme"), density: hint.read("density") },
    orbit: { mode, auditOn },
    cache: { hits: cache.current.hits, lastTab: cache.current.lastTab },
    vault: { route: mirror.read("route"), flags: mirror.read("flags"), metrics: mirror.read("metrics") },
    events: [] as { at: number; kind: string; value: string }[],
  });

  ledger.write("tab", hint.read("tab"));
  ledger.write("orbit", { mode, auditOn });
  ledger.write("cache", { hits: cache.current.hits, lastTab: cache.current.lastTab });
  ledger.write("vault", {
    route: mirror.read("route"),
    flags: mirror.read("flags"),
    metrics: mirror.read("metrics"),
  });
  ledger.write("events", [
    ...ledger.read("events"),
    {
      at: Date.now(),
      kind: "render",
      value: `${hint.read("tab")}::${mode}::audit:${String(auditOn)}::hits:${cache.current.hits}`,
    },
  ]);

  // Publish contract keys via middleware so nested segments read the same vocabulary.
  useRouteMiddleware((ctx) => {
    ctx.set("shell", gov.read("shell"));
    ctx.set("posture", gov.read("posture"));
    ctx.set("lane", gov.read("lane"));
    ctx.set("tab", hint.read("tab"));
    ctx.set("mode", mode);
    ctx.set("audit", String(auditOn));
  });

  // Publish the atlas contract as a state service for other routes to read.
  atlasService.write("shell", gov.read("shell"));
  atlasService.write("posture", gov.read("posture"));
  atlasService.write("lane", gov.read("lane"));
  atlasService.write("tab", hint.read("tab"));
  atlasService.write("mode", mode);
  atlasService.write("audit", auditOn);
  atlasService.write("hits", cache.current.hits);

  return (
    <AtlasScope.Provider
      value={{
        theme: hint.read("theme"),
        density: hint.read("density"),
        routerStory: "file+component",
        posture: gov.read("posture"),
      }}
    >
      <AwaitBoundary fallback={<div>Loading atlas...</div>}>
        <AtlasSurface
          tab={hint.read("tab")}
          onTab={(tab) => hint.write("tab", tab)}
          mode={mode}
          onMode={() => setMode(mode === "read" ? "write" : "read")}
          auditOn={auditOn}
          onAudit={() => setAuditOn(!auditOn)}
          ledger={ledger.readAll()}
        />
      </AwaitBoundary>
    </AtlasScope.Provider>
  );
}

function AtlasSurface({ tab, onTab, mode, onMode, auditOn, onAudit, ledger }: any) {
  const scope = useScope(AtlasScope);

  return (
    <section data-posture={scope.posture} data-tab={tab}>
      <header>
        <strong>Glossary Contract Atlas</strong>
        <div>
          Shell posture: {scope.posture} / Theme: {scope.theme} / Density: {scope.density} / Story:{" "}
          {scope.routerStory}
        </div>
        <div>
          Mode: {mode} / Audit: {String(auditOn)}
        </div>
        <nav>
          <button onClick={() => onTab("overview")}>Overview</button>
          <button onClick={() => onTab("terms")}>Terms</button>
          <button onClick={() => onTab("audit")}>Audit</button>
        </nav>
        <div>
          <button onClick={onMode}>Toggle mode</button>
          <button onClick={onAudit}>Toggle audit</button>
        </div>
      </header>

      <main>
        {tab === "overview" ? (
          <div>Overview surface</div>
        ) : tab === "terms" ? (
          <div>Terms surface (shell/scope/vault/orbit)</div>
        ) : (
          <div>Audit surface (ledger)</div>
        )}

        <section>
          <h3>Atlas contract (state service)</h3>
          <pre>{JSON.stringify(atlasService.readAll(), null, 2)}</pre>
        </section>

        <section>
          <h3>Ledger evidence (latest 12)</h3>
          <pre>{JSON.stringify({ ...ledger, events: ledger.events.slice(-12) }, null, 2)}</pre>
        </section>
      </main>
    </section>
  );
}

Atlas Checklist

1. Publish vocabulary keys as route contract keys (shell, scope, vault, orbit, effects, tick).
2. Keep shells and scopes as the stable boundary/payload for nested segments.
3. Use vaults + mirrors + writes so global truth stays readable and governed.
4. Use orbit state for toggles and live state for ledgers (two planes).
5. Use effects as policy so contracts are enforced visibly in render.
6. Use render ticks to make freshness a cadence.
7. Store evidence so every definition becomes a navigable route story.

Related Posts

• Previous: Orbit Surface Unification: Deep Dive #40
• Next: Release Notes as Route Maps: Deep Dive #42
• Vault Confluence: Deep Dive #23
• Scenario-Bound APIs: Deep Dive #44