rimecms 0.31.5 → 0.32.1

package/dist/core/prototype/index.js

@@ -0,0 +1,14 @@
+/**
+ * The two prototypes, isomorphic halves.
+ *
+ * There was a registry here — `prototypeNames`, `protos`, `prototypes`, plus folds over them. It
+ * bought core the ability never to write the words `collection` and `area`, and it cost the folder
+ * its entry point: three exports that were three views of the same two objects, and callers that
+ * merged both lists only to split them apart again further down.
+ *
+ * The server halves are **not** re-exported here. They carry `api`, `rest` and `boot`, they are
+ * different objects under the same two names, and a caller that needs one names
+ * `collection/definition.server.js` — the path says which half, where the name could not.
+ */
+export { collection } from './collection/index.js';
+export { area } from './area/index.js';

package/dist/core/prototype/naming.d.ts

@@ -0,0 +1,22 @@
+/**
+ * A prototype slug's URL form.
+ *
+ * One canonical slug produces every other representation by pure transform, so nothing here
+ * knows what any particular marker means:
+ *
+ *   pages               ->  pages
+ *   someSlug            ->  some-slug
+ *   $someSlug__versions ->  some-slug--versions
+ *   $someSlugDirectories->  some-slug-directories
+ *
+ * The `$` is dropped — it marks a slug as rime-derived for config authors, and has no business
+ * in a URL. The `__` becomes `--`, keeping a segment boundary visible and distinct from the
+ * word breaks around it.
+ *
+ * This replaced a `prototypeKebabToSlug` that matched `/(_(?:directories|versions))$/` — core
+ * hardcoding two features' suffixes. Going the other way is now a lookup against the config
+ * rather than an inverse transform (see handlers/routes.server.ts), which is both exact and
+ * feature-agnostic: `medias-directories` cannot be reversed by rule, since it is indistinguishable
+ * from a user collection named `mediasDirectories`.
+ */
+export declare const prototypeKebab: (slug: string) => string;

package/dist/core/prototype/naming.js

@@ -0,0 +1,23 @@
+import { mapSegments, toKebabCase } from '../../util/string.js';
+/**
+ * A prototype slug's URL form.
+ *
+ * One canonical slug produces every other representation by pure transform, so nothing here
+ * knows what any particular marker means:
+ *
+ *   pages               ->  pages
+ *   someSlug            ->  some-slug
+ *   $someSlug__versions ->  some-slug--versions
+ *   $someSlugDirectories->  some-slug-directories
+ *
+ * The `$` is dropped — it marks a slug as rime-derived for config authors, and has no business
+ * in a URL. The `__` becomes `--`, keeping a segment boundary visible and distinct from the
+ * word breaks around it.
+ *
+ * This replaced a `prototypeKebabToSlug` that matched `/(_(?:directories|versions))$/` — core
+ * hardcoding two features' suffixes. Going the other way is now a lookup against the config
+ * rather than an inverse transform (see handlers/routes.server.ts), which is both exact and
+ * feature-agnostic: `medias-directories` cannot be reversed by rule, since it is indistinguishable
+ * from a user collection named `mediasDirectories`.
+ */
+export const prototypeKebab = (slug) => mapSegments(slug.replace(/^\$/, ''), toKebabCase, '--');

package/dist/core/prototype/shared/metas/constant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * How long a claim on a document stays good without being renewed.
+ *
+ * The lock stops two people overwriting each other; it does not reserve a document. Nothing
+ * releases a claim when an editor walks away, so the expiry is what keeps an abandoned one from
+ * stranding the document behind whoever opened it.
+ */
+export declare const EDIT_LOCK_TTL_MS: number;
+/**
+ * How long a claim survives the tab going away.
+ *
+ * A release is a short lease, not a hand-back: a refresh unloads the page and reclaims it a
+ * moment later, and clearing the claim outright leaves a window where another tab's renewal
+ * takes the document from someone who never left.
+ */
+export declare const EDIT_LOCK_TTL_AFTER_CLOSE_MS: number;

package/dist/core/prototype/shared/metas/constant.js

@@ -0,0 +1,16 @@
+/**
+ * How long a claim on a document stays good without being renewed.
+ *
+ * The lock stops two people overwriting each other; it does not reserve a document. Nothing
+ * releases a claim when an editor walks away, so the expiry is what keeps an abandoned one from
+ * stranding the document behind whoever opened it.
+ */
+export const EDIT_LOCK_TTL_MS = 5 * 60 * 1000;
+/**
+ * How long a claim survives the tab going away.
+ *
+ * A release is a short lease, not a hand-back: a refresh unloads the page and reclaims it a
+ * moment later, and clearing the claim outright leaves a window where another tab's renewal
+ * takes the document from someone who never left.
+ */
+export const EDIT_LOCK_TTL_AFTER_CLOSE_MS = 10 * 1000;

package/dist/core/prototype/shared/metas/fields.d.ts

@@ -0,0 +1,8 @@
+export declare const metasFields: {
+    currentlyEditedBy: () => import("../../../../fields/text/index.js").TextFieldBuilder;
+    currentlyEditedAt: () => import("../../../../fields/date/index.js").DateFieldBuilder;
+    createdBy: () => import("../../../../fields/text/index.js").TextFieldBuilder;
+    createdAt: () => import("../../../../fields/date/index.js").DateFieldBuilder;
+    updatedBy: () => import("../../../../fields/text/index.js").TextFieldBuilder;
+    updatedAt: () => import("../../../../fields/date/index.js").DateFieldBuilder;
+};

package/dist/core/prototype/shared/metas/fields.js

@@ -0,0 +1,27 @@
+import { isStaff } from '../../../auth/access.js';
+import { date } from '../../../../fields/date/index.js';
+import { text } from '../../../../fields/text/index.js';
+/**
+ * The metas fields, declared once for both halves of the module.
+ *
+ * Factories, not instances: a builder is mutable and ends up on one config's field list, so the
+ * two halves share the declaration rather than the object. `module.server.ts` calls the same
+ * factories and adds the foreign key to `staff` on the three id columns.
+ */
+/**
+ * Who wrote a document and who is holding it open are staff business. Said on the field, so the
+ * pipeline enforces it for every caller — `processDocumentFields` drops what a reader may not
+ * see, `validateFields` drops what a writer may not set — rather than each read path remembering.
+ */
+const staffOnly = {
+    read: (user) => isStaff(user),
+    update: (user) => isStaff(user)
+};
+export const metasFields = {
+    currentlyEditedBy: () => text('currentlyEditedBy').hidden().access(staffOnly),
+    currentlyEditedAt: () => date('currentlyEditedAt').hidden().access(staffOnly),
+    createdBy: () => text('createdBy').hidden().$root().access(staffOnly),
+    createdAt: () => date('createdAt').hidden(),
+    updatedBy: () => text('updatedBy').hidden().access(staffOnly),
+    updatedAt: () => date('updatedAt').hidden()
+};

package/dist/core/prototype/shared/metas/hooks/delete-panel-lock-metas.server.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Drops the edit lock from every read that is not a panel read.
+ *
+ * The fields already carry `.access({ read: isStaff })`, which answers "who may see a lock" —
+ * a different question from "where does a lock mean anything". It only means something in the
+ * panel, and a staff member reading through the API is still staff, so the field access alone
+ * would hand them a lock they cannot act on.
+ */
+export declare const deletePanelLockMetas: import("../../../../pipeline/types").Hook<"raw", "read", "before">;

package/dist/core/prototype/shared/metas/hooks/delete-panel-lock-metas.server.js

@@ -0,0 +1,20 @@
+import { Hooks } from '../../../../pipeline/define-hook.js';
+/**
+ * Drops the edit lock from every read that is not a panel read.
+ *
+ * The fields already carry `.access({ read: isStaff })`, which answers "who may see a lock" —
+ * a different question from "where does a lock mean anything". It only means something in the
+ * panel, and a staff member reading through the API is still staff, so the field access alone
+ * would hand them a lock they cannot act on.
+ */
+export const deletePanelLockMetas = Hooks.beforeRead(async (args) => {
+    const { rime } = args.event.locals;
+    if (args.context.isSystemOperation)
+        return args;
+    if (rime.routes.isPanel)
+        return args;
+    const doc = args.doc;
+    delete doc.currentlyEditedBy;
+    delete doc.currentlyEditedAt;
+    return { ...args, doc };
+});

package/dist/core/prototype/shared/metas/hooks/index.server.d.ts

@@ -0,0 +1,7 @@
+/**
+ * This feature's hooks, by name, so a prototype can place them as `metas.someHook`.
+ *
+ * A barrel and nothing else — see the note on `title/hooks/index.server.ts`.
+ */
+export { deletePanelLockMetas } from './delete-panel-lock-metas.server.js';
+export { stampCreatedBy, stampUpdatedBy } from './stamp-authorship.server.js';

package/dist/core/prototype/shared/metas/hooks/index.server.js

@@ -0,0 +1,7 @@
+/**
+ * This feature's hooks, by name, so a prototype can place them as `metas.someHook`.
+ *
+ * A barrel and nothing else — see the note on `title/hooks/index.server.ts`.
+ */
+export { deletePanelLockMetas } from './delete-panel-lock-metas.server.js';
+export { stampCreatedBy, stampUpdatedBy } from './stamp-authorship.server.js';

package/dist/core/prototype/shared/metas/hooks/stamp-authorship.server.d.ts

@@ -0,0 +1,2 @@
+export declare const stampCreatedBy: import("../../../../pipeline/types").Hook<"raw", "create", "before">;
+export declare const stampUpdatedBy: import("../../../../pipeline/types").Hook<"raw", "update", "before">;

package/dist/core/prototype/shared/metas/hooks/stamp-authorship.server.js

@@ -0,0 +1,27 @@
+import { Hooks } from '../../../../pipeline/define-hook.js';
+/**
+ * Records who made a document, and who last wrote to it.
+ *
+ * Two hooks rather than one `beforeUpsert`, because they do not write the same fields: a create
+ * answers both questions at once, an update only the second. `createdBy` is never rewritten —
+ * that is the whole difference between it and `updatedBy`.
+ *
+ * **Both stand down without a user, and on a system operation.** Rime writes as itself when it
+ * bootstraps a singleton, propagates a document into the other locales, or migrates. None of
+ * those is somebody editing, and stamping them would name whoever's request happened to trigger
+ * the work as the author of documents they never touched.
+ */
+/** Who is writing, when that is a person and not rime itself. */
+const editor = (args) => (args.context.isSystemOperation ? undefined : args.event.locals.user?.id);
+export const stampCreatedBy = Hooks.beforeCreate(async function stampCreatedBy(args) {
+    const by = editor(args);
+    if (!by)
+        return args;
+    return { ...args, data: { ...args.data, createdBy: by, updatedBy: by } };
+});
+export const stampUpdatedBy = Hooks.beforeUpdate(async function stampUpdatedBy(args) {
+    const by = editor(args);
+    if (!by)
+        return args;
+    return { ...args, data: { ...args.data, updatedBy: by } };
+});

package/dist/core/prototype/shared/metas/lock.d.ts

@@ -0,0 +1,15 @@
+import type { GenericDoc } from '../../types.js';
+/**
+ * Reading a claim. Pure, and in the isomorphic half on purpose: the server decides whether to
+ * grant a claim and the panel decides whether to draw the overlay, and the two have to agree on
+ * what "held" means.
+ */
+/** A claim older than the TTL says nothing: whoever made it is not coming back. */
+export declare const isLockStale: (at: unknown, now?: number) => boolean;
+/**
+ * The id a claim names. A read hands the holder back joined, `{ id, name, email }`; a write and
+ * an older row carry the bare id.
+ */
+export declare const lockHolderId: (doc: Partial<GenericDoc>) => string | null;
+/** Somebody other than `userId` is in this document, recently enough to still mean it. */
+export declare const isLockHeldByOther: (doc: Partial<GenericDoc>, userId: string, now?: number) => boolean;

package/dist/core/prototype/shared/metas/lock.js

@@ -0,0 +1,30 @@
+import { EDIT_LOCK_TTL_MS } from './constant.js';
+/**
+ * Reading a claim. Pure, and in the isomorphic half on purpose: the server decides whether to
+ * grant a claim and the panel decides whether to draw the overlay, and the two have to agree on
+ * what "held" means.
+ */
+/** A claim older than the TTL says nothing: whoever made it is not coming back. */
+export const isLockStale = (at, now = Date.now()) => {
+    if (!at)
+        return true;
+    const since = at instanceof Date ? at.getTime() : new Date(at).getTime();
+    return Number.isNaN(since) || now - since >= EDIT_LOCK_TTL_MS;
+};
+/**
+ * The id a claim names. A read hands the holder back joined, `{ id, name, email }`; a write and
+ * an older row carry the bare id.
+ */
+export const lockHolderId = (doc) => {
+    const by = doc.currentlyEditedBy;
+    if (typeof by === 'string')
+        return by;
+    if (by && typeof by === 'object' && typeof by.id === 'string')
+        return by.id;
+    return null;
+};
+/** Somebody other than `userId` is in this document, recently enough to still mean it. */
+export const isLockHeldByOther = (doc, userId, now = Date.now()) => {
+    const by = lockHolderId(doc);
+    return !!by && by !== userId && !isLockStale(doc.currentlyEditedAt, now);
+};

package/dist/core/prototype/shared/metas/lock.server.d.ts

@@ -0,0 +1,46 @@
+import type { BuiltArea, BuiltCollection } from '../../../config/types.js';
+import type { GenericDoc } from '../../types.js';
+import type { RequestEvent } from '@sveltejs/kit';
+type LockArgs = {
+    event: RequestEvent;
+    config: BuiltCollection | BuiltArea;
+    /** The document being edited. Its `versionId`, when it has one, is the row the claim sits on. */
+    doc: Partial<GenericDoc>;
+    userId: string;
+};
+/**
+ * Take the document, unless somebody else holds it.
+ *
+ * Also the renewal: a claim we already hold is rewritten with a fresh timestamp, which is what
+ * keeps a lock alive while its holder is still in the document. Answers whether the caller holds
+ * it afterwards.
+ *
+ * `force` takes it regardless — the *Take control* button, which exists to get past a claim
+ * somebody walked away from before it ages out.
+ */
+export declare const claimEditLock: (args: LockArgs & {
+    force?: boolean;
+}) => Promise<boolean>;
+/**
+ * Give the document back, if it is ours to give — as a short lease rather than a hand-back.
+ *
+ * The claim keeps our name and is back-dated to expire in `EDIT_LOCK_TTL_AFTER_CLOSE_MS`, so a
+ * refresh has time to reclaim it. Clearing it outright is what let another tab's renewal take the
+ * document from someone who only reloaded.
+ *
+ * The `doc` guard matters: a release racing somebody else's claim would otherwise hand them a
+ * document with no lock on it a moment after they took it.
+ */
+export declare const releaseEditLock: (args: LockArgs) => Promise<boolean>;
+/**
+ * Carry a claim onto the row just made from the one it sits on.
+ *
+ * An auto-save or a fork continues the same edit on a new row. Made by the holder, the new row
+ * is theirs from the first moment: the claim is cleared on `doc` and stamped on `to`, and the
+ * client keeps renewing whatever row its form is on. Nothing moves when `doc` is held by somebody
+ * else, by nobody, or by a claim that has aged out.
+ */
+export declare const moveEditLock: (args: LockArgs & {
+    to: Partial<GenericDoc>;
+}) => Promise<boolean>;
+export {};

package/dist/core/prototype/shared/metas/lock.server.js

@@ -0,0 +1,91 @@
+import { logger } from '../../../logger.server.js';
+import { EDIT_LOCK_TTL_AFTER_CLOSE_MS, EDIT_LOCK_TTL_MS } from './constant.js';
+import { isLockHeldByOther, isLockStale, lockHolderId } from './lock.js';
+/**
+ * Write the lock fields and nothing else, on the row being edited.
+ *
+ * **Which row.** The lock is not `$root()`, so on a versioned config it lives with the content —
+ * one claim per revision. Two people on two different versions are not editing the same thing, and
+ * locking one must not lock the other. Where there are no versions there is one row and this
+ * resolves to it.
+ *
+ * **`updateWhere` rather than `update`**: a table, a filter and a patch, writing exactly the
+ * columns it is given. Opening a document is not editing it, so the write leaves `updatedAt` where
+ * it is and never runs the pipeline — which would stamp `updatedBy` and cut a revision whose only
+ * change is who is looking at it.
+ */
+const writeLock = async (args, data) => {
+    const { event, config, doc } = args;
+    const { rime } = event.locals;
+    const versionsSlug = config._versions?.slug;
+    // A versioned config keeps these columns on its versions table and nowhere else — they are not
+    // `$root()`. Writing to the base row would target columns that table does not have, so a
+    // versioned document with no `versionId` is a caller bug, not a row to guess at.
+    if (versionsSlug && !doc.versionId) {
+        logger.warn(`edit lock on ${config.slug}: versioned document with no versionId, ignored`);
+        return;
+    }
+    const id = versionsSlug ? doc.versionId : doc.id;
+    await rime.adapter.contentOwner(config.slug).updateWhere({
+        query: `where[id][equals]=${id}`,
+        data
+    });
+    // Tell whoever else has the document open, so they reload — for the overlay, and for the
+    // content, which the holder has usually just changed. Only when the lock actually changed
+    // hands: a claim is also the renewal, and those would reach every client twice a TTL.
+    if (lockHolderId(doc) !== data.currentlyEditedBy) {
+        // Keyed on the document's own id, not the version row's — it is what the panel subscribed to.
+        rime.sse.emit(`rime:${config.slug}:${doc.id}`, 'rime:lock');
+    }
+};
+/**
+ * Take the document, unless somebody else holds it.
+ *
+ * Also the renewal: a claim we already hold is rewritten with a fresh timestamp, which is what
+ * keeps a lock alive while its holder is still in the document. Answers whether the caller holds
+ * it afterwards.
+ *
+ * `force` takes it regardless — the *Take control* button, which exists to get past a claim
+ * somebody walked away from before it ages out.
+ */
+export const claimEditLock = async (args) => {
+    if (!args.force && isLockHeldByOther(args.doc, args.userId))
+        return false;
+    await writeLock(args, { currentlyEditedBy: args.userId, currentlyEditedAt: new Date() });
+    return true;
+};
+/**
+ * Give the document back, if it is ours to give — as a short lease rather than a hand-back.
+ *
+ * The claim keeps our name and is back-dated to expire in `EDIT_LOCK_TTL_AFTER_CLOSE_MS`, so a
+ * refresh has time to reclaim it. Clearing it outright is what let another tab's renewal take the
+ * document from someone who only reloaded.
+ *
+ * The `doc` guard matters: a release racing somebody else's claim would otherwise hand them a
+ * document with no lock on it a moment after they took it.
+ */
+export const releaseEditLock = async (args) => {
+    if (lockHolderId(args.doc) !== args.userId)
+        return false;
+    await writeLock(args, {
+        currentlyEditedBy: args.userId,
+        currentlyEditedAt: new Date(Date.now() - EDIT_LOCK_TTL_MS + EDIT_LOCK_TTL_AFTER_CLOSE_MS)
+    });
+    return true;
+};
+/**
+ * Carry a claim onto the row just made from the one it sits on.
+ *
+ * An auto-save or a fork continues the same edit on a new row. Made by the holder, the new row
+ * is theirs from the first moment: the claim is cleared on `doc` and stamped on `to`, and the
+ * client keeps renewing whatever row its form is on. Nothing moves when `doc` is held by somebody
+ * else, by nobody, or by a claim that has aged out.
+ */
+export const moveEditLock = async (args) => {
+    const { doc, to, userId } = args;
+    if (lockHolderId(doc) !== userId || isLockStale(doc.currentlyEditedAt))
+        return false;
+    await writeLock(args, { currentlyEditedBy: null, currentlyEditedAt: null });
+    await writeLock({ ...args, doc: to }, { currentlyEditedBy: userId, currentlyEditedAt: new Date() });
+    return true;
+};

package/dist/core/prototype/shared/metas/module.d.ts

@@ -0,0 +1,38 @@
+import type { Collection } from '../../../config/types.js';
+type Input = {
+    fields?: Collection<any>['fields'];
+};
+/**
+ * The bookkeeping every document carries: when it was written, and by whom.
+ *
+ * Three separate questions about who, because each has its own lifetime — one is written once,
+ * one on every write, and one is ephemeral:
+ *
+ * - `createdBy` — who made *the document*. One answer, whatever its revision history.
+ * - `updatedBy` — who wrote *this revision*.
+ * - `currentlyEditedBy` / `currentlyEditedAt` — who holds the document open, and since when.
+ *
+ * **Which of them are `$root()`.** On a versioned config the schema generator sends `$root()`
+ * fields to the base row and everything else to the versions table
+ * (`adapter-sqlite/generate-schema/index.server.ts`), so each lands where the question it answers
+ * belongs. `createdBy` is a property of the document — one answer per document, whatever its
+ * revisions — so it sits on the base row. `updatedBy` and the lock are properties of a *revision*:
+ * two people on two different versions are not editing the same thing, so locking one must not
+ * lock the other.
+ *
+ * **Text columns, read back as the staff member.** Each of the three ids is a `text` column the
+ * server half marks `$references('staff', { resolve: true })`: the adapter joins the target on
+ * read, so the document carries `{ id, name, email }` on the same key and the panel has a name to
+ * show. A write takes that object or the id. A text column is also what can be `$root()`, which
+ * a relation field cannot.
+ *
+ * **The lock is staff-only, said on the field.** `.access({ read, update })` is enforced by the
+ * pipeline for every caller — `processDocumentFields` drops what a reader may not see,
+ * `validateFields` drops what a writer may not set — so who can see and claim a lock is one
+ * declaration here rather than a rule each read path has to remember.
+ *
+ * The client half. `module.server.ts` adds the reference to `staff` on the three id columns,
+ * which is what decides what happens to a document whose author is deleted.
+ */
+export declare const augmentMetas: <T extends Input>(config: T) => T;
+export {};

package/dist/core/prototype/shared/metas/module.js

@@ -0,0 +1,38 @@
+import { metasFields } from './fields.js';
+/**
+ * The bookkeeping every document carries: when it was written, and by whom.
+ *
+ * Three separate questions about who, because each has its own lifetime — one is written once,
+ * one on every write, and one is ephemeral:
+ *
+ * - `createdBy` — who made *the document*. One answer, whatever its revision history.
+ * - `updatedBy` — who wrote *this revision*.
+ * - `currentlyEditedBy` / `currentlyEditedAt` — who holds the document open, and since when.
+ *
+ * **Which of them are `$root()`.** On a versioned config the schema generator sends `$root()`
+ * fields to the base row and everything else to the versions table
+ * (`adapter-sqlite/generate-schema/index.server.ts`), so each lands where the question it answers
+ * belongs. `createdBy` is a property of the document — one answer per document, whatever its
+ * revisions — so it sits on the base row. `updatedBy` and the lock are properties of a *revision*:
+ * two people on two different versions are not editing the same thing, so locking one must not
+ * lock the other.
+ *
+ * **Text columns, read back as the staff member.** Each of the three ids is a `text` column the
+ * server half marks `$references('staff', { resolve: true })`: the adapter joins the target on
+ * read, so the document carries `{ id, name, email }` on the same key and the panel has a name to
+ * show. A write takes that object or the id. A text column is also what can be `$root()`, which
+ * a relation field cannot.
+ *
+ * **The lock is staff-only, said on the field.** `.access({ read, update })` is enforced by the
+ * pipeline for every caller — `processDocumentFields` drops what a reader may not see,
+ * `validateFields` drops what a writer may not set — so who can see and claim a lock is one
+ * declaration here rather than a rule each read path has to remember.
+ *
+ * The client half. `module.server.ts` adds the reference to `staff` on the three id columns,
+ * which is what decides what happens to a document whose author is deleted.
+ */
+export const augmentMetas = (config) => {
+    const fields = [...(config.fields || [])];
+    fields.push(metasFields.createdBy(), metasFields.updatedBy(), metasFields.currentlyEditedBy(), metasFields.currentlyEditedAt(), metasFields.createdAt(), metasFields.updatedAt());
+    return { ...config, fields };
+};

package/dist/core/prototype/shared/metas/module.server.d.ts

@@ -0,0 +1,30 @@
+import type { Collection } from '../../../config/types.js';
+type Input = {
+    slug?: string;
+    fields?: Collection<any>['fields'];
+};
+/**
+ * The metas' server half: the same fields, carrying a foreign key to `staff`.
+ *
+ * **A column with a reference, not a relation field.** A `relation('createdBy').to('staff')` would
+ * store the id in the junction table, one row per document per field — so the answer to "who made
+ * this" would not be visible beside the document in any database view, and reading it would cost a
+ * join the panel's list does per row. A `text` column with `$references` puts the id in the row
+ * itself and still gets referential integrity out of the database.
+ *
+ * **`resolve: true` is what puts a name in the panel.** The adapter joins the staff member on
+ * read and the document carries `{ id, name, email }` where the id column is; the pipeline
+ * writes the id back.
+ *
+ * **`onDelete: 'set null'` is the policy for a deleted user**, and it is the reason this half
+ * exists at all. Without a reference, deleting a staff member leaves their id behind on every
+ * document they touched, pointing at nothing — the panel renders a dash and the database cannot
+ * tell you the row is stale. `set null` says it plainly: the documents outlive their author and
+ * lose the attribution. A config where documents genuinely should not outlive their owner wants
+ * `cascade` instead, and that is a one-word change here rather than a cleanup job.
+ *
+ * The reference has to be on the builder at construction, which is why this is written out rather
+ * than wrapping the client half — the same reason `nested/module.server.ts` is.
+ */
+export declare const augmentMetas: <T extends Input>(config: T) => T;
+export {};

package/dist/core/prototype/shared/metas/module.server.js

@@ -0,0 +1,38 @@
+import { STAFF_SLUG } from '../../../auth/tables.js';
+import { metasFields } from './fields.js';
+/**
+ * The metas' server half: the same fields, carrying a foreign key to `staff`.
+ *
+ * **A column with a reference, not a relation field.** A `relation('createdBy').to('staff')` would
+ * store the id in the junction table, one row per document per field — so the answer to "who made
+ * this" would not be visible beside the document in any database view, and reading it would cost a
+ * join the panel's list does per row. A `text` column with `$references` puts the id in the row
+ * itself and still gets referential integrity out of the database.
+ *
+ * **`resolve: true` is what puts a name in the panel.** The adapter joins the staff member on
+ * read and the document carries `{ id, name, email }` where the id column is; the pipeline
+ * writes the id back.
+ *
+ * **`onDelete: 'set null'` is the policy for a deleted user**, and it is the reason this half
+ * exists at all. Without a reference, deleting a staff member leaves their id behind on every
+ * document they touched, pointing at nothing — the panel renders a dash and the database cannot
+ * tell you the row is stale. `set null` says it plainly: the documents outlive their author and
+ * lose the attribution. A config where documents genuinely should not outlive their owner wants
+ * `cascade` instead, and that is a one-word change here rather than a cleanup job.
+ *
+ * The reference has to be on the builder at construction, which is why this is written out rather
+ * than wrapping the client half — the same reason `nested/module.server.ts` is.
+ */
+export const augmentMetas = (config) => {
+    const fields = [...(config.fields || [])];
+    // The staff collection's own metas cannot reference the table they sit on without a
+    // self-referencing accessor; it is also the one collection where "who made this user" is
+    // answered by the bootstrap rather than a person.
+    const staffRef = (field) => field.$references(STAFF_SLUG, {
+        onDelete: 'set null',
+        resolve: true,
+        selfReferencing: config.slug === STAFF_SLUG
+    });
+    fields.push(staffRef(metasFields.createdBy()), staffRef(metasFields.updatedBy()), staffRef(metasFields.currentlyEditedBy()), metasFields.currentlyEditedAt(), metasFields.createdAt(), metasFields.updatedAt());
+    return { ...config, fields };
+};

package/dist/core/prototype/shared/title/augment.d.ts

@@ -0,0 +1,27 @@
+import type { Collection } from '../../../config/types.js';
+type Input = {
+    fields?: Collection<any>['fields'];
+    /**
+     * The prototype's fallback, as any feature before this one left it.
+     *
+     * Required, not optional: this augment has no default of its own, so a config reaching it
+     * without one is a prototype that failed to seed it rather than a document with no name.
+     */
+    _titleFallback: string;
+};
+type WithAsTitle<T> = T & {
+    asTitle: string;
+};
+/**
+ * Resolves `asTitle`: the field that stands in for a document wherever one is listed.
+ *
+ * **It names no feature, and it owns no default.** The prototype seeds `_titleFallback` with what
+ * its documents are called; a feature that knows better overrides it (auth with `email`, upload
+ * with `filename`); this reads whatever is left.
+ *
+ * The precedence: a field marked as the title wins, then the last override, then the prototype's
+ * own fallback. "Last override" is registry order — upload comes after auth, so upload wins for a
+ * config carrying both.
+ */
+export declare const augmentTitle: <T extends Input>(config: T) => WithAsTitle<T>;
+export {};

package/dist/core/prototype/shared/title/augment.js

@@ -0,0 +1,19 @@
+import { findTitleField } from './find-title.js';
+/**
+ * Resolves `asTitle`: the field that stands in for a document wherever one is listed.
+ *
+ * **It names no feature, and it owns no default.** The prototype seeds `_titleFallback` with what
+ * its documents are called; a feature that knows better overrides it (auth with `email`, upload
+ * with `filename`); this reads whatever is left.
+ *
+ * The precedence: a field marked as the title wins, then the last override, then the prototype's
+ * own fallback. "Last override" is registry order — upload comes after auth, so upload wins for a
+ * config carrying both.
+ */
+export const augmentTitle = (config) => {
+    const titleField = findTitleField(config.fields);
+    return {
+        ...config,
+        asTitle: titleField?.path ?? config._titleFallback
+    };
+};

package/dist/core/prototype/shared/title/find-title.d.ts

@@ -0,0 +1,14 @@
+import type { FieldBuilder } from '../../../fields/builders/field-builder.js';
+import { FormFieldBuilder } from '../../../fields/builders/form-field-builder.js';
+import type { DateField } from '../../../../fields/date/index.js';
+import type { EmailField } from '../../../../fields/email/index.js';
+import type { SlugField } from '../../../../fields/slug/index.js';
+import type { TextField } from '../../../../fields/text/index.js';
+import type { Field, FormField, RichTextField } from '../../../../fields/types.js';
+export declare const hasMaybeTitle: (field: Field) => field is TextField | DateField | SlugField | EmailField | RichTextField;
+interface TitleFieldResult {
+    field: FormFieldBuilder<FormField>;
+    path: string;
+}
+export declare function findTitleField(fields?: FieldBuilder<Field>[], basePath?: string): TitleFieldResult | null;
+export {};