@happyvertical/smrt-template-sveltekit 0.37.5 → 0.37.7

package/AGENTS.md

@@ -12,8 +12,10 @@ Base SvelteKit project template used by `smrt init`. Scaffolds a full-stack, mul
 
 - `template/src/hooks.server.ts` — pre-wires `enableTenancy()`, `createSessionHandler({ enterTenantContext: true })`, and a subdomain → tenantId handle, sequenced in that order
 - `template/src/lib/server/tenancy.ts` — pluggable tenant resolver (`subdomainStrategy`, `pathPrefixStrategy`, `headerStrategy`, `createTenantResolver`)
-- `template/src/lib/server/smrt.ts` — centralized SmrtClassOptions / collection factory
+- `template/src/lib/server/smrt.ts` — centralized SmrtClassOptions / collection factory; imports the plugin-generated `smrt-register.js` (guarded — the file is gitignored and regenerated on every dev/build run) and seeds `.smrt/manifest.json` so server runtimes get package-qualified registrations + scanned field metadata (without them, writes silently drop domain columns)
+- `template/vite.config.ts` — smrtPlugin() + smrtConsumer(), plus explicit `oxc: { decorator: { legacy: true } }` (Vite 8's oxc transform does not reliably honor `experimentalDecorators` through the SvelteKit tsconfig `extends` chain)
 - `template/src/lib/objects/Item.ts` — example `@smrt()` object
+- `template/src/routes/+page.server.ts` + `+page.svelte` — reference SSR data loading: server load queries collections directly (opt-in read cache via `cache: { ttl }`), declares `depends('smrt:items')`, and a form action + `invalidate('smrt:items')` demonstrates post-mutation refresh
 - `template/src/app.d.ts` — `App.Locals` extends `SessionLocals` from `@happyvertical/smrt-users/sveltekit`
 
 ## Test Infrastructure
@@ -23,6 +25,7 @@ Base SvelteKit project template used by `smrt init`. Scaffolds a full-stack, mul
 
 ## Key Patterns
 
+- **SSR data loading convention**: reference pages load collection data in `+page.server.ts` (serialized into the HTML, hydrated without a duplicate client fetch). Loads declare `depends('smrt:<collection>')` (REST route segment naming: `/api/items` → `smrt:items`); mutations call `invalidate('smrt:<collection>')` to re-run them.
 - **Pluggable tenant resolver**: `tenancy.ts` exports strategy functions + a `createTenantResolver()` factory. Consumers swap strategies by editing one line.
 - **File copying with placeholder substitution**: project name is replaced in template files during generation.
 - **No template-internal test pollution**: `__tests__/` and the `.svelte-kit/` stub are package-level and excluded from `copyTemplate` output.

package/README.md

@@ -7,6 +7,7 @@ SvelteKit project template with SMRT framework integration. Scaffolds a full-sta
 - SvelteKit 2.x with Svelte 5 and TypeScript
 - `smrtPlugin()` Vite integration for automatic REST API route generation
 - Example `@smrt()` object (`Item.ts`) with barrel export
+- Reference SSR data loading: `+page.server.ts` server load with the `depends('smrt:<collection>')` / `invalidate('smrt:<collection>')` refresh convention and opt-in collection read caching
 - Server-side SMRT initialization (`src/lib/server/smrt.ts`)
 - `smrt.config.ts` with SQLite database and optional AI provider
 - `.env.example` with starter environment variables
@@ -81,9 +82,11 @@ template/
     │   │   ├── index.ts    # Barrel export
     │   │   └── Item.ts     # Example @smrt() object
     │   └── server/
-    │       ├── smrt.ts     # Server-side SMRT initialization
+    │       ├── smrt.ts     # Server-side SMRT initialization + manifest seeding
+    │       ├── smrt-register.ts # Object registration (generated by smrtPlugin, gitignored)
     │       └── tenancy.ts  # Pluggable tenant resolver
     └── routes/
+        ├── +page.server.ts # Home page server load + demo mutation (reference pattern)
         └── +page.svelte    # Home page
 ```
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@happyvertical/smrt-template-sveltekit",
-  "version": "0.37.5",
+  "version": "0.37.7",
   "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.37.5"
+    "@happyvertical/smrt-core": "0.37.7"
   },
   "devDependencies": {
     "vitest": "^4.1.9"

package/template/AGENTS.md

@@ -16,6 +16,15 @@ tools, and agent/developer knowledge artifacts.
 
 ## Package Guidance
 
+- Load page data in `+page.server.ts` server loads that query collections
+  directly (see `src/routes/+page.server.ts`); never fetch `/api/*` from
+  `$effect`/`onMount` for initial page data.
+- Declare `depends('smrt:<collection>')` in loads (route segment naming:
+  `/api/items` → `smrt:items`) and call `invalidate('smrt:<collection>')`
+  after mutations to refresh in place.
+- Opt read-heavy SSR reads into the collection cache with
+  `list({ cache: { ttl } })`; skip it for per-user data and admin editors
+  (see README "Data loading").
 - Keep SMRT object relationship metadata close to the `@smrt()` decorator.
 - Use `knowledge: false` only for objects that should stay out of authored
   agent context while remaining in the runtime manifest.

package/template/README.md

@@ -34,16 +34,137 @@ A SvelteKit application with SMRT framework integration for rapid development of
 │   │   │   ├── index.ts       # Export all objects here
 │   │   │   └── Item.ts        # Example SMRT object
 │   │   └── server/
-│   │       ├── smrt.ts        # SMRT configuration
+│   │       ├── smrt.ts        # SMRT configuration + local manifest seeding
+│   │       ├── smrt-register.ts # Object registration (generated by smrtPlugin, gitignored)
 │   │       └── tenancy.ts     # Pluggable tenant resolver
 │   └── routes/
 │       ├── api/               # Auto-generated API routes (don't edit!)
+│       ├── +page.server.ts    # Home page server load + demo mutation (reference pattern)
 │       └── +page.svelte       # Home page
 ├── smrt.config.ts             # Root SMRT config
 ├── vite.config.ts             # Vite + SMRT plugin config
 └── svelte.config.js           # SvelteKit config
 ```
 
+## Data loading (SSR + hydration)
+
+The home page (`src/routes/+page.server.ts` + `+page.svelte`) is the reference
+pattern for getting collection data onto a page. Copy it for your own routes.
+
+**Query collections in a server `load`, not with `fetch` on mount.** A server
+load runs during SSR, reads the database directly through the collection API
+(no HTTP round-trip through your own `/api/*` routes), and SvelteKit
+serializes the result into the initial HTML. The client hydrates that data
+without re-fetching — the page renders with its data on first paint, and the
+first client render issues no duplicate request.
+
+```typescript
+// src/routes/+page.server.ts
+import type { Item } from '$lib/objects/Item';
+import { getCollection } from '$lib/server/smrt';
+import type { PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async ({ depends }) => {
+  depends('smrt:items'); // see "Refreshing after mutations" below
+
+  const items = await getCollection<Item>('Item');
+  const rows = await items.list({ orderBy: 'created_at DESC', limit: 50 });
+
+  // Return plain serializable objects, not class instances.
+  return {
+    items: rows.map((item) => ({ id: item.id, title: item.title, status: item.status })),
+  };
+};
+```
+
+```svelte
+<!-- src/routes/+page.svelte -->
+<script lang="ts">
+  import type { PageProps } from './$types';
+
+  let { data }: PageProps = $props();
+</script>
+
+{#each data.items as item (item.id)}
+  <p>{item.title}</p>
+{/each}
+```
+
+Avoid the mount-time fetch anti-pattern (`$effect(() => { fetch('/api/items') ... })`):
+it renders an empty page first, waterfalls a second request on every
+navigation, and skips SvelteKit's load/hydration machinery entirely. Reserve
+client-side `fetch` of the generated `/api/*` routes for after-load
+interactions (mutations, polling, external clients) — not for initial page
+data.
+
+### Refreshing after mutations (`depends` / `invalidate`)
+
+Convention: each load declares one dependency key per collection it reads,
+named `smrt:<collection>` — where `<collection>` is the generated REST route
+segment (`/api/items` → `smrt:items`). After a mutation, client code calls
+`invalidate('smrt:<collection>')` and every load that declared that key
+re-runs, updating the page in place:
+
+```svelte
+<script lang="ts">
+  import { invalidate } from '$app/navigation';
+
+  async function createItem(title: string) {
+    await fetch('/api/items', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ title }),
+    });
+    await invalidate('smrt:items'); // re-runs every load that declared depends('smrt:items')
+  }
+</script>
+```
+
+The home page demonstrates the same flow with a progressively-enhanced form
+action: `use:enhance` applies the action result with
+`update({ invalidateAll: false })`, then calls `invalidate('smrt:items')` so
+only the loads that depend on items re-run (instead of SvelteKit's default
+invalidate-everything). Note that the generated `/api/*` routes are
+fail-closed — mutations 401 unless the request is authenticated or the object
+opts in via `@smrt({ api: { public: true } })` — which is why the demo uses a
+form action running server-side.
+
+### Caching SSR reads
+
+Server-side reads can opt into the collection read cache, per call or per
+model:
+
+```typescript
+// Per call — this load only
+const rows = await items.list({ where: { status: 'published' }, cache: { ttl: 60_000 } });
+
+// Per model — every read of this collection
+@smrt({ cache: { ttl: 60_000 } })
+export class Item extends SmrtObject { /* ... */ }
+```
+
+Cached rows are keyed by the final SQL + parameters and live for `ttl`
+milliseconds. Every mutation that goes through SMRT (`create()`, `save()`,
+`delete()`) invalidates the table's cached entries in this process
+automatically — so the post-mutation `invalidate('smrt:...')` re-run sees
+fresh rows, as the home page demonstrates.
+
+Use it for read-heavy, write-rare data rendered for many visitors: catalogs,
+published content, navigation. Do **not** cache:
+
+- **Per-user data** (dashboards, "my items"): each user's query shape churns
+  the cache for little reuse, and any staleness is personally visible.
+- **Admin editors / read-your-writes flows**: editors must always see the
+  row they just changed, including across processes.
+- **Multi-replica deployments without `crossProcess: true`**: the cache is
+  per-process, so a write on one replica leaves the others stale until TTL.
+  Set `cache: { ttl, crossProcess: true }` (uses the database adapter's
+  notification capability, e.g. Postgres LISTEN/NOTIFY) or keep the TTL
+  short enough to tolerate.
+
+Pass `cache: false` on a specific call to bypass a model-level cache where
+freshness matters.
+
 ## Multi-tenancy
 
 This template ships with multi-tenancy pre-wired. Out of the box you get:

package/template/package.json

@@ -20,8 +20,8 @@
     "vite": "^8.1.2"
   },
   "dependencies": {
-    "@happyvertical/smrt-core": "^0.37.5",
-    "@happyvertical/smrt-tenancy": "^0.37.5",
-    "@happyvertical/smrt-users": "^0.37.5"
+    "@happyvertical/smrt-core": "^0.37.7",
+    "@happyvertical/smrt-tenancy": "^0.37.7",
+    "@happyvertical/smrt-users": "^0.37.7"
   }
 }

package/template/src/hooks.server.ts

@@ -25,7 +25,7 @@
  */
 
 import { sequence } from '@sveltejs/kit/hooks';
-import type { Handle, RequestEvent } from '@sveltejs/kit';
+import type { Handle } from '@sveltejs/kit';
 
 import { createSessionHandler } from '@happyvertical/smrt-users/sveltekit';
 import {
@@ -59,9 +59,10 @@ enableTenancy();
  */
 const tenancyHandle = createSvelteKitHandle({
   resolveTenantId: async (event) => {
-    // The createSvelteKitHandle adapter passes a structural event; our
-    // resolver accepts that same shape.
-    const result = await resolveTenant(event as RequestEvent);
+    // The createSvelteKitHandle adapter passes a structural event that is
+    // directly assignable to the resolver's `TenantResolverEvent` shape
+    // (`url` + `request.headers`), so no cast is needed.
+    const result = await resolveTenant(event);
     return result.tenantId;
   },
 }) as unknown as Handle;

package/template/src/lib/server/smrt.ts

@@ -5,11 +5,41 @@
  * Import this file in your routes to get properly configured collections.
  */
 
-import { ObjectRegistry, type SmrtClassOptions } from '@happyvertical/smrt-core';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
 
-// Import all SMRT objects to register them
+import {
+  ObjectRegistry,
+  type SmrtClassOptions,
+  type SmrtObject,
+} from '@happyvertical/smrt-core';
+import { loadManifestFromPathSync } from '@happyvertical/smrt-core/manifest';
+
+// Import all SMRT objects to register them.
 import '../objects/index.js';
 
+// Upgrade those registrations to package-qualified identities
+// (`<package>:<Class>`) — required to link each class to its scanned field
+// metadata below. smrtPlugin() generates this module on every dev/build run
+// (it is gitignored, like the generated API routes); guard the import so a
+// fresh checkout that has not run the plugin yet still boots.
+try {
+  await import('./smrt-register.js');
+} catch {
+  // Not generated yet — the first `vite dev` / `vite build` will create it.
+}
+
+// Hydrate field metadata for this app's own objects from the local manifest
+// written by smrtPlugin() (`.smrt/manifest.json`). The decorator import above
+// registers the classes, but their scanned field metadata (plain properties
+// like `title: string = ''`) lives in the manifest — without seeding it, the
+// runtime only knows the framework base fields and server-side writes would
+// silently drop your domain columns.
+const localManifestPath = join(process.cwd(), '.smrt', 'manifest.json');
+if (existsSync(localManifestPath)) {
+  loadManifestFromPathSync(localManifestPath);
+}
+
 declare global {
   // eslint-disable-next-line no-var
   var __smrtGetRequestScopedDatabase:
@@ -67,7 +97,7 @@ export function getSmrtConfig(className: string): SmrtClassOptions {
  *   const products = await getCollection<Product>('Product');
  *   const items = await products.list();
  */
-export async function getCollection<T>(className: string) {
+export async function getCollection<T extends SmrtObject>(className: string) {
   const config = getSmrtConfig(className);
   const objectOverride = objectOverrides[className];
   const requestScopedDb = objectOverride?.db

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

@@ -0,0 +1,107 @@
+/**
+ * Home page server load + demo mutation.
+ *
+ * This file is the reference data-loading pattern for SMRT + SvelteKit apps:
+ *
+ *   1. **Query collections in a server `load`** — not with a client-side
+ *      `fetch` on mount. SvelteKit runs this during SSR, serializes the
+ *      returned data into the initial HTML, and hydrates it on the client
+ *      without re-fetching. The page renders with its data on first paint;
+ *      there is no empty-then-fetch waterfall and no duplicate first-render
+ *      request. Server loads read the database directly through the
+ *      collection API — they do not round-trip through your own
+ *      `/api/*` routes.
+ *
+ *   2. **Declare one dependency key per collection** with
+ *      `depends('smrt:<collection>')`, where `<collection>` matches the
+ *      generated REST route segment (`/api/items` → `smrt:items`). After a
+ *      mutation, client code calls `invalidate('smrt:<collection>')`
+ *      (see `+page.svelte`) and every load that declared the key re-runs.
+ *
+ *   3. **Opt read-heavy SSR reads into the collection read cache** with
+ *      `cache: { ttl }`. Mutations that go through SMRT (`create()`,
+ *      `save()`, `delete()`) invalidate the table's cache entries
+ *      in-process automatically, so the post-mutation `invalidate()`
+ *      re-runs this load against fresh rows. See "Data loading" in the
+ *      README for multi-replica caveats and when NOT to cache.
+ */
+
+import { fail } from '@sveltejs/kit';
+import type { Item } from '$lib/objects/Item';
+import { getCollection } from '$lib/server/smrt';
+import type { Actions, PageServerLoad } from './$types';
+
+export const load: PageServerLoad = async ({ depends }) => {
+  // Convention: `smrt:<collection>`. Registered before the query so even a
+  // failed load (e.g. database not initialized yet) re-runs on invalidation.
+  depends('smrt:items');
+
+  try {
+    const items = await getCollection<Item>('Item');
+    const rows = await items.list({
+      orderBy: 'created_at DESC',
+      limit: 50,
+      // Opt this SSR read into the collection read cache (issue #1499).
+      // Safe here because all writes go through SMRT, which invalidates the
+      // table's entries in this process. Running multiple replicas? Add
+      // `crossProcess: true` or drop the cache — see the README.
+      cache: { ttl: 30_000 },
+    });
+
+    return {
+      // Return plain serializable objects: SvelteKit encodes load data into
+      // the initial HTML with devalue, so pick the fields the page needs
+      // rather than returning class instances. Persisted rows always carry a
+      // UUID `id`; the filter narrows the field's `string | null | undefined`
+      // type instead of coercing — a '' fallback would produce colliding
+      // `{#each}` keys if an id were ever missing.
+      items: rows
+        .filter((item): item is Item & { id: string } => Boolean(item.id))
+        .map((item) => ({
+          id: item.id,
+          title: item.title,
+          status: item.status,
+        })),
+      loadError: null as string | null,
+    };
+  } catch (e) {
+    // First run before `smrt db:setup` has created the tables: render the
+    // page with guidance instead of a 500.
+    return {
+      items: [] as { id: string; title: string; status: string }[],
+      loadError: e instanceof Error ? e.message : 'Failed to load items',
+    };
+  }
+};
+
+export const actions: Actions = {
+  /**
+   * Demo mutation for the invalidation convention: creates an Item, then the
+   * client (`+page.svelte`) calls `invalidate('smrt:items')` so the load
+   * above re-runs and the new row appears without a full page reload.
+   *
+   * NOTE: this demo action is intentionally unauthenticated so the refresh
+   * flow works out of the box. Real mutations should be gated on
+   * `locals.user` / permissions (the generated `/api/*` routes are already
+   * fail-closed: they 401 unless authenticated or `@smrt({ api: { public } })`).
+   */
+  create: async ({ request }) => {
+    const form = await request.formData();
+    const title = String(form.get('title') ?? '').trim();
+
+    if (!title) {
+      return fail(400, { title, error: 'Title is required' });
+    }
+
+    try {
+      const items = await getCollection<Item>('Item');
+      await items.create({ title });
+      return { created: title };
+    } catch (e) {
+      return fail(500, {
+        title,
+        error: e instanceof Error ? e.message : 'Failed to create item',
+      });
+    }
+  },
+};

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

@@ -1,23 +1,15 @@
 <script lang="ts">
-  let items: any[] = $state([]);
-  let loading = $state(true);
-  let error: string | null = $state(null);
-
-  $effect(() => {
-    fetchItems();
-  });
-
-  async function fetchItems() {
-    try {
-      const response = await fetch('/api/items');
-      const data = await response.json();
-      items = data.items || [];
-    } catch (e) {
-      error = e instanceof Error ? e.message : 'Failed to fetch items';
-    } finally {
-      loading = false;
-    }
-  }
+  import { enhance } from '$app/forms';
+  import { invalidate } from '$app/navigation';
+  import type { PageProps } from './$types';
+
+  // `data` comes from the server load in `+page.server.ts`. It is fetched
+  // during SSR, serialized into the initial HTML, and hydrated here — the
+  // first client render issues NO fetch for it. It re-runs only when
+  // something calls `invalidate('smrt:items')` (below) or on navigation.
+  let { data, form }: PageProps = $props();
+
+  let creating = $state(false);
 </script>
 
 <svelte:head>
@@ -30,15 +22,14 @@
   <section>
     <h2>Items</h2>
 
-    {#if loading}
-      <p>Loading...</p>
-    {:else if error}
-      <p class="error">{error}</p>
-    {:else if items.length === 0}
-      <p>No items yet. Create your first item!</p>
+    {#if data.loadError}
+      <p class="error">{data.loadError}</p>
+      <p>If this is a fresh project, initialize the database with <code>smrt db:setup</code>.</p>
+    {:else if data.items.length === 0}
+      <p>No items yet. Create your first item below!</p>
     {:else}
       <ul>
-        {#each items as item}
+        {#each data.items as item (item.id)}
           <li>
             <strong>{item.title}</strong>
             <span class="status">{item.status}</span>
@@ -46,12 +37,58 @@
         {/each}
       </ul>
     {/if}
+
+    <!--
+      Post-mutation refresh convention: submit the mutation (a form action
+      here, but a fetch to a generated /api route works the same way), then
+      call `invalidate('smrt:items')`. Every load that declared
+      `depends('smrt:items')` re-runs and the list updates in place.
+      Without JavaScript this form still works — SvelteKit falls back to a
+      full-page POST + re-render.
+    -->
+    <form
+      method="POST"
+      action="?/create"
+      use:enhance={() => {
+        creating = true;
+        return async ({ result, update }) => {
+          try {
+            // Apply the action result (sets `form`, resets the input) but
+            // skip SvelteKit's default invalidateAll() — we re-run only the
+            // loads that depend on this collection.
+            await update({ invalidateAll: false });
+            if (result.type === 'success') {
+              await invalidate('smrt:items');
+            }
+          } finally {
+            // Always re-enable the form, even if update()/invalidate()
+            // throws (network error, aborted navigation, …).
+            creating = false;
+          }
+        };
+      }}
+    >
+      <input
+        name="title"
+        placeholder="New item title"
+        aria-label="New item title"
+        required
+      />
+      <button type="submit" disabled={creating}>
+        {creating ? 'Creating…' : 'Create item'}
+      </button>
+    </form>
+
+    {#if form?.error}
+      <p class="error">{form.error}</p>
+    {/if}
   </section>
 
   <section>
     <h2>Getting Started</h2>
     <ul>
       <li>Edit <code>src/lib/objects/Item.ts</code> to customize your SMRT object</li>
+      <li>Load data in <code>+page.server.ts</code> files — see this page's load for the SSR + <code>depends</code>/<code>invalidate</code> pattern</li>
       <li>Run <code>smrt objects</code> to see registered objects</li>
       <li>Run <code>smrt generate-routes</code> to regenerate API routes</li>
       <li>API routes are auto-generated in <code>src/routes/api/</code></li>
@@ -90,6 +127,35 @@
     margin-left: 8px;
   }
 
+  form {
+    display: flex;
+    gap: 0.5rem;
+    margin-top: 1rem;
+  }
+
+  input {
+    flex: 1;
+    padding: 0.5rem;
+    border: 1px solid #ccc;
+    border-radius: var(--smrt-radius-sm, 4px);
+    font-size: 1em;
+  }
+
+  button {
+    padding: 0.5rem 1rem;
+    border: none;
+    border-radius: var(--smrt-radius-sm, 4px);
+    background: #667eea;
+    color: white;
+    font-size: 1em;
+    cursor: pointer;
+  }
+
+  button:disabled {
+    opacity: 0.6;
+    cursor: wait;
+  }
+
   code {
     background: #e0e0e0;
     padding: 2px 6px;

package/template/vite.config.ts

@@ -1,8 +1,21 @@
 import { sveltekit } from '@sveltejs/kit/vite';
+import { smrtConsumer } from '@happyvertical/smrt-core/consumer-plugin';
 import { smrtPlugin } from '@happyvertical/smrt-core/vite-plugin';
 import { defineConfig } from 'vite';
 
 export default defineConfig({
+  // Lower `@smrt()` legacy (experimentalDecorators) decorators explicitly.
+  // tsconfig.json sets experimentalDecorators, but Vite's oxc transform does
+  // not reliably honor it through the SvelteKit `extends
+  // "./.svelte-kit/tsconfig.json"` chain — raw `@decorator class` syntax then
+  // reaches the SSR runtime and throws `SyntaxError: Invalid or unexpected
+  // token` on the first request.
+  oxc: {
+    decorator: {
+      legacy: true,
+      emitDecoratorMetadata: true,
+    },
+  },
   plugins: [
     sveltekit(),
     smrtPlugin({
@@ -17,5 +30,9 @@ export default defineConfig({
         configFileName: 'smrt.ts',
       },
     }),
+    // Required alongside smrtPlugin(): this project depends on external SMRT
+    // packages (@happyvertical/smrt-users, smrt-tenancy, …), and the consumer
+    // plugin emits `.smrt/register.js` so their classes load for CLI/runtime.
+    smrtConsumer(),
   ],
 });