@vincle/flow 0.9.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Christophe Jean
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,513 @@
+# @vincle/flow
+
+Fragment streaming extension for [@vincle/core](https://github.com/cjean-fr/vincle/tree/main/packages/core). Renders deferred JSX fragments and delivers them to the browser as DOM patches. **Pick the adapter that matches your JS budget: from zero JS (WebPlatform/ESI) to ~550 B (Native) to full framework (Turbo/HTMX).**
+
+## When to use
+
+Use `@vincle/core` alone for SSG, emails, and pure SSR. Add `@vincle/flow` when you need **progressive enhancement**: the initial HTML loads fast with placeholders, and heavy or slow components are rendered separately and patched into the page without a full reload.
+
+| `@vincle/core`            | `@vincle/flow`                                     |
+| ------------------------- | -------------------------------------------------- |
+| Renders JSX → HTML string | Adds deferred fragments + streaming patch delivery |
+| Server-only, zero runtime | Emits adapter-specific markup for DOM updates      |
+| `renderToString()`        | `renderToStream()` / `renderToStatic()`            |
+| N/A                       | Adapters: Turbo, HTMX, Native, WebPlatform, ESI    |
+
+## Why deferred regions in streaming SSR
+
+A standard `renderToString` call is a serial pipeline: the server computes the full page before sending the first byte. With streaming, the shell (layout, navigation, above-the-fold content) goes to the browser immediately while heavy components are still rendering.
+
+Deferred regions of the same **wave** render **in parallel** and independently: the slowest one does not block its wave-mates. Waves flush one after another, and streams run on their own separate schedule. The browser receives the shell, paints it, then receives patches as they arrive and applies them in-place.
+
+- **TTFB / FCP**: users see content in one round-trip, not after all async work settles
+- **No virtual DOM, no hydration**: patches are applied as plain HTML by the adapter's client mechanism (Turbo, HTMX) or a minimal polyfill
+- **Fault isolation**: a failed fragment routes to `onError` (or logs) and is skipped; the rest of the page is unaffected
+- **Memory**: fragments are streamed out as they render, not accumulated before flushing
+
+## Why deferred regions in SSG
+
+In static generation every page is a snapshot. Cache invalidation is the hard part: when a deeply nested component changes, you regenerate the entire page. Deferred fragments split that snapshot.
+
+The shell (stable layout, navigation) is one file. Each fragment is a separate file at a predictable URL. Your build pipeline treats them independently:
+
+- **Granular invalidation**: only fragments whose data changed need to be regenerated; the shell stays cached
+- **Per-fragment TTL**: a "live prices" fragment can expire in 60 s while the surrounding page is cached for a day
+- **CDN composition**: shell and fragments are plain HTML files; any CDN can serve them
+- **Incremental builds**: on large sites, regenerating ten fragment files instead of ten thousand pages cuts build time
+
+## Install
+
+```bash
+bun add @vincle/flow
+```
+
+## Components
+
+@vincle/flow provides three declarative primitives for deferred content: a unified family built around **Slot** (the hole) and **Defer** (the deferred content that fills it). Each works with any adapter, in both streaming and static generation.
+
+### `<Slot>`: a named insertion point with fallback content
+
+Declares a named insertion point in the shell. Its `children` are rendered immediately as placeholder content: visible in the initial HTML until a `<Defer target="…">` overrides them.
+
+```tsx
+import { Slot, Defer } from "@vincle/flow";
+
+function Layout() {
+  return (
+    <html>
+      <body>
+        <nav>...</nav>
+        <main>
+          <Slot name="page">
+            <p>Loading…</p>
+          </Slot>
+        </main>
+      </body>
+    </html>
+  );
+}
+
+// Elsewhere in the tree (or a different component):
+function PageContent() {
+  return <Defer target="page">{() => <h1>Hello</h1>}</Defer>;
+}
+```
+
+`Slot` registers nothing in the pending store. It is purely a passive hole. The `children` are the initial fallback, visible until a `<Defer>` pushes deferred content that patches the placeholder.
+
+### `<Defer>`: deferred fragment (sync or lazy)
+
+Defines deferred content targeting a DOM element by id. **Unified**: one component for both synchronous and deferred content. The behaviour depends on `children`:
+
+| `children` type     | `fallback` | Behaviour                                         |
+| ------------------- | ---------- | ------------------------------------------------- |
+| `VNode` (plain JSX) | N/A        | Registers content; renders a placeholder          |
+| `VNode` (plain JSX) | provided   | Registers content; placeholder renders `fallback` |
+| `(signal) => …`     | N/A        | Lazy content; renders a placeholder               |
+| `(signal) => …`     | provided   | Lazy content; placeholder renders `fallback`      |
+
+**Sync**: plain JSX:
+
+```tsx
+import { Defer } from "@vincle/flow";
+
+<Defer target="page"><h1>Hello</h1></Defer>
+<Defer target="comments"><Comments /></Defer>
+```
+
+**Lazy with placeholder**: factory + fallback:
+
+```tsx
+<Defer target="comments" fallback={<p>Loading…</p>}>
+  {() => <Comments />}
+</Defer>
+```
+
+**Cancellable**: factory receives `AbortSignal` (request lifetime + per-fragment timeout):
+
+```tsx
+// One-shot
+<Defer target="page">{() => <h1>Hello</h1>}</Defer>
+
+// Async
+<Defer target="comments">{() => <Comments />}</Defer>
+
+// Stream: each yield is a separate patch
+<Defer target="feed" merge="append">
+  {() => liveRows()}
+</Defer>
+
+// With timeout: receives AbortSignal
+<Defer target="dashboard" timeout={2000}>
+  {(signal) => <Dashboard signal={signal} />}
+</Defer>
+```
+
+The factory is invoked only when the fragment is about to render. It receives an `AbortSignal` for cancellation and must return a renderable JSX node (or a `Promise` / `AsyncIterable` thereof, which the runtime unwraps automatically).
+
+`Defer` always renders a placeholder at its position in the shell: `fallback` is that placeholder's content (empty if none given), and the deferred content replaces it when it resolves. Rendering a `Defer` without any adapter throws at registration: there is no placeholder to emit and nothing to patch into.
+
+### `<Include>`: client-side fetch only
+
+Renders a placeholder with a `src` attribute: the browser fetches the fragment after the shell lands. No server-push, works with any static host.
+
+```tsx
+import { Include } from "@vincle/flow";
+
+<Include src="/fragments/comments.html" />;
+<Include src="/fragments/stats.html" fallback={<Spinner />} />;
+
+// @ts-expect-error: dangerous schemes are rejected at compile time
+<Include src="javascript:alert(1)" />;
+```
+
+`src` uses a strict **whitelist**: for string **literals**, only `http(s):` and relative paths compile. Every other scheme (`javascript:`, `data:`, `mailto:`, …) is a compile-time error. A fragment fetch needs no other scheme. Dynamic `string` values pass through and remain the caller's responsibility.
+
+Named after the [draft HTML `<include>` element](https://github.com/whatwg/html/issues/2791) and ESI `<esi:include>`: short, standard, self-explanatory.
+
+### Content forms
+
+`Defer` accepts content in either form:
+
+| Child                        | Behaviour                                                            |
+| ---------------------------- | -------------------------------------------------------------------- |
+| JSX node (plain children)    | Deferred automatically: executes when the fragment renders           |
+| `(signal: AbortSignal) => …` | **Cancellable**: receives `AbortSignal` (request cancel + `timeout`) |
+
+`Slot` children are plain JSX (not deferred). They render immediately as the fallback placeholder in the shell.
+
+### Common props
+
+| Prop       | Applies to | Meaning                                                            |
+| ---------- | ---------- | ------------------------------------------------------------------ |
+| `name`     | `Slot`     | id of the placeholder (required)                                   |
+| `target`   | `Defer`    | target DOM id to push content into                                 |
+| `fallback` | `Defer`    | placeholder content shown in the shell (only for lazy factories)   |
+| `merge`    | `Defer`    | how content applies to its target (default `"replace"`): see below |
+| `timeout`  | `Defer`    | per-fragment render timeout in ms                                  |
+| `onError`  | `Defer`    | per-fragment error handler, overriding the renderer's `onError`    |
+| `src`      | `Include`  | URL the browser fetches for the fragment content                   |
+
+### Merge types
+
+`merge` describes how content is applied **relative to the target DOM element identified by `id`**.
+
+| `merge`     | Effect                                                         |
+| ----------- | -------------------------------------------------------------- |
+| `"replace"` | Target element is replaced by content (default)                |
+| `"append"`  | Content inserted as last child of target                       |
+| `"prepend"` | Content inserted as first child of target                      |
+| `"before"`  | Content inserted as previous sibling of target                 |
+| `"after"`   | Content inserted as next sibling of target                     |
+| `"morph"`   | Target element is diffed against content, preserving DOM state |
+
+The first five say **where** content goes; `"morph"` says **how** it is applied: the client diffs instead of swapping, so focus, scroll position and form state survive the update. It needs a diffing client: `TurboAdapter` (Turbo >= 8) and `HtmxAdapter` (htmx >= 4) only.
+
+An adapter that cannot express a merge **rejects it at registration** with a clear error (see capabilities). `NativeAdapter` supports the five positions but not `"morph"`: diffing is far past a 550 B budget. `WebPlatformAdapter` and `EsiAdapter` support `"replace"` only.
+
+## Adapters
+
+Each adapter implements `Placeholder`/`Patch`/`Frame` (JSX), optional `transformShell`, and a `capabilities` descriptor. The streaming wire format (shell → fragments, `\n`-separated) is the primitive's own serialization in `renderToStream`: an adapter only declares it can stream (`capabilities.streaming: true`), it does not implement the wire. Adapters are **pure wire formats**: HTTP negotiation is a separate concern (see below).
+
+| Adapter              | `Placeholder`          | `Patch` (streaming inline)                      | `Frame` (SSG lazy-load) |
+| -------------------- | ---------------------- | ----------------------------------------------- | ----------------------- |
+| `TurboAdapter`       | `<turbo-frame>`        | `<turbo-stream action="…">`                     | `<turbo-frame id="…">`  |
+| `HtmxAdapter`        | `<div hx-get>`         | `<div hx-swap-oob="…">`                         | `<div id="…">`          |
+| `NativeAdapter`      | `<?start name>…<?end>` | `<template for>` (`data-merge` for non-replace) | `<template for="…">`    |
+| `WebPlatformAdapter` | `<?start name>…<?end>` | `<template for="…">` (`replace` only)           | `<template for="…">`    |
+| `EsiAdapter`         | `<esi:include src>`    | `<esi:inline name fetchable>` (static only)     | raw HTML                |
+
+- **`Patch`**: fragment delivered inline in the same HTTP response as the shell.
+- **`Frame`**: fragment served as a standalone file fetched by the client (SSG).
+- `NativeAdapter` injects a ~550 B polyfill for DOM patching. Pass `WebPlatformAdapter` for zero-JS output, or `EsiAdapter` for CDN-level composition without client JS. An adapter is **required**: `renderToStream` takes it as its second argument, and a `Defer` without one throws at registration.
+
+### Capabilities
+
+Every adapter declares what its wire format can express:
+
+```ts
+type AdapterCapabilities = {
+  streaming: boolean; // can carry a live FlowEvent stream
+  merges: readonly MergeType[]; // which merges it supports
+};
+```
+
+This is surfaced in the type system. `renderToStream` / `serve` require a streaming adapter, so **`EsiAdapter` is rejected at compile time** there: ESI composition happens at the CDN, via `renderToStatic` + `emitFragments`. An unsupported `merge` fails fast at registration.
+
+#### `NativeAdapter` (~550 B polyfill)
+
+Uses the [Declarative Partial Updates](https://developer.chrome.com/blog/declarative-partial-updates) API plus a minimal polyfill injected via `transformShell`. All five merge positions (not `"morph"`), no external client library, works in modern browsers.
+
+Every update is a **declarative `<template for>`**: the merge mode rides on `data-merge`, lazy client fetches on `data-src`. There are **no per-fragment inline scripts**; the only JS is a single static polyfill, which makes a strict CSP straightforward:
+
+```ts
+import { NativeAdapter, nativePolyfillHash, NATIVE_POLYFILL } from "@vincle/flow/adapters";
+
+// Option A: keep the inline <script>, pin it by hash (static ⇒ cache/SSG-safe):
+res.headers.set("Content-Security-Policy", `script-src 'self' '${await nativePolyfillHash()}'`);
+
+// Option B: serve the polyfill from your origin under script-src 'self':
+//   write NATIVE_POLYFILL to e.g. /flow.js, then:
+const selfHosted = {
+  ...NativeAdapter,
+  transformShell: (shell: string) => injectIntoHead(shell, `<script src="/flow.js"></script>`),
+};
+```
+
+A per-request **nonce** is intentionally not offered: it would break the static-cache/SSG story. A hash works because the script never changes.
+
+#### `WebPlatformAdapter`
+
+Emits the [WICG Declarative Partial Updates](https://developer.chrome.com/docs/web-platform/declarative-partial-updates) wire format without a client-side runtime. It supports `"replace"` only and requires native browser support, which is not universal. Use `NativeAdapter` for a polyfilled fallback.
+
+#### `EsiAdapter`: CDN-level composition
+
+For **SSG with a CDN ESI processor** (Varnish, Fastly, nginx ESI module). The shell contains `<esi:include src="…">` tags; the CDN fetches each fragment independently, applies separate TTLs, and assembles the final response before it reaches the browser. `"replace"` only; no client-side JS.
+
+```tsx
+// Defer with ESI: placeholder becomes esi:include, content renders the fragment
+<Defer target="nav" fallback={<span>Loading nav…</span>}>
+  {(signal) => <Nav signal={signal} />}
+</Defer>
+<Defer target="feed" fallback={<span>Loading feed…</span>}>
+  {(signal) => <Feed signal={signal} />}
+</Defer>
+// Plain JSX also works when no signal is needed:
+<Defer target="footer" fallback={<span>Loading…</span>}>
+  <Footer />
+</Defer>
+```
+
+## Usage
+
+### Streaming (server pushes fragments)
+
+```tsx
+import { renderToStream, Defer } from "@vincle/flow";
+import { NativeAdapter } from "@vincle/flow/adapters";
+
+const stream = renderToStream(
+  () => (
+    <html>
+      <body>
+        <header>Fast</header>
+        <Defer target="dashboard" fallback={<p>Loading…</p>}>
+          <HeavyDashboard />
+        </Defer>
+      </body>
+    </html>
+  ),
+  NativeAdapter,
+);
+// → ReadableStream<string>. Pipe it to the HTTP response.
+// Swap the adapter (TurboAdapter, HtmxAdapter, …) to change wire format.
+```
+
+### Static generation, pure-static (no deferred content)
+
+```tsx
+import { renderToStatic } from "@vincle/flow";
+
+await renderToStatic(async (ctx) => {
+  for (const page of pages) {
+    const html = await ctx.renderPage(() => page.component({ currentPage: page.url }));
+    await Bun.write(page.outPath, "<!DOCTYPE html>\n" + html);
+  }
+});
+```
+
+No adapter required: @vincle/flow stays invisible for pure-static rendering, as long as no `<Defer>` is rendered. A `Defer` without an adapter throws at registration.
+
+### Static generation with deferred fragments
+
+```tsx
+import { renderToStatic } from "@vincle/flow";
+import { NativeAdapter } from "@vincle/flow/adapters";
+
+await renderToStatic(
+  async (ctx) => {
+    for (const page of pages) {
+      const html = await ctx.renderPage(() => page.component({ currentPage: page.url }));
+      await Bun.write(page.outPath, "<!DOCTYPE html>\n" + html);
+    }
+
+    // Each fragment is already wrapped in adapter.Frame and rendered,
+    // `html` is ready to write, no raw()/renderToString needed.
+    await ctx.emitFragments((id, url, html) => Bun.write("./out" + url, html));
+  },
+  {
+    adapter: NativeAdapter,
+    generatePath: (id) => `/fragments/${id}.html`,
+  },
+);
+```
+
+### On-demand fragment regeneration
+
+When one piece of data changes, `renderFragment` writes just its fragment: no site rebuild:
+
+```tsx
+import { renderFragment } from "@vincle/flow";
+import { NativeAdapter } from "@vincle/flow/adapters";
+
+const { url, html } = await renderFragment("price-AAPL", <span>{price}</span>, {
+  adapter: NativeAdapter,
+});
+// `url` matches what the full build wrote: upload `html` there (blob store,
+// on-demand revalidation, CDN purge + PUT…). The shell that includes it is untouched.
+```
+
+This is host-agnostic on purpose. It fits Netlify's on-demand functions or Vercel's on-demand revalidation, but doesn't depend on either.
+
+### HTTP responses with negotiation
+
+Negotiation is **opt-in and decoupled from the adapter**: pass a `negotiate` function (e.g. `negotiateHtmx`, or your own) to extract per-request hints and headers. Without it, the full page is rendered and the client library extracts its own target.
+
+```tsx
+import { serve, negotiateHtmx } from "@vincle/flow/http";
+import { WebPlatformAdapter } from "@vincle/flow/adapters";
+
+Bun.serve({
+  fetch(req) {
+    return serve(req, (n) => <App target={n.target} />, WebPlatformAdapter, {
+      negotiate: negotiateHtmx,
+      // `mode: "fragment"` (shell suppressed) is an explicit opt-in and only
+      // produces output when the targeted content is expressed as deferred fragments.
+    });
+  },
+});
+```
+
+### Composing shell transforms
+
+`composeShell` chains several `transformShell` functions (e.g. to inject `<title>`, asset links) into one: falsy entries are skipped, so an adapter's own transform splices in cleanly:
+
+```tsx
+import { NativeAdapter, createAdapter } from "@vincle/flow/adapters";
+import { composeShell, injectIntoHead } from "@vincle/flow/utils";
+
+const metadata = () => (html: string) => injectIntoHead(html, "<title>Home</title>");
+
+const MyAdapter = createAdapter({
+  ...NativeAdapter,
+  transformShell: composeShell(NativeAdapter.transformShell, metadata()),
+});
+```
+
+#### `ShellContext`
+
+`transformShell` receives a `ShellContext` with one field:
+
+```ts
+interface ShellContext {
+  fragments: { size: number };
+}
+```
+
+The fragment count is the number of registered `<Defer>` / `<Slot>` entries after the shell rendered. Use it to conditionally inject client runtime only when fragments exist:
+
+```ts
+const SmartAdapter = {
+  ...NativeAdapter,
+  transformShell: (shell: string, ctx) => (ctx.fragments.size > 0 ? injectPolyfill(shell) : shell),
+};
+```
+
+### Fragment timeouts
+
+`renderToStream`, `serve`, and `renderToStatic` accept `defaultTimeout` on their options:
+
+```ts
+renderToStream(() => <Page />, NativeAdapter, { defaultTimeout: 5000 });
+```
+
+It is a fallback for any `<Defer>` that has no `timeout` prop. A fragment that exceeds its timeout aborts and routes to `onError` (or logs and skips). Per-fragment `timeout` overrides the default:
+
+```tsx
+<Defer target="page" timeout={2000}>
+  {/* This fragment has a 2s timeout, not the 5s default */}
+  <SlowComponent />
+</Defer>
+```
+
+### Custom negotiation
+
+Write a custom `negotiate` function for any client library that uses custom headers:
+
+```ts
+import type { Negotiate } from "@vincle/flow";
+
+const negotiateMyLib: Negotiate = (req) => {
+  const fragment = req.headers.get("X-Fragment-Id") ?? undefined;
+  return {
+    headers: { Vary: "X-Fragment-Id" },
+    target: fragment,
+  };
+};
+```
+
+The `Vary` header is **unioned** with existing `Vary` values (not overwritten), so multiple negotiators or manual headers never corrupt shared-cache keys.
+
+```
+
+## API
+
+All exports are importable from `@vincle/flow` unless noted otherwise.
+
+### Components
+
+| Export    | Import path               | Description                                                                    |
+| --------- | ------------------------- | ------------------------------------------------------------------------------ |
+| `Slot`    | `@vincle/flow`            | Named insertion point with optional fallback children; renders a placeholder   |
+| `Defer`   | `@vincle/flow`            | Push deferred content into a target DOM id: sync (plain JSX) or lazy (factory) |
+| `Include` | `@vincle/flow`            | Client-side fetch placeholder: no server deferral                              |
+| `Style`   | `@vincle/flow/components` | Named, deduplicated `<style>` tag                                              |
+| `Script`  | `@vincle/flow/components` | Named, deduplicated `<script>` tag                                             |
+
+### Renderers
+
+| Export               | Import path         | Description                                                                                   |
+| -------------------- | ------------------- | --------------------------------------------------------------------------------------------- |
+| `renderToStream`     | `@vincle/flow`      | Streams shell + fragments as a `ReadableStream<string>` via the given `adapter`               |
+| `renderToFlowEvents` | `@vincle/flow`      | Lower level: `ReadableStream<FlowEvent>` (semantic events) with backpressure and cancellation |
+| `renderToStatic`     | `@vincle/flow`      | Runs `handler` in a static render scope                                                       |
+| `renderFragment`     | `@vincle/flow`      | Renders one fragment on demand, outside a full build: for on-demand regeneration              |
+| `serve`              | `@vincle/flow/http` | Full HTTP `Response` builder                                                                  |
+
+### Negotiation
+
+| Export          | Import path         | Description                                      |
+| --------------- | ------------------- | ------------------------------------------------ |
+| `negotiateHtmx` | `@vincle/flow/http` | HTMX negotiation: reads `HX-Target`, sets `Vary` |
+| `Negotiate`     | `@vincle/flow/http` | Type: `(req: Request) => Negotiation`            |
+
+### Adapters
+
+| Export               | Import path             | Description                                            |
+| -------------------- | ----------------------- | ------------------------------------------------------ |
+| `NativeAdapter`      | `@vincle/flow/adapters` | Declarative Partial Updates + polyfill: no `morph`     |
+| `TurboAdapter`       | `@vincle/flow/adapters` | Hotwire Turbo Streams: all merge types                 |
+| `HtmxAdapter`        | `@vincle/flow/adapters` | HTMX OOB swaps: all merge types                        |
+| `WebPlatformAdapter` | `@vincle/flow/adapters` | Pure WICG spec, zero JS: `replace` only                |
+| `EsiAdapter`         | `@vincle/flow/adapters` | CDN-level ESI composition: `replace` only, static only |
+| `createAdapter`      | `@vincle/flow/adapters` | Build a custom adapter                                 |
+| `NATIVE_POLYFILL`    | `@vincle/flow/adapters` | Native adapter polyfill as a JS string                 |
+| `nativePolyfillHash` | `@vincle/flow/adapters` | `() => Promise<string>`: CSP hash for the polyfill     |
+
+### Types
+
+| Export                | Import path             | Description                                                                                                                                              |
+| --------------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Adapter`             | `@vincle/flow/adapters` | `{ Placeholder, Patch, Frame, capabilities, transformShell? }`                                                                                           |
+| `StreamingAdapter`    | `@vincle/flow/adapters` | `Adapter` with `capabilities.streaming: true`                                                                                                            |
+| `AdapterCapabilities` | `@vincle/flow/adapters` | `{ streaming: boolean; merges: readonly MergeType[] }`                                                                                                   |
+| `ShellContext`        | `@vincle/flow/adapters` | What `transformShell` receives: `{ fragments: { size } }`                                                                                                |
+| `PureStaticContext`   | `@vincle/flow`          | Static generation context (no `emitFragments`)                                                                                                           |
+| `StaticContext`       | `@vincle/flow`          | Static generation context with `emitFragments`                                                                                                           |
+| `MergeType`           | `@vincle/flow`          | `"replace" \| "append" \| "prepend" \| "before" \| "after" \| "morph"`                                                                                   |
+| `FlowEvent`           | `@vincle/flow`          | `{ type: "shell" \| "fragment" \| "close", … }`                                                                                                          |
+| `Negotiation`         | `@vincle/flow`          | `{ headers?, mode?, target? }`                                                                                                                           |
+| `DeferContent`        | `@vincle/flow`          | `JSX.Element \| string \| ((signal: AbortSignal) => JSX.Element) \| AsyncIterable<JSX.Element> \| ((signal: AbortSignal) => AsyncIterable<JSX.Element>)` |
+
+### Utilities
+
+| Export           | Import path          | Description                                                          |
+| ---------------- | -------------------- | -------------------------------------------------------------------- |
+| `composeShell`   | `@vincle/flow/utils` | Compose several `transformShell` (string→string) into one            |
+| `injectIntoHead` | `@vincle/flow/utils` | Insert markup before `</head>` (building block for shell transforms) |
+
+### Flow context
+
+| Export        | Import path            | Description                                                                             |
+| ------------- | ---------------------- | --------------------------------------------------------------------------------------- |
+| `Flow`        | `@vincle/flow/context` | The `Scope` key for the per-render flow context: `Scope.get(Flow)` from within a render |
+| `FlowContext` | `@vincle/flow/context` | The per-render context: `config`, `registerFragment`, `nextId`, asset state             |
+
+> `<Style>` / `<Script>` emit their tag directly, deduplicating as the walk
+> reaches them: no post-render pass, so nothing has to re-derive the document
+> order the engine already guarantees.
+
+## License
+
+MIT © Christophe Jean
+```

package/dist/adapters/index.d.ts

@@ -0,0 +1,2 @@
+import { a as withPolyfill, c as TurboAdapter, d as createAdapter, i as WebPlatformAdapter, l as Adapter, n as HtmxAdapter, o as NATIVE_POLYFILL, r as NativeAdapter, s as nativePolyfillHash, t as EsiAdapter, u as ShellContext } from "../index-M7xu3JXg.js";
+export { type Adapter, EsiAdapter, HtmxAdapter, NATIVE_POLYFILL, NativeAdapter, type ShellContext, TurboAdapter, WebPlatformAdapter, createAdapter, nativePolyfillHash, withPolyfill };

package/dist/adapters/index.js

@@ -0,0 +1,19 @@
+import{a as e,r as t,u as n}from"../utils-DKRixAvn.js";import{raw as r}from"@vincle/core";import{Fragment as i,jsx as a,jsxs as o}from"@vincle/core/jsx-runtime";import{escapeAttr as s}from"@vincle/core/html";const c={streaming:!0,merges:n};function l(t){let n={...t,capabilities:t.capabilities??c};return e(n,`createAdapter`),n}const u={replace:`replace`,append:`append`,prepend:`prepend`,before:`before`,after:`after`,morph:`replace`},d=l({Placeholder:function({id:e,src:t,children:n}){return t?/* @__PURE__ */ a(`turbo-frame`,{id:e,src:t,children:n}):/* @__PURE__ */ a(`turbo-frame`,{id:e,children:n})},Patch:({id:e,children:t,merge:n})=>/* @__PURE__ */ a(`turbo-stream`,{action:u[n],method:n===`morph`?`morph`:void 0,target:e,children:/* @__PURE__ */ a(`template`,{children:t})}),Frame:({id:e,children:t})=>/* @__PURE__ */ a(`turbo-frame`,{id:e,children:t})}),f=`(function(){
+var ADJ={append:"beforeend",prepend:"afterbegin",before:"beforebegin",after:"afterend"};
+function fill(name,frag){
+var it=document.createNodeIterator(document.body||document.documentElement,128),nd,s=null,e=null;
+while((nd=it.nextNode())){if(!s&&nd.nodeValue==='?start name="'+name+'"'){s=nd;continue;}if(s&&nd.nodeValue==='?end'){e=nd;break;}}
+if(!s)return;var c=s.nextSibling;while(c&&c!==e){var x=c.nextSibling;c.remove();c=x;}s.after(frag);
+}
+function run(t){
+var name=t.getAttribute("for");if(!name)return;
+var src=t.getAttribute("data-src");
+if(src!=null&&src!==""){try{var p=new URL(src,document.baseURI||location.href).protocol;if(p!=="http:"&&p!=="https:"){t.remove();return;}}catch(e){t.remove();return;}fetch(src).then(function(r){return r.text();}).then(function(h){var x=document.createElement("template");x.innerHTML=h;fill(name,x.content);});t.remove();return;}
+var merge=t.getAttribute("data-merge");
+if(merge&&merge!=="replace"){var el=document.getElementById(name);if(el)el.insertAdjacentHTML(ADJ[merge],t.innerHTML);t.remove();return;}
+fill(name,t.content.cloneNode(true));t.remove();
+}
+function scan(r){var ts=r.querySelectorAll?r.querySelectorAll("template[for]"):[];for(var i=0;i<ts.length;i++)run(ts[i]);}
+scan(document);
+new MutationObserver(function(ms){ms.forEach(function(m){m.addedNodes.forEach(function(n){if(n.nodeName==='TEMPLATE'&&n.getAttribute&&n.getAttribute('for'))run(n);});});}).observe(document.documentElement,{childList:true,subtree:true});
+})()`,p=`<script>${f}<\/script>`;async function m(){let e=await crypto.subtle.digest(`SHA-256`,new TextEncoder().encode(f));return`sha256-${btoa(String.fromCharCode(...new Uint8Array(e)))}`}const h=l({capabilities:{streaming:!0,merges:[`replace`]},Placeholder:function({id:e,src:t,children:n}){let c=s(e);return t?/* @__PURE__ */ o(i,{children:[r(`<?start name="${c}">`),n,r(`<?end>`),/* @__PURE__ */ a(`template`,{htmlFor:e,"data-src":t})]}):/* @__PURE__ */ o(i,{children:[r(`<?start name="${c}">`),n,r(`<?end>`)]})},Patch:({id:e,children:t,merge:n})=>n===`replace`?/* @__PURE__ */ a(`template`,{htmlFor:e,children:t}):/* @__PURE__ */ a(`template`,{htmlFor:e,"data-merge":n,children:t}),Frame:({id:e,children:t})=>/* @__PURE__ */ a(`template`,{htmlFor:e,children:t})}),g=[`replace`,`append`,`prepend`,`before`,`after`];function _(e){return{...e,capabilities:{streaming:e.capabilities.streaming,merges:g},transformShell:(n,r)=>{let i=e.transformShell?e.transformShell(n,r):n;return r.fragments.size===0?i:t(i,p)}}}const v=_(h),y={replace:`outerHTML`,append:`beforeend`,prepend:`afterbegin`,before:`beforebegin`,after:`afterend`,morph:`outerMorph`},b=l({Placeholder:function({id:e,src:t,children:n}){return t?/* @__PURE__ */ a(`div`,{id:e,"hx-get":t,"hx-trigger":`load`,"hx-swap":`outerHTML`,children:n}):/* @__PURE__ */ a(`div`,{id:e,children:n})},Patch:({id:e,children:t,merge:n})=>/* @__PURE__ */ a(`div`,{id:e,"hx-swap-oob":y[n],children:t}),Frame:({id:e,children:t})=>/* @__PURE__ */ a(`div`,{id:e,children:t})}),x=l({capabilities:{streaming:!1,merges:[`replace`]},Placeholder:({src:e,children:t})=>e?/* @__PURE__ */ a(i,{children:r(`<esi:include src="${s(e)}" />`)}):/* @__PURE__ */ a(i,{children:t}),Patch:({id:e,children:t})=>/* @__PURE__ */ o(i,{children:[r(`<esi:inline name="${s(e)}" fetchable="yes">`),t,r(`</esi:inline>`)]}),Frame:({children:e})=>/* @__PURE__ */ a(i,{children:e})});export{x as EsiAdapter,b as HtmxAdapter,f as NATIVE_POLYFILL,v as NativeAdapter,d as TurboAdapter,h as WebPlatformAdapter,l as createAdapter,m as nativePolyfillHash,_ as withPolyfill};

package/dist/components/index.d.ts

@@ -0,0 +1,19 @@
+import { Awaitable, JSX } from "@vincle/core";
+//#region src/components/assets.d.ts
+interface BaseAssetProps {
+  name: string;
+}
+interface StyleProps extends BaseAssetProps {
+  media?: string;
+  children: string | (() => Awaitable<string>);
+}
+interface ScriptProps extends BaseAssetProps {
+  src?: string;
+  module?: boolean;
+  defer?: boolean;
+  children?: string | (() => Awaitable<string>);
+}
+export declare function Style(props: StyleProps): JSX.Element | null;
+export declare function Script(props: ScriptProps): JSX.Element | null;
+//#endregion
+export type { ScriptProps, StyleProps };

package/dist/components/index.js

@@ -0,0 +1 @@
+import{l as e,t,u as n}from"../context-DlzTTBsQ.js";import{Scope as r}from"@vincle/core";import{jsx as i}from"@vincle/core/jsx-runtime";const a=e=>typeof e==`function`?e():e;function o(o){let{assets:s}=r.get(t),{name:c,media:l,children:u}=o,d={};return l!=null&&(d.media=l),n(s,c,{type:`style`,content:u,attrs:d}),e(s,c)?/* @__PURE__ */ i(`style`,{"data-name":c,...d,children:a(u)}):null}function s(o){let{assets:s}=r.get(t),{name:c,src:l,module:u,defer:d,children:f}=o,p={};l!=null&&(p.src=l),u&&(p.type=`module`),d&&(p.defer=!0);let m=f??``;return n(s,c,{type:`script`,content:m,attrs:p}),e(s,c)?/* @__PURE__ */ i(`script`,{"data-name":c,...p,children:a(m)}):null}export{s as Script,o as Style};

package/dist/context-DlzTTBsQ.js

@@ -0,0 +1 @@
+import{c as e,f as t,h as n,i as r,m as i,o as a,t as o,v as s}from"./utils-DKRixAvn.js";import{Scope as c,renderToString as l}from"@vincle/core";function u(){return{entries:/* @__PURE__ */ new Map,emitted:/* @__PURE__ */ new Set,suppressed:!1}}function d(){return{entries:/* @__PURE__ */ new Map,emitted:/* @__PURE__ */ new Set,suppressed:!0}}function f(e,t,n){if(e.entries.has(t)){if(process.env.NODE_ENV!==`production`){let r=e.entries.get(t);(r.type!==n.type||JSON.stringify(r.attrs)!==JSON.stringify(n.attrs))&&console.warn(`[vincle/flow] Asset "${t}" is declared multiple times with different attributes. The first declaration wins.`)}return}e.entries.set(t,n)}function p(e,t){return e.suppressed||e.emitted.has(t)?!1:(e.emitted.add(t),!0)}function m(a){let c=/* @__PURE__ */ new Map,l=a.adapter?.capabilities.merges??[];return{register(u,d){if(o(u,`Defer`),e(d.timeout,`<Defer target="${u}">`),!a.adapter)throw s(`${r} <Defer target="${u}">: Defer requires an adapter: without one there is no placeholder to render and no patch to emit. Pass { adapter: ... } to renderToStatic, or render through renderToStream/serve with an adapter (TurboAdapter, NativeAdapter, HtmxAdapter, WebPlatformAdapter, EsiAdapter).`,n);if(!l.includes(d.merge)){let e=l.length>0?`it supports: ${l.join(`, `)}`:`it supports no merges (static output only)`;throw s(`${r} <Defer target="${u}" merge="${d.merge}">: merge="${d.merge}" is not supported by this adapter: ${e}. Pick one of those, or use an adapter that supports "${d.merge}".`,i)}if(c.has(u))throw s(`${r} <Defer target="${u}">: target is already registered: a target is registered once per render. Two <Defer> on the same target would emit two placeholders with the same DOM id, and only the second fragment would be patched. Give the second fragment a different target, or omit target to get a generated one.`,t);c.set(u,d)},get(e){return c.get(e)},outstanding(e){let t=[];for(let[n,r]of c)e.has(n)||t.push([n,r]);return t},hasOutstanding(e){for(let t of c.keys())if(!e.has(t))return!0;return!1},get size(){return c.size},clear(){c.clear()}}}const h=c.key(`@vincle/flow:flow`);function g(e,t,i){let{config:a}=c.get(h);if(!a.adapter)throw s(`${r} renderPlaceholder("${e}"): no adapter configured: a placeholder needs an adapter to emit its deferred-fragment markup. Pass { adapter: ... } to renderToStatic, or render through renderToStream() with an adapter.`,n);let o=i??(a.mode===`static`?a.generatePath(e):null);return a.adapter.Placeholder({id:e,src:o,children:t??null})}const _=()=>({names:/* @__PURE__ */ new Set,mark:void 0});function v(e,t){return e.mark??=`vincle-defer-${crypto.randomUUID()}`,[`<!--${e.mark}:${t}-->`,`<!--/${e.mark}:${t}-->`]}async function y(e){let t=await l(e);if(!t.includes(`<!--vincle-defer-`))return t;let{slots:n}=c.get(h),r=`<!--${n.mark}:`,i=0;for(;;){let e=t.indexOf(r,i);if(e===-1)return t;let a=t.indexOf(`-->`,e),o=t.slice(e+r.length,a),s=`<!--/${n.mark}:${o}-->`,c=t.indexOf(s,a);if(c===-1)return t;let l=n.names.has(o)?``:t.slice(a+3,c);t=t.slice(0,e)+l+t.slice(c+s.length),i=e}}function b(e){a(e);let t=0,n=m(e),r=u();c.set(h,{config:e,fragments:n,assets:r,slots:_(),nextId:()=>`${e.idPrefix??`fragment-`}${++t}`,registerFragment(e,t){n.register(e,t)}})}function x(){let e=c.get(h);c.set(h,{...e,assets:u(),slots:_()})}function S(){let e=c.get(h);c.set(h,{...e,assets:d()})}function C(e,t){return c.with(async function(){return b(t),e(c.get(h))})}export{y as a,C as c,v as i,p as l,b as n,g as o,x as r,S as s,h as t,f as u};

package/dist/context.d.ts

@@ -0,0 +1,127 @@
+import { S as OnError, m as FlowConfig, p as DeferContent, y as MergeType } from "./index-M7xu3JXg.js";
+import { JSX, ScopeKey, renderToString } from "@vincle/core";
+//#region src/assets.d.ts
+type AssetType = "style" | "script";
+type AssetContent = string | (() => string | Promise<string>);
+type AssetEntry = {
+  type: AssetType;
+  content: AssetContent;
+  attrs: Record<string, string | boolean>;
+};
+type AssetState = {
+  entries: Map<string, AssetEntry>;
+  emitted: Set<string>;
+  /**
+   * Suppress every emission, whatever the name. Used for standalone fragment
+   * files, which carry no assets of their own: see `renderToStatic`.
+   */
+  suppressed: boolean;
+};
+//#endregion
+//#region src/fragment-store.d.ts
+/**
+ * A unit of deferred content, keyed by its target DOM `id`. The renderer
+ * decides at drain time whether `content` is a one-shot patch or a live
+ * stream: see `flushFragments`.
+ */
+type FragmentEntry = {
+  content: DeferContent;
+  /** Tree context at the point where the fragment was registered. */
+  treeScope?: <T>(render: () => T) => T;
+  merge: MergeType;
+  /** Per-fragment render timeout in ms. Falls back to FlowOptions.defaultTimeout. */
+  timeout?: number;
+  /** Per-fragment error handler, overriding FlowOptions.onError. */
+  onError?: OnError;
+  /** Initial fallback content rendered in the placeholder element. */
+  fallback?: JSX.Element;
+};
+/**
+ * Internal storage for registered fragment entries.
+ *
+ * Hides the `Map` implementation behind a narrow interface so callers don't
+ * depend on the storage primitive. Iteration logic (filtering processed ids)
+ * lives here rather than in `flushFragments`.
+ */
+type FragmentStore = {
+  /** Register an entry for `id`. One target is registered once per render: a second registration throws. Validates id, timeout, adapter and merge support. */
+  register(id: string, entry: FragmentEntry): void;
+  /** Retrieve a registered entry by id. */
+  get(id: string): FragmentEntry | undefined;
+  /** Entries whose id is not in `processed`. */
+  outstanding(processed: Set<string>): Array<[string, FragmentEntry]>;
+  /** True when at least one entry is not in `processed`. */
+  hasOutstanding(processed: Set<string>): boolean;
+  /** Total registered entries (including processed ones). */
+  readonly size: number;
+  /** Purge all entries to eagerly release closures and references. */
+  clear(): void;
+};
+//#endregion
+//#region src/context.d.ts
+export interface FlowContext {
+  config: FlowConfig;
+  /** Internal fragment-content store. */
+  fragments: FragmentStore;
+  /** Named asset state for `<Style name>` / `<Script name>` dedup. */
+  assets: AssetState;
+  /** The page's `<Slot>` names, and the mark around a placeholder one may replace. */
+  slots: SlotState;
+  nextId: () => string;
+  /**
+   * Register fragment content to render into the DOM element with this `id`.
+   * Validates the id and that `merge` is supported by the active adapter.
+   * Throws when the id is already registered: one target per render.
+   */
+  registerFragment(id: string, entry: FragmentEntry): void;
+}
+export declare const Flow: ScopeKey<FlowContext>;
+/**
+ * The single adapter negotiation for deferred-fragment placeholders. Defer,
+ * Slot and Include all end in `adapter.Placeholder({ id, src, children })`;
+ * only their *policies* differ (what to register, which URL to allow, whether
+ * a missing adapter is an error). Everything about the negotiation lives here:
+ *
+ * - a missing adapter is an error (callers that want to tolerate it, e.g.
+ *   Defer in pure-static mode, check `config.adapter` themselves first);
+ * - in static mode `src` defaults to `generatePath(id)`; callers that carry
+ *   their own URL (Include) pass it explicitly;
+ * - children are normalized to `null`.
+ */
+export declare function renderPlaceholder(id: string, children?: JSX.Element | null, src?: string): JSX.Element;
+/**
+ * A `<Defer>` whose target names a `<Slot>` has no placeholder of its own: the
+ * slot is it. One rendered earlier is known at once. One rendered later is not,
+ * so the `<Defer>` marks its placeholder, and `renderFlow` drops it once the page
+ * is rendered if a slot of that name turned up.
+ */
+export interface SlotState {
+  readonly names: Set<string>;
+  /** Random per page, so no markup the author writes can match it. */
+  mark: string | undefined;
+}
+/** The comment pair around the placeholder of a `<Defer>` whose slot may come later. */
+export declare function pendingMarks(slots: SlotState, id: string): [string, string];
+/**
+ * Render a tree that may hold flow components, and settle every marked
+ * placeholder: dropped when a slot of its id was rendered, unwrapped otherwise.
+ * Ids are unique per render, so each open mark has one close mark.
+ */
+export declare function renderFlow(node: Parameters<typeof renderToString>[0]): Promise<string>;
+export declare function initFlow(config: FlowConfig): void;
+/**
+ * Give the current scope its own asset state and slot names: a page boundary.
+ *
+ * A new context object, not a mutation of the existing one: two `renderPage`
+ * calls awaited together each get their own scope, and a shared object would
+ * have them race on `.assets` and `.slots`.
+ */
+export declare function initFlowAssets(): void;
+/**
+ * Give the current scope an asset state that emits nothing: used for standalone
+ * fragment files, whose assets belong to the shell that includes them.
+ */
+export declare function suppressFlowAssets(): void;
+export declare function withFlow<T>(handler: (ctx: FlowContext) => T, config: FlowConfig): Promise<T>;
+//#endregion
+export type { FlowConfig };

package/dist/context.js

@@ -0,0 +1 @@
+import{a as e,c as t,i as n,n as r,o as i,r as a,s as o,t as s}from"./context-DlzTTBsQ.js";export{s as Flow,r as initFlow,a as initFlowAssets,n as pendingMarks,e as renderFlow,i as renderPlaceholder,o as suppressFlowAssets,t as withFlow};

package/dist/http.d.ts

@@ -0,0 +1,23 @@
+import { _ as FlowOptions, b as Negotiate, w as StreamingAdapter, x as Negotiation } from "./index-M7xu3JXg.js";
+import { JSX } from "@vincle/core";
+//#region src/http.d.ts
+/**
+ * Create a `Response` from a page component and an adapter.
+ *
+ * Negotiation is opt-in and orthogonal to the adapter: pass `negotiate` (e.g.
+ * `negotiateHtmx`, or your own) to extract per-request hints and headers.
+ * Without it, the full page is rendered: the client library extracts its own
+ * target. `mode: "fragment"` (shell suppressed) is an explicit opt-in; it only
+ * produces output when the targeted content is expressed as `<Defer>` fragments.
+ */
+export declare function serve(req: Request, page: (negotiation: Negotiation) => JSX.Element, adapter: StreamingAdapter, opts?: FlowOptions & ResponseInit & {
+  negotiate?: Negotiate;
+  mode?: "full" | "fragment";
+}): Promise<Response>;
+/**
+ * HTMX negotiation: read `HX-Target`, and `Vary` on it so shared caches never
+ * serve a fragment response to a full-page navigation.
+ */
+export declare function negotiateHtmx(req: Request): Negotiation;
+//#endregion
+export type { Negotiate, Negotiation };

package/dist/http.js

@@ -0,0 +1 @@
+import{n as e}from"./render-zCgGmdz0.js";function t(e,t){let n=/* @__PURE__ */ new Set,r=[],i=e=>{if(e)for(let t of e.split(`,`)){let e=t.trim(),i=e.toLowerCase();e&&!n.has(i)&&(n.add(i),r.push(e))}};i(e.get(`vary`)),i(t),e.set(`vary`,r.join(`, `))}function n(e,n,r){let i=new Headers(e);for(let e of[n,r])for(let[n,r]of new Headers(e??{}))n===`vary`?t(i,r):i.set(n,r);return i}async function r(t,r,i,a){let o=a?.negotiate?.(t)??{},s=e(()=>r(o),i,{...a,mode:a?.mode??o.mode}).pipeThrough(new TextEncoderStream),c=n({"content-type":`text/html; charset=utf-8`},a?.headers,o.headers);return new Response(s,{...a,headers:c})}function i(e){return{headers:{Vary:`HX-Target`},target:e.headers.get(`HX-Target`)??void 0}}export{i as negotiateHtmx,r as serve};

package/dist/index-M7xu3JXg.d.ts

@@ -0,0 +1,201 @@
+import { Awaitable, JSX, RawString } from "@vincle/core";
+//#region src/types.d.ts
+declare const ALL_MERGES: readonly ["replace", "append", "prepend", "before", "after", "morph"];
+/** Derived from `ALL_MERGES`, the single declaration `assertAdapter` also validates: runtime and type can't drift. */
+type MergeType = (typeof ALL_MERGES)[number];
+interface AdapterCapabilities {
+  streaming: boolean;
+  merges: readonly MergeType[];
+}
+/**
+ * Content renderable as a deferred fragment:
+ * - `JSX.Element | string`: one-shot sync/async render; strings are escaped
+ *   text. For real HTML, wrap with `raw()`.
+ * - `(signal) => JSX.Element | string`: lazy factory; `signal` = request abort + fragment timeout
+ * - `AsyncIterable<JSX.Element | string>`: streaming; each string is escaped
+ */
+type DeferValue = Awaitable<JSX.Element> | string;
+type DeferStream = AsyncIterable<JSX.Element | string>;
+type DeferContent = DeferValue | ((signal: AbortSignal) => DeferValue | DeferStream) | DeferStream | ((signal: AbortSignal) => DeferStream);
+interface Shell {
+  type: "shell";
+  html: string;
+}
+interface Fragment {
+  type: "fragment";
+  id: string;
+  html: string;
+  merge: MergeType;
+}
+type FlowEvent = Shell | Fragment | {
+  type: "close";
+  html: string;
+};
+type FlowErrorInfo = {
+  id: string;
+  kind: "fragment" | "stream";
+};
+type OnError = (error: unknown, info: FlowErrorInfo) => JSX.Element | void;
+interface FlowOptions {
+  signal?: AbortSignal;
+  onError?: OnError;
+  defaultTimeout?: number;
+}
+type FlowConfig = {
+  adapter: Adapter;
+  mode: "streaming";
+  generatePath?: never;
+  idPrefix?: string;
+} | {
+  adapter?: Adapter;
+  mode: "static";
+  generatePath: (id: string) => string;
+  idPrefix?: string;
+};
+interface Negotiation {
+  headers?: HeadersInit;
+  mode?: "full" | "fragment";
+  target?: string;
+}
+type Negotiate = (req: Request) => Negotiation;
+type StreamingAdapter = Adapter & {
+  capabilities: {
+    streaming: true;
+  };
+};
+//#endregion
+//#region src/adapters/shared.d.ts
+type Child = JSX.Element | RawString | string | null;
+/**
+ * What `transformShell` sees of the flow state, not the full `FlowContext`.
+ * A shell transform has exactly one legitimate reason to look at flow state:
+ * deciding whether fragments are pending. The full context also carries
+ * `assets`, `nextId`, and `registerFragment`/the rest of `FragmentStore`,
+ * mutation hooks a *shell transform* has no business reaching, so it isn't
+ * handed the context that owns them.
+ */
+interface ShellContext {
+  /** Pending `<Defer>`/`<Slot>` fragments, after the shell has rendered. */
+  readonly fragments: {
+    readonly size: number;
+  };
+}
+type Adapter = {
+  Placeholder(props: {
+    id: string;
+    src: string | null;
+    children: Child;
+  }): JSX.Element;
+  Patch(props: {
+    id: string;
+    children: Child;
+    merge: MergeType;
+  }): JSX.Element;
+  Frame(props: {
+    id: string;
+    children: Child;
+  }): JSX.Element;
+  capabilities: AdapterCapabilities;
+  /**
+   * Post-process the shell before it enters the stream. Receives a
+   * `ShellContext`, so an adapter can decide based on the real fragment
+   * count: e.g. inject a client runtime only when `ctx.fragments.size >
+   * 0` (fragments exist). Always called inside the flow scope, after the
+   * shell node renders.
+   */
+  transformShell?(shell: string, ctx: ShellContext): string;
+};
+declare const DEFAULT_CAPABILITIES: {
+  streaming: true;
+  merges: typeof ALL_MERGES;
+};
+type AdapterSpec<C extends AdapterCapabilities> = Omit<Adapter, "capabilities"> & {
+  capabilities?: C;
+};
+declare function createAdapter<const C extends AdapterCapabilities = typeof DEFAULT_CAPABILITIES>(spec: AdapterSpec<C>): Adapter & {
+  capabilities: C;
+};
+//#endregion
+//#region src/adapters/turbo.d.ts
+declare const TurboAdapter: Adapter & {
+  capabilities: {
+    streaming: true;
+    merges: typeof ALL_MERGES;
+  };
+};
+//#endregion
+//#region src/adapters/native-polyfill.d.ts
+declare const NATIVE_POLYFILL = "(function(){\nvar ADJ={append:\"beforeend\",prepend:\"afterbegin\",before:\"beforebegin\",after:\"afterend\"};\nfunction fill(name,frag){\nvar it=document.createNodeIterator(document.body||document.documentElement,128),nd,s=null,e=null;\nwhile((nd=it.nextNode())){if(!s&&nd.nodeValue==='?start name=\"'+name+'\"'){s=nd;continue;}if(s&&nd.nodeValue==='?end'){e=nd;break;}}\nif(!s)return;var c=s.nextSibling;while(c&&c!==e){var x=c.nextSibling;c.remove();c=x;}s.after(frag);\n}\nfunction run(t){\nvar name=t.getAttribute(\"for\");if(!name)return;\nvar src=t.getAttribute(\"data-src\");\nif(src!=null&&src!==\"\"){try{var p=new URL(src,document.baseURI||location.href).protocol;if(p!==\"http:\"&&p!==\"https:\"){t.remove();return;}}catch(e){t.remove();return;}fetch(src).then(function(r){return r.text();}).then(function(h){var x=document.createElement(\"template\");x.innerHTML=h;fill(name,x.content);});t.remove();return;}\nvar merge=t.getAttribute(\"data-merge\");\nif(merge&&merge!==\"replace\"){var el=document.getElementById(name);if(el)el.insertAdjacentHTML(ADJ[merge],t.innerHTML);t.remove();return;}\nfill(name,t.content.cloneNode(true));t.remove();\n}\nfunction scan(r){var ts=r.querySelectorAll?r.querySelectorAll(\"template[for]\"):[];for(var i=0;i<ts.length;i++)run(ts[i]);}\nscan(document);\nnew MutationObserver(function(ms){ms.forEach(function(m){m.addedNodes.forEach(function(n){if(n.nodeName==='TEMPLATE'&&n.getAttribute&&n.getAttribute('for'))run(n);});});}).observe(document.documentElement,{childList:true,subtree:true});\n})()";
+declare function nativePolyfillHash(): Promise<string>;
+//#endregion
+//#region src/adapters/native.d.ts
+/**
+ * WICG Declarative Partial Updates wire format: no polyfill, zero JS.
+ *
+ * `merges: ["replace"]` only: `Patch` can write `data-merge`, but nothing reads
+ * it without a polyfill, and declaring the others would accept a merge the
+ * spec silently ignores. `withPolyfill` is what makes them real, so it's the
+ * one that declares them.
+ */
+declare const WebPlatformAdapter: Adapter & {
+  capabilities: {
+    readonly streaming: true;
+    readonly merges: readonly ["replace"];
+  };
+};
+/**
+ * What the polyfill can express: `insertAdjacentHTML`'s four positions, plus
+ * `replace`. `morph` is out: diffing two DOM trees is orders of magnitude past
+ * this budget, so the adapter refuses it rather than degrading it to a replace.
+ */
+declare const POLYFILL_MERGES: readonly ["replace", "append", "prepend", "before", "after"];
+/**
+ * Decorate any adapter with the ~550 B inline polyfill for the WICG
+ * Declarative Partial Updates API. The polyfill is injected into `<head>`
+ * only when fragments are present (`ctx.fragments.size > 0`).
+ *
+ * Useful when you want to use `WebPlatformAdapter` in browsers that do
+ * not yet support `<template for>` natively.
+ */
+declare function withPolyfill<T extends Adapter>(adapter: T): Omit<T, "capabilities"> & {
+  capabilities: {
+    streaming: T["capabilities"]["streaming"];
+    merges: typeof POLYFILL_MERGES;
+  };
+};
+/** Default Native adapter: WICG format + inline polyfill (~550 B). */
+declare const NativeAdapter: Omit<Adapter & {
+  capabilities: {
+    readonly streaming: true;
+    readonly merges: readonly ["replace"];
+  };
+}, "capabilities"> & {
+  capabilities: {
+    streaming: true;
+    merges: typeof POLYFILL_MERGES;
+  };
+};
+//#endregion
+//#region src/adapters/htmx.d.ts
+declare const HtmxAdapter: Adapter & {
+  capabilities: {
+    streaming: true;
+    merges: typeof ALL_MERGES;
+  };
+};
+//#endregion
+//#region src/adapters/esi.d.ts
+/**
+ * ESI is CDN-level: the `<esi:include>` tags are resolved by an edge proxy, so
+ * there is no live stream to a browser. `capabilities.streaming: false` says
+ * so: `renderToStream` refuses it, `renderToStatic` (with `emitFragments`)
+ * is the path for ESI output.
+ */
+declare const EsiAdapter: Adapter & {
+  capabilities: {
+    readonly streaming: false;
+    readonly merges: readonly ["replace"];
+  };
+};
+//#endregion
+export { Shell as C, OnError as S, FlowOptions as _, withPolyfill as a, Negotiate as b, TurboAdapter as c, createAdapter as d, AdapterCapabilities as f, FlowEvent as g, FlowErrorInfo as h, WebPlatformAdapter as i, Adapter as l, FlowConfig as m, HtmxAdapter as n, NATIVE_POLYFILL as o, DeferContent as p, NativeAdapter as r, nativePolyfillHash as s, EsiAdapter as t, ShellContext as u, Fragment as v, StreamingAdapter as w, Negotiation as x, MergeType as y };

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+import { C as Shell, S as OnError, _ as FlowOptions, b as Negotiate, f as AdapterCapabilities, g as FlowEvent, h as FlowErrorInfo, l as Adapter, m as FlowConfig, p as DeferContent, v as Fragment, w as StreamingAdapter, x as Negotiation, y as MergeType } from "./index-M7xu3JXg.js";
+import { JSX, VNode } from "@vincle/core";
+//#region src/components/Slot.d.ts
+interface SlotProps {
+  name: string;
+  children?: JSX.Element;
+}
+export declare function Slot(props: SlotProps): JSX.Element;
+//#endregion
+//#region src/components/Defer.d.ts
+interface DeferProps {
+  target?: string;
+  children: DeferContent;
+  merge?: MergeType;
+  timeout?: number;
+  onError?: OnError;
+  fallback?: JSX.Element;
+}
+export declare function Defer(props: DeferProps): JSX.Element | null;
+//#endregion
+//#region src/components/Include.d.ts
+type SchemeOf<S extends string> = S extends `${infer Head}:${string}` ? Head extends `${string}${"/" | "?" | "#"}${string}` ? null : Head extends "" ? null : Head : null;
+type FetchUrl<S extends string> = SchemeOf<S> extends null ? S : Lowercase<SchemeOf<S> & string> extends "http" | "https" ? S : {
+  __error: "Include needs an HTML URL: only http(s): or a relative path";
+};
+interface IncludeProps<S extends string = string> {
+  src: S & FetchUrl<S>;
+  fallback?: VNode;
+}
+export declare function Include<const S extends string>(props: IncludeProps<S>): JSX.Element;
+//#endregion
+//#region src/render.d.ts
+/**
+ * Return a `ReadableStream<FlowEvent>` with proper backpressure and cancellation.
+ */
+export declare function renderToFlowEvents(node: () => JSX.Element, adapter: StreamingAdapter, opts?: FlowOptions & {
+  mode?: "full" | "fragment";
+}): ReadableStream<FlowEvent>;
+/**
+ * Render to a `ReadableStream<string>` of adapter-encoded HTML: the shell
+ * followed by each fragment as wire-format markup.
+ *
+ * The wire is the primitive's own serialization (`encodeWith`); an adapter
+ * only has to declare it can stream (`capabilities.streaming: true`). The
+ * runtime check keeps a plain-JS caller from running a static adapter (e.g.
+ * ESI) through the streaming path.
+ */
+export declare function renderToStream(node: () => JSX.Element, adapter: StreamingAdapter, opts?: FlowOptions & {
+  mode?: "full" | "fragment";
+}): ReadableStream<string>;
+//#endregion
+//#region src/static.d.ts
+/**
+ * Static generation context for pure-static pages: no adapter, no fragment
+ * emission. When `renderToStatic` is called without options, the handler
+ * receives this type and cannot call `emitFragments`.
+ */
+interface PureStaticContext {
+  /** Render a page node, applying adapter.transformShell if present. */
+  renderPage(node: () => JSX.Element): Promise<string>;
+}
+/**
+ * Static generation context extended with fragment emission. When
+ * `renderToStatic` is called with `{ adapter }`, the handler receives
+ * this type and can call `emitFragments` after rendering all pages.
+ */
+interface StaticContext extends PureStaticContext {
+  /**
+   * Materialize every pending fragment as a standalone file. Each is
+   * wrapped with `adapter.Frame` and rendered, so `html` is ready to write as
+   * is; `url` is the path from `generatePath(id)`.
+   */
+  emitFragments(cb: (id: string, url: string, html: string) => void | Promise<void>): Promise<void>;
+}
+interface StaticOptions {
+  /** Wire-format adapter for fragment framing. Required when using emitFragments. */
+  adapter: Adapter;
+  /** Fragment URL convention. Default: (id) => `/fragments/${id}.html`. */
+  generatePath?: (id: string) => string;
+}
+/**
+ * Static generation for pure-static sites (no lazy `<Defer>` content).
+ * Call without options: the handler receives a `PureStaticContext`
+ * without `emitFragments`.
+ */
+export declare function renderToStatic<T>(handler: (ctx: PureStaticContext) => T): Promise<T>;
+/**
+ * Static generation with deferred fragments.
+ * Pass `{ adapter }`: the handler receives a `StaticContext` with
+ * `emitFragments` to materialize fragment files.
+ */
+export declare function renderToStatic<T>(handler: (ctx: StaticContext) => T, options: StaticOptions): Promise<T>;
+//#endregion
+//#region src/fragment.d.ts
+interface RenderFragmentOptions {
+  /** Wire-format adapter: the same one the site's full build uses. */
+  adapter: Adapter;
+  /**
+   * Fragment URL convention. Must match the full build's `generatePath`, or
+   * the file lands somewhere the shell's placeholder doesn't reference.
+   * Default: `(id) => \`/fragments/${id}.html\``.
+   */
+  generatePath?: (id: string) => string;
+  /** Per-render timeout in ms, forwarded to the underlying `<Defer>`. */
+  timeout?: number;
+  onError?: OnError;
+}
+/**
+ * Render a single fragment on demand, outside a full site build: given
+ * fresh content, produces the exact bytes `emitFragments` would have written
+ * for this `id` during a full build, at the same URL. The page that includes
+ * it (via `Include`/`Frame`) never needs rebuilding.
+ *
+ * Framework- and host-agnostic: write `html` to `url` yourself, or hand both
+ * to whatever partial-update mechanism your host offers (Netlify Blobs,
+ * Vercel on-demand revalidation, a CDN purge + upload…).
+ */
+export declare function renderFragment(id: string, content: DeferContent, opts: RenderFragmentOptions): Promise<{
+  url: string;
+  html: string;
+}>;
+//#endregion
+export type { AdapterCapabilities, DeferContent, DeferProps, FlowConfig, FlowErrorInfo, FlowEvent, FlowOptions, Fragment, IncludeProps, MergeType, Negotiate, Negotiation, OnError, PureStaticContext, RenderFragmentOptions, Shell, SlotProps, StaticContext, StaticOptions, StreamingAdapter };

package/dist/index.js

@@ -0,0 +1 @@
+import{a as e,c as t,i as n,o as r,r as i,s as a,t as o}from"./context-DlzTTBsQ.js";import{a as s,d as c,g as l,h as u,i as d,l as f,p,s as m,v as h}from"./utils-DKRixAvn.js";import{n as g,r as _,t as v}from"./render-zCgGmdz0.js";import{Scope as y,raw as b,renderToString as x,snapshotContext as S}from"@vincle/core";import{Fragment as C,jsx as w,jsxs as T}from"@vincle/core/jsx-runtime";import{schemeOf as E}from"@vincle/core/html";function D(e){let{name:t,children:n}=e;return y.get(o).slots.names.add(t),r(t,n)}function O(e){let{registerFragment:t,nextId:i,slots:a}=y.get(o),{children:s,merge:c,timeout:l,onError:u,fallback:d}=e,f=e.target??i();if(t(f,{content:s,treeScope:S(),merge:c??`replace`,timeout:l,onError:u,fallback:d}),a.names.has(f))return null;let p=r(f,d);if(e.target===void 0)return p;let[m,h]=n(a,f);return/* @__PURE__ */ T(C,{children:[b(m),p,b(h)]})}function k(e){let t=E(e);return t===void 0||t===`http`||t===`https`}function A(e){let{nextId:t}=y.get(o);if(!k(e.src)){let t=E(e.src);throw h(`${d} <Include src="${e.src}">: forbidden scheme${t===void 0?``:` ${JSON.stringify(t)}`}: only http(s): or relative paths are allowed. Use an absolute http(s) URL or a path relative to the page, e.g. src="/fragments/hero.html".`,p)}return r(t(),e.fallback,e.src)}const j=e=>`/fragments/${e}.html`;function M(t,n,r){return{renderPage:r=>y.with(async()=>{i();let a=await e(r());return n?.transformShell?n.transformShell(a,t):a},y.snapshot()),emitFragments:async e=>{if(!n)throw h(`${d} emitFragments(): emitFragments requires an adapter: fragments cannot be framed into standalone files without one. Pass { adapter: ... } to renderToStatic. Example: renderToStatic(handler, { adapter: NativeAdapter })`,u);await y.with(async()=>{a(),await _(t,async t=>{if(t.type===`fragment`){let i=await x(n.Frame({id:t.id,children:b(t.html)}));await e(t.id,r(t.id),i)}})},y.snapshot()),t.fragments.clear()}}}async function N(e,n){let r=n?.adapter,i=n?.generatePath??j;if(s(r,`renderToStatic`),n?.generatePath!==void 0&&typeof n.generatePath!=`function`)throw h(`${d} renderToStatic: generatePath must be a function (id) => string, got ${f(n.generatePath)}. Example: (id) => \`/fragments/\${id}.html\`.`,c);return t(t=>e(M(t,r,i)),{adapter:r,mode:`static`,generatePath:i})}async function P(e,t,n){if(n.adapter===void 0)throw h(`${d} renderFragment: opts.adapter is required: pass the same adapter the site's full build uses (e.g. TurboAdapter).`,u);s(n.adapter,`renderFragment`),m(n,`renderFragment`);let r;if(await N(async i=>{await i.renderPage(()=>/* @__PURE__ */ w(O,{target:e,timeout:n.timeout,onError:n.onError,children:t})),await i.emitFragments((t,n,i)=>{t===e&&(r={url:n,html:i})})},{adapter:n.adapter,generatePath:n.generatePath}),!r)throw h(`${d} renderFragment("${e}"): produced no output for this id. The fragment was never registered or rendered: its content may have thrown or timed out (check the onError/console log), or the id differs from the <Defer target> that was rendered. Verify the id matches and that the content renders.`,l);return r}export{O as Defer,A as Include,D as Slot,P as renderFragment,v as renderToFlowEvents,N as renderToStatic,g as renderToStream};

package/dist/render-zCgGmdz0.js

@@ -0,0 +1,5 @@
+import{a as e,c as t}from"./context-DlzTTBsQ.js";import{_ as n,a as r,i,s as a,v as o}from"./utils-DKRixAvn.js";import{raw as s,renderToString as c}from"@vincle/core";import{isAsyncIterable as l}from"@vincle/core/html";function u(e,t){let n=new AbortController,r=t?.signal?AbortSignal.any([t.signal,n.signal]):n.signal,i,a=[],o=()=>{for(let e of a.splice(0))e()};r.addEventListener(`abort`,o,{once:!0});let s=async e=>{if(!r.aborted){for(;(i.desiredSize??1)<=0&&!r.aborted;)await new Promise(e=>a.push(e));r.aborted||i.enqueue(e)}};return new ReadableStream({start(t){i=t,e(s,r).then(()=>{try{t.close()}catch{}},e=>{try{t.error(e)}catch{}})},pull(){o()},cancel(e){n.abort(e)}})}function d(e,t,n){let r=e;if(r==null)return{signal:t??new AbortController().signal,cleanup:()=>{}};let a=new AbortController,o=setTimeout(()=>a.abort(/* @__PURE__ */ Error(`${i} Fragment "${n}" timed out after ${r}ms: its content did not finish in time. Increase the timeout (the fragment's timeout prop or defaultTimeout), or make the content finish faster, e.g. by forwarding the abort signal to fetch().`)),r);return{signal:t?AbortSignal.any([t,a.signal]):a.signal,cleanup:()=>clearTimeout(o)}}const f=e=>typeof e==`function`;function p(e,t){try{let n=f(e.content)?e.content(t):e.content;return l(n)?{kind:`stream`,iterable:n}:{kind:`value`,value:n}}catch(e){return{kind:`sync-error`,error:e}}}async function m(t,n,r,i,a){console.error(`[vincle/flow] Error rendering ${i} "${r}"`,a);let o=n?.(a,{id:r,kind:i});o!=null&&await t({type:`fragment`,id:r,html:await e(o),merge:`replace`})}async function h(e,t,n,r,i){try{await m(e,t,n,r,i)}catch{throw i}}function g(e,t,n,r){return t.treeScope?t.treeScope(()=>_(e,t,n,r)):_(e,t,n,r)}function _(e,t,n,r){let i=t.onError??r.onError,{signal:a,cleanup:o}=d(t.timeout??r.defaultTimeout,r.signal,e),s=p(t,a);switch(s.kind){case`sync-error`:return o(),{isStreaming:!1,done:m(n,i,e,`fragment`,s.error)};case`stream`:return{isStreaming:!0,done:y(e,s.iterable,t.merge,n,i,a).finally(o)};case`value`:return{isStreaming:!1,done:v(e,s.value,t.merge,n,i,a,o)}}}async function v(t,n,r,i,a,o,s){let c;try{c=await e(n)}catch(e){await h(i,a,t,`fragment`,e);return}finally{s()}if(o.aborted){await h(i,a,t,`fragment`,o.reason);return}try{await i({type:`fragment`,id:t,html:c,merge:r})}catch(e){throw console.error(`[vincle/flow] Failed to emit fragment "${t}"`,e),e}}async function y(t,n,r,i,a,o){let s=n[Symbol.asyncIterator](),c=new Promise(e=>{let t=()=>e({done:!0,value:void 0});o.aborted?t():o.addEventListener(`abort`,t,{once:!0})}),l=!1;try{for(;;){let n=Promise.resolve(s.next());n.catch(()=>{});let o=await Promise.race([n,c]);if(o.done)break;let u;try{u=await e(o.value)}catch(e){await h(i,a,t,`stream`,e);continue}try{await i({type:`fragment`,id:t,html:u,merge:r})}catch(e){throw console.error(`[vincle/flow] Failed to emit stream chunk for "${t}"`,e),l=!0,e}}}catch(e){if(l)throw e;await h(i,a,t,`stream`,e)}finally{o.aborted&&await s.return?.(void 0).catch(()=>{})}}async function b(e){if(e.length===0)return;let t=await Promise.allSettled(e);for(let e of t)if(e.status===`rejected`)throw e.reason}function x(e){let t=Promise.resolve();return{emit:n=>{let r=t.then(()=>e(n));return t=r.catch(()=>{}),r},drain:()=>t}}async function S(e,t,n={}){let r=/* @__PURE__ */ new Set,i=[],a=x(t);for(;!n.signal?.aborted;){let t=e.fragments.outstanding(r);if(t.length>0){let e=[];for(let[o,s]of t){r.add(o);let{isStreaming:t,done:c}=g(o,s,a.emit,n);(t?i:e).push(c)}await b(e);continue}if(i.length===0||(await b(i),i.length=0,!e.fragments.hasOutstanding(r)))break}i.length>0&&await b(i),await a.drain()}function C(e){let t=e.trimEnd();if(!t.endsWith(`</html>`))return{body:e,closingTag:``};let n=t.slice(0,-7).trimEnd(),r=n.endsWith(`</body>`)?n.length-7:n.length;return{body:e.slice(0,r),closingTag:e.slice(r)}}function w(e){let t=!1;return new TransformStream({async transform(n,r){if(n.type===`shell`){t=!0,r.enqueue(n.html);return}let i=``;if(t&&(t=!1,i=`
+`),n.type===`fragment`){let t=await c(e.Patch({id:n.id,children:s(n.html),merge:n.merge}));r.enqueue(i+t+`
+`)}else r.enqueue(i+n.html+`
+`)},flush(e){t&&e.enqueue(`
+`)}})}async function T(t,n,r){let{body:i,closingTag:a}=C(await e(t()));return{shellBody:n.transformShell?n.transformShell(i,r):i,closingTag:a}}async function E(e,n,r,i,a){await t(async t=>{let{fragments:o}=t;try{if(n.aborted)return;let{shellBody:s,closingTag:c}=await T(r,i,t);a.mode!==`fragment`&&s!==``&&await e({type:`shell`,html:s}),await S({fragments:o},e,{...a,signal:n}),a.mode!==`fragment`&&c&&await e({type:`close`,html:c})}finally{o.clear()}},{adapter:i,mode:`streaming`})}function D(e,t,n){a(n,e),r(t,e)}function O(e,t,n={}){return D(`renderToFlowEvents`,t,n),u((r,i)=>E(r,i,e,t,n),{signal:n.signal})}function k(e,t,r){if(D(`renderToStream`,t,r),t.capabilities.streaming!==!0)throw o(`[vincle/flow] renderToStream(): this adapter does not stream: capabilities.streaming is false, so it can only produce static output. Use renderToStatic() with this adapter, or pass a streaming adapter (TurboAdapter, NativeAdapter, HtmxAdapter, WebPlatformAdapter).`,n);return O(e,t,r).pipeThrough(w(t))}export{k as n,S as r,O as t};

package/dist/utils-DKRixAvn.js

@@ -0,0 +1 @@
+const e=`ERR_VINCLE_FLOW_CONFIG`,t=`ERR_VINCLE_FLOW_NO_ADAPTER`,n=`ERR_VINCLE_FLOW_MERGE_UNSUPPORTED`,r=`ERR_VINCLE_FLOW_NO_FRAGMENT`,i=`ERR_VINCLE_FLOW_NO_STREAMING`,a=`ERR_VINCLE_FLOW_FORBIDDEN_SCHEME`,o=`ERR_VINCLE_FLOW_DUP_FRAGMENT`;function s(e,t){let n=Error(e);return n.code=t,Error.captureStackTrace?.(n,s),n}const c=[`replace`,`append`,`prepend`,`before`,`after`,`morph`],l=`[vincle/flow]`;function u(e){if(e===null)return`null`;if(typeof e==`string`)return JSON.stringify(e.length>80?e.slice(0,80)+`…`:e);if(typeof e==`number`||typeof e==`bigint`||typeof e==`boolean`)return String(e);if(typeof e==`function`)return`function ${e.name||`<anonymous>`}`;if(e instanceof Error)return`${e.name}: ${e.message}`;try{let t=JSON.stringify(e);return t===void 0?String(e):t.length>100?t.slice(0,100)+`…`:t}catch{return String(e)}}function d(e){return e instanceof AbortSignal||typeof e==`object`&&!!e&&typeof e.aborted==`boolean`&&typeof e.addEventListener==`function`&&typeof e.onabort==`object`}function f(t,n){if(t!=null){if(typeof t!=`object`)throw s(`${l} ${n}: options must be an object, got ${u(t)}. Example: { defaultTimeout: 5000, onError, signal }`,e);if(t.defaultTimeout!==void 0&&(!Number.isFinite(t.defaultTimeout)||t.defaultTimeout<0))throw s(`${l} ${n}: defaultTimeout must be a number of milliseconds >= 0, got ${u(t.defaultTimeout)}. Pass e.g. defaultTimeout: 5000, or omit it for no limit.`,e);if(t.onError!==void 0&&typeof t.onError!=`function`)throw s(`${l} ${n}: onError must be a function (error, { id, kind }) => JSX.Element | void, got ${u(t.onError)}. Omit it to log errors to the console instead.`,e);if(t.signal!==void 0&&!d(t.signal))throw s(`${l} ${n}: signal must be an AbortSignal, got ${u(t.signal)}. Example: const controller = new AbortController(); … { signal: controller.signal }`,e)}}const p=[`Placeholder`,`Patch`,`Frame`];function m(t,n){if(t===void 0)return;if(typeof t!=`object`||!t)throw s(`${l} ${n}: adapter must be an adapter object, got ${u(t)}. Use a built-in (TurboAdapter, NativeAdapter, HtmxAdapter, WebPlatformAdapter, EsiAdapter) or createAdapter().`,e);let r=t,i=p.filter(e=>typeof r[e]!=`function`);if(i.length>0)throw s(`${l} ${n}: the adapter is missing ${i.map(e=>`"${e}"`).join(`, `)}: an adapter needs Placeholder, Patch and Frame. Use createAdapter() or a built-in adapter.`,e);let a=r.capabilities;if(typeof a!=`object`||!a)throw s(`${l} ${n}: the adapter is missing capabilities: declare { streaming: boolean, merges: MergeType[] } (see createAdapter()).`,e);if(typeof a.streaming!=`boolean`)throw s(`${l} ${n}: adapter.capabilities.streaming must be a boolean, got ${u(a.streaming)}.`,e);let o=a.merges;if(!(Array.isArray(o)&&o.every(e=>typeof e==`string`&&c.includes(e))))throw s(`${l} ${n}: adapter.capabilities.merges must be an array of merge types (${c.join(`, `)}), got ${u(o)}.`,e);if(r.transformShell!==void 0&&typeof r.transformShell!=`function`)throw s(`${l} ${n}: adapter.transformShell must be a function (shell, ctx) => string, got ${u(r.transformShell)}.`,e)}function h(t){if(typeof t!=`object`||!t)throw s(`${l} FlowConfig: the flow config must be an object, got ${u(t)}. Example: { adapter: TurboAdapter, mode: "streaming" }`,e);let n=t,r=n.mode;if(r!==`streaming`&&r!==`static`)throw s(`${l} FlowConfig.mode must be "streaming" or "static", got ${u(r)}.`,e);let i=n.idPrefix;if(i!==void 0&&typeof i!=`string`)throw s(`${l} FlowConfig.idPrefix must be a string, got ${u(i)}. Default: "fragment-".`,e);let a=n.generatePath;if(a!==void 0&&typeof a!=`function`)throw s(`${l} FlowConfig.generatePath must be a function (id) => string, got ${u(a)}. Example: (id) => \`/fragments/\${id}.html\`.`,e);if(r===`static`){if(a===void 0)throw s(`${l} FlowConfig: static mode requires generatePath: (id) => string. Example: generatePath: (id) => \`/fragments/\${id}.html\`.`,e)}else if(a!==void 0)throw s(`${l} FlowConfig: generatePath is only used in static mode (renderToStatic): remove it from the streaming config, or drop mode: "streaming" if you meant static generation.`,e);m(n.adapter,`FlowConfig`)}function g(t,n){if(t!==void 0&&(!Number.isFinite(t)||t<0))throw s(`${l} ${n}: timeout must be a number of milliseconds >= 0, got ${u(t)}. Pass e.g. timeout={5000}, or omit it to use defaultTimeout.`,e)}const _=/^[a-zA-Z][a-zA-Z0-9_-]*$/;function v(e,t){if(!_.test(e))throw s(`${l} ${t}: "${e}" is not a valid fragment id: ids must start with a letter and contain only letters, digits, hyphens and underscores (e.g. "price-aapl"). Fragment ids become DOM ids and URL segments.`,`ERR_VINCLE_FLOW_FRAGMENT_ID`)}function y(e,t){let n=e.match(/<\/head\s*>/i);if(n){let r=n.index;return e.slice(0,r)+t+e.slice(r)}let r=`<head>${t}</head>`,i=e.match(/<html\b[^>]*>/i);if(i)return b(e,i.index+i[0].length,r);let a=e.match(/^\s*<!doctype\b[^>]*>/i);return a?b(e,a[0].length,r):r+e}const b=(e,t,n)=>e.slice(0,t)+n+e.slice(t);function x(...e){let t=e.filter(Boolean);return(e,n)=>t.reduce((e,t)=>t(e,n),e)}export{i as _,m as a,g as c,e as d,o as f,r as g,t as h,l as i,u as l,n as m,x as n,h as o,a as p,y as r,f as s,v as t,c as u,s as v};

package/dist/utils.d.ts

@@ -0,0 +1,36 @@
+import { u as ShellContext } from "./index-M7xu3JXg.js";
+//#region src/utils.d.ts
+export declare function assertFragmentId(id: string, label: string): void;
+/**
+ * Injects `content` immediately before `</head>`, opening a `<head>` if the
+ * shell has none.
+ *
+ * Four placements, in decreasing order of what the shell tells us:
+ *
+ *   1. before `</head>`: the shell said where its head is;
+ *   2. just after `<html …>`: wherever it sits, not only at offset 0;
+ *   3. just after a leading doctype: a fragment shell that still declares one;
+ *   4. at the front: a bare fragment, nothing to preserve.
+ *
+ * Case 3 is why a leading doctype is matched on its own rather than folded
+ * into case 2. Nothing may precede a doctype; a browser that sees markup
+ * first ignores the doctype and renders the page in quirks mode.
+ */
+export declare function injectIntoHead(html: string, content: string): string;
+/**
+ * Compose shell transforms left-to-right into a single `transformShell`. Each
+ * transform receives the output of the previous one; falsy entries are skipped,
+ * so an adapter's own (possibly `undefined`) transform can be spliced in:
+ *
+ * Each transform receives the active `ShellContext` as its second argument, so a
+ * fragment-aware transform (e.g. NativeAdapter's polyfill injection) still sees
+ * the pending fragment count; transforms that don't need it simply ignore it.
+ *
+ * @example
+ * createAdapter({
+ *   ...NativeAdapter,
+ *   transformShell: composeShell(NativeAdapter.transformShell, metadata(), assets()),
+ * });
+ */
+export declare function composeShell(...transforms: Array<((shell: string, ctx: ShellContext) => string) | undefined | null | false>): (shell: string, ctx: ShellContext) => string;
+//#endregion

package/dist/utils.js

@@ -0,0 +1 @@
+import{n as e,r as t,t as n}from"./utils-DKRixAvn.js";export{n as assertFragmentId,e as composeShell,t as injectIntoHead};

package/package.json

@@ -0,0 +1,87 @@
+{
+  "name": "@vincle/flow",
+  "version": "0.9.0",
+  "description": "HTML document orchestration layer for @vincle/core",
+  "keywords": [
+    "deferred",
+    "dom-patching",
+    "esi",
+    "fragments",
+    "html",
+    "htmx",
+    "jsx",
+    "ssr",
+    "streaming",
+    "turbo"
+  ],
+  "homepage": "https://vincle.cjean.fr",
+  "bugs": {
+    "url": "https://github.com/cjean-fr/vincle/issues"
+  },
+  "license": "MIT",
+  "author": "Christophe Jean",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cjean-fr/vincle.git",
+    "directory": "packages/flow"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./adapters": {
+      "types": "./dist/adapters/index.d.ts",
+      "default": "./dist/adapters/index.js"
+    },
+    "./components": {
+      "types": "./dist/components/index.d.ts",
+      "default": "./dist/components/index.js"
+    },
+    "./http": {
+      "types": "./dist/http.d.ts",
+      "default": "./dist/http.js"
+    },
+    "./utils": {
+      "types": "./dist/utils.d.ts",
+      "default": "./dist/utils.js"
+    },
+    "./context": {
+      "types": "./dist/context.d.ts",
+      "default": "./dist/context.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "check": "tsc --noEmit",
+    "coverage": "bun test --coverage --coverage-reporter=lcov",
+    "format": "oxfmt",
+    "mutation": "stryker run",
+    "test": "bun test"
+  },
+  "devDependencies": {
+    "@stryker-mutator/core": "^10.0.0",
+    "@types/bun": "^1.4.2",
+    "@vincle/core": "0.9.0",
+    "oxc-parser": "^0.150.0",
+    "tsdown": "^0.23.0",
+    "typescript": "^6.0.3"
+  },
+  "peerDependencies": {
+    "@vincle/core": "^0.9.0"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  }
+}