elm-ssr 0.90.1 → 0.91.1

package/README.md

@@ -26,21 +26,59 @@ bunx elm-ssr build
 
 ## CLI commands
 
-- **`elm-ssr build`** — scans each configured app's `src/<Namespace>/Routes/`
-  and `Islands/`, generates `.elm-ssr/Main.elm` (the router with file-based
-  routes + dynamic segments) and the islands manifest, syncs the Elm authoring
-  modules into the app's `.elm-ssr/src/ElmSsr/`, and compiles via `elm make`
-  (one combined island bundle exposing `Elm.<App>.Islands.<Name>`).
-- **`elm-ssr new <name>`** — scaffold a new app and register it in
-  `elm-ssr.config.json`.
-- **`elm-ssr dev`** — `build` then `wrangler dev` for Cloudflare-like local
-  development. For other hosts, build with `elm-ssr build` and adapt
-  `worker.fetch` in your own server/entrypoint.
-- **`elm-ssr compress`** — pre-compress generated bundles with gzip.
-- **`elm-ssr migrate <up|down|status>`** — apply / revert / inspect SQL-file
-  migrations. `--db postgres://…`, `sqlite://path`, or a plain SQLite file path;
-  `--dir <path>` (default `./migrations`); `--count N` (for `down`, default 1).
-  Reads `DATABASE_URL` if `--db` is omitted.
+Run the CLI using `bunx elm-ssr <command>`.
+
+### `build`
+Generates `.elm-ssr/Main.elm` (router) and the islands manifest for all configured apps, syncs the Elm authoring modules into `.elm-ssr/src/ElmSsr/`, and compiles pages and island bundles.
+
+### `compress`
+Runs the `build` pipeline and additionally pre-compresses generated JS/CSS assets with Gzip for faster delivery on edge networks.
+
+### `dev`
+Starts the local development loop. Compiles the Elm code and runs `wrangler dev` (monitoring `.elm` and `.css` files for hot-reloads).
+
+### `init <name> [--db] [--auth betterAuth|auth0]`
+Initialises a self-contained, single-app project in the current directory.
+- `--db`: Configures local SQLite database support (generates initial migration and configures `inMemoryEffects`).
+- `--auth <betterAuth|auth0>`: Scaffolds basic route modules (`Login.elm`, `Profile.elm`), signed cookie/CSRF middleware, and callback intercepts. (Automatically implies `--db`).
+
+### `new <name> [--in <subdir>] [--db] [--auth betterAuth|auth0]`
+Creates a new app under `<workspace>/<name>/` (or `<workspace>/<subdir>/<name>/` if `--in <subdir>` is provided) and registers it in `elm-ssr.config.json`.
+- `--in <subdir>`: Target subdirectory group (e.g. `--in apps` places it under `apps/<name>/`).
+- `--db`: Configures SQLite database support and an initial migration.
+- `--auth <betterAuth|auth0>`: Scaffolds authentication views, cookies, and callback handlers.
+
+### `route <path> [--app <name>] [--api] [--ws] [--sse]`
+Scaffolds a new route or endpoint:
+- `--app <app-name>`: Required if multiple apps are configured in the workspace.
+- `--api`: Scaffolds a JSON API page/action route instead of an HTML page.
+- `--ws` or `--websocket`: Scaffolds a TypeScript WebSocket handler in `src/Endpoints/<route>.ts`.
+- `--sse`: Scaffolds a TypeScript Server-Sent Events (SSE) stream handler in `src/Endpoints/<route>.ts`.
+
+### `query [--app <name>] [--dir <path>] [--output <path>]`
+Generates type-safe Elm database schema and query helpers directly from raw SQL files in the migrations directory.
+- `--app <app-name>`: Required if multiple apps exist.
+- `--dir <path>`: Directory containing migrations (default: `<app_root>/migrations`).
+- `--output <path>`: Directory where Elm Db modules will be generated (default: `<app_root>/src/<Module>/Db`).
+
+### `migrate <up|down|status> [--db <conn>] [--dir <path>] [--count <n>] [--table <name>]`
+SQL migration runner.
+- `up`: Applies all pending migrations.
+- `down`: Reverts the last migration (or `n` migrations via `--count`).
+- `status`: Lists all applied and pending migrations.
+- `--db <conn>`: Database connection string (Postgres URL, SQLite URL, or plain file path). Reads `DATABASE_URL` if omitted.
+- `--dir <path>`: Path to the SQL migrations directory (default: `./migrations`).
+- `--count <n>`: The number of migrations to revert when running `down` (default: 1).
+- `--table <name>`: Tracking database table name (default: `__elm_ssr_migrations`).
+
+### `routes`
+Prints a list of all configured apps, their root directories, and their route source directories.
+
+### `info`
+Prints the workspace name and registered app names.
+
+## Global options
+- `--root <path>`: Overrides where the CLI looks for `elm-ssr.config.json` (defaults to current directory).
 
 Configuration lives in `elm-ssr.config.json` at the repo root:
 

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,211 @@ 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 _ =
+    Loader.requireUser userDecoder "/login" (\\user ->
+        Loader.succeed (view user)
+    )
+
+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 +495,7 @@ export const routes: RouteCatalog = {
       path: "/counter",
       methods: ["GET", "HEAD"],
       description: "Interactive counter route rendered from Elm."
-    }
+    },${routeAuthAdditions}
   ],
   assets: [
     {
@@ -344,28 +540,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 +640,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 +697,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 +766,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 +774,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.1",
+  "version": "0.91.1",
   "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

@@ -396,8 +396,8 @@ export const injectDebugger = (html: string, data: unknown): string => {
     highlight.style.display = 'none';
   };
 
-  // Track island mutations to detect client-side state updates
   const islandMutations = new Map();
+  const islandActiveStates = new Map();
   const activeObservers = new Map();
   
   const setupMutationObservers = () => {
@@ -428,6 +428,16 @@ export const injectDebugger = (html: string, data: unknown): string => {
     });
   };
 
+  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'));
@@ -449,6 +459,22 @@ export const injectDebugger = (html: string, data: unknown): string => {
         ? \`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';
@@ -465,6 +491,7 @@ export const injectDebugger = (html: string, data: unknown): string => {
             <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>
@@ -479,6 +506,20 @@ 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;
   window.addEventListener('elm-ssr-broadcast', (event) => {
@@ -491,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;">

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));
     }