@aphexcms/cms-core 7.0.0 → 8.0.0

package/dist/lib/utils/preview.js

@@ -32,25 +32,49 @@ function toPreviewString(value) {
  * — the first non-empty string wins.
  */
 const DEFAULT_TITLE_FIELDS = ['title', 'heading', 'name', 'label'];
+/**
+ * Run `preview.prepare` if defined: resolve every dot-path in `select`,
+ * pass the resolved selection map to `prepare`, and return the result.
+ * Returns `null` when no `prepare` is configured — callers should fall
+ * back to direct `select.title` / `select.subtitle` reads in that case.
+ */
+function runPrepare(item, schema) {
+    const prepare = schema?.preview?.prepare;
+    if (!prepare)
+        return null;
+    const select = schema?.preview?.select ?? {};
+    const selection = {};
+    for (const [key, path] of Object.entries(select)) {
+        selection[key] = readPath(item, path);
+    }
+    return prepare(selection);
+}
 /**
  * Resolve the title to display for an item (array row, document list row,
- * reference picker row). Honors `schema.preview.select.title` first
- * (with dot-path support), then falls back to the conventional field
- * names, then the schema's own title, then the type name.
+ * reference picker row). Precedence: `preview.prepare()` → `select.title`
+ * dot-path → conventional field names → schema title → type name.
  */
 export function resolvePreviewTitle(item, schema, defaultTypeLabel) {
-    const configured = schema?.preview?.select?.title;
-    if (configured) {
-        const resolved = toPreviewString(readPath(item, configured));
+    const prepared = runPrepare(item, schema);
+    if (prepared) {
+        const resolved = toPreviewString(prepared.title);
         if (resolved)
             return resolved;
     }
     else {
-        for (const name of DEFAULT_TITLE_FIELDS) {
-            const resolved = toPreviewString(item?.[name]);
+        const configured = schema?.preview?.select?.title;
+        if (configured) {
+            const resolved = toPreviewString(readPath(item, configured));
             if (resolved)
                 return resolved;
         }
+        else {
+            for (const name of DEFAULT_TITLE_FIELDS) {
+                const resolved = toPreviewString(item?.[name]);
+                if (resolved)
+                    return resolved;
+            }
+        }
     }
     return schema?.title ?? defaultTypeLabel ?? 'Untitled';
 }
@@ -60,6 +84,9 @@ export function resolvePreviewTitle(item, schema, defaultTypeLabel) {
  * should branch on the null and skip rendering the subtitle line.
  */
 export function resolvePreviewSubtitle(item, schema) {
+    const prepared = runPrepare(item, schema);
+    if (prepared)
+        return toPreviewString(prepared.subtitle);
     const configured = schema?.preview?.select?.subtitle;
     if (!configured)
         return null;

package/dist/lib/utils/preview.js.map

@@ -1 +1 @@
-{"version":3,"file":"preview.js","sourceRoot":"","sources":["../../../src/lib/utils/preview.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,QAAQ,CAAC,IAAS,EAAE,IAAY;IAC/C,IAAI,OAAO,GAAQ,IAAI,CAAC;IACxB,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,CAAC;QACvC,IAAI,OAAO,IAAI,IAAI;YAAE,OAAO,SAAS,CAAC;QACtC,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5B,CAAC;IACD,OAAO,OAAO,CAAC;AAChB,CAAC;AAED;;;GAGG;AACH,SAAS,eAAe,CAAC,KAAc;IACtC,IAAI,OAAO,KAAK,KAAK,QAAQ,EAAE,CAAC;QAC/B,MAAM,OAAO,GAAG,KAAK,CAAC,IAAI,EAAE,CAAC;QAC7B,OAAO,OAAO,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,IAAI,CAAC;IACjC,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;IAC9E,IAAI,OAAO,KAAK,KAAK,SAAS;QAAE,OAAO,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,CAAC;IAChE,OAAO,IAAI,CAAC;AACb,CAAC;AAED;;;;GAIG;AACH,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,UAAU,mBAAmB,CAClC,IAAS,EACT,MAAqC,EACrC,gBAAyB;IAEzB,MAAM,UAAU,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC;IAClD,IAAI,UAAU,EAAE,CAAC;QAChB,MAAM,QAAQ,GAAG,eAAe,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;QAC7D,IAAI,QAAQ;YAAE,OAAO,QAAQ,CAAC;IAC/B,CAAC;SAAM,CAAC;QACP,KAAK,MAAM,IAAI,IAAI,oBAAoB,EAAE,CAAC;YACzC,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;YAC/C,IAAI,QAAQ;gBAAE,OAAO,QAAQ,CAAC;QAC/B,CAAC;IACF,CAAC;IACD,OAAO,MAAM,EAAE,KAAK,IAAI,gBAAgB,IAAI,UAAU,CAAC;AACxD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,sBAAsB,CACrC,IAAS,EACT,MAAqC;IAErC,MAAM,UAAU,GAAG,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,CAAC;IACrD,IAAI,CAAC,UAAU;QAAE,OAAO,IAAI,CAAC;IAC7B,OAAO,eAAe,CAAC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;AACpD,CAAC"}
+{"version":3,"file":"preview.js","sourceRoot":"","sources":["../../../src/lib/utils/preview.ts"],"names":[],"mappings":"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"}

package/dist/lib/utils/reference-walk.d.ts

@@ -0,0 +1,8 @@
+import type { SchemaType } from '../types/schemas.js';
+/**
+ * Collect all referenced document IDs from a doc's data. The `schema` and
+ * `registry` params are accepted for API compatibility but no longer used —
+ * the unified ref shape makes them unnecessary.
+ */
+export declare function collectReferenceIds(data: unknown, _schema?: SchemaType | null, _registry?: SchemaType[]): string[];
+//# sourceMappingURL=reference-walk.d.ts.map

package/dist/lib/utils/reference-walk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-walk.d.ts","sourceRoot":"","sources":["../../../src/lib/utils/reference-walk.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD;;;;GAIG;AACH,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,OAAO,EACb,OAAO,CAAC,EAAE,UAAU,GAAG,IAAI,EAC3B,SAAS,CAAC,EAAE,UAAU,EAAE,GACtB,MAAM,EAAE,CAIV"}

package/dist/lib/utils/reference-walk.js

@@ -0,0 +1,39 @@
+// Walks a document's data and collects every reference's target ID. Both
+// singular and array refs share the same on-disk shape now —
+// `{ _type: 'reference', _ref }` — so this can be schema-less.
+//
+// Asset references (image/file) wrap an Asset, not a document, and aren't
+// subject to the publish workflow — so they're skipped (we only collect
+// ids whose marker is exactly 'reference').
+/**
+ * Collect all referenced document IDs from a doc's data. The `schema` and
+ * `registry` params are accepted for API compatibility but no longer used —
+ * the unified ref shape makes them unnecessary.
+ */
+export function collectReferenceIds(data, _schema, _registry) {
+    const ids = new Set();
+    walk(data, ids);
+    return Array.from(ids);
+}
+function walk(value, ids) {
+    if (value == null)
+        return;
+    if (Array.isArray(value)) {
+        for (const item of value)
+            walk(item, ids);
+        return;
+    }
+    if (typeof value !== 'object')
+        return;
+    const obj = value;
+    if (obj._type === 'reference' && typeof obj._ref === 'string' && obj._ref) {
+        ids.add(obj._ref);
+        return;
+    }
+    for (const key of Object.keys(obj)) {
+        if (key.startsWith('_'))
+            continue;
+        walk(obj[key], ids);
+    }
+}
+//# sourceMappingURL=reference-walk.js.map

package/dist/lib/utils/reference-walk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference-walk.js","sourceRoot":"","sources":["../../../src/lib/utils/reference-walk.ts"],"names":[],"mappings":"AAAA,yEAAyE;AACzE,6DAA6D;AAC7D,+DAA+D;AAC/D,EAAE;AACF,0EAA0E;AAC1E,wEAAwE;AACxE,4CAA4C;AAI5C;;;;GAIG;AACH,MAAM,UAAU,mBAAmB,CAClC,IAAa,EACb,OAA2B,EAC3B,SAAwB;IAExB,MAAM,GAAG,GAAG,IAAI,GAAG,EAAU,CAAC;IAC9B,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IAChB,OAAO,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACxB,CAAC;AAED,SAAS,IAAI,CAAC,KAAc,EAAE,GAAgB;IAC7C,IAAI,KAAK,IAAI,IAAI;QAAE,OAAO;IAC1B,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QAC1B,KAAK,MAAM,IAAI,IAAI,KAAK;YAAE,IAAI,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC1C,OAAO;IACR,CAAC;IACD,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO;IACtC,MAAM,GAAG,GAAG,KAAgC,CAAC;IAC7C,IAAI,GAAG,CAAC,KAAK,KAAK,WAAW,IAAI,OAAO,GAAG,CAAC,IAAI,KAAK,QAAQ,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;QAC3E,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QAClB,OAAO;IACR,CAAC;IACD,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC;QACpC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC;YAAE,SAAS;QAClC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,GAAG,CAAC,CAAC;IACrB,CAAC;AACF,CAAC"}

package/dist/local-api/collection-api.d.ts

@@ -2,6 +2,7 @@ import type { DocumentCache } from '../cache/index.js';
 import type { DatabaseAdapter } from '../db/index.js';
 import type { HierarchyService } from '../services/hierarchy-service.js';
 import type { VersionService } from '../services/version-service.js';
+import type { ReferencesService } from '../services/references-service.js';
 import type { Where, WhereTyped, FindOptions, FindResult } from '../types/filters.js';
 import type { Document } from '../types/document.js';
 import type { LocalAPIContext } from './types.js';
@@ -43,7 +44,15 @@ export declare class CollectionAPI<T = Document> {
     private documentCache?;
     private hierarchyService?;
     private versionService?;
-    constructor(collectionName: string, databaseAdapter: DatabaseAdapter, _schema: SchemaType, permissions: PermissionChecker, documentCache?: (DocumentCache | null) | undefined, hierarchyService?: HierarchyService | undefined, versionService?: VersionService | undefined);
+    private referencesService?;
+    private schemaRegistry?;
+    constructor(collectionName: string, databaseAdapter: DatabaseAdapter, _schema: SchemaType, permissions: PermissionChecker, documentCache?: (DocumentCache | null) | undefined, hierarchyService?: HierarchyService | undefined, versionService?: VersionService | undefined, referencesService?: ReferencesService | undefined, schemaRegistry?: SchemaType[] | undefined);
+    /**
+     * Refresh the back-reference index for this doc using the freshly-saved
+     * draftData. Best-effort: failures are logged inside the service and
+     * never thrown — a stale ref index doesn't block the user's save.
+     */
+    private syncReferences;
     /**
      * Get the schema for this collection
      */

package/dist/local-api/collection-api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"collection-api.d.ts","sourceRoot":"","sources":["../../src/lib/local-api/collection-api.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"collection-api.d.ts","sourceRoot":"","sources":["../../src/lib/local-api/collection-api.ts"],"names":[],"mappings":"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"}

package/dist/local-api/collection-api.js

@@ -3,6 +3,7 @@
 // Collection API - provides type-safe CRUD operations for a single collection
 import { singletonId } from '../schema-utils/singleton.js';
 import { validateDocumentData } from '../field-validation/utils.js';
+import { collectReferenceIds } from '../utils/reference-walk.js';
 import { hiddenReadFields, hiddenWriteFields, dropLockedWrites, stripHiddenFields } from '../field-access.js';
 const EMPTY_SET = new Set();
 /**
@@ -79,7 +80,9 @@ export class CollectionAPI {
     documentCache;
     hierarchyService;
     versionService;
-    constructor(collectionName, databaseAdapter, _schema, permissions, documentCache, hierarchyService, versionService) {
+    referencesService;
+    schemaRegistry;
+    constructor(collectionName, databaseAdapter, _schema, permissions, documentCache, hierarchyService, versionService, referencesService, schemaRegistry) {
         this.collectionName = collectionName;
         this.databaseAdapter = databaseAdapter;
         this._schema = _schema;
@@ -87,9 +90,21 @@ export class CollectionAPI {
         this.documentCache = documentCache;
         this.hierarchyService = hierarchyService;
         this.versionService = versionService;
+        this.referencesService = referencesService;
+        this.schemaRegistry = schemaRegistry;
         // Validate collection exists
         this.permissions.validateCollection(collectionName);
     }
+    /**
+     * Refresh the back-reference index for this doc using the freshly-saved
+     * draftData. Best-effort: failures are logged inside the service and
+     * never thrown — a stale ref index doesn't block the user's save.
+     */
+    async syncReferences(organizationId, documentId, data) {
+        if (!this.referencesService)
+            return;
+        await this.referencesService.syncReferencesFor(organizationId, documentId, data, this._schema, this.schemaRegistry ?? []);
+    }
     /**
      * Get the schema for this collection
      */
@@ -326,6 +341,7 @@ export class CollectionAPI {
             createdBy: context.user?.id,
             id: options?.id
         });
+        await this.syncReferences(context.organizationId, document.id, validationResult.normalizedData);
         // Create initial draft version
         if (this.versionService && !options?.skipVersioning) {
             await this.versionService.createVersion(this.databaseAdapter, context.organizationId, document.id, 'draft', validationResult.normalizedData, context.user?.id);
@@ -398,6 +414,7 @@ export class CollectionAPI {
         if (!document) {
             return null;
         }
+        await this.syncReferences(context.organizationId, id, validationResult.normalizedData);
         if (options?.publish) {
             await this.permissions.canPublish(context, this.collectionName, document);
             // Block publish if validation fails
@@ -488,6 +505,27 @@ export class CollectionAPI {
                 .join('; ');
             throw new Error(`Cannot publish: validation errors - ${errorMessage}`);
         }
+        // Guard: block publish if any referenced document is not published
+        const refIds = collectReferenceIds(document.draftData);
+        if (refIds.length > 0) {
+            const unpublished = [];
+            for (const refId of refIds) {
+                const refDoc = await this.databaseAdapter.findByDocIdAdvanced(context.organizationId, refId);
+                if (refDoc && !refDoc.publishedData) {
+                    const data = refDoc.draftData;
+                    const title = data?.title ||
+                        data?.name ||
+                        refDoc.id;
+                    unpublished.push({ id: refDoc.id, type: refDoc.type, title });
+                }
+            }
+            if (unpublished.length > 0) {
+                const names = unpublished
+                    .map((d) => `"${d.title}" (${d.type})`)
+                    .join(', ');
+                throw new Error(`Cannot publish — ${unpublished.length} referenced document(s) are not published: ${names}`);
+            }
+        }
         // Validation passed - proceed with publish (with version if service available)
         const publishedDocument = this.versionService
             ? await this.versionService.publishWithVersion(this.databaseAdapter, context.organizationId, id)

package/dist/local-api/index.d.ts

@@ -1,6 +1,7 @@
 import type { CMSConfig } from '../types/config.js';
 import type { DatabaseAdapter } from '../db/index.js';
 import { VersionService } from '../services/version-service.js';
+import { ReferencesService } from '../services/references-service.js';
 import type { FindOptions } from '../types/filters.js';
 import type { SchemaType } from '../types/schemas.js';
 import { CollectionAPI } from './collection-api.js';
@@ -50,6 +51,7 @@ export declare class LocalAPI {
     private documentCache;
     private hierarchyService;
     versionService: VersionService;
+    referencesService: ReferencesService;
     private permissions;
     private schemas;
     constructor(config: CMSConfig, userAdapter: DatabaseAdapter, systemAdapter?: DatabaseAdapter);
@@ -83,6 +85,33 @@ export declare class LocalAPI {
         type: string;
         document: unknown;
     } | null>;
+    /**
+     * Find all documents that reference the given target — the back-reference
+     * lookup that powers the unpublish guard. Returns lightweight rows
+     * (id/type/status); callers fetch full docs separately if they need data.
+     */
+    getBackReferences(context: LocalAPIContext, refId: string): Promise<Array<{
+        id: string;
+        type: string;
+        status: string | null;
+    }>>;
+    /**
+     * Batch lookup — fetch many documents by ID in one call. Routes through
+     * each doc's collection so the returned shape matches `collection.findByID`
+     * (perms applied, transformed, hidden fields stripped). Org hierarchy is
+     * resolved once for the whole batch and threaded into each per-collection
+     * call.
+     *
+     * Heterogeneous batches (mixed types) leave T as the default `unknown`;
+     * homogeneous callers (e.g. an array-of-references-to-one-type) can
+     * narrow it: `findDocumentsByIds<MenuItem>(ctx, ids)`.
+     *
+     * Missing/forbidden IDs are dropped from the result rather than thrown —
+     * callers compare result length to input length to detect gaps. If/when
+     * an adapter exposes a true `WHERE id IN (...)` batch we can short-circuit
+     * the per-id collection round-trips here without changing call sites.
+     */
+    findDocumentsByIds<T = unknown>(context: LocalAPIContext, ids: string[], options?: Partial<FindOptions<T>>): Promise<T[]>;
 }
 /**
  * Create and initialize the Local API

package/dist/local-api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/local-api/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAEnD,OAAO,EAAE,cAAc,EAAE,MAAM,6BAA6B,CAAC;AAC7D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAYjD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE/C;;;GAGG;AACH,MAAM,WAAW,WAAW;IAE3B,CAAC,cAAc,EAAE,MAAM,GAAG,aAAa,CAAC,OAAO,CAAC,CAAC;CAGjD;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,qBAAa,QAAQ;IAWnB,OAAO,CAAC,MAAM;IAVR,WAAW,EAAE,WAAW,CAAqB;IACpD,OAAO,CAAC,WAAW,CAAkB;IACrC,OAAO,CAAC,aAAa,CAAyB;IAC9C,OAAO,CAAC,aAAa,CAAuB;IAC5C,OAAO,CAAC,gBAAgB,CAAmB;IACpC,cAAc,EAAE,cAAc,CAAC;IACtC,OAAO,CAAC,WAAW,CAAoB;IACvC,OAAO,CAAC,OAAO,CAA0B;gBAGhC,MAAM,EAAE,SAAS,EACzB,WAAW,EAAE,eAAe,EAC5B,aAAa,CAAC,EAAE,eAAe;IAwBhC;;OAEG;IACH,OAAO,CAAC,qBAAqB;IA0D7B;;;OAGG;IACH,OAAO,CAAC,UAAU;IAOlB;;OAEG;IACH,kBAAkB,IAAI,MAAM,EAAE;IAI9B;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAIpC;;OAEG;IACH,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,SAAS;IAIzD;;;;OAIG;IACG,gBAAgB,CACrB,OAAO,EAAE,eAAe,EACxB,EAAE,EAAE,MAAM,EACV,OAAO,CAAC,EAAE,OAAO,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC,GACrC,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,OAAO,CAAA;KAAE,GAAG,IAAI,CAAC;CAetD;AAKD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,cAAc,CAC7B,MAAM,EAAE,SAAS,EACjB,WAAW,EAAE,eAAe,EAC5B,aAAa,CAAC,EAAE,eAAe,GAC7B,QAAQ,CAGV;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,IAAI,QAAQ,CAKtC;AAGD,OAAO,EACN,aAAa,EACb,uBAAuB,EACvB,KAAK,cAAc,EACnB,KAAK,mBAAmB,EACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACnE,YAAY,EAAE,eAAe,EAAE,aAAa,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7E,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/lib/local-api/index.ts"],"names":[],"mappings":"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"}

package/dist/local-api/index.js

@@ -4,6 +4,7 @@
 import { DocumentCache } from '../cache/index.js';
 import { HierarchyService } from '../services/hierarchy-service.js';
 import { VersionService } from '../services/version-service.js';
+import { ReferencesService } from '../services/references-service.js';
 import { CollectionAPI } from './collection-api.js';
 /**
  * CollectionAPI methods that compute synchronously and don't touch the DB.
@@ -53,6 +54,7 @@ export class LocalAPI {
     documentCache;
     hierarchyService;
     versionService;
+    referencesService;
     permissions;
     schemas;
     constructor(config, userAdapter, systemAdapter) {
@@ -64,6 +66,7 @@ export class LocalAPI {
         this.versionService = new VersionService({
             maxVersions: config.versioning?.maxVersions ?? 25
         });
+        this.referencesService = new ReferencesService(userAdapter);
         // Build schema map for quick lookups
         this.schemas = new Map(config.schemaTypes
             .filter((schema) => schema.type === 'document')
@@ -80,7 +83,7 @@ export class LocalAPI {
         const documentSchemas = this.config.schemaTypes.filter((s) => s.type === 'document');
         for (const schema of documentSchemas) {
             // Create a proxy that selects the correct adapter based on context
-            const collectionAPI = new Proxy(new CollectionAPI(schema.name, this.userAdapter, schema, this.permissions, this.documentCache, this.hierarchyService, this.versionService), {
+            const collectionAPI = new Proxy(new CollectionAPI(schema.name, this.userAdapter, schema, this.permissions, this.documentCache, this.hierarchyService, this.versionService, this.referencesService, this.config.schemaTypes), {
                 get: (target, prop) => {
                     const method = target[prop];
                     // Sync, pure-computation methods bypass the adapter-swap
@@ -97,7 +100,7 @@ export class LocalAPI {
                             const context = args[0];
                             const adapter = this.getAdapter(context);
                             // Create new CollectionAPI with the correct adapter
-                            const api = new CollectionAPI(schema.name, adapter, schema, this.permissions, this.documentCache, this.hierarchyService, this.versionService);
+                            const api = new CollectionAPI(schema.name, adapter, schema, this.permissions, this.documentCache, this.hierarchyService, this.versionService, new ReferencesService(adapter), this.config.schemaTypes);
                             // Call the method on the new instance
                             return api[prop].apply(api, args);
                         };
@@ -154,6 +157,67 @@ export class LocalAPI {
             return null;
         return { type: rawDoc.type, document: rawDoc };
     }
+    /**
+     * Find all documents that reference the given target — the back-reference
+     * lookup that powers the unpublish guard. Returns lightweight rows
+     * (id/type/status); callers fetch full docs separately if they need data.
+     */
+    async getBackReferences(context, refId) {
+        const adapter = this.getAdapter(context);
+        return adapter.findBackReferences(context.organizationId, refId);
+    }
+    /**
+     * Batch lookup — fetch many documents by ID in one call. Routes through
+     * each doc's collection so the returned shape matches `collection.findByID`
+     * (perms applied, transformed, hidden fields stripped). Org hierarchy is
+     * resolved once for the whole batch and threaded into each per-collection
+     * call.
+     *
+     * Heterogeneous batches (mixed types) leave T as the default `unknown`;
+     * homogeneous callers (e.g. an array-of-references-to-one-type) can
+     * narrow it: `findDocumentsByIds<MenuItem>(ctx, ids)`.
+     *
+     * Missing/forbidden IDs are dropped from the result rather than thrown —
+     * callers compare result length to input length to detect gaps. If/when
+     * an adapter exposes a true `WHERE id IN (...)` batch we can short-circuit
+     * the per-id collection round-trips here without changing call sites.
+     */
+    async findDocumentsByIds(context, ids, options) {
+        if (ids.length === 0)
+            return [];
+        const adapter = this.getAdapter(context);
+        // Resolve org hierarchy once for the whole batch; thread into each
+        // per-id call so collection.findByID skips its own hierarchy lookup.
+        let filterOrganizationIds = options?.filterOrganizationIds;
+        if (!filterOrganizationIds && this.hierarchyService) {
+            filterOrganizationIds = await this.hierarchyService.getOrgIdsWithChildren(context.organizationId);
+        }
+        // First: cheap type lookups so we know which collection to route through.
+        const typeLookups = await Promise.all(ids.map((id) => adapter
+            .findByDocIdAdvanced(context.organizationId, id, { filterOrganizationIds })
+            .then((row) => (row ? { id, type: row.type } : null))));
+        // Second: per-collection findByID for each resolved doc. Fan out in
+        // parallel; collection.findByID enforces perms and applies the
+        // standard processing pipeline.
+        const docs = await Promise.all(typeLookups.map(async (lookup) => {
+            if (!lookup)
+                return null;
+            const collection = this.collections[lookup.type];
+            if (!collection)
+                return null;
+            try {
+                return (await collection.findByID(context, lookup.id, {
+                    ...options,
+                    filterOrganizationIds
+                }));
+            }
+            catch {
+                // Permission denied or similar — drop silently per the contract.
+                return null;
+            }
+        }));
+        return docs.filter((d) => d != null);
+    }
 }
 // Global Local API instance
 let localAPIInstance = null;

package/dist/schema-utils/validator.js

@@ -57,6 +57,21 @@ export function validateSchemaReferences(schemas) {
         // Check array field references
         if (field.type === 'array' && field.of) {
             for (const arrayType of field.of) {
+                // Reference items inside an array must declare `to` and target known schemas
+                if (arrayType.type === 'reference') {
+                    const to = arrayType.to;
+                    if (!Array.isArray(to) || to.length === 0) {
+                        errors.push(`Schema "${parentSchema}" field "${field.name}" has a reference array item missing "to" — declare allowed target document types`);
+                    }
+                    else {
+                        for (const target of to) {
+                            if (!schemaNames.has(target.type)) {
+                                errors.push(`Schema "${parentSchema}" field "${field.name}" reference array item targets unknown document type "${target.type}"`);
+                            }
+                        }
+                    }
+                    continue;
+                }
                 // Skip validation for primitive types and inline objects
                 if (primitiveTypes.includes(arrayType.type)) {
                     continue;
@@ -123,17 +138,12 @@ export function validateSchemaReferences(schemas) {
         if (schema.preview?.select) {
             const fieldNames = new Set(schema.fields?.map((f) => f.name) || []);
             const rootOf = (path) => path.split('.', 1)[0] ?? path;
-            if (schema.preview.select.title &&
-                !fieldNames.has(rootOf(schema.preview.select.title))) {
-                errors.push(`Schema "${schema.name}" preview.select.title references unknown field "${schema.preview.select.title}"`);
-            }
-            if (schema.preview.select.subtitle &&
-                !fieldNames.has(rootOf(schema.preview.select.subtitle))) {
-                errors.push(`Schema "${schema.name}" preview.select.subtitle references unknown field "${schema.preview.select.subtitle}"`);
-            }
-            if (schema.preview.select.media &&
-                !fieldNames.has(rootOf(schema.preview.select.media))) {
-                errors.push(`Schema "${schema.name}" preview.select.media references unknown field "${schema.preview.select.media}"`);
+            for (const [key, path] of Object.entries(schema.preview.select)) {
+                if (typeof path !== 'string' || !path)
+                    continue;
+                if (!fieldNames.has(rootOf(path))) {
+                    errors.push(`Schema "${schema.name}" preview.select.${key} references unknown field "${path}"`);
+                }
             }
         }
         // Validate orderings

package/dist/server/api/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/server/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAoB7C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG;IACtB,SAAS,EAAE;QACV,QAAQ,EAAE,YAAY,CAAC;QACvB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;KAClB,CAAC;IACF,QAAQ,EAAE;QACT,QAAQ,EAAE,YAAY,CAAC;QACvB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;KAClB,CAAC;CACF,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,cAAc,kGAY7B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,QAoCrD;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC5B,SAAS,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,IAEzC,GAAG,OAAO,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,uBAejD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/server/api/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAC;AAoB7C;;;;;;;;;;GAUG;AACH,MAAM,MAAM,QAAQ,GAAG;IACtB,SAAS,EAAE;QACV,QAAQ,EAAE,YAAY,CAAC;QACvB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;KAClB,CAAC;IACF,QAAQ,EAAE;QACT,QAAQ,EAAE,YAAY,CAAC;QACvB,IAAI,EAAE,IAAI,GAAG,IAAI,CAAC;KAClB,CAAC;CACF,CAAC;AAEF;;;;;;;GAOG;AACH,wBAAgB,cAAc,kGAY7B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,GAAG,EAAE,IAAI,CAAC,QAAQ,CAAC,QAsCrD;AAED,MAAM,MAAM,SAAS,GAAG,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;AAE1D;;;;;;;;;;GAUG;AACH,wBAAgB,aAAa,CAC5B,SAAS,EAAE,CAAC,KAAK,EAAE,GAAG,KAAK,OAAO,CAAC,QAAQ,CAAC,GAAG,QAAQ,IAEzC,GAAG,OAAO,MAAM,EAAE,OAAO,CAAC,QAAQ,CAAC,uBAejD"}

package/dist/server/api/index.js

@@ -52,8 +52,10 @@ export function mountAphexBuiltins(app) {
     app.route('/documents', documentsQueryRouter);
     app.route('/documents', documentsPublishRouter);
     app.route('/documents', documentVersionsRouter);
-    app.route('/documents', documentsByIdRouter);
+    // documentsRouter has the literal `/by-ids` batch endpoint, which must
+    // mount before documentsByIdRouter or `:id` will swallow it.
     app.route('/documents', documentsRouter);
+    app.route('/documents', documentsByIdRouter);
     // Assets — same precedence rule: specific paths before parametric.
     // `/assets/bulk` and `/assets/references/counts` must register before
     // `/assets/:id` or Hono will capture them as `:id = "bulk"` etc.

package/dist/server/api/routes/documents-by-id.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"documents-by-id.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/documents-by-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAO5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,eAAO,MAAM,mBAAmB,EAAE,IAAI,CAAC,QAAQ,CAkM5C,CAAC"}
+{"version":3,"file":"documents-by-id.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/documents-by-id.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAO5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAEzC,eAAO,MAAM,mBAAmB,EAAE,IAAI,CAAC,QAAQ,CA6N5C,CAAC"}

package/dist/server/api/routes/documents-by-id.js

@@ -148,4 +148,27 @@ export const documentsByIdRouter = new Hono()
             message: error instanceof Error ? error.message : 'Unknown error'
         }, 500);
     }
+})
+    .get('/:id/back-references', async (c) => {
+    try {
+        const { localAPI } = c.var.aphexCMS;
+        const context = authToContext(c.var.auth);
+        const id = c.req.param('id');
+        if (!id) {
+            return c.json({ success: false, error: 'Document ID is required' }, 400);
+        }
+        const refs = await localAPI.getBackReferences(context, id);
+        return c.json({ success: true, data: refs });
+    }
+    catch (error) {
+        cmsLogger.error('Failed to fetch back-references:', error);
+        if (error instanceof PermissionError) {
+            return c.json({ success: false, error: 'Forbidden', message: error.message }, 403);
+        }
+        return c.json({
+            success: false,
+            error: 'Failed to fetch back-references',
+            message: error instanceof Error ? error.message : 'Unknown error'
+        }, 500);
+    }
 });

package/dist/server/api/routes/documents.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/documents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAM5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAKzC,eAAO,MAAM,eAAe,EAAE,IAAI,CAAC,QAAQ,CAuKxC,CAAC"}
+{"version":3,"file":"documents.d.ts","sourceRoot":"","sources":["../../../../src/lib/server/api/routes/documents.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAU5B,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,UAAU,CAAC;AAKzC,eAAO,MAAM,eAAe,EAAE,IAAI,CAAC,QAAQ,CAyMxC,CAAC"}

package/dist/server/api/routes/documents.js

@@ -3,7 +3,7 @@ import { zValidator } from '@hono/zod-validator';
 import { authToContext } from '../../../local-api/auth-helpers.js';
 import { PermissionError } from '../../../local-api/permissions.js';
 import { cmsLogger } from '../../../utils/logger.js';
-import { createDocumentRequest, listDocumentsQuery } from '../../../api/schemas/documents.js';
+import { createDocumentRequest, getDocumentsByIdsQuery, listDocumentsQuery } from '../../../api/schemas/documents.js';
 const DEFAULT_PAGE_SIZE = 20;
 const DEFAULT_PAGE = 1;
 export const documentsRouter = new Hono()
@@ -83,6 +83,34 @@ export const documentsRouter = new Hono()
             message: error instanceof Error ? error.message : 'Unknown error'
         }, 500);
     }
+})
+    .get('/by-ids', zValidator('query', getDocumentsByIdsQuery, (result, c) => {
+    if (!result.success) {
+        return c.json({
+            success: false,
+            error: 'Invalid query parameters',
+            issues: result.error.issues
+        }, 400);
+    }
+}), async (c) => {
+    try {
+        const { localAPI } = c.var.aphexCMS;
+        const context = authToContext(c.var.auth);
+        const { ids } = c.req.valid('query');
+        const docs = await localAPI.findDocumentsByIds(context, ids);
+        return c.json({ success: true, data: docs });
+    }
+    catch (error) {
+        cmsLogger.error('Failed to batch-fetch documents:', error);
+        if (error instanceof PermissionError) {
+            return c.json({ success: false, error: 'Forbidden', message: error.message }, 403);
+        }
+        return c.json({
+            success: false,
+            error: 'Failed to fetch documents',
+            message: error instanceof Error ? error.message : 'Unknown error'
+        }, 500);
+    }
 })
     .post('/', zValidator('json', createDocumentRequest, (result, c) => {
     if (!result.success) {

package/dist/services/references-service.d.ts

@@ -0,0 +1,35 @@
+import type { DatabaseAdapter } from '../db/interfaces.js';
+import type { SchemaType } from '../types/schemas.js';
+/**
+ * Maintains the back-reference index. After every doc save the collection-API
+ * calls into here with the doc's draftData (the freshly-saved version) and
+ * its schema; we walk the data via the schema-aware walker, dedupe the
+ * resulting ref IDs, and atomically replace the rows for that referencer.
+ *
+ * Failures are logged but never thrown — a stale ref index is bad UX (the
+ * publish/unpublish guards may be wrong), but it shouldn't block the user's
+ * save. The boot-time backfill catches up gaps when the studio restarts.
+ */
+export declare class ReferencesService {
+    private databaseAdapter;
+    constructor(databaseAdapter: DatabaseAdapter);
+    /**
+     * Sync the back-reference rows for a single document. Idempotent —
+     * safe to call repeatedly with the same data.
+     */
+    syncReferencesFor(organizationId: string, documentId: string, data: unknown, schema: SchemaType | null, registry: SchemaType[]): Promise<void>;
+    /**
+     * Boot-time backfill — if the references table is empty for an org,
+     * scan every document and rebuild the index. Idempotent and cheap when
+     * the index already has rows (the empty check short-circuits).
+     *
+     * Skipped silently in error paths — boot must keep going even if the
+     * scan can't run (missing perms, connection issues, etc).
+     */
+    backfillIfEmpty(organizationId: string, schemas: SchemaType[], listAllDocuments: () => Promise<Array<{
+        id: string;
+        type: string;
+        data: unknown;
+    }>>): Promise<void>;
+}
+//# sourceMappingURL=references-service.d.ts.map

package/dist/services/references-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"references-service.d.ts","sourceRoot":"","sources":["../../src/lib/services/references-service.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,kBAAkB,CAAC;AACxD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAInD;;;;;;;;;GASG;AACH,qBAAa,iBAAiB;IACjB,OAAO,CAAC,eAAe;gBAAf,eAAe,EAAE,eAAe;IAEpD;;;OAGG;IACG,iBAAiB,CACtB,cAAc,EAAE,MAAM,EACtB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,UAAU,GAAG,IAAI,EACzB,QAAQ,EAAE,UAAU,EAAE,GACpB,OAAO,CAAC,IAAI,CAAC;IAShB;;;;;;;OAOG;IACG,eAAe,CACpB,cAAc,EAAE,MAAM,EACtB,OAAO,EAAE,UAAU,EAAE,EACrB,gBAAgB,EAAE,MAAM,OAAO,CAC9B,KAAK,CAAC;QAAE,EAAE,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAClD,GACC,OAAO,CAAC,IAAI,CAAC;CAwBhB"}