@thebes/cadmus 0.2.1 → 0.3.0

package/dist/{index-BUrCSGVb.d.cts → index-BRZrCTsN.d.ts}

@@ -1,6 +1,499 @@
 import { BaseSQLiteDatabase, SQLiteTableWithColumns, sqliteTable } from "drizzle-orm/sqlite-core";
 import { InferInsertModel, InferSelectModel, SQL } from "drizzle-orm";
 
+//#region src/cms/blocks.d.ts
+/**
+ * Renderer registry for block/document content (issue #13) — adopts the
+ * Portable Text + `@portabletext/react` pattern (idea, not code): a content
+ * document is a serializable **array of typed blocks**, and rendering is a
+ * lookup of `block.type → renderer`, not a hand-rolled `switch`. Adding a
+ * new block type becomes "register a renderer" with no edit to a central
+ * branch.
+ *
+ * Framework-agnostic on purpose: `TRenderer` is whatever a host wants a
+ * block's renderer to be — a string-producing function (SSR/preview HTML),
+ * an Astro component, a Solid component, etc. The registry only does lookup,
+ * fallback, and introspection; it never assumes a rendering technology.
+ */
+/**
+ * The minimal shape every block must have: a string discriminant under
+ * `type`. (Portable Text uses `_type`; Cadmea content is TipTap-JSON-shaped
+ * and already keyed on `type`, so the registry keys on `type` to stay
+ * drop-in with stored content — the editor can stay TipTap.)
+ */
+interface PortableBlockLike {
+  type: string;
+}
+interface BlockRegistry<TRenderer> {
+  /** Register (or replace) the renderer for a block type. Chainable. */
+  register(type: string, renderer: TRenderer): BlockRegistry<TRenderer>;
+  /** Register several at once. Chainable. */
+  registerMany(renderers: Record<string, TRenderer>): BlockRegistry<TRenderer>;
+  /** The renderer registered for `type`, or `undefined`. */
+  get(type: string): TRenderer | undefined;
+  /** Whether a renderer is registered for `type`. */
+  has(type: string): boolean;
+  /** Every registered block type, in registration order. */
+  types(): string[];
+  /** Set the fallback used when a type has no registered renderer. Chainable. */
+  setFallback(renderer: TRenderer): BlockRegistry<TRenderer>;
+  /** The renderer for `type`, else the fallback, else `undefined`. */
+  resolve(type: string): TRenderer | undefined;
+}
+/**
+ * Create a block renderer registry. Seed it with an initial `type → renderer`
+ * map and/or an `options.fallback` for unknown types.
+ *
+ * ```ts
+ * const registry = createBlockRegistry<StringBlockRenderer>({
+ *   divider: () => "<hr>",
+ * });
+ * registry.register("hero", (b) => `<h1>${b.heading}</h1>`);
+ * renderBlocksToString(blocks, registry);
+ * ```
+ */
+declare function createBlockRegistry<TRenderer>(initial?: Record<string, TRenderer>, options?: {
+  fallback?: TRenderer;
+}): BlockRegistry<TRenderer>;
+/**
+ * A renderer that turns one block into an HTML string — the registry value
+ * type for SSR/preview paths that build markup as strings (e.g. a Hono
+ * preview route) rather than mounting components.
+ */
+type StringBlockRenderer<TBlock extends PortableBlockLike = PortableBlockLike> = (block: TBlock) => string;
+/**
+ * Render an array of blocks to a single HTML string via a registry of
+ * {@link StringBlockRenderer}s. Blocks whose type resolves to no renderer
+ * (and no fallback) contribute the empty string — the same forgiving
+ * behavior the old hand-rolled `switch` had for unknown types.
+ */
+declare function renderBlocksToString<TBlock extends PortableBlockLike>(blocks: readonly TBlock[], registry: BlockRegistry<StringBlockRenderer<TBlock>>): string;
+//#endregion
+//#region src/errors.d.ts
+declare global {
+  interface ErrorConstructor {
+    captureStackTrace?(targetObject: object, constructorOpt?: Function): void;
+  }
+}
+/**
+ * Base class for all Cadmus errors.
+ * All primitives throw CadmusError or a typed subclass — never a raw Error.
+ *
+ * @example
+ * try {
+ *   await createMagicLink({ kv, email, to })
+ * } catch (e) {
+ *   if (e instanceof CadmusAuthError) {
+ *     // auth-specific handling
+ *   } else if (e instanceof CadmusError) {
+ *     // any cadmus error — e.code tells you which primitive threw
+ *   } else {
+ *     throw e // re-throw unknown errors
+ *   }
+ * }
+ */
+declare class CadmusError extends Error {
+  readonly code: string;
+  readonly cause?: unknown | undefined;
+  constructor(message: string, code: string, cause?: unknown | undefined);
+}
+/** Thrown by @thebes/cadmus/auth primitives */
+declare class CadmusAuthError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/db primitives */
+declare class CadmusDbError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/storage primitives */
+declare class CadmusStorageError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/cache primitives */
+declare class CadmusCacheError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/email primitives */
+declare class CadmusEmailError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/session primitives */
+declare class CadmusSessionError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/rate-limit primitives */
+declare class CadmusRateLimitError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/queues primitives */
+declare class CadmusQueueError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/** Thrown by @thebes/cadmus/cms primitives */
+declare class CadmusCmsError extends CadmusError {
+  constructor(message: string, cause?: unknown);
+}
+/**
+ * Thrown by @thebes/cadmus/cms's createLocalApi when a collection's
+ * `access` function rejects an operation. A distinct subclass (rather than
+ * a plain CadmusCmsError) so consumers like mountCmsRoutes can map it to
+ * 403 by `instanceof`, not by matching on message text.
+ */
+declare class CadmusAccessDeniedError extends CadmusCmsError {
+  constructor(message: string, cause?: unknown);
+}
+/**
+ * One failed field-validation rule (issue #16). `path` is the field's key
+ * (flattened, e.g. `shippingAddress_city` for a group subfield). `severity`
+ * lets a rule warn without blocking the write — only `"error"` violations
+ * cause createLocalApi to throw; `"warning"` ones are carried through for
+ * the studio to surface non-blockingly.
+ */
+interface ValidationViolation {
+  path: string;
+  message: string;
+  severity: "error" | "warning";
+}
+/**
+ * Thrown by createLocalApi when a collection's field-validation rules
+ * (Sanity-style chainable `Rule` API — see cms/validation.ts) reject a
+ * create/update. Carries the structured `violations` so the studio can
+ * surface per-field messages, and `mountCmsRoutes` can map it to HTTP 422
+ * by `instanceof` rather than message matching. A subclass of
+ * CadmusCmsError, so existing `instanceof CadmusCmsError` handling still
+ * catches it. Only `"error"`-severity violations are ever thrown.
+ */
+declare class CadmusValidationError extends CadmusCmsError {
+  readonly violations: ValidationViolation[];
+  constructor(message: string, violations: ValidationViolation[], cause?: unknown);
+}
+/**
+ * Thrown by @thebes/cadmus/hono's `createCmsApiClient` when a request
+ * against a `mountCmsRoutes` surface returns a non-2xx response. Carries
+ * the HTTP status and parsed body so callers can branch on `status`
+ * (e.g. 403 → access denied, 404 → not found) instead of re-parsing
+ * `{ error: string }` response bodies by hand.
+ */
+declare class CadmusApiError extends CadmusError {
+  readonly status: number;
+  readonly body: unknown;
+  constructor(message: string, status: number, body: unknown);
+}
+//#endregion
+//#region src/cms/localApi.d.ts
+type AnyTable$1 = SQLiteTableWithColumns<any>;
+/**
+ * `TContext` is the per-request value passed to every method and forwarded
+ * unchanged to the collection's `access` functions (see {@link CollectionAccess}).
+ * Cadmus doesn't standardize its shape — Cadmea types it as `{ session }`,
+ * other consumers may type it differently. `context` is a required first
+ * argument on every method (not optional) so a call site can't forget it.
+ */
+interface LocalApi<TTable extends AnyTable$1, TContext = unknown> {
+  /**
+   * `depth: 0` (default) returns relationship fields as bare ids; `depth: 1`
+   * batch-resolves `hasMany: false` relationship fields into the related
+   * row, gated by that collection's own `read` access fn — see
+   * `resolveRelationships` below. Requires `createLocalApi`'s `registry`
+   * param; throws CadmusCmsError if `depth: 1` is requested without one.
+   */
+  find(context: TContext, options?: {
+    where?: SQL;
+    depth?: RelationshipDepth; /** Row cap, applied after `where` — for paginated list views. */
+    limit?: number; /** Rows to skip, applied after `where` — pairs with `limit`. */
+    offset?: number; /** One or more `asc(table.col)`/`desc(table.col)` expressions. */
+    orderBy?: SQL | SQL[];
+  }): Promise<InferSelectModel<TTable>[]>;
+  findByID(context: TContext, id: number, options?: {
+    depth?: RelationshipDepth;
+  }): Promise<InferSelectModel<TTable>>;
+  /**
+   * Total row count for `where` (ignoring `limit`/`offset`) — pairs with
+   * `find` to compute page counts/next-page availability without fetching
+   * every row. Gated by the same `read` access check as `find`.
+   */
+  count(context: TContext, options?: {
+    where?: SQL;
+  }): Promise<number>;
+  /**
+   * Full-text search over this collection's `search.fields`-configured
+   * companion FTS5 table — see types.ts's `CollectionConfig.search` and
+   * codegen.ts's `collectionSearchTableSQL`. Gated by `read` access, same
+   * as `find`/`findByID`. Throws `CadmusCmsError` if the collection has no
+   * `search` config.
+   */
+  search(context: TContext, query: string, options?: {
+    limit?: number;
+  }): Promise<InferSelectModel<TTable>[]>;
+  create(context: TContext, input: InferInsertModel<TTable>): Promise<InferSelectModel<TTable>>;
+  update(context: TContext, id: number, input: Partial<InferInsertModel<TTable>>): Promise<InferSelectModel<TTable>>;
+  deleteByID(context: TContext, id: number): Promise<InferSelectModel<TTable>>;
+}
+/**
+ * Lets `createLocalApi` resolve `depth: 1` relationship fields without
+ * importing every other collection's Local API (which would be a circular
+ * dependency the moment two collections relate to each other). The
+ * registry is just the raw ingredients — a table and a config per
+ * collection slug — built once by the app (e.g. from `cadmeaConfig.collections`)
+ * and passed to every `createLocalApi` call that has relationship fields.
+ *
+ * `apis` is a second, optional registry on the same object, for a
+ * different problem: a *hook* (not `createLocalApi` itself) on one
+ * collection that needs to write to *another* collection's Local API —
+ * e.g. a CRM upsert hook on a lead-capture collection that creates/updates
+ * `contacts`/`activities` rows. `tables`/`configs` can't serve this, since
+ * a hook needs a real `LocalApi` (with its own access/hooks/search wiring
+ * already applied), not raw ingredients to rebuild one from.
+ *
+ * The chicken-and-egg problem this solves: building collection A's
+ * `LocalApi` might need to reference collection B's `LocalApi` (for a
+ * hook), but collection B's `LocalApi` doesn't exist yet at the point A's
+ * is constructed — and vice versa if B also has a hook referencing A.
+ * The fix is **late binding**: build one `CmsRegistry` object, pass the
+ * *same reference* into every `createLocalApi` call (so every collection's
+ * hooks close over the same mutable object), construct every `LocalApi`,
+ * then fill in `registry.apis` afterwards:
+ *
+ * ```ts
+ * const registry: CmsRegistry = { tables, configs, apis: {} };
+ * const contactsApi = createLocalApi(db, contactsTable, contactsCollection, registry);
+ * const inquiriesApi = createLocalApi(db, inquiriesTable, inquiriesCollection, registry);
+ * // populate *after* every createLocalApi call returns — any hook that
+ * // reads registry.apis lazily (inside its returned function body, not
+ * // at hook-factory-call time) sees the fully-populated map, since hooks
+ * // only ever run once real requests start landing.
+ * Object.assign(registry.apis!, { contacts: contactsApi, inquiries: inquiriesApi });
+ * ```
+ *
+ * See `getRegisteredApi` for the accessor a hook factory should use to
+ * read from this map, rather than indexing `registry.apis` directly.
+ */
+interface CmsRegistry {
+  tables: Record<string, AnyTable$1>;
+  configs: Record<string, CollectionConfig>;
+  apis?: Record<string, LocalApi<AnyTable$1, any>>;
+}
+/**
+ * Reads collection `slug`'s `LocalApi` out of `registry.apis` — the
+ * accessor hook factories should use (see `CmsRegistry`'s doc comment for
+ * the late-binding pattern this assumes) instead of indexing
+ * `registry.apis` directly, so every caller gets the same clear error if
+ * the registry wasn't built/populated correctly. `TContext` is a type-only
+ * parameter (the registry itself is stored with `never` to stay variance-
+ * safe across collections with different context shapes) — callers assert
+ * the context type they expect, the same way `resolveRelationships`'s own
+ * registry lookups do.
+ */
+declare function getRegisteredApi<TContext>(registry: CmsRegistry | undefined, slug: string): LocalApi<AnyTable$1, TContext>;
+/**
+ * Non-throwing counterpart to `checkAccess` below, for UI code that wants
+ * to hide/disable an action a context can't perform rather than let it
+ * fail server-side after a click (see Phase 6 / issue #26's
+ * `getPageCapabilities`). `checkAccess` calls through this same function
+ * rather than duplicating the "no access fn = allowed" logic, so `can()`'s
+ * answer and the real operation's enforcement can never disagree.
+ */
+declare function can<TContext>(config: CollectionConfig, operation: keyof CollectionAccess, context: TContext): Promise<boolean>;
+declare function createLocalApi<TTable extends AnyTable$1, TContext = unknown>(db: BaseSQLiteDatabase<"async", unknown>, table: TTable, config: CollectionConfig, registry?: CmsRegistry): LocalApi<TTable, TContext>;
+/**
+ * Extends {@link LocalApi} with draft/publish operations for a collection
+ * that opted in via `CollectionConfig.versions.drafts` (see codegen.ts's
+ * `collectionVersionsTable`). A separate interface (not a wider
+ * `LocalApi`) so non-versioned collections' types don't grow these methods
+ * — TypeScript can't conditionally widen `createLocalApi`'s return type
+ * off a runtime config value, so this is `createVersionedLocalApi`'s own
+ * factory rather than a branch inside `createLocalApi`.
+ *
+ * Scope, deliberately: a document is always created via the inherited
+ * `create()` first (existing behavior, unaffected by versioning) — these
+ * methods operate against an *existing* row. `saveDraft` never validates
+ * required fields (an incomplete draft is valid); `publish` runs the same
+ * full validation `create`/`update` do, since publishing is what makes a
+ * version the public-facing document. Plain `find`/`findByID` are
+ * unchanged by any of this — they always return the main table's current
+ * row regardless of `publishedVersionId`; filtering reads to
+ * published-only content is not this phase's concern.
+ */
+interface VersionedLocalApi<TTable extends AnyTable$1, TVersionsTable extends AnyTable$1, TContext = unknown> extends LocalApi<TTable, TContext> {
+  findVersions(context: TContext, parentId: number): Promise<InferSelectModel<TVersionsTable>[]>;
+  /** Inserts a new version row holding `input` as a draft snapshot. */
+  saveDraft(context: TContext, id: number, input: Partial<InferInsertModel<TTable>>): Promise<InferSelectModel<TVersionsTable>>;
+  /** Copies a version's snapshot onto the main row and marks it published. */
+  publish(context: TContext, versionId: number): Promise<InferSelectModel<TTable>>;
+  /** Clears the main row's published pointer; the row's data is untouched. */
+  unpublish(context: TContext, id: number): Promise<InferSelectModel<TTable>>;
+}
+declare function createVersionedLocalApi<TTable extends AnyTable$1, TVersionsTable extends AnyTable$1, TContext = unknown>(db: BaseSQLiteDatabase<"async", unknown>, table: TTable, versionsTable: TVersionsTable, config: CollectionConfig, registry?: CmsRegistry): VersionedLocalApi<TTable, TVersionsTable, TContext>;
+//#endregion
+//#region src/cms/validation.d.ts
+type AnyTable = SQLiteTableWithColumns<any>;
+/**
+ * Chainable field validation for Cadmea (issue #16) — adopts Sanity's
+ * `defineField`/`Rule` validation API (pattern, not code). A field declares
+ * `validation: (rule) => rule.required().min(2).custom(...)`; this module
+ * turns that chain into a list of declarative checks and evaluates them at
+ * write time (server-side, in createLocalApi) as well as anywhere the studio
+ * wants synchronous feedback.
+ *
+ * Design notes:
+ * - The builder is **immutable** — every method returns a new {@link Rule}
+ *   with one more check appended, so a shared base rule can't be mutated by
+ *   a consumer's chain (mirrors Sanity).
+ * - Most checks are synchronous and pure (min/max/regex/custom over the
+ *   value alone). Two — `unique` and `reference` — need the database and so
+ *   only run where {@link validateDocument} is given a `db` (i.e. the Local
+ *   API); they're skipped (not failed) in a pure client-side pass.
+ */
+type ValidationSeverity = "error" | "warning";
+/**
+ * What a {@link CustomValidator} may return:
+ * - `true` / `undefined` → valid
+ * - `false` → invalid, generic message
+ * - `string` → invalid, that message
+ * - `{ message, severity? }` → invalid, that message at the given severity
+ */
+type CustomValidatorResult = boolean | undefined | string | {
+  message: string;
+  severity?: ValidationSeverity;
+};
+interface ValidationFieldContext {
+  /** The whole document being validated (nested shape, post-hooks). */
+  document: Record<string, unknown>;
+  /** This field's flattened key (e.g. `slug`, `shippingAddress_city`). */
+  path: string;
+  /** Whether this is a create or an update. */
+  operation: "create" | "update";
+  /** The document's id on update — lets `unique` exclude the row itself. */
+  id?: number;
+}
+type CustomValidator = (value: unknown, context: ValidationFieldContext) => CustomValidatorResult | Promise<CustomValidatorResult>;
+type Check = ({
+  kind: "required";
+} | {
+  kind: "min";
+  n: number;
+} | {
+  kind: "max";
+  n: number;
+} | {
+  kind: "length";
+  n: number;
+} | {
+  kind: "regex";
+  re: RegExp;
+  label: string;
+} | {
+  kind: "integer";
+} | {
+  kind: "positive";
+} | {
+  kind: "unique";
+} | {
+  kind: "reference";
+} | {
+  kind: "custom";
+  fn: CustomValidator;
+}) & {
+  message?: string;
+  severity?: ValidationSeverity;
+};
+/**
+ * Immutable, chainable rule builder — the value a field's `validation`
+ * function receives and returns. Build a `Rule` with the module-level
+ * {@link rule} factory, or accept the one passed to your `validation`
+ * callback.
+ */
+declare class Rule {
+  private readonly checks;
+  constructor(checks?: readonly Check[]);
+  private add;
+  /** Override the message of the most recently added check. */
+  error(message: string): Rule;
+  /**
+   * Demote the most recently added check to a warning (non-blocking),
+   * optionally with a message. Sanity's `Rule.warning()` analogue.
+   */
+  warning(message?: string): Rule;
+  private withLast;
+  required(): Rule;
+  /** Minimum string length / array length / numeric value. */
+  min(n: number): Rule;
+  /** Maximum string length / array length / numeric value. */
+  max(n: number): Rule;
+  /** Exact string/array length. */
+  length(n: number): Rule;
+  regex(re: RegExp, label?: string): Rule;
+  email(): Rule;
+  /** Lowercase kebab-case slug format. Pair with `.unique()` for slugs. */
+  slug(): Rule;
+  integer(): Rule;
+  positive(): Rule;
+  /**
+   * Value must be unique across the collection (DB-backed; skipped in a
+   * pure client-side pass). A first-class rule rather than the hand-rolled
+   * column `unique` flag, so the failure is a clear field message instead of
+   * a raw UNIQUE-constraint write error.
+   */
+  unique(): Rule;
+  /**
+   * For a `relationship` field: the referenced id must exist in the related
+   * collection (DB-backed; skipped client-side).
+   */
+  reference(): Rule;
+  custom(fn: CustomValidator): Rule;
+  /** Internal: the accumulated checks, read by {@link validateDocument}. */
+  toChecks(): readonly Check[];
+}
+/** Fresh, empty rule — the root of a chain. */
+declare function rule(): Rule;
+/**
+ * A field's `validation` value: a function from a fresh Rule to the
+ * configured chain (Sanity's signature). Returning an array lets a field
+ * carry several independent rule chains.
+ */
+type ValidationBuilder = (r: Rule) => Rule | Rule[];
+/**
+ * Identity helper mirroring Sanity's `defineField` — returns the field
+ * config unchanged but gives editors autocomplete and a single, greppable
+ * call site for field definitions. Optional: a plain object literal is still
+ * a valid field.
+ */
+declare function defineField<T extends FieldConfig>(field: T): T;
+interface ValidateDocumentOptions {
+  operation: "create" | "update";
+  /** Document id (update only) — passed to `unique`/custom validators. */
+  id?: number;
+  /**
+   * Restrict validation to these flattened field keys. Used by update(),
+   * which only receives a partial document — validating absent fields would
+   * spuriously fail their rules. Omit to validate every field (create).
+   */
+  onlyFields?: ReadonlySet<string>;
+  /**
+   * Database handle for DB-backed rules (`unique`, `reference`). When
+   * omitted, those rules are skipped — so the same function powers a pure
+   * client-side validation pass.
+   */
+  db?: BaseSQLiteDatabase<"async", unknown>;
+  /** This collection's own table (for `unique`). */
+  table?: AnyTable;
+  /** Registry of tables by slug (for `reference` target lookups). */
+  registry?: CmsRegistry;
+}
+/**
+ * Evaluate every field's validation rules against `doc`, returning all
+ * violations (both errors and warnings). `doc` is the nested document; field
+ * values are read from its flattened form so group subfields validate too.
+ */
+declare function validateDocument(config: CollectionConfig, doc: Record<string, unknown>, options: ValidateDocumentOptions): Promise<ValidationViolation[]>;
+/**
+ * Run {@link validateDocument} and throw {@link CadmusValidationError} if any
+ * `"error"`-severity violations are found. Warnings are returned (never
+ * thrown) so a caller can still surface them. The thrown error's message is
+ * a readable, joined summary of every blocking violation.
+ */
+declare function assertValid(config: CollectionConfig, doc: Record<string, unknown>, options: ValidateDocumentOptions): Promise<ValidationViolation[]>;
+//#endregion
 //#region src/cms/types.d.ts
 interface BaseFieldConfig {
   /** column name override; defaults to the config key */
@@ -8,6 +501,16 @@ interface BaseFieldConfig {
   required?: boolean;
   unique?: boolean;
   defaultValue?: unknown;
+  /**
+   * Chainable validation rules (issue #16), Sanity's `defineField`
+   * `validation` analogue: `validation: (rule) => rule.required().min(2)`.
+   * Evaluated server-side by createLocalApi on every create/update (and by
+   * the studio for client-side feedback). Independent of the `required`/
+   * `unique` flags above — those still drive the DB schema; these drive
+   * value-level checks with clear, per-field error messages. See
+   * {@link ValidationBuilder} and `validation.ts`.
+   */
+  validation?: ValidationBuilder;
 }
 interface TextFieldConfig extends BaseFieldConfig {
   type: "text";
@@ -219,6 +722,57 @@ interface CollectionHooks<TDoc = Record<string, unknown>> {
     id: number;
   }) => void | Promise<void>>;
 }
+/**
+ * Studio-presentation hints for a collection, modeled on Sanity's Structure
+ * Builder (`sanity/structure`). Purely about how the admin sidebar/editor
+ * *presents* a collection — never affects the DB schema, the Local API, or
+ * access control. Consumed by {@link buildStudioStructure} (see
+ * `structure.ts`); a collection with no `admin` block falls back to sensible
+ * defaults (visible, editable, listed, grouped under the default group,
+ * label = capitalized slug). Plugin-injected collections can't carry an
+ * `admin` block in hand-written config, so `buildStudioStructure` also
+ * accepts per-slug overrides at the call site — see its `overrides` option.
+ */
+interface CollectionAdminConfig {
+  /**
+   * Sidebar group heading this collection appears under (e.g. "Content",
+   * "Store"). Collections without a group fall into the builder's default
+   * group. Decoupling nav grouping from the raw collection list is the whole
+   * point of the Structure Builder.
+   */
+  group?: string;
+  /**
+   * Sort order within a group — lower sorts first. Ties (and the absence of
+   * an explicit order) break by the collection's position in the config
+   * array, so config order is the stable default.
+   */
+  order?: number;
+  /**
+   * Drop this collection from the sidebar entirely. For pure system/log
+   * tables a human never browses (e.g. `webhook_events`).
+   */
+  hidden?: boolean;
+  /**
+   * Mark as read-only in the studio — still navigable/viewable, but the UI
+   * suppresses create/edit/delete affordances. For machine-written tables a
+   * human should inspect but never edit (e.g. `payments`).
+   */
+  readOnly?: boolean;
+  /**
+   * Singleton: exactly one document. The sidebar links straight to its
+   * editor (`/admin/<slug>`) instead of a list-then-create flow — Sanity's
+   * singleton-document structure pattern. (Storage is unchanged; this only
+   * changes navigation.)
+   */
+  singleton?: boolean;
+  /** Display label override; defaults to a capitalized slug. */
+  label?: string;
+  /**
+   * Optional icon identifier passed through to the sidebar renderer (e.g. a
+   * Phosphor icon name). The builder treats it as an opaque string.
+   */
+  icon?: string;
+}
 interface CollectionConfig {
   /** table name in D1; also the Local API's collection slug (later step) */
   slug: string;
@@ -263,6 +817,13 @@ interface CollectionConfig {
   search?: {
     fields: readonly string[];
   };
+  /**
+   * Studio-presentation hints — grouping, ordering, hidden/read-only,
+   * singleton, label, icon. Consumed only by {@link buildStudioStructure}
+   * (the Structure Builder); never affects schema, Local API, or access.
+   * See {@link CollectionAdminConfig}.
+   */
+  admin?: CollectionAdminConfig;
 }
 /**
  * A Cadmea plugin — a synchronous transform over the whole CMS config,
@@ -417,162 +978,97 @@ declare function cmsConfigToSchema(config: CmsConfig): Record<string, ReturnType
 declare function defineCollection(config: CollectionConfig): CollectionConfig;
 declare function defineCmsConfig(config: CmsConfig): CmsConfig;
 //#endregion
-//#region src/cms/localApi.d.ts
-type AnyTable = SQLiteTableWithColumns<any>;
+//#region src/cms/meta.d.ts
+interface CollectionMeta {
+  slug: string;
+  fields: CollectionConfig["fields"];
+  /** Whether `LocalApi.search()` is usable for this collection — see `CollectionConfig.search`. */
+  searchable: boolean;
+}
+declare function getCollectionsMeta(config: CmsConfig): CollectionMeta[];
+//#endregion
+//#region src/cms/schema-gen.d.ts
+declare function generateSchemaSource(config: CmsConfig): string;
+//#endregion
+//#region src/cms/structure.d.ts
 /**
- * `TContext` is the per-request value passed to every method and forwarded
- * unchanged to the collection's `access` functions (see {@link CollectionAccess}).
- * Cadmus doesn't standardize its shape — Cadmea types it as `{ session }`,
- * other consumers may type it differently. `context` is a required first
- * argument on every method (not optional) so a call site can't forget it.
+ * Cadmea's Structure Builder — the framework half of issue #12.
+ *
+ * Adopts Sanity's `sanity/structure` idea (pattern, not code): **decouple
+ * the admin nav from the raw collection list.** Instead of mapping every
+ * `config.collections` entry to an `/admin/<slug>` link — which surfaces
+ * system/log tables as editable links and produces dead links — the sidebar
+ * renders from an explicit, grouped structure derived here from each
+ * collection's `admin` hints (see {@link CollectionAdminConfig}) plus
+ * optional per-slug overrides supplied at the call site.
+ *
+ * Pure data in / pure data out: no SolidJS, no DOM, no server imports — so
+ * it's safe to import from a client studio component (e.g. the site's
+ * `PanelNav`) and trivially testable.
  */
-interface LocalApi<TTable extends AnyTable, TContext = unknown> {
+/** Default group heading for collections that don't declare `admin.group`. */
+declare const DEFAULT_STUDIO_GROUP = "Content";
+/** One navigable collection entry in the studio sidebar. */
+interface StudioStructureItem {
+  /** The collection's slug. */
+  slug: string;
+  /** Human label — `admin.label`, else the capitalized slug. */
+  label: string;
+  /** Where the sidebar link points (`/admin/<slug>`, configurable prefix). */
+  href: string;
+  /** Read-only collections are viewable but not editable in the studio. */
+  readOnly: boolean;
   /**
-   * `depth: 0` (default) returns relationship fields as bare ids; `depth: 1`
-   * batch-resolves `hasMany: false` relationship fields into the related
-   * row, gated by that collection's own `read` access fn — see
-   * `resolveRelationships` below. Requires `createLocalApi`'s `registry`
-   * param; throws CadmusCmsError if `depth: 1` is requested without one.
+   * Singletons link straight to their editor rather than a list+create
+   * flow. (The href is identical; the renderer uses this to skip the list.)
    */
-  find(context: TContext, options?: {
-    where?: SQL;
-    depth?: RelationshipDepth; /** Row cap, applied after `where` — for paginated list views. */
-    limit?: number; /** Rows to skip, applied after `where` — pairs with `limit`. */
-    offset?: number; /** One or more `asc(table.col)`/`desc(table.col)` expressions. */
-    orderBy?: SQL | SQL[];
-  }): Promise<InferSelectModel<TTable>[]>;
-  findByID(context: TContext, id: number, options?: {
-    depth?: RelationshipDepth;
-  }): Promise<InferSelectModel<TTable>>;
+  singleton: boolean;
+  /** Opaque icon identifier from `admin.icon`, if any. */
+  icon?: string;
+}
+/** A titled group of sidebar items, in render order. */
+interface StudioStructureGroup {
+  title: string;
+  items: StudioStructureItem[];
+}
+interface BuildStudioStructureOptions {
   /**
-   * Total row count for `where` (ignoring `limit`/`offset`) — pairs with
-   * `find` to compute page counts/next-page availability without fetching
-   * every row. Gated by the same `read` access check as `find`.
+   * Per-slug presentation overrides, merged over each collection's own
+   * `admin` block (override keys win). The escape hatch for plugin-injected
+   * collections (`products`, `payments`, `webhook_events`, …) that can't
+   * carry an `admin` block in hand-written config — the studio declares
+   * their presentation here, exactly like Sanity defines structure at the
+   * studio level rather than on the schema.
    */
-  count(context: TContext, options?: {
-    where?: SQL;
-  }): Promise<number>;
+  overrides?: Record<string, CollectionAdminConfig>;
   /**
-   * Full-text search over this collection's `search.fields`-configured
-   * companion FTS5 table — see types.ts's `CollectionConfig.search` and
-   * codegen.ts's `collectionSearchTableSQL`. Gated by `read` access, same
-   * as `find`/`findByID`. Throws `CadmusCmsError` if the collection has no
-   * `search` config.
+   * Explicit group ordering by title. Groups listed here render first, in
+   * this order; any remaining groups follow in first-appearance order. A
+   * group title absent from `config`'s collections simply doesn't appear.
    */
-  search(context: TContext, query: string, options?: {
-    limit?: number;
-  }): Promise<InferSelectModel<TTable>[]>;
-  create(context: TContext, input: InferInsertModel<TTable>): Promise<InferSelectModel<TTable>>;
-  update(context: TContext, id: number, input: Partial<InferInsertModel<TTable>>): Promise<InferSelectModel<TTable>>;
-  deleteByID(context: TContext, id: number): Promise<InferSelectModel<TTable>>;
+  groupOrder?: readonly string[];
+  /**
+   * Link prefix for each item's `href`. Defaults to `/admin`, producing
+   * `/admin/<slug>`. No trailing slash.
+   */
+  basePath?: string;
 }
 /**
- * Lets `createLocalApi` resolve `depth: 1` relationship fields without
- * importing every other collection's Local API (which would be a circular
- * dependency the moment two collections relate to each other). The
- * registry is just the raw ingredients — a table and a config per
- * collection slug — built once by the app (e.g. from `cadmeaConfig.collections`)
- * and passed to every `createLocalApi` call that has relationship fields.
- *
- * `apis` is a second, optional registry on the same object, for a
- * different problem: a *hook* (not `createLocalApi` itself) on one
- * collection that needs to write to *another* collection's Local API —
- * e.g. a CRM upsert hook on a lead-capture collection that creates/updates
- * `contacts`/`activities` rows. `tables`/`configs` can't serve this, since
- * a hook needs a real `LocalApi` (with its own access/hooks/search wiring
- * already applied), not raw ingredients to rebuild one from.
- *
- * The chicken-and-egg problem this solves: building collection A's
- * `LocalApi` might need to reference collection B's `LocalApi` (for a
- * hook), but collection B's `LocalApi` doesn't exist yet at the point A's
- * is constructed — and vice versa if B also has a hook referencing A.
- * The fix is **late binding**: build one `CmsRegistry` object, pass the
- * *same reference* into every `createLocalApi` call (so every collection's
- * hooks close over the same mutable object), construct every `LocalApi`,
- * then fill in `registry.apis` afterwards:
- *
- * ```ts
- * const registry: CmsRegistry = { tables, configs, apis: {} };
- * const contactsApi = createLocalApi(db, contactsTable, contactsCollection, registry);
- * const inquiriesApi = createLocalApi(db, inquiriesTable, inquiriesCollection, registry);
- * // populate *after* every createLocalApi call returns — any hook that
- * // reads registry.apis lazily (inside its returned function body, not
- * // at hook-factory-call time) sees the fully-populated map, since hooks
- * // only ever run once real requests start landing.
- * Object.assign(registry.apis!, { contacts: contactsApi, inquiries: inquiriesApi });
- * ```
+ * Build the studio sidebar structure from a resolved CMS config.
  *
- * See `getRegisteredApi` for the accessor a hook factory should use to
- * read from this map, rather than indexing `registry.apis` directly.
- */
-interface CmsRegistry {
-  tables: Record<string, AnyTable>;
-  configs: Record<string, CollectionConfig>;
-  apis?: Record<string, LocalApi<AnyTable, any>>;
-}
-/**
- * Reads collection `slug`'s `LocalApi` out of `registry.apis` — the
- * accessor hook factories should use (see `CmsRegistry`'s doc comment for
- * the late-binding pattern this assumes) instead of indexing
- * `registry.apis` directly, so every caller gets the same clear error if
- * the registry wasn't built/populated correctly. `TContext` is a type-only
- * parameter (the registry itself is stored with `never` to stay variance-
- * safe across collections with different context shapes) — callers assert
- * the context type they expect, the same way `resolveRelationships`'s own
- * registry lookups do.
- */
-declare function getRegisteredApi<TContext>(registry: CmsRegistry | undefined, slug: string): LocalApi<AnyTable, TContext>;
-/**
- * Non-throwing counterpart to `checkAccess` below, for UI code that wants
- * to hide/disable an action a context can't perform rather than let it
- * fail server-side after a click (see Phase 6 / issue #26's
- * `getPageCapabilities`). `checkAccess` calls through this same function
- * rather than duplicating the "no access fn = allowed" logic, so `can()`'s
- * answer and the real operation's enforcement can never disagree.
- */
-declare function can<TContext>(config: CollectionConfig, operation: keyof CollectionAccess, context: TContext): Promise<boolean>;
-declare function createLocalApi<TTable extends AnyTable, TContext = unknown>(db: BaseSQLiteDatabase<"async", unknown>, table: TTable, config: CollectionConfig, registry?: CmsRegistry): LocalApi<TTable, TContext>;
-/**
- * Extends {@link LocalApi} with draft/publish operations for a collection
- * that opted in via `CollectionConfig.versions.drafts` (see codegen.ts's
- * `collectionVersionsTable`). A separate interface (not a wider
- * `LocalApi`) so non-versioned collections' types don't grow these methods
- * — TypeScript can't conditionally widen `createLocalApi`'s return type
- * off a runtime config value, so this is `createVersionedLocalApi`'s own
- * factory rather than a branch inside `createLocalApi`.
+ * - Hidden collections (`admin.hidden`) are dropped entirely.
+ * - Each remaining collection is placed in its `admin.group` (or
+ *   {@link DEFAULT_STUDIO_GROUP}).
+ * - Within a group, items sort by `admin.order` (ascending; unset sorts
+ *   after set), then by their original position in `config.collections` —
+ *   so config order is the stable tiebreaker.
+ * - Groups render in `options.groupOrder` first, then first-appearance
+ *   order for the rest.
  *
- * Scope, deliberately: a document is always created via the inherited
- * `create()` first (existing behavior, unaffected by versioning) — these
- * methods operate against an *existing* row. `saveDraft` never validates
- * required fields (an incomplete draft is valid); `publish` runs the same
- * full validation `create`/`update` do, since publishing is what makes a
- * version the public-facing document. Plain `find`/`findByID` are
- * unchanged by any of this — they always return the main table's current
- * row regardless of `publishedVersionId`; filtering reads to
- * published-only content is not this phase's concern.
+ * The input is expected to be the *resolved* config (post-plugins), since
+ * that's what carries plugin-injected collections like `products`.
  */
-interface VersionedLocalApi<TTable extends AnyTable, TVersionsTable extends AnyTable, TContext = unknown> extends LocalApi<TTable, TContext> {
-  findVersions(context: TContext, parentId: number): Promise<InferSelectModel<TVersionsTable>[]>;
-  /** Inserts a new version row holding `input` as a draft snapshot. */
-  saveDraft(context: TContext, id: number, input: Partial<InferInsertModel<TTable>>): Promise<InferSelectModel<TVersionsTable>>;
-  /** Copies a version's snapshot onto the main row and marks it published. */
-  publish(context: TContext, versionId: number): Promise<InferSelectModel<TTable>>;
-  /** Clears the main row's published pointer; the row's data is untouched. */
-  unpublish(context: TContext, id: number): Promise<InferSelectModel<TTable>>;
-}
-declare function createVersionedLocalApi<TTable extends AnyTable, TVersionsTable extends AnyTable, TContext = unknown>(db: BaseSQLiteDatabase<"async", unknown>, table: TTable, versionsTable: TVersionsTable, config: CollectionConfig, registry?: CmsRegistry): VersionedLocalApi<TTable, TVersionsTable, TContext>;
-//#endregion
-//#region src/cms/meta.d.ts
-interface CollectionMeta {
-  slug: string;
-  fields: CollectionConfig["fields"];
-  /** Whether `LocalApi.search()` is usable for this collection — see `CollectionConfig.search`. */
-  searchable: boolean;
-}
-declare function getCollectionsMeta(config: CmsConfig): CollectionMeta[];
-//#endregion
-//#region src/cms/schema-gen.d.ts
-declare function generateSchemaSource(config: CmsConfig): string;
+declare function buildStudioStructure(config: CmsConfig, options?: BuildStudioStructureOptions): StudioStructureGroup[];
 //#endregion
 //#region src/cms/webhooks.d.ts
 interface WebhookConfig {
@@ -612,5 +1108,5 @@ declare function createWebhookHook(queue: Queue<WebhookMessage>, config: Webhook
  */
 declare function deliverWebhookMessage(message: WebhookMessage): Promise<void>;
 //#endregion
-export { CollectionAccess as A, RelationshipFieldConfig as B, relationshipJoinTables as C, CadmeaPlugin as D, BaseFieldConfig as E, GroupFieldConfig as F, flattenDoc as G, SelectFieldConfig as H, JsonFieldConfig as I, flattenFields as K, JsonValue as L, CollectionHooks as M, DateFieldConfig as N, CheckboxFieldConfig as O, FieldConfig as P, NumberFieldConfig as R, extractSearchText as S, ArrayFieldConfig as T, TextFieldConfig as U, RichTextFieldConfig as V, UploadFieldConfig as W, cmsConfigToSchema as _, generateSchemaSource as a, collectionToTable as b, CmsRegistry as c, can as d, createLocalApi as f, defineCollection as g, defineCmsConfig as h, deliverWebhookMessage as i, CollectionConfig as j, CmsConfig as k, LocalApi as l, getRegisteredApi as m, WebhookMessage as n, CollectionMeta as o, createVersionedLocalApi as p, nestDoc as q, createWebhookHook as r, getCollectionsMeta as s, WebhookConfig as t, VersionedLocalApi as u, collectionSearchTableName as v, AccessFn as w, collectionVersionsTable as x, collectionSearchTableSQL as y, RelationshipDepth as z };
-//# sourceMappingURL=index-BUrCSGVb.d.cts.map
+export { ValidationSeverity as $, CollectionConfig as A, RichTextFieldConfig as B, ArrayFieldConfig as C, CadmusValidationError as Ct, CmsConfig as D, StringBlockRenderer as Dt, CheckboxFieldConfig as E, PortableBlockLike as Et, JsonFieldConfig as F, flattenFields as G, TextFieldConfig as H, JsonValue as I, CustomValidatorResult as J, nestDoc as K, NumberFieldConfig as L, DateFieldConfig as M, FieldConfig as N, CollectionAccess as O, createBlockRegistry as Ot, GroupFieldConfig as P, ValidationFieldContext as Q, RelationshipDepth as R, AccessFn as S, CadmusStorageError as St, CadmeaPlugin as T, BlockRegistry as Tt, UploadFieldConfig as U, SelectFieldConfig as V, flattenDoc as W, ValidateDocumentOptions as X, Rule as Y, ValidationBuilder as Z, collectionSearchTableSQL as _, CadmusEmailError as _t, BuildStudioStructureOptions as a, LocalApi as at, extractSearchText as b, CadmusRateLimitError as bt, StudioStructureItem as c, createLocalApi as ct, CollectionMeta as d, CadmusAccessDeniedError as dt, assertValid as et, getCollectionsMeta as f, CadmusApiError as ft, collectionSearchTableName as g, CadmusDbError as gt, cmsConfigToSchema as h, CadmusCmsError as ht, deliverWebhookMessage as i, CmsRegistry as it, CollectionHooks as j, CollectionAdminConfig as k, renderBlocksToString as kt, buildStudioStructure as l, createVersionedLocalApi as lt, defineCollection as m, CadmusCacheError as mt, WebhookMessage as n, rule as nt, DEFAULT_STUDIO_GROUP as o, VersionedLocalApi as ot, defineCmsConfig as p, CadmusAuthError as pt, CustomValidator as q, createWebhookHook as r, validateDocument as rt, StudioStructureGroup as s, can as st, WebhookConfig as t, defineField as tt, generateSchemaSource as u, getRegisteredApi as ut, collectionToTable as v, CadmusError as vt, BaseFieldConfig as w, ValidationViolation as wt, relationshipJoinTables as x, CadmusSessionError as xt, collectionVersionsTable as y, CadmusQueueError as yt, RelationshipFieldConfig as z };
+//# sourceMappingURL=index-BRZrCTsN.d.ts.map