@gogitcms/editor 0.23.0

package/app/src/apollo.ts

@@ -0,0 +1,119 @@
+import { ApolloClient, InMemoryCache, HttpLink, split } from "@apollo/client";
+import { offsetLimitPagination, getMainDefinition } from "@apollo/client/utilities";
+import { setContext } from "@apollo/client/link/context";
+import { onError } from "@apollo/client/link/error";
+import { GraphQLWsLink } from "@apollo/client/link/subscriptions";
+import { createClient } from "graphql-ws";
+import { config } from "./config";
+import { beginAuthorize } from "./auth";
+
+// The access token lives in memory only. It is set after a PKCE token exchange
+// and re-minted by bouncing through the issuer — never persisted to storage.
+let token = "";
+export function setAuthToken(t: string) {
+  token = t;
+  // Clearing the token happens only on an explicit sign-out (see App's onSignOut,
+  // which clears it and then navigates to /logout). In that window, in-flight or
+  // polling operations fire with no token and come back 401 — which must NOT
+  // trigger the auto-reauthorize below, or its top-level redirect to /authorize
+  // would race (and beat) the logout navigation and silently sign the user back
+  // in from the still-live issuer session. A real token means we're authed, so
+  // the expiry-driven reauthorize is armed again.
+  signingOut = t === "";
+}
+// The collab WebSocket reads the current token on each (re)connect and sends it
+// via the WebSocket subprotocol (never the URL).
+export function getAuthToken(): string {
+  return token;
+}
+
+// config.apiUrl is the server host (injected) or "" for same-origin.
+const httpLink = new HttpLink({ uri: `${config.apiUrl}/graphql` });
+const authLink = setContext((_, { headers }) => ({
+  headers: {
+    ...headers,
+    ...(token ? { authorization: `Bearer ${token}` } : {}),
+    // The local server requires a custom header on anything that can change
+    // state. That is its CSRF barrier: a cross-origin simple POST cannot set a
+    // custom header without a preflight, which the server's origin check then
+    // refuses. Harmless to send to a hosted API, but scoped to local mode so it
+    // never appears on a request that has no reason to carry it.
+    ...(config.local ? { "X-GitCms-Local": "1" } : {}),
+  },
+}));
+
+// Subscriptions ride a WebSocket (queries/mutations stay on HTTP). The token
+// can't ride an Authorization header on a WS upgrade, so it goes in the
+// graphql-ws connection_init payload — read fresh on each (re)connect, exactly
+// as the collab socket does, so a reconnect after a token refresh reauthenticates.
+function graphqlWsURL(): string {
+  const base = config.apiUrl;
+  if (base) return base.replace(/^http/i, "ws").replace(/\/$/, "") + "/graphql";
+  if (typeof window === "undefined") return "";
+  const proto = window.location.protocol === "https:" ? "wss" : "ws";
+  return `${proto}://${window.location.host}/graphql`;
+}
+
+const wsLink =
+  typeof window === "undefined"
+    ? null
+    : new GraphQLWsLink(
+        createClient({
+          url: graphqlWsURL(),
+          connectionParams: () => (token ? { authorization: `Bearer ${token}` } : {}),
+        }),
+      );
+
+// Route subscription operations to the WS link, everything else to HTTP.
+const requestLink = wsLink
+  ? split(
+      ({ query }) => {
+        const def = getMainDefinition(query);
+        return def.kind === "OperationDefinition" && def.operation === "subscription";
+      },
+      wsLink,
+      authLink.concat(httpLink),
+    )
+  : authLink.concat(httpLink);
+
+// When the access token has expired, the server answers 401 (network) or an
+// UNAUTHENTICATED GraphQL error. Re-authorize via a top-level redirect to the
+// issuer, which re-mints a token from the first-party session cookie there. The
+// guard prevents a storm of in-flight operations from each firing a redirect.
+let reauthorizing = false;
+// True from the moment the token is cleared for sign-out until a real token is
+// set again. It suppresses the expiry-driven reauthorize so a 401 during logout
+// teardown can't bounce the user back through /authorize and re-establish the
+// session the logout is trying to end.
+let signingOut = false;
+function reauthorize() {
+  if (reauthorizing || signingOut) return;
+  reauthorizing = true;
+  void beginAuthorize();
+}
+
+const errorLink = onError(({ graphQLErrors, networkError }) => {
+  const unauthenticated =
+    graphQLErrors?.some((e) => e.extensions?.code === "UNAUTHENTICATED") ||
+    (networkError as { statusCode?: number } | null)?.statusCode === 401;
+  if (unauthenticated) reauthorize();
+});
+
+export const client = new ApolloClient({
+  link: errorLink.concat(requestLink),
+  cache: new InMemoryCache({
+    typePolicies: {
+      Query: {
+        fields: {
+          // Server-side paginated entry list: fetchMore requests successive
+          // offset windows, which this policy concatenates into one contiguous
+          // list per (repository, branch, collection, search, filters). offset/limit
+          // are NOT key args, so pages of the same search merge into one cached
+          // list; search/filters ARE key args, so each distinct search/filter set
+          // is its own list (they don't bleed together). See CmsView's fetchMore.
+          documents: offsetLimitPagination(["repositoryId", "branchId", "collection", "search", "filters"]),
+        },
+      },
+    },
+  }),
+});

package/app/src/auth.ts

@@ -0,0 +1,248 @@
+// PKCE authorization-code flow for the content-editing SPA.
+//
+// The editor can be served from any customer domain while the token issuer lives
+// on a separate origin, so it cannot hold a refresh token securely (a cross-site
+// cookie would be third-party and blocked; anything in JS storage is readable by
+// injected scripts). Instead it holds only a short-lived access token in memory
+// and re-mints it by bouncing the browser through the issuer's /authorize
+// endpoint — a top-level navigation where the issuer session cookie is
+// first-party. PKCE ensures a code intercepted in the redirect URL is useless
+// without the verifier we keep here.
+import { config } from "./config";
+
+const VERIFIER_KEY = "cms.pkce.verifier";
+const STATE_KEY = "cms.pkce.state";
+// Set when the user explicitly signs out; makes the sign-out sticky for the tab.
+// While present, nothing may silently re-establish a session — not the PKCE
+// bounce, not the dev-server broker, not a 401-driven retry. It is the durable
+// version of the transient ?loggedout marker: a top-level /logout round-trip (or
+// any reload, or a lost query param) can't wash it away, so a still-live issuer
+// session can't sign the user straight back in. Cleared only when the user
+// initiates a fresh sign-in. sessionStorage (not local): scoped to this tab, so
+// opening the editor in a new tab still authorizes normally.
+const SIGNED_OUT_KEY = "cms.signedOut";
+
+export function isSignedOut(): boolean {
+  return sessionStorage.getItem(SIGNED_OUT_KEY) === "1";
+}
+// clearSignedOut lifts the suppression. Called at every explicit sign-in entry
+// point (the GitHub bounce and the password/magic-link forms), so a deliberate
+// sign-in always wins over a prior sign-out.
+export function clearSignedOut(): void {
+  sessionStorage.removeItem(SIGNED_OUT_KEY);
+}
+
+const authBase = `${config.apiUrl}/api/v1/auth`;
+
+// Every call that signs the user in has to be credentialed, and it is the whole
+// reason a session survives a reload.
+//
+// The issuer answers a sign-in with two things: an access token in the body,
+// which this SPA keeps in memory, and its session cookie as a Set-Cookie header.
+// The cookie is what /authorize reads on the next load to re-mint silently. But
+// the editor is served from a different origin than the issuer, and a
+// cross-origin fetch with the default credentials mode ("same-origin") neither
+// sends cookies nor *stores* the ones a response sets — the browser drops the
+// header on the floor, with no error anywhere.
+//
+// So without this, signing in appears to work — an access token comes back and
+// the editor loads — and then every refresh lands on the sign-in form, because
+// the issuer session it would have authorized against was never written.
+//
+// The API is already set up for it: its CORS layer reflects the request origin
+// and sets Access-Control-Allow-Credentials, precisely so a cross-origin editor
+// can use the HttpOnly refresh cookie.
+const credentialed: RequestInit = { credentials: "include" };
+
+function base64url(bytes: Uint8Array): string {
+  let s = "";
+  for (const b of bytes) s += String.fromCharCode(b);
+  return btoa(s).replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+function randomString(byteLen = 32): string {
+  const buf = new Uint8Array(byteLen);
+  crypto.getRandomValues(buf);
+  return base64url(buf);
+}
+
+async function s256(verifier: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier));
+  return base64url(new Uint8Array(digest));
+}
+
+// redirectUri is the current page without query/hash — where /authorize sends
+// the code back. It must match a redirect target the server allowlists (a
+// same-origin /app path, or a registered self-hosted editor origin).
+function redirectUri(): string {
+  return window.location.origin + window.location.pathname;
+}
+
+// beginAuthorize starts (or restarts) the flow: it stashes a fresh verifier and
+// state, then navigates the whole tab to the issuer. This never returns — the
+// browser leaves the page and comes back to the callback.
+export async function beginAuthorize(): Promise<void> {
+  // An explicit sign-out is sticky: never silently re-authorize against a
+  // still-live issuer session. This is the guard that actually stops the
+  // "logout immediately signs me back in" loop — it holds no matter what called
+  // us (Root's boot path or a 401-driven retry) and survives the /logout
+  // round-trip, unlike an in-memory flag.
+  if (isSignedOut()) return;
+  const verifier = randomString();
+  const state = randomString(16);
+  sessionStorage.setItem(VERIFIER_KEY, verifier);
+  sessionStorage.setItem(STATE_KEY, state);
+
+  const params = new URLSearchParams({
+    redirect_uri: redirectUri(),
+    code_challenge: await s256(verifier),
+    code_challenge_method: "S256",
+    state,
+  });
+  window.location.assign(`${authBase}/authorize?${params.toString()}`);
+}
+
+// beginLogout ends the session at the issuer and returns to the editor. Like
+// beginAuthorize it is a top-level navigation (and never returns): the issuer's
+// session cookie is SameSite=Lax, so only a first-party top-level request clears
+// it — a cross-origin fetch to /logout would omit the cookie, leave the session
+// alive, and let the next authorize silently sign the user back in.
+export function beginLogout(): void {
+  // Record the intent before leaving, so it is already durable when the browser
+  // comes back from /logout (and even if a stray 401 tries to re-authorize
+  // during the teardown, or the ?loggedout marker is lost). Cleared only by an
+  // explicit sign-in.
+  sessionStorage.setItem(SIGNED_OUT_KEY, "1");
+  const params = new URLSearchParams({ redirect_uri: redirectUri() });
+  window.location.assign(`${authBase}/logout?${params.toString()}`);
+}
+
+// beginGitHub starts GitHub sign-in as a top-level navigation to the issuer,
+// asking it to return the signed verification token to this editor page (its
+// origin is on the same allowlist the PKCE flow uses). handleCallback then trades
+// that token for an access token. Never returns — the tab leaves and comes back.
+export function beginGitHub(): void {
+  // An explicit sign-in overrides a prior sign-out.
+  clearSignedOut();
+  const params = new URLSearchParams({ redirect_uri: redirectUri() });
+  window.location.assign(`${authBase}/github?${params.toString()}`);
+}
+
+// brokeredToken asks the local dev server for an access token. `gogitcms-editor dev`
+// serves this page from a localhost origin the issuer will never allowlist for
+// PKCE, so the CLI — which already signed in via the device grant — lends its
+// session through a same-origin endpoint. Returns "" when there is no broker
+// (every hosted build) or it has no session to lend, in which case the caller
+// falls back to PKCE.
+export async function brokeredToken(): Promise<string> {
+  if (!config.tokenEndpoint) return "";
+  try {
+    const res = await fetch(config.tokenEndpoint, { headers: { Accept: "application/json" } });
+    if (!res.ok) return "";
+    const body = await res.json();
+    return typeof body.accessToken === "string" ? body.accessToken : "";
+  } catch {
+    return "";
+  }
+}
+
+export type CallbackResult =
+  | { kind: "none" } // no auth params in the URL — a normal load
+  | { kind: "token"; accessToken: string }
+  | { kind: "error"; error: string }
+  | { kind: "loggedout" }; // returned from /logout — stay signed out
+
+// handleCallback inspects the URL for an authorize redirect result. On ?code it
+// verifies state and exchanges the code (with the stored verifier) for an access
+// token. It always strips the auth params from the URL so a reload can't replay
+// them. `login_required` surfaces as an error so the SPA can prompt sign-in.
+export async function handleCallback(): Promise<CallbackResult> {
+  const url = new URL(window.location.href);
+  const code = url.searchParams.get("code");
+  const error = url.searchParams.get("error");
+  const state = url.searchParams.get("state");
+  const loggedOut = url.searchParams.get("loggedout");
+
+  // Return from /logout: the issuer session is cleared. Strip the marker and
+  // report it so the SPA lands on sign-in instead of silently re-authorizing.
+  if (loggedOut) {
+    stripAuthParams();
+    return { kind: "loggedout" };
+  }
+
+  // Return from GitHub sign-in: the issuer handed back a signed verification
+  // token (?token). Trade it for an access token via /github/complete. (A GitHub
+  // failure comes back as ?error, handled by the PKCE path below.)
+  const ghToken = url.searchParams.get("token");
+  if (ghToken && !code) {
+    stripAuthParams();
+    const res = await fetch(`${authBase}/github/complete`, {
+      ...credentialed,
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ token: ghToken }),
+    });
+    if (!res.ok) {
+      return { kind: "error", error: res.status === 409 ? "github_claim_required" : "github_failed" };
+    }
+    const body = await res.json();
+    return { kind: "token", accessToken: body.accessToken as string };
+  }
+
+  if (!code && !error) return { kind: "none" };
+
+  const expectedState = sessionStorage.getItem(STATE_KEY);
+  const verifier = sessionStorage.getItem(VERIFIER_KEY);
+  sessionStorage.removeItem(STATE_KEY);
+  sessionStorage.removeItem(VERIFIER_KEY);
+  stripAuthParams();
+
+  if (error) return { kind: "error", error };
+  if (!state || state !== expectedState || !verifier) {
+    return { kind: "error", error: "state_mismatch" };
+  }
+
+  const res = await fetch(`${authBase}/token`, {
+    ...credentialed,
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ code, codeVerifier: verifier }),
+  });
+  if (!res.ok) return { kind: "error", error: "exchange_failed" };
+  const body = await res.json();
+  return { kind: "token", accessToken: body.accessToken as string };
+}
+
+// requestMagicLink asks the issuer to email a passwordless sign-in code. Always
+// resolves for a valid request (the endpoint returns 200 even for unknown
+// addresses so it can't be used to probe which emails exist).
+export async function requestMagicLink(email: string): Promise<void> {
+  const res = await fetch(`${authBase}/register/magic-link`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ email }),
+  });
+  if (!res.ok) throw new Error("could not send sign-in link");
+}
+
+// redeemMagicLink exchanges the emailed code for an access token. The editor is
+// cross-origin to the issuer and holds no refresh token, so it keeps only the
+// returned access token in memory (like the PKCE flow); the emailed link opens
+// the dashboard, so the code is entered into the editor by hand.
+export async function redeemMagicLink(code: string): Promise<string> {
+  const res = await fetch(`${authBase}/magic-link/redeem`, {
+    ...credentialed,
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ code }),
+  });
+  if (!res.ok) throw new Error("invalid or expired code");
+  const body = await res.json();
+  return body.accessToken as string;
+}
+
+function stripAuthParams() {
+  const url = new URL(window.location.href);
+  for (const k of ["code", "state", "error", "loggedout", "token"]) url.searchParams.delete(k);
+  window.history.replaceState(null, "", url.pathname + url.search + url.hash);
+}

package/app/src/config.ts

@@ -0,0 +1,88 @@
+// Runtime configuration for the SPA. Resolved from two sources, in order:
+//   1. Build-time values injected via Vite `define` (from cms.config.js|ts).
+//   2. Window globals injected by the Go server into the served HTML.
+// Build-time wins so a purpose-built bundle can't be overridden at runtime.
+
+import { resolveAnalyticsConfig, type AnalyticsConfig, type RawAnalyticsConfig } from "@gogitcms/analytics";
+
+export type CmsConfig = {
+  apiUrl: string;
+  workspaceId?: string;
+  repositoryId?: string;
+  // Pins this deployment to a single project of the repository. A locked editor
+  // renders no project picker and refuses a URL naming a different project, so a
+  // self-hosted instance can be handed to a team that should only ever see one
+  // project's content.
+  //
+  // The value is the project's manifest NAME, not its id: names are portable
+  // across deployments, so the same cms.config.js works against staging and
+  // production, and it is the same token the URL segment carries.
+  project?: string;
+  // Same-origin path that hands this page an access token, set only by
+  // `gogitcms-editor dev`. A local dev origin can never be on the issuer's PKCE
+  // redirect allowlist, so the CLI lends the SPA the session it already holds.
+  // Absent in every hosted build, which keeps using PKCE.
+  tokenEndpoint?: string;
+  // Origin of the collaboration WebSocket, for deployments that run `collab` as
+  // its own process on its own port. Empty means it is served by the API origin,
+  // which is what the single-process server does.
+  collabUrl?: string;
+  // True when the API is the local filesystem server (`gogitcms-editor dev --local`).
+  //
+  // Local mode is a subset of the hosted API: one branch, no merges, no
+  // collaboration. The editor uses this to HIDE those surfaces rather than let
+  // someone click into an error — a feature the user never sees beats a failure
+  // they cannot act on.
+  local: boolean;
+};
+
+type RawConfig = {
+  API_URL?: string;
+  WORKSPACE_ID?: string;
+  REPOSITORY_ID?: string;
+  PROJECT?: string;
+  TOKEN_ENDPOINT?: string;
+  COLLAB_URL?: string;
+  MODE?: string;
+} & RawAnalyticsConfig;
+
+// Replaced at build time by Vite `define`; `typeof` guards the undeclared case
+// (plain `vite` dev with no config) without throwing.
+declare const __CMS_CONFIG_BUILD__: RawConfig | undefined;
+
+const build: RawConfig =
+  typeof __CMS_CONFIG_BUILD__ !== "undefined" && __CMS_CONFIG_BUILD__ ? __CMS_CONFIG_BUILD__ : {};
+
+const runtime: RawConfig =
+  (typeof window !== "undefined" && (window as any).__CMS_CONFIG__) || {};
+
+const pick = (key: keyof RawConfig): string | undefined => build[key] || runtime[key] || undefined;
+
+export const config: CmsConfig = {
+  apiUrl: pick("API_URL") ?? "",
+  workspaceId: pick("WORKSPACE_ID"),
+  project: pick("PROJECT"),
+  repositoryId: pick("REPOSITORY_ID"),
+  // Only honoured from the build-time side: a runtime global is injected by
+  // whoever serves the page, and a hosted deployment must not be able to point
+  // the editor's credential fetch at a path of its choosing.
+  tokenEndpoint: build.TOKEN_ENDPOINT || undefined,
+  collabUrl: pick("COLLAB_URL"),
+  // Build-time only, like tokenEndpoint: whoever serves the page must not be
+  // able to talk the editor into (or out of) local mode at runtime.
+  local: build.MODE === "local",
+};
+
+// PostHog, resolved through the same two-source chain. Build-time values come
+// from cms.config.js (or POSTHOG_* env vars at build time, which the
+// cms-frontend CLI folds into the same object); the runtime globals let a
+// server-embedded bundle be configured by the deployment serving it.
+//
+// Empty POSTHOG_API_KEY — the default everywhere — leaves analytics off.
+export const analyticsConfig: AnalyticsConfig = resolveAnalyticsConfig({
+  POSTHOG_API_KEY: pick("POSTHOG_API_KEY"),
+  POSTHOG_API_HOST: pick("POSTHOG_API_HOST"),
+  POSTHOG_UI_HOST: pick("POSTHOG_UI_HOST"),
+  POSTHOG_ENVIRONMENT: pick("POSTHOG_ENVIRONMENT"),
+  POSTHOG_SESSION_RECORDING: pick("POSTHOG_SESSION_RECORDING"),
+});

package/app/src/main.tsx

@@ -0,0 +1,18 @@
+import { AppRegistry } from "react-native";
+import { loadPlugins } from "@gogitcms/plugin-sdk";
+import { plugins } from "virtual:cms-plugins";
+import App from "./App";
+import { pluginRegistry } from "./plugins";
+
+// Kick off plugin loading before mount and render immediately: contributions
+// appear as each plugin's chunk lands (the app re-renders from registry
+// subscriptions). With no `plugins` in cms.config.js the list is empty and
+// this is a no-op.
+void loadPlugins(plugins, pluginRegistry);
+
+// Canonical react-native-web mount: runApplication injects the styles that make
+// the app root fill the viewport, which the RN `flex: 1` layouts depend on.
+AppRegistry.registerComponent("CMS", () => App);
+AppRegistry.runApplication("CMS", {
+  rootTag: document.getElementById("root"),
+});

package/app/src/media.ts

@@ -0,0 +1,151 @@
+import { useMemo } from "react";
+import { useApolloClient, useQuery } from "@apollo/client";
+import type { MediaApi, MediaAsset, MediaFacets, MediaResolution, MediaSetInfo } from "@gogitcms/design-system";
+import {
+  MEDIA,
+  MEDIA_BY_ID,
+  MEDIA_COUNT,
+  MEDIA_FACETS,
+  MEDIA_SETS,
+  RESOLVE_MEDIA,
+  CREATE_MEDIA_UPLOAD,
+  FINALIZE_MEDIA_UPLOAD,
+} from "./queries";
+
+// The Apollo implementation of the design system's media seam. The DS owns the
+// picker and preview UI and knows nothing about transport; this file is the only
+// place media queries live on the web client.
+
+// Reads bypass the cache deliberately. A Media carries a presigned `url` with a
+// short lifetime, so a cached copy from an hour ago would hand the editor an
+// expired URL and render a broken image.
+const NO_CACHE = { fetchPolicy: "no-cache" as const };
+
+export function useMediaApi(repositoryId?: string, branchId?: string, project?: string): MediaApi | undefined {
+  const client = useApolloClient();
+  const skip = !repositoryId || !branchId;
+
+  // Sets come from the branch's config and change only on re-import, so unlike
+  // the assets themselves they are worth caching.
+  const { data } = useQuery(MEDIA_SETS, {
+    // Media hangs off the config, which is per project, so the sets a picker
+    // browses are the selected project's — not every project's on the branch.
+    variables: { repositoryId, branchId, project: project ?? null },
+    skip,
+  });
+  const sets: MediaSetInfo[] = data?.mediaSets ?? [];
+
+  return useMemo(() => {
+    if (skip) return undefined;
+    // Every media operation is scoped to one project's config, so the project
+    // travels with the ids rather than being remembered per call site. On a
+    // branch carrying several projects the server cannot pick for us: omitting
+    // it is an ambiguity error, not a default.
+    const ids = { repositoryId, branchId, project: project ?? null };
+
+    return {
+      sets,
+
+      resolve: async (paths, documentPath) => {
+        if (paths.length === 0) return [];
+        const res = await client.query({
+          query: RESOLVE_MEDIA,
+          variables: { ...ids, paths, documentPath: documentPath ?? null },
+          ...NO_CACHE,
+        });
+        return (res.data?.resolveMedia ?? []) as MediaResolution[];
+      },
+
+      byId: async (id) => {
+        const res = await client.query({
+          query: MEDIA_BY_ID,
+          variables: { ...ids, id },
+          ...NO_CACHE,
+        });
+        return (res.data?.mediaById ?? null) as MediaAsset | null;
+      },
+
+      list: async ({ set, kinds, search, filters, limit, offset }) => {
+        const res = await client.query({
+          query: MEDIA,
+          variables: {
+            ...ids,
+            set: set ?? null,
+            kinds: kinds ?? null,
+            search: search ?? null,
+            filters: filters ?? null,
+            limit: limit ?? null,
+            offset: offset ?? null,
+          },
+          ...NO_CACHE,
+        });
+        return (res.data?.media ?? []) as MediaAsset[];
+      },
+
+      count: async ({ set, kinds, search, filters }) => {
+        const res = await client.query({
+          query: MEDIA_COUNT,
+          variables: {
+            ...ids,
+            set: set ?? null,
+            kinds: kinds ?? null,
+            search: search ?? null,
+            filters: filters ?? null,
+          },
+          ...NO_CACHE,
+        });
+        return (res.data?.mediaCount ?? 0) as number;
+      },
+
+      // Facets describe the set, not the current result, so unlike the listing
+      // they are safe to cache: they only change when media is re-imported.
+      facets: async (set) => {
+        const res = await client.query({
+          query: MEDIA_FACETS,
+          variables: { ...ids, set: set ?? null },
+        });
+        return res.data.mediaFacets as MediaFacets;
+      },
+
+      // Three steps: ask the server for a presigned PUT, send the bytes straight
+      // to the object store, then tell the server they landed. The file never
+      // passes through the API process.
+      upload: async ({ set, file, folder }) => {
+        const granted = await client.mutate({
+          mutation: CREATE_MEDIA_UPLOAD,
+          variables: {
+            ...ids,
+            set,
+            filename: file.name,
+            contentType: file.type || "application/octet-stream",
+            size: file.size,
+            folder: folder ?? null,
+          },
+        });
+        const grant = granted.data?.createMediaUpload;
+        if (!grant) throw new Error("Upload was not granted.");
+
+        const put = await fetch(grant.url, {
+          method: "PUT",
+          // Must match the type the grant was issued for. Presigning does not
+          // actually enforce this (S3 and MinIO both accept a different header),
+          // so the server re-checks the stored object on finalize and rejects a
+          // mismatch — sending the right one here keeps that check passing.
+          headers: { "Content-Type": file.type || "application/octet-stream" },
+          body: file,
+        });
+        if (!put.ok) {
+          throw new Error(`Upload failed (${put.status}). The file was not stored.`);
+        }
+
+        const finalized = await client.mutate({
+          mutation: FINALIZE_MEDIA_UPLOAD,
+          variables: { ...ids, uploadId: grant.uploadId },
+        });
+        const asset = finalized.data?.finalizeMediaUpload;
+        if (!asset) throw new Error("Upload could not be finalized.");
+        return asset as MediaAsset;
+      },
+    };
+  }, [client, repositoryId, branchId, project, skip, sets]);
+}