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

package/dist/types.d.ts

@@ -0,0 +1,76 @@
+import type { Manifest, UrlEntry, WidgetProps } from '@vespercms/core';
+import type { CloudConnection } from './cloud/connection.ts';
+import type { CloudSettings } from './cloud/session.ts';
+import type { GitHubStudioSettings } from './github/session.ts';
+import type { ComponentType } from 'react';
+import type { StudioApi } from './app/api.ts';
+/** What a widget receives (spec §6.3.3); defined in core so sites can type widgets without the studio. */
+export type { WidgetProps };
+export type WidgetComponent = ComponentType<WidgetProps<any>>;
+/** A custom widget from vesper.config.ts, loaded only when a field uses it. */
+export type WidgetLoader = () => Promise<{
+    default: WidgetComponent;
+}>;
+export type StudioOptions = {
+    manifest: Manifest;
+    /**
+     * The storage back end, or `null` when this build has none yet: a deployed
+     * site before GitHub mode (Phase 3). The studio then explains where to edit.
+     */
+    api: StudioApi | null;
+    /** Custom widgets by name (spec §6.3.3). */
+    widgets?: Record<string, WidgetLoader>;
+    /**
+     * Loads declared MDX components' Zod props schemas from vesper.config.ts,
+     * so props are checked exactly as the site checks them (spec §6.5.2). On
+     * first use: Zod stays out of the studio's first load.
+     */
+    loadMdxProps?: () => Promise<Record<string, unknown>>;
+    /** Shown in the top bar and the page title. */
+    siteName?: string;
+    /** The site's home page, for "View site". */
+    siteUrl?: string;
+    /**
+     * GitHub mode in a built site (spec §6.8): with no `api`, the studio
+     * signs the editor in with GitHub and saves to this repository.
+     */
+    github?: GitHubStudioSettings | null;
+    /** The site's static routes at build, for GitHub mode's collision checks. */
+    routes?: readonly (readonly [string, string])[];
+    /** Function-form URL patterns from vesper.config.ts, for GitHub mode's moves and links. */
+    loadUrlFunctions?: () => Promise<Readonly<Record<string, (entry: UrlEntry) => unknown>>>;
+    /** Who is signed in, set by GitHub mode and the cloud. */
+    account?: Account;
+    /**
+     * The cloud in a built site (spec §6.9): with no `api`, the studio signs
+     * the editor in to Vesper, and saves become drafts.
+     */
+    cloud?: CloudSettings | null;
+    /** The studio connected to the cloud, set by the cloud's gate once signed in. */
+    connection?: CloudConnection;
+};
+/** The signed-in editor, in GitHub mode or the cloud: the user menu shows it. */
+export type Account = {
+    /** The user menu's button: `@login` on GitHub, the person's name on Vesper. */
+    label: string;
+    /** The person's name, at the top of the open menu and for their initials. */
+    name: string;
+    /** Their picture's address, beside the name; without one, their initials show. */
+    picture?: string;
+    /** The menu's name: "Signed in to GitHub as @login". */
+    description: string;
+    /** The menu's way out: "Sign out of GitHub", "Sign out of Vesper". */
+    signOutLabel: string;
+    /** The cloud's dashboard, for "Open dashboard". */
+    dashboardUrl?: string;
+    /**
+     * GitHub mode: the repository is public, so a change scheduled there can
+     * be read before it goes live (spec §6.17). The Schedule dialog says so.
+     */
+    publicRepository?: boolean;
+    signOut: () => void;
+    /** Signs in again after the session expired, coming back to the same screen. */
+    signInAgain: () => void;
+    /** True once GitHub has said the session expired. */
+    expired: boolean;
+};

package/dist/widgets/basic.d.ts

@@ -0,0 +1,25 @@
+import { type DataValue } from '@vespercms/core';
+import type { WidgetProps } from '../types.ts';
+/** Native inputs share the ui kit's control look. */
+export declare const inputClass: string;
+export declare function TextWidget(props: WidgetProps<string>): import("react").JSX.Element;
+export declare function EmailWidget(props: WidgetProps<string>): import("react").JSX.Element;
+export declare function TextAreaWidget(props: WidgetProps<string>): import("react").JSX.Element;
+export declare function NumberWidget({ value, onChange, field, id, describedBy, invalid, disabled, }: WidgetProps<number>): import("react").JSX.Element;
+export declare function SwitchWidget({ value, onChange, id, describedBy, invalid, disabled, }: WidgetProps<boolean>): import("react").JSX.Element;
+/**
+ * A calendar date. The value keeps its type: a Date stays a Date (written
+ * back as `2026-10-17`), and a quoted string stays a string.
+ */
+export declare function DateWidget({ value, onChange, field, id, describedBy, invalid, disabled, }: WidgetProps<Date | string>): import("react").JSX.Element;
+export declare function SelectWidget({ value, onChange, field, id, describedBy, invalid, disabled, }: WidgetProps<string>): import("react").JSX.Element;
+/** Up to four options, all visible. Rendered inside the field's fieldset, which names it. */
+export declare function RadioWidget({ value, onChange, field, id, describedBy, invalid, disabled, }: WidgetProps<string>): import("react").JSX.Element;
+/** A list of strings: type and press Enter to add, each with a named remove button. */
+export declare function TagsWidget({ value, onChange, field, id, describedBy, invalid, disabled, }: WidgetProps<string[]>): import("react").JSX.Element;
+/**
+ * The raw field (spec §6.3 step 4): any value Vesper can't map to a control,
+ * edited as a small YAML snippet and parsed the way Astro parses it. The
+ * text is kept while it's invalid, so nothing typed is lost.
+ */
+export declare function RawWidget({ value, onChange, field, id, describedBy, invalid, disabled, }: WidgetProps<DataValue>): import("react").JSX.Element;

package/dist/widgets/blank-date.d.ts

@@ -0,0 +1,8 @@
+import { type FocusEvent, type KeyboardEvent } from 'react';
+/** Props for a `date` or `datetime-local` input whose value is `value`. */
+export declare function useBlankWhenEmpty(value: string): {
+    'data-blank': string | undefined;
+    onPointerDown: () => void;
+    onKeyDown: (event: KeyboardEvent) => void;
+    onBlur: (event: FocusEvent<HTMLInputElement>) => void;
+};

package/dist/widgets/crops.d.ts

@@ -0,0 +1,43 @@
+import { type CropRect, type ImageSize, type ImageValue } from '@vespercms/core';
+export type Ratio = {
+    name: string;
+    ratio: number;
+};
+/** A ratio's name for people: "Wide", or "Social image" for the built-in og. */
+export declare function ratioName(name: string): string;
+/** The image positioned inside a box of the crop's shape so only the crop shows. */
+export declare function cropStyle(rect: CropRect): {
+    width: string;
+    height: string;
+    left: string;
+    top: string;
+};
+export type CropPreviewsProps = {
+    id: string;
+    src: string;
+    /** The image's natural size; previews wait for it. */
+    size: ImageSize | null;
+    value: ImageValue;
+    ratios: Ratio[];
+    /** The field's crops after a change: one applied, or one reset to the focal point. */
+    onChange: (crops: Record<string, CropRect>) => void;
+    disabled: boolean;
+};
+export declare function CropPreviews({ id, src, size, value, ratios, onChange, disabled, }: CropPreviewsProps): import("react").JSX.Element;
+/** "40% from the left, 10% from the top, 45% of the width", for the crop box. */
+export declare function describeCrop(rect: CropRect): string;
+export type CropDialogProps = {
+    src: string;
+    size: ImageSize;
+    name: string;
+    ratio: number;
+    /** Where the box starts: the custom crop, or the focal point's. */
+    start: {
+        rect: CropRect;
+        custom: boolean;
+    };
+    onClose: () => void;
+    onApply: (rect: CropRect) => void;
+    onReset: () => void;
+};
+export declare function CropDialog({ src, size, name, ratio, start, onClose, onApply, onReset, }: CropDialogProps): import("react").JSX.Element;

package/dist/widgets/focal-point.d.ts

@@ -0,0 +1,15 @@
+import { type FocalPoint, type ImageSize } from '@vespercms/core';
+/** "62% across, 35% down", the words the control and the announcements use. */
+export declare function describeFocus(focus: FocalPoint | undefined): string;
+export type FocalPointControlProps = {
+    id: string;
+    /** The image's URL. */
+    src: string;
+    focus: FocalPoint | undefined;
+    /** A new focal point, or undefined to go back to the centre. */
+    onChange: (focus: FocalPoint | undefined) => void;
+    /** The image's natural size, once it has loaded (for the crop previews). */
+    onImageSize?: (size: ImageSize) => void;
+    disabled: boolean;
+};
+export declare function FocalPointControl({ id, src, focus, onChange, onImageSize, disabled, }: FocalPointControlProps): import("react").JSX.Element;

package/dist/widgets/geo-map.d.ts

@@ -0,0 +1,10 @@
+import 'maplibre-gl/dist/maplibre-gl.css';
+import type { LatLng } from './geo.tsx';
+export default function GeoMap({ label, point, center, zoom, disabled, onChange, }: {
+    label: string;
+    point: LatLng | null;
+    center: LatLng | undefined;
+    zoom: number | undefined;
+    disabled: boolean;
+    onChange: (point: LatLng) => void;
+}): import("react").JSX.Element;

package/dist/widgets/geo.d.ts

@@ -0,0 +1,16 @@
+import { type DataValue } from '@vespercms/core';
+import type { ValuePath } from '../editor/values.ts';
+import type { WidgetProps } from '../types.ts';
+export type LatLng = {
+    lat: number;
+    lng: number;
+};
+/**
+ * A place (spec §6.3.2): latitude and longitude as two number fields, which
+ * are the real, always-visible controls. A map with a draggable,
+ * keyboard-movable pin loads only when asked for: it fetches map tiles from
+ * the internet, and it's a convenience, not the way in.
+ */
+export declare function GeoWidget({ value, onChange, field, id, disabled, invalid, describedBy, }: WidgetProps<DataValue> & {
+    path: ValuePath;
+}): import("react").JSX.Element;

package/dist/widgets/group.d.ts

@@ -0,0 +1,41 @@
+import { type DataValue, type FieldModel } from '@vespercms/core';
+import { type ValuePath } from '../editor/values.ts';
+import type { WidgetProps } from '../types.ts';
+type GroupProps = WidgetProps<DataValue> & {
+    path: ValuePath;
+};
+/** An object: its fields, in schema order, inside the field's fieldset. */
+export declare function GroupWidget({ field, path }: GroupProps): import("react").JSX.Element;
+/** What one item and several are called: "point" and "points", from the list's own label. */
+export declare function itemNames(list: FieldModel): {
+    one: string;
+    many: string;
+};
+/**
+ * A list item's name, from its own content: an image's alt text or file
+ * name; otherwise the `summary` hint's field, a title-like field, or its
+ * first text, in that order; else "Point 3".
+ */
+export declare function itemSummary(value: DataValue, index: number, list: FieldModel): {
+    name: string;
+    key: string | undefined;
+};
+/**
+ * The repeater (spec §6.3.2). A list of objects or images shows each item as
+ * a row named by its content, which opens in place (DECISIONS.md, "Top-level
+ * groups are sections, and list items are rows that open in place"). Rows
+ * are closed when the entry opens, except a new item and any holding a field
+ * that a refused save names. Order never depends on drag-and-drop (spec
+ * §10.6): each item's "…" menu moves it, and Alt+↑/↓ on a row does too. A
+ * row's handle drags it as well, for the pointer only (DECISIONS.md, "List
+ * rows drag by a handle"). Closed items stay in the page
+ * (`hidden="until-found"`), so the browser's find, the error summary and Go
+ * to field still reach every field.
+ *
+ * A list of kinds (a discriminated union) names each row by its kind. Add
+ * offers the kinds, each row's "…" menu adds one below it or changes its
+ * kind, and a change that would remove content asks first (DECISIONS.md,
+ * "Blocks are a discriminated union of objects").
+ */
+export declare function RepeaterWidget({ value, onChange, field, path, disabled, id }: GroupProps): import("react").JSX.Element;
+export {};

package/dist/widgets/icon.d.ts

@@ -0,0 +1,9 @@
+import type { WidgetProps } from '../types.ts';
+/**
+ * An icon field (`fields.icon`): a searchable list of the names it offers,
+ * each with its icon before it, and the chosen one's icon in the field. The
+ * drawings come from the manifest, which holds only the icons the site's
+ * fields offer, so the studio carries no icon set of its own. The file
+ * stores the name.
+ */
+export declare function IconWidget({ value, onChange, field, id, describedBy, invalid, disabled, }: WidgetProps<string>): import("react").JSX.Element;

package/dist/widgets/image.d.ts

@@ -0,0 +1,16 @@
+import { type DataValue, type FieldModel } from '@vespercms/core';
+import { type ValuePath } from '../editor/values.ts';
+import type { WidgetProps } from '../types.ts';
+import { type Ratio } from './crops.tsx';
+/** The ratios a field previews: the ones it lists, else every ratio the site has (spec §6.6.3). */
+export declare function fieldRatios(field: FieldModel, site: Record<string, number>): Ratio[];
+/**
+ * An image: preview, choose or replace, alt text written for this page, and
+ * a "Decorative image" option that stores `alt: ""` and `decorative: true`.
+ * A plain `image()` field stores just the path, with no alt text here.
+ */
+export declare function ImageWidget({ value, onChange, field, id, describedBy, invalid, disabled, path, }: WidgetProps<DataValue> & {
+    path: ValuePath;
+}): import("react").JSX.Element;
+/** A file (PDF and so on): its name, type and size, with choose, replace and remove. */
+export declare function FileWidget({ value, onChange, field, id, describedBy, disabled, }: WidgetProps<string>): import("react").JSX.Element;

package/dist/widgets/markdown-lazy.d.ts

@@ -0,0 +1,2 @@
+import type { WidgetProps } from '../types.ts';
+export declare function LazyMarkdownWidget(props: WidgetProps<string>): import("react").JSX.Element;

package/dist/widgets/markdown.d.ts

@@ -0,0 +1,2 @@
+import type { WidgetProps } from '../types.ts';
+export declare function MarkdownWidget(props: WidgetProps<string>): import("react").JSX.Element;

package/dist/widgets/reference.d.ts

@@ -0,0 +1,12 @@
+import { type DataValue } from '@vespercms/core';
+import type { WidgetProps } from '../types.ts';
+/** The ID a stored reference points at. */
+export declare function referenceId(value: DataValue): string | undefined;
+/** One reference: a searchable list of the other collection's entries. */
+export declare function ReferenceWidget({ value, onChange, field, id, describedBy, invalid, disabled, }: WidgetProps<DataValue>): import("react").JSX.Element;
+/**
+ * Several references, in order. Order usually matters (related posts), so
+ * each has Move up, Move down and Remove buttons, and new ones are added
+ * from a search box at the end.
+ */
+export declare function ReferencesWidget({ value, onChange, field, id, describedBy, invalid, disabled, }: WidgetProps<DataValue[]>): import("react").JSX.Element;

package/dist/widgets/registry.d.ts

@@ -0,0 +1,32 @@
+import type { FieldModel } from '@vespercms/core';
+import type { ComponentType } from 'react';
+import type { ValuePath } from '../editor/values.ts';
+import type { WidgetProps } from '../types.ts';
+export type BuiltinWidgetProps = WidgetProps<any> & {
+    path: ValuePath;
+    /** The field is a list item in its own row, which already names it (a union's kind). */
+    inRow?: boolean;
+};
+export type BuiltinWidget = {
+    component: ComponentType<BuiltinWidgetProps>;
+    /**
+     * Renders as a fieldset whose legend is the label (objects, lists, radio
+     * groups); `'boxed'` also draws a hairline around it (an image, a map).
+     */
+    group?: true | 'boxed';
+    /** Renders each child (or item) as its own field, so their errors show there. */
+    rendersChildren?: true;
+    /**
+     * At the form's first level it's a section: a hairline above, its own
+     * heading, more space (DECISIONS.md, "Top-level groups are sections").
+     * Deeper, an object is set off by an indent guide instead of a frame.
+     */
+    section?: true;
+    /** Ids of controls it renders for some of its children, as suffixes of its own id (`alt` → `-alt`). */
+    childControls?: Readonly<Record<string, string>>;
+};
+/**
+ * The built-in control for a field: its resolved widget, else the one its
+ * type implies (spec §6.3 step 3), else the raw YAML field (step 4).
+ */
+export declare function builtinWidget(field: FieldModel): BuiltinWidget;

package/dist/widgets/special.d.ts

@@ -0,0 +1,20 @@
+import type { WidgetProps } from '../types.ts';
+/**
+ * Colour (spec §6.3.2). The hex text field is the primary control; the
+ * native picker is a convenience beside it. With a palette, it's a radio
+ * group of named swatches instead, each named in words.
+ */
+export declare function ColorWidget({ value, onChange, field, id, describedBy, invalid, disabled, }: WidgetProps<string>): import("react").JSX.Element;
+/**
+ * Slug (spec §6.3.2): follows its source field (usually the title) until
+ * someone edits it by hand. It follows only on entries that haven't been
+ * saved yet, so a published page's URL never changes behind anyone's back.
+ */
+export declare function SlugWidget({ value, onChange, field, id, describedBy, invalid, disabled, }: WidgetProps<string>): import("react").JSX.Element;
+/** URL, with a link that opens it (spec §6.3.2). */
+export declare function UrlWidget({ value, onChange, field, id, describedBy, invalid, disabled, }: WidgetProps<string>): import("react").JSX.Element;
+/**
+ * Date and time in the site's time zone, named in text (spec §6.17). The
+ * value keeps its type: a Date stays a Date, written with that day's offset.
+ */
+export declare function DateTimeWidget({ value, onChange, field, id, describedBy, invalid, disabled, }: WidgetProps<Date | string>): import("react").JSX.Element;

package/dist/widgets/union.d.ts

@@ -0,0 +1,36 @@
+import { type DataObject, type DataValue, type FieldModel, type FieldVariant } from '@vespercms/core';
+import { type ValuePath } from '../editor/values.ts';
+import type { WidgetProps } from '../types.ts';
+/** A new value of a kind: its key first, then its fields' own defaults, as a new entry gets them. */
+export declare function kindValue(union: FieldModel, kind: FieldVariant): DataObject;
+export type KindChange = {
+    value: DataObject;
+    /** Labels of the fields both kinds have, whose values carried over. */
+    kept: string[];
+    /** Labels of the fields with content the new kind has no place for. */
+    dropped: string[];
+};
+/**
+ * A value moved to another kind. A field the new kind has under the same key
+ * and of the same kind keeps its value; the rest are dropped. `setAside` is
+ * what this value last held as the new kind, in this visit: changing back
+ * before saving brings it back.
+ */
+export declare function changeKind(union: FieldModel, value: DataValue, to: FieldVariant, setAside?: DataObject): KindChange;
+/** "Heading kept. Cards and Layout removed." for the status line after a change of kind. */
+export declare function changeSummary(change: KindChange): string;
+/**
+ * How a list names an item of a kind: by its kind, with its own words after
+ * it ("Card grid", "This industry has rules"). On a page, the order of kinds
+ * is what someone scans for, and kinds are short names.
+ */
+export declare function kindRow(value: DataValue, union: FieldModel): {
+    name: string;
+    detail: string;
+};
+type UnionProps = WidgetProps<DataValue> & {
+    path: ValuePath;
+    inRow?: boolean;
+};
+export declare function UnionWidget(props: UnionProps): import("react").JSX.Element | null;
+export {};

package/package.json

@@ -1,6 +1,65 @@
 {
   "name": "@vespercms/admin",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-next.1",
+  "description": "The Vesper studio: the editor UI served at /admin, one bundle for every storage mode.",
+  "license": "MIT",
+  "homepage": "https://vespercms.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vespercms/vespercms.git",
+    "directory": "packages/admin"
+  },
+  "type": "module",
+  "sideEffects": [
+    "*.css"
+  ],
+  "//exports": "Source in this workspace (@vesper/source); dist/ elsewhere. dist/studio.css is precompiled, so sites need no Tailwind (DECISIONS.md, Studio).",
+  "exports": {
+    ".": {
+      "@vesper/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/studio.js"
+    },
+    "./studio.css": {
+      "@vesper/source": "./src/studio.css",
+      "default": "./dist/studio.css"
+    }
+  },
+  "files": [
+    "dist",
+    "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/**/__snapshots__",
+    "!src/test",
+    "!src/test-env.d.ts"
+  ],
+  "scripts": {
+    "build": "vite build && tsc -p tsconfig.build.json",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@tiptap/core": "^3.32.0",
+    "@tiptap/extension-image": "^3.32.0",
+    "@tiptap/markdown": "^3.32.0",
+    "@tiptap/pm": "^3.32.0",
+    "@tiptap/react": "^3.32.0",
+    "@tiptap/starter-kit": "^3.32.0",
+    "@vespercms/core": "0.1.0-next.1",
+    "dompurify": "^3.4.17",
+    "maplibre-gl": "^6.14.0",
+    "pdfjs-dist": "^6.4.299",
+    "react-aria-components": "^1.22.1"
+  },
+  "//peerDependencies": "One React for the studio and the site's custom widgets, which render inside it (spec §6.3.3).",
+  "peerDependencies": {
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@fontsource/figtree": "^5.3.0",
+    "@tailwindcss/vite": "^4.3.3",
+    "@vespercms/ui": "0.0.0",
+    "tailwindcss": "^4.3.3"
+  }
+}

package/src/a11y/FieldNotes.tsx

@@ -0,0 +1,56 @@
+import type { A11yNote } from '@vespercms/core';
+import { Icon } from '@vespercms/ui';
+import type { ReactNode } from 'react';
+
+/** A note's words: what it's about, the problem, and why it matters (spec §6.18). */
+export function NoteText({ note }: { note: A11yNote }) {
+  return (
+    <>
+      {note.subject ? `${note.subject}: ` : ''}
+      {note.message} <span className="text-content-muted">{note.why}</span>
+    </>
+  );
+}
+
+/**
+ * Accessibility notes under the field they're about. Text, never a coloured
+ * badge (spec §10.4): the small warning mark is the only colour, and the
+ * words say what it is. The list is part of the control's description.
+ */
+export function FieldNotes({ id, notes }: { id: string; notes: readonly A11yNote[] }) {
+  return (
+    <ul id={id} className="m-0 flex list-none flex-col gap-1 p-0">
+      {notes.map((note, index) => (
+        <li key={`${note.rule}:${String(index)}`} className="flex gap-2 text-small text-content">
+          <NoteLine>
+            <NoteText note={note} />
+          </NoteLine>
+        </li>
+      ))}
+    </ul>
+  );
+}
+
+/**
+ * One note the studio writes itself, not from a rule (a replaced image's alt
+ * text), in the same words and mark as the rules' notes beside a field.
+ */
+export function FieldNote({ id, children }: { id: string; children: ReactNode }) {
+  return (
+    <p id={id} className="flex gap-2 text-small text-content">
+      <NoteLine>{children}</NoteLine>
+    </p>
+  );
+}
+
+function NoteLine({ children }: { children: ReactNode }) {
+  return (
+    <>
+      <Icon name="warning" size={16} className="mt-0.5 text-warning" />
+      <span>
+        <span className="font-semibold">Accessibility note: </span>
+        {children}
+      </span>
+    </>
+  );
+}

package/src/a11y/NotesDrawer.tsx

@@ -0,0 +1,81 @@
+import type { A11yNote } from '@vespercms/core';
+import { Button, Drawer, Icon } from '@vespercms/ui';
+import { NoteText } from './FieldNotes.tsx';
+
+/** The notes about one field (or the body), under its name. */
+export type NoteGroup = { key: string; label: string; notes: A11yNote[] };
+
+/** "2 accessibility notes", and how many refuse a save under the site's gate. */
+export function notesCount(notes: number, blocking: number): string {
+  const text = `${String(notes)} accessibility ${notes === 1 ? 'note' : 'notes'}`;
+  if (blocking === 0) return text;
+  return `${text}, ${String(blocking)} ${blocking === 1 ? 'blocks' : 'block'} saving`;
+}
+
+/**
+ * Every accessibility note on the entry (spec §6.18), opened from the count
+ * in the top bar: grouped under each field's name in form order, each with
+ * why it matters and "Go to field". A modal drawer: focus moves in, Escape
+ * closes it, and focus returns to the count.
+ */
+export function NotesDrawer({
+  isOpen,
+  onOpenChange,
+  groups,
+  isBlocking,
+  onGo,
+}: {
+  isOpen: boolean;
+  onOpenChange: (open: boolean) => void;
+  groups: readonly NoteGroup[];
+  isBlocking: (note: A11yNote) => boolean;
+  /** Closes the drawer and takes focus to the note's field. */
+  onGo: (note: A11yNote) => void;
+}) {
+  return (
+    <Drawer title="Accessibility notes" isOpen={isOpen} onOpenChange={onOpenChange}>
+      <div className="flex flex-col gap-6">
+        <p className="text-content-muted">
+          Automated checks find some problems, not all. Check the page by hand too, with a keyboard
+          and a screen reader.
+        </p>
+        {groups.map((group) => (
+          <section key={group.key} aria-labelledby={`a11y-group-${group.key}`}>
+            <h3 id={`a11y-group-${group.key}`} className="mb-2 text-heading-3 text-content">
+              {group.label}
+            </h3>
+            <ul className="m-0 flex list-none flex-col gap-4 p-0">
+              {group.notes.map((note, index) => {
+                const id = `a11y-note-${group.key}-${String(index)}`;
+                return (
+                  <li key={id} className="flex flex-col items-start gap-2">
+                    <p id={id} className="m-0 flex gap-2">
+                      <Icon name="warning" size={16} className="mt-1 text-warning" />
+                      <span>
+                        <NoteText note={note} />
+                        {isBlocking(note) && (
+                          <span className="font-semibold">
+                            {' '}
+                            This site doesn’t save until it’s fixed.
+                          </span>
+                        )}
+                      </span>
+                    </p>
+                    <Button
+                      aria-describedby={id}
+                      onPress={() => {
+                        onGo(note);
+                      }}
+                    >
+                      Go to field
+                    </Button>
+                  </li>
+                );
+              })}
+            </ul>
+          </section>
+        ))}
+      </div>
+    </Drawer>
+  );
+}

package/src/a11y/pdf.ts

@@ -0,0 +1,45 @@
+import type { PdfFacts } from '@vespercms/core';
+import { GlobalWorkerOptions, getDocument } from 'pdfjs-dist/legacy/build/pdf.mjs';
+import workerUrl from 'pdfjs-dist/legacy/build/pdf.worker.min.mjs?url';
+
+/*
+ * What a PDF says about its own accessibility (spec §6.18): whether it's
+ * tagged, its title and its language, read with PDF.js in the browser, so it
+ * works in every storage mode. This module and PDF.js load only when an entry
+ * has a PDF to check. The legacy build runs in browsers older than the
+ * modern build's floor (Chrome 140, Firefox 133, Safari 18.2).
+ */
+
+GlobalWorkerOptions.workerSrc = workerUrl;
+
+/** Reads the facts the PDF rules need. Nothing is rendered, and no script in the file runs. */
+export async function readPdfFacts(bytes: ArrayBuffer | Uint8Array): Promise<PdfFacts> {
+  const task = getDocument({
+    data: bytes instanceof Uint8Array ? bytes : new Uint8Array(bytes),
+    enableXfa: false,
+    disableFontFace: true,
+    verbosity: 0,
+  });
+  try {
+    const pdf = await task.promise;
+    const [mark, meta] = await Promise.all([pdf.getMarkInfo(), pdf.getMetadata()]);
+    // A tagged PDF marks itself as tagged and has a structure tree.
+    const tree = pdf.numPages > 0 ? await (await pdf.getPage(1)).getStructTree() : null;
+    const info = meta.info as { Title?: unknown; Language?: unknown };
+    // Typed as always there, but null for a PDF with no XMP metadata.
+    const metadata = meta.metadata as { get: (name: string) => unknown } | null;
+    const xmpTitle = metadata?.get('dc:title');
+    const text = (value: unknown) =>
+      typeof value === 'string' && value.trim() !== '' ? value.trim() : null;
+    // PDF.js 6 gives the mark info as a Map; older versions as an object.
+    const marked: unknown =
+      mark instanceof Map ? (mark as Map<string, unknown>).get('Marked') : mark?.Marked;
+    return {
+      tagged: marked === true && tree !== null,
+      title: text(info.Title) ?? text(xmpTitle),
+      language: text(info.Language),
+    };
+  } finally {
+    await task.destroy();
+  }
+}

package/src/a11y/run.ts

@@ -0,0 +1,12 @@
+import { entryChecker, type Manifest } from '@vespercms/core';
+
+/*
+ * The accessibility checks themselves (spec §6.18). They read bodies with
+ * micromark and Markdoc, which are large, so this module loads on first use,
+ * like the body checks (DECISIONS.md, "The body editor loads on first use").
+ */
+export function a11yChecker(manifest: Manifest): ReturnType<typeof entryChecker> {
+  return entryChecker(manifest);
+}
+
+export { pdfNotes } from '@vespercms/core';