@happyvertical/smrt-template-sveltekit 0.38.3 → 0.38.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-template-sveltekit",
-  "version": "0.38.3",
+  "version": "0.38.4",
   "description": "SvelteKit project template with SMRT framework integration",
   "type": "module",
   "main": "index.js",
@@ -29,7 +29,7 @@
     "directory": "packages/template-sveltekit"
   },
   "peerDependencies": {
-    "@happyvertical/smrt-core": "0.38.3"
+    "@happyvertical/smrt-core": "0.38.4"
   },
   "devDependencies": {
     "vitest": "^4.1.9"

package/template/README.md

@@ -39,8 +39,11 @@ A SvelteKit application with SMRT framework integration for rapid development of
 │   │       └── tenancy.ts     # Pluggable tenant resolver
 │   └── routes/
 │       ├── api/               # Auto-generated API routes (don't edit!)
+│       ├── +layout.server.ts  # Builds AdminShell tenant nav server-side (manifest → nav)
+│       ├── +layout.svelte     # WASD AdminShell chrome wrapping every page
+│       ├── settings/          # ShellSettingsPanel (panel layout + hotkeys)
 │       ├── +page.server.ts    # Home page server load + demo mutation (reference pattern)
-│       └── +page.svelte       # Home page
+│       └── +page.svelte       # Home page (renders inside AdminShell)
 ├── smrt.config.ts             # Root SMRT config
 ├── vite.config.ts             # Vite + SMRT plugin config
 └── svelte.config.js           # SvelteKit config
@@ -226,6 +229,84 @@ same REST route segment as `depends`/`invalidate`). Add
 `@happyvertical/smrt-web` and `@happyvertical/smrt-svelte` to the project's
 dependencies before using this pattern.
 
+## Workspace shell (AdminShell)
+
+This template renders every page inside the **WASD AdminShell** — a four-edge
+admin layout from `@happyvertical/smrt-svelte/workspace`. Each edge is a scope
+(top = app, left = tenant, right = focus, bottom = system) toggled with
+<kbd>W</kbd>/<kbd>A</kbd>/<kbd>S</kbd>/<kbd>D</kbd> (press <kbd>?</kbd> for the
+shortcuts). It is wired in the root layout:
+
+- `src/routes/+layout.server.ts` builds the left "tenant" nav **server-side**
+  with `tenantNavFromManifest()` from the SMRT manifest (`.smrt/manifest.json`)
+  and returns it as layout data — no client-side nav fetch.
+- `src/routes/+layout.svelte` wraps `{@render children()}` in `<AdminShell>`
+  (inside `<ThemeProvider>` — see **Theming** below), feeding that nav to
+  `<TenantNav>`, a brand/app panel on top, and a couple of status chips on the
+  bottom.
+- `src/routes/settings/+page.svelte` drops in `<ShellSettingsPanel>` so users
+  can toggle panels and remap the hotkeys; the choices persist in
+  `localStorage` under the shell's `storageKey`.
+
+**The shell preserves the server-load pattern above.** AdminShell's public core
+is SSR-safe: it renders statically on the server and only activates hotkeys /
+`localStorage` after mount. The active page still renders inside the shell's
+`<main>` and keeps its own `+page.server.ts` load and `invalidate()` refresh —
+the shell is chrome around the page, not a replacement for its data flow. The
+home page's `depends('smrt:items')` / `invalidate('smrt:items')` cycle works
+unchanged.
+
+### Theming
+
+The layout wraps the shell in **`<ThemeProvider>`** from
+`@happyvertical/smrt-ui/themes` — the standard SMRT theming wrapper (the same
+pattern the reference `@happyvertical/smrt-content` app uses):
+
+```svelte
+<script lang="ts">
+  import { ThemeProvider } from '@happyvertical/smrt-ui/themes';
+  // @font-face rules for the SMRT type stack (Space Grotesk / Inter /
+  // JetBrains Mono woff2). ThemeProvider supplies the token *variables*;
+  // this loads the font *files*. Bundled — no CDN request.
+  import '@happyvertical/smrt-ui/themes/styles/fonts.css';
+</script>
+
+<ThemeProvider colorScheme="system" persist={true}>
+  <!-- AdminShell + every page render themed inside here -->
+</ThemeProvider>
+```
+
+- ThemeProvider injects the **entire `--smrt-*` token set** (colors, typography,
+  spacing, radius, elevation, motion, z-index) as an inline style it computes
+  during render — so the tokens are present in the SSR HTML with **no unstyled
+  flash**, and it re-resolves them on the client. You do **not** need to import
+  `styles/tokens.css` or `themes/styles/*.css` separately; the provider is the
+  runtime source of truth.
+- `colorScheme="system"` follows the OS light/dark preference; `persist` saves a
+  user's explicit switch to `localStorage`. Switch presets/scheme at runtime
+  with `ThemeSwitcher` / `ColorSchemeToggle` (also from `.../themes`), or read
+  the current theme via the theme context.
+- The one thing the provider does not carry is the font **files** — hence the
+  `themes/styles/fonts.css` import above. Drop it and the type stack degrades to
+  `system-ui` / `ui-monospace` automatically.
+
+To pin a specific look instead of following the OS, set
+`colorScheme="light"` (or `"dark"`) and `preset="material"` (or `"glass"` /
+`"studio"` / `"smrt"`).
+
+The status chips ship static (`Local`, `Ready`). To make them (and the focus
+edge) live — job counts, dispatch depth, connection state — feed real values
+through `systemFeed` (`@happyvertical/smrt-svelte/workspace/live`) or
+`activityFeed` (`@happyvertical/smrt-svelte/web`).
+
+- **Migration guide** (old `WorkspaceShell`/`RoleShell` → `AdminShell`, and why
+  adoption is additive):
+  [`@happyvertical/smrt-svelte` → `src/components/workspace/MIGRATION.md`](https://github.com/happyvertical/smrt/blob/main/packages/smrt-svelte/src/components/workspace/MIGRATION.md)
+- **Four-scope demo** (all edges, focus tools, activities) and the live-feed
+  variants, in the smrt-svelte playground:
+  `playground/src/routes/admin-shell`, `admin-shell-activity-feed`, and
+  `admin-shell-system-feed`.
+
 ## Multi-tenancy
 
 This template ships with multi-tenancy pre-wired. Out of the box you get:

package/template/package.json

@@ -20,8 +20,10 @@
     "vite": "^8.1.3"
   },
   "dependencies": {
-    "@happyvertical/smrt-core": "^0.38.3",
-    "@happyvertical/smrt-tenancy": "^0.38.3",
-    "@happyvertical/smrt-users": "^0.38.3"
+    "@happyvertical/smrt-core": "^0.38.4",
+    "@happyvertical/smrt-svelte": "^0.38.4",
+    "@happyvertical/smrt-tenancy": "^0.38.4",
+    "@happyvertical/smrt-ui": "^0.38.4",
+    "@happyvertical/smrt-users": "^0.38.4"
   }
 }

package/template/src/routes/+layout.server.ts

@@ -0,0 +1,69 @@
+/**
+ * Root layout server load — builds the AdminShell tenant navigation.
+ *
+ * The WASD AdminShell (`src/routes/+layout.svelte`) is the default chrome for
+ * this app. Its left "tenant" rail is driven by a nav tree derived from the
+ * SMRT manifest, and that tree is built HERE — server-side — rather than with a
+ * client-side fetch. This mirrors the home page's data pattern
+ * (`+page.server.ts`): data is produced during SSR, serialized into the initial
+ * HTML, and hydrated on the client with no duplicate request.
+ *
+ * `tenantNavFromManifest()` is a pure function (data in → data out). It reads
+ * the same generated manifest the runtime uses (`.smrt/manifest.json`, written
+ * by `smrtPlugin()` and already loaded by `src/lib/server/smrt.ts`), so the nav
+ * stays in sync with your `@smrt()` classes automatically instead of being
+ * hand-maintained.
+ *
+ * This load reads no URL/params and declares no `depends()`, so after its
+ * initial SSR run SvelteKit does not re-run it on client navigations — only on
+ * a full reload or `invalidateAll()`. The manifest-derived nav is therefore
+ * effectively static for the session, which is fine (the manifest is fixed at
+ * build time). It is independent of each page's own load, so the home page's
+ * `depends('smrt:items')` / `invalidate('smrt:items')` refresh flow is
+ * untouched by this file.
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+
+import { loadManifestFromPathSync } from '@happyvertical/smrt-core/manifest';
+import {
+  type ShellNavItem,
+  type SmrtManifestLike,
+  tenantNavFromManifest,
+} from '@happyvertical/smrt-svelte/workspace';
+import type { LayoutServerLoad } from './$types';
+
+export const load: LayoutServerLoad = async () => {
+  // Same manifest file `src/lib/server/smrt.ts` seeds the registry from. Reading
+  // it here returns the parsed object we hand to the pure nav builder; if it is
+  // not generated yet (fresh checkout before the first `vite dev`/`vite build`)
+  // we fall back to an empty rail rather than failing the whole layout.
+  const manifestPath = join(process.cwd(), '.smrt', 'manifest.json');
+
+  let nav: ShellNavItem[] = [];
+  if (existsSync(manifestPath)) {
+    const manifest = loadManifestFromPathSync(manifestPath);
+    if (manifest) {
+      // `tenantNavFromManifest` reads a documented subset of the manifest
+      // (`SmrtManifestLike`). The core `SmartObjectManifest` carries richer
+      // field types (e.g. `ApiConfig` has no index signature), so narrow it to
+      // the structural shape the pure helper consumes.
+      //
+      // `basePath: ''` emits page-style hrefs (`/items`) for the developer to
+      // wire to their own list routes. `sectionHints` groups classes by
+      // package into readable section titles — extend it as you add packages.
+      // `NavSection[]` is structurally a superset of `ShellNavItem[]`, so it
+      // feeds straight into <TenantNav items={nav}>.
+      nav = tenantNavFromManifest(manifest as unknown as SmrtManifestLike, {
+        basePath: '',
+        sectionHints: {
+          '@happyvertical/smrt-content': 'Content',
+          '@happyvertical/smrt-users': 'Users',
+        },
+      });
+    }
+  }
+
+  return { nav };
+};

package/template/src/routes/+layout.svelte

@@ -0,0 +1,110 @@
+<script lang="ts">
+  import { page } from '$app/state';
+  import {
+    AdminShell,
+    AppScopePanel,
+    type ShellStatusChip,
+    SystemStatusChips,
+    TenantNav,
+  } from '@happyvertical/smrt-svelte/workspace';
+  import { ThemeProvider } from '@happyvertical/smrt-ui/themes';
+  // Self-hosted @font-face rules for the SMRT type stack (Space Grotesk /
+  // Inter / JetBrains Mono woff2). `<ThemeProvider>` supplies every `--smrt-*`
+  // token variable at runtime, but not the font FILES — this import loads them
+  // so `--smrt-font-family` renders as the real stack instead of falling back
+  // to system-ui. Bundled with the app; no CDN request.
+  import '@happyvertical/smrt-ui/themes/styles/fonts.css';
+  import type { LayoutProps } from './$types';
+
+  // `data.nav` is built server-side in `+layout.server.ts` from the SMRT
+  // manifest and hydrated here — no client-side nav fetch. `children` is the
+  // active page, which renders inside AdminShell's `<main>` and keeps its own
+  // server load + `invalidate` flow (see `+page.server.ts`).
+  let { data, children }: LayoutProps = $props();
+
+  // Both wrappers are SSR-safe. ThemeProvider emits its `--smrt-*` token
+  // variables as an inline style computed during render (no `window`), so the
+  // tokens are present in the server HTML with no unstyled flash; it only reads
+  // `matchMedia` after mount to resolve `colorScheme="system"`. AdminShell's
+  // public core likewise renders statically and only wires WASD hotkeys /
+  // localStorage persistence after mount. Nothing here reads `window` or
+  // `localStorage` at module or render time. `$app/state`'s `page` is populated
+  // on the server too, so `currentHref` is correct on first paint.
+  const currentHref = $derived(page.url.pathname);
+
+  // Minimal, static system chips. Full live wiring (job counts, dispatch
+  // depth, connection state) is a documented next step: feed real values
+  // through `systemFeed` (`@happyvertical/smrt-svelte/workspace/live`) or
+  // `activityFeed` (`@happyvertical/smrt-svelte/web`)
+  // — see the migration guide and the playground `admin-shell-system-feed`
+  // demo. Keeping these static here avoids loading the client engine on every
+  // page of the scaffold.
+  const statusChips: ShellStatusChip[] = [
+    { id: 'env', label: 'Local', tone: 'info' },
+    { id: 'connection', label: 'Ready', tone: 'success' },
+  ];
+</script>
+
+<!--
+  ThemeProvider is the standard SMRT theming wrapper (mirrors the reference app
+  `@happyvertical/smrt-content` → `src/routes/+layout.svelte`). It injects the
+  full `--smrt-*` token set the shell and pages consume, and `colorScheme="system"`
+  follows the OS light/dark preference at runtime; `persist` remembers a user's
+  explicit choice. Wrap it OUTERMOST so AdminShell and every page render themed.
+-->
+<ThemeProvider colorScheme="system" persist={true}>
+<AdminShell title="SMRT App" subtitle="SvelteKit" storageKey="smrt-app-shell">
+  {#snippet appPanel()}
+    <AppScopePanel
+      appName="SMRT App"
+      tenantName="Local development"
+      environment="local"
+      showSettings={false}
+    >
+      {#snippet docs()}
+        <nav class="app-scope-links">
+          <a href="/settings">Shell settings</a>
+        </nav>
+      {/snippet}
+    </AppScopePanel>
+  {/snippet}
+
+  {#snippet tenantPanel()}
+    <TenantNav items={data.nav} {currentHref} />
+  {/snippet}
+
+  {#snippet systemBar()}
+    <div class="system-bar">
+      <SystemStatusChips chips={statusChips} />
+      <a class="system-bar__settings" href="/settings">Settings</a>
+    </div>
+  {/snippet}
+
+  {@render children()}
+</AdminShell>
+</ThemeProvider>
+
+<style>
+  :global(body) {
+    margin: 0;
+  }
+
+  .app-scope-links {
+    display: grid;
+    gap: var(--smrt-spacing-1);
+  }
+
+  .app-scope-links a,
+  .system-bar__settings {
+    color: var(--smrt-color-primary);
+    text-decoration: none;
+  }
+
+  .system-bar {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--smrt-spacing-3);
+    inline-size: 100%;
+  }
+</style>

package/template/src/routes/+page.svelte

@@ -16,7 +16,14 @@
   <title>SMRT SvelteKit App</title>
 </svelte:head>
 
-<main>
+<!--
+  This page renders inside the root layout's <AdminShell> `<main>`
+  (`src/routes/+layout.svelte`). Its server load + `invalidate('smrt:items')`
+  refresh flow is unchanged by the shell — the shell is chrome around the
+  page, not a replacement for its data loading. A plain wrapper element (not a
+  second <main>) keeps the HTML valid.
+-->
+<div class="page">
   <h1>Welcome to SMRT + SvelteKit</h1>
 
   <section>
@@ -94,10 +101,10 @@
       <li>API routes are auto-generated in <code>src/routes/api/</code></li>
     </ul>
   </section>
-</main>
+</div>
 
 <style>
-  main {
+  .page {
     max-width: 800px;
     margin: 0 auto;
     padding: 2rem;

package/template/src/routes/settings/+page.svelte

@@ -0,0 +1,41 @@
+<script lang="ts">
+  import { ShellSettingsPanel } from '@happyvertical/smrt-svelte/workspace';
+
+  // This page renders inside the root layout's <AdminShell>, so the shell
+  // context set by AdminShell is available to descendants — ShellSettingsPanel
+  // reads it via useAdminShell() with no extra wiring. It lets users toggle
+  // panel visibility and remap the WASD hotkeys; changes persist through the
+  // shell's `storageKey` (localStorage), applied client-side after mount.
+</script>
+
+<svelte:head>
+  <title>Settings · SMRT App</title>
+</svelte:head>
+
+<section class="settings">
+  <header>
+    <h1>Settings</h1>
+    <p>Adjust the workspace shell — panel layout and keyboard shortcuts.</p>
+  </header>
+
+  <ShellSettingsPanel />
+</section>
+
+<style>
+  .settings {
+    display: grid;
+    gap: var(--smrt-spacing-6, 1.5rem);
+    max-width: 720px;
+    padding: var(--smrt-spacing-8, 2rem);
+  }
+
+  .settings header {
+    display: grid;
+    gap: var(--smrt-spacing-2, 0.5rem);
+  }
+
+  .settings h1,
+  .settings p {
+    margin: 0;
+  }
+</style>