@gogitcms/design-system 0.15.0-next.3

package/src/fieldComponents.ts

@@ -0,0 +1,63 @@
+// The set of display components valid for each field type, and the default
+// component when `display.component` is omitted.
+//
+// This is the TypeScript mirror of packages/importer/schema/components.go — the
+// Go file is the source of truth validated on config import; keep the two in
+// sync. `select` is the enum picker (string / number). date and datetime are
+// valid for both string (ISO-8601 text) and number (epoch).
+
+export const componentsByType: Record<string, string[]> = {
+  string: ["input", "textarea", "body", "slug", "email", "url", "date", "datetime", "select", "media"],
+  boolean: ["checkbox", "switch"],
+  integer: ["number", "stepper", "telephone", "date", "datetime", "select"],
+  float: ["number", "stepper", "telephone", "date", "datetime", "select"],
+  array: ["list", "mixedList"],
+  object: ["inlineGroup", "group", "media"],
+};
+
+export const defaultComponentByType: Record<string, string> = {
+  string: "input",
+  boolean: "checkbox",
+  integer: "number",
+  float: "number",
+  array: "list",
+  object: "inlineGroup",
+};
+
+// defaultComponent returns the component to render when none is specified.
+export function defaultComponent(type: string): string {
+  return defaultComponentByType[type] ?? "input";
+}
+
+// resolveComponent returns the effective component for a field: its explicit
+// display.component, or the default for its type.
+//
+// A "plugin:"-prefixed component resolves to a default too. Naming one is not a
+// claim that the client has it — the host renders the plugin ahead of these
+// controls when it does (createPluginRenderField), and reaches here only when
+// the plugin is absent or refused the field's type. Matching nothing in that
+// case fell through to the single-line input, which is a poor control for a
+// field the plugin was chosen for and a terrible one for a whole file body, so
+// the fallback is picked from what the schema does say: `source: body` means
+// the value is the document's prose, hence the multi-line control.
+export function resolveComponent(field: {
+  type: string;
+  component?: string | null;
+  source?: string | null;
+}): string {
+  if (!field.component || field.component.startsWith("plugin:")) {
+    return field.source === "body" ? "textarea" : defaultComponent(field.type);
+  }
+  return field.component;
+}
+
+// componentAllowed reports whether a component is valid for a field type. The
+// server rejects invalid combinations on import; this mirror lets clients guard
+// too. A "plugin:"-prefixed component names a client-side plugin field
+// (docs/plugin-system.md): any named plugin component passes here — the host
+// enforces the plugin's own type restriction at render time and falls back to
+// the type's default control when the plugin is absent.
+export function componentAllowed(type: string, component: string): boolean {
+  if (component.startsWith("plugin:")) return component !== "plugin:";
+  return (componentsByType[type] ?? []).includes(component);
+}

package/src/icons.ts

@@ -0,0 +1,102 @@
+// Lucide-style line icons (24px grid, 1.5px stroke, round joins, no fill).
+// Each icon is a list of SVG path `d` strings so it renders identically via a
+// raw <svg> on web and react-native-svg on native.
+
+export const icons = {
+  file: ["M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z", "M14 2v6h6"],
+  newspaper: [
+    "M4 22a2 2 0 0 1-2-2V6a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2v14a2 2 0 0 0 2 2z",
+    "M18 22a2 2 0 0 0 2-2",
+    "M8 8h8", "M8 12h8", "M8 16h5",
+  ],
+  image: [
+    "M19 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2Z",
+    "M9 11a2 2 0 1 0 0-4 2 2 0 0 0 0 4Z",
+    "m21 15-3.1-3.1a2 2 0 0 0-2.8 0L6 21",
+  ],
+  braces: [
+    "M8 3H7a2 2 0 0 0-2 2v5a2 2 0 0 1-2 2 2 2 0 0 1 2 2v5a2 2 0 0 0 2 2h1",
+    "M16 21h1a2 2 0 0 0 2-2v-5a2 2 0 0 1 2-2 2 2 0 0 1-2-2V5a2 2 0 0 0-2-2h-1",
+  ],
+  listTree: ["M21 12h-8", "M21 6H8", "M21 18h-8", "M4 6v4a2 2 0 0 0 2 2h2", "M4 10v6a2 2 0 0 0 2 2h2"],
+  settings: [
+    "M12 15a3 3 0 1 0 0-6 3 3 0 0 0 0 6Z",
+    "M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 1 1-2.83 2.83l-.06-.06a1.65 1.65 0 0 0-2.82 1.17V21a2 2 0 0 1-4 0v-.09A1.65 1.65 0 0 0 8 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 1 1-2.83-2.83l.06-.06A1.65 1.65 0 0 0 4.6 14H4.5a2 2 0 0 1 0-4h.09A1.65 1.65 0 0 0 6 8.6a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 1 1 2.83-2.83l.06.06A1.65 1.65 0 0 0 10 4.6h.09A1.65 1.65 0 0 0 11 3.09V3a2 2 0 0 1 4 0v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 1 1 2.83 2.83l-.06.06A1.65 1.65 0 0 0 19.4 10h.1a2 2 0 0 1 0 4h-.1a1.65 1.65 0 0 0-1.5 1Z",
+  ],
+  chevronRight: ["m9 18 6-6-6-6"],
+  chevronLeft: ["m15 18-6-6 6-6"],
+  chevronDown: ["m6 9 6 6 6-6"],
+  chevronUp: ["m18 15-6-6-6 6"],
+  folder: ["M3 6a2 2 0 0 1 2-2h5l2 2h7a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2z"],
+  building: ["M3 21h18", "M6 21V7l7-4v18", "M18 21V11l-5-3"],
+  menu: ["M3 6h18", "M3 12h18", "M3 18h18"],
+  plus: ["M5 12h14", "M12 5v14"],
+  sun: [
+    "M12 8a4 4 0 1 0 0 8 4 4 0 0 0 0-8Z",
+    "M12 2v2", "M12 20v2", "m4.9 4.9 1.4 1.4", "m17.7 17.7 1.4 1.4",
+    "M2 12h2", "M20 12h2", "m6.3 17.7-1.4 1.4", "m19.1 4.9-1.4 1.4",
+  ],
+  moon: ["M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"],
+  search: ["M11 3a8 8 0 1 0 0 16 8 8 0 0 0 0-16Z", "m21 21-4.3-4.3"],
+  filter: ["M22 3H2l8 9.46V19l4 2v-8.54L22 3z"],
+  gitBranch: ["M6 3v12", "M6 21a3 3 0 1 0 0-6 3 3 0 0 0 0 6Z", "M18 9a3 3 0 1 0 0-6 3 3 0 0 0 0 6Z", "M18 9a9 9 0 0 1-9 9"],
+  gitCommit: ["M12 15a3 3 0 1 0 0-6 3 3 0 0 0 0 6Z", "M3 12h6", "M15 12h6"],
+  gitMerge: ["M6 9a3 3 0 1 0 0-6 3 3 0 0 0 0 6Z", "M18 21a3 3 0 1 0 0-6 3 3 0 0 0 0 6Z", "M6 21V9a9 9 0 0 0 9 9"],
+  gitPullRequest: ["M6 9a3 3 0 1 0 0-6 3 3 0 0 0 0 6Z", "M18 21a3 3 0 1 0 0-6 3 3 0 0 0 0 6Z", "M13 6h3a2 2 0 0 1 2 2v7", "M6 9v12"],
+  copy: ["M10 8h10a2 2 0 0 1 2 2v10a2 2 0 0 1-2 2H10a2 2 0 0 1-2-2V10a2 2 0 0 1 2-2Z", "M4 16a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2"],
+  lock: ["M5 11h14a2 2 0 0 1 2 2v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-6a2 2 0 0 1 2-2Z", "M7 11V7a5 5 0 0 1 10 0v4"],
+  panelLeft: ["M19 3H5a2 2 0 0 0-2 2v14a2 2 0 0 0 2 2h14a2 2 0 0 0 2-2V5a2 2 0 0 0-2-2Z", "M9 3v18"],
+  more: ["M12 13a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z", "M19 13a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z", "M5 13a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z"],
+  gripVertical: [
+    "M9 6a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z", "M9 13a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z", "M9 20a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z",
+    "M15 6a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z", "M15 13a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z", "M15 20a1 1 0 1 0 0-2 1 1 0 0 0 0 2Z",
+  ],
+  x: ["M18 6 6 18", "m6 6 12 12"],
+  trash: [
+    "M3 6h18", "M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2",
+    "M19 6v14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2V6", "M10 11v6", "M14 11v6",
+  ],
+  check: ["M20 6 9 17l-5-5"],
+  help: ["M12 22a10 10 0 1 0 0-20 10 10 0 0 0 0 20Z", "M9.09 9a3 3 0 0 1 5.83 1c0 2-3 3-3 3", "M12 17h.01"],
+  history: ["M3 3v5h5", "M3.05 13A9 9 0 1 0 6 5.3L3 8", "M12 7v5l4 2"],
+  logOut: ["M9 21H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h4", "m16 17 5-5-5-5", "M21 12H9"],
+  bell: [
+    "M10.268 21a2 2 0 0 0 3.464 0",
+    "M3.262 15.326A1 1 0 0 0 4 17h16a1 1 0 0 0 .74-1.673C19.41 13.956 18 12.499 18 8A6 6 0 0 0 6 8c0 4.499-1.411 5.956-2.738 7.326",
+  ],
+  // Media kinds: one icon per render class, for the collapsed representation of
+  // an asset and for the file chip that stands in where no preview is possible.
+  video: ["m16 13 5.223 3.482a.5.5 0 0 0 .777-.416V7.87a.5.5 0 0 0-.752-.432L16 10.5", "M2 6a2 2 0 0 1 2-2h10a2 2 0 0 1 2 2v12a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2z"],
+  audio: ["M9 18V5l12-2v13", "M9 18a3 3 0 1 1-6 0 3 3 0 0 1 6 0Z", "M21 16a3 3 0 1 1-6 0 3 3 0 0 1 6 0Z"],
+  fileText: [
+    "M15 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V7z",
+    "M14 2v5h6",
+    "M8 13h8", "M8 17h8", "M8 9h2",
+  ],
+  upload: ["M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4", "M7 10l5-5 5 5", "M12 5v12"],
+  download: ["M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4", "M7 10l5 5 5-5", "M12 15V3"],
+  link: [
+    "M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71",
+    "M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71",
+  ],
+  alert: ["M12 9v4", "M12 17h.01", "M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0Z"],
+  // Preview — the document toolbar's "show me this on the site" action.
+  eye: [
+    "M2 12s3.6-7 10-7 10 7 10 7-3.6 7-10 7-10-7-10-7Z",
+    "M12 15a3 3 0 1 0 0-6 3 3 0 0 0 0 6Z",
+  ],
+  // "Opens somewhere else" — a preview pointing at an external environment.
+  externalLink: ["M15 3h6v6", "M10 14 21 3", "M21 14v5a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5"],
+  // Grid / list view toggle for the media browser.
+  grid: [
+    "M3 3h7v7H3z", "M14 3h7v7h-7z", "M14 14h7v7h-7z", "M3 14h7v7H3z",
+  ],
+  rows: [
+    "M3 5h18", "M3 12h18", "M3 19h18",
+  ],
+  // A ring with one quarter missing — meaningless standing still, so only ever
+  // rendered inside <Spinner/>, which rotates it.
+  loader: ["M21 12a9 9 0 1 1-6.219-8.56"],
+} as const;
+
+export type IconName = keyof typeof icons;

package/src/index.ts

@@ -0,0 +1,198 @@
+// Theme + hooks
+export {
+  makeTheme,
+  lightTheme,
+  darkTheme,
+  DESKTOP_BREAKPOINT,
+} from "./theme";
+export type { Theme, ThemeMode } from "./theme";
+export {
+  ThemeProvider,
+  ThemeScope,
+  useTheme,
+  useThemeMode,
+  useResponsive,
+} from "./ThemeProvider";
+export type { ThemeProviderProps } from "./ThemeProvider";
+
+// Icons
+export { Icon } from "./components/Icon";
+export type { IconProps } from "./components/Icon";
+export { icons } from "./icons";
+export type { IconName } from "./icons";
+
+// Typography
+export { Text } from "./components/Text";
+export type { TextProps } from "./components/Text";
+
+// Forms
+export { Button, IconButton } from "./components/Button";
+export type { ButtonProps, ButtonVariant, ButtonSize, IconButtonProps } from "./components/Button";
+export { Input } from "./components/Input";
+export type { InputProps } from "./components/Input";
+
+// Data display
+export { Card, Badge, DiffStat, Avatar, Divider, SectionLabel } from "./components/primitives";
+export type { BadgeTone } from "./components/primitives";
+export { NavRow } from "./components/NavRow";
+export type { NavRowProps } from "./components/NavRow";
+
+// Surface switching + branch selection (the editor top bar)
+export { Segment } from "./components/Segment";
+export type { SegmentProps, SegmentItem } from "./components/Segment";
+export { BranchMenu } from "./components/BranchMenu";
+export type { BranchMenuProps, BranchRef } from "./components/BranchMenu";
+export { ProjectMenu } from "./components/ProjectMenu";
+export type { ProjectMenuProps, ProjectRef } from "./components/ProjectMenu";
+
+// Apply changes (merge) progress modal
+export { ApplyChangesModal } from "./components/ApplyChangesModal";
+export type {
+  ApplyChangesModalProps,
+  MergeProgress,
+  MergeStatus,
+  MergeStep,
+} from "./components/ApplyChangesModal";
+
+// Change-request summary surface (developer escalation)
+export { ChangeRequestSummary } from "./components/ChangeRequestSummary";
+export type {
+  ChangeRequestSummaryProps,
+  ChangeRequestSummaryData,
+  ChangeRequestComment,
+} from "./components/ChangeRequestSummary";
+
+// Changes surface: one document's diff between a branch and its base
+export { ChangeDetail } from "./components/ChangeDetail";
+export type {
+  ChangeDetailProps,
+  DocumentChange,
+  FieldChange,
+  FieldChangeKind,
+  ChangePreview,
+  FieldConflict,
+  ConflictChoice,
+} from "./components/ChangeDetail";
+
+// Onboarding: the guided-tour framework (spotlight overlay + target registry).
+// The tours themselves are defined by the host app, not here.
+export {
+  OnboardingProvider,
+  OnboardingOverlay,
+  OnboardingTarget,
+  useOnboarding,
+  useOnboardingOptional,
+  useOnboardingTarget,
+  placeCard,
+} from "./components/Onboarding";
+export type {
+  OnboardingProviderProps,
+  OnboardingFlow,
+  OnboardingFlowStep,
+  OnboardingPlacement,
+  OnboardingProgress,
+  OnboardingStatus,
+  OnboardingSession,
+  OnboardingApi,
+} from "./components/Onboarding";
+
+// First-import gate: the full-screen states an editor holds while (or instead of)
+// opening a branch that has never been imported.
+export { BranchImportingScreen, BranchImportFailedScreen } from "./components/BranchImport";
+export type {
+  BranchImportingScreenProps,
+  BranchImportFailedScreenProps,
+} from "./components/BranchImport";
+
+// Spinner
+export { Spinner } from "./components/Spinner";
+export type { SpinnerProps } from "./components/Spinner";
+
+// Notifications
+export { NotificationBell, NotificationList } from "./components/Notifications";
+export type {
+  NotificationItem,
+  NotificationBellProps,
+  NotificationListProps,
+} from "./components/Notifications";
+
+// Layout
+export {
+  Screen,
+  TopBar,
+  Pane,
+  AppShell,
+  MobileScreen,
+  ThemeToggle,
+} from "./components/layout";
+
+// Media: the picker control, its previews, and the host data seam
+export { MediaField, MediaPicker, MediaProvider, DocumentPathProvider, useMediaApi, pathForStoreAs } from "./components/MediaField";
+export type { MediaFieldProps, MediaPickerProps } from "./components/MediaField";
+export { MediaPreview, MediaChip } from "./components/MediaPreview";
+export type { MediaPreviewProps } from "./components/MediaPreview";
+export { MediaBrowser } from "./components/MediaBrowser";
+export type { MediaBrowserProps } from "./components/MediaBrowser";
+export {
+  MEDIA_KINDS,
+  MEDIA_OBJECT_FIELDS,
+  isMediaValue,
+  kindIcon,
+  formatBytes,
+  // Nav-key helpers: the sidebar's Media button is derived by ContentBrowser, so
+  // a host needs these to map its URL state onto the media surface and the
+  // selected set.
+  MEDIA_NAV_KEY,
+  mediaNavKey,
+  isMediaNavKey,
+  parseMediaNavKey,
+} from "./media";
+export type {
+  MediaKind,
+  StoreAs,
+  MediaValue,
+  MediaAsset,
+  MediaResolution,
+  MediaSetInfo,
+  MediaApi,
+  MediaCondition,
+  MediaFilterField,
+  MediaFilterOp,
+  MediaFacetValue,
+  MediaFacets,
+} from "./media";
+
+// Field components registry (mirror of the Go schema's component set)
+export {
+  componentsByType,
+  defaultComponentByType,
+  defaultComponent,
+  resolveComponent,
+  componentAllowed,
+} from "./fieldComponents";
+
+// Templates
+export { ContentBrowser } from "./components/ContentBrowser";
+export { ContentBrowserSkeleton, SkeletonBox } from "./components/Skeleton";
+export type {
+  ContentBrowserProps,
+  CmsNavItem,
+  CmsNavSection,
+  UserMenuItem,
+  CmsEntry,
+  OpenTab,
+  EntryField,
+  FacetField,
+  DocFilter,
+  CmsWorkspace,
+  FieldSlotArgs,
+  RenderField,
+  EntrySaveChange,
+  SaveEntry,
+  SaveStatus,
+  CollabApi,
+  CollabText,
+  CollabRegister,
+  CollabPeer,
+  CollabParticipant,
+} from "./components/ContentBrowser";

package/src/media.ts

@@ -0,0 +1,229 @@
+// The media picker's display keys and its render classification.
+//
+// This is the TypeScript mirror of packages/importer/schema/media.go — the Go
+// file is the source of truth validated on config import; keep the two in sync.
+
+import type { IconName } from "./icons";
+
+// Media is one asset as the server delivers it. `kind` is derived server-side
+// from the mime type, so a preview never has to guess from a filename; `url` is
+// a short-lived presigned read URL (the object store itself is never public).
+export interface MediaAsset {
+  id: string;
+  set: string;
+  repoPath: string;
+  publicPath?: string | null;
+  cdnPath?: string | null;
+  mimeType: string;
+  // Lower-cased, no dot ("png"). Empty for a file without one.
+  extension: string;
+  kind: MediaKind;
+  size: number;
+  width?: number | null;
+  height?: number | null;
+  pending: boolean;
+  url: string;
+}
+
+// MediaResolution is the answer to "what asset does this frontmatter string
+// mean?". `media` null with `ambiguous` false is a miss, not an error — the
+// string is an external URL or points outside every configured set, and the
+// field should render it as-is.
+export interface MediaResolution {
+  input: string;
+  media?: MediaAsset | null;
+  aliasKind?: string | null;
+  ambiguous: boolean;
+  candidates: MediaAsset[];
+}
+
+// MediaSetInfo is one browsable group of assets, from the repository's config.
+export interface MediaSetInfo {
+  name: string;
+  path: string;
+  mimeTypes: string[];
+  publicBase?: string | null;
+  cdnBase?: string | null;
+  count: number;
+}
+
+// One condition in the media browser's faceted search. The field set is closed
+// and enforced server-side; an unknown field or a mismatched operator is an
+// error rather than a dropped filter.
+//
+//   name       repository path, case-insensitive substring — contains, eq
+//   extension  lower-cased, no dot ("png")                 — eq, in
+//   mimeType   exact ("image/png") or wildcard ("image/*") — eq, in
+//   kind       image|svg|video|audio|pdf|file              — eq, in
+//   size       bytes                                       — eq, gt, lt, gte, lte
+//   width      pixels                                      — eq, gt, lt, gte, lte
+//   height     pixels                                      — eq, gt, lt, gte, lte
+//   pending    "true"/"false"                              — eq
+export type MediaFilterField =
+  | "name" | "extension" | "mimeType" | "kind"
+  | "size" | "width" | "height" | "pending";
+
+export type MediaFilterOp = "eq" | "in" | "contains" | "gt" | "lt" | "gte" | "lte";
+
+export interface MediaCondition {
+  field: MediaFilterField;
+  op: MediaFilterOp;
+  value?: string;
+  values?: string[];
+}
+
+// One available value for a facet, with how many files carry it — so the panel
+// can show "png (42)" and omit options that would return nothing.
+export interface MediaFacetValue {
+  value: string;
+  count: number;
+}
+
+// The filter panel's options for a set. Counts deliberately ignore the user's
+// own selections, so the options don't vanish from under them as they click.
+export interface MediaFacets {
+  extensions: MediaFacetValue[];
+  mimeTypes: MediaFacetValue[];
+  kinds: MediaFacetValue[];
+  minSize: number;
+  maxSize: number;
+  total: number;
+}
+
+// Media occupies one nav key space, prefixed so it cannot collide with a
+// collection: a collection name is restricted to [A-Za-z0-9_-] by the config
+// schema, so it can never contain a colon — not even a collection literally
+// named "media".
+//
+//   "media:"         the Media button, with no set chosen yet
+//   "media:uploads"  a specific set, which is what makes a set deep-linkable
+const MEDIA_NAV_PREFIX = "media:";
+
+// MEDIA_NAV_KEY is the Media button's own key — media with nothing selected.
+export const MEDIA_NAV_KEY = MEDIA_NAV_PREFIX;
+
+// mediaNavKey returns the nav key for a set, or for the Media button when the
+// set is omitted.
+export function mediaNavKey(set?: string): string {
+  return set ? MEDIA_NAV_PREFIX + set : MEDIA_NAV_PREFIX;
+}
+
+// isMediaNavKey reports whether a nav key addresses media at all — true for the
+// Media button and for any set beneath it. This is what a host checks to know
+// the media surface is showing.
+export function isMediaNavKey(key: string | null | undefined): boolean {
+  return !!key && key.startsWith(MEDIA_NAV_PREFIX);
+}
+
+// parseMediaNavKey returns the media set a nav key selects: null for an ordinary
+// collection, and also null for the bare Media button (media is showing, but no
+// set is chosen). Pair it with isMediaNavKey to tell those two apart.
+export function parseMediaNavKey(key: string | null | undefined): string | null {
+  if (!isMediaNavKey(key)) return null;
+  const set = key!.slice(MEDIA_NAV_PREFIX.length);
+  return set.length > 0 ? set : null;
+}
+
+// MediaApi is the data seam between the design system and its host. The DS owns
+// the picker and preview UI; the host (Apollo on web/mobile, REST on desktop)
+// owns fetching. Omitting it from ContentBrowser renders media fields read-only,
+// which is also what a deployment with no object store gets.
+export interface MediaApi {
+  // The sets available to browse.
+  sets: MediaSetInfo[];
+  // Resolve frontmatter strings to assets. Batched by the caller; the server
+  // answers all of a document's media fields in one round trip.
+  resolve: (paths: string[], documentPath?: string) => Promise<MediaResolution[]>;
+  // Fetch one asset by id — the object value form's lookup, which needs no
+  // resolution because the id is authoritative. Null when the asset is gone.
+  byId: (id: string) => Promise<MediaAsset | null>;
+  // One page of a set's assets, for both the field picker and the browser.
+  list: (params: {
+    set?: string;
+    kinds?: MediaKind[];
+    search?: string;
+    filters?: MediaCondition[];
+    limit?: number;
+    offset?: number;
+  }) => Promise<MediaAsset[]>;
+  // How many assets match, ignoring paging — the total behind "12 of 340" and
+  // the count shown while building filters. Omit to hide those affordances.
+  count?: (params: {
+    set?: string;
+    kinds?: MediaKind[];
+    search?: string;
+    filters?: MediaCondition[];
+  }) => Promise<number>;
+  // The filter panel's options for a set. Omit to render the browser without a
+  // faceted panel (plain search only).
+  facets?: (set?: string) => Promise<MediaFacets>;
+  // Upload a file into a set. Resolves to the finalized asset. Omit to disable
+  // the picker's upload affordance.
+  upload?: (params: {
+    set: string;
+    file: File;
+    folder?: string;
+  }) => Promise<MediaAsset>;
+}
+
+// MediaKind is the render class a preview switches on. It is derived server-side
+// on import and delivered on every Media object, so clients never re-derive it
+// from a filename (and never disagree with the server about it).
+export type MediaKind = "image" | "svg" | "video" | "audio" | "pdf" | "file";
+
+export const MEDIA_KINDS: MediaKind[] = ["image", "svg", "video", "audio", "pdf", "file"];
+
+// StoreAs is which form of the path a string media field writes when the user
+// picks an asset. The object form needs no equivalent: it stores the media id.
+export type StoreAs = "repo" | "public" | "cdn";
+
+// The child fields an object media field must have, in order.
+export const MEDIA_OBJECT_FIELDS = ["id", "public_path", "cdn_path"] as const;
+
+// MediaValue is the object form of a media field's value.
+export interface MediaValue {
+  id: string;
+  public_path?: string | null;
+  cdn_path?: string | null;
+}
+
+// isMediaValue narrows an unknown field value to the object form. A string media
+// field's value is a plain string and needs resolution to find its asset; the
+// object form carries the id and does not.
+export function isMediaValue(v: unknown): v is MediaValue {
+  return typeof v === "object" && v !== null && typeof (v as MediaValue).id === "string";
+}
+
+// kindIcon maps a render kind to the design-system icon used for the collapsed /
+// non-previewable representation of an asset.
+export function kindIcon(kind: MediaKind): IconName {
+  switch (kind) {
+    case "image":
+    case "svg":
+      return "image";
+    case "video":
+      return "video";
+    case "audio":
+      return "audio";
+    case "pdf":
+      return "fileText";
+    default:
+      return "file";
+  }
+}
+
+// formatBytes renders a file size for display next to an asset.
+export function formatBytes(bytes: number): string {
+  if (!Number.isFinite(bytes) || bytes < 0) return "";
+  if (bytes < 1024) return `${bytes} B`;
+  const units = ["KB", "MB", "GB", "TB"];
+  let value = bytes / 1024;
+  let unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  // One decimal below 10 ("1.4 MB"), none above ("14 MB") — enough precision to
+  // distinguish sizes without implying more than the number is worth.
+  return `${value < 10 ? value.toFixed(1) : Math.round(value)} ${units[unit]}`;
+}