@invisibleloop/pulse 0.17.0 → 0.17.2

package/src/mcp/mcp.test.js

@@ -152,14 +152,19 @@ const agentDocs = [
   '.claude/commands/verify.md',
   '.claude/commands/new-doc-page.md',
   'CLAUDE.md',
+  'README.md',
 ]
 
 test('no agent doc states a four-score Lighthouse bar (100/100/100/100)', () => {
+  const fourScore = (src) =>
+    src.includes('100/100/100/100') ||
+    /all four (scores|categories)/i.test(src) ||
+    /Accessibility, Best Practices, SEO,? and Performance[^.\n]*must (all )?be 100/i.test(src)
   const offenders = agentDocs.filter(f =>
     fs.existsSync(path.join(ROOT, f)) &&
-    fs.readFileSync(path.join(ROOT, f), 'utf8').includes('100/100/100/100')
+    fourScore(fs.readFileSync(path.join(ROOT, f), 'utf8'))
   )
-  if (serverSrc.includes('100/100/100/100')) offenders.push('src/mcp/server.js')
+  if (fourScore(serverSrc)) offenders.push('src/mcp/server.js')
   assert(
     offenders.length === 0,
     `Four-score Lighthouse bar found in: ${offenders.join(', ')}. ` +
@@ -204,6 +209,115 @@ test('workflow.md Mode B instructs writing the creative-override spec comment',
   )
 })
 
+test('checklist points cross-spec shared components at src/components/, not src/ui/', () => {
+  const checklist = fs.readFileSync(path.join(agentDir, 'checklist.md'), 'utf8')
+  assert(
+    !/shared component in `src\/ui\/`/.test(checklist),
+    'checklist.md tells the agent to create shared components in src/ui/ — that is the ' +
+    'framework\'s own library inside the package. Project-level shared code goes in src/components/.'
+  )
+  assert(
+    /shared component in `src\/components\/`/.test(checklist),
+    'checklist.md must direct cross-spec shared components to src/components/.'
+  )
+})
+
+test('guide-spec.md states the one-spec-per-page mental model', () => {
+  const guideSpec = fs.readFileSync(path.join(agentDir, 'guide-spec.md'), 'utf8')
+  assert(
+    /one spec per page/i.test(guideSpec) && /dynamic route is still one spec/i.test(guideSpec),
+    'guide-spec.md must state the mental model explicitly: one spec = one route = one file, ' +
+    'and a dynamic route is still one spec serving many URLs.'
+  )
+})
+
+test('approval pause mechanism is wired end to end', () => {
+  // The design-approval gate requires the agent to end its turn and wait for the
+  // user — but the scaffolded Stop hooks block any turn ending with unverified
+  // edits. Without an escape hatch the hooks steamroll the approval gate (the
+  // agent gets blocked, reads "Run /verify", and proceeds without an answer).
+  const scaffoldSrc = fs.readFileSync(path.join(ROOT, 'src/cli/scaffold.js'), 'utf8')
+  const coverageSrc = fs.readFileSync(path.join(agentDir, 'coverage-check.js'), 'utf8')
+  const workflow    = fs.readFileSync(path.join(agentDir, 'workflow.md'), 'utf8')
+
+  // 1. The MCP server must expose the tool that writes the marker
+  assert(/registerTool\(\s*'pulse_await_approval'/.test(serverSrc),
+    'server.js must register pulse_await_approval')
+
+  // 2. Every inline Stop hook in the scaffold must early-exit on the marker
+  const stopHookCount   = (scaffoldSrc.match(/decision:'block'/g) || []).length
+  const markerCheckCount = (scaffoldSrc.match(/\.pulse-awaiting-approval'\)\)process\.exit\(0\)/g) || []).length
+  assert(stopHookCount >= 2 && markerCheckCount >= stopHookCount,
+    `scaffold.js has ${stopHookCount} blocking Stop hooks but only ${markerCheckCount} check ` +
+    `.pulse-awaiting-approval — every blocking Stop hook must allow the approval pause.`)
+
+  // 3. coverage-check.js (the third Stop hook) must early-exit on the marker
+  assert(coverageSrc.includes('.pulse-awaiting-approval'),
+    'coverage-check.js must early-exit when .pulse-awaiting-approval exists')
+
+  // 4. The marker must be consumed when the user replies — one turn-end only
+  assert(/UserPromptSubmit/.test(scaffoldSrc) && /unlinkSync\('\.pulse-awaiting-approval'\)/.test(scaffoldSrc),
+    'scaffold.js must register a UserPromptSubmit hook that deletes .pulse-awaiting-approval')
+
+  // 5. The workflow must teach the mechanism at the design-approval gate
+  assert(workflow.includes('pulse_await_approval'),
+    'workflow.md Phase 5a must explain how to pause: always pulse_await_approval before asking')
+
+  // 6. No doc may claim a host question tool avoids ending the turn — field
+  //    testing showed AskUserQuestion in Claude Code still ends the turn and
+  //    fires the Stop hooks. The safe instruction is: always write the marker
+  //    first, regardless of how the question is asked.
+  const claimDocs = agentDocs.filter(f =>
+    fs.existsSync(path.join(ROOT, f)) &&
+    /without ending the turn/i.test(fs.readFileSync(path.join(ROOT, f), 'utf8'))
+  )
+  if (/without ending the turn.*Stop hooks never fire/is.test(serverSrc)) claimDocs.push('src/mcp/server.js')
+  assert(claimDocs.length === 0,
+    `These docs claim a question tool avoids ending the turn (empirically false in Claude Code): ${claimDocs.join(', ')}. ` +
+    `Instruct: always call pulse_await_approval before asking, whichever way the question is asked.`)
+})
+
+test('pulse_check_contrast extracts variables from [data-theme="light"] blocks', () => {
+  // Regression: the light-theme block pattern was an ungrouped alternation
+  // (a|b) + '\\s*\\{([^}]+)\\}' — the body matcher bound only to the second
+  // alternative, so [data-theme="light"] blocks matched with no body capture
+  // and the checker silently reported nothing for the light theme.
+  // Recreate extractVars with the exact pattern strings from server.js source.
+  const patterns = [...serverSrc.matchAll(/extractVars\(source,\s*'((?:[^'\\]|\\.)*)'\)/g)].map(m =>
+    m[1].replace(/\\\\/g, '\\').replace(/\\'/g, "'")
+  )
+  assert(patterns.length === 2, `Expected 2 extractVars call patterns in server.js, found ${patterns.length}`)
+  const lightPattern = patterns.find(p => p.includes('data-theme'))
+  assert(lightPattern, 'No data-theme pattern found in extractVars calls')
+
+  const sampleCss = `:root { --accent: #112233; }\n[data-theme="light"] { --accent: #445566; --bg: #ffffff; }`
+  const blockRegex = new RegExp(lightPattern + '\\s*\\{([^}]+)\\}', 'gi')
+  const m = blockRegex.exec(sampleCss)
+  assert(m && m[1] && m[1].includes('--accent'),
+    `The light-theme block pattern in pulse_check_contrast fails to capture the block body. ` +
+    `Pattern: ${lightPattern} — alternations must be wrapped in (?:...).`)
+})
+
+test('dark theme default is declared at every spec-writing entry point', () => {
+  // Agents repeatedly assumed the default theme is light, built the page, then
+  // discovered dark at the screenshot — costing an edit → restart → re-approval
+  // cycle. The dark default must be stated wherever a spec is first written:
+  // the spec skeleton, the plan/build brief, and the checklist.
+  const guideSpec = fs.readFileSync(path.join(agentDir, 'guide-spec.md'), 'utf8')
+  const workflow  = fs.readFileSync(path.join(agentDir, 'workflow.md'), 'utf8')
+  const checklist = fs.readFileSync(path.join(agentDir, 'checklist.md'), 'utf8')
+  const claudeMd  = fs.readFileSync(path.join(ROOT, 'CLAUDE.md'), 'utf8')
+
+  assert(/theme:/.test(guideSpec) && /DEFAULT IS DARK/i.test(guideSpec),
+    'guide-spec.md meta skeleton must include the theme field with the dark-default warning')
+  assert(/Theme:\s+light \| dark/.test(workflow),
+    'workflow.md build brief template must include a Theme line')
+  assert(/default theme is DARK/i.test(checklist),
+    'checklist.md Critical section must state the dark default')
+  assert(/theme:\s+'light'/.test(claudeMd) && /default is DARK/i.test(claudeMd),
+    'CLAUDE.md spec meta block must show theme with the dark-default warning')
+})
+
 test('identity.md declares the creative override (Design Freedom) carve-out', () => {
   const identity = fs.readFileSync(path.join(agentDir, 'identity.md'), 'utf8')
   assert(

package/src/mcp/server.js

@@ -1203,6 +1203,33 @@ The stop hook compares each changed spec's mtime against this stamp. Any spec ne
   }
 )
 
+// ---------------------------------------------------------------------------
+// pulse_await_approval
+// ---------------------------------------------------------------------------
+
+server.registerTool(
+  'pulse_await_approval',
+  {
+    description: `Pause the workflow to wait for the user's answer — call this immediately BEFORE asking a blocking question (e.g. the design-approval gate: "Happy with the layout and direction…?").
+
+It writes a .pulse-awaiting-approval marker that tells the Stop hooks (missing tests, coverage, verify stamp) to let the turn end without demanding /verify first. The marker is deleted automatically when the user sends their next message — the gates return in full force for your following turn.
+
+**Always call this before the approval question, regardless of how you ask.** In some hosts (including Claude Code) even a dedicated question tool like AskUserQuestion ends the turn, which fires the Stop hooks. The marker is harmless if the turn does not end — it is simply consumed when the user replies. Calling it first works in every host; relying on the question tool to keep the turn open does not.
+
+Do NOT use this to skip verification — it buys exactly one turn-end, paired with a question the user must answer. Calling it without asking anything just delays the gates by one message.`,
+    inputSchema: {},
+  },
+  () => {
+    const markerPath = path.join(ROOT, '.pulse-awaiting-approval')
+    try {
+      fs.writeFileSync(markerPath, String(Math.floor(Date.now() / 1000)), 'utf8')
+      return text('✓ Awaiting-approval marker written. Ask the user your question and end your turn — the Stop hooks will allow it. The marker is cleared when the user replies.')
+    } catch (err) {
+      return text(`Error writing .pulse-awaiting-approval: ${err.message}\nFallback: run \`touch .pulse-awaiting-approval\` in Bash, then ask your question.`)
+    }
+  }
+)
+
 // ---------------------------------------------------------------------------
 // pulse_run_tests
 // ---------------------------------------------------------------------------
@@ -2072,6 +2099,7 @@ Returns observations grouped by category: completeness, data flow, components, s
       if (!content.includes('title:'))       quickWins.push('`meta.title` is missing — every page needs a unique title.')
       if (!content.includes('description:')) quickWins.push('`meta.description` is missing — used for SEO and social previews.')
       if (!content.includes('styles:'))      quickWins.push('`meta.styles` not set — add `[\'/pulse-ui.css\']` if you are using any UI components.')
+      if (!content.includes('theme:'))       quickWins.push('`meta.theme` not set — Pulse renders DARK by default. If this design is light, add `theme: \'light\'` now rather than discovering a dark page at the screenshot.')
     }
 
     // --- Export ---
@@ -2405,7 +2433,7 @@ Accepts antiStyle ("what should this NOT look like?") and inspiration (a site or
       targetUser: z.string().optional().describe('Who this is for — shapes copy tone. E.g. "busy professionals", "indie developers", "home cooks"'),
       palette:    z.string().optional().describe('Brand colours as hex values, comma-separated. E.g. "#6366f1, #f8fafc, #1e1b4b". Used for early contrast check.'),
       font:       z.string().optional().describe('Brand font name, or omit for system-ui'),
-      theme:      z.enum(['light', 'dark']).optional().describe('Colour theme preference'),
+      theme:      z.enum(['light', 'dark']).optional().describe('Colour theme — ALWAYS ask the user for this; Pulse renders DARK when meta.theme is unset, so an unstated light design ships dark and costs a rework cycle. Pass the answer through to meta.theme in the spec.'),
       vibe:       z.enum(['warm', 'editorial', 'playful', 'minimal', 'bold', 'brutalist', 'retro', 'corporate', 'neon', 'paper']).optional().describe('Visual personality — see pulse://guide/design-references for full descriptions. warm (rounded, inviting), editorial (serif, sharp), playful (very rounded), minimal (clean), bold (impact headings), brutalist (zero radius, raw), retro (slab serif, nostalgic), corporate (conservative), neon (monospace, futuristic), paper (organic, serif, journal)'),
       styleNotes: z.string().optional().describe('Free-form style direction — e.g. "like a print poster", "market stall chalkboard feel", "clinical and professional"'),
       antiStyle:  z.string().optional().describe('"What should this NOT look like?" — negative aesthetic constraint. E.g. "not corporate SaaS", "not another Vercel dark card page", "not a startup landing page". Used to steer component and layout choices away from over-used patterns.'),
@@ -2970,6 +2998,78 @@ Returns tokens grouped by category.`,
   }
 )
 
+server.registerTool(
+  'pulse_check_csp',
+  {
+    description: `Resolve the redirect chains of external asset URLs (images, fonts, stylesheets) and return the complete set of origins your CSP must allow — as ready-to-paste config.
+
+Many asset hosts redirect to a CDN origin (picsum.photos → fastly.picsum.photos): allowing only the URL you wrote still blocks the actual bytes, and the browser error names the CDN origin, which is confusing to debug. This tool follows each redirect chain (up to 5 hops) and reports every origin involved.
+
+Call it with the external URLs you plan to use, before your first Lighthouse run. Suggested directive: img-src for images, font-src for font files, style-src for stylesheets.`,
+    inputSchema: {
+      urls:      z.array(z.string()).describe('External asset URLs to check, e.g. ["https://picsum.photos/id/10/1200/600"]'),
+      directive: z.string().optional().describe("CSP directive these assets belong to (default: 'img-src')"),
+    },
+  },
+  async ({ urls, directive = 'img-src' }) => {
+    const MAX_HOPS = 5
+    const origins  = new Set()
+    const lines    = []
+
+    for (const rawUrl of urls.slice(0, 10)) {
+      let url
+      try { url = new URL(rawUrl) } catch { lines.push(`✗ ${rawUrl} — not a valid URL`); continue }
+
+      const chain = [url.origin]
+      let blocked = null
+      try {
+        for (let hop = 0; hop < MAX_HOPS; hop++) {
+          const res = await fetch(url, { method: 'HEAD', redirect: 'manual', signal: AbortSignal.timeout(5000) })
+          if (res.status >= 300 && res.status < 400 && res.headers.get('location')) {
+            url = new URL(res.headers.get('location'), url)
+            chain.push(url.origin)
+            continue
+          }
+          if (res.status === 405) {
+            // Host rejects HEAD — confirm with a ranged GET so we still see redirects
+            const get = await fetch(url, { method: 'GET', redirect: 'manual', headers: { Range: 'bytes=0-0' }, signal: AbortSignal.timeout(5000) })
+            if (get.status >= 300 && get.status < 400 && get.headers.get('location')) {
+              url = new URL(get.headers.get('location'), url)
+              chain.push(url.origin)
+              continue
+            }
+          }
+          break
+        }
+      } catch (err) {
+        blocked = err?.name === 'TimeoutError' ? 'timed out' : (err?.message || 'request failed')
+      }
+
+      const uniqueChain = [...new Set(chain)]
+      for (const o of uniqueChain) origins.add(o)
+      lines.push(
+        blocked
+          ? `⚠ ${rawUrl} — ${blocked}; allowing origin from the URL only: ${uniqueChain.join(' → ')}`
+          : uniqueChain.length > 1
+            ? `↪ ${rawUrl} — redirects: ${uniqueChain.join(' → ')} (allow ALL of these)`
+            : `✓ ${rawUrl} — no redirect, origin: ${uniqueChain[0]}`
+      )
+    }
+
+    const config = [...origins].map(o => `'${o}'`).join(', ')
+    lines.push('')
+    lines.push('Ready to paste:')
+    lines.push('```js')
+    lines.push(`csp: {`)
+    lines.push(`  '${directive}': [${[...origins].map(o => `'${o}'`).join(', ')}],`)
+    lines.push(`}`)
+    lines.push('```')
+    if (config.includes('http://')) lines.push('⚠ An origin resolved to plain http: — use https URLs in production.')
+
+    return text(lines.join('\n'))
+  }
+)
+
 server.registerTool(
   'pulse_check_contrast',
   {
@@ -3009,8 +3109,12 @@ Run this immediately after writing a theme file — before production build and
       return vars
     }
 
+    // NOTE: alternations must be wrapped in a non-capturing group. An ungrouped
+    // pattern (a|b) followed by '\\s*\\{...' binds the body matcher to the second
+    // alternative only — [data-theme="light"] blocks then match the selector
+    // alone with no body capture, silently returning zero variables.
     const rootVars  = extractVars(source, ':root')
-    const lightVars = extractVars(source, '\\[data-theme=["\']light["\']\\]|[.]ui-theme-light')
+    const lightVars = extractVars(source, '(?:\\[data-theme=["\']light["\']\\]|[.]ui-theme-light)')
 
     // pulse-ui.css maps --NAME → --ui-NAME (e.g. --accent → --ui-accent).
     // Theme files written per the guide define bare --* tokens. Synthesize the

package/src/ui/drop-cap.js

@@ -24,6 +24,6 @@ export function dropCap({
   const classes = ['ui-drop-cap', cls].filter(Boolean).join(' ')
   
   return `<p class="${e(classes)}">
-  <span class="ui-drop-cap-letter" style="float:left;font-size:${lines * 1.2}em;line-height:${lines * 0.8};margin-right:0.1em" aria-hidden="true">${e(letter)}</span>${e(content)}
+  <span class="ui-drop-cap-letter" style="font-size:${+(lines * 1.2).toFixed(2)}em" aria-hidden="true">${e(letter)}</span>${e(content)}
 </p>`
 }

package/src/ui/gallery.js

@@ -11,6 +11,9 @@
  * @param {'sm'|'md'|'lg'} opts.gap - Gap between images (default: 'md')
  * @param {boolean} opts.rounded  - Rounded corners on images
  * @param {string}  opts.ratio    - CSS aspect-ratio for grid/strip cells e.g. '4/3', '1/1', '16/9'
+ * @param {boolean} opts.lazy     - loading="lazy" on images (default: true). Set false for
+ *                                  above-the-fold galleries or when full-page screenshots
+ *                                  during development need every image rendered eagerly.
  * @param {string}  opts.class
  */
 
@@ -26,6 +29,7 @@ export function gallery({
   gap     = 'md',
   rounded = false,
   ratio   = '4/3',
+  lazy    = true,
   class: cls = '',
 } = {}) {
   if (!LAYOUTS.has(layout)) layout = 'grid'
@@ -42,7 +46,7 @@ export function gallery({
   ].filter(Boolean).join(' ')
 
   const items = images.map(img => {
-    const imgTag = `<img src="${e(img.src)}" alt="${e(img.alt || '')}" class="ui-gallery-img" loading="lazy" decoding="async">`
+    const imgTag = `<img src="${e(img.src)}" alt="${e(img.alt || '')}" class="ui-gallery-img"${lazy ? ' loading="lazy"' : ''} decoding="async">`
     const cap    = img.caption ? `<figcaption class="ui-gallery-caption">${e(img.caption)}</figcaption>` : ''
     const inner  = img.href
       ? `<a href="${e(img.href)}" class="ui-gallery-link">${imgTag}</a>`

package/src/ui/ui.test.js

@@ -25,6 +25,8 @@ import { pricing }     from './pricing.js'
 import { accordion }   from './accordion.js'
 import { nav }         from './nav.js'
 import { appBadge }    from './app-badge.js'
+import { dropCap }     from './drop-cap.js'
+import { gallery }     from './gallery.js'
 import { container }   from './container.js'
 import { section }     from './section.js'
 import { grid }        from './grid.js'
@@ -1319,4 +1321,36 @@ test('uiImage: escapes src to prevent XSS', () => {
   assert.doesNotMatch(html, /<script>/)
 })
 
+test('dropCap: inline style carries only the dynamic font-size — alignment lives in CSS', () => {
+  // Regression: a relative inline line-height (lines * 0.8 → 2.4 for 3 lines)
+  // made the float box ~3x the glyph height, so serif caps floated below the
+  // opening line instead of top-aligning. line-height/float/margin now live in
+  // .ui-drop-cap-letter (pulse-ui.css) with a fixed ~cap-height value.
+  const html = dropCap({ letter: 'O', content: 'nce upon a time.' })
+  assert.match(html, /class="ui-drop-cap-letter"/)
+  assert.match(html, /style="font-size:3\.6em"/)
+  assert.doesNotMatch(html, /line-height/)
+  assert.doesNotMatch(html, /float:left/)
+})
+
+test('dropCap: lines option scales the font-size', () => {
+  const html = dropCap({ letter: 'O', content: 'nce.', lines: 5 })
+  assert.match(html, /style="font-size:6em"/)
+})
+
+test('gallery: images are lazy by default', () => {
+  const html = gallery({ images: [{ src: '/a.jpg', alt: 'A' }] })
+  assert.match(html, /loading="lazy"/)
+})
+
+test('gallery: lazy:false renders eager images', () => {
+  const html = gallery({ images: [{ src: '/a.jpg', alt: 'A' }], lazy: false })
+  assert.doesNotMatch(html, /loading="lazy"/)
+})
+
+test('dropCap: escapes letter and content', () => {
+  const html = dropCap({ letter: '<', content: '<script>alert(1)</script>' })
+  assert.doesNotMatch(html, /<script>/)
+})
+
 console.log('✓ All UI component tests passed')