@withl5e/l5e 0.1.0-alpha.0

package/src/island/ClientIsland.ts

@@ -0,0 +1,71 @@
+import { jsxFactory, registerIsland, type JSXChild, type JSXNode } from '../core/jsx-runtime';
+
+/**
+ * Derive component name from `from` path.
+ * "./react/Counter" → "Counter"
+ * "~/features/newsfeed/react/NewsfeedApp" → "NewsfeedApp"
+ */
+function deriveComponentName(from: string): string {
+  const segments = from.split('/');
+  let filename = segments[segments.length - 1];
+  filename = filename.replace(/\.(tsx?|jsx?)$/, '');
+  return filename;
+}
+export type MountStrategy = 'load' | 'idle' | 'visible' | 'media' | 'none';
+export interface ClientIslandProps {
+  from: string;
+  props?: Record<string, any>;
+  mount?: MountStrategy | string;
+  mountOpts?: string;
+  class?: string;
+  id?: string;
+  children?: JSXChild | JSXChild[];
+
+  /** INTERNAL — injected by vite-plugin. Format: "[name]_[hash]" */
+  __key?: string;
+  /** INTERNAL — injected by vite-plugin. Manifest-compatible source path with extension */
+  __src?: string;
+}
+
+export function ClientIsland(attrs: ClientIslandProps): JSXNode {
+  const {
+    from,
+    props = {},
+    mount = 'load',
+    mountOpts,
+    class: className,
+    id,
+    children,
+    __key,
+    __src,
+  } = attrs;
+
+  const componentName = deriveComponentName(from);
+
+  // Register island in render context (like useClientJs)
+  // server.ts will use this to generate per-page window.__L5E_ISLANDS__
+  if (__key && __src) {
+    registerIsland(__key, __src, componentName);
+  }
+
+  const dataAttrs: Record<string, string> = {
+    'data-island': __key || 'unresolved',
+    'data-island-name': componentName,
+    'data-island-props': JSON.stringify(props),
+    'data-island-mount': mount,
+  };
+
+  if (mountOpts) {
+    dataAttrs['data-island-opts'] = mountOpts;
+  }
+
+  return jsxFactory(
+    'div',
+    {
+      ...dataAttrs,
+      ...(id ? { id } : {}),
+      class: className ? `l5e-island ${className}` : 'l5e-island',
+    },
+    children,
+  );
+}

package/src/island/client.ts

@@ -0,0 +1,3 @@
+// Client-side exports (for custom strategies)
+export { registerMountStrategy } from './strategy-registry';
+export type { MountStrategy } from './types';

package/src/island/index.ts

@@ -0,0 +1,3 @@
+// Island module exports — server-side only
+export { ClientIsland } from './ClientIsland';
+export type { MountStrategy, IslandMeta } from './types';

package/src/island/runtime.ts

@@ -0,0 +1,149 @@
+import type { IslandMeta } from './types';
+import { strategies, registerMountStrategy } from './strategy-registry';
+
+// ============================================================
+// PART 1: Built-in strategies
+// ============================================================
+
+registerMountStrategy('load', (mount) => {
+  mount();
+});
+
+registerMountStrategy('idle', (mount) => {
+  if ('requestIdleCallback' in window) {
+    requestIdleCallback(() => mount());
+  } else {
+    setTimeout(() => mount(), 200);
+  }
+});
+
+registerMountStrategy('visible', (mount, opts, el) => {
+  const rootMargin = opts || '200px';
+  const observer = new IntersectionObserver(
+    (entries) => {
+      entries.forEach((entry) => {
+        if (entry.isIntersecting) {
+          observer.disconnect();
+          mount();
+        }
+      });
+    },
+    { rootMargin },
+  );
+  observer.observe(el);
+  return () => observer.disconnect();
+});
+
+registerMountStrategy('media', (mount, opts) => {
+  if (!opts) {
+    console.error('[l5e-island] Strategy "media" requires mountOpts (media query)');
+    return;
+  }
+  const mql = window.matchMedia(opts);
+  if (mql.matches) {
+    mount();
+  } else {
+    const handler = (e: MediaQueryListEvent) => {
+      if (e.matches) mount();
+    };
+    mql.addEventListener('change', handler, { once: true });
+    return () => mql.removeEventListener('change', handler);
+  }
+});
+
+registerMountStrategy('none', () => {
+  // Don't mount - keep placeholder as-is
+});
+
+// ============================================================
+// PART 2: Import custom strategies (if any)
+// ============================================================
+
+import 'virtual:l5e-island-strategies';
+
+// ============================================================
+// PART 3: Island discovery + mount logic
+// ============================================================
+
+// Per-page island registry injected by server.ts as inline script
+// Format: { "Counter_a3f2": "/assets/Counter-Abc123.js" }
+const islandRegistry: Record<string, string> = (window as any).__L5E_ISLANDS__ || {};
+
+function discoverIslands(): IslandMeta[] {
+  return Array.from(document.querySelectorAll('[data-island]')).map((el) => ({
+    element: el as HTMLElement,
+    registryKey: el.getAttribute('data-island')!,
+    exportName: el.getAttribute('data-island-name')!,
+    props: JSON.parse(el.getAttribute('data-island-props') || '{}'),
+    mount: el.getAttribute('data-island-mount') || 'load',
+    mountOpts: el.getAttribute('data-island-opts') || undefined,
+  }));
+}
+
+function createMountFn(island: IslandMeta): () => Promise<void> {
+  let mounted = false;
+  return async () => {
+    if (mounted) return;
+    mounted = true;
+
+    // Look up component URL from per-page registry
+    const url = islandRegistry[island.registryKey];
+    if (!url) {
+      console.error(
+        `[l5e-island] Component "${island.registryKey}" not found in page registry.`,
+        `Available: ${Object.keys(islandRegistry).join(', ')}`,
+      );
+      return;
+    }
+
+    try {
+      const [{ createRoot }, { createElement }, mod] = await Promise.all([
+        import('react-dom/client'),
+        import('react'),
+        import(/* @vite-ignore */ url),
+      ]);
+
+      const Component = mod.default || mod[island.exportName];
+      if (!Component) {
+        console.error(`[l5e-island] No export "default" or "${island.exportName}" in module`);
+        return;
+      }
+
+      const root = createRoot(island.element);
+      root.render(createElement(Component, island.props));
+    } catch (error) {
+      console.error(`[l5e-island] Failed to mount "${island.registryKey}":`, error);
+    }
+  };
+}
+
+function scheduleMount(island: IslandMeta) {
+  const strategy = strategies.get(island.mount);
+
+  if (!strategy) {
+    console.error(
+      `[l5e-island] Strategy "${island.mount}" not found.`,
+      `Available: ${[...strategies.keys()].join(', ')}`,
+      `\nDid you forget to registerMountStrategy("${island.mount}", ...)?`,
+    );
+    return;
+  }
+
+  const mountFn = createMountFn(island);
+  strategy(mountFn, island.mountOpts, island.element);
+}
+
+// ============================================================
+// PART 4: Boot
+// ============================================================
+
+function boot() {
+  const islands = discoverIslands();
+  islands.forEach(scheduleMount);
+}
+
+if (document.readyState === 'loading') {
+  document.addEventListener('DOMContentLoaded', boot);
+} else {
+  boot();
+}

package/src/island/strategy-registry.ts

@@ -0,0 +1,10 @@
+import type { MountStrategy } from './types';
+
+export const strategies = new Map<string, MountStrategy>();
+
+export function registerMountStrategy(name: string, fn: MountStrategy) {
+  if (strategies.has(name)) {
+    console.warn(`[l5e-island] Strategy "${name}" already registered, overwriting.`);
+  }
+  strategies.set(name, fn);
+}

package/src/island/types.ts

@@ -0,0 +1,28 @@
+/**
+ * Mount strategy function signature
+ *
+ * @param mount  - Call when you want to load JS + mount React component
+ * @param opts   - Value from mountOpts prop (string | undefined)
+ * @param el     - DOM element containing the island
+ * @returns      - Optional cleanup function (called when island is removed)
+ */
+export type MountStrategy = (
+  mount: () => Promise<void>,
+  opts: string | undefined,
+  el: HTMLElement,
+) => void | (() => void);
+
+export interface IslandMeta {
+  element: HTMLElement;
+  registryKey: string; // "Counter_a3f2" - to find loader in registry
+  exportName: string; // "Counter" - to find export in module
+  props: Record<string, any>;
+  mount: string; // Strategy name
+  mountOpts?: string; // Options passed to strategy function
+}
+
+export interface IslandEntry {
+  component: string; // "Counter" (derived from resolvedPath filename)
+  resolvedPath: string; // "/src/views/test-island/react/Counter"
+  key: string; // "Counter_a3f2"
+}

package/src/middleware/defineMiddleware.ts

@@ -0,0 +1,5 @@
+import type { MiddlewareHandler } from './types';
+
+export function defineMiddleware(fn: MiddlewareHandler): MiddlewareHandler {
+  return fn;
+}

package/src/middleware/index.ts

@@ -0,0 +1,133 @@
+import { parseCookies } from '../core/request';
+import { defineMiddleware } from './defineMiddleware';
+import { sequence } from './sequence';
+import type { CreateContext, MiddlewareContext, RewritePayload } from './types';
+
+export type {
+  CreateContext,
+  MiddlewareContext,
+  MiddlewareHandler,
+  MiddlewareNext,
+  RewritePayload,
+} from './types';
+
+export { defineMiddleware, sequence };
+
+export function createContext({
+  request,
+  requestInfo,
+  locals = {},
+  clientAddress,
+}: CreateContext): MiddlewareContext {
+  const context = {
+    cookies: parseCookies(request.headers.get('cookie') ?? undefined),
+    request,
+    requestInfo,
+    url: new URL(request.url),
+    redirect(path: string | URL, status = 302) {
+      return new Response(null, {
+        status,
+        headers: {
+          Location: path.toString(),
+        },
+      });
+    },
+    rewrite(payload: RewritePayload) {
+      return Promise.resolve(new Response(null));
+    },
+    get clientAddress() {
+      if (clientAddress) {
+        return clientAddress;
+      }
+      throw new Error('clientAddress is not available for this request.');
+    },
+  } as Omit<MiddlewareContext, 'locals'> & {
+    locals: Record<string, unknown>;
+  };
+
+  Object.defineProperty(context, 'locals', {
+    enumerable: true,
+    get() {
+      if (typeof locals !== 'object' || locals === null || Array.isArray(locals)) {
+        throw new Error('Middleware locals must be a plain object.');
+      }
+      return locals;
+    },
+    set() {
+      throw new Error('Middleware locals cannot be reassigned. Mutate its properties instead.');
+    },
+  });
+
+  context.rewrite = (payload: RewritePayload) => {
+    return Promise.resolve(
+      new Response(null, {
+        status: 307,
+        headers: {
+          'X-L5E-Rewrite': stringifyRewritePayload(payload, context.url),
+        },
+      }),
+    );
+  };
+
+  return context;
+}
+
+export function isLocalsSerializable(value: unknown): boolean {
+  const stack: unknown[] = [value];
+
+  while (stack.length > 0) {
+    const current = stack.pop();
+    const type = typeof current;
+
+    if (current === null || type === 'string' || type === 'number' || type === 'boolean') {
+      continue;
+    }
+
+    if (Array.isArray(current)) {
+      stack.push(...current);
+      continue;
+    }
+
+    if (type === 'object' && isPlainObject(current)) {
+      stack.push(...Object.values(current as Record<string, unknown>));
+      continue;
+    }
+
+    return false;
+  }
+
+  return true;
+}
+
+function isPlainObject(value: unknown): value is object {
+  if (typeof value !== 'object' || value === null) return false;
+
+  const proto = Object.getPrototypeOf(value);
+  if (proto === null) return true;
+
+  let baseProto = proto;
+  while (Object.getPrototypeOf(baseProto) !== null) {
+    baseProto = Object.getPrototypeOf(baseProto);
+  }
+
+  return proto === baseProto;
+}
+
+export function trySerializeLocals(value: unknown): string {
+  if (isLocalsSerializable(value)) {
+    return JSON.stringify(value);
+  }
+  throw new Error("The passed value can't be serialized.");
+}
+
+function stringifyRewritePayload(payload: RewritePayload, currentUrl: URL): string {
+  if (payload instanceof Request) {
+    return payload.url;
+  }
+
+  if (payload instanceof URL) {
+    return payload.href;
+  }
+
+  return new URL(payload, currentUrl).href;
+}

package/src/middleware/sequence.ts

@@ -0,0 +1,105 @@
+import { parseCookies } from '../core/request';
+import { defineMiddleware } from './defineMiddleware';
+import type { MiddlewareContext, MiddlewareHandler, RewritePayload } from './types';
+
+// From SvelteKit via Astro: compose middleware handlers in declaration order.
+export function sequence(...handlers: Array<MiddlewareHandler | false | null | undefined>) {
+  const filtered = handlers.filter(Boolean) as MiddlewareHandler[];
+  const length = filtered.length;
+
+  if (!length) {
+    return defineMiddleware((_context, next) => {
+      return next();
+    });
+  }
+
+  return defineMiddleware((context, next) => {
+    let carriedPayload: RewritePayload | undefined;
+    return applyHandle(0, context);
+
+    function applyHandle(
+      i: number,
+      handleContext: MiddlewareContext,
+    ): Promise<Response> | Response {
+      const handle = filtered[i];
+
+      return handle(handleContext, async (payload?: RewritePayload) => {
+        if (i < length - 1) {
+          if (payload) {
+            carriedPayload = payload;
+            updateContextForRewrite(handleContext, payload);
+          }
+          return applyHandle(i + 1, handleContext);
+        }
+
+        return next(payload ?? carriedPayload);
+      });
+    }
+  });
+}
+
+function updateContextForRewrite(context: MiddlewareContext, payload: RewritePayload): void {
+  let request: Request;
+
+  if (payload instanceof Request) {
+    request = payload;
+  } else if (payload instanceof URL) {
+    request = new Request(payload.href, context.request.clone());
+  } else {
+    request = new Request(new URL(payload, context.url).href, context.request.clone());
+  }
+
+  const previousUrl = context.url;
+  const nextUrl = new URL(request.url);
+  const nextCookies = parseCookies(request.headers.get('cookie') ?? undefined);
+  context.request = request;
+  context.url = nextUrl;
+  context.cookies = nextCookies;
+
+  if (context.requestInfo) {
+    const headers: Record<string, string> = {};
+    request.headers.forEach((value, key) => {
+      headers[key] = value;
+    });
+
+    context.requestInfo = {
+      ...context.requestInfo,
+      url: nextUrl,
+      path: getRequestInfoPath(nextUrl, previousUrl, context.requestInfo.path),
+      pathname: nextUrl.pathname,
+      method: request.method,
+      headers,
+      cookies: nextCookies,
+      query: Object.fromEntries(nextUrl.searchParams.entries()),
+    };
+  }
+}
+
+function getRequestInfoPath(nextUrl: URL, previousUrl: URL, previousPath?: string): string {
+  const nextPath = `${nextUrl.pathname}${nextUrl.search}` || '/';
+  if (!previousPath) {
+    return nextPath;
+  }
+
+  const previousPathname = previousPath.split('?')[0] || '/';
+  if (
+    previousPathname === previousUrl.pathname ||
+    !previousUrl.pathname.endsWith(previousPathname)
+  ) {
+    return nextPath;
+  }
+
+  const basePathname = previousUrl.pathname.slice(
+    0,
+    previousUrl.pathname.length - previousPathname.length,
+  );
+  if (!basePathname || !nextUrl.pathname.startsWith(basePathname)) {
+    return nextPath;
+  }
+
+  const strippedPathname = nextUrl.pathname.slice(basePathname.length) || '/';
+  const normalizedPathname = strippedPathname.startsWith('/')
+    ? strippedPathname
+    : `/${strippedPathname}`;
+  return `${normalizedPathname}${nextUrl.search}`;
+}

package/src/middleware/types.ts

@@ -0,0 +1,28 @@
+import type { RequestInfo } from '../core/entry-server';
+
+export type RewritePayload = string | URL | Request;
+
+export type MiddlewareNext = (payload?: RewritePayload) => Promise<Response>;
+
+export interface CreateContext {
+  request: Request;
+  requestInfo?: RequestInfo;
+  locals?: Record<string, unknown>;
+  clientAddress?: string | null;
+}
+
+export interface MiddlewareContext {
+  request: Request;
+  requestInfo?: RequestInfo;
+  url: URL;
+  cookies: Record<string, string>;
+  locals: Record<string, unknown>;
+  redirect: (path: string | URL, status?: number) => Response;
+  rewrite: (payload: RewritePayload) => Promise<Response>;
+  clientAddress: string;
+}
+
+export type MiddlewareHandler = (
+  context: MiddlewareContext,
+  next: MiddlewareNext,
+) => Response | Promise<Response>;