@elytracms/studio 0.0.91 → 0.0.93

package/dist/lib/cms/field-patch.js

@@ -0,0 +1,25 @@
+import { fieldPath, isFieldLocalized, readValueAt } from '@elytracms/core/cms-core';
+/**
+ * EC-595 A2 — the patch a FIELD write emits at its source.
+ *
+ * Every writer that writes one field's value through core's `writeField` (the form, a
+ * table cell, bulk set-field, an AI field change, a translation, fill-from-base) knows
+ * the position it wrote: the field, and — for a localized field — the locale bucket
+ * (EC-595 binding point 3: "localized fields patch per bucket"). This reads the value
+ * the write left at that position in `written` (the document AFTER `writeField`, so the
+ * value is the canonical one, EC-586) and says so as one `set` — or `unset` when the
+ * write cleared the key (writing `undefined`, an emptied list).
+ */
+export function fieldWritePatch(collection, written, fieldName, locale) {
+    const path = fieldPositionPath(collection, fieldName, locale);
+    const value = readValueAt(written, path);
+    return value === undefined ? { op: 'unset', path } : { op: 'set', path, value };
+}
+/** The position a field write addresses: `[field]`, or `[field, locale]` for a localized field. */
+export function fieldPositionPath(collection, fieldName, locale) {
+    return fieldPath(fieldName, isFieldLocalized(collection, fieldName) ? locale : undefined);
+}
+// EC-585: the field-position patches of the publish-time hidden strip (the one writer
+// that hands back a whole document) are computed inside `documents.publish` now, where
+// the strip runs for every publish path (`core/operations/documents.ts`, `stripPatches`).
+//# sourceMappingURL=field-patch.js.map

package/dist/lib/cms/field-patch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"field-patch.js","sourceRoot":"","sources":["../../../src/lib/cms/field-patch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,0BAA0B,CAAA;AAGnF;;;;;;;;;;GAUG;AACH,MAAM,UAAU,eAAe,CAC7B,UAAyB,EACzB,OAAoB,EACpB,SAAiB,EACjB,MAA0B;IAE1B,MAAM,IAAI,GAAG,iBAAiB,CAAC,UAAU,EAAE,SAAS,EAAE,MAAM,CAAC,CAAA;IAC7D,MAAM,KAAK,GAAG,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,CAAA;IACxC,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,KAAK,EAAE,CAAA;AACjF,CAAC;AAED,mGAAmG;AACnG,MAAM,UAAU,iBAAiB,CAC/B,UAAyB,EACzB,SAAiB,EACjB,MAA0B;IAE1B,OAAO,SAAS,CAAC,SAAS,EAAE,gBAAgB,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,CAAC,CAAA;AAC3F,CAAC;AAED,sFAAsF;AACtF,uFAAuF;AACvF,0FAA0F","sourcesContent":["import { fieldPath, isFieldLocalized, readValueAt } from '@elytracms/core/cms-core'\nimport type { CmsDocument, CollectionDef, DocumentPatch, Locale, ValuePath } from '@elytracms/core/cms-core'\n\n/**\n * EC-595 A2 — the patch a FIELD write emits at its source.\n *\n * Every writer that writes one field's value through core's `writeField` (the form, a\n * table cell, bulk set-field, an AI field change, a translation, fill-from-base) knows\n * the position it wrote: the field, and — for a localized field — the locale bucket\n * (EC-595 binding point 3: \"localized fields patch per bucket\"). This reads the value\n * the write left at that position in `written` (the document AFTER `writeField`, so the\n * value is the canonical one, EC-586) and says so as one `set` — or `unset` when the\n * write cleared the key (writing `undefined`, an emptied list).\n */\nexport function fieldWritePatch(\n  collection: CollectionDef,\n  written: CmsDocument,\n  fieldName: string,\n  locale: Locale | undefined,\n): DocumentPatch {\n  const path = fieldPositionPath(collection, fieldName, locale)\n  const value = readValueAt(written, path)\n  return value === undefined ? { op: 'unset', path } : { op: 'set', path, value }\n}\n\n/** The position a field write addresses: `[field]`, or `[field, locale]` for a localized field. */\nexport function fieldPositionPath(\n  collection: CollectionDef,\n  fieldName: string,\n  locale: Locale | undefined,\n): ValuePath {\n  return fieldPath(fieldName, isFieldLocalized(collection, fieldName) ? locale : undefined)\n}\n\n// EC-585: the field-position patches of the publish-time hidden strip (the one writer\n// that hands back a whole document) are computed inside `documents.publish` now, where\n// the strip runs for every publish path (`core/operations/documents.ts`, `stripPatches`).\n"]}

package/dist/lib/cms/published-documents.d.ts

@@ -25,7 +25,7 @@ export interface PublishedDocuments {
  * EC-579 (RESIDUE-2c): `documents.pinVersion` moves the pin too — it is how a
  * changeset revert restores a prior live version — and was missing, so a revert left
  * the live URLs on the old pool until a reload. `documents.restore` was here and
- * moves nothing: it writes the DRAFT from a recorded version (`cms.upsertDocument`),
+ * moves nothing: it writes the DRAFT from a recorded version (`documents.replace`),
  * never the pin. The same answer the Convex trigger gives server-side: only a pin
  * move or the delete of a pinned row changes published output.
  */

package/dist/lib/cms/published-documents.js

@@ -5,7 +5,7 @@ import { useOperationQuery } from '@elytracms/studio/lib/query';
  * EC-579 (RESIDUE-2c): `documents.pinVersion` moves the pin too — it is how a
  * changeset revert restores a prior live version — and was missing, so a revert left
  * the live URLs on the old pool until a reload. `documents.restore` was here and
- * moves nothing: it writes the DRAFT from a recorded version (`cms.upsertDocument`),
+ * moves nothing: it writes the DRAFT from a recorded version (`documents.replace`),
  * never the pin. The same answer the Convex trigger gives server-side: only a pin
  * move or the delete of a pinned row changes published output.
  */

package/dist/lib/cms/published-documents.js.map

@@ -1 +1 @@
-{"version":3,"file":"published-documents.js","sourceRoot":"","sources":["../../../src/lib/cms/published-documents.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAsB/D;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,mBAAmB;IACnB,qBAAqB;IACrB,sBAAsB;IACtB,kBAAkB;IAClB,iBAAiB;CACT,CAAA;AAEV,MAAM,UAAU,GAAqC,IAAI,GAAG,EAAE,CAAA;AAE9D;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,UAA4B,EAC5B,SAAiB,EACjB,YAAoB;IAEpB,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,SAAS,CAAC,aAAa,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAA;IAChG,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,IAAI,GAAG,EAAE,CAAA;IAChC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAuB,CAAA;IAC3C,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,KAAK;QAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAA;IACpE,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,SAA6B,EAC7B,YAAoB;IAEpB,MAAM,KAAK,GAAG,iBAAiB,CAA2B;QACxD,4EAA4E;QAC5E,QAAQ,EAAE,CAAC,oBAAoB,EAAE,SAAS,IAAI,GAAG,EAAE,YAAY,CAAC;QAChE,MAAM,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,sBAAsB,CAAC,UAAU,EAAE,SAAmB,EAAE,YAAY,CAAC;QAC7F,YAAY,EAAE,oBAAoB;QAClC,OAAO,EAAE,SAAS,KAAK,SAAS;KACjC,CAAC,CAAA;IACF,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IACzE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA;AAC1F,CAAC","sourcesContent":["import type { CmsDocument } from '@elytracms/core/cms-core'\nimport type { OperationsClient } from '../operations'\nimport { useOperationQuery } from '@elytracms/studio/lib/query'\n\n/**\n * The PUBLISHED-perspective documents of a collection (EC-205, \"live = published\")\n * — the pinned published snapshot of each currently-published document, keyed by\n * id. Live surfaces (a document's live URL + \"View live\", EC-216) MUST derive\n * from this, never from the draft rows the studio edits: an unpublished document,\n * or an unpublished `slug`/`parent` edit, must never leak into a \"live\" URL. The\n * pool is exactly the set the live site would serve, so composing a nested page's\n * URL from these ancestors yields the URL the live site actually resolves.\n *\n * EC-308/AD-17: loaded + kept fresh through the one `useOperationQuery` cache\n * seam — invalidated only when a command that moves a live pin succeeds (NOT on\n * every autosave upsert — a draft edit doesn't change what's published). Cost: ONE\n * bulk `documents.listPublished` read (EC-307).\n */\nexport interface PublishedDocuments {\n  /** Pinned published snapshot per published document id. Empty while loading. */\n  byId: ReadonlyMap<string, CmsDocument>\n  status: 'loading' | 'ready'\n}\n\n/**\n * Commands that change which version is pinned live (and thus the pool).\n *\n * EC-579 (RESIDUE-2c): `documents.pinVersion` moves the pin too — it is how a\n * changeset revert restores a prior live version — and was missing, so a revert left\n * the live URLs on the old pool until a reload. `documents.restore` was here and\n * moves nothing: it writes the DRAFT from a recorded version (`cms.upsertDocument`),\n * never the pin. The same answer the Convex trigger gives server-side: only a pin\n * move or the delete of a pinned row changes published output.\n */\nexport const PUBLISHED_RELOAD_OPS = [\n  'documents.publish',\n  'documents.unpublish',\n  'documents.pinVersion',\n  'documents.delete',\n  'documents.clear',\n] as const\n\nconst EMPTY_POOL: ReadonlyMap<string, CmsDocument> = new Map()\n\n/**\n * Build the published pool of a collection (pure over the operations client): the\n * pinned published snapshot of every currently-published document, keyed by id.\n * EC-307: one bulk `documents.listPublished` read — the backend resolves each\n * `publishedVersion` pointer to its recorded snapshot — instead of a `list` plus a\n * per-document `listVersions` fan-out. Read failures degrade to an empty pool.\n */\nexport async function loadPublishedDocuments(\n  operations: OperationsClient,\n  projectId: string,\n  collectionId: string,\n): Promise<Map<string, CmsDocument>> {\n  const result = await operations.documents.listPublished({ projectId, collection: collectionId })\n  if (!result.ok) return new Map()\n  const byId = new Map<string, CmsDocument>()\n  for (const snapshot of result.value) byId.set(snapshot.id, snapshot)\n  return byId\n}\n\nexport function usePublishedDocuments(\n  projectId: string | undefined,\n  collectionId: string,\n): PublishedDocuments {\n  const query = useOperationQuery<Map<string, CmsDocument>>({\n    // Playground/fixture mode (no backend) is `enabled: false` → never queried.\n    queryKey: ['publishedDocuments', projectId ?? '∅', collectionId],\n    loader: (operations) => loadPublishedDocuments(operations, projectId as string, collectionId),\n    invalidateOn: PUBLISHED_RELOAD_OPS,\n    enabled: projectId !== undefined,\n  })\n  if (projectId === undefined) return { byId: EMPTY_POOL, status: 'ready' }\n  return { byId: query.data ?? EMPTY_POOL, status: query.isPending ? 'loading' : 'ready' }\n}\n"]}
+{"version":3,"file":"published-documents.js","sourceRoot":"","sources":["../../../src/lib/cms/published-documents.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,6BAA6B,CAAA;AAsB/D;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,mBAAmB;IACnB,qBAAqB;IACrB,sBAAsB;IACtB,kBAAkB;IAClB,iBAAiB;CACT,CAAA;AAEV,MAAM,UAAU,GAAqC,IAAI,GAAG,EAAE,CAAA;AAE9D;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAC1C,UAA4B,EAC5B,SAAiB,EACjB,YAAoB;IAEpB,MAAM,MAAM,GAAG,MAAM,UAAU,CAAC,SAAS,CAAC,aAAa,CAAC,EAAE,SAAS,EAAE,UAAU,EAAE,YAAY,EAAE,CAAC,CAAA;IAChG,IAAI,CAAC,MAAM,CAAC,EAAE;QAAE,OAAO,IAAI,GAAG,EAAE,CAAA;IAChC,MAAM,IAAI,GAAG,IAAI,GAAG,EAAuB,CAAA;IAC3C,KAAK,MAAM,QAAQ,IAAI,MAAM,CAAC,KAAK;QAAE,IAAI,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC,CAAA;IACpE,OAAO,IAAI,CAAA;AACb,CAAC;AAED,MAAM,UAAU,qBAAqB,CACnC,SAA6B,EAC7B,YAAoB;IAEpB,MAAM,KAAK,GAAG,iBAAiB,CAA2B;QACxD,4EAA4E;QAC5E,QAAQ,EAAE,CAAC,oBAAoB,EAAE,SAAS,IAAI,GAAG,EAAE,YAAY,CAAC;QAChE,MAAM,EAAE,CAAC,UAAU,EAAE,EAAE,CAAC,sBAAsB,CAAC,UAAU,EAAE,SAAmB,EAAE,YAAY,CAAC;QAC7F,YAAY,EAAE,oBAAoB;QAClC,OAAO,EAAE,SAAS,KAAK,SAAS;KACjC,CAAC,CAAA;IACF,IAAI,SAAS,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,UAAU,EAAE,MAAM,EAAE,OAAO,EAAE,CAAA;IACzE,OAAO,EAAE,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,UAAU,EAAE,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,OAAO,EAAE,CAAA;AAC1F,CAAC","sourcesContent":["import type { CmsDocument } from '@elytracms/core/cms-core'\nimport type { OperationsClient } from '../operations'\nimport { useOperationQuery } from '@elytracms/studio/lib/query'\n\n/**\n * The PUBLISHED-perspective documents of a collection (EC-205, \"live = published\")\n * — the pinned published snapshot of each currently-published document, keyed by\n * id. Live surfaces (a document's live URL + \"View live\", EC-216) MUST derive\n * from this, never from the draft rows the studio edits: an unpublished document,\n * or an unpublished `slug`/`parent` edit, must never leak into a \"live\" URL. The\n * pool is exactly the set the live site would serve, so composing a nested page's\n * URL from these ancestors yields the URL the live site actually resolves.\n *\n * EC-308/AD-17: loaded + kept fresh through the one `useOperationQuery` cache\n * seam — invalidated only when a command that moves a live pin succeeds (NOT on\n * every autosave upsert — a draft edit doesn't change what's published). Cost: ONE\n * bulk `documents.listPublished` read (EC-307).\n */\nexport interface PublishedDocuments {\n  /** Pinned published snapshot per published document id. Empty while loading. */\n  byId: ReadonlyMap<string, CmsDocument>\n  status: 'loading' | 'ready'\n}\n\n/**\n * Commands that change which version is pinned live (and thus the pool).\n *\n * EC-579 (RESIDUE-2c): `documents.pinVersion` moves the pin too — it is how a\n * changeset revert restores a prior live version — and was missing, so a revert left\n * the live URLs on the old pool until a reload. `documents.restore` was here and\n * moves nothing: it writes the DRAFT from a recorded version (`documents.replace`),\n * never the pin. The same answer the Convex trigger gives server-side: only a pin\n * move or the delete of a pinned row changes published output.\n */\nexport const PUBLISHED_RELOAD_OPS = [\n  'documents.publish',\n  'documents.unpublish',\n  'documents.pinVersion',\n  'documents.delete',\n  'documents.clear',\n] as const\n\nconst EMPTY_POOL: ReadonlyMap<string, CmsDocument> = new Map()\n\n/**\n * Build the published pool of a collection (pure over the operations client): the\n * pinned published snapshot of every currently-published document, keyed by id.\n * EC-307: one bulk `documents.listPublished` read — the backend resolves each\n * `publishedVersion` pointer to its recorded snapshot — instead of a `list` plus a\n * per-document `listVersions` fan-out. Read failures degrade to an empty pool.\n */\nexport async function loadPublishedDocuments(\n  operations: OperationsClient,\n  projectId: string,\n  collectionId: string,\n): Promise<Map<string, CmsDocument>> {\n  const result = await operations.documents.listPublished({ projectId, collection: collectionId })\n  if (!result.ok) return new Map()\n  const byId = new Map<string, CmsDocument>()\n  for (const snapshot of result.value) byId.set(snapshot.id, snapshot)\n  return byId\n}\n\nexport function usePublishedDocuments(\n  projectId: string | undefined,\n  collectionId: string,\n): PublishedDocuments {\n  const query = useOperationQuery<Map<string, CmsDocument>>({\n    // Playground/fixture mode (no backend) is `enabled: false` → never queried.\n    queryKey: ['publishedDocuments', projectId ?? '∅', collectionId],\n    loader: (operations) => loadPublishedDocuments(operations, projectId as string, collectionId),\n    invalidateOn: PUBLISHED_RELOAD_OPS,\n    enabled: projectId !== undefined,\n  })\n  if (projectId === undefined) return { byId: EMPTY_POOL, status: 'ready' }\n  return { byId: query.data ?? EMPTY_POOL, status: query.isPending ? 'loading' : 'ready' }\n}\n"]}

package/dist/lib/cms-views/view-model.d.ts

@@ -38,8 +38,8 @@ export type FilterClause = z.infer<typeof filterClauseSchema>;
 export declare const viewSortSchema: z.ZodObject<{
     field: z.ZodString;
     dir: z.ZodEnum<{
-        desc: "desc";
         asc: "asc";
+        desc: "desc";
     }>;
 }, z.core.$strip>;
 export type ViewSort = z.infer<typeof viewSortSchema>;
@@ -63,8 +63,8 @@ export declare const tableViewStateSchema: z.ZodObject<{
     sort: z.ZodNullable<z.ZodObject<{
         field: z.ZodString;
         dir: z.ZodEnum<{
-            desc: "desc";
             asc: "asc";
+            desc: "desc";
         }>;
     }, z.core.$strip>>;
     columns: z.ZodArray<z.ZodString>;
@@ -305,8 +305,8 @@ export declare const configViewSchema: z.ZodObject<{
     sort: z.ZodOptional<z.ZodNullable<z.ZodObject<{
         field: z.ZodString;
         dir: z.ZodEnum<{
-            desc: "desc";
             asc: "asc";
+            desc: "desc";
         }>;
     }, z.core.$strip>>>;
     columns: z.ZodOptional<z.ZodArray<z.ZodString>>;

package/dist/lib/collection-view/__fixtures__/document-writes.d.ts

@@ -0,0 +1,6 @@
+import type { DocumentWrites } from '../collection-view-source.js';
+/**
+ * A no-op revisioned-document write model (EC-595 A2) for surface tests that render a
+ * CMS-shaped source with `renderToStaticMarkup` and never write.
+ */
+export declare function noopDocumentWrites(): DocumentWrites;

package/dist/lib/collection-view/__fixtures__/document-writes.js

@@ -0,0 +1,23 @@
+/**
+ * A no-op revisioned-document write model (EC-595 A2) for surface tests that render a
+ * CMS-shaped source with `renderToStaticMarkup` and never write.
+ */
+export function noopDocumentWrites() {
+    return {
+        kind: 'document',
+        commit: async () => undefined,
+        revisionOf: () => undefined,
+        insert: () => { },
+        newId: () => 'new-id',
+        conflicts: () => [],
+        resolveConflict: () => { },
+        adoptSnapshot: () => { },
+        flush: async () => { },
+        replace: () => { },
+        subscribe: () => () => { },
+        reportPresence: () => { },
+        clearPresence: () => { },
+        presenceSessionId: 'test-session',
+    };
+}
+//# sourceMappingURL=document-writes.js.map

package/dist/lib/collection-view/__fixtures__/document-writes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"document-writes.js","sourceRoot":"","sources":["../../../../src/lib/collection-view/__fixtures__/document-writes.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC,SAAS;QAC7B,UAAU,EAAE,GAAG,EAAE,CAAC,SAAS;QAC3B,MAAM,EAAE,GAAG,EAAE,GAAE,CAAC;QAChB,KAAK,EAAE,GAAG,EAAE,CAAC,QAAQ;QACrB,SAAS,EAAE,GAAG,EAAE,CAAC,EAAE;QACnB,eAAe,EAAE,GAAG,EAAE,GAAE,CAAC;QACzB,aAAa,EAAE,GAAG,EAAE,GAAE,CAAC;QACvB,KAAK,EAAE,KAAK,IAAI,EAAE,GAAE,CAAC;QACrB,OAAO,EAAE,GAAG,EAAE,GAAE,CAAC;QACjB,SAAS,EAAE,GAAG,EAAE,CAAC,GAAG,EAAE,GAAE,CAAC;QACzB,cAAc,EAAE,GAAG,EAAE,GAAE,CAAC;QACxB,aAAa,EAAE,GAAG,EAAE,GAAE,CAAC;QACvB,iBAAiB,EAAE,cAAc;KAClC,CAAA;AACH,CAAC","sourcesContent":["import type { DocumentWrites } from '../collection-view-source'\n\n/**\n * A no-op revisioned-document write model (EC-595 A2) for surface tests that render a\n * CMS-shaped source with `renderToStaticMarkup` and never write.\n */\nexport function noopDocumentWrites(): DocumentWrites {\n  return {\n    kind: 'document',\n    commit: async () => undefined,\n    revisionOf: () => undefined,\n    insert: () => {},\n    newId: () => 'new-id',\n    conflicts: () => [],\n    resolveConflict: () => {},\n    adoptSnapshot: () => {},\n    flush: async () => {},\n    replace: () => {},\n    subscribe: () => () => {},\n    reportPresence: () => {},\n    clearPresence: () => {},\n    presenceSessionId: 'test-session',\n  }\n}\n"]}

package/dist/lib/collection-view/collection-view-source.d.ts

@@ -1,7 +1,8 @@
-import type { CmsDocument, CollectionDef, DocumentRef, DocumentUrl, FieldDef, Locale, LocaleConfig, LocalizedString, RestoreScope } from '@elytracms/core/cms-core';
+import type { CmsDocument, CollectionDef, DocumentPatch, DocumentRef, ValuePath, DocumentUrl, FieldDef, Locale, LocaleConfig, LocalizedString, RestoreScope } from '@elytracms/core/cms-core';
 import type { CmsValidationIssue } from '@elytracms/core/cms-core';
 import type { OperationError } from '@elytracms/core/operations';
-import type { ReferenceTarget } from '@elytracms/core/persistence';
+import type { CmsDocumentRecord, PresenceEntry, ReferenceTarget } from '@elytracms/core/persistence';
+import type { CommitOutcome, DocumentConflict } from '../operations/cms-persistence.js';
 import type { TableViewState } from '../cms-views/view-model.js';
 import type { CellCommitInput, CellCommitOutcome } from '../../components/cms/cell-edit.js';
 import type { BulkAction, BulkReport, BulkSetField } from '../../components/cms/bulk-actions.js';
@@ -96,7 +97,7 @@ export interface CollectionViewSource {
      * when there is no asset backend (a source without assets degrades to a label
      * via {@link titleOf}, matching today's "no AssetsProvider" behaviour).
      */
-    resolveAsset?(id: string): ResolvedAsset | undefined;
+    resolveAsset?(id: string): AssetDisplay | undefined;
     /**
      * How this rail's records are addressed in the EC-155 reference index — the
      * target shape the delete/unpublish confirmation's inbound pre-flight queries
@@ -135,7 +136,15 @@ export interface CollectionViewSource {
     viewState(): TableViewState;
     setViewState(update: TableViewState | ((prev: TableViewState) => TableViewState)): void;
     create(): DocumentRef;
-    save(doc: CmsDocument): void;
+    /**
+     * EC-595 A2 — HOW this source's records are written: exactly one model per source,
+     * so a surface can never write a revisioned document the record way or vice versa.
+     * `record` — the explicit-save rails (users, redirects, assets, the account): the
+     * editor's Save button hands the whole record over. `document` — the CMS: every
+     * writer emits patches at its source, committed on quiescence and merged per path
+     * at the store; the editor shows per-field conflicts and follows the subscription.
+     */
+    readonly writes: CollectionWrites;
     remove(ref: DocumentRef): void;
     /**
      * Bulk publish/unpublish/delete/set-field (only when `capabilities.bulk`): one
@@ -171,6 +180,56 @@ export interface CollectionViewSource {
      */
     readonly imports?: ImportCapability;
 }
+/** EC-595 A2 — the write model of a source (see {@link CollectionViewSource.writes}). */
+export type CollectionWrites = RecordWrites | DocumentWrites;
+/** An explicit-save rail: the editor's Save button writes the whole record. */
+export interface RecordWrites {
+    readonly kind: 'record';
+    save(doc: CmsDocument): void;
+}
+/**
+ * The revisioned-document write model (EC-595, ratified 2026-10-24): patches at the
+ * source, the persister's queue, per-field conflicts, the document subscription.
+ */
+export interface DocumentWrites {
+    readonly kind: 'document';
+    /**
+     * Commit the patches a writer made; resolves once acknowledged (`undefined` in a
+     * fixture session). `bases` — per patch, the revision the edit was started at.
+     */
+    commit(ref: DocumentRef, patches: readonly DocumentPatch[], bases?: readonly (number | undefined)[]): Promise<CommitOutcome | undefined>;
+    /** The revision the session's view of a document is at. */
+    revisionOf(ref: DocumentRef): number | undefined;
+    /** Create a document from a whole value (insert-if-absent): duplicate. */
+    insert(doc: CmsDocument): void;
+    /** A fresh document id from the session's injected factory (EC-578). */
+    newId(): string;
+    /** The open per-field conflicts on a document. */
+    conflicts(ref: DocumentRef): readonly DocumentConflict[];
+    resolveConflict(ref: DocumentRef, conflictId: string, choice: 'theirs' | 'mine'): void;
+    /** Adopt a row the document subscription pushed (local edits win on their paths until flushed). */
+    adoptSnapshot(ref: DocumentRef, record: CmsDocumentRecord | undefined): void;
+    /** The forced flush's persistence half: await every queued write of the document. */
+    flush(ref: DocumentRef): Promise<void>;
+    /**
+     * Write the whole document at the revision the session holds (a document-level key
+     * the value-position grammar has no position for — the slot `alias`). A move since
+     * is refused, never overwritten.
+     */
+    replace(doc: CmsDocument): void;
+    /**
+     * EC-595 point 7 — follow ONE document while it is open: every pushed row is adopted
+     * under the local edits (the editor rebases), and the presence on it is delivered to
+     * `onPresence`. Returns the unsubscribe function.
+     */
+    subscribe(ref: DocumentRef, onPresence: (presence: readonly PresenceEntry[]) => void): () => void;
+    /** Thin presence (Stage A): this session is on the document, in `path`'s field (or on no field). */
+    reportPresence(ref: DocumentRef, path: ValuePath | undefined): void;
+    /** This session left the document. */
+    clearPresence(ref: DocumentRef): void;
+    /** This session's presence id (one per tab), so the editor can leave itself out. */
+    readonly presenceSessionId: string;
+}
 /**
  * The capability matrix. Each flag gates a shell region AND the presence of its
  * method group. The **users rail** (EC-240) sets `publish:false`, `versions:false`
@@ -220,8 +279,12 @@ export type FieldAccess = 'edit' | 'read' | 'hidden';
  * principal edit / see this field?", so the default-open fallback lives in one spot.
  */
 export declare function resolveFieldAccess(source: CollectionViewSource, field: FieldDef, record?: CmsDocument): FieldAccess;
-/** Asset display metadata a cell/field renders (thumbnail or labelled badge). */
-export interface ResolvedAsset {
+/**
+ * Asset display metadata a cell/field renders (thumbnail or labelled badge). EC-587:
+ * named apart from core's `ResolvedAsset` (the delivery shape) — this is the studio's
+ * label/thumbnail slice; its `alt` is the one reader's (`assetAlt`).
+ */
+export interface AssetDisplay {
     readonly url?: string;
     readonly contentType?: string;
     readonly title?: string;

package/dist/lib/collection-view/collection-view-source.js.map

@@ -1 +1 @@
-{"version":3,"file":"collection-view-source.js","sourceRoot":"","sources":["../../../src/lib/collection-view/collection-view-source.ts"],"names":[],"mappings":"AAeA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAkOvD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAA4B,EAC5B,KAAe,EACf,MAAoB;IAEpB,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AACjG,CAAC;AAiDD;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA4B;IACjE,OAAO,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE;QAClC,UAAU,EAAE,MAAM,CAAC,UAAU,KAAK,SAAS;QAC3C,UAAU,EAAE,MAAM,CAAC,UAAU,KAAK,SAAS;QAC3C,QAAQ,EAAE,MAAM,CAAC,YAAY,CAAC,OAAO;KACtC,CAAC,CAAA;AACJ,CAAC","sourcesContent":["import type {\n  CmsDocument,\n  CollectionDef,\n  DocumentRef,\n  DocumentUrl,\n  FieldDef,\n  Locale,\n  LocaleConfig,\n  LocalizedString,\n  RestoreScope,\n} from '@elytracms/core/cms-core'\nimport type { CmsValidationIssue } from '@elytracms/core/cms-core'\nimport type { OperationError } from '@elytracms/core/operations'\nimport type { ReferenceTarget } from '@elytracms/core/persistence'\nimport type { TableViewState } from '../cms-views/view-model'\nimport { pseudoColumns } from '../cms-views/view-model'\n// The concrete inline-edit + bulk vocabulary (Stream A relocates it into `lib` as it settles).\nimport type { CellCommitInput, CellCommitOutcome } from '../../components/cms/cell-edit'\nimport type { BulkAction, BulkReport, BulkSetField } from '../../components/cms/bulk-actions'\nimport type { DocumentVersionsView, ImportReport } from '../../components/cms/cms-store'\n\n/**\n * `CollectionViewSource` — the studio's UNIVERSAL interaction seam (EC-240,\n * vision AD-19).\n *\n * The list surface (`CollectionTable`) and the edit-shell (`DetailEditor`) are\n * the studio's universal interaction surfaces. Historically they read the\n * concrete `CmsStore` through `useCms()`, so they only served `cmsDocuments`.\n * This interface is the data-agnostic seam they render over instead, so the SAME\n * surfaces drive the users rail (EC-240), redirects (EC-303), the Components app\n * edit-shell, and any future rail — no hand-rolled UI per rail.\n *\n * **Shape:** the source is scoped to ONE collection (it carries `schema` +\n * `collectionId`), and its methods mirror the subset of `CmsStore` the surfaces\n * actually use — dropping the `collectionId` argument (the source already knows\n * it). Keeping the names/signatures aligned makes the CMS adapter a\n * behaviour-preserving pass-through and the migration near-mechanical.\n *\n * **Referential stability:** the surfaces put `documents`, `isPublished`,\n * `localeConfig`, etc. in `useMemo` dependency arrays. An implementation MUST\n * return stable references across renders (delegate to the underlying store's\n * already-stable methods; never wrap in a fresh closure each render) or memos\n * bust and the inline-edit order snapshot / perf regress.\n *\n * **Capabilities:** flags gate whole shell regions AND method presence — a source\n * with `capabilities.versions === false` (the users rail) never mounts the\n * Versions pane, so no `listVersions` read fires on credential records. Optional\n * method groups are present iff the flag is set.\n */\nexport interface CollectionViewSource {\n  /** The rail/collection this source serves. */\n  readonly collectionId: string\n  /** The schema lens: fields, form tabs/groups, `titleField`, display nouns. */\n  readonly schema: CollectionDef\n  /** Which regions/methods this source supports. */\n  readonly capabilities: CollectionViewCapabilities\n\n  /** The project scope (asset picker, published-pool queries). Absent in fixture sessions. */\n  readonly projectId?: string\n  /**\n   * The collection id assets live in (for a cell/field's `titleOf` label fallback\n   * when {@link resolveAsset} finds no record). Present only for sources that\n   * reference assets — a rail without assets (users) omits it.\n   */\n  readonly assetCollectionId?: string\n  /** The ambient locale lens (only meaningful when `capabilities.locales`). */\n  readonly localeConfig: LocaleConfig\n  readonly activeLocale: Locale\n\n  // --- Reads -----------------------------------------------------------------\n  /** The full row set (view mechanics filter/sort this client-side). */\n  documents(): CmsDocument[]\n  get(ref: DocumentRef): CmsDocument | undefined\n  /** A relation/asset target's display title (hides the string-vs-function `titleField`). */\n  titleOf(ref: DocumentRef): string\n  /**\n   * List the candidate records of a relation field's declared `target` collection\n   * — the pick-list for a relation picker (EC-072). References are first-class and\n   * collection-based: the field's schema declares which collection(s) it targets,\n   * and this resolves those rows for ANY target (cross-collection), not just this\n   * source's own collection. The caller passes `field.target`; a multi-target field\n   * (future) merges one call per declared target. An unknown/empty target yields `[]`.\n   */\n  referenceCandidates(collectionId: string): CmsDocument[]\n  /**\n   * The workspace schema a reference/asset can point at — the schema counterpart to\n   * {@link referenceCandidates}. Needed for the cases that read a TARGET collection's\n   * fields (an asset field editing the asset collection's own metadata; the reuse\n   * capability correlating embed manifests against their target collection). A\n   * reference is collection-based, so resolving one sometimes needs the target's\n   * schema, not just its rows.\n   */\n  readonly collections: readonly CollectionDef[]\n  isFieldReadOnly(field: FieldDef): boolean\n  /**\n   * Principal-based field access (EC-240, vision AD-18): `edit` (writable), `read`\n   * (visible but read-only), or `hidden` (not rendered for this principal). This is\n   * IDENTITY-driven and distinct from a field's content-conditional `hidden(values)`\n   * — e.g. an editor's own `role` resolves to `read`, a viewer never SEES a\n   * sensitive field (`hidden`). A single tri-state (never two independent flags) so\n   * the nonsensical writable-but-invisible state can't be expressed. Optional:\n   * absent ⇒ derived from {@link isFieldReadOnly} (`read`|`edit`), i.e. default-open\n   * (permissions RESTRICT, never grant a baseline). Per-rail policy lives on the\n   * source; the starter's policy flows into its construction (engine = mechanism).\n   * Prefer {@link resolveFieldAccess} over calling this directly (it applies the\n   * default-open fallback).\n   */\n  fieldAccess?(field: FieldDef, record?: CmsDocument): FieldAccess\n  validate(doc: CmsDocument): CmsValidationIssue[]\n  /**\n   * Resolve an asset id to its display metadata for a cell/field, or `undefined`\n   * when there is no asset backend (a source without assets degrades to a label\n   * via {@link titleOf}, matching today's \"no AssetsProvider\" behaviour).\n   */\n  resolveAsset?(id: string): ResolvedAsset | undefined\n  /**\n   * How this rail's records are addressed in the EC-155 reference index — the\n   * target shape the delete/unpublish confirmation's inbound pre-flight queries\n   * (EC-433). Absent ⇒ the document shape (`{ type: 'document', id: 'collection:id' }`),\n   * which every `cmsDocuments` collection uses. The assets rail supplies\n   * `{ type: 'asset' }` so its list/bulk delete confirmation enumerates the SAME\n   * inbound references its detail surface does — a document-shaped lookup would\n   * report a referenced asset as \"not referenced\" (the EC-319 objection that\n   * originally kept `remove` off the assets rail).\n   */\n  referenceTarget?(ref: DocumentRef): ReferenceTarget\n  /** The last failed/denied mutation, surfaced by the shell (never a silent failure). */\n  readonly lastError: OperationError | null\n  clearLastError(): void\n  /**\n   * Land any queued/optimistic writes so a subsequent pre-flight READ sees them\n   * (the reference index is maintained on write). A source with no async\n   * persistence omits it — its reads are already authoritative.\n   */\n  flush?(): Promise<void>\n\n  /**\n   * The studio route splat for a record's detail surface (the row link + the\n   * post-create navigation target), e.g. `studioPath.cmsDocument(collectionId, id)`.\n   * Rail-owned so the list never hard-codes the CMS route. `undefined` ⇒ the rail\n   * has no detail surface, so rows render as plain text (no navigation).\n   */\n  detailPath?(id: string): string\n  /**\n   * The studio route splat for this rail's LIST surface — the edit shell's\n   * \"back to list\" breadcrumb crumb and its post-delete navigation target, e.g.\n   * `studioPath.cmsCollection(collectionId)`. Rail-owned so the edit shell never\n   * hard-codes the CMS route (the counterpart to {@link detailPath}). `undefined`\n   * ⇒ the crumb is unlinked and delete falls back to the project index.\n   */\n  readonly listPath?: string\n\n  // --- View state (list) -----------------------------------------------------\n  viewState(): TableViewState\n  setViewState(update: TableViewState | ((prev: TableViewState) => TableViewState)): void\n\n  // --- Writes ----------------------------------------------------------------\n  create(): DocumentRef\n  save(doc: CmsDocument): void\n  remove(ref: DocumentRef): void\n  /**\n   * Bulk publish/unpublish/delete/set-field (only when `capabilities.bulk`): one\n   * command PER item, per-item outcomes enumerated in the report (partial failure\n   * is never silent).\n   */\n  bulk?(ids: readonly string[], action: BulkAction, setField?: BulkSetField): Promise<BulkReport>\n\n  // --- Capability method groups (present iff the matching flag is set) --------\n  /** `publish` — published-pool predicate + publish/unpublish. */\n  readonly publishing?: PublishingCapability\n  /**\n   * Per-document timestamps (EC-445) — the data behind the `$updatedAt`\n   * pseudo-column (and, once its data path lands, `$publishedAt`). Present iff the\n   * source materializes them (the CMS source, sourced through session-hydration);\n   * a rail that carries no timestamps omits it, so those pseudo-columns simply don't\n   * apply (see {@link pseudoColumnsForSource}). The accessor shape mirrors\n   * {@link PublishingCapability.isPublished} — a per-ref lookup, referentially stable.\n   */\n  readonly timestamps?: DocumentTimestampsCapability\n  /** `versions` — version history + restore. */\n  readonly versioning?: VersioningCapability\n  /** `inlineEdit` — the list's single-command optimistic cell write. */\n  readonly inlineEditing?: InlineEditCapability\n  /**\n   * Config-as-code named lenses (EC-246b) the header view selector switches\n   * between. Optional: a source that declares no named views (a non-CMS rail\n   * like users) omits it, and the selector renders nothing (single default).\n   */\n  readonly views?: NamedViewsCapability\n  /**\n   * `importExport` — JSON round-trip of the collection's records. CMS-specific;\n   * a rail whose records are credential-bearing (users) omits it, so neither the\n   * import dialog nor the export action mounts (identities aren't dumped to JSON).\n   */\n  readonly imports?: ImportCapability\n}\n\n/**\n * The capability matrix. Each flag gates a shell region AND the presence of its\n * method group. The **users rail** (EC-240) sets `publish:false`, `versions:false`\n * (credential caution), `create:false` (identity minted by sign-up), and no\n * `liveUrl`/`hierarchy`.\n */\nexport interface CollectionViewCapabilities {\n  readonly publish: boolean\n  readonly versions: boolean\n  readonly locales: boolean\n  readonly inlineEdit: boolean\n  readonly create: boolean\n  /**\n   * Duplicate-document action (EC-442, amended same day). Deliberately its own\n   * flag, never derived from `create`: the owner call (2026-07-17) is CMS\n   * collections ONLY — no primitive rail offers Duplicate for now (identities\n   * and uploads aren't copyable content; redirects deferred until requested as\n   * a product feature).\n   */\n  readonly duplicate: boolean\n  readonly remove: boolean\n  readonly bulk: boolean\n  /** The derived live-URL column (published pool × deployment routes). */\n  readonly liveUrl: boolean\n  /** Parent-self-relation tree mode (hierarchical collections only). */\n  readonly hierarchy: boolean\n  /** JSON import/export of the collection's records (off for credential rails). */\n  readonly importExport: boolean\n  /**\n   * The rail is administration-scoped (mirrors `ADMIN_ONLY_OPERATIONS`). The\n   * nav-permission layer reads this to gate the rail item. Absent ⇒ not admin-only.\n   */\n  readonly adminOnly?: boolean\n}\n\n/**\n * Principal-based field access (EC-240, AD-18). One tri-state drives BOTH visibility\n * and writability: `edit` (writable), `read` (visible, read-only), `hidden` (not\n * rendered). Default `edit` (default-open). Distinct from content-`hidden(values)`;\n * they compose — a field shows iff *not content-hidden AND access ≠ hidden*, and is\n * editable iff *access = edit AND not otherwise read-only* (published view, `form.readOnly`).\n */\nexport type FieldAccess = 'edit' | 'read' | 'hidden'\n\n/**\n * Resolve a field's effective principal access for a source — its {@link\n * CollectionViewSource.fieldAccess} policy when present, else derived from the\n * boolean `isFieldReadOnly` (default-open). The one place the shell asks \"may this\n * principal edit / see this field?\", so the default-open fallback lives in one spot.\n */\nexport function resolveFieldAccess(\n  source: CollectionViewSource,\n  field: FieldDef,\n  record?: CmsDocument,\n): FieldAccess {\n  return source.fieldAccess?.(field, record) ?? (source.isFieldReadOnly(field) ? 'read' : 'edit')\n}\n\n/** Asset display metadata a cell/field renders (thumbnail or labelled badge). */\nexport interface ResolvedAsset {\n  readonly url?: string\n  readonly contentType?: string\n  readonly title?: string\n  readonly filename?: string\n  readonly alt?: string\n}\n\n/** `publish` capability. */\nexport interface PublishingCapability {\n  /** Published-ness from the version pointer (NOT a row field). */\n  isPublished(ref: DocumentRef): boolean\n  /**\n   * Does this PUBLISHED document's working draft carry unpublished changes\n   * (EC-449)? The cheap per-row signal behind the amber \"changed\" `$state` dot —\n   * sourced from the MATERIALIZED `hasUnpublishedChanges` record flag (computed\n   * once at the write chokepoint), never a per-row snapshot compare. Optional: a\n   * source without the signal omits it, and the list derives only\n   * published/draft (exactly the pre-EC-449 rendering). Same referentially-stable\n   * per-ref accessor shape as {@link isPublished}.\n   */\n  hasUnpublishedChanges?(ref: DocumentRef): boolean\n  publish(ref: DocumentRef): Promise<void>\n  unpublish(ref: DocumentRef): Promise<void>\n  /**\n   * Live URLs for the routable documents, keyed by id — derived from the\n   * PUBLISHED pool (never draft rows) so an unpublished slug/parent edit can't\n   * leak into a live link (EC-205/EC-216). `null` when the collection is not\n   * routable → the live-URL column is hidden. Only present when `capabilities.liveUrl`.\n   */\n  liveUrls?(): Map<string, DocumentUrl> | null\n}\n\n/**\n * `timestamps` capability (EC-445/EC-447): per-document record timestamps as ISO\n * strings, or `undefined` when a document carries none. The `$updatedAt`/`$publishedAt`\n * pseudo-columns read + sort by these. `updatedAt` is the last-write instant;\n * `publishedAt` (EC-447) is the FIRST-publish instant — set-once on publish, cleared on\n * unpublish, so it is `undefined` for a draft / never-published / currently-unpublished\n * document (the column shows EmDash).\n */\nexport interface DocumentTimestampsCapability {\n  updatedAt(ref: DocumentRef): string | undefined\n  publishedAt(ref: DocumentRef): string | undefined\n}\n\n/**\n * The reserved pseudo-columns applicable to a source's list (EC-445), derived from\n * its capabilities: `$updatedAt` iff it materializes timestamps, `$state` iff it has a\n * publish lifecycle, `$url` iff it resolves delivery URLs. The one place the list\n * surface + the Display picker agree on which pseudo-columns exist for a source, so\n * the column universe never drifts between where columns render and where they toggle.\n */\nexport function pseudoColumnsForSource(source: CollectionViewSource): string[] {\n  return pseudoColumns(source.schema, {\n    timestamps: source.timestamps !== undefined,\n    publishing: source.publishing !== undefined,\n    routable: source.capabilities.liveUrl,\n  })\n}\n\n/** `versions` capability. */\nexport interface VersioningCapability {\n  restore(ref: DocumentRef, version: number, scope?: RestoreScope): Promise<CmsDocument | null>\n  /**\n   * The document's recorded version history + live pin. Folds the flush-before-read\n   * ordering INTO the loader (the adapter's concern), so every fetch lists an\n   * authoritative history regardless of which surface triggered the change (EC-224).\n   */\n  load(ref: DocumentRef): Promise<DocumentVersionsView>\n}\n\n/** `inlineEdit` capability: the list's single-command optimistic cell write (EC-168). */\nexport interface InlineEditCapability {\n  commitField(input: CellCommitInput): Promise<CellCommitOutcome>\n}\n\n/** A named lens the header selector offers — id + display name only (the header never needs its state). */\nexport interface NamedView {\n  readonly id: string\n  /** Display name; a {@link LocalizedString} (EC-343), resolved at the render site like `form.label`. */\n  readonly name: LocalizedString\n}\n\n/** `importExport` capability: validate + fold external JSON records into the collection (EC-079). */\nexport interface ImportCapability {\n  importDocuments(items: unknown[]): ImportReport\n}\n\n/**\n * `views` capability: config-as-code named lenses (EC-246b). The header selector\n * only *picks* a lens — it never creates/edits/deletes one (shared views are code).\n */\nexport interface NamedViewsCapability {\n  /** The built-in default + config-declared named views. */\n  list(): readonly NamedView[]\n  /** The currently-selected view id. */\n  activeId(): string\n  /** Switch views (resets the working table state to the view's baseline). */\n  setActive(id: string): void\n}\n\nexport type { CellCommitInput, CellCommitOutcome, ImportReport }\n"]}
+{"version":3,"file":"collection-view-source.js","sourceRoot":"","sources":["../../../src/lib/collection-view/collection-view-source.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAA;AAmSvD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAChC,MAA4B,EAC5B,KAAe,EACf,MAAoB;IAEpB,OAAO,MAAM,CAAC,WAAW,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAA;AACjG,CAAC;AAqDD;;;;;;GAMG;AACH,MAAM,UAAU,sBAAsB,CAAC,MAA4B;IACjE,OAAO,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE;QAClC,UAAU,EAAE,MAAM,CAAC,UAAU,KAAK,SAAS;QAC3C,UAAU,EAAE,MAAM,CAAC,UAAU,KAAK,SAAS;QAC3C,QAAQ,EAAE,MAAM,CAAC,YAAY,CAAC,OAAO;KACtC,CAAC,CAAA;AACJ,CAAC","sourcesContent":["import type {\n  CmsDocument,\n  CollectionDef,\n  DocumentPatch,\n  DocumentRef,\n  ValuePath,\n  DocumentUrl,\n  FieldDef,\n  Locale,\n  LocaleConfig,\n  LocalizedString,\n  RestoreScope,\n} from '@elytracms/core/cms-core'\nimport type { CmsValidationIssue } from '@elytracms/core/cms-core'\nimport type { OperationError } from '@elytracms/core/operations'\nimport type { CmsDocumentRecord, PresenceEntry, ReferenceTarget } from '@elytracms/core/persistence'\nimport type { CommitOutcome, DocumentConflict } from '../operations/cms-persistence'\nimport type { TableViewState } from '../cms-views/view-model'\nimport { pseudoColumns } from '../cms-views/view-model'\n// The concrete inline-edit + bulk vocabulary (Stream A relocates it into `lib` as it settles).\nimport type { CellCommitInput, CellCommitOutcome } from '../../components/cms/cell-edit'\nimport type { BulkAction, BulkReport, BulkSetField } from '../../components/cms/bulk-actions'\nimport type { DocumentVersionsView, ImportReport } from '../../components/cms/cms-store'\n\n/**\n * `CollectionViewSource` — the studio's UNIVERSAL interaction seam (EC-240,\n * vision AD-19).\n *\n * The list surface (`CollectionTable`) and the edit-shell (`DetailEditor`) are\n * the studio's universal interaction surfaces. Historically they read the\n * concrete `CmsStore` through `useCms()`, so they only served `cmsDocuments`.\n * This interface is the data-agnostic seam they render over instead, so the SAME\n * surfaces drive the users rail (EC-240), redirects (EC-303), the Components app\n * edit-shell, and any future rail — no hand-rolled UI per rail.\n *\n * **Shape:** the source is scoped to ONE collection (it carries `schema` +\n * `collectionId`), and its methods mirror the subset of `CmsStore` the surfaces\n * actually use — dropping the `collectionId` argument (the source already knows\n * it). Keeping the names/signatures aligned makes the CMS adapter a\n * behaviour-preserving pass-through and the migration near-mechanical.\n *\n * **Referential stability:** the surfaces put `documents`, `isPublished`,\n * `localeConfig`, etc. in `useMemo` dependency arrays. An implementation MUST\n * return stable references across renders (delegate to the underlying store's\n * already-stable methods; never wrap in a fresh closure each render) or memos\n * bust and the inline-edit order snapshot / perf regress.\n *\n * **Capabilities:** flags gate whole shell regions AND method presence — a source\n * with `capabilities.versions === false` (the users rail) never mounts the\n * Versions pane, so no `listVersions` read fires on credential records. Optional\n * method groups are present iff the flag is set.\n */\nexport interface CollectionViewSource {\n  /** The rail/collection this source serves. */\n  readonly collectionId: string\n  /** The schema lens: fields, form tabs/groups, `titleField`, display nouns. */\n  readonly schema: CollectionDef\n  /** Which regions/methods this source supports. */\n  readonly capabilities: CollectionViewCapabilities\n\n  /** The project scope (asset picker, published-pool queries). Absent in fixture sessions. */\n  readonly projectId?: string\n  /**\n   * The collection id assets live in (for a cell/field's `titleOf` label fallback\n   * when {@link resolveAsset} finds no record). Present only for sources that\n   * reference assets — a rail without assets (users) omits it.\n   */\n  readonly assetCollectionId?: string\n  /** The ambient locale lens (only meaningful when `capabilities.locales`). */\n  readonly localeConfig: LocaleConfig\n  readonly activeLocale: Locale\n\n  // --- Reads -----------------------------------------------------------------\n  /** The full row set (view mechanics filter/sort this client-side). */\n  documents(): CmsDocument[]\n  get(ref: DocumentRef): CmsDocument | undefined\n  /** A relation/asset target's display title (hides the string-vs-function `titleField`). */\n  titleOf(ref: DocumentRef): string\n  /**\n   * List the candidate records of a relation field's declared `target` collection\n   * — the pick-list for a relation picker (EC-072). References are first-class and\n   * collection-based: the field's schema declares which collection(s) it targets,\n   * and this resolves those rows for ANY target (cross-collection), not just this\n   * source's own collection. The caller passes `field.target`; a multi-target field\n   * (future) merges one call per declared target. An unknown/empty target yields `[]`.\n   */\n  referenceCandidates(collectionId: string): CmsDocument[]\n  /**\n   * The workspace schema a reference/asset can point at — the schema counterpart to\n   * {@link referenceCandidates}. Needed for the cases that read a TARGET collection's\n   * fields (an asset field editing the asset collection's own metadata; the reuse\n   * capability correlating embed manifests against their target collection). A\n   * reference is collection-based, so resolving one sometimes needs the target's\n   * schema, not just its rows.\n   */\n  readonly collections: readonly CollectionDef[]\n  isFieldReadOnly(field: FieldDef): boolean\n  /**\n   * Principal-based field access (EC-240, vision AD-18): `edit` (writable), `read`\n   * (visible but read-only), or `hidden` (not rendered for this principal). This is\n   * IDENTITY-driven and distinct from a field's content-conditional `hidden(values)`\n   * — e.g. an editor's own `role` resolves to `read`, a viewer never SEES a\n   * sensitive field (`hidden`). A single tri-state (never two independent flags) so\n   * the nonsensical writable-but-invisible state can't be expressed. Optional:\n   * absent ⇒ derived from {@link isFieldReadOnly} (`read`|`edit`), i.e. default-open\n   * (permissions RESTRICT, never grant a baseline). Per-rail policy lives on the\n   * source; the starter's policy flows into its construction (engine = mechanism).\n   * Prefer {@link resolveFieldAccess} over calling this directly (it applies the\n   * default-open fallback).\n   */\n  fieldAccess?(field: FieldDef, record?: CmsDocument): FieldAccess\n  validate(doc: CmsDocument): CmsValidationIssue[]\n  /**\n   * Resolve an asset id to its display metadata for a cell/field, or `undefined`\n   * when there is no asset backend (a source without assets degrades to a label\n   * via {@link titleOf}, matching today's \"no AssetsProvider\" behaviour).\n   */\n  resolveAsset?(id: string): AssetDisplay | undefined\n  /**\n   * How this rail's records are addressed in the EC-155 reference index — the\n   * target shape the delete/unpublish confirmation's inbound pre-flight queries\n   * (EC-433). Absent ⇒ the document shape (`{ type: 'document', id: 'collection:id' }`),\n   * which every `cmsDocuments` collection uses. The assets rail supplies\n   * `{ type: 'asset' }` so its list/bulk delete confirmation enumerates the SAME\n   * inbound references its detail surface does — a document-shaped lookup would\n   * report a referenced asset as \"not referenced\" (the EC-319 objection that\n   * originally kept `remove` off the assets rail).\n   */\n  referenceTarget?(ref: DocumentRef): ReferenceTarget\n  /** The last failed/denied mutation, surfaced by the shell (never a silent failure). */\n  readonly lastError: OperationError | null\n  clearLastError(): void\n  /**\n   * Land any queued/optimistic writes so a subsequent pre-flight READ sees them\n   * (the reference index is maintained on write). A source with no async\n   * persistence omits it — its reads are already authoritative.\n   */\n  flush?(): Promise<void>\n\n  /**\n   * The studio route splat for a record's detail surface (the row link + the\n   * post-create navigation target), e.g. `studioPath.cmsDocument(collectionId, id)`.\n   * Rail-owned so the list never hard-codes the CMS route. `undefined` ⇒ the rail\n   * has no detail surface, so rows render as plain text (no navigation).\n   */\n  detailPath?(id: string): string\n  /**\n   * The studio route splat for this rail's LIST surface — the edit shell's\n   * \"back to list\" breadcrumb crumb and its post-delete navigation target, e.g.\n   * `studioPath.cmsCollection(collectionId)`. Rail-owned so the edit shell never\n   * hard-codes the CMS route (the counterpart to {@link detailPath}). `undefined`\n   * ⇒ the crumb is unlinked and delete falls back to the project index.\n   */\n  readonly listPath?: string\n\n  // --- View state (list) -----------------------------------------------------\n  viewState(): TableViewState\n  setViewState(update: TableViewState | ((prev: TableViewState) => TableViewState)): void\n\n  // --- Writes ----------------------------------------------------------------\n  create(): DocumentRef\n  /**\n   * EC-595 A2 — HOW this source's records are written: exactly one model per source,\n   * so a surface can never write a revisioned document the record way or vice versa.\n   * `record` — the explicit-save rails (users, redirects, assets, the account): the\n   * editor's Save button hands the whole record over. `document` — the CMS: every\n   * writer emits patches at its source, committed on quiescence and merged per path\n   * at the store; the editor shows per-field conflicts and follows the subscription.\n   */\n  readonly writes: CollectionWrites\n  remove(ref: DocumentRef): void\n  /**\n   * Bulk publish/unpublish/delete/set-field (only when `capabilities.bulk`): one\n   * command PER item, per-item outcomes enumerated in the report (partial failure\n   * is never silent).\n   */\n  bulk?(ids: readonly string[], action: BulkAction, setField?: BulkSetField): Promise<BulkReport>\n\n  // --- Capability method groups (present iff the matching flag is set) --------\n  /** `publish` — published-pool predicate + publish/unpublish. */\n  readonly publishing?: PublishingCapability\n  /**\n   * Per-document timestamps (EC-445) — the data behind the `$updatedAt`\n   * pseudo-column (and, once its data path lands, `$publishedAt`). Present iff the\n   * source materializes them (the CMS source, sourced through session-hydration);\n   * a rail that carries no timestamps omits it, so those pseudo-columns simply don't\n   * apply (see {@link pseudoColumnsForSource}). The accessor shape mirrors\n   * {@link PublishingCapability.isPublished} — a per-ref lookup, referentially stable.\n   */\n  readonly timestamps?: DocumentTimestampsCapability\n  /** `versions` — version history + restore. */\n  readonly versioning?: VersioningCapability\n  /** `inlineEdit` — the list's single-command optimistic cell write. */\n  readonly inlineEditing?: InlineEditCapability\n  /**\n   * Config-as-code named lenses (EC-246b) the header view selector switches\n   * between. Optional: a source that declares no named views (a non-CMS rail\n   * like users) omits it, and the selector renders nothing (single default).\n   */\n  readonly views?: NamedViewsCapability\n  /**\n   * `importExport` — JSON round-trip of the collection's records. CMS-specific;\n   * a rail whose records are credential-bearing (users) omits it, so neither the\n   * import dialog nor the export action mounts (identities aren't dumped to JSON).\n   */\n  readonly imports?: ImportCapability\n}\n\n/** EC-595 A2 — the write model of a source (see {@link CollectionViewSource.writes}). */\nexport type CollectionWrites = RecordWrites | DocumentWrites\n\n/** An explicit-save rail: the editor's Save button writes the whole record. */\nexport interface RecordWrites {\n  readonly kind: 'record'\n  save(doc: CmsDocument): void\n}\n\n/**\n * The revisioned-document write model (EC-595, ratified 2026-10-24): patches at the\n * source, the persister's queue, per-field conflicts, the document subscription.\n */\nexport interface DocumentWrites {\n  readonly kind: 'document'\n  /**\n   * Commit the patches a writer made; resolves once acknowledged (`undefined` in a\n   * fixture session). `bases` — per patch, the revision the edit was started at.\n   */\n  commit(\n    ref: DocumentRef,\n    patches: readonly DocumentPatch[],\n    bases?: readonly (number | undefined)[],\n  ): Promise<CommitOutcome | undefined>\n  /** The revision the session's view of a document is at. */\n  revisionOf(ref: DocumentRef): number | undefined\n  /** Create a document from a whole value (insert-if-absent): duplicate. */\n  insert(doc: CmsDocument): void\n  /** A fresh document id from the session's injected factory (EC-578). */\n  newId(): string\n  /** The open per-field conflicts on a document. */\n  conflicts(ref: DocumentRef): readonly DocumentConflict[]\n  resolveConflict(ref: DocumentRef, conflictId: string, choice: 'theirs' | 'mine'): void\n  /** Adopt a row the document subscription pushed (local edits win on their paths until flushed). */\n  adoptSnapshot(ref: DocumentRef, record: CmsDocumentRecord | undefined): void\n  /** The forced flush's persistence half: await every queued write of the document. */\n  flush(ref: DocumentRef): Promise<void>\n  /**\n   * Write the whole document at the revision the session holds (a document-level key\n   * the value-position grammar has no position for — the slot `alias`). A move since\n   * is refused, never overwritten.\n   */\n  replace(doc: CmsDocument): void\n  /**\n   * EC-595 point 7 — follow ONE document while it is open: every pushed row is adopted\n   * under the local edits (the editor rebases), and the presence on it is delivered to\n   * `onPresence`. Returns the unsubscribe function.\n   */\n  subscribe(ref: DocumentRef, onPresence: (presence: readonly PresenceEntry[]) => void): () => void\n  /** Thin presence (Stage A): this session is on the document, in `path`'s field (or on no field). */\n  reportPresence(ref: DocumentRef, path: ValuePath | undefined): void\n  /** This session left the document. */\n  clearPresence(ref: DocumentRef): void\n  /** This session's presence id (one per tab), so the editor can leave itself out. */\n  readonly presenceSessionId: string\n}\n\n/**\n * The capability matrix. Each flag gates a shell region AND the presence of its\n * method group. The **users rail** (EC-240) sets `publish:false`, `versions:false`\n * (credential caution), `create:false` (identity minted by sign-up), and no\n * `liveUrl`/`hierarchy`.\n */\nexport interface CollectionViewCapabilities {\n  readonly publish: boolean\n  readonly versions: boolean\n  readonly locales: boolean\n  readonly inlineEdit: boolean\n  readonly create: boolean\n  /**\n   * Duplicate-document action (EC-442, amended same day). Deliberately its own\n   * flag, never derived from `create`: the owner call (2026-07-17) is CMS\n   * collections ONLY — no primitive rail offers Duplicate for now (identities\n   * and uploads aren't copyable content; redirects deferred until requested as\n   * a product feature).\n   */\n  readonly duplicate: boolean\n  readonly remove: boolean\n  readonly bulk: boolean\n  /** The derived live-URL column (published pool × deployment routes). */\n  readonly liveUrl: boolean\n  /** Parent-self-relation tree mode (hierarchical collections only). */\n  readonly hierarchy: boolean\n  /** JSON import/export of the collection's records (off for credential rails). */\n  readonly importExport: boolean\n  /**\n   * The rail is administration-scoped (mirrors `ADMIN_ONLY_OPERATIONS`). The\n   * nav-permission layer reads this to gate the rail item. Absent ⇒ not admin-only.\n   */\n  readonly adminOnly?: boolean\n}\n\n/**\n * Principal-based field access (EC-240, AD-18). One tri-state drives BOTH visibility\n * and writability: `edit` (writable), `read` (visible, read-only), `hidden` (not\n * rendered). Default `edit` (default-open). Distinct from content-`hidden(values)`;\n * they compose — a field shows iff *not content-hidden AND access ≠ hidden*, and is\n * editable iff *access = edit AND not otherwise read-only* (published view, `form.readOnly`).\n */\nexport type FieldAccess = 'edit' | 'read' | 'hidden'\n\n/**\n * Resolve a field's effective principal access for a source — its {@link\n * CollectionViewSource.fieldAccess} policy when present, else derived from the\n * boolean `isFieldReadOnly` (default-open). The one place the shell asks \"may this\n * principal edit / see this field?\", so the default-open fallback lives in one spot.\n */\nexport function resolveFieldAccess(\n  source: CollectionViewSource,\n  field: FieldDef,\n  record?: CmsDocument,\n): FieldAccess {\n  return source.fieldAccess?.(field, record) ?? (source.isFieldReadOnly(field) ? 'read' : 'edit')\n}\n\n/**\n * Asset display metadata a cell/field renders (thumbnail or labelled badge). EC-587:\n * named apart from core's `ResolvedAsset` (the delivery shape) — this is the studio's\n * label/thumbnail slice; its `alt` is the one reader's (`assetAlt`).\n */\nexport interface AssetDisplay {\n  readonly url?: string\n  readonly contentType?: string\n  readonly title?: string\n  readonly filename?: string\n  readonly alt?: string\n}\n\n/** `publish` capability. */\nexport interface PublishingCapability {\n  /** Published-ness from the version pointer (NOT a row field). */\n  isPublished(ref: DocumentRef): boolean\n  /**\n   * Does this PUBLISHED document's working draft carry unpublished changes\n   * (EC-449)? The cheap per-row signal behind the amber \"changed\" `$state` dot —\n   * sourced from the MATERIALIZED `hasUnpublishedChanges` record flag (computed\n   * once at the write chokepoint), never a per-row snapshot compare. Optional: a\n   * source without the signal omits it, and the list derives only\n   * published/draft (exactly the pre-EC-449 rendering). Same referentially-stable\n   * per-ref accessor shape as {@link isPublished}.\n   */\n  hasUnpublishedChanges?(ref: DocumentRef): boolean\n  publish(ref: DocumentRef): Promise<void>\n  unpublish(ref: DocumentRef): Promise<void>\n  /**\n   * Live URLs for the routable documents, keyed by id — derived from the\n   * PUBLISHED pool (never draft rows) so an unpublished slug/parent edit can't\n   * leak into a live link (EC-205/EC-216). `null` when the collection is not\n   * routable → the live-URL column is hidden. Only present when `capabilities.liveUrl`.\n   */\n  liveUrls?(): Map<string, DocumentUrl> | null\n}\n\n/**\n * `timestamps` capability (EC-445/EC-447): per-document record timestamps as ISO\n * strings, or `undefined` when a document carries none. The `$updatedAt`/`$publishedAt`\n * pseudo-columns read + sort by these. `updatedAt` is the last-write instant;\n * `publishedAt` (EC-447) is the FIRST-publish instant — set-once on publish, cleared on\n * unpublish, so it is `undefined` for a draft / never-published / currently-unpublished\n * document (the column shows EmDash).\n */\nexport interface DocumentTimestampsCapability {\n  updatedAt(ref: DocumentRef): string | undefined\n  publishedAt(ref: DocumentRef): string | undefined\n}\n\n/**\n * The reserved pseudo-columns applicable to a source's list (EC-445), derived from\n * its capabilities: `$updatedAt` iff it materializes timestamps, `$state` iff it has a\n * publish lifecycle, `$url` iff it resolves delivery URLs. The one place the list\n * surface + the Display picker agree on which pseudo-columns exist for a source, so\n * the column universe never drifts between where columns render and where they toggle.\n */\nexport function pseudoColumnsForSource(source: CollectionViewSource): string[] {\n  return pseudoColumns(source.schema, {\n    timestamps: source.timestamps !== undefined,\n    publishing: source.publishing !== undefined,\n    routable: source.capabilities.liveUrl,\n  })\n}\n\n/** `versions` capability. */\nexport interface VersioningCapability {\n  restore(ref: DocumentRef, version: number, scope?: RestoreScope): Promise<CmsDocument | null>\n  /**\n   * The document's recorded version history + live pin. Folds the flush-before-read\n   * ordering INTO the loader (the adapter's concern), so every fetch lists an\n   * authoritative history regardless of which surface triggered the change (EC-224).\n   */\n  load(ref: DocumentRef): Promise<DocumentVersionsView>\n}\n\n/** `inlineEdit` capability: the list's single-command optimistic cell write (EC-168). */\nexport interface InlineEditCapability {\n  commitField(input: CellCommitInput): Promise<CellCommitOutcome>\n}\n\n/** A named lens the header selector offers — id + display name only (the header never needs its state). */\nexport interface NamedView {\n  readonly id: string\n  /** Display name; a {@link LocalizedString} (EC-343), resolved at the render site like `form.label`. */\n  readonly name: LocalizedString\n}\n\n/** `importExport` capability: validate + fold external JSON records into the collection (EC-079). */\nexport interface ImportCapability {\n  importDocuments(items: unknown[]): ImportReport\n}\n\n/**\n * `views` capability: config-as-code named lenses (EC-246b). The header selector\n * only *picks* a lens — it never creates/edits/deletes one (shared views are code).\n */\nexport interface NamedViewsCapability {\n  /** The built-in default + config-declared named views. */\n  list(): readonly NamedView[]\n  /** The currently-selected view id. */\n  activeId(): string\n  /** Switch views (resets the working table state to the view's baseline). */\n  setActive(id: string): void\n}\n\nexport type { CellCommitInput, CellCommitOutcome, ImportReport }\n"]}

package/dist/lib/data/collection-content.d.ts

@@ -1,5 +1,5 @@
 import type { ContentQueryError, GetDocumentResult, ListDocumentsQuery, ListDocumentsResult, ResolvedDocument } from '@elytracms/core/content';
-import type { CmsDocument, CollectionDef, DocumentRef, Locale, LocaleConfig, OrphanedCollection, RouteRecord } from '@elytracms/core/cms-core';
+import type { CmsDocument, CollectionDef, DocumentRef, Locale, LocaleConfig, OrphanedCollection, Perspective, RouteRecord } from '@elytracms/core/cms-core';
 import type { AssetRecord } from '@elytracms/core/persistence';
 import type { ListingQuery } from '@elytracms/core/runtime-renderer';
 import type { Clock } from '@elytracms/core/determinism';
@@ -80,15 +80,6 @@ export interface ContentSessionState {
  * the same loader.
  */
 export declare const playgroundCollections: readonly CollectionDef[];
-/**
- * The perspective a canvas preview resolves references against (EC-300/AD-16). The
- * canvas is draft-coherent: the editable Draft view resolves references to their
- * `'draft'` targets (so a just-made reusable shows immediately), the read-only
- * Published view resolves `'published'` (an honest preview of what delivery serves;
- * an unpublished hard ref shows the in-canvas placeholder). Delivery stays
- * published-only — this does not weaken `live-is-published-only`.
- */
-export type CanvasPerspective = 'draft' | 'published';
 /** The current content-session epoch — bumps on every `configureContentSession`. */
 export declare function contentSessionEpoch(): number;
 /**
@@ -142,7 +133,7 @@ export declare function getCollectionDocument(collectionId: string, idOrSlug: st
  * Reusable's element) exactly as delivery renders them. `null` when the target is
  * missing or not visible → the block degrades to its own empty state.
  */
-export declare function resolveCanvasRelation(ref: DocumentRef, locale?: Locale, perspective?: CanvasPerspective): ResolvedDocument | null;
+export declare function resolveCanvasRelation(ref: DocumentRef, locale?: Locale, perspective?: Perspective): ResolvedDocument | null;
 /**
  * Resolve a listing block's query to its documents for the canvas (EC-255) — the
  * studio analog of the host's baked listings map. Runs the query (collection +
@@ -154,7 +145,7 @@ export declare function resolveCanvasRelation(ref: DocumentRef, locale?: Locale,
  * ({@link validateCanvasListingQuery}) says why. Reuses the same `listDocuments`
  * path as `runCollectionListQuery`.
  */
-export declare function resolveCanvasListing(query: ListingQuery, locale?: Locale, perspective?: CanvasPerspective, clock?: Clock): ResolvedDocument[];
+export declare function resolveCanvasListing(query: ListingQuery, locale?: Locale, perspective?: Perspective, clock?: Clock): ResolvedDocument[];
 /**
  * Statically validate a listing block's query against the ACTIVE session schema
  * (EC-460, the never-silent rule): the exact `validateWhere`/`validateSort`/
@@ -175,7 +166,7 @@ export declare function validateCanvasListingQuery(query: ListingQuery, clock?:
  * no route → the rich-text renderer shows the EC-290 `unresolved-ref` issue. Reuses
  * the same `resolveLink` path as the host bake, so both agree on the derived URL.
  */
-export declare function resolveCanvasLink(ref: DocumentRef, locale?: Locale, perspective?: CanvasPerspective): string | null;
+export declare function resolveCanvasLink(ref: DocumentRef, locale?: Locale, perspective?: Perspective): string | null;
 /** A pickable entry of a collection (the template-page preview switcher). */
 export interface CollectionEntrySummary {
     id: string;

package/dist/lib/data/collection-content.js

@@ -1,5 +1,5 @@
 import { createContentClient, createContentContext, queryError, validateLimit, validateSort, validateWhere, } from '@elytracms/core/content';
-import { documentKey, localeSchema, parseLocaleConfig, resolveDocumentTitle, valuesInLocale, } from '@elytracms/core/cms-core';
+import { documentKey, localeSchema, parseLocaleConfig, perspectiveKey, resolveDocumentTitle, valuesInLocale, } from '@elytracms/core/cms-core';
 import { listingRequestOf } from '@elytracms/core/runtime-renderer';
 import { getStudioLocale, getStudioLocaleConfig } from '../locale/locale-store.js';
 /**
@@ -149,7 +149,7 @@ export function withPlaygroundFilterable(collections) {
 }
 /**
  * Synthesize the persistence-shaped asset record the asset resolver reads. EC-580:
- * the record's single `alt` is the DEFAULT locale's displayed value
+ * the record's single alt (`meta.alt`, EC-587) is the DEFAULT locale's displayed value
  * (`valuesInLocale`, the project's config default) — it used to read
  * `localized.en.alt` whatever the project's locales were (MODE F5b, "further
  * evidence"), so a `de`-default project's previews had no alt and a shared `alt`
@@ -167,7 +167,8 @@ function assetRecordOf(doc, collection, locales) {
         filename: typeof values.filename === 'string' ? values.filename : doc.id,
         contentType: 'image/png',
         byteSize: 0,
-        alt: typeof alt === 'string' ? alt : undefined,
+        // EC-587: an asset's alt lives in `meta` (its one home), never the legacy column.
+        ...(typeof alt === 'string' ? { meta: { alt } } : {}),
         storageKey: typeof values.url === 'string' ? values.url : doc.id,
         createdAt: '2026-01-01T00:00:00.000Z',
         updatedAt: '2026-01-01T00:00:00.000Z',
@@ -219,7 +220,12 @@ function createLookup(collectionDefs, documents, publishedKeys, assetRecords, lo
 }
 /**
  * One deterministic client per (locale, perspective): EC-018 locale fallback,
- * draft-or-published perspective (EC-300/AD-16, default `'published'`). The studio's
+ * draft-or-published perspective (EC-300/AD-16, default `'published'`). The canvas is
+ * draft-coherent: the editable Draft view resolves references against the draft
+ * perspective (`DRAFT_PERSPECTIVE` — a just-made reusable shows immediately), the
+ * read-only Published view against `'published'` (an honest preview of what delivery
+ * serves; an unpublished hard ref shows the in-canvas placeholder). Delivery stays
+ * published-only — this does not weaken `live-is-published-only`. The studio's
  * ambient active locale (EC-176, `lib/locale`) picks the locale at query time, so the
  * canvas previews follow the locale switcher exactly like delivery would; the canvas's
  * Draft/Published view picks the perspective. The cache resets whenever the content
@@ -231,7 +237,7 @@ function clientFor(locale, perspective = 'published') {
     // from the ambient studio store, which changes independently of the session the
     // cache is cleared on, so keying by locale alone could serve a client built
     // against a superseded locale set.
-    const key = `${locale}:${perspective}:${locales.default}|${locales.locales.join(',')}`;
+    const key = `${locale}:${perspectiveKey(perspective)}:${locales.default}|${locales.locales.join(',')}`;
     const existing = clients.get(key);
     if (existing)
         return existing;