@elytracms/studio 0.0.94 → 0.0.96

package/dist/lib/assets/upload.d.ts

@@ -1,4 +1,4 @@
-import type { FieldDef } from '@elytracms/core/cms-core';
+import type { FieldDef, Locale } from '@elytracms/core/cms-core';
 import type { AssetRecord, AssetRepository, AssetWriteInput, BlobStorageAdapter } from '@elytracms/core/persistence';
 import type { ImageDimensions } from './image-dimensions.js';
 import type { GeneratedVariants } from './thumbnail.js';
@@ -35,6 +35,15 @@ export interface UploadDeps {
      * written (a field without `source` is never filled).
      */
     assetFields?: readonly FieldDef[];
+    /**
+     * The project's locales (EC-632): a `localized: true` asset field's embedded value goes
+     * to the locale buckets — each locale its `xml:lang` alternative, the default the
+     * `x-default` reading. Absent → every field is written to the shared `meta`.
+     */
+    locales?: {
+        readonly default: Locale;
+        readonly locales: readonly Locale[];
+    };
     /** Client-direct transport; only used when `blobs.createUploadUrl` exists. */
     transport?: UploadTransport;
     /** Injectable dimension detection; defaults to `createImageBitmap`-based. */
@@ -79,16 +88,25 @@ export type UploadResult = {
  * previous `state` to retry (the attempt counter carries over).
  */
 export declare function runUpload(deps: UploadDeps, request: UploadRequest, previous?: UploadState): Promise<UploadResult>;
+/** What a file's embedded facts write (EC-568 → EC-632): shared `meta` keys, and per-locale buckets of the localized fields. */
+export interface EmbeddedAssetWrite {
+    meta: Record<string, unknown>;
+    localizedMeta: Record<string, Record<string, unknown>>;
+}
 /**
  * The write of a file REPLACE (EC-568, the owner's ruling: "override the values with
  * available metadata, or keep the existing if no metadata is available"):
  * - the bytes' columns are SET — and a derived column the new file does not have is
  *   CLEARED (`null`), so an old thumb, lqip or dimension never outlives its file;
- * - `meta` is the stored bag (a legacy `alt` column lifted in, EC-587) with each key the
- *   new file brings overridden; written only when the file brings something, and then
- *   the legacy column is cleared, as every `meta` write does;
- * - the id, the focal point, the title and every other column are absent → kept.
+ * - each `meta` key the new file brings is a per-key `metaPatch` (EC-634), applied to the
+ *   bag as STORED inside the write — never a copy read before the upload, so an editor's
+ *   metadata save that lands while the bytes travel is kept. Sent only when the file
+ *   brings something; the write rule then lifts a legacy `alt` column into the bag and
+ *   clears it (EC-587), as for every patch;
+ * - the id, the focal point, the title and every other column are absent → kept;
+ * - `mustExist`: the write only updates the stored asset — gone (deleted meanwhile), it is
+ *   refused inside the write and nothing is created.
  */
-export declare function replaceWrite(stored: AssetRecord, derived: Pick<AssetRecord, 'filename' | 'contentType' | 'byteSize' | 'storageKey'> & {
+export declare function replaceWrite(assetId: string, derived: Pick<AssetRecord, 'filename' | 'contentType' | 'byteSize' | 'storageKey'> & {
     url: string;
-}, dimensions: ImageDimensions | undefined, variants: GeneratedVariants, embedded: Record<string, unknown>): AssetWriteInput;
+}, dimensions: ImageDimensions | undefined, variants: GeneratedVariants, embedded: EmbeddedAssetWrite): AssetWriteInput;

package/dist/lib/assets/upload.js

@@ -1,5 +1,4 @@
-import { embeddedMetaValues, readEmbeddedMetadata } from '@elytracms/core/cms-core';
-import { liftLegacyAlt } from '@elytracms/core/persistence';
+import { embeddedAssetMeta, readEmbeddedMetadata } from '@elytracms/core/cms-core';
 import { detectImageDimensions } from './image-dimensions.js';
 import { generateVariants } from './thumbnail.js';
 import { initialUploadState, uploadReducer } from './upload-state.js';
@@ -123,7 +122,7 @@ export async function runUpload(deps, request, previous) {
     // --- confirm: metadata record linked to the stored blob --------------------
     try {
         // EC-568: the ONE embedded-metadata reader, for a first upload and a replace alike.
-        const embedded = await embeddedAssetMeta(file, deps.assetFields);
+        const embedded = await embeddedMetaOf(file, deps.assetFields, deps.locales);
         const detect = deps.detectDimensions ?? defaultDetectDimensions;
         const dimensions = await detect(file);
         // EC-400 + EC-420: produce the thumb + lqip previews from the bytes already in
@@ -147,10 +146,10 @@ export async function runUpload(deps, request, previous) {
         };
         let write;
         if (request.replace) {
-            const stored = await assets.findAsset(projectId, request.replace.assetId);
-            if (!stored)
-                throw new Error(`No asset “${request.replace.assetId}” is stored to replace the file of.`);
-            write = replaceWrite(stored, derived, dimensions, variants, embedded);
+            // A replace edits an asset, never creates one — decided by the write itself
+            // (`mustExist`), against the row as it is when the write lands: a delete by another
+            // session in the meantime makes the write fail here, visibly, and creates nothing.
+            write = replaceWrite(request.replace.assetId, derived, dimensions, variants, embedded);
         }
         else {
             write = {
@@ -158,7 +157,8 @@ export async function runUpload(deps, request, previous) {
                 ...(dimensions ? { width: dimensions.width, height: dimensions.height } : {}),
                 ...(variants.thumb ? { thumb: variants.thumb } : {}),
                 ...(variants.lqip ? { lqip: variants.lqip } : {}),
-                ...(Object.keys(embedded).length > 0 ? { meta: embedded } : {}),
+                ...(Object.keys(embedded.meta).length > 0 ? { meta: embedded.meta } : {}),
+                ...(Object.keys(embedded.localizedMeta).length > 0 ? { localizedMeta: embedded.localizedMeta } : {}),
             };
         }
         const asset = await assets.upsertAsset(projectId, write);
@@ -175,14 +175,15 @@ export async function runUpload(deps, request, previous) {
  * bytes, mapped through the asset collection's `source` declarations. A file that cannot
  * be read yields `{}` — metadata never fails an upload.
  */
-async function embeddedAssetMeta(file, fields) {
+async function embeddedMetaOf(file, fields, locales) {
+    const none = { meta: {}, localizedMeta: {} };
     if (!fields || !fields.some((field) => field.source !== undefined))
-        return {};
+        return none;
     try {
-        return embeddedMetaValues(fields, readEmbeddedMetadata(new Uint8Array(await file.arrayBuffer())));
+        return embeddedAssetMeta(fields, readEmbeddedMetadata(new Uint8Array(await file.arrayBuffer())), locales);
     }
     catch {
-        return {};
+        return none;
     }
 }
 /**
@@ -190,22 +191,30 @@ async function embeddedAssetMeta(file, fields) {
  * available metadata, or keep the existing if no metadata is available"):
  * - the bytes' columns are SET — and a derived column the new file does not have is
  *   CLEARED (`null`), so an old thumb, lqip or dimension never outlives its file;
- * - `meta` is the stored bag (a legacy `alt` column lifted in, EC-587) with each key the
- *   new file brings overridden; written only when the file brings something, and then
- *   the legacy column is cleared, as every `meta` write does;
- * - the id, the focal point, the title and every other column are absent → kept.
+ * - each `meta` key the new file brings is a per-key `metaPatch` (EC-634), applied to the
+ *   bag as STORED inside the write — never a copy read before the upload, so an editor's
+ *   metadata save that lands while the bytes travel is kept. Sent only when the file
+ *   brings something; the write rule then lifts a legacy `alt` column into the bag and
+ *   clears it (EC-587), as for every patch;
+ * - the id, the focal point, the title and every other column are absent → kept;
+ * - `mustExist`: the write only updates the stored asset — gone (deleted meanwhile), it is
+ *   refused inside the write and nothing is created.
  */
-export function replaceWrite(stored, derived, dimensions, variants, embedded) {
-    const brings = Object.keys(embedded).length > 0;
-    const base = liftLegacyAlt(stored)?.meta ?? stored.meta ?? {};
+export function replaceWrite(assetId, derived, dimensions, variants, embedded) {
+    const brings = Object.keys(embedded.meta).length > 0;
+    const bringsLocales = Object.keys(embedded.localizedMeta).length > 0;
     return {
-        id: stored.id,
+        id: assetId,
+        // EC-634 follow-on: an update of a stored asset, never a create (a concurrent delete wins).
+        mustExist: true,
         ...derived,
         width: dimensions?.width ?? null,
         height: dimensions?.height ?? null,
         thumb: variants.thumb ?? null,
         lqip: variants.lqip ?? null,
-        ...(brings ? { meta: { ...base, ...embedded }, alt: null } : {}),
+        ...(brings ? { metaPatch: embedded.meta } : {}),
+        // EC-632: a localized field's embedded values patch their locale buckets per key.
+        ...(bringsLocales ? { localizedMetaPatch: embedded.localizedMeta } : {}),
     };
 }
 //# sourceMappingURL=upload.js.map

package/dist/lib/assets/upload.js.map

@@ -1 +1 @@
-{"version":3,"file":"upload.js","sourceRoot":"","sources":["../../../src/lib/assets/upload.ts"],"names":[],"mappings":"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","sourcesContent":["import { embeddedMetaValues, readEmbeddedMetadata } from '@elytracms/core/cms-core'\nimport type { FieldDef } from '@elytracms/core/cms-core'\nimport { liftLegacyAlt } from '@elytracms/core/persistence'\nimport type {\n  AssetRecord,\n  AssetRepository,\n  AssetWriteInput,\n  BlobStorageAdapter,\n} from '@elytracms/core/persistence'\nimport { detectImageDimensions } from './image-dimensions'\nimport type { ImageDimensions } from './image-dimensions'\nimport { generateVariants } from './thumbnail'\nimport type { GeneratedVariants } from './thumbnail'\nimport { initialUploadState, uploadReducer } from './upload-state'\nimport type { UploadEvent, UploadFailure, UploadState } from './upload-state'\n\n/**\n * Upload orchestration (EC-151): request upload URL → transfer bytes →\n * confirm by writing the EC-044 metadata record (dimensions, mime, serve URL).\n * Storage is reached *only* through the {@link BlobStorageAdapter}; every\n * effect is injectable so the whole flow unit-tests without a browser or a\n * live Convex deployment.\n */\n\n/** The structural slice of a browser `File` the upload flow needs. */\nexport interface UploadableFile {\n  name: string\n  type: string\n  size: number\n  arrayBuffer(): Promise<ArrayBuffer>\n}\n\n/** Sends bytes to an upload URL, reporting progress; returns the assigned storage key. */\nexport type UploadTransport = (\n  uploadUrl: string,\n  file: UploadableFile,\n  onProgress: (loaded: number, total: number) => void,\n) => Promise<{ storageKey: string }>\n\n/**\n * Default browser transport: XMLHttpRequest POST for real byte progress\n * (fetch has no upload progress without streams support everywhere).\n */\nexport const xhrUploadTransport: UploadTransport = (uploadUrl, file, onProgress) =>\n  new Promise((resolve, reject) => {\n    const xhr = new XMLHttpRequest()\n    xhr.open('POST', uploadUrl)\n    if (file.type) xhr.setRequestHeader('Content-Type', file.type)\n    xhr.upload.onprogress = (event) => {\n      if (event.lengthComputable) onProgress(event.loaded, event.total)\n    }\n    xhr.onerror = () => reject(new Error('Network error while uploading bytes.'))\n    xhr.onabort = () => reject(new Error('Upload was aborted.'))\n    xhr.onload = () => {\n      if (xhr.status < 200 || xhr.status >= 300) {\n        reject(new Error(`Upload failed with HTTP ${xhr.status}.`))\n        return\n      }\n      try {\n        const payload = JSON.parse(xhr.responseText) as { storageId?: unknown }\n        if (typeof payload.storageId === 'string' && payload.storageId.length > 0) {\n          resolve({ storageKey: payload.storageId })\n        } else {\n          reject(new Error('Upload response did not include a storageId.'))\n        }\n      } catch {\n        reject(new Error('Upload response was not valid JSON.'))\n      }\n    }\n    void file.arrayBuffer().then(\n      (bytes) => xhr.send(bytes),\n      () => reject(new Error('Could not read file bytes.')),\n    )\n  })\n\nexport interface UploadDeps {\n  blobs: BlobStorageAdapter\n  assets: AssetRepository\n  /**\n   * The project's asset collection fields (EC-568): the `source` declarations that map\n   * the file's embedded IPTC facts onto `meta` keys. Absent → no embedded metadata is\n   * written (a field without `source` is never filled).\n   */\n  assetFields?: readonly FieldDef[]\n  /** Client-direct transport; only used when `blobs.createUploadUrl` exists. */\n  transport?: UploadTransport\n  /** Injectable dimension detection; defaults to `createImageBitmap`-based. */\n  detectDimensions?: (file: UploadableFile) => Promise<ImageDimensions | undefined>\n  /**\n   * Injectable preview generation (EC-400 thumb + EC-420 lqip). Defaults to a\n   * single `createImageBitmap` + canvas decode that stores the thumb via a second\n   * `blobs.store()` and inlines the lqip data URI. Returns `{}` (or a partial) for\n   * skipped/failed variants — a preview NEVER fails the upload (AD-2). Tests inject\n   * a deterministic implementation.\n   */\n  generateVariants?: (\n    file: UploadableFile,\n    dimensions: ImageDimensions | undefined,\n  ) => Promise<GeneratedVariants>\n}\n\nexport interface UploadRequest {\n  projectId: string\n  file: UploadableFile\n  /**\n   * EC-568 — REPLACE the file inside this existing asset instead of creating one: the\n   * same id, the new bytes and everything derived from them (storage key, url,\n   * dimensions, type, size, thumb, lqip) through this one upload path; `meta` overridden\n   * per key where the new file carries a value (else kept); the focal point, the title\n   * and every other key kept. The previous blobs are kept (see EC-568 § Done).\n   */\n  replace?: { assetId: string }\n  /** Observe every state transition (drives progress UI). */\n  onState?: (state: UploadState) => void\n}\n\nexport type UploadResult =\n  | { ok: true; asset: AssetRecord; state: UploadState }\n  | { ok: false; failure: UploadFailure; state: UploadState }\n\nasync function defaultDetectDimensions(file: UploadableFile): Promise<ImageDimensions | undefined> {\n  if (typeof Blob === 'undefined' || !(file instanceof Blob)) return undefined\n  return detectImageDimensions(file as Blob & { type: string })\n}\n\n/**\n * Default preview step (EC-400 thumb + EC-420 lqip): decode the real `File` (which\n * IS a `Blob` in the browser) ONCE and produce both variants — store the thumb on\n * `blobs`, inline the lqip data URI. Guards the `Blob` narrowing so a non-browser\n * `UploadableFile` (or a backend without `store()`) simply yields no thumb — never\n * an error that could fail the upload.\n */\nfunction defaultGenerateVariants(blobs: BlobStorageAdapter) {\n  return async (\n    file: UploadableFile,\n    dimensions: ImageDimensions | undefined,\n  ): Promise<GeneratedVariants> => {\n    if (typeof Blob === 'undefined' || !(file instanceof Blob)) return {}\n    return generateVariants({ blobs }, file, {\n      contentType: file.type,\n      ...(dimensions ? { width: dimensions.width, height: dimensions.height } : {}),\n    })\n  }\n}\n\nfunction failureOf(stage: UploadFailure['stage'], error: unknown): UploadFailure {\n  return {\n    stage,\n    message: error instanceof Error ? error.message : String(error),\n    retryable: true,\n  }\n}\n\n/**\n * Run one upload attempt. Resolves with a discriminated result — it never\n * throws, and a failed transfer leaves no metadata record behind. Pass the\n * previous `state` to retry (the attempt counter carries over).\n */\nexport async function runUpload(\n  deps: UploadDeps,\n  request: UploadRequest,\n  previous?: UploadState,\n): Promise<UploadResult> {\n  let state = previous ?? initialUploadState\n  const dispatch = (event: UploadEvent): void => {\n    state = uploadReducer(state, event)\n    request.onState?.(state)\n  }\n  dispatch(state.phase === 'failed' ? { type: 'retry' } : { type: 'start' })\n\n  const { blobs, assets } = deps\n  const { projectId, file } = request\n\n  // --- prepare + transfer ---------------------------------------------------\n  let storageKey: string\n  try {\n    if (blobs.createUploadUrl && deps.transport) {\n      const uploadUrl = await blobs.createUploadUrl()\n      dispatch({ type: 'url-ready' })\n      try {\n        const sent = await deps.transport(uploadUrl, file, (loaded, total) =>\n          dispatch({ type: 'progress', loaded, total }),\n        )\n        storageKey = sent.storageKey\n      } catch (error) {\n        dispatch({ type: 'failed', ...failureOf('transfer', error) })\n        return { ok: false, failure: failureOf('transfer', error), state }\n      }\n    } else {\n      // Backend without client-direct uploads: push bytes through the adapter.\n      dispatch({ type: 'url-ready' })\n      const bytes = new Uint8Array(await file.arrayBuffer())\n      try {\n        if (blobs.store) {\n          storageKey = await blobs.store(bytes, file.type)\n        } else {\n          storageKey = `${projectId}/${file.name}`\n          await blobs.put(storageKey, bytes, file.type)\n        }\n      } catch (error) {\n        dispatch({ type: 'failed', ...failureOf('transfer', error) })\n        return { ok: false, failure: failureOf('transfer', error), state }\n      }\n    }\n  } catch (error) {\n    dispatch({ type: 'failed', ...failureOf('prepare', error) })\n    return { ok: false, failure: failureOf('prepare', error), state }\n  }\n  dispatch({ type: 'transferred' })\n\n  // --- confirm: metadata record linked to the stored blob --------------------\n  try {\n    // EC-568: the ONE embedded-metadata reader, for a first upload and a replace alike.\n    const embedded = await embeddedAssetMeta(file, deps.assetFields)\n    const detect = deps.detectDimensions ?? defaultDetectDimensions\n    const dimensions = await detect(file)\n    // EC-400 + EC-420: produce the thumb + lqip previews from the bytes already in\n    // hand (one decode). A preview failure is swallowed — the asset simply ships\n    // without them (AD-2, scope §4); absence = today's behaviour, never an error.\n    const generate = deps.generateVariants ?? defaultGenerateVariants(blobs)\n    let variants: GeneratedVariants\n    try {\n      variants = await generate(file, dimensions)\n    } catch {\n      variants = {}\n    }\n    const url = (await blobs.resolveUrl?.(storageKey)) ?? blobs.url(storageKey)\n    const derived = {\n      filename: file.name,\n      contentType: file.type || 'application/octet-stream',\n      byteSize: file.size,\n      storageKey,\n      url,\n    }\n    let write: AssetWriteInput\n    if (request.replace) {\n      const stored = await assets.findAsset(projectId, request.replace.assetId)\n      if (!stored) throw new Error(`No asset “${request.replace.assetId}” is stored to replace the file of.`)\n      write = replaceWrite(stored, derived, dimensions, variants, embedded)\n    } else {\n      write = {\n        ...derived,\n        ...(dimensions ? { width: dimensions.width, height: dimensions.height } : {}),\n        ...(variants.thumb ? { thumb: variants.thumb } : {}),\n        ...(variants.lqip ? { lqip: variants.lqip } : {}),\n        ...(Object.keys(embedded).length > 0 ? { meta: embedded } : {}),\n      }\n    }\n    const asset = await assets.upsertAsset(projectId, write)\n    dispatch({ type: 'confirmed', assetId: asset.id })\n    return { ok: true, asset, state }\n  } catch (error) {\n    dispatch({ type: 'failed', ...failureOf('confirm', error) })\n    return { ok: false, failure: failureOf('confirm', error), state }\n  }\n}\n\n/**\n * The file's embedded facts as `meta` values (EC-568): `readEmbeddedMetadata` over the\n * bytes, mapped through the asset collection's `source` declarations. A file that cannot\n * be read yields `{}` — metadata never fails an upload.\n */\nasync function embeddedAssetMeta(\n  file: UploadableFile,\n  fields: readonly FieldDef[] | undefined,\n): Promise<Record<string, unknown>> {\n  if (!fields || !fields.some((field) => field.source !== undefined)) return {}\n  try {\n    return embeddedMetaValues(fields, readEmbeddedMetadata(new Uint8Array(await file.arrayBuffer())))\n  } catch {\n    return {}\n  }\n}\n\n/**\n * The write of a file REPLACE (EC-568, the owner's ruling: \"override the values with\n * available metadata, or keep the existing if no metadata is available\"):\n * - the bytes' columns are SET — and a derived column the new file does not have is\n *   CLEARED (`null`), so an old thumb, lqip or dimension never outlives its file;\n * - `meta` is the stored bag (a legacy `alt` column lifted in, EC-587) with each key the\n *   new file brings overridden; written only when the file brings something, and then\n *   the legacy column is cleared, as every `meta` write does;\n * - the id, the focal point, the title and every other column are absent → kept.\n */\nexport function replaceWrite(\n  stored: AssetRecord,\n  derived: Pick<AssetRecord, 'filename' | 'contentType' | 'byteSize' | 'storageKey'> & { url: string },\n  dimensions: ImageDimensions | undefined,\n  variants: GeneratedVariants,\n  embedded: Record<string, unknown>,\n): AssetWriteInput {\n  const brings = Object.keys(embedded).length > 0\n  const base = liftLegacyAlt(stored)?.meta ?? stored.meta ?? {}\n  return {\n    id: stored.id,\n    ...derived,\n    width: dimensions?.width ?? null,\n    height: dimensions?.height ?? null,\n    thumb: variants.thumb ?? null,\n    lqip: variants.lqip ?? null,\n    ...(brings ? { meta: { ...base, ...embedded }, alt: null } : {}),\n  }\n}\n"]}
+{"version":3,"file":"upload.js","sourceRoot":"","sources":["../../../src/lib/assets/upload.ts"],"names":[],"mappings":"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","sourcesContent":["import { embeddedAssetMeta, readEmbeddedMetadata } from '@elytracms/core/cms-core'\nimport type { FieldDef, Locale } from '@elytracms/core/cms-core'\nimport type {\n  AssetRecord,\n  AssetRepository,\n  AssetWriteInput,\n  BlobStorageAdapter,\n} from '@elytracms/core/persistence'\nimport { detectImageDimensions } from './image-dimensions'\nimport type { ImageDimensions } from './image-dimensions'\nimport { generateVariants } from './thumbnail'\nimport type { GeneratedVariants } from './thumbnail'\nimport { initialUploadState, uploadReducer } from './upload-state'\nimport type { UploadEvent, UploadFailure, UploadState } from './upload-state'\n\n/**\n * Upload orchestration (EC-151): request upload URL → transfer bytes →\n * confirm by writing the EC-044 metadata record (dimensions, mime, serve URL).\n * Storage is reached *only* through the {@link BlobStorageAdapter}; every\n * effect is injectable so the whole flow unit-tests without a browser or a\n * live Convex deployment.\n */\n\n/** The structural slice of a browser `File` the upload flow needs. */\nexport interface UploadableFile {\n  name: string\n  type: string\n  size: number\n  arrayBuffer(): Promise<ArrayBuffer>\n}\n\n/** Sends bytes to an upload URL, reporting progress; returns the assigned storage key. */\nexport type UploadTransport = (\n  uploadUrl: string,\n  file: UploadableFile,\n  onProgress: (loaded: number, total: number) => void,\n) => Promise<{ storageKey: string }>\n\n/**\n * Default browser transport: XMLHttpRequest POST for real byte progress\n * (fetch has no upload progress without streams support everywhere).\n */\nexport const xhrUploadTransport: UploadTransport = (uploadUrl, file, onProgress) =>\n  new Promise((resolve, reject) => {\n    const xhr = new XMLHttpRequest()\n    xhr.open('POST', uploadUrl)\n    if (file.type) xhr.setRequestHeader('Content-Type', file.type)\n    xhr.upload.onprogress = (event) => {\n      if (event.lengthComputable) onProgress(event.loaded, event.total)\n    }\n    xhr.onerror = () => reject(new Error('Network error while uploading bytes.'))\n    xhr.onabort = () => reject(new Error('Upload was aborted.'))\n    xhr.onload = () => {\n      if (xhr.status < 200 || xhr.status >= 300) {\n        reject(new Error(`Upload failed with HTTP ${xhr.status}.`))\n        return\n      }\n      try {\n        const payload = JSON.parse(xhr.responseText) as { storageId?: unknown }\n        if (typeof payload.storageId === 'string' && payload.storageId.length > 0) {\n          resolve({ storageKey: payload.storageId })\n        } else {\n          reject(new Error('Upload response did not include a storageId.'))\n        }\n      } catch {\n        reject(new Error('Upload response was not valid JSON.'))\n      }\n    }\n    void file.arrayBuffer().then(\n      (bytes) => xhr.send(bytes),\n      () => reject(new Error('Could not read file bytes.')),\n    )\n  })\n\nexport interface UploadDeps {\n  blobs: BlobStorageAdapter\n  assets: AssetRepository\n  /**\n   * The project's asset collection fields (EC-568): the `source` declarations that map\n   * the file's embedded IPTC facts onto `meta` keys. Absent → no embedded metadata is\n   * written (a field without `source` is never filled).\n   */\n  assetFields?: readonly FieldDef[]\n  /**\n   * The project's locales (EC-632): a `localized: true` asset field's embedded value goes\n   * to the locale buckets — each locale its `xml:lang` alternative, the default the\n   * `x-default` reading. Absent → every field is written to the shared `meta`.\n   */\n  locales?: { readonly default: Locale; readonly locales: readonly Locale[] }\n  /** Client-direct transport; only used when `blobs.createUploadUrl` exists. */\n  transport?: UploadTransport\n  /** Injectable dimension detection; defaults to `createImageBitmap`-based. */\n  detectDimensions?: (file: UploadableFile) => Promise<ImageDimensions | undefined>\n  /**\n   * Injectable preview generation (EC-400 thumb + EC-420 lqip). Defaults to a\n   * single `createImageBitmap` + canvas decode that stores the thumb via a second\n   * `blobs.store()` and inlines the lqip data URI. Returns `{}` (or a partial) for\n   * skipped/failed variants — a preview NEVER fails the upload (AD-2). Tests inject\n   * a deterministic implementation.\n   */\n  generateVariants?: (\n    file: UploadableFile,\n    dimensions: ImageDimensions | undefined,\n  ) => Promise<GeneratedVariants>\n}\n\nexport interface UploadRequest {\n  projectId: string\n  file: UploadableFile\n  /**\n   * EC-568 — REPLACE the file inside this existing asset instead of creating one: the\n   * same id, the new bytes and everything derived from them (storage key, url,\n   * dimensions, type, size, thumb, lqip) through this one upload path; `meta` overridden\n   * per key where the new file carries a value (else kept); the focal point, the title\n   * and every other key kept. The previous blobs are kept (see EC-568 § Done).\n   */\n  replace?: { assetId: string }\n  /** Observe every state transition (drives progress UI). */\n  onState?: (state: UploadState) => void\n}\n\nexport type UploadResult =\n  | { ok: true; asset: AssetRecord; state: UploadState }\n  | { ok: false; failure: UploadFailure; state: UploadState }\n\nasync function defaultDetectDimensions(file: UploadableFile): Promise<ImageDimensions | undefined> {\n  if (typeof Blob === 'undefined' || !(file instanceof Blob)) return undefined\n  return detectImageDimensions(file as Blob & { type: string })\n}\n\n/**\n * Default preview step (EC-400 thumb + EC-420 lqip): decode the real `File` (which\n * IS a `Blob` in the browser) ONCE and produce both variants — store the thumb on\n * `blobs`, inline the lqip data URI. Guards the `Blob` narrowing so a non-browser\n * `UploadableFile` (or a backend without `store()`) simply yields no thumb — never\n * an error that could fail the upload.\n */\nfunction defaultGenerateVariants(blobs: BlobStorageAdapter) {\n  return async (\n    file: UploadableFile,\n    dimensions: ImageDimensions | undefined,\n  ): Promise<GeneratedVariants> => {\n    if (typeof Blob === 'undefined' || !(file instanceof Blob)) return {}\n    return generateVariants({ blobs }, file, {\n      contentType: file.type,\n      ...(dimensions ? { width: dimensions.width, height: dimensions.height } : {}),\n    })\n  }\n}\n\nfunction failureOf(stage: UploadFailure['stage'], error: unknown): UploadFailure {\n  return {\n    stage,\n    message: error instanceof Error ? error.message : String(error),\n    retryable: true,\n  }\n}\n\n/**\n * Run one upload attempt. Resolves with a discriminated result — it never\n * throws, and a failed transfer leaves no metadata record behind. Pass the\n * previous `state` to retry (the attempt counter carries over).\n */\nexport async function runUpload(\n  deps: UploadDeps,\n  request: UploadRequest,\n  previous?: UploadState,\n): Promise<UploadResult> {\n  let state = previous ?? initialUploadState\n  const dispatch = (event: UploadEvent): void => {\n    state = uploadReducer(state, event)\n    request.onState?.(state)\n  }\n  dispatch(state.phase === 'failed' ? { type: 'retry' } : { type: 'start' })\n\n  const { blobs, assets } = deps\n  const { projectId, file } = request\n\n  // --- prepare + transfer ---------------------------------------------------\n  let storageKey: string\n  try {\n    if (blobs.createUploadUrl && deps.transport) {\n      const uploadUrl = await blobs.createUploadUrl()\n      dispatch({ type: 'url-ready' })\n      try {\n        const sent = await deps.transport(uploadUrl, file, (loaded, total) =>\n          dispatch({ type: 'progress', loaded, total }),\n        )\n        storageKey = sent.storageKey\n      } catch (error) {\n        dispatch({ type: 'failed', ...failureOf('transfer', error) })\n        return { ok: false, failure: failureOf('transfer', error), state }\n      }\n    } else {\n      // Backend without client-direct uploads: push bytes through the adapter.\n      dispatch({ type: 'url-ready' })\n      const bytes = new Uint8Array(await file.arrayBuffer())\n      try {\n        if (blobs.store) {\n          storageKey = await blobs.store(bytes, file.type)\n        } else {\n          storageKey = `${projectId}/${file.name}`\n          await blobs.put(storageKey, bytes, file.type)\n        }\n      } catch (error) {\n        dispatch({ type: 'failed', ...failureOf('transfer', error) })\n        return { ok: false, failure: failureOf('transfer', error), state }\n      }\n    }\n  } catch (error) {\n    dispatch({ type: 'failed', ...failureOf('prepare', error) })\n    return { ok: false, failure: failureOf('prepare', error), state }\n  }\n  dispatch({ type: 'transferred' })\n\n  // --- confirm: metadata record linked to the stored blob --------------------\n  try {\n    // EC-568: the ONE embedded-metadata reader, for a first upload and a replace alike.\n    const embedded = await embeddedMetaOf(file, deps.assetFields, deps.locales)\n    const detect = deps.detectDimensions ?? defaultDetectDimensions\n    const dimensions = await detect(file)\n    // EC-400 + EC-420: produce the thumb + lqip previews from the bytes already in\n    // hand (one decode). A preview failure is swallowed — the asset simply ships\n    // without them (AD-2, scope §4); absence = today's behaviour, never an error.\n    const generate = deps.generateVariants ?? defaultGenerateVariants(blobs)\n    let variants: GeneratedVariants\n    try {\n      variants = await generate(file, dimensions)\n    } catch {\n      variants = {}\n    }\n    const url = (await blobs.resolveUrl?.(storageKey)) ?? blobs.url(storageKey)\n    const derived = {\n      filename: file.name,\n      contentType: file.type || 'application/octet-stream',\n      byteSize: file.size,\n      storageKey,\n      url,\n    }\n    let write: AssetWriteInput\n    if (request.replace) {\n      // A replace edits an asset, never creates one — decided by the write itself\n      // (`mustExist`), against the row as it is when the write lands: a delete by another\n      // session in the meantime makes the write fail here, visibly, and creates nothing.\n      write = replaceWrite(request.replace.assetId, derived, dimensions, variants, embedded)\n    } else {\n      write = {\n        ...derived,\n        ...(dimensions ? { width: dimensions.width, height: dimensions.height } : {}),\n        ...(variants.thumb ? { thumb: variants.thumb } : {}),\n        ...(variants.lqip ? { lqip: variants.lqip } : {}),\n        ...(Object.keys(embedded.meta).length > 0 ? { meta: embedded.meta } : {}),\n        ...(Object.keys(embedded.localizedMeta).length > 0 ? { localizedMeta: embedded.localizedMeta } : {}),\n      }\n    }\n    const asset = await assets.upsertAsset(projectId, write)\n    dispatch({ type: 'confirmed', assetId: asset.id })\n    return { ok: true, asset, state }\n  } catch (error) {\n    dispatch({ type: 'failed', ...failureOf('confirm', error) })\n    return { ok: false, failure: failureOf('confirm', error), state }\n  }\n}\n\n/**\n * The file's embedded facts as `meta` values (EC-568): `readEmbeddedMetadata` over the\n * bytes, mapped through the asset collection's `source` declarations. A file that cannot\n * be read yields `{}` — metadata never fails an upload.\n */\nasync function embeddedMetaOf(\n  file: UploadableFile,\n  fields: readonly FieldDef[] | undefined,\n  locales: UploadDeps['locales'],\n): Promise<EmbeddedAssetWrite> {\n  const none: EmbeddedAssetWrite = { meta: {}, localizedMeta: {} }\n  if (!fields || !fields.some((field) => field.source !== undefined)) return none\n  try {\n    return embeddedAssetMeta(fields, readEmbeddedMetadata(new Uint8Array(await file.arrayBuffer())), locales)\n  } catch {\n    return none\n  }\n}\n\n/** What a file's embedded facts write (EC-568 → EC-632): shared `meta` keys, and per-locale buckets of the localized fields. */\nexport interface EmbeddedAssetWrite {\n  meta: Record<string, unknown>\n  localizedMeta: Record<string, Record<string, unknown>>\n}\n\n/**\n * The write of a file REPLACE (EC-568, the owner's ruling: \"override the values with\n * available metadata, or keep the existing if no metadata is available\"):\n * - the bytes' columns are SET — and a derived column the new file does not have is\n *   CLEARED (`null`), so an old thumb, lqip or dimension never outlives its file;\n * - each `meta` key the new file brings is a per-key `metaPatch` (EC-634), applied to the\n *   bag as STORED inside the write — never a copy read before the upload, so an editor's\n *   metadata save that lands while the bytes travel is kept. Sent only when the file\n *   brings something; the write rule then lifts a legacy `alt` column into the bag and\n *   clears it (EC-587), as for every patch;\n * - the id, the focal point, the title and every other column are absent → kept;\n * - `mustExist`: the write only updates the stored asset — gone (deleted meanwhile), it is\n *   refused inside the write and nothing is created.\n */\nexport function replaceWrite(\n  assetId: string,\n  derived: Pick<AssetRecord, 'filename' | 'contentType' | 'byteSize' | 'storageKey'> & { url: string },\n  dimensions: ImageDimensions | undefined,\n  variants: GeneratedVariants,\n  embedded: EmbeddedAssetWrite,\n): AssetWriteInput {\n  const brings = Object.keys(embedded.meta).length > 0\n  const bringsLocales = Object.keys(embedded.localizedMeta).length > 0\n  return {\n    id: assetId,\n    // EC-634 follow-on: an update of a stored asset, never a create (a concurrent delete wins).\n    mustExist: true,\n    ...derived,\n    width: dimensions?.width ?? null,\n    height: dimensions?.height ?? null,\n    thumb: variants.thumb ?? null,\n    lqip: variants.lqip ?? null,\n    ...(brings ? { metaPatch: embedded.meta } : {}),\n    // EC-632: a localized field's embedded values patch their locale buckets per key.\n    ...(bringsLocales ? { localizedMetaPatch: embedded.localizedMeta } : {}),\n  }\n}\n"]}

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

@@ -1,5 +1,7 @@
 import type { CmsDocument } from '@elytracms/core/cms-core';
+import type { OperationError } from '@elytracms/core/operations';
 import type { OperationsClient } from '../operations/index.js';
+import type { ReadState } from '../query/index.js';
 /**
  * The PUBLISHED-perspective documents of a collection (EC-205, "live = published")
  * — the pinned published snapshot of each currently-published document, keyed by
@@ -13,12 +15,13 @@ import type { OperationsClient } from '../operations/index.js';
  * seam — invalidated only when a command that moves a live pin succeeds (NOT on
  * every autosave upsert — a draft edit doesn't change what's published). Cost: ONE
  * bulk `documents.listPublished` read (EC-307).
+ *
+ * EC-628: the pool is a {@link ReadState} — `ready` carries the pinned published snapshot
+ * per published document id; a failed read is `error` with the localized reason, and
+ * every surface reading the pool (the list's URL column, the editor header's live link)
+ * shows it. A failure is never an empty pool: an empty pool says "nothing is published".
  */
-export interface PublishedDocuments {
-    /** Pinned published snapshot per published document id. Empty while loading. */
-    byId: ReadonlyMap<string, CmsDocument>;
-    status: 'loading' | 'ready';
-}
+export type PublishedDocuments = ReadState<ReadonlyMap<string, CmsDocument>>;
 /**
  * Commands that change which version is pinned live (and thus the pool).
  *
@@ -30,12 +33,27 @@ export interface PublishedDocuments {
  * move or the delete of a pinned row changes published output.
  */
 export declare const PUBLISHED_RELOAD_OPS: readonly ["documents.publish", "documents.unpublish", "documents.pinVersion", "documents.delete", "documents.clear"];
+/**
+ * A failed `documents.listPublished` read (EC-628), carrying the operation's typed error so
+ * the surface localizes it when it renders — the query cache outlives a UI-language switch.
+ */
+export declare class PublishedReadError extends Error {
+    readonly error: OperationError;
+    constructor(error: OperationError);
+}
 /**
  * Build the published pool of a collection (pure over the operations client): the
  * pinned published snapshot of every currently-published document, keyed by id.
  * EC-307: one bulk `documents.listPublished` read — the backend resolves each
  * `publishedVersion` pointer to its recorded snapshot — instead of a `list` plus a
- * per-document `listVersions` fan-out. Read failures degrade to an empty pool.
+ * per-document `listVersions` fan-out. A failed read REJECTS with
+ * {@link PublishedReadError} (EC-628) — it used to resolve to an empty pool.
  */
 export declare function loadPublishedDocuments(operations: OperationsClient, projectId: string, collectionId: string): Promise<Map<string, CmsDocument>>;
+/** The {@link PublishedDocuments} state of the pool's query (pure — the hook's mapping). */
+export declare function publishedDocumentsState(query: {
+    readonly isError: boolean;
+    readonly error: unknown;
+    readonly data: ReadonlyMap<string, CmsDocument> | undefined;
+}): PublishedDocuments;
 export declare function usePublishedDocuments(projectId: string | undefined, collectionId: string): PublishedDocuments;

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

@@ -1,4 +1,6 @@
-import { useOperationQuery } from '../query/index.js';
+import { readStateOf, useOperationQuery } from '../query/index.js';
+import { translate } from '../i18n/index.js';
+import { operationErrorMessage } from '../persona/labels.js';
 /**
  * Commands that change which version is pinned live (and thus the pool).
  *
@@ -16,23 +18,54 @@ export const PUBLISHED_RELOAD_OPS = [
     'documents.delete',
     'documents.clear',
 ];
-const EMPTY_POOL = new Map();
+/** No project (a fixture session without a backend): nothing is published, by construction. */
+const NO_PROJECT_POOL = { status: 'ready', value: new Map() };
+/**
+ * A failed `documents.listPublished` read (EC-628), carrying the operation's typed error so
+ * the surface localizes it when it renders — the query cache outlives a UI-language switch.
+ */
+export class PublishedReadError extends Error {
+    error;
+    constructor(error) {
+        super(error.message);
+        this.error = error;
+        this.name = 'PublishedReadError';
+    }
+}
 /**
  * Build the published pool of a collection (pure over the operations client): the
  * pinned published snapshot of every currently-published document, keyed by id.
  * EC-307: one bulk `documents.listPublished` read — the backend resolves each
  * `publishedVersion` pointer to its recorded snapshot — instead of a `list` plus a
- * per-document `listVersions` fan-out. Read failures degrade to an empty pool.
+ * per-document `listVersions` fan-out. A failed read REJECTS with
+ * {@link PublishedReadError} (EC-628) — it used to resolve to an empty pool.
  */
 export async function loadPublishedDocuments(operations, projectId, collectionId) {
     const result = await operations.documents.listPublished({ projectId, collection: collectionId });
     if (!result.ok)
-        return new Map();
+        throw new PublishedReadError(result.error);
     const byId = new Map();
     for (const snapshot of result.value)
         byId.set(snapshot.id, snapshot);
     return byId;
 }
+/**
+ * The pool's sentence when its read failed (EC-628): one message, shown by every surface
+ * that reads the pool — the operation's reason in the UI language when it carries a
+ * catalog reference (EC-494), its English otherwise.
+ */
+function publishedReadFailure(error) {
+    const reason = error instanceof PublishedReadError
+        ? operationErrorMessage(error.error)
+        : error instanceof Error
+            ? error.message
+            : String(error);
+    return translate('cms.editor.publishedReadFailed', { reason });
+}
+/** The {@link PublishedDocuments} state of the pool's query (pure — the hook's mapping). */
+export function publishedDocumentsState(query) {
+    return readStateOf(query, publishedReadFailure);
+}
 export function usePublishedDocuments(projectId, collectionId) {
     const query = useOperationQuery({
         // Playground/fixture mode (no backend) is `enabled: false` → never queried.
@@ -42,7 +75,7 @@ export function usePublishedDocuments(projectId, collectionId) {
         enabled: projectId !== undefined,
     });
     if (projectId === undefined)
-        return { byId: EMPTY_POOL, status: 'ready' };
-    return { byId: query.data ?? EMPTY_POOL, status: query.isPending ? 'loading' : 'ready' };
+        return NO_PROJECT_POOL;
+    return publishedDocumentsState(query);
 }
 //# sourceMappingURL=published-documents.js.map

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,UAAU,CAAA;AAsB5C;;;;;;;;;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 '../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"]}
+{"version":3,"file":"published-documents.js","sourceRoot":"","sources":["../../../src/lib/cms/published-documents.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAA;AAEzD,OAAO,EAAE,SAAS,EAAE,MAAM,SAAS,CAAA;AACnC,OAAO,EAAE,qBAAqB,EAAE,MAAM,mBAAmB,CAAA;AAuBzD;;;;;;;;;GASG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG;IAClC,mBAAmB;IACnB,qBAAqB;IACrB,sBAAsB;IACtB,kBAAkB;IAClB,iBAAiB;CACT,CAAA;AAEV,+FAA+F;AAC/F,MAAM,eAAe,GAAuB,EAAE,MAAM,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,GAAG,EAAE,EAAE,CAAA;AAEjF;;;GAGG;AACH,MAAM,OAAO,kBAAmB,SAAQ,KAAK;IACtB;IAArB,YAAqB,KAAqB;QACxC,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAA;QADD,UAAK,GAAL,KAAK,CAAgB;QAExC,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAA;IAClC,CAAC;CACF;AAED;;;;;;;GAOG;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,MAAM,IAAI,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IAC1D,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;;;;GAIG;AACH,SAAS,oBAAoB,CAAC,KAAc;IAC1C,MAAM,MAAM,GACV,KAAK,YAAY,kBAAkB;QACjC,CAAC,CAAC,qBAAqB,CAAC,KAAK,CAAC,KAAK,CAAC;QACpC,CAAC,CAAC,KAAK,YAAY,KAAK;YACtB,CAAC,CAAC,KAAK,CAAC,OAAO;YACf,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;IACrB,OAAO,SAAS,CAAC,gCAAgC,EAAE,EAAE,MAAM,EAAE,CAAC,CAAA;AAChE,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,uBAAuB,CAAC,KAIvC;IACC,OAAO,WAAW,CAAC,KAAK,EAAE,oBAAoB,CAAC,CAAA;AACjD,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,CAAA;IACnD,OAAO,uBAAuB,CAAC,KAAK,CAAC,CAAA;AACvC,CAAC","sourcesContent":["import type { CmsDocument } from '@elytracms/core/cms-core'\nimport type { OperationError } from '@elytracms/core/operations'\nimport type { OperationsClient } from '../operations'\nimport { readStateOf, useOperationQuery } from '../query'\nimport type { ReadState } from '../query'\nimport { translate } from '../i18n'\nimport { operationErrorMessage } from '../persona/labels'\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 *\n * EC-628: the pool is a {@link ReadState} — `ready` carries the pinned published snapshot\n * per published document id; a failed read is `error` with the localized reason, and\n * every surface reading the pool (the list's URL column, the editor header's live link)\n * shows it. A failure is never an empty pool: an empty pool says \"nothing is published\".\n */\nexport type PublishedDocuments = ReadState<ReadonlyMap<string, CmsDocument>>\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\n/** No project (a fixture session without a backend): nothing is published, by construction. */\nconst NO_PROJECT_POOL: PublishedDocuments = { status: 'ready', value: new Map() }\n\n/**\n * A failed `documents.listPublished` read (EC-628), carrying the operation's typed error so\n * the surface localizes it when it renders — the query cache outlives a UI-language switch.\n */\nexport class PublishedReadError extends Error {\n  constructor(readonly error: OperationError) {\n    super(error.message)\n    this.name = 'PublishedReadError'\n  }\n}\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. A failed read REJECTS with\n * {@link PublishedReadError} (EC-628) — it used to resolve 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) throw new PublishedReadError(result.error)\n  const byId = new Map<string, CmsDocument>()\n  for (const snapshot of result.value) byId.set(snapshot.id, snapshot)\n  return byId\n}\n\n/**\n * The pool's sentence when its read failed (EC-628): one message, shown by every surface\n * that reads the pool — the operation's reason in the UI language when it carries a\n * catalog reference (EC-494), its English otherwise.\n */\nfunction publishedReadFailure(error: unknown): string {\n  const reason =\n    error instanceof PublishedReadError\n      ? operationErrorMessage(error.error)\n      : error instanceof Error\n        ? error.message\n        : String(error)\n  return translate('cms.editor.publishedReadFailed', { reason })\n}\n\n/** The {@link PublishedDocuments} state of the pool's query (pure — the hook's mapping). */\nexport function publishedDocumentsState(query: {\n  readonly isError: boolean\n  readonly error: unknown\n  readonly data: ReadonlyMap<string, CmsDocument> | undefined\n}): PublishedDocuments {\n  return readStateOf(query, publishedReadFailure)\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 NO_PROJECT_POOL\n  return publishedDocumentsState(query)\n}\n"]}

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

@@ -1,5 +1,6 @@
 import { z } from 'zod';
-import type { CmsDocument, CollectionDef, FieldDef, Locale, LocaleConfig, LocalizedString } from '@elytracms/core/cms-core';
+import { configViewSchema, filterClauseSchema, filterScalarSchema, isPseudoColumn, PUBLISHED_AT_FIELD, STATE_FIELD, UPDATED_AT_FIELD, URL_FIELD, sortSchema } from '@elytracms/core/cms-core';
+import type { CmsDocument, CollectionDef, ConfigView, FieldDef, FilterClause, Locale, LocaleConfig, LocalizedString, Sort } from '@elytracms/core/cms-core';
 import type { FilterOperator, FilterScalar } from '@elytracms/core/content';
 /**
  * The pure table-view model for the CMS collection table (EC-169).
@@ -17,90 +18,36 @@ import type { FilterOperator, FilterScalar } from '@elytracms/core/content';
  * "show me drafts → bulk publish" working set and still speaks only the
  * closed vocabulary (`eq`/`in`).
  */
-export declare const filterScalarSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>;
-export declare const filterClauseSchema: z.ZodObject<{
-    field: z.ZodString;
-    op: z.ZodEnum<{
-        endsWith: "endsWith";
-        startsWith: "startsWith";
-        in: "in";
-        empty: "empty";
-        contains: "contains";
-        eq: "eq";
-        gt: "gt";
-        gte: "gte";
-        lt: "lt";
-        lte: "lte";
-    }>;
-    value: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>]>;
-}, z.core.$strip>;
-export type FilterClause = z.infer<typeof filterClauseSchema>;
-export declare const viewSortSchema: z.ZodObject<{
-    field: z.ZodString;
-    dir: z.ZodEnum<{
-        desc: "desc";
-        asc: "asc";
-    }>;
-}, z.core.$strip>;
-export type ViewSort = z.infer<typeof viewSortSchema>;
+export { configViewSchema, filterClauseSchema, filterScalarSchema, isPseudoColumn, PUBLISHED_AT_FIELD, sortSchema, STATE_FIELD, UPDATED_AT_FIELD, URL_FIELD, };
+export type { ConfigView, FilterClause, Sort };
 export declare const tableViewStateSchema: z.ZodObject<{
     filters: z.ZodArray<z.ZodObject<{
         field: z.ZodString;
         op: z.ZodEnum<{
+            in: "in";
             endsWith: "endsWith";
             startsWith: "startsWith";
-            in: "in";
-            empty: "empty";
-            contains: "contains";
             eq: "eq";
             gt: "gt";
             gte: "gte";
             lt: "lt";
             lte: "lte";
+            contains: "contains";
+            empty: "empty";
         }>;
         value: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>]>;
     }, z.core.$strip>>;
     sort: z.ZodNullable<z.ZodObject<{
         field: z.ZodString;
-        dir: z.ZodEnum<{
-            desc: "desc";
+        direction: z.ZodDefault<z.ZodEnum<{
             asc: "asc";
-        }>;
-    }, z.core.$strip>>;
+            desc: "desc";
+        }>>;
+    }, z.core.$strict>>;
     columns: z.ZodArray<z.ZodString>;
     hidden: z.ZodDefault<z.ZodArray<z.ZodString>>;
 }, z.core.$strip>;
 export type TableViewState = z.infer<typeof tableViewStateSchema>;
-/**
- * Sentinel field key for the publication state. `$`-prefixed so it can never
- * collide with a schema field name (`fieldDefSchema` names are identifiers).
- */
-export declare const STATE_FIELD = "$state";
-/**
- * Reserved pseudo-COLUMN keys — the columns-axis siblings of the filter-axis
- * {@link STATE_FIELD}. `$`-prefixed so they can never collide with a schema field
- * name; they participate in a view's `columns` list AND the Display picker exactly
- * like a schema field (orderable / hideable / includable), but they are NOT drawn
- * from `collection.fields` — the column UNIVERSE is `[...schemaFields, ...pseudoColumns]`.
- *
- * - `$state` — publication status. A reserved `$`-key, but NO LONGER a reorderable
- *   column: EC-448 promoted it to a FIXED structural leading column (checkbox →
- *   status-dot → title), so it is NOT emitted by {@link pseudoColumns} and never
- *   participates in the reorderable columns/hidden/order model. It stays a reserved
- *   key (filter + sort) and {@link isPseudoColumn} still recognizes it, so an authored
- *   view listing `$state` is a harmless no-op (see {@link resolveConfigColumns}).
- * - `$url` — the derived delivery URL (routable collections only; NON-sortable).
- * - `$updatedAt` — the record's last-write timestamp.
- * - `$publishedAt` — the record's FIRST-publish instant (EC-447; opt-in, HIDDEN by
- *   default). Now materialized end-to-end (`cmsDocuments.publishedAt` → source
- *   `timestamps.publishedAt`) and emitted by {@link pseudoColumns} when the source
- *   both materializes timestamps and has a publish lifecycle.
- */
-export declare const URL_FIELD = "$url";
-export declare const PUBLISHED_AT_FIELD = "$publishedAt";
-export declare const UPDATED_AT_FIELD = "$updatedAt";
-/** Is `name` a reserved pseudo-column (a `$`-key, not a schema field)? */
-export declare function isPseudoColumn(name: string): boolean;
 /**
  * Capability signals that make a pseudo-column applicable to a collection/source
  * (EC-445). Supplied by the caller from the portable source — the model stays pure.
@@ -240,13 +187,20 @@ export type IsPublished = (doc: CmsDocument) => boolean;
  * relation membership all behave the same on the table as on the live site).
  */
 export declare function clauseMatches(collection: CollectionDef, doc: CmsDocument, localeConfig: LocaleConfig, locale: Locale, clause: FilterClause, isPublished?: IsPublished): boolean;
+/**
+ * The sort a column header click leads to (EC-169): a new column sorts ascending, the
+ * active one flips to descending, then clears. Reads `direction`, which every parsed
+ * sort carries — THE sort shape normalises an omitted one to `'asc'` (EC-660), so a
+ * config view declared `{ field }` flips on its first click instead of clearing.
+ */
+export declare function nextHeaderSort(prev: Sort | null, field: string): Sort | null;
 /**
  * Sort documents by one column in the canonical deterministic order
  * (`compareListEntries`: typed value order, id-ascending tiebreak). Unlike the
  * content accessors, the *table* may sort any rendered column — sorting is a
  * presentation concern here; the `filterable` flag governs filters.
  */
-export declare function sortViewDocuments(collection: CollectionDef, docs: readonly CmsDocument[], localeConfig: LocaleConfig, locale: Locale, sort: ViewSort | null, isPublished?: IsPublished, meta?: PseudoColumnMeta): CmsDocument[];
+export declare function sortViewDocuments(collection: CollectionDef, docs: readonly CmsDocument[], localeConfig: LocaleConfig, locale: Locale, sort: Sort | null, isPublished?: IsPublished, meta?: PseudoColumnMeta): CmsDocument[];
 /** The filtered + sorted documents of a view, plus any clause issues. */
 export interface AppliedViewState {
     docs: CmsDocument[];
@@ -269,49 +223,14 @@ export declare function defaultViewState(collection: CollectionDef, pseudo?: rea
  * same shape {@link defaultViewState} produces, so {@link resolveColumns} renders
  * precisely the authored list, visible, in that order. An omitted (or empty) list
  * inherits the collection's default lens (all scalars visible, composites hidden).
- * Unknown names in the authored list (a field the schema no longer has) are dropped.
+ * An authored name outside the universe — no longer a field, or a reserved column that
+ * does not apply to this source — is skipped here so the list still renders; a name that
+ * is neither a top-level field nor a reserved `$` key never reaches a resolved config
+ * (EC-622: the config gate refuses it, `collectionViewFindings`).
  */
 export declare function resolveConfigColumns(collection: CollectionDef, visible: readonly string[] | undefined, pseudo?: readonly string[]): Pick<TableViewState, 'columns' | 'hidden'>;
 /** The reserved `views[]` id whose entry OVERRIDES the synthesized baseline view (EC-444). */
 export declare const DEFAULT_VIEW_OVERRIDE_ID = "default";
-/**
- * A config-declared view (EC-246b/EC-444) — the flat authoring shape a collection
- * declares in `cms/` config: `{ name, initial?, filters?, sort?, columns? }`.
- * Filters/sort/columns sit at the top level (no nested `state` wrapper). The
- * studio validates + interprets these; `cms-core` stores them opaquely (it
- * can't reference the filter vocabulary without a layering cycle).
- */
-export declare const configViewSchema: z.ZodObject<{
-    id: z.ZodOptional<z.ZodString>;
-    name: z.ZodUnion<readonly [z.ZodString, z.ZodRecord<z.ZodString, z.ZodString>]>;
-    initial: z.ZodOptional<z.ZodBoolean>;
-    default: z.ZodOptional<z.ZodBoolean>;
-    filters: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        field: z.ZodString;
-        op: z.ZodEnum<{
-            endsWith: "endsWith";
-            startsWith: "startsWith";
-            in: "in";
-            empty: "empty";
-            contains: "contains";
-            eq: "eq";
-            gt: "gt";
-            gte: "gte";
-            lt: "lt";
-            lte: "lte";
-        }>;
-        value: z.ZodUnion<readonly [z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>, z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean]>>]>;
-    }, z.core.$strip>>>;
-    sort: z.ZodOptional<z.ZodNullable<z.ZodObject<{
-        field: z.ZodString;
-        dir: z.ZodEnum<{
-            desc: "desc";
-            asc: "asc";
-        }>;
-    }, z.core.$strip>>>;
-    columns: z.ZodOptional<z.ZodArray<z.ZodString>>;
-}, z.core.$strip>;
-export type ConfigView = z.infer<typeof configViewSchema>;
 /**
  * A resolved view: identity + the table state it restores (matches `SavedView`).
  * `name` stays a {@link LocalizedString} — resolved at the render site (EC-343), like
@@ -327,7 +246,8 @@ export interface ResolvedView {
 /**
  * Resolve a collection's config-declared `views` into full {@link ResolvedView}s
  * (EC-246b). Each is validated with {@link configViewSchema}; malformed entries
- * and duplicate ids are dropped (defensive). Columns fall back to the collection
+ * and duplicate ids are skipped (defensive — a malformed view never reaches a resolved
+ * config: the config gate refuses it, EC-622). Columns fall back to the collection
  * default when a view doesn't pin them, so a filter-only view still renders every
  * column. Config views are shared and change only in
  * code — the runtime never mutates them.