@elurjs/kit 2.4.10 → 2.5.1

package/dist/lib/island/generate-entry.d.ts

@@ -1,4 +1,28 @@
 import type { IslandModule } from "./scan.js";
+/**
+ * Router options for the generated client entry (Fase 8.3).
+ */
+export interface RouterEntryOptions {
+    /**
+     * Include SPA navigation code. When `false` the generated entry is
+     * hydrate-only and no router file is emitted. Default: `true`.
+     */
+    enabled?: boolean;
+    /** Forwarded to `startClientRouter({ prefetch })`. Default: `true`. */
+    prefetch?: boolean;
+    /** Forwarded to `startClientRouter({ morph })` (idiomorph swap). */
+    morph?: boolean;
+    /** Forwarded to `startClientRouter({ loadingIndicator })`. */
+    loadingIndicator?: boolean;
+    /**
+     * Split mode: the entry hydrates islands only and the router lives in a
+     * separate generated module (`router.ts` next to the entry, emitted as its
+     * own chunk). This is what lets pages without islands load only the router.
+     */
+    separate?: boolean;
+    /** Absolute path of the generated router module when `separate` is set. */
+    outFile?: string;
+}
 /** Options for generating the client entry module. */
 export interface GenerateEntryOptions {
     /** Islands to register, from `scanIslands`. */
@@ -15,11 +39,25 @@ export interface GenerateEntryOptions {
      * Defaults to the published subpath `@elurjs/kit/router`.
      */
     routerImport?: string;
+    /**
+     * Router inclusion. Omit for the legacy combined entry (router embedded).
+     * With `separate: true`, a standalone router module is also generated at
+     * `router.outFile`.
+     */
+    router?: RouterEntryOptions;
 }
+/**
+ * Source for the standalone router module emitted in split builds. Router
+ * options are baked in so the public module takes no arguments.
+ */
+export declare function buildRouterEntrySource(routerImport?: string, options?: Omit<RouterEntryOptions, "enabled" | "separate" | "outFile">): string;
 /** Builds the source code of the client entry module. */
-export declare function buildEntrySource(islands: IslandModule[], outFile: string, hydrateImport?: string, routerImport?: string): string;
+export declare function buildEntrySource(islands: IslandModule[], outFile: string, hydrateImport?: string, routerImport?: string, router?: RouterEntryOptions): string;
 /**
- * Generates and writes the client entry module for the given islands.
+ * Generates and writes the client entry module for the given islands. When
+ * `options.router.separate` is set (and the router is enabled), a standalone
+ * router module is written alongside it (default: `router.ts` next to the
+ * entry — bundle it as a second input to emit `/_elur/router.js`).
  *
  * @param options Generation options.
  * @returns The absolute path of the written entry file.

package/dist/lib/island/hydrate.d.cts

@@ -21,13 +21,26 @@ export type IslandRegistry = Record<string, IslandRegistryEntry<any>>;
  */
 export declare function lazyIsland<TProps = unknown>(loader: () => Promise<IslandComponent<TProps>>): IslandLoader<TProps>;
 /**
- * Hydrates all islands on the page using the provided registry.
- *
- * @param registry Map from island name to component factory.
+ * Options for {@link cleanupHydratedIslands}.
  */
+export interface CleanupIslandsOptions {
+    /**
+     * Root elements whose islands must NOT be disposed — used by the SPA router
+     * to keep the live state of islands inside `data-elur-persist` nodes that
+     * are moved (not re-rendered) into the new page. The router passes them via
+     * the `elur:before-render` event detail (`detail.persisted`).
+     */
+    except?: Iterable<Element>;
+}
 /**
- * Dispose all currently hydrated islands. Called by the client router before
- * swapping the page body to prevent leaked effects and stale DOM writes.
+ * Dispose all currently hydrated islands. Runs on the `elur:before-render`
+ * event — dispatched by the client router BEFORE it swaps the page body — so
+ * effects are cleaned up while their DOM is still attached, and islands inside
+ * `except` roots keep running untouched.
+ *
+ * Hosts that only dispatch the legacy `elur:rendered` event keep working: the
+ * generated entry runs this cleanup on `elur:rendered` as a compat fallback
+ * when no `elur:before-render` preceded it.
  */
-export declare function cleanupHydratedIslands(): void;
+export declare function cleanupHydratedIslands(options?: CleanupIslandsOptions): void;
 export declare function hydrateIslands(registry: IslandRegistry): void;

package/dist/lib/island/hydrate.d.ts

@@ -21,13 +21,26 @@ export type IslandRegistry = Record<string, IslandRegistryEntry<any>>;
  */
 export declare function lazyIsland<TProps = unknown>(loader: () => Promise<IslandComponent<TProps>>): IslandLoader<TProps>;
 /**
- * Hydrates all islands on the page using the provided registry.
- *
- * @param registry Map from island name to component factory.
+ * Options for {@link cleanupHydratedIslands}.
  */
+export interface CleanupIslandsOptions {
+    /**
+     * Root elements whose islands must NOT be disposed — used by the SPA router
+     * to keep the live state of islands inside `data-elur-persist` nodes that
+     * are moved (not re-rendered) into the new page. The router passes them via
+     * the `elur:before-render` event detail (`detail.persisted`).
+     */
+    except?: Iterable<Element>;
+}
 /**
- * Dispose all currently hydrated islands. Called by the client router before
- * swapping the page body to prevent leaked effects and stale DOM writes.
+ * Dispose all currently hydrated islands. Runs on the `elur:before-render`
+ * event — dispatched by the client router BEFORE it swaps the page body — so
+ * effects are cleaned up while their DOM is still attached, and islands inside
+ * `except` roots keep running untouched.
+ *
+ * Hosts that only dispatch the legacy `elur:rendered` event keep working: the
+ * generated entry runs this cleanup on `elur:rendered` as a compat fallback
+ * when no `elur:before-render` preceded it.
  */
-export declare function cleanupHydratedIslands(): void;
+export declare function cleanupHydratedIslands(options?: CleanupIslandsOptions): void;
 export declare function hydrateIslands(registry: IslandRegistry): void;

package/dist/lib/island/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("../hydrate-D6MR24mz.cjs");exports.cleanupHydratedIslands=e.t,exports.hydrateIslands=e.n,exports.lazyIsland=e.r;
+Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("../island-kfQEKRe_.cjs"),t=require("../hydrate-BSLuI0Nh.cjs");exports.ISLAND_MARKER_ATTR=e.t,exports.PERSIST_ATTR=e.n,exports.cleanupHydratedIslands=t.t,exports.hydrateIslands=t.n,exports.lazyIsland=t.r;

package/dist/lib/island/index.d.cts

@@ -1,2 +1,3 @@
-export { hydrateIslands, cleanupHydratedIslands, lazyIsland, type IslandRegistry, type IslandLoader, type IslandRegistryEntry } from "./hydrate.js";
+export { hydrateIslands, cleanupHydratedIslands, lazyIsland, type IslandRegistry, type IslandLoader, type IslandRegistryEntry, type CleanupIslandsOptions } from "./hydrate.js";
 export type { IslandComponent, IslandDirective, IslandOptions } from "./island.js";
+export { ISLAND_MARKER_ATTR, PERSIST_ATTR } from "./island.js";

package/dist/lib/island/index.d.ts

@@ -1,2 +1,3 @@
-export { hydrateIslands, cleanupHydratedIslands, lazyIsland, type IslandRegistry, type IslandLoader, type IslandRegistryEntry } from "./hydrate.js";
+export { hydrateIslands, cleanupHydratedIslands, lazyIsland, type IslandRegistry, type IslandLoader, type IslandRegistryEntry, type CleanupIslandsOptions } from "./hydrate.js";
 export type { IslandComponent, IslandDirective, IslandOptions } from "./island.js";
+export { ISLAND_MARKER_ATTR, PERSIST_ATTR } from "./island.js";

package/dist/lib/island/index.js

@@ -1 +1 @@
-import{n as e,r as t,t as n}from"../hydrate-CJbUWdXu.js";export{n as cleanupHydratedIslands,e as hydrateIslands,t as lazyIsland};
+import{n as e,t}from"../island-CTBnsOhI.js";import{n,r,t as i}from"../hydrate-BaS7-d8C.js";export{t as ISLAND_MARKER_ATTR,e as PERSIST_ATTR,i as cleanupHydratedIslands,n as hydrateIslands,r as lazyIsland};

package/dist/lib/island/island.d.cts

@@ -1,5 +1,20 @@
 import { type ElurTemplate } from "@elurjs/core";
 export type IslandDirective = "load" | "idle" | "visible" | "only";
+/**
+ * HTML attribute that marks an island marker element. The renderer scans the
+ * rendered body for this attribute to decide whether the page needs the
+ * hydration entry at all (0% JS gating); the client hydrator queries the DOM
+ * with `[data-elur-island]`.
+ */
+export declare const ISLAND_MARKER_ATTR = "data-elur-island";
+/**
+ * HTML attribute that marks an element whose live DOM node is moved (not
+ * re-rendered) across SPA navigations — the Astro `transition:persist` /
+ * Turbo `data-turbo-permanent` pattern. The client router matches nodes by
+ * the attribute value (`data-elur-persist="key"`) between the old and new
+ * page, preserving component state, media playback, scroll position, etc.
+ */
+export declare const PERSIST_ATTR = "data-elur-persist";
 export interface IslandComponent<TProps = unknown> {
     (props: TProps): ElurTemplate | null | false | undefined;
 }

package/dist/lib/island/island.d.ts

@@ -1,5 +1,20 @@
 import { type ElurTemplate } from "@elurjs/core";
 export type IslandDirective = "load" | "idle" | "visible" | "only";
+/**
+ * HTML attribute that marks an island marker element. The renderer scans the
+ * rendered body for this attribute to decide whether the page needs the
+ * hydration entry at all (0% JS gating); the client hydrator queries the DOM
+ * with `[data-elur-island]`.
+ */
+export declare const ISLAND_MARKER_ATTR = "data-elur-island";
+/**
+ * HTML attribute that marks an element whose live DOM node is moved (not
+ * re-rendered) across SPA navigations — the Astro `transition:persist` /
+ * Turbo `data-turbo-permanent` pattern. The client router matches nodes by
+ * the attribute value (`data-elur-persist="key"`) between the old and new
+ * page, preserving component state, media playback, scroll position, etc.
+ */
+export declare const PERSIST_ATTR = "data-elur-persist";
 export interface IslandComponent<TProps = unknown> {
     (props: TProps): ElurTemplate | null | false | undefined;
 }

package/dist/lib/island-CTBnsOhI.js

@@ -0,0 +1,59 @@
+import { ELUR_RENDER_PROTOCOL as e } from "@elurjs/core";
+//#region src/island/island.ts
+var t = "data-elur-island", n = "data-elur-persist";
+function r(n, r, l, u = "load", d) {
+	let f = u === "only" ? !1 : d?.ssr ?? !0, p = d?.fallback, m = (e) => `<div ${t}="${s(n)}" data-directive="${u}" data-props='${c(l)}'>${e}</div>`;
+	return {
+		__isElurTemplate: !0,
+		[e]: { async renderServer(e) {
+			let t = "";
+			if (f) try {
+				let n = r(l);
+				t = n !== null && n !== !1 && n !== void 0 ? await e.render(n, { markers: !0 }) : await a(p, e);
+			} catch (e) {
+				throw i(n, e);
+			}
+			else t = await a(p, e);
+			return m(t);
+		} },
+		_render(e, t) {
+			let n = document.createElement("div"), i = "";
+			if (f) {
+				let e = r(l);
+				if (e !== null && e !== !1 && e !== void 0) {
+					let t = e._render(n, null);
+					i = n.innerHTML, t();
+				} else i = o(p, n);
+			} else i = o(p, n);
+			let a = document.createElement("template");
+			a.innerHTML = m(i);
+			let s = a.content, c = s.firstChild;
+			return e.insertBefore(s, t), () => {
+				c?.parentNode && c.parentNode.removeChild(c);
+			};
+		}
+	};
+}
+function i(e, t) {
+	let n = t instanceof Error ? t : Error(String(t)), r = t instanceof Error ? t.message : String(t);
+	return Error(`[elur-kit] Island "${e}" threw during SSR: ${r}\n  If the component accesses browser-only globals (document, window, etc.),\n  use directive: "only" or options: { ssr: false } to skip server rendering.\n  For environment reads (matchMedia, localStorage, navigator) you may guard\n  the access with isSSR() from "@elurjs/kit".`, { cause: n });
+}
+async function a(e, t) {
+	return e == null || e === "" ? "" : typeof e == "string" ? e : t.render(e, { markers: !1 });
+}
+function o(e, t) {
+	if (e == null || e === "") return "";
+	if (typeof e == "string") return e;
+	let n = e._render(t, null), r = t.innerHTML;
+	return n(), r;
+}
+function s(e) {
+	return e.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&#39;");
+}
+function c(e) {
+	return JSON.stringify(e ?? null).replace(/</g, "\\u003c").replace(/'/g, "\\u0027");
+}
+//#endregion
+export { n, r, t };
+
+//# sourceMappingURL=island-CTBnsOhI.js.map

package/dist/lib/island-CTBnsOhI.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"island-CTBnsOhI.js","names":[],"sources":["../../src/island/island.ts"],"sourcesContent":["import { ELUR_RENDER_PROTOCOL, type ElurTemplate, type ServerRenderProtocolContext } from \"@elurjs/core\";\n\n// --- Islands helper ---\n//\n// Marks a component as an island. During server-side rendering it emits a\n// static placeholder with `data-elur-island` attributes. The client entry finds\n// these markers and hydrates them with the real component + reactive signals.\n//\n// SSR strategy\n// ------------\n// By default the component is executed on the server to produce a fallback HTML\n// fragment (better first paint, SEO, less layout shift). Components that access\n// browser-only globals (`document`, `window`, `navigator`, ...) in their body\n// cannot run on the server. Two opt-out mechanisms are provided, mirroring the\n// industry standard (Astro `client:only`, Next.js `dynamic(..., { ssr: false })`):\n//\n//   1. directive: \"only\"  — shortcut for client-only with `load` scheduling.\n//   2. options: { ssr: false } — client-only with any directive (load/idle/visible).\n//\n// When SSR is skipped, only `options.fallback` (a ElurTemplate or string) is\n// rendered into the marker. The client hydrates from scratch.\n//\n// When SSR runs and the component throws, the error is NOT swallowed: it is\n// re-thrown wrapped with an actionable message naming the island and suggesting\n// `directive: \"only\"` / `{ ssr: false }` / `isSSR()`. This matches Astro and\n// Next.js, which never try/catch to \"auto-detect\" client-only components.\n\nexport type IslandDirective = \"load\" | \"idle\" | \"visible\" | \"only\";\n\n/**\n * HTML attribute that marks an island marker element. The renderer scans the\n * rendered body for this attribute to decide whether the page needs the\n * hydration entry at all (0% JS gating); the client hydrator queries the DOM\n * with `[data-elur-island]`.\n */\nexport const ISLAND_MARKER_ATTR = \"data-elur-island\";\n\n/**\n * HTML attribute that marks an element whose live DOM node is moved (not\n * re-rendered) across SPA navigations — the Astro `transition:persist` /\n * Turbo `data-turbo-permanent` pattern. The client router matches nodes by\n * the attribute value (`data-elur-persist=\"key\"`) between the old and new\n * page, preserving component state, media playback, scroll position, etc.\n */\nexport const PERSIST_ATTR = \"data-elur-persist\";\n\nexport interface IslandComponent<TProps = unknown> {\n  (props: TProps): ElurTemplate | null | false | undefined;\n}\n\n/**\n * Options for {@link island}.\n *\n * - `ssr`: Whether to execute the component on the server. Defaults to `true`\n *   unless `directive === \"only\"` (then `false`). When `false`, the component\n *   is never called during SSR; only `fallback` is rendered.\n * - `fallback`: HTML to render inside the island marker when SSR is skipped or\n *   the component returns null/false. Accepts a `ElurTemplate` (reactive, with\n *   signals) or a plain string. Defaults to an empty string.\n */\nexport interface IslandOptions {\n  ssr?: boolean;\n  fallback?: ElurTemplate | string;\n}\n\n/**\n * Renders a component to a static HTML string with island markers.\n *\n * @param name Unique island name used by the client entry to look up the module.\n * @param component Island component. Executed on the server unless `directive`\n *   is `\"only\"` or `options.ssr` is `false`.\n * @param props Props passed to the component and serialized for hydration.\n * @param directive When to hydrate on the client. Use `\"only\"` to skip SSR\n *   entirely (client-only island).\n * @param options SSR strategy and fallback content.\n * @returns A ElurTemplate that renders the island placeholder.\n */\nexport function island<TProps>(\n  name: string,\n  component: IslandComponent<TProps>,\n  props: TProps,\n  directive: IslandDirective = \"load\",\n  options?: IslandOptions,\n): ElurTemplate {\n  // `directive: \"only\"` forces ssr off; explicit `options.ssr` wins otherwise.\n  const ssr = directive === \"only\" ? false : (options?.ssr ?? true);\n  const fallback = options?.fallback;\n\n  const markerHtml = (innerHtml: string) =>\n    `<div ${ISLAND_MARKER_ATTR}=\"${escapeHtml(name)}\" data-directive=\"${directive}\" data-props='${serializeProps(props)}'>${innerHtml}</div>`;\n\n  return {\n    __isElurTemplate: true as const,\n    [ELUR_RENDER_PROTOCOL]: {\n      async renderServer(context: ServerRenderProtocolContext) {\n        let innerHtml = \"\";\n        if (ssr) {\n          try {\n            const template = component(props);\n            if (template !== null && template !== false && template !== undefined) {\n              innerHtml = await context.render(template, { markers: true });\n            } else {\n              // Component returned null/false/undefined — render fallback if any.\n              innerHtml = await renderFallback(fallback, context);\n            }\n          } catch (error) {\n            throw wrapIslandSSRError(name, error);\n          }\n        } else {\n          innerHtml = await renderFallback(fallback, context);\n        }\n        return markerHtml(innerHtml);\n      },\n    },\n    _render(parent: Node, before: Node | null): () => void {\n      const container = document.createElement(\"div\");\n      let innerHtml = \"\";\n      if (ssr) {\n        const template = component(props);\n        if (template !== null && template !== false && template !== undefined) {\n          const dispose = template._render(container, null);\n          innerHtml = container.innerHTML;\n          dispose();\n        } else {\n          // null/false/undefined — render fallback if any.\n          innerHtml = renderFallbackSync(fallback, container);\n        }\n      } else {\n        innerHtml = renderFallbackSync(fallback, container);\n      }\n      const wrapper = document.createElement(\"template\");\n      wrapper.innerHTML = markerHtml(innerHtml);\n      const fragment = wrapper.content;\n      const inserted = fragment.firstChild;\n      parent.insertBefore(fragment, before);\n      return () => {\n        if (inserted?.parentNode) inserted.parentNode.removeChild(inserted);\n      };\n    },\n  } as unknown as ElurTemplate;\n}\n\n/**\n * Wraps an SSR error from an island component with an actionable message.\n *\n * Following the Astro/Next.js convention, SSR errors are never silently\n * swallowed — they propagate so real bugs surface. The wrapper adds the island\n * name and three concrete remediation paths.\n */\nfunction wrapIslandSSRError(name: string, error: unknown): Error {\n  const cause = error instanceof Error ? error : new Error(String(error));\n  const msg = error instanceof Error ? error.message : String(error);\n  return new Error(\n    `[elur-kit] Island \"${name}\" threw during SSR: ${msg}\\n` +\n    `  If the component accesses browser-only globals (document, window, etc.),\\n` +\n    `  use directive: \"only\" or options: { ssr: false } to skip server rendering.\\n` +\n    `  For environment reads (matchMedia, localStorage, navigator) you may guard\\n` +\n    `  the access with isSSR() from \"@elurjs/kit\".`,\n    { cause },\n  );\n}\n\n/** Renders the fallback (ElurTemplate or string) to an HTML string on the server. */\nasync function renderFallback(\n  fallback: ElurTemplate | string | undefined,\n  context: ServerRenderProtocolContext,\n): Promise<string> {\n  if (fallback == null || fallback === \"\") return \"\";\n  if (typeof fallback === \"string\") return fallback;\n  return context.render(fallback, { markers: false });\n}\n\n/** Renders the fallback into a container and returns its innerHTML (client path). */\nfunction renderFallbackSync(fallback: ElurTemplate | string | undefined, container: HTMLElement): string {\n  if (fallback == null || fallback === \"\") return \"\";\n  if (typeof fallback === \"string\") return fallback;\n  const dispose = fallback._render(container, null);\n  const html = container.innerHTML;\n  dispose();\n  return html;\n}\n\nfunction escapeHtml(value: string): string {\n  return value\n    .replace(/&/g, \"&amp;\")\n    .replace(/</g, \"&lt;\")\n    .replace(/>/g, \"&gt;\")\n    .replace(/\"/g, \"&quot;\")\n    .replace(/'/g, \"&#39;\");\n}\n\nfunction serializeProps(props: unknown): string {\n  return JSON.stringify(props ?? null)\n    .replace(/</g, \"\\\\u003c\")\n    .replace(/'/g, \"\\\\u0027\");\n}\n"],"mappings":";;AAmCA,IAAa,IAAqB,oBASrB,IAAe;AAiC5B,SAAgB,EACd,GACA,GACA,GACA,IAA6B,QAC7B,GACc;CAEd,IAAM,IAAM,MAAc,SAAS,KAAS,GAAS,OAAO,IACtD,IAAW,GAAS,UAEpB,KAAc,MAClB,QAAQ,EAAmB,IAAI,EAAW,CAAI,EAAE,oBAAoB,EAAU,gBAAgB,EAAe,CAAK,EAAE,IAAI,EAAU;CAEpI,OAAO;EACL,kBAAkB;GACjB,IAAuB,EACtB,MAAM,aAAa,GAAsC;GACvD,IAAI,IAAY;GAChB,IAAI,GACF,IAAI;IACF,IAAM,IAAW,EAAU,CAAK;IAChC,AAIE,IAJE,MAAa,QAAQ,MAAa,MAAS,MAAa,KAAA,IAC9C,MAAM,EAAQ,OAAO,GAAU,EAAE,SAAS,GAAK,CAAC,IAGhD,MAAM,EAAe,GAAU,CAAO;GAEtD,SAAS,GAAO;IACd,MAAM,EAAmB,GAAM,CAAK;GACtC;QAEA,IAAY,MAAM,EAAe,GAAU,CAAO;GAEpD,OAAO,EAAW,CAAS;EAC7B,EACF;EACA,QAAQ,GAAc,GAAiC;GACrD,IAAM,IAAY,SAAS,cAAc,KAAK,GAC1C,IAAY;GAChB,IAAI,GAAK;IACP,IAAM,IAAW,EAAU,CAAK;IAChC,IAAI,MAAa,QAAQ,MAAa,MAAS,MAAa,KAAA,GAAW;KACrE,IAAM,IAAU,EAAS,QAAQ,GAAW,IAAI;KAEhD,AADA,IAAY,EAAU,WACtB,EAAQ;IACV,OAEE,IAAY,EAAmB,GAAU,CAAS;GAEtD,OACE,IAAY,EAAmB,GAAU,CAAS;GAEpD,IAAM,IAAU,SAAS,cAAc,UAAU;GACjD,EAAQ,YAAY,EAAW,CAAS;GACxC,IAAM,IAAW,EAAQ,SACnB,IAAW,EAAS;GAE1B,OADA,EAAO,aAAa,GAAU,CAAM,SACvB;IACX,AAAI,GAAU,cAAY,EAAS,WAAW,YAAY,CAAQ;GACpE;EACF;CACF;AACF;AASA,SAAS,EAAmB,GAAc,GAAuB;CAC/D,IAAM,IAAQ,aAAiB,QAAQ,IAAY,MAAM,OAAO,CAAK,CAAC,GAChE,IAAM,aAAiB,QAAQ,EAAM,UAAU,OAAO,CAAK;CACjE,OAAW,MACT,sBAAsB,EAAK,sBAAsB,EAAI,yRAKrD,EAAE,SAAM,CACV;AACF;AAGA,eAAe,EACb,GACA,GACiB;CAGjB,OAFI,KAAY,QAAQ,MAAa,KAAW,KAC5C,OAAO,KAAa,WAAiB,IAClC,EAAQ,OAAO,GAAU,EAAE,SAAS,GAAM,CAAC;AACpD;AAGA,SAAS,EAAmB,GAA6C,GAAgC;CACvG,IAAI,KAAY,QAAQ,MAAa,IAAI,OAAO;CAChD,IAAI,OAAO,KAAa,UAAU,OAAO;CACzC,IAAM,IAAU,EAAS,QAAQ,GAAW,IAAI,GAC1C,IAAO,EAAU;CAEvB,OADA,EAAQ,GACD;AACT;AAEA,SAAS,EAAW,GAAuB;CACzC,OAAO,EACJ,QAAQ,MAAM,OAAO,CAAC,CACtB,QAAQ,MAAM,MAAM,CAAC,CACrB,QAAQ,MAAM,MAAM,CAAC,CACrB,QAAQ,MAAM,QAAQ,CAAC,CACvB,QAAQ,MAAM,OAAO;AAC1B;AAEA,SAAS,EAAe,GAAwB;CAC9C,OAAO,KAAK,UAAU,KAAS,IAAI,CAAC,CACjC,QAAQ,MAAM,SAAS,CAAC,CACxB,QAAQ,MAAM,SAAS;AAC5B"}

package/dist/lib/island-kfQEKRe_.cjs

@@ -0,0 +1,2 @@
+let e=require("@elurjs/core");var t=`data-elur-island`,n=`data-elur-persist`;function r(n,r,l,u=`load`,d){let f=u===`only`?!1:d?.ssr??!0,p=d?.fallback,m=e=>`<div ${t}="${s(n)}" data-directive="${u}" data-props='${c(l)}'>${e}</div>`;return{__isElurTemplate:!0,[e.ELUR_RENDER_PROTOCOL]:{async renderServer(e){let t=``;if(f)try{let n=r(l);t=n!==null&&n!==!1&&n!==void 0?await e.render(n,{markers:!0}):await a(p,e)}catch(e){throw i(n,e)}else t=await a(p,e);return m(t)}},_render(e,t){let n=document.createElement(`div`),i=``;if(f){let e=r(l);if(e!==null&&e!==!1&&e!==void 0){let t=e._render(n,null);i=n.innerHTML,t()}else i=o(p,n)}else i=o(p,n);let a=document.createElement(`template`);a.innerHTML=m(i);let s=a.content,c=s.firstChild;return e.insertBefore(s,t),()=>{c?.parentNode&&c.parentNode.removeChild(c)}}}}function i(e,t){let n=t instanceof Error?t:Error(String(t)),r=t instanceof Error?t.message:String(t);return Error(`[elur-kit] Island "${e}" threw during SSR: ${r}\n  If the component accesses browser-only globals (document, window, etc.),\n  use directive: "only" or options: { ssr: false } to skip server rendering.\n  For environment reads (matchMedia, localStorage, navigator) you may guard\n  the access with isSSR() from "@elurjs/kit".`,{cause:n})}async function a(e,t){return e==null||e===``?``:typeof e==`string`?e:t.render(e,{markers:!1})}function o(e,t){if(e==null||e===``)return``;if(typeof e==`string`)return e;let n=e._render(t,null),r=t.innerHTML;return n(),r}function s(e){return e.replace(/&/g,`&amp;`).replace(/</g,`&lt;`).replace(/>/g,`&gt;`).replace(/"/g,`&quot;`).replace(/'/g,`&#39;`)}function c(e){return JSON.stringify(e??null).replace(/</g,`\\u003c`).replace(/'/g,`\\u0027`)}Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return n}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return t}});
+//# sourceMappingURL=island-kfQEKRe_.cjs.map

package/dist/lib/island-kfQEKRe_.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"island-kfQEKRe_.cjs","names":[],"sources":["../../src/island/island.ts"],"sourcesContent":["import { ELUR_RENDER_PROTOCOL, type ElurTemplate, type ServerRenderProtocolContext } from \"@elurjs/core\";\n\n// --- Islands helper ---\n//\n// Marks a component as an island. During server-side rendering it emits a\n// static placeholder with `data-elur-island` attributes. The client entry finds\n// these markers and hydrates them with the real component + reactive signals.\n//\n// SSR strategy\n// ------------\n// By default the component is executed on the server to produce a fallback HTML\n// fragment (better first paint, SEO, less layout shift). Components that access\n// browser-only globals (`document`, `window`, `navigator`, ...) in their body\n// cannot run on the server. Two opt-out mechanisms are provided, mirroring the\n// industry standard (Astro `client:only`, Next.js `dynamic(..., { ssr: false })`):\n//\n//   1. directive: \"only\"  — shortcut for client-only with `load` scheduling.\n//   2. options: { ssr: false } — client-only with any directive (load/idle/visible).\n//\n// When SSR is skipped, only `options.fallback` (a ElurTemplate or string) is\n// rendered into the marker. The client hydrates from scratch.\n//\n// When SSR runs and the component throws, the error is NOT swallowed: it is\n// re-thrown wrapped with an actionable message naming the island and suggesting\n// `directive: \"only\"` / `{ ssr: false }` / `isSSR()`. This matches Astro and\n// Next.js, which never try/catch to \"auto-detect\" client-only components.\n\nexport type IslandDirective = \"load\" | \"idle\" | \"visible\" | \"only\";\n\n/**\n * HTML attribute that marks an island marker element. The renderer scans the\n * rendered body for this attribute to decide whether the page needs the\n * hydration entry at all (0% JS gating); the client hydrator queries the DOM\n * with `[data-elur-island]`.\n */\nexport const ISLAND_MARKER_ATTR = \"data-elur-island\";\n\n/**\n * HTML attribute that marks an element whose live DOM node is moved (not\n * re-rendered) across SPA navigations — the Astro `transition:persist` /\n * Turbo `data-turbo-permanent` pattern. The client router matches nodes by\n * the attribute value (`data-elur-persist=\"key\"`) between the old and new\n * page, preserving component state, media playback, scroll position, etc.\n */\nexport const PERSIST_ATTR = \"data-elur-persist\";\n\nexport interface IslandComponent<TProps = unknown> {\n  (props: TProps): ElurTemplate | null | false | undefined;\n}\n\n/**\n * Options for {@link island}.\n *\n * - `ssr`: Whether to execute the component on the server. Defaults to `true`\n *   unless `directive === \"only\"` (then `false`). When `false`, the component\n *   is never called during SSR; only `fallback` is rendered.\n * - `fallback`: HTML to render inside the island marker when SSR is skipped or\n *   the component returns null/false. Accepts a `ElurTemplate` (reactive, with\n *   signals) or a plain string. Defaults to an empty string.\n */\nexport interface IslandOptions {\n  ssr?: boolean;\n  fallback?: ElurTemplate | string;\n}\n\n/**\n * Renders a component to a static HTML string with island markers.\n *\n * @param name Unique island name used by the client entry to look up the module.\n * @param component Island component. Executed on the server unless `directive`\n *   is `\"only\"` or `options.ssr` is `false`.\n * @param props Props passed to the component and serialized for hydration.\n * @param directive When to hydrate on the client. Use `\"only\"` to skip SSR\n *   entirely (client-only island).\n * @param options SSR strategy and fallback content.\n * @returns A ElurTemplate that renders the island placeholder.\n */\nexport function island<TProps>(\n  name: string,\n  component: IslandComponent<TProps>,\n  props: TProps,\n  directive: IslandDirective = \"load\",\n  options?: IslandOptions,\n): ElurTemplate {\n  // `directive: \"only\"` forces ssr off; explicit `options.ssr` wins otherwise.\n  const ssr = directive === \"only\" ? false : (options?.ssr ?? true);\n  const fallback = options?.fallback;\n\n  const markerHtml = (innerHtml: string) =>\n    `<div ${ISLAND_MARKER_ATTR}=\"${escapeHtml(name)}\" data-directive=\"${directive}\" data-props='${serializeProps(props)}'>${innerHtml}</div>`;\n\n  return {\n    __isElurTemplate: true as const,\n    [ELUR_RENDER_PROTOCOL]: {\n      async renderServer(context: ServerRenderProtocolContext) {\n        let innerHtml = \"\";\n        if (ssr) {\n          try {\n            const template = component(props);\n            if (template !== null && template !== false && template !== undefined) {\n              innerHtml = await context.render(template, { markers: true });\n            } else {\n              // Component returned null/false/undefined — render fallback if any.\n              innerHtml = await renderFallback(fallback, context);\n            }\n          } catch (error) {\n            throw wrapIslandSSRError(name, error);\n          }\n        } else {\n          innerHtml = await renderFallback(fallback, context);\n        }\n        return markerHtml(innerHtml);\n      },\n    },\n    _render(parent: Node, before: Node | null): () => void {\n      const container = document.createElement(\"div\");\n      let innerHtml = \"\";\n      if (ssr) {\n        const template = component(props);\n        if (template !== null && template !== false && template !== undefined) {\n          const dispose = template._render(container, null);\n          innerHtml = container.innerHTML;\n          dispose();\n        } else {\n          // null/false/undefined — render fallback if any.\n          innerHtml = renderFallbackSync(fallback, container);\n        }\n      } else {\n        innerHtml = renderFallbackSync(fallback, container);\n      }\n      const wrapper = document.createElement(\"template\");\n      wrapper.innerHTML = markerHtml(innerHtml);\n      const fragment = wrapper.content;\n      const inserted = fragment.firstChild;\n      parent.insertBefore(fragment, before);\n      return () => {\n        if (inserted?.parentNode) inserted.parentNode.removeChild(inserted);\n      };\n    },\n  } as unknown as ElurTemplate;\n}\n\n/**\n * Wraps an SSR error from an island component with an actionable message.\n *\n * Following the Astro/Next.js convention, SSR errors are never silently\n * swallowed — they propagate so real bugs surface. The wrapper adds the island\n * name and three concrete remediation paths.\n */\nfunction wrapIslandSSRError(name: string, error: unknown): Error {\n  const cause = error instanceof Error ? error : new Error(String(error));\n  const msg = error instanceof Error ? error.message : String(error);\n  return new Error(\n    `[elur-kit] Island \"${name}\" threw during SSR: ${msg}\\n` +\n    `  If the component accesses browser-only globals (document, window, etc.),\\n` +\n    `  use directive: \"only\" or options: { ssr: false } to skip server rendering.\\n` +\n    `  For environment reads (matchMedia, localStorage, navigator) you may guard\\n` +\n    `  the access with isSSR() from \"@elurjs/kit\".`,\n    { cause },\n  );\n}\n\n/** Renders the fallback (ElurTemplate or string) to an HTML string on the server. */\nasync function renderFallback(\n  fallback: ElurTemplate | string | undefined,\n  context: ServerRenderProtocolContext,\n): Promise<string> {\n  if (fallback == null || fallback === \"\") return \"\";\n  if (typeof fallback === \"string\") return fallback;\n  return context.render(fallback, { markers: false });\n}\n\n/** Renders the fallback into a container and returns its innerHTML (client path). */\nfunction renderFallbackSync(fallback: ElurTemplate | string | undefined, container: HTMLElement): string {\n  if (fallback == null || fallback === \"\") return \"\";\n  if (typeof fallback === \"string\") return fallback;\n  const dispose = fallback._render(container, null);\n  const html = container.innerHTML;\n  dispose();\n  return html;\n}\n\nfunction escapeHtml(value: string): string {\n  return value\n    .replace(/&/g, \"&amp;\")\n    .replace(/</g, \"&lt;\")\n    .replace(/>/g, \"&gt;\")\n    .replace(/\"/g, \"&quot;\")\n    .replace(/'/g, \"&#39;\");\n}\n\nfunction serializeProps(props: unknown): string {\n  return JSON.stringify(props ?? null)\n    .replace(/</g, \"\\\\u003c\")\n    .replace(/'/g, \"\\\\u0027\");\n}\n"],"mappings":"8BAmCA,IAAa,EAAqB,mBASrB,EAAe,oBAiC5B,SAAgB,EACd,EACA,EACA,EACA,EAA6B,OAC7B,EACc,CAEd,IAAM,EAAM,IAAc,OAAS,GAAS,GAAS,KAAO,GACtD,EAAW,GAAS,SAEpB,EAAc,GAClB,QAAQ,EAAmB,IAAI,EAAW,CAAI,EAAE,oBAAoB,EAAU,gBAAgB,EAAe,CAAK,EAAE,IAAI,EAAU,QAEpI,MAAO,CACL,iBAAkB,IACjB,EAAA,sBAAuB,CACtB,MAAM,aAAa,EAAsC,CACvD,IAAI,EAAY,GAChB,GAAI,EACF,GAAI,CACF,IAAM,EAAW,EAAU,CAAK,EAChC,AAIE,EAJE,IAAa,MAAQ,IAAa,IAAS,IAAa,IAAA,GAC9C,MAAM,EAAQ,OAAO,EAAU,CAAE,QAAS,EAAK,CAAC,EAGhD,MAAM,EAAe,EAAU,CAAO,CAEtD,OAAS,EAAO,CACd,MAAM,EAAmB,EAAM,CAAK,CACtC,KAEA,GAAY,MAAM,EAAe,EAAU,CAAO,EAEpD,OAAO,EAAW,CAAS,CAC7B,CACF,EACA,QAAQ,EAAc,EAAiC,CACrD,IAAM,EAAY,SAAS,cAAc,KAAK,EAC1C,EAAY,GAChB,GAAI,EAAK,CACP,IAAM,EAAW,EAAU,CAAK,EAChC,GAAI,IAAa,MAAQ,IAAa,IAAS,IAAa,IAAA,GAAW,CACrE,IAAM,EAAU,EAAS,QAAQ,EAAW,IAAI,EAChD,EAAY,EAAU,UACtB,EAAQ,CACV,KAEE,GAAY,EAAmB,EAAU,CAAS,CAEtD,KACE,GAAY,EAAmB,EAAU,CAAS,EAEpD,IAAM,EAAU,SAAS,cAAc,UAAU,EACjD,EAAQ,UAAY,EAAW,CAAS,EACxC,IAAM,EAAW,EAAQ,QACnB,EAAW,EAAS,WAE1B,OADA,EAAO,aAAa,EAAU,CAAM,MACvB,CACP,GAAU,YAAY,EAAS,WAAW,YAAY,CAAQ,CACpE,CACF,CACF,CACF,CASA,SAAS,EAAmB,EAAc,EAAuB,CAC/D,IAAM,EAAQ,aAAiB,MAAQ,EAAY,MAAM,OAAO,CAAK,CAAC,EAChE,EAAM,aAAiB,MAAQ,EAAM,QAAU,OAAO,CAAK,EACjE,OAAW,MACT,sBAAsB,EAAK,sBAAsB,EAAI,wRAKrD,CAAE,OAAM,CACV,CACF,CAGA,eAAe,EACb,EACA,EACiB,CAGjB,OAFI,GAAY,MAAQ,IAAa,GAAW,GAC5C,OAAO,GAAa,SAAiB,EAClC,EAAQ,OAAO,EAAU,CAAE,QAAS,EAAM,CAAC,CACpD,CAGA,SAAS,EAAmB,EAA6C,EAAgC,CACvG,GAAI,GAAY,MAAQ,IAAa,GAAI,MAAO,GAChD,GAAI,OAAO,GAAa,SAAU,OAAO,EACzC,IAAM,EAAU,EAAS,QAAQ,EAAW,IAAI,EAC1C,EAAO,EAAU,UAEvB,OADA,EAAQ,EACD,CACT,CAEA,SAAS,EAAW,EAAuB,CACzC,OAAO,EACJ,QAAQ,KAAM,OAAO,CAAC,CACtB,QAAQ,KAAM,MAAM,CAAC,CACrB,QAAQ,KAAM,MAAM,CAAC,CACrB,QAAQ,KAAM,QAAQ,CAAC,CACvB,QAAQ,KAAM,OAAO,CAC1B,CAEA,SAAS,EAAe,EAAwB,CAC9C,OAAO,KAAK,UAAU,GAAS,IAAI,CAAC,CACjC,QAAQ,KAAM,SAAS,CAAC,CACxB,QAAQ,KAAM,SAAS,CAC5B"}