elm-ssr 0.90.0 → 0.91.0

package/bin/elm-ssr.mjs

@@ -77,8 +77,9 @@ const printHelp = () => {
   compress      Pre-compress island and app bundles using Gzip for faster edge delivery
   dev           Build and start wrangler dev using the current workspace config
   init <name>   Initialize a self-contained single-app project in the current directory
-  new <name>    Create a new app at <workspace>/<name>/ (or <workspace>/<subdir>/<name>/
-                with --in <subdir>) and register it in elm-ssr.config.json
+                (use --db to wire SQLite/migrations, --auth betterAuth|auth0 for auth guards)
+  new <name>    Create a new app at <workspace>/<name>/ and register it in elm-ssr.config.json
+                (use --in <subdir> to group, --db for SQLite, --auth betterAuth|auth0 for auth)
   routes        Print configured apps and their public modules
   route <path>  Scaffold a new route (standard HTML, --api JSON, --ws WebSocket, or --sse EventSource)
   query         Generate type-safe Elm Db modules from SQL table definitions
@@ -195,11 +196,22 @@ switch (command) {
     const name = args[1];
 
     if (!name) {
-      console.error("Usage: elm-ssr init <name>");
+      console.error("Usage: elm-ssr init <name> [--db] [--auth betterAuth|auth0]");
       process.exit(1);
     }
 
-    const created = await createAppScaffold(rootPath, name, { root: "." });
+    const db = args.includes("--db");
+    let auth = findFlagValue("--auth");
+    if (auth) {
+      if (auth === "better-auth" || auth === "betterAuth") {
+        auth = "better-auth";
+      } else if (auth !== "auth0") {
+        console.error("Error: --auth only supports 'betterAuth' or 'auth0'");
+        process.exit(1);
+      }
+    }
+
+    const created = await createAppScaffold(rootPath, name, { root: ".", db, auth });
     console.log(`Initialized ${created.name} in current directory`);
     break;
   }
@@ -208,7 +220,7 @@ switch (command) {
     const name = args[1];
 
     if (!name) {
-      console.error("Usage: elm-ssr new <name> [--in <subdir>]");
+      console.error("Usage: elm-ssr new <name> [--in <subdir>] [--db] [--auth betterAuth|auth0]");
       console.error("  Default location: <workspace>/<name>/");
       console.error("  Use --in apps to place it under <workspace>/apps/<name>/, etc.");
       process.exit(1);
@@ -216,7 +228,19 @@ switch (command) {
 
     const subdir = findFlagValue("--in");
     const appRoot = subdir ? `${subdir.replace(/\/+$/, "")}/${name}` : name;
-    const created = await createAppScaffold(rootPath, name, { root: appRoot });
+    
+    const db = args.includes("--db");
+    let auth = findFlagValue("--auth");
+    if (auth) {
+      if (auth === "better-auth" || auth === "betterAuth") {
+        auth = "better-auth";
+      } else if (auth !== "auth0") {
+        console.error("Error: --auth only supports 'betterAuth' or 'auth0'");
+        process.exit(1);
+      }
+    }
+
+    const created = await createAppScaffold(rootPath, name, { root: appRoot, db, auth });
     console.log(`Created ${created.name} at ${created.root}`);
     break;
   }

package/lib/scaffold.mjs

@@ -85,7 +85,10 @@ import ${namespace}.View.Shared as Shared
 
 page : Request -> Loader (Document Never)
 page _ =
-    Loader.succeed view
+    Loader.env "GREETING"
+        |> Loader.map (\\maybeGreeting ->
+            view (Maybe.withDefault "Hello from default env!" maybeGreeting)
+        )
 
 
 action : Request -> Action (Document Never)
@@ -93,14 +96,15 @@ action _ =
     Action.fail 405 "Method not allowed"
 
 
-view : Document Never
-view =
+view : String -> Document Never
+view greeting =
     Page.page
         { title = "Starter | elm-ssr"
         , head = Shared.head
         , body =
             [ Shared.shell "elm-ssr starter"
-                [ p [] [ text "This page is stateless and renders on the edge with no client runtime." ]
+                [ p [] [ text ("Greeting from environment: " ++ greeting) ]
+                , p [] [ text "This page is stateless and renders on the edge with no client runtime." ]
                 , p [] [ a [ class "link", href "/counter" ] [ text "Open the interactive counter" ] ]
                 ]
             ]
@@ -272,19 +276,210 @@ view =
         }
 `;
 
-const runtimeTemplate = (appRoot) => {
+const loginRouteTemplate = (namespace, authProvider) => `module ${namespace}.Routes.Login exposing (page, action)
+
+import ElmSsr.Action as Action exposing (Action)
+import ElmSsr.Document exposing (Document)
+import ElmSsr.Html exposing (a, div, p, text)
+import ElmSsr.Html.Attributes as Attr
+import ElmSsr.Loader as Loader exposing (Loader)
+import ElmSsr.Page as Page
+import ElmSsr.Route exposing (Request)
+import ${namespace}.View.Shared as Shared
+
+page : Request -> Loader (Document Never)
+page _ =
+    Loader.succeed view
+
+action : Request -> Action (Document Never)
+action _ =
+    Action.fail 405 "Method not allowed"
+
+view : Document Never
+view =
+    Page.page
+        { title = "Login | elm-ssr"
+        , head = Shared.head
+        , body =
+            [ Shared.shell "Sign In"
+                [ div [ Attr.class "login-container" ]
+                    [ p [] [ text "Access user authentication example (${authProvider})." ]
+                    , div [ Attr.style "margin-top" "20px" ]
+                        [ a 
+                            [ Attr.class "button primary"
+                            , Attr.href "/api/auth/login"
+                            ] 
+                            [ text "Sign In with Auth Provider" ]
+                        ]
+                    ]
+                ]
+            ]
+        }
+`;
+
+const profileRouteTemplate = (namespace) => `module ${namespace}.Routes.Profile exposing (page, action)
+
+import ElmSsr.Action as Action exposing (Action)
+import ElmSsr.Document exposing (Document)
+import ElmSsr.Html exposing (a, div, h2, p, text)
+import ElmSsr.Html.Attributes as Attr
+import ElmSsr.Loader as Loader exposing (Loader)
+import ElmSsr.Page as Page
+import ElmSsr.Route as Route exposing (Request)
+import ${namespace}.View.Shared as Shared
+import Json.Decode as Decode
+
+type alias UserProfile =
+    { email : String
+    , name : Maybe String
+    }
+
+userDecoder : Decode.Decoder UserProfile
+userDecoder =
+    Decode.map2 UserProfile
+        (Decode.field "email" Decode.string)
+        (Decode.maybe (Decode.field "name" Decode.string))
+
+page : Request -> Loader (Document Never)
+page request =
+    Loader.requireUser userDecoder "/login" request
+        |> Loader.map view
+
+action : Request -> Action (Document Never)
+action _ =
+    Action.fail 405 "Method not allowed"
+
+view : UserProfile -> Document Never
+view user =
+    Page.page
+        { title = "Profile | elm-ssr"
+        , head = Shared.head
+        , body =
+            [ Shared.shell "User Profile"
+                [ div []
+                    [ h2 [] [ text ("Welcome, " ++ (Maybe.withDefault user.email user.name)) ]
+                    , p [] [ text ("Email: " ++ user.email) ]
+                    , p [ Attr.style "margin-top" "20px" ]
+                        [ a [ Attr.class "button", Attr.href "/api/auth/logout" ] [ text "Sign Out" ] ]
+                    ]
+                ]
+            ]
+        }
+`;
+
+const authEndpointTemplate = (authProvider) => `export const handleAuth = async (request: Request, env: any): Promise<Response> => {
+  const url = new URL(request.url);
+
+  if (url.pathname === "/api/auth/login") {
+    // Mock login session update for ${authProvider}
+    return new Response(null, {
+      status: 302,
+      headers: {
+        "Location": "/profile",
+        "Set-Cookie": "__elm_ssr_session=" + encodeURIComponent(JSON.stringify({
+          user: { email: "user@example.com", name: "${authProvider === "better-auth" ? "BetterAuth User" : "Auth0 User"}" }
+        })) + "; Path=/; HttpOnly; SameSite=Lax"
+      }
+    });
+  }
+
+  if (url.pathname === "/api/auth/logout") {
+    return new Response(null, {
+      status: 302,
+      headers: {
+        "Location": "/login",
+        "Set-Cookie": "__elm_ssr_session=; Path=/; Max-Age=0; HttpOnly"
+      }
+    });
+  }
+
+  return new Response("${authProvider} Endpoint API Mock", { status: 200 });
+};
+`;
+
+const runtimeTemplate = (appRoot, db = false, auth = undefined) => {
   // appRoot is a slash-separated path like "my-app" or "apps/my-app".
   // The generated bundles live at <workspaceRoot>/generated/<appRoot>/. From
   // <workspaceRoot>/<appRoot>/runtime.ts, we climb out by one ".." per segment.
   const upToRoot = appRoot === "." ? "." : appRoot.split("/").map(() => "..").join("/");
   const generatedPrefix = `${upToRoot}/generated/${appRoot === "." ? "" : appRoot}`.replace(/\/+$/, "");
-  return `import { createWorkerApp } from "elm-ssr";
-import { renderApp, type CompiledElmModule } from "elm-ssr/render";
-import type { RouteCatalog } from "elm-ssr/http";
-import { islands, bundleSource } from "${generatedPrefix}/islands-manifest";
-import { stylesheet } from "./styles";
-// @ts-expect-error Generated at build time.
-import ElmRuntime from "${generatedPrefix}/app.mjs";
+
+  const imports = [
+    `import { createWorkerApp } from "elm-ssr";`,
+    `import { renderApp, type CompiledElmModule } from "elm-ssr/render";`,
+    `import type { RouteCatalog } from "elm-ssr/http";`,
+    `import { islands, bundleSource } from "${generatedPrefix}/islands-manifest";`,
+    `import { stylesheet } from "./styles";`,
+    `// @ts-expect-error Generated at build time.`,
+    `import ElmRuntime from "${generatedPrefix}/app.mjs";`
+  ];
+
+  if (db) {
+    imports.push(`import { Database } from "bun:sqlite";`);
+    imports.push(`import { inMemoryEffects } from "elm-ssr/effects";`);
+  }
+  if (auth) {
+    imports.push(`import { handleAuth } from "./src/Endpoints/Auth";`);
+  }
+
+  let dbInit = '';
+  if (db) {
+    dbInit = `\nconst db = new Database("app.db");\n`;
+  }
+
+  let routeAuthAdditions = '';
+  if (auth) {
+    routeAuthAdditions = `
+    {
+      path: "/login",
+      methods: ["GET"],
+      description: "User authentication login page."
+    },
+    {
+      path: "/profile",
+      methods: ["GET"],
+      description: "Authenticated user profile."
+    },`;
+  }
+
+  let effectsConfig = '';
+  if (db) {
+    effectsConfig = `,
+  effects: inMemoryEffects({
+    env: process.env as any,
+    sql: (sql, params) => {
+      const query = db.prepare(sql);
+      return query.all(...params);
+    }
+  })`;
+  }
+
+  let sessionsConfig = '';
+  if (auth) {
+    sessionsConfig = `,
+  sessions: {
+    secret: (env) => (env?.SESSION_SECRET as string) || "change-me-to-a-secure-random-hmac-secret-key-that-is-at-least-32-chars",
+    secure: false
+  },
+  csrf: true`;
+  }
+
+  let authIntercept = '';
+  if (auth) {
+    authIntercept = `
+// Intercept Auth Provider requests
+const baseWorkerFetch = worker.fetch;
+worker.fetch = async (request, env, ctx) => {
+  const url = new URL(request.url);
+  if (url.pathname.startsWith("/api/auth/")) {
+    return handleAuth(request, env);
+  }
+  return baseWorkerFetch(request, env, ctx);
+};
+`;
+  }
+
+  return `${imports.join("\n")}
 
 const elmModule = ElmRuntime as CompiledElmModule;
 
@@ -299,7 +494,7 @@ export const routes: RouteCatalog = {
       path: "/counter",
       methods: ["GET", "HEAD"],
       description: "Interactive counter route rendered from Elm."
-    }
+    },${routeAuthAdditions}
   ],
   assets: [
     {
@@ -344,28 +539,39 @@ export const routes: RouteCatalog = {
   ]
 };
 
-export const createFlags = ({ request, path, formData }: { request?: Request; url?: URL; path: string; formData?: Record<string, string> }) => {
+export const createFlags = ({ request, path, formData, env }: { request?: Request; url?: URL; path: string; formData?: Record<string, string>; env?: Record<string, unknown> }) => {
   const [pathname, search = ""] = path.split("?");
 
+  const envVars: Record<string, string | number | boolean> = {};
+  if (env) {
+    for (const [key, value] of Object.entries(env)) {
+      if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") {
+        envVars[key] = value;
+      }
+    }
+  }
+
   return {
     method: request?.method ?? "GET",
     path: pathname,
     query: Object.fromEntries(new URLSearchParams(search)),
-    formData: formData ?? {}
+    formData: formData ?? {},
+    env: envVars
   };
 };
 
 export const renderPath = async (path: string) =>
   renderApp(elmModule, createFlags({ path }));
-
+${dbInit}
 export const worker = createWorkerApp({
   elmModule,
   islands,
   islandsBundle: bundleSource,
   stylesheet,
   routes,
-  createFlags
+  createFlags${sessionsConfig}${effectsConfig}
 });
+${authIntercept}
 `;
 };
 
@@ -433,8 +639,56 @@ body {
 \`;
 `;
 
-const filesForApp = (name, appRoot) => {
+const filesForApp = (name, appRoot, options = {}) => {
   const namespace = toPascalCase(name);
+  const db = options.db || !!options.auth;
+  const auth = options.auth;
+
+  const files = [
+    { path: `${appRoot}/elm.json`, content: JSON.stringify(elmJsonTemplate(), null, 2) + "\n" },
+    { path: `${appRoot}/runtime.ts`, content: runtimeTemplate(appRoot, db, auth) },
+    { path: `${appRoot}/worker.ts`, content: workerTemplate() },
+    { path: `${appRoot}/styles.ts`, content: stylesTemplate() },
+    { path: `${appRoot}/src/${namespace}/View/Shared.elm`, content: sharedTemplate(namespace) },
+    { path: `${appRoot}/src/${namespace}/Routes/Index.elm`, content: indexRouteTemplate(namespace) },
+    { path: `${appRoot}/src/${namespace}/Routes/Counter.elm`, content: counterRouteTemplate(namespace) },
+    { path: `${appRoot}/src/${namespace}/Routes/NotFound.elm`, content: notFoundRouteTemplate(namespace) },
+    { path: `${appRoot}/src/${namespace}/Islands/Counter.elm`, content: counterIslandTemplate(namespace) },
+    {
+      path: `${appRoot}/.dev.vars`,
+      content: `GREETING="Hello from your local .dev.vars file!"
+SESSION_SECRET="change-me-to-a-secure-random-hmac-secret-key-that-is-at-least-32-chars"
+`
+    }
+  ];
+
+  if (db) {
+    files.push({
+      path: `${appRoot}/migrations/0001_init.sql`,
+      content: `CREATE TABLE IF NOT EXISTS users (
+    id INTEGER PRIMARY KEY AUTOINCREMENT,
+    email TEXT NOT NULL UNIQUE,
+    name TEXT,
+    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP
+);
+`
+    });
+  }
+
+  if (auth) {
+    files.push({
+      path: `${appRoot}/src/${namespace}/Routes/Login.elm`,
+      content: loginRouteTemplate(namespace, auth)
+    });
+    files.push({
+      path: `${appRoot}/src/${namespace}/Routes/Profile.elm`,
+      content: profileRouteTemplate(namespace)
+    });
+    files.push({
+      path: `${appRoot}/src/Endpoints/Auth.ts`,
+      content: authEndpointTemplate(auth)
+    });
+  }
 
   return {
     configEntry: {
@@ -442,17 +696,7 @@ const filesForApp = (name, appRoot) => {
       root: appRoot,
       module: namespace
     },
-    files: [
-      { path: `${appRoot}/elm.json`, content: JSON.stringify(elmJsonTemplate(), null, 2) + "\n" },
-      { path: `${appRoot}/runtime.ts`, content: runtimeTemplate(appRoot) },
-      { path: `${appRoot}/worker.ts`, content: workerTemplate() },
-      { path: `${appRoot}/styles.ts`, content: stylesTemplate() },
-      { path: `${appRoot}/src/${namespace}/View/Shared.elm`, content: sharedTemplate(namespace) },
-      { path: `${appRoot}/src/${namespace}/Routes/Index.elm`, content: indexRouteTemplate(namespace) },
-      { path: `${appRoot}/src/${namespace}/Routes/Counter.elm`, content: counterRouteTemplate(namespace) },
-      { path: `${appRoot}/src/${namespace}/Routes/NotFound.elm`, content: notFoundRouteTemplate(namespace) },
-      { path: `${appRoot}/src/${namespace}/Islands/Counter.elm`, content: counterIslandTemplate(namespace) }
-    ]
+    files
   };
 };
 
@@ -521,7 +765,7 @@ export const createAppScaffold = async (rootPath, name, options = {}) => {
 
   const appRoot = normalizeAppRoot(options.root, name);
 
-  const { configEntry, files } = filesForApp(name, appRoot);
+  const { configEntry, files } = filesForApp(name, appRoot, options);
 
   for (const file of files) {
     const filePath = resolve(rootPath, file.path);
@@ -529,6 +773,20 @@ export const createAppScaffold = async (rootPath, name, options = {}) => {
     await writeFile(filePath, file.content, "utf8");
   }
 
+  // Create .env at workspace root if it doesn't exist
+  const envPath = resolve(rootPath, ".env");
+  let envExists = false;
+  try {
+    await stat(envPath);
+    envExists = true;
+  } catch {}
+
+  if (!envExists) {
+    await writeFile(envPath, `GREETING="Hello from your local .env file!"
+SESSION_SECRET="change-me-to-a-secure-random-hmac-secret-key-that-is-at-least-32-chars"
+`, "utf8");
+  }
+
   await writeWorkspaceConfig(rootPath, {
     ...config,
     apps: [...config.apps, configEntry]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "elm-ssr",
-  "version": "0.90.0",
+  "version": "0.91.0",
   "description": "Elm-first SSR library and framework for Cloudflare Workers (and Bun): file-based routes/islands, backend-neutral effect adapters (KV/D1/Redis/Postgres), background tasks (waitUntil/Queues), SQL-file migrations, CLI scaffold + build.",
   "license": "MIT",
   "author": "Michał Majchrzak <michmajchrzak@gmail.com>",

package/src/app.ts

@@ -107,7 +107,7 @@ export const createWorkerApp = ({
         requestId: "",
         startedAt: performance.now(),
         executionCtx,
-        env: (env ?? undefined) as Record<string, unknown> | undefined
+        env: (env ?? (typeof process !== "undefined" ? process.env : undefined)) as Record<string, unknown> | undefined
       });
     }
   };

package/src/client-runtime/islands.ts

@@ -27,7 +27,26 @@ function createIslandsRuntime(deps) {
 
     if (app.ports.broadcastOut) {
       app.ports.broadcastOut.subscribe((event) => {
-        window.dispatchEvent(new window.CustomEvent("elm-ssr-broadcast", { detail: event }));
+        const detail = {
+          ...event,
+          __elmssr_origin: {
+            name: marker.getAttribute("data-elmssr-island"),
+            id: marker.getAttribute("data-elmssr-id")
+          }
+        };
+        window.dispatchEvent(new window.CustomEvent("elm-ssr-broadcast", { detail }));
+      });
+    }
+
+    if (app.ports.stateOut) {
+      app.ports.stateOut.subscribe((state) => {
+        window.dispatchEvent(new window.CustomEvent("elm-ssr-state-update", {
+          detail: {
+            name: marker.getAttribute("data-elmssr-island"),
+            id: marker.getAttribute("data-elmssr-id"),
+            state
+          }
+        }));
       });
     }
 

package/src/debugger.ts

@@ -235,38 +235,51 @@ export const injectDebugger = (html: string, data: unknown): string => {
   toggleBtn.id = 'elm-ssr-debug-toggle';
   toggleBtn.innerHTML = '⚡ Debug';
   document.body.appendChild(toggleBtn);
-
+  
   // 4. Create Panel DOM
   const panel = document.createElement('div');
   panel.id = 'elm-ssr-debug-panel';
   
-  let effectsHtml = '';
-  if (data.effects && data.effects.length > 0) {
-    effectsHtml = data.effects.map(eff => {
-      const isSql = ['query', 'queryOne', 'execute'].includes(eff.kind);
-      const sqlSnippet = isSql ? \`<pre class="debug-code">\${eff.payload.sql}</pre>\` : '';
-      const paramsSnippet = isSql && eff.payload.params && eff.payload.params.length > 0 ? 
-        \`<div><strong>Params:</strong> \${JSON.stringify(eff.payload.params)}</div>\` : '';
-      const outcome = eff.ok ? '<span class="status-ok">SUCCESS</span>' : '<span class="status-error">FAILED</span>';
-      const detailError = eff.error ? \`<div class="status-error">\${eff.error}</div>\` : '';
-      return \`
-        <li class="debug-item">
-          <div class="debug-item-meta" style="flex: 1;">
-            <div style="display: flex; gap: 8px; align-items: center;">
-              <span class="debug-badge badge-primary">\${eff.kind}</span>
-              \${outcome}
-              <span style="color: #9ca3af; font-size: 0.85em;">\${eff.durationMs.toFixed(1)}ms</span>
-            </div>
-            \${sqlSnippet}
-            \${paramsSnippet}
-            \${detailError}
+  const isSqlKind = (kind) => ['query', 'queryOne', 'execute'].includes(kind);
+  
+  const generateEffectItemHtml = (eff) => {
+    const isSql = isSqlKind(eff.kind);
+    const sqlSnippet = isSql ? \`<pre class="debug-code">\${eff.payload.sql}</pre>\` : '';
+    const paramsSnippet = isSql && eff.payload.params && eff.payload.params.length > 0 ? 
+      \`<div><strong>Params:</strong> \${JSON.stringify(eff.payload.params)}</div>\` : '';
+    const outcome = eff.ok ? '<span class="status-ok">SUCCESS</span>' : '<span class="status-error">FAILED</span>';
+    const detailError = eff.error ? \`<div class="status-error">\${eff.error}</div>\` : '';
+    return \`
+      <li class="debug-item">
+        <div class="debug-item-meta" style="flex: 1;">
+          <div style="display: flex; gap: 8px; align-items: center;">
+            <span class="debug-badge badge-primary">\${eff.kind}</span>
+            \${outcome}
+            <span style="color: #9ca3af; font-size: 0.85em;">\${eff.durationMs.toFixed(1)}ms</span>
           </div>
-        </li>
-      \`;
-    }).join('');
-  } else {
-    effectsHtml = '<div style="color: #9ca3af; text-align: center; padding: 20px;">No server-side effects executed for this request.</div>';
-  }
+          \${sqlSnippet}
+          \${paramsSnippet}
+          \${detailError}
+        </div>
+      </li>
+    \`;
+  };
+
+  const getDbHtml = (effects) => {
+    const dbEffects = (effects || []).filter(eff => isSqlKind(eff.kind));
+    if (dbEffects.length === 0) {
+      return '<div style="color: #9ca3af; text-align: center; padding: 20px;">No SQL database queries executed for this request.</div>';
+    }
+    return \`<ul class="debug-list">\${dbEffects.map(generateEffectItemHtml).join('')}</ul>\`;
+  };
+
+  const getEffectsHtml = (effects) => {
+    const nonDbEffects = (effects || []).filter(eff => !isSqlKind(eff.kind));
+    if (nonDbEffects.length === 0) {
+      return '<div style="color: #9ca3af; text-align: center; padding: 20px;">No other server-side effects executed for this request.</div>';
+    }
+    return \`<ul class="debug-list">\${nonDbEffects.map(generateEffectItemHtml).join('')}</ul>\`;
+  };
 
   panel.innerHTML = \`
     <div class="debug-header">
@@ -276,6 +289,7 @@ export const injectDebugger = (html: string, data: unknown): string => {
       <div class="debug-tabs">
         <button class="debug-tab active" data-tab="overview">Overview</button>
         <button class="debug-tab" data-tab="islands">Islands</button>
+        <button class="debug-tab" data-tab="database">Database</button>
         <button class="debug-tab" data-tab="effects">Effects</button>
         <button class="debug-tab" data-tab="session">Session</button>
         <button class="debug-tab" data-tab="bridges">Bridges</button>
@@ -313,11 +327,14 @@ export const injectDebugger = (html: string, data: unknown): string => {
         </ul>
       </div>
       
+      <!-- DATABASE TAB -->
+      <div class="debug-pane" id="pane-database">
+        \${getDbHtml(data.effects)}
+      </div>
+      
       <!-- EFFECTS TAB -->
       <div class="debug-pane" id="pane-effects">
-        <ul class="debug-list">
-          \${effectsHtml}
-        </ul>
+        \${getEffectsHtml(data.effects)}
       </div>
       
       <!-- SESSION TAB -->
@@ -379,6 +396,48 @@ export const injectDebugger = (html: string, data: unknown): string => {
     highlight.style.display = 'none';
   };
 
+  const islandMutations = new Map();
+  const islandActiveStates = new Map();
+  const activeObservers = new Map();
+  
+  const setupMutationObservers = () => {
+    for (const obs of activeObservers.values()) {
+      obs.disconnect();
+    }
+    activeObservers.clear();
+    
+    const markers = Array.from(document.getElementsByTagName('elm-ssr-island'));
+    markers.forEach(marker => {
+      if (!islandMutations.has(marker)) {
+        islandMutations.set(marker, { count: 0, lastUpdate: null });
+      }
+      
+      const observer = new MutationObserver(() => {
+        const stats = islandMutations.get(marker);
+        stats.count += 1;
+        stats.lastUpdate = new Date();
+        
+        const activeTab = panel.querySelector('.debug-tab.active')?.getAttribute('data-tab');
+        if (activeTab === 'islands') {
+          scanIslands();
+        }
+      });
+      
+      observer.observe(marker, { childList: true, subtree: true, characterData: true, attributes: true });
+      activeObservers.set(marker, observer);
+    });
+  };
+
+  const findMarkerByOrigin = (origin) => {
+    if (!origin) return null;
+    const markers = Array.from(document.getElementsByTagName('elm-ssr-island'));
+    return markers.find(marker => {
+      const name = marker.getAttribute('data-elmssr-island');
+      const id = marker.getAttribute('data-elmssr-id');
+      return name === origin.name && (id === origin.id || (!id && !origin.id));
+    });
+  };
+
   const scanIslands = () => {
     const list = panel.querySelector('#debug-islands-list');
     const markers = Array.from(document.getElementsByTagName('elm-ssr-island'));
@@ -395,6 +454,27 @@ export const injectDebugger = (html: string, data: unknown): string => {
       const isBooted = marker.getAttribute('data-elmssr-booted') === 'true';
       const id = marker.getAttribute('data-elmssr-id') || 'none';
       
+      const stats = islandMutations.get(marker) || { count: 0, lastUpdate: null };
+      const lastUpdateStr = stats.lastUpdate 
+        ? \`Last active DOM mutation: \${stats.lastUpdate.toLocaleTimeString()}\`
+        : 'No client state changes recorded';
+      
+      const activeState = islandActiveStates.get(marker);
+      const domTextPreview = marker.textContent.trim().replace(/\\s+/g, ' ');
+      
+      let stateSnippet = '';
+      if (activeState) {
+        stateSnippet = \`
+          <div style="font-size: 0.85em; margin-top: 6px; color: #a5b4fc;"><strong>Active Model State:</strong></div>
+          <pre class="debug-code" style="font-size: 0.85em; max-height: 120px; overflow-y: auto; color: #818cf8;">\${JSON.stringify(activeState, null, 2)}</pre>
+        \`;
+      } else if (domTextPreview) {
+        stateSnippet = \`
+          <div style="font-size: 0.85em; margin-top: 6px; color: #9ca3af;"><strong>DOM Text Preview (Live):</strong></div>
+          <div class="debug-code" style="font-size: 0.85em; color: #9ca3af; white-space: nowrap; overflow: hidden; text-overflow: ellipsis;">\${domTextPreview}</div>
+        \`;
+      }
+      
       const li = document.createElement('li');
       li.className = 'debug-item';
       li.style.cursor = 'pointer';
@@ -406,9 +486,13 @@ export const injectDebugger = (html: string, data: unknown): string => {
               \${isBooted ? 'BOOTED' : 'INITIALIZING'}
             </span>
           </div>
-          <div style="font-size: 0.8em; margin-top: 4px; color: #9ca3af;">
+          <div style="font-size: 0.8em; margin-top: 4px; color: #9ca3af; display: flex; justify-content: space-between;">
             <span><strong>ID:</strong> \${id}</span>
+            <span style="color: #34d399;"><strong>DOM Mutations:</strong> \${stats.count}</span>
           </div>
+          <div style="font-size: 0.75em; color: #9ca3af; margin-top: 2px;">\${lastUpdateStr}</div>
+          \${stateSnippet}
+          <div style="font-size: 0.8em; margin-top: 6px; color: #e5e7eb;"><strong>Initial Props:</strong></div>
           <pre class="debug-code" style="font-size: 0.85em; max-height: 80px; overflow-y: auto;">\${JSON.stringify(JSON.parse(props), null, 2)}</pre>
         </div>
       \`;
@@ -420,6 +504,21 @@ export const injectDebugger = (html: string, data: unknown): string => {
   };
 
   panel.querySelector('[data-tab="islands"]').addEventListener('click', scanIslands);
+  setupMutationObservers();
+
+  // Listen to explicit state update ports
+  window.addEventListener('elm-ssr-state-update', (event) => {
+    if (event.detail) {
+      const marker = findMarkerByOrigin(event.detail);
+      if (marker) {
+        islandActiveStates.set(marker, event.detail.state);
+        const activeTab = panel.querySelector('.debug-tab.active')?.getAttribute('data-tab');
+        if (activeTab === 'islands') {
+          scanIslands();
+        }
+      }
+    }
+  });
 
   const bridgeLog = panel.querySelector('#debug-bridges-log');
   let firstBridge = true;
@@ -433,7 +532,18 @@ export const injectDebugger = (html: string, data: unknown): string => {
     const payload = event.detail && event.detail.payload;
     const time = new Date().toLocaleTimeString();
     
-    const li = document.createElement('li');
+    // Check if it is a state update event
+    if (tag === '__elmssr_state__' && event.detail.__elmssr_origin) {
+      const marker = findMarkerByOrigin(event.detail.__elmssr_origin);
+      if (marker) {
+        islandActiveStates.set(marker, payload);
+        const activeTab = panel.querySelector('.debug-tab.active')?.getAttribute('data-tab');
+        if (activeTab === 'islands') {
+          scanIslands();
+        }
+      }
+    }
+     const li = document.createElement('li');
     li.className = 'debug-item';
     li.innerHTML = \`
       <div class="debug-item-meta" style="flex: 1;">
@@ -472,35 +582,11 @@ export const injectDebugger = (html: string, data: unknown): string => {
       </div>
     \`;
     
+    const dbPane = panel.querySelector('#pane-database');
+    dbPane.innerHTML = getDbHtml(newData.effects);
+    
     const effectsPane = panel.querySelector('#pane-effects');
-    let newEffectsHtml = '';
-    if (newData.effects && newData.effects.length > 0) {
-      newEffectsHtml = newData.effects.map(eff => {
-        const isSql = ['query', 'queryOne', 'execute'].includes(eff.kind);
-        const sqlSnippet = isSql ? \`<pre class="debug-code">\${eff.payload.sql}</pre>\` : '';
-        const paramsSnippet = isSql && eff.payload.params && eff.payload.params.length > 0 ? 
-          \`<div><strong>Params:</strong> \${JSON.stringify(eff.payload.params)}</div>\` : '';
-        const outcome = eff.ok ? '<span class="status-ok">SUCCESS</span>' : '<span class="status-error">FAILED</span>';
-        const detailError = eff.error ? \`<div class="status-error">\${eff.error}</div>\` : '';
-        return \`
-          <li class="debug-item">
-            <div class="debug-item-meta" style="flex: 1;">
-              <div style="display: flex; gap: 8px; align-items: center;">
-                <span class="debug-badge badge-primary">\${eff.kind}</span>
-                \${outcome}
-                <span style="color: #9ca3af; font-size: 0.85em;">\${eff.durationMs.toFixed(1)}ms</span>
-              </div>
-              \${sqlSnippet}
-              \${paramsSnippet}
-              \${detailError}
-            </div>
-          </li>
-        \`;
-      }).join('');
-      effectsPane.innerHTML = \`<ul class="debug-list">\${newEffectsHtml}</ul>\`;
-    } else {
-      effectsPane.innerHTML = '<div style="color: #9ca3af; text-align: center; padding: 20px;">No server-side effects executed for this request.</div>';
-    }
+    effectsPane.innerHTML = getEffectsHtml(newData.effects);
     
     const sessionPane = panel.querySelector('#pane-session');
     sessionPane.innerHTML = \`
@@ -512,6 +598,8 @@ export const injectDebugger = (html: string, data: unknown): string => {
       </div>
     \`;
     
+    setupMutationObservers(); // Observe any newly mounted islands
+    
     const activeTab = panel.querySelector('.debug-tab.active').getAttribute('data-tab');
     if (activeTab === 'islands') {
       scanIslands();

package/src/http.ts

@@ -3,6 +3,7 @@ export interface RenderFlagsContext {
   url: URL;
   path: string;
   formData?: Record<string, string>;
+  env?: Record<string, unknown>;
 }
 
 export interface WorkerExecutionContext {

package/src/request-handler.ts

@@ -97,7 +97,8 @@ const createFlagsFromContext = async (
     request: context.request,
     url: context.url,
     path,
-    formData
+    formData,
+    env: context.env
   });
 };
 

package/src/sessions/middleware.ts

@@ -6,7 +6,7 @@ import type { RequestSession, SessionStore } from "./types";
 
 export interface SessionMiddlewareOptions {
   /** HMAC-SHA256 secret used to sign the session cookie. Must not leak. */
-  secret: string;
+  secret: string | ((env: any) => string);
   /** Where to persist sessions. Use `memorySessionStore()` in dev, `cacheStore(...)` in prod. */
   store: SessionStore;
   /** Cookie name. Default `"session"`. */
@@ -87,9 +87,18 @@ export const sessionMiddleware = (options: SessionMiddlewareOptions): Middleware
     sameSite: options.sameSite ?? "lax" as const
   };
 
+  const resolveSecret = (env: any): string => {
+    if (typeof options.secret === "function") {
+      return options.secret(env);
+    }
+    return options.secret;
+  };
+
   return async (context, next) => {
+    const env = context.env ?? {};
+    const secret = resolveSecret(env);
     const cookieHeader = context.request.headers.get("cookie");
-    const sessionId = await readSignedCookie(cookieHeader, cookieName, options.secret);
+    const sessionId = await readSignedCookie(cookieHeader, cookieName, secret);
 
     let session: RequestSession;
     if (sessionId) {
@@ -125,7 +134,7 @@ export const sessionMiddleware = (options: SessionMiddlewareOptions): Middleware
         csrf: session.csrf,
         expiresAt: Date.now() + maxAge * 1000
       });
-      const signed = await signValue(options.secret, session.id);
+      const signed = await signValue(secret, session.id);
       return appendSetCookie(response, buildSetCookie(cookieName, signed, maxAge, cookieOptions));
     }