@absolutejs/absolute 0.19.0-beta.171 → 0.19.0-beta.173

package/ROADMAP.md

@@ -580,3 +580,453 @@ Bun-only. Requires a long-running Bun server process. No serverless or edge adap
 - New: `src/adapters/docker/Dockerfile`
 - New: `src/adapters/lambda.ts` — AWS Lambda adapter
 - Documentation for common deployment targets
+
+---
+
+## P1 — Out-of-Order Streaming
+
+**What SolidStart does:**
+Components stream to the client as they resolve, not in DOM order. If your sidebar data query finishes before your main content query, the sidebar HTML ships first. The browser renders each chunk into the correct DOM position regardless of arrival order. This means the fastest data always appears first — no waterfall where a slow hero section blocks the entire page.
+
+**What AbsoluteJS has today:**
+Full streaming SSR via `renderToReadableStream` for all frameworks. But streaming is in-order — the HTML is sent top-to-bottom as React/Svelte/Vue render the component tree. If a component high in the tree is slow (data fetch, heavy computation), everything below it waits.
+
+**Why this matters:**
+In a typical dashboard page, you might have:
+- A navbar (instant, no data)
+- A stats section (slow — aggregation query)
+- A recent activity feed (fast — simple query)
+- A footer (instant, no data)
+
+With in-order streaming, the activity feed waits for the stats section even though its data is ready. With out-of-order streaming, the navbar, activity feed, and footer arrive immediately while the stats section streams in when its query finishes. The user sees a useful page faster.
+
+**What needs to be built:**
+
+*Server side:*
+- Placeholder slots in the HTML — when a component is async/suspended, send a lightweight placeholder `<div id="slot-{id}">` with a loading skeleton or empty space
+- As each async component resolves, send an `<template>` or `<script>` block that contains the real HTML and swaps it into the placeholder
+- This is how React 18's Suspense streaming works under the hood — `renderToReadableStream` already supports this for React via `<Suspense>` boundaries. The work is extending this pattern to Svelte, Vue, and Angular.
+
+*Per-framework implementation:*
+- **React**: Already supports this via `<Suspense>` boundaries with `renderToReadableStream`. Each `<Suspense>` boundary becomes an independent streaming slot. The main work is documenting the pattern and ensuring it works with AbsoluteJS's page handler.
+- **Svelte**: Svelte 5 has `{#await}` blocks. The custom `renderToReadableStream` in `src/svelte/renderToReadableStream.ts` needs to support async resolution — when an `{#await}` block is pending, send a placeholder and stream the resolved content later.
+- **Vue**: Vue's `<Suspense>` component with `renderToWebStream` can be extended similarly. Each `<Suspense>` boundary becomes a streaming slot.
+- **Angular**: Angular's `@defer` blocks are the equivalent. The SSR renderer can send placeholders for `@defer` blocks and stream them in when resolved.
+
+*Client side:*
+- A small inline script (sent at the start of the stream) that listens for arriving chunks and swaps them into their placeholder slots
+- Pattern: `<script>function $RC(id,html){document.getElementById('slot-'+id).outerHTML=html}</script>`
+- Each resolved chunk arrives as: `<script>$RC("stats-section","<div>...real content...</div>")</script>`
+- This script is ~200 bytes and makes out-of-order streaming work without any framework JS loaded yet
+
+*Integration with islands:*
+- Islands with `hydrate="idle"` or `hydrate="visible"` are natural candidates for out-of-order streaming — send the placeholder, stream the SSR'd HTML when ready, hydrate later based on the directive
+- This creates a smooth pipeline: placeholder → streamed HTML (visible but not interactive) → hydrated (interactive)
+
+**Design considerations:**
+- Fallback content for each slot (loading skeleton, spinner, or empty space) should be configurable per-component
+- If streaming takes too long (>5s), the placeholder should remain visible with its fallback content — don't leave empty holes
+- The out-of-order script must be sent before any slot content so the browser knows how to handle arriving chunks
+- CSS for streamed-in content must already be loaded (sent in the initial `<head>` or preloaded) to avoid layout shift when content swaps in
+
+**Files likely involved:**
+- `src/react/pageHandler.ts` — document and test `<Suspense>` boundary streaming (may already work)
+- `src/svelte/renderToReadableStream.ts` — add out-of-order support for `{#await}` blocks
+- `src/vue/pageHandler.ts` — add `<Suspense>` boundary support to the streaming pipeline
+- `src/angular/pageHandler.ts` — add `@defer` block support to SSR streaming
+- New: `src/utils/streamingSlots.ts` — shared utilities for generating placeholder HTML and the `$RC` swap script
+- New: `src/client/streamSwap.ts` — the inline client script that handles out-of-order chunk insertion
+
+---
+
+## P1 — Form Actions with Progressive Enhancement
+
+**What SvelteKit and Remix do:**
+Forms submit to the server as plain HTML `<form action="/submit" method="POST">` — this works with zero JavaScript. The server processes the form, validates input, and returns a result (redirect, error, or updated page). When JavaScript IS available, the framework intercepts the submission, sends it via `fetch()` instead, and updates the page without a full reload. The developer writes one handler that works both ways.
+
+SvelteKit's form actions return typed data that flows back to the page. Remix's actions return data that's available via `useActionData()`. Both support validation errors that display inline without losing form state.
+
+**What AbsoluteJS has today:**
+Elysia POST handlers work for form processing, but there's no convention for progressive enhancement. If JS fails to load, forms don't work unless the developer manually sets up a standard HTML form submission flow. HTMX pages handle this naturally, but React/Svelte/Vue/Angular pages don't.
+
+**Why this matters:**
+- Forms are the primary way users mutate data on the web. Every app has them.
+- Progressive enhancement means forms work even when JS fails (slow connections, CDN outage, corporate firewalls blocking scripts). This is real resilience, not theoretical.
+- The developer writes one handler and gets both behaviors. Less code, more robust.
+- Inline validation errors without losing form state is a huge DX win — users hate re-filling forms after a server error.
+
+**What needs to be built:**
+
+*Server side — action handlers:*
+- A convention for defining form actions on Elysia routes. This could be as simple as a helper that creates a POST handler with typed input validation:
+  ```ts
+  import { defineAction } from 'absolutejs'
+  import { t } from 'elysia'
+
+  const createUser = defineAction({
+    body: t.Object({
+      name: t.String(),
+      email: t.String({ format: 'email' }),
+    }),
+    handler: async ({ body }) => {
+      const user = await db.insert(users).values(body).returning()
+      return { success: true, user }
+    },
+    error: (errors) => {
+      return { success: false, errors }
+      // errors is typed: { name?: string, email?: string }
+    }
+  })
+
+  app.post('/users', createUser)
+  ```
+- The action handler detects whether the request came from a plain form submission (no JS) or a `fetch()` call (JS available):
+  - Plain form: process, then redirect (POST/Redirect/GET pattern) or re-render the page with errors
+  - Fetch: return JSON with the result or validation errors
+- Detection via `Accept` header — `application/json` means JS fetch, `text/html` means plain form
+
+*Client side — per-framework hooks:*
+- **React**: `useFormAction(actionUrl)` hook that returns `{ submit, data, errors, isSubmitting }`. Intercepts `<form onSubmit>`, sends via fetch, returns typed result. Falls back to normal form submission if hook isn't used.
+  ```tsx
+  const { submit, errors, isSubmitting } = useFormAction('/users')
+
+  <form onSubmit={submit}>
+    <input name="name" />
+    {errors?.name && <span>{errors.name}</span>}
+    <input name="email" />
+    {errors?.email && <span>{errors.email}</span>}
+    <button disabled={isSubmitting}>Create</button>
+  </form>
+  ```
+- **Svelte**: `useFormAction` that returns a store with the same shape. Bind to `<form use:enhance>` pattern.
+- **Vue**: `useFormAction` composable returning reactive refs.
+- **Angular**: `FormAction` service that returns an Observable-based interface.
+- All hooks preserve form state on validation errors — the form doesn't reset when the server returns errors.
+
+*Progressive enhancement flow:*
+1. Server renders the page with a `<form action="/users" method="POST">`
+2. If JS loads: the hook intercepts submit, sends fetch, updates UI reactively
+3. If JS fails: the form submits normally, server processes it, redirects or re-renders with errors
+4. Same server handler handles both cases — the developer doesn't write two code paths
+
+*Type safety:*
+- The action's `body` schema (Elysia's `t.Object`) defines both server validation and client-side error types
+- `errors` in the hook is typed to match the schema fields — `errors.name` exists only if `name` is in the schema
+- The action's return type flows to the hook's `data` — full end-to-end type safety via Elysia's existing type system
+
+**Design considerations:**
+- The `<form>` must have a real `action` and `method` attribute for the no-JS path to work. The hook enhances it, doesn't replace it.
+- File uploads should work in both paths — `multipart/form-data` for plain forms, `FormData` via fetch for enhanced forms.
+- Optimistic UI: the hook could accept an `optimistic` callback that updates the UI immediately before the server responds, then reconciles when the real response arrives.
+- CSRF protection should be built in — the action handler validates a token automatically.
+
+**Files likely involved:**
+- New: `src/utils/defineAction.ts` — action handler factory with typed validation and dual-mode response
+- New: `src/react/hooks/useFormAction.ts` — React hook for form enhancement
+- New: `src/svelte/useFormAction.ts` — Svelte store-based form enhancement
+- New: `src/vue/useFormAction.ts` — Vue composable for form enhancement
+- New: `src/angular/form-action.service.ts` — Angular service for form enhancement
+- New: `types/action.ts` — types for action definitions, error shapes, and hook returns
+
+---
+
+## P2 — Partial Prerendering (requires SSG)
+
+**What Next.js 16 does:**
+A page is split into a static shell (navbar, footer, layout — cached at CDN) and dynamic "holes" that stream in at request time (user-specific content, real-time data). The static parts load instantly from cache while the dynamic parts stream in via SSR. From the user's perspective, the page appears instantly with personalized content filling in smoothly.
+
+Next.js implements this by combining static generation with Suspense boundaries — everything outside a `<Suspense>` boundary is pre-rendered at build time, and the Suspense fallbacks are replaced with streamed server-rendered content at request time.
+
+**What AbsoluteJS has today:**
+Every page is fully server-rendered at request time. No static caching of any page content. The entire page waits for all data before any HTML is sent (unless using streaming SSR, which streams in-order but still requires the server to render everything on each request).
+
+**Why this matters:**
+Most pages are 80% static content (nav, sidebar, footer, headings, layout) and 20% dynamic (user name, notifications, personalized feed). Rendering that 80% on every request is wasted work. Partial prerendering means:
+- The static shell loads from CDN in ~50ms (no server round-trip)
+- The dynamic holes stream from the server in ~200-500ms
+- Combined: users see a near-instant page with dynamic content appearing smoothly
+- Server load drops dramatically — most of the HTML is served from cache
+
+**What needs to be built (depends on SSG being implemented first):**
+
+*Build-time static shell generation:*
+- During the build, render each page but stop at dynamic boundaries (Suspense, `{#await}`, `<Suspense>`, `@defer`)
+- Write the static HTML (everything outside dynamic boundaries) to disk with placeholder slots for the dynamic parts
+- The static shell includes all CSS, the page layout, and fallback content (loading skeletons) for each dynamic slot
+
+*Request-time dynamic streaming:*
+- When a request comes in, serve the static shell immediately from disk/cache
+- Simultaneously, render the dynamic parts on the server and stream them into the placeholder slots
+- Reuse the out-of-order streaming infrastructure — the `$RC` swap script handles inserting dynamic content into the static shell
+
+*Per-framework dynamic boundaries:*
+- **React**: `<Suspense>` boundaries — everything inside is dynamic, everything outside is static
+- **Svelte**: `{#await}` blocks or a new `<Dynamic>` component
+- **Vue**: `<Suspense>` component — same pattern as React
+- **Angular**: `@defer` blocks — natural fit, Angular already distinguishes static vs deferred content
+
+*Caching strategy:*
+- Static shells cached in memory and/or on disk with content-hash keys
+- Cache invalidation: rebuild the shell when the page's static parts change (detected via file watcher or manual invalidation)
+- Dynamic parts are never cached (they're user-specific/time-specific)
+- CDN integration: set `Cache-Control` headers so the static shell is edge-cached while the dynamic stream bypasses cache
+
+*Configuration:*
+- Per-page opt-in via a config option or export:
+  ```ts
+  // In the route handler
+  app.get('/dashboard', () =>
+    handleReactPageRequest(Dashboard, manifest['DashboardIndex'], {
+      prerender: 'partial',  // static shell + dynamic streaming
+      props: { userId: getCurrentUser() }
+    })
+  )
+  ```
+- Or via the build config for pages that should always be partially prerendered
+
+**Design considerations:**
+- The static shell must be a valid HTML document on its own — if dynamic streaming fails, the user sees the shell with fallback content (loading skeletons), not a broken page.
+- Dynamic boundaries should be explicit — the developer marks what's dynamic, everything else is assumed static. No guessing.
+- This compounds with islands — an island with `hydrate="visible"` inside a dynamic boundary gets: static shell → streamed SSR HTML → hydrated on scroll. Three layers of progressive loading.
+- Hot reloading in dev: skip the static cache and render everything server-side (same as today). Partial prerendering is a production optimization only.
+
+**Files likely involved:**
+- Builds on top of SSG implementation and out-of-order streaming
+- New: `src/core/partialPrerender.ts` — orchestrates static shell serving + dynamic streaming
+- New: `src/build/generateStaticShells.ts` — renders pages at build time, extracts static content, writes shells to disk
+- `src/utils/streamingSlots.ts` — reused from out-of-order streaming for dynamic slot insertion
+- Each framework's `pageHandler.ts` — add `prerender: 'partial'` mode that serves cached shell + streams dynamic parts
+- `src/plugins/hmr.ts` — static shell cache invalidation when source files change
+
+---
+
+## P1 — AI/LLM Streaming Helpers
+
+**What exists today in the ecosystem:**
+Vercel's `ai` SDK (`npm install ai`) provides React hooks and server utilities for streaming LLM responses. It works with Next.js, SvelteKit, and Nuxt. But it uses Server-Sent Events (SSE) because Next.js has no native WebSocket support. SSE is one-directional (server → client only) — the client can't send messages mid-stream (cancel, follow-up, branch conversation) without opening a new HTTP request.
+
+**What AbsoluteJS has today:**
+Native bidirectional WebSocket via Elysia. The HMR system already proves the WebSocket infrastructure works at scale with reconnection, message typing, and broadcast. But there are no helpers for connecting an LLM API to a WebSocket channel.
+
+**Why this is a killer feature:**
+AI-powered apps are the dominant use case for new web projects in 2025-2026. Every chat interface, AI assistant, code editor, and content generator needs LLM streaming. The current state of the art (Vercel AI SDK over SSE) has real limitations:
+- SSE is one-directional — canceling a generation requires a separate abort request
+- SSE connections can't be reused — each message opens a new HTTP connection
+- No native support for branching conversations, tool use feedback, or multi-turn streaming
+- WebSocket solves all of these: bidirectional, persistent, multiplexed
+
+AbsoluteJS has WebSocket built in. Adding thin helpers on top makes it the best framework for AI apps with zero additional infrastructure.
+
+**What needs to be built:**
+
+*Server side — `streamAI()` utility:*
+```ts
+import { streamAI } from 'absolutejs'
+
+app.ws('/chat', {
+  message: async (ws, { prompt, conversationId }) => {
+    // streamAI connects to the LLM provider, pipes token chunks
+    // over the WebSocket, and handles backpressure/cancellation
+    await streamAI(ws, {
+      provider: 'anthropic',
+      model: 'claude-sonnet-4-5-20250514',
+      messages: [{ role: 'user', content: prompt }],
+      // Optional: called for each token chunk before sending
+      onChunk: (chunk) => {
+        // Transform, log, filter, or store chunks
+        saveToConversation(conversationId, chunk)
+        return chunk
+      },
+      // Optional: called when the stream completes
+      onComplete: (fullResponse) => {
+        saveMessage(conversationId, fullResponse)
+      }
+    })
+  }
+})
+```
+
+- `streamAI()` is provider-agnostic — supports Anthropic, OpenAI, and any provider that returns a `ReadableStream` or async iterator
+- Handles backpressure — if the client is slow to consume, the server buffers appropriately
+- Handles cancellation — if the client disconnects or sends a cancel message, the LLM request is aborted
+- Handles errors — if the LLM API errors mid-stream, sends a typed error message to the client
+- The `onChunk` callback enables middleware-like processing: content filtering, token counting, database persistence, RAG augmentation
+
+*Provider adapters:*
+```ts
+// Built-in adapters for common providers
+import { anthropic, openai, ollama } from 'absolutejs/ai'
+
+// Each adapter normalizes the provider's streaming API into a common interface
+await streamAI(ws, {
+  provider: anthropic({ apiKey: env.ANTHROPIC_API_KEY }),
+  // or: provider: openai({ apiKey: env.OPENAI_API_KEY }),
+  // or: provider: ollama({ baseUrl: 'http://localhost:11434' }),
+  model: 'claude-sonnet-4-5-20250514',
+  messages,
+})
+```
+
+- Adapters handle provider-specific auth, endpoints, and stream formats
+- Common interface: `{ stream: AsyncIterable<{ type: 'text' | 'tool_use' | 'error', content: string }> }`
+- Easy to add new providers — just implement the adapter interface
+
+*Client side — per-framework hooks:*
+
+**React:**
+```tsx
+import { useAIStream } from 'absolutejs/react'
+
+const Chat = () => {
+  const {
+    messages,     // Message[] — full conversation history
+    send,         // (content: string) => void — send a message
+    cancel,       // () => void — cancel current generation
+    isStreaming,  // boolean — true while LLM is generating
+    error,        // string | null — last error
+  } = useAIStream('/chat')
+
+  return (
+    <div>
+      {messages.map(m => (
+        <div key={m.id} data-role={m.role}>
+          {m.content}
+          {m.isStreaming && <span className="cursor" />}
+        </div>
+      ))}
+      <form onSubmit={(e) => {
+        e.preventDefault()
+        send(e.currentTarget.input.value)
+      }}>
+        <input name="input" disabled={isStreaming} />
+        {isStreaming
+          ? <button type="button" onClick={cancel}>Stop</button>
+          : <button type="submit">Send</button>
+        }
+      </form>
+    </div>
+  )
+}
+```
+
+**Svelte:**
+```svelte
+<script lang="ts">
+  import { createAIStream } from 'absolutejs/svelte'
+
+  const { messages, send, cancel, isStreaming, error } = createAIStream('/chat')
+</script>
+
+{#each $messages as message}
+  <div data-role={message.role}>
+    {message.content}
+    {#if message.isStreaming}<span class="cursor" />{/if}
+  </div>
+{/each}
+
+<form on:submit|preventDefault={(e) => send(e.currentTarget.input.value)}>
+  <input name="input" disabled={$isStreaming} />
+  {#if $isStreaming}
+    <button type="button" on:click={cancel}>Stop</button>
+  {:else}
+    <button type="submit">Send</button>
+  {/if}
+</form>
+```
+
+**Vue:**
+```vue
+<script setup lang="ts">
+import { useAIStream } from 'absolutejs/vue'
+
+const { messages, send, cancel, isStreaming, error } = useAIStream('/chat')
+</script>
+
+<template>
+  <div v-for="m in messages" :key="m.id" :data-role="m.role">
+    {{ m.content }}
+    <span v-if="m.isStreaming" class="cursor" />
+  </div>
+  <form @submit.prevent="send($event.target.input.value)">
+    <input name="input" :disabled="isStreaming" />
+    <button v-if="isStreaming" type="button" @click="cancel">Stop</button>
+    <button v-else type="submit">Send</button>
+  </form>
+</template>
+```
+
+**Angular:**
+```typescript
+import { Component, inject } from '@angular/core'
+import { AIStreamService } from 'absolutejs/angular'
+
+@Component({
+  selector: 'app-chat',
+  template: `
+    @for (m of ai.messages(); track m.id) {
+      <div [attr.data-role]="m.role">
+        {{ m.content }}
+        @if (m.isStreaming) { <span class="cursor"></span> }
+      </div>
+    }
+    <form (submit)="onSubmit($event)">
+      <input name="input" [disabled]="ai.isStreaming()" />
+      @if (ai.isStreaming()) {
+        <button type="button" (click)="ai.cancel()">Stop</button>
+      } @else {
+        <button type="submit">Send</button>
+      }
+    </form>
+  `
+})
+export class ChatComponent {
+  ai = inject(AIStreamService).connect('/chat')
+
+  onSubmit(e: Event) {
+    e.preventDefault()
+    const input = (e.target as HTMLFormElement).input as HTMLInputElement
+    this.ai.send(input.value)
+  }
+}
+```
+
+*WebSocket message protocol for AI streaming:*
+```ts
+// Client → Server
+type AIClientMessage =
+  | { type: 'message', content: string, conversationId?: string }
+  | { type: 'cancel' }
+
+// Server → Client
+type AIServerMessage =
+  | { type: 'chunk', content: string, messageId: string }
+  | { type: 'tool_use', name: string, input: unknown, messageId: string }
+  | { type: 'complete', messageId: string, usage?: { inputTokens: number, outputTokens: number } }
+  | { type: 'error', message: string }
+```
+
+*Advanced features:*
+- **Tool use / function calling**: When the LLM calls a tool, the server sends a `tool_use` message. The client can display a "searching..." or "running code..." UI. The server executes the tool and feeds the result back to the LLM, continuing the stream.
+- **Conversation branching**: The client sends a `conversationId` — the server maintains conversation state and supports branching (edit a previous message, regenerate from a point).
+- **Multi-model routing**: `streamAI` could accept a `router` function that picks the model based on the message (simple questions → Haiku, complex → Opus).
+- **Token counting**: The `onChunk` callback can count tokens for usage tracking / rate limiting.
+- **Reconnection**: If the WebSocket drops mid-stream, the client hook reconnects and requests the remaining content from the server (using the `messageId` as a cursor).
+
+**Design considerations:**
+- The AI helpers should be optional — users who don't build AI features never import them and they're tree-shaken from the bundle.
+- Provider API keys should come from environment variables, never sent to the client.
+- The client hooks manage the WebSocket connection lifecycle — connect on mount, disconnect on unmount, reconnect on drop. Same patterns as the HMR client.
+- The message protocol should be extensible — providers may add new message types (images, audio) and the protocol should handle unknown types gracefully.
+- SSR: the chat component renders empty on the server (no messages). Conversation history loads on hydration from the server or local storage.
+
+**Files likely involved:**
+- New: `src/ai/streamAI.ts` — core streaming utility that pipes LLM responses to WebSocket
+- New: `src/ai/providers/anthropic.ts` — Anthropic adapter
+- New: `src/ai/providers/openai.ts` — OpenAI adapter
+- New: `src/ai/providers/ollama.ts` — Ollama adapter (local LLMs)
+- New: `src/react/hooks/useAIStream.ts` — React hook
+- New: `src/svelte/createAIStream.ts` — Svelte store-based hook
+- New: `src/vue/useAIStream.ts` — Vue composable
+- New: `src/angular/ai-stream.service.ts` — Angular service
+- New: `types/ai.ts` — message protocol types, provider interface, hook return types
+- Package exports: `absolutejs/ai` for server utilities, per-framework exports for client hooks