@voltro/cli 0.52.0 → 0.54.0

package/templates/apps/changelog/src/pages/page.test.tsx

@@ -1,49 +1,25 @@
 // @vitest-environment jsdom
 //
-// `/` changelog index — lists every release, newest first. The real release
-// source (`../lib/releases`) reads .mdx via `import.meta.glob` + node-gated
-// shiki, so we mock it with canned releases and assert the observable render:
-// config exports, meta, one entry per release, and its tags + link.
+// `/` changelog index — lists every release, newest first, loaded through
+// the REAL `releases` content collection (this app's content/releases/*.mdx)
+// so the test exercises frontmatter decoding, draft/future filtering and
+// ordering — no canned copies to drift.
 
 import { afterEach, describe, expect, test, vi } from 'vitest'
 import { act, createElement, type ReactNode } from 'react'
 import { createRoot, type Root } from 'react-dom/client'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { setContentRoot } from '@voltro/content'
 
-interface Release {
-  version: string
-  releasedAt: string
-  slug: string
-  tags: ReadonlyArray<string>
-  title: string
-  summary: string
-  html: string
-}
-
-const releases: ReadonlyArray<Release> = [
-  {
-    version: '0.2.0',
-    releasedAt: '2026-06-21',
-    slug: 'v0-2-0',
-    tags: ['feature', 'performance'],
-    title: 'Typed env + faster boot',
-    summary: 'Declare your environment once.',
-    html: '<p>body</p>',
-  },
-  {
-    version: '0.1.0',
-    releasedAt: '2026-01-15',
-    slug: 'v0-1-0',
-    tags: ['feature'],
-    title: 'First release',
-    summary: 'The initial cut.',
-    html: '<p>body</p>',
-  },
-]
+setContentRoot(join(dirname(fileURLToPath(import.meta.url)), '..', '..'))
 
-vi.mock('../lib/releases', () => ({ releases }))
 // `withLocalePrefix` (lib/locale) reads useLocation; the page pins the locale
 // via useLocale, so any bare path is fine here.
-vi.mock('@voltro/web', () => ({ useLocation: () => '/' }))
+vi.mock('@voltro/web', () => ({
+  useLocation: () => '/',
+  useLoaderData: () => entries,
+}))
 // Chrome (meta via getCatalog + the empty state) comes from @voltro/i18n;
 // stub it (identity catalog defs, useLocale → en, <T> passes children through).
 vi.mock('@voltro/i18n', () => ({
@@ -57,7 +33,8 @@ vi.mock('@voltro/i18n', () => ({
   T: ({ id }: { id: string }) => id,
 }))
 
-const { default: ChangelogIndex, meta, renderMode, interactive } = await import('./page')
+const { default: ChangelogIndex, meta, renderMode, interactive, loader } = await import('./page')
+const entries = await loader()
 
 ;(globalThis as { IS_REACT_ACT_ENVIRONMENT?: boolean }).IS_REACT_ACT_ENVIRONMENT = true
 

package/templates/apps/changelog/src/pages/page.tsx

@@ -2,16 +2,18 @@
 // locale) and mirrored at `/de` by src/pages/[locale]/index.tsx. Pure static
 // render with no client JS (`interactive: 'none'`).
 //
-// `meta` is a FUNCTION of `{ locale }` so each variant's <title>/<description>
-// is localised in the pre-rendered HTML. The release list itself is CONTENT
-// (the .mdx files) and is NOT translated — only the chrome (page meta, the
-// empty state) comes from the catalogs. Entry links are locale-prefixed via
-// `withLocalePrefix` so /de stays on /de.
+// The list comes from the `releases` CONTENT COLLECTION: the loader runs at
+// build time, decodes each entry's frontmatter against the schema, and
+// filters drafts + future-dated entries (visibleReleases). The release list
+// itself is CONTENT and is NOT translated — only the chrome comes from the
+// catalogs. Entry links are locale-prefixed via `withLocalePrefix`.
 
 import type { ReactNode } from 'react'
 import type { PageMeta } from '@voltro/web'
+import { useLoaderData } from '@voltro/web'
+import { getCollection } from '@voltro/content'
 import { T, useLocale } from '@voltro/i18n'
-import { releases } from '../lib/releases'
+import { releases, tagsOf, visibleReleases, type ReleaseData, type ReleaseEntry } from '../collections/releases.collection'
 import { getCatalog, withLocalePrefix } from '../lib/locale'
 
 export const renderMode = 'static' as const
@@ -25,9 +27,13 @@ export const meta = ({ locale }: { locale: string }): PageMeta => {
   }
 }
 
+export const loader = async (): Promise<ReadonlyArray<ReleaseEntry>> =>
+  visibleReleases(await getCollection<ReleaseData>(releases.name))
+
 export default function ChangelogIndex(): ReactNode {
+  const entries = useLoaderData<ReadonlyArray<ReleaseEntry>>()
   const locale = useLocale()
-  if (releases.length === 0) {
+  if (entries.length === 0) {
     return (
       <p>
         <T id="empty.body" values={{ code: (chunks: ReactNode) => <code>{chunks}</code> }} />
@@ -36,18 +42,18 @@ export default function ChangelogIndex(): ReactNode {
   }
   return (
     <div>
-      {releases.map((release) => (
+      {entries.map((release) => (
         <article key={release.slug} className="changelog-entry">
           <p className="changelog-meta">
-            <time dateTime={release.releasedAt}>{release.releasedAt}</time> · v{release.version}
-            {release.tags.map((tag) => (
+            <time dateTime={release.data.releasedAt}>{release.data.releasedAt}</time> · v{release.data.version}
+            {tagsOf(release.data).map((tag) => (
               <span key={tag} className="changelog-tag">{tag}</span>
             ))}
           </p>
           <h2>
-            <a href={withLocalePrefix(`/${release.slug}`, locale)}>{release.title}</a>
+            <a href={withLocalePrefix(`/${release.slug}`, locale)}>{release.data.title}</a>
           </h2>
-          <p>{release.summary}</p>
+          <p>{release.data.summary}</p>
         </article>
       ))}
     </div>

package/templates/apps/edge-functions/package.json

@@ -12,8 +12,8 @@
   },
   "dependencies": {
     "@effect/platform": "^0.97.0",
-    "@voltro/cli": "0.52.0",
-    "@voltro/serverless": "0.52.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/serverless": "0.54.0",
     "effect": "^3.22.0"
   },
   "devDependencies": {

package/templates/apps/frontend-admin/package.json

@@ -12,18 +12,18 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.52.0",
-    "@voltro/cli": "0.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/env": "0.52.0",
-    "@voltro/i18n": "0.52.0",
-    "@voltro/ui-shadcn": "0.52.0",
-    "@voltro/web": "0.52.0",
+    "@{{projectName}}/api": "0.54.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-app/package.json

@@ -12,19 +12,19 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.52.0",
-    "@voltro/cli": "0.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/env": "0.52.0",
-    "@voltro/i18n": "0.52.0",
-    "@voltro/ui-shadcn": "0.52.0",
-    "@voltro/web": "0.52.0",
+    "@{{projectName}}/api": "0.54.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
-    "@voltro/testing": "0.52.0",
+    "@voltro/devtools": "0.54.0",
+    "@voltro/testing": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-auth/package.json

@@ -12,18 +12,18 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.52.0",
-    "@voltro/cli": "0.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/env": "0.52.0",
-    "@voltro/i18n": "0.52.0",
-    "@voltro/ui-shadcn": "0.52.0",
-    "@voltro/web": "0.52.0",
+    "@{{projectName}}/api": "0.54.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-blank/package.json

@@ -12,17 +12,17 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@voltro/cli": "0.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/env": "0.52.0",
-    "@voltro/i18n": "0.52.0",
-    "@voltro/ui-shadcn": "0.52.0",
-    "@voltro/web": "0.52.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-cms/package.json

@@ -12,19 +12,19 @@
     "test": "voltro test"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.52.0",
-    "@voltro/cli": "0.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/cms": "0.52.0",
-    "@voltro/env": "0.52.0",
-    "@voltro/i18n": "0.52.0",
-    "@voltro/ui-shadcn": "0.52.0",
-    "@voltro/web": "0.52.0",
+    "@{{projectName}}/api": "0.54.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/cms": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
+    "@voltro/devtools": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-collab/README.md

@@ -2,7 +2,7 @@
 
 Voltro collaborative-editing frontend (template: **frontend-collab**).
 
-A document editor whose textarea is bound to a `crdtText()` body over the
+A **rich-text** document editor — Tiptap, bound to a `crdtDoc()` body over the
 framework's reactive loop. Type in **two browser tabs at once** and the edits
 **converge** — no last-write-wins loser — because the api merges every update
 into the shared document server-side, then broadcasts the merged result back
@@ -30,45 +30,64 @@ same URL and type in both. Every keystroke merges — both tabs' edits survive.
 ```
  Tab A                              api (api-collab)
  ─────                              ────────────────
- local crdtText() handle           documents.setBody (crdtText 'body' column)
-   │  keystroke → insert/delete       └─ runtime folds the update into the
-   │  → handle.encode()  ──rpc──►        STORED state (mergeCrdtStates) → merged
+ useCrdtDoc  →  CrdtDocHandle      documents.setBody (crdtDoc 'body' column)
+   │  editor edit → doc.onUpdate       └─ runtime folds the update into the
+   │  (local:true) → push ──rpc──►        STORED state (mergeCrdtStates) → merged
    ▼                                        └─► reactive delta ──WS──► every tab
  useSubscription('app',
-   'documents.list')  ◄──WS── merged body ── handle.merge(body) → textarea
+   'documents.list')  ◄──WS── merged body ── folded (local:false → no push back)
+   │
+   └─ useCrdtEditor({ doc })  →  Tiptap <EditorContent>
 ```
 
 1. **`useSubscription('app', 'documents.list')`** streams the shared document,
-   including its **merged** `body` (encoded CRDT bytes), on every write.
-2. A **local `crdtText()` handle** (`@voltro/local-first`) is seeded from that
-   body. Each keystroke applies a contiguous insert/delete to the handle and
-   sends `handle.encode()` via **`useMutation('app', 'documents.setBody')`**.
-3. The api's **authoritative server-side merge** folds the update into the
+   including its **merged** `body` (encoded CRDT bytes), on every write. That
+   value is `useCrdtDoc`'s `remote` — `null` means *not loaded*, not *empty*.
+2. **`useCrdtDoc`** owns one sync client and one live CRDT document for the
+   cell. **`useCrdtEditor({ doc })`** mounts a Tiptap editor over it, so typing
+   mutates the shared document directly.
+3. Those edits surface as `doc.onUpdate(update, { local: true })` and are queued
+   as **incremental** updates through **`useMutation('app',
+   'documents.setBody')`** — a keystroke is bytes, not the whole document.
+4. The api's **authoritative server-side merge** folds each update into the
    stored state before broadcasting — so concurrent edits converge.
-4. Incoming server bodies are **folded back** into the local handle
-   (idempotent), keeping every tab in sync.
+5. Incoming bodies are **folded back** into the same document. Those folds
+   report `local: false`, and the hook's **echo guard** drops them: without it,
+   one keystroke becomes one server write *per open tab*.
 
-This page is exactly the app-level binding the local-first docs describe as the
-`SyncClient` transport: `push` = the `setBody` mutation, `onRemoteState` = the
-`documents` subscription.
+The two names the framework cannot derive are the app's to supply, and they are
+the whole binding: `push` = the `setBody` mutation, `remote` = the `documents`
+subscription. The sync-client lifecycle, offline queue, bounded retry,
+`outstanding`/`synced` and the echo guard all live in the hook.
 
-## Not wired here: presence cursors
+## `renderMode = 'client'`
 
-Live "who else is editing" cursors (`usePresence` from
-`@voltro/local-first/react`) need a `PresenceChannel` bound to the app's
-broadcast broker — a runtime binding, not zero-infra in a single dev process
-across tabs — so this template omits them. The CRDT text convergence above needs
-none of that; it rides the reactive engine you already have.
+`page.tsx` sets it explicitly. A rich-text editor needs a browser: `renderMode`
+defaults to `'static'`, which pre-renders at build time, and Tiptap's
+`new Editor()` finds no `window` there — the build fails. There is nothing
+worth pre-rendering for a document that arrives over a live subscription
+anyway.
+
+## Not wired here: presence carets
+
+Live "who else is editing" carets need two things this template does not ship:
+a `PresenceChannel` bound to the app's broadcast broker, and an
+`AwarenessTransport` over a `delivery: 'latest'` event
+(`useCrdtEditor({ doc, awareness, user })`). Both are runtime bindings, not
+zero-infra in a single dev process across tabs. The convergence above needs
+none of it — it rides the reactive engine you already have.
 
 ## Files
 
 ```
 app.config.ts            type:web + the `apis: { app }` wiring
-package.json             depends on @{{projectName}}/api (the sibling) + @voltro/local-first
+package.json             depends on @{{projectName}}/api (the sibling),
+                         @voltro/local-first + the four @tiptap/* peers
 src/pages/
   layout.tsx             root shell (header + <main>)
-  page.tsx               the collaborative editor — subscription + CRDT handle + setBody
-  page.test.tsx          render + edit-dispatch tests (jsdom)
+  page.tsx               the collaborative editor — subscription + useCrdtDoc + useCrdtEditor
+  page.test.tsx          page-contract tests (jsdom) — states, create, and a
+                         server-side fold converging into the open editor
 src/locales/{en,de}.ts   bilingual UI strings
 ```
 

package/templates/apps/frontend-collab/app.config.ts

@@ -1,8 +1,8 @@
 // Web app for the {{projectName}} project. Read by `voltro dev` / `voltro start`.
 //
-// This is the COLLABORATIVE-EDITING frontend — a textarea bound to a
-// `crdtText()` document body over the framework's reactive loop. Open it in two
-// browser tabs and type in both: the edits CONVERGE (no last-write-wins loser)
+// This is the COLLABORATIVE-EDITING frontend — a Tiptap rich-text editor bound
+// to a `crdtDoc()` document body over the framework's reactive loop. Open it in
+// two browser tabs and type in both: the edits CONVERGE (no last-write-wins loser)
 // because the api's server-authoritative CRDT merge folds every update into the
 // stored state, then the reactive engine broadcasts the merged row back. Zero
 // infra — the merge + broadcast are in-process on a single `voltro dev`.

package/templates/apps/frontend-collab/package.json

@@ -12,20 +12,24 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@{{projectName}}/api": "0.52.0",
-    "@voltro/cli": "0.52.0",
-    "@voltro/client": "0.52.0",
-    "@voltro/env": "0.52.0",
-    "@voltro/i18n": "0.52.0",
-    "@voltro/local-first": "0.52.0",
-    "@voltro/ui-shadcn": "0.52.0",
-    "@voltro/web": "0.52.0",
+    "@{{projectName}}/api": "0.54.0",
+    "@tiptap/extension-collaboration": "^3.0.0",
+    "@tiptap/extension-collaboration-caret": "^3.0.0",
+    "@tiptap/react": "^3.0.0",
+    "@tiptap/starter-kit": "^3.0.0",
+    "@voltro/cli": "0.54.0",
+    "@voltro/client": "0.54.0",
+    "@voltro/env": "0.54.0",
+    "@voltro/i18n": "0.54.0",
+    "@voltro/local-first": "0.54.0",
+    "@voltro/ui-shadcn": "0.54.0",
+    "@voltro/web": "0.54.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@voltro/devtools": "0.52.0",
-    "@voltro/testing": "0.52.0",
+    "@voltro/devtools": "0.54.0",
+    "@voltro/testing": "0.54.0",
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "jsdom": "^30.0.0",

package/templates/apps/frontend-collab/src/locales/de.ts

@@ -14,7 +14,7 @@ export default defineLocale<typeof en>()({
   'lang.label':  'Sprache',
 
   'editor.heading':       'Kollaborativer Editor',
-  'editor.intro':         'Öffne diese Seite in <strong>zwei Browser-Tabs</strong> und tippe in beiden. Die Änderungen <strong>konvergieren</strong> — kein Last-Write-Wins-Verlierer — weil die API jedes Update serverseitig in den gemeinsamen <code>crdtText()</code>-Body mergt und live zurücksendet.',
+  'editor.intro':         'Öffne diese Seite in <strong>zwei Browser-Tabs</strong> und tippe in beiden. Die Änderungen <strong>konvergieren</strong> — kein Last-Write-Wins-Verlierer — weil die API jedes Update serverseitig in den gemeinsamen <code>crdtDoc()</code>-Body mergt und live zurücksendet.',
   'editor.status.tenant': 'Mandant <code>{tenant}</code> · Revision {revision}',
   'editor.status.saving': ' · synchronisiere…',
   'editor.status.loading': ' · lädt…',
@@ -24,6 +24,5 @@ export default defineLocale<typeof en>()({
   'editor.create':        'Dokument erstellen',
   'editor.creating':      'Wird erstellt…',
   'editor.docLabel':      'Bearbeite <strong>{title}</strong>',
-  'editor.placeholder':   'Fang an zu tippen — jeder Tastendruck synchronisiert und mergt.',
   'editor.hint':          'Tipp: Öffne einen zweiten Tab und tippe gleichzeitig. Beide Änderungen bleiben erhalten.',
 })

package/templates/apps/frontend-collab/src/locales/en.ts

@@ -16,7 +16,7 @@ export default defineCatalog({
 
   // ---- Editor page (pages/page.tsx) ----
   'editor.heading':       'Collaborative editor',
-  'editor.intro':         'Open this page in <strong>two browser tabs</strong> and type in both. Edits <strong>converge</strong> — no last-write-wins loser — because the api merges every update into the shared <code>crdtText()</code> body server-side, then broadcasts it back live.',
+  'editor.intro':         'Open this page in <strong>two browser tabs</strong> and type in both. Edits <strong>converge</strong> — no last-write-wins loser — because the api merges every update into the shared <code>crdtDoc()</code> body server-side, then broadcasts it back live.',
   'editor.status.tenant': 'Tenant <code>{tenant}</code> · revision {revision}',
   'editor.status.saving': ' · syncing…',
   'editor.status.loading': ' · loading…',
@@ -26,6 +26,5 @@ export default defineCatalog({
   'editor.create':        'Create document',
   'editor.creating':      'Creating…',
   'editor.docLabel':      'Editing <strong>{title}</strong>',
-  'editor.placeholder':   'Start typing — every keystroke syncs and merges.',
   'editor.hint':          'Tip: open a second tab and type at the same time. Both edits survive.',
 } as const)