From c201028bfcf040c62212be319d8e9891f1a0749d 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/4] 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 d07fa28f4..b99f7d0b0 100644
--- a/docs/features/plugin-system.md
+++ b/docs/features/plugin-system.md
@@ -542,7 +542,10 @@ 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'
 ```
@@ -551,6 +554,8 @@ const name = await api.cms.hooks.emit('sync.done', { /* … */ })
 
 Every filter handler returns the same runtime value type it received. `src/core/plugins/hookBus.ts` checks each result before passing it to the next handler; a mismatched result keeps the previous value and logs the offending plugin ID. For example, `publish.html` returns a string and `content.entry.cells` returns an object, never `null`.
 
+`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 cf4bc0d37..3f4dee5a6 100644
--- a/docs/features/publisher.md
+++ b/docs/features/publisher.md
@@ -424,7 +424,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 dd961723e..9316caa73 100644
--- a/server/handlers/cms/data/preview.ts
+++ b/server/handlers/cms/data/preview.ts
@@ -144,6 +144,7 @@ export async function handleRowPreview(
       html: published.html,
       pageId: merged.id,
       slug: merged.slug,
+      path: publicPath,
       siteId: snapshot.site.id,
       jsModuleIds: published.jsModuleIds.filter((id) => moduleJsMap.has(id)),
       publishVersion: getPublishVersion(),
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 c8f41a48a..d12531de7 100644
--- a/server/publish/publicRenderer.ts
+++ b/server/publish/publicRenderer.ts
@@ -41,6 +41,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
@@ -66,8 +68,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
@@ -133,16 +135,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,
+  }
 }
 
 /**
@@ -162,12 +169,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(
@@ -193,7 +207,7 @@ 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(
@@ -203,5 +217,11 @@ export async function renderPublishedDataRowTemplate(
     ctx,
     readEntrySeoOverride(row.cells),
   )
-  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 18a81b1f7..22db6a11f 100644
--- a/server/publish/publishedHtmlPipeline.ts
+++ b/server/publish/publishedHtmlPipeline.ts
@@ -65,6 +65,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 8d429b27c..f389efb75 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 5486d493a..c1754ba55 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()
   })
 
@@ -349,20 +361,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 () => {
@@ -412,7 +434,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 030a08644..502107618 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 b0bc66398..78533c03e 100644
--- a/src/core/plugins/hookBus.ts
+++ b/src/core/plugins/hookBus.ts
@@ -166,7 +166,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 8a5c9b70e74da7f8be6024a722b2190a249f5b7c 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/4] 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 b99f7d0b0..0964f4c7e 100644
--- a/docs/features/plugin-system.md
+++ b/docs/features/plugin-system.md
@@ -554,7 +554,7 @@ const name = await api.cms.hooks.emit('sync.done', { /* … */ })
 
 Every filter handler returns the same runtime value type it received. `src/core/plugins/hookBus.ts` checks each result before passing it to the next handler; a mismatched result keeps the previous value and logs the offending plugin ID. For example, `publish.html` returns a string and `content.entry.cells` returns an object, never `null`.
 
-`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', …)`.
 
@@ -761,7 +761,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. `repeater` accepts a one-level `fields` schema made from ordinary authorable fields; nested relation slugs are resolved through the same gate, while recursive repeaters, `pageTree`, and `fieldSchema` item fields are rejected by the boundary schema.
 
-`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 93a06ac7b..eb6e72e57 100644
--- a/server/plugins/host/handlers/content.ts
+++ b/server/plugins/host/handlers/content.ts
@@ -646,7 +646,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 f389efb75..0c8cf22c3 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.
@@ -88,7 +100,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 86903aee6..7c3eadac2 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 502107618..71669828c 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 78533c03e..e4e6fd58d 100644
--- a/src/core/plugins/hookBus.ts
+++ b/src/core/plugins/hookBus.ts
@@ -165,8 +165,9 @@ class HookBus {
    * 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 decf3a590c6e88796dae4ed18e78f42aa681b25f 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/4] 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'

From b91ab3b1f0a5eee9810436a21275ebd5ba45af59 Mon Sep 17 00:00:00 2001
From: Mariomarquezt <60635115+Mariomarquezt@users.noreply.github.com>
Date: Wed, 30 Sep 2026 02:09:33 -0700
Subject: [PATCH 4/4] fix(publish): pass the public path from every render path

Completes the publish.html `path` context from #297 on current main:

- Branch preview (added after #297) now passes the visitor's pathname.
- Admin entry preview reports the encoded URL pathname, matching live,
  baked and branch-preview renders (e.g. /posts/caf%C3%A9).
- Entry SEO tests added on main after #297 now pass the required url.
- republish.ts imports buildPageFrame through the @core/templates barrel.
- Docs: branch preview runs the publish.* hooks; the publish pipeline and
  republishAll rows match the code.
---
 docs/features/publisher.md                    |   6 +-
 server/handlers/cms/data/preview.ts           |   4 +-
 server/publish/branchPreview.ts               |  10 +-
 server/publish/republish.ts                   |  10 +-
 .../server/branchPreviewLinks.test.ts         |  91 +++++++++++-
 .../server/dataPreviewPublishContext.test.ts  | 140 ++++++++++++++++++
 src/__tests__/server/publicRendering.test.ts  |  13 +-
 src/__tests__/server/republish.test.ts        |   6 +-
 src/core/templates/index.ts                   |   2 +-
 9 files changed, 262 insertions(+), 20 deletions(-)
 create mode 100644 src/__tests__/server/dataPreviewPublishContext.test.ts

diff --git a/docs/features/publisher.md b/docs/features/publisher.md
index 3f4dee5a6..de7e7512b 100644
--- a/docs/features/publisher.md
+++ b/docs/features/publisher.md
@@ -386,17 +386,17 @@ Because `serializeCsp` sorts, the same plugins + adapters always emit a **byte-i
 |-------------------------------------------------|---------------------------------------------------------------------|
 | `server/publish/publicRouter.ts`                | Gateway: Layer A disk fast-path → Layer B LRU → live `resolvePublicRoute` + `renderPublicResolution`. |
 | `server/publish/publicRoutes.ts`                | Dispatcher tail: `tryServeBranchPreviewLink` (preview cookie in/out), `tryServePublicRoute` (a live preview cookie → `renderBranchPreview`, otherwise `renderPublicResolution`), setup redirect, 404 page. |
-| `server/publish/branchPreview.ts`               | Render a public URL from a branch's DRAFT for preview-link visitors: same composition as the editor's runtime preview (inline CSS, loops on the branch, on-demand runtime bundles kept in `branchPreviewAssets.ts`, plugin frontend injections, no publish hooks), `no-store` + `noindex`, with a banner. |
+| `server/publish/branchPreview.ts`               | Render a public URL from a branch's DRAFT for preview-link visitors: same composition as the editor's runtime preview (inline CSS, loops on the branch, on-demand runtime bundles kept in `branchPreviewAssets.ts`, plugin frontend injections), then the same `applyPublishedHtmlPipeline` as a published page, so `publish.before` / `publish.html` / `publish.after` fire (the `publish.html` context `path` is the visitor's public pathname), `no-store` + `noindex`, with a banner. |
 | `server/publish/staticArtefact.ts`              | Two-slot pointer-file swap (`swapSlot`), per-file atomic writes (`writeArtefact`, `updateArtefactInPlace`), and reads (`readArtefact`). Layer A. |
 | `server/publish/renderCache.ts`                 | In-memory LRU keyed by `(urlPath, canonicalQuery)`, entries versioned. `getOrRender` (single-flight). Reads the version from `publishState`; version captured at render start — a publish landing mid-render discards the result rather than caching stale HTML. Layer B. |
 | `server/publish/publishState.ts`                | Publish-time process state: `publishVersion` (`bumpPublishVersion`/`getPublishVersion`), `withPublishLock` (ISS-038 publish serializer), and `createVersionedSingleFlight` — the generalized version-keyed single-flight memo the hole endpoint reuses. Repositories import the version + lock from here (not from the cache). |
 | `server/publish/holeRuntime.ts`                 | Exports `runInstaticHoleRuntime` (the TypeScript source of the Layer C runtime) and `HOLE_RUNTIME_JS` (IIFE-serialized string, ~1.1 KB, served to browsers). Tests call `runInstaticHoleRuntime()` directly to avoid dynamic eval. |
 | `server/publish/publicRenderer.ts`              | `renderPublishedSnapshot`, `renderPublishedDataRowTemplate` — thin wrappers (resolve + compose the template chain, seed the context) over one shared `renderMergedTemplate` (CSS bundle + loop/media prefetch + `publishPage` + publish-version stamping). The entry path also passes the row's `readEntrySeoOverride(...)` through as `documentMeta`. |
-| `server/publish/publishedHtmlPipeline.ts`       | Post-process: DOMPurify the final HTML, run plugin `publish.html` filter, splice in declarative tags from plugin manifests, inject runtime assets. Runs at publish time only — never per-request. |
+| `server/publish/publishedHtmlPipeline.ts`       | `applyPublishedHtmlPipeline` — the one post-render pipeline for every HTML-emitting path: emits `publish.before`, splices plugin `frontend.assets[]` tags (`injectFrontendAssets`, with CSP rewrite), stamps CMS form tokens (`stampFormPageTokens`), appends module-JS `<script defer>` tags (`injectModuleScripts`), runs the plugin `publish.html` filter with context `{ siteId, pageId, slug, path }`, then emits `publish.after`. Runs at bake time (`publishSite.ts`, `publishRow.ts`, `bakeDataRows.ts`), on live renders (`publicRouter.ts`), for previews (`branchPreview.ts`, `server/handlers/cms/data/preview.ts`), and in background republish (`republish.ts`). |
 | `server/publish/siteCssBundle.ts`               | Hash the four CSS strings, write `uploads/css/...` files. The framework bundle's module-CSS half comes from the shared walk in `siteModuleAssets.ts`. |
 | `server/publish/siteModuleAssets.ts`            | `collectSiteModuleAssets` — the one full-site render walk whose accumulators feed BOTH the framework CSS bundle (`cssMap`) and the published module-JS map (`jsMap`). |
 | `server/publish/moduleJsBundle.ts`              | Module-JS channel: `buildSiteModuleJsMap` (fresh), `buildPublishedSiteModuleJsMap` (memoised per publishVersion + site, invalidated by `bumpPublishVersion()`), and `injectModuleScripts` (per-page `<script defer>` tags + CSP `script-src 'self'` relaxation). |
-| `server/publish/republish.ts`                   | Bulk re-publish on settings change (touches every page).            |
+| `server/publish/republish.ts`                   | `republishAllPages` (plugin API `cms.content.republishAll`): re-renders every directly routable published page through `applyPublishedHtmlPipeline` so plugin hooks and filters fire, discarding the HTML. Skips template documents (no standalone public path). |
 | `server/publish/publishScheduler.ts`            | Scheduled publish jobs (cron-style).                                |
 | `server/publish/frontendInjections.ts`          | Compute plugin `<script>`/`<link>`/`<meta>` tags, preserve per-kind manifest attributes, protect host-owned attributes, and derive CSP entries. |
 | `server/publish/mediaPresentation.ts`           | Materialize media paths (originals + responsive variants) for publisher consumers. |
diff --git a/server/handlers/cms/data/preview.ts b/server/handlers/cms/data/preview.ts
index 9316caa73..695d850d9 100644
--- a/server/handlers/cms/data/preview.ts
+++ b/server/handlers/cms/data/preview.ts
@@ -144,7 +144,9 @@ export async function handleRowPreview(
       html: published.html,
       pageId: merged.id,
       slug: merged.slug,
-      path: publicPath,
+      // The encoded pathname, matching what live, baked and branch-preview
+      // renders report for the same entry (e.g. `/posts/caf%C3%A9`).
+      path: syntheticUrl.pathname,
       siteId: snapshot.site.id,
       jsModuleIds: published.jsModuleIds.filter((id) => moduleJsMap.has(id)),
       publishVersion: getPublishVersion(),
diff --git a/server/publish/branchPreview.ts b/server/publish/branchPreview.ts
index 46fe6076a..049ce4d80 100644
--- a/server/publish/branchPreview.ts
+++ b/server/publish/branchPreview.ts
@@ -5,9 +5,12 @@
  * Mirrors the editor's own runtime preview rather than the publish path: the
  * page (or entry template) is composed from the branch's draft rows, loops
  * read the branch, runtime scripts are bundled on demand and served from
- * memory, CSS is inlined, and no publish hook fires. Nothing here touches
- * the published snapshots, the render caches, or the disk slots — a preview
- * is a render, never a publish.
+ * memory, and CSS is inlined. The HTML then runs the same post-render
+ * pipeline as a published page (`applyPublishedHtmlPipeline`): the
+ * `publish.before` / `publish.after` events and the `publish.html` filter
+ * fire, with `path` set to the visitor's public pathname. Nothing here
+ * touches the published snapshots, the render caches, or the disk slots —
+ * a preview is a render, never a publish.
  *
  * Every response is `no-store` and `noindex`, and carries a banner naming
  * the branch with an exit link.
@@ -236,6 +239,7 @@ export async function renderBranchPreview(
       html: rendered.html,
       pageId: merged.id,
       slug: merged.slug,
+      path: url.pathname,
       siteId: site.id,
       jsModuleIds: rendered.jsModuleIds.filter((id) => moduleJsMap.has(id)),
       publishVersion: getPublishVersion(),
diff --git a/server/publish/republish.ts b/server/publish/republish.ts
index 0c8cf22c3..a1752255f 100644
--- a/server/publish/republish.ts
+++ b/server/publish/republish.ts
@@ -1,9 +1,10 @@
 /**
  * Background republish primitives.
  *
- * Called from the plugin API surface `api.cms.pages.republish(pageId)` and
- * `api.cms.pages.republishAll()`. These drive the full publish pipeline
- * (publish.before → publish.html filter → publish.after) for already-
+ * `republishAllPages` backs the plugin API call `api.cms.content.republishAll()`
+ * (host handler `handleContentRepublishAll` in
+ * `server/plugins/host/handlers/content.ts`). It drives the full published-HTML
+ * pipeline (publish.before → publish.html filter → publish.after) for already-
  * published pages, without writing a new snapshot. The side-effects — hook
  * listeners and filter handlers firing — are the whole point.
  *
@@ -14,8 +15,7 @@
  */
 
 import type { DbClient } from '../db/client'
-import { buildPageFrame } from '@core/templates/contextFrames'
-import { isTemplatePage } from '@core/templates'
+import { buildPageFrame, isTemplatePage } from '@core/templates'
 import { getPublishedPageSnapshotById } from '../repositories/publish'
 import { renderPublishedSnapshot } from './publicRenderer'
 import { applyPublishedHtmlPipeline } from './publishedHtmlPipeline'
diff --git a/src/__tests__/server/branchPreviewLinks.test.ts b/src/__tests__/server/branchPreviewLinks.test.ts
index 1f9636fe9..899d65e80 100644
--- a/src/__tests__/server/branchPreviewLinks.test.ts
+++ b/src/__tests__/server/branchPreviewLinks.test.ts
@@ -2,9 +2,10 @@
  * Branch preview links — issuing, the cookie handshake, rendering the
  * branch's draft on the public site, and revocation.
  */
-import { afterEach, describe, expect, it } from 'bun:test'
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
 import { handleServerRequest } from '../../../server/router'
 import { listDataRows, saveDataRowDraft, upsertDataRowDraft } from '../../../server/repositories/data'
+import { hookBus } from '../../core/plugins/hookBus'
 import {
   createCapabilityTestHarness,
   expectForbidden,
@@ -29,7 +30,12 @@ function cookieFrom(res: Response): string {
 describe('branch preview links', () => {
   let harness: CapabilityTestHarness | null = null
 
+  beforeEach(() => {
+    hookBus.reset()
+  })
+
   afterEach(async () => {
+    hookBus.reset()
     await harness?.cleanup()
     harness = null
   })
@@ -167,6 +173,89 @@ describe('branch preview links', () => {
     expect(html).toContain('<meta name="description" content="Search description">')
   })
 
+  it('passes the visitor pathname to publish.html, and the template slug for an entry', async () => {
+    harness = await createCapabilityTestHarness()
+    const owner = await harness.setupOwner()
+    const created = await harness.cms(BRANCHES, { method: 'POST', cookie: owner, json: { name: 'Filter Path' } })
+    expect(created.status).toBe(201)
+    const { branch } = await readJson<{ branch: { id: string } }>(created)
+    const scope = { branchId: branch.id }
+    const node = (id: string, moduleId: string, props: Record<string, unknown>, children: string[] = []) =>
+      ({ id, moduleId, props, children, breakpointOverrides: {}, classIds: [] })
+    await upsertDataRowDraft(harness.db, scope, {
+      id: 'about-page',
+      tableId: 'pages',
+      slug: 'about',
+      cells: {
+        title: 'About',
+        slug: 'about',
+        body: {
+          rootNodeId: 'root',
+          nodes: {
+            root: node('root', 'base.container', {}, ['copy']),
+            copy: node('copy', 'base.text', { text: 'About copy' }),
+          },
+        },
+      },
+    })
+    await upsertDataRowDraft(harness.db, scope, {
+      id: 'post-template',
+      tableId: 'pages',
+      slug: 'post-template',
+      cells: {
+        title: 'Post template',
+        slug: 'post-template',
+        templateEnabled: true,
+        templateTarget: { kind: 'postTypes', tableSlugs: ['posts'] },
+        templatePriority: 0,
+        body: {
+          rootNodeId: 'root',
+          nodes: {
+            root: node('root', 'base.container', {}, ['copy']),
+            copy: node('copy', 'base.text', { text: 'Entry body' }),
+          },
+        },
+      },
+    })
+    await upsertDataRowDraft(harness.db, scope, {
+      id: 'hello-world',
+      tableId: 'posts',
+      slug: 'hello-world',
+      cells: { title: 'Hello', slug: 'hello-world' },
+    })
+
+    const issued = await harness.cms(`${BRANCHES}/${branch.id}/preview`, { method: 'POST', cookie: owner })
+    expect(issued.status).toBe(201)
+    const { url } = await readJson<{ url: string }>(issued)
+    const entry = await handleServerRequest(publicRequest(new URL(url).pathname), { db: harness.db })
+    const cookie = cookieFrom(entry)
+
+    hookBus.filter('branch-preview-path', '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 previewedEntry = await handleServerRequest(publicRequest('/posts/hello-world', cookie), { db: harness.db })
+    expect(previewedEntry.status).toBe(200)
+    const entryHtml = await previewedEntry.text()
+    expect(entryHtml).toContain('Entry body')
+    expect(entryHtml).toContain('<meta name="publish-context-path" content="/posts/hello-world">')
+    expect(entryHtml).toContain('<meta name="publish-context-slug" content="post-template">')
+
+    const previewedPage = await handleServerRequest(publicRequest('/about', cookie), { db: harness.db })
+    expect(previewedPage.status).toBe(200)
+    const pageHtml = await previewedPage.text()
+    expect(pageHtml).toContain('About copy')
+    expect(pageHtml).toContain('<meta name="publish-context-path" content="/about">')
+    expect(pageHtml).toContain('<meta name="publish-context-slug" content="about">')
+
+    const previewedHome = await handleServerRequest(publicRequest('/', cookie), { db: harness.db })
+    expect(previewedHome.status).toBe(200)
+    const homeHtml = await previewedHome.text()
+    expect(homeHtml).toContain('<meta name="publish-context-path" content="/">')
+    expect(homeHtml).toContain('<meta name="publish-context-slug" content="index">')
+  })
+
   it('rotates the link on every share and gates issuing on who may act on the branch', async () => {
     harness = await createCapabilityTestHarness()
     const owner = await harness.setupOwner()
diff --git a/src/__tests__/server/dataPreviewPublishContext.test.ts b/src/__tests__/server/dataPreviewPublishContext.test.ts
new file mode 100644
index 000000000..93827de50
--- /dev/null
+++ b/src/__tests__/server/dataPreviewPublishContext.test.ts
@@ -0,0 +1,140 @@
+import { afterEach, beforeEach, describe, expect, it } from 'bun:test'
+import { handleCmsRequest } from '../../../server/handlers/cms'
+import type { DbClient } from '../../../server/db'
+import { persistSitePublish } from '../../../server/repositories/publish'
+import { resetForTests } from '../../../server/publish/renderCache'
+import { hookBus } from '../../core/plugins/hookBus'
+import { createTestDb, type TestDb } from '../helpers/createTestDb'
+import { makePage, makeSite } from '../publisher/helpers'
+import '@modules/base'
+
+const password = 'long-enough-password'
+
+async function request(
+  db: DbClient,
+  path: string,
+  options: RequestInit & { cookie?: string } = {},
+): Promise<Response> {
+  const headers = new Headers(options.headers)
+  if (options.body && !headers.has('content-type')) headers.set('content-type', 'application/json')
+  const req = new Request(`http://localhost${path}`, { ...options, headers })
+  // Set after construction: the Request constructor drops a `cookie` header.
+  if (options.cookie) req.headers.set('cookie', options.cookie)
+  return handleCmsRequest(req, db)
+}
+
+function sessionCookie(res: Response): string {
+  return (res.headers.get('set-cookie') ?? '').split(';')[0]
+}
+
+async function setupOwner(db: DbClient): Promise<string> {
+  const setup = await request(db, '/admin/api/cms/setup', {
+    method: 'POST',
+    body: JSON.stringify({ siteName: 'Preview Path Test', email: 'owner@example.com', password }),
+  })
+  expect(setup.status).toBe(201)
+  const login = await request(db, '/admin/api/cms/login', {
+    method: 'POST',
+    body: JSON.stringify({ email: 'owner@example.com', password }),
+  })
+  expect(login.status).toBe(200)
+  const stepUp = await request(db, '/admin/api/cms/auth/step-up', {
+    method: 'POST',
+    cookie: sessionCookie(login),
+    body: JSON.stringify({ password }),
+  })
+  expect(stepUp.status).toBe(200)
+  return sessionCookie(stepUp)
+}
+
+/** Publish a site snapshot whose only page is an entry template for `posts`. */
+async function publishPostTemplate(db: DbClient): Promise<void> {
+  const { rows: pageRows } = await db<{ id: string }>`
+    select id from data_rows where table_id = 'pages' and deleted_at is null limit 1
+  `
+  const { rows: userRows } = await db<{ id: string }>`select id from users limit 1`
+  const pageRowId = pageRows[0]!.id
+  const template = makePage({
+    root: { moduleId: 'base.body', props: {}, children: ['title'] },
+    title: { moduleId: 'base.text', props: { text: 'Entry', tag: 'h1' } },
+  })
+  template.id = pageRowId
+  template.title = 'Post Template'
+  template.slug = 'post-template'
+  template.template = {
+    enabled: true,
+    target: { kind: 'postTypes', tableSlugs: ['posts'] },
+    priority: 100,
+  }
+  await persistSitePublish(db, {
+    siteSnapshotId: crypto.randomUUID(),
+    site: makeSite({ pages: [template] }),
+    serializedImportmap: null,
+    pages: [{
+      pageId: pageRowId,
+      title: template.title,
+      slug: template.slug,
+      versionId: crypto.randomUUID(),
+      versionNumber: 1,
+      runtimeAssets: null,
+      runtimeFiles: [],
+    }],
+    publishedByUserId: userRows[0]!.id,
+  })
+}
+
+describe('admin entry preview publish.html context', () => {
+  const cleanupFns: Array<() => Promise<void>> = []
+
+  // resetForTests also clears the version-keyed memos (incl. the module-JS
+  // map the preview populates) so no state leaks into other test files.
+  beforeEach(() => {
+    resetForTests()
+    hookBus.reset()
+  })
+
+  afterEach(async () => {
+    resetForTests()
+    hookBus.reset()
+    while (cleanupFns.length) await cleanupFns.pop()?.()
+  })
+
+  async function makeDb(): Promise<TestDb> {
+    const testDb = await createTestDb()
+    cleanupFns.push(testDb.cleanup)
+    return testDb
+  }
+
+  it('reports the percent-encoded public pathname as `path`, matching live and baked renders', async () => {
+    const { db } = await makeDb()
+    const cookie = await setupOwner(db)
+    await publishPostTemplate(db)
+
+    const created = await request(db, '/admin/api/cms/data/tables/posts/rows', {
+      method: 'POST',
+      cookie,
+      body: JSON.stringify({ cells: { title: 'Cafe post', slug: 'cafe-post' } }),
+    })
+    expect(created.status).toBe(201)
+    const { row } = await created.json() as { row: { id: string } }
+
+    hookBus.filter('fx-04-regression', 'publish.html', (html, context) => {
+      const { path } = context as { path?: string }
+      return `${html}<!--publish-path:${JSON.stringify(path ?? null)}-->`
+    })
+
+    const preview = await request(db, `/admin/api/cms/data/rows/${row.id}/preview`, {
+      method: 'POST',
+      cookie,
+      body: JSON.stringify({ cells: { slug: 'café' } }),
+    })
+    const html = await preview.text()
+    expect(preview.status).toBe(200)
+
+    const reported = /<!--publish-path:(.*?)-->/.exec(html)?.[1]
+    expect(reported).toBeDefined()
+    const expected = new URL('http://x/posts/café').pathname
+    expect(expected).toBe('/posts/caf%C3%A9')
+    expect(JSON.parse(reported!)).toBe(expected)
+  })
+})
diff --git a/src/__tests__/server/publicRendering.test.ts b/src/__tests__/server/publicRendering.test.ts
index c1754ba55..b4a26b9f0 100644
--- a/src/__tests__/server/publicRendering.test.ts
+++ b/src/__tests__/server/publicRendering.test.ts
@@ -229,6 +229,9 @@ describe('public rendering', () => {
       },
     })
 
+  // Public URL of `entryBaseRow` (`tableRouteBase` + `slug`).
+  const entryUrl = () => new URL('http://localhost/blog/hello')
+
   const entryBaseRow: Omit<PublishedDataRow, 'cells'> = {
     id: 'ver_1',
     rowId: 'row_1',
@@ -271,7 +274,7 @@ describe('public rendering', () => {
           seoDescription: 'SEO override description',
         },
       },
-      { db: makeFakeDb(snap) },
+      { db: makeFakeDb(snap), url: entryUrl() },
     )
     expect(withSeo?.html).toContain('<title>SEO Override Title</title>')
     expect(withSeo?.html).toContain(
@@ -288,7 +291,7 @@ describe('public rendering', () => {
     const withoutSeo = await renderPublishedDataRowTemplate(
       snap,
       { ...entryBaseRow, cells: { title: 'Plain H1 Title' } },
-      { db: makeFakeDb(snap) },
+      { db: makeFakeDb(snap), url: entryUrl() },
     )
     expect(withoutSeo?.html).toContain('<title>Plain H1 Title</title>')
     expect(withoutSeo?.html).not.toContain('<meta name="description"')
@@ -300,7 +303,7 @@ describe('public rendering', () => {
     const blankSeo = await renderPublishedDataRowTemplate(
       snap,
       { ...entryBaseRow, cells: { title: 'Plain H1 Title', seoTitle: '   ', seoDescription: '' } },
-      { db: makeFakeDb(snap) },
+      { db: makeFakeDb(snap), url: entryUrl() },
     )
     expect(blankSeo?.html).toContain('<title>Plain H1 Title</title>')
     expect(blankSeo?.html).not.toContain('<meta name="description"')
@@ -325,7 +328,7 @@ describe('public rendering', () => {
           seoDescription: 'SEO override description',
         },
       },
-      { db: makeFakeDb(snap) },
+      { db: makeFakeDb(snap), url: entryUrl() },
     )
     expect(withSeo?.html).toContain('<title>SEO Override Title</title>')
     expect(withSeo?.html).toContain(
@@ -339,7 +342,7 @@ describe('public rendering', () => {
     const withoutSeo = await renderPublishedDataRowTemplate(
       snap,
       { ...entryBaseRow, cells: { title: 'Plain H1 Title' } },
-      { db: makeFakeDb(snap) },
+      { db: makeFakeDb(snap), url: entryUrl() },
     )
     expect(withoutSeo?.html).toContain('<title>Site Wide Meta Title</title>')
     expect(withoutSeo?.html).toContain(
diff --git a/src/__tests__/server/republish.test.ts b/src/__tests__/server/republish.test.ts
index f46d58da7..e2262e100 100644
--- a/src/__tests__/server/republish.test.ts
+++ b/src/__tests__/server/republish.test.ts
@@ -1,4 +1,4 @@
-import { beforeEach, describe, expect, it } from 'bun:test'
+import { afterEach, 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'
@@ -83,6 +83,10 @@ describe('background republish', () => {
     hookBus.reset()
   })
 
+  afterEach(() => {
+    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) => {
diff --git a/src/core/templates/index.ts b/src/core/templates/index.ts
index d1144d7f1..8315b9fb5 100644
--- a/src/core/templates/index.ts
+++ b/src/core/templates/index.ts
@@ -18,7 +18,7 @@ export {
   normalizeRouteBase,
   type RouteResolutionContext,
 } from './templateMatching'
-export { buildRouteFrame } from './contextFrames'
+export { buildPageFrame, buildRouteFrame } from './contextFrames'
 export type { TemplateRenderDataContext } from './dynamicBindings'
 export { composeTemplateChain } from './templateCompose'
 export { firstOutletId, treeHasOutlet, subtreeHasOutlet } from './outlet'