@invisibleloop/pulse 0.1.28 → 0.1.30

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,14 +23,13 @@ jobs:
 
       - run: npm test
 
-      - name: Bump version and tag
-        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
+      - name: Bump patch version if already published, then publish
         env:
           NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+        run: |
+          VERSION=$(node -p "require('./package.json').version")
+          while npm view @invisibleloop/pulse@$VERSION version 2>/dev/null | grep -q .; do
+            VERSION=$(node -e "const [a,b,c]='$VERSION'.split('.').map(Number);console.log(a+'.'+b+'.'+(c+1))")
+          done
+          npm version $VERSION --no-git-tag-version
+          npm publish --provenance --access public

package/README.md

@@ -1,6 +1,6 @@
 # Pulse
 
-**A spec-first, AI-native web framework.** Early access — v0.1.
+**A spec-first, AI-native web framework.** Early access — v0.1.30.
 
 Write a plain JavaScript object that describes what a page does. Pulse handles routing, SSR, hydration, client-side navigation, compression, security headers, and caching automatically.
 

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.28",
+  "version": "0.1.30",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",

package/public/pulse-ui.css

@@ -810,8 +810,8 @@ hr.ui-divider {
 }
 
 .ui-testimonial-avatar--initials {
-  background:      var(--ui-accent-dim, rgba(155,141,255,.12));
-  color:           var(--ui-accent, var(--accent, #9b8dff));
+  background:      var(--ui-muted-bg, rgba(128,128,128,.2));
+  color:           var(--ui-text, var(--text, #e2e2ea));
   font-size:       .8rem;
   font-weight:     700;
   display:         flex;

package/src/agent/guide-components.md

@@ -151,7 +151,7 @@ Use `prose()` for HTML from external sources (CMS, markdown). Use `heading()`/`l
 | `feature` | `icon` (HTML slot), `title`, `level` (1–6, default 3), `description`, `center` |
 | `testimonial` | `quote`, `name`, `role`, `src`, `rating` (1–5) |
 | `pricing` | `name`, `level` (1–6, default 3), `price`, `period`, `features` ([strings]), `action` (HTML slot), `highlighted` |
-| `accordion` | `items` ([{title,content}]) — native `<details>`, no JS |
+| `accordion` | `items` ([{question,answer}]) — native `<details>`, no JS |
 | `appBadge` | `store` (apple/google), `href` |
 | `cta` | `eyebrow`, `title`, `level` (1–6, default 2), `subtitle`, `actions` (HTML slot), `align` |
 

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.
@@ -67,6 +75,7 @@ export default {
 ## Key rules
 
 - view() returns an HTML string using template literals
+- **Component props are auto-escaped — pass literal strings, not HTML entities.** Use `'© 2026 Acme'` not `'© 2026 Acme'`. Use `'Pricing & Plans'` not `'Pricing & Plans'`. Passing HTML entities to component props double-escapes them (`&`, `©`) and shows raw entity text to the user.
 - data-event="mutationName" on buttons/elements — passes the DOM event to the mutation
 - data-event="change:mutationName" to fire on input change
 - data-action="actionName" on <form> elements only — submits pass FormData to the action

package/src/agent/guide-styles.md

@@ -73,7 +73,20 @@ All components use `--ui-font` (body) and `--ui-mono` (code). These resolve from
 
 ### Google Fonts
 
-Add the Google Fonts stylesheet URL **before** `pulse-ui.css` in `meta.styles`. Use `family=Name:wght@weights` and always include `&display=swap`.
+**Google Fonts requires CSP configuration** — the default CSP blocks external font and stylesheet sources. You must pass `csp` to `createServer`, otherwise the font will be blocked and the page will fail Lighthouse Best Practices:
+
+```js
+// server.js
+createServer(specs, {
+  port: 3000,
+  csp: {
+    'style-src':  ['https://fonts.googleapis.com'],
+    'font-src':   ['https://fonts.gstatic.com'],
+  },
+})
+```
+
+Then add the URL **before** `pulse-ui.css` in `meta.styles`. Use `family=Name:wght@weights` and always include `&display=swap`.
 
 ```js
 meta: {
@@ -90,6 +103,8 @@ Then in app.css:
 :root { --font: 'Inter', system-ui, sans-serif; }
 ```
 
+If you cannot modify `createServer` (e.g. the project uses auto-discovery), use a self-hosted font in `public/fonts/` with `@font-face` in `app.css` — no CSP changes needed.
+
 For multiple weights or italic variants, separate them with a semicolon in the URL:
 ```
 ?family=Inter:ital,wght@0,400;0,700;1,400&display=swap

package/src/agent/workflow.md

@@ -33,7 +33,7 @@ Wait for the user to confirm or adjust the plan before writing any code.
 
 ## Phase 3 — Build
 
-Write the spec and any related files (components, styles, tests skeleton). Follow the checklist in full. After each file is written, output a one-line status: `✓ Page written — validating...`
+Write the spec and any related files using the **Write tool** — not `pulse_create_page`. This shows the user a readable diff of the file content. After writing, call `pulse_create_page(name)` to validate the file you just wrote. After each file is written, output a one-line status: `✓ Page written — validating...`
 
 ---
 

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: