rimecms 0.31.4 → 0.32.0

package/dist/core/plugins/sse/index.d.ts

@@ -1,2 +1,10 @@
-/// <reference path="../../../.rime-modules.d.ts" />
-export { sse } from "$rime/modules/rimecms/core/plugins/sse";
+/**
+ * The event stream, client half. The server half is `index.server.ts`.
+ *
+ * - The client calls `openSse` with the keys it wants, which opens `GET /api/sse?keys=…`.
+ * - The server answers it in `connect`: it checks each key, then leaves the response open.
+ * - The server sends an event with `emit`, which writes it to the connections holding that key.
+ * - The client's handler is called with that event.
+ */
+export { openSse } from './client.js';
+export type { SSEAccess, SSEEvent, SSEHandler } from './types.js';

package/dist/core/plugins/sse/index.js

@@ -1 +1,9 @@
-export { sse } from "$rime/modules/rimecms/core/plugins/sse";
+/**
+ * The event stream, client half. The server half is `index.server.ts`.
+ *
+ * - The client calls `openSse` with the keys it wants, which opens `GET /api/sse?keys=…`.
+ * - The server answers it in `connect`: it checks each key, then leaves the response open.
+ * - The server sends an event with `emit`, which writes it to the connections holding that key.
+ * - The client's handler is called with that event.
+ */
+export { openSse } from './client.js';

package/dist/core/plugins/sse/index.server.d.ts

@@ -0,0 +1,29 @@
+import { emit } from './bus.server.js';
+import type { SSEAccess } from './types.js';
+/**
+ * The event stream, at `/api/sse`.
+ *
+ * Send with `rime.sse.emit(key, event, payload)`, listen with `openSse(keys, handler)`.
+ *
+ * `rime:` keys are the panel's and need staff; every other key is refused until `access` says
+ * otherwise, so an app opens its own deliberately rather than by leaving a default alone.
+ *
+ * @example
+ * sse({ access: (key) => key.startsWith('public:') })
+ */
+export declare const sse: (options?: {
+    access?: SSEAccess;
+}) => {
+    readonly name: "sse";
+    readonly actions: {
+        readonly emit: (key: string, event: string, payload?: Record<string, any>) => void;
+    };
+    readonly routes: {
+        readonly '/api/sse': {
+            readonly GET: import("@sveltejs/kit").RequestHandler;
+        };
+    };
+};
+export type SSEActions = {
+    emit: typeof emit;
+};

package/dist/core/plugins/sse/index.server.js

@@ -0,0 +1,18 @@
+import { definePlugin } from '../index.js';
+import { connect, emit } from './bus.server.js';
+/**
+ * The event stream, at `/api/sse`.
+ *
+ * Send with `rime.sse.emit(key, event, payload)`, listen with `openSse(keys, handler)`.
+ *
+ * `rime:` keys are the panel's and need staff; every other key is refused until `access` says
+ * otherwise, so an app opens its own deliberately rather than by leaving a default alone.
+ *
+ * @example
+ * sse({ access: (key) => key.startsWith('public:') })
+ */
+export const sse = definePlugin((options) => ({
+    name: 'sse',
+    actions: { emit },
+    routes: { '/api/sse': { GET: connect(options?.access ?? (() => false)) } }
+}));

package/dist/core/plugins/sse/types.d.ts

@@ -1,8 +1,16 @@
-import type { Operation } from '../../operations/hooks/index.server.js';
-import type { PrototypeSlug } from '../../../types.js';
-export type ContentUpdatePayload = {
-    documentType: PrototypeSlug;
-    id: string;
-    operation: Omit<Operation, 'read'>;
-    timestamp: string;
+import type { User } from '../../auth/types.js';
+/** One event on the stream. */
+export type SSEEvent = {
+    /** `rime:lock`, or an app's own name. */
+    event: string;
+    payload: Record<string, any>;
 };
+/** Handles one event. Returning a promise is fine; nothing waits on it. */
+export type SSEHandler = (event: SSEEvent) => void | Promise<void>;
+/**
+ * Whether this caller may listen to this key.
+ *
+ * Asked once per key when the connection opens, before anything is written to it — which is the
+ * point of naming keys up front rather than filtering in the browser.
+ */
+export type SSEAccess = (key: string, user?: User) => boolean;

package/dist/core/prototype/area/api.server.d.ts

@@ -0,0 +1,91 @@
+import type { BuiltArea } from '../../config/types.js';
+import type { RegisterArea } from '../../../index.js';
+import type { PrototypeApiContext } from '../define.js';
+import type { RequestEvent } from '@sveltejs/kit';
+import type { Dic } from '../../../util/types.js';
+import type { GenericDoc } from '../types.js';
+import type { OperationQuery } from '../../pipeline/types.js';
+import { type FindArgs } from './operations/find.js';
+import { type UpdateArgs } from './operations/update.js';
+/** What building an area's API for one request needs. */
+export type AreaApiArgs = {
+    config: BuiltArea;
+    event: RequestEvent;
+    defaultLocale: string | undefined;
+};
+/**
+ * Everything `rime.area('settings')` can do: exactly two operations.
+ *
+ * There is no `create` and no `delete` — not switched off, absent, because a singleton has no
+ * second document to make and nothing left to read if its only one goes. Nor is there an id
+ * anywhere in these signatures. That is the whole difference from a collection, and it is why
+ * this is its own class rather than a collection with a flag.
+ *
+ * `blank()` is the document as its fields default it, full stop: no auth step, because an area
+ * lists no `auth`. The collection's strips auth's private members — the two were one
+ * `prototypeContext` with a `shapeBlank(doc, config, intent)` between them, for a branch neither
+ * kind could reach.
+ */
+declare class AreaAPI<Doc extends GenericDoc> implements PrototypeApiContext<BuiltArea> {
+    private readonly args;
+    readonly config: BuiltArea;
+    readonly event: RequestEvent;
+    readonly defaultLocale: string | undefined;
+    /** True when rime itself is the caller: access checks and some hooks stand down. */
+    readonly isSystemOperation: boolean;
+    constructor(args: AreaApiArgs, isSystemOperation?: boolean);
+    /**
+     * The same API, telling the pipeline that rime is the caller.
+     *
+     * A new instance rather than a flag, so a system call cannot leak back into the one it was
+     * escalated from. `system(false)` hands this one back.
+     */
+    system(isSystem?: boolean): AreaAPI<Doc>;
+    /** The area's document with every default applied. */
+    blank(): Doc;
+    /** The locale to act in: the one asked for, else the request's, else the config's default. */
+    fallbackLocale(locale?: string): string | undefined;
+    /** Which version row a read means — see `versionsReadQuery`. */
+    versionQuery(params: {
+        latest?: boolean;
+        versionId?: string;
+    }): OperationQuery | undefined;
+    /** Read through the API cache when it is on and this is not a system call. */
+    cached<T>(operation: string, key: Dic, read: () => Promise<T>): Promise<T>;
+    /**
+     * Retrieves the area's document
+     *
+     * - For non-versioned areas: Returns the single document
+     * - For versioned areas without draft support: Returns the latest version by default, or a
+     *   specific version if versionId is provided
+     * - For versioned areas with draft support:
+     *   - If versionId is provided: Returns that specific version
+     *   - If latest=true: Returns the newest version (regardless of status)
+     *   - If draft=false: Returns the published version
+     *
+     * @example
+     * const doc = await rime.area('settings').find({ locale })
+     * const doc = await rime.area('settings').find({ versionId: '123' })
+     * const doc = await rime.area('settings').find({ latest: true })
+     */
+    find(args?: FindArgs): Promise<Doc>;
+    /**
+     * Updates the area's document
+     *
+     * `versionId`, else `latest`, else the published version selects the row; `fork` makes a new
+     * version from it instead of writing it. See the collection's `updateById`.
+     *
+     * @example
+     * rime.area('settings').update({ data, locale })
+     */
+    update(args: UpdateArgs<Doc>): Promise<Doc>;
+}
+/** Builds an area's API for one request. What `rime.area(slug)` calls. */
+export declare const areaApi: <Doc extends GenericDoc>(args: AreaApiArgs) => AreaApi<Doc>;
+/**
+ * What `rime.area(slug)` hands back — written out, not read off the class. See the note on
+ * `CollectionApi` for why the plumbing must not appear in this type.
+ */
+export type AreaApi<Doc extends GenericDoc = GenericDoc> = Pick<AreaAPI<Doc>, 'config' | 'blank' | 'find' | 'update' | 'system'>;
+export type AreaAccessor = <Slug extends keyof RegisterArea>(slug: Slug) => AreaApi<RegisterArea[Slug]>;
+export {};

package/dist/core/prototype/area/api.server.js

@@ -0,0 +1,117 @@
+import { createBlankDocument } from '../doc.js';
+import { versionsReadQuery } from '../shared/versions/read-query.js';
+import { find } from './operations/find.js';
+import { update } from './operations/update.js';
+/**
+ * Everything `rime.area('settings')` can do: exactly two operations.
+ *
+ * There is no `create` and no `delete` — not switched off, absent, because a singleton has no
+ * second document to make and nothing left to read if its only one goes. Nor is there an id
+ * anywhere in these signatures. That is the whole difference from a collection, and it is why
+ * this is its own class rather than a collection with a flag.
+ *
+ * `blank()` is the document as its fields default it, full stop: no auth step, because an area
+ * lists no `auth`. The collection's strips auth's private members — the two were one
+ * `prototypeContext` with a `shapeBlank(doc, config, intent)` between them, for a branch neither
+ * kind could reach.
+ */
+class AreaAPI {
+    args;
+    config;
+    event;
+    defaultLocale;
+    /** True when rime itself is the caller: access checks and some hooks stand down. */
+    isSystemOperation;
+    constructor(args, isSystemOperation = false) {
+        this.args = args;
+        this.config = args.config;
+        this.event = args.event;
+        this.defaultLocale = args.defaultLocale;
+        this.isSystemOperation = isSystemOperation;
+    }
+    /**
+     * The same API, telling the pipeline that rime is the caller.
+     *
+     * A new instance rather than a flag, so a system call cannot leak back into the one it was
+     * escalated from. `system(false)` hands this one back.
+     */
+    system(isSystem = true) {
+        return isSystem ? new AreaAPI(this.args, true) : this;
+    }
+    /** The area's document with every default applied. */
+    blank() {
+        return createBlankDocument(this.config, this.event);
+    }
+    /** The locale to act in: the one asked for, else the request's, else the config's default. */
+    fallbackLocale(locale) {
+        return locale || this.event.locals.locale || this.defaultLocale;
+    }
+    /** Which version row a read means — see `versionsReadQuery`. */
+    versionQuery(params) {
+        return versionsReadQuery({ config: this.config, params });
+    }
+    /** Read through the API cache when it is on and this is not a system call. */
+    cached(operation, key, read) {
+        if (!this.event.locals.cacheEnabled || this.isSystemOperation)
+            return read();
+        const cacheKey = this.event.locals.rime.cache.createKey(operation, {
+            slug: this.config.slug,
+            userEmail: this.event.locals.user?.email,
+            userRoles: this.event.locals.user?.roles,
+            ...key
+        });
+        return this.event.locals.rime.cache.get(cacheKey, read);
+    }
+    /**
+     * Retrieves the area's document
+     *
+     * - For non-versioned areas: Returns the single document
+     * - For versioned areas without draft support: Returns the latest version by default, or a
+     *   specific version if versionId is provided
+     * - For versioned areas with draft support:
+     *   - If versionId is provided: Returns that specific version
+     *   - If latest=true: Returns the newest version (regardless of status)
+     *   - If draft=false: Returns the published version
+     *
+     * @example
+     * const doc = await rime.area('settings').find({ locale })
+     * const doc = await rime.area('settings').find({ versionId: '123' })
+     * const doc = await rime.area('settings').find({ latest: true })
+     */
+    find(args = {}) {
+        const { locale, select = [], depth = 0, versionId, latest, localeFallback } = args;
+        // As on a collection's find: the key holds the caller's locale, not the resolved one.
+        return this.cached('area.find', { select, versionId, depth, latest, locale, localeFallback }, () => find({
+            ctx: this,
+            select,
+            versionId,
+            depth,
+            latest,
+            localeFallback,
+            locale: this.fallbackLocale(locale)
+        }));
+    }
+    /**
+     * Updates the area's document
+     *
+     * `versionId`, else `latest`, else the published version selects the row; `fork` makes a new
+     * version from it instead of writing it. See the collection's `updateById`.
+     *
+     * @example
+     * rime.area('settings').update({ data, locale })
+     */
+    update(args) {
+        const { data, locale, versionId, latest, fork, autoSave } = args;
+        return update({
+            ctx: this,
+            data,
+            versionId,
+            latest,
+            fork,
+            autoSave,
+            locale: this.fallbackLocale(locale)
+        });
+    }
+}
+/** Builds an area's API for one request. What `rime.area(slug)` calls. */
+export const areaApi = (args) => new AreaAPI(args);

package/dist/core/prototype/area/augment-label.d.ts

@@ -0,0 +1,16 @@
+type WithAreaLabel<T> = Omit<T, 'label'> & {
+    label: string;
+};
+/**
+ * An area's label: what the author wrote, else its capitalised slug.
+ *
+ * The area's one own augment, and the mirror of the collection's — which normalises a string or
+ * an object into `{ singular, plural }`, because a collection is named in two numbers and an area
+ * in one. The kind's own statement about itself, so it belongs to the kind rather than to a
+ * shared factory.
+ */
+export declare const augmentAreaLabel: <T extends {
+    slug: string;
+    label?: string;
+}>(config: T) => WithAreaLabel<T>;
+export {};

package/dist/core/prototype/area/augment-label.js

@@ -0,0 +1,13 @@
+import { capitalize } from '../../../util/string.js';
+/**
+ * An area's label: what the author wrote, else its capitalised slug.
+ *
+ * The area's one own augment, and the mirror of the collection's — which normalises a string or
+ * an object into `{ singular, plural }`, because a collection is named in two numbers and an area
+ * in one. The kind's own statement about itself, so it belongs to the kind rather than to a
+ * shared factory.
+ */
+export const augmentAreaLabel = (config) => ({
+    ...config,
+    label: config.label ? config.label : capitalize(config.slug)
+});

package/dist/core/prototype/area/definition.d.ts

@@ -0,0 +1,18 @@
+import type { BuiltArea } from '../../config/types.js';
+import type { AreaWithoutSlug } from './types.js';
+/**
+ * An area holds exactly one document, so create and delete are off and reads and updates need no
+ * id to say which one they mean.
+ *
+ * The adapter reads `config.type` and builds an `AreaHandle` accordingly —
+ * `adapter-sqlite/area.server.ts`.
+ *
+ * The client half of the pair — what an area *is*. `api`, `rest` and `boot` are server-only and
+ * live in `definition.server.ts`.
+ */
+export declare const area: import("../define.js").PrototypeDefinition<import("../define.js").BuiltPrototype>;
+/**
+ * The public authoring API: `Area.create('settings', {…})`. See the collection's for why the
+ * signature is stated here rather than on the definition.
+ */
+export declare const create: <S extends string>(slug: S, config: AreaWithoutSlug<S>) => BuiltArea;

package/dist/core/prototype/area/definition.js

@@ -0,0 +1,44 @@
+import { augmentMetas } from 'rimecms/core/prototype/shared/metas/module';
+import { augmentTitle } from '../shared/title/augment.js';
+import { augmentUrl } from '../shared/url/augment.js';
+import { hasUrl } from '../shared/url/enabled.js';
+import { augmentVersions } from '../shared/versions/augment.js';
+import { when } from '../when.js';
+import { definePrototype } from '../define.js';
+import { augmentAreaLabel } from './augment-label.js';
+/**
+ * An area holds exactly one document, so create and delete are off and reads and updates need no
+ * id to say which one they mean.
+ *
+ * The adapter reads `config.type` and builds an `AreaHandle` accordingly —
+ * `adapter-sqlite/area.server.ts`.
+ *
+ * The client half of the pair — what an area *is*. `api`, `rest` and `boot` are server-only and
+ * live in `definition.server.ts`.
+ */
+export const area = definePrototype({
+    /** The name it is exported under, and the `type` every area config carries. */
+    name: 'area',
+    /**
+     * Everything that shapes an area config, in the order it runs — which is column order.
+     *
+     * Shorter than a collection's by four: no `auth`, `upload`, `nested` or `thumbnail`. An area is
+     * one document, so there is nothing to sign in as, nothing listing it, and nothing to nest it
+     * in — it simply does not list them. That is what the two lists say that a shared
+     * implementation with a flag could not.
+     */
+    augments: () => [
+        augmentAreaLabel,
+        augmentVersions,
+        when(hasUrl, augmentUrl),
+        augmentTitle,
+        augmentMetas
+    ]
+});
+/**
+ * The public authoring API: `Area.create('settings', {…})`. See the collection's for why the
+ * signature is stated here rather than on the definition.
+ */
+export const create = (slug, config) => 
+// See the collection's for the cast.
+area.create(slug, config);

package/dist/core/prototype/area/definition.server.d.ts

@@ -0,0 +1,9 @@
+import type { BuiltArea } from '../../config/types.js';
+/**
+ * The server half: the same area, plus `rest` and the boot step.
+ *
+ * `boot` is the consequence of `singleton: true`: nothing at runtime may create the row, so it has
+ * to exist before requests arrive. Doing it here keeps writes off the read path, and makes an
+ * area's creation time and locale a property of the config rather than of its first reader.
+ */
+export declare const area: import("../define.js").PrototypeDefinition<BuiltArea>;

package/dist/core/prototype/area/definition.server.js

@@ -0,0 +1,40 @@
+import { definePrototype } from '../define.js';
+import { createBlankDocument } from '../doc.js';
+import { blankVersion } from '../shared/versions/blank.js';
+import { area as base } from './definition.js';
+import { areaHooks } from './hooks.server.js';
+import { rest } from './rest/index.server.js';
+/**
+ * The server half: the same area, plus `rest` and the boot step.
+ *
+ * `boot` is the consequence of `singleton: true`: nothing at runtime may create the row, so it has
+ * to exist before requests arrive. Doing it here keeps writes off the read path, and makes an
+ * area's creation time and locale a property of the config rather than of its first reader.
+ */
+export const area = definePrototype({
+    ...base,
+    rest,
+    /**
+     * The area's own document hooks, listed in `hooks.server.ts` beside this file. On the server
+     * half for the reason the collection's are — a hook typed through `event.locals.rime` cannot sit
+     * where the config factory imports it.
+     */
+    hooks: areaHooks,
+    boot: async ({ config, adapter, defaultLocale }) => {
+        /**
+         * No request event: boot has no request. `createBlankDocument` takes one only to pass to a
+         * field's `defaultValue({ event })`, which already declares it optional — so a default that
+         * reads it gets `undefined` here rather than whichever request arrived first.
+         *
+         * The locale is the config's default for the same reason: the locale of an area's first row
+         * is a property of the config, not of its first reader.
+         */
+        await adapter.area(config.slug).ensureExists({
+            // Intent `'seed'`, not `'create'`: a feature that gives this prototype a versions table may need
+            // the first row to differ from what an author's create starts with. See
+            // FeatureDefinition.blank.
+            blank: blankVersion(createBlankDocument(config), config),
+            locale: defaultLocale
+        });
+    }
+});

package/dist/core/prototype/area/hooks.server.d.ts

@@ -0,0 +1,17 @@
+import type { AnyHook, HookTiming } from '../../pipeline/types.js';
+/**
+ * The area prototype's *own* document hooks — the ones that are its, unconditionally.
+ *
+ * In its own file for the reason the collection's are (see collection/hooks.server.ts): a list of
+ * hooks depends on nothing, so anything can import it without going through `definition.server.ts`
+ * and its module-scope `{ ...base }` spread. The area's config factory needs exactly this list and
+ * the feature list, and reaching them through the server definition is what made the collection
+ * silently lose its feature hooks when an import order changed.
+ *
+ * No create, no delete: a second row is not a thing.
+ *
+ * The order is written, not computed — see the long note in `collection/hooks.server.ts`, which
+ * also says what nothing checks. An area lists fewer features than a collection (no `auth`,
+ * `upload`, `nested` or `thumbnail`), so it places fewer hooks.
+ */
+export declare const areaHooks: Partial<Record<HookTiming, AnyHook[]>>;

package/dist/core/prototype/area/hooks.server.js

@@ -0,0 +1,61 @@
+import { authorize } from '../../pipeline/hooks/authorize.server.js';
+import { buildDataConfigMap } from '../../pipeline/hooks/data-config-map.server.js';
+import { getOriginalDocument } from '../../pipeline/hooks/get-original-document.server.js';
+import { normalizeResolvedReferences } from '../../pipeline/hooks/normalize-resolved-references.server.js';
+import { buildOriginalDocConfigMap } from '../../pipeline/hooks/original-config-map.server.js';
+import { processDocumentFields } from '../../pipeline/hooks/process-document-fields.server.js';
+import { resolveContentOwner } from '../../pipeline/hooks/resolve-content-owner.server.js';
+import { setDefaultValues } from '../../pipeline/hooks/set-default-values.server.js';
+import { setDocumentLocale } from '../../pipeline/hooks/set-document-locale.server.js';
+import { setDocumentType } from '../../pipeline/hooks/set-document-type.server.js';
+import { validateFields } from '../../pipeline/hooks/validate-fields.server.js';
+import * as metas from '../shared/metas/hooks/index.server.js';
+import * as title from '../shared/title/hooks/index.server.js';
+import { hasUrl } from '../shared/url/enabled.js';
+import * as url from '../shared/url/hooks/index.server.js';
+import { isVersioned } from '../shared/versions/enabled.js';
+import * as versions from '../shared/versions/hooks/index.server.js';
+import { when } from '../when.js';
+/**
+ * The area prototype's *own* document hooks — the ones that are its, unconditionally.
+ *
+ * In its own file for the reason the collection's are (see collection/hooks.server.ts): a list of
+ * hooks depends on nothing, so anything can import it without going through `definition.server.ts`
+ * and its module-scope `{ ...base }` spread. The area's config factory needs exactly this list and
+ * the feature list, and reaching them through the server definition is what made the collection
+ * silently lose its feature hooks when an import order changed.
+ *
+ * No create, no delete: a second row is not a thing.
+ *
+ * The order is written, not computed — see the long note in `collection/hooks.server.ts`, which
+ * also says what nothing checks. An area lists fewer features than a collection (no `auth`,
+ * `upload`, `nested` or `thumbnail`), so it places fewer hooks.
+ */
+export const areaHooks = {
+    beforeOperation: [authorize],
+    beforeRead: [
+        processDocumentFields,
+        setDocumentLocale,
+        setDocumentType,
+        when(isVersioned, versions.exposeVersionId),
+        title.setDocumentTitle,
+        // After the title, for the reason the collection's list gives.
+        when(hasUrl, url.populateURL),
+        metas.deletePanelLockMetas
+    ],
+    beforeUpdate: [
+        versions.stripAutoSaveFlag,
+        getOriginalDocument,
+        buildOriginalDocConfigMap,
+        resolveContentOwner,
+        when(isVersioned, versions.defineVersionOperation),
+        when(isVersioned, versions.handleNewVersion),
+        // Between the two, for the reasons the collection's list gives.
+        metas.stampUpdatedBy,
+        buildDataConfigMap,
+        setDefaultValues,
+        normalizeResolvedReferences,
+        validateFields,
+        when(isVersioned, versions.demoteOtherVersions)
+    ]
+};

package/dist/core/prototype/area/index.d.ts

@@ -0,0 +1 @@
+export { area, create } from './definition.js';

package/dist/core/prototype/area/index.js

@@ -0,0 +1 @@
+export { area, create } from './definition.js';

package/dist/core/prototype/area/operations/find.d.ts

@@ -0,0 +1,18 @@
+import type { BuiltArea } from '../../../config/types.js';
+import type { PrototypeApiContext } from '../../define.js';
+import type { GenericDoc } from '../../types.js';
+export type FindArgs = {
+    locale?: string | undefined;
+    depth?: number;
+    select?: string[];
+    versionId?: string;
+    /** The newest version, whatever its status; the published one otherwise. */
+    latest?: boolean;
+    /** See the collection's findById. */
+    localeFallback?: boolean;
+};
+type Args = FindArgs & {
+    ctx: PrototypeApiContext<BuiltArea>;
+};
+export declare const find: <T extends GenericDoc>(args: Args) => Promise<T>;
+export {};

package/dist/core/prototype/area/operations/find.js

@@ -0,0 +1,43 @@
+import { RimeError } from '../../../errors/index.js';
+import { readDocument, runBeforeOperation } from '../../../pipeline/run.server.js';
+export const find = async (args) => {
+    const { ctx, locale, depth, select, versionId, latest, localeFallback } = args;
+    const { config, event, isSystemOperation } = ctx;
+    let context = {
+        params: {
+            locale,
+            depth,
+            select,
+            versionId,
+            latest
+        },
+        isSystemOperation
+    };
+    context = await runBeforeOperation({
+        config,
+        event,
+        operation: 'read',
+        context
+    });
+    // No id: a singleton has exactly one row, and the handle knows it.
+    const documentRaw = await event.locals.rime.adapter.area(config.slug).find({
+        locale,
+        localeFallback,
+        select,
+        // See the collection's findById.
+        content: ctx.versionQuery({ latest, versionId })
+    });
+    if (!documentRaw)
+        throw new RimeError(RimeError.NOT_FOUND);
+    const { doc } = await readDocument({
+        raw: documentRaw,
+        config,
+        event,
+        context,
+        locale,
+        localeFallback,
+        depth,
+        select
+    });
+    return doc;
+};

package/dist/core/prototype/area/operations/update.d.ts

@@ -0,0 +1,29 @@
+import type { BuiltArea } from '../../../config/types.js';
+import type { PrototypeApiContext } from '../../define.js';
+import type { GenericDoc } from '../../types.js';
+import type { DeepPartial } from '../../../../util/types.js';
+export type UpdateArgs<T> = {
+    data: DeepPartial<T>;
+    locale?: string | undefined;
+    versionId?: string;
+    /** Start from the newest version rather than the published one. `PARAMS.LATEST`. */
+    latest?: boolean;
+    /** Make a new version from the selected row rather than write it. `PARAMS.FORK`. */
+    fork?: boolean;
+    /** Write the caller's auto-saved row of the version `versionId` names. Panel only. */
+    autoSave?: boolean;
+    /** This write copies another locale's rows onto the row — see `copyLocales`. */
+    isLocaleCopy?: boolean;
+};
+type Args<T> = UpdateArgs<T> & {
+    ctx: PrototypeApiContext<BuiltArea>;
+};
+/**
+ * Updates an area's single document.
+ *
+ * The pipeline itself lives in operations/run.server.ts — shared with a collection's
+ * updateById. Only the two prototype-specific pieces are here: which adapter method writes the
+ * root row, and how the saved document is read back.
+ */
+export declare const update: <T extends GenericDoc = GenericDoc>(args: Args<T>) => Promise<T>;
+export {};