@elytracms/studio 0.0.44 → 0.0.45

package/convex/cms.ts

@@ -1,4 +1,6 @@
 import { v } from 'convex/values'
+import { foldDocument, unfoldDocument } from '@elytracms/core/cms-core'
+import type { CmsDocument } from '@elytracms/core/cms-core'
 import { mutation, query } from './functions'
 import { requireCapability } from './guard'
 
@@ -9,8 +11,29 @@ import { requireCapability } from './guard'
  * table and no schema read/write function here. Collection-membership
  * validation lives in `@elytracms/core/cms-core` `validateDocument` (the studio runs it
  * pre-dispatch); this layer is a pure document store.
+ *
+ * ## EC-260 depth-budget codec (the storage boundary)
+ *
+ * Convex caps STORED documents at 16 nesting levels but allows 64 in function
+ * args/returns. Ordinary content (deep rich text, nested compositions) trips 16 at
+ * rest, so every write here FOLDS over-budget field values into self-describing
+ * leaf envelopes immediately before `ctx.db`, and every read UNFOLDS before the
+ * value leaves the function. Mutations receive the UNFOLDED value over the wire, so
+ * the AD-15 reference walker (in the write-chokepoint trigger, which unfolds first)
+ * always sees structured content. The wire never carries an envelope; only raw
+ * `ctx.db` reads / the dashboard see the folded storage form.
  */
 
+/** Unfold the `document` blob of a stored row before it leaves the function. */
+function withUnfoldedDocument<R extends { document: unknown }>(row: R): R {
+  return { ...row, document: unfoldDocument(row.document as CmsDocument) }
+}
+
+/** Unfold the `snapshot` blob of a version row before it leaves the function. */
+function withUnfoldedSnapshot<R extends { snapshot: unknown }>(row: R): R {
+  return { ...row, snapshot: unfoldDocument(row.snapshot as CmsDocument) }
+}
+
 export const upsertDocument = mutation({
   args: {
     collection: v.string(),
@@ -21,6 +44,10 @@ export const upsertDocument = mutation({
   },
   handler: async (ctx, args) => {
     await requireCapability(ctx, 'content.write') // EC-150
+    // EC-260: fold for storage. `args.document` arrives UNFOLDED over the 64-level
+    // arg wire; the trigger unfolds before extracting references, so folding here
+    // (strictly before the `ctx.db` write) never hides a reference from the walker.
+    const stored = { ...args, document: foldDocument(args.document as CmsDocument) }
     const existing = await ctx.db
       .query('cmsDocuments')
       .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
@@ -28,17 +55,19 @@ export const upsertDocument = mutation({
     if (existing) {
       // EC-153 parity: updates preserve `createdAt`, exactly like in-memory.
       // EC-286: the write-chokepoint trigger reindexes references in-transaction.
-      const patch = { ...args, createdAt: existing.createdAt }
+      const patch = { ...stored, createdAt: existing.createdAt }
       await ctx.db.patch(existing._id, patch)
       // EC-322: return the merged row directly instead of re-reading the full
       // (up-to-~20 KB) document body via `ctx.db.get`. `patch` only overwrites the
       // supplied fields, so `{ ...existing, ...patch }` is byte-identical to the
       // stored row (system fields + untouched `publishedVersion` carried from
       // `existing`) — cutting one full-document read off the hottest write path.
-      return { ...existing, ...patch }
+      // EC-260: unfold the folded body back to structured form for the return.
+      return withUnfoldedDocument({ ...existing, ...patch })
     }
-    const id = await ctx.db.insert('cmsDocuments', args)
-    return ctx.db.get(id)
+    const id = await ctx.db.insert('cmsDocuments', stored)
+    const row = await ctx.db.get(id)
+    return row ? withUnfoldedDocument(row) : row
   },
 })
 
@@ -46,10 +75,11 @@ export const getDocument = query({
   args: { collection: v.string(), docId: v.string() },
   handler: async (ctx, args) => {
     await requireCapability(ctx, 'content.read') // EC-150
-    return ctx.db
+    const row = await ctx.db
       .query('cmsDocuments')
       .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
       .first()
+    return row ? withUnfoldedDocument(row) : row // EC-260: unfold before returning
   },
 })
 
@@ -57,14 +87,13 @@ export const listDocuments = query({
   args: { collection: v.optional(v.string()) },
   handler: async (ctx, args) => {
     await requireCapability(ctx, 'content.read') // EC-150
-    if (args.collection) {
-      const collection = args.collection
-      return ctx.db
-        .query('cmsDocuments')
-        .withIndex('by_collection', (q) => q.eq('collection', collection))
-        .collect()
-    }
-    return ctx.db.query('cmsDocuments').collect()
+    const rows = args.collection
+      ? await ctx.db
+          .query('cmsDocuments')
+          .withIndex('by_collection', (q) => q.eq('collection', args.collection as string))
+          .collect()
+      : await ctx.db.query('cmsDocuments').collect()
+    return rows.map(withUnfoldedDocument) // EC-260: unfold before returning
   },
 })
 
@@ -113,8 +142,12 @@ export const saveDocumentVersion = mutation({
       .order('desc')
       .first()
     const version = (latest?.version ?? 0) + 1
-    const id = await ctx.db.insert('documentVersions', { ...args, version })
-    return ctx.db.get(id)
+    // EC-260: the snapshot embeds the CmsDocument at draft depth, so it folds at rest
+    // identically. `documentVersions` has no trigger — no walker to keep structured.
+    const stored = { ...args, snapshot: foldDocument(args.snapshot as CmsDocument), version }
+    const id = await ctx.db.insert('documentVersions', stored)
+    const row = await ctx.db.get(id)
+    return row ? withUnfoldedSnapshot(row) : row
   },
 })
 
@@ -127,7 +160,7 @@ export const listDocumentVersions = query({
       .withIndex('by_doc', (q) => q.eq('collection', args.collection).eq('docId', args.docId))
       .collect()
     // Newest first (parity with the in-memory `listDocumentVersions`).
-    return rows.sort((a, b) => b.version - a.version)
+    return rows.sort((a, b) => b.version - a.version).map(withUnfoldedSnapshot) // EC-260
   },
 })
 
@@ -138,12 +171,13 @@ export const getDocumentVersion = query({
     // EC-307: address the row directly via `by_doc_version` instead of collecting
     // the whole — unbounded — per-document history and finding in JS. `version` is
     // unique per (collection, docId), so `.unique()` both fetches and asserts that.
-    return ctx.db
+    const row = await ctx.db
       .query('documentVersions')
       .withIndex('by_doc_version', (q) =>
         q.eq('collection', args.collection).eq('docId', args.docId).eq('version', args.version),
       )
       .unique()
+    return row ? withUnfoldedSnapshot(row) : row // EC-260: unfold before returning
   },
 })
 
@@ -175,7 +209,8 @@ export const listPublishedDocuments = query({
           q.eq('collection', doc.collection).eq('docId', doc.docId).eq('version', version),
         )
         .unique()
-      if (pinned) snapshots.push(pinned.snapshot)
+      // EC-260: unfold the pinned snapshot before it leaves the function.
+      if (pinned) snapshots.push(unfoldDocument(pinned.snapshot as CmsDocument))
     }
     return snapshots
   },
@@ -186,7 +221,8 @@ export const listAllDocumentVersions = query({
   args: {},
   handler: async (ctx) => {
     await requireCapability(ctx, 'content.read') // EC-150
-    return ctx.db.query('documentVersions').collect()
+    const rows = await ctx.db.query('documentVersions').collect()
+    return rows.map(withUnfoldedSnapshot) // EC-260: unfold before returning
   },
 })
 
@@ -208,7 +244,8 @@ export const publishDocumentVersion = mutation({
     // write-chokepoint trigger sees — it reindexes the published reference rows
     // and fires host revalidation (EC-146 instant publish). No manual calls here.
     await ctx.db.patch(doc._id, { publishedVersion: args.version, updatedAt: args.updatedAt })
-    return ctx.db.get(doc._id)
+    const row = await ctx.db.get(doc._id)
+    return row ? withUnfoldedDocument(row) : row // EC-260: unfold before returning
   },
 })
 
@@ -225,6 +262,7 @@ export const unpublishDocument = mutation({
     // EC-286: clearing the pin is a change the write-chokepoint trigger sees — it
     // drops the published index rows and revalidates the host. No manual calls.
     await ctx.db.patch(doc._id, { publishedVersion: undefined, updatedAt: args.updatedAt })
-    return ctx.db.get(doc._id)
+    const row = await ctx.db.get(doc._id)
+    return row ? withUnfoldedDocument(row) : row // EC-260: unfold before returning
   },
 })

package/convex/content.ts

@@ -1,4 +1,4 @@
-import { documentKey, documentSchema } from '@elytracms/core/cms-core'
+import { documentKey, documentSchema, unfoldValue } from '@elytracms/core/cms-core'
 import type {
   CmsDocument,
   CmsValidationIssue,
@@ -157,7 +157,9 @@ export async function createContent(
   // a published read can serve the *pinned* version rather than the live draft.
   const versionsByKey = new Map<string, Map<number, CmsDocument>>()
   for (const row of await ctx.db.query('documentVersions').collect()) {
-    const parsed = documentSchema.safeParse(row.snapshot)
+    // EC-260: unfold the folded storage form before parsing — the kit resolves over
+    // STRUCTURED values, exactly like the Next-side snapshot (byte-equivalence).
+    const parsed = documentSchema.safeParse(unfoldValue(row.snapshot))
     if (!parsed.success) continue
     const key = `${row.collection}:${row.docId}`
     let byVersion = versionsByKey.get(key)
@@ -176,7 +178,8 @@ export async function createContent(
   // resolves exactly as before.
   const parsedSources: { key: string; source: ContentDocumentSource }[] = []
   for (const row of documentRows) {
-    const parsed = documentSchema.safeParse(row.document)
+    // EC-260: unfold the folded storage form before parsing (see the versions loop).
+    const parsed = documentSchema.safeParse(unfoldValue(row.document))
     if (!parsed.success) {
       loadIssues.push({
         code: 'invalid-stored-document',

package/convex/delivery.ts

@@ -1,4 +1,5 @@
 import { v } from 'convex/values'
+import { unfoldValue } from '@elytracms/core/cms-core'
 import { dataSourceSchema } from '@elytracms/core/data-binding'
 import { query } from './functions'
 import type { QueryCtx } from './functions'
@@ -134,6 +135,10 @@ export async function loadSnapshot(
   const { projectId } = args
 
   const documentRows = await ctx.db.query('cmsDocuments').collect()
+  // EC-260: the stored `document`/`snapshot` blobs are folded; unfold every one
+  // before it enters the delivery snapshot so the host receives STRUCTURED content
+  // (no client ever sees an envelope). `unfoldValue` is identity on legacy data.
+  const unfoldDraft = (row: { document: unknown }): unknown => unfoldValue(row.document)
   // THE published-content invariant (the trust boundary): the public snapshot
   // ships ONLY published content — never a draft. Under the EC-224 pointer model
   // a published row is served as its *pinned version snapshot* (decoupled from
@@ -142,7 +147,7 @@ export async function loadSnapshot(
   // fallback (the `state` field is gone).
   let documents: unknown[]
   if (perspective === 'draft') {
-    documents = documentRows.map((row) => row.document as unknown)
+    documents = documentRows.map(unfoldDraft)
   } else {
     documents = []
     for (const row of documentRows) {
@@ -160,7 +165,7 @@ export async function loadSnapshot(
           q.eq('collection', row.collection).eq('docId', row.docId).eq('version', version),
         )
         .unique()
-      if (pinned) documents.push(pinned.snapshot as unknown)
+      if (pinned) documents.push(unfoldValue(pinned.snapshot))
     }
   }
 
@@ -202,9 +207,7 @@ export async function loadSnapshot(
   // extracted from every stored row (independent of publish state) — published
   // bindings must always resolve their definitions, even when the defining
   // `cms-data-sources` row is not itself "published".
-  const sources = dataSourcesFromSystemCollection(
-    documentRows.map((row) => row.document as unknown),
-  )
+  const sources = dataSourcesFromSystemCollection(documentRows.map(unfoldDraft))
 
   // Editorial redirects (EC-303): only ENABLED entries serve — a disabled redirect
   // is stored but never live, in either perspective. Projected to the routing

package/convex/triggers.ts

@@ -1,3 +1,4 @@
+import { unfoldDocument } from '@elytracms/core/cms-core'
 import type { CmsDocument } from '@elytracms/core/cms-core'
 import { Triggers } from 'convex-helpers/server/triggers'
 import type { DataModel } from './functions'
@@ -42,11 +43,17 @@ triggers.register('cmsDocuments', async (ctx, change) => {
     return
   }
   const doc = change.newDoc
+  // EC-260: the stored `document` is FOLDED (deep field values collapsed to leaf
+  // envelopes). Unfold it here so `extractReferences` walks the STRUCTURED value and
+  // still finds references buried inside a folded field — this is the write chokepoint
+  // (EC-286), so every writer's references are derived from structured content by
+  // construction, regardless of the folded storage form. `unfoldDocument` is identity
+  // on already-structural data, so a legacy unfolded row costs nothing.
   await maintainDocumentReferences(
     ctx,
     doc.collection,
     doc.docId,
-    doc.document as CmsDocument,
+    unfoldDocument(doc.document as CmsDocument),
     doc.publishedVersion !== undefined,
   )
   const before = change.oldDoc?.publishedVersion

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@elytracms/studio",
   "author": "finaldream <hi@finaldream.de>",
-  "version": "0.0.44",
+  "version": "0.0.45",
   "private": false,
   "description": "The Elytra studio engine (UI + lib + routes + data-only Convex schema) as an importable package. Extraction staged in EXTRACTION.md (EC-223); Stages 1-2 = UI primitives + router-free lib leaves.",
   "license": "MIT",
@@ -136,7 +136,7 @@
     "lucide-react": "^1.23.0",
     "tailwind-merge": "^3.6.0",
     "zod": "^4.4.3",
-    "@elytracms/core": "^0.0.44"
+    "@elytracms/core": "^0.0.45"
   },
   "peerDependencies": {
     "@tanstack/react-router": "^1.170.0",