v0.2 Phase 6: shell split — AppRuntime / AppChrome / AppOverlays

src/routes/+layout.svelte was 537 LOC of mixed runtime, chrome and
overlay concerns. Split into three single-purpose shells under
src/lib/shell/, with +layout.svelte reduced to ~28 LOC of pure
composition.

AppRuntime (no DOM beyond <svelte:window>):
  - Global hotkey dual backend (evdev / tauri-plugin-global-shortcut)
  - 120ms hotkey debounce (sacred behaviour §5 #2)
  - PREFERENCES_CHANGED_EVENT listener (sacred §5 #4)
  - KI-05 one-shot legacy-theme migration
  - Sidebar hotkeys: [ toggle, Ctrl+K, Ctrl+, (sacred §5 #10)
  - Wind-down tray listener
  - Meeting auto-capture poller
  - Global frontend error capture
  - Nudge bus + implementation intentions lifecycle
  - Font-size CSS var $effect
  - Window resize → sidebar auto-collapse
  - Onboarding/first-run check + update check + LLM status warm-up

AppChrome (the visual shell):
  - Titlebar (OS-aware via customChrome helper)
  - Sidebar (recording-state-aware — sacred §5 #1 stays in
    Sidebar.svelte verbatim)
  - Main slot
  - TaskSidebar conditional rail

AppOverlays (mounted-once globals):
  - ToastViewport
  - FocusTimer
  - MorningTriageModal
  - ResizeHandles (OS-gated)

src/lib/utils/customChrome.svelte.ts holds the single source of truth
for useCustomChrome, a module-level $state both AppChrome and
AppOverlays subscribe to. Each only ever sees one loadOsInfo() call
between them.

Secondary windows still escape via their own +layout@.svelte; the
defensive isSecondaryWindow check in +layout.svelte stays so a
direct /float, /viewer, /preview navigation through the root layout
also drops the chrome.

Phase 6 per-page gate green: npm run check (0/0/5704 files),
npm test, npm run test:browser (3/3), npm run test:e2e (16/16).
No regressions in the Phase 1 smoke baseline.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

src/lib/shell/AppChrome.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+  // @ts-nocheck
+  // v0.2 Phase 6 — visual shell. Titlebar (OS-aware), sidebar
+  // (recording-state-aware), main slot, task rail slot.
+  //
+  // The recording-state nav fade behaviour (sacred — see
+  // docs/release/v0.2-frontend-overhaul.md §5 #1) lives in Sidebar
+  // itself and continues to work verbatim through this wrapper.
+  import { onMount } from "svelte";
+  import Sidebar from "$lib/Sidebar.svelte";
+  import TaskSidebar from "$lib/components/TaskSidebar.svelte";
+  import Titlebar from "$lib/components/Titlebar.svelte";
+  import { page } from "$lib/stores/page.svelte.js";
+  import {
+    ensureCustomChromeLoaded,
+    customChrome,
+  } from "$lib/utils/customChrome.svelte.ts";
+
+  let { children } = $props();
+
+  onMount(() => {
+    ensureCustomChromeLoaded();
+  });
+</script>
+
+<div class="flex flex-col h-screen w-screen overflow-hidden grain">
+  {#if customChrome.current}
+    <Titlebar />
+  {/if}
+  <div class="flex flex-1 min-h-0 relative">
+    {#if page.current !== "first-run"}
+      <Sidebar />
+    {/if}
+    <div class="flex-1 overflow-hidden bg-bg">
+      {@render children()}
+    </div>
+    {#if page.taskSidebarOpen && page.current !== "first-run"}
+      <div class="w-[280px] min-w-[280px] shadow-xl">
+        <TaskSidebar />
+      </div>
+    {/if}
+  </div>
+</div>

src/lib/shell/AppOverlays.svelte

@@ -0,0 +1,43 @@
+<script lang="ts">
+  // @ts-nocheck
+  // v0.2 Phase 6 — global overlays. Mounted once at the app root so
+  // any component can call toasts.error(...), fire lumotia:start-timer,
+  // and so the morning triage modal can layer over any page.
+  //
+  // ResizeHandles is OS-gated by customChrome (suppressed on Linux,
+  // which uses native KWin/Mutter resize edges).
+  import { onMount } from "svelte";
+  import ToastViewport from "$lib/components/ToastViewport.svelte";
+  import FocusTimer from "$lib/components/FocusTimer.svelte";
+  import MorningTriageModal from "$lib/components/MorningTriageModal.svelte";
+  import ResizeHandles from "$lib/components/ResizeHandles.svelte";
+  import {
+    ensureCustomChromeLoaded,
+    customChrome,
+  } from "$lib/utils/customChrome.svelte.ts";
+
+  onMount(() => {
+    ensureCustomChromeLoaded();
+  });
+</script>
+
+<!-- Global toast viewport. Mounted once so any component can call
+     toasts.error(...), toasts.success(...) etc. -->
+<ToastViewport />
+
+<!-- Global focus-timer overlay. Renders nothing until a
+     `lumotia:start-timer` event fires; then pins a shrinking
+     colour ring to the top-right. -->
+<FocusTimer />
+
+<!-- Phase 5 morning triage modal. Self-gated — no-op unless the user
+     has enabled `ritualsMorning` and the local clock is past their
+     set trigger time. Mounted here so it can appear over any page. -->
+<MorningTriageModal />
+
+<!-- Invisible resize margins for frameless (macOS/Windows). On Linux
+     we use native decorations, so ResizeHandles would compete with
+     the compositor's own resize and is suppressed. -->
+{#if customChrome.current}
+  <ResizeHandles />
+{/if}

src/lib/shell/AppRuntime.svelte

@@ -0,0 +1,399 @@
+<script lang="ts">
+  // @ts-nocheck
+  // v0.2 Phase 6 — runtime/background side of the app shell.
+  //
+  // Owns: Tauri listeners, evdev hotkey wiring, tauri-plugin-global-shortcut
+  // fallback, 120ms hotkey debounce, PREFERENCES_CHANGED_EVENT, update
+  // check, global frontend error capture, sidebar hotkeys ([, Ctrl+K,
+  // Ctrl+,), KI-05 legacy-theme one-shot migration, meeting auto-capture
+  // poller, nudge bus, implementation intentions, OS info warm-up.
+  //
+  // Does NOT render DOM — only <svelte:window onkeydown={…} />.
+  import { onMount, onDestroy } from "svelte";
+  import { invoke } from "@tauri-apps/api/core";
+  import { getCurrentWindow } from "@tauri-apps/api/window";
+  import { listen } from "@tauri-apps/api/event";
+  import { hasTauriRuntime } from "$lib/utils/runtime.js";
+  import { isMac, loadOsInfo } from "$lib/utils/osInfo.js";
+  import { page, settings, saveSettings } from "$lib/stores/page.svelte.js";
+  import {
+    getPreferences,
+    updatePreferences,
+    applyExternalPreferences,
+    PREFERENCES_CHANGED_EVENT,
+  } from "$lib/stores/preferences.svelte.js";
+  import { profilesStore } from "$lib/stores/profiles.svelte.ts";
+  import { toasts } from "$lib/stores/toasts.svelte.js";
+  import { initI18n } from "$lib/i18n";
+  import { refreshLlmStatus } from "$lib/stores/llmStatus.svelte.js";
+  import { startNudgeBus, stopNudgeBus } from "$lib/stores/nudgeBus.svelte.ts";
+  import {
+    startImplementationIntentions,
+    stopImplementationIntentions,
+  } from "$lib/stores/implementationIntentions.svelte.ts";
+
+  // Set up svelte-i18n once per app instance. Safe to call from every
+  // window — initI18n guards itself against re-init.
+  initI18n();
+
+  const prefs = getPreferences();
+  const tauriRuntimeAvailable = hasTauriRuntime();
+
+  // KI-05 v0.2 one-shot: copy legacy settings.theme into preferences.theme,
+  // then strip it from localStorage. Idempotent.
+  function migrateLegacyTheme() {
+    if (typeof localStorage === "undefined") return;
+    const raw = localStorage.getItem("lumotia_settings");
+    if (!raw) return;
+    let parsed;
+    try { parsed = JSON.parse(raw); } catch { return; }
+    const data = parsed?.data ?? parsed;
+    if (!data || typeof data !== "object" || !("theme" in data)) return;
+    const legacy = data.theme;
+    const mapped = legacy === "Light" ? "light" : legacy === "System" ? "system" : "dark";
+    if (mapped !== prefs.theme) updatePreferences({ theme: mapped });
+    delete data.theme;
+    if (parsed && typeof parsed === "object" && "data" in parsed) parsed.data = data;
+    else parsed = data;
+    try { localStorage.setItem("lumotia_settings", JSON.stringify(parsed)); } catch {}
+  }
+
+  // Global hotkey — dual backend (evdev on Wayland, tauri-plugin-global-
+  // shortcut elsewhere). Main-window-only.
+  let registeredHotkey = null;
+  let hotkeyBackend = $state("unknown");
+
+  async function initHotkeyBackend() {
+    if (!tauriRuntimeAvailable) {
+      hotkeyBackend = "unavailable";
+      return;
+    }
+    try {
+      const isWayland = await invoke("is_wayland_session");
+      if (isWayland) {
+        try {
+          await invoke("check_hotkey_access");
+          hotkeyBackend = "evdev";
+          console.log("Hotkey backend: evdev (Wayland)");
+        } catch (err) {
+          console.warn("evdev hotkey access denied:", err);
+          console.warn("Add your user to the 'input' group for global hotkeys on Wayland");
+          hotkeyBackend = "unavailable";
+        }
+      } else {
+        hotkeyBackend = "tauri";
+        console.log("Hotkey backend: tauri-plugin-global-shortcut (X11)");
+      }
+    } catch {
+      hotkeyBackend = "tauri";
+    }
+  }
+
+  async function registerGlobalHotkey(hotkey) {
+    if (!tauriRuntimeAvailable) return;
+    if (hotkeyBackend === "unknown") return;
+
+    try {
+      const label = (await import("@tauri-apps/api/window")).getCurrentWindow().label;
+      if (label !== "main") return;
+    } catch { /* main is the expected default */ }
+
+    try {
+      if (hotkeyBackend === "evdev") {
+        if (registeredHotkey) {
+          await invoke("update_evdev_hotkey", { hotkey });
+        } else {
+          await invoke("start_evdev_hotkey", { hotkey });
+        }
+        registeredHotkey = hotkey;
+      } else if (hotkeyBackend === "tauri") {
+        const mod = await import("@tauri-apps/plugin-global-shortcut");
+        if (registeredHotkey) {
+          await mod.unregister(registeredHotkey).catch(() => {});
+        }
+        await mod.register(hotkey, () => {
+          if (page.current !== "dictation") page.current = "dictation";
+          requestAnimationFrame(() => {
+            window.dispatchEvent(new CustomEvent("lumotia:toggle-recording"));
+          });
+        });
+        registeredHotkey = hotkey;
+      }
+    } catch (err) {
+      console.error("Hotkey registration failed:", err);
+      const msg = err instanceof Error ? err.message : String(err);
+      toasts.error(
+        "Hotkey not registered",
+        `${hotkey}. ${msg}. Reverted to ${registeredHotkey ?? "previous value"}.`,
+      );
+      if (registeredHotkey && registeredHotkey !== hotkey) {
+        settings.globalHotkey = registeredHotkey;
+        saveSettings();
+      }
+    }
+  }
+
+  // evdev hotkey debounce. autorepeat / sticky key / nervous double-tap
+  // can deliver the same press within ~100ms — without debouncing the
+  // recording toggle bounces twice and the capture is lost.
+  // Matches Handy #1143 ("first press records nothing, second works").
+  const HOTKEY_DEBOUNCE_MS = 120;
+  let lastHotkeyAtMs = 0;
+  let unlistenEvdev = null;
+  async function setupEvdevListener() {
+    if (!tauriRuntimeAvailable) return;
+    unlistenEvdev = await listen("lumotia:hotkey-pressed", () => {
+      const now = Date.now();
+      if (now - lastHotkeyAtMs < HOTKEY_DEBOUNCE_MS) return;
+      lastHotkeyAtMs = now;
+      if (page.current !== "dictation") page.current = "dictation";
+      requestAnimationFrame(() => {
+        window.dispatchEvent(new CustomEvent("lumotia:toggle-recording"));
+      });
+    });
+  }
+
+  $effect(() => {
+    if (hotkeyBackend === "evdev" && !unlistenEvdev) {
+      setupEvdevListener();
+    }
+  });
+
+  $effect(() => {
+    if (hotkeyBackend !== "unknown") {
+      registerGlobalHotkey(settings.globalHotkey);
+    }
+  });
+
+  // Apply font size setting as CSS variable (legacy, kept for backwards compat).
+  $effect(() => {
+    document.body.style.setProperty("--font-size-transcript", `${settings.fontSize}px`);
+  });
+
+  const CUSTOM_WIDGET_SELECTOR =
+    '[role="combobox"], [role="listbox"], [role="radio"], [role="switch"], [role="menuitem"], [role="tab"]';
+
+  function isInputFocused(e) {
+    const tag = e.target?.tagName;
+    if (tag === "INPUT" || tag === "TEXTAREA" || e.target?.isContentEditable) {
+      return true;
+    }
+    const active = document.activeElement;
+    if (active && typeof active.closest === "function" && active.closest(CUSTOM_WIDGET_SELECTOR)) {
+      return true;
+    }
+    return false;
+  }
+
+  function handleKeydown(e) {
+    try {
+      if (e.key === "Escape") {
+        if (page.taskSidebarOpen) {
+          page.taskSidebarOpen = false;
+          return;
+        }
+        window.dispatchEvent(new CustomEvent("lumotia:escape"));
+        return;
+      }
+
+      const modKey = isMac() ? e.metaKey : e.ctrlKey;
+
+      if (modKey && e.key === "k" && !isInputFocused(e)) {
+        e.preventDefault();
+        if (page.current === "history") {
+          window.dispatchEvent(new CustomEvent("lumotia:focus-search"));
+        } else {
+          page.current = "history";
+          requestAnimationFrame(() => {
+            window.dispatchEvent(new CustomEvent("lumotia:focus-search"));
+          });
+        }
+        return;
+      }
+
+      if (modKey && e.key === "," && !isInputFocused(e)) {
+        e.preventDefault();
+        page.current = "settings";
+        return;
+      }
+
+      if (e.key === "[" && !isInputFocused(e)) {
+        settings.sidebarCollapsed = !settings.sidebarCollapsed;
+        saveSettings();
+      }
+    } catch {
+      // A keydown error must never silence the listener — swallow silently.
+    }
+  }
+
+  function handleResize() {
+    if (window.innerWidth < 900 && !settings.sidebarCollapsed) {
+      settings.sidebarCollapsed = true;
+      saveSettings();
+    }
+  }
+
+  // Phase 5: tray "Evening wind-down" routes here.
+  let unlistenWindDown = null;
+  async function setupWindDownListener() {
+    if (!tauriRuntimeAvailable) return;
+    unlistenWindDown = await listen("lumotia:open-wind-down", () => {
+      page.current = "shutdown";
+    });
+  }
+
+  // Cross-window preference sync via Tauri events.
+  let unlistenPrefs = null;
+  async function setupPreferencesSync() {
+    if (!tauriRuntimeAvailable) return;
+    let ownLabel = null;
+    try { ownLabel = getCurrentWindow().label; } catch {}
+    unlistenPrefs = await listen(PREFERENCES_CHANGED_EVENT, (event) => {
+      const payload = event?.payload;
+      if (!payload || payload.source === ownLabel) return;
+      applyExternalPreferences(payload.prefs);
+    });
+  }
+
+  // Global frontend error capture — forwards to Rust error_log via
+  // log_frontend_error. Best-effort; never crashes the app over logging.
+  let onWindowError = null;
+  let onUnhandledRejection = null;
+
+  function installGlobalErrorCapture() {
+    if (!hasTauriRuntime()) return;
+
+    const safeLog = (context, message, stack) => {
+      try {
+        invoke("log_frontend_error", { context, message: String(message ?? ""), stack: stack ?? null })
+          .catch(() => {});
+      } catch {}
+    };
+
+    onWindowError = (ev) => {
+      safeLog(
+        "window.onerror",
+        ev?.message || ev?.error?.message || "Unknown error",
+        ev?.error?.stack || null,
+      );
+    };
+
+    onUnhandledRejection = (ev) => {
+      const reason = ev?.reason;
+      const msg = (reason && (reason.message || String(reason))) || "Unhandled rejection";
+      safeLog("unhandledrejection", msg, reason?.stack || null);
+    };
+
+    window.addEventListener("error", onWindowError);
+    window.addEventListener("unhandledrejection", onUnhandledRejection);
+  }
+
+  onMount(async () => {
+    // KI-05 first — preferences must be in the right state before
+    // any theme-sensitive render.
+    migrateLegacyTheme();
+
+    handleResize();
+    window.addEventListener("resize", handleResize);
+
+    setupPreferencesSync();
+    setupWindDownListener();
+
+    startNudgeBus();
+    startImplementationIntentions();
+
+    installGlobalErrorCapture();
+
+    // Warm the OS-info cache so isMac()/isWayland() return quickly
+    // from any component that reads them after first render.
+    loadOsInfo().catch(() => {});
+
+    if (!tauriRuntimeAvailable) {
+      hotkeyBackend = "unavailable";
+      return;
+    }
+
+    await initHotkeyBackend();
+    await profilesStore.load();
+
+    try {
+      const completed: boolean = await invoke("has_completed_onboarding");
+      const whisper = await invoke("list_models");
+      const parakeet = await invoke("list_parakeet_models");
+      const noModels = whisper.length === 0 && parakeet.length === 0;
+      const replayRequested = sessionStorage.getItem("lumotia:replay-tutorial") === "1";
+
+      if (replayRequested) {
+        sessionStorage.removeItem("lumotia:replay-tutorial");
+        page.current = "first-run";
+      } else if (!completed && noModels) {
+        page.current = "first-run";
+      }
+    } catch { /* skip first-run check on command failure */ }
+
+    invoke("check_for_update")
+      .then((version) => {
+        if (version) {
+          toasts.info(`Lumotia ${version} is available. Download and restart to update.`);
+        }
+      })
+      .catch(() => {});
+
+    refreshLlmStatus(settings.aiTier).catch(() => {});
+
+    if (settings.prewarmModelOnStartup) {
+      invoke("prewarm_default_model_cmd").catch(() => {});
+    }
+  });
+
+  // Meeting auto-capture poller. Edge-triggered: re-firing the same
+  // match stays quiet until the app exits and returns.
+  $effect(() => {
+    if (!tauriRuntimeAvailable) return;
+    if (!settings.meetingAutoCapture) return;
+
+    let previous: Set<string> = new Set();
+    const id = window.setInterval(async () => {
+      const patterns = settings.meetingAutoCaptureApps;
+      if (!Array.isArray(patterns) || patterns.length === 0) return;
+      try {
+        const matches: string[] = await invoke("detect_meeting_processes", { patterns });
+        const current = new Set(matches);
+        for (const match of matches) {
+          if (!previous.has(match)) {
+            toasts.info(
+              `${match[0].toUpperCase()}${match.slice(1)} detected`,
+              `Press ${settings.globalHotkey} to start recording.`,
+            );
+          }
+        }
+        previous = current;
+      } catch {}
+    }, 15000);
+
+    return () => { window.clearInterval(id); };
+  });
+
+  onDestroy(() => {
+    window.removeEventListener("resize", handleResize);
+    if (onWindowError) window.removeEventListener("error", onWindowError);
+    if (onUnhandledRejection) window.removeEventListener("unhandledrejection", onUnhandledRejection);
+    if (!tauriRuntimeAvailable) {
+      return;
+    }
+    if (hotkeyBackend === "evdev") {
+      invoke("stop_evdev_hotkey").catch(() => {});
+    } else if (hotkeyBackend === "tauri" && registeredHotkey) {
+      import("@tauri-apps/plugin-global-shortcut")
+        .then((mod) => mod.unregister(registeredHotkey))
+        .catch(() => {});
+    }
+    if (unlistenEvdev) unlistenEvdev();
+    if (unlistenPrefs) unlistenPrefs();
+    if (unlistenWindDown) unlistenWindDown();
+    stopNudgeBus();
+    stopImplementationIntentions();
+  });
+</script>
+
+<svelte:window onkeydown={handleKeydown} />

src/lib/utils/customChrome.svelte.ts

@@ -0,0 +1,26 @@
+// v0.2 Phase 6 helper. Single source of truth for the "should this
+// window paint its own titlebar + resize handles?" flag.
+//
+// Linux uses native KWin/Mutter decorations, so useCustomChrome is
+// false. macOS and Windows opt in. AppChrome (titlebar) and
+// AppOverlays (ResizeHandles) both subscribe to the same reactive
+// value rather than each calling loadOsInfo independently.
+
+import { loadOsInfo, isLinux } from "$lib/utils/osInfo.js";
+
+let initialised = false;
+let value = $state(false);
+
+export function ensureCustomChromeLoaded() {
+  if (initialised) return;
+  initialised = true;
+  loadOsInfo()
+    .then(() => { value = !isLinux(); })
+    .catch(() => { /* fallback to false; matches the safer Linux path */ });
+}
+
+export const customChrome = {
+  get current() {
+    return value;
+  },
+};