@vespercms/admin 0.0.0-stage → 0.1.0-next.1

package/dist/body/commands.d.ts

@@ -0,0 +1,31 @@
+import type { Editor, JSONContent } from '@tiptap/core';
+import { type EditorState } from '@tiptap/pm/state';
+import type { BlockKind, BlockShape } from './catalog.ts';
+import type { ContainerTypes } from './nodes.ts';
+/** Node types that are blocks the studio manages: tags, components and protected blocks. */
+export declare function isManaged(type: string, containers: ContainerTypes): boolean;
+/** The managed node the selection is on (a node selection), or null. */
+export declare function selectedNode(editor: Editor, containers: ContainerTypes): {
+    pos: number;
+    type: string;
+} | null;
+/** The innermost container the cursor is inside, or null. */
+export declare function enclosingContainer(editor: Editor, containers: ContainerTypes): number | null;
+/** Selects the block at `pos` as a whole, so its frame shows focus and Enter opens its settings. */
+export declare function selectBlock(editor: Editor, pos: number): void;
+/** Moves the block at `pos` past its previous or next sibling. Returns its new position, or null. */
+export declare function moveBlock(editor: Editor, pos: number, direction: -1 | 1): number | null;
+/** Removes the block or chip at `pos`, leaving the cursor where it was. */
+export declare function removeBlock(editor: Editor, pos: number): void;
+/** The editor node a new block of `kind` starts as. */
+export declare function newNode(kind: BlockKind, shape: BlockShape, containers: ContainerTypes, attributes?: Readonly<Record<string, unknown>>, inner?: string): JSONContent;
+/** Where a kind can go at the cursor: as a block, inline, or not at all. Reads only the state. */
+export declare function placementAt(state: EditorState, kind: BlockKind, containers: ContainerTypes): BlockShape | null;
+/**
+ * Inserts a new block or chip of `kind` at the cursor (replacing `range`,
+ * the "/" text, when given) and returns its position.
+ */
+export declare function insertBlock(editor: Editor, kind: BlockKind, shape: BlockShape, containers: ContainerTypes, range?: {
+    from: number;
+    to: number;
+}, attributes?: Readonly<Record<string, unknown>>): number | null;

package/dist/body/document.d.ts

@@ -0,0 +1,42 @@
+import type { JSONContent } from '@tiptap/core';
+import type { MarkdownManager } from '@tiptap/markdown';
+import { type BodyFormat, type BodyItem, type MarkdocParseOptions, type ParsedBody, type TableEdit, type TableValue } from '@vespercms/core';
+import type { Catalog } from './catalog.ts';
+import { type ContainerTypes } from './nodes.ts';
+export type BodyContext = {
+    format: BodyFormat;
+    markdown: MarkdownManager;
+    catalog: Catalog;
+    containers: ContainerTypes;
+    markdoc?: MarkdocParseOptions;
+};
+export type BodyDocument = {
+    /** The text the document was built from, and its blocks. */
+    parsed: ParsedBody;
+    doc: JSONContent;
+};
+/** Builds the editor document for a body. */
+export declare function buildDocument(body: string, context: BodyContext): BodyDocument;
+/** Text with `indent` taken off every line after the first; null when a line isn't indented so. */
+export declare function dedent(text: string, indent: string): string | null;
+/** How every node with a path first looked: its JSON, or for a container its opening. */
+export declare function snapshot(doc: JSONContent, containers: ContainerTypes): Map<string, string>;
+type ItemsContext = Pick<BodyContext, 'markdown' | 'containers'> & {
+    parsed?: ParsedBody;
+    /** How the body parses, for checking a changed table reads back. */
+    format?: BodyFormat;
+    markdoc?: MarkdocParseOptions;
+};
+/** The edited body as items: unchanged blocks keep their bytes, changed ones are written. */
+export declare function bodyItems(doc: JSONContent, initial: ReadonlyMap<string, string>, context: ItemsContext): BodyItem[];
+/**
+ * A table's text as it will be saved: spliced into the table it was loaded
+ * from (`path`), or written new. Refused when it wouldn't read back as this
+ * table.
+ */
+export declare function tableEdit(path: string | null, value: TableValue, context: ItemsContext): TableEdit;
+/** A node's text as it will be saved. */
+export declare function nodeText(node: JSONContent, markdown: MarkdownManager): string;
+/** A plain-language name for a protected block, from its parser type. */
+export declare function sourceLabel(blockType: string): string;
+export {};

package/dist/body/insert.d.ts

@@ -0,0 +1,69 @@
+import { Extension, type Editor } from '@tiptap/core';
+import { PluginKey, type EditorState } from '@tiptap/pm/state';
+import { type BlockKind, type BlockShape, type Catalog } from './catalog.ts';
+import type { ContainerTypes } from './nodes.ts';
+export type InsertChoice = {
+    kind: BlockKind;
+    shape: BlockShape;
+};
+type SlashState = {
+    active: false;
+} | {
+    active: true;
+    from: number;
+    index: number;
+};
+export declare const slashKey: PluginKey<SlashState>;
+/** What can be inserted at the cursor right now, by friendly name. */
+export declare function choicesAt(state: EditorState, catalog: Catalog, containers: ContainerTypes): InsertChoice[];
+export declare function slashQuery(state: EditorState): string | null;
+export declare function filterChoices(choices: readonly InsertChoice[], query: string): InsertChoice[];
+export type SlashOptions = {
+    listboxId: string;
+    optionId: (index: number) => string;
+    /** The options for the current query (computed by the caller, which knows the catalog). */
+    choices: (state: EditorState) => InsertChoice[];
+    choose: (choice: InsertChoice, range: {
+        from: number;
+        to: number;
+    }) => void;
+    disabled: () => boolean;
+};
+/**
+ * The "/" plugin: opens on "/" typed at a line's start or after a space in a
+ * paragraph, closes on Escape, a space, or the cursor leaving the query, and
+ * sets the editor's role and ARIA state while it's open.
+ */
+export declare function SlashCommands(options: SlashOptions): Extension<any, any>;
+/**
+ * The text's role and ARIA state: a multi-line textbox, or a combobox while
+ * the "/" list is open. Given to the editor through `editorProps.attributes`,
+ * which is the only place that can replace Tiptap's own `role="textbox"`.
+ */
+export declare function slashAttributes(state: EditorState, options: Pick<SlashOptions, 'listboxId' | 'optionId'> & {
+    count: (query: string) => number;
+}): Record<string, string>;
+/** The "/" list, shown under the cursor while the plugin is open. */
+export declare function SlashList({ editor, listboxId, optionId, choices, onChoose, }: {
+    editor: Editor;
+    listboxId: string;
+    optionId: (index: number) => string;
+    choices: (state: EditorState) => InsertChoice[];
+    onChoose: (choice: InsertChoice, range: {
+        from: number;
+        to: number;
+    }) => void;
+}): import("react").JSX.Element | null;
+/** The toolbar's Insert menu: the same list, for people who don't use "/". */
+export declare function InsertMenu({ editor, choices, onChoose, disabled, }: {
+    editor: Editor;
+    choices: (state: EditorState) => InsertChoice[];
+    onChoose: (choice: InsertChoice) => void;
+    disabled: boolean;
+}): import("react").JSX.Element | null;
+/** Stable ids for the "/" listbox and its options. */
+export declare function useSlashIds(): {
+    listboxId: string;
+    optionId: (index: number) => string;
+};
+export {};

package/dist/body/nodes.d.ts

@@ -0,0 +1,38 @@
+import { Extension, Node, type AnyExtension } from '@tiptap/core';
+import type { BlockKind, Catalog } from './catalog.ts';
+/** Editor node types a Markdown block may become. Anything else stays source. */
+export declare const WRITABLE_NODES: Set<string>;
+/** Remembers which original block a Markdown node came from. */
+export declare const BlockIndex: Extension<any, any>;
+/** A block the writing view can't show: kept exactly, editable as raw text. */
+export declare const SourceBlock: Node<any, any>;
+/** A tag or component without editable content (spec §6.5.1: "a compact card"). Its whole text is `source`. */
+export declare const VesperCard: Node<any, any>;
+/**
+ * A pipe table the writing view edits cell by cell (DECISIONS.md, "Tables
+ * are edited as a grid, and a save splices cells"). One atom, whose view is
+ * a grid that owns its own focus; `value` is the table as `table.ts` holds it.
+ */
+export declare const VesperTable: Node<any, any>;
+/**
+ * An inline chip: an inline tag, a variable, an annotation, inline JSX or an
+ * expression. Its text is `source`. To the Markdown parser and serializer it
+ * is one placeholder (see chips.ts).
+ */
+export declare const VesperInline: Node<any, any>;
+export type ContainerTypes = {
+    /** Editor node types for containers, one per kind that has content. */
+    extensions: AnyExtension[];
+    /** The editor node type for a kind's container. */
+    typeOf: (kind: BlockKind) => string | undefined;
+    /** The kind behind a container node type. */
+    kindOf: (type: string) => BlockKind | undefined;
+    /** Whether a node of `type` may sit directly inside a container of `kind`. */
+    allows: (kind: BlockKind, type: string) => boolean;
+};
+/**
+ * One container node type per tag or component with content. Its content
+ * expression comes from Markdoc's `children`, so only allowed node types
+ * fit inside (spec §6.5.1), and protected blocks always do.
+ */
+export declare function containerTypes(catalog: Catalog): ContainerTypes;

package/dist/body/reveal.d.ts

@@ -0,0 +1,13 @@
+import type { Editor } from '@tiptap/core';
+import { type BodyBlock, type BodyFormat, type MarkdocParseOptions } from '@vespercms/core';
+import type { ContainerTypes } from './nodes.ts';
+/** The index of the block holding `offset` at each level, going into containers' children. */
+export declare function blockPathAt(blocks: readonly BodyBlock[], offset: number): number[];
+/** Selects the block at `offset` of `text` in the writing view, focuses it and scrolls to it. */
+export declare function revealInEditor(editor: Editor, text: string, offset: number, options: {
+    format: BodyFormat;
+    markdoc?: MarkdocParseOptions;
+    containers: ContainerTypes;
+}): void;
+/** Selects a range of the source view's text, focuses it and scrolls to it. */
+export declare function revealInSource(textarea: HTMLTextAreaElement, start: number, end: number): void;

package/dist/body/scroll.d.ts

@@ -0,0 +1,16 @@
+import type { EditorView } from '@tiptap/pm/view';
+/**
+ * A formatting toolbar inside its editor's frame, stuck below whatever
+ * already floats at the top of the scroller (`--sticky-top`, set by the
+ * screen or the pane), and only while its editor is on screen. Outside them,
+ * in a dialog, it sticks to the dialog's top.
+ */
+export declare const stuckToolbar = "sticky top-[var(--sticky-top,0px)] z-1 rounded-t-md border-b border-border bg-surface-raised p-1";
+/**
+ * ProseMirror keeps the caret inside its scroller's box, but a stuck
+ * formatting toolbar (and the glass above it) covers that box's top, so the
+ * caret could move up beneath them out of sight. Before ProseMirror scrolls,
+ * this scrolls a caret that's under the toolbar clear of it; ProseMirror's
+ * own scrolling then does the rest. Always false, so it never replaces it.
+ */
+export declare function scrollClearOfToolbar(view: EditorView, toolbar: HTMLElement | null): boolean;

package/dist/body/settings.d.ts

@@ -0,0 +1,19 @@
+import type { Editor } from '@tiptap/core';
+export declare function BlockSettings({ editor, pos, onClose, }: {
+    editor: Editor;
+    pos: number | null;
+    onClose: () => void;
+}): import("react").JSX.Element;
+/** Partial-like files, as paths relative to the entry (how the tag stores them), labelled by site path. */
+export declare function partialOptions(files: readonly string[], entryPath: string, current: string): {
+    value: string;
+    label: string;
+}[];
+/**
+ * Markdoc files named like partials (`_name.mdoc`, or in a `partials`
+ * folder), nearest the entry first: its own folder, then the folders above
+ * it, then everything else.
+ */
+export declare function partialFiles(files: readonly string[], entryPath: string): string[];
+/** `to` relative to the folder holding `from`, both site-relative: `_x.mdoc`, `../_x.mdoc`. */
+export declare function relativePath(from: string, to: string): string;

package/dist/body/shortcuts.d.ts

@@ -0,0 +1,13 @@
+/**
+ * A keyboard shortcut as people read it ("Ctrl+B", "⌘B") and as
+ * `aria-keyshortcuts` writes it ("Control+B", "Meta+B"). `Mod` is Command on
+ * a Mac and Control elsewhere, as in Tiptap's own keymaps.
+ */
+export type Shortcut = {
+    text: string;
+    aria: string;
+};
+export declare const isMac: boolean;
+type Modifier = 'Mod' | 'Alt' | 'Shift';
+export declare function shortcut(...keys: [...Modifier[], string]): Shortcut;
+export {};

package/dist/body/table.d.ts

@@ -0,0 +1,31 @@
+import type { JSONContent } from '@tiptap/core';
+import type { MarkdownManager } from '@tiptap/markdown';
+import { type BodyTable, type TableAlign, type TableValue } from '@vespercms/core';
+/** A cell's inline nodes, from its text as written (pipes escaped, chips as placeholders). */
+export declare function parseCell(markdown: MarkdownManager, text: string): JSONContent[] | null;
+/** Inline nodes as a cell's text: one line, every pipe escaped. */
+export declare function cellText(markdown: MarkdownManager, inline: readonly JSONContent[]): string;
+/**
+ * The cell's inline nodes when the writing view can own it: one line of
+ * inline Markdown that reads back the same once written. Null otherwise.
+ */
+export declare function cellFits(markdown: MarkdownManager, text: string): JSONContent[] | null;
+/** The table as loaded, each cell with its chips as placeholders. */
+export declare function editorValue(text: string, table: BodyTable): TableValue;
+/** The table with every chip's text back in place, for core's writer. */
+export declare function savedValue(value: TableValue): TableValue;
+/** A new table: a header row and one row, two columns, all empty. */
+export declare function newTableValue(): TableValue;
+export declare function setCell(value: TableValue, row: number, column: number, text: string): TableValue;
+/** A new empty row at `at` (1 or more: the header stays first). */
+export declare function insertRow(value: TableValue, at: number): TableValue;
+/** A new empty column at `at`. */
+export declare function insertColumn(value: TableValue, at: number): TableValue;
+/** Moves a row below the header to `to` (also below the header). */
+export declare function moveRow(value: TableValue, from: number, to: number): TableValue;
+export declare function moveColumn(value: TableValue, from: number, to: number): TableValue;
+/** Deletes a row below the header. */
+export declare function deleteRow(value: TableValue, row: number): TableValue;
+/** Deletes a column, unless it's the only one. */
+export declare function deleteColumn(value: TableValue, column: number): TableValue;
+export declare function alignColumn(value: TableValue, column: number, align: TableAlign): TableValue;

package/dist/body/ui.d.ts

@@ -0,0 +1,30 @@
+import type { BodyIssue, TableEdit, TableValue } from '@vespercms/core';
+import type { BlockKind, Catalog } from './catalog.ts';
+import type { BodyChecks } from './checks.ts';
+import type { ContainerTypes } from './nodes.ts';
+export type BodyActions = {
+    openSettings: (pos: number) => void;
+    move: (pos: number, direction: -1 | 1) => void;
+    remove: (pos: number) => void;
+};
+export type BodyUi = BodyActions & {
+    catalog: Catalog;
+    containers: ContainerTypes;
+    disabled: boolean;
+    checks: BodyChecks;
+    /** Site-relative paths of the files a partial can point at, once loaded. */
+    partials: readonly string[] | null;
+    entryPath: string;
+    /** Says something in the body's polite status ("Row added below row 3."). */
+    announce: (message: string) => void;
+    /** Whether a table's change would save, through core's writer, against the table it was loaded from. */
+    checkTable: (path: string | null, value: TableValue) => TableEdit;
+    /** True once, for the table just inserted, so it starts with its first cell being edited. */
+    takeNewTable: () => boolean;
+};
+export declare const BodyUiContext: import("react").Context<BodyUi | null>;
+export declare function useBodyUi(): BodyUi;
+/** One block's issues, from its own text: synchronous for Markdoc, after a tick for MDX. */
+export declare function useBlockIssues(text: string): BodyIssue[];
+/** The header's summary: the summary attribute's value, shown with its option label. */
+export declare function summaryOf(kind: BlockKind | undefined, values: Readonly<Record<string, unknown>>): string;

package/dist/body/views.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNodeViewProps } from '@tiptap/react';
+/** A tag with editable content: the header, then the content, inside a hairline frame. */
+export declare function ContainerView({ node, getPos, selected, editor }: ReactNodeViewProps): import("react").JSX.Element;
+/** A tag or component without editable content. */
+export declare function CardView({ node, getPos, selected }: ReactNodeViewProps): import("react").JSX.Element;
+/** An inline chip. Tags and components show their friendly name and text; the rest show their source. */
+export declare function InlineView({ node, selected }: ReactNodeViewProps): import("react").JSX.Element;
+/** A protected block: named, shown as source, editable as raw text. */
+export declare function SourceView({ node, getPos, selected }: ReactNodeViewProps): import("react").JSX.Element;

package/dist/checks-C-0xDu-I.js

@@ -0,0 +1,57 @@
+import { issuesFromZod as e, markdocConfigFromManifest as t, partialChecker as n, validateMarkdocBody as r, validateMdxBody as i } from "@vespercms/core";
+//#region \0rolldown/runtime.js
+var a = Object.defineProperty, o = /* @__PURE__ */ ((e, t) => {
+	let n = {};
+	for (var r in e) a(n, r, {
+		get: e[r],
+		enumerable: !0
+	});
+	return t || a(n, Symbol.toStringTag, { value: "Module" }), n;
+})({ bodyChecks: () => s });
+function s(a) {
+	let { manifest: o, format: s, partials: c, entryPath: l } = a;
+	if (s === "mdoc") {
+		let e = t(o.markdoc), i = (t) => r(t, {
+			config: e,
+			...o.markdoc ? {
+				parse: o.markdoc.options,
+				tags: o.markdoc.tags
+			} : {},
+			...c ? { partialExists: n(l, c) } : {}
+		});
+		return {
+			validate: (e) => Promise.resolve(i(e)),
+			validateSync: i
+		};
+	}
+	if (s === "mdx" && (o.mdx?.components.length ?? 0) > 0) {
+		let t = null, n = () => (t ??= a.loadMdxProps().then((t) => {
+			let n = /* @__PURE__ */ new Map();
+			for (let r of o.mdx?.components ?? []) {
+				let i = t[r.name], a = i?.safeParseAsync?.bind(i);
+				a && n.set(r.name, {
+					label: r.label,
+					fields: r.fields,
+					validate: async (t) => {
+						let n = await a(t, { reportInput: !0 });
+						return n.success ? [] : e(n.error?.issues ?? []);
+					}
+				});
+			}
+			return n;
+		}), t);
+		return {
+			validate: async (e) => {
+				let t = await n();
+				return t.size > 0 ? i(e, t) : [];
+			},
+			validateSync: () => null
+		};
+	}
+	return {
+		validate: () => Promise.resolve([]),
+		validateSync: () => []
+	};
+}
+//#endregion
+export { o as n, s as t };

package/dist/cloud/CloudGate.d.ts

@@ -0,0 +1,14 @@
+import { type GitHubStudioSettings } from '../github/session.ts';
+import type { StudioOptions } from '../types.ts';
+import { type CloudSettings, type StoredSession } from './session.ts';
+import type { KeyValueStore } from '../app/idb.ts';
+type GateOptions = Omit<StudioOptions, 'api' | 'github' | 'account' | 'cloud' | 'connection'>;
+export declare function CloudGate({ settings, github, options, fetcher, store, }: {
+    settings: CloudSettings;
+    github?: GitHubStudioSettings | null;
+    options: GateOptions;
+    fetcher?: typeof fetch;
+    /** Where the key and tokens are kept: IndexedDB unless a test passes its own. */
+    store?: KeyValueStore<StoredSession>;
+}): import("react").JSX.Element;
+export {};

package/dist/cloud/access.d.ts

@@ -0,0 +1,14 @@
+import { type CollectionManifest } from '@vespercms/core';
+import type { CloudConnection } from './connection.ts';
+/** True when a collection belongs on this member's menus and home screen. */
+export declare function shownTo(cloud: CloudConnection | undefined, collection: string): boolean;
+/** True when an entry file belongs in this member's lists. */
+export declare function entryShownTo(cloud: CloudConnection | undefined, path: string): boolean;
+/** True when the member may start a new entry at the top of a collection (or in `parent`, in a tree). */
+export declare function mayCreateIn(cloud: CloudConnection | undefined, collection: CollectionManifest, parent?: string): boolean;
+/**
+ * True when the member may change a page at this place in a tree (spec
+ * §6.15.2, §7.5). A tree path is a grant key: `admissions` is the
+ * Admissions section page, `admissions/apply` a page under it.
+ */
+export declare function treeCovered(cloud: CloudConnection | undefined, collection: string, path: string): boolean;

package/dist/cloud/changes.d.ts

@@ -0,0 +1,26 @@
+import { type ReactNode } from 'react';
+type ChangesState = {
+    open: boolean;
+    setOpen: (open: boolean) => void;
+};
+/**
+ * `linked` is the `#/changes` address, where review emails send an approver:
+ * it opens the drawer, and closing the drawer goes back to `#/`, so a reload
+ * or Back doesn't open it again.
+ */
+export declare function ChangesProvider({ children, linked }: {
+    children: ReactNode;
+    linked: boolean;
+}): import("react").JSX.Element;
+/** Opens and closes the drawer; null when the studio isn't connected. */
+export declare function useChanges(): ChangesState | null;
+/** The top bar's button: "3 changes", and how many wait for this member's review. */
+export declare function ChangesButton(): import("react").JSX.Element | null;
+/** How many drafts wait to be published: none when the studio isn't connected. */
+export declare function useDraftsWaiting(): number;
+/**
+ * The line about drafts waiting to be published, which opens Changes: on
+ * Home, or among panes beside the collections.
+ */
+export declare function DraftsWaiting(): import("react").JSX.Element | null;
+export {};

package/dist/cloud/connection.d.ts

@@ -0,0 +1,100 @@
+import { type CloudClient, type CloudUser, type CommitTrailers, type DeployStatus, type Draft, type HoldResponse, type Manifest, type Member, type PublishResponse, type Review, type ScheduleResponse } from '@vespercms/core';
+import { type StudioApi } from '../app/api.ts';
+import { createBrowserApi } from '../app/browser-api.ts';
+import type { CloudSettings } from './session.ts';
+import { CloudStorage } from './storage.ts';
+export type CloudConnection = {
+    user: CloudUser;
+    member: Member;
+    siteName: string;
+    dashboardUrl: string;
+    client: CloudClient;
+    storage: CloudStorage;
+    drafts: DraftsStore;
+    /** What the member may do to a file. */
+    access: (path: string) => {
+        edit: boolean;
+        publish: boolean;
+    };
+    /** What the member may do with a whole draft: the API refuses the same (spec §7.5). */
+    draftAccess: (draft: Draft) => {
+        edit: boolean;
+        publish: boolean;
+    };
+    /** True when the member's grants cover the whole site (the redirects, settings outside collections). */
+    wholeSite: boolean;
+    /** True when the member may change anything at all. */
+    editsAnything: boolean;
+};
+export type DraftsSnapshot = {
+    drafts: readonly Draft[];
+    reviews: readonly Review[];
+    version: string;
+    /**
+     * How the site publishes on schedule, and where each change stands (spec
+     * §6.17). Absent on a site with no scheduled collection, or until read.
+     */
+    schedule?: ScheduleResponse;
+};
+/** Drafts and reviews as screens see them, kept current after every change. */
+export declare class DraftsStore {
+    private snapshot;
+    private readonly listeners;
+    private readonly client;
+    private readonly storage;
+    private readonly scheduled;
+    /** `scheduled`: the site has a scheduled collection, so the schedule is read with the drafts. */
+    constructor(client: CloudClient, storage: CloudStorage, scheduled?: boolean);
+    subscribe: (listener: () => void) => (() => void);
+    get: () => DraftsSnapshot;
+    /** Called by the storage whenever the drafts change. */
+    setDrafts(drafts: readonly Draft[], version: string): void;
+    private emit;
+    /** Asks the cloud for the drafts and reviews again, and the schedule where the site has one. */
+    refresh(): Promise<void>;
+    /** The draft holding a file, if one does. */
+    draftOf(path: string): Draft | undefined;
+    publish(ids: readonly string[]): Promise<PublishResponse>;
+    discard(id: string): Promise<void>;
+    keepMine(id: string, paths: readonly string[]): Promise<void>;
+    requestReview(ids: readonly string[], note: string): Promise<Review>;
+    answer(id: string, action: 'comment' | 'request-changes', body: string): Promise<Review>;
+    status(commit: string): Promise<DeployStatus>;
+    /** Holds drafts in the cloud until `at`, to be published then (`holdScheduledDrafts`). */
+    hold(ids: readonly string[], at: Date): Promise<HoldResponse>;
+    /** A held draft stops waiting, and stays a draft. */
+    release(event: string): Promise<void>;
+    /**
+     * Cancels a published entry's time to go live (call 9): one publish takes
+     * its file out of the site, and its content comes back as a draft. The
+     * file isn't live yet, so visitors see no change.
+     */
+    backToDraft(path: string, message: {
+        summary: string;
+        trailers?: CommitTrailers;
+    }): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        message: string;
+    }>;
+}
+/** The cloud's errors in the studio's terms: plain words, and a status the screens understand. */
+export declare function cloudApiError(error: unknown, onExpired?: () => void): unknown;
+export type ConnectOptions = {
+    settings: CloudSettings;
+    client: CloudClient;
+    user: CloudUser;
+    member: Member;
+    siteName: string;
+    manifest: Manifest;
+    loadMdxProps: () => Promise<Readonly<Record<string, unknown>>>;
+    loadUrlFunctions?: Parameters<typeof createBrowserApi>[0]['loadUrlFunctions'];
+    routes?: readonly (readonly [string, string])[];
+    onExpired?: () => void;
+};
+/** The studio's back end over the cloud, and the connection screens use. */
+export declare function connect(options: ConnectOptions): {
+    api: StudioApi;
+    connection: CloudConnection;
+};

package/dist/cloud/editor.d.ts

@@ -0,0 +1,44 @@
+import { type DeployStatus, type Draft, type Review } from '@vespercms/core';
+import type { DraftsSnapshot } from './connection.ts';
+/** The drafts and reviews, current after every change. Empty when not connected. */
+export declare function useDrafts(): DraftsSnapshot;
+/** The draft holding a file, and the review that draft waits in. */
+export declare function useEntryDraft(path: string): {
+    draft: Draft | undefined;
+    review: Review | undefined;
+};
+/** What the host reported for a published commit, asked again until the build is done. */
+export declare function useDeployStatus(commit: string | null): DeployStatus | null;
+/** The plain sentence after a publish (spec §6.16): building, live, failed, or nothing reported. */
+export declare function DeployLine({ commit }: {
+    commit: string;
+}): import("react").JSX.Element;
+/**
+ * A change published since the draft began (spec §7.4): the published file
+ * and the draft side by side, and the editor's choice. Nothing is
+ * overwritten silently.
+ */
+export declare function ConflictCompare({ path, draft, publishedVersion, onKeep, onDiscard, }: {
+    path: string;
+    draft: Draft;
+    publishedVersion: string | null;
+    onKeep: () => void;
+    onDiscard: () => void;
+}): import("react").JSX.Element;
+/** Asks for review, with an optional note for the approvers. */
+export declare function RequestReviewDialog({ isOpen, onOpenChange, onSend, }: {
+    isOpen: boolean;
+    onOpenChange: (open: boolean) => void;
+    onSend: (note: string) => Promise<void>;
+}): import("react").JSX.Element;
+/**
+ * Unsaved changes kept on this device while the cloud can't be reached
+ * (spec §6.9): written as they're typed, cleared once a draft is saved.
+ */
+export type KeptChanges = {
+    values: unknown;
+    body: string;
+    raw: string;
+};
+export declare function keptChanges(): import("../app/idb.ts").KeyValueStore<KeptChanges>;
+export declare function keptKey(project: string, collection: string, id: string | null): string;

package/dist/cloud/session.d.ts

@@ -0,0 +1,62 @@
+import { CloudClient, type CloudStudioSettings, type CloudTokens, type CloudUser, type Member } from '@vespercms/core';
+import { type KeyValueStore } from '../app/idb.ts';
+/** The cloud's settings, as the build writes them into the studio. */
+export type CloudSettings = CloudStudioSettings & {
+    /** The site's schemas built for the browser. */
+    schemas: string;
+};
+export type StoredSession = {
+    key: CryptoKeyPair;
+    tokens: CloudTokens | null;
+    user?: CloudUser;
+    member?: Member;
+    siteName?: string;
+};
+export declare function sessionStore(): KeyValueStore<StoredSession>;
+/** The stored key, made and kept on first use: a sign-in must exchange its code with the key it started with. */
+export declare function sessionKey(project: string, store?: KeyValueStore<StoredSession>): Promise<StoredSession>;
+/** The studio's own address, which the app sends the browser back to. */
+export declare function studioAddress(): string;
+/** Goes to the app's sign-in. `route` is the studio's hash route to come back to. */
+export declare function startCloudSignIn(settings: CloudSettings, route: string, store?: KeyValueStore<StoredSession>): Promise<void>;
+/** The callback's parameters, when the app sent the browser back here. */
+export declare function callbackParams(hash?: string): URLSearchParams | null;
+export type CloudSignedIn = {
+    client: CloudClient;
+    user: CloudUser;
+    member: Member;
+    siteName: string;
+};
+export type CloudSignIn = ({
+    ok: true;
+    route: string;
+} & CloudSignedIn) | {
+    ok: false;
+    message: string;
+};
+/**
+ * Finishes a sign-in when the app sent the browser back here, or returns
+ * null when it didn't. The code leaves the address either way.
+ */
+export declare function finishCloudSignIn(settings: CloudSettings, options?: {
+    store?: KeyValueStore<StoredSession>;
+    fetch?: typeof fetch;
+}): Promise<CloudSignIn | null>;
+export type Resumed = ({
+    kind: 'signed-in';
+} & CloudSignedIn) | {
+    kind: 'signed-out';
+} | {
+    kind: 'unreachable';
+};
+/**
+ * Picks up a sign-in this browser already has. The refresh brings fresh
+ * tokens and the person's current role and grants, which may have changed
+ * in the dashboard since.
+ */
+export declare function resumeCloudSession(settings: CloudSettings, options?: {
+    store?: KeyValueStore<StoredSession>;
+    fetch?: typeof fetch;
+}): Promise<Resumed>;
+/** Ends the sign-in, here and in the cloud. The key goes too: the next sign-in makes a new one. */
+export declare function endCloudSession(settings: CloudSettings, client: CloudClient | null, store?: KeyValueStore<StoredSession>): Promise<void>;