feat(router): add defineLayout helper (#10)

* feat(router): add defineLayout helper

* chore(router): update readme (exports)

Author: yzuyr

packages/router/README.md

@@ -321,6 +321,32 @@ const wrapped = wrapLayout(myLayout, myPage);
 
 ---
 
+### `defineLayout(fn)`
+
+A typed helper that returns the layout function as-is. Use it instead of the `satisfies LayoutHandler` cast for a cleaner, import-light syntax.
+
+```ts
+// src/pages/+layout.ts
+import { defineLayout } from "@ilha/router";
+import ilha, { html } from "ilha";
+
+export default defineLayout((children) =>
+  ilha.render(
+    () => html`
+      <nav>
+        <a href="/">Home</a>
+        <a href="/about">About</a>
+      </nav>
+      <main>${children}</main>
+    `,
+  ),
+);
+```
+
+Equivalent to annotating with `satisfies LayoutHandler` but requires no explicit type import.
+
+---
+
 ### `wrapError(handler, page)`
 
 Wraps a page island with an error boundary. If the page throws during SSR (`.toString()`), the `handler` receives the error and current route snapshot and returns a fallback island. Also intercepts errors during `.mount()` for client-side resilience.
@@ -367,6 +393,9 @@ interface HydrateOptions {
   root?: Element;
   target?: string | Element;
 }
+
+// Helper — returns fn as-is with LayoutHandler type enforced
+function defineLayout(fn: LayoutHandler): LayoutHandler;
 ```
 
 ---
@@ -467,8 +496,28 @@ A `+layout.ts` wraps every page in its directory and all subdirectories. Layouts
 
 ```ts
 // src/pages/+layout.ts
-import { html } from "ilha";
+import { defineLayout } from "@ilha/router";
+import ilha, { html } from "ilha";
+
+export default defineLayout((children) =>
+  ilha.render(
+    () => html`
+      <nav>
+        <a href="/">Home</a>
+        <a href="/about">About</a>
+      </nav>
+      <main>${children}</main>
+    `,
+  ),
+);
+```
+
+Alternatively, using the explicit type annotation:
+
+```ts
+// src/pages/+layout.ts — using satisfies (equivalent)
 import type { LayoutHandler } from "@ilha/router/vite";
+import ilha, { html } from "ilha";
 
 export default ((children) =>
   ilha.render(

packages/router/src/index.test.ts

@@ -12,6 +12,7 @@ import {
   routePath,
   routeParams,
   routeSearch,
+  defineLayout,
 } from "./index";
 
 // ─────────────────────────────────────────────
@@ -948,3 +949,66 @@ describe("SSR full-page HTML template", () => {
     expect(routeParams()).toEqual({});
   });
 });
+
+// ─────────────────────────────────────────────
+// defineLayout()
+// ─────────────────────────────────────────────
+
+describe("defineLayout()", () => {
+  it("returns the same function reference (identity)", () => {
+    const layout = (children: typeof homePage) => ilha.render(() => children.toString());
+    const result = defineLayout(layout);
+    expect(result).toBe(layout);
+  });
+
+  it("wraps page content when the returned layout is called", () => {
+    const layout = defineLayout((children) =>
+      ilha.render(() => `<layout>${children.toString()}</layout>`),
+    );
+    const page = ilha.render(() => `<p>content</p>`);
+    const wrapped = layout(page);
+    expect(wrapped.toString()).toContain("<layout>");
+    expect(wrapped.toString()).toContain("<p>content</p>");
+  });
+
+  it("returned island has .toString and .mount", () => {
+    const layout = defineLayout((children) => ilha.render(() => children.toString()));
+    const wrapped = layout(homePage);
+    expect(typeof wrapped.toString).toBe("function");
+    expect(typeof wrapped.mount).toBe("function");
+  });
+
+  it("composes with wrapLayout — output is identical to satisfies LayoutHandler pattern", () => {
+    // defineLayout should produce the same result as the manual satisfies cast
+    const fn = (children: typeof homePage) =>
+      ilha.render(() => `<shell>${children.toString()}</shell>`);
+
+    const viaDefine = defineLayout(fn);
+    const page = ilha.render(() => `<p>page</p>`);
+
+    const wrappedViaDefine = viaDefine(page);
+    const wrappedDirect = fn(page);
+
+    expect(wrappedViaDefine.toString()).toBe(wrappedDirect.toString());
+  });
+
+  it("nested defineLayout calls compose inside-out", () => {
+    const outer = defineLayout((children) =>
+      ilha.render(() => `<outer>${children.toString()}</outer>`),
+    );
+    const inner = defineLayout((children) =>
+      ilha.render(() => `<inner>${children.toString()}</inner>`),
+    );
+    const page = ilha.render(() => `<p>page</p>`);
+
+    // outer wraps inner wraps page — outermost last in call chain
+    const wrapped = outer(inner(page));
+    const html = wrapped.toString();
+
+    expect(html).toContain("<outer>");
+    expect(html).toContain("<inner>");
+    expect(html).toContain("<p>page</p>");
+    expect(html.indexOf("<outer>")).toBeLessThan(html.indexOf("<inner>"));
+    expect(html.indexOf("<inner>")).toBeLessThan(html.indexOf("<p>page</p>"));
+  });
+});

packages/router/src/index.ts

@@ -81,6 +81,10 @@ export function wrapError(handler: ErrorHandler, page: Island<any, any>): Island
   return wrapper;
 }
 
+export function defineLayout(layout: LayoutHandler): LayoutHandler {
+  return layout;
+}
+
 export interface NavigateOptions {
   replace?: boolean;
 }