cursedbelt 0.0.0 → 2.3.0

package/src/verify/types.ts

@@ -0,0 +1,517 @@
+/**
+ * The verification pipeline's vocabulary (04 §1). Everything the eight stages
+ * consume or produce is declared here so the four run moments — studio, export,
+ * boot, CI — share one implementation and can never drift into "studio says
+ * fine, boot says no".
+ *
+ * The design stance is a single sentence: **fail-closed on structure,
+ * degrade-with-diagnostic on capability.** A config that references something
+ * which will not exist at runtime is an ERROR. A config asking for more than the
+ * environment delivers resolves to a declared degradation with a visible
+ * diagnostic — never silence.
+ */
+import type { z } from 'zod';
+import type { EngineId, FillDecl, RouteDecl } from '../config/appConfig';
+import type { CCWireMarshaller, TokenDef } from '../core/tokens/registry';
+
+export type Severity = 'error' | 'warning' | 'info';
+
+/**
+ * Every diagnostic the pipeline can emit. Declared as a value array (not a bare
+ * type union) so fixtures' expected-diagnostic files can be validated against it
+ * — a typo in an expectation would otherwise make a fixture vacuously pass.
+ */
+export const DIAGNOSTIC_CODES = [
+  // ── V0 — strict parse & staging ingestion ────────────────────────────────
+  'staging-token-file-invalid',
+  'staging-catalog-ingested',
+  'unknown-config-key',
+  'config-version-unknown',
+  'config-not-an-object',
+  'engine-dependency-missing',
+  'missing-required-config',
+  'config-invalid-value',
+  // ── V1 — reference resolution ────────────────────────────────────────────
+  'duplicate-instance-id',
+  'unknown-connection-endpoint',
+  'port-direction-mismatch',
+  'source-not-registered',
+  'route-param-mismatch',
+  'route-collision',
+  'ambiguous-deep-link',
+  'dangling-view-reference',
+  'literal-route-in-config',
+  'slot-unknown',
+  'unknown-fill-component',
+  'unknown-required-feature',
+  'unknown-plugin-with-migration-hint',
+  'unknown-deep-link-entity',
+  // ── V2 — effective capability computation ────────────────────────────────
+  'deploy-target-unspecified',
+  'capability-downgrade',
+  'port-disabled-by-config',
+  'op-disabled-by-config',
+  'privileged-feature-unclaimed',
+  'media-degraded-progressive',
+  // ── V3 — token lattice & contracts ───────────────────────────────────────
+  'token-not-registered',
+  'token-namespace-violation',
+  'token-collision',
+  'subtype-inversion',
+  'token-incompatible',
+  'port-mode-mismatch',
+  'token-schema-extended',
+  'token-schema-drift',
+  'marshaller-missing',
+  'marshaller-payload-unbounded',
+  'marshaller-worker-offload-missing',
+  'unstructured-internal-completion',
+  'token-deprecated',
+  'required-port-unwired',
+  // ── V4 — graph & event semantics ─────────────────────────────────────────
+  'cycle-unmarked',
+  'cycle-allowed',
+  'emission-unversioned',
+  'cycle-without-damping',
+  'cycle-broken-by-config',
+  'signal-may-miss-premount',
+  'payload-buffering-banned',
+  'pane-subscription-leak',
+  'unscoped-fanin',
+  'over-invalidation-risk',
+  'eventbus-cycle',
+  'bus-to-hub-sync-emit',
+  'cross-engine-state-write',
+  'exec-arbitrary-argv',
+  'exec-outside-dev-mixin',
+  'storm-budget-undeclared',
+  // ── V5 — exportability & bundle identity ─────────────────────────────────
+  'non-exportable-source',
+  'staging-plugin-in-export',
+  'bundle-tier-mismatch',
+  'lazy-boundary-missing',
+  'css-isolation-missing',
+  'stylesheet-duplication',
+  'virtualized-grid-unbounded',
+  'generated-app-plugin-loader',
+  // ── V6 — storage & registry contract ─────────────────────────────────────
+  'missing-tenancy-column',
+  'rls-policy-missing',
+  'unpooled-saas-connection',
+  'missing-declared-index',
+  'pragma-drift',
+  'wal-checkpoint-starvation',
+  'migration-namespace-missing',
+  'client-ddl-on-shared-db',
+  'staging-ddl-escape',
+  'telemetry-in-registry',
+  'port-toctou-pattern',
+  'legacy-vault-detected',
+  'key-material-as-string',
+  'row-signature-missing',
+  'meter-event-loss-possible',
+  'telemetry-blocking-request',
+  'config-drift',
+  'unsafe-live-db-backup',
+  'promotion-against-live-db',
+  // ── V7 — runtime probes ──────────────────────────────────────────────────
+  'route-surface-mismatch',
+  'private-bytes-leaked',
+  'rbac-not-enforced',
+  // The runtime twin of the static `infra-privilege-gate` fixture (05 §B5): the
+  // fixture proves a config DECLARES the claim, this proves the running server
+  // ENFORCES it. Distinct from `rbac-not-enforced` on purpose — that one is
+  // about roles, this one is about a permission that binds even where RBAC is
+  // off, which is the whole point of a privileged feature (J2-2).
+  'privileged-op-unguarded',
+  'wire-smoke-silent-drop',
+  'instance-config-crosstalk',
+  'last-good-not-served',
+  'lifecycle-leak',
+  'lifecycle-order',
+  'eventloop-guard-missing',
+  'cross-tab-lock-missing',
+  'cors-policy-violation',
+  'csp-header-overridden',
+  'reconnect-stampede',
+  'integrity-tamper-undetected',
+  'injection-guard-missing',
+  'exec-jail-escape',
+  'ssrf-guard-missing',
+  'layout-recompute-missing',
+  'deep-link-fallback-missing',
+  'meter-event-loss',
+  'verify-zombie-process',
+  'verify-probes-executed',
+  'probe-harness-error',
+] as const;
+
+export type DiagnosticCode = (typeof DIAGNOSTIC_CODES)[number];
+
+const DIAGNOSTIC_CODE_SET: ReadonlySet<string> = new Set<string>(DIAGNOSTIC_CODES);
+export const isDiagnosticCode = (value: string): value is DiagnosticCode => DIAGNOSTIC_CODE_SET.has(value);
+
+export interface Diagnostic {
+  code: DiagnosticCode;
+  severity: Severity;
+  instanceId?: string;
+  port?: string;
+  path?: string;
+  message: string;
+  /** Machine-actionable hint — REQUIRED for every error (asserted by the pipeline's own spec). */
+  fix?: string;
+}
+
+/** The four run moments. They differ ONLY in disposition and capability source (04 §1). */
+export type VerifyMoment = 'studio' | 'export' | 'boot' | 'ci';
+
+/** Host/target capabilities a feature can depend on: `{ ffmpeg: true, mps: false, ... }`. */
+export type CapabilityProfile = Readonly<Record<string, boolean>>;
+
+/* ------------------------------------------------------------------ ports */
+
+export type EffectiveFeatureMap = Readonly<Record<string, boolean | number | string | readonly string[]>>;
+
+/**
+ * 04 §3 — the fail-closed mechanism. `enabledWhen` is a TypeScript predicate
+ * (ruling J2-3): engine-authored compiled code evaluated exactly once, in V2,
+ * against the instance's effective features. It is never user data and never
+ * evaluated at delivery time, so an excluded port simply does not exist in the
+ * manifest — the studio cannot draw the wire, export cannot emit it, boot cannot
+ * mount it, and the runtime hub needs no feature-gating layer at all.
+ */
+export interface PortSpec<T = unknown> {
+  id: string;
+  token: TokenDef<z.ZodType<T>>;
+  direction: 'in' | 'out';
+  /** required-in with no wire = ERROR `required-port-unwired`. */
+  required: boolean;
+  enabledWhen?: (effective: EffectiveFeatureMap, profile: 'local' | 'saas') => boolean;
+  /** V4 replay-audit declaration: this input is subscribed at instance mount. */
+  subscribesAtMount?: boolean;
+  /** REQUIRED for value outputs (V4 `emission-unversioned`). */
+  emission?: 'versioned';
+  /** Declared scope filters for fan-in consumers (V4 `over-invalidation-risk`). */
+  scopeFilter?: readonly string[];
+  /** Scopes a fan-in producer stamps on its envelopes (V4 `unscoped-fanin`). */
+  scopes?: readonly string[];
+  /** Storm breaker threshold for this channel; absent ⇒ V4 `storm-budget-undeclared`. */
+  stormBudgetPerWindow?: number;
+}
+
+/* --------------------------------------------------------------- engines */
+
+export interface EngineViewDecl {
+  id: string;
+  /** Route params the view accepts; V1 `route-param-mismatch` compares against the declaration. */
+  params: readonly string[];
+  /** Feature key that must be effective-on for the view to exist. */
+  requiredFeature?: string;
+  /** Heavy chunk tiers this view pulls (`ffmpeg.wasm`, `hls.js`, `editor`) — V5 bundle identity. */
+  tiers?: readonly string[];
+  /** True when the view renders a virtualized grid/list (V5 `virtualized-grid-unbounded`). */
+  virtualized?: boolean;
+  /** True when the view is mounted behind a React.lazy boundary (V5 `lazy-boundary-missing`). */
+  lazy?: boolean;
+}
+
+export interface EngineOpDecl {
+  id: string;
+  requiredFeature?: string;
+  /** Permission the mixin sub-block must declare (02 §4.4). */
+  permission?: string;
+}
+
+export interface EngineFillDecl {
+  id: string;
+  slot: string;
+  requiredFeatures?: readonly string[];
+  requiredPermissions?: readonly string[];
+}
+
+/**
+ * The compile-time export index of an engine: what it can contribute to an app.
+ * This is the structure V1/V2/V5 check a config against, and the structure the
+ * verify-mode server composes its route surface from — one declaration, both
+ * layers (03 §3).
+ */
+export interface EngineDescriptor {
+  id: EngineId;
+  /** `/api/<apiNamespace>/*` — the fixed server block this engine contributes (03 §1). */
+  apiNamespace: string;
+  views: readonly EngineViewDecl[];
+  ports: readonly PortSpec[];
+  ops: readonly EngineOpDecl[];
+  fills: readonly EngineFillDecl[];
+  /** feature key → capability key it depends on. `effective(f) = features[f] ∧ capabilities[dep(f)]`. */
+  capabilityDeps: Readonly<Record<string, string>>;
+  /** Features that require an RBAC permission on their mixin sub-block (02 §4.4). */
+  privilegedFeatures: Readonly<Record<string, string>>;
+  /** Heavy bundle tiers keyed by the feature that pulls them (V5). */
+  featureTiers: Readonly<Record<string, readonly string[]>>;
+  /** Routes served under `/api/<ns>/` that exist only when a feature is effective-on. */
+  routeFeatureGates?: Readonly<Record<string, string>>;
+}
+
+/* ------------------------------------------------------- external inputs */
+
+/** A registered data source referenced by a `data:<sourceId>` endpoint (V1/V5). */
+export interface SourceDecl {
+  id: string;
+  token: string;
+  /** `false` ⇒ export ERROR `non-exportable-source` (studio: warning). */
+  exportable: boolean;
+  /** `external` payloads may only enter through a registered marshaller (02 §7.1). */
+  format?: 'canonical' | 'external';
+  /** Declared inbound item count — named by the `media-degraded-progressive` INFO. */
+  itemCount?: number;
+  description?: string;
+}
+
+/**
+ * A port a staging module grafts onto its target engine's instances while the
+ * module's `featureKey` is effective-on (02 §3.2). Declared by token id rather
+ * than by object reference: the token itself is harvested from the same file, so
+ * it does not exist until the registry accepts it.
+ */
+export interface StagingPortDecl {
+  id: string;
+  tokenId: string;
+  direction: 'in' | 'out';
+  required?: boolean;
+  subscribesAtMount?: boolean;
+  emission?: 'versioned';
+  scopes?: readonly string[];
+  scopeFilter?: readonly string[];
+  stormBudgetPerWindow?: number;
+}
+
+/** A harvested staging module manifest (02 §3.2) plus its token extensions. */
+export interface StagingCatalog {
+  pluginId: string;
+  targetEngine?: EngineId;
+  featureKey?: string;
+  tokens: readonly TokenDef[];
+  ports?: readonly StagingPortDecl[];
+  /** Absolute path of the harvested file — named by `staging-token-file-invalid`. */
+  path: string;
+}
+
+/* --------------------------------------------- storage contract (V6) */
+
+export interface StorageColumnDecl {
+  name: string;
+  type: string;
+  notNull?: boolean;
+}
+
+export interface StorageTableDecl {
+  name: string;
+  database: string;
+  columns: readonly StorageColumnDecl[];
+  /** Row-scoped by user as well as tenant (spine items, secrets). */
+  userScoped?: boolean;
+  /** Declared query shapes that must be covered by an index (V6 `missing-declared-index`). */
+  declaredQueries?: readonly { readonly columns: readonly string[] }[];
+  indexes?: readonly { readonly name: string; readonly columns: readonly string[] }[];
+  /** SaaS: the RLS policy / namespace guarding the table. */
+  rlsPolicy?: string;
+  /** Rows are signature-chained (01 §2.7) — required for secrets/ports/meter_events. */
+  rowSignature?: boolean;
+  /** Table holds a plaintext secret column — always fatal (V6 `legacy-vault-detected`). */
+  plaintextSecretColumns?: readonly string[];
+}
+
+export interface StorageMigrationDecl {
+  /** Must be `<domain>/<nnnn>_<name>` (V6 `migration-namespace-missing`). */
+  id: string;
+  targetDatabase: string;
+  /** True when the migration issues DDL (used by the shared-db and staging-escape gates). */
+  ddl: boolean;
+  /** The package issuing it — only the station may run DDL on `cc-registry.db`. */
+  issuedBy: 'station' | 'app' | 'staging';
+}
+
+export interface StorageContract {
+  tables: readonly StorageTableDecl[];
+  migrations: readonly StorageMigrationDecl[];
+  /** Pragma profile actually asserted at open — compared against CC_PRAGMAS (01 §1.2). */
+  pragmas: Readonly<Record<string, string | number>>;
+  /** The Maximum Transaction Lifetime Guard is installed and armed (01 §1.2 / J5-3). */
+  transactionLifetimeGuardMs?: number;
+  /** Port allocation implementation shape — `read-then-write` is the TOCTOU pattern (J4-C). */
+  portAllocation: 'socket-probed-insert-unique-retry' | 'read-then-write';
+  /** Key material representation in the secrets path (01 §3.4). */
+  keyMaterial: 'binary-buffer' | 'string';
+  /** Secret envelope AAD binding — must bind (app_id, key). */
+  envelopeAad?: readonly string[];
+  /** Backup strategy — a live-DB tar is never safe (01 §5.3). */
+  backup: 'vacuum-into' | 'live-db-tar' | 'none';
+  /** Telemetry writer declarations (01 §4.1). */
+  telemetry: {
+    meterEventsSpillPath: boolean;
+    apiCallsAwaitedOnRequestPath: boolean;
+  };
+  /** SaaS connection pooling (01 §2.5 / J5-4). */
+  saasConnectionPool?: 'single-shared-capped' | 'per-request' | 'multiple';
+  /** A promotion is being attempted while a registered app holds the DB open (J1-C). */
+  promotionAgainstLiveDb?: boolean;
+  /** Legacy `Vault`/`Unlock`-era tables still present anywhere. */
+  legacyVaultTables?: readonly string[];
+}
+
+/* ------------------------------------------------------ pipeline input */
+
+export interface CodeContractDeclarations {
+  /** Internal automation call sites that use unstructured completion (V3 / 03 §7.2). */
+  unstructuredInternalCompletions?: readonly { site: string; note?: string }[];
+  /** ExecutionDriver call sites passing raw argv strings (V4 / 03 §7.1). */
+  rawArgvExecSites?: readonly { site: string }[];
+  /** `exec` references outside the DevStudio mixin (V4). */
+  execOutsideDevMixin?: readonly { site: string }[];
+  /** Engine modules importing another engine's store (V4 `cross-engine-state-write`). */
+  crossEngineStateWrites?: readonly { site: string; targetEngine: EngineId }[];
+  /** Declared raw-payload buffering for unrendered panes (banned, R-4). */
+  payloadBufferingSites?: readonly { site: string }[];
+  /** Pane subscriptions with no unmount teardown (V4 `pane-subscription-leak`). */
+  paneSubscriptionsWithoutTeardown?: readonly { site: string }[];
+  /** Cycles damped by reference equality rather than by envelope `rev` (R-5, V4). */
+  referenceEqualityDampingSites?: readonly { site: string; connection?: string }[];
+  /** `<instanceId>:<portId>` inputs that declare mount-refetch equivalence (V4 replay audit). */
+  mountRefetchEquivalentPorts?: readonly string[];
+  /** Static event-bus handler graph incl. hook interceptors (03 §6.4). */
+  eventHandlers?: readonly EventHandlerDecl[];
+  /** Bus handlers emitting synchronously into the port hub (V4 `bus-to-hub-sync-emit`). */
+  busToHubSyncEmitSites?: readonly { site: string }[];
+  /** Instances whose global-stylesheet dependency is inlined into a shadow root (V5). */
+  stylesheetDuplicationSites?: readonly { instanceId: string; site: string }[];
+  /** Instances importing a global `.css` (V5 `css-isolation-missing`). */
+  globalStylesheetImports?: readonly { instanceId: string; site: string }[];
+  /** Virtualized views NOT wrapped in `CCResizeBoundary` (V5, J5-1). */
+  virtualizedWithoutBoundary?: readonly { instanceId: string; view: string }[];
+  /** Heavy tiers actually present in the built bundle (V5 `bundle-tier-mismatch`). */
+  bundledTiers?: readonly string[];
+  /** Views shipped without a React.lazy boundary (V5 `lazy-boundary-missing`). */
+  eagerHeavyViews?: readonly { instanceId: string; view: string }[];
+  /**
+   * Emitted app sources scanned for runtime plugin-registration calls (V5
+   * `generated-app-plugin-loader`, 02 §1.4). The generator hands its own output
+   * here; the same scan runs at generation time so a violation never reaches disk.
+   */
+  generatedSources?: readonly { path: string; source: string }[];
+}
+
+export interface EventHandlerDecl {
+  /** Handler id — an engine subscriber or a `CCHookInterceptor`. */
+  id: string;
+  subscribes: string;
+  emits: readonly string[];
+  /** A handler that terminates the chain (depth guard exit) rather than re-emitting. */
+  depthGuarded?: boolean;
+}
+
+/** Registry / .env / config precedence inputs for the V6 drift check (01 §3.2). */
+export interface ConfigProvenance {
+  registryPort?: number;
+  envPort?: number;
+  deployEnvPort?: number;
+  manifestDefaultPort?: number;
+}
+
+export interface VerifyInput {
+  /** Raw, unparsed config — V0 owns the parse. */
+  config: unknown;
+  moment: VerifyMoment;
+  /** Live host probe (studio/boot) or pinned fixture profile (CI). Export uses deployTarget. */
+  capabilities?: CapabilityProfile;
+  /** Root to harvest every `plugin-*` staging package's `*.token-extension.ts` catalogs from. */
+  stagingRoot?: string;
+  /** Registered sources for `data:<sourceId>` endpoints. */
+  sources?: readonly SourceDecl[];
+  storage?: StorageContract;
+  code?: CodeContractDeclarations;
+  provenance?: ConfigProvenance;
+  /** Overrides the engine catalog (fixtures/tests inject a narrower one). */
+  engines?: readonly EngineDescriptor[];
+  /** Marshallers registered for this compilation — the external-payload seam (02 §7.1). */
+  marshallers?: readonly CCWireMarshaller[];
+  /** Injected file reader — the harvester's retry seam (J4-A). */
+  readStagingFile?: (path: string) => Promise<string>;
+}
+
+/* ----------------------------------------------------- pipeline output */
+
+export interface MaterializedPort {
+  spec: PortSpec;
+  /** Result of `enabledWhen(effective, profile)` — false ⇒ the port does not exist. */
+  enabled: boolean;
+}
+
+export interface EffectiveInstance {
+  id: string;
+  engine: EngineId;
+  title?: string;
+  effective: EffectiveFeatureMap;
+  /** Stable hash of the effective feature set — Slot keys (02 §6.1) and bundleKey (V5). */
+  effectiveFeaturesHash: string;
+  ports: readonly MaterializedPort[];
+  routes: readonly RouteDecl[];
+  fills: readonly FillDecl[];
+  cssIsolation: 'none' | 'scope' | 'shadow';
+  /** Ops callable on this instance — the server allowlist mirror of the port rule (03 §3.2). */
+  ops: readonly EngineOpDecl[];
+}
+
+export interface EffectiveManifest {
+  appId: string;
+  title: string;
+  profile: 'local' | 'saas';
+  moment: VerifyMoment;
+  engines: readonly EngineId[];
+  instances: readonly EffectiveInstance[];
+  connections: readonly { from: string; to: string; cyclic: boolean }[];
+  /** Compiled `connect-src` allowlist injected into the pinned CSP (03 §2.4). */
+  cspConnectAllowlist: readonly string[];
+  /** Sorted engine ids + effective feature sets + media/ffmpeg tier (V5). */
+  bundleKey: string;
+  /** Heavy tiers that must be present in the bundle iff effective-on. */
+  requiredTiers: readonly string[];
+  capabilities: CapabilityProfile;
+  /** Where `capabilities` came from — the only sanctioned per-moment divergence. */
+  capabilitySource: 'live-probe' | 'deploy-target' | 'pinned-fixture';
+  /** Token ids reachable from the app, staging extensions included. */
+  tokenIds: readonly string[];
+  stagingCatalogs: readonly StagingCatalog[];
+  /**
+   * The app's theme, carried from `AppConfig.theme` (owner decision E7).
+   *
+   * It is on the manifest because the manifest is what the GENERATOR reads:
+   * `emitStylesCss(manifest)` writes `overrides` into the app's stylesheet as a
+   * `:root` block. Before this field existed, `AppConfigSchema.theme.overrides`
+   * was a documented CSS custom-property map that V2 dropped on the floor —
+   * every generated app rendered the default accent no matter what its config
+   * said, and the migrator emitted a `theme-not-consumed` warning to say so.
+   * Both halves are plain JSON, so the frozen-manifest codec round-trips them
+   * with no special handling.
+   */
+  theme: { preset: string; overrides: Readonly<Record<string, string>> };
+}
+
+export interface VerifyResult {
+  /** Null when V0 failed hard — there is nothing to build a manifest from. */
+  manifest: EffectiveManifest | null;
+  diagnostics: readonly Diagnostic[];
+  /** No ERROR diagnostics. The disposition per moment is the caller's (04 §1). */
+  ok: boolean;
+  /** Last stage that ran; a stage only runs when every earlier stage was error-free. */
+  lastStage: 'V0' | 'V1' | 'V2' | 'V3' | 'V4' | 'V5' | 'V6' | 'V7';
+}
+
+export const errorsOf = (diagnostics: readonly Diagnostic[]): Diagnostic[] =>
+  diagnostics.filter((d) => d.severity === 'error');
+
+/** Numeric assertions compare with this buffer — never exact float equality (04 §4). */
+export const VERIFY_EPSILON = 1e-5;
+
+export const withinEpsilon = (a: number, b: number, epsilon: number = VERIFY_EPSILON): boolean =>
+  Math.abs(a - b) <= epsilon;

package/src/workspace.css

@@ -0,0 +1,146 @@
+/*
+ * cursedbelt — the WORKSPACE stylesheet. Opt-in, and separate from `styles.css`
+ * on purpose.
+ *
+ * `styles.css` is the layer every consumer needs whether it knows it or not:
+ * the dialog family's motion, the tooltip pointer-events fix, the ambient/glass
+ * classes. This file is the layer only a DENSE, DATA-HEAVY surface needs — an
+ * admin grid, a queue, a fleet table. A public WebGL studio with one canvas and
+ * three controls should not ship a table framework, and the byte budgets in
+ * `cursed-satellites/scripts/assetBudget.test.ts` are what noticed: adding these
+ * rules to the always-imported sheet pushed three apps over their CSS backstop
+ * at once, none of which render a table.
+ *
+ * Consume it beside the other two, in an app that has a workspace surface:
+ *
+ *   @import "tailwindcss";
+ *   @import "cursedbelt/styles.css";     (or belt-static.css, scoped apps)
+ *   @import "cursedbelt/theme.css";
+ *   @import "cursedbelt/workspace.css";  ← this file
+ *
+ * It carries NO `@source`, so it costs a scoped app nothing but its own bytes.
+ * The tokens these rules read (`--row-pad-*`, `--rule`, `--text-data`,
+ * `--glow-focus`, and the `.cb-dense` scope) live in `theme.css` with every
+ * other token — a token is cheap and belongs with its family; a rule that
+ * paints forty table cells is what actually costs bytes.
+ */
+
+/* Tabular numerals for anything a person reads DOWN a column: dates, sizes,
+   counts, ids, hashes, durations. Proportional digits make every row a different
+   width, so the eye has to re-find the start of each value; tabular digits lock
+   them to one grid and a column of timestamps becomes scannable at a glance.
+   Unlike `.cb-code` this paints no surface — it is a typographic setting for
+   inline data, not a code block. `0.94em` keeps a mono glyph optically the same
+   size as the proportional text beside it (mono faces run visually larger at an
+   identical px), so a cell can mix `Aug 7, 2026` and prose without a step. */
+.cb-num {
+  font-family: var(--font-mono, ui-monospace, SFMono-Regular, Menlo, Consolas, monospace);
+  font-variant-numeric: tabular-nums;
+  font-size: 0.94em;
+  letter-spacing: -0.01em;
+}
+
+/*
+ * ── The dense data grid ─────────────────────────────────────────────────────
+ * `.cb-table` on a <table> is the whole high-density grid system: a quiet sticky
+ * header, 13px rows on the shared row rhythm, and hairline INTERNAL rules.
+ *
+ * Three decisions worth keeping:
+ *   • `border-collapse: separate` — a collapsed table draws its borders in a
+ *     layer that a `position: sticky` header scrolls UNDER, so the header ends up
+ *     with rows bleeding through its top edge. Separate + a per-cell border-top
+ *     is the fix, not a preference.
+ *   • rules come from `--rule`, never `--border` — repeating a card's ENCLOSURE
+ *     hairline down forty rows reads as forty boxes instead of one surface.
+ *   • padding comes from `--row-pad-*`, so `.cb-dense` compresses every table in
+ *     the app at once and no call site hardcodes a py-2.
+ */
+.cb-table {
+  width: 100%;
+  border-collapse: separate;
+  border-spacing: 0;
+  font-size: var(--text-data, 0.8125rem);
+  color: var(--foreground);
+}
+
+.cb-table thead th {
+  position: sticky;
+  top: 0;
+  z-index: var(--z-sticky, 100);
+  text-align: left;
+  white-space: nowrap;
+  font-size: var(--text-caption, 0.75rem);
+  font-weight: 600;
+  text-transform: uppercase;
+  letter-spacing: 0.06em;
+  color: var(--muted-foreground);
+  padding: var(--row-pad-y, 0.5rem) var(--row-pad-x, 1rem);
+  /* Opaque, not translucent: rows scrolling beneath a see-through header is the
+     single most common "cheap table" tell. The blur is what keeps it from
+     reading as a second, heavier surface stacked on the card. */
+  background: var(--card);
+  backdrop-filter: blur(6px);
+  -webkit-backdrop-filter: blur(6px);
+  border-bottom: 1px solid var(--border);
+}
+
+.cb-table tbody td {
+  padding: var(--row-pad-y, 0.5rem) var(--row-pad-x, 1rem);
+  border-top: 1px solid var(--rule);
+  vertical-align: middle;
+}
+
+.cb-table tbody tr:first-child td {
+  border-top: 0;
+}
+
+/* Row hover is a READING aid on a wide grid — it ties the far-right cell back to
+   the name on the far left. Tinted from --muted so it lands correctly in every
+   theme, and kept well below the selected state so the two never compete. */
+.cb-table tbody tr:hover td {
+  background: color-mix(in srgb, var(--muted) 55%, transparent);
+}
+
+.cb-table tbody tr[data-selected="true"] td {
+  background: color-mix(in srgb, var(--accent) 10%, transparent);
+}
+
+/* Sticky first column, for a matrix wider than the viewport: the WHO column has
+   to stay put or a horizontal scroll turns every row into an anonymous line of
+   badges. Opt-in per table (`.cb-table--pin-first`) because it costs a
+   background paint on every cell in that column. */
+.cb-table--pin-first thead th:first-child,
+.cb-table--pin-first tbody td:first-child {
+  position: sticky;
+  left: 0;
+  background: var(--card);
+  z-index: 1;
+}
+.cb-table--pin-first thead th:first-child {
+  z-index: calc(var(--z-sticky, 100) + 1);
+}
+.cb-table--pin-first tbody tr:hover td:first-child {
+  background: color-mix(in srgb, var(--muted) 55%, var(--card));
+}
+.cb-table--pin-first tbody tr[data-selected="true"] td:first-child {
+  background: color-mix(in srgb, var(--accent) 10%, var(--card));
+}
+
+/*
+ * The focused-control halo (`--glow-focus`, theme.css) as a class, so a bespoke
+ * control — a cell trigger, a card that opens a panel, a custom combobox — gets
+ * the product's focus treatment without re-deriving the shadow. `focus-visible`
+ * only: a MOUSE click on a button must not leave a glow behind it, which is the
+ * bug a plain `:focus` version of this would ship everywhere at once.
+ */
+.cb-focus-glow:focus-visible {
+  outline: none;
+  box-shadow: var(--glow-focus);
+}
+
+/* The wrapper form of the same thing: a field group (label + input + affix) that
+   should light up as one unit when the input inside it takes focus. */
+.cb-focus-glow-within:focus-within {
+  outline: none;
+  box-shadow: var(--glow-focus);
+}