create-astram-app 0.1.3 → 0.2.0

package/template/frontend/src/platform/shieldTransport.js

@@ -0,0 +1,172 @@
+/**
+ * shieldTransport — the WEB `Transport` implementation for `@astram/sdk`'s
+ * `ShieldClient` (Phase E slice 1). Wraps the SAME injected `http` client every other
+ * frontend service uses (`createWebHttpClient` — see `platform/httpClient.js`), mapping
+ * HTTP outcomes to the SDK's `Transport` contract (`packages/sdk/src/transport.ts`).
+ *
+ * ⛔ THE CRITICAL FRAMING: this transport (and the projection it fetches) is a UX
+ * CONVENIENCE, NEVER the security boundary. The server's `decide()` on every
+ * `@Classified` route is the REAL enforcement — a tampered/stale frontend simply hits a
+ * 403 there. This file must never grow security logic; it only classifies an HTTP
+ * response into the SDK's fail-closed vocabulary so the UI can hide/disable actions the
+ * caller can't use.
+ *
+ * HTTP -> outcome classification for `fetchProjection` (per the SDK's ADR-0016 contract):
+ *   - fetch threw / network failure  → `http.get` never throws; it resolves
+ *     `{ ok:false, status:0, data:null }` (see httpClient.js's catch branches) — TRANSIENT.
+ *   - status 0 (network/transport failure)  → TRANSIENT → throw `TransportUnavailableError`.
+ *   - status >= 500 (server outage, incl. our own 503 on a loadCoarseGrants store outage)
+ *                                            → TRANSIENT → throw `TransportUnavailableError`.
+ *   - status 401 (missing/invalid/expired token) → a SESSION concern, NOT a permission
+ *     deny — the engine must not read "no token" as "no permissions" and cache an empty
+ *     deny-everything projection past a token refresh. Treated as TRANSIENT (throw), so
+ *     the engine holds its last-good/empty projection and the NEXT session-established
+ *     fetch (post-refresh/re-login) supersedes it, rather than baking in a deny.
+ *   - a real 403 (or any other non-5xx !ok)  → TERMINAL deny → return an EMPTY projection
+ *     `{ principalId:'', facts:[], projectedAt: Date.now() }` (deny-all).
+ *   - 200 with a body                        → return `r.data` (the projection) AS-IS.
+ *
+ * `check` / `issueStepUp` / `satisfyStepUp` are DEFERRED (locked decision — slice 1 does
+ * not implement per-check gating or step-up). Each stays a throwing/deny stub; the SDK
+ * engine already fail-closes around an absent/erroring capability (see `client.ts`'s
+ * `checkOnce` — a throw that isn't `TransportUnavailableError` degrades to a safe
+ * `deny`, and `issueStepUpForScope` swallows a throw to `null`).
+ *
+ * `currentVersion()` (Phase E slice 2 — ADR-0011 frontend twin) IS implemented, opting
+ * this transport into `client.ts`'s `isVersionAware` duck-type so `ShieldClient` can
+ * detect a backend permission-version BUMP and auto-refetch the projection.
+ *
+ * ⚠️ CONTRACT MATCHED (read `client.ts`'s `isProjectionFresh`, packages/sdk/src/client.ts
+ * lines 385-395, before touching this): `isProjectionFresh` calls
+ * `await transport.currentVersion()` completely UNGUARDED — no try/catch wraps that call,
+ * neither in `isProjectionFresh` itself nor at its one call site in
+ * `fetchAndCacheProjection` (the surrounding try/catch there only wraps the LATER
+ * `transport.fetchProjection` call). A `currentVersion()` THROW would therefore propagate
+ * all the way out of `getAuthFacts` UNCAUGHT — breaking the SDK's documented "getAuthFacts
+ * never throws" fail-closed guarantee that `AuthContext.refreshAuthFacts` relies on. So
+ * this implementation MUST NEVER THROW.
+ *
+ * Freshness is decided by `cached.permissionsVersion >= current` (client.ts:392) — a
+ * cache is stale (refetch) whenever `current` is NOT LESS than the cached version. So the
+ * fail-closed way to say "I can't tell you the real version" is to RETURN a number that
+ * can never compare `<=` any real cached version: `Number.POSITIVE_INFINITY`. That makes
+ * every comparison `cached.permissionsVersion >= Infinity` evaluate `false` — always
+ * stale, always refetch — mirroring the SDK's own NaN-version adversarial test
+ * (`adversarial.test.ts` "ATTACK 2": a version that can never compare `>=` current is
+ * always treated as stale, never phantom-fresh). This is fail-closed WITHOUT throwing:
+ * an unreadable version can never be mistaken for "cache is fresh".
+ *
+ * A non-ok probe (status 0 network failure, 401 session concern, >=500 server/store
+ * outage) is exactly this "can't-know" case → returns `Number.POSITIVE_INFINITY` (forces
+ * a refetch on the NEXT `getAuthFacts` call; it does NOT itself throw or fetch — the
+ * projection refetch, if it also fails transiently, is `fetchProjection`'s concern, which
+ * DOES throw `TransportUnavailableError` and IS caught by the SDK's try/catch).
+ * A 200 with a well-formed numeric `data.version` returns that number. The whole body
+ * is wrapped in try/catch as a defensive backstop (the real `http.get` never rejects,
+ * but this keeps the never-throw contract robust even against a misbehaving/mocked
+ * `http` dependency) — any unexpected throw ALSO resolves `Number.POSITIVE_INFINITY`
+ * rather than escaping.
+ */
+import { TransportUnavailableError } from '@astram/sdk';
+
+const AUTH_FACTS_PATH = '/identity/auth-facts';
+const PERMISSIONS_VERSION_PATH = '/identity/permissions-version';
+
+/**
+ * @param {{ http: import('@astram/frontend-core').HttpClient, getToken: () => string | null | undefined }} deps
+ *   `getToken` is a GETTER (not a captured value) so the transport — built ONCE at
+ *   AuthContext construction — always reads the CURRENT access token, surviving a
+ *   token refresh without being re-created (mirrors AuthContext's `reenrollRef` /
+ *   ref-based-not-snapshot pattern for the same reason).
+ * @returns {import('@astram/sdk').Transport}
+ */
+export function createWebShieldTransport({ http, getToken }) {
+  return {
+    /** @param {string} principalId */
+    async fetchProjection(principalId) {
+      const r = await http.get(AUTH_FACTS_PATH, { bearerToken: getToken() });
+
+      // status 0 (network/fetch failure) or a 5xx (incl. our 503 loadCoarseGrants
+      // outage) or 401 (session concern, not a deny) — all TRANSIENT, never a deny.
+      if (r.status === 0 || r.status >= 500 || r.status === 401) {
+        throw new TransportUnavailableError(
+          `auth-facts projection temporarily unavailable (status ${r.status})`,
+        );
+      }
+
+      // A real 403 (or any other non-2xx that isn't transient) — TERMINAL deny.
+      // Empty projection: no facts for anyone, including the requested principal (the
+      // engine's own emptyProjection uses the SAME shape — see client.ts).
+      if (!r.ok) {
+        return { principalId: '', facts: [], projectedAt: Date.now() };
+      }
+
+      // 200 — the projection as returned by the server, unchanged. `void principalId`:
+      // the endpoint is self-scoped (derives the caller from the bearer token server-
+      // side), so the requested principalId is never sent as a param — see
+      // auth-facts.controller.ts. Keeping the parameter (frozen Transport signature)
+      // but not using it to build the request is intentional, not an oversight.
+      void principalId;
+      return r.data;
+    },
+
+    /**
+     * DEFERRED (locked decision — slice 1 does not wire per-check gating). Always
+     * resolves `deny` rather than throwing, matching the SDK's own no-transport
+     * fail-closed default (`ShieldClient.check`) — a stub capability behaves exactly
+     * like an absent one.
+     */
+    async check(_action, _resource) {
+      void _action;
+      void _resource;
+      return { kind: 'deny', reasonCode: 'not_implemented' };
+    },
+
+    /** DEFERRED (locked decision — no step-up in slice 1). Never issues a challenge. */
+    async issueStepUp(_input) {
+      void _input;
+      return null;
+    },
+
+    /** DEFERRED (locked decision — no step-up in slice 1). Never satisfies. */
+    async satisfyStepUp(input) {
+      return { challengeId: input.challengeId, satisfied: false };
+    },
+
+    /**
+     * Phase E slice 2 (ADR-0011 frontend twin) — the cheap current-permission-version
+     * probe `client.ts`'s `isVersionAware` duck-types for. MUST NEVER THROW (see the
+     * file-header contract note above: `isProjectionFresh`'s call to this is unguarded
+     * by any try/catch, so a throw here would escape `getAuthFacts` uncaught).
+     *
+     * A non-ok probe (status 0 / 401 / >=500 — the SAME "can't-know" set
+     * `fetchProjection` treats as transient) returns `Number.POSITIVE_INFINITY`: it can
+     * never compare `<=` a real cached version, so `cached.permissionsVersion >= current`
+     * is always `false` — always stale, always refetch. Fail-closed WITHOUT throwing:
+     * an unreadable version is never mistaken for "the cache is fresh".
+     *
+     * A malformed 200 body (missing/non-numeric `data.version`) is treated the same
+     * way — `Number.POSITIVE_INFINITY` — rather than trusting a shape a hostile/broken
+     * server didn't actually promise.
+     *
+     * Defensively wrapped in try/catch: the real `createWebHttpClient.get` never
+     * rejects (it catches internally and resolves `{ok:false,status:0,data:null}` —
+     * see httpClient.js), but this guards the never-throw contract even against a
+     * misbehaving/mocked `http` dependency, rather than relying solely on that
+     * upstream guarantee.
+     *
+     * @returns {Promise<number>}
+     */
+    async currentVersion() {
+      try {
+        const r = await http.get(PERMISSIONS_VERSION_PATH, { bearerToken: getToken() });
+        if (!r.ok || typeof r.data?.version !== 'number' || Number.isNaN(r.data.version)) {
+          return Number.POSITIVE_INFINITY;
+        }
+        return r.data.version;
+      } catch {
+        return Number.POSITIVE_INFINITY;
+      }
+    },
+  };
+}

package/template/frontend/src/platform/shieldTransport.test.mjs

@@ -0,0 +1,245 @@
+// shieldTransport.test.mjs — Phase E slice 1: the web Transport's HTTP -> outcome
+// classification (ADR-0016 fail-closed contract). Plain JS over a MOCK http client (the
+// same `{ok, status, data}` shape `createWebHttpClient` resolves — see httpClient.js),
+// no React/DOM/browser globals involved, so this runs directly under Node's built-in
+// test runner with zero new dependencies/config:
+//
+//   node --test src/platform/shieldTransport.test.mjs
+//
+// (There is no existing frontend/shared test harness in this repo at all yet — no
+// vitest/jest config — so this intentionally uses `node:test` + `node:assert` rather
+// than introducing a new toolchain dependency for one file.)
+import { test, describe } from 'node:test';
+import assert from 'node:assert/strict';
+import { createWebShieldTransport } from './shieldTransport.js';
+import { TransportUnavailableError } from '@astram/sdk';
+
+/** A mock `http` whose `.get` resolves exactly the given `{ok, status, data}` result —
+ *  mirrors `createWebHttpClient`'s contract (never throws). */
+function mockHttp(result) {
+  return {
+    get: async (path, opts) => {
+      mockHttp.lastCall = { path, opts };
+      return result;
+    },
+  };
+}
+
+describe('shieldTransport.fetchProjection — HTTP -> outcome classification', () => {
+  test('status 0 (network/fetch failure) -> throws TransportUnavailableError (transient)', async () => {
+    const transport = createWebShieldTransport({
+      http: mockHttp({ ok: false, status: 0, data: null }),
+      getToken: () => 'tok',
+    });
+    await assert.rejects(
+      () => transport.fetchProjection('principal-1'),
+      (err) => err instanceof TransportUnavailableError,
+    );
+  });
+
+  test('a 500 (server outage) -> throws TransportUnavailableError (transient)', async () => {
+    const transport = createWebShieldTransport({
+      http: mockHttp({ ok: false, status: 500, data: null }),
+      getToken: () => 'tok',
+    });
+    await assert.rejects(
+      () => transport.fetchProjection('principal-1'),
+      (err) => err instanceof TransportUnavailableError,
+    );
+  });
+
+  test('a 503 (our own loadCoarseGrants outage mapping) -> throws TransportUnavailableError', async () => {
+    const transport = createWebShieldTransport({
+      http: mockHttp({ ok: false, status: 503, data: { message: 'permission facts store unavailable' } }),
+      getToken: () => 'tok',
+    });
+    await assert.rejects(
+      () => transport.fetchProjection('principal-1'),
+      (err) => err instanceof TransportUnavailableError,
+    );
+  });
+
+  test('a 401 (missing/expired token) -> throws TransportUnavailableError, NOT a deny', async () => {
+    // A 401 is a SESSION concern, not "you have no permissions" — must not resolve to
+    // an empty/deny projection (that would look identical to a real permission deny).
+    const transport = createWebShieldTransport({
+      http: mockHttp({ ok: false, status: 401, data: { error: 'unauthorized' } }),
+      getToken: () => null,
+    });
+    await assert.rejects(
+      () => transport.fetchProjection('principal-1'),
+      (err) => err instanceof TransportUnavailableError,
+    );
+  });
+
+  test('a real 403 (terminal deny) -> resolves an EMPTY projection, does NOT throw', async () => {
+    const transport = createWebShieldTransport({
+      http: mockHttp({ ok: false, status: 403, data: { error: 'forbidden' } }),
+      getToken: () => 'tok',
+    });
+    const projection = await transport.fetchProjection('principal-1');
+    assert.deepEqual(projection.facts, []);
+    assert.equal(projection.principalId, '');
+    assert.equal(typeof projection.projectedAt, 'number');
+  });
+
+  test('any other non-5xx !ok status (e.g. 400) -> resolves an EMPTY projection (terminal, not thrown)', async () => {
+    const transport = createWebShieldTransport({
+      http: mockHttp({ ok: false, status: 400, data: null }),
+      getToken: () => 'tok',
+    });
+    const projection = await transport.fetchProjection('principal-1');
+    assert.deepEqual(projection.facts, []);
+  });
+
+  test('200 with a body -> returns the projection AS-IS', async () => {
+    const serverProjection = {
+      principalId: 'principal-1',
+      facts: [{ action: 'identity:company:read', allowed: true }],
+      projectedAt: 999,
+      permissionsVersion: 4,
+    };
+    const transport = createWebShieldTransport({
+      http: mockHttp({ ok: true, status: 200, data: serverProjection }),
+      getToken: () => 'tok',
+    });
+    const projection = await transport.fetchProjection('principal-1');
+    assert.deepEqual(projection, serverProjection);
+  });
+
+  test('reads the CURRENT token via the getToken getter (not a captured snapshot)', async () => {
+    let currentToken = 'first-token';
+    const http = {
+      get: async (_path, opts) => {
+        http.seenToken = opts.bearerToken;
+        return { ok: true, status: 200, data: { principalId: 'p', facts: [], projectedAt: 1 } };
+      },
+    };
+    const transport = createWebShieldTransport({ http, getToken: () => currentToken });
+
+    await transport.fetchProjection('p');
+    assert.equal(http.seenToken, 'first-token');
+
+    currentToken = 'refreshed-token'; // simulate a token refresh AFTER construction
+    await transport.fetchProjection('p');
+    assert.equal(http.seenToken, 'refreshed-token');
+  });
+});
+
+describe('shieldTransport — deferred capabilities stay fail-closed stubs (slice 1 scope)', () => {
+  test('check() resolves a deny outcome, never throws, never allows', async () => {
+    const transport = createWebShieldTransport({ http: mockHttp({}), getToken: () => 'tok' });
+    const outcome = await transport.check('identity:company:read');
+    assert.equal(outcome.kind, 'deny');
+  });
+
+  test('issueStepUp() resolves null (no challenge)', async () => {
+    const transport = createWebShieldTransport({ http: mockHttp({}), getToken: () => 'tok' });
+    const challenge = await transport.issueStepUp({ action: 'x' });
+    assert.equal(challenge, null);
+  });
+
+  test('satisfyStepUp() resolves { satisfied: false }', async () => {
+    const transport = createWebShieldTransport({ http: mockHttp({}), getToken: () => 'tok' });
+    const result = await transport.satisfyStepUp({
+      challengeId: 'c1',
+      factor: 'totp',
+      proof: '000000',
+    });
+    assert.deepEqual(result, { challengeId: 'c1', satisfied: false });
+  });
+
+});
+
+describe('shieldTransport.currentVersion — ADR-0011 bump-driven refetch probe (Phase E slice 2)', () => {
+  test('is implemented (opts this transport into the SDK\'s isVersionAware duck-type)', () => {
+    const transport = createWebShieldTransport({ http: mockHttp({}), getToken: () => 'tok' });
+    assert.equal(typeof transport.currentVersion, 'function');
+  });
+
+  test('200 with a numeric version -> resolves that number', async () => {
+    const transport = createWebShieldTransport({
+      http: mockHttp({ ok: true, status: 200, data: { version: 7 } }),
+      getToken: () => 'tok',
+    });
+    const version = await transport.currentVersion();
+    assert.equal(version, 7);
+  });
+
+  test('status 0 (network failure) -> resolves +Infinity (never throws — forces stale/refetch)', async () => {
+    const transport = createWebShieldTransport({
+      http: mockHttp({ ok: false, status: 0, data: null }),
+      getToken: () => 'tok',
+    });
+    const version = await transport.currentVersion();
+    assert.equal(version, Number.POSITIVE_INFINITY);
+  });
+
+  test('a 401 (missing/expired token) -> resolves +Infinity, does NOT throw', async () => {
+    const transport = createWebShieldTransport({
+      http: mockHttp({ ok: false, status: 401, data: { error: 'unauthorized' } }),
+      getToken: () => null,
+    });
+    const version = await transport.currentVersion();
+    assert.equal(version, Number.POSITIVE_INFINITY);
+  });
+
+  test('a 503 (permission-version store outage) -> resolves +Infinity, does NOT throw', async () => {
+    const transport = createWebShieldTransport({
+      http: mockHttp({ ok: false, status: 503, data: { message: 'permission version store unavailable' } }),
+      getToken: () => 'tok',
+    });
+    const version = await transport.currentVersion();
+    assert.equal(version, Number.POSITIVE_INFINITY);
+  });
+
+  test('a 500 -> resolves +Infinity, does NOT throw', async () => {
+    const transport = createWebShieldTransport({
+      http: mockHttp({ ok: false, status: 500, data: null }),
+      getToken: () => 'tok',
+    });
+    const version = await transport.currentVersion();
+    assert.equal(version, Number.POSITIVE_INFINITY);
+  });
+
+  test('a 200 with a malformed body (missing/non-numeric version) -> resolves +Infinity, does NOT throw', async () => {
+    const transport = createWebShieldTransport({
+      http: mockHttp({ ok: true, status: 200, data: { version: 'not-a-number' } }),
+      getToken: () => 'tok',
+    });
+    const version = await transport.currentVersion();
+    assert.equal(version, Number.POSITIVE_INFINITY);
+  });
+
+  test('reads the CURRENT token via the getToken getter (not a captured snapshot)', async () => {
+    let currentToken = 'first-token';
+    const http = {
+      get: async (_path, opts) => {
+        http.seenToken = opts.bearerToken;
+        return { ok: true, status: 200, data: { version: 1 } };
+      },
+    };
+    const transport = createWebShieldTransport({ http, getToken: () => currentToken });
+
+    await transport.currentVersion();
+    assert.equal(http.seenToken, 'first-token');
+
+    currentToken = 'refreshed-token';
+    await transport.currentVersion();
+    assert.equal(http.seenToken, 'refreshed-token');
+  });
+
+  test('never throws, even if http.get itself rejects unexpectedly (defensive backstop)', async () => {
+    // The real createWebHttpClient never rejects (it catches internally), but
+    // currentVersion() is defensively wrapped so it stays contract-safe even against
+    // a misbehaving/mocked `http` dependency — this is the CRITICAL property: the
+    // SDK's client.ts calls currentVersion() completely unguarded (no try/catch at
+    // its call site), so a throw here would escape getAuthFacts uncaught.
+    const transport = createWebShieldTransport({
+      http: { get: async () => { throw new Error('boom'); } },
+      getToken: () => 'tok',
+    });
+    const version = await transport.currentVersion();
+    assert.equal(version, Number.POSITIVE_INFINITY);
+  });
+});

package/template/frontend/src/shell/AppShell.jsx

@@ -0,0 +1,237 @@
+/**
+ * AppShell — the post-login layout: collapsible sidebar (desktop rail / mobile
+ * drawer) + a sticky header (mobile menu button, user menu with theme control,
+ * sign-out) + the routed content. Collapse state is persisted to localStorage.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { useLocation, useNavigate } from 'react-router-dom';
+import { saveReturnPath } from '@/platform/returnPathStore';
+import {
+  Bell,
+  HelpCircle,
+  LogOut,
+  Menu,
+  PanelLeft,
+  Search,
+  Settings,
+  X,
+} from 'lucide-react';
+import { useAuth } from '@/auth/AuthContext';
+import { Button } from '@/components/ui/button';
+import { Input } from '@/components/ui/input';
+import { Avatar, AvatarFallback } from '@/components/ui/avatar';
+import { Tooltip, TooltipContent, TooltipProvider, TooltipTrigger } from '@/components/ui/tooltip';
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuItem,
+  DropdownMenuLabel,
+  DropdownMenuSeparator,
+  DropdownMenuTrigger,
+} from '@/components/ui/dropdown-menu';
+import ThemeToggle from '@/theme/ThemeToggle';
+import Sidebar from './Sidebar';
+
+/** A header icon-action button with a tooltip (ffs pattern). */
+function IconAction({ icon: Icon, label, dot }) {
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button className="relative flex size-9 items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-secondary hover:text-foreground">
+          <Icon className="size-[18px]" />
+          {dot && (
+            <span className="absolute right-2 top-2 size-2 rounded-full bg-destructive ring-2 ring-background" />
+          )}
+        </button>
+      </TooltipTrigger>
+      <TooltipContent>{label}</TooltipContent>
+    </Tooltip>
+  );
+}
+
+const COLLAPSE_KEY = 'app-sidebar-collapsed';
+
+// `title` / `section` are still accepted from callers (every page passes them) but are
+// no longer rendered here — the breadcrumb moved into each page's <PageHeader>. They're
+// destructured to `_`-prefixed names so they're consumed-and-ignored without an
+// unused-var lint error, and callers don't need to change.
+export default function AppShell({ children, title: _title, section: _section }) {
+  const { logout, identityHint, profile } = useAuth();
+  const navigate = useNavigate();
+  const location = useLocation();
+
+  const [collapsed, setCollapsed] = useState(() => {
+    try {
+      return localStorage.getItem(COLLAPSE_KEY) === '1';
+    } catch {
+      return false;
+    }
+  });
+  const [drawerOpen, setDrawerOpen] = useState(false);
+
+  const toggleCollapse = useCallback(() => {
+    setCollapsed((c) => {
+      const next = !c;
+      try {
+        localStorage.setItem(COLLAPSE_KEY, next ? '1' : '0');
+      } catch {
+        /* ignore */
+      }
+      return next;
+    });
+  }, []);
+
+  // Close the mobile drawer on Escape.
+  useEffect(() => {
+    if (!drawerOpen) return undefined;
+    const onKey = (e) => e.key === 'Escape' && setDrawerOpen(false);
+    window.addEventListener('keydown', onKey);
+    return () => window.removeEventListener('keydown', onKey);
+  }, [drawerOpen]);
+
+  const onLogout = async () => {
+    // Remember the current page so the next login returns here (OCA-style). Explicit
+    // logout doesn't pass through RequireAuth, so save it directly before clearing.
+    saveReturnPath(location.pathname + location.search);
+    await logout();
+    navigate('/login', { replace: true });
+  };
+
+  // Human-readable display: prefer the resolved profile name from /auth/me (a display
+  // NAME, never a UUID); fall back to the interim login hint, then a generic label.
+  const displayName = profile?.name || identityHint || 'Signed in';
+  const companyName = profile?.company?.name || '';
+  // Prefer the part before "@" for a cleaner label + initials.
+  const shortName = displayName.includes('@') ? displayName.split('@')[0] : displayName;
+  const initials = shortName.replace(/[^a-zA-Z0-9]/g, '').slice(0, 2).toUpperCase() || 'U';
+
+  return (
+    <div className="flex h-screen overflow-hidden bg-background">
+      {/* Desktop sidebar */}
+      <div className="hidden lg:block">
+        <Sidebar collapsed={collapsed} onLogout={onLogout} />
+      </div>
+
+      {/* Mobile drawer */}
+      {drawerOpen && (
+        <div className="fixed inset-0 z-50 lg:hidden">
+          <button
+            className="modal-overlay absolute inset-0"
+            onClick={() => setDrawerOpen(false)}
+            aria-label="Close menu"
+          />
+          <div className="absolute inset-y-0 left-0 flex">
+            <Sidebar mobile onLogout={onLogout} onNavigate={() => setDrawerOpen(false)} />
+            <button
+              className="absolute right-2 top-3 rounded-md p-1.5 text-sidebar-foreground/70 hover:bg-sidebar-accent"
+              onClick={() => setDrawerOpen(false)}
+              aria-label="Close"
+            >
+              <X className="size-5" />
+            </button>
+          </div>
+        </div>
+      )}
+
+      {/* Main column */}
+      <div className="flex min-w-0 flex-1 flex-col">
+        <TooltipProvider delayDuration={100}>
+          <header className="z-10 flex h-14 shrink-0 items-center gap-3 border-b border-border bg-background px-4 shadow-sm">
+            {/* Mobile hamburger */}
+            <Button
+              variant="ghost"
+              size="icon"
+              className="lg:hidden"
+              onClick={() => setDrawerOpen(true)}
+              aria-label="Open menu"
+            >
+              <Menu className="size-5" />
+            </Button>
+
+            {/* Desktop collapse toggle (moved here from the sidebar footer). */}
+            <Tooltip>
+              <TooltipTrigger asChild>
+                <button
+                  onClick={toggleCollapse}
+                  className="hidden size-9 items-center justify-center rounded-lg text-muted-foreground transition-colors hover:bg-secondary hover:text-foreground lg:flex"
+                  aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
+                >
+                  <PanelLeft className="size-[18px]" />
+                </button>
+              </TooltipTrigger>
+              <TooltipContent>{collapsed ? 'Expand sidebar' : 'Collapse sidebar'}</TooltipContent>
+            </Tooltip>
+
+            {/* Search — left-aligned right after the sidebar toggle, stretching to fill
+                (OCA `.dash-topbar-l` search pattern). BORDERLESS + transparent by default
+                (just the icon + placeholder); on focus it reveals a light border + a subtle
+                secondary background. The header breadcrumb was removed — the page-level
+                breadcrumb now lives in each page's header. */}
+            <div className="relative hidden max-w-xs flex-1 md:block">
+              <Search className="pointer-events-none absolute left-3 top-1/2 size-4 -translate-y-1/2 text-muted-foreground" />
+              <Input
+                placeholder="Search…"
+                aria-label="Search"
+                className="h-9 w-full border-transparent bg-transparent pl-9 text-sm shadow-none transition-colors focus-visible:border-border focus-visible:bg-secondary focus-visible:ring-0"
+              />
+            </div>
+
+            <div className="flex-1" />
+
+            {/* Icon actions */}
+            <IconAction icon={Bell} label="Notifications" dot />
+            <IconAction icon={Settings} label="Settings" />
+            <IconAction icon={HelpCircle} label="Help" />
+
+            <div className="mx-1 h-6 w-px bg-border" />
+
+            {/* User menu — avatar only in the header; identity lives in the dropdown. */}
+            <DropdownMenu>
+              <DropdownMenuTrigger asChild>
+                <button
+                  className="rounded-full transition-opacity hover:opacity-80"
+                  aria-label="Account menu"
+                >
+                  <Avatar className="size-8">
+                    <AvatarFallback className="bg-primary text-xs font-semibold text-primary-foreground">
+                      {initials}
+                    </AvatarFallback>
+                  </Avatar>
+                </button>
+              </DropdownMenuTrigger>
+              <DropdownMenuContent align="end" className="w-64">
+                <DropdownMenuLabel className="font-normal">
+                  <div className="flex items-center gap-2.5">
+                    <Avatar className="size-9">
+                      <AvatarFallback className="bg-primary text-sm font-semibold text-primary-foreground">
+                        {initials}
+                      </AvatarFallback>
+                    </Avatar>
+                    <div className="min-w-0 leading-tight">
+                      <div className="truncate text-sm font-semibold">{displayName}</div>
+                      <div className="truncate text-[11px] text-muted-foreground">
+                        {companyName || 'Signed in'}
+                      </div>
+                    </div>
+                  </div>
+                </DropdownMenuLabel>
+                <DropdownMenuSeparator />
+                <div className="px-2 py-2">
+                  <div className="mb-1.5 text-[11px] font-medium text-muted-foreground">Theme</div>
+                  <ThemeToggle />
+                </div>
+                <DropdownMenuSeparator />
+                <DropdownMenuItem onClick={onLogout} className="text-destructive focus:text-destructive">
+                  <LogOut className="mr-2 size-4" />
+                  Sign out
+                </DropdownMenuItem>
+              </DropdownMenuContent>
+            </DropdownMenu>
+          </header>
+        </TooltipProvider>
+
+        <main className="engineering-grid flex-1 overflow-y-auto">{children}</main>
+      </div>
+    </div>
+  );
+}