ilha 0.2.1 → 0.3.0

package/README.md

@@ -289,23 +289,51 @@ ilha.css(styles).render(() => `<div class="card">…</div>`);
 
 ---
 
-### `.slot(name, island)`
+### Composing Islands
 
-Embeds a child island as a named slot. The child island is mounted and managed independently. During SSR the slot renders the child's HTML inline; during client mount the child island is activated for interactivity.
+Child islands are interpolated directly inside a parent's html&grave;&grave; template. During SSR the child's HTML is rendered inline; during client mount the child is activated independently inside its own host element.
 
 ```ts
 const Icon = ilha.render(() => `<svg>…</svg>`);
 
-const Card = ilha.slot("icon", Icon).render(
-  ({ slots }) => html`
+const Card = ilha.render(
+  () => html`
     <div class="card">
-      ${slots.icon()}
+      ${Icon}
       <p>Card content</p>
     </div>
   `,
 );
 ```
 
+**Passing props** — call the child island with a props object:
+
+```ts
+const Badge = ilha
+  .input(z.object({ label: z.string(), color: z.string().default("teal") }))
+  .render(({ input }) => html`<span style="background:${input.color}">${input.label}</span>`);
+
+const Card = ilha.render(
+  () => html`
+    <div>
+      ${Badge({ label: "New", color: "coral" })}
+      <p>Content</p>
+    </div>
+  `,
+);
+```
+
+**Keyed children** — use `.key()` when a child may reorder or appear conditionally. Keys must be unique within a parent render:
+
+```ts
+const List = ilha.render(
+  () =>
+    html`<ul>
+      ${items.map((item) => html`<li>${Item.key(item.id)({ name: item.name })}</li>`)}
+    </ul>`,
+);
+```
+
 ---
 
 ### `.transition(opts)`
@@ -331,7 +359,7 @@ The `leave` transition is awaited before cleanup runs.
 
 ### `.render(fn)`
 
-Finalises the builder and returns an `Island`. The render function receives `{ state, derived, input, slots }` and must return a string or `RawHtml`.
+Finalises the builder and returns an `Island`. The render function receives `{ state, derived, input }` and must return a string or `RawHtml`.
 
 ```ts
 const MyIsland = ilha.state("x", 1).render(({ state, input }) => html`<p>${state.x}</p>`);
@@ -471,6 +499,7 @@ Interpolation rules:
 | `raw(str)`           | Inserted as-is (no escaping)                |
 | `html\`…\``          | Inserted as-is (already safe)               |
 | Signal accessor      | Called and escaped                          |
+| Island / Island call | Emitted as `data-ilha-slot` host element    |
 | Array                | Each item processed recursively (no commas) |
 
 **List rendering pattern:**
@@ -581,7 +610,7 @@ import type {
   IslandState,
   IslandDerived,
   DerivedValue,
-  SlotAccessor,
+  KeyedIsland,
   HydratableOptions,
   OnMountContext,
   HandlerContext,

package/dist/index.d.ts

@@ -31,16 +31,18 @@ declare namespace StandardSchemaV1 {
   type InferOutput<Schema extends StandardSchemaV1> = NonNullable<Schema["~standard"]["types"]>["output"];
 }
 declare const RAW: unique symbol;
-declare const SLOT_ACCESSOR: unique symbol;
 declare const SIGNAL_ACCESSOR: unique symbol;
+declare const ISLAND: unique symbol;
+declare const ISLAND_CALL: unique symbol;
 interface RawHtml {
   [RAW]: true;
   value: string;
 }
-interface SlotAccessor<TProps = Record<string, unknown>> {
-  (props?: TProps): RawHtml;
-  toString(): string;
-  [SLOT_ACCESSOR]: true;
+interface IslandCall {
+  [ISLAND_CALL]: true;
+  island: AnyIsland;
+  props: Record<string, unknown> | undefined;
+  key: string | undefined;
 }
 interface MarkedSignalAccessor<T> {
   (): T;
@@ -96,16 +98,18 @@ interface Island<TInput = Record<string, unknown>, _TStateMap extends Record<str
   toString(props?: Partial<TInput>): string;
   mount(host: Element, props?: Partial<TInput>): () => void;
   hydratable(props: Partial<TInput>, options: HydratableOptions): Promise<string>;
+  key(key: string): KeyedIsland<TInput>;
+  [ISLAND]: true;
+}
+interface KeyedIsland<TInput> {
+  (props?: Partial<TInput>): IslandCall;
+  [ISLAND_CALL]: true;
 }
-type InferIslandInput<T> = T extends Island<infer TInput, any> ? TInput : Record<string, unknown>;
 type AnyIsland = Island<any, any>;
-type SlotMap = Record<string, AnyIsland>;
-type SlotsProxy<TSlots extends SlotMap> = { readonly [K in keyof TSlots]: SlotAccessor<Partial<InferIslandInput<TSlots[K]>>> };
-type RenderContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>, TSlots extends SlotMap> = {
+type RenderContext<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>> = {
   state: IslandState<TStateMap>;
   derived: IslandDerived<TDerivedMap>;
   input: TInput;
-  slots: SlotsProxy<TSlots>;
 };
 type EffectContext<TInput, TStateMap extends Record<string, unknown>> = {
   state: IslandState<TStateMap>;
@@ -167,40 +171,38 @@ interface MountOptions {
 interface MountResult {
   unmount: () => void;
 }
-interface BuilderConfig<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>, _TSlots extends SlotMap> {
+interface BuilderConfig<TInput, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown>> {
   schema: StandardSchemaV1 | null;
   states: StateEntry<TInput>[];
   deriveds: DerivedEntry<TInput, TStateMap>[];
   ons: OnEntry<TInput, TStateMap, TDerivedMap>[];
   effects: EffectEntry<TInput, TStateMap>[];
   onMounts: OnMountEntry<TInput, TStateMap, TDerivedMap>[];
-  slots: Record<string, AnyIsland>;
   transition: TransitionOptions | null;
   binds: BindEntry<TStateMap>[];
   css: string | null;
 }
-declare class IlhaBuilder<TInput extends Record<string, unknown>, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<string, never>, TSlots extends SlotMap = Record<string, never>> {
-  readonly _cfg: BuilderConfig<TInput, TStateMap, TDerivedMap, TSlots>;
-  constructor(cfg: BuilderConfig<TInput, TStateMap, TDerivedMap, TSlots>);
-  input<T extends Record<string, unknown>>(): IlhaBuilder<T, Record<string, never>, Record<string, never>, Record<string, never>>;
-  input<S extends StandardSchemaV1>(schema: S): IlhaBuilder<StandardSchemaV1.InferOutput<S> & Record<string, unknown>, Record<string, never>, Record<string, never>, Record<string, never>>;
-  state<V = undefined, K extends string = string>(key: K, init?: StateInit<TInput, V> | undefined): IlhaBuilder<TInput, MergeState<TStateMap, K, V>, TDerivedMap, TSlots>;
-  derived<K extends string, V>(key: K, fn: DerivedFn<TInput, TStateMap, V>): IlhaBuilder<TInput, TStateMap, TDerivedMap & Record<K, V>, TSlots>;
-  bind(selector: string, stateKey: keyof TStateMap & string): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
-  bind<T>(selector: string, externalSignal: ExternalSignal<T>): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
-  on<S extends OnSelectorString>(selectorOrCombined: S, handler: (ctx: S extends `${string}@${infer E}:${string}` ? HandlerContextFor<TInput, TStateMap, E, TDerivedMap> : S extends `${string}@${infer E}` ? HandlerContextFor<TInput, TStateMap, E, TDerivedMap> : HandlerContext<TInput, TStateMap, TDerivedMap>) => void | Promise<void>): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
-  on(selectorOrCombined: string, handler: (ctx: HandlerContext<TInput, TStateMap, TDerivedMap>) => void | Promise<void>): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
-  effect(fn: (ctx: EffectContext<TInput, TStateMap>) => (() => void) | void): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
-  onMount(fn: (ctx: OnMountContext<TInput, TStateMap, TDerivedMap>) => (() => void) | void): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
-  slot<K extends string, I extends AnyIsland>(name: K, island: I): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots & Record<K, I>>;
-  transition(opts: TransitionOptions): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
-  css(strings: TemplateStringsArray | string, ...values: (string | number)[]): IlhaBuilder<TInput, TStateMap, TDerivedMap, TSlots>;
-  render(fn: (ctx: RenderContext<TInput, TStateMap, TDerivedMap, TSlots>) => string | RawHtml): Island<TInput, TStateMap>;
+declare class IlhaBuilder<TInput extends Record<string, unknown>, TStateMap extends Record<string, unknown>, TDerivedMap extends Record<string, unknown> = Record<string, never>> {
+  readonly _cfg: BuilderConfig<TInput, TStateMap, TDerivedMap>;
+  constructor(cfg: BuilderConfig<TInput, TStateMap, TDerivedMap>);
+  input<T extends Record<string, unknown>>(): IlhaBuilder<T, Record<string, never>, Record<string, never>>;
+  input<S extends StandardSchemaV1>(schema: S): IlhaBuilder<StandardSchemaV1.InferOutput<S> & Record<string, unknown>, Record<string, never>, Record<string, never>>;
+  state<V = undefined, K extends string = string>(key: K, init?: StateInit<TInput, V> | undefined): IlhaBuilder<TInput, MergeState<TStateMap, K, V>, TDerivedMap>;
+  derived<K extends string, V>(key: K, fn: DerivedFn<TInput, TStateMap, V>): IlhaBuilder<TInput, TStateMap, TDerivedMap & Record<K, V>>;
+  bind(selector: string, stateKey: keyof TStateMap & string): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
+  bind<T>(selector: string, externalSignal: ExternalSignal<T>): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
+  on<S extends OnSelectorString>(selectorOrCombined: S, handler: (ctx: S extends `${string}@${infer E}:${string}` ? HandlerContextFor<TInput, TStateMap, E, TDerivedMap> : S extends `${string}@${infer E}` ? HandlerContextFor<TInput, TStateMap, E, TDerivedMap> : HandlerContext<TInput, TStateMap, TDerivedMap>) => void | Promise<void>): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
+  on(selectorOrCombined: string, handler: (ctx: HandlerContext<TInput, TStateMap, TDerivedMap>) => void | Promise<void>): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
+  effect(fn: (ctx: EffectContext<TInput, TStateMap>) => (() => void) | void): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
+  onMount(fn: (ctx: OnMountContext<TInput, TStateMap, TDerivedMap>) => (() => void) | void): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
+  transition(opts: TransitionOptions): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
+  css(strings: TemplateStringsArray | string, ...values: (string | number)[]): IlhaBuilder<TInput, TStateMap, TDerivedMap>;
+  render(fn: (ctx: RenderContext<TInput, TStateMap, TDerivedMap>) => string | RawHtml): Island<TInput, TStateMap>;
 }
 declare function ilhaFrom<TInput, TStateMap extends Record<string, unknown>>(selector: string | Element, island: Island<TInput, TStateMap>, props?: Partial<TInput>): (() => void) | null;
 type IslandRegistry = Record<string, AnyIsland>;
 declare function mountAll(registry: IslandRegistry, options?: MountOptions): MountResult;
-declare const ilha: IlhaBuilder<Record<string, unknown>, Record<string, never>, Record<string, never>, Record<string, never>> & {
+declare const ilha: IlhaBuilder<Record<string, unknown>, Record<string, never>, Record<string, never>> & {
   html: typeof ilhaHtml;
   raw: typeof ilhaRaw;
   mount: typeof mountAll;
@@ -214,4 +216,4 @@ declare const mount: typeof mountAll;
 declare const from: typeof ilhaFrom;
 declare const context: typeof ilhaContext;
 //#endregion
-export { DerivedValue, HandlerContext, HandlerContextFor, HydratableOptions, Island, IslandDerived, IslandState, MountOptions, MountResult, OnMountContext, RawHtml, SignalAccessor, SlotAccessor, context, css, ilha as default, from, html, mount, raw };
+export { DerivedValue, HandlerContext, HandlerContextFor, HydratableOptions, Island, IslandDerived, IslandState, KeyedIsland, MountOptions, MountResult, OnMountContext, RawHtml, SignalAccessor, context, css, ilha as default, from, html, mount, raw };

package/dist/index.js

@@ -77,8 +77,9 @@ function dedentString(str) {
 	return lines.map((l) => l.slice(indent)).join("\n");
 }
 const RAW = Symbol("ilha.raw");
-const SLOT_ACCESSOR = Symbol("ilha.slotAccessor");
 const SIGNAL_ACCESSOR = Symbol("ilha.signalAccessor");
+const ISLAND = Symbol("ilha.island");
+const ISLAND_CALL = Symbol("ilha.islandCall");
 const SLOT_ATTR = "data-ilha-slot";
 const PROPS_ATTR = "data-ilha-props";
 const STATE_ATTR = "data-ilha-state";
@@ -86,17 +87,70 @@ const CSS_ATTR = "data-ilha-css";
 function buildScopedStyle(css) {
 	return `<style ${CSS_ATTR}>@scope (:scope) to ([data-ilha]){${css}}</style>`;
 }
-function makeSlotAccessor(render) {
-	const fn = (props) => ({
-		[RAW]: true,
-		value: render(props)
+const renderCtxStack = [];
+function pushRenderCtx(liveHost, asyncChildren) {
+	const ctx = {
+		slots: /* @__PURE__ */ new Map(),
+		positional: 0,
+		liveHost,
+		pending: asyncChildren ? /* @__PURE__ */ new Map() : void 0
+	};
+	renderCtxStack.push(ctx);
+	return ctx;
+}
+function popRenderCtx() {
+	renderCtxStack.pop();
+}
+function currentRenderCtx() {
+	return renderCtxStack[renderCtxStack.length - 1];
+}
+function isIsland(v) {
+	return typeof v === "function" && ISLAND in v;
+}
+function isIslandCall(v) {
+	return (typeof v === "object" || typeof v === "function") && v !== null && ISLAND_CALL in v;
+}
+function emitIslandSlot(island, props, key) {
+	const ctx = currentRenderCtx();
+	let id;
+	if (key !== void 0) {
+		id = `k:${key}`;
+		if (ctx && __DEV__ && ctx.slots.has(id)) warn(`Duplicate slot key "${key}" — two children with the same key in a single render will collide. Each .key() call must be unique.`);
+	} else id = ctx ? `p:${ctx.positional++}` : "p:0";
+	if (ctx) ctx.slots.set(id, {
+		island,
+		props
 	});
-	fn.toString = () => render(void 0);
-	fn[SLOT_ACCESSOR] = true;
-	return fn;
+	const propsAttr = props ? ` ${PROPS_ATTR}='${escapeHtml(JSON.stringify(props))}'` : "";
+	if (ctx?.liveHost) return `<div ${SLOT_ATTR}="${escapeHtml(id)}"${propsAttr}></div>`;
+	if (ctx?.pending) {
+		popRenderCtx();
+		try {
+			const result = island(props);
+			if (result instanceof Promise) {
+				ctx.pending.set(id, result.then(String));
+				return `<div ${SLOT_ATTR}="${escapeHtml(id)}"${propsAttr}></div>`;
+			}
+			return `<div ${SLOT_ATTR}="${escapeHtml(id)}"${propsAttr}>${result}</div>`;
+		} finally {
+			renderCtxStack.push(ctx);
+		}
+	}
+	const inner = island.toString(props);
+	return `<div ${SLOT_ATTR}="${escapeHtml(id)}"${propsAttr}>${inner}</div>`;
 }
-function isSlotAccessor(v) {
-	return typeof v === "function" && SLOT_ACCESSOR in v;
+async function resolveAsyncChildren(html, ctx) {
+	for (const [id, promise] of ctx.pending) {
+		const inner = await promise;
+		const escaped = escapeHtml(id);
+		if (escaped.length > 500) throw new Error(`Slot id exceeds safe length for regex replacement (${escaped.length} > 500).`);
+		const attrPattern = escaped.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+		const placeholder = new RegExp(`<div\\s[^>]*${SLOT_ATTR}="${attrPattern}"[^>]*></div>`, "g");
+		html = html.replace(placeholder, (match) => {
+			return match.slice(0, -6) + `>${inner}</div>`;
+		});
+	}
+	return html;
 }
 function markSignalAccessor(fn) {
 	fn[SIGNAL_ACCESSOR] = true;
@@ -124,7 +178,11 @@ function interpolateValue(v) {
 	if (v == null) return "";
 	if (Array.isArray(v)) return v.map(interpolateValue).join("");
 	if (typeof v === "object" && RAW in v) return v.value;
-	if (isSlotAccessor(v)) return v.toString();
+	if (isIslandCall(v)) {
+		const call = typeof v === "function" ? v() : v;
+		return emitIslandSlot(call.island, call.props, call.key);
+	}
+	if (isIsland(v)) return emitIslandSlot(v, void 0, void 0);
 	if (isSignalAccessor(v)) return escapeHtml(v());
 	if (typeof v === "function") return escapeHtml(v());
 	return escapeHtml(v);
@@ -321,7 +379,6 @@ var IlhaBuilder = class IlhaBuilder {
 			ons: [],
 			effects: [],
 			onMounts: [],
-			slots: {},
 			transition: null,
 			binds: [],
 			css: null
@@ -380,15 +437,6 @@ var IlhaBuilder = class IlhaBuilder {
 			onMounts: [...this._cfg.onMounts, { fn }]
 		});
 	}
-	slot(name, island) {
-		return new IlhaBuilder({
-			...this._cfg,
-			slots: {
-				...this._cfg.slots,
-				[name]: island
-			}
-		});
-	}
 	transition(opts) {
 		return new IlhaBuilder({
 			...this._cfg,
@@ -413,28 +461,38 @@ var IlhaBuilder = class IlhaBuilder {
 		});
 	}
 	render(fn) {
-		const { schema, states, deriveds, ons, effects, onMounts, slots: slotDefs, transition, binds, css: cssSource } = this._cfg;
+		const { schema, states, deriveds, ons, effects, onMounts, transition, binds, css: cssSource } = this._cfg;
 		const stylePrefix = cssSource != null ? buildScopedStyle(cssSource) : "";
 		function resolveInput(props) {
 			const value = props ?? {};
 			if (!schema) return value;
 			return validateSchema(schema, value);
 		}
-		function makeSlotsProxy(ssr, host) {
-			return new Proxy({}, { get(_, prop) {
-				const name = String(prop);
-				if (!slotDefs[name]) return makeSlotAccessor(() => "");
-				if (ssr) return makeSlotAccessor((props) => {
-					const json = props ? ` ${PROPS_ATTR}='${escapeHtml(JSON.stringify(props))}'` : "";
-					return `<div ${SLOT_ATTR}="${escapeHtml(name)}"${json}>${slotDefs[name].toString(props)}</div>`;
-				});
-				return makeSlotAccessor((props) => {
-					const liveSlot = host?.querySelector(`[${SLOT_ATTR}="${escapeHtml(name)}"]`);
-					if (liveSlot) return liveSlot.outerHTML;
-					const json = props ? ` ${PROPS_ATTR}='${escapeHtml(JSON.stringify(props))}'` : "";
-					return `<div ${SLOT_ATTR}="${escapeHtml(name)}"${json}></div>`;
-				});
-			} });
+		function renderWithCtx(fn, liveHost, asyncChildren) {
+			const ctx = pushRenderCtx(liveHost, asyncChildren);
+			let isAsync = false;
+			try {
+				const html = unwrapHtml(fn());
+				if (ctx.pending && ctx.pending.size > 0) {
+					isAsync = true;
+					return (async () => {
+						try {
+							return {
+								html: await resolveAsyncChildren(html, ctx),
+								slots: ctx.slots
+							};
+						} finally {
+							popRenderCtx();
+						}
+					})();
+				}
+				return {
+					html,
+					slots: ctx.slots
+				};
+			} finally {
+				if (!isAsync) popRenderCtx();
+			}
 		}
 		function buildPlainState(input) {
 			const state = {};
@@ -462,7 +520,6 @@ var IlhaBuilder = class IlhaBuilder {
 		function renderToString(props, sync = false) {
 			const input = resolveInput(props);
 			const state = buildPlainState(input);
-			const slots = makeSlotsProxy(true);
 			const results = deriveds.map((entry) => {
 				try {
 					return {
@@ -492,12 +549,12 @@ var IlhaBuilder = class IlhaBuilder {
 					value: r.result,
 					error: void 0
 				};
-				return stylePrefix + unwrapHtml(fn({
+				const { html } = renderWithCtx(() => fn({
 					state,
 					derived,
-					input,
-					slots
+					input
 				}));
+				return stylePrefix + html;
 			}
 			return Promise.all(results.map(async (r) => {
 				try {
@@ -519,15 +576,15 @@ var IlhaBuilder = class IlhaBuilder {
 						}
 					};
 				}
-			})).then((resolved) => {
+			})).then(async (resolved) => {
 				const derived = {};
 				for (const r of resolved) derived[r.key] = r.envelope;
-				return stylePrefix + unwrapHtml(fn({
+				const { html } = await renderWithCtx(() => fn({
 					state,
 					derived,
-					input,
-					slots
-				}));
+					input
+				}), void 0, true);
+				return stylePrefix + html;
 			});
 		}
 		function mountIsland(host, props) {
@@ -576,28 +633,49 @@ Element: ${host.outerHTML.slice(0, 120)}`);
 			}
 			const { proxy: derived, stop: stopDerived } = buildDerivedSignals(deriveds, state, input, derivedSnapshot);
 			cleanups.push(stopDerived);
-			const slotCleanups = /* @__PURE__ */ new Map();
-			const slotEls = /* @__PURE__ */ new Map();
-			function mountSlots() {
-				for (const [name, childIsland] of Object.entries(slotDefs)) {
-					const slotEl = host.querySelector(`[${SLOT_ATTR}="${name}"]`);
+			const mountedSlots = /* @__PURE__ */ new Map();
+			function findSlot(id) {
+				const escaped = typeof CSS !== "undefined" && CSS.escape ? CSS.escape(id) : id.replace(/["\\]/g, "\\$&");
+				const candidates = host.querySelectorAll(`[${SLOT_ATTR}="${escaped}"]`);
+				for (const candidate of candidates) {
+					let el = candidate;
+					while (el && el !== host) {
+						if (el.hasAttribute("data-ilha")) break;
+						el = el.parentElement;
+					}
+					if (el === host) return candidate;
+				}
+				return null;
+			}
+			function mountSlots(slotMap) {
+				for (const [id, entry] of mountedSlots) if (!slotMap.has(id)) {
+					entry.unmount();
+					mountedSlots.delete(id);
+				}
+				for (const [id, { island: childIsland, props }] of slotMap) {
+					if (mountedSlots.has(id)) continue;
+					const slotEl = findSlot(id);
 					if (!slotEl) continue;
-					if (slotEls.get(name) === slotEl) continue;
-					slotEls.set(name, slotEl);
-					slotCleanups.get(name)?.();
-					let slotProps;
-					const rawProps = slotEl.getAttribute(PROPS_ATTR) ?? slotEl.getAttribute("data-props");
-					if (rawProps) try {
-						slotProps = JSON.parse(rawProps);
-					} catch {
-						warn(`Failed to parse props on [${SLOT_ATTR}="${name}"] — invalid JSON ignored.`);
+					let slotProps = props;
+					if (slotProps === void 0) {
+						const rawProps = slotEl.getAttribute(PROPS_ATTR) ?? slotEl.getAttribute("data-props");
+						if (rawProps) try {
+							slotProps = JSON.parse(rawProps);
+						} catch {
+							warn(`Failed to parse props on [${SLOT_ATTR}="${id}"] — invalid JSON ignored.`);
+						}
 					}
 					const prevSub = setActiveSub(void 0);
+					let unmount;
 					try {
-						slotCleanups.set(name, childIsland.mount(slotEl, slotProps));
+						unmount = childIsland.mount(slotEl, slotProps);
 					} finally {
 						setActiveSub(prevSub);
 					}
+					mountedSlots.set(id, {
+						el: slotEl,
+						unmount
+					});
 				}
 			}
 			const listeners = [];
@@ -644,18 +722,18 @@ Element: ${host.outerHTML.slice(0, 120)}`);
 				for (const l of listeners) l.target.removeEventListener(l.type, l.fn, l.options);
 				listeners.length = 0;
 			}
-			const slots = makeSlotsProxy(false, host);
-			if (!(hydrated && host.childNodes.length > 0)) host.innerHTML = stylePrefix + unwrapHtml(fn({
+			const hasExistingContent = hydrated && host.childNodes.length > 0;
+			const initial = renderWithCtx(() => fn({
 				state,
 				derived,
-				input,
-				slots
-			}));
+				input
+			}), hasExistingContent ? host : void 0);
+			if (!hasExistingContent) host.innerHTML = stylePrefix + initial.html;
 			attachListeners();
 			let stopBindings = applyBindings(host, binds, state);
 			cleanups.push(() => stopBindings());
-			mountSlots();
-			cleanups.push(() => slotCleanups.forEach((unmount) => unmount()));
+			mountSlots(initial.slots);
+			cleanups.push(() => mountedSlots.forEach((entry) => entry.unmount()));
 			if (!shouldSkipOnMount) for (const entry of onMounts) {
 				const prevSub = setActiveSub(void 0);
 				let userCleanup;
@@ -674,24 +752,42 @@ Element: ${host.outerHTML.slice(0, 120)}`);
 			}
 			let initialized = false;
 			const stopRender = effect(() => {
-				const html = stylePrefix + unwrapHtml(fn({
+				const { html: rendered, slots: newSlotMap } = renderWithCtx(() => fn({
 					state,
 					derived,
-					input,
-					slots
-				}));
+					input
+				}), host);
+				const html = stylePrefix + rendered;
 				if (!initialized) {
 					initialized = true;
 					return;
 				}
 				detachListeners();
 				stopBindings();
+				for (const [id, entry] of mountedSlots) if (!newSlotMap.has(id)) {
+					entry.unmount();
+					mountedSlots.delete(id);
+				}
+				const preserved = /* @__PURE__ */ new Map();
+				for (const [id, entry] of mountedSlots) {
+					if (!newSlotMap.has(id)) continue;
+					if (!entry.el.isConnected) continue;
+					const stub = document.createElement("div");
+					stub.setAttribute(SLOT_ATTR, id);
+					entry.el.replaceWith(stub);
+					preserved.set(id, entry.el);
+				}
 				const tpl = document.createElement("template");
 				tpl.innerHTML = `<div>${html}</div>`;
 				morphInner(host, tpl.content.firstElementChild);
+				for (const [id, liveEl] of preserved) {
+					const stub = findSlot(id);
+					if (!stub) continue;
+					stub.replaceWith(liveEl);
+				}
 				attachListeners();
 				stopBindings = applyBindings(host, binds, state);
-				mountSlots();
+				mountSlots(newSlotMap);
 			});
 			cleanups.push(stopRender);
 			cleanups.push(detachListeners);
@@ -728,11 +824,41 @@ Element: ${host.outerHTML.slice(0, 120)}`);
 				cleanups.forEach((c) => c());
 			};
 		}
+		/**
+		* Dual-mode island invocation:
+		* - When called inside an `html` interpolation (i.e. {@link currentRenderCtx}
+		*   is active), returns an {@link IslandCall} carrying props to be emitted
+		*   as a child slot marker; {@link interpolateValue} consumes this marker.
+		* - When called at the top level with no active render context, returns
+		*   SSR HTML via {@link renderToString} (backward-compatible public API).
+		*
+		* The declared return type omits {@link IslandCall} because TypeScript
+		* cannot narrow based on runtime stack state.
+		*/
 		const island = function(props) {
+			if (currentRenderCtx()) return {
+				[ISLAND_CALL]: true,
+				island,
+				props,
+				key: void 0
+			};
 			return renderToString(props);
 		};
 		island.toString = (props) => renderToString(props, true);
 		island.mount = (host, props) => mountIsland(host, props);
+		island.key = (key) => {
+			if (typeof key !== "string" || key.trim().length === 0) throw new Error("island.key() requires a non-empty string.");
+			if (key.includes(":")) throw new Error(`island.key() key cannot contain the slot separator ":" (got "${key}").`);
+			const keyed = ((props) => ({
+				[ISLAND_CALL]: true,
+				island,
+				props,
+				key
+			}));
+			keyed[ISLAND_CALL] = true;
+			return keyed;
+		};
+		island[ISLAND] = true;
 		island.hydratable = async (props, opts) => {
 			const { name, as: tag = "div", snapshot = false, skipOnMount: explicitSkipOnMount } = opts;
 			const resolvedProps = props ?? {};
@@ -831,7 +957,6 @@ const rootBuilder = new IlhaBuilder({
 	ons: [],
 	effects: [],
 	onMounts: [],
-	slots: {},
 	transition: null,
 	binds: [],
 	css: null

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ilha",
-  "version": "0.2.1",
+  "version": "0.3.0",
   "description": "A tiny, framework-free island architecture library",
   "license": "MIT",
   "author": "Ryuz <ryuzer@proton.me>",