unhead 3.0.4 → 3.1.0

package/dist/shared/{unhead.BmdY3z1V.d.ts → unhead.gui9LmZS.d.ts}

@@ -1,5 +1,5 @@
 import { HookableCore } from 'hookable';
-import { r as GenericScript, aK as ScriptHttpEvents, D as DataKeys, _ as MaybeEventFnHandlers, x as HttpEventAttributes, aH as SchemaAugmentations, t as HeadTag, at as ResolvableHead, aT as TagPosition, aU as TagPriority, ao as ProcessesTemplateParams, aG as ResolvesDuplicates, aW as TemplateParams } from './unhead.BcynQ3qJ.js';
+import { t as GenericScript, aN as ScriptHttpEvents, D as DataKeys, a1 as MaybeEventFnHandlers, z as HttpEventAttributes, aK as SchemaAugmentations, v as HeadTag, aw as ResolvableHead, aX as TagPosition, aY as TagPriority, ar as ProcessesTemplateParams, aJ as ResolvesDuplicates, a_ as TemplateParams } from './unhead.DeoGMp34.js';
 
 type UseScriptStatus = 'awaitingLoad' | 'loading' | 'loaded' | 'error' | 'removed';
 type UseScriptContext<T extends Record<symbol | string, any>> = ScriptInstance<T>;

package/dist/shared/{unhead.CvqH1vcy.d.ts → unhead.q49lHHFN.d.ts}

@@ -1,4 +1,4 @@
-import { aq as RawInput, at as ResolvableHead, aF as ResolvableValue, ay as ResolvableProperties, G as GenericLink, D as DataKeys, aH as SchemaAugmentations, a3 as MetaGeneric, r as GenericScript, a_ as UnheadHtmlAttributes, aZ as UnheadBodyAttributesWithoutEvents } from './unhead.BcynQ3qJ.js';
+import { at as RawInput, aw as ResolvableHead, aI as ResolvableValue, aB as ResolvableProperties, G as GenericLink, D as DataKeys, aK as SchemaAugmentations, a6 as MetaGeneric, t as GenericScript, b2 as UnheadHtmlAttributes, b1 as UnheadBodyAttributesWithoutEvents } from './unhead.DeoGMp34.js';
 
 type Base = RawInput<'base'>;
 type HtmlAttributes = RawInput<'htmlAttrs'>;

package/dist/stream/client.d.mts

@@ -1,13 +1,32 @@
-import { C as ClientUnhead } from '../shared/unhead.Bbk6Q9rK.mjs';
-import { c as CreateClientHeadOptions, U as Unhead } from '../shared/unhead.m4TuRTvV.mjs';
-import { aM as SerializableHead, at as ResolvableHead } from '../shared/unhead.BcynQ3qJ.mjs';
+import { C as ClientUnhead } from '../shared/unhead.Cv5yrrUd.mjs';
+import { aP as SerializableHead, aw as ResolvableHead } from '../shared/unhead.DeoGMp34.mjs';
+import { U as Unhead, c as CreateClientHeadOptions } from '../shared/unhead.BoZ-Ul8T.mjs';
 import 'hookable';
 
-interface UnheadStreamQueue {
+/**
+ * Shape of the streaming queue written to `window[streamKey]` (default
+ * `window.__unhead__`) by the server-emitted bootstrap script. The client
+ * IIFE reads from it to replay queued entries, and the streaming client
+ * wraps the resulting head instance.
+ *
+ * Both the server bootstrap (`createBootstrapScript`) and the client
+ * (`createStreamableHead`, iife) must agree on this shape.
+ */
+interface StreamingGlobal {
+    /** Queued entry batches pushed before the client IIFE took over. */
     _q: SerializableHead[][];
+    /** Resolved Unhead instance, populated once the IIFE initialises. */
     _head?: Unhead<any>;
+    /** True while framework hydration is in progress (client push suppression). */
+    _hydrationLocked?: () => boolean;
+    /** Push an entry batch onto the queue (pre-init) or the head (post-init). */
     push: (entries: SerializableHead[]) => void;
 }
+/**
+ * @deprecated Use `StreamingGlobal` instead. Kept as an alias for back-compat.
+ */
+type UnheadStreamQueue = StreamingGlobal;
+
 declare const DEFAULT_STREAM_KEY = "__unhead__";
 interface CreateStreamableClientHeadOptions extends Omit<CreateClientHeadOptions, 'render'> {
     streamKey?: string;
@@ -19,4 +38,4 @@ interface CreateStreamableClientHeadOptions extends Omit<CreateClientHeadOptions
 declare function createStreamableHead<T = ResolvableHead>(options?: CreateStreamableClientHeadOptions): ClientUnhead<T> | undefined;
 
 export { DEFAULT_STREAM_KEY, createStreamableHead };
-export type { CreateStreamableClientHeadOptions, UnheadStreamQueue };
+export type { CreateStreamableClientHeadOptions, StreamingGlobal, UnheadStreamQueue };

package/dist/stream/client.d.ts

@@ -1,13 +1,32 @@
-import { C as ClientUnhead } from '../shared/unhead.CHsGwxB0.js';
-import { c as CreateClientHeadOptions, U as Unhead } from '../shared/unhead.BmdY3z1V.js';
-import { aM as SerializableHead, at as ResolvableHead } from '../shared/unhead.BcynQ3qJ.js';
+import { C as ClientUnhead } from '../shared/unhead.-D8hRpkn.js';
+import { aP as SerializableHead, aw as ResolvableHead } from '../shared/unhead.DeoGMp34.js';
+import { U as Unhead, c as CreateClientHeadOptions } from '../shared/unhead.gui9LmZS.js';
 import 'hookable';
 
-interface UnheadStreamQueue {
+/**
+ * Shape of the streaming queue written to `window[streamKey]` (default
+ * `window.__unhead__`) by the server-emitted bootstrap script. The client
+ * IIFE reads from it to replay queued entries, and the streaming client
+ * wraps the resulting head instance.
+ *
+ * Both the server bootstrap (`createBootstrapScript`) and the client
+ * (`createStreamableHead`, iife) must agree on this shape.
+ */
+interface StreamingGlobal {
+    /** Queued entry batches pushed before the client IIFE took over. */
     _q: SerializableHead[][];
+    /** Resolved Unhead instance, populated once the IIFE initialises. */
     _head?: Unhead<any>;
+    /** True while framework hydration is in progress (client push suppression). */
+    _hydrationLocked?: () => boolean;
+    /** Push an entry batch onto the queue (pre-init) or the head (post-init). */
     push: (entries: SerializableHead[]) => void;
 }
+/**
+ * @deprecated Use `StreamingGlobal` instead. Kept as an alias for back-compat.
+ */
+type UnheadStreamQueue = StreamingGlobal;
+
 declare const DEFAULT_STREAM_KEY = "__unhead__";
 interface CreateStreamableClientHeadOptions extends Omit<CreateClientHeadOptions, 'render'> {
     streamKey?: string;
@@ -19,4 +38,4 @@ interface CreateStreamableClientHeadOptions extends Omit<CreateClientHeadOptions
 declare function createStreamableHead<T = ResolvableHead>(options?: CreateStreamableClientHeadOptions): ClientUnhead<T> | undefined;
 
 export { DEFAULT_STREAM_KEY, createStreamableHead };
-export type { CreateStreamableClientHeadOptions, UnheadStreamQueue };
+export type { CreateStreamableClientHeadOptions, StreamingGlobal, UnheadStreamQueue };

package/dist/stream/server.d.mts

@@ -1,6 +1,6 @@
-import { S as ServerUnhead } from '../shared/unhead.BfINO8Du.mjs';
-import { f as CreateStreamableServerHeadOptions, U as Unhead, s as SSRHeadPayload } from '../shared/unhead.m4TuRTvV.mjs';
-import { at as ResolvableHead } from '../shared/unhead.BcynQ3qJ.mjs';
+import { S as ServerUnhead } from '../shared/unhead.B2jfOxG1.mjs';
+import { f as CreateStreamableServerHeadOptions, U as Unhead, s as SSRHeadPayload } from '../shared/unhead.BoZ-Ul8T.mjs';
+import { aw as ResolvableHead } from '../shared/unhead.DeoGMp34.mjs';
 import 'hookable';
 
 /**
@@ -67,9 +67,10 @@ declare function createStreamableHead<T = ResolvableHead>(options?: CreateStream
  * use this directly to inject the bootstrap into your shell `<head>`.
  *
  * @param streamKey - The window property name for the stream queue (default: '__unhead__')
+ * @param nonce - Optional CSP nonce to stamp on the script tag
  * @returns An inline `<script>` tag string
  */
-declare function createBootstrapScript(streamKey?: string): string;
+declare function createBootstrapScript(streamKey?: string, nonce?: string): string;
 /**
  * Renders the current head state and clears entries atomically.
  *
@@ -166,8 +167,10 @@ interface StreamingTemplateParts {
 /**
  * @experimental
  *
- * Prepares a template for streaming SSR by splitting it at body tag boundaries
- * and injecting head content into both parts.
+ * Prepares a template for streaming SSR by splitting it at the SSR outlet
+ * marker (`<!--app-html-->` / `<!--ssr-outlet-->`) when present, so the
+ * streamed app content lands inside the mount container. Falls back to
+ * splitting at body tag boundaries when no marker is found.
  *
  * This is the recommended way to handle streaming templates as it:
  * - Uses consistent template parsing (same as transformHtmlTemplateRaw)

package/dist/stream/server.d.ts

@@ -1,6 +1,6 @@
-import { S as ServerUnhead } from '../shared/unhead.9aHQrEvB.js';
-import { f as CreateStreamableServerHeadOptions, U as Unhead, s as SSRHeadPayload } from '../shared/unhead.BmdY3z1V.js';
-import { at as ResolvableHead } from '../shared/unhead.BcynQ3qJ.js';
+import { S as ServerUnhead } from '../shared/unhead.DdarjSpi.js';
+import { f as CreateStreamableServerHeadOptions, U as Unhead, s as SSRHeadPayload } from '../shared/unhead.gui9LmZS.js';
+import { aw as ResolvableHead } from '../shared/unhead.DeoGMp34.js';
 import 'hookable';
 
 /**
@@ -67,9 +67,10 @@ declare function createStreamableHead<T = ResolvableHead>(options?: CreateStream
  * use this directly to inject the bootstrap into your shell `<head>`.
  *
  * @param streamKey - The window property name for the stream queue (default: '__unhead__')
+ * @param nonce - Optional CSP nonce to stamp on the script tag
  * @returns An inline `<script>` tag string
  */
-declare function createBootstrapScript(streamKey?: string): string;
+declare function createBootstrapScript(streamKey?: string, nonce?: string): string;
 /**
  * Renders the current head state and clears entries atomically.
  *
@@ -166,8 +167,10 @@ interface StreamingTemplateParts {
 /**
  * @experimental
  *
- * Prepares a template for streaming SSR by splitting it at body tag boundaries
- * and injecting head content into both parts.
+ * Prepares a template for streaming SSR by splitting it at the SSR outlet
+ * marker (`<!--app-html-->` / `<!--ssr-outlet-->`) when present, so the
+ * streamed app content lands inside the mount container. Falls back to
+ * splitting at body tag boundaries when no marker is found.
  *
  * This is the recommended way to handle streaming templates as it:
  * - Uses consistent template parsing (same as transformHtmlTemplateRaw)

package/dist/stream/server.mjs

@@ -42,9 +42,10 @@ function getStreamKey(head) {
   assertValidStreamKey(key);
   return key;
 }
-function createBootstrapScript(streamKey = DEFAULT_STREAM_KEY) {
+function createBootstrapScript(streamKey = DEFAULT_STREAM_KEY, nonce) {
   assertValidStreamKey(streamKey);
-  return `<script>window.${streamKey}={_q:[],push(e){this._q.push(e)}}<\/script>`;
+  const nonceAttr = nonce ? ` nonce="${nonce.replace(/"/g, "&quot;")}"` : "";
+  return `<script${nonceAttr}>window.${streamKey}={_q:[],push(e){this._q.push(e)}}<\/script>`;
 }
 function renderShell(head) {
   const result = head.render();
@@ -110,8 +111,18 @@ function prepareStreamingTemplate(head, template, preRenderedState) {
   const bodyEnd = parsed.indexes.bodyTagEnd;
   const bodyCloseStart = parsed.indexes.bodyCloseTagStart;
   if (bodyEnd >= 0 && bodyCloseStart >= 0) {
-    const shellPart = template.substring(0, bodyEnd);
     const bodyInterior = template.substring(bodyEnd, bodyCloseStart);
+    const markerMatch = bodyInterior.match(/<!--\s*(?:app-html|ssr-outlet)\s*-->/);
+    let beforeStream;
+    let afterStream;
+    if (markerMatch) {
+      beforeStream = bodyInterior.substring(0, markerMatch.index);
+      afterStream = bodyInterior.substring(markerMatch.index + markerMatch[0].length);
+    } else {
+      beforeStream = "";
+      afterStream = bodyInterior;
+    }
+    const shellPart = template.substring(0, bodyEnd) + beforeStream;
     const endPart = template.substring(bodyCloseStart);
     const shellParsed = parseHtmlForIndexes(`${shellPart}</body></html>`);
     const shell = applyHeadToHtml(shellParsed, {
@@ -122,7 +133,7 @@ function prepareStreamingTemplate(head, template, preRenderedState) {
     }).replace("</body></html>", "");
     return {
       shell,
-      end: bodyInterior + ssr.bodyTags + endPart
+      end: afterStream + ssr.bodyTags + endPart
     };
   }
   return {

package/dist/stream/unplugin.d.mts

@@ -0,0 +1,81 @@
+import * as unplugin from 'unplugin';
+import { UnpluginOptions } from 'unplugin';
+
+declare const VIRTUAL_CLIENT_ID = "virtual:@unhead/streaming-client";
+declare const VIRTUAL_IIFE_ID = "virtual:@unhead/streaming-iife.js";
+type Nonce = string | (() => string | undefined);
+interface StreamingPluginOptions {
+    /** Framework package e.g. '@unhead/vue' */
+    framework: string;
+    /** Plugin name (optional, defaults to `${framework}:streaming`) */
+    name?: string;
+    /**
+     * File extension filter for transform hook, e.g. /\.vue$/. Optional;
+     * only required by frameworks whose client streaming support relies on
+     * source-level AST injection (React/Solid/Svelte). Vue does not use it.
+     */
+    filter?: RegExp;
+    /** Transform handler called for files matching `filter`. */
+    transform?: (code: string, id: string, options?: {
+        ssr?: boolean;
+    }) => {
+        code: string;
+        map?: any;
+    } | null | undefined | void;
+    /**
+     * How to load the streaming client (vite-only, ignored on webpack/rspack/rollup where
+     * index.html injection isn't available; frameworks inject the iife themselves in SSR).
+     * - 'async' (default): Non-blocking external script. In dev served from a virtual
+     *   module; in production emitted as a real asset chunk via `emitFile`.
+     * - 'inline': Inline the IIFE directly in HTML. Largest HTML, smallest TTFB,
+     *   always safe in production. Recommended for streaming SSR.
+     * - 'module': ES module dynamic import of the client bootstrap. Vite rewrites the
+     *   import path through its module graph so it survives production builds.
+     * @default 'async'
+     */
+    mode?: 'async' | 'inline' | 'module';
+    /**
+     * CSP nonce forwarded on every injected `<script>` tag. Pass a string or a
+     * function returning a string (useful when the nonce rotates per request).
+     * Omit to inject without a nonce.
+     */
+    nonce?: Nonce;
+    /**
+     * Stream key global name; must match `experimentalStreamKey` on the server
+     * head instance. Used by dev-mode warnings to detect when the server
+     * bootstrap script hasn't run (common misconfig).
+     * @default '__unhead__'
+     */
+    streamKey?: string;
+    /**
+     * Emit a warning when the client IIFE runs but no server bootstrap queue
+     * has been installed (i.e. server didn't call `wrapStream` /
+     * `renderSSRHeadShell`). Dev-only.
+     * @default true in dev, false in prod
+     */
+    warnOnMissingServerBootstrap?: boolean;
+}
+/**
+ * Builds the bundler-agnostic unplugin hook set for the streaming plugin. Exposed so
+ * framework wrappers (e.g. `@unhead/vue/bundler`) can bake in their own
+ * `framework`, `filter`, and `transform` while still using this factory
+ * to produce hooks that work across vite/webpack/rspack/rollup/esbuild via `createUnplugin`.
+ *
+ * SSR detection is bundler-specific:
+ * - vite build: `config.env.isSsrBuild`
+ * - vite dev (v6+ environments): `this.environment.name === 'ssr'` per-transform
+ * - webpack/rspack: `compiler.options.name === 'server'` or `target === 'node'`
+ */
+declare function buildStreamingPluginOptions(options: StreamingPluginOptions): UnpluginOptions;
+/**
+ * Internal cross-bundler unplugin factory. Framework wrappers pick a single bundler's
+ * output (`.vite`, `.webpack`, `.rspack`, etc.) to expose via their own subpath export.
+ *
+ * Consumers should prefer the unified framework bundler entry (e.g.
+ * `@unhead/{vue,react,svelte,solid-js}/bundler`) rather than importing this
+ * directly.
+ */
+declare const createStreamingPlugin: unplugin.UnpluginInstance<StreamingPluginOptions, boolean>;
+
+export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, buildStreamingPluginOptions, createStreamingPlugin };
+export type { Nonce, StreamingPluginOptions };

package/dist/stream/unplugin.d.ts

@@ -0,0 +1,81 @@
+import * as unplugin from 'unplugin';
+import { UnpluginOptions } from 'unplugin';
+
+declare const VIRTUAL_CLIENT_ID = "virtual:@unhead/streaming-client";
+declare const VIRTUAL_IIFE_ID = "virtual:@unhead/streaming-iife.js";
+type Nonce = string | (() => string | undefined);
+interface StreamingPluginOptions {
+    /** Framework package e.g. '@unhead/vue' */
+    framework: string;
+    /** Plugin name (optional, defaults to `${framework}:streaming`) */
+    name?: string;
+    /**
+     * File extension filter for transform hook, e.g. /\.vue$/. Optional;
+     * only required by frameworks whose client streaming support relies on
+     * source-level AST injection (React/Solid/Svelte). Vue does not use it.
+     */
+    filter?: RegExp;
+    /** Transform handler called for files matching `filter`. */
+    transform?: (code: string, id: string, options?: {
+        ssr?: boolean;
+    }) => {
+        code: string;
+        map?: any;
+    } | null | undefined | void;
+    /**
+     * How to load the streaming client (vite-only, ignored on webpack/rspack/rollup where
+     * index.html injection isn't available; frameworks inject the iife themselves in SSR).
+     * - 'async' (default): Non-blocking external script. In dev served from a virtual
+     *   module; in production emitted as a real asset chunk via `emitFile`.
+     * - 'inline': Inline the IIFE directly in HTML. Largest HTML, smallest TTFB,
+     *   always safe in production. Recommended for streaming SSR.
+     * - 'module': ES module dynamic import of the client bootstrap. Vite rewrites the
+     *   import path through its module graph so it survives production builds.
+     * @default 'async'
+     */
+    mode?: 'async' | 'inline' | 'module';
+    /**
+     * CSP nonce forwarded on every injected `<script>` tag. Pass a string or a
+     * function returning a string (useful when the nonce rotates per request).
+     * Omit to inject without a nonce.
+     */
+    nonce?: Nonce;
+    /**
+     * Stream key global name; must match `experimentalStreamKey` on the server
+     * head instance. Used by dev-mode warnings to detect when the server
+     * bootstrap script hasn't run (common misconfig).
+     * @default '__unhead__'
+     */
+    streamKey?: string;
+    /**
+     * Emit a warning when the client IIFE runs but no server bootstrap queue
+     * has been installed (i.e. server didn't call `wrapStream` /
+     * `renderSSRHeadShell`). Dev-only.
+     * @default true in dev, false in prod
+     */
+    warnOnMissingServerBootstrap?: boolean;
+}
+/**
+ * Builds the bundler-agnostic unplugin hook set for the streaming plugin. Exposed so
+ * framework wrappers (e.g. `@unhead/vue/bundler`) can bake in their own
+ * `framework`, `filter`, and `transform` while still using this factory
+ * to produce hooks that work across vite/webpack/rspack/rollup/esbuild via `createUnplugin`.
+ *
+ * SSR detection is bundler-specific:
+ * - vite build: `config.env.isSsrBuild`
+ * - vite dev (v6+ environments): `this.environment.name === 'ssr'` per-transform
+ * - webpack/rspack: `compiler.options.name === 'server'` or `target === 'node'`
+ */
+declare function buildStreamingPluginOptions(options: StreamingPluginOptions): UnpluginOptions;
+/**
+ * Internal cross-bundler unplugin factory. Framework wrappers pick a single bundler's
+ * output (`.vite`, `.webpack`, `.rspack`, etc.) to expose via their own subpath export.
+ *
+ * Consumers should prefer the unified framework bundler entry (e.g.
+ * `@unhead/{vue,react,svelte,solid-js}/bundler`) rather than importing this
+ * directly.
+ */
+declare const createStreamingPlugin: unplugin.UnpluginInstance<StreamingPluginOptions, boolean>;
+
+export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, buildStreamingPluginOptions, createStreamingPlugin };
+export type { Nonce, StreamingPluginOptions };

package/dist/stream/unplugin.mjs

@@ -0,0 +1,166 @@
+import { createUnplugin } from 'unplugin';
+
+const VIRTUAL_CLIENT_ID = "virtual:@unhead/streaming-client";
+const VIRTUAL_IIFE_ID = "virtual:@unhead/streaming-iife.js";
+const RESOLVED_ID = `\0${VIRTUAL_CLIENT_ID}`;
+const RESOLVED_IIFE_ID = `\0${VIRTUAL_IIFE_ID}`;
+const VIRTUAL_RE = /virtual:@unhead\/streaming/;
+const RESOLVED_RE = /^\0virtual:@unhead\/streaming/;
+let iifeCode;
+let iifeCodeLoading;
+async function loadIifeCode() {
+  if (iifeCode)
+    return;
+  iifeCodeLoading ||= import('unhead/stream/iife').then((mod) => {
+    iifeCode = mod.streamingIifeCode;
+  });
+  await iifeCodeLoading;
+}
+function resolveNonce(nonce) {
+  if (!nonce)
+    return void 0;
+  return typeof nonce === "function" ? nonce() : nonce;
+}
+function buildClientStub(framework, streamKey, warnOnMissing) {
+  const key = JSON.stringify(streamKey);
+  const warnBranch = warnOnMissing ? `else{console.warn('[unhead] streaming client loaded but window['+${key}+'] is undefined; did the server call wrapStream()/renderSSRHeadShell()?')}` : "";
+  return `import{createHead}from'${framework}/client'
+const s=window[${key}];if(s){const q=s._q;s._q=[];const h=createHead({document});q.forEach(e=>h.push(e));s.push=e=>h.push(e);s._head=h}${warnBranch}`;
+}
+function buildStreamingPluginOptions(options) {
+  const {
+    framework,
+    name,
+    mode = "async",
+    nonce,
+    streamKey = "__unhead__",
+    warnOnMissingServerBootstrap
+  } = options;
+  const state = {
+    isBuild: false,
+    ssr: false
+  };
+  function isSSRCall(hookThis, opts) {
+    const envName = hookThis?.environment?.name;
+    return envName === "ssr" || envName === "server" || opts?.ssr === true || state.ssr;
+  }
+  function warnEnabled() {
+    return warnOnMissingServerBootstrap ?? !state.isBuild;
+  }
+  return {
+    name: name ?? `${framework}:streaming`,
+    enforce: "pre",
+    async buildStart() {
+      await loadIifeCode();
+      if (mode === "async" && state.isBuild && typeof this.emitFile === "function") {
+        if (!iifeCode)
+          throw new Error("[unhead] Streaming IIFE not built. Run `pnpm build` in packages/unhead first.");
+        state.emittedIifeFileName = this.emitFile({
+          type: "asset",
+          name: "unhead-streaming.js",
+          source: iifeCode
+        });
+      }
+    },
+    resolveId: {
+      filter: { id: VIRTUAL_RE },
+      handler(id) {
+        if (id === VIRTUAL_CLIENT_ID || id === `/${VIRTUAL_CLIENT_ID}`)
+          return RESOLVED_ID;
+        if (id === VIRTUAL_IIFE_ID || id === `/${VIRTUAL_IIFE_ID}`)
+          return RESOLVED_IIFE_ID;
+      }
+    },
+    load: {
+      filter: { id: RESOLVED_RE },
+      handler(id, opts) {
+        const isSSR = isSSRCall(this, opts);
+        if (id === RESOLVED_ID) {
+          if (isSSR)
+            return { code: "export {}", moduleType: "js" };
+          return {
+            code: buildClientStub(framework, streamKey, warnEnabled()),
+            moduleType: "js"
+          };
+        }
+        if (id === RESOLVED_IIFE_ID) {
+          if (isSSR)
+            return { code: "", moduleType: "js" };
+          if (!iifeCode)
+            throw new Error("[unhead] Streaming IIFE not built. Run `pnpm build` in packages/unhead first.");
+          return { code: iifeCode, moduleType: "js" };
+        }
+      }
+    },
+    ...options.transform && options.filter ? {
+      transform: {
+        filter: { id: options.filter },
+        handler(code, id, opts) {
+          return options.transform(code, id, { ssr: isSSRCall(this, opts) });
+        }
+      }
+    } : {},
+    webpack(compiler) {
+      const { name: n, target } = compiler.options;
+      if (n === "server" || target === "node" || target === "async-node")
+        state.ssr = true;
+    },
+    rspack(compiler) {
+      const { name: n, target } = compiler.options;
+      if (n === "server" || target === "node" || target === "async-node")
+        state.ssr = true;
+    },
+    vite: {
+      apply(_config, env) {
+        if (env.isSsrBuild)
+          state.ssr = true;
+        if (env.command === "build")
+          state.isBuild = true;
+        return true;
+      },
+      configResolved(config) {
+        if (config.command === "build")
+          state.isBuild = true;
+      },
+      transformIndexHtml: {
+        // `order: 'pre'` is separate from the plugin-level `enforce: 'pre'`:
+        // it runs this HTML transform before other non-pre HTML transforms
+        // so the virtual module `<script>` tags we inject go through the
+        // full Vite plugin pipeline (resolveId/load) and aren't stripped or
+        // rewritten by downstream HTML transforms.
+        order: "pre",
+        handler() {
+          const nonceValue = resolveNonce(nonce);
+          const nonceAttr = nonceValue ? { nonce: nonceValue } : {};
+          if (mode === "inline") {
+            if (!iifeCode)
+              throw new Error("[unhead] Streaming IIFE not built. Run `pnpm build` in packages/unhead first.");
+            return [{
+              tag: "script",
+              attrs: nonceAttr,
+              children: iifeCode,
+              injectTo: "head-prepend"
+            }];
+          }
+          if (mode === "async") {
+            const src = state.isBuild && state.emittedIifeFileName ? `/${state.emittedIifeFileName}` : `/${VIRTUAL_IIFE_ID}`;
+            return [{
+              tag: "script",
+              attrs: { ...nonceAttr, async: true, src },
+              injectTo: "head-prepend"
+            }];
+          }
+          return [{
+            tag: "script",
+            attrs: nonceAttr,
+            children: `import("/${VIRTUAL_CLIENT_ID}")`,
+            injectTo: "head-prepend"
+          }];
+        }
+      }
+    }
+  };
+}
+const createStreamingPlugin = createUnplugin(buildStreamingPluginOptions);
+
+export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, buildStreamingPluginOptions, createStreamingPlugin };

package/dist/stream/vite.d.mts

@@ -1,31 +1,23 @@
 import { Plugin } from 'vite';
+import { StreamingPluginOptions } from './unplugin.mjs';
+export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, buildStreamingPluginOptions } from './unplugin.mjs';
+import 'unplugin';
 
-declare const VIRTUAL_CLIENT_ID = "virtual:@unhead/streaming-client";
-declare const VIRTUAL_IIFE_ID = "virtual:@unhead/streaming-iife.js";
-interface StreamingPluginOptions {
-    /** Framework package e.g. '@unhead/vue' */
-    framework: string;
-    /** Plugin name (optional, defaults to `${framework}:streaming`) */
-    name?: string;
-    /** File extension filter for transform hook, e.g. /\.vue$/ */
-    filter: RegExp;
-    /** Transform handler called for files matching `filter` */
-    transform: (code: string, id: string, options?: {
-        ssr?: boolean;
-    }) => {
-        code: string;
-        map?: any;
-    } | null | undefined | void;
-    /**
-     * How to load the streaming client:
-     * - 'async': Load as async script (non-blocking, may have brief queue delay)
-     * - 'inline': Inline the IIFE directly in HTML (larger HTML, but immediate execution)
-     * - 'module': Use ES module import (original behavior, waits for bundle)
-     * @default 'async'
-     */
-    mode?: 'async' | 'inline' | 'module';
-}
+/**
+ * @deprecated Import from `unhead/stream/unplugin` instead and call `.vite(options)`
+ * on the returned unplugin instance. The `unhead/stream/vite` subpath will be
+ * removed in a future major release.
+ *
+ * ```ts
+ * // Before
+ * import { createStreamingPlugin } from 'unhead/stream/vite'
+ * const plugin = createStreamingPlugin({ framework, filter, transform })
+ *
+ * // After
+ * import { createStreamingPlugin } from 'unhead/stream/unplugin'
+ * const plugin = createStreamingPlugin.vite({ framework, filter, transform })
+ * ```
+ */
 declare function createStreamingPlugin(options: StreamingPluginOptions): Plugin;
 
-export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, createStreamingPlugin };
-export type { StreamingPluginOptions };
+export { StreamingPluginOptions, createStreamingPlugin };

package/dist/stream/vite.d.ts

@@ -1,31 +1,23 @@
 import { Plugin } from 'vite';
+import { StreamingPluginOptions } from './unplugin.js';
+export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, buildStreamingPluginOptions } from './unplugin.js';
+import 'unplugin';
 
-declare const VIRTUAL_CLIENT_ID = "virtual:@unhead/streaming-client";
-declare const VIRTUAL_IIFE_ID = "virtual:@unhead/streaming-iife.js";
-interface StreamingPluginOptions {
-    /** Framework package e.g. '@unhead/vue' */
-    framework: string;
-    /** Plugin name (optional, defaults to `${framework}:streaming`) */
-    name?: string;
-    /** File extension filter for transform hook, e.g. /\.vue$/ */
-    filter: RegExp;
-    /** Transform handler called for files matching `filter` */
-    transform: (code: string, id: string, options?: {
-        ssr?: boolean;
-    }) => {
-        code: string;
-        map?: any;
-    } | null | undefined | void;
-    /**
-     * How to load the streaming client:
-     * - 'async': Load as async script (non-blocking, may have brief queue delay)
-     * - 'inline': Inline the IIFE directly in HTML (larger HTML, but immediate execution)
-     * - 'module': Use ES module import (original behavior, waits for bundle)
-     * @default 'async'
-     */
-    mode?: 'async' | 'inline' | 'module';
-}
+/**
+ * @deprecated Import from `unhead/stream/unplugin` instead and call `.vite(options)`
+ * on the returned unplugin instance. The `unhead/stream/vite` subpath will be
+ * removed in a future major release.
+ *
+ * ```ts
+ * // Before
+ * import { createStreamingPlugin } from 'unhead/stream/vite'
+ * const plugin = createStreamingPlugin({ framework, filter, transform })
+ *
+ * // After
+ * import { createStreamingPlugin } from 'unhead/stream/unplugin'
+ * const plugin = createStreamingPlugin.vite({ framework, filter, transform })
+ * ```
+ */
 declare function createStreamingPlugin(options: StreamingPluginOptions): Plugin;
 
-export { VIRTUAL_CLIENT_ID, VIRTUAL_IIFE_ID, createStreamingPlugin };
-export type { StreamingPluginOptions };
+export { StreamingPluginOptions, createStreamingPlugin };