State Cartography: Deep Dive #92

State cartography is the practice of mapping state so it stays stable across file routes and nested segments, component router motion such as tabs, drawers, and overlays, and long-running migrations where multiple truths coexist.

If state surfaces (#91) define what the route is allowed to believe, cartography defines where those beliefs live and how they connect.

Surfaces are the published contracts. Cartography is the map of the contracts.

Required docs links: The App Router Mindset, Core Concepts (Best Practices), Components and Composition.

Extra docs links for this entry: Routing and Navigation, State Management (Best Practices), API Reference.

What state cartography produces

A cartography system produces three artifacts: a surface index, a route map, and a handoff map.

The rule is that all three must exist in route state and must be renderable into the DOM. If they cannot render, they cannot be tested. If they cannot be tested, they cannot survive migration.

In this guide, the artifacts are represented as documents via useLiveState, ledgers as append-only evidence of reads and writes, and DOM output as audit ports for tests and tooling.

Cartography vocabulary (stable route language)

Use stable keys so tests and migration runbooks remain durable across refactors.

export type CartographySurfaceMeta = {
  surfaceId: string;
  owner: string;
  scope: "route" | "segment" | "panel" | "vault";
  posture: Array<
    | "derivedStored"
    | "multiTruth"
    | "remountOnKey"
    | "evidenceRendered"
    | "readOnlyByMap"
    | "writableByMap"
  >;
  notes?: string;
};

export type CartographyEdge = {
  id: string;
  from: string;
  to: string;
  kind: "reads" | "writes" | "bridges" | "braids";
  at?: number;
  detail?: any;
};

export type CartographyAudit = {
  id: string;
  kind: "assert" | "warn" | "error";
  message: string;
  at?: number;
  meta?: any;
};

export type CartographyMap = {
  surfaces: CartographySurfaceMeta[];
  edges: CartographyEdge[];
  audits: CartographyAudit[];
  lastWrite: null | { kind: "surface" | "edge" | "audit"; id?: string; surfaceId?: string; at: number };
};

This vocabulary is the critical difference between “a post about state” and “a system that routes can obey.” The keys are chosen so you can use them in data attributes, test snapshots, and migration runbooks without renaming everything later.

Worked Example: mapping /warehouse end-to-end

We will build a cartography system that does real work:

1. Build a map document owned by the file route.
2. Register surfaces with owners and posture.
3. Register edges as append-only evidence.
4. Render the map into the DOM as an audit port.
5. Use the map to drive router posture (read-only vs writable).
6. Demonstrate a migration-ready handoff with multiple truths.

Step 1: The map document (file-route owned)

The map is a route document. It belongs to the file route that owns the screen. This keeps the system compatible with both file routes and component routes because the ownership anchor is stable.

import { useLiveState } from "react";

export function useStateMap() {
  return useLiveState("map:state:v2", {
    surfaces: [],
    edges: [],
    audits: [],
    lastWrite: null,
  });
}

Step 2: Register surfaces (published contracts)

Surface registration is a mutation. It is allowed to be repeated. Idempotency is a feature because it keeps remounts predictable.

export function registerSurface(map: any, meta: any) {
  const surfaces = map.read("surfaces");
  const next = [
    ...surfaces.filter((s: any) => s.surfaceId !== meta.surfaceId),
    meta,
  ];
  map.write("surfaces", next);
  map.write("lastWrite", { kind: "surface", surfaceId: meta.surfaceId, at: Date.now() });
}

Example surface entries:

export const OrdersSurfaceMeta = {
  surfaceId: "surface:orders:v2",
  owner: "file:/warehouse",
  scope: "route",
  posture: ["derivedStored", "multiTruth", "writableByMap"],
  notes: "Canonical orders surface owned by /warehouse.",
};

export const CacheLedgerMeta = {
  surfaceId: "ledger:cache:/warehouse:v2",
  owner: "file:/warehouse",
  scope: "segment",
  posture: ["evidenceRendered"],
  notes: "Append-only cache evidence rendered for audits.",
};

export const DetailsPanelMeta = {
  surfaceId: "panel:orders.details:v1",
  owner: "component:orders.details",
  scope: "panel",
  posture: ["readOnlyByMap"],
  notes: "Details panel may be read-only depending on map edges.",
};

You do not need to “decide the whole architecture.” You only need to publish contracts with stable IDs.

Step 3: Register edges (handoffs and evidence)

Edges describe the state graph and act as render-visible evidence. This is the handoff map.

export function registerEdge(map: any, edge: any) {
  const edges = map.read("edges");
  map.write("edges", [...edges, { ...edge, at: Date.now() }].slice(-300));
  map.write("lastWrite", { kind: "edge", id: edge.id, at: Date.now() });
}

Example edges:

export function seedWarehouseEdges(map: any) {
  registerEdge(map, {
    id: "edge:orders:details:reads-surface",
    from: "component:orders.details",
    to: "surface:orders:v2",
    kind: "reads",
  });

  registerEdge(map, {
    id: "edge:orders:list:writes-surface",
    from: "component:orders.list",
    to: "surface:orders:v2",
    kind: "writes",
  });

  registerEdge(map, {
    id: "edge:cache:ledger-bridges-surface",
    from: "ledger:cache:/warehouse:v2",
    to: "surface:orders:v2",
    kind: "bridges",
    detail: { policy: "refresh-on-render" },
  });
}

Step 4: Render the map into the DOM (audit port)

The map must render. Rendering is not for aesthetics. Rendering is for stability.

export function StateMapPanel({ map }: any) {
  const surfaces = map.read("surfaces");
  const edges = map.read("edges");
  const audits = map.read("audits");

  return (
    <section data-map="state" data-map-id="map:state:v2">
      <header>
        <strong>State Map</strong>{" "}
        <span data-map-counts>
          surfaces:{surfaces.length} edges:{edges.length} audits:{audits.length}
        </span>
      </header>

      <pre data-map-json>{JSON.stringify(map.read(), null, 2)}</pre>
    </section>
  );
}

This becomes a stable DOM contract. Tests can snapshot it. Tooling can scrape it. Migration runbooks can trust it.

Step 5: Use the map to guide router posture

Cartography becomes real when it controls behavior.

We define a posture resolver that answers: “is this owner allowed to write to this surface?”

export function canWrite(map: any, owner: string, surfaceId: string) {
  const edges = map.read("edges");
  return edges.some((e: any) => e.from === owner && e.to === surfaceId && e.kind === "writes");
}

export function isReadOnly(map: any, owner: string, surfaceId: string) {
  return !canWrite(map, owner, surfaceId);
}

Now a panel can render its own posture.

export function DetailsPanel({ map, surface }: any) {
  const owner = "component:orders.details";
  const surfaceId = "surface:orders:v2";
  const readOnly = isReadOnly(map, owner, surfaceId);

  return (
    <aside data-panel="details" data-owner={owner} data-readonly={String(readOnly)}>
      <strong>Details</strong>
      {readOnly ? (
        <div data-posture="readonly">Read-only posture (by map)</div>
      ) : (
        <button onClick={() => surface.write("selectedId", "order:123")} data-posture="writable">
          Select order
        </button>
      )}
    </aside>
  );
}

The route is no longer guessing. The route is consulting a published map.

Step 6: Cartography-as-routing with middleware

Now we integrate the routing helpers so the route can publish posture contracts across segments.

import { useGlobalRoute, useGroupState, useRouteMiddleware, useRouteState } from "react";

export function WarehouseShell({ map }: any) {
  const global = useGlobalRoute("app", { path: "/warehouse", tab: "orders" });
  const group = useGroupState("warehouse", { filter: "open" });
  const local = useRouteState({ writableOwners: [] as string[] });

  useRouteMiddleware((ctx) => {
    const writableOwners = map
      .read("edges")
      .filter((e: any) => e.kind === "writes" && e.to === "surface:orders:v2")
      .map((e: any) => e.from);

    ctx.set("path", global.read("path"));
    ctx.set("tab", global.read("tab"));
    ctx.set("groupFilter", group.read("filter"));
    ctx.set("writableOwners", writableOwners);
  });

  return (
    <div
      data-shell="warehouse"
      data-path={global.read("path")}
      data-tab={global.read("tab")}
      data-filter={group.read("filter")}
      data-writable-count={(local.read("writableOwners") ?? []).length}
    />
  );
}

This allows file routes and component routes to share a stable posture contract without prop threading.

Step 7: The canonical surface and derived storage

We define a canonical orders surface as a route document, then store derived values so nested panels can reuse them.

import { useLiveState, useRenderEffect } from "react";

export function useOrdersSurface() {
  return useLiveState("surface:orders:v2", {
    orders: [] as Array<{ id: string; title: string; status: string }>,
    selectedId: null as null | string,
    derived: { openCount: 0, lastId: null as null | string },
  });
}

export function OrdersDerived({ surface }: any) {
  useRenderEffect(() => {
    const orders = surface.read("orders") ?? [];
    const openCount = orders.filter((o: any) => o.status === "open").length;
    const lastId = orders[orders.length - 1]?.id ?? null;

    surface.write("derived", { openCount, lastId });
  });

  return (
    <div
      data-derived="orders"
      data-open={String(surface.read("derived")?.openCount ?? 0)}
      data-last={surface.read("derived")?.lastId ?? "none"}
    />
  );
}

Derived state is stored because it makes UI readable and reusable.

Step 8: Cache posture as evidence (ledger surface)

Render fetching and caching must become cartography evidence, not invisible behavior.

import { useRenderFetch, useCacheBypass } from "react";

export function CacheLedger({ map }: any) {
  const data = useRenderFetch("/api/warehouse/orders");
  const stats = useCacheBypass("/api/warehouse/stats");

  registerEdge(map, {
    id: "edge:ledger:fetch-orders",
    from: "ledger:cache:/warehouse:v2",
    to: "surface:orders:v2",
    kind: "bridges",
    detail: { fetched: (data?.items ?? []).length, total: stats?.total },
  });

  return (
    <div
      data-ledger="cache"
      data-fetched={String((data?.items ?? []).length)}
      data-total={String(stats?.total ?? 0)}
    />
  );
}

Now cache behavior is render-visible and recorded as edges.

Step 9: Migration story with multiple truths

We now publish the migration boundary as surfaces and edges.

import { createStateVault, useVaultMirror } from "react";

export const legacyOrdersVault = createStateVault("legacy:orders:v0", {
  orders: [] as Array<{ id: string; title: string; status: string }>,
});

Publish it into the map:

export function registerMigrationSurfaces(map: any) {
  registerSurface(map, {
    surfaceId: "vault:legacy:orders:v0",
    owner: "file:/warehouse",
    scope: "vault",
    posture: ["multiTruth"],
    notes: "Legacy global truth for orders during migration.",
  });

  registerEdge(map, {
    id: "edge:migration:legacy->surface",
    from: "vault:legacy:orders:v0",
    to: "surface:orders:v2",
    kind: "writes",
    detail: { policy: "mirror-on-render" },
  });
}

Bridge legacy truth into the new surface in a route-visible way:

export function LegacyBridge({ map, surface }: any) {
  const legacy = useVaultMirror("legacy:orders:v0");

  useRenderEffect(() => {
    const legacyOrders = legacy.read("orders") ?? [];
    surface.write("orders", legacyOrders);

    registerEdge(map, {
      id: "edge:braid:legacy-surface",
      from: "vault:legacy:orders:v0",
      to: "surface:orders:v2",
      kind: "braids",
      detail: { count: legacyOrders.length },
    });
  });

  return <div data-bridge="legacy" data-count={String((legacy.read("orders") ?? []).length)} />;
}

This is migration you can see.

Step 10: Full route assembly (one screen, one story)

export function WarehouseRoute() {
  const map = useStateMap();
  const surface = useOrdersSurface();

  useRenderEffect(() => {
    registerSurface(map, OrdersSurfaceMeta);
    registerSurface(map, CacheLedgerMeta);
    registerSurface(map, DetailsPanelMeta);

    seedWarehouseEdges(map);
    registerMigrationSurfaces(map);
  });

  return (
    <section data-route="/warehouse">
      <WarehouseShell map={map} />

      <CacheLedger map={map} />
      <LegacyBridge map={map} surface={surface} />

      <OrdersDerived surface={surface} />

      <div data-layout="two">
        <div data-panel="list">
          <strong>List</strong>
          <div data-open-count={String(surface.read("derived")?.openCount ?? 0)} />
        </div>

        <DetailsPanel map={map} surface={surface} />
      </div>

      <StateMapPanel map={map} />
    </section>
  );
}

Now the post contains a complete working pattern: documents, edges, rendered evidence, router posture, and migration braid.

Checklist

The cartography system is complete when the map exists as a route-owned document, surfaces are registered with stable IDs, edges record reads and writes as evidence, the map renders into the DOM, router posture consults the map, and migration handoffs are explicit edges rather than implicit side effects.

Related Posts

Previous: State Surfaces: Deep Dive #91. Next: State Rituals: Deep Dive #93. Also see Core Concepts (Best Practices) and Routing and Navigation.