@invisibleloop/pulse 0.20.57 → 0.20.59

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@invisibleloop/pulse",
-  "version": "0.20.57",
+  "version": "0.20.59",
   "type": "module",
   "description": "AI-first frontend framework. The spec is the source of truth.",
   "license": "MIT",
@@ -76,7 +76,7 @@
   "scripts": {
     "dev": "node --watch src/cli/dev.js",
     "build": "node scripts/build.js",
-    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/cli/validate.test.js && node src/cli/diagnose.test.js && node src/cli/check-bundles.test.js && node src/cli/review.test.js && node src/cli/process-utils.test.js && node src/cli/stamp.test.js && node src/cli/feedback.test.js && node src/cli/update.test.js && node src/cli/dev-host.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node scripts/css-purge.test.js && node scripts/release-version.test.js && node src/mcp/mcp.test.js && node src/mcp/guards.test.js",
+    "test": "node src/spec/schema.test.js && node src/runtime/runtime.test.js && node src/runtime/navigate.test.js && node src/runtime/morph.test.js && node src/runtime/ssr.test.js && node src/runtime/image.test.js && node src/server/server.test.js && node src/cli/cli.test.js && node src/cli/validate.test.js && node src/cli/diagnose.test.js && node src/cli/check-bundles.test.js && node src/cli/review.test.js && node src/cli/process-utils.test.js && node src/cli/stamp.test.js && node src/cli/feedback.test.js && node src/cli/update.test.js && node src/cli/dev-host.test.js && node src/cli/dev-reload.test.js && node src/ui/ui.test.js && node src/testing/testing.test.js && node src/store/store.test.js && node src/md/md.test.js && node scripts/strip-server.test.js && node scripts/css-purge.test.js && node scripts/release-version.test.js && node src/mcp/mcp.test.js && node src/mcp/guards.test.js",
     "typecheck": "tsc --noEmit",
     "docs": "node --watch src/cli/dev.js --root ../../docs --port 4000",
     "docs:start": "node ../../docs/server.js"

package/public/.pulse-ui-version

@@ -1 +1 @@
-0.20.57
+0.20.59

package/public/pulse-ui.css

@@ -3026,3 +3026,9 @@ fieldset[disabled] .ui-rating-stars .ui-rating-star:hover ~ .ui-rating-star { co
   line-height: 0;
 }
 
+/* ─── Framework skip link ───────────────────────────────────────────────────
+ * Injected by the server's buffered render path (404s, POST re-renders, stream: false).
+ * Hidden until keyboard focus, like the one in pulse.css — pages that load only
+ * pulse-ui.css must not see it as a plain link at the top of the page. */
+.pulse-skip-link{position:absolute;left:-9999px;top:auto;width:1px;height:1px;overflow:hidden}
+.pulse-skip-link:focus{position:fixed;left:1rem;top:1rem;width:auto;height:auto;padding:.5rem 1rem;background:#000;color:#fff;font-size:1rem;font-weight:600;border-radius:4px;text-decoration:none;z-index:9999;outline:3px solid #fff;outline-offset:2px}

package/scripts/css-purge.js

@@ -9,8 +9,13 @@
 // CSS class extractor
 // ---------------------------------------------------------------------------
 
+// Classes the framework itself writes into the document (src/runtime/ssr.js wrapDocument),
+// outside any page's view, so nothing the build scans ever contains them. Always kept:
+// without this a built app loses the rules that hide the injected skip link (#161).
+export const FRAMEWORK_INJECTED_CLASSES = ['pulse-skip-link']
+
 export function extractUsedClasses(htmlContents, jsContents, safelist = []) {
-  const used = new Set()
+  const used = new Set(FRAMEWORK_INJECTED_CLASSES)
 
   // Extract from class="..." in rendered HTML (no template expressions to worry about)
   for (const content of htmlContents) {

package/src/cli/dev.js

@@ -10,6 +10,8 @@
 
 import path    from 'path'
 import fs      from 'fs'
+import { register } from 'node:module'
+import { pathToFileURL } from 'node:url'
 import { createServer } from '../server/index.js'
 import { loadPages, loadStore } from './discover.js'
 import * as log         from './logger.js'
@@ -31,6 +33,14 @@ const ROOT = rootArg !== -1
 // resolve to the project root, not wherever the parent process was launched from.
 if (process.cwd() !== ROOT) process.chdir(ROOT)
 
+// Hot reload re-imports each page with a cache-busting stamp; this hook passes the stamp on
+// to the project modules the page imports, so editing src/lib or src/components takes
+// effect too (see reload-hooks.js). realpath: Node reports resolved URLs without symlinks.
+register('./reload-hooks.js', {
+  parentURL: import.meta.url,
+  data: { rootUrl: pathToFileURL(fs.realpathSync(ROOT)).href + '/' },
+})
+
 let _config = {}
 const configPath = path.join(ROOT, 'pulse.config.js')
 if (fs.existsSync(configPath)) {

package/src/cli/discover.js

@@ -14,6 +14,7 @@
 
 import fs   from 'fs'
 import path from 'path'
+import { pathToFileURL } from 'url'
 
 /**
  * Derive a route from a file path relative to the pages directory.
@@ -136,7 +137,7 @@ export async function loadStore(projectRoot, cacheBust = null) {
   const storePath = path.join(projectRoot, 'pulse.store.js')
   if (!fs.existsSync(storePath)) return null
 
-  const url = 'file://' + storePath + (cacheBust ? `?t=${cacheBust}` : '')
+  const url = pathToFileURL(storePath).href + (cacheBust ? `?t=${cacheBust}` : '')
   const mod = await import(url)
   const def = mod.default
   if (!def || typeof def !== 'object') {

package/src/cli/reload-hooks.js

@@ -0,0 +1,35 @@
+/**
+ * Pulse — module-loader hook for dev hot reload
+ *
+ * `pulse dev` re-imports each page with `?t=<stamp>` to dodge Node's ESM cache, but that
+ * only refreshes the page file: everything the page imports (src/lib, src/components, ...)
+ * resolves to the same URL as before and comes back stale from the cache. This hook gives
+ * a project module imported by a stamped module the same stamp, so the whole project
+ * graph is re-evaluated on a reload.
+ *
+ * Only the project's own files are stamped. Anything in node_modules, the framework
+ * itself, and `node:` builtins keep their URL, so packages (and framework singletons)
+ * are evaluated once rather than once per edit.
+ *
+ * Limits: CommonJS files (.cjs) are cached by path, so the stamp cannot refresh them, and
+ * modules outside the project root (e.g. a sibling workspace package) are neither stamped
+ * nor watched.
+ */
+
+let rootUrl = ''
+
+export function initialize(data) {
+  rootUrl = data.rootUrl
+}
+
+export async function resolve(specifier, context, nextResolve) {
+  const result = await nextResolve(specifier, context)
+  const url = result.url
+  if (!rootUrl || !url.startsWith(rootUrl) || url.includes('?')) return result
+  if (url.slice(rootUrl.length).includes('node_modules/')) return result // below the root: a project may itself live under a node_modules folder
+  if (!context.parentURL?.startsWith(rootUrl)) return result
+
+  const stamp = new URL(context.parentURL).searchParams.get('t')
+  if (!stamp || !/^\d+$/.test(stamp)) return result
+  return { ...result, url: `${url}?t=${stamp}` }
+}

package/src/cli/scaffold.archive.js

@@ -605,7 +605,7 @@ Rules:
 Every page must be fully navigable by keyboard alone.
 
 **Structure**
-- Wrap page content in \`<main id="main-content">\` — the skip link injected by the framework targets this id
+- Wrap page content in \`<main id="main-content">\` — a skip link targets this id (add your own to the layout; the framework only injects a fallback on 404s and form re-renders)
 - Use semantic elements: \`<nav>\`, \`<main>\`, \`<header>\`, \`<footer>\`, \`<section>\`, \`<article>\`, \`<aside>\`
 - One \`<h1>\` per page — the primary heading that describes the current page
 
@@ -896,7 +896,7 @@ Threshold merge order: **global config → environment override → per-route ov
 - **Redirect loops** — if \`/dashboard\` guards redirect to \`/login\`, and \`/login\` guards redirect authenticated users to \`/dashboard\`, test both directions to confirm there is no loop.
 
 ### Performance & Lighthouse
-- **Missing \`<main id="main-content">\`** — the framework injects a skip link targeting \`#main-content\` on every page. A missing element breaks the skip link and fails Lighthouse Accessibility.
+- **Missing \`<main id="main-content">\`** — skip links target \`#main-content\`. A missing element breaks the skip link and fails Lighthouse Accessibility.
 - **Multiple \`<h1>\` elements** — one \`<h1>\` per page. Multiple at the same level fail Lighthouse Accessibility.
 - **Images without \`width\` and \`height\`** — omitting dimensions prevents the browser from reserving space, causing layout shift and a non-zero CLS. Always provide both.
 - **Colour contrast** — \`#888\` on \`#111\` is the practical minimum for muted text that passes WCAG AA. Lighter greys will fail. Check new colour tokens before committing.
@@ -909,7 +909,7 @@ Threshold merge order: **global config → environment override → per-route ov
 ## Rules the agent must follow
 
 - **Never set \`hydrate\`** — the framework sets it automatically.
-- **Always wrap page content in \`<main id="main-content">\`** — the framework injects a skip link targeting this id on every page.
+- **Always wrap page content in \`<main id="main-content">\`** — skip links target this id.
 - **Never use \`data-event\` on text inputs** to mirror value into state. It destroys focus on every keystroke. Use uncontrolled inputs and read values from \`FormData\` in \`action.onStart\` instead. For client-side filtering/search, render all items in the HTML and use an inline \`<script>\` to show/hide elements — no state or re-render needed.
 - **Never add \`<script>\` tags manually** — hydration is handled by the framework.
 - **Never add external npm packages** for client-side behaviour — express it in the spec.

package/src/runtime/ssr.js

@@ -343,6 +343,10 @@ export function wrapDocument({ content, spec = {}, serverState = {}, storeState
   const meta  = spec.meta  || {}
   const title = meta.title || 'Pulse'
 
+  // The fallback skip link is only for pages that have none: a page (or its layout) that
+  // already links to #main-content supplies its own, and two would be a redundant tab stop.
+  const ownSkipLink = /href=["']#main-content["']/.test(content)
+
   const bodyAttr = [
     meta.theme ? `data-theme="${esc(meta.theme)}"` : '',
     meta.vibe  ? `data-vibe="${esc(meta.vibe)}"` : '',
@@ -419,7 +423,7 @@ export function wrapDocument({ content, spec = {}, serverState = {}, storeState
   ${schemaScript}
 </head>
 <body${bodyAttr}>
-  <a href="#main-content" class="pulse-skip-link">Skip to main content</a>
+  ${ownSkipLink ? '' : '<a href="#main-content" class="pulse-skip-link">Skip to main content</a>'}
   <div id="pulse-root">
     ${content}
   </div>