@invisibleloop/pulse 0.20.11 → 0.20.20

package/docs/src/pages/prompt-examples.js

@@ -1,186 +0,0 @@
-import { renderLayout, h1, lead } from '../lib/layout.js'
-import { prevNext } from '../lib/nav.js'
-
-const { prev, next } = prevNext('/prompt-examples')
-
-function promptCard({ tag, prompt, produces }) {
-  return `
-    <div class="prompt-card">
-      <div class="prompt-tag">${tag}</div>
-      <blockquote class="prompt-text">${prompt}</blockquote>
-      <p class="prompt-produces">${produces}</p>
-    </div>`
-}
-
-function promptGroup(title, cards) {
-  return `
-    <div class="prompt-group">
-      <h3 class="prompt-group-title">${title}</h3>
-      <div class="prompt-grid">
-        ${cards.map(promptCard).join('')}
-      </div>
-    </div>`
-}
-
-export default {
-  route: '/prompt-examples',
-  meta: {
-    theme:       'light',
-    title: 'Prompt Examples — Pulse Docs',
-    description: 'Real prompts for building Pulse pages with your AI agent — from creating pages to authentication, performance audits, and integrations.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/prompt-examples',
-    prev,
-    next,
-    content: `
-      ${h1('Prompt Examples')}
-      ${lead('These prompts produce correct Pulse specs because the framework constrains the output. The agent works within a defined structure — there is no ambiguity about where state lives, how data is fetched, or how validation is wired.')}
-
-      ${promptGroup('Creating pages', [
-        {
-          tag: 'New page',
-          prompt: 'Create a page at /about with a heading, a short paragraph about the company, and a link back to the home page.',
-          produces: 'A static page spec with <code>route</code>, <code>meta</code>, and a <code>view</code> returning the HTML.',
-        },
-        {
-          tag: 'Dynamic route',
-          prompt: 'Create a blog post page at /posts/:slug. It should fetch the post from the database by slug and display the title, published date, and body content. If no post is found, return a 404.',
-          produces: 'A spec with a parameterised <code>route</code>, a <code>server.data</code> fetcher using <code>ctx.params.slug</code>, and a 404 raw response if the post is missing.',
-        },
-        {
-          tag: 'Listing page',
-          prompt: 'Create a paginated list of articles at /articles. Read the ?page query parameter to fetch the right slice. Show 10 articles per page with previous and next links.',
-          produces: 'A spec with <code>server.data</code> reading <code>ctx.query.page</code>, pagination state, and prev/next links rendered in the view.',
-        },
-      ])}
-
-      ${promptGroup('State & interactions', [
-        {
-          tag: 'Live filter',
-          prompt: 'Add a search input to the /products page that filters the visible product list as the user types. Keep the full product list in server data and filter it in the view.',
-          produces: 'A mutation bound to <code>data-event="input:setQuery"</code> that updates a <code>query</code> state field, with the view filtering <code>server.data.products</code> against it.',
-        },
-        {
-          tag: 'Toggle',
-          prompt: 'Add a show/hide toggle to the FAQ page. Each question should expand its answer when clicked and collapse when clicked again.',
-          produces: 'An <code>openId</code> state field and a <code>toggle</code> mutation. The view renders answers conditionally based on whether their id matches <code>openId</code>.',
-        },
-        {
-          tag: 'Tabs',
-          prompt: 'The /dashboard page has three tabs: Overview, Activity, and Settings. Clicking a tab should show its panel and hide the others without a page reload.',
-          produces: 'An <code>activeTab</code> state field, a <code>setTab</code> mutation, and tab panels rendered conditionally in the view.',
-        },
-      ])}
-
-      ${promptGroup('Forms & validation', [
-        {
-          tag: 'Contact form',
-          prompt: 'Add a contact form at /contact with name, email, and message fields. All three are required. Email must be a valid format. Show inline errors on failure. Show a success message on submission.',
-          produces: 'A spec with <code>validation</code> rules, an <code>actions.submit</code> with <code>validate: true</code>, and <code>onSuccess</code>/<code>onError</code> state transitions.',
-        },
-        {
-          tag: 'Multi-step form',
-          prompt: 'Create a multi-step signup form at /signup with three steps: account details, personal info, and confirmation. Show a step indicator at the top. Only advance when the current step is valid.',
-          produces: 'A <code>step</code> state field, step-specific validation, a <code>next</code> action that validates before advancing, and a view that renders the active step panel.',
-        },
-        {
-          tag: 'Constraints',
-          prompt: 'The quantity input on the /cart page should never go below 1 or above 99. Enforce this on the server — not just in the UI.',
-          produces: 'A <code>constraints</code> block with <code>quantity: { min: 1, max: 99 }</code> that the framework enforces after every mutation, regardless of what the client sends.',
-        },
-      ])}
-
-      ${promptGroup('Server data & actions', [
-        {
-          tag: 'Dashboard data',
-          prompt: 'The /dashboard page should show the logged-in user\'s name and their last 5 orders. Fetch both in parallel.',
-          produces: 'A <code>server.data</code> fetcher that runs two queries concurrently with <code>Promise.all</code> and passes the results to the view as <code>server.data.user</code> and <code>server.data.orders</code>.',
-        },
-        {
-          tag: 'Async action',
-          prompt: 'Add a Delete button to each row in the /users table. It should send a DELETE request to the API, remove the row on success, and show an error message on failure.',
-          produces: 'An action with <code>onStart</code> setting a loading flag, <code>run</code> making the API call, <code>onSuccess</code> removing the item from state, and <code>onError</code> setting an error message.',
-        },
-        {
-          tag: 'File upload',
-          prompt: 'Add an avatar upload form to /settings. The user picks a file, it uploads to storage, and the page shows the new avatar on success.',
-          produces: 'An action whose <code>run</code> reads the file from <code>FormData</code>, converts it to an <code>ArrayBuffer</code>, and uploads it to storage. <code>onSuccess</code> updates the avatar URL in state.',
-        },
-      ])}
-
-      ${promptGroup('Authentication', [
-        {
-          tag: 'Login page',
-          prompt: 'Create a login page at /login with email and password fields. On success, set an httpOnly session cookie and redirect to /dashboard. Show an error message if credentials are wrong.',
-          produces: 'A raw response action that verifies credentials, sets <code>Set-Cookie</code> headers with <code>httpOnly; SameSite=Strict</code>, and redirects. Failed logins return the form with an error state.',
-        },
-        {
-          tag: 'Protected route',
-          prompt: 'Protect the /dashboard page so only logged-in users can access it. Redirect anyone without a valid session to /login.',
-          produces: 'A <code>guard</code> function that reads the session cookie, verifies it, and returns a redirect response if invalid.',
-        },
-        {
-          tag: 'Logout',
-          prompt: 'Add a logout button to the nav. It should clear the session and redirect to /login.',
-          produces: 'A page spec at <code>/logout</code> using the raw response spec (<code>contentType</code> + <code>render</code>) that sets the session cookie to <code>maxAge: 0</code> and issues a 302 redirect.',
-        },
-      ])}
-
-      ${promptGroup('Streaming SSR', [
-        {
-          tag: 'Deferred content',
-          prompt: 'The /feed page is slow because it waits for the activity feed before painting anything. Make it stream — show the page chrome instantly and load the feed in the background.',
-          produces: 'A <code>stream</code> block with <code>shell: [\'header\']</code> and <code>deferred: [\'feed\']</code>. The view becomes a keyed object of named segment functions.',
-        },
-        {
-          tag: 'Multiple segments',
-          prompt: 'The /home page has a hero, a trending section, and a recommendations section. The hero should appear instantly. The other two can load as data resolves.',
-          produces: 'Three view segments — <code>hero</code> in the shell, <code>trending</code> and <code>recommendations</code> deferred. Each fetches its own data independently.',
-        },
-      ])}
-
-      ${promptGroup('Performance & tooling', [
-        {
-          tag: 'Lighthouse audit',
-          prompt: 'Run a Lighthouse audit across all pages and show me the results.',
-          produces: 'The agent runs <code>/pulse-report</code>, which audits every registered route and opens the results dashboard.',
-        },
-        {
-          tag: 'Score thresholds',
-          prompt: 'Make the audit fail if any page scores below 90 for performance or below 95 for accessibility.',
-          produces: 'A <code>lighthouse</code> block in <code>pulse.config.js</code> with <code>performance: 90</code> and <code>accessibility: 95</code>.',
-        },
-        {
-          tag: 'Load test',
-          prompt: 'Load test the /api/data endpoint with 50 concurrent connections for 30 seconds and tell me the p99 latency.',
-          produces: 'The agent runs <code>/pulse-load</code> against that route with the specified parameters and reports the results.',
-        },
-        {
-          tag: 'Environment config',
-          prompt: 'Set up a staging environment so I can run audits against https://staging.myapp.com instead of localhost.',
-          produces: 'An <code>environments.staging</code> block in <code>pulse.config.js</code> with the remote URL. The agent uses it when running <code>/pulse-report</code> or <code>/pulse-load</code>.',
-        },
-      ])}
-
-      ${promptGroup('Integrations', [
-        {
-          tag: 'Supabase query',
-          prompt: 'The /profile page should load the current user\'s row from the Supabase users table. It should only return data the logged-in user owns.',
-          produces: 'A <code>server.data</code> fetcher using the Supabase public client initialised with the user\'s access token, so Row Level Security applies automatically.',
-        },
-        {
-          tag: 'Supabase auth',
-          prompt: 'Use Supabase for authentication. The login form should call Supabase\'s signInWithPassword and store the tokens in httpOnly cookies.',
-          produces: 'A login action that calls <code>supabase.auth.signInWithPassword</code>, reads the session tokens from the response, and sets them as <code>httpOnly; SameSite=Strict</code> cookies.',
-        },
-        {
-          tag: 'Stripe checkout',
-          prompt: 'Add a checkout button to the /pricing page for the Pro plan. Clicking it should create a Stripe Checkout Session and redirect the user to the Stripe-hosted page.',
-          produces: 'An action whose <code>run</code> calls the Stripe API to create a session and returns the checkout URL. <code>onSuccess</code> triggers a redirect via state.',
-        },
-      ])}
-    `,
-  }),
-}

package/docs/src/pages/raw-responses.js

@@ -1,122 +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('/raw-responses')
-
-export default {
-  route: '/raw-responses',
-  meta: {
-    theme:       'light',
-    title: 'Raw Responses — Pulse Docs',
-    description: 'Return non-HTML responses from Pulse specs — RSS, XML, JSON, and other content types.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/raw-responses',
-    prev,
-    next,
-    content: `
-      ${h1('Raw Responses')}
-      ${lead('Setting <code>contentType</code> switches a spec from the HTML pipeline to a raw response mode. The view returns the response body directly — no doctype, no hydration script. Security headers and compression still apply.')}
-
-      ${section('basics', 'The basics')}
-      <p>Set <code>contentType</code> to any valid MIME type. When present, the normal HTML wrapper (doctype, head, body, hydration script) is skipped. The <code>render</code> function receives <code>(ctx, serverState)</code> and returns a string:</p>
-      ${codeBlock(highlight(`export default {
-  route: '/feed.xml',
-  contentType: 'application/rss+xml',
-  server: {
-    data: async () => ({
-      posts: await db.posts.latest(20),
-    }),
-  },
-  view: (ctx, server) => \`<?xml version="1.0" encoding="UTF-8"?>
-<rss version="2.0">
-  <channel>
-    <title>My Blog</title>
-    <link>https://example.com</link>
-    <description>Recent posts</description>
-    \${server.posts.map(post => \`
-    <item>
-      <title>\${esc(post.title)}</title>
-      <link>https://example.com/blog/\${post.slug}</link>
-      <pubDate>\${new Date(post.date).toUTCString()}</pubDate>
-      <description>\${esc(post.excerpt)}</description>
-    </item>
-    \`).join('')}
-  </channel>
-</rss>\`,
-}`, 'js'))}
-
-      ${section('json', 'JSON API endpoints')}
-      ${codeBlock(highlight(`export default {
-  route: '/api/products',
-  contentType: 'application/json',
-  server: {
-    data: async (ctx) => ({
-      products: await db.products.list({
-        page:     parseInt(ctx.query.page ?? '1', 10),
-        category: ctx.query.category,
-      }),
-    }),
-  },
-  view: (ctx, server) => JSON.stringify({
-    products: server.products,
-    page:     parseInt(ctx.query.page ?? '1', 10),
-  }),
-}`, 'js'))}
-
-      ${section('sitemap', 'XML sitemap')}
-      ${callout('tip', 'For most sites you don\'t need a raw spec for this — set <code>sitemap: true</code> in <code>createServer</code> and Pulse generates <code>/sitemap.xml</code> and <code>robots.txt</code> from the registered routes automatically. See <a href="/meta#sitemap">Metadata &amp; SEO</a>. Write a raw sitemap spec only when you need full control over the XML.')}
-      ${codeBlock(highlight(`export default {
-  route: '/sitemap.xml',
-  contentType: 'application/xml',
-  serverTtl:   3600,
-  server: {
-    data: async () => ({
-      pages: await db.pages.allPublished(),
-    }),
-  },
-  view: (ctx, server) => \`<?xml version="1.0" encoding="UTF-8"?>
-<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
-  \${server.pages.map(p => \`
-  <url>
-    <loc>https://example.com\${p.path}</loc>
-    <lastmod>\${p.updatedAt.toISOString().slice(0, 10)}</lastmod>
-  </url>
-  \`).join('')}
-</urlset>\`,
-}`, 'js'))}
-
-      ${section('view-signature', 'View function signature')}
-      <p>For raw responses, the <code>view</code> function signature is <code>(ctx, serverState)</code>, not <code>(state, serverState)</code>. The <code>ctx</code> argument is the request context object with <code>params</code>, <code>query</code>, <code>headers</code>, and <code>cookies</code>.</p>
-      ${callout('note', 'There is no client state (<code>state</code>) for raw response specs — they are purely server-side. The <code>state: {}</code> field is still required for spec validation, but is not used.')}
-
-      ${section('escaping', 'Escaping in XML and HTML')}
-      <p>Pulse does not auto-escape raw response bodies. When returning XML or HTML, escaping all user-supplied and dynamic content is required — unescaped output is an injection vulnerability:</p>
-      ${codeBlock(highlight(`// Simple escape helper for XML/HTML contexts
-function esc(str) {
-  return String(str)
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&#39;')
-}`, 'js'))}
-      ${callout('warning', 'Never interpolate raw user data or database content into XML/HTML without escaping. This applies to raw response specs just as much as to HTML view functions.')}
-
-      ${section('caching-raw', 'Caching raw responses')}
-      <p>Raw response specs support the same <code>serverTtl</code> and <code>cache</code> options as HTML specs. For feeds and sitemaps that update infrequently, a generous TTL dramatically reduces server load:</p>
-      ${codeBlock(highlight(`export default {
-  route:       '/feed.xml',
-  contentType: 'application/rss+xml',
-  serverTtl:   300,   // cache data for 5 minutes
-  cache: {
-    public:  true,
-    maxAge:  300,
-  },
-  // ...
-}`, 'js'))}
-    `,
-  }),
-}

package/docs/src/pages/routing.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('/routing')
-
-export default {
-  route: '/routing',
-  meta: {
-    theme:       'light',
-    title: 'Routing — Pulse Docs',
-    description: 'How Pulse routes requests to page specs — static and dynamic routes, params, and conventions.',
-    styles: ['/theme.css', '/docs.css'],
-  },
-  view: () => renderLayout({
-    currentHref: '/routing',
-    prev,
-    next,
-    content: `
-      ${h1('Routing')}
-      ${lead('Every route in Pulse is explicitly declared in the spec. There is no file-based routing, no magic directory conventions, and no implicit mapping. Every page\'s URL is visible in its spec file and nowhere else.')}
-
-      ${section('route-field', 'The route field')}
-      <p>Every spec has a <code>route</code> field. This is the URL pattern the spec handles:</p>
-      ${codeBlock(highlight(`export default {
-  route: '/about',
-  view: () => \`<h1>About</h1>\`,
-}`, 'js'))}
-      <p>Pulse matches the exact path. By default, trailing slashes are removed — <code>/about/</code> redirects to <code>/about</code> with a 301. This is controlled by the <code>trailingSlash</code> option in <code>createServer</code>:</p>
-      ${table(
-        ['Value', 'Behaviour'],
-        [
-          ['<code>"remove"</code> (default)', 'Redirects <code>/about/</code> → <code>/about</code> (301)'],
-          ['<code>"add"</code>', 'Redirects <code>/about</code> → <code>/about/</code> (301)'],
-          ['<code>"allow"</code>', 'Serves both — no redirect'],
-        ]
-      )}
-      ${codeBlock(highlight(`createServer(specs, {
-  trailingSlash: 'add', // enforce trailing slashes
-})`, 'js'))}
-
-      ${section('dynamic', 'Dynamic segments')}
-      <p>Use a colon prefix for dynamic path segments. Named segments are captured and available in <code>ctx.params</code> in <a href="/server-data">server data</a>:</p>
-      ${codeBlock(highlight(`export default {
-  route: '/products/:id',
-  state: { quantity: 1 },
-  server: {
-    data: async (ctx) => {
-      // ctx.params.id is the captured segment
-      const product = await db.products.find(ctx.params.id)
-      return { product }
-    },
-  },
-  view: (state, server) => \`<h1>\${server.product.name}</h1>\`,
-}`, 'js'))}
-
-      ${section('multi-segment', 'Multiple dynamic segments')}
-      <p>Any number of dynamic segments can appear in a route:</p>
-      ${codeBlock(highlight(`route: '/blog/:year/:month/:slug'
-// Matches: /blog/2025/03/my-first-post
-// ctx.params = { year: '2025', month: '03', slug: 'my-first-post' }`, 'js'))}
-
-      ${section('registering', 'Registering routes')}
-      <p>Specs are registered explicitly by passing them to <code>createServer</code> as an array. Routes are matched in order — more specific routes must come before more general ones:</p>
-      ${codeBlock(highlight(`import { createServer } from '@invisibleloop/pulse'
-import home     from './src/pages/home.js'
-import products from './src/pages/products.js'
-import product  from './src/pages/product.js'   // more specific — comes first
-import blog     from './src/pages/blog.js'
-
-createServer([home, product, products, blog], { port: 3000 })`, 'js'))}
-
-      ${section('query', 'Query strings')}
-      <p>Query string parameters are not part of the route pattern but are accessible via <code>ctx.query</code> in server data:</p>
-      ${codeBlock(highlight(`// URL: /products?category=shoes&sort=price
-server: {
-  data: async (ctx) => {
-    const { category, sort } = ctx.query
-    return { products: await db.products.list({ category, sort }) }
-  },
-}`, 'js'))}
-
-      ${section('redirects', 'Redirects')}
-      <p>Migrating an existing site? Preserve the old URLs with the <code>redirects</code> map — legacy links and search rankings survive the move:</p>
-      ${codeBlock(highlight(`await createServer(pages, {
-  redirects: {
-    '/old-blog/:slug': '/blog/:slug',                 // 301 — :params carry over
-    '/pricing-2024':   '/pricing',                    // 301 (default)
-    '/promo':          { to: '/sale', status: 302 },  // temporary redirect
-    '/moved/:slug':    'https://other.com/:slug',     // absolute targets for domain moves
-  },
-})`, 'js'))}
-      <p>Redirects respond <strong>301</strong> by default (permanent — search engines transfer ranking to the target). Use <code>{ to, status }</code> for <code>302</code>, <code>307</code>, or <code>308</code>. The query string is preserved, redirects apply to GET/HEAD only, and the map is validated at startup — a bad entry fails the boot rather than silently misrouting traffic.</p>
-      ${callout('note', 'Redirects are checked before route matching, so a redirect source that equals a registered route shadows the page — the server logs a startup warning when that happens. Occasionally intentional (retiring a page), usually a mistake.')}
-
-      ${section('not-found', '404 handling')}
-      <p>If no spec matches the incoming request path, Pulse returns a 404. To customise it, create a spec with <code>route: '*'</code> — it renders through the normal pipeline (layout, styles, components) with status 404:</p>
-      ${codeBlock(highlight(`export default {
-  route: '*',
-  meta:  { title: 'Page not found', styles: ['/pulse-ui.css', '/theme.css', '/app.css'] },
-  view:  () => \`<main id="main-content"><h1>Page not found</h1><p><a href="/">Back home</a></p></main>\`,
-}`, 'js'), 'src/pages/not-found.js')}
-      <p>See <a href="/error-pages">Error Pages</a> for the full behaviour, including 500 handling.</p>
-
-      ${section('conventions', 'File naming conventions')}
-      <p>While Pulse does not auto-discover files, the recommended convention maps file names to routes:</p>
-      ${table(
-        ['File', 'Route'],
-        [
-          ['<code>src/pages/home.js</code>', '<code>/</code>'],
-          ['<code>src/pages/about.js</code>', '<code>/about</code>'],
-          ['<code>src/pages/products.js</code>', '<code>/products</code>'],
-          ['<code>src/pages/product.js</code>', '<code>/products/:id</code>'],
-          ['<code>src/pages/blog-post.js</code>', '<code>/blog/:slug</code>'],
-        ]
-      )}
-      ${callout('tip', 'The filename does not need to match the route exactly — it is just a helpful convention. A file named <code>product.js</code> can handle <code>/products/:id</code> without any issue.')}
-    `,
-  }),
-}