@invisibleloop/pulse 0.5.1 → 0.6.0

package/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/scripts/build.js

@@ -32,7 +32,14 @@ import { renderToString } from '../src/runtime/ssr.js'
  *     from being shipped to and evaluated in the browser
  *   - avoids bundling errors when server imports use Node-only modules
  */
-const SERVER_ONLY_KEYS = ['server', 'guard', 'serverTimeout', 'contentType', 'render']
+const SERVER_ONLY_KEYS = ['server', 'meta', 'guard', 'serverTimeout', 'contentType', 'render']
+
+/**
+ * Pulse subpath exports that are server-only (use Node built-ins).
+ * Imports from these paths are removed from client bundles along with any
+ * top-level variable declarations whose right-hand side calls the imported names.
+ */
+const SERVER_ONLY_IMPORTS = ['@invisibleloop/pulse/md']
 
 /**
  * Strip all server-only property declarations from a spec source string.
@@ -46,6 +53,50 @@ function stripServerOnlyKeys(source) {
   return source
 }
 
+/**
+ * Strip import statements for known server-only modules and any top-level
+ * variable declarations that called those imported functions.
+ *
+ * Handles patterns like:
+ *   import { md } from '@invisibleloop/pulse/md'
+ *   const fetchPost = md('src/content/blog/:slug.md')
+ */
+function stripServerOnlyImports(source) {
+  for (const mod of SERVER_ONLY_IMPORTS) {
+    const escaped = mod.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    const importRe = new RegExp(
+      `^[ \\t]*import\\s+(?:\\{[^}]*\\}|[\\w*]+(?:\\s+as\\s+\\w+)?)\\s+from\\s+['"]${escaped}['"]\\s*;?[ \\t]*\\n?`,
+      'gm'
+    )
+
+    // Collect imported binding names before removing the statement
+    const importedNames = new Set()
+    for (const m of source.matchAll(importRe)) {
+      const named = m[0].match(/\{\s*([^}]*)\s*\}/)
+      if (named) {
+        for (const part of named[1].split(',')) {
+          const name = part.trim().split(/\s+as\s+/).pop().trim()
+          if (name) importedNames.add(name)
+        }
+      }
+      const def = m[0].match(/import\s+([\w]+)\s+from/)
+      if (def) importedNames.add(def[1])
+    }
+
+    source = source.replace(importRe, '')
+
+    // Remove top-level: const/let/var X = importedFn(...)
+    for (const name of importedNames) {
+      const declRe = new RegExp(
+        `^[ \\t]*(?:const|let|var)\\s+\\w+\\s*=\\s*${name}\\s*\\([^\\n]*\\)\\s*;?[ \\t]*\\n?`,
+        'gm'
+      )
+      source = source.replace(declRe, '')
+    }
+  }
+  return source
+}
+
 /**
  * Remove a single named property (key + value + optional trailing comma/newline)
  * from a JS source string. Uses a character-level scanner to correctly handle
@@ -265,7 +316,7 @@ function createStripServerPlugin(pagesDir) {
             args.path !== pagesDir.replace(/\/$/, '') + '.js') return undefined
 
         const source   = fs.readFileSync(args.path, 'utf8')
-        const stripped = stripServerOnlyKeys(source)
+        const stripped = stripServerOnlyImports(stripServerOnlyKeys(source))
         return { contents: stripped, loader: 'js' }
       })
     }

package/scripts/strip-server.test.js

@@ -7,13 +7,49 @@
 // Inline the scanner functions (duplicated here to keep test self-contained)
 // ---------------------------------------------------------------------------
 
-const SERVER_ONLY_KEYS = ['server', 'guard', 'serverTimeout', 'contentType', 'render']
+const SERVER_ONLY_KEYS = ['server', 'meta', 'guard', 'serverTimeout', 'contentType', 'render']
+const SERVER_ONLY_IMPORTS = ['@invisibleloop/pulse/md']
 
 function stripServerOnlyKeys(source) {
   for (const key of SERVER_ONLY_KEYS) source = removeObjectKey(source, key)
   return source
 }
 
+function stripServerOnlyImports(source) {
+  for (const mod of SERVER_ONLY_IMPORTS) {
+    const escaped = mod.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+    const importRe = new RegExp(
+      `^[ \\t]*import\\s+(?:\\{[^}]*\\}|[\\w*]+(?:\\s+as\\s+\\w+)?)\\s+from\\s+['"]${escaped}['"]\\s*;?[ \\t]*\\n?`,
+      'gm'
+    )
+    const importedNames = new Set()
+    for (const m of source.matchAll(importRe)) {
+      const named = m[0].match(/\{\s*([^}]*)\s*\}/)
+      if (named) {
+        for (const part of named[1].split(',')) {
+          const name = part.trim().split(/\s+as\s+/).pop().trim()
+          if (name) importedNames.add(name)
+        }
+      }
+      const def = m[0].match(/import\s+([\w]+)\s+from/)
+      if (def) importedNames.add(def[1])
+    }
+    source = source.replace(importRe, '')
+    for (const name of importedNames) {
+      const declRe = new RegExp(
+        `^[ \\t]*(?:const|let|var)\\s+\\w+\\s*=\\s*${name}\\s*\\([^\\n]*\\)\\s*;?[ \\t]*\\n?`,
+        'gm'
+      )
+      source = source.replace(declRe, '')
+    }
+  }
+  return source
+}
+
+function strip(source) {
+  return stripServerOnlyImports(stripServerOnlyKeys(source))
+}
+
 function isInsideString(source, pos) {
   let i = 0
   const stack = []
@@ -124,7 +160,7 @@ function scanTemplateLiteral(src, pos) {
 let pass = 0, fail = 0
 
 function test(label, input, expected) {
-  const got = stripServerOnlyKeys(input).trim()
+  const got = strip(input).trim()
   const exp = expected.trim()
   if (got === exp) {
     console.log('  \u2713 ' + label)
@@ -221,6 +257,42 @@ test('server: inside a double-quoted string is not stripped',
   'export default {\n  route: \'/docs\',\n  view: () => "<pre>server: { data: async () => {} }</pre>"\n}'
 )
 
+test('meta object is stripped (client runtime never reads spec.meta)',
+  `export default {\n  route: '/blog',\n  meta: {\n    title: async (ctx) => fetchPost(ctx).frontmatter.title,\n    styles: ['/pulse-ui.css'],\n  },\n  view: () => ''\n}`,
+  `export default {\n  route: '/blog',\n  view: () => ''\n}`
+)
+
+test('meta: inside a template literal string is not stripped',
+  'export default {\n  view: () => `<pre>meta: { title: \'Home\' }</pre>`\n}',
+  'export default {\n  view: () => `<pre>meta: { title: \'Home\' }</pre>`\n}'
+)
+
+// ---------------------------------------------------------------------------
+// Server-only import stripping
+// ---------------------------------------------------------------------------
+
+console.log('\nServer-only import stripping\n')
+
+test('strips @invisibleloop/pulse/md import and const declaration',
+  `import { md } from '@invisibleloop/pulse/md'\nconst fetchPost = md('src/content/blog.md')\nexport default {\n  route: '/blog',\n  view: () => ''\n}`,
+  `export default {\n  route: '/blog',\n  view: () => ''\n}`
+)
+
+test('strips named import with multiple bindings',
+  `import { md, parseMd } from '@invisibleloop/pulse/md'\nconst post = md('src/content/post.md')\nconst result = parseMd('# Hello')\nexport default {\n  view: () => ''\n}`,
+  `export default {\n  view: () => ''\n}`
+)
+
+test('strips import + const then strips meta that used the const',
+  `import { md } from '@invisibleloop/pulse/md'\nconst fetchPost = md('src/content/trees.md')\nexport default {\n  route: '/blog',\n  meta: {\n    title: async (ctx) => (await fetchPost(ctx)).frontmatter.title,\n    styles: ['/pulse-ui.css'],\n  },\n  server: { post: fetchPost },\n  view: () => ''\n}`,
+  `export default {\n  route: '/blog',\n  view: () => ''\n}`
+)
+
+test('does not strip non-server imports',
+  `import { nav, footer } from '@invisibleloop/pulse/ui'\nexport default {\n  view: () => nav({})\n}`,
+  `import { nav, footer } from '@invisibleloop/pulse/ui'\nexport default {\n  view: () => nav({})\n}`
+)
+
 // ---------------------------------------------------------------------------
 
 console.log(`\n${pass + fail} tests: ${pass} passed, ${fail} failed\n`)

package/src/agent/checklist.md

@@ -4,6 +4,20 @@ Before finishing any spec, verify every point below. Fix anything that fails.
 
 ### Critical
 
+- **`meta` must be a plain object — never a function.** Individual fields (`title`, `description`, `styles`) can be `async (ctx) => value` functions, but `meta` itself is always `{}`.
+
+  ```js
+  // WRONG — meta is not a function factory
+  meta: async (ctx) => ({ title: '...', styles: [...] })
+
+  // CORRECT — meta is a plain object; individual fields are functions
+  meta: {
+    title:       async (ctx) => (await post(ctx)).frontmatter.title,
+    description: async (ctx) => (await post(ctx)).frontmatter.description,
+    styles:      ['/pulse-ui.css', '/app.css'],
+  }
+  ```
+
 - **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
@@ -77,6 +91,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/src/agent/guide-server.md

@@ -256,3 +256,65 @@ shutdown()
 ```
 
 `shutdown()` is idempotent — calling it multiple times is safe.
+
+## Markdown
+
+Pulse has a built-in markdown parser. Use it for any content written in `.md` files — blog posts, documentation, static pages. All parsing happens server-side. Zero browser JS.
+
+### `md(pathPattern)` — file helper
+
+```js
+import { md }    from '@invisibleloop/pulse/md'
+import { prose } from '@invisibleloop/pulse/ui'
+
+const page = md('content/about.md')
+
+export default {
+  route:  '/about',
+  server: { page },
+  view:   (state, { page }) => prose({ content: page.html }),
+}
+```
+
+Returns `{ html, frontmatter }`. `html` goes into `prose()`. `frontmatter` is the parsed `---` block.
+
+### Frontmatter for meta tags
+
+The same fetcher can be called in both `meta` and `server` — the file is only read once per request (cached on `ctx._mdCache`):
+
+```js
+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>`,
+}
+```
+
+Always add `onViewError` on dynamic markdown routes — if the file does not exist the fetcher throws `{ status: 404 }`.
+
+### `parseMd(source)` — string parser
+
+For markdown from a database or API rather than a file:
+
+```js
+import { parseMd } from '@invisibleloop/pulse/md'
+
+server: {
+  post: async (ctx) => {
+    const record = await db.posts.find(ctx.params.id)
+    const { html, frontmatter } = parseMd(record.body)
+    return { html, title: frontmatter.title ?? record.title }
+  }
+}
+```

package/src/agent/guide-spec.md

@@ -4,13 +4,15 @@ Pulse is a spec-first frontend framework. Pages are JS files that export a defau
 
 ```js
 export default {
+  // meta MUST be a plain object — never make meta itself a function.
+  // Individual fields may be strings or (ctx) => value functions (sync or async).
   meta: {
-    title:       'Page Title',             // string or (ctx) => string
-    description: 'Meta description',       // string or (ctx) => string
+    title:       'Page Title',             // string or async (ctx) => string
+    description: 'Meta description',       // string or async (ctx) => string
     styles:      ['/app.css'],             // string[] or (ctx) => string[]
     ogTitle:     'Social title',           // optional — falls back to title
     ogImage:     'https://…/og.jpg',       // optional — 1200×630 recommended
-    canonical:   'https://mysite.com/…',  // optional — string or (ctx, serverState) => string
+    canonical:   'https://mysite.com/…',  // optional — string or (ctx) => string
     schema:      { '@context': 'https://schema.org', '@type': 'WebPage', … },  // optional JSON-LD
   },
   state: { /* initial state */ },

package/src/agent/guide.md

@@ -874,8 +874,8 @@ import { prose } from '@invisibleloop/pulse/ui'
 // CMS rich text field — output directly, fully styled
 prose({ content: server.article.bodyHtml })
 
-// Markdown rendered to HTML
-prose({ content: renderMarkdown(server.post.body) })
+// Markdown rendered to HTML (use md() helper — see Markdown section below)
+prose({ content: server.page.html })
 
 // Larger text (e.g. hero intro)
 prose({ content: server.page.intro, size: 'lg' })
@@ -885,6 +885,109 @@ prose({ content: server.page.intro, size: 'lg' })
 - **`prose()`** — when the HTML comes from outside your spec (CMS, database, markdown). You don't control the tags.
 - **`heading()` / `list()`** — when you're writing the content yourself inside the view template.
 
+---
+
+## Markdown
+
+Pulse has a built-in markdown parser. Use it for static-site content, blog posts, documentation pages, or any content written in `.md` files. Zero browser JS — all parsing happens server-side.
+
+### `md(pathPattern)` — file helper
+
+Import from `@invisibleloop/pulse/md`. Returns an async server fetcher. Use it in `server` and optionally `meta`:
+
+```js
+import { md }    from '@invisibleloop/pulse/md'
+import { prose } from '@invisibleloop/pulse/ui'
+
+const page = md('content/about.md')
+
+export default {
+  route:  '/about',
+  server: { page },
+  view:   (state, { page }) => prose({ content: page.html }),
+}
+```
+
+The fetcher returns `{ html, frontmatter }`. `html` is ready to pass to `prose()`. `frontmatter` is the parsed `---` block.
+
+### Frontmatter for meta tags
+
+**`meta` must be a plain object — never a function.** Individual fields can be `async (ctx) => value`. This is the correct pattern for pulling frontmatter into meta:
+
+```js
+// WRONG — meta cannot be a function factory
+meta: async (ctx) => {
+  const post = await fetchPost(ctx)
+  return { title: post.frontmatter.title, styles: ['/app.css'] }
+}
+
+// CORRECT — meta is a plain object; each field is a function
+meta: {
+  title:       async (ctx) => (await post(ctx)).frontmatter.title,
+  description: async (ctx) => (await post(ctx)).frontmatter.description,
+  styles:      ['/pulse-ui.css', '/app.css'],  // static fields stay as values
+}
+```
+
+Call the same fetcher in both `meta` and `server` — it reads the file only once per request (cached on `ctx._mdCache`):
+
+```js
+const page = md('content/about.md')
+
+export default {
+  route: '/about',
+  meta: {
+    title:       async (ctx) => (await page(ctx)).frontmatter.title,
+    description: async (ctx) => (await page(ctx)).frontmatter.description,
+  },
+  server: { page },
+  view:   (state, { page }) => prose({ content: page.html }),
+}
+```
+
+### Dynamic routes — `:param` placeholders
+
+```js
+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>`,
+}
+```
+
+Always add `onViewError` on dynamic markdown routes — if the file doesn't exist the fetcher throws `{ status: 404 }`.
+
+### `parseMd(source)` — string parser
+
+For markdown that comes from a database or API rather than a file:
+
+```js
+import { parseMd } from '@invisibleloop/pulse/md'
+
+server: {
+  post: async (ctx) => {
+    const record = await db.posts.find(ctx.params.id)
+    const { html, frontmatter } = parseMd(record.body)
+    return { html, title: frontmatter.title ?? record.title }
+  }
+}
+```
+
+### What the parser supports
+
+Headings (with auto anchor IDs), bold/italic/strikethrough, inline code, fenced code blocks with syntax highlighting (js/ts/html/css/bash/json), links, images, ordered + unordered lists (nested), blockquotes, GFM tables, horizontal rules, frontmatter.
+
 ### Attaching Pulse events to components
 
 Pass events via `attrs` — must be an object, not a string:

package/src/cli/dev.js

@@ -25,6 +25,10 @@ const ROOT = rootArg !== -1
   ? path.resolve(args[rootArg + 1])
   : process.cwd()
 
+// Ensure process.cwd() === ROOT so relative paths in specs (e.g. md('src/content/foo.md'))
+// resolve to the project root, not wherever the parent process was launched from.
+if (process.cwd() !== ROOT) process.chdir(ROOT)
+
 let _config = {}
 const configPath = path.join(ROOT, 'pulse.config.js')
 if (fs.existsSync(configPath)) {

package/src/cli/scaffold.js

@@ -220,8 +220,6 @@ import { button, heading, iconMinus, iconPlus } from '@invisibleloop/pulse/ui'
 export default {
   route: '/',
 
-  hydrate: '/src/pages/home.js',
-
   meta: {
     title:       '${appName}',
     description: '${appName} — built with Pulse.',

package/src/cli/start.js

@@ -18,6 +18,7 @@ const rootArg = args.indexOf('--root')
 const portArg = args.indexOf('--port')
 
 const ROOT = rootArg !== -1 ? path.resolve(args[rootArg + 1]) : process.cwd()
+if (process.cwd() !== ROOT) process.chdir(ROOT)
 const PUBLIC_DIR = path.join(ROOT, 'public')
 const DIST_DIR   = path.join(PUBLIC_DIR, 'dist')