@codemation/next-host 0.0.1

package/src/middleware/CodemationNextHostMiddlewarePathRules.ts

@@ -0,0 +1,31 @@
+/** Path classification for Next.js middleware (Edge). Extracted for unit tests. */
+export class CodemationNextHostMiddlewarePathRules {
+  static isFrameworkAuthRoute(pathname: string): boolean {
+    return pathname.startsWith("/api/auth");
+  }
+
+  static isAnonymousApiRoute(pathname: string): boolean {
+    return (
+      pathname.startsWith("/api/webhooks") ||
+      pathname === "/api/dev/runtime" ||
+      pathname === "/api/dev/bootstrap-summary" ||
+      pathname === "/api/users/invites/verify" ||
+      pathname === "/api/users/invites/accept" ||
+      // Anonymous whitelabel logo (login page `<img>`; same path as ApiPaths.whitelabelLogo() / Hono anonymous policy).
+      pathname === "/api/whitelabel/logo"
+    );
+  }
+
+  static isPublicUiRoute(pathname: string): boolean {
+    return pathname === "/login" || pathname.startsWith("/login/") || pathname.startsWith("/invite/");
+  }
+
+  static isNextStaticAsset(pathname: string): boolean {
+    return (
+      pathname.startsWith("/_next") ||
+      pathname === "/favicon.ico" ||
+      pathname.startsWith("/favicon.ico") ||
+      pathname.startsWith("/public")
+    );
+  }
+}

package/src/providers/CodemationSessionProvider.tsx

@@ -0,0 +1,23 @@
+"use client";
+
+import type { Session } from "next-auth";
+import { SessionProvider } from "next-auth/react";
+import { Component, type ReactNode } from "react";
+
+type CodemationSessionRootProps = Readonly<{
+  children: ReactNode;
+  enabled: boolean;
+  /**
+   * Server-resolved session so the first client paint matches SSR (avoids `useSession` hydration mismatches).
+   */
+  session: Session | null;
+}>;
+
+export class CodemationSessionRoot extends Component<CodemationSessionRootProps> {
+  override render(): ReactNode {
+    if (!this.props.enabled) {
+      return this.props.children;
+    }
+    return <SessionProvider session={this.props.session}>{this.props.children}</SessionProvider>;
+  }
+}

package/src/providers/Providers.tsx

@@ -0,0 +1,36 @@
+import type { Logger } from "@codemation/host-src/application/logging/Logger";
+
+import { BrowserLoggerFactory } from "@codemation/host-src/infrastructure/logging/BrowserLoggerFactory";
+import { logLevelPolicyFactory } from "@codemation/host-src/infrastructure/logging/LogLevelPolicyFactory";
+
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+
+import { useState, type ReactNode } from "react";
+
+import { RealtimeBoundary } from "./RealtimeBoundary";
+
+export function Providers(args: Readonly<{ children: ReactNode; websocketPort?: string }>) {
+  const { children, websocketPort } = args;
+  const defaultQueryStaleTimeMs = process.env.NODE_ENV === "development" ? 30_000 : 0;
+  const [loggerFactory] = useState(() => new BrowserLoggerFactory(logLevelPolicyFactory.create()));
+  const [realtimeLogger] = useState<Logger>(() => loggerFactory.create("workflow-realtime.frontend"));
+  const [queryClient] = useState(
+    () =>
+      new QueryClient({
+        defaultOptions: {
+          queries: {
+            staleTime: defaultQueryStaleTimeMs,
+            refetchOnWindowFocus: false,
+          },
+        },
+      }),
+  );
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <RealtimeBoundary logger={realtimeLogger} websocketPort={websocketPort}>
+        {children}
+      </RealtimeBoundary>
+    </QueryClientProvider>
+  );
+}

package/src/providers/RealtimeBoundary.tsx

@@ -0,0 +1,17 @@
+import type { Logger } from "@codemation/host-src/application/logging/Logger";
+
+import type { ReactNode } from "react";
+
+import { WorkflowRealtimeProvider } from "../features/workflows/hooks/realtime/realtime";
+
+export function RealtimeBoundary(args: Readonly<{ children: ReactNode; logger: Logger; websocketPort?: string }>) {
+  const { children, logger, websocketPort } = args;
+  if (typeof window === "undefined") {
+    return <>{children}</>;
+  }
+  return (
+    <WorkflowRealtimeProvider logger={logger} websocketPort={websocketPort}>
+      {children}
+    </WorkflowRealtimeProvider>
+  );
+}

package/src/providers/WhitelabelProvider.tsx

@@ -0,0 +1,22 @@
+"use client";
+
+import { createContext, useContext, type ReactNode } from "react";
+
+import type { CodemationWhitelabelSnapshot } from "../whitelabel/CodemationWhitelabelSnapshot";
+
+const defaultSnapshot: CodemationWhitelabelSnapshot = {
+  productName: "Codemation",
+  logoUrl: null,
+};
+
+const WhitelabelContext = createContext<CodemationWhitelabelSnapshot>(defaultSnapshot);
+
+export function WhitelabelProvider(
+  args: Readonly<{ children: ReactNode; value: CodemationWhitelabelSnapshot }>,
+): ReactNode {
+  return <WhitelabelContext.Provider value={args.value}>{args.children}</WhitelabelContext.Provider>;
+}
+
+export function useWhitelabel(): CodemationWhitelabelSnapshot {
+  return useContext(WhitelabelContext);
+}

package/src/server/CodemationAuthPrismaClient.ts

@@ -0,0 +1,21 @@
+import type { PrismaClient } from "@codemation/host-src/infrastructure/persistence/generated/prisma-client/client.js";
+
+export class CodemationAuthPrismaClient {
+  static async resolveShared(): Promise<PrismaClient> {
+    return await CodemationAuthPrismaClient.resolveFromPreparedNextHost();
+  }
+
+  private static async resolveFromPreparedNextHost(): Promise<PrismaClient> {
+    const { CodemationNextHost } = await import("./CodemationNextHost");
+    try {
+      return await CodemationNextHost.shared.getPreparedPrismaClient();
+    } catch {
+      throw new Error(
+        [
+          "Codemation authentication requires prepared runtime database persistence.",
+          "Ensure the Next host has been prepared with PostgreSQL or PGlite before creating the auth adapter.",
+        ].join(" "),
+      );
+    }
+  }
+}

package/src/server/CodemationNextHost.ts

@@ -0,0 +1,379 @@
+import type { Container } from "@codemation/core";
+import type { CodemationAuthConfig, CodemationPlugin } from "@codemation/host";
+import {
+  ApplicationTokens,
+  CodemationApplication,
+  CodemationBootstrapRequest,
+  CodemationFrontendBootstrapRequest,
+  CodemationHonoApiApp,
+  CodemationPluginListMerger,
+  logLevelPolicyFactory,
+  ServerLoggerFactory,
+  WorkflowWebsocketServer,
+} from "@codemation/host/next/server";
+import type { PrismaClient } from "@codemation/host-src/infrastructure/persistence/generated/prisma-client/client.js";
+import { CodemationTsyringeTypeInfoRegistrar } from "@codemation/host/dev-server-sidecar";
+import type { CodemationConsumerApp } from "@codemation/host-src/presentation/server/CodemationConsumerAppResolver";
+import type { Hono } from "hono";
+import { access, readFile, stat } from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+import { CodemationWhitelabelSnapshotFactory } from "../whitelabel/CodemationWhitelabelSnapshotFactory";
+import type { CodemationWhitelabelSnapshot } from "../whitelabel/CodemationWhitelabelSnapshot";
+
+export type CodemationNextHostContext = Readonly<{
+  application: CodemationApplication;
+  authConfig: CodemationAuthConfig | undefined;
+  buildVersion: string;
+  consumerRoot: string;
+  repoRoot: string;
+  workflowSources: ReadonlyArray<string>;
+  /** Derived from the loaded consumer manifest config (same source as {@link CodemationApplication.useConfig}). */
+  whitelabelSnapshot: CodemationWhitelabelSnapshot;
+}>;
+
+type CodemationNextHostGlobal = typeof globalThis & {
+  __codemationNextHost__?: CodemationNextHost;
+};
+
+type CodemationConsumerBuildManifest = Readonly<{
+  buildVersion: string;
+  consumerRoot: string;
+  entryPath: string;
+  pluginEntryPath: string;
+  workflowSourcePaths: ReadonlyArray<string>;
+}>;
+
+/**
+ * Next-hosted consumer runtime: one loaded context per process.
+ * In development, the consumer manifest `buildVersion` is re-read on each prepare; when it changes
+ * (e.g. after `codemation build` / dev publish), the previous {@link CodemationApplication} is torn
+ * down so whitelabel and config updates apply without restarting Next.
+ */
+export class CodemationNextHost {
+  private readonly pluginListMerger = new CodemationPluginListMerger();
+  private nextApiApp: Hono | null = null;
+  private nextApiAppBuildVersion: string | null = null;
+  private contextPromise: Promise<CodemationNextHostContext> | null = null;
+  /** Tracks which manifest `buildVersion` the current {@link contextPromise} was built from (dev invalidation). */
+  private loadedManifestBuildVersion: string | null = null;
+  /** Single-flight so concurrent `prepare()` calls do not create duplicate application graphs. */
+  private prepareInFlight: Promise<CodemationNextHostContext> | null = null;
+  private sharedWorkflowWebsocketServer: WorkflowWebsocketServer | null = null;
+
+  static get shared(): CodemationNextHost {
+    const globalState = globalThis as CodemationNextHostGlobal;
+    if (!globalState.__codemationNextHost__) {
+      globalState.__codemationNextHost__ = new CodemationNextHost();
+    }
+    return globalState.__codemationNextHost__;
+  }
+
+  async prepare(): Promise<CodemationNextHostContext> {
+    if (this.prepareInFlight) {
+      return this.prepareInFlight;
+    }
+    this.prepareInFlight = this.prepareInternal();
+    try {
+      return await this.prepareInFlight;
+    } finally {
+      this.prepareInFlight = null;
+    }
+  }
+
+  private async prepareInternal(): Promise<CodemationNextHostContext> {
+    const manifest = await this.resolveBuildManifest();
+    if (this.shouldReloadContextForDev(manifest)) {
+      await this.teardownLoadedContext();
+    }
+    if (!this.contextPromise) {
+      const context = await this.createContext(manifest);
+      this.loadedManifestBuildVersion = manifest.buildVersion;
+      this.contextPromise = Promise.resolve(context);
+    }
+    return await this.contextPromise;
+  }
+
+  private shouldReloadContextForDev(manifest: CodemationConsumerBuildManifest): boolean {
+    if (process.env.NODE_ENV === "production") {
+      return false;
+    }
+    if (this.contextPromise === null || this.loadedManifestBuildVersion === null) {
+      return false;
+    }
+    return this.loadedManifestBuildVersion !== manifest.buildVersion;
+  }
+
+  private async teardownLoadedContext(): Promise<void> {
+    if (!this.contextPromise) {
+      return;
+    }
+    try {
+      const ctx = await this.contextPromise;
+      await ctx.application.stop({ stopWebsocketServer: false });
+    } catch {
+      // Best-effort teardown before reloading consumer output.
+    }
+    this.contextPromise = null;
+    this.nextApiApp = null;
+    this.nextApiAppBuildVersion = null;
+    this.loadedManifestBuildVersion = null;
+  }
+
+  async getContainer(): Promise<Container> {
+    return (await this.prepare()).application.getContainer();
+  }
+
+  async getPreparedPrismaClient(): Promise<PrismaClient> {
+    const preparedContext = await this.prepare();
+    const existingPrisma = this.tryResolvePreparedPrismaClient(preparedContext);
+    if (existingPrisma) {
+      return existingPrisma;
+    }
+    await this.teardownLoadedContext();
+    const refreshedContext = await this.prepare();
+    const refreshedPrisma = this.tryResolvePreparedPrismaClient(refreshedContext);
+    if (refreshedPrisma) {
+      return refreshedPrisma;
+    }
+    throw new Error(
+      [
+        "Codemation authentication requires prepared runtime database persistence.",
+        "Ensure the Next host has been prepared with PostgreSQL or PGlite before creating the auth adapter.",
+      ].join(" "),
+    );
+  }
+
+  /**
+   * Resolved whitelabel for Server Components (sidebar, login, metadata). Requires {@link prepare} first.
+   * Uses the snapshot captured from the built consumer config so branding matches `codemation.config` even if DI
+   * resolution were ever misaligned in a bundled server graph.
+   */
+  async getWhitelabelSnapshot(): Promise<CodemationWhitelabelSnapshot> {
+    const context = await this.prepare();
+    return context.whitelabelSnapshot;
+  }
+
+  /**
+   * Entry point for all `/api/**` traffic when the App Router route is not proxying to the dev gateway.
+   */
+  async fetchApi(request: Request): Promise<Response> {
+    const context = await this.prepare();
+    const app = this.resolveNextApiApp(context);
+    return app.fetch(request);
+  }
+
+  private resolveNextApiApp(context: CodemationNextHostContext): Hono {
+    if (this.nextApiApp && this.nextApiAppBuildVersion === context.buildVersion) {
+      return this.nextApiApp;
+    }
+    const coreApp = context.application.getContainer().resolve(CodemationHonoApiApp).getHono();
+    this.nextApiApp = coreApp;
+    this.nextApiAppBuildVersion = context.buildVersion;
+    return coreApp;
+  }
+
+  private async createContext(buildManifest: CodemationConsumerBuildManifest): Promise<CodemationNextHostContext> {
+    const consumerRoot = path.resolve(buildManifest.consumerRoot);
+    const repoRoot = await this.detectWorkspaceRoot(consumerRoot);
+    const prismaCliOverride = await this.resolvePrismaCliOverride();
+    const hostPackageRoot = path.resolve(repoRoot, "packages", "host");
+    if (prismaCliOverride) {
+      process.env.CODEMATION_PRISMA_CLI_PATH = prismaCliOverride;
+    }
+    process.env.CODEMATION_HOST_PACKAGE_ROOT = hostPackageRoot;
+    process.env.CODEMATION_PRISMA_CONFIG_PATH = path.resolve(hostPackageRoot, "prisma.config.ts");
+    const resolvedConsumerApp = await this.loadBuiltConsumerApp(buildManifest.entryPath);
+    const whitelabelSnapshot = CodemationWhitelabelSnapshotFactory.fromConsumerConfig(resolvedConsumerApp.config);
+    const env = { ...process.env };
+    if (prismaCliOverride) {
+      env.CODEMATION_PRISMA_CLI_PATH = prismaCliOverride;
+    }
+    env.CODEMATION_HOST_PACKAGE_ROOT = hostPackageRoot;
+    env.CODEMATION_PRISMA_CONFIG_PATH = path.resolve(hostPackageRoot, "prisma.config.ts");
+    env.CODEMATION_CONSUMER_ROOT = consumerRoot;
+    const isRuntimeDevProxy = Boolean(process.env.CODEMATION_RUNTIME_DEV_URL?.trim());
+    const bootstrapRequest = new CodemationBootstrapRequest({
+      consumerRoot,
+      repoRoot,
+      env,
+      workflowSources: resolvedConsumerApp.workflowSources,
+    });
+    const application = new CodemationApplication();
+    application.useSharedWorkflowWebsocketServer(this.resolveSharedWorkflowWebsocketServer());
+    const discoveredPlugins = await this.loadDiscoveredPlugins(buildManifest);
+
+    application.useConfig(resolvedConsumerApp.config);
+    if (discoveredPlugins.length > 0) {
+      application.usePlugins(this.pluginListMerger.merge(resolvedConsumerApp.config.plugins ?? [], discoveredPlugins));
+    }
+    await application.applyPlugins(bootstrapRequest);
+    await application.prepareContainer(bootstrapRequest);
+    const typeInfoRegistrar = new CodemationTsyringeTypeInfoRegistrar(application.getContainer());
+    typeInfoRegistrar.registerWorkflowDefinitions(resolvedConsumerApp.config.workflows ?? []);
+    await application.bootFrontend(
+      new CodemationFrontendBootstrapRequest({
+        bootstrap: bootstrapRequest,
+        skipPresentationServers: isRuntimeDevProxy,
+      }),
+    );
+    return {
+      application,
+      authConfig: resolvedConsumerApp.config.auth,
+      buildVersion: buildManifest.buildVersion,
+      consumerRoot,
+      repoRoot,
+      workflowSources: resolvedConsumerApp.workflowSources,
+      whitelabelSnapshot,
+    };
+  }
+
+  private tryResolvePreparedPrismaClient(context: CodemationNextHostContext): PrismaClient | null {
+    const container = context.application.getContainer();
+    if (!container.isRegistered(ApplicationTokens.PrismaClient, true)) {
+      return null;
+    }
+    return container.resolve(ApplicationTokens.PrismaClient);
+  }
+
+  private async detectWorkspaceRoot(startDirectory: string): Promise<string> {
+    let currentDirectory = path.resolve(startDirectory);
+    while (true) {
+      if (await this.exists(path.resolve(currentDirectory, "pnpm-workspace.yaml"))) {
+        return currentDirectory;
+      }
+      const parentDirectory = path.dirname(currentDirectory);
+      if (parentDirectory === currentDirectory) {
+        return startDirectory;
+      }
+      currentDirectory = parentDirectory;
+    }
+  }
+
+  private async resolvePrismaCliOverride(): Promise<string | null> {
+    const candidate = path.resolve(process.cwd(), "node_modules", "prisma", "build", "index.js");
+    return (await this.exists(candidate)) ? candidate : null;
+  }
+
+  private async resolveBuildManifest(): Promise<CodemationConsumerBuildManifest> {
+    const manifestPath = await this.resolveBuildManifestPath();
+    const manifestText = await readFile(manifestPath, "utf8");
+    const parsedManifest = JSON.parse(manifestText) as Partial<CodemationConsumerBuildManifest>;
+    if (
+      typeof parsedManifest.buildVersion !== "string" ||
+      typeof parsedManifest.consumerRoot !== "string" ||
+      typeof parsedManifest.entryPath !== "string" ||
+      typeof parsedManifest.pluginEntryPath !== "string" ||
+      !Array.isArray(parsedManifest.workflowSourcePaths)
+    ) {
+      throw new Error(`Invalid Codemation consumer build manifest at ${manifestPath}.`);
+    }
+    const buildManifest: CodemationConsumerBuildManifest = {
+      buildVersion: parsedManifest.buildVersion,
+      consumerRoot: path.resolve(parsedManifest.consumerRoot),
+      entryPath: path.resolve(parsedManifest.entryPath),
+      pluginEntryPath: path.resolve(parsedManifest.pluginEntryPath),
+      workflowSourcePaths: parsedManifest.workflowSourcePaths.filter(
+        (workflowSourcePath): workflowSourcePath is string => typeof workflowSourcePath === "string",
+      ),
+    };
+    if (!(await this.exists(buildManifest.entryPath))) {
+      throw new Error(
+        `Built consumer output not found at ${buildManifest.entryPath}. Run \`codemation build\` before starting the Next host.`,
+      );
+    }
+    if (!(await this.exists(buildManifest.pluginEntryPath))) {
+      throw new Error(
+        `Discovered plugins output not found at ${buildManifest.pluginEntryPath}. Run \`codemation build\` before starting the Next host.`,
+      );
+    }
+    return buildManifest;
+  }
+
+  private async resolveBuildManifestPath(): Promise<string> {
+    const configuredPath = process.env.CODEMATION_CONSUMER_OUTPUT_MANIFEST_PATH;
+    if (!configuredPath || configuredPath.trim().length === 0) {
+      throw new Error(
+        "Missing CODEMATION_CONSUMER_OUTPUT_MANIFEST_PATH. Start the Next host through `codemation dev` or `codemation build`.",
+      );
+    }
+    const resolvedPath = path.resolve(configuredPath);
+    if (!(await this.exists(resolvedPath))) {
+      throw new Error(
+        `Build manifest not found at ${resolvedPath}. Run \`codemation build\` before starting the Next host.`,
+      );
+    }
+    return resolvedPath;
+  }
+
+  private async loadBuiltConsumerApp(outputPath: string): Promise<CodemationConsumerApp> {
+    const importedModule = (await import(
+      /* webpackIgnore: true */ await this.createRuntimeImportSpecifier(outputPath)
+    )) as {
+      codemationConsumerApp?: CodemationConsumerApp;
+      default?: CodemationConsumerApp;
+    };
+    const consumerApp = importedModule.codemationConsumerApp ?? importedModule.default;
+    if (!consumerApp) {
+      throw new Error(`Built consumer output did not export a Codemation consumer app: ${outputPath}`);
+    }
+    return consumerApp;
+  }
+
+  private async loadDiscoveredPlugins(
+    buildManifest: CodemationConsumerBuildManifest,
+  ): Promise<ReadonlyArray<CodemationPlugin>> {
+    const resolvedPath = path.resolve(buildManifest.pluginEntryPath);
+    if (!(await this.exists(resolvedPath))) {
+      return [];
+    }
+    const importedModule = (await import(
+      /* webpackIgnore: true */ await this.createRuntimeImportSpecifier(resolvedPath)
+    )) as {
+      codemationDiscoveredPlugins?: ReadonlyArray<CodemationPlugin>;
+      default?: ReadonlyArray<CodemationPlugin>;
+    };
+    return importedModule.codemationDiscoveredPlugins ?? importedModule.default ?? [];
+  }
+
+  private async createRuntimeImportSpecifier(filePath: string): Promise<string> {
+    const fileUrl = pathToFileURL(filePath);
+    const fileStats = await stat(filePath);
+    fileUrl.searchParams.set("t", String(fileStats.mtimeMs));
+    return fileUrl.href;
+  }
+
+  private resolveSharedWorkflowWebsocketServer(): WorkflowWebsocketServer {
+    if (!this.sharedWorkflowWebsocketServer) {
+      this.sharedWorkflowWebsocketServer = new WorkflowWebsocketServer(
+        this.resolveWebSocketPort(),
+        this.resolveWebSocketBindHost(),
+        new ServerLoggerFactory(logLevelPolicyFactory).create("codemation-websocket.server"),
+      );
+    }
+    return this.sharedWorkflowWebsocketServer;
+  }
+
+  private resolveWebSocketPort(): number {
+    const rawPort = process.env.CODEMATION_WS_PORT ?? process.env.VITE_CODEMATION_WS_PORT;
+    const parsedPort = Number(rawPort);
+    if (Number.isInteger(parsedPort) && parsedPort > 0) {
+      return parsedPort;
+    }
+    return 3001;
+  }
+
+  private resolveWebSocketBindHost(): string {
+    return process.env.CODEMATION_WS_BIND_HOST ?? "0.0.0.0";
+  }
+
+  private async exists(filePath: string): Promise<boolean> {
+    try {
+      await access(filePath);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}

package/src/shell/AppLayout.tsx

@@ -0,0 +1,141 @@
+"use client";
+
+import { Component, type ReactNode } from "react";
+
+import { Button } from "@/components/ui/button";
+import { cn } from "@/lib/utils";
+
+import { AppLayoutNavItems } from "./AppLayoutNavItems";
+import { AppLayoutPageHeader } from "./AppLayoutPageHeader";
+import { AppLayoutSidebarBrand } from "./AppLayoutSidebarBrand";
+import { AppMainContent } from "./AppMainContent";
+import { IconChevronLeft, IconChevronRight } from "./appLayoutSidebarIcons";
+
+const SIDEBAR_WIDTH_KEY = "codemation-sidebar-width";
+const SIDEBAR_COLLAPSED_KEY = "codemation-sidebar-collapsed";
+const MIN_SIDEBAR_WIDTH = 12;
+const MAX_SIDEBAR_WIDTH = 28;
+const DEFAULT_SIDEBAR_WIDTH = 16;
+
+export interface AppLayoutProps {
+  readonly children: ReactNode;
+}
+
+type AppLayoutState = {
+  sidebarWidth: number;
+  sidebarCollapsed: boolean;
+  isResizing: boolean;
+};
+
+function loadSidebarWidth(): number {
+  if (typeof window === "undefined") return DEFAULT_SIDEBAR_WIDTH;
+  const stored = localStorage.getItem(SIDEBAR_WIDTH_KEY);
+  const n = stored ? Number.parseFloat(stored) : DEFAULT_SIDEBAR_WIDTH;
+  return Number.isFinite(n) ? Math.min(MAX_SIDEBAR_WIDTH, Math.max(MIN_SIDEBAR_WIDTH, n)) : DEFAULT_SIDEBAR_WIDTH;
+}
+
+function loadSidebarCollapsed(): boolean {
+  if (typeof window === "undefined") return false;
+  return localStorage.getItem(SIDEBAR_COLLAPSED_KEY) === "1";
+}
+
+export class AppLayout extends Component<AppLayoutProps, AppLayoutState> {
+  override state: AppLayoutState = {
+    sidebarWidth: DEFAULT_SIDEBAR_WIDTH,
+    sidebarCollapsed: false,
+    isResizing: false,
+  };
+
+  override componentDidMount(): void {
+    this.setState({
+      sidebarWidth: loadSidebarWidth(),
+      sidebarCollapsed: loadSidebarCollapsed(),
+    });
+  }
+
+  private handleResizeStart = (e: React.MouseEvent): void => {
+    e.preventDefault();
+    this.setState({ isResizing: true });
+    const onMove = (moveEvent: MouseEvent): void => {
+      const rem = moveEvent.clientX / 16;
+      const w = Math.min(MAX_SIDEBAR_WIDTH, Math.max(MIN_SIDEBAR_WIDTH, rem));
+      this.setState({ sidebarWidth: w });
+      localStorage.setItem(SIDEBAR_WIDTH_KEY, String(w));
+    };
+    const onUp = (): void => {
+      this.setState({ isResizing: false });
+      document.removeEventListener("mousemove", onMove);
+      document.removeEventListener("mouseup", onUp);
+      document.body.style.cursor = "";
+      document.body.style.userSelect = "";
+    };
+    document.body.style.cursor = "col-resize";
+    document.body.style.userSelect = "none";
+    document.addEventListener("mousemove", onMove);
+    document.addEventListener("mouseup", onUp);
+  };
+
+  private handleToggleCollapse = (): void => {
+    this.setState((s) => {
+      const next = !s.sidebarCollapsed;
+      localStorage.setItem(SIDEBAR_COLLAPSED_KEY, next ? "1" : "0");
+      return { sidebarCollapsed: next };
+    });
+  };
+
+  override render(): ReactNode {
+    const { children } = this.props;
+    const { sidebarWidth, sidebarCollapsed, isResizing } = this.state;
+    const widthRem = sidebarCollapsed ? 3.5 : sidebarWidth;
+    return (
+      <div className={cn("flex h-screen min-h-0 overflow-hidden", isResizing && "select-none")}>
+        <aside
+          className="relative flex flex-col border-r border-sidebar-border bg-sidebar text-sidebar-foreground transition-[width,min-width] duration-200 ease-in-out"
+          style={{ width: `${widthRem}rem`, minWidth: `${widthRem}rem` }}
+          data-testid="app-sidebar"
+        >
+          <div className="flex h-14 shrink-0 items-center justify-between border-b border-sidebar-border px-4">
+            <AppLayoutSidebarBrand collapsed={sidebarCollapsed} />
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon-sm"
+              className="text-muted-foreground hover:bg-sidebar-accent hover:text-sidebar-foreground"
+              onClick={this.handleToggleCollapse}
+              aria-label={sidebarCollapsed ? "Expand sidebar" : "Collapse sidebar"}
+              data-testid="sidebar-toggle"
+            >
+              {sidebarCollapsed ? <IconChevronRight /> : <IconChevronLeft />}
+            </Button>
+          </div>
+          <nav
+            className={cn(
+              "flex min-h-0 flex-1 flex-col gap-1 overflow-x-hidden overflow-y-auto p-3",
+              sidebarCollapsed && "[scrollbar-width:none] [&::-webkit-scrollbar]:hidden",
+            )}
+            aria-label="Main navigation"
+          >
+            <AppLayoutNavItems collapsed={sidebarCollapsed} />
+          </nav>
+          {!sidebarCollapsed && (
+            <div
+              className={cn(
+                "absolute top-0 right-0 h-full w-1 cursor-col-resize bg-transparent hover:bg-primary/30",
+                isResizing && "bg-primary/30",
+              )}
+              onMouseDown={this.handleResizeStart}
+              role="separator"
+              aria-orientation="vertical"
+              aria-label="Resize sidebar"
+              data-testid="sidebar-resize-handle"
+            />
+          )}
+        </aside>
+        <main className="flex min-h-0 min-w-0 flex-1 flex-col overflow-hidden bg-background">
+          <AppLayoutPageHeader />
+          <AppMainContent>{children}</AppMainContent>
+        </main>
+      </div>
+    );
+  }
+}