From 4be3e2ef96b44ee9138d768d5eecae0f98dc0088 Mon Sep 17 00:00:00 2001
From: EuanTop <euan@mail.bnu.edu.cn>
Date: Tue, 28 Jul 2026 14:26:19 +0800
Subject: [PATCH 1/3] fix(publish): expose public path to publish filters

---
 docs/features/plugin-system.md                |  7 ++-
 docs/features/publisher.md                    |  2 +-
 server/handlers/cms/data/preview.ts           |  1 +
 server/plugins/protocol/messages.ts           |  2 +-
 server/publish/publicRenderer.ts              | 50 +++++++++++++------
 server/publish/publishedHtmlPipeline.ts       |  1 +
 server/publish/republish.ts                   | 18 +++----
 .../publish-html-filter-context.test.ts       |  2 +-
 .../server/cmsTemplateRoutes.test.ts          |  9 ++++
 src/__tests__/server/publicRendering.test.ts  | 39 ++++++++++++---
 src/core/plugin-sdk/types/hooks.ts            | 17 +++++--
 src/core/plugins/hookBus.ts                   |  2 +-
 12 files changed, 109 insertions(+), 41 deletions(-)

diff --git a/docs/features/plugin-system.md b/docs/features/plugin-system.md
index 7bd0a856f..1f827ac4b 100644
--- a/docs/features/plugin-system.md
+++ b/docs/features/plugin-system.md
@@ -536,13 +536,18 @@ Plugin storage is per-plugin, per-collection. The collection name must match a `
 
 ```js
 api.cms.hooks.on('publish.after', async (event) => { /* … */ })
-api.cms.hooks.filter('publish.html', async (html) => html + '<!-- plugin -->')
+api.cms.hooks.filter('publish.html', async (html, { path }) => {
+  const canonical = new URL(path, 'https://example.com').href
+  return html.replace('</head>', `<link rel="canonical" href="${canonical}"></head>`)
+})
 const name = await api.cms.hooks.emit('sync.done', { /* … */ })
 // name === 'plugin.<your-plugin-id>.sync.done'
 ```
 
 **Host-emitted events** (the reserved core list, `CORE_HOOK_EVENTS` in `src/core/plugins/hookBus.ts`): `publish.before`, `publish.after`, `content.entry.created`, `content.entry.updated`, `content.entry.deleted`, `settings.changed`. **Filters**: `publish.html`, `publish.headers`, `content.entry.cells`.
 
+`publish.html` and `publish.headers` handlers receive `{ pluginId, siteId, pageId, slug, path }`. `slug` identifies the rendered page or template document; for an entry route it remains the entry template's slug. `path` is the emitted page's public URL pathname, so it differs per entry (for example `/posts/hello-world`) and is `/` for the home page.
+
 **Plugin emits are namespaced.** The host rewrites every `emit('<name>', …)` to `plugin.<your-plugin-id>.<name>` (a name already in your own namespace passes through unchanged), so event provenance is unforgeable — a plugin cannot fire `content.entry.created` or any other core event at other listeners, and emitting a name in *another* plugin's namespace (`plugin.<other-id>.*`) is rejected with an error. `emit` resolves to the canonical namespaced name. Cross-plugin eventing still works: subscribing is unrestricted, so a plugin listens to another plugin's events by their full namespaced name, e.g. `api.cms.hooks.on('plugin.acme.analytics.page-view', …)`.
 
 ### Loop sources — requires `loops.register`
diff --git a/docs/features/publisher.md b/docs/features/publisher.md
index 340879c1e..027f4d9cd 100644
--- a/docs/features/publisher.md
+++ b/docs/features/publisher.md
@@ -390,7 +390,7 @@ applyPublishedHtmlPipeline(renderedOutput, db)
     ├─→ Splice in declarative tags from plugin manifests' `frontend.assets[]`
     ├─→ Stamp form page tokens onto CMS-native <form> tags (`stampFormPageTokens`)
     ├─→ Inject per-module published JS: one `<script src="/_instatic/module-js/<id>.js?v=N" defer data-instatic-module-js="<id>">` per moduleId in the page's injection set (render-emitted ∪ hole-subtree ∩ site jsMap), sorted; CSP script-src → 'self' iff ≥ 1 tag
-    ├─→ Run `publish.html` filters in registration order (plugins transform the HTML string)
+    ├─→ Run `publish.html` filters in registration order with `{ siteId, pageId, slug, path }`
     ├─→ Emit `publish.after` hook
     └─→ Return final HTML
 ```
diff --git a/server/handlers/cms/data/preview.ts b/server/handlers/cms/data/preview.ts
index 57644952a..43f5ac0c9 100644
--- a/server/handlers/cms/data/preview.ts
+++ b/server/handlers/cms/data/preview.ts
@@ -133,6 +133,7 @@ export async function handleRowPreview(
       html: published.html,
       pageId: merged.id,
       slug: merged.slug,
+      path: publicPath,
       siteId: snapshot.site.id,
       cssBundle,
       jsModuleIds: published.jsModuleIds.filter((id) => moduleJsMap.has(id)),
diff --git a/server/plugins/protocol/messages.ts b/server/plugins/protocol/messages.ts
index dfcb1c16b..7077c64e9 100644
--- a/server/plugins/protocol/messages.ts
+++ b/server/plugins/protocol/messages.ts
@@ -162,7 +162,7 @@ export interface RunHookFilterRequest {
    * Extra context fields forwarded from `hookBus.applyFilter`. Plugin
    * handlers receive these merged into `{ pluginId, ...context }`.
    * For `publish.html` / `publish.headers` this carries
-   * `{ siteId, pageId, slug }`.
+   * `{ siteId, pageId, slug, path }`.
    */
   context?: Record<string, unknown>
 }
diff --git a/server/publish/publicRenderer.ts b/server/publish/publicRenderer.ts
index a35e01772..7cbbd588e 100644
--- a/server/publish/publicRenderer.ts
+++ b/server/publish/publicRenderer.ts
@@ -40,6 +40,8 @@ export interface RendererOutput {
   /** Identifies what was rendered, for the publish.html filter context. */
   pageId: string
   slug: string
+  /** Public URL pathname for this rendered artefact or request. */
+  path: string
   siteId: string
   /**
    * Sorted moduleIds whose published JS this page must load — already
@@ -65,8 +67,8 @@ export interface RendererOutput {
 
 interface RenderPublishedSnapshotContext {
   db: DbClient
-  /** Optional request URL — when present, drives per-loop pagination. */
-  url?: URL
+  /** Public/request URL — drives route bindings, loop pagination, and plugin context. */
+  url: URL
   /**
    * Publish version to stamp into `<instatic-hole data-instatic-version>` placeholders.
    * Defaults to the live `getPublishVersion()`. The full/incremental publish
@@ -129,16 +131,21 @@ export async function renderPublishedSnapshot(
   const chain = resolveTemplateChain(snapshot.site, { kind: 'page' })
   const merged = composeTemplateChain(chain, { kind: 'page', page })
 
-  // Seed route frame from the actual request URL (when available) so
+  // Seed route frame from the actual request URL so
   // `{route.slug}` / `{route.path}` bindings resolve to live values.
-  // publishPage falls back to the page permalink if no templateContext
-  // is provided.
-  const templateContext: TemplateRenderDataContext | undefined = ctx.url
-    ? { entryStack: [], route: buildRouteFrame(ctx.url.toString()) }
-    : undefined
+  const templateContext: TemplateRenderDataContext = {
+    entryStack: [],
+    route: buildRouteFrame(ctx.url.toString()),
+  }
 
   const rendered = await renderMergedTemplate(merged, snapshot, templateContext, ctx)
-  return { ...rendered, pageId: snapshot.pageRowId, slug: page.slug, siteId: snapshot.site.id }
+  return {
+    ...rendered,
+    pageId: snapshot.pageRowId,
+    slug: page.slug,
+    path: ctx.url.pathname,
+    siteId: snapshot.site.id,
+  }
 }
 
 /**
@@ -158,12 +165,19 @@ export async function renderPublishedNotFound(
   const chain = resolveTemplateChain(snapshot.site, { kind: 'page' })
   const merged = composeTemplateChain(chain, { kind: 'page', page })
 
-  const templateContext: TemplateRenderDataContext | undefined = ctx.url
-    ? { entryStack: [], route: buildRouteFrame(ctx.url.toString()) }
-    : undefined
+  const templateContext: TemplateRenderDataContext = {
+    entryStack: [],
+    route: buildRouteFrame(ctx.url.toString()),
+  }
 
   const rendered = await renderMergedTemplate(merged, snapshot, templateContext, ctx)
-  return { ...rendered, pageId: page.id, slug: page.slug, siteId: snapshot.site.id }
+  return {
+    ...rendered,
+    pageId: page.id,
+    slug: page.slug,
+    path: ctx.url.pathname,
+    siteId: snapshot.site.id,
+  }
 }
 
 export async function renderPublishedDataRowTemplate(
@@ -186,9 +200,15 @@ export async function renderPublishedDataRowTemplate(
   // seed. page/site/viewer frames are filled by `publishPage` from the document.
   const templateContext: TemplateRenderDataContext = {
     entryStack: [publishedDataRowToLoopItem(row)],
-    ...(ctx.url ? { route: buildRouteFrame(ctx.url.toString()) } : {}),
+    route: buildRouteFrame(ctx.url.toString()),
   }
 
   const rendered = await renderMergedTemplate(merged, snapshot, templateContext, ctx)
-  return { ...rendered, pageId: merged.id, slug: merged.slug, siteId: snapshot.site.id }
+  return {
+    ...rendered,
+    pageId: merged.id,
+    slug: merged.slug,
+    path: ctx.url.pathname,
+    siteId: snapshot.site.id,
+  }
 }
diff --git a/server/publish/publishedHtmlPipeline.ts b/server/publish/publishedHtmlPipeline.ts
index 96686a955..107bc6fed 100644
--- a/server/publish/publishedHtmlPipeline.ts
+++ b/server/publish/publishedHtmlPipeline.ts
@@ -62,6 +62,7 @@ export async function applyPublishedHtmlPipeline(
     siteId: rendered.siteId,
     pageId: rendered.pageId,
     slug: rendered.slug,
+    path: rendered.path,
   })
   await hookBus.emit('publish.after', {
     siteId: rendered.siteId,
diff --git a/server/publish/republish.ts b/server/publish/republish.ts
index 93262d76e..b8d0a602c 100644
--- a/server/publish/republish.ts
+++ b/server/publish/republish.ts
@@ -7,15 +7,12 @@
  * published pages, without writing a new snapshot. The side-effects — hook
  * listeners and filter handlers firing — are the whole point.
  *
- * Note on the synthetic URL: `renderPublishedSnapshot` accepts an optional
- * `url` on its context for per-loop pagination and `{route.*}` binding
- * resolution. For background republish (not driven by an inbound HTTP
- * request), we pass a synthetic localhost URL so the renderer has a valid
- * URL object to work with. The URL is not user-visible and its exact value
- * is irrelevant beyond being parseable.
+ * Background republishes use the page's public permalink as their synthetic
+ * URL so route bindings and plugin filter context match a visitor render.
  */
 
 import type { DbClient } from '../db/client'
+import { buildPageFrame } from '@core/templates/contextFrames'
 import { getPublishedPageSnapshotById } from '../repositories/publish'
 import { renderPublishedSnapshot } from './publicRenderer'
 import { applyPublishedHtmlPipeline } from './publishedHtmlPipeline'
@@ -56,10 +53,11 @@ async function republishSinglePage(db: DbClient, pageId: string): Promise<void>
     throw new PageNotPublishedError(pageId)
   }
 
-  // Synthetic URL for background republish. The URL object is used by
-  // renderPublishedSnapshot for pagination helpers and {route.*} bindings.
-  // Its exact value is irrelevant for background re-renders.
-  const syntheticUrl = new URL('http://localhost/__republish')
+  const page = snapshot.site.pages.find((candidate) => candidate.id === snapshot.pageRowId)
+  if (!page) {
+    throw new PageNotPublishedError(pageId)
+  }
+  const syntheticUrl = new URL(buildPageFrame(page).permalink, 'http://localhost')
 
   // Drive the full pipeline (publish.before → frontend.assets injection →
   // publish.html filter → publish.after). The returned HTML is discarded —
diff --git a/src/__tests__/architecture/publish-html-filter-context.test.ts b/src/__tests__/architecture/publish-html-filter-context.test.ts
index 0e09c3948..303cb5b27 100644
--- a/src/__tests__/architecture/publish-html-filter-context.test.ts
+++ b/src/__tests__/architecture/publish-html-filter-context.test.ts
@@ -3,7 +3,7 @@
  * server must pass a third argument (the context object).
  *
  * This ensures that plugin filter handlers for `publish.html` always receive
- * `{ siteId, pageId, slug }` in their context — without this, plugins that
+ * `{ siteId, pageId, slug, path }` in their context — without this, plugins that
  * destructure those fields would silently receive `undefined`.
  */
 
diff --git a/src/__tests__/server/cmsTemplateRoutes.test.ts b/src/__tests__/server/cmsTemplateRoutes.test.ts
index e76e9eef7..625732b1a 100644
--- a/src/__tests__/server/cmsTemplateRoutes.test.ts
+++ b/src/__tests__/server/cmsTemplateRoutes.test.ts
@@ -8,6 +8,7 @@ import { resetForTests } from '../../../server/publish/renderCache'
 import type { PublishedPageSnapshot } from '../../../server/repositories/publish'
 import { makePage, makeSite } from '../publisher/helpers'
 import { createFakeDb } from './dbTestFake'
+import { hookBus } from '../../core/plugins/hookBus'
 import {
   prepareInactiveSlot,
   writeArtefact,
@@ -37,6 +38,7 @@ describe('CMS dynamic template routes', () => {
   // published site can't leak into the next (or in from another test file).
   beforeEach(() => {
     resetForTests()
+    hookBus.reset()
   })
 
   it('renders a published data row through the highest priority page template', async () => {
@@ -131,6 +133,11 @@ describe('CMS dynamic template routes', () => {
       },
     ])
 
+    hookBus.filter('issue-225-regression', 'publish.html', (html, context) => {
+      const { path, slug } = context as { path?: string; slug?: string }
+      return `${html}<meta name="publish-context-path" content="${path ?? ''}"><meta name="publish-context-slug" content="${slug ?? ''}">`
+    })
+
     const res = await handleServerRequest(new Request('http://localhost/posts/dynamic-post'), { db })
     const html = await res.text()
 
@@ -138,6 +145,8 @@ describe('CMS dynamic template routes', () => {
     expect(res.headers.get('content-type')).toContain('text/html')
     expect(html).toContain('<h1>Dynamic Post</h1>')
     expect(html).not.toContain('Static title')
+    expect(html).toContain('<meta name="publish-context-path" content="/posts/dynamic-post">')
+    expect(html).toContain('<meta name="publish-context-slug" content="post-template">')
   })
 
   it('serves a template route from disk when a baked artefact exists', async () => {
diff --git a/src/__tests__/server/publicRendering.test.ts b/src/__tests__/server/publicRendering.test.ts
index 0a35f8a3b..db6e780df 100644
--- a/src/__tests__/server/publicRendering.test.ts
+++ b/src/__tests__/server/publicRendering.test.ts
@@ -7,6 +7,7 @@ import {
   renderPublishedDataRowTemplate,
 } from '../../../server/publish/publicRenderer'
 import type { PublishedDataRow } from '@core/data/schemas'
+import { hookBus } from '@core/plugins/hookBus'
 import { handleServerRequest } from '../../../server/router'
 
 function snapshot(text: string): PublishedPageSnapshot {
@@ -111,11 +112,15 @@ describe('public rendering', () => {
   // without a reset, one test's cached `/` render would be served to the next.
   beforeEach(() => {
     resetForTests()
+    hookBus.reset()
   })
 
   it('renders complete HTML from a published snapshot', async () => {
     const snap = snapshot('Visible to public')
-    const { html } = await renderPublishedSnapshot(snap, { db: makeFakeDb(snap) })
+    const { html } = await renderPublishedSnapshot(snap, {
+      db: makeFakeDb(snap),
+      url: new URL('http://localhost/'),
+    })
 
     expect(html).toContain('<!DOCTYPE html>')
     expect(html).toContain('Visible to public')
@@ -125,11 +130,15 @@ describe('public rendering', () => {
   // Guards the page-wrapper's identity reporting after the shared
   // `renderMergedTemplate` extraction: pageId/slug come from the page row,
   // not the merged tree.
-  it('reports pageId and slug from the page row for the snapshot path', async () => {
+  it('reports page identity and the public path for the snapshot path', async () => {
     const snap = snapshot('Identity')
-    const out = await renderPublishedSnapshot(snap, { db: makeFakeDb(snap) })
+    const out = await renderPublishedSnapshot(snap, {
+      db: makeFakeDb(snap),
+      url: new URL('http://localhost/'),
+    })
     expect(out.pageId).toBe('page_home')
     expect(out.slug).toBe('index')
+    expect(out.path).toBe('/')
     expect(out.siteId).toBe('project_1')
   })
 
@@ -161,7 +170,10 @@ describe('public rendering', () => {
       publishedAt: '2024-01-01T00:00:00.000Z',
       createdAt: '2024-01-01T00:00:00.000Z',
     }
-    const result = await renderPublishedDataRowTemplate(snap, row, { db: makeFakeDb(snap) })
+    const result = await renderPublishedDataRowTemplate(snap, row, {
+      db: makeFakeDb(snap),
+      url: new URL('http://localhost/blog/hello'),
+    })
     expect(result).toBeNull()
   })
 
@@ -179,20 +191,30 @@ describe('public rendering', () => {
       ],
     }
 
-    const { html } = await renderPublishedSnapshot(published, { db: makeFakeDb(published) })
+    const { html } = await renderPublishedSnapshot(published, {
+      db: makeFakeDb(published),
+      url: new URL('http://localhost/'),
+    })
 
     expect(html).toContain("script-src 'self'")
     expect(html).toContain('/_instatic/assets/version_1/entries/entry.js')
   })
 
   it('serves / from the active published index snapshot', async () => {
+    hookBus.filter('home-path-test', 'publish.html', (html, context) => {
+      const { path, slug } = context as { path?: string; slug?: string }
+      return `${html}<meta name="publish-context" content="${path ?? ''}|${slug ?? ''}">`
+    })
+
     const res = await handleServerRequest(new Request('http://localhost/'), {
       db: makeFakeDb(snapshot('Homepage')),
     })
 
     expect(res.status).toBe(200)
     expect(res.headers.get('content-type')).toContain('text/html')
-    expect(await res.text()).toContain('Homepage')
+    const html = await res.text()
+    expect(html).toContain('Homepage')
+    expect(html).toContain('<meta name="publish-context" content="/|index">')
   })
 
   it('serves immutable published runtime assets by public path', async () => {
@@ -222,7 +244,10 @@ describe('public rendering', () => {
 
   it('emits external CSS <link> tags pointing at the per-site bundle', async () => {
     const snap = snapshot('Hello')
-    const { html } = await renderPublishedSnapshot(snap, { db: makeFakeDb(snap) })
+    const { html } = await renderPublishedSnapshot(snap, {
+      db: makeFakeDb(snap),
+      url: new URL('http://localhost/'),
+    })
     expect(html).toMatch(/<link rel="stylesheet" href="\/_instatic\/css\/reset-[a-f0-9]{12}\.css">/)
     // No inline reset block — site-wide CSS lives in the external bundle.
     expect(html).not.toContain(':where(*, *::before, *::after)')
diff --git a/src/core/plugin-sdk/types/hooks.ts b/src/core/plugin-sdk/types/hooks.ts
index 8f061658b..c1255ddc1 100644
--- a/src/core/plugin-sdk/types/hooks.ts
+++ b/src/core/plugin-sdk/types/hooks.ts
@@ -70,14 +70,23 @@ export interface CmsServerFilters {
  *
  * Filter handlers destructure what they need:
  * ```ts
- * api.cms.hooks.filter('publish.html', (html, { siteId, pageId, slug }) => {
- *   return html.replace('</body>', `<!-- page:${slug} -->\n</body>`)
+ * api.cms.hooks.filter('publish.html', (html, { siteId, pageId, slug, path }) => {
+ *   return html.replace('</body>', `<!-- page:${slug} path:${path} -->\n</body>`)
  * })
  * ```
  */
+interface PublishFilterContext {
+  siteId: string
+  pageId: string
+  /** Slug of the rendered page or template document. */
+  slug: string
+  /** Public URL pathname of the emitted page, such as `/` or `/posts/hello`. */
+  path: string
+}
+
 export interface CmsServerFilterContexts {
-  'publish.html': { siteId: string; pageId: string; slug: string }
-  'publish.headers': { siteId: string; pageId: string; slug: string }
+  'publish.html': PublishFilterContext
+  'publish.headers': PublishFilterContext
   'content.entry.cells': {
     tableSlug: string
     entryId: string
diff --git a/src/core/plugins/hookBus.ts b/src/core/plugins/hookBus.ts
index d18fbe3b2..b33e14be1 100644
--- a/src/core/plugins/hookBus.ts
+++ b/src/core/plugins/hookBus.ts
@@ -159,7 +159,7 @@ class HookBus {
    *
    * @param contextExtras  Additional context fields forwarded to every
    *   handler alongside `{ pluginId }`. Used by `publish.html` and
-   *   `publish.headers` to pass `{ siteId, pageId, slug }`.
+   *   `publish.headers` to pass `{ siteId, pageId, slug, path }`.
    */
   async applyFilter<T>(
     name: string,

From 247b87d6adbe66b994cc9ffa8708e919d5c1c4da Mon Sep 17 00:00:00 2001
From: EuanTop <euan@mail.bnu.edu.cn>
Date: Tue, 28 Jul 2026 15:15:10 +0800
Subject: [PATCH 2/3] fix(publish): skip templates during background republish

---
 docs/features/plugin-system.md          |   4 +-
 server/plugins/host/handlers/content.ts |   2 +-
 server/plugins/protocol/messages.ts     |   4 +-
 server/publish/republish.ts             |  28 +++++--
 src/__tests__/server/republish.test.ts  | 104 ++++++++++++++++++++++++
 src/core/plugin-sdk/capabilities.ts     |   2 +-
 src/core/plugin-sdk/types/hooks.ts      |   6 +-
 src/core/plugins/hookBus.ts             |   5 +-
 8 files changed, 136 insertions(+), 19 deletions(-)
 create mode 100644 src/__tests__/server/republish.test.ts

diff --git a/docs/features/plugin-system.md b/docs/features/plugin-system.md
index 1f827ac4b..4dbbc1198 100644
--- a/docs/features/plugin-system.md
+++ b/docs/features/plugin-system.md
@@ -546,7 +546,7 @@ const name = await api.cms.hooks.emit('sync.done', { /* … */ })
 
 **Host-emitted events** (the reserved core list, `CORE_HOOK_EVENTS` in `src/core/plugins/hookBus.ts`): `publish.before`, `publish.after`, `content.entry.created`, `content.entry.updated`, `content.entry.deleted`, `settings.changed`. **Filters**: `publish.html`, `publish.headers`, `content.entry.cells`.
 
-`publish.html` and `publish.headers` handlers receive `{ pluginId, siteId, pageId, slug, path }`. `slug` identifies the rendered page or template document; for an entry route it remains the entry template's slug. `path` is the emitted page's public URL pathname, so it differs per entry (for example `/posts/hello-world`) and is `/` for the home page.
+`publish.html` handlers receive `{ pluginId, siteId, pageId, slug, path }`. `slug` identifies the rendered page or template document; for an entry route it remains the entry template's slug. `path` is the emitted page's public URL pathname, so it differs per entry (for example `/posts/hello-world`) and is `/` for the home page.
 
 **Plugin emits are namespaced.** The host rewrites every `emit('<name>', …)` to `plugin.<your-plugin-id>.<name>` (a name already in your own namespace passes through unchanged), so event provenance is unforgeable — a plugin cannot fire `content.entry.created` or any other core event at other listeners, and emitting a name in *another* plugin's namespace (`plugin.<other-id>.*`) is rejected with an error. `emit` resolves to the canonical namespaced name. Cross-plugin eventing still works: subscribing is unrestricted, so a plugin listens to another plugin's events by their full namespaced name, e.g. `api.cms.hooks.on('plugin.acme.analytics.page-view', …)`.
 
@@ -751,7 +751,7 @@ const { count } = await api.cms.content.republishAll()
 
 `tables.create(input)` accepts the plugin-facing field projection, then maps it to the host's canonical `DataField` schema before storage. `richText` fields default to Markdown format, `select` / `multiSelect` option `value`s become stable option IDs, and `relation.targetTableSlug` must resolve to an existing table slug.
 
-`republishAll` fires the full publish pipeline (`publish.before` → `publish.html` → `publish.after`), so other plugins' filters and listeners participate.
+`republishAll` fires the full publish pipeline (`publish.before` → `publish.html` → `publish.after`) for directly routable published pages, so other plugins' filters and listeners participate. Template documents are skipped because they have no standalone public path.
 
 Tree mutation and replacement payloads are validated against the canonical `@core/page-tree` TypeBox schemas before host dispatch. `insertNode.node` must be a complete `PageNode`, and `replace(tree)` must receive a complete `NodeTree` with a valid `rootNodeId`, matching node-map keys, resolvable child IDs, and no reachable cycles.
 
diff --git a/server/plugins/host/handlers/content.ts b/server/plugins/host/handlers/content.ts
index f0909c354..195293e12 100644
--- a/server/plugins/host/handlers/content.ts
+++ b/server/plugins/host/handlers/content.ts
@@ -639,7 +639,7 @@ export async function handleContentRepublishAll(
   _entry: HostPluginRecord,
   _db: DbClient,
 ): Promise<void> {
-  // `republishAll` operates on the host's full published-pages set —
+  // `republishAll` operates on the host's directly routable published pages —
   // the per-table access check would over-constrain a callee that only
   // wants to flush the publish pipeline. The kernel-of-correctness
   // remains the `cms.content.publish` permission grant.
diff --git a/server/plugins/protocol/messages.ts b/server/plugins/protocol/messages.ts
index 7077c64e9..f3f256208 100644
--- a/server/plugins/protocol/messages.ts
+++ b/server/plugins/protocol/messages.ts
@@ -161,8 +161,8 @@ export interface RunHookFilterRequest {
   /**
    * Extra context fields forwarded from `hookBus.applyFilter`. Plugin
    * handlers receive these merged into `{ pluginId, ...context }`.
-   * For `publish.html` / `publish.headers` this carries
-   * `{ siteId, pageId, slug, path }`.
+   * For `publish.html` this carries `{ siteId, pageId, slug, path }`;
+   * `publish.headers` carries `{ siteId, pageId, slug }`.
    */
   context?: Record<string, unknown>
 }
diff --git a/server/publish/republish.ts b/server/publish/republish.ts
index b8d0a602c..d7b3a58d0 100644
--- a/server/publish/republish.ts
+++ b/server/publish/republish.ts
@@ -7,12 +7,15 @@
  * published pages, without writing a new snapshot. The side-effects — hook
  * listeners and filter handlers firing — are the whole point.
  *
- * Background republishes use the page's public permalink as their synthetic
- * URL so route bindings and plugin filter context match a visitor render.
+ * Background republishes skip template documents, which have no standalone
+ * public route. Directly routable pages use their public permalink as the
+ * synthetic URL so route bindings and plugin filter context match a visitor
+ * render.
  */
 
 import type { DbClient } from '../db/client'
 import { buildPageFrame } from '@core/templates/contextFrames'
+import { isTemplatePage } from '@core/templates'
 import { getPublishedPageSnapshotById } from '../repositories/publish'
 import { renderPublishedSnapshot } from './publicRenderer'
 import { applyPublishedHtmlPipeline } from './publishedHtmlPipeline'
@@ -41,10 +44,14 @@ class PageNotPublishedError extends Error {
  * fire plugin hook listeners and filters so their side-effects are applied to
  * a page that was published before the plugin was activated.
  *
- * Throws `PageNotPublishedError` if the page is not found or is not
- * currently published.
+ * Returns `false` for a published template document because templates only
+ * wrap public routes and must not be presented to plugins as standalone
+ * public pages.
+ *
+ * Throws `PageNotPublishedError` if the page is not found or is not currently
+ * published.
  */
-async function republishSinglePage(db: DbClient, pageId: string): Promise<void> {
+async function republishSinglePage(db: DbClient, pageId: string): Promise<boolean> {
   // Typed read through the publish repository — the snapshot column is parsed
   // by the DbClient (`*_json` auto-parse) and typed as `PublishedPageSnapshot`,
   // so there is no boundary cast here.
@@ -57,6 +64,9 @@ async function republishSinglePage(db: DbClient, pageId: string): Promise<void>
   if (!page) {
     throw new PageNotPublishedError(pageId)
   }
+  if (isTemplatePage(page)) {
+    return false
+  }
   const syntheticUrl = new URL(buildPageFrame(page).permalink, 'http://localhost')
 
   // Drive the full pipeline (publish.before → frontend.assets injection →
@@ -65,11 +75,13 @@ async function republishSinglePage(db: DbClient, pageId: string): Promise<void>
   // catch up on pages published before they were activated).
   const rendered = await renderPublishedSnapshot(snapshot, { db, url: syntheticUrl })
   await applyPublishedHtmlPipeline(rendered, db)
+  return true
 }
 
 /**
- * Republish every currently-published page. Iterates all published pages and
- * calls `republishSinglePage` for each. Returns the total count published.
+ * Republish every currently-published, directly routable page. Template
+ * documents are intentionally skipped because they do not have standalone
+ * public paths. Returns the total count republished.
  *
  * Errors for individual pages are logged and do not abort the batch — the
  * count reflects pages that completed without error.
@@ -87,7 +99,7 @@ export async function republishAllPages(db: DbClient): Promise<number> {
   let count = 0
   for (const [i, result] of results.entries()) {
     if (result.status === 'fulfilled') {
-      count++
+      if (result.value) count++
     } else {
       console.error(`[publish:republish] republishSinglePage("${rows[i].id}") threw:`, result.reason)
     }
diff --git a/src/__tests__/server/republish.test.ts b/src/__tests__/server/republish.test.ts
new file mode 100644
index 000000000..f46d58da7
--- /dev/null
+++ b/src/__tests__/server/republish.test.ts
@@ -0,0 +1,104 @@
+import { beforeEach, describe, expect, it } from 'bun:test'
+import type { DbClient, DbResult } from '../../../server/db'
+import type { PublishedPageSnapshot } from '../../../server/repositories/publish'
+import { republishAllPages } from '../../../server/publish/republish'
+import { hookBus } from '@core/plugins/hookBus'
+import { makePage } from '../publisher/helpers'
+import { createFakeDb } from './dbTestFake'
+
+function makeSnapshots(): Map<string, PublishedPageSnapshot> {
+  const home = makePage({
+    root: { moduleId: 'base.body', children: ['copy'] },
+    copy: { moduleId: 'base.text', props: { text: 'Home', tag: 'h1' } },
+  })
+  home.id = 'page-home'
+  home.slug = 'index'
+  home.title = 'Home'
+
+  const template = makePage({
+    root: { moduleId: 'base.body', children: ['outlet'] },
+    outlet: { moduleId: 'base.outlet' },
+  })
+  template.id = 'page-template'
+  template.slug = 'post-template'
+  template.title = 'Post template'
+  template.template = {
+    enabled: true,
+    target: { kind: 'postTypes', tableSlugs: ['posts'] },
+    priority: 0,
+  }
+
+  const site = {
+    id: 'site-1',
+    name: 'Republish test',
+    pages: [home, template],
+    files: [],
+    visualComponents: [],
+    breakpoints: [{ id: 'desktop', label: 'Desktop', width: 1440, icon: 'monitor' }],
+    settings: { metaTitle: 'Republish test', shortcuts: {} },
+    styleRules: {},
+    createdAt: 1,
+    updatedAt: 1,
+  }
+
+  return new Map([
+    [home.id, { cmsSnapshotVersion: 1, pageRowId: home.id, site }],
+    [template.id, { cmsSnapshotVersion: 1, pageRowId: template.id, site }],
+  ])
+}
+
+function makeFakeDb(snapshots: Map<string, PublishedPageSnapshot>): DbClient {
+  return createFakeDb(async (sql: string, params: unknown[]): Promise<DbResult> => {
+    const normalized = sql.replace(/\s+/g, ' ').trim().toLowerCase()
+
+    if (normalized.startsWith('select id from data_rows')) {
+      return {
+        rows: [...snapshots.keys()].map((id) => ({ id })),
+        rowCount: snapshots.size,
+      }
+    }
+
+    if (normalized.includes('site_snapshots.site_json')) {
+      const snapshot = snapshots.get(String(params[0]))
+      return {
+        rows: snapshot
+          ? [{
+              row_id: snapshot.pageRowId,
+              site_json: snapshot.site,
+              runtime_assets_json: null,
+              importmap_body: null,
+              importmap_sha256: null,
+            }]
+          : [],
+        rowCount: snapshot ? 1 : 0,
+      }
+    }
+
+    return { rows: [], rowCount: 0 }
+  })
+}
+
+describe('background republish', () => {
+  beforeEach(() => {
+    hookBus.reset()
+  })
+
+  it('republishes directly routable pages and skips template documents', async () => {
+    const contexts: Array<Record<string, unknown>> = []
+    hookBus.filter('republish-test', 'publish.html', (html, context) => {
+      contexts.push(context)
+      return html
+    })
+
+    const count = await republishAllPages(makeFakeDb(makeSnapshots()))
+
+    expect(count).toBe(1)
+    expect(contexts).toEqual([{
+      pluginId: 'republish-test',
+      siteId: 'site-1',
+      pageId: 'page-home',
+      slug: 'index',
+      path: '/',
+    }])
+  })
+})
diff --git a/src/core/plugin-sdk/capabilities.ts b/src/core/plugin-sdk/capabilities.ts
index a0ac615b4..829a67333 100644
--- a/src/core/plugin-sdk/capabilities.ts
+++ b/src/core/plugin-sdk/capabilities.ts
@@ -156,7 +156,7 @@ export const PLUGIN_CAPABILITIES: PluginCapability[] = [
   {
     permission: 'cms.content.publish',
     label: 'Publish CMS content',
-    description: 'Allows the plugin to publish or schedule-publish individual entries and to republish every published page. The full publish pipeline runs (publish.before → publish.html → publish.after), so hook listeners from other plugins fire as part of the chain.',
+    description: 'Allows the plugin to publish or schedule-publish individual entries and to republish every directly routable published page. The full publish pipeline runs (publish.before → publish.html → publish.after), so hook listeners from other plugins fire as part of the chain.',
     risk: 'high',
     surfaces: ['server', 'cms'],
   },
diff --git a/src/core/plugin-sdk/types/hooks.ts b/src/core/plugin-sdk/types/hooks.ts
index c1255ddc1..07c37b705 100644
--- a/src/core/plugin-sdk/types/hooks.ts
+++ b/src/core/plugin-sdk/types/hooks.ts
@@ -75,7 +75,7 @@ export interface CmsServerFilters {
  * })
  * ```
  */
-interface PublishFilterContext {
+interface PublishHtmlFilterContext {
   siteId: string
   pageId: string
   /** Slug of the rendered page or template document. */
@@ -85,8 +85,8 @@ interface PublishFilterContext {
 }
 
 export interface CmsServerFilterContexts {
-  'publish.html': PublishFilterContext
-  'publish.headers': PublishFilterContext
+  'publish.html': PublishHtmlFilterContext
+  'publish.headers': { siteId: string; pageId: string; slug: string }
   'content.entry.cells': {
     tableSlug: string
     entryId: string
diff --git a/src/core/plugins/hookBus.ts b/src/core/plugins/hookBus.ts
index b33e14be1..f29c3bd02 100644
--- a/src/core/plugins/hookBus.ts
+++ b/src/core/plugins/hookBus.ts
@@ -158,8 +158,9 @@ class HookBus {
    * logged and the value is left unchanged.
    *
    * @param contextExtras  Additional context fields forwarded to every
-   *   handler alongside `{ pluginId }`. Used by `publish.html` and
-   *   `publish.headers` to pass `{ siteId, pageId, slug, path }`.
+   *   handler alongside `{ pluginId }`. `publish.html` passes
+   *   `{ siteId, pageId, slug, path }`; `publish.headers` passes
+   *   `{ siteId, pageId, slug }`.
    */
   async applyFilter<T>(
     name: string,

From 2859a248c4d045dfcf72f129014ff5bb1249e76a Mon Sep 17 00:00:00 2001
From: EuanTop <euan@mail.bnu.edu.cn>
Date: Tue, 28 Jul 2026 15:22:57 +0800
Subject: [PATCH 3/3] docs(test): clarify publish filter architecture gate

---
 .../architecture/publish-html-filter-context.test.ts        | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/__tests__/architecture/publish-html-filter-context.test.ts b/src/__tests__/architecture/publish-html-filter-context.test.ts
index 303cb5b27..4c0e04a38 100644
--- a/src/__tests__/architecture/publish-html-filter-context.test.ts
+++ b/src/__tests__/architecture/publish-html-filter-context.test.ts
@@ -2,9 +2,9 @@
  * Architecture gate: every `applyFilter('publish.html', ...)` call in the
  * server must pass a third argument (the context object).
  *
- * This ensures that plugin filter handlers for `publish.html` always receive
- * `{ siteId, pageId, slug, path }` in their context — without this, plugins that
- * destructure those fields would silently receive `undefined`.
+ * This gate ensures that plugin filter handlers receive a context object.
+ * Runtime rendering tests verify its `{ siteId, pageId, slug, path }` contract
+ * and the route-specific values supplied for those fields.
  */
 
 import { describe, expect, it } from 'bun:test'