@invisibleloop/pulse 0.5.0 → 0.6.0

package/CLAUDE.md

@@ -448,6 +448,42 @@ Pulse views are plain JS template literals, not JSX. These React patterns are **
 
 Also: mutations must be pure (no fetch, no DOM access). Only `actions` can be async.
 
+## Markdown
+
+Pulse has a built-in markdown parser. Use it for blog posts, docs pages, and any static content written in `.md` files. Import from `@invisibleloop/pulse/md`. All parsing is server-side — zero browser JS.
+
+```js
+import { md }    from '@invisibleloop/pulse/md'
+import { prose } from '@invisibleloop/pulse/ui'
+
+// Static path
+const page = md('content/about.md')
+
+// Dynamic route — :param resolved from ctx.params
+const post = md('content/blog/:slug.md')
+
+export default {
+  route: '/blog/:slug',
+  meta: {
+    title:       async (ctx) => (await post(ctx)).frontmatter.title,
+    description: async (ctx) => (await post(ctx)).frontmatter.description,
+  },
+  server: { post },
+  view: (state, { post }) => `
+    <main id="main-content">
+      ${prose({ content: post.html })}
+    </main>
+  `,
+  onViewError: () => `<main id="main-content"><p>Post not found.</p></main>`,
+}
+```
+
+- `md(path)` returns an async fetcher — call it in both `meta` and `server`, the file is read only once per request
+- Result is `{ html, frontmatter }` — `html` goes into `prose()`, `frontmatter` holds the `---` key/value pairs
+- Missing file throws `{ status: 404 }` — always add `onViewError` on dynamic markdown routes
+- For markdown from a database/API use `parseMd(source)` directly: `import { parseMd } from '@invisibleloop/pulse/md'`
+- Use `new URL('./content/file.md', import.meta.url)` to resolve relative to the spec file rather than `process.cwd()`
+
 ## Check Components Before Building
 
 Before writing any UI HTML by hand, check `src/ui/index.js` — there are 50+ components available. Use them. Do not reinvent `button`, `card`, `alert`, `modal`, `spinner`, `badge`, `input`, etc.

package/docs/.claude/pulse-checklist.md

@@ -4,11 +4,7 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 ### Critical
 
-- **`hydrate` is set on every interactive page.** Without it, `data-event` / `data-action` bindings do nothing, `persist` never runs, and client-side navigation cannot re-mount the page. Every spec with `mutations`, `actions`, or `persist` must include:
-  ```js
-  hydrate: '/src/pages/my-page.js',  // browser-importable path to this file
-  ```
-  Omit `hydrate` only for purely server-rendered pages with zero client interactivity.
+- **Do not set `hydrate` in specs.** It is auto-derived by the framework from the URL entry passed to `createServer`. Specs with `mutations`, `actions`, or `persist` are hydrated automatically. Purely server-rendered specs get zero JavaScript — no configuration needed.
 
 ### Components first
 
@@ -81,6 +77,12 @@ Before finishing any spec, verify every point below. Fix anything that fails.
   ```
   Supported selectors: `tag`, `.class`, `#id`, `[attr]`, `[attr="value"]`, and combinations (`button.primary[disabled]`).
 
+### Markdown
+
+- **Use `md()` from `@invisibleloop/pulse/md` for `.md` file content.** Never read and parse markdown manually. Pass the result's `html` to `prose()`.
+- **Call the same `md()` fetcher in both `meta` and `server`** — it caches on `ctx._mdCache` so the file is only read once per request. Do not create two separate fetchers for the same file.
+- **Always add `onViewError` on dynamic markdown routes** (routes with `:param` segments loading `.md` files). A missing file throws `{ status: 404 }` which must be caught gracefully.
+
 ### View error handling
 
 - **Define `onViewError` on any page where the view could throw due to bad or missing data.** Without it, a runtime view error returns a 500 on the server and shows a generic inline message on the client. With it, the server returns 200 with your fallback HTML instead of a 500, and the client renders your fallback:

package/docs/public/.pulse-ui-version

@@ -1 +1 @@
-0.2.14
+0.5.0

package/docs/public/pulse-ui.css

@@ -2806,6 +2806,26 @@ fieldset[disabled] .ui-rating-stars .ui-rating-star:hover ~ .ui-rating-star { co
   color:         var(--ui-text);
 }
 
+/* ─── Syntax highlighting tokens ────────────────────────────────────────────
+   Used by ui-prose pre code blocks rendered via @invisibleloop/pulse/md.
+   Dark theme defaults; light theme overrides below.                          */
+:root {
+  --tok-kw:    #c792ea;
+  --tok-str:   #c3e88d;
+  --tok-cmt:   #7a8a9a;
+  --tok-num:   #f78c6c;
+  --tok-fn:    #82aaff;
+  --tok-op:    #89ddff;
+  --tok-punct: #7e8899;
+}
+.tok-kw    { color: var(--tok-kw);    }
+.tok-str   { color: var(--tok-str);   }
+.tok-cmt   { color: var(--tok-cmt);   font-style: italic; }
+.tok-num   { color: var(--tok-num);   }
+.tok-fn    { color: var(--tok-fn);    }
+.tok-op    { color: var(--tok-op);    }
+.tok-punct { color: var(--tok-punct); }
+
 /* ─── Light theme ────────────────────────────────────────────────────────────
    Apply to any ancestor element: <body data-theme="light"> or .ui-theme-light
    All --ui-* tokens are overridden; component markup stays identical.        */
@@ -2829,4 +2849,11 @@ fieldset[disabled] .ui-rating-stars .ui-rating-star:hover ~ .ui-rating-star { co
   --ui-blue:            #1e40af;
   --ui-blue-dim:        rgba( 30,  64, 175, .12);
   --ui-nav-sticky-bg:   rgba(255, 255, 255, .85);
+  --tok-kw:             #7c3aed;
+  --tok-str:            #15803d;
+  --tok-cmt:            #6b7280;
+  --tok-num:            #c2410c;
+  --tok-fn:             #1d4ed8;
+  --tok-op:             #0891b2;
+  --tok-punct:          #6b7280;
 }

package/docs/server.js

@@ -33,6 +33,7 @@ await createServer(
     new URL('./src/pages/persist.js',           import.meta.url),
     // Server
     new URL('./src/pages/server-data.js',       import.meta.url),
+    new URL('./src/pages/markdown.js',          import.meta.url),
     new URL('./src/pages/store.js',             import.meta.url),
     new URL('./src/pages/routing.js',           import.meta.url),
     new URL('./src/pages/streaming.js',         import.meta.url),

package/docs/src/lib/highlight.js

@@ -1,299 +1,2 @@
-/**
- * Pulse Docs — Server-side syntax highlighter
- *
- * Character-by-character tokeniser. No dependencies, no client JS.
- * Returns an HTML string of <span> elements ready to drop inside <code>.
- */
-
-const KEYWORDS = new Set([
-  'export', 'default', 'import', 'from', 'as',
-  'async', 'await', 'const', 'let', 'var',
-  'return', 'if', 'else', 'for', 'while', 'of', 'in',
-  'true', 'false', 'null', 'undefined',
-  'function', 'class', 'new', 'this', 'typeof', 'instanceof',
-  'try', 'catch', 'finally', 'throw',
-])
-
-function esc(s) {
-  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
-}
-
-function span(cls, text) {
-  return `<span class="${cls}">${esc(text)}</span>`
-}
-
-export function highlight(code, lang = 'js') {
-  if (lang === 'bash') return highlightBash(code)
-  if (lang === 'html') return highlightHtml(code)
-  return highlightJs(code)
-}
-
-// ---------------------------------------------------------------------------
-// JavaScript tokeniser
-// ---------------------------------------------------------------------------
-
-function highlightJs(code) {
-  let out = ''
-  let i = 0
-  const n = code.length
-
-  while (i < n) {
-    const ch  = code[i]
-    const ch2 = code[i + 1]
-
-    // Single-line comment
-    if (ch === '/' && ch2 === '/') {
-      const end = code.indexOf('\n', i)
-      const tok = end === -1 ? code.slice(i) : code.slice(i, end)
-      out += span('tok-cmt', tok)
-      i += tok.length
-      continue
-    }
-
-    // Block comment
-    if (ch === '/' && ch2 === '*') {
-      const end = code.indexOf('*/', i + 2)
-      const tok = end === -1 ? code.slice(i) : code.slice(i, end + 2)
-      out += span('tok-cmt', tok)
-      i += tok.length
-      continue
-    }
-
-    // Template literal
-    if (ch === '`') {
-      let tok = '`'
-      i++
-      let depth = 0
-      while (i < n) {
-        if (code[i] === '\\') {
-          tok += code[i] + (code[i + 1] || '')
-          i += 2
-          continue
-        }
-        if (code[i] === '$' && code[i + 1] === '{') {
-          tok += '${'
-          i += 2
-          depth++
-          continue
-        }
-        if (code[i] === '}' && depth > 0) {
-          tok += '}'
-          i++
-          depth--
-          continue
-        }
-        if (code[i] === '`' && depth === 0) {
-          tok += '`'
-          i++
-          break
-        }
-        tok += code[i++]
-      }
-      out += span('tok-str', tok)
-      continue
-    }
-
-    // Single or double quoted string
-    if (ch === '"' || ch === "'") {
-      let tok = ch
-      i++
-      while (i < n && code[i] !== ch && code[i] !== '\n') {
-        if (code[i] === '\\') {
-          tok += code[i] + (code[i + 1] || '')
-          i += 2
-          continue
-        }
-        tok += code[i++]
-      }
-      if (i < n && code[i] === ch) tok += code[i++]
-      out += span('tok-str', tok)
-      continue
-    }
-
-    // Number
-    if (/\d/.test(ch) && (i === 0 || !/\w/.test(code[i - 1]))) {
-      let tok = ''
-      while (i < n && /[\d.xXa-fA-F]/.test(code[i])) tok += code[i++]
-      out += span('tok-num', tok)
-      continue
-    }
-
-    // Identifier / keyword
-    if (/[a-zA-Z_$]/.test(ch)) {
-      let tok = ''
-      while (i < n && /[\w$]/.test(code[i])) tok += code[i++]
-
-      if (KEYWORDS.has(tok)) {
-        out += span('tok-kw', tok)
-      } else {
-        // Look ahead: followed by ( → function call
-        let j = i
-        while (j < n && code[j] === ' ') j++
-        if (code[j] === '(') {
-          out += span('tok-fn', tok)
-        } else {
-          out += esc(tok)
-        }
-      }
-      continue
-    }
-
-    // Operators
-    if (/[=!<>|&?.]/.test(ch)) {
-      let tok = ch
-      // Grab two-char operators
-      if (/[=!<>|&?]/.test(ch) && /[=|&>?]/.test(ch2)) {
-        tok = code.slice(i, i + 2)
-        // Three-char: ===, !==, ...
-        if (code[i + 2] === '=') tok = code.slice(i, i + 3)
-      }
-      out += span('tok-op', tok)
-      i += tok.length
-      continue
-    }
-
-    // Punctuation
-    if (/[{}()[\],;:]/.test(ch)) {
-      out += span('tok-punct', ch)
-      i++
-      continue
-    }
-
-    // Everything else (whitespace, newlines, etc.)
-    out += esc(ch)
-    i++
-  }
-
-  return out
-}
-
-// ---------------------------------------------------------------------------
-// Bash tokeniser (minimal)
-// ---------------------------------------------------------------------------
-
-function highlightBash(code) {
-  return code.split('\n').map(line => {
-    // Comment line
-    if (/^\s*#/.test(line)) return span('tok-cmt', line)
-
-    let out = ''
-    let i = 0
-    while (i < line.length) {
-      // Inline comment
-      if (line[i] === '#') {
-        out += span('tok-cmt', line.slice(i))
-        break
-      }
-      // String
-      if (line[i] === '"' || line[i] === "'") {
-        const q = line[i]
-        let tok = q
-        i++
-        while (i < line.length && line[i] !== q) tok += line[i++]
-        tok += line[i] === q ? line[i++] : ''
-        out += span('tok-str', tok)
-        continue
-      }
-      // Flag/option
-      if (line[i] === '-' && /\w/.test(line[i + 1] || '')) {
-        let tok = '-'
-        i++
-        while (i < line.length && /[-\w]/.test(line[i])) tok += line[i++]
-        out += span('tok-op', tok)
-        continue
-      }
-      out += esc(line[i++])
-    }
-    return out
-  }).join('\n')
-}
-
-// ---------------------------------------------------------------------------
-// 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
-  const n = code.length
-
-  while (i < n) {
-    // Comment
-    if (code.slice(i, i + 4) === '<!--') {
-      const end = code.indexOf('-->', i + 4)
-      const tok = end === -1 ? code.slice(i) : code.slice(i, end + 3)
-      out += span('tok-cmt', tok)
-      i += tok.length
-      continue
-    }
-
-    // Tag
-    if (code[i] === '<') {
-      const end = code.indexOf('>', i)
-      if (end === -1) { out += esc(code[i++]); continue }
-      out += highlightHtmlTag(code.slice(i, end + 1))
-      i = end + 1
-      continue
-    }
-
-    out += esc(code[i++])
-  }
-
-  return out
-}
+// Re-export from the framework's canonical highlight implementation.
+export { highlight } from '../../../src/md/highlight.js'

package/docs/src/lib/nav.js

@@ -38,6 +38,7 @@ export const NAV = [
     section: 'Server',
     items: [
       { label: 'Server Data',    href: '/server-data'   },
+      { label: 'Markdown',       href: '/markdown'      },
       { label: 'Global Store',   href: '/store'         },
       { label: 'Routing',        href: '/routing'       },
       { label: 'Streaming SSR',  href: '/streaming'     },

package/docs/src/pages/accessibility.js

@@ -11,7 +11,6 @@ export default {
     description: 'Keyboard navigation, focus management, semantic HTML, and ARIA patterns in Pulse.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/accessibility',
     prev,

package/docs/src/pages/auth.js

@@ -11,7 +11,6 @@ export default {
     description: 'Integrating Auth0 OAuth authentication with Pulse using guard functions, ctx.setCookie, and raw response specs.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/auth',
     prev,
@@ -141,7 +140,6 @@ export default {
     profile: async (ctx) => fetchUserProfile(ctx.cookies.session),
   },
 
-  state: {},
   view: (state, server) => \`
     <main id="main-content">
       <h1>Welcome, \${server.profile.name}</h1>

package/docs/src/pages/caching.js

@@ -11,7 +11,6 @@ export default {
     description: 'HTTP cache headers, in-process server data caching, and asset caching in Pulse.',
     styles: ['/docs.css'],
   },
-  state: {},
   view: () => renderLayout({
     currentHref: '/caching',
     prev,

package/docs/src/pages/components/accordion.js

@@ -12,7 +12,6 @@ export default {
     description: 'Accordion component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/accordion',
     prev,

package/docs/src/pages/components/alert.js

@@ -11,7 +11,6 @@ export default {
     description: 'Alert component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/alert',
     prev,

package/docs/src/pages/components/app-badge.js

@@ -12,7 +12,6 @@ export default {
     description: 'App Badge component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/app-badge',
     prev,

package/docs/src/pages/components/avatar.js

@@ -11,7 +11,6 @@ export default {
     description: 'Avatar component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/avatar',
     prev,

package/docs/src/pages/components/badge.js

@@ -11,7 +11,6 @@ export default {
     description: 'Badge component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/badge',
     prev,

package/docs/src/pages/components/banner.js

@@ -12,7 +12,6 @@ export default {
     description: 'Banner component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/banner',
     prev,

package/docs/src/pages/components/breadcrumbs.js

@@ -12,7 +12,6 @@ export default {
     description: 'Accessible breadcrumb navigation component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/breadcrumbs',
     prev,

package/docs/src/pages/components/button.js

@@ -13,7 +13,6 @@ export default {
     description: 'Button component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/button',
     prev,

package/docs/src/pages/components/card.js

@@ -12,7 +12,6 @@ export default {
     description: 'Card component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/card',
     prev,

package/docs/src/pages/components/carousel.js

@@ -16,7 +16,6 @@ export default {
     description: 'Carousel / slider component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/carousel',
     prev,

package/docs/src/pages/components/charts.js

@@ -32,7 +32,6 @@ export default {
     description: 'Server-rendered SVG charts for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/charts',
     prev,

package/docs/src/pages/components/checkbox.js

@@ -12,7 +12,6 @@ export default {
     description: 'Custom-styled checkbox component for Pulse UI.',
     styles:      ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/checkbox',
     prev,

package/docs/src/pages/components/cluster.js

@@ -12,7 +12,6 @@ export default {
     description: 'Cluster component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/cluster',
     prev,

package/docs/src/pages/components/code-window.js

@@ -12,7 +12,6 @@ export default {
     description: 'macOS-style window chrome around a code block. Accepts pre-highlighted HTML as the content slot.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/code-window',
     prev,

package/docs/src/pages/components/container.js

@@ -12,7 +12,6 @@ export default {
     description: 'Container component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/container',
     prev,

package/docs/src/pages/components/divider.js

@@ -12,7 +12,6 @@ export default {
     description: 'Divider component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/divider',
     prev,

package/docs/src/pages/components/empty.js

@@ -11,7 +11,6 @@ export default {
     description: 'Empty state component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/empty',
     prev,

package/docs/src/pages/components/feature.js

@@ -13,7 +13,6 @@ export default {
     description: 'Feature component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/feature',
     prev,

package/docs/src/pages/components/fieldset.js

@@ -12,7 +12,6 @@ export default {
     description: 'Semantic grouping of related form fields with an accessible legend.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/fieldset',
     prev,

package/docs/src/pages/components/footer.js

@@ -12,7 +12,6 @@ export default {
     description: 'Accessible site footer with logo slot, navigation links, and legal text.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/footer',
     prev,

package/docs/src/pages/components/grid.js

@@ -16,7 +16,6 @@ export default {
     description: 'Grid component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/grid',
     prev,

package/docs/src/pages/components/heading.js

@@ -12,7 +12,6 @@ export default {
     description: 'Styled semantic heading component for Pulse UI.',
     styles: ['/pulse-ui.css', '/docs.css'],
   },
-  state: {},
   view: () => renderComponentPage({
     currentHref: '/components/heading',
     prev,