@megabudino/stack-utils 1.4.1 → 2.0.0

package/README.md

@@ -43,25 +43,37 @@ export const handle = createProxyHandle({
 });
 ```
 
+If you want client-side proxy islands with auto-generated browser wiring, also install the Vite plugin once:
+
+```ts
+import { sveltekit } from '@sveltejs/kit/vite';
+import { defineConfig } from 'vite';
+import { proxyIslands } from '@megabudino/stack-utils/proxy/vite';
+
+export default defineConfig({
+	plugins: [proxyIslands(), sveltekit()]
+});
+```
+
 Proxy config:
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `originUrl` | `string` | required | Origin server URL |
 | `siteUrl` | `string` | required | Public site URL |
-| `sitemaps` | `string[]` | `[]` | SvelteKit sitemap URLs to inject into sitemap indexes |
-| `sitemapCacheSeconds` | `number` | `3600` | Cache max-age for sitemap responses |
+| `sitemap` | `SitemapConfig` | `{}` | Sitemap index injection and origin URL filtering |
 | `proxyAssets` | `boolean` | `false` | Rewrite origin asset URLs to relative paths |
 | `additionalOrigins` | `string[]` | `[]` | Additional absolute origins to rewrite like `originUrl` |
-| `domActions` | `DomAction[]` | `[]` | Declarative DOM transformations for proxied HTML |
-| `textReplacements` | `Record<string, string>` | `{}` | Final string replacements applied after DOM actions |
+| `transformDom` | `TransformDomHook` | — | `($, ctx)` cheerio hook against the proxied document |
+| `islands` | `ProxyIslandsConfig` | — | Svelte component registry used by `transformDom`'s `ctx.renderIsland(...)` |
+| `textReplacements` | `Record<string, string>` | `{}` | Final string replacements applied after `transformDom` |
 
 What it does:
 
 - lets SvelteKit routes resolve normally when a route exists
 - proxies unmatched requests to the configured origin
 - rewrites redirects back to the public domain
-- rewrites HTML, applies optional DOM actions, and injects extra sitemap entries when configured
+- rewrites HTML, runs the optional `transformDom` hook against cheerio, and rewrites sitemap XML when configured
 
 ### `images`
 

package/dist/proxy/client.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Browser-side island bootstrap.
+ *
+ * Lives in a separate subpath (`@megabudino/stack-utils/proxy/client`) so the
+ * server proxy can keep depending on `svelte/server` while this entry point
+ * resolves to the browser build of `svelte` (for `mount` / `hydrate`).
+ */
+import type { IslandComponent, IslandMode } from './types.js';
+export interface MountIslandsConfig {
+    /** Registry of components keyed by the same names used on the server. */
+    components: Record<string, IslandComponent>;
+    /**
+     * Override the default mode used when an island has no
+     * `data-stack-island-mode` attribute. Defaults to `'mount'`.
+     */
+    defaultMode?: Exclude<IslandMode, 'serverOnly'>;
+    /**
+     * Root element to search. Defaults to `document`. Pass a specific node
+     * when re-mounting a subtree after client-side navigation.
+     */
+    root?: ParentNode;
+    /**
+     * Optional logger for missing-component or malformed-props warnings.
+     * Defaults to `console.warn`. Pass `null` to silence.
+     */
+    onWarn?: ((message: string) => void) | null;
+}
+/**
+ * Walk the DOM and activate every island the server tagged with
+ * `data-stack-island`. Safe to call more than once: already-activated islands
+ * carry a marker and are skipped on subsequent calls.
+ */
+export declare function mountIslands(config: MountIslandsConfig): void;

package/dist/proxy/client.js

@@ -0,0 +1,101 @@
+/**
+ * Browser-side island bootstrap.
+ *
+ * Lives in a separate subpath (`@megabudino/stack-utils/proxy/client`) so the
+ * server proxy can keep depending on `svelte/server` while this entry point
+ * resolves to the browser build of `svelte` (for `mount` / `hydrate`).
+ */
+import { hydrate, mount } from 'svelte';
+const DATA_ISLAND_ATTR = 'data-stack-island';
+const DATA_ISLAND_MODE_ATTR = 'data-stack-island-mode';
+const DATA_ISLAND_ID_ATTR = 'data-stack-island-id';
+const DATA_PROPS_FOR_ATTR = 'data-stack-island-for';
+/**
+ * Walk the DOM and activate every island the server tagged with
+ * `data-stack-island`. Safe to call more than once: already-activated islands
+ * carry a marker and are skipped on subsequent calls.
+ */
+export function mountIslands(config) {
+    const root = config.root ?? document;
+    const warn = config.onWarn === undefined ? defaultWarn : config.onWarn;
+    const defaultMode = config.defaultMode ?? 'mount';
+    const elements = root.querySelectorAll(`[${DATA_ISLAND_ATTR}]`);
+    for (const el of elements) {
+        activateIsland(el, config.components, defaultMode, warn);
+    }
+}
+const ACTIVATED = Symbol.for('stack-utils.island.activated');
+function activateIsland(el, components, defaultMode, warn) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    if (el[ACTIVATED]) {
+        return;
+    }
+    const name = el.getAttribute(DATA_ISLAND_ATTR);
+    if (!name) {
+        return;
+    }
+    const rawMode = el.getAttribute(DATA_ISLAND_MODE_ATTR);
+    const mode = rawMode ?? defaultMode;
+    if (mode === 'serverOnly') {
+        return;
+    }
+    const Component = components[name];
+    if (!Component) {
+        warn?.(`[stack-utils] island component "${name}" is not registered on the client.`);
+        return;
+    }
+    const props = readProps(el, name, warn);
+    try {
+        if (mode === 'hydrate') {
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            hydrate(Component, { target: el, props, recover: true });
+        }
+        else {
+            el.replaceChildren();
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            mount(Component, { target: el, props });
+        }
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        el[ACTIVATED] = true;
+    }
+    catch (error) {
+        warn?.(`[stack-utils] island "${name}" failed to ${mode}: ${stringifyError(error)}`);
+    }
+}
+function readProps(el, name, warn) {
+    const islandId = el.getAttribute(DATA_ISLAND_ID_ATTR);
+    if (!islandId) {
+        return {};
+    }
+    const script = document.querySelector(`script[type="application/json"][${DATA_PROPS_FOR_ATTR}="${cssEscape(islandId)}"]`);
+    if (!script) {
+        return {};
+    }
+    try {
+        return JSON.parse(script.textContent ?? '{}');
+    }
+    catch (error) {
+        warn?.(`[stack-utils] failed to parse props for island "${name}": ${stringifyError(error)}`);
+        return {};
+    }
+}
+function defaultWarn(message) {
+    if (typeof console !== 'undefined' && typeof console.warn === 'function') {
+        console.warn(message);
+    }
+}
+function stringifyError(error) {
+    if (error instanceof Error) {
+        return error.message;
+    }
+    return String(error);
+}
+/** Minimal CSS.escape fallback (covers the id strings we emit). */
+function cssEscape(value) {
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const native = globalThis.CSS?.escape;
+    if (typeof native === 'function') {
+        return native(value);
+    }
+    return value.replace(/[^a-zA-Z0-9\-_]/g, (ch) => `\\${ch}`);
+}

package/dist/proxy/define-islands.d.ts

@@ -0,0 +1,16 @@
+import type { ProxyIslandsConfig } from './types.js';
+declare const AUTO_WIRED_PROXY_ISLANDS: unique symbol;
+type AutoWiredProxyIslandsConfig = ProxyIslandsConfig & {
+    readonly [AUTO_WIRED_PROXY_ISLANDS]?: true;
+};
+/**
+ * Declare a proxy islands registry in a form the `proxyIslands()` Vite plugin
+ * can recognize and auto-wire for the browser.
+ *
+ * Runtime behavior stays minimal: the helper returns the original config
+ * object with a non-enumerable internal marker so the proxy can produce a
+ * helpful error when client islands are used without the build plugin.
+ */
+export declare function defineProxyIslands<T extends ProxyIslandsConfig>(config: T): T;
+export declare function isAutoWiredProxyIslandsConfig(config: ProxyIslandsConfig | undefined): config is AutoWiredProxyIslandsConfig;
+export {};

package/dist/proxy/define-islands.js

@@ -0,0 +1,21 @@
+const AUTO_WIRED_PROXY_ISLANDS = Symbol.for('stack-utils.proxy.auto-wired-islands');
+/**
+ * Declare a proxy islands registry in a form the `proxyIslands()` Vite plugin
+ * can recognize and auto-wire for the browser.
+ *
+ * Runtime behavior stays minimal: the helper returns the original config
+ * object with a non-enumerable internal marker so the proxy can produce a
+ * helpful error when client islands are used without the build plugin.
+ */
+export function defineProxyIslands(config) {
+    Object.defineProperty(config, AUTO_WIRED_PROXY_ISLANDS, {
+        value: true,
+        enumerable: false,
+        configurable: false,
+        writable: false
+    });
+    return config;
+}
+export function isAutoWiredProxyIslandsConfig(config) {
+    return Boolean(config && config[AUTO_WIRED_PROXY_ISLANDS]);
+}

package/dist/proxy/handle.js

@@ -1,5 +1,6 @@
-import { applyDomActions } from './dom-actions.js';
-import { injectIntoSitemapIndex, rewriteHtml } from './rewrite.js';
+import { validateIslandsConfigAtStartup } from './islands.js';
+import { injectIntoSitemapIndex, normalizeSitemapPath, removeExcludedUrlsFromSitemap, rewriteHtml } from './rewrite.js';
+import { transformProxiedHtml } from './transform-html.js';
 /**
  * Create a SvelteKit `Handle` hook that reverse-proxies requests to an origin.
  *
@@ -7,13 +8,19 @@ import { injectIntoSitemapIndex, rewriteHtml } from './rewrite.js';
  * everything else is forwarded to the origin.
  */
 export function createProxyHandle(config) {
+    assertNoRemovedConfig(config);
     const { originUrl, siteUrl } = config;
-    const sitemaps = config.sitemaps ?? [];
-    const sitemapCache = `public, max-age=${config.sitemapCacheSeconds ?? 3600}`;
+    const sitemap = config.sitemap ?? {};
+    const sitemapIndexPath = sitemap.indexPath ? normalizeSitemapPath(sitemap.indexPath) : undefined;
+    const sitemapIncludeFiles = sitemap.includeFiles ?? [];
+    const sitemapExcludePaths = sitemap.excludePaths ?? [];
+    const sitemapCache = `public, max-age=${sitemap.cacheSeconds ?? 3600}`;
     const proxyAssets = config.proxyAssets ?? false;
     const additionalOrigins = config.additionalOrigins ?? [];
     const maxRedirects = config.maxInternalRedirects ?? 5;
-    const domActions = config.domActions ?? [];
+    const transformDom = config.transformDom;
+    const islandsConfig = config.islands;
+    validateIslandsConfigAtStartup(islandsConfig);
     const textReplacements = config.textReplacements ?? {};
     const siteHost = new URL(siteUrl).hostname;
     const originHosts = new Set([
@@ -68,12 +75,25 @@ export function createProxyHandle(config) {
             cleanHeaders.delete('content-encoding');
             cleanHeaders.delete('content-length');
             cleanHeaders.delete('transfer-encoding');
+            if (isNullBodyStatus(upstreamResponse.status)) {
+                return new Response(null, {
+                    status: upstreamResponse.status,
+                    statusText: upstreamResponse.statusText,
+                    headers: cleanHeaders
+                });
+            }
             const contentType = upstreamResponse.headers.get('content-type') ?? '';
             if (contentType.includes('text/xml') || contentType.includes('application/xml')) {
                 let xml = await upstreamResponse.text();
                 xml = xml.replace(/<\?xml-stylesheet[^?]*\?>\s*/g, '');
-                if (sitemaps.length > 0 && xml.includes('</sitemapindex>')) {
-                    xml = injectIntoSitemapIndex(xml, siteUrl, sitemaps);
+                const isConfiguredSitemapIndex = sitemapIndexPath !== undefined && normalizeSitemapPath(pathname) === sitemapIndexPath;
+                if (isConfiguredSitemapIndex &&
+                    sitemapIncludeFiles.length > 0 &&
+                    xml.includes('</sitemapindex>')) {
+                    xml = injectIntoSitemapIndex(xml, siteUrl, sitemapIncludeFiles);
+                }
+                else if (sitemapExcludePaths.length > 0 && xml.includes('</urlset>')) {
+                    xml = removeExcludedUrlsFromSitemap(xml, sitemapExcludePaths);
                 }
                 cleanHeaders.set('cache-control', sitemapCache);
                 return new Response(xml, {
@@ -85,7 +105,12 @@ export function createProxyHandle(config) {
             if (contentType.includes('text/html')) {
                 const html = await upstreamResponse.text();
                 let result = rewriteHtml(html, originUrl, siteUrl, proxyAssets, additionalOrigins);
-                result = applyDomActions(result, domActions);
+                result = await transformProxiedHtml(result, {
+                    transformDom,
+                    islandsConfig,
+                    event,
+                    url: event.url
+                });
                 for (const [search, replace] of Object.entries(textReplacements)) {
                     result = result.replaceAll(search, replace);
                 }
@@ -103,3 +128,23 @@ export function createProxyHandle(config) {
         }
     };
 }
+/**
+ * Surface removed config options at startup with a migration-friendly error
+ * instead of silently ignoring them or — worse — applying half of the legacy
+ * behavior. The TypeScript types already reject these via
+ * `DeprecatedProxyOption` sentinels; this is the JS-runtime safety net.
+ */
+function assertNoRemovedConfig(config) {
+    if ('sitemaps' in config) {
+        throw new Error('`sitemaps` is deprecated and no longer supported. Use `sitemap.includeFiles` with `sitemap.indexPath` instead.');
+    }
+    if ('sitemapCacheSeconds' in config) {
+        throw new Error('`sitemapCacheSeconds` is deprecated and no longer supported. Use `sitemap.cacheSeconds` instead.');
+    }
+    if ('domActions' in config) {
+        throw new Error('`domActions` was removed in v2. Migrate every transformation to `transformDom: ($, ctx) => { ... }` and call `ctx.renderIsland(...)` for islands.');
+    }
+}
+function isNullBodyStatus(status) {
+    return status === 101 || status === 103 || status === 204 || status === 205 || status === 304;
+}

package/dist/proxy/index.d.ts

@@ -1,2 +1,3 @@
+export { defineProxyIslands } from './define-islands.js';
 export { createProxyHandle } from './handle.js';
-export type { DomAction, ProxyConfig } from './types.js';
+export type { IslandComponent, IslandMode, IslandSpec, ProxyConfig, ProxyIslandsConfig, SitemapConfig, TransformDomContext, TransformDomHook, TransformDomTarget } from './types.js';

package/dist/proxy/index.js

@@ -1 +1,2 @@
+export { defineProxyIslands } from './define-islands.js';
 export { createProxyHandle } from './handle.js';

package/dist/proxy/islands.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Server-side island rendering helpers.
+ *
+ * Kept in its own module so `svelte/server` is only imported when the proxy
+ * actually needs to render an island. The first call lazily resolves the
+ * `render` export and caches it for the lifetime of the process.
+ */
+import type { IslandMode, IslandSpec, ProxyIslandsConfig } from './types.js';
+export declare const ISLAND_ATTRS: Readonly<{
+    island: "data-stack-island";
+    mode: "data-stack-island-mode";
+    id: "data-stack-island-id";
+    props: "data-stack-island-props";
+    propsFor: "data-stack-island-for";
+}>;
+export interface RenderedIsland {
+    name: string;
+    mode: IslandMode;
+    headHtml: string;
+    bodyHtml: string;
+    serializedProps: string | null;
+}
+/** Render an island spec into SSR HTML plus optional serialized props. */
+export declare function renderIsland(spec: IslandSpec, islandsConfig: ProxyIslandsConfig): Promise<RenderedIsland>;
+/**
+ * Escape a JSON payload for safe embedding in a `<script>` tag.
+ * Prevents premature `</script>` termination and HTML comment hijacks.
+ */
+export declare function escapeJsonForScript(json: string): string;
+/** Build the `<script>` tag that carries serialized props for a rendered island. */
+export declare function buildPropsScript(islandId: string, serializedProps: string): string;
+/**
+ * Validate the islands config at startup.
+ *
+ * Whether or not a request actually renders a client island is a runtime
+ * decision (`transformDom` is dynamic), so the per-island checks
+ * (unknown name, invalid mode, JSON-serializable props) happen lazily in
+ * {@link renderIsland}. Still, when the registry was declared with
+ * `defineProxyIslands(...)` we know the consumer expects the
+ * `proxyIslands()` Vite plugin to inject `clientEntry`. If it didn't, the
+ * plugin is missing from `vite.config.ts` and every client island would fail
+ * at the first request — surface that mistake at startup instead.
+ */
+export declare function validateIslandsConfigAtStartup(islandsConfig: ProxyIslandsConfig | undefined): void;
+/**
+ * Build the `<script type="module">` tag that loads the consumer's client
+ * bootstrap. Returns an empty string when no client entry is configured.
+ */
+export declare function buildBootstrapScript(clientEntry: string): string;
+export declare function buildModulePreloadLink(clientEntry: string): string;
+export declare function buildStylesheetLink(stylesheetUrl: string): string;

package/dist/proxy/islands.js

@@ -0,0 +1,105 @@
+/**
+ * Server-side island rendering helpers.
+ *
+ * Kept in its own module so `svelte/server` is only imported when the proxy
+ * actually needs to render an island. The first call lazily resolves the
+ * `render` export and caches it for the lifetime of the process.
+ */
+import { isAutoWiredProxyIslandsConfig } from './define-islands.js';
+const DATA_ISLAND_ATTR = 'data-stack-island';
+const DATA_ISLAND_MODE_ATTR = 'data-stack-island-mode';
+const DATA_ISLAND_ID_ATTR = 'data-stack-island-id';
+const DATA_PROPS_ATTR = 'data-stack-island-props';
+const DATA_PROPS_FOR_ATTR = 'data-stack-island-for';
+export const ISLAND_ATTRS = Object.freeze({
+    island: DATA_ISLAND_ATTR,
+    mode: DATA_ISLAND_MODE_ATTR,
+    id: DATA_ISLAND_ID_ATTR,
+    props: DATA_PROPS_ATTR,
+    propsFor: DATA_PROPS_FOR_ATTR
+});
+let cachedRender = null;
+async function getSvelteRender() {
+    if (cachedRender) {
+        return cachedRender;
+    }
+    let mod;
+    try {
+        mod = (await import('svelte/server'));
+    }
+    catch (cause) {
+        throw new Error('[stack-utils proxy] failed to load `svelte/server`. Islands require Svelte 5 as a peer dependency.', { cause: cause });
+    }
+    cachedRender = mod.render;
+    return cachedRender;
+}
+/** Render an island spec into SSR HTML plus optional serialized props. */
+export async function renderIsland(spec, islandsConfig) {
+    const component = islandsConfig.components[spec.name];
+    if (!component) {
+        throw new Error(`[stack-utils proxy] island component "${spec.name}" is not registered.`);
+    }
+    const mode = spec.mode ?? 'serverOnly';
+    const props = spec.props ?? {};
+    const render = await getSvelteRender();
+    const output = render(component, { props });
+    const headHtml = output.head ?? '';
+    const bodyHtml = output.body ?? output.html ?? '';
+    let serializedProps = null;
+    if (mode !== 'serverOnly') {
+        try {
+            serializedProps = escapeJsonForScript(JSON.stringify(props));
+        }
+        catch (cause) {
+            throw new Error(`[stack-utils proxy] island "${spec.name}" props must be JSON-serializable for mode "${mode}".`, { cause: cause });
+        }
+    }
+    return { name: spec.name, mode, headHtml, bodyHtml, serializedProps };
+}
+/**
+ * Escape a JSON payload for safe embedding in a `<script>` tag.
+ * Prevents premature `</script>` termination and HTML comment hijacks.
+ */
+export function escapeJsonForScript(json) {
+    return json.replace(/<\/(script)/gi, '<\\/$1').replace(/<!--/g, '<\\!--');
+}
+/** Build the `<script>` tag that carries serialized props for a rendered island. */
+export function buildPropsScript(islandId, serializedProps) {
+    return `<script type="application/json" ${DATA_PROPS_ATTR} ${DATA_PROPS_FOR_ATTR}="${islandId}">${serializedProps}</script>`;
+}
+/**
+ * Validate the islands config at startup.
+ *
+ * Whether or not a request actually renders a client island is a runtime
+ * decision (`transformDom` is dynamic), so the per-island checks
+ * (unknown name, invalid mode, JSON-serializable props) happen lazily in
+ * {@link renderIsland}. Still, when the registry was declared with
+ * `defineProxyIslands(...)` we know the consumer expects the
+ * `proxyIslands()` Vite plugin to inject `clientEntry`. If it didn't, the
+ * plugin is missing from `vite.config.ts` and every client island would fail
+ * at the first request — surface that mistake at startup instead.
+ */
+export function validateIslandsConfigAtStartup(islandsConfig) {
+    if (!islandsConfig) {
+        return;
+    }
+    if (isAutoWiredProxyIslandsConfig(islandsConfig) && !islandsConfig.clientEntry) {
+        throw new Error('[stack-utils proxy] `islands` was declared with `defineProxyIslands(...)` but no `clientEntry` was injected. Add `proxyIslands()` to your `vite.config.ts` plugins.');
+    }
+}
+/**
+ * Build the `<script type="module">` tag that loads the consumer's client
+ * bootstrap. Returns an empty string when no client entry is configured.
+ */
+export function buildBootstrapScript(clientEntry) {
+    const escaped = clientEntry.replace(/"/g, '&quot;');
+    return `<script type="module" src="${escaped}"></script>`;
+}
+export function buildModulePreloadLink(clientEntry) {
+    const escaped = clientEntry.replace(/"/g, '&quot;');
+    return `<link rel="modulepreload" href="${escaped}">`;
+}
+export function buildStylesheetLink(stylesheetUrl) {
+    const escaped = stylesheetUrl.replace(/"/g, '&quot;');
+    return `<link rel="stylesheet" href="${escaped}">`;
+}

package/dist/proxy/rewrite.d.ts

@@ -9,5 +9,9 @@
  * - When `proxyAssets` is false, absolute origin URLs are left as-is.
  */
 export declare function rewriteHtml(html: string, originUrl: string, siteUrl: string, proxyAssets?: boolean, additionalOrigins?: string[]): string;
-/** Inject SvelteKit sitemap references into a `<sitemapindex>`. */
-export declare function injectIntoSitemapIndex(xml: string, siteUrl: string, sitemaps: string[]): string;
+/** Normalize URL-like values to comparable sitemap pathnames. */
+export declare function normalizeSitemapPath(value: string): string;
+/** Inject local sitemap references into a configured `<sitemapindex>`. */
+export declare function injectIntoSitemapIndex(xml: string, siteUrl: string, includeFiles: string[]): string;
+/** Remove `<url>` entries whose `<loc>` pathname is listed in `excludePaths`. */
+export declare function removeExcludedUrlsFromSitemap(xml: string, excludePaths: string[]): string;

package/dist/proxy/rewrite.js

@@ -41,10 +41,44 @@ export function rewriteHtml(html, originUrl, siteUrl, proxyAssets = false, addit
     }
     return html;
 }
-/** Inject SvelteKit sitemap references into a `<sitemapindex>`. */
-export function injectIntoSitemapIndex(xml, siteUrl, sitemaps) {
-    const entries = sitemaps
+/** Normalize URL-like values to comparable sitemap pathnames. */
+export function normalizeSitemapPath(value) {
+    let pathname = value.trim();
+    try {
+        pathname = new URL(pathname, 'https://stack-utils.local').pathname;
+    }
+    catch {
+        // Fall back to the raw value below; invalid URL-like values should not crash rewriting.
+    }
+    if (!pathname.startsWith('/')) {
+        pathname = `/${pathname}`;
+    }
+    if (pathname === '/') {
+        return pathname;
+    }
+    return pathname.replace(/\/+$/g, '') || '/';
+}
+/** Inject local sitemap references into a configured `<sitemapindex>`. */
+export function injectIntoSitemapIndex(xml, siteUrl, includeFiles) {
+    if (includeFiles.length === 0) {
+        return xml;
+    }
+    const entries = includeFiles
         .map((url) => `\t<sitemap>\n\t\t<loc>${siteUrl}${url}</loc>\n\t</sitemap>`)
         .join('\n');
     return xml.replace('</sitemapindex>', `${entries}\n</sitemapindex>`);
 }
+/** Remove `<url>` entries whose `<loc>` pathname is listed in `excludePaths`. */
+export function removeExcludedUrlsFromSitemap(xml, excludePaths) {
+    if (excludePaths.length === 0) {
+        return xml;
+    }
+    const excluded = new Set(excludePaths.map(normalizeSitemapPath));
+    return xml.replace(/<url\b[\s\S]*?<\/url>/g, (entry) => {
+        const loc = entry.match(/<loc\b[^>]*>\s*([\s\S]*?)\s*<\/loc>/i)?.[1];
+        if (!loc) {
+            return entry;
+        }
+        return excluded.has(normalizeSitemapPath(loc)) ? '' : entry;
+    });
+}

package/dist/proxy/transform-html.d.ts

@@ -0,0 +1,20 @@
+import type { ProxyIslandsConfig, TransformDomHook } from './types.js';
+export interface TransformProxiedHtmlOptions {
+    /** Power-user hook. Receives the cheerio root for the proxied document. */
+    transformDom?: TransformDomHook;
+    /** Island registry and bootstrap config. Required for any island rendering. */
+    islandsConfig?: ProxyIslandsConfig;
+    /** SvelteKit request event, forwarded to `transformDom`. */
+    event: import('@sveltejs/kit').RequestEvent;
+    /** Request URL, forwarded to `transformDom`. Usually `event.url`. */
+    url: URL;
+}
+/**
+ * Run the `transformDom` hook against the proxied document and finalize the
+ * island bootstrap (SSR head dedup, modulepreload, stylesheets, module
+ * script).
+ *
+ * Async because rendering Svelte islands lazily loads `svelte/server` on the
+ * first call.
+ */
+export declare function transformProxiedHtml(html: string, options: TransformProxiedHtmlOptions): Promise<string>;

package/dist/proxy/transform-html.js

@@ -0,0 +1,80 @@
+import { load } from 'cheerio';
+import { ISLAND_ATTRS, buildBootstrapScript, buildModulePreloadLink, buildPropsScript, buildStylesheetLink, renderIsland } from './islands.js';
+/**
+ * Run the `transformDom` hook against the proxied document and finalize the
+ * island bootstrap (SSR head dedup, modulepreload, stylesheets, module
+ * script).
+ *
+ * Async because rendering Svelte islands lazily loads `svelte/server` on the
+ * first call.
+ */
+export async function transformProxiedHtml(html, options) {
+    const { transformDom, islandsConfig, event, url } = options;
+    if (!transformDom) {
+        return html;
+    }
+    const $ = load(html);
+    const tracker = {
+        islandCounter: 0,
+        clientIslandsRendered: false,
+        headSnippets: new Set()
+    };
+    await transformDom($, {
+        event,
+        url,
+        renderIsland: (target, spec) => renderIslandInto($, target, spec, islandsConfig, tracker)
+    });
+    finalizeIslandBootstrap($, tracker, islandsConfig);
+    return $.html();
+}
+async function renderIslandInto($, target, spec, islandsConfig, tracker) {
+    if (target.length === 0) {
+        return;
+    }
+    if (!islandsConfig?.components) {
+        throw new Error('[stack-utils proxy] `renderIsland(...)` was called but no `islands.components` registry was provided on `ProxyConfig.islands`.');
+    }
+    const rendered = await renderIsland(spec, islandsConfig);
+    if (rendered.headHtml) {
+        tracker.headSnippets.add(rendered.headHtml);
+    }
+    target.each((_, raw) => {
+        const $el = $(raw);
+        const islandId = `stack-island-${++tracker.islandCounter}`;
+        $el.html(rendered.bodyHtml);
+        $el.attr(ISLAND_ATTRS.island, rendered.name);
+        $el.attr(ISLAND_ATTRS.mode, rendered.mode);
+        if (rendered.serializedProps !== null) {
+            $el.attr(ISLAND_ATTRS.id, islandId);
+            $el.after(buildPropsScript(islandId, rendered.serializedProps));
+            tracker.clientIslandsRendered = true;
+        }
+    });
+}
+function finalizeIslandBootstrap($, tracker, islandsConfig) {
+    if (tracker.headSnippets.size > 0) {
+        const head = $('head');
+        if (head.length > 0) {
+            for (const snippet of tracker.headSnippets) {
+                head.append(`\n${snippet}\n`);
+            }
+        }
+    }
+    if (!tracker.clientIslandsRendered) {
+        return;
+    }
+    if (!islandsConfig?.clientEntry) {
+        throw new Error('[stack-utils proxy] client islands were rendered but `islands.clientEntry` is not configured. Either provide `islands.clientEntry` directly or wrap the config with `defineProxyIslands(...)` and install the `proxyIslands()` Vite plugin.');
+    }
+    const head = $('head');
+    if (head.length > 0 && !islandsConfig.clientEntry.startsWith('data:')) {
+        head.append(`\n${buildModulePreloadLink(islandsConfig.clientEntry)}\n`);
+    }
+    if (head.length > 0) {
+        const stylesheets = islandsConfig.clientStylesheets ?? [];
+        for (const stylesheetUrl of stylesheets) {
+            head.append(`\n${buildStylesheetLink(stylesheetUrl)}\n`);
+        }
+    }
+    $('body').append(`\n${buildBootstrapScript(islandsConfig.clientEntry)}\n`);
+}