@invisibleloop/pulse 0.1.29 → 0.1.31

package/.github/workflows/publish.yml

@@ -23,12 +23,14 @@ jobs:
 
       - run: npm test
 
-      - name: Publish if version is new
+      - name: Bump patch version if already published, then publish
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: |
           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
+          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
+          echo "$VERSION" > public/.pulse-ui-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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.1.29",
+  "version": "0.1.31",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.1.17
+0.1.31

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-spec.md

@@ -75,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/mcp/server.js

@@ -233,25 +233,27 @@ server.registerTool(
 server.registerTool(
   'pulse_create_page',
   {
-    description: `Create a new page in the Pulse project. Filename determines route: home.js → /, about.js → /about.
+    description: `Validate and register a page spec that you have already written to disk with the Write tool.
 
-IMPORTANT: Always follow these rules when writing the spec content:
+Workflow — always in this order:
+1. Write the spec file to src/pages/<name>.js using the Write tool (user sees the diff)
+2. Call pulse_create_page with just the name to validate it
+
+Do NOT pass content here — write the file first, then call this tool.
+
+Rules for the spec you write:
 - Import Pulse UI components from '@invisibleloop/pulse/ui' — never write raw HTML for nav, hero, button, card, input, etc.
 - Include '/pulse-ui.css' in meta.styles whenever using any UI component
-- Use u- utility classes for spacing/layout (u-flex, u-flex-col, u-gap-4, u-mt-8, u-text-center, etc.) — never inline styles
-- Use var(--ui-*) CSS tokens in any custom CSS — never hardcode hex colours
+- Use u- utility classes for spacing/layout — never inline styles
+- Use var(--ui-*) CSS tokens for any colour — never hardcode hex values
 - onSuccess AND onError are both required in every action
 - Do NOT use data-event on text inputs — use FormData in onStart/run instead
 - Always export default spec`,
     inputSchema: {
-      name:    z.string().describe('Filename without extension, e.g. "about" or "blog/post"'),
-      content: z.string().describe('Complete JS spec — must export default a valid Pulse spec object'),
+      name: z.string().describe('Filename without extension, matching what you wrote — e.g. "about" or "blog/post"'),
     },
   },
-  async ({ name, content }) => {
-    const validation = await validateContent(content)
-    if (validation.content[0].text.startsWith('Invalid')) return validation
-
+  async ({ name }) => {
     const segments = name.replace(/\.js$/, '').split('/')
     const fullPath = path.join(PAGES_DIR, ...segments) + '.js'
 
@@ -259,11 +261,16 @@ IMPORTANT: Always follow these rules when writing the spec content:
       return text('Error: page name must not escape src/pages/')
     }
 
-    fs.mkdirSync(path.dirname(fullPath), { recursive: true })
-    fs.writeFileSync(fullPath, content, 'utf8')
+    if (!fs.existsSync(fullPath)) {
+      return text(`Error: ${path.relative(ROOT, fullPath)} does not exist — write the file with the Write tool first, then call pulse_create_page.`)
+    }
+
+    const content = fs.readFileSync(fullPath, 'utf8')
+    const validation = await validateContent(content)
+    if (validation.content[0].text.startsWith('Invalid')) return validation
 
     const route = derivedRouteFromName(name)
-    return text(`Created ${path.relative(ROOT, fullPath)} → route "${route}"`)
+    return text(`Validated ${path.relative(ROOT, fullPath)} → route "${route}"`)
   }
 )
 
@@ -685,10 +692,19 @@ server.registerTool(
 server.registerTool(
   'pulse_update',
   {
-    description: 'Re-copy pulse-ui.css, pulse-ui.js, and the agent checklist from the installed package into public/. Run after npm update @invisibleloop/pulse, or when visual output looks wrong and you suspect stale CSS.',
+    description: 'Install the latest @invisibleloop/pulse package, then re-copy pulse-ui.css, pulse-ui.js, and the agent checklist into public/. One command does the full upgrade.',
     inputSchema: {},
   },
-  () => {
+  async () => {
+    // 1. npm install latest
+    const { execSync } = await import('child_process')
+    try {
+      execSync('npm install @invisibleloop/pulse@latest', { cwd: ROOT, stdio: 'pipe' })
+    } catch (e) {
+      return text(`npm install failed:\n${e.stderr?.toString() || e.message}`)
+    }
+
+    // 2. Copy assets from the newly installed package
     const pkgPublic  = new URL('../../public', import.meta.url).pathname
     const publicDir  = path.join(ROOT, 'public')
     const assets     = ['pulse-ui.css', 'pulse-ui.js', '.pulse-ui-version']
@@ -711,7 +727,7 @@ server.registerTool(
 
     const versionFile = path.join(publicDir, '.pulse-ui-version')
     const version     = fs.existsSync(versionFile) ? fs.readFileSync(versionFile, 'utf8').trim() : '?'
-    return text(`pulse-ui updated to v${version}\n\n${updated.map(f => `✓ ${f}`).join('\n')}`)
+    return text(`Pulse updated to v${version}\n\n${updated.map(f => `✓ ${f}`).join('\n')}`)
   }
 )
 
@@ -826,7 +842,7 @@ const PULSE_GUIDE_INDEX = `# Pulse Framework Guide
 - \`pulse_list_structure\` — list pages, components, and pulse-ui version. Call at the start of every session.
 - \`pulse_validate\` — validate spec content. Call after every write. Fix all errors AND warnings.
 - \`pulse_review\` — switch into reviewer mode and critically examine a spec you just built. Returns the source, rendered HTML, validator output, and a full review checklist. **Call this only after validate, Lighthouse (desktop + mobile), and tests all pass — it is the final phase before declaring done.**
-- \`pulse_create_page\` — create a new page spec. Validates before writing.
+- \`pulse_create_page\` — validate a page spec you already wrote to disk. **Always write the file with the Write tool first, then call this.** Never pass content to this tool.
 - \`pulse_create_component\` — create a reusable component.
 - \`pulse_create_store\` — create the pulse.store.js global store.
 - \`pulse_create_action\` — generate a correctly-structured action snippet.
@@ -834,7 +850,7 @@ const PULSE_GUIDE_INDEX = `# Pulse Framework Guide
 - \`pulse_restart_server\` — stop and restart the dev server.
 - \`pulse_build\` — production build + starts prod server on devPort+1 for Lighthouse. Returns the URL. Call \`pulse_restart_server\` after to return to dev. **Slow — takes 30–60 s. Tell the user before calling.**
 - \`pulse_check_version\` — check installed package version, static asset version, and latest on npm. Use this instead of running npm commands when the user asks about updates.
-- \`pulse_update\` — re-copy \`pulse-ui.css\`, \`pulse-ui.js\`, and the agent checklist from the installed package into \`public/\`. Run this after \`npm update @invisibleloop/pulse\`, or whenever visual output looks wrong and you suspect stale CSS.
+- \`pulse_update\` — install the latest \`@invisibleloop/pulse\` package and re-copy \`pulse-ui.css\`, \`pulse-ui.js\`, and the agent checklist into \`public/\`. One command does the full upgrade.
 
 **Chrome DevTools MCP tools** (globally available):
 - \`mcp__chrome-devtools__take_screenshot\` — visual screenshot of the page.

package/src/server/index.js

@@ -16,7 +16,11 @@ import fs     from 'fs'
 import path   from 'path'
 import zlib   from 'zlib'
 import crypto from 'crypto'
-import { promisify } from 'util'
+import { promisify }  from 'util'
+import { createRequire } from 'module'
+
+const _require = createRequire(import.meta.url)
+export const version = _require('../../package.json').version
 import { renderToString, renderToStream, wrapDocument, resolveServerState } from '../runtime/ssr.js'
 import { validateSpec } from '../spec/schema.js'
 import { validateStore, resolveStoreState } from '../store/index.js'

package/src/ui/stat.js

@@ -39,7 +39,7 @@ export function stat({
 
   const changeHtml = change
     ? `<p class="ui-stat-change ui-stat-change--${e(trend)}">
-  <span aria-label="${e(TREND_LABELS[trend])}">${TREND_ICONS[trend]}</span>
+  <span role="img" aria-label="${e(TREND_LABELS[trend])}">${TREND_ICONS[trend]}</span>
   ${e(change)}
 </p>`
     : ''

package/src/ui/ui.test.js

@@ -346,6 +346,12 @@ test('stat: renders change with trend class', () => {
   assert.match(html, /\+5%/)
 })
 
+test('stat: trend icon span has role=img for valid aria-label', () => {
+  const html = stat({ label: 'X', value: '10', change: '+5%', trend: 'up' })
+  assert.match(html, /role="img"/)
+  assert.match(html, /aria-label="increase"/)
+})
+
 test('stat: no change rendered when change is empty', () => {
   const html = stat({ label: 'X', value: '10' })
   assert.doesNotMatch(html, /ui-stat-change/)

package/.claude/settings.local.json

@@ -1,113 +0,0 @@
-{
-  "permissions": {
-    "allow": [
-      "mcp__chrome-devtools__navigate_page",
-      "mcp__chrome-devtools__evaluate_script",
-      "Bash(grep:*)",
-      "mcp__chrome-devtools__list_console_messages",
-      "mcp__chrome-devtools__take_screenshot",
-      "Bash(pkill -f \"docs/server.js\")",
-      "Bash(curl -s -o /dev/null -w \"%{http_code}\" http://localhost:4000/)",
-      "Bash(node:*)",
-      "Bash(for f:*)",
-      "Bash(do echo:*)",
-      "Read(//Users/andy.stubbs/Repos/AS/pulse2/src/ui/**)",
-      "Bash(/dev/null done:*)",
-      "Bash(mkdir -p /Users/andy.stubbs/Repos/AS/agent-test/.claude)",
-      "Bash(mv /Users/andy.stubbs/Repos/AS/agent-test/CLAUDE.md /Users/andy.stubbs/Repos/AS/agent-test/.claude/CLAUDE.md)",
-      "Read(//Users/andy.stubbs/Repos/AS/agent-test-3/public/**)",
-      "Bash(ls /Users/andy.stubbs/Repos/AS/pulse2/public/*.css /Users/andy.stubbs/Repos/AS/pulse2/public/*.js)",
-      "Bash(cp /Users/andy.stubbs/Repos/AS/pulse2/public/pulse-ui.css /Users/andy.stubbs/Repos/AS/agent-test-3/public/pulse-ui.css)",
-      "Bash(cp /Users/andy.stubbs/Repos/AS/pulse2/public/pulse-ui.js /Users/andy.stubbs/Repos/AS/agent-test-3/public/pulse-ui.js)",
-      "Bash(cp /Users/andy.stubbs/Repos/AS/pulse2/public/pulse-ui.css /Users/andy.stubbs/Repos/AS/agent-test/public/pulse-ui.css)",
-      "Bash(cp /Users/andy.stubbs/Repos/AS/pulse2/public/pulse-ui.css /Users/andy.stubbs/Repos/AS/my-amazing-pulse-project/public/pulse-ui.css)",
-      "Bash(npm test:*)",
-      "Bash(npm run:*)",
-      "Bash(git config:*)",
-      "Bash(curl -s -o /dev/null -w \"%{http_code}\" http://localhost:4000)",
-      "Bash(curl:*)",
-      "Bash(xargs kill:*)",
-      "mcp__chrome-devtools__lighthouse_audit",
-      "Bash(git add:*)",
-      "Bash(git commit:*)",
-      "Bash(git push:*)",
-      "Bash(git pull:*)",
-      "Bash(git stash:*)",
-      "Bash(__NEW_LINE_9ac7abf2e7b711bb__ node -e \":*)",
-      "Bash(python3:*)",
-      "mcp__chrome-devtools__list_pages",
-      "mcp__chrome-devtools__emulate",
-      "Bash(npx tsc:*)",
-      "Bash(find /Users/andy.stubbs/.claude -name *.json)",
-      "Bash(ls /Users/andy.stubbs/Repos/AS/pulse2/src/**/*.test.js)",
-      "mcp__chrome-devtools__list_network_requests",
-      "mcp__chrome-devtools__get_network_request",
-      "Bash(find /Users/andy.stubbs/Repos/AS/forge -name *.md -o -name *.txt)",
-      "Bash(node_modules/.bin/tsc --noEmit)",
-      "Bash(/Users/andy.stubbs/Repos/AS/forge/node_modules/.bin/tsc --noEmit --project /Users/andy.stubbs/Repos/AS/forge/tsconfig.json)",
-      "WebFetch(domain:localhost)",
-      "Skill(update-config)",
-      "Bash(jq:*)",
-      "Bash(ls /Users/andy.stubbs/Repos/AS/tasty/.claude/ grep -r \"pulse-dev\\\\|pulse-stop\\\\|pulse-build\\\\|pulse-start\\\\|Pulse project\" /Users/andy.stubbs/Repos/AS/tasty/.claude/ 2)",
-      "Bash(/dev/null grep:*)",
-      "Bash(ls -1 /Users/andy.stubbs/Repos/AS/pulse2/src/ui/*.js)",
-      "Bash(ls /Users/andy.stubbs/Repos/AS/pulse2/docs/src/pages/*.js)",
-      "Bash(wc -c /Users/andy.stubbs/Repos/AS/pulse2/src/agent/guide-*.md)",
-      "Bash(npx:*)",
-      "Bash(npm install:*)",
-      "Bash(./node_modules/.bin/tsc --noEmit --strict --moduleResolution bundler --module esnext --target esnext --allowJs false --skipLibCheck false types/schema.d.ts types/server.d.ts types/runtime.d.ts types/navigate.d.ts types/ssr.d.ts types/html.d.ts types/image.d.ts types/ui.d.ts types/index.d.ts 2>&1)",
-      "Bash(./node_modules/.bin/tsc --noEmit --strict --moduleResolution bundler --module esnext --target esnext --allowJs false --lib esnext,dom types/schema.d.ts types/server.d.ts types/runtime.d.ts types/navigate.d.ts types/ssr.d.ts types/html.d.ts types/image.d.ts types/ui.d.ts types/index.d.ts 2>&1)",
-      "Bash(/Users/andy.stubbs/Repos/AS/pulse2/node_modules/.bin/tsc -p /tmp/tsconfig_test.json 2>&1)",
-      "Bash(find /Users/andy.stubbs/Repos/AS/pulse2 -name *.test.js -type f)",
-      "Bash(wc:*)",
-      "Bash(ls -1 *.js)",
-      "Bash(grep -l \"<h[2-6]\" /Users/andy.stubbs/Repos/AS/pulse2/src/ui/*.js)",
-      "Bash(node --input-type=module --eval \"import ''''/Users/andy.stubbs/Repos/AS/pulse2/src/cli/scaffold.js''''\")",
-      "Bash(head -10 grep -n \"level\\\\|heading\" /Users/andy.stubbs/Repos/AS/pulse2/docs/src/pages/components/section.js)",
-      "Bash(head -10 grep -n \"level\\\\|heading\" /Users/andy.stubbs/Repos/AS/pulse2/docs/src/pages/components/modal.js)",
-      "Bash(head -10 grep -n \"table\\(\\\\|''''Prop''''\\\\|flush\\\\|center\\\\|highlighted\\\\|eyebrow\\\\|align\\\\|size.*md\\\\|ui-modal\" /Users/andy.stubbs/Repos/AS/pulse2/docs/src/pages/components/modal.js)",
-      "Bash(head -10 grep -n \"table\\(\\\\|''''Prop''''\\\\|eyebrow\\\\|padding\\\\|variant\\\\|subtitle\" /Users/andy.stubbs/Repos/AS/pulse2/docs/src/pages/components/section.js)",
-      "Bash(head -10 grep -n \"table\\(\\\\|''''Prop''''\\\\|highlighted\\\\|badge\\\\|period\\\\|features\" /Users/andy.stubbs/Repos/AS/pulse2/docs/src/pages/components/pricing.js)",
-      "Bash(head -10 grep -n \"table\\(\\\\|''''Prop''''\\\\|eyebrow\\\\|subtitle\\\\|actions\\\\|align\" /Users/andy.stubbs/Repos/AS/pulse2/docs/src/pages/components/cta.js)",
-      "Bash(echo \"exit: $?\")",
-      "Bash(xargs node:*)",
-      "Bash(find /Users/andy.stubbs/Repos/AS/ultimate-demo/twizzer -name server.js -o -name *.config.*)",
-      "Bash(xargs ls:*)",
-      "Bash(xargs -I{} lsof -p {})",
-      "Bash(brotli --best -c /Users/andy.stubbs/Repos/AS/ultimate-demo/twizzer/public/dist/home.boot-TJOPUIR4.js)",
-      "WebSearch",
-      "WebFetch(domain:github.com)",
-      "Bash(ls:*)",
-      "Bash(git -C /Users/andy.stubbs/Repos/AS/pulse2 log --follow --diff-filter=A --format=\"%ar\" -- public/dist/runtime-YLZ4ZGK4.js)",
-      "Read(//Users/andy.stubbs/Repos/AS/pulse2/**)",
-      "Bash(GetFileInfo /Users/andy.stubbs/Repos/AS/pulse2/public/dist/runtime-YLZ4ZGK4.js)",
-      "mcp__chrome-devtools__performance_start_trace",
-      "Bash(pkill -f docs/server.js)",
-      "Bash(sleep 1 node -e \":*)",
-      "mcp__chrome-devtools__close_page",
-      "mcp__chrome-devtools__fill",
-      "mcp__chrome-devtools__click",
-      "mcp__chrome-devtools__take_snapshot",
-      "mcp__chrome-devtools__type_text",
-      "Bash(head -5 grep -n \"section\\\\|container\" /Users/andy.stubbs/Repos/AS/pulse2/src/ui/index.js)",
-      "Bash(head -35 grep \"ui-section-header\\\\|ui-section-title\\\\|ui-section-eyebrow\\\\|ui-section--\" /Users/andy.stubbs/Repos/AS/pulse2/public/pulse-ui.css)",
-      "mcp__chrome-devtools__performance_analyze_insight",
-      "Bash(git checkout:*)",
-      "Bash(git branch:*)",
-      "Bash(gh run:*)",
-      "Bash(xargs -I{} gh run delete {} --repo invisibleloop/pulse-framework)",
-      "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:*)"
-    ]
-  }
-}