@stapel/workspaces-react 0.1.0

package/package.json

@@ -0,0 +1,85 @@
+{
+  "name": "@stapel/workspaces-react",
+  "version": "0.1.0",
+  "description": "Headless React flow pair for stapel-workspaces: typed API client, TanStack Query hooks, flow machines, headless components, and i18n keys. Zero visual opinion.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/usestapel/stapel-react.git",
+    "directory": "packages/workspaces-react"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./i18n/ru": {
+      "types": "./dist/i18n/ru.d.ts",
+      "default": "./dist/i18n/ru.js"
+    },
+    "./manifest": "./manifest.json",
+    "./manifest.json": "./manifest.json",
+    "./llms.txt": "./llms.txt",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "src",
+    "tsconfig.json",
+    "README.md",
+    "MODULE.md",
+    "CHANGELOG.md",
+    "manifest.json",
+    "llms.txt"
+  ],
+  "size-limit": [
+    {
+      "name": "index — the ru locale must NOT be in the main bundle",
+      "path": "dist/index.js",
+      "limit": "12 KB"
+    },
+    {
+      "name": "i18n/ru subpath (opt-in locale: en floor + generated ru + ru UI)",
+      "path": "dist/i18n/ru.js",
+      "limit": "3.5 KB"
+    }
+  ],
+  "peerDependencies": {
+    "@stapel/core": ">=0.3.0 <1.0.0",
+    "@tanstack/react-query": "^5.0.0",
+    "react": ">=19"
+  },
+  "devDependencies": {
+    "@size-limit/preset-small-lib": "^11.2.0",
+    "@tanstack/react-query": "^5.81.0",
+    "@testing-library/react": "^16.3.0",
+    "@types/react": "^19.1.0",
+    "@types/react-dom": "^19.1.0",
+    "jsdom": "^26.1.0",
+    "msw": "^2.10.2",
+    "react": "^19.1.0",
+    "react-dom": "^19.1.0",
+    "size-limit": "^11.2.0",
+    "typescript": "^5.8.3",
+    "vitest": "^3.2.4",
+    "@stapel/showcase": "^0.2.0",
+    "@stapel/tokens": "^0.2.0",
+    "@stapel/core": "^0.3.0"
+  },
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.demo.json && vitest run",
+    "lint": "eslint .",
+    "size": "size-limit"
+  }
+}

package/src/analytics/generated/events.json

@@ -0,0 +1,7 @@
+{
+  "$generated": "by scripts/gen-events.mjs — do not edit; drift-gated (pnpm gen:events:check)",
+  "package": "@stapel/workspaces-react",
+  "version": "0.1.0",
+  "defined": [],
+  "flows": []
+}

package/src/api/extensions.ts

@@ -0,0 +1,7 @@
+/**
+ * Hand-authored API surface the codegen does not (yet) cover — browser-redirect
+ * URL builders, open-redirect guards, narrow domain type-guards, header
+ * conventions. Everything that CAN be derived from schema.json belongs in the
+ * generated operations (`api/workspacesApi.ts`), not here.
+ */
+export {};

package/src/api/types.ts

@@ -0,0 +1,58 @@
+/**
+ * Wire types for the stapel-workspaces HTTP contract — **derived from the generated
+ * OpenAPI surface** (frontend-standard §2/§3), never hand-maintained. The
+ * single source of truth is `components["schemas"]` from `@stapel/core`
+ * (`packages/core/src/generated/schema.ts`, produced by `pnpm gen:api` from the
+ * unified all-modules OpenAPI). Alias the schemas this pair uses under local
+ * names here; do NOT write parallel response bodies. Where drf-spectacular +
+ * openapi-typescript under-describe the runtime, apply a small documented
+ * correction (see auth-react `api/types.ts` for the three canonical patterns).
+ */
+import type { components } from "@stapel/core";
+
+/** The generated schema table — the one source of truth for wire shapes. */
+export type Schemas = components["schemas"];
+
+// ── aliases (the stapel-workspaces schemas this pair uses) ────────────────────
+
+/** One workspace — identity, storage, my role, member count (GET/POST/PATCH). */
+export type Workspace = Schemas["WorkspaceResponse"];
+/** GET / 200 body — the caller's workspaces (memberships). */
+export type WorkspaceList = Schemas["WorkspaceListResponse"];
+/** POST / request body — create a workspace (slug auto-generated when omitted). */
+export type WorkspaceCreate = Schemas["WorkspaceCreateRequest"];
+/** PATCH /{id} request body — a partial name / slug / settings update. */
+export type WorkspaceUpdate = Schemas["PatchedWorkspaceUpdateRequest"];
+/** One workspace member (GET members, PATCH member role, POST accept). */
+export type Member = Schemas["MemberResponse"];
+/** GET /{id}/members 200 body — a workspace's members. */
+export type MemberList = Schemas["MemberListResponse"];
+/** POST /{id}/members/invite request body — one or more emails + a role. */
+export type MemberInvite = Schemas["MemberInviteRequest"];
+/** POST /{id}/members/invite 201 body — the created invitations. */
+export type MemberInviteResult = Schemas["MemberInviteResponse"];
+/** PATCH /{id}/members/{userId} request body — the new role. */
+export type MemberRoleUpdate = Schemas["PatchedMemberUpdateRequest"];
+/** One pending/accepted invitation (a row of {@link MemberInviteResult}). */
+export type Invitation = Schemas["InvitationResponse"];
+/** POST /invitations/accept request body — the token from the email link. */
+export type InvitationAccept = Schemas["InvitationAcceptRequest"];
+
+// ── documented corrections (drf-spectacular under-describes) ──────────────────
+
+/**
+ * A workspace membership role, ordered least→most privileged. The generated
+ * schema types `MemberResponse.role` / the invite `role` as a bare `string`,
+ * but the backend (`models.Role`, a Django `TextChoices`) constrains it to
+ * exactly these values. Narrowing here gives call sites a checked union — a
+ * documented correction of the same kind auth-react/billing-react apply.
+ */
+export type WorkspaceRole = "owner" | "admin" | "member" | "viewer";
+
+/**
+ * A workspace category. The generated schema types `WorkspaceResponse.type` /
+ * the create `type` as a bare `string`; the backend (`models.WorkspaceType`)
+ * constrains it to exactly these two. Narrowed for the same reason as
+ * {@link WorkspaceRole}.
+ */
+export type WorkspaceKind = "personal" | "work";

package/src/api/workspacesApi.ts

@@ -0,0 +1,139 @@
+import type { StapelClient, StapelRequestOptions } from "@stapel/core";
+import type {
+  Member,
+  MemberInvite,
+  MemberInviteResult,
+  MemberList,
+  MemberRoleUpdate,
+  InvitationAccept,
+  Workspace,
+  WorkspaceCreate,
+  WorkspaceList,
+  WorkspaceUpdate,
+} from "./types.js";
+
+/**
+ * CSRF rule for cookie-authenticated browser clients (mirrors auth-react): the
+ * simplest SPA rule is to always send `X-Requested-With: XMLHttpRequest` on
+ * mutating requests. Header-token clients ignore it; it is harmless there, so
+ * every mutation carries it.
+ */
+const CSRF_HEADERS: Record<string, string> = {
+  "X-Requested-With": "XMLHttpRequest",
+};
+
+function mutating(
+  options?: Omit<StapelRequestOptions, "method" | "body">
+): Omit<StapelRequestOptions, "method" | "body"> {
+  return {
+    ...options,
+    headers: { ...CSRF_HEADERS, ...options?.headers },
+  };
+}
+
+/**
+ * The pair's typed operation surface — one method per stapel-workspaces endpoint
+ * a signed-in browser client may call, bound to the injected {@link StapelClient}
+ * (the per-module override seam of frontend-standard §7.2). Paths are relative
+ * to the runtime's `baseUrl` (e.g. `/workspaces/api`).
+ *
+ * The service-to-service `GET /internal/{ws}/members/{user}` (membership check
+ * from another backend) and `POST /internal/users/{user}/personal` (get-or-create
+ * a personal workspace on first login) are intentionally absent — they are
+ * machine-to-machine surfaces (`IsServiceRequest | IsStaffUser`), not part of the
+ * signed-in UI this pair drives.
+ *
+ * These operations will be GENERATED from schema.json operationIds by gen-api
+ * v2 (task `core-typed-ops`); until then they are hand-authored here (the ONE
+ * legal home of path strings — `stapel/no-string-paths` §2.3 carve-out).
+ */
+export interface WorkspacesApi {
+  readonly client: StapelClient;
+
+  /** The caller's workspaces (accepted memberships, newest-accessed first). */
+  listWorkspaces(): Promise<WorkspaceList>;
+  /** Create a workspace and seed the caller as owner. */
+  createWorkspace(body: WorkspaceCreate): Promise<Workspace>;
+  /** A single workspace by id (touches last-accessed). */
+  getWorkspace(workspaceId: string): Promise<Workspace>;
+  /** Partially update a workspace's name / slug / settings (admin+). */
+  updateWorkspace(
+    workspaceId: string,
+    patch: WorkspaceUpdate
+  ): Promise<Workspace>;
+  /** Soft-delete a workspace (owner only). */
+  deleteWorkspace(workspaceId: string): Promise<void>;
+
+  /** A workspace's members (viewer+). */
+  listMembers(workspaceId: string): Promise<MemberList>;
+  /** Invite one or more emails to a workspace at a role (admin+). */
+  inviteMembers(
+    workspaceId: string,
+    body: MemberInvite
+  ): Promise<MemberInviteResult>;
+  /** Change a member's role (admin+; owner grants require owner). */
+  updateMemberRole(
+    workspaceId: string,
+    userId: string,
+    patch: MemberRoleUpdate
+  ): Promise<Member>;
+  /** Remove a member from a workspace (admin+; the last owner is protected). */
+  removeMember(workspaceId: string, userId: string): Promise<void>;
+
+  /** Accept an invitation by its token — returns the caller's new membership. */
+  acceptInvitation(body: InvitationAccept): Promise<Member>;
+}
+
+export function createWorkspacesApi(client: StapelClient): WorkspacesApi {
+  return {
+    client,
+
+    listWorkspaces: () => client.get("/"),
+
+    createWorkspace: (body) =>
+      client.post("/", body satisfies WorkspaceCreate, mutating()),
+
+    getWorkspace: (workspaceId) =>
+      client.get(`/${encodeURIComponent(workspaceId)}`),
+
+    updateWorkspace: (workspaceId, patch) =>
+      client.patch(
+        `/${encodeURIComponent(workspaceId)}`,
+        patch satisfies WorkspaceUpdate,
+        mutating()
+      ),
+
+    deleteWorkspace: (workspaceId) =>
+      client.delete(`/${encodeURIComponent(workspaceId)}`, mutating()),
+
+    listMembers: (workspaceId) =>
+      client.get(`/${encodeURIComponent(workspaceId)}/members`),
+
+    inviteMembers: (workspaceId, body) =>
+      client.post(
+        `/${encodeURIComponent(workspaceId)}/members/invite`,
+        body satisfies MemberInvite,
+        mutating()
+      ),
+
+    updateMemberRole: (workspaceId, userId, patch) =>
+      client.patch(
+        `/${encodeURIComponent(workspaceId)}/members/${encodeURIComponent(userId)}`,
+        patch satisfies MemberRoleUpdate,
+        mutating()
+      ),
+
+    removeMember: (workspaceId, userId) =>
+      client.delete(
+        `/${encodeURIComponent(workspaceId)}/members/${encodeURIComponent(userId)}`,
+        mutating()
+      ),
+
+    acceptInvitation: (body) =>
+      client.post(
+        "/invitations/accept",
+        body satisfies InvitationAccept,
+        mutating()
+      ),
+  };
+}

package/src/flows/errors.ts

@@ -0,0 +1,16 @@
+import { toFlowError as coreToFlowError } from "@stapel/core";
+import type { FlowError } from "@stapel/core";
+
+export type { FlowError } from "@stapel/core";
+export { isErrorCode } from "@stapel/core";
+
+/**
+ * Fold any thrown value into a {@link FlowError} using this pair's own
+ * module-scoped fallback key (`workspaces.error.unknown`, an en string in
+ * {@link workspacesI18nBundleEn}) so a non-`StapelApiError` fault still renders
+ * real copy rather than a raw key. The primitive lives in `@stapel/core`
+ * (frontend-core-architecture §4b); this wrapper only pins the fallback.
+ */
+export function toFlowError(error: unknown): FlowError {
+  return coreToFlowError(error, "workspaces.error.unknown");
+}

package/src/flows/generated/flows.gen.ts

@@ -0,0 +1,38 @@
+// AUTO-GENERATED by scripts/gen-flows.mjs — do not edit by hand.
+// Source: unified Stapel flows.json (stapel-example-monolith `make codegen`).
+// Regenerate: pnpm gen:flows   ·   Drift gate: pnpm gen:flows:check
+
+/**
+ * The canonical workspaces flow registry — the machine-facing projection of the
+ * flow source (docs/flow-system.md §5). Each entry carries a flow's canonical
+ * id (`flow.<id>.<step>` analytics funnel = this flow), its i18n keys, and its
+ * ordered step→endpoint contract. Flow machines bind their `id` to
+ * `WORKSPACES_FLOWS[...].id` so a backend flow rename/re-step surfaces as a drift
+ * here (`pnpm gen:flows:check`) rather than a silent analytics/contract skew.
+ */
+export const WORKSPACES_FLOWS = {
+
+} as const;
+
+/** Canonical flow ids present in flows.json (a subset grows as the backend annotates more). */
+export type WorkspacesFlowId = keyof typeof WORKSPACES_FLOWS;
+
+export type WorkspacesFlowSpec = (typeof WORKSPACES_FLOWS)[WorkspacesFlowId];
+
+export interface FlowEndpoint {
+  readonly method: string;
+  readonly path: string;
+}
+
+/** All HTTP endpoints a flow touches, in step order (for the contract test / MSW). */
+export function flowEndpoints(id: WorkspacesFlowId): readonly FlowEndpoint[] {
+  // Guard the empty-registry case: a module with no annotated flows makes
+  // `WorkspacesFlowId` = `never` and `WORKSPACES_FLOWS` = `{}`, so a direct
+  // `WORKSPACES_FLOWS[id].steps` does not type-check. Widening to an optional spec
+  // keeps this body valid for the zero-flow scaffold AND correct once the
+  // backend annotates `@flow_step` and the registry fills in.
+  const spec = WORKSPACES_FLOWS[id] as
+    | { readonly steps: readonly { readonly endpoints: readonly FlowEndpoint[] }[] }
+    | undefined;
+  return spec ? spec.steps.flatMap((s) => s.endpoints) : [];
+}

package/src/flows/generated/flows.json

@@ -0,0 +1 @@
+[]

package/src/headless/AcceptInvitation.tsx

@@ -0,0 +1,53 @@
+import type { ReactNode } from "react";
+import type { StapelApiError } from "@stapel/core";
+import type { Member } from "../api/types.js";
+import { useAcceptInvitation } from "../model/mutations.js";
+
+/** Render-prop bag for {@link AcceptInvitation}. */
+export interface AcceptInvitationBag {
+  /** Accept the invitation identified by `token`. */
+  accept(token: string): void;
+  /** An accept call is in flight. */
+  readonly isAccepting: boolean;
+  /** The accept succeeded — the caller's new membership. */
+  readonly isAccepted: boolean;
+  /** The membership created on success, else null. */
+  readonly member: Member | null;
+  /** The accept failed. */
+  readonly isError: boolean;
+  /**
+   * The error, when `isError`. A dead token surfaces a localizable
+   * `StapelApiError` — `error.400.invitation_expired` /
+   * `error.400.invitation_revoked` / `error.400.invitation_already_used` /
+   * `error.404.invitation_not_found` — each carrying its backend remediation.
+   */
+  readonly error: StapelApiError | null;
+}
+
+/**
+ * Headless invitation-accept control — a renderless "join by token" action.
+ * Wires {@link useAcceptInvitation} and hands an {@link AcceptInvitationBag} to
+ * `children`; bring your own accept button / status. Zero visual opinion
+ * (frontend-standard §2).
+ *
+ * ```tsx
+ * <AcceptInvitation>
+ *   {({ accept, isAccepted, error }) => ( ... )}
+ * </AcceptInvitation>
+ * ```
+ */
+export function AcceptInvitation(props: {
+  children: (bag: AcceptInvitationBag) => ReactNode;
+}): ReactNode {
+  const mutation = useAcceptInvitation();
+  return props.children({
+    accept: (token) => {
+      mutation.mutate({ token });
+    },
+    isAccepting: mutation.isPending,
+    isAccepted: mutation.isSuccess,
+    member: mutation.data ?? null,
+    isError: mutation.isError,
+    error: mutation.error ?? null,
+  });
+}

package/src/headless/Members.tsx

@@ -0,0 +1,89 @@
+import type { ReactNode } from "react";
+import type { StapelApiError } from "@stapel/core";
+import type { Member, MemberInvite } from "../api/types.js";
+import { useMembers } from "../model/queries.js";
+import {
+  useInviteMembers,
+  useRemoveMember,
+  useUpdateMemberRole,
+} from "../model/mutations.js";
+import type { MemberRoleChange } from "../model/mutations.js";
+
+/** Render-prop bag for {@link Members}. */
+export interface MembersBag {
+  /** The workspace's members once loaded (empty before load). */
+  readonly members: readonly Member[];
+  /** The initial member-list load is in flight. */
+  readonly isLoading: boolean;
+  /** The read, an invite, a role change, or a removal failed. */
+  readonly isError: boolean;
+  /** The error, when `isError` (a localizable `StapelApiError`), else null. */
+  readonly error: StapelApiError | null;
+  /** Invite one or more emails at a role. */
+  invite(body: MemberInvite): void;
+  /** An invite call is in flight. */
+  readonly isInviting: boolean;
+  /** Change a member's role. */
+  updateRole(change: MemberRoleChange): void;
+  /** A role-change call is in flight. */
+  readonly isUpdatingRole: boolean;
+  /** Remove a member by `userId`. */
+  remove(userId: string): void;
+  /** A removal call is in flight. */
+  readonly isRemoving: boolean;
+  /** Refetch the member list from the server. */
+  refetch(): void;
+}
+
+/**
+ * Headless member roster — a renderless view + invite / role-change / removal
+ * controls over one workspace's members. Wires {@link useMembers},
+ * {@link useInviteMembers}, {@link useUpdateMemberRole}, and
+ * {@link useRemoveMember} and hands a {@link MembersBag} to `children`; bring your
+ * own roster / invite form / role menu. Zero visual opinion (frontend-standard §2).
+ *
+ * ```tsx
+ * <Members workspaceId={id}>
+ *   {({ members, invite, updateRole, remove }) => ( ... )}
+ * </Members>
+ * ```
+ */
+export function Members(props: {
+  workspaceId: string;
+  children: (bag: MembersBag) => ReactNode;
+}): ReactNode {
+  const query = useMembers(props.workspaceId);
+  const inviteMutation = useInviteMembers(props.workspaceId);
+  const roleMutation = useUpdateMemberRole(props.workspaceId);
+  const removeMutation = useRemoveMember(props.workspaceId);
+  return props.children({
+    members: query.data?.members ?? [],
+    isLoading: query.isLoading,
+    isError:
+      query.isError ||
+      inviteMutation.isError ||
+      roleMutation.isError ||
+      removeMutation.isError,
+    error:
+      query.error ??
+      inviteMutation.error ??
+      roleMutation.error ??
+      removeMutation.error ??
+      null,
+    invite: (body) => {
+      inviteMutation.mutate(body);
+    },
+    isInviting: inviteMutation.isPending,
+    updateRole: (change) => {
+      roleMutation.mutate(change);
+    },
+    isUpdatingRole: roleMutation.isPending,
+    remove: (userId) => {
+      removeMutation.mutate(userId);
+    },
+    isRemoving: removeMutation.isPending,
+    refetch: () => {
+      void query.refetch();
+    },
+  });
+}

package/src/headless/WorkspaceList.tsx

@@ -0,0 +1,58 @@
+import type { ReactNode } from "react";
+import type { StapelApiError } from "@stapel/core";
+import type { Workspace, WorkspaceCreate } from "../api/types.js";
+import { useWorkspaces } from "../model/queries.js";
+import { useCreateWorkspace } from "../model/mutations.js";
+
+/** Render-prop bag for {@link WorkspaceList}. */
+export interface WorkspaceListBag {
+  /** The caller's workspaces once loaded (empty before load). */
+  readonly workspaces: readonly Workspace[];
+  /** The initial list load is in flight (no data yet). */
+  readonly isLoading: boolean;
+  /** Either the read or the create failed. */
+  readonly isError: boolean;
+  /** The error, when `isError` (a localizable `StapelApiError`), else null. */
+  readonly error: StapelApiError | null;
+  /** Create a workspace (owner-seeded). */
+  create(body: WorkspaceCreate): void;
+  /** A create call is in flight. */
+  readonly isCreating: boolean;
+  /** The workspace created by the last `create`, else null. */
+  readonly created: Workspace | null;
+  /** Refetch the list from the server. */
+  refetch(): void;
+}
+
+/**
+ * Headless workspace list — a renderless view + create control over the caller's
+ * workspaces. Wires {@link useWorkspaces} + {@link useCreateWorkspace} and hands a
+ * {@link WorkspaceListBag} to `children`; bring your own list / create form.
+ * Zero visual opinion (frontend-standard §2).
+ *
+ * ```tsx
+ * <WorkspaceList>
+ *   {({ workspaces, create }) => ( ... )}
+ * </WorkspaceList>
+ * ```
+ */
+export function WorkspaceList(props: {
+  children: (bag: WorkspaceListBag) => ReactNode;
+}): ReactNode {
+  const query = useWorkspaces();
+  const mutation = useCreateWorkspace();
+  return props.children({
+    workspaces: query.data?.workspaces ?? [],
+    isLoading: query.isLoading,
+    isError: query.isError || mutation.isError,
+    error: query.error ?? mutation.error ?? null,
+    create: (body) => {
+      mutation.mutate(body);
+    },
+    isCreating: mutation.isPending,
+    created: mutation.data ?? null,
+    refetch: () => {
+      void query.refetch();
+    },
+  });
+}

package/src/headless/WorkspacesProvider.tsx

@@ -0,0 +1,25 @@
+import type { ReactElement, ReactNode } from "react";
+import { WorkspacesRuntimeContext } from "../model/context.js";
+import type { WorkspacesRuntime } from "../model/runtime.js";
+
+/**
+ * Provides the wired {@link WorkspacesRuntime} to every workspaces hook and
+ * headless component below it. Bring your own visual shell — this component
+ * renders nothing of its own.
+ *
+ * ```tsx
+ * const runtime = createWorkspacesRuntime({ baseUrl: "/workspaces/api/" });
+ * // give runtime.client to core's <StapelConfigProvider config={{ client }}>
+ * <WorkspacesProvider runtime={runtime}>{app}</WorkspacesProvider>
+ * ```
+ */
+export function WorkspacesProvider(props: {
+  runtime: WorkspacesRuntime;
+  children: ReactNode;
+}): ReactElement {
+  return (
+    <WorkspacesRuntimeContext.Provider value={props.runtime}>
+      {props.children}
+    </WorkspacesRuntimeContext.Provider>
+  );
+}

package/src/i18n/errorsMap.ts

@@ -0,0 +1,31 @@
+/**
+ * The pair's error map (frontend-standard §4 checklist #7, frontend-core §2.5):
+ * the generated `code → { status, params, remediation, en }` catalog plus a
+ * tiny `explain()` lookup. Backs the manifest `errors` block and gives hosts a
+ * mechanical UX branch beside `t(code, params)`. The map itself is generated
+ * from the backend registry (`pnpm gen:errors`); this file only adds the lookup
+ * helper and re-exports the public surface.
+ */
+import { WORKSPACES_ERRORS } from "./generated/errors.gen.js";
+import type { Remediation } from "./generated/errors.gen.js";
+
+export {
+  WORKSPACES_ERRORS,
+  WORKSPACES_ERROR_CODES,
+  workspacesErrorBundleEn,
+} from "./generated/errors.gen.js";
+export type {
+  WorkspacesErrorCode,
+  WorkspacesErrorSpec,
+  Remediation,
+} from "./generated/errors.gen.js";
+
+/**
+ * Resolve a backend error code to its remediation hint, or `undefined` for a
+ * code this module doesn't know (e.g. a cross-cutting `stapel.http.*` fallback).
+ * Zero guessing at runtime — a static lookup over the generated map.
+ */
+export function explainWorkspacesError(code: string): Remediation | undefined {
+  return (WORKSPACES_ERRORS as Record<string, { remediation: Remediation }>)[code]
+    ?.remediation;
+}