cursedbelt 2.8.0 → 3.0.0

package/src/react/studios/types.ts

@@ -1,792 +0,0 @@
-// cursedbelt/react/studios — the engine PRESENTATION SHELLS (02 §1, Phase-2 client
-// layer). The framework already ships the primitives every studio composes — the
-// Slot/Fill coordinator, the CCPortalProvider focus stack, CCResizeBoundary, the
-// CCDataLink locator link, the SPA router table, and the heavy `react/media`
-// component set. What was missing (Set 7 §6: "primitives only — no app shell composes
-// them") is the top-level view that reads an instance's EFFECTIVE feature manifest and
-// wires those primitives into the canonical AssetStudio / KnowledgeStudio layouts.
-//
-// These shells are pure presentation: data arrives via props (the framework has no
-// production services yet — Set 7 §0), so an app resolves rows against its own
-// `*Service` and hands them down. Because the shells pull the heavy `react/media`
-// libraries, this is a DEDICATED entry (`cursedbelt/react/studios`), never the main
-// `react` barrel — an app that shows no studios never bundles them, exactly like
-// `react/media` and `react/charts`.
-
-import type { ReactNode } from 'react';
-import type { EngineId, SignupMode } from '../../config/appConfig';
-import type { CCRole, CCUserClaims } from '../../core/session/claims';
-import type { AccountMember, AccountSession } from '../data/accountClient';
-import type {
-  AuditEntryView,
-  BudgetEntryView,
-  BudgetView,
-  ContactView,
-  FamilyEventView,
-  KanbanBoardView,
-  KanbanCardView,
-  KanbanColumnView,
-  ListCellValue,
-  ListCellView,
-  ListColumnType,
-  ListColumnView,
-  ListRowView,
-  ListView,
-  PartnershipView,
-  PersonView,
-  RecordDetailView,
-  RecordView,
-  RecordingView,
-  SegmentView,
-  SubscriptionCadence,
-  SubscriptionView,
-  TimeOffLedgerView,
-  TimeOffPolicyView,
-  TimeOffRequestView,
-} from '../../server/mixins/services';
-import type { FillContribution } from '../slots/Slot';
-import type { EffectiveFeatureMap } from '../../verify/types';
-import type { MediaItem } from '../../core/media/types';
-import type { MediaCatalogueLayout } from '../media/types';
-import type { PrivateUnlock } from '../media/usePrivateUnlock';
-
-/**
- * The slice of an `EffectiveInstance` (02 §V2 manifest) a studio shell needs. We take
- * the resolved shape, never the raw config: `effective` is the post-V2 feature map
- * (defaults applied, cross-engine rules enforced) and `effectiveFeaturesHash` is the
- * stable hash the Slot coordinator (02 §6.1) and these shells key on so any feature or
- * role toggle forces a clean remount instead of bleeding a stale closure.
- */
-export interface StudioInstance {
-  id: string;
-  engine: EngineId;
-  title?: string;
-  effective: EffectiveFeatureMap;
-  effectiveFeaturesHash: string;
-  cssIsolation?: 'none' | 'scope' | 'shadow';
-}
-
-/** A folder node for the AssetStudio `fileBrowser` rail (File Gallery, 02 §1.1). */
-export interface AssetFolder {
-  id: string;
-  name: string;
-  /** Item count shown next to the folder, when the source knows it. */
-  count?: number;
-  /** Nesting depth (0 = root child) — the rail indents by this. */
-  depth?: number;
-}
-
-/**
- * The vault-upload controller (03 §1c) — the near side of
- * `POST /api/asset/vault/upload`.
- *
- * It is OPTIONAL for one structural reason: that route is mounted only when an
- * asset instance has `vaultSource` effective-on (R-3, composition-time absence).
- * With the feature off the prop is absent, the shell renders no affordance at
- * all, and there is no control whose every use would be a correct 404.
- *
- * `deduped` is carried on the RESULT rather than surfaced as an error: uploading
- * bytes the vault already holds is a success (the content-addressed asset is
- * returned), and a user who dragged the same photo twice deserves to be told
- * which of the two things happened.
- */
-export interface AssetUploadState {
-  /** Stream these files to the vault route — one request each, in order. */
-  onUpload: (files: readonly File[]) => void;
-  /** A request is in flight; the picker and drop zone refuse new files. */
-  busy?: boolean;
-  /** The last failure, rendered ON the control (not in the app-error overlay). */
-  error?: string | null;
-  /** The last completed file — `deduped` means it matched an existing asset. */
-  lastResult?: { fileName: string; deduped: boolean } | null;
-  /** File-picker `accept` filter (e.g. `image/*`). Omit to accept any file. */
-  accept?: string;
-}
-
-export interface AssetStudioShellProps {
-  instance: StudioInstance;
-  /** URL-only media rows (the app pre-resolves/signs URLs — 00-README invariant #3). */
-  items: MediaItem[];
-  /** Folders for the `fileBrowser` rail; omit to render the flat catalogue. */
-  folders?: AssetFolder[];
-  activeFolderId?: string;
-  onSelectFolder?: (folderId: string) => void;
-  onSelectItem?: (item: MediaItem) => void;
-  /**
-   * Delete one item (03 §1, D26's other half).
-   *
-   * ABSENT ⇒ no delete affordance is rendered, which is the R-3 shape every
-   * other optional surface here follows: a button that 404s is worse than no
-   * button. `MediaCell` has had the control since it was written; nothing ever
-   * passed a handler, so `DELETE /api/asset/items/:id` — the route that posts
-   * the NEGATIVE storage credit — was reachable by an API client and not by a
-   * user. Until this landed, a tenant could fill their plan and had no way to
-   * empty it.
-   */
-  onDeleteItem?: (item: MediaItem) => void;
-  /** Total available (drives the "N of M" hint + load-more arming). */
-  totalCount?: number;
-  loading?: boolean;
-  /** Fired once when the viewport nears the last row (infinite scroll). */
-  onLoadMore?: () => void;
-  /**
-   * Override the catalogue layout. Omit to derive it from `features.galleryLayouts`
-   * (masonry when the instance opted into masonry mode — the absorbed Photo Gallery).
-   */
-  layout?: MediaCatalogueLayout;
-  /**
-   * The private-media controller (`usePrivateUnlock`). Only rendered when
-   * `features.privateMedia` is effective-on; the shell shows the guarded cleanup
-   * index, never raw private bytes through a public route (Set 7 finding 4.3).
-   */
-  privateUnlock?: PrivateUnlock;
-  /**
-   * The vault upload controller (03 §1c). Absent ⇒ `vaultSource` is off for this
-   * instance and the upload route does not exist, so nothing is rendered.
-   */
-  upload?: AssetUploadState;
-  className?: string;
-  emptyState?: ReactNode;
-}
-
-/* ------------------------------------ asset detail surfaces (03 §1e) */
-
-/**
- * The `video-detail` surface — ONE item, named by the route's `videoId`.
- *
- * `item` and `missing` are separate rather than one nullable field because the
- * three states a detail screen has are genuinely three: still loading (`item`
- * null, `missing` false), settled-with-nothing (`missing` true — deleted,
- * foreign, or sealed, all indistinguishable by design), and loaded. Collapsing
- * the first two shows "not found" for a quarter-second on every navigation.
- */
-export interface VideoDetailShellProps {
-  instance: StudioInstance;
-  item: AssetDetailItem | null;
-  missing?: boolean;
-  loading?: boolean;
-  className?: string;
-}
-
-/**
- * One catalogue item as a detail surface renders it. Distinct from `MediaItem`
- * (the catalogue tile) because a detail surface needs the ADAPTIVE url too: a
- * player handed only `streamUrl` downloads the original 4K master to show a
- * thumbnail-sized preview, which is the whole reason the HLS ladder exists.
- */
-export interface AssetDetailItem {
-  id: string;
-  name: string;
-  kind: 'video' | 'photo' | 'file';
-  /** Progressive bytes URL. Always present — resolved by the SERVER, never assembled here. */
-  streamUrl: string;
-  /** HLS master; present only when the item has a rendition AND `hls` is effective-on. */
-  hlsUrl?: string;
-}
-
-/**
- * One row of an editor's picker rail: an id, a label, and the PROGRESSIVE bytes
- * URL. Not `MediaItem` — an editor reads these bytes with `fetch`/`<canvas>`, so
- * it needs a URL it can decode, and handing it a catalogue tile whose `url` may
- * be an HLS master would give it an m3u8 to paint.
- */
-export interface AssetEditorItem {
-  id: string;
-  name: string;
-  url: string;
-  thumbnailUrl?: string;
-}
-
-/**
- * The `video-editor` surface — pick a video, choose a range, export.
- *
- * The export runs in the BROWSER on ffmpeg.wasm and the result is uploaded as a
- * new asset; that is what the view's declared tiers (`ffmpeg.wasm`, `editor`)
- * mean, and it is why `onExport` hands back a range rather than a server job id.
- * The original is never touched — an export adds an asset (03 §1e).
- */
-export interface VideoEditorShellProps {
-  instance: StudioInstance;
-  /** Catalogue videos this instance can edit. */
-  videos: readonly AssetEditorItem[];
-  activeId?: string;
-  onSelect?: (id: string) => void;
-  /** Render + upload the chosen range. Resolves once the new asset has landed. */
-  onExport?: (spec: VideoExportSpec) => Promise<void>;
-  exporting?: boolean;
-  /** 0–100 across the whole render, or null when nothing is rendering. */
-  progress?: number | null;
-  error?: string | null;
-  lastExport?: { fileName: string } | null;
-  loading?: boolean;
-  className?: string;
-}
-
-export interface VideoExportSpec {
-  startSeconds: number;
-  endSeconds: number;
-  format: 'mp4' | 'webm';
-  quality: 'high' | 'medium' | 'low';
-}
-
-/**
- * The `image-studio` surface — pick an image, edit it, save it as a NEW asset.
- *
- * `onSave` takes the edited bytes, not a spec: the editor's client mode yields a
- * Blob, and the app's job (per `ImageEditorProps`) is the upload. The server
- * pipeline mode is deliberately unused here — no engine route accepts an
- * `ImagePipelineSpec`, and pointing the editor at one would be an affordance
- * whose every use is a 404 (Law #1).
- */
-export interface ImageStudioShellProps {
-  instance: StudioInstance;
-  images: readonly AssetEditorItem[];
-  activeId?: string;
-  onSelect?: (id: string) => void;
-  onSave?: (input: { blob: Blob; fileName: string }) => Promise<void>;
-  saving?: boolean;
-  error?: string | null;
-  lastSaved?: { fileName: string } | null;
-  loading?: boolean;
-  className?: string;
-}
-
-/** The six flat-spine record kinds KnowledgeStudio absorbs (01 §2.1, `k_items`). */
-export type KnowledgeSpineKind = 'note' | 'todo' | 'bookmark' | 'worklog' | 'habit' | 'article';
-
-/**
- * One row of the KnowledgeStudio note spine. Shared columns are real fields (title,
- * updatedAt); type-specific columns ride an optional satellite object per kind (01
- * §2.1 — satellite tables, not an attribute bag). `links` are `cc://` locators the
- * detail panel renders through {@link CCDataLink}, never raw hrefs (03 §4).
- */
-export interface KnowledgeSpineItem {
-  id: string;
-  kind: KnowledgeSpineKind;
-  title: string;
-  /** Epoch ms — the spine sorts newest-first. */
-  updatedAt: number;
-  snippet?: string;
-  todo?: { done: boolean; priority?: number; dueAt?: number };
-  bookmark?: { url: string; tags?: readonly string[] };
-  worklog?: { day: string; minutes: number };
-  habit?: { cadence: string; streak: number };
-  article?: { status: string; source?: string };
-  /** `cc://<engine>/<id>` locators for cross-feature links (e.g. an asset ref). */
-  links?: readonly string[];
-}
-
-export interface KnowledgeStudioShellProps {
-  instance: StudioInstance;
-  items: KnowledgeSpineItem[];
-  /** The selected row (master-detail). Omit to let the shell pick the first row. */
-  activeId?: string;
-  onSelect?: (id: string) => void;
-  totalCount?: number;
-  loading?: boolean;
-  onLoadMore?: () => void;
-  className?: string;
-  emptyState?: ReactNode;
-}
-
-/* -------------------------------- knowledge detail surfaces (03 §1e) */
-
-/**
- * The `note` surface — ONE record, named by the route's `noteId`, WITH its body
- * and satellite (the fields `RecordView` deliberately omits from a listing).
- *
- * Editing is title + body only. The satellites are rendered read-only because
- * their writers are `updateRecordFull`-shaped repo ops with no route behind them
- * yet: a form that PATCHed `{ todo: { done } }` would post a field
- * `/api/knowledge/entity/:id` drops on the floor, which is worse than no control.
- */
-export interface NoteDetailShellProps {
-  instance: StudioInstance;
-  record: NoteRecord | null;
-  missing?: boolean;
-  loading?: boolean;
-  onSave?: (patch: { title: string; bodyMd: string }) => void;
-  saving?: boolean;
-  saveError?: string | null;
-  className?: string;
-}
-
-/** What the note surface renders — the wire detail shape, re-exported for shells. */
-export type NoteRecord = RecordDetailView;
-
-/** One exchange in the retrieval conversation. */
-export interface ConversationTurn {
-  id: string;
-  question: string;
-  /** The records retrieval matched, in rank order. Empty ⇒ nothing matched. */
-  hits: readonly RecordView[];
-  /** Set when this turn's search failed; the turn stays in the transcript. */
-  error?: string;
-  pending?: boolean;
-}
-
-/**
- * The `conversation` surface — retrieval chat over the corpus (`ragChat`).
- *
- * **The transcript is session-local and that is disclosed, not hidden.** There is
- * no `conversations` table in any domain DDL, so there is nothing to persist to;
- * `conversationId` (from the route) keys the in-memory transcript so two
- * conversations never blend, and a reload starts a fresh one. Persisting it is a
- * DDL + repository + service job, and inventing a fake "saved" affordance over
- * storage that does not exist is the orphan seam Law #1 forbids.
- */
-export interface ConversationShellProps {
-  instance: StudioInstance;
-  conversationId?: string;
-  turns: readonly ConversationTurn[];
-  onAsk?: (question: string) => void;
-  pending?: boolean;
-  className?: string;
-}
-
-/** One side of the text compare: a chosen record (or free text) plus its content. */
-export interface TextComparePane {
-  /** The selected record's id, or undefined when the pane holds free text. */
-  recordId?: string;
-  text: string;
-}
-
-/**
- * The `text-compare` surface — a line diff between two texts (`textCompare`).
- *
- * It needs no server route of its own: both sides are either a record this
- * instance already reads or text the user pasted, and the comparison itself is
- * `diffLines` from cwip — pure arithmetic over two strings.
- */
-export interface TextCompareShellProps {
-  instance: StudioInstance;
-  /** Records offered in each side's picker. */
-  records: readonly RecordView[];
-  left: TextComparePane;
-  right: TextComparePane;
-  onChangePane?: (side: 'left' | 'right', pane: TextComparePane) => void;
-  /** True while a picked record's body is being read. */
-  loading?: boolean;
-  className?: string;
-}
-
-/* ----------------------------------------- knowledge verticals (03 §1b) */
-
-/**
- * The five hierarchical knowledge verticals are NOT spine rows, so they do not
- * ride `KnowledgeStudioShellProps`: a kanban board, a typed grid, a contact
- * book, a family graph and a transcript are five different shapes, and folding
- * them into the flat `k_items` master-detail would have meant one shell whose
- * props are a union nobody can read.
- *
- * Each shell below is presentation-pure in the same sense as the two landed
- * ones: rows in, callbacks out, no fetch. `KnowledgeStudioView` picks which one
- * the route's view id means and owns every request.
- */
-export interface KanbanShellProps {
-  instance: StudioInstance;
-  boards: readonly KanbanBoardView[];
-  activeBoardId?: string;
-  onSelectBoard?: (boardId: string) => void;
-  /** The active board's columns, in position order. */
-  columns: readonly KanbanColumnView[];
-  /** EVERY card on the active board — the shell buckets them by column. */
-  cards: readonly KanbanCardView[];
-  onCreateBoard?: (title: string) => void;
-  onCreateColumn?: (title: string) => void;
-  onCreateCard?: (columnId: string, title: string) => void;
-  /**
-   * Move a card to another column — the O(1) `knowledge:move-card` op. The
-   * shell only ever names an ADJACENT column: a drag-and-drop tier is a
-   * separate concern, and a board you cannot reorganize without one is not
-   * reachable.
-   */
-  onMoveCard?: (cardId: string, toColumnId: string, position: number) => void;
-  onRemoveCard?: (cardId: string) => void;
-  loading?: boolean;
-  className?: string;
-}
-
-export interface ListGridShellProps {
-  instance: StudioInstance;
-  lists: readonly ListView[];
-  activeListId?: string;
-  onSelectList?: (listId: string) => void;
-  columns: readonly ListColumnView[];
-  /** Rows in list order, or in one column's typed order when `sortColumnId` is set. */
-  rows: readonly ListRowView[];
-  /** Every stored cell of the active list — the grid joins them by `rowId:columnId`. */
-  cells: readonly ListCellView[];
-  /** The column the rows are sorted by (the typed-sort proof), or undefined for list order. */
-  sortColumnId?: string;
-  sortDescending?: boolean;
-  onSort?: (columnId: string | undefined, descending: boolean) => void;
-  onCreateList?: (title: string) => void;
-  onCreateColumn?: (input: { name: string; colType: ListColumnType }) => void;
-  onCreateRow?: () => void;
-  /** Write one typed cell. The shell parses the text to the column's class first. */
-  onSetCell?: (rowId: string, columnId: string, value: ListCellValue) => void;
-  /** The `knowledge:reorder-list-column` op. */
-  onReorderColumn?: (columnId: string, position: number) => void;
-  /** A cell the SERVER refused (a class mismatch), rendered inline on that cell. */
-  cellError?: { rowId: string; columnId: string; message: string } | null;
-  loading?: boolean;
-  className?: string;
-}
-
-export interface ContactsShellProps {
-  instance: StudioInstance;
-  contacts: readonly ContactView[];
-  activeId?: string;
-  onSelect?: (id: string) => void;
-  onCreate?: (input: { displayName: string; birthday?: string }) => void;
-  onRemove?: (id: string) => void;
-  loading?: boolean;
-  className?: string;
-}
-
-export interface FamilyTreeShellProps {
-  instance: StudioInstance;
-  people: readonly PersonView[];
-  partnerships: readonly PartnershipView[];
-  activePersonId?: string;
-  onSelectPerson?: (id: string) => void;
-  /** The selected person's life events. */
-  events: readonly FamilyEventView[];
-  onCreatePerson?: (input: { displayName: string; birth?: string }) => void;
-  onCreateEvent?: (input: { personId: string; kind: string; at?: string }) => void;
-  onCreatePartnership?: (input: { aId: string; bId: string }) => void;
-  loading?: boolean;
-  className?: string;
-}
-
-export interface OralHistoryShellProps {
-  instance: StudioInstance;
-  recordings: readonly RecordingView[];
-  activeId?: string;
-  onSelect?: (id: string) => void;
-  /** The selected recording's transcript segments, in `seq` order. */
-  segments: readonly SegmentView[];
-  onCreateRecording?: (input: { title: string }) => void;
-  onAddSegment?: (input: { startMs: number; endMs: number; transcript: string }) => void;
-  onEditSegment?: (segmentId: string, transcript: string) => void;
-  loading?: boolean;
-  className?: string;
-}
-
-/* ------------------------------------------------- dev / system / guard */
-
-/**
- * What every multi-surface shell shares (04 §5c–§5e).
- *
- * `claims` is REQUIRED rather than optional: a shell whose privileged surfaces
- * disappear when claims are absent must be handed the claims explicitly, so
- * "forgot to pass them" renders the smaller surface rather than the larger one.
- * Fail-closed, in a prop signature.
- */
-export interface StudioShellBaseProps {
-  instance: StudioInstance;
-  claims: CCUserClaims | null;
-  /** The surface to render (the route's view id). Omit to let the shell pick. */
-  view?: string;
-  onSelectView?: (view: string) => void;
-  loading?: boolean;
-  className?: string;
-}
-
-export interface DevAppRow {
-  appId: string;
-  title: string;
-  running: boolean;
-  port?: number;
-}
-
-export interface DevStudioShellProps extends StudioShellBaseProps {
-  apps?: readonly DevAppRow[];
-  fleet?: readonly DevAppRow[];
-  disk?: readonly { path: string; bytes: number }[];
-  onDeploy?: (appId: string) => void;
-  /** The app whose deploy is in flight (drives the button spinner). */
-  deployingAppId?: string | null;
-  /** The loaded config for the selected app — `null` while none is chosen. */
-  config?: { appId: string; text: string } | null;
-  onSelectConfigApp?: (appId: string) => void;
-  onConfigChange?: (text: string) => void;
-  onSaveConfig?: () => void;
-  configSaving?: boolean;
-  /** Domain databases this app can snapshot (`knowledge`, `media`, …). */
-  domains?: readonly string[];
-  onExportDatabase?: (domain: string) => void;
-  exportedSnapshotPath?: string | null;
-
-  /* ------------- the four nav surfaces of 03 §1e's second half ------------- */
-
-  /** Open one app's detail view. Absent ⇒ the Apps rows are not links. */
-  onOpenApp?: (appId: string) => void;
-  /** `docs` surface: every doc every registered app declares. */
-  docs?: readonly DevDocRow[];
-  /** The doc currently open, `null` while none is chosen. */
-  openDoc?: DevDocContent | null;
-  onOpenDoc?: (appId: string, path: string) => void;
-  /** `pipelines` surface: the whitelist and the runs dispatched from it. */
-  pipelines?: readonly DevPipelineRow[];
-  pipelineRuns?: readonly DevPipelineRunRow[];
-  onRunPipeline?: (commandId: string, args: Readonly<Record<string, string>>) => void;
-  runningPipelineId?: string | null;
-  /** `screenshots` surface. `screenshotUrl` resolves a name to its bytes route. */
-  screenshots?: readonly DevScreenshotRow[];
-  screenshotUrl?: (name: string) => string;
-  /** `orchestration` surface: recent terminal job outcomes, newest first. */
-  jobs?: readonly DevJobRow[];
-}
-
-export interface DevDocRow {
-  appId: string;
-  appTitle: string;
-  path: string;
-}
-
-export interface DevDocContent extends DevDocRow {
-  text: string;
-}
-
-export interface DevPipelineRow {
-  id: string;
-  params: readonly string[];
-  timeoutMs?: number;
-}
-
-export interface DevPipelineRunRow {
-  handleId: string;
-  commandId: string;
-  state: 'running' | 'exited' | 'killed' | 'failed';
-  exitCode: number | null;
-  startedAt: number;
-  endedAt: number | null;
-}
-
-export interface DevScreenshotRow {
-  name: string;
-  bytes: number;
-  capturedAt: string;
-  contentType: string;
-}
-
-export interface DevJobRow {
-  jobId: string;
-  ok: boolean;
-  error?: string;
-  at: string;
-  instanceId?: string;
-}
-
-/** The `app-detail` view's subject — one registered app in full. */
-export interface DevAppDetail extends DevAppRow {
-  kind: string;
-  localPath: string;
-  pid?: number;
-  lastBooted?: string;
-  ports: readonly number[];
-  aliases: readonly { name: string; command: string }[];
-  commands: Readonly<Record<string, string>>;
-  docs: readonly string[];
-}
-
-export interface DevAppDetailShellProps {
-  instance: StudioInstance;
-  app: DevAppDetail | null;
-  /** True once a read settled with no such app — distinct from "none selected". */
-  missing?: boolean;
-  loading?: boolean;
-  /** Open one of the app's declared docs on the `docs` surface. */
-  onOpenDoc?: (appId: string, path: string) => void;
-  className?: string;
-}
-
-export interface SystemCalendarEvent {
-  id: string;
-  title: string;
-  /** ISO timestamp, exactly as `/api/system/calendar` returns it. */
-  startsAt: string;
-  endsAt?: string;
-}
-
-export interface SystemNotificationRow {
-  id: string;
-  title: string;
-  body?: string;
-  done: boolean;
-}
-
-export interface SystemUtilityShellProps extends StudioShellBaseProps {
-  /**
-   * `DashboardWidget` fills — the canonical Slot host (02 §6.1). The shell
-   * passes claims straight through, so a widget whose fill declares a permission
-   * the session lacks is never constructed.
-   */
-  fills?: readonly FillContribution[];
-  events?: readonly SystemCalendarEvent[];
-  notifications?: readonly SystemNotificationRow[];
-  onMarkNotificationDone?: (id: string) => void;
-  /** The month the calendar opens on. Omit for the current month. */
-  month?: Date;
-  onMonthChange?: (month: Date) => void;
-  /** Request-builder send; the SERVER performs it (CSP + SSRF guard, 02 §1.5). */
-  onSendHttp?: (spec: { url: string; method: string }) => void;
-  httpResult?: { status: number; body: string } | null;
-  httpSending?: boolean;
-
-  /* ---- the three data surfaces (03 §1b) -------------------------------- */
-  /**
-   * Time off, budgets and subscriptions arrive as ONE state object each rather
-   * than as a dozen loose props: they are three independent surfaces of the same
-   * shell, and flattening them would make the shell's signature the union of
-   * three unrelated screens.
-   */
-  timeOff?: TimeOffSurfaceState;
-  budgets?: BudgetSurfaceState;
-  subscriptions?: SubscriptionSurfaceState;
-}
-
-export interface TimeOffSurfaceState {
-  policies: readonly TimeOffPolicyView[];
-  requests: readonly TimeOffRequestView[];
-  ledger: readonly TimeOffLedgerView[];
-  /** The folded ledger balance in days (negative ⇒ net debited). */
-  balance: number;
-  onCreatePolicy?: (input: { title: string; accrualDays?: number }) => void;
-  onCreateRequest?: (input: { policyId?: string; startsOn: string; endsOn: string; days: number }) => void;
-  /** The `system:approve-timeoff` / `deny-timeoff` / `cancel-timeoff` ops. */
-  onDecide?: (id: string, decision: 'approve' | 'deny' | 'cancel') => void;
-  decidingId?: string | null;
-}
-
-export interface BudgetSurfaceState {
-  budgets: readonly BudgetView[];
-  activeBudgetId?: string;
-  onSelectBudget?: (id: string) => void;
-  /** The active budget's entries. */
-  entries: readonly BudgetEntryView[];
-  onCreateBudget?: (input: { title: string; amountCents: number }) => void;
-  onCreateEntry?: (input: { occurredOn: string; amountCents: number; note?: string }) => void;
-  onRemoveEntry?: (id: string) => void;
-}
-
-export interface SubscriptionSurfaceState {
-  subscriptions: readonly SubscriptionView[];
-  includeCancelled: boolean;
-  onToggleCancelled?: (include: boolean) => void;
-  onCreate?: (input: { title: string; amountCents: number; cadence: SubscriptionCadence }) => void;
-  /** The idempotent `system:cancel-subscription` op. */
-  onCancel?: (id: string) => void;
-  cancellingId?: string | null;
-}
-
-export interface GuardSecretRow {
-  key: string;
-  updatedAt: string;
-}
-
-export interface GuardEngineShellProps extends StudioShellBaseProps {
-  /** True when the private scope is currently unlocked for this session. */
-  unlocked: boolean;
-  /** Submit a passphrase. The shell never keeps it — see the shell's own note. */
-  onUnlock?: (passphrase: string) => void;
-  onLock?: () => void;
-  unlockError?: string | null;
-  unlocking?: boolean;
-  secrets?: readonly GuardSecretRow[];
-  onRotateSecret?: (key: string) => void;
-  rotatingKey?: string | null;
-
-  /* ---- the account surface (02 §5 / 03 §1e) ---------------------------- */
-  /**
-   * The account state for the `account` view. Absent ⇒ the surface renders its
-   * sign-in half, which is the correct state for an app whose session has not
-   * been established yet — never a blank panel.
-   */
-  account?: GuardAccountState;
-}
-
-/**
- * Everything the `account` surface renders, as ONE prop rather than a dozen:
- * the shell stays presentation-pure and `GuardEngineView` owns every fetch.
- */
-export interface GuardAccountState {
-  /** The signed-in account, or null (⇒ the sign-in panel). */
-  identity: {
-    userId: string;
-    email?: string;
-    tenantId: string;
-    tenantTitle?: string;
-    role: CCRole;
-    permissions: readonly string[];
-  } | null;
-  /** An `?invite=` token to prefill on the signup half. */
-  inviteToken?: string;
-  /**
-   * The launch gate (D33) — `guard.features.signupMode`. `invite`/`closed`
-   * replace the signup half with a "coming soon" notice (an `?invite=` link
-   * still opens the signup form under `invite`). Absent ⇒ `open`.
-   */
-  signupMode?: SignupMode;
-  onSignIn(input: { email: string; password: string }): Promise<unknown>;
-  onSignUp(input: { email: string; password: string; inviteToken?: string }): Promise<unknown>;
-  onChangePassword(input: { current: string; next: string }): Promise<unknown>;
-  onSignOut?: () => void;
-  onSignOutEverywhere?: () => void;
-  signingOut?: boolean;
-  /** This account's live sessions (02 §4). */
-  sessions?: readonly AccountSession[];
-  onEndSession?: (jti: string) => void;
-  endingJti?: string | null;
-  /** The tenant's members — ADMIN+ only; absent for everyone else. */
-  members?: readonly AccountMember[];
-  onInvite?: (input: { email: string; role: CCRole }) => void;
-  issuedInvitation?: { email: string; token: string; expiresAt: string } | null;
-  inviting?: boolean;
-  onChangeRole?: (userId: string, role: CCRole) => void;
-  onRemoveMember?: (userId: string) => void;
-  busyUserId?: string | null;
-  /**
-   * The audit trail (05 §B2, D25) — `infra:write` only, and ABSENT rather than
-   * empty for everyone else. The server refuses the read below that permission,
-   * so rendering the panel for a MEMBER would be a permanently-empty box that
-   * reads as "nothing has happened" instead of "this is not yours to see".
-   */
-  auditEntries?: readonly AuditEntryView[];
-  onRefreshAudit?: () => void;
-  auditRefreshing?: boolean;
-  /**
-   * The marketing-copy editor (D36) — ABSENT for everyone but the platform
-   * tenant's OWNER, and absent when `guard.features.siteCopy` is off. The
-   * bound view learns this by asking the admin route (a 403/404 means "not
-   * yours"), so this surface follows the same omission law as `members` and
-   * `auditEntries`: never a panel that renders as permanently empty.
-   */
-  siteCopy?: GuardSiteCopyState;
-}
-
-/** One editable marketing-copy key, as `/api/guard/site-copy/admin` lists it. */
-export interface SiteCopyAdminEntry {
-  key: string;
-  /** The shipped default — what the page bakes and what "reset" restores. */
-  defaultValue: string;
-  /** The stored override; absent when the deployment runs on the default. */
-  value?: string;
-  updatedAt?: string;
-  updatedBy?: string;
-}
-
-/** Everything the site-copy admin section renders (D36). */
-export interface GuardSiteCopyState {
-  entries: readonly SiteCopyAdminEntry[];
-  /** Keys the runtime overlay cannot apply (`<head>` metadata) — the panel
-   *  labels these "applies at the next site publish". */
-  bakedOnly: readonly string[];
-  onSave(key: string, value: string): void;
-  onReset(key: string): void;
-  /** The key with an in-flight save/reset, for per-row busy state. */
-  busyKey?: string | null;
-  error?: string | null;
-}