feat(editor): page templates - live whole-page embed (MVP)

Embed another page's LIVE content into a host page (it updates when the source
changes, not a static copy). A page can be flagged a template for discovery in
the picker; any accessible page can be embedded.

Server:
- migrations: pages.is_template (+ partial index) and page_template_references
  (whole-page back-refs); db.d.ts/entity types hand-merged (db.d.ts is curated).
- POST /pages/toggle-template (CASL Edit) flips is_template; is_template is
  returned by findById + the sidebar tree select so the tree menu label
  reflects state. Search suggestions gain an onlyTemplates filter for the picker.
- POST /pages/template/lookup ({sourcePageIds[]}, <=50): returns each accessible
  source's {title, icon, slugId, content, sourceUpdatedAt} with comment marks
  stripped (same access path as transclusion: filterViewerAccessiblePageIds;
  inaccessible -> no_access, missing -> not_found; error path -> not_found, never
  raw content).
- reference sync (collectPageEmbedsFromPmJson + syncPageTemplateReferences) on
  the Yjs save hook; duplicatePage remaps pageEmbed.sourcePageId + inserts refs.
  Known MVP gap: REST content updates don't resync refs (lookup uses in-doc ids).

Client:
- pageEmbed node (editor-ext, registered in BOTH client + server schemas);
  read-only NodeView with a batching lookup; '/Embed page' slash + template
  picker (self-embed prevented); 'Make/Unset template' in the tree node menu.
- Cycle guard: an ancestry-chain context + depth cap (5) render a 'circular
  embed' placeholder instead of recursing.
- Public shares show a placeholder (no public lookup in MVP).

MVP excludes (follow-ups): public-share lookup, unsync->static copy, server-side
expansion for export/RAG, MCP schema mirror, point-in-time snapshots.

Implements docs/page-templates-plan.md (MVP, variant A).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

apps/server/src/database/database.module.ts

@@ -13,6 +13,7 @@ import { PagePermissionRepo } from './repos/page/page-permission.repo';
 import { CommentRepo } from './repos/comment/comment.repo';
 import { PageTransclusionsRepo } from './repos/page-transclusions/page-transclusions.repo';
 import { PageTransclusionReferencesRepo } from './repos/page-transclusions/page-transclusion-references.repo';
+import { PageTemplateReferencesRepo } from './repos/page-template-references/page-template-references.repo';
 import { PageHistoryRepo } from './repos/page/page-history.repo';
 import { AttachmentRepo } from './repos/attachment/attachment.repo';
 import { KyselyDB } from '@docmost/db/types/kysely.types';
@@ -85,6 +86,7 @@ import { normalizePostgresUrl } from '../common/helpers';
     PagePermissionRepo,
     PageTransclusionsRepo,
     PageTransclusionReferencesRepo,
+    PageTemplateReferencesRepo,
     PageHistoryRepo,
     CommentRepo,
     FavoriteRepo,
@@ -115,6 +117,7 @@ import { normalizePostgresUrl } from '../common/helpers';
     PagePermissionRepo,
     PageTransclusionsRepo,
     PageTransclusionReferencesRepo,
+    PageTemplateReferencesRepo,
     PageHistoryRepo,
     CommentRepo,
     FavoriteRepo,

apps/server/src/database/migrations/20260620T130000-page-is-template.ts

@@ -0,0 +1,20 @@
+import { type Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .alterTable('pages')
+    .addColumn('is_template', 'boolean', (col) =>
+      col.notNull().defaultTo(false),
+    )
+    .execute();
+
+  // Partial index backing the template picker: only template rows are indexed.
+  await sql`CREATE INDEX pages_is_template_idx ON pages (workspace_id) WHERE is_template`.execute(
+    db,
+  );
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropIndex('pages_is_template_idx').execute();
+  await db.schema.alterTable('pages').dropColumn('is_template').execute();
+}

apps/server/src/database/migrations/20260620T131000-page-template-references.ts

@@ -0,0 +1,42 @@
+import { type Kysely, sql } from 'kysely';
+
+export async function up(db: Kysely<any>): Promise<void> {
+  await db.schema
+    .createTable('page_template_references')
+    .addColumn('id', 'uuid', (col) =>
+      col.primaryKey().defaultTo(sql`gen_uuid_v7()`),
+    )
+    .addColumn('workspace_id', 'uuid', (col) =>
+      col.notNull().references('workspaces.id').onDelete('cascade'),
+    )
+    .addColumn('reference_page_id', 'uuid', (col) =>
+      col.notNull().references('pages.id').onDelete('cascade'),
+    )
+    .addColumn('source_page_id', 'uuid', (col) =>
+      col.notNull().references('pages.id').onDelete('cascade'),
+    )
+    .addColumn('created_at', 'timestamptz', (col) =>
+      col.notNull().defaultTo(sql`now()`),
+    )
+    .addUniqueConstraint('page_template_references_unique', [
+      'reference_page_id',
+      'source_page_id',
+    ])
+    .execute();
+
+  await db.schema
+    .createIndex('page_template_references_source_idx')
+    .on('page_template_references')
+    .column('source_page_id')
+    .execute();
+
+  await db.schema
+    .createIndex('page_template_references_ws_idx')
+    .on('page_template_references')
+    .column('workspace_id')
+    .execute();
+}
+
+export async function down(db: Kysely<any>): Promise<void> {
+  await db.schema.dropTable('page_template_references').execute();
+}

apps/server/src/database/repos/page-template-references/page-template-references.repo.ts

@@ -0,0 +1,66 @@
+import { Injectable } from '@nestjs/common';
+import { InjectKysely } from 'nestjs-kysely';
+import { KyselyDB, KyselyTransaction } from '@docmost/db/types/kysely.types';
+import { dbOrTx } from '@docmost/db/utils';
+import {
+  InsertablePageTemplateReference,
+  PageTemplateReference,
+} from '@docmost/db/types/entity.types';
+
+@Injectable()
+export class PageTemplateReferencesRepo {
+  constructor(@InjectKysely() private readonly db: KyselyDB) {}
+
+  async findByReferencePageId(
+    referencePageId: string,
+    trx?: KyselyTransaction,
+  ): Promise<PageTemplateReference[]> {
+    return dbOrTx(this.db, trx)
+      .selectFrom('pageTemplateReferences')
+      .selectAll()
+      .where('referencePageId', '=', referencePageId)
+      .execute();
+  }
+
+  async findReferencePageIdsBySource(
+    sourcePageId: string,
+    workspaceId: string,
+    trx?: KyselyTransaction,
+  ): Promise<string[]> {
+    const rows = await dbOrTx(this.db, trx)
+      .selectFrom('pageTemplateReferences')
+      .select('referencePageId')
+      .distinct()
+      .where('workspaceId', '=', workspaceId)
+      .where('sourcePageId', '=', sourcePageId)
+      .execute();
+    return rows.map((r) => r.referencePageId);
+  }
+
+  async insertMany(
+    rows: InsertablePageTemplateReference[],
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    if (rows.length === 0) return;
+    await dbOrTx(this.db, trx)
+      .insertInto('pageTemplateReferences')
+      .values(rows)
+      .onConflict((oc) =>
+        oc.columns(['referencePageId', 'sourcePageId']).doNothing(),
+      )
+      .execute();
+  }
+
+  async deleteByReferenceAndSources(
+    referencePageId: string,
+    sourcePageIds: string[],
+    trx?: KyselyTransaction,
+  ): Promise<void> {
+    if (sourcePageIds.length === 0) return;
+    await dbOrTx(this.db, trx)
+      .deleteFrom('pageTemplateReferences')
+      .where('referencePageId', '=', referencePageId)
+      .where('sourcePageId', 'in', sourcePageIds)
+      .execute();
+  }
+}

apps/server/src/database/repos/page/page.repo.ts

@@ -40,6 +40,7 @@ export class PageRepo {
     'spaceId',
     'workspaceId',
     'isLocked',
+    'isTemplate',
     'createdAt',
     'updatedAt',
     'deletedAt',
@@ -112,6 +113,7 @@ export class PageRepo {
     opts?: {
       trx?: KyselyTransaction;
       workspaceId?: string;
+      includeContent?: boolean;
     },
   ): Promise<Page[]> {
     if (pageIds.length === 0) return [];
@@ -120,6 +122,7 @@ export class PageRepo {
     let query = db
       .selectFrom('pages')
       .select(this.baseFields)
+      .$if(opts?.includeContent, (qb) => qb.select('content'))
       .where('id', 'in', pageIds);
 
     if (opts?.workspaceId) {

apps/server/src/database/types/db.d.ts

@@ -240,6 +240,14 @@ export interface PageTransclusionReferences {
   workspaceId: string;
 }
 
+export interface PageTemplateReferences {
+  createdAt: Generated<Timestamp>;
+  id: Generated<string>;
+  referencePageId: string;
+  sourcePageId: string;
+  workspaceId: string;
+}
+
 export interface PageTransclusions {
   content: Json;
   createdAt: Generated<Timestamp>;
@@ -281,6 +289,7 @@ export interface Pages {
   icon: string | null;
   id: Generated<string>;
   isLocked: Generated<boolean>;
+  isTemplate: Generated<boolean>;
   lastUpdatedAiChatId: string | null;
   lastUpdatedById: string | null;
   lastUpdatedSource: Generated<string>;
@@ -615,6 +624,7 @@ export interface DB {
   notifications: Notifications;
   pageAccess: PageAccess;
   pageTransclusionReferences: PageTransclusionReferences;
+  pageTemplateReferences: PageTemplateReferences;
   pageTransclusions: PageTransclusions;
   pagePermissions: PagePermissions;
   pageHistory: PageHistory;

apps/server/src/database/types/entity.types.ts

@@ -11,6 +11,7 @@ import {
   PageAccess as _PageAccess,
   PageTransclusions,
   PageTransclusionReferences,
+  PageTemplateReferences,
   PagePermissions as _PagePermissions,
   PageVerifications as _PageVerifications,
   PageVerifiers as _PageVerifiers,
@@ -180,6 +181,14 @@ export type UpdatablePageTransclusionReference = Updateable<
   Omit<PageTransclusionReferences, 'id'>
 >;
 
+// Page Template Reference (whole-page live embed back-references)
+export type PageTemplateReference = Selectable<PageTemplateReferences>;
+export type InsertablePageTemplateReference =
+  Insertable<PageTemplateReferences>;
+export type UpdatablePageTemplateReference = Updateable<
+  Omit<PageTemplateReferences, 'id'>
+>;
+
 // File Task
 export type FileTask = Selectable<FileTasks>;
 export type InsertableFileTask = Insertable<FileTasks>;