@elytracms/studio 0.0.73 → 0.0.75

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

@@ -76,6 +76,74 @@ export type TableViewState = z.infer<typeof tableViewStateSchema>;
  * 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.
+ */
+export interface PseudoColumnOptions {
+    /** The source materializes per-document timestamps → `$updatedAt` applies. */
+    timestamps?: boolean;
+    /**
+     * The collection has a publish lifecycle. Gates `$publishedAt` (with `timestamps`).
+     * EC-448: it no longer gates a reorderable `$state` column — `$state` is the FIXED
+     * structural status column, gated by the same signal at the render site, not here.
+     */
+    publishing?: boolean;
+    /** The collection resolves delivery URLs → `$url` applies (mirrors `urlByDocId`). */
+    routable?: boolean;
+}
+/**
+ * The reserved REORDERABLE pseudo-columns that APPLY to a collection, in their default
+ * appended order (EC-445/EC-447): `$updatedAt`, `$publishedAt`, then `$url`. `$url` is
+ * gated on `routable` (a non-routable collection has no URL column, not an empty one),
+ * `$updatedAt` on `timestamps`. `$publishedAt` (EC-447) needs BOTH `timestamps` (its
+ * materialized value) AND `publishing` (a publish lifecycle to have a publish date) —
+ * it is OPT-IN, HIDDEN by default (`DEFAULT_HIDDEN_PSEUDO_COLUMNS`), so it joins the
+ * universe/picker without appearing in the baseline lens.
+ *
+ * NOTE (EC-448): `$state` is NO LONGER emitted here. It became a FIXED structural
+ * leading column (checkbox → status-dot → title), rendered by `collection-table.tsx`
+ * regardless of the reorderable model — so it is never in the order/hide/picker set,
+ * even though `publishing` is what gates BOTH it and the status column's presence.
+ * `opts.publishing` therefore only affects `$publishedAt` here. Pure — a caller
+ * (`pseudoColumnsForSource`) supplies the signals from the source.
+ */
+export declare function pseudoColumns(collection: CollectionDef, opts?: PseudoColumnOptions): string[];
+/**
+ * The per-document metadata accessors the pseudo-DATE columns sort by (EC-445) — the
+ * columns-axis analogue of {@link IsPublished}. Threaded into the sort machinery so a
+ * `$updatedAt`/`$publishedAt` sort orders by the source's materialized timestamp; a
+ * missing accessor (fixtures/tests) sorts those rows last. `$url` is derived → never sorted.
+ */
+export interface PseudoColumnMeta {
+    updatedAt?(doc: CmsDocument): string | undefined;
+    publishedAt?(doc: CmsDocument): string | undefined;
+}
 /** One field the filter builder may offer. */
 export interface FilterableFieldOption {
     /** Clause field key: a schema field name, or {@link STATE_FIELD}. */
@@ -173,7 +241,7 @@ export declare function clauseMatches(collection: CollectionDef, doc: CmsDocumen
  * 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, sort: ViewSort | null, isPublished?: IsPublished): CmsDocument[];
+export declare function sortViewDocuments(collection: CollectionDef, docs: readonly CmsDocument[], localeConfig: LocaleConfig, sort: ViewSort | null, isPublished?: IsPublished, meta?: PseudoColumnMeta): CmsDocument[];
 /** The filtered + sorted documents of a view, plus any clause issues. */
 export interface AppliedViewState {
     docs: CmsDocument[];
@@ -185,10 +253,10 @@ export interface AppliedViewState {
  * ones, sort. Invalid clauses never filter silently — they come back as
  * issues for the UI to surface.
  */
-export declare function applyViewState(collection: CollectionDef, docs: readonly CmsDocument[], localeConfig: LocaleConfig, state: TableViewState, isPublished?: IsPublished): AppliedViewState;
+export declare function applyViewState(collection: CollectionDef, docs: readonly CmsDocument[], localeConfig: LocaleConfig, state: TableViewState, isPublished?: IsPublished, meta?: PseudoColumnMeta): AppliedViewState;
 /** The id of the synthesized built-in "All entries" baseline view (EC-444). */
 export declare const ALL_VIEW_ID = "all";
-export declare function defaultViewState(collection: CollectionDef): TableViewState;
+export declare function defaultViewState(collection: CollectionDef, pseudo?: readonly string[]): TableViewState;
 /**
  * Resolve an authored VISIBLE column list (EC-444) into the internal two-axis
  * `{columns, hidden}` table state. The authored list is exactly the columns shown,
@@ -198,7 +266,7 @@ export declare function defaultViewState(collection: CollectionDef): TableViewSt
  * 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.
  */
-export declare function resolveConfigColumns(collection: CollectionDef, visible: readonly string[] | undefined): Pick<TableViewState, 'columns' | 'hidden'>;
+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";
 /**
@@ -259,7 +327,7 @@ export interface ResolvedView {
  * column. Config views are shared and change only in
  * code — the runtime never mutates them.
  */
-export declare function configViewsFor(collection: CollectionDef): ResolvedView[];
+export declare function configViewsFor(collection: CollectionDef, pseudo?: readonly string[]): ResolvedView[];
 /**
  * Does the collection declare a baseline-override view (a config view whose id is
  * {@link DEFAULT_VIEW_OVERRIDE_ID})? When true the synthesized "All entries" lens is
@@ -274,7 +342,7 @@ export declare function hasDefaultViewOverride(collection: CollectionDef): boole
  * `synthesizedBaseline` the caller passes (the studio's translated "All entries"
  * lens). Pure — the store supplies the synthesized baseline (i18n-bound `name`).
  */
-export declare function resolveCollectionViews(collection: CollectionDef, synthesizedBaseline: ResolvedView): ResolvedView[];
+export declare function resolveCollectionViews(collection: CollectionDef, synthesizedBaseline: ResolvedView, pseudo?: readonly string[]): ResolvedView[];
 /**
  * The ids of config views that still use the DEPRECATED `default` flag without the
  * new `initial` (EC-444). Drives the one-release deprecation warning (mirrors the
@@ -325,9 +393,9 @@ export interface ResolvedColumn {
  * or hidden" — order is preserved across hide/show because visibility lives in
  * `hidden`, never in the order.
  */
-export declare function resolveColumns(collection: CollectionDef, state: TableViewState): ResolvedColumn[];
+export declare function resolveColumns(collection: CollectionDef, state: TableViewState, pseudo?: readonly string[]): ResolvedColumn[];
 /** The visible columns of a view, in render order (EC-213). */
-export declare function visibleColumns(collection: CollectionDef, state: TableViewState): string[];
+export declare function visibleColumns(collection: CollectionDef, state: TableViewState, pseudo?: readonly string[]): string[];
 /**
  * The title/link column — the document IDENTITY column (EC-242): the schema title
  * field, shown as the leftmost linked cell whose content is `resolveDocumentTitle`
@@ -337,7 +405,7 @@ export declare function visibleColumns(collection: CollectionDef, state: TableVi
  * the first visible column, then the first field, then `id`, when no title field
  * is resolvable (e.g. a function title with no backing `title` field).
  */
-export declare function primaryColumn(collection: CollectionDef, state: TableViewState): string;
+export declare function primaryColumn(collection: CollectionDef, state: TableViewState, pseudo?: readonly string[]): string;
 /**
  * The canonical, schema-resolved form of a view state — full column order with
  * `hidden` pruned to live fields (EC-213). Two states that render identically
@@ -345,12 +413,12 @@ export declare function primaryColumn(collection: CollectionDef, state: TableVie
  * reconciliation or a stale `hidden` entry (only a real filter/sort/visibility/
  * order change counts as "unsaved").
  */
-export declare function canonicalViewState(collection: CollectionDef, state: TableViewState): TableViewState;
+export declare function canonicalViewState(collection: CollectionDef, state: TableViewState, pseudo?: readonly string[]): TableViewState;
 /**
  * Toggle a column's visibility — position is preserved (EC-213): visibility
  * lives in `hidden`, the order in `columns` is untouched. Columns the saved
  * order predates are pinned into `columns` first so their place is stable.
  */
-export declare function toggleColumn(collection: CollectionDef, state: TableViewState, field: string): TableViewState;
+export declare function toggleColumn(collection: CollectionDef, state: TableViewState, field: string, pseudo?: readonly string[]): TableViewState;
 /** Move a column one position left (-1) or right (+1) in the full column order. */
-export declare function moveColumn(collection: CollectionDef, state: TableViewState, field: string, delta: -1 | 1): TableViewState;
+export declare function moveColumn(collection: CollectionDef, state: TableViewState, field: string, delta: -1 | 1, pseudo?: readonly string[]): TableViewState;

package/dist/lib/cms-views/view-model.js

@@ -55,6 +55,83 @@ export const tableViewStateSchema = z.object({
  */
 export const STATE_FIELD = '$state';
 const STATE_VALUES = ['draft', 'published'];
+// --- Reserved pseudo-COLUMNS (EC-445) ------------------------------------------
+/**
+ * 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 const URL_FIELD = '$url';
+export const PUBLISHED_AT_FIELD = '$publishedAt';
+export const UPDATED_AT_FIELD = '$updatedAt';
+/**
+ * Every reserved pseudo-column key. `$state` is included (it is still a reserved
+ * `$`-key: the filter/sort axis + the FIXED structural status column, EC-448) so
+ * {@link isPseudoColumn} never mistakes it for a schema field — but it is NOT a
+ * reorderable column, so it is absent from the `pseudo` sets {@link pseudoColumns}
+ * emits into the order/hide/picker model.
+ */
+const PSEUDO_COLUMN_FIELDS = [
+    STATE_FIELD,
+    URL_FIELD,
+    PUBLISHED_AT_FIELD,
+    UPDATED_AT_FIELD,
+];
+/** Is `name` a reserved pseudo-column (a `$`-key, not a schema field)? */
+export function isPseudoColumn(name) {
+    return PSEUDO_COLUMN_FIELDS.includes(name);
+}
+/**
+ * Pseudo-columns HIDDEN by default (opt-in): the extra publish timestamp. Everything
+ * else applicable (`$updatedAt`/`$state`/`$url`) is on by default (owner, 2026-07-17).
+ */
+const DEFAULT_HIDDEN_PSEUDO_COLUMNS = new Set([PUBLISHED_AT_FIELD]);
+/**
+ * The reserved REORDERABLE pseudo-columns that APPLY to a collection, in their default
+ * appended order (EC-445/EC-447): `$updatedAt`, `$publishedAt`, then `$url`. `$url` is
+ * gated on `routable` (a non-routable collection has no URL column, not an empty one),
+ * `$updatedAt` on `timestamps`. `$publishedAt` (EC-447) needs BOTH `timestamps` (its
+ * materialized value) AND `publishing` (a publish lifecycle to have a publish date) —
+ * it is OPT-IN, HIDDEN by default (`DEFAULT_HIDDEN_PSEUDO_COLUMNS`), so it joins the
+ * universe/picker without appearing in the baseline lens.
+ *
+ * NOTE (EC-448): `$state` is NO LONGER emitted here. It became a FIXED structural
+ * leading column (checkbox → status-dot → title), rendered by `collection-table.tsx`
+ * regardless of the reorderable model — so it is never in the order/hide/picker set,
+ * even though `publishing` is what gates BOTH it and the status column's presence.
+ * `opts.publishing` therefore only affects `$publishedAt` here. Pure — a caller
+ * (`pseudoColumnsForSource`) supplies the signals from the source.
+ */
+export function pseudoColumns(collection, opts = {}) {
+    void collection; // reserved for future per-collection gating; kept for API symmetry
+    const cols = [];
+    if (opts.timestamps)
+        cols.push(UPDATED_AT_FIELD);
+    // EC-447: a publish date needs both a timestamps source (the value) AND a publish
+    // lifecycle (the meaning). Hidden by default → surfaced via the Display picker / a
+    // config view's `columns`, never a blank column on a rail that can't publish.
+    if (opts.timestamps && opts.publishing)
+        cols.push(PUBLISHED_AT_FIELD);
+    // EC-448: $state is structural (fixed leading column), not a reorderable pseudo-column.
+    if (opts.routable)
+        cols.push(URL_FIELD);
+    return cols;
+}
 export const STATE_OPTION = {
     field: STATE_FIELD,
     label: 'State',
@@ -267,9 +344,17 @@ function rawValueOf(collection, doc, field, localeConfig, isPublished) {
     return resolveField(collection, doc, field, locale, localeConfig).value;
 }
 /** The scalar a document exposes for a SORT field, locale-resolved. */
-function scalarOf(collection, doc, field, localeConfig, isPublished) {
+function scalarOf(collection, doc, field, localeConfig, isPublished, meta = {}) {
     if (field === STATE_FIELD)
         return isPublished(doc) ? 'published' : 'draft';
+    // EC-445: the pseudo-DATE columns sort by the source's materialized ISO timestamp
+    // (ISO strings order lexicographically = chronologically); `$url` is derived → not sortable.
+    if (field === UPDATED_AT_FIELD)
+        return meta.updatedAt?.(doc) ?? null;
+    if (field === PUBLISHED_AT_FIELD)
+        return meta.publishedAt?.(doc) ?? null;
+    if (field === URL_FIELD)
+        return null;
     if (!collection.fields.some((f) => f.name === field))
         return null;
     const locale = documentDefaultLocale(doc, localeConfig);
@@ -292,10 +377,13 @@ export function clauseMatches(collection, doc, localeConfig, clause, isPublished
  * content accessors, the *table* may sort any rendered column — sorting is a
  * presentation concern here; the `filterable` flag governs filters.
  */
-export function sortViewDocuments(collection, docs, localeConfig, sort, isPublished = defaultIsPublished) {
+export function sortViewDocuments(collection, docs, localeConfig, sort, isPublished = defaultIsPublished, meta = {}) {
     if (sort === null)
         return [...docs];
-    const positions = new Map(docs.map((doc) => [doc.id, scalarOf(collection, doc, sort.field, localeConfig, isPublished)]));
+    const positions = new Map(docs.map((doc) => [
+        doc.id,
+        scalarOf(collection, doc, sort.field, localeConfig, isPublished, meta),
+    ]));
     return [...docs].sort((a, b) => compareListEntries({ id: a.id, sortValue: positions.get(a.id) ?? null }, { id: b.id, sortValue: positions.get(b.id) ?? null }, sort.dir));
 }
 /**
@@ -303,13 +391,13 @@ export function sortViewDocuments(collection, docs, localeConfig, sort, isPublis
  * ones, sort. Invalid clauses never filter silently — they come back as
  * issues for the UI to surface.
  */
-export function applyViewState(collection, docs, localeConfig, state, isPublished = defaultIsPublished) {
+export function applyViewState(collection, docs, localeConfig, state, isPublished = defaultIsPublished, meta = {}) {
     const issues = validateClauses(collection, state.filters);
     const invalid = new Set(issues.map((issue) => issue.index));
     const active = state.filters.filter((_, index) => !invalid.has(index));
     const matched = docs.filter((doc) => active.every((clause) => clauseMatches(collection, doc, localeConfig, clause, isPublished)));
     return {
-        docs: sortViewDocuments(collection, matched, localeConfig, state.sort, isPublished),
+        docs: sortViewDocuments(collection, matched, localeConfig, state.sort, isPublished, meta),
         issues,
     };
 }
@@ -333,17 +421,24 @@ const NON_DEFAULT_COLUMN_TYPES = new Set(['blocks', 'richText', 'object']);
  * and a view curates columns by declaring an explicit `columns` list (or the
  * `id: 'default'` baseline override).
  */
-function defaultHiddenColumns(collection) {
-    return collection.fields.filter((f) => NON_DEFAULT_COLUMN_TYPES.has(f.type)).map((f) => f.name);
-}
-export function defaultViewState(collection) {
+function defaultHiddenColumns(collection, pseudo = []) {
+    const composites = collection.fields
+        .filter((f) => NON_DEFAULT_COLUMN_TYPES.has(f.type))
+        .map((f) => f.name);
+    // EC-445: applicable opt-in pseudo-columns ($publishedAt) start hidden; the rest
+    // ($updatedAt/$state/$url) are visible by default (owner: keep them on).
+    const hiddenPseudo = pseudo.filter((name) => DEFAULT_HIDDEN_PSEUDO_COLUMNS.has(name));
+    return [...composites, ...hiddenPseudo];
+}
+export function defaultViewState(collection, pseudo = []) {
     return {
         filters: [],
         sort: null,
         // Every field keeps a slot (order + picker), but the composite surfaces start
         // hidden so the default lens is the collection's scalar columns (EC-246b/EC-444).
-        columns: orderedColumnNames(collection),
-        hidden: defaultHiddenColumns(collection),
+        // EC-445: the applicable reserved pseudo-columns append after the data columns.
+        columns: orderedColumnNames(collection, pseudo),
+        hidden: defaultHiddenColumns(collection, pseudo),
     };
 }
 /**
@@ -355,23 +450,35 @@ export function defaultViewState(collection) {
  * 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.
  */
-export function resolveConfigColumns(collection, visible) {
+export function resolveConfigColumns(collection, visible, pseudo = []) {
     if (visible === undefined || visible.length === 0) {
-        const base = defaultViewState(collection);
+        const base = defaultViewState(collection, pseudo);
         return { columns: base.columns, hidden: base.hidden };
     }
-    const schemaNames = orderedColumnNames(collection);
-    const schema = new Set(schemaNames);
+    const universe = orderedColumnNames(collection, pseudo);
+    const inUniverse = new Set(universe);
     const seen = new Set();
     const shown = [];
     for (const name of visible) {
-        if (schema.has(name) && !seen.has(name)) {
+        if (inUniverse.has(name) && !seen.has(name)) {
             shown.push(name);
             seen.add(name);
         }
     }
-    const rest = schemaNames.filter((name) => !seen.has(name));
-    return { columns: [...shown, ...rest], hidden: rest };
+    const rest = universe.filter((name) => !seen.has(name));
+    // EC-445: a schema-ONLY authored list (mentioning no pseudo-column) keeps the
+    // applicable pseudo-columns at their DEFAULT visibility — so a consumer's
+    // pre-EC-445 `columns:[…schema…]` list still shows today's url (+ updatedAt).
+    // Mentioning ANY reorderable pseudo-column switches them to the visible-list rule
+    // (only listed shows). EC-448: `$state` is EXCLUDED here — it is a fixed structural
+    // column, not a reorderable one, so an authored `$state` is an inert no-op: it must
+    // not flip the visible-list rule (nor is it in the universe, so it is simply dropped).
+    const mentionsPseudo = visible.some((name) => isPseudoColumn(name) && name !== STATE_FIELD);
+    const keepVisible = mentionsPseudo
+        ? new Set()
+        : new Set(pseudo.filter((name) => !DEFAULT_HIDDEN_PSEUDO_COLUMNS.has(name)));
+    const hidden = rest.filter((name) => !keepVisible.has(name));
+    return { columns: [...shown, ...rest], hidden };
 }
 /** The reserved `views[]` id whose entry OVERRIDES the synthesized baseline view (EC-444). */
 export const DEFAULT_VIEW_OVERRIDE_ID = 'default';
@@ -436,7 +543,7 @@ function configViewId(name, index) {
  * column. Config views are shared and change only in
  * code — the runtime never mutates them.
  */
-export function configViewsFor(collection) {
+export function configViewsFor(collection, pseudo = []) {
     const declared = collection.views;
     if (!Array.isArray(declared))
         return [];
@@ -453,7 +560,7 @@ export function configViewsFor(collection) {
         seen.add(id);
         // EC-444: `initial` supersedes the deprecated `default` alias (one-release window).
         const initial = view.initial ?? view.default;
-        const { columns, hidden } = resolveConfigColumns(collection, view.columns);
+        const { columns, hidden } = resolveConfigColumns(collection, view.columns, pseudo);
         resolved.push({
             id,
             name: view.name,
@@ -484,8 +591,8 @@ export function hasDefaultViewOverride(collection) {
  * `synthesizedBaseline` the caller passes (the studio's translated "All entries"
  * lens). Pure — the store supplies the synthesized baseline (i18n-bound `name`).
  */
-export function resolveCollectionViews(collection, synthesizedBaseline) {
-    const configViews = configViewsFor(collection);
+export function resolveCollectionViews(collection, synthesizedBaseline, pseudo = []) {
+    const configViews = configViewsFor(collection, pseudo);
     const overrideIndex = configViews.findIndex((view) => view.id === DEFAULT_VIEW_OVERRIDE_ID);
     if (overrideIndex < 0)
         return [synthesizedBaseline, ...configViews];
@@ -555,12 +662,15 @@ export function configViewIssues(collection) {
  * selector, treating the first visible column as the title), then the
  * remaining fields in schema order.
  */
-function orderedColumnNames(collection) {
+function orderedColumnNames(collection, pseudo = []) {
     const names = collection.fields.map((field) => field.name);
     const title = titleFieldOf(collection)?.name;
-    if (title === undefined || !names.includes(title))
-        return names;
-    return [title, ...names.filter((name) => name !== title)];
+    const schemaOrdered = title === undefined || !names.includes(title)
+        ? names
+        : [title, ...names.filter((name) => name !== title)];
+    // EC-445: the column UNIVERSE = schema fields, then the applicable reserved
+    // pseudo-columns (they are NOT in `collection.fields`).
+    return [...schemaOrdered, ...pseudo];
 }
 /** Deep-cloned canonical form (stable key order via the Zod shape). */
 export function normalizeViewState(state) {
@@ -578,26 +688,40 @@ export function viewStatesEqual(a, b) {
  * or hidden" — order is preserved across hide/show because visibility lives in
  * `hidden`, never in the order.
  */
-export function resolveColumns(collection, state) {
+export function resolveColumns(collection, state, pseudo = []) {
     const schemaNames = collection.fields.map((field) => field.name);
-    const schema = new Set(schemaNames);
+    // EC-445: the valid universe to KEEP from the saved order is schema fields PLUS the
+    // applicable pseudo-columns (which are not in `collection.fields`) — so a seeded
+    // `$state`/`$url`/`$updatedAt` is preserved + ordered, never dropped as "unknown".
+    const keep = new Set([...schemaNames, ...pseudo]);
     const hidden = new Set(state.hidden);
-    // Keep the saved order, restricted to live fields and de-duplicated (a
+    const inState = new Set(state.columns);
+    // Keep the saved order, restricted to the live universe and de-duplicated (a
     // corrupted persisted state must never render one field as two columns).
     const ordered = [];
     const seen = new Set();
     for (const name of state.columns) {
-        if (schema.has(name) && !seen.has(name)) {
+        if (keep.has(name) && !seen.has(name)) {
             ordered.push(name);
             seen.add(name);
         }
     }
-    const appended = schemaNames.filter((name) => !seen.has(name));
-    return [...ordered, ...appended].map((field) => ({ field, visible: !hidden.has(field) }));
+    // Append universe members the saved order predates: new schema fields (EC-213
+    // discovery), then applicable pseudo-columns not yet placed (EC-445).
+    const appended = [
+        ...schemaNames.filter((name) => !seen.has(name)),
+        ...pseudo.filter((name) => !seen.has(name)),
+    ];
+    return [...ordered, ...appended].map((field) => {
+        // A freshly-appended opt-in pseudo-column ($publishedAt) starts hidden; once it
+        // is in the saved order (an editor un-hid it) its visibility follows `hidden`.
+        const defaultHiddenAppend = DEFAULT_HIDDEN_PSEUDO_COLUMNS.has(field) && !inState.has(field);
+        return { field, visible: !hidden.has(field) && !defaultHiddenAppend };
+    });
 }
 /** The visible columns of a view, in render order (EC-213). */
-export function visibleColumns(collection, state) {
-    return resolveColumns(collection, state)
+export function visibleColumns(collection, state, pseudo = []) {
+    return resolveColumns(collection, state, pseudo)
         .filter((column) => column.visible)
         .map((column) => column.field);
 }
@@ -610,9 +734,11 @@ export function visibleColumns(collection, state) {
  * the first visible column, then the first field, then `id`, when no title field
  * is resolvable (e.g. a function title with no backing `title` field).
  */
-export function primaryColumn(collection, state) {
+export function primaryColumn(collection, state, pseudo = []) {
     return (titleFieldOf(collection)?.name ??
-        visibleColumns(collection, state)[0] ??
+        // EC-445: a pseudo-column is never the identity column (it has no title value) —
+        // fall back to the first visible SCHEMA column.
+        visibleColumns(collection, state, pseudo).find((name) => !isPseudoColumn(name)) ??
         collection.fields[0]?.name ??
         'id');
 }
@@ -622,8 +748,8 @@ export function primaryColumn(collection, state) {
  * `hidden` to fields the live schema still has (a column removed from the schema
  * must not leave dead `hidden` cruft that trips dirty-detection / persists).
  */
-function withResolvedOrder(collection, state) {
-    const columns = resolveColumns(collection, state).map((column) => column.field);
+function withResolvedOrder(collection, state, pseudo = []) {
+    const columns = resolveColumns(collection, state, pseudo).map((column) => column.field);
     const live = new Set(columns);
     const hidden = state.hidden.filter((name) => live.has(name));
     return { ...state, columns, hidden };
@@ -635,24 +761,24 @@ function withResolvedOrder(collection, state) {
  * reconciliation or a stale `hidden` entry (only a real filter/sort/visibility/
  * order change counts as "unsaved").
  */
-export function canonicalViewState(collection, state) {
-    return normalizeViewState(withResolvedOrder(collection, state));
+export function canonicalViewState(collection, state, pseudo = []) {
+    return normalizeViewState(withResolvedOrder(collection, state, pseudo));
 }
 /**
  * Toggle a column's visibility — position is preserved (EC-213): visibility
  * lives in `hidden`, the order in `columns` is untouched. Columns the saved
  * order predates are pinned into `columns` first so their place is stable.
  */
-export function toggleColumn(collection, state, field) {
-    const base = withResolvedOrder(collection, state);
+export function toggleColumn(collection, state, field, pseudo = []) {
+    const base = withResolvedOrder(collection, state, pseudo);
     const hidden = base.hidden.includes(field)
         ? base.hidden.filter((name) => name !== field)
         : [...base.hidden, field];
     return { ...base, hidden };
 }
 /** Move a column one position left (-1) or right (+1) in the full column order. */
-export function moveColumn(collection, state, field, delta) {
-    const base = withResolvedOrder(collection, state);
+export function moveColumn(collection, state, field, delta, pseudo = []) {
+    const base = withResolvedOrder(collection, state, pseudo);
     const from = base.columns.indexOf(field);
     const to = from + delta;
     if (from < 0 || to < 0 || to >= base.columns.length)