lakebed 0.0.19 → 0.0.20

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lakebed",
-  "version": "0.0.19",
+  "version": "0.0.20",
   "description": "Agent-native CLI and runtime for building and deploying Lakebed capsules.",
   "license": "UNLICENSED",
   "type": "module",

package/src/anonymous-server.js

@@ -474,6 +474,26 @@ function routeSystemPath(pathname) {
   return pathname;
 }
 
+function wantsHtml(req) {
+  const accept = String(req.headers.accept ?? "");
+  return !accept || accept.includes("text/html");
+}
+
+function isReservedClientShellPath(pathname) {
+  return (
+    pathname === "/client.js" ||
+    pathname === "/__lakebed" ||
+    pathname.startsWith("/__lakebed/") ||
+    pathname === "/__span" ||
+    pathname.startsWith("/__span/") ||
+    (pathname.startsWith("/auth/") && pathname !== "/auth/callback")
+  );
+}
+
+function isClientShellRequest(req, pathname) {
+  return req.method === "GET" && wantsHtml(req) && !isReservedClientShellPath(pathname);
+}
+
 function parsePathDeploy(url) {
   const parts = url.pathname.split("/").filter(Boolean);
   if (parts[0] !== "d" || !parts[1]) {
@@ -6771,6 +6791,14 @@ export async function startAnonymousServer({
         return;
       }
 
+      if (isClientShellRequest(req, appPath)) {
+        sendText(res, 200, html(loaded.artifact.name ?? "Lakebed Capsule", loaded.basePath, { clientBundleHash: loaded.deploy.clientBundleHash, shooBaseUrl }), {
+          "Cache-Control": "no-store",
+          "Content-Type": "text/html; charset=utf-8"
+        });
+        return;
+      }
+
       sendText(res, 404, "Not found\n", { "Content-Type": "text/plain; charset=utf-8" });
     } catch (error) {
       if (isQuotaError(error)) {

package/src/cli.js

@@ -452,6 +452,26 @@ function html(title, { shooBaseUrl } = {}) {
 </html>`;
 }
 
+function wantsHtml(req) {
+  const accept = String(req.headers.accept ?? "");
+  return !accept || accept.includes("text/html");
+}
+
+function isReservedClientShellPath(pathname) {
+  return (
+    pathname === "/client.js" ||
+    pathname === "/__lakebed" ||
+    pathname.startsWith("/__lakebed/") ||
+    pathname === "/__span" ||
+    pathname.startsWith("/__span/") ||
+    (pathname.startsWith("/auth/") && pathname !== "/auth/callback")
+  );
+}
+
+function isClientShellRequest(req, pathname) {
+  return req.method === "GET" && wantsHtml(req) && !isReservedClientShellPath(pathname);
+}
+
 function sendJson(ws, message) {
   ws.send(JSON.stringify(message));
 }
@@ -819,6 +839,12 @@ export async function startDevServer({
         return;
       }
 
+      if (isClientShellRequest(req, requestUrl.pathname)) {
+        res.writeHead(200, { "Cache-Control": "no-store", "Content-Type": "text/html; charset=utf-8" });
+        res.end(html(currentBuild.app.name ?? "Lakebed Capsule", { shooBaseUrl }));
+        return;
+      }
+
       res.writeHead(404);
       res.end("Not found");
     } catch (error) {
@@ -1751,7 +1777,7 @@ Your role is to build software within this capsule. Lakebed is the runtime, the
 - Data needed on client should be fetched through queries. User-driven changes should be done via mutations. Endpoints should be treated as an "escape hatch" for exposing functionality over endpoints for HTTP-based flows.
 - Styling must be done via raw CSS or Tailwind classes in the JSX.
 - Do not add a CSS, PostCSS, or Tailwind build pipeline. They are built in.
-- There is no file based routing. You can define routes yourself through typescript.
+- There is no file based routing. Use the built-in client router from \`lakebed/client\` when you need pages.
 - All imports must be from Lakebed or from relative paths.
 - Do not use Node built-ins in app code.
 - Use auth through \`ctx.auth\` on the server and \`useAuth()\` on the client.
@@ -1812,7 +1838,7 @@ function todoTemplate(name) {
   return {
     "AGENTS.md": agentInstructions,
     "CLAUDE.md": agentInstructions,
-    "server/index.ts": `import { boolean, capsule, mutation, query, string, table } from "lakebed/server";
+    "server/index.ts": `import { boolean, capsule, endpoint, mutation, query, string, table, text } from "lakebed/server";
 import { cleanTodoText } from "../shared/todo";
 
 export default capsule({
@@ -1844,10 +1870,15 @@ export default capsule({
 
       ctx.db.todos.insert({ text: cleanText, ownerId: ctx.auth.userId });
     })
+  },
+
+  endpoints: {
+    status: endpoint({ method: "GET", path: "/api/status" }, () => text("ok"))
   }
 });
 `,
-    "client/index.tsx": `import { SignInWithGoogle, signOut, useAuth, useMutation, useQuery } from "lakebed/client";
+    "client/index.tsx": `import { Link, Route, Router, Routes, SignInWithGoogle, signOut, useAuth, useMutation, useQuery } from "lakebed/client";
+import { useState } from "preact/hooks";
 import { cleanTodoText, type Todo } from "../shared/todo";
 
 function AuthAvatar({ label, picture }: { label: string; picture?: string }) {
@@ -1874,12 +1905,9 @@ function AuthAvatar({ label, picture }: { label: string; picture?: string }) {
   );
 }
 
-export function App() {
-  const auth = useAuth();
+function TodoPage() {
   const todos = useQuery<Todo[]>("todos");
   const addTodo = useMutation<[text: string], void>("addTodo");
-  const authLabel = auth.displayName;
-  const authStatus = auth.isLoading && auth.isGuest ? "checking session" : "signed in as " + authLabel;
 
   async function onSubmit(event: SubmitEvent) {
     event.preventDefault();
@@ -1895,33 +1923,75 @@ export function App() {
   }
 
   return (
-    <main className="min-h-screen bg-black px-6 py-10 text-white">
-      <section className="mx-auto max-w-2xl">
-        <div className="mb-3 flex items-center justify-between gap-3">
-          <div className="flex min-w-0 items-center gap-2">
-            {!auth.isLoading ? <AuthAvatar label={authLabel} picture={auth.picture} /> : null}
-            <p className="min-w-0 truncate font-mono text-sm text-neutral-500">{authStatus}</p>
+    <section>
+      <h1 className="mb-8 text-5xl font-bold tracking-tight">${title}</h1>
+      <form className="mb-8 flex gap-3" onSubmit={(event) => void onSubmit(event)}>
+        <input className="min-w-0 flex-1 border border-neutral-700 bg-black px-3 py-2 text-white outline-none focus:border-white" name="text" placeholder="Add a todo" />
+        <button className="border border-white px-4 py-2 font-medium" type="submit">Add</button>
+      </form>
+      <ul className="divide-y divide-neutral-800 border-y border-neutral-800">
+        {todos.map((todo) => (
+          <li className="py-3" key={todo.id}>{todo.text}</li>
+        ))}
+      </ul>
+    </section>
+  );
+}
+
+function StatusPage() {
+  const [status, setStatus] = useState("not checked");
+
+  async function checkStatus() {
+    const response = await fetch("api/status");
+    setStatus(response.ok ? await response.text() : "error " + response.status);
+  }
+
+  return (
+    <section>
+      <h1 className="mb-4 text-4xl font-bold tracking-tight">Status</h1>
+      <p className="mb-6 text-neutral-400">This route calls the server endpoint at /api/status.</p>
+      <button className="border border-white px-4 py-2 font-medium" type="button" onClick={() => void checkStatus()}>
+        Check endpoint
+      </button>
+      <p className="mt-4 font-mono text-sm text-neutral-400">endpoint: {status}</p>
+    </section>
+  );
+}
+
+export function App() {
+  const auth = useAuth();
+  const authLabel = auth.displayName;
+  const authStatus = auth.isLoading && auth.isGuest ? "checking session" : "signed in as " + authLabel;
+
+  return (
+    <Router>
+      <main className="min-h-screen bg-black px-6 py-10 text-white">
+        <section className="mx-auto max-w-2xl">
+          <div className="mb-3 flex items-center justify-between gap-3">
+            <div className="flex min-w-0 items-center gap-2">
+              {!auth.isLoading ? <AuthAvatar label={authLabel} picture={auth.picture} /> : null}
+              <p className="min-w-0 truncate font-mono text-sm text-neutral-500">{authStatus}</p>
+            </div>
+            {!auth.isLoading && auth.isGuest ? (
+              <SignInWithGoogle className="shrink-0 border border-neutral-700 px-3 py-1.5 text-sm font-medium text-neutral-200 hover:border-white hover:text-white" />
+            ) : !auth.isLoading ? (
+              <button className="shrink-0 text-sm text-neutral-400 hover:text-white" type="button" onClick={() => signOut()}>
+                Sign out
+              </button>
+            ) : null}
           </div>
-          {!auth.isLoading && auth.isGuest ? (
-            <SignInWithGoogle className="shrink-0 border border-neutral-700 px-3 py-1.5 text-sm font-medium text-neutral-200 hover:border-white hover:text-white" />
-          ) : !auth.isLoading ? (
-            <button className="shrink-0 text-sm text-neutral-400 hover:text-white" type="button" onClick={() => signOut()}>
-              Sign out
-            </button>
-          ) : null}
-        </div>
-        <h1 className="mb-8 text-5xl font-bold tracking-tight">${title}</h1>
-        <form className="mb-8 flex gap-3" onSubmit={(event) => void onSubmit(event)}>
-          <input className="min-w-0 flex-1 border border-neutral-700 bg-black px-3 py-2 text-white outline-none focus:border-white" name="text" placeholder="Add a todo" />
-          <button className="border border-white px-4 py-2 font-medium" type="submit">Add</button>
-        </form>
-        <ul className="divide-y divide-neutral-800 border-y border-neutral-800">
-          {todos.map((todo) => (
-            <li className="py-3" key={todo.id}>{todo.text}</li>
-          ))}
-        </ul>
-      </section>
-    </main>
+          <nav className="mb-8 flex gap-4 text-sm text-neutral-400">
+            <Link className="hover:text-white" to="/">Todos</Link>
+            <Link className="hover:text-white" to="/status">Status</Link>
+          </nav>
+          <Routes>
+            <Route path="/" element={<TodoPage />} />
+            <Route path="/status" element={<StatusPage />} />
+            <Route path="*" element={<section><h1 className="mb-4 text-4xl font-bold">Not found</h1><Link className="text-neutral-300 hover:text-white" to="/">Back to todos</Link></section>} />
+          </Routes>
+        </section>
+      </main>
+    </Router>
   );
 }
 `,
@@ -1948,6 +2018,17 @@ Run this Lakebed capsule:
 \`\`\`sh
 npx lakebed dev
 \`\`\`
+
+The starter app includes two client routes:
+
+- \`/\`: the todo list.
+- \`/status\`: a page that calls the \`GET /api/status\` endpoint.
+
+You can also call the endpoint directly:
+
+\`\`\`sh
+curl http://localhost:3000/api/status
+\`\`\`
 `
   };
 }

package/src/client.d.ts

@@ -53,11 +53,49 @@ export type SignInWithGoogleProps = Omit<JSX.ButtonHTMLAttributes<HTMLButtonElem
     children?: ComponentChildren;
   };
 
+export type LakebedLocation = {
+  pathname: string;
+  search: string;
+  hash: string;
+  href: string;
+};
+
+export type NavigateOptions = {
+  replace?: boolean;
+};
+
+export type RouterProps = {
+  children?: ComponentChildren;
+};
+
+export type RoutesProps = {
+  children?: ComponentChildren;
+};
+
+export type RouteProps = {
+  path: string;
+  element: ComponentChildren;
+};
+
+export type LinkProps = Omit<JSX.AnchorHTMLAttributes<HTMLAnchorElement>, "href"> & {
+  to: string;
+  replace?: boolean;
+  children?: ComponentChildren;
+};
+
 export function useAuth(): Auth;
 export function signInWithGoogle(options?: SignInWithGoogleOptions): Promise<SignInWithGoogleResult>;
 export function signOut(): void;
 export function getIdentity(): Identity;
 export function decodeIdentityClaims(idToken?: string): IdentityClaims | null;
 export function SignInWithGoogle(props?: SignInWithGoogleProps): JSX.Element;
+export function Router(props?: RouterProps): JSX.Element;
+export function Routes(props?: RoutesProps): JSX.Element | null;
+export function Route(props: RouteProps): JSX.Element | null;
+export function Link(props: LinkProps): JSX.Element;
+export function navigate(to: string, options?: NavigateOptions): void;
+export function useLocation(): LakebedLocation;
+export function useNavigate(): (to: string, options?: NavigateOptions) => void;
+export function useParams<TParams = Record<string, string | undefined>>(): TParams;
 export function useQuery<T>(name: string): T;
 export function useMutation<TArgs extends unknown[], TResult>(name: string): (...args: TArgs) => Promise<TResult>;

package/src/client.js

@@ -1,5 +1,5 @@
-import { h } from "preact";
-import { useEffect, useState } from "preact/hooks";
+import { createContext, h, toChildArray } from "preact";
+import { useContext, useEffect, useState } from "preact/hooks";
 
 const DEFAULT_SHOO_BASE_URL = "https://shoo.dev";
 const AUTH_STORAGE_KEY = "lakebed_identity";
@@ -23,6 +23,14 @@ let authInitialized = false;
 let authResumeStarted = false;
 let refreshRequested = false;
 
+const RouterContext = createContext(null);
+const RouteContext = createContext({ params: {} });
+
+function normalizeBasePathValue(value) {
+  const clean = String(value ?? "").replace(/\/+$/g, "");
+  return clean === "/" ? "" : clean;
+}
+
 function toGuestName(name) {
   return (
     String(name ?? "local")
@@ -144,7 +152,7 @@ function send(message) {
 }
 
 function basePath() {
-  return window.__LAKEBED_BASE_PATH__ ?? "";
+  return normalizeBasePathValue(window.__LAKEBED_BASE_PATH__ ?? "");
 }
 
 function authConfig() {
@@ -159,6 +167,214 @@ function currentRoute() {
   return `${window.location.pathname}${window.location.search}${window.location.hash}`;
 }
 
+function appPathnameFromBrowserPathname(pathname) {
+  const base = basePath();
+  if (!base) {
+    return pathname || "/";
+  }
+
+  if (pathname === base) {
+    return "/";
+  }
+
+  if (pathname.startsWith(`${base}/`)) {
+    return pathname.slice(base.length) || "/";
+  }
+
+  return pathname || "/";
+}
+
+function currentAppLocation() {
+  if (typeof window === "undefined") {
+    return { hash: "", href: "/", pathname: "/", search: "" };
+  }
+
+  const pathname = appPathnameFromBrowserPathname(window.location.pathname);
+  const search = window.location.search;
+  const hash = window.location.hash;
+  return {
+    hash,
+    href: `${pathname}${search}${hash}`,
+    pathname,
+    search
+  };
+}
+
+function isExternalHref(value) {
+  return /^[a-zA-Z][a-zA-Z\d+.-]*:/.test(value) || value.startsWith("//");
+}
+
+function browserHrefForAppHref(appHref) {
+  const url = new URL(appHref, "http://lakebed.local/");
+  const base = basePath();
+  const pathname = base ? `${base}${url.pathname === "/" ? "/" : url.pathname}` : url.pathname;
+  return `${pathname}${url.search}${url.hash}`;
+}
+
+function hrefForRoute(to) {
+  const value = String(to ?? "");
+  if (!value) {
+    return browserHrefForAppHref(currentAppLocation().href);
+  }
+
+  if (isExternalHref(value)) {
+    return value;
+  }
+
+  const current = currentAppLocation();
+  const resolved = new URL(value, `http://lakebed.local${current.href}`);
+  return browserHrefForAppHref(`${resolved.pathname}${resolved.search}${resolved.hash}`);
+}
+
+function emitLocationChange() {
+  window.dispatchEvent(new Event("lakebed:locationchange"));
+}
+
+export function navigate(to, options = {}) {
+  const href = hrefForRoute(to);
+  const parsed = new URL(href, window.location.href);
+
+  if (parsed.origin !== window.location.origin) {
+    window.location.assign(parsed.toString());
+    return;
+  }
+
+  const next = `${parsed.pathname}${parsed.search}${parsed.hash}`;
+  const current = `${window.location.pathname}${window.location.search}${window.location.hash}`;
+  if (next === current) {
+    return;
+  }
+
+  if (options.replace) {
+    window.history.replaceState({}, "", next);
+  } else {
+    window.history.pushState({}, "", next);
+  }
+  emitLocationChange();
+}
+
+function useBrowserLocation() {
+  const [location, setLocation] = useState(currentAppLocation);
+
+  useEffect(() => {
+    function updateLocation() {
+      setLocation(currentAppLocation());
+    }
+
+    window.addEventListener("popstate", updateLocation);
+    window.addEventListener("lakebed:locationchange", updateLocation);
+    return () => {
+      window.removeEventListener("popstate", updateLocation);
+      window.removeEventListener("lakebed:locationchange", updateLocation);
+    };
+  }, []);
+
+  return location;
+}
+
+function normalizeMatchPath(path) {
+  const value = String(path ?? "/").trim();
+  if (value === "*" || value === "/*") {
+    return "*";
+  }
+
+  const withSlash = value.startsWith("/") ? value : `/${value}`;
+  return withSlash.length > 1 ? withSlash.replace(/\/+$/g, "") : "/";
+}
+
+function pathSegments(path) {
+  const normalized = normalizeMatchPath(path);
+  if (normalized === "*" || normalized === "/") {
+    return [];
+  }
+
+  return normalized.replace(/^\/+|\/+$/g, "").split("/");
+}
+
+function decodeRouteSegment(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+
+function matchRoutePath(pattern, pathname) {
+  const normalizedPattern = normalizeMatchPath(pattern);
+  if (normalizedPattern === "*") {
+    return { params: {} };
+  }
+
+  const patternSegments = pathSegments(normalizedPattern);
+  const pathnameSegments = pathSegments(pathname);
+  const params = {};
+
+  for (let index = 0; index < patternSegments.length; index += 1) {
+    const patternSegment = patternSegments[index];
+    const pathnameSegment = pathnameSegments[index];
+
+    if (patternSegment === "*") {
+      params["*"] = pathnameSegments.slice(index).map(decodeRouteSegment).join("/");
+      return { params };
+    }
+
+    if (pathnameSegment === undefined) {
+      return null;
+    }
+
+    if (patternSegment.startsWith(":")) {
+      const name = patternSegment.slice(1);
+      if (!name) {
+        return null;
+      }
+      params[name] = decodeRouteSegment(pathnameSegment);
+      continue;
+    }
+
+    if (patternSegment !== pathnameSegment) {
+      return null;
+    }
+  }
+
+  if (patternSegments.length !== pathnameSegments.length) {
+    return null;
+  }
+
+  return { params };
+}
+
+function routeChildren(children) {
+  const routes = [];
+  for (const child of toChildArray(children)) {
+    if (!child || typeof child !== "object") {
+      continue;
+    }
+
+    if (child.props?.path !== undefined) {
+      routes.push(child);
+      continue;
+    }
+
+    if (child.props?.children !== undefined) {
+      routes.push(...routeChildren(child.props.children));
+    }
+  }
+  return routes;
+}
+
+function shouldHandleLinkClick(event, target) {
+  return (
+    !event.defaultPrevented &&
+    event.button === 0 &&
+    !event.altKey &&
+    !event.ctrlKey &&
+    !event.metaKey &&
+    !event.shiftKey &&
+    (!target || target === "_self") &&
+    !event.currentTarget?.hasAttribute("download")
+  );
+}
+
 function normalizeReturnTo(value) {
   if (!value) {
     return null;
@@ -746,6 +962,72 @@ export function SignInWithGoogle({
   );
 }
 
+export function Router({ children } = {}) {
+  const location = useBrowserLocation();
+  return h(RouterContext.Provider, { value: { location, navigate } }, children);
+}
+
+export function Routes({ children } = {}) {
+  const location = useLocation();
+  const routes = routeChildren(children);
+  for (const route of routes) {
+    const match = matchRoutePath(route.props.path, location.pathname);
+    if (!match) {
+      continue;
+    }
+
+    return h(RouteContext.Provider, { value: match }, route.props.element ?? null);
+  }
+
+  return null;
+}
+
+export function Route() {
+  return null;
+}
+
+export function Link({ children, onClick, replace = false, target, to, ...props } = {}) {
+  const href = hrefForRoute(to);
+  return h(
+    "a",
+    {
+      ...props,
+      href,
+      onClick: (event) => {
+        onClick?.(event);
+        if (!shouldHandleLinkClick(event, target)) {
+          return;
+        }
+
+        const parsed = new URL(href, window.location.href);
+        if (parsed.origin !== window.location.origin) {
+          return;
+        }
+
+        event.preventDefault();
+        navigate(to, { replace });
+      },
+      target
+    },
+    children
+  );
+}
+
+export function useLocation() {
+  const context = useContext(RouterContext);
+  const fallback = useBrowserLocation();
+  return context?.location ?? fallback;
+}
+
+export function useNavigate() {
+  const context = useContext(RouterContext);
+  return context?.navigate ?? navigate;
+}
+
+export function useParams() {
+  return useContext(RouteContext).params;
+}
+
 export function useQuery(name) {
   const [value, setValue] = useState(queryValues.get(name) ?? []);
 

package/src/version.js

@@ -1 +1 @@
-export const LAKEBED_VERSION = "0.0.19";
+export const LAKEBED_VERSION = "0.0.20";