@invisibleloop/pulse 0.1.23 → 0.1.29

package/.claude/settings.local.json

@@ -96,7 +96,18 @@
       "Bash(git branch:*)",
       "Bash(gh run:*)",
       "Bash(xargs -I{} gh run delete {} --repo invisibleloop/pulse-framework)",
-      "Bash(gh api:*)"
+      "Bash(gh api:*)",
+      "Bash(npm access:*)",
+      "Bash(gh pr:*)",
+      "Bash(git fetch:*)",
+      "Bash(git rebase:*)",
+      "Bash(git rm:*)",
+      "Bash(sed -i '' 's/Ship with it built in/Production quality, built in/' docs/src/pages/home.js)",
+      "Bash(3 \" -A2 docs/src/pages/home.js)",
+      "Bash(git merge:*)",
+      "Bash(node -p \"require\\(''./package.json''\\).version\")",
+      "Bash(npm view:*)",
+      "Bash(git cherry-pick:*)"
     ]
   }
 }

package/.github/workflows/publish.yml

@@ -1,25 +1,17 @@
 name: Release
 
 on:
-  workflow_dispatch:
-    inputs:
-      bump:
-        description: Version bump
-        type: choice
-        options: [patch, minor, major]
-        default: patch
-        required: true
+  push:
+    branches: [main]
 
 jobs:
   release:
     runs-on: ubuntu-latest
     permissions:
-      contents: write
+      contents: read
       id-token: write
     steps:
       - uses: actions/checkout@v4
-        with:
-          token: ${{ secrets.GITHUB_TOKEN }}
 
       - uses: actions/setup-node@v4
         with:
@@ -31,12 +23,12 @@ jobs:
 
       - run: npm test
 
-      - name: Bump version and tag
+      - name: Publish if version is new
         run: |
-          git config user.name "github-actions[bot]"
-          git config user.email "github-actions[bot]@users.noreply.github.com"
-          git pull --rebase
-          npm version ${{ inputs.bump }} -m "chore: release %s [skip ci]"
-          git push --follow-tags
-
-      - run: npm publish --provenance --access public
+          VERSION=$(node -p "require('./package.json').version")
+          EXISTS=$(npm view @invisibleloop/pulse@$VERSION version 2>/dev/null || echo "")
+          if [ -z "$EXISTS" ]; then
+            npm publish --provenance --access public
+          else
+            echo "Version $VERSION already published — skipping."
+          fi

package/docs/public/.pulse-ui-version

@@ -1 +1 @@
-0.1.20
+0.1.28

package/docs/public/docs.css

@@ -167,6 +167,15 @@ a:hover {
   margin-bottom: 1.25rem;
 }
 
+.hero-kicker {
+  font-size: 0.95rem;
+  font-weight: 500;
+  color: #0a0a0a;
+  opacity: 0.55;
+  margin-bottom: 1rem;
+  letter-spacing: 0.01em;
+}
+
 .hero-badge {
   display: inline-flex;
   align-items: center;
@@ -432,6 +441,7 @@ a:hover {
 .home-code {
   background: #111114;
   padding: 5rem 2rem 6rem;
+  --muted: #9090a0;
 }
 
 .home-code-inner {
@@ -1467,7 +1477,11 @@ a:hover {
   border: none;
   color: var(--muted);
   cursor: pointer;
-  padding: 0.25rem;
+  min-width: 44px;
+  min-height: 44px;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
 }
 .mobile-menu-btn:hover {
   color: var(--text);
@@ -1476,6 +1490,10 @@ a:hover {
 .header-logo-mobile {
   display: none;
   color: var(--text);
+  min-width: 44px;
+  min-height: 44px;
+  align-items: center;
+  justify-content: center;
 }
 
 .header-github {

package/docs/public/pulse-ui.css

@@ -1635,6 +1635,7 @@ hr.ui-divider {
   font-family: var(--ui-mono);
   color:       var(--ui-muted);
   margin-left: auto;
+  opacity:     .7;
 }
 
 .ui-code-window-pre {

package/docs/server.js

@@ -37,6 +37,7 @@ import meta               from './src/pages/meta.js'
 import performance        from './src/pages/performance.js'
 import accessibility      from './src/pages/accessibility.js'
 import testing           from './src/pages/testing.js'
+import store             from './src/pages/store.js'
 
 // Component pages
 import compButton      from './src/pages/components/button.js'
@@ -130,6 +131,7 @@ createServer(
     performance,
     accessibility,
     testing,
+    store,
     // Component pages
     compButton,
     compBadge,
@@ -186,7 +188,8 @@ createServer(
     compIcons,
   ],
   {
-    port:      process.env.PORT ? Number(process.env.PORT) : 4000,
-    staticDir: new URL('./public', import.meta.url).pathname,
+    port:         process.env.PORT ? Number(process.env.PORT) : 4000,
+    staticDir:    new URL('./public', import.meta.url).pathname,
+    defaultCache: true,
   }
 )

package/docs/src/lib/highlight.js

@@ -212,6 +212,62 @@ function highlightBash(code) {
 // HTML tokeniser (minimal)
 // ---------------------------------------------------------------------------
 
+function highlightHtmlTag(tag) {
+  // Single-pass tag highlighter — avoids the chained .replace() trap where a
+  // later pass re-processes class="tok-fn" strings already injected by an
+  // earlier pass, producing broken HTML like <span class=<span …>"tok-fn"</span>>.
+  let out = ''
+  let i = 0
+
+  // Opening < or </
+  out += '&lt;'
+  i++ // skip <
+  if (tag[i] === '/') { out += '/'; i++ }
+
+  // Tag name
+  let name = ''
+  while (i < tag.length && /[\w-]/.test(tag[i])) name += tag[i++]
+  if (name) out += span('tok-kw', name)
+
+  // Attributes and remainder up to >
+  while (i < tag.length) {
+    const ch = tag[i]
+    if (ch === '>') { out += '&gt;'; i++; break }
+    if (ch === '/') { out += '/'; i++; continue }
+
+    if (/[\w-]/.test(ch)) {
+      // Attribute name
+      let attr = ''
+      while (i < tag.length && /[\w-]/.test(tag[i])) attr += tag[i++]
+
+      if (tag[i] === '=') {
+        out += span('tok-fn', attr) + esc('=')
+        i++ // skip =
+        // Attribute value
+        const q = tag[i]
+        if (q === '"' || q === "'") {
+          let val = q
+          i++
+          while (i < tag.length && tag[i] !== q) {
+            if (tag[i] === '\\') { val += tag[i] + (tag[i + 1] || ''); i += 2; continue }
+            val += tag[i++]
+          }
+          if (i < tag.length) val += tag[i++] // closing quote
+          out += span('tok-str', val)
+        }
+      } else {
+        out += esc(attr)
+      }
+      continue
+    }
+
+    out += esc(ch)
+    i++
+  }
+
+  return out
+}
+
 function highlightHtml(code) {
   let out = ''
   let i = 0
@@ -231,19 +287,7 @@ function highlightHtml(code) {
     if (code[i] === '<') {
       const end = code.indexOf('>', i)
       if (end === -1) { out += esc(code[i++]); continue }
-      const tag = code.slice(i, end + 1)
-      // Simple: highlight tag name + attributes
-      const highlighted = tag.replace(
-        /^(<\/?)([\w-]+)/,
-        (_, lt, name) => esc(lt) + span('tok-kw', name)
-      ).replace(
-        /([\w-]+)(=)/g,
-        (_, attr, eq) => span('tok-fn', attr) + esc(eq)
-      ).replace(
-        /("(?:[^"\\]|\\.)*"|'(?:[^'\\]|\\.)*')/g,
-        (_, str) => span('tok-str', str)
-      )
-      out += highlighted
+      out += highlightHtmlTag(code.slice(i, end + 1))
       i = end + 1
       continue
     }

package/docs/src/lib/layout.js

@@ -6,6 +6,9 @@
  */
 
 import { NAV } from './nav.js'
+import pkg from '../../../package.json' with { type: 'json' }
+
+const { version } = pkg
 
 function esc(s) {
   return String(s).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;')
@@ -33,7 +36,7 @@ function sidebar(currentHref) {
           </svg>
           <span class="logo-name">Pulse</span>
         </a>
-        <span class="version-badge">v0.1</span>
+        <span class="version-badge">v${version}</span>
       </div>
       <nav class="sidebar-nav">
         ${sections}
@@ -74,7 +77,7 @@ export function renderLayout({ currentHref, content, prev = null, next = null })
             <path d="M13 2L4.5 13.5H11L10 22L19.5 10.5H13L13 2Z" fill="var(--accent)" stroke="var(--accent)" stroke-width="1" stroke-linejoin="round"/>
           </svg>
         </a>
-        <a href="https://github.com/invisibleloop/pulse" class="header-github" aria-label="View on GitHub" target="_blank" rel="noopener noreferrer">
+        <a href="https://github.com/invisibleloop/pulse-framework" class="header-github" aria-label="View on GitHub" target="_blank" rel="noopener noreferrer">
           <svg width="20" height="20" viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
             <path d="M12 2C6.477 2 2 6.484 2 12.017c0 4.425 2.865 8.18 6.839 9.504.5.092.682-.217.682-.483 0-.237-.008-.868-.013-1.703-2.782.605-3.369-1.343-3.369-1.343-.454-1.158-1.11-1.466-1.11-1.466-.908-.62.069-.608.069-.608 1.003.07 1.531 1.032 1.531 1.032.892 1.53 2.341 1.088 2.91.832.092-.647.35-1.088.636-1.338-2.22-.253-4.555-1.113-4.555-4.951 0-1.093.39-1.988 1.029-2.688-.103-.253-.446-1.272.098-2.65 0 0 .84-.27 2.75 1.026A9.564 9.564 0 0112 6.844c.85.004 1.705.115 2.504.337 1.909-1.296 2.747-1.027 2.747-1.027.546 1.379.202 2.398.1 2.651.64.7 1.028 1.595 1.028 2.688 0 3.848-2.339 4.695-4.566 4.943.359.309.678.92.678 1.855 0 1.338-.012 2.419-.012 2.747 0 .268.18.58.688.482A10.019 10.019 0 0022 12.017C22 6.484 17.522 2 12 2z"/>
           </svg>

package/docs/src/pages/faq.js

@@ -1,5 +1,8 @@
 import { renderLayout, h1, lead } from '../lib/layout.js'
 import { prevNext } from '../lib/nav.js'
+import pkg from '../../../package.json' with { type: 'json' }
+
+const { version } = pkg
 
 const { prev, next } = prevNext('/faq')
 
@@ -30,7 +33,7 @@ export default {
       ${q(
         'Is Pulse ready for production?',
         `<p>The architecture is production-quality — streaming SSR, security headers, immutable caching, and zero runtime dependencies are built in and have been running reliably in real deployments. The framework itself targets Lighthouse 100 on every scaffolded page.</p>
-        <p>That said, Pulse is v0.1 early access. The core spec format is stable, but some APIs may change before v1. It is best suited to new projects where you control the stack, and to teams who are comfortable building on something that is still evolving. If you need a framework with a five-year stability guarantee, wait for v1.</p>`
+        <p>That said, Pulse is v${version} early access. The core spec format is stable, but some APIs may change before v1. It is best suited to new projects where you control the stack, and to teams who are comfortable building on something that is still evolving. If you need a framework with a five-year stability guarantee, wait for v1.</p>`
       )}
 
       ${q(
@@ -42,7 +45,7 @@ export default {
       ${q(
         'Why no virtual DOM?',
         `<p>A virtual DOM solves the problem of efficient incremental updates to a large, complex component tree. Pulse pages are server-rendered HTML strings — the client runtime re-renders a bounded section of the page when state changes, which is fast enough for the kinds of interactions Pulse is designed for.</p>
-        <p>Eliminating the virtual DOM means eliminating the ~40–100 kB runtime that comes with it. Pulse ships ~2 kB brotli to the browser on first visit. That is not a compression trick — there is genuinely no framework runtime on the client.</p>`
+        <p>Eliminating the virtual DOM means eliminating the ~40–100 kB runtime that comes with it. Pulse ships ~3.5 kB brotli to the browser on first visit (shared runtime + page bundle). That is not a compression trick — there is genuinely no framework runtime on the client.</p>`
       )}
 
       ${q(

package/docs/src/pages/home.js

@@ -1,6 +1,9 @@
 import { highlight }     from '../lib/highlight.js'
 import { metricsStore }  from '../lib/metrics-store.js'
 import { codeWindow }    from '../../../src/ui/code-window.js'
+import pkg from '../../../package.json' with { type: 'json' }
+
+const { version } = pkg
 
 const exampleSpec = highlight(`export default {
   route: '/dashboard',
@@ -52,7 +55,7 @@ export default {
         </a>
         <div class="home-nav-links">
           <a href="/getting-started">Docs</a>
-          <a href="https://github.com/invisibleloop/pulse" target="_blank" rel="noopener">GitHub</a>
+          <a href="https://github.com/invisibleloop/pulse-framework" target="_blank" rel="noopener">GitHub</a>
         </div>
       </nav>
 
@@ -63,9 +66,10 @@ export default {
             <path d="M13 2L4.5 13.5H11L10 22L19.5 10.5H13L13 2Z" fill="var(--accent)" stroke="var(--accent)" stroke-width="1" stroke-linejoin="round"/>
           </svg>
         </div>
-        <div class="hero-badge">v0.1 — EARLY ACCESS</div>
+        <div class="hero-badge">v${version} — EARLY ACCESS</div>
+        <p class="hero-kicker">A Node.js framework for building server-rendered web apps</p>
         <h1 class="hero-title">Describe the outcome. Pulse guarantees it.</h1>
-        <p class="hero-subtitle">One spec object per page — server data, state, mutations, and view, co-located in plain JS. Streaming SSR, security headers, and production caching are enforced by the framework, not left to configuration.<br><br>Designed for AI agents. Production-quality architecture.</p>
+        <p class="hero-subtitle">One spec object per page — server data, state, mutations, and view in plain JS. Streaming SSR, security headers, and production caching are enforced by the framework, not left to configuration. Designed for AI agents.</p>
         <div class="hero-ctas">
           <a href="/getting-started" class="btn-primary">Get Started</a>
           <a href="/spec" class="btn-secondary">Read the Spec</a>
@@ -112,7 +116,7 @@ export default {
           <div class="how-connector" aria-hidden="true"></div>
           <div class="how-step">
             <div class="how-step-num">3</div>
-            <h3>Ship with it built in</h3>
+            <h3>Production quality, built in</h3>
             <p>Streaming SSR, security headers, and immutable caching come from the framework — not your config. Follow the spec, and the results follow.</p>
           </div>
         </div>
@@ -394,7 +398,7 @@ export default {
 
       </main>
       <footer class="home-footer">
-        <p>MIT License · <a href="https://github.com/invisibleloop/pulse" target="_blank" rel="noopener">GitHub</a> · <a href="/getting-started">Get started in 2 minutes</a></p>
+        <p>MIT License · <a href="https://github.com/invisibleloop/pulse-framework" target="_blank" rel="noopener">GitHub</a> · <a href="/getting-started">Get started in 2 minutes</a></p>
       </footer>
     </div>
   `,

package/docs/src/pages/meta.js

@@ -46,6 +46,7 @@ export default {
           ['<code>ogTitle</code>', '<code>string</code>', 'Open Graph title. If omitted, falls back to <code>title</code>.'],
           ['<code>ogImage</code>', '<code>string</code>', 'Open Graph image URL — shown when the page is shared on social media.'],
           ['<code>schema</code>', '<code>object</code>', 'JSON-LD structured data object — emitted as a <code>&lt;script type="application/ld+json"&gt;</code> tag.'],
+          ['<code>canonical</code>', '<code>string | (ctx, serverState) => string</code>', 'Canonical URL — overrides the auto-derived canonical. Accepts a function for dynamic values.'],
         ]
       )}
 
@@ -96,6 +97,26 @@ export default {
         ]
       )}
 
+      ${section('canonical', 'Canonical URLs')}
+      <p>Pulse automatically derives a canonical URL from the request and emits it as a <code>&lt;link rel="canonical"&gt;</code> tag on every page. In most cases no configuration is needed.</p>
+      <p>Use <code>meta.canonical</code> to override — for example, on paginated pages or when content is accessible at more than one URL. A plain string is resolved once at startup:</p>
+      ${codeBlock(highlight(`// Paginated blog — pages 2, 3, … all canonicalise to the first page
+meta: {
+  title:     'Blog — Page 2',
+  canonical: 'https://mysite.com/blog',
+}`, 'js'))}
+      <p>Pass a function to derive the canonical from the request context or server data. The function receives <code>(ctx, serverState)</code>:</p>
+      ${codeBlock(highlight(`// Canonical from a URL param
+meta: {
+  canonical: (ctx) => \`https://mysite.com/products/\${ctx.params.slug}\`,
+}
+
+// Canonical from a server fetcher result (e.g. canonical slug from a database lookup)
+meta: {
+  canonical: (ctx, serverState) => \`https://mysite.com/products/\${serverState.product.slug}\`,
+}`, 'js'))}
+      ${callout('note', '<strong>Streaming caveat:</strong> when <code>stream: true</code> (the default), the <code>&lt;head&gt;</code> is written before server fetchers resolve, so <code>serverState</code> will be <code>null</code> for streaming responses. If your canonical depends on server data, set <code>stream: false</code> on that spec, or derive it from <code>ctx.params</code> instead.')}
+
       ${section('styles', 'Stylesheets')}
       <p>The <code>styles</code> array accepts any number of stylesheet URLs. They are emitted as <code>&lt;link rel="stylesheet"&gt;</code> tags in the <code>&lt;head&gt;</code> in the order declared:</p>
       ${codeBlock(highlight(`meta: {

package/docs/src/pages/routing.js

@@ -27,7 +27,18 @@ export default {
   state: {},
   view: () => \`<h1>About</h1>\`,
 }`, 'js'))}
-      <p>Pulse matches the exact path. Trailing slashes are normalised — <code>/about</code> and <code>/about/</code> are treated the same.</p>
+      <p>Pulse matches the exact path. By default, trailing slashes are removed — <code>/about/</code> redirects to <code>/about</code> with a 301. This is controlled by the <code>trailingSlash</code> option in <code>createServer</code>:</p>
+      ${table(
+        ['Value', 'Behaviour'],
+        [
+          ['<code>"remove"</code> (default)', 'Redirects <code>/about/</code> → <code>/about</code> (301)'],
+          ['<code>"add"</code>', 'Redirects <code>/about</code> → <code>/about/</code> (301)'],
+          ['<code>"allow"</code>', 'Serves both — no redirect'],
+        ]
+      )}
+      ${codeBlock(highlight(`createServer(specs, {
+  trailingSlash: 'add', // enforce trailing slashes
+})`, 'js'))}
 
       ${section('dynamic', 'Dynamic segments')}
       <p>Use a colon prefix for dynamic path segments. Named segments are captured and available in <code>ctx.params</code> in <a href="/server-data">server data</a>:</p>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.1.23",
+  "version": "0.1.29",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",
@@ -65,6 +65,10 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "esbuild": "^0.27.4"
   },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/invisibleloop/pulse-framework"
+  },
   "publishConfig": {
     "access": "public"
   },
@@ -72,4 +76,4 @@
     "@types/node": "^25.5.0",
     "typescript": "^5.9.3"
   }
-}
+}

package/src/agent/guide-routing.md

@@ -34,3 +34,23 @@ Convention: name dynamic-route files [param].js inside a subfolder:
   src/pages/blog/[slug].js  with  route: '/blog/:slug'
 
 This is purely a human readability convention. Pulse does not process [ ] in filenames.
+
+## Canonical URLs
+
+Pulse auto-derives a canonical URL from every request and emits `<link rel="canonical">` in the `<head>`. No config needed in most cases.
+
+Override with `meta.canonical` when content is accessible at multiple URLs, or for paginated series:
+
+```js
+// Static override
+meta: { canonical: 'https://mysite.com/blog' }
+
+// From URL params (works in both streaming and string mode)
+meta: { canonical: (ctx) => `https://mysite.com/products/${ctx.params.slug}` }
+
+// From server data — e.g. canonical slug from a DB lookup
+// Only works when stream: false. In streaming mode serverState is null at head-write time.
+meta: { canonical: (ctx, serverState) => `https://mysite.com/products/${serverState.product.slug}` }
+```
+
+The function signature is `(ctx, serverState) => string`. `serverState` is only populated on the string (non-streaming) path — if your canonical depends on server fetcher results, add `stream: false` to that spec.

package/src/agent/guide-spec.md

@@ -4,7 +4,15 @@ Pulse is a spec-first frontend framework. Pages are JS files that export a defau
 
 ```js
 export default {
-  meta: { title, description, styles: ['/app.css'] },
+  meta: {
+    title:       'Page Title',             // string or (ctx) => string
+    description: 'Meta description',       // string or (ctx) => string
+    styles:      ['/app.css'],             // string[] or (ctx) => string[]
+    ogTitle:     'Social title',           // optional — falls back to title
+    ogImage:     'https://…/og.jpg',       // optional — 1200×630 recommended
+    canonical:   'https://mysite.com/…',  // optional — string or (ctx, serverState) => string
+    schema:      { '@context': 'https://schema.org', '@type': 'WebPage', … },  // optional JSON-LD
+  },
   state: { /* initial state */ },
   mutations: {
     // Synchronous. Return partial state. First arg is state, second is the DOM event.

package/src/cli/scaffold.js

@@ -53,8 +53,9 @@ export async function scaffold(targetDir, options = {}) {
 ${port !== 3000 ? `  port: ${port},\n` : ''}}
 `)
 
-  // Home page — working counter proves the app runs
-  write(targetDir, 'src/pages/home.js', homePage(name))
+  // Home page + tests — working counter proves the app runs
+  write(targetDir, 'src/pages/home.js',      homePage(name))
+  write(targetDir, 'src/pages/home.test.js', homePageTest(name))
 
   // Minimal stylesheet
   write(targetDir, 'public/app.css', baseCSS())
@@ -184,6 +185,15 @@ ${port !== 3000 ? `  port: ${port},\n` : ''}}
   } catch {
     execSync('npm install', { cwd: targetDir, stdio: 'inherit' })
   }
+
+  // Initialise git so the Stop hook can use `git status` to track only changed files.
+  // Without this the hook falls back to listing all src/pages/*.js and flags home.js.
+  try {
+    execSync('git init && git add -A && git commit -m "init"', { cwd: targetDir, stdio: 'pipe' })
+    console.log('  ✓ Git repository initialised')
+  } catch {
+    // Non-fatal — project still works without git, stop hook falls back gracefully.
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -244,6 +254,51 @@ export default {
 `
 }
 
+function homePageTest(_appName) {
+  return `\
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { renderSync } from '@invisibleloop/pulse/testing'
+import spec from './home.js'
+
+test('home page renders app name', () => {
+  const r = renderSync(spec)
+  assert(r.has('main#main-content'))
+  assert(r.has('h1'))
+})
+
+test('home page renders counter at 0', () => {
+  const r = renderSync(spec)
+  assert(r.has('span[aria-live]'))
+  assert.equal(r.get('span[aria-live]').text, '0')
+})
+
+test('home page decrement disabled at min', () => {
+  const r = renderSync(spec, { state: { count: 0 } })
+  const buttons = r.findAll('button')
+  const dec = buttons.find(b => b.attr('aria-label') === 'Decrease count')
+  assert(dec, 'decrement button not found')
+  assert(dec.attrs.disabled !== undefined, 'decrement should be disabled at 0')
+})
+
+test('home page increment disabled at max', () => {
+  const r = renderSync(spec, { state: { count: 10 } })
+  const buttons = r.findAll('button')
+  const inc = buttons.find(b => b.attr('aria-label') === 'Increase count')
+  assert(inc, 'increment button not found')
+  assert(inc.attrs.disabled !== undefined, 'increment should be disabled at 10')
+})
+
+test('increment mutation adds 1', () => {
+  assert.deepEqual(spec.mutations.increment({ count: 4 }), { count: 5 })
+})
+
+test('decrement mutation subtracts 1', () => {
+  assert.deepEqual(spec.mutations.decrement({ count: 4 }), { count: 3 })
+})
+`
+}
+
 function baseCSS() {
   return `\
 *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
@@ -280,6 +335,12 @@ public/app.css   ← global stylesheet
 
 The MCP guide is the single source of truth. Follow it for all technical decisions, component usage, and the mandatory verification workflow.
 
+## Before writing any code
+
+**Always present a plan and wait for the user to confirm before writing a single line of code.**
+
+The plan must include: route, page sections, components used, state shape, and whether hydration is needed. End the plan with an explicit question — "Shall I go ahead?" — and stop. Do not proceed until the user says yes (or equivalent). This applies to every new page or significant change, no matter how clear the task seems.
+
 ## After completing any feature
 
 Run these steps in order — do not declare work done without them:

package/src/server/index.js

@@ -541,14 +541,16 @@ export function createServer(specs, options = {}) {
         }
       }
 
-      // Build canonical URL — prefer spec.meta.canonical, otherwise derive from request.
+      // Derive the canonical base URL from the request.
       // Canonical path follows the trailingSlash mode so the <link> is consistent with redirects.
+      // spec.meta.canonical (string or function) is resolved inside each handler, where serverState
+      // is available — allowing dynamic canonicals from server fetcher results.
       const proto        = req.headers['x-forwarded-proto'] || 'http'
       const host         = req.headers['x-forwarded-host'] || req.headers.host || `localhost:${port}`
       const canonicalPath = trailingSlash === 'add' && pathname !== '/'
         ? (pathname.endsWith('/') ? pathname : pathname + '/')
         : (pathname !== '/' && pathname.endsWith('/') ? pathname.slice(0, -1) : pathname)
-      const canonicalUrl = spec.meta?.canonical || `${proto}://${host}${canonicalPath}`
+      const canonicalBase = `${proto}://${host}${canonicalPath}`
 
       // Raw content spec (RSS, sitemap, JSON API, webhooks) — bypass HTML pipeline
       if (spec.contentType) {
@@ -563,9 +565,9 @@ export function createServer(specs, options = {}) {
       }
 
       if (stream) {
-        await handleStreamResponse(spec, ctx, req, res, extraBody, dev, canonicalUrl, nonce, runtimeBundle, defaultCache, store, csp)
+        await handleStreamResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp)
       } else {
-        await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalUrl, nonce, runtimeBundle, defaultCache, store, csp)
+        await handleStringResponse(spec, ctx, req, res, extraBody, dev, canonicalBase, nonce, runtimeBundle, defaultCache, store, csp)
       }
 
     } catch (err) {
@@ -676,7 +678,7 @@ async function handleNavResponse(spec, ctx, res, dev = false) {
  * Render to a complete string then send — simpler, easier to cache.
  * Checks the in-process page cache before rendering; stores result after.
  */
-async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalUrl = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}) {
+async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}) {
   const cacheKey = spec.route + '\0' + JSON.stringify(ctx.params) + '\0' + JSON.stringify(ctx.query)
   // Pages with server data or store data embed a nonce'd __PULSE_SERVER__ script — don't cache them
   const ttl      = (!spec.server && !spec.store?.length) ? pageCacheTtl(spec, dev, defaultCache) : 0
@@ -689,6 +691,12 @@ async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = f
     fromCache  = true
   } else {
     const { html: content, serverState, timing } = await cachedRenderToString(spec, ctx, dev)
+    // Resolve canonical — supports a function receiving (ctx, serverState) so the URL can be
+    // derived from server fetcher results (e.g. a canonical slug from a database lookup).
+    const canonicalRaw = spec.meta?.canonical
+    const canonicalUrl = typeof canonicalRaw === 'function'
+      ? (canonicalRaw(ctx, serverState) || canonicalBase)
+      : (canonicalRaw || canonicalBase)
     const canonicalTag      = canonicalUrl ? `<link rel="canonical" href="${escHtml(canonicalUrl)}">` : ''
     const resolvedSpec      = { ...spec, meta: resolveMeta(spec.meta, ctx) }
     const resolvedExtraBody = typeof extraBody === 'function' ? extraBody(nonce) : extraBody
@@ -720,7 +728,7 @@ async function handleStringResponse(spec, ctx, req, res, extraBody = '', dev = f
  * Stream the response — shell first, deferred segments follow.
  * On a page-cache hit, serves the buffered HTML as a string (no streaming needed).
  */
-async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalUrl = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}) {
+async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = false, canonicalBase = '', nonce = '', runtimeBundle = '', defaultCache = null, store = null, csp = {}) {
   // Serve from in-process page cache when available — skip streaming overhead.
   // Pages with spec.server or spec.store embed a nonce'd __PULSE_SERVER__ script so are never cached.
   const cacheKey = spec.route + '\0' + JSON.stringify(ctx.params) + '\0' + JSON.stringify(ctx.query)
@@ -748,6 +756,13 @@ async function handleStreamResponse(spec, ctx, req, res, extraBody = '', dev = f
   // Write the document opening immediately so the browser starts parsing
   const meta  = resolveMeta(spec.meta, ctx)
   const title = meta.title || 'Pulse'
+  // Resolve canonical — supports a string or a function receiving (ctx).
+  // Note: server fetcher results are not yet available when the <head> is written in streaming mode.
+  // If your canonical depends on server data, use stream: false on that spec, or set it as a string.
+  const canonicalRaw = spec.meta?.canonical
+  const canonicalUrl = typeof canonicalRaw === 'function'
+    ? (canonicalRaw(ctx) || canonicalBase)
+    : (canonicalRaw || canonicalBase)
 
   const stylePreloads = (meta.styles || [])
     .map(href => `  <link rel="preload" as="style" href="${escHtml(href)}">`)