@invisibleloop/pulse 0.15.1 → 0.17.0

package/src/agent/identity.md

@@ -14,7 +14,7 @@ Every page you ship must meet all of the following. These are not aspirational
 
 **Lighthouse 100 on Accessibility, Best Practices, and SEO.** The \`lighthouse_audit\` tool returns these three scores — all must be 100. If any cannot hit 100, something is wrong with the spec. (Performance is not part of the audit tool and is not required.) The audit is slow — ~30–60 s per run. Always tell the user before calling it.
 
-**Polished and considered.** Use the component library — `button`, `card`, `input`, `alert`, `stat`, `empty`, `table`, and the rest. Use the spacing scale (`u-mt-*`, `u-gap-*`, `u-py-*`). Use the type scale (`u-text-xl`, `u-font-semibold`). Use the colour tokens (`var(--ui-accent)`, `var(--ui-muted)`). Do not leave raw unstyled HTML. Do not invent a layout from scratch when the grid, stack, cluster, container, and section components already solve it.
+**Polished and considered.** Use the component library — `button`, `card`, `input`, `alert`, `stat`, `empty`, `table`, and the rest. Use the spacing scale (`u-mt-*`, `u-gap-*`, `u-py-*`). Use the type scale (`u-text-xl`, `u-font-semibold`). Use the colour tokens (`var(--ui-accent)`, `var(--ui-muted)`). Do not leave raw unstyled HTML. Do not invent a layout from scratch when the grid, stack, cluster, container, and section components already solve it — *unless you have declared a creative override (see "Design Freedom" below), in which case a custom layout is the deliberate, correct choice.*
 
 **Works correctly on first load.** SSR is always on. The page must be readable and navigable before any JavaScript executes. Do not build pages that require client JS to render content.
 
@@ -22,15 +22,30 @@ Every page you ship must meet all of the following. These are not aspirational
 
 **Accessible form labels.** Every `input`, `select`, and `textarea` has a label. Every form has a submit button. Required fields are marked required. Error messages are associated with the field that caused them.
 
+# Design Freedom — The Rule
+
+There are two valid build modes. Knowing which one you are in tells you exactly which rules apply.
+
+**Mode A — components first (the default).** All standard UI patterns come from the component library. The component rules in "What You Will Not Do" below apply in full. This is the right mode for most pages.
+
+**Mode B — creative override.** When the design intent genuinely calls for it — a highly custom visual identity, an asymmetric or typographically-driven layout, a brutalist/editorial/retro/neon/paper vibe that components would constrain, or a layout a component simply cannot reproduce — you may build with raw HTML throughout. This is a deliberate design decision available to you, not a rule violation and not a shortcut. To use it:
+
+1. **Declare it in a comment at the top of the spec:** `// component-free — creative override: <reason>`. The review tool reads this comment from the source file — announcing the mode in chat is not enough.
+2. Functional atoms (`button`, `input`, `badge`, `modal`) still come from components unless there is a specific design reason not to.
+3. `/pulse-ui.css` stays in `meta.styles` — your custom CSS builds on its token system.
+4. The pass bar changes: instead of the component checklist, **Lighthouse 100 on Accessibility, Best Practices, and SEO, desktop and mobile**, plus CLS 0.00. A component-free page that passes every audit is correct. A component-heavy page that fails accessibility is not.
+
+The component rules marked *(Mode A)* below are suspended under a declared creative override. Everything else — accessibility, security, testing, escaping, error handling — applies in both modes, always.
+
 # What You Will Not Do
 
 - Install client-side JS dependencies. No React, Vue, Alpine, htmx, Tailwind, Lodash, Axios, or any other package that runs in the browser. Pulse handles rendering, state, actions, navigation, and SSR. If you need a utility, write it.
 - Use emoji characters in UI output. Use icons from the icon library instead — `iconCheck`, `iconStar`, `iconZap`, etc. If the right icon does not exist, create it in `src/ui/icons.js` following the existing pattern (see the guide for how). Emoji are not accessible, are not theme-aware, and render inconsistently across platforms.
-- Hardcode hex colours in CSS. Use `var(--ui-*)` tokens. They cascade through every component automatically and make theming possible.
-- Use inline `style=""` attributes. Use utility classes or `var(--ui-*)` tokens in a stylesheet.
-- Write raw `<button>`, `<input>`, `<select>`, or `<textarea>` HTML when the component library already provides accessible, styled versions.
-- Write raw `<h1>`–`<h6>` without styling. Use `heading({ level, text })` instead.
-- Write raw `<ul>` or `<ol>` without styling. Use `list({ items })` instead.
+- Hardcode hex colours in CSS. Use `var(--ui-*)` tokens — they cascade through every component automatically and make theming possible. The one place hex values belong is `public/theme.css`, as token *definitions*; every other stylesheet references them via `var()`. A lint hook enforces this.
+- Use inline `style=""` attributes. Use utility classes or `var(--ui-*)` tokens in a stylesheet. *Exception:* structural image styles with no utility-class equivalent (`aspect-ratio`, `object-fit`) are permitted inline — these are layout facts, not theming, and the design gallery uses them this way.
+- Write raw `<button>`, `<input>`, `<select>`, or `<textarea>` HTML when the component library already provides accessible, styled versions. *(Mode A — under a creative override, functional atoms should still come from components unless there is a specific design reason.)*
+- Write raw `<h1>`–`<h6>` without styling. Use `heading({ level, text })` instead. *(Mode A)*
+- Write raw `<ul>` or `<ol>` without styling. Use `list({ items })` instead. *(Mode A)*
 - Output CMS or database HTML without a `prose()` wrapper. Raw HTML from external sources has no styling — always wrap it in `prose({ content: html })`.
 - Use `data-event` on text inputs. Re-rendering on every keystroke destroys focus. Use uncontrolled inputs and read values from `FormData` in `action.onStart` or `action.run`.
 - Skip `onError` in an action. It is required. Always handle failure.

package/src/agent/workflow.md

@@ -73,7 +73,7 @@ Decide the complexity tier (see below) and confirm with the user if the task is
 
 **Skip confirmation for trivially small tasks** (add a button, fix a label, swap a component). When in doubt, confirm.
 
-**When asking the user questions:** ask one question at a time. If you present choices, use at most 4 options — the `ask_user` tool enforces this limit and will error if exceeded. For open-ended questions (names, copy, features, hex colours), ask as plain prose with no choices at all.
+**When asking the user questions:** ask one question at a time. If you present choices, use at most 4 options — question tools in agent hosts (e.g. Claude Code's AskUserQuestion) cap the number of choices and will error if exceeded. For open-ended questions (names, copy, features, hex colours), ask as plain prose with no choices at all.
 
 ---
 
@@ -161,11 +161,12 @@ If you're about to type `class="hero"` or `class="product-card"` in Mode A, stop
 When the design intent calls for a more expressive, unconventional, or typographically-driven layout that components would constrain, you may build with raw HTML throughout. This is a deliberate design decision, not a shortcut.
 
 Rules for Mode B:
+- **Declare it in a comment at the top of the spec file:** `// component-free — creative override: <reason>`. The review tool detects creative override by reading this comment from the source — without it, `pulse_review` will flag every component pattern as a violation even though you chose Mode B deliberately. Announcing the mode in chat is not enough; the comment must be in the file.
 - Load `/pulse-ui.css` in `meta.styles` — the token system is still required
 - Functional atoms (`button`, `input`, `badge`, `modal`) should still come from components unless there is a specific design reason
-- The quality gate is 100/100/100/100 Lighthouse on both desktop and mobile — this replaces the component checklist as the pass bar
+- The quality gate is Lighthouse 100 on Accessibility, Best Practices, and SEO (desktop and mobile) plus CLS 0.00 — this replaces the component checklist as the pass bar. Performance is reported but not gated.
 
-Announce Mode B explicitly in the build brief: *"Mode B — component-free, raw HTML for creative control."*
+Announce Mode B explicitly in the build brief (*"Mode B — component-free, raw HTML for creative control"*) **and** write the override comment into the spec.
 
 ### 3b — Announce before writing
 

package/src/html.js

@@ -21,4 +21,5 @@ export function escHtml(str) {
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
     .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
 }

package/src/mcp/mcp.test.js

@@ -0,0 +1,219 @@
+/**
+ * MCP integrity tests — run with: node src/mcp/mcp.test.js
+ *
+ * Guards against guide file drift: every guide-*.md file under src/agent/
+ * must be registered as a named MCP resource in server.js, and every
+ * readFileSync call in server.js that references a guide-*.md must point
+ * to a file that actually exists.
+ */
+
+import fs   from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
+const ROOT      = path.resolve(__dirname, '../..')
+
+let passed = 0
+let failed = 0
+
+function test(label, fn) {
+  try {
+    fn()
+    console.log(`  ✓ ${label}`)
+    passed++
+  } catch (e) {
+    console.log(`  ✗ ${label}`)
+    console.log(`    ${e.message}`)
+    failed++
+  }
+}
+
+function assert(condition, msg) {
+  if (!condition) throw new Error(msg || 'Assertion failed')
+}
+
+// ── Read source files ────────────────────────────────────────────────────────
+
+const serverSrc = fs.readFileSync(path.join(__dirname, 'server.js'), 'utf8')
+const agentDir  = path.join(ROOT, 'src/agent')
+
+// All guide-*.md files that exist on disk
+const guideFiles = fs.readdirSync(agentDir)
+  .filter(f => f.startsWith('guide-') && f.endsWith('.md'))
+  .sort()
+
+// All guide-*.md files referenced via readFileSync in server.js
+// Pattern: new URL('../agent/guide-*.md', import.meta.url)
+const referencedFiles = [...serverSrc.matchAll(/new URL\(['"`][^'"`]*?(guide-[^'"`/]+\.md)['"`]/g)]
+  .map(m => m[1])
+
+// All guide-*.md filenames registered as MCP resource URIs
+const registeredUris = [...serverSrc.matchAll(/uri:\s*['"`](pulse:\/\/guide\/[^'"`]+)['"`]/g)]
+  .map(m => m[1])
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+console.log('\nGuide file coverage\n')
+
+test('guide-routing.md exists on disk', () => {
+  assert(fs.existsSync(path.join(agentDir, 'guide-routing.md')), 'guide-routing.md not found')
+})
+
+test('guide-components.md exists on disk', () => {
+  assert(fs.existsSync(path.join(agentDir, 'guide-components.md')), 'guide-components.md not found')
+})
+
+for (const file of guideFiles) {
+  test(`${file} is referenced by readFileSync in server.js`, () => {
+    assert(
+      referencedFiles.includes(file),
+      `${file} exists in src/agent/ but is not loaded by server.js via readFileSync. ` +
+      `Either register it as a guide resource or delete it.`
+    )
+  })
+}
+
+for (const file of referencedFiles) {
+  test(`${file} (referenced in server.js) exists on disk`, () => {
+    assert(
+      fs.existsSync(path.join(agentDir, file)),
+      `server.js references ${file} via readFileSync but the file does not exist in src/agent/`
+    )
+  })
+}
+
+test('every guide-*.md on disk has a corresponding pulse://guide/* MCP resource', () => {
+  // Map file names to expected URI slugs: guide-design-references.md → pulse://guide/design-references
+  const fileToUri = (f) => 'pulse://guide/' + f.replace(/^guide-/, '').replace(/\.md$/, '')
+  const missing = guideFiles.filter(f => !registeredUris.includes(fileToUri(f)))
+  assert(
+    missing.length === 0,
+    `These guide files have no registered MCP resource URI:\n    ${missing.join('\n    ')}\n` +
+    `Add them to GUIDE_RESOURCES in server.js or delete them.`
+  )
+})
+
+test('no orphaned guide.md (monolithic legacy file should not exist)', () => {
+  assert(
+    !fs.existsSync(path.join(agentDir, 'guide.md')),
+    'guide.md exists in src/agent/ — this is the old monolithic guide and should be deleted. ' +
+    'Content should live in the split guide-*.md files.'
+  )
+})
+
+// ── Duplicated doc sync ──────────────────────────────────────────────────────
+// Several agent docs exist in two places (a canonical source plus a copy that is
+// scaffolded into consumer projects or kept in this repo's own .claude/). These
+// pairs must stay byte-identical or the two audiences receive drifting rules.
+
+console.log('\nDuplicated doc sync\n')
+
+const SYNC_PAIRS = [
+  ['src/agent/checklist.md',        '.claude/pulse-checklist.md'],
+  ['src/agent/checklist.md',        'docs/.claude/pulse-checklist.md'],
+  ['src/agent/checklist.md',        'examples/.claude/pulse-checklist.md'],
+  ['src/agent/commands/verify.md',  '.claude/commands/verify.md'],
+]
+
+for (const [a, b] of SYNC_PAIRS) {
+  test(`${a} is in sync with ${b}`, () => {
+    const fa = path.join(ROOT, a)
+    const fb = path.join(ROOT, b)
+    assert(fs.existsSync(fa), `${a} does not exist`)
+    assert(fs.existsSync(fb), `${b} does not exist`)
+    assert(
+      fs.readFileSync(fa, 'utf8') === fs.readFileSync(fb, 'utf8'),
+      `${a} and ${b} have drifted apart. Edit the canonical file and copy it over the other ` +
+      `(cp ${a} ${b} or vice versa) so both audiences get the same rules.`
+    )
+  })
+}
+
+// ── Agent doc consistency guards ─────────────────────────────────────────────
+// Contradictions between agent docs leave the agent unable to know what it can
+// and cannot do. These guards pin the resolved decisions:
+//   - The Lighthouse pass bar is THREE gated scores (Accessibility, Best
+//     Practices, SEO) — Performance is reported, never gated. "100/100/100/100"
+//     reintroduces a four-score bar the audit tooling cannot verify.
+//   - "ask_user" is not a real tool in any host — docs must not name it.
+//   - Emoji are banned in UI output — design guides must not suggest them.
+
+console.log('\nAgent doc consistency\n')
+
+const agentDocs = [
+  ...fs.readdirSync(agentDir).filter(f => f.endsWith('.md')).map(f => path.join('src/agent', f)),
+  ...fs.readdirSync(path.join(agentDir, 'commands')).filter(f => f.endsWith('.md')).map(f => path.join('src/agent/commands', f)),
+  ...fs.readdirSync(path.join(agentDir, 'skills')).flatMap(d => {
+    const p = path.join(agentDir, 'skills', d, 'SKILL.md')
+    return fs.existsSync(p) ? [path.join('src/agent/skills', d, 'SKILL.md')] : []
+  }),
+  '.claude/commands/build-page.md',
+  '.claude/commands/verify.md',
+  '.claude/commands/new-doc-page.md',
+  'CLAUDE.md',
+]
+
+test('no agent doc states a four-score Lighthouse bar (100/100/100/100)', () => {
+  const offenders = agentDocs.filter(f =>
+    fs.existsSync(path.join(ROOT, f)) &&
+    fs.readFileSync(path.join(ROOT, f), 'utf8').includes('100/100/100/100')
+  )
+  if (serverSrc.includes('100/100/100/100')) offenders.push('src/mcp/server.js')
+  assert(
+    offenders.length === 0,
+    `Four-score Lighthouse bar found in: ${offenders.join(', ')}. ` +
+    `The gated scores are Accessibility, Best Practices, and SEO (three) — Performance is reported, not gated.`
+  )
+})
+
+test('no agent doc references a literal ask_user tool', () => {
+  const offenders = agentDocs.filter(f =>
+    fs.existsSync(path.join(ROOT, f)) &&
+    /\bask_user\b/.test(fs.readFileSync(path.join(ROOT, f), 'utf8'))
+  )
+  assert(
+    offenders.length === 0,
+    `"ask_user" referenced in: ${offenders.join(', ')}. ` +
+    `No host exposes a tool by that name — phrase host-agnostically (e.g. "your host's question tool").`
+  )
+})
+
+test('design guides do not suggest emoji in UI output', () => {
+  const designGuides = ['src/agent/guide-design-references.md', 'src/agent/guide-design-gallery.md']
+  const offenders = designGuides.filter(f => {
+    const src = fs.readFileSync(path.join(ROOT, f), 'utf8')
+    // Allow lines that mention emoji only to ban them; flag lines that suggest using them
+    return src.split('\n').some(line =>
+      /emoji/i.test(line) && !/never|not |banned|instead of emoji/i.test(line)
+    )
+  })
+  assert(
+    offenders.length === 0,
+    `Emoji suggested (without a ban qualifier) in: ${offenders.join(', ')}. ` +
+    `Emoji are banned in UI output (identity.md) — suggest icon-library glyphs instead.`
+  )
+})
+
+test('workflow.md Mode B instructs writing the creative-override spec comment', () => {
+  const workflow = fs.readFileSync(path.join(agentDir, 'workflow.md'), 'utf8')
+  assert(
+    /component.free — creative override/.test(workflow),
+    'workflow.md Mode B must instruct writing the `// component-free — creative override: <reason>` ' +
+    'comment into the spec — pulse_review detects creative override by reading the source file.'
+  )
+})
+
+test('identity.md declares the creative override (Design Freedom) carve-out', () => {
+  const identity = fs.readFileSync(path.join(agentDir, 'identity.md'), 'utf8')
+  assert(
+    /creative override/i.test(identity),
+    'identity.md must include the creative-override carve-out — without it the persona ' +
+    'unconditionally bans raw HTML that workflow.md Mode B explicitly permits.'
+  )
+})
+
+// ── Result ───────────────────────────────────────────────────────────────────
+
+console.log(`\n${passed} passed, ${failed} failed\n`)
+if (failed > 0) process.exit(1)

package/src/mcp/server.js

@@ -1057,12 +1057,33 @@ ${(() => {
     checks.push('✓ No obvious hex colours in view')
   }
   
+  // XSS test coverage — check whether the test file includes a <script>alert assertion
+  // for each user-controlled string interpolated into the view.
+  // Heuristic: if the view interpolates any exported string variable (escape(), or direct
+  // string props), the test file should contain a '<script>' XSS assertion.
+  if (file) {
+    const testFile = file.replace(/\.js$/, '.test.js')
+    let xssNote = ''
+    if (fs.existsSync(testFile)) {
+      const testSrc = fs.readFileSync(testFile, 'utf8')
+      const hasXssAssertion = testSrc.includes('<script>') || testSrc.includes('xss') || testSrc.includes('script>alert')
+      if (!hasXssAssertion) {
+        xssNote = '⚠ **No XSS test found** — test file exists but has no `<script>alert` assertion. Add at least one test that passes a `\'<script>alert(1)</script>\'` string as a user-controlled input and asserts it does not appear unescaped in the output.'
+      } else {
+        xssNote = '✓ XSS test assertion present'
+      }
+    } else {
+      xssNote = '○ No test file found — create one at ' + path.basename(testFile)
+    }
+    checks.push(xssNote)
+  }
+
   // Creative override detection — check if spec declares component-free mode
   const creativeOverride = /component.free|creative\s+override|raw\s+HTML\s+throughout/i.test(source)
   checks.push(creativeOverride
-    ? '⚡ **Creative override declared** — component pattern checks are advisory only. Lighthouse 100/100/100/100 is the pass bar.'
+    ? '⚡ **Creative override declared** — component pattern checks are advisory only. Lighthouse 100 on Accessibility, Best Practices, and SEO (desktop + mobile) plus CLS 0.00 is the pass bar.'
     : '○ No creative override declared — component checks apply')
-  
+
   return checks.join('\n')
 })()}
 
@@ -1101,7 +1122,7 @@ Work through every item. Fix anything that fails. Refer to the spec source at ${
 
   If no creative override is declared and a component *could* reproduce the design, refactor to use it. Custom utility classes on top of components are fine (\`hero({ ... })\` + override CSS) — but do not write the entire structure from scratch when the component supports the layout.
 
-- [ ] **Creative override** (fill in if applicable): *State the override reason here — e.g. "full-viewport gradient hero not achievable with hero() component"*. Confirm Lighthouse 100/100/100/100 desktop and mobile passes before closing the review.
+- [ ] **Creative override** (fill in if applicable): *State the override reason here — e.g. "full-viewport gradient hero not achievable with hero() component"*. Confirm Lighthouse 100 on Accessibility, Best Practices, and SEO (desktop and mobile) plus CLS 0.00 before closing the review.
 - [ ] No \`data-event\` on text inputs — this destroys focus on every keystroke
 - [ ] No \`className\`, \`htmlFor\`, \`onClick=\`, or other React patterns
 - [ ] No hardcoded hex colours in view — only \`var(--ui-*)\` tokens (anchor \`href="#id"\` values are fine — those are not colours)

package/src/mcp/validate-worker.js

@@ -156,6 +156,24 @@ try {
     warnings.push('Inline <script> block detected in view — Pulse\'s CSP (script-src with nonces) will block these scripts at runtime. Move JavaScript to a file in public/ and reference it via meta.scripts: [\'/my-script.js\'] in the spec instead.')
   }
 
+  // External image URLs in src attributes — will be blocked by Pulse's default CSP (img-src 'self')
+  // unless the domain is explicitly listed in pulse.config.js under csp['img-src'].
+  // Flag any http/https src that isn't a data URI or relative path.
+  const externalImgSrcs = [...html.matchAll(/\bsrc=["'](https?:\/\/[^"']+)["']/gi)]
+    .map(m => m[1])
+  if (externalImgSrcs.length) {
+    const domains = [...new Set(externalImgSrcs.map(u => {
+      try { return new URL(u).origin } catch { return u }
+    }))].slice(0, 3)
+    warnings.push(
+      `External image URL${externalImgSrcs.length > 1 ? 's' : ''} in view (${domains.join(', ')}) — ` +
+      `Pulse's default CSP blocks cross-origin images. ` +
+      `Either download the images to public/ and use a relative path (/images/foo.jpg), ` +
+      `or allow the domain in pulse.config.js:\n` +
+      `  export default { csp: { 'img-src': ['${domains[0]}'] } }`
+    )
+  }
+
   // Hardcoded hex colours in view HTML — must use var(--ui-*) tokens instead.
   // Matches: style="...color:#hex..." or style="...background:#hex..."
   // Allows: href="#section-id" (anchor links are not colours)

package/src/md/index.js

@@ -25,6 +25,33 @@ function esc(s) {
     .replace(/"/g, '"')
 }
 
+/**
+ * Sanitise a markdown link/image URL.
+ *
+ * Allows http(s), mailto, tel, relative paths, fragment/query refs, and
+ * image data: URIs. Any other scheme — notably javascript:, vbscript:, and
+ * non-image data: URIs — is neutralised to '#', preventing XSS when markdown
+ * comes from an untrusted source (database, user submission, external API).
+ *
+ * The value has already passed through esc(), so it is safe to embed in an
+ * attribute; this guard only blocks dangerous URL schemes.
+ *
+ * @param {string} url
+ * @param {boolean} [isImage=false] - permit image data: URIs when true
+ * @returns {string}
+ */
+function safeUrl(url, isImage = false) {
+  // Strip leading control chars/whitespace that browsers ignore when parsing
+  // the scheme (e.g. "java\tscript:"), then test for a scheme prefix.
+  const stripped = url.replace(/[\x00-\x20]+/g, '')
+  const scheme   = stripped.match(/^([a-zA-Z][a-zA-Z0-9+.\-]*):/)
+  if (!scheme) return url  // no scheme → relative / fragment / query, safe
+  const proto = scheme[1].toLowerCase()
+  if (proto === 'http' || proto === 'https' || proto === 'mailto' || proto === 'tel') return url
+  if (isImage && /^data:image\/(png|jpe?g|gif|webp|avif|svg\+xml);/i.test(stripped)) return url
+  return '#'
+}
+
 // ---------------------------------------------------------------------------
 // Frontmatter — --- key: value --- block at top of file
 // ---------------------------------------------------------------------------
@@ -69,12 +96,12 @@ function renderInline(raw) {
   // 3. Images (before links — same syntax with leading !)
   s = s.replace(/!\[([^\]]*)\]\(([^)\s"]+)(?:\s+"([^"]*)")?\)/g,
     (_, alt, src, title) =>
-      `<img src="${src}" alt="${alt}"${title ? ` title="${title}"` : ''}>`)
+      `<img src="${safeUrl(src, true)}" alt="${alt}"${title ? ` title="${title}"` : ''}>`)
 
   // 4. Links
   s = s.replace(/\[([^\]]+)\]\(([^)\s"]+)(?:\s+"([^"]*)")?\)/g,
     (_, label, href, title) =>
-      `<a href="${href}"${title ? ` title="${title}"` : ''}>${label}</a>`)
+      `<a href="${safeUrl(href)}"${title ? ` title="${title}"` : ''}>${label}</a>`)
 
   // 5. Bold + italic (order: *** before ** before *)
   s = s.replace(/\*{3}([^*\n]+)\*{3}/g, (_, t) => `<strong><em>${t}</em></strong>`)

package/src/md/md.test.js

@@ -175,6 +175,42 @@ test('HTML is escaped in inline text', () => {
   assert(html.includes('<script>'), `Got: ${html}`)
 })
 
+// --- URL scheme sanitisation (XSS) -----------------------------------------
+
+test('link with javascript: scheme is neutralised to #', () => {
+  const { html } = parseMd('[x](javascript:alert(1))')
+  assert(!html.toLowerCase().includes('javascript:'), `Got: ${html}`)
+  assert(html.includes('href="#"'), `Got: ${html}`)
+})
+
+test('javascript: scheme neutralised regardless of case', () => {
+  const { html } = parseMd('[x](JaVaScRiPt:alert(1))')
+  assert(!html.toLowerCase().includes('javascript:'), `Got: ${html}`)
+})
+
+test('image with javascript: scheme is neutralised', () => {
+  const { html } = parseMd('![i](javascript:alert(1))')
+  assert(!html.toLowerCase().includes('javascript:'), `Got: ${html}`)
+  assert(html.includes('src="#"'), `Got: ${html}`)
+})
+
+test('non-image data: URI in image is neutralised', () => {
+  const { html } = parseMd('![i](data:text/html,<script>alert(1)</script>)')
+  assert(html.includes('src="#"'), `Got: ${html}`)
+})
+
+test('image data: URI is allowed', () => {
+  const { html } = parseMd('![i](data:image/png;base64,iVBOR)')
+  assert(html.includes('src="data:image/png;base64,iVBOR"'), `Got: ${html}`)
+})
+
+test('safe schemes and relative/fragment URLs are preserved', () => {
+  for (const url of ['https://ok.com', 'http://ok.com', '/relative', '#frag', 'mailto:a@b.com', 'tel:+15551234']) {
+    const { html } = parseMd(`[x](${url})`)
+    assert(html.includes(`href="${url}"`), `Expected ${url} preserved, got: ${html}`)
+  }
+})
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${passed + failed} tests: ${passed} passed, ${failed} failed\n`)

package/src/runtime/ssr.js

@@ -621,4 +621,5 @@ function esc(str) {
     .replace(/</g, '&lt;')
     .replace(/>/g, '&gt;')
     .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;')
 }

package/src/runtime/tt.js

@@ -4,6 +4,14 @@
  * everywhere else — behaviour is identical, the protection is simply absent.
  *
  * Policy name 'pulse' must match the trusted-types CSP directive on the server.
+ *
+ * SECURITY NOTE: createHTML/createScriptURL are intentional pass-throughs. The
+ * framework owns the HTML it renders, so this policy does NOT sanitise — it
+ * exists to satisfy `require-trusted-types-for 'script'` and to confine HTML
+ * sinks to a single audited policy (preventing *other* code on the page from
+ * creating its own policy). It is NOT a defence against unescaped user data in
+ * a view: view authors remain responsible for escaping untrusted values with
+ * escHtml() before interpolating them into markup.
  */
 
 let _policy = null