@invisibleloop/pulse 0.20.11 → 0.20.20

package/docs/src/pages/hydration.js

@@ -1,108 +0,0 @@
-import { renderLayout, h1, lead, section, sub, codeBlock, callout, table } from '../lib/layout.js'
-import { prevNext } from '../lib/nav.js'
-import { highlight } from '../lib/highlight.js'
-
-const { prev, next } = prevNext('/hydration')
-
-export default {
-  route: '/hydration',
-  meta: {
-    theme:       'light',
-    title: 'Hydration — Pulse Docs',
-    description: 'How Pulse hydrates server-rendered HTML on the client — automatic hydration, mount(), and production bundles.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  state: {},
-  view: () => renderLayout({
-    currentHref: '/hydration',
-    prev,
-    next,
-    content: `
-      ${h1('Hydration')}
-      ${lead('Hydration in Pulse is automatic. Specs with <code>mutations</code>, <code>actions</code>, or <code>persist</code> are hydrated automatically — Pulse binds events to the server-rendered HTML without re-rendering it. Purely server-rendered specs get zero JavaScript sent to the browser.')}
-
-      ${section('enabling', 'How hydration works')}
-      <p>Pass spec files as <code>URL</code> objects to <code>createServer</code>. Pulse detects whether each spec needs client-side interactivity and, if so, derives the browser-importable path automatically — no <code>hydrate</code> field needed in the spec:</p>
-      ${codeBlock(highlight(`// server.js
-await createServer(
-  [
-    new URL('./src/pages/counter.js', import.meta.url),  // has mutations → auto-hydrated
-    new URL('./src/pages/about.js',   import.meta.url),  // no mutations  → zero JS
-  ],
-  { port: 3000, root: new URL('.', import.meta.url) }
-)
-
-// src/pages/counter.js — no hydrate field needed
-export default {
-  route: '/counter',
-  state: { count: 0 },
-  mutations: {
-    increment: (state) => ({ count: state.count + 1 }),
-    decrement: (state) => ({ count: state.count - 1 }),
-  },
-  view: (state) => \`
-    <div>
-      <button data-event="decrement">-</button>
-      <span>\${state.count}</span>
-      <button data-event="increment">+</button>
-    </div>
-  \`,
-}`, 'js'))}
-
-      ${section('dev-bootstrap', 'Development bootstrap')}
-      <p>In development Pulse emits an inline bootstrap script that imports the spec and runtime source files directly — no build step required:</p>
-      ${codeBlock(highlight(`<script type="module">
-  import spec from '/src/pages/counter.js'
-  import { mount } from '/src/runtime/index.js'
-  import { initNavigation } from '/src/runtime/navigate.js'
-  mount(spec, root, window.__PULSE_SERVER__ || {}, { ssr: true })
-  initNavigation(root, mount)
-</script>`, 'html'))}
-      <p>This imports the spec and runtime source files directly — no build step required for development.</p>
-
-      ${section('production', 'Production bundles')}
-      <p>Run <code>npm run build</code> to generate production bundles. This creates content-hashed files in <code>public/dist/</code> and a <code>manifest.json</code> mapping spec hydrate paths to bundle paths.</p>
-      ${codeBlock(highlight(`# Generated by npm run build
-public/dist/
-  runtime-abc123.js          # shared runtime (~3.8 kB brotli)
-  counter.boot-def456.js     # per-page spec bundle (~0.4–0.9 kB brotli)
-  manifest.json              # { '/src/pages/counter.js': '/dist/counter.boot-def456.js' }`, 'bash'))}
-      <p>When Pulse detects a manifest (via <code>staticDir</code> auto-detection or explicit <code>manifest</code> option), it resolves the auto-derived hydrate path to the bundle path and emits a single <code>&lt;script src&gt;</code> tag instead of the inline bootstrap:</p>
-      ${codeBlock(highlight(`<script type="module" src="/dist/counter.boot-def456.js"></script>`, 'html'))}
-
-      ${section('ssr-true', 'The { ssr: true } option')}
-      <p>The bootstrap script calls <code>mount(spec, root, serverState, { ssr: true })</code>. This tells the runtime to skip the initial re-render and bind event listeners to the existing DOM only.</p>
-      <p>This is what keeps LCP fast. The server-painted HTML is the LCP element. The JavaScript binds events without touching the DOM — no flash, no layout shift, no JS-rendered replacement.</p>
-      ${callout('warning', 'Never set <code>{ ssr: false }</code> on a server-rendered page. It re-renders the entire DOM on mount, replacing the server-painted HTML — causing a visible flash and pushing LCP to 400–600ms.')}
-
-      ${section('mount', 'mount()')}
-      <p>The <code>mount</code> function attaches the Pulse runtime to a DOM element:</p>
-      ${codeBlock(highlight(`import { mount } from '@invisibleloop/pulse/runtime'
-
-mount(
-  spec,          // the page spec
-  rootEl,        // the DOM element to mount into
-  serverState,   // window.__PULSE_SERVER__ (server data from SSR)
-  { ssr: true }  // skip re-render on first mount
-)`, 'js'))}
-      <p>After mount, all <code>data-event</code> and <code>data-action</code> attributes in the DOM are wired to the spec's mutations and actions. State updates trigger a full view re-render via <code>innerHTML</code> replacement.</p>
-
-      ${section('no-hydrate', 'Pages without hydration')}
-      <p>Specs with no <code>mutations</code>, <code>actions</code>, or <code>persist</code> automatically get zero JavaScript — no runtime overhead, no hydration cost. This is the correct default for:</p>
-      <ul>
-        <li>Documentation pages</li>
-        <li>Marketing/landing pages</li>
-        <li>Blog posts and articles</li>
-        <li>Any page with no client-side interactivity</li>
-      </ul>
-      ${callout('tip', 'Many pages that appear to need JavaScript can be handled server-side with <a href="/routing">routing</a> and <a href="/server-data">server data</a>. Keep specs free of mutations and actions wherever possible.')}
-
-      ${section('server-state', 'Passing server state to the client')}
-      <p>Server data fetched via <code>server.data()</code> is serialised into the page HTML as <code>window.__PULSE_SERVER__</code>. The client runtime reads this on mount, making server data available to the view during client re-renders without an additional network request.</p>
-      ${codeBlock(highlight(`// Emitted in the page HTML
-<script id="__PULSE_SERVER__" type="application/json">
-  {"product":{"id":1,"name":"Widget","price":9.99}}
-</script>`, 'html'))}
-    `,
-  }),
-}

package/docs/src/pages/images.js

@@ -1,120 +0,0 @@
-import { renderLayout, h1, lead, section, sub, codeBlock, callout, table } from '../lib/layout.js'
-import { prevNext } from '../lib/nav.js'
-import { highlight } from '../lib/highlight.js'
-
-const { prev, next } = prevNext('/images')
-
-export default {
-  route: '/images',
-  meta: {
-    theme:       'light',
-    title: 'Images — Pulse Docs',
-    description: 'The img() and picture() helpers for optimised, CLS-free image markup.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/images',
-    prev,
-    next,
-    content: `
-      ${h1('Images')}
-      ${lead('The <code>img()</code> and <code>picture()</code> helpers generate image markup that prevents CLS by requiring dimensions and handles loading priority correctly. Pulse targets 0.00 CLS — these helpers enforce the attributes that make that possible.')}
-
-      ${section('import', 'Importing')}
-      ${codeBlock(highlight(`// In your page spec or component
-import { img, picture } from '@invisibleloop/pulse/image'`, 'js'))}
-
-      ${section('img', 'img(options)')}
-      <p>Generates an optimised <code>&lt;img&gt;</code> element:</p>
-      ${codeBlock(highlight(`img({
-  src:      '/images/hero.jpg',
-  alt:      'A hero image showing our product',
-  width:    1200,
-  height:   630,
-  priority: true,    // → eager loading + high fetchpriority
-})`, 'js'))}
-      <p>Output:</p>
-      ${codeBlock(highlight(`<img src="/images/hero.jpg" alt="A hero image showing our product" width="1200" height="630" loading="eager" decoding="async" fetchpriority="high">`, 'html'))}
-
-      ${section('img-options', 'img() options')}
-      ${table(
-        ['Option', 'Type', 'Required', 'Description'],
-        [
-          ['<code>src</code>', '<code>string</code>', 'Yes', 'Image URL.'],
-          ['<code>alt</code>', '<code>string</code>', 'Yes', 'Alt text. Required for accessibility. Use an empty string for decorative images.'],
-          ['<code>width</code>', '<code>number</code>', 'Recommended', 'Intrinsic width in pixels. Prevents CLS by reserving layout space.'],
-          ['<code>height</code>', '<code>number</code>', 'Recommended', 'Intrinsic height in pixels. Prevents CLS.'],
-          ['<code>priority</code>', '<code>boolean</code>', 'No', 'If true: <code>loading="eager"</code> + <code>fetchpriority="high"</code>. Use for LCP images. Default: <code>false</code>.'],
-          ['<code>class</code>', '<code>string</code>', 'No', 'CSS class applied to the <code>&lt;img&gt;</code> element.'],
-        ]
-      )}
-
-      ${callout('warning', '<code>width</code> and <code>height</code> are required to prevent Cumulative Layout Shift. Without them the browser cannot reserve layout space before the image loads. Pulse targets 0.00 CLS — omitting these attributes breaks that guarantee.')}
-
-      ${section('picture', 'picture(options)')}
-      <p>Generates a <code>&lt;picture&gt;</code> element with modern format sources and a fallback <code>&lt;img&gt;</code>. Use this to serve AVIF or WebP to browsers that support them, with JPEG/PNG as the fallback:</p>
-      ${codeBlock(highlight(`picture({
-  src:      '/images/hero.jpg',      // fallback
-  alt:      'Hero image',
-  width:    1200,
-  height:   630,
-  priority: true,
-  sources: [
-    { src: '/images/hero.avif', type: 'image/avif' },
-    { src: '/images/hero.webp', type: 'image/webp' },
-  ],
-})`, 'js'))}
-      <p>Output:</p>
-      ${codeBlock(highlight(`<picture>
-  <source srcset="/images/hero.avif" type="image/avif">
-  <source srcset="/images/hero.webp" type="image/webp">
-  <img src="/images/hero.jpg" alt="Hero image" width="1200" height="630" loading="eager" decoding="async" fetchpriority="high">
-</picture>`, 'html'))}
-
-      ${section('picture-options', 'picture() options')}
-      ${table(
-        ['Option', 'Type', 'Description'],
-        [
-          ['<code>src</code>', '<code>string</code>', 'Fallback image URL (JPEG/PNG for universal compatibility).'],
-          ['<code>alt</code>', '<code>string</code>', 'Alt text — shared by the inner <code>&lt;img&gt;</code>.'],
-          ['<code>width</code>', '<code>number</code>', 'Intrinsic width — applied to inner <code>&lt;img&gt;</code>.'],
-          ['<code>height</code>', '<code>number</code>', 'Intrinsic height — applied to inner <code>&lt;img&gt;</code>.'],
-          ['<code>priority</code>', '<code>boolean</code>', 'If true: eager loading + high priority.'],
-          ['<code>class</code>', '<code>string</code>', 'CSS class on the inner <code>&lt;img&gt;</code>.'],
-          ['<code>sources</code>', '<code>{src, type}[]</code>', 'Modern format sources in preference order (AVIF first, WebP second).'],
-        ]
-      )}
-
-      ${section('priority', 'When to use priority')}
-      <p>Set <code>priority: true</code> on the <strong>Largest Contentful Paint (LCP) element</strong> — typically the hero image above the fold. This tells the browser to load it with high priority, improving LCP.</p>
-      <p>Every other image should omit <code>priority</code> (defaults to lazy loading with <code>loading="lazy"</code>). Lazy images are not fetched until they approach the viewport — reducing initial page weight and speeding up load time.</p>
-      ${callout('tip', 'Only one image per page should have <code>priority: true</code>. Using it on multiple images defeats the purpose — every image becomes "high priority" which is the same as no image being prioritised.')}
-
-      ${section('in-view', 'Using in a view')}
-      ${codeBlock(highlight(`import { img, picture } from '@invisibleloop/pulse/image'
-
-export default {
-  route: '/blog/:slug',
-  server: {
-    data: async (ctx) => ({ post: await db.posts.findBySlug(ctx.params.slug) }),
-  },
-  view: (state, server) => \`
-    <article>
-      \${picture({
-        src:      server.post.heroImage,
-        alt:      server.post.heroAlt,
-        width:    1200,
-        height:   630,
-        priority: true,
-        sources:  [
-          { src: server.post.heroImage.replace('.jpg', '.avif'), type: 'image/avif' },
-          { src: server.post.heroImage.replace('.jpg', '.webp'), type: 'image/webp' },
-        ],
-      })}
-      <h1>\${server.post.title}</h1>
-    </article>
-  \`,
-}`, 'js'))}
-    `,
-  }),
-}

package/docs/src/pages/markdown.js

@@ -1,156 +0,0 @@
-import { renderLayout, h1, lead, section, codeBlock, callout, table } from '../lib/layout.js'
-import { prevNext } from '../lib/nav.js'
-import { highlight } from '../lib/highlight.js'
-
-const { prev, next } = prevNext('/markdown')
-
-export default {
-  route: '/markdown',
-  meta: {
-    theme:       'light',
-    title: 'Markdown — Pulse Docs',
-    description: 'Render markdown files as pages with syntax-highlighted code blocks, frontmatter, and the prose component.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/markdown',
-    prev,
-    next,
-    content: `
-      ${h1('Markdown')}
-      ${lead('Pulse includes a built-in markdown parser. Write content in <code>.md</code> files, load them with the <code>md()</code> helper, and render with the <code>prose</code> component. No external dependencies — zero browser bytes.')}
-
-      ${section('basic', 'Basic usage')}
-      <p>Import <code>md</code> from <code>@invisibleloop/pulse/md</code> and call it with a file path. It returns an async server fetcher — use it in <code>server</code> and optionally in <code>meta</code>:</p>
-      ${codeBlock(highlight(`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 }),
-}`, 'js'))}
-      <p>The fetcher returns <code>{ html, frontmatter }</code>. The <code>html</code> is ready to pass directly to <code>prose()</code>. The <code>frontmatter</code> object contains the parsed key/value pairs from the <code>---</code> block at the top of the file.</p>
-
-      ${section('frontmatter', 'Frontmatter')}
-      <p>Add a <code>---</code> block at the top of any <code>.md</code> file to define metadata. Use the values in <code>meta</code> for SEO:</p>
-      ${codeBlock(highlight(`---
-title: About Us
-description: Learn about our company
-date: 2024-01-15
----
-
-# About Us
-
-Welcome to our company…`, 'bash'))}
-      ${codeBlock(highlight(`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 }),
-}`, 'js'))}
-      ${callout('tip', 'Calling <code>page(ctx)</code> in both <code>meta</code> and <code>server</code> reads the file only once per request — the result is cached on <code>ctx._mdCache</code> automatically.')}
-
-      ${section('dynamic', 'Dynamic routes')}
-      <p>Use <code>:param</code> placeholders in the path — they are resolved from <code>ctx.params</code> at request time:</p>
-      ${codeBlock(highlight(`import { md }    from '@invisibleloop/pulse/md'
-import { prose } from '@invisibleloop/pulse/ui'
-
-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: (err) => \`
-    <main id="main-content">
-      <p>Post not found.</p>
-    </main>
-  \`,
-}`, 'js'))}
-      ${callout('note', 'If the file does not exist, the fetcher throws with <code>{ status: 404 }</code>. Define <code>onViewError</code> on dynamic-route pages to render a friendly not-found message instead of a 500.')}
-
-      ${section('parseMd', 'parseMd()')}
-      <p>For cases where you already have a markdown string (from a database, API, or generated content), use <code>parseMd</code> directly instead of the file helper:</p>
-      ${codeBlock(highlight(`import { parseMd } from '@invisibleloop/pulse/md'
-import { prose }   from '@invisibleloop/pulse/ui'
-
-export default {
-  route: '/post/:id',
-  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 }
-    }
-  },
-  view: (state, { post }) => prose({ content: post.html }),
-}`, 'js'))}
-
-      ${section('what-renders', 'What the parser renders')}
-      ${table(
-        ['Markdown', 'Output'],
-        [
-          ['<code># Heading</code> through <code>###### Heading</code>', '<code>&lt;h1&gt;</code>–<code>&lt;h6&gt;</code> with auto <code>id</code> anchors'],
-          ['<code>**bold**</code>, <code>*italic*</code>, <code>~~strike~~</code>', '<code>&lt;strong&gt;</code>, <code>&lt;em&gt;</code>, <code>&lt;del&gt;</code>'],
-          ['<code>`inline code`</code>', '<code>&lt;code&gt;</code>'],
-          ['Fenced code block with language tag', '<code>&lt;pre&gt;&lt;code class="language-X"&gt;</code> with syntax highlighting'],
-          ['<code>[text](url)</code>, <code>![alt](url)</code>', '<code>&lt;a&gt;</code>, <code>&lt;img&gt;</code>'],
-          ['<code>- item</code>, <code>1. item</code>', '<code>&lt;ul&gt;</code>, <code>&lt;ol&gt;</code> (nested lists supported)'],
-          ['<code>&gt; quote</code>', '<code>&lt;blockquote&gt;</code>'],
-          ['GFM table (<code>| col | col |</code>)', '<code>&lt;table&gt;</code> with <code>&lt;thead&gt;</code> and <code>&lt;tbody&gt;</code>'],
-          ['<code>---</code> (three or more)', '<code>&lt;hr&gt;</code>'],
-        ]
-      )}
-
-      ${section('syntax-highlighting', 'Syntax highlighting')}
-      <p>Fenced code blocks with a language tag are syntax-highlighted automatically — no client JS required. The highlighting runs on the server and emits <code>&lt;span class="tok-*"&gt;</code> elements. The colour tokens are defined in <code>pulse-ui.css</code> and respect the active theme.</p>
-      ${codeBlock(highlight(`\`\`\`js
-const greeting = 'Hello, world'
-console.log(greeting)
-\`\`\``, 'bash'))}
-      <p>Supported languages:</p>
-      ${table(
-        ['Tag(s)', 'Highlighter'],
-        [
-          ['<code>js</code>, <code>javascript</code>, <code>ts</code>, <code>typescript</code>, <code>jsx</code>, <code>tsx</code>', 'JavaScript / TypeScript'],
-          ['<code>html</code>, <code>xml</code>, <code>svg</code>, <code>vue</code>, <code>svelte</code>', 'HTML / XML'],
-          ['<code>css</code>, <code>scss</code>, <code>less</code>', 'CSS'],
-          ['<code>bash</code>, <code>sh</code>, <code>shell</code>, <code>zsh</code>', 'Bash / Shell'],
-          ['<code>json</code>, <code>jsonc</code>', 'JSON'],
-          ['Any other tag', 'Plain text (escaped, no colour tokens)'],
-        ]
-      )}
-
-      ${section('prose', 'The prose component')}
-      <p>The <code>prose</code> component is designed specifically for markdown output. It applies typographic styles to all descendant elements — headings, paragraphs, lists, blockquotes, code blocks, tables, images — without requiring any classes on the elements themselves:</p>
-      ${codeBlock(highlight(`import { prose } from '@invisibleloop/pulse/ui'
-
-// Wrap the html from parseMd or md()
-prose({ content: page.html })
-
-// Optional size modifier
-prose({ content: page.html, size: 'lg' })  // 'sm' | 'base' | 'lg'`, 'js'))}
-      ${callout('note', 'The <code>content</code> slot is injected as raw HTML — only pass server-side content that you trust. Never pass user-submitted HTML directly; sanitise it first.')}
-
-      ${section('url-paths', 'Using URL paths')}
-      <p>Pass a <code>URL</code> object to resolve paths relative to the spec file rather than the process working directory:</p>
-      ${codeBlock(highlight(`const page = md(new URL('./content/about.md', import.meta.url))`, 'js'))}
-    `,
-  }),
-}

package/docs/src/pages/meta.js

@@ -1,193 +0,0 @@
-import { renderLayout, h1, lead, section, sub, codeBlock, callout, table } from '../lib/layout.js'
-import { prevNext } from '../lib/nav.js'
-import { highlight } from '../lib/highlight.js'
-
-const { prev, next } = prevNext('/meta')
-
-export default {
-  route: '/meta',
-  meta: {
-    theme:       'light',
-    title: 'Metadata & SEO — Pulse Docs',
-    description: 'How to configure page metadata, Open Graph tags, and structured data in Pulse.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/meta',
-    prev,
-    next,
-    content: `
-      ${h1('Metadata & SEO')}
-      ${lead('The <code>meta</code> field declares everything that appears in the <code>&lt;head&gt;</code> — title, description, stylesheets, Open Graph tags, and structured data. All metadata is rendered server-side, so crawlers and social media scrapers see the final HTML without executing JavaScript.')}
-
-      ${section('basics', 'Basic metadata')}
-      ${codeBlock(highlight(`export default {
-  route: '/about',
-  meta: {
-    title:       'About Us — Acme Corp',
-    description: 'Learn about the team behind Acme Corp.',
-    styles:      ['/app.css'],
-  },
-  view: () => \`<h1>About Us</h1>\`,
-}`, 'js'))}
-      <p>This generates:</p>
-      ${codeBlock(highlight(`<title>About Us — Acme Corp</title>
-<meta name="description" content="Learn about the team behind Acme Corp.">
-<link rel="stylesheet" href="/app.css">`, 'html'))}
-
-      ${section('all-fields', 'All meta fields')}
-      ${table(
-        ['Field', 'Type', 'Description'],
-        [
-          ['<code>title</code>', '<code>string</code>', 'Page title — appears in the browser tab and search results.'],
-          ['<code>description</code>', '<code>string</code>', 'Meta description — appears in search engine snippets. Keep under 160 characters.'],
-          ['<code>styles</code>', '<code>string[]</code>', 'Array of stylesheet URLs — each emits a <code>&lt;link rel="stylesheet"&gt;</code> tag.'],
-          ['<code>ogTitle</code>', '<code>string</code>', 'Open Graph title. If omitted, falls back to <code>title</code>.'],
-          ['<code>ogImage</code>', '<code>string</code>', 'Open Graph image URL — shown when the page is shared on social media.'],
-          ['<code>schema</code>', '<code>object</code>', 'JSON-LD structured data object — emitted as a <code>&lt;script type="application/ld+json"&gt;</code> tag.'],
-          ['<code>canonical</code>', '<code>string | (ctx, serverState) => string</code>', 'Canonical URL — overrides the auto-derived canonical. Accepts a function for dynamic values.'],
-        ]
-      )}
-
-      ${section('open-graph', 'Open Graph')}
-      <p>Open Graph tags control how the page appears when shared on social media (Twitter/X, Facebook, LinkedIn, Slack, etc.):</p>
-      ${codeBlock(highlight(`meta: {
-  title:       'My Product — Acme Corp',
-  description: 'The best product ever made.',
-  ogTitle:     'My Product',                         // shorter for social
-  ogImage:     'https://acme.com/og/my-product.jpg', // 1200×630 recommended
-}`, 'js'))}
-      <p>Generated tags:</p>
-      ${codeBlock(highlight(`<meta property="og:title" content="My Product">
-<meta property="og:description" content="The best product ever made.">
-<meta property="og:image" content="https://acme.com/og/my-product.jpg">
-<meta name="twitter:card" content="summary_large_image">
-<meta name="twitter:title" content="My Product">
-<meta name="twitter:image" content="https://acme.com/og/my-product.jpg">`, 'html'))}
-      ${callout('tip', 'Use an absolute URL for <code>ogImage</code> — social media crawlers need the full URL to fetch the image. Recommended size: 1200×630 pixels.')}
-
-      ${section('structured-data', 'Structured data (ld+json)')}
-      <p>The <code>schema</code> field accepts a plain object conforming to <a href="https://schema.org" target="_blank" rel="noopener" aria-label="schema.org (opens in new tab)">schema.org</a> vocabulary. Pulse serialises it as a <code>&lt;script type="application/ld+json"&gt;</code> tag in the head:</p>
-      ${codeBlock(highlight(`meta: {
-  title: 'How to make sourdough — My Blog',
-  schema: {
-    '@context': 'https://schema.org',
-    '@type':    'Article',
-    headline:   'How to make sourdough',
-    author: {
-      '@type': 'Person',
-      name:    'Jane Smith',
-    },
-    datePublished: '2025-01-15',
-    image:         'https://myblog.com/sourdough.jpg',
-  },
-}`, 'js'))}
-      <p>Common schema types:</p>
-      ${table(
-        ['@type', 'Use for'],
-        [
-          ['<code>WebSite</code>', 'The homepage or site root'],
-          ['<code>WebPage</code>', 'General pages'],
-          ['<code>Article</code>', 'Blog posts, news articles'],
-          ['<code>Product</code>', 'E-commerce product pages'],
-          ['<code>FAQPage</code>', 'FAQ pages (enables rich results in Google)'],
-          ['<code>BreadcrumbList</code>', 'Breadcrumb navigation'],
-          ['<code>Organization</code>', 'Company/brand information'],
-        ]
-      )}
-
-      ${section('canonical', 'Canonical URLs')}
-      <p>Pulse automatically derives a canonical URL from the request and emits it as a <code>&lt;link rel="canonical"&gt;</code> tag on every page. In most cases no configuration is needed.</p>
-      <p>Use <code>meta.canonical</code> to override — for example, on paginated pages or when content is accessible at more than one URL. A plain string is resolved once at startup:</p>
-      ${codeBlock(highlight(`// Paginated blog — pages 2, 3, … all canonicalise to the first page
-meta: {
-  title:     'Blog — Page 2',
-  canonical: 'https://mysite.com/blog',
-}`, 'js'))}
-      <p>Pass a function to derive the canonical from the request context or server data. The function receives <code>(ctx, serverState)</code>:</p>
-      ${codeBlock(highlight(`// Canonical from a URL param
-meta: {
-  canonical: (ctx) => \`https://mysite.com/products/\${ctx.params.slug}\`,
-}
-
-// Canonical from a server fetcher result (e.g. canonical slug from a database lookup)
-meta: {
-  canonical: (ctx, serverState) => \`https://mysite.com/products/\${serverState.product.slug}\`,
-}`, 'js'))}
-      ${callout('note', '<strong>Streaming caveat:</strong> when <code>stream: true</code> (the default), the <code>&lt;head&gt;</code> is written before server fetchers resolve, so <code>serverState</code> will be <code>null</code> for streaming responses. If your canonical depends on server data, set <code>stream: false</code> on that spec, or derive it from <code>ctx.params</code> instead.')}
-
-      ${section('sitemap', 'Sitemap & robots.txt')}
-      <p>Pulse generates <code>/sitemap.xml</code> and <code>/robots.txt</code> from the registered routes — enable it with one option:</p>
-      ${codeBlock(highlight(`await createServer(pages, {
-  sitemap: true,                          // or { origin: 'https://mysite.com' } to pin the origin
-})`, 'js'))}
-      <p>Static page routes are included automatically. Excluded by default: the <code>route: '*'</code> not-found page, raw content specs, guarded pages (set <code>sitemap: true</code> on the spec to opt one in), and any page with <code>sitemap: false</code>.</p>
-      <p>Dynamic <code>:param</code> routes can't be enumerated automatically — give them a <code>sitemap</code> enumerator or they are skipped (the server logs a startup hint listing them):</p>
-      ${codeBlock(highlight(`export default {
-  route: '/blog/:slug',
-  sitemap: async () => {
-    const posts = await db.posts.allPublished()
-    return posts.map(p => ({ path: \`/blog/\${p.slug}\`, lastmod: p.updatedAt }))
-  },
-  // entries are '/path' strings or { path, lastmod } objects
-}`, 'js'))}
-      ${table(
-        ['Where', 'Value', 'Effect'],
-        [
-          ['<code>createServer</code>', '<code>sitemap: true | { origin }</code>', 'Enables generation. Origin defaults to the request host; pin it for multi-domain setups.'],
-          ['<code>createServer</code>', '<code>robots: false | string</code>', 'Disable robots.txt, or serve a custom string verbatim. Default auto-generates allow-all + the Sitemap line.'],
-          ['spec', '<code>sitemap: false</code>', 'Exclude this page.'],
-          ['spec', '<code>sitemap: true</code>', 'Include a guarded page that would be excluded by default.'],
-          ['spec', '<code>sitemap: array | function</code>', 'Enumerate URLs — required for dynamic routes.'],
-        ]
-      )}
-      ${callout('note', 'A physical <code>sitemap.xml</code> or <code>robots.txt</code> in <code>staticDir</code> always wins over the generated one — drop a file in <code>public/</code> to take full manual control. For fully hand-built XML, see <a href="/raw-responses#sitemap">Raw Responses</a>.')}
-
-      ${section('styles', 'Stylesheets')}
-      <p>The <code>styles</code> array accepts any number of stylesheet URLs. They are emitted as <code>&lt;link rel="stylesheet"&gt;</code> tags in the <code>&lt;head&gt;</code> in the order declared:</p>
-      ${codeBlock(highlight(`meta: {
-  styles: [
-    '/app.css',
-    '/fonts.css',
-    'https://fonts.googleapis.com/css2?family=Inter:wght@400;600&display=swap',
-  ],
-}`, 'js'))}
-      ${callout('note', 'For maximum performance, host your own fonts rather than using Google Fonts. External stylesheet requests add render-blocking latency and a DNS lookup.')}
-
-      ${section('vibe', 'Personality presets (meta.vibe)')}
-      <p>Set <code>meta.vibe</code> to apply a personality preset that adjusts typography, border radius, and letter-spacing across all components on the page. The preset sets a <code>data-vibe</code> attribute on <code>&lt;body&gt;</code> — pair it with a <code>theme.css</code> for complete brand expression.</p>
-      ${codeBlock(highlight(`export default {
-  route: '/landing',
-  meta: {
-    vibe:   'playful',
-    styles: ['/pulse-ui.css', '/theme.css'],
-  },
-}`, 'js'))}
-      ${table(
-        ['Vibe', 'Character', 'Best for'],
-        [
-          ['<code>warm</code>',       'Friendly, rounded (14px), humanist feel',                   'Local businesses, wellness, food, services'],
-          ['<code>editorial</code>',  'Serif display, zero radius, tight tracking',                  'Publications, blogs, journalism, literary'],
-          ['<code>playful</code>',    'Extra-large radius (22px), loose spacing',                    'Consumer apps, kids, lifestyle, creators'],
-          ['<code>minimal</code>',    'Ultra-low radius (2px), refined whitespace',                  'Portfolios, luxury, developer tools'],
-          ['<code>bold</code>',       'Tight tracking, strong presence',                             'Agencies, startups, sports'],
-          ['<code>brutalist</code>',  'Zero radius, oversized Arial Black / Impact headings',         'Art, fashion, counter-culture, zines'],
-          ['<code>retro</code>',      'Slab serif, medium radius (8px), nostalgic geometry',          'Craft, breweries, vintage, heritage brands'],
-          ['<code>corporate</code>',  'Conservative radius (4px), tight tracking, professional',     'B2B, finance, legal, consultancies'],
-          ['<code>neon</code>',       'Monospace headline, futuristic, sharp edges',                  'Gaming, crypto, dark-tech, cyberpunk'],
-          ['<code>paper</code>',      'Organic radius (10px), serif body, tactile feel',              'Journals, bookshops, newsletters, diaries'],
-        ]
-      )}
-      ${callout('tip', 'Vibe only adjusts shape and type tokens — it does not set colours. Add a <code>theme.css</code> that defines <code>--ui-accent</code>, <code>--color-bg</code>, and other colour tokens to complete the personality.')}
-
-      ${section('seo-tips', 'SEO tips')}
-      <ul>
-        <li>Write a unique <code>title</code> and <code>description</code> for every page — duplicate metadata prevents pages from competing in search results.</li>
-        <li>Keep descriptions under 160 characters — longer values are truncated.</li>
-        <li>Use structured data to qualify for Google rich results.</li>
-        <li>All metadata is in the server-rendered HTML — search engines and social scrapers do not need to execute JavaScript to read it.</li>
-        <li>Pulse targets 100/100 Lighthouse SEO out of the box. Run <code>/pulse-report</code> after new pages to confirm.</li>
-      </ul>
-    `,
-  }),
-}