@saena-io/create 0.1.0

package/template/base/src/admin/data.ts

@@ -0,0 +1,261 @@
+import { getAdminContextFn } from '@/server/admin-context';
+import { getBrandingFn, saveBrandingFn } from '@/server/branding';
+import { getBusinessProfileFn, saveBusinessProfileFn } from '@/server/business-profile';
+import {
+  createStaffFn,
+  deleteStaffFn,
+  listRolesFn,
+  listStaffFn,
+  updateStaffRoleFn,
+} from '@/server/team';
+import {
+  addLocaleFn,
+  listLocalesFn,
+  listTranslationsFn,
+  removeLocaleFn,
+  setMainLocaleFn,
+  setReviewedFn,
+  setTranslationFn,
+} from '@/server/translations';
+import {
+  ADMIN_CONTEXT_KEY,
+  type AdminContextRecord,
+  type AdminData,
+  BRANDING_KEY,
+  BUSINESS_PROFILE_KEY,
+  type BrandingRecord,
+  type BusinessProfileRecord,
+  type LocaleRecord,
+  // SAENA:translation:line
+  MACHINE_TRANSLATE_SERVICE,
+  type RoleRecord,
+  type StaffRecord,
+  type TranslationCell,
+  type TranslationEdit,
+} from '@saena-io/admin';
+import type { StaffCreateInput } from '@saena-io/plugin-sdk';
+// SAENA:translation:start
+import { translationFns } from '@saena-io/translation/contract';
+// SAENA:translation:end
+import { createCollection } from '@tanstack/db';
+import { QueryClient } from '@tanstack/query-core';
+import { queryCollectionOptions } from '@tanstack/query-db-collection';
+
+// The host-built admin data layer: TanStack DB collections that call the server functions (which reach
+// core) and are injected into the shell via <AdminDataProvider>, so @saena-io/admin never imports the host
+// or core (the boundary, ARCHITECTURE.md §13). Collections start syncing as soon as they're created, so
+// they are built LAZILY — once, on first use by the authed shell (getAdminData below) — to avoid a
+// wasted, unauthorised fetch on the public login page.
+
+let cached: AdminData | undefined;
+
+/** Build the admin collections once, on first call. Called from inside the authenticated shell only. */
+export function getAdminData(): AdminData {
+  if (cached) return cached;
+
+  const queryClient = new QueryClient();
+
+  // The business profile is a single project-wide record (§5); model it as a one-row collection keyed by
+  // a constant so admin pages read it with useLiveQuery and write optimistically through the server
+  // functions.
+  const businessProfile = createCollection(
+    queryCollectionOptions<BusinessProfileRecord>({
+      id: 'business-profile',
+      queryKey: ['business-profile'],
+      queryClient,
+      getKey: (item) => item.id,
+      queryFn: async () => {
+        const profile = await getBusinessProfileFn();
+        return profile ? [{ id: BUSINESS_PROFILE_KEY, ...profile }] : [];
+      },
+      // Insert (first-time) and update both map to the single upsert server fn. The synthetic `id` is
+      // dropped by the schema validator (zod strips unknown keys) before it reaches core.
+      onInsert: async ({ transaction }) => {
+        for (const m of transaction.mutations) await saveBusinessProfileFn({ data: m.modified });
+      },
+      onUpdate: async ({ transaction }) => {
+        for (const m of transaction.mutations) await saveBusinessProfileFn({ data: m.modified });
+      },
+    }),
+  );
+
+  // Branding is another single project-wide record (§5) — the same one-row collection shape as the
+  // business profile, keyed by a constant and upserted through one server function.
+  const branding = createCollection(
+    queryCollectionOptions<BrandingRecord>({
+      id: 'branding',
+      queryKey: ['branding'],
+      queryClient,
+      getKey: (item) => item.id,
+      queryFn: async () => {
+        const record = await getBrandingFn();
+        return record ? [{ id: BRANDING_KEY, ...record }] : [];
+      },
+      onInsert: async ({ transaction }) => {
+        for (const m of transaction.mutations) await saveBrandingFn({ data: m.modified });
+      },
+      onUpdate: async ({ transaction }) => {
+        for (const m of transaction.mutations) await saveBrandingFn({ data: m.modified });
+      },
+    }),
+  );
+
+  // Team / RBAC (§10). Staff is read + role-reassign + remove via the collection; CREATE is a one-shot
+  // action (createStaff) because better-auth owns the id and the password must not enter the collection.
+  const staff = createCollection(
+    queryCollectionOptions<StaffRecord>({
+      id: 'staff',
+      queryKey: ['staff'],
+      queryClient,
+      getKey: (item) => item.id,
+      queryFn: () => listStaffFn(),
+      onUpdate: async ({ transaction }) => {
+        for (const m of transaction.mutations) await updateStaffRoleFn({ data: m.modified });
+      },
+      onDelete: async ({ transaction }) => {
+        for (const m of transaction.mutations) await deleteStaffFn({ data: { id: String(m.key) } });
+      },
+    }),
+  );
+
+  // Roles are read-only (ADR-0012 phase 3): the predefined Admin/Owner/Editor, seeded at deploy by
+  // `ensureRoles`. The admin lists them to assign to members + shows a read-only reference — no create/edit/
+  // delete, so the collection has no mutation handlers.
+  const roles = createCollection(
+    queryCollectionOptions<RoleRecord>({
+      id: 'roles',
+      queryKey: ['roles'],
+      queryClient,
+      getKey: (item) => item.id,
+      queryFn: () => listRolesFn(),
+    }),
+  );
+
+  // The admin context (ADR-0012 phase 3): the signed-in actor's permission ids (for advisory nav/section
+  // gating) + the read-only predefined-role reference. A one-row collection keyed by a constant, like the
+  // single-record settings above; read-only (no mutations).
+  const adminContext = createCollection(
+    queryCollectionOptions<AdminContextRecord>({
+      id: 'admin-context',
+      queryKey: ['admin-context'],
+      queryClient,
+      getKey: (item) => item.id,
+      queryFn: async () => [{ id: ADMIN_CONTEXT_KEY, ...(await getAdminContextFn()) }],
+    }),
+  );
+
+  const createStaff = async (input: StaffCreateInput): Promise<void> => {
+    await createStaffFn({ data: input });
+    await queryClient.invalidateQueries({ queryKey: ['staff'] });
+  };
+
+  // Translations (§9, ADR-0005) — every (key, locale) value as a grid cell, loaded whole and
+  // searched/filtered client-side. The grid READS this; writes go through the actions below (which
+  // refetch), because editing the source re-stales sibling cells — a ripple a single optimistic row
+  // update can't express.
+  const translations = createCollection(
+    queryCollectionOptions<TranslationCell>({
+      id: 'translations',
+      queryKey: ['translations'],
+      queryClient,
+      getKey: (item) => item.id,
+      queryFn: async () => {
+        const rows = await listTranslationsFn();
+        return rows.map((r) => ({ id: `${r.key}::${r.locale}`, ...r }));
+      },
+    }),
+  );
+
+  // Project locales (read-only here; the source-locale swap is the setMainLocale action below, and
+  // add/remove-locale lands with the Languages settings UI).
+  const locales = createCollection(
+    queryCollectionOptions<LocaleRecord>({
+      id: 'locales',
+      queryKey: ['locales'],
+      queryClient,
+      getKey: (item) => item.code,
+      queryFn: () => listLocalesFn(),
+    }),
+  );
+
+  // Persist edits in the given order (caller passes the source edit first, so the translations it
+  // re-stales then re-anchor correctly), then refetch so the grid reflects the new values + staleness.
+  const saveTranslations = async (edits: TranslationEdit[]): Promise<void> => {
+    for (const e of edits) {
+      await setTranslationFn({ data: { key: e.key, locale: e.locale, text: e.text } });
+    }
+    await queryClient.invalidateQueries({ queryKey: ['translations'] });
+  };
+
+  const setTranslationReviewed = async (
+    key: string,
+    locale: string,
+    reviewed: boolean,
+  ): Promise<void> => {
+    await setReviewedFn({ data: { key, locale, reviewed } });
+    await queryClient.invalidateQueries({ queryKey: ['translations'] });
+  };
+
+  const addLocale = async (code: string, label: string): Promise<void> => {
+    await addLocaleFn({ data: { code, label } });
+    await queryClient.invalidateQueries({ queryKey: ['locales'] });
+  };
+
+  // Removing a locale deletes its translation values too, so refetch the grid as well.
+  const removeLocale = async (code: string): Promise<void> => {
+    await removeLocaleFn({ data: { code } });
+    await queryClient.invalidateQueries({ queryKey: ['locales'] });
+    await queryClient.invalidateQueries({ queryKey: ['translations'] });
+  };
+
+  // Swapping the main locale re-anchors staleness across every key server-side, so refetch both.
+  const setMainLocale = async (code: string): Promise<void> => {
+    await setMainLocaleFn({ data: { code } });
+    await queryClient.invalidateQueries({ queryKey: ['locales'] });
+    await queryClient.invalidateQueries({ queryKey: ['translations'] });
+  };
+
+  // SAENA:translation:start
+  // Machine/AI translation (ADR-0010): call the @saena-io/translation plugin fn via the generic /api/plugin
+  // dispatch. It writes an origin:'machine' value server-side, so refetch the grid to surface the chip.
+  const machineTranslate = async (input: {
+    key: string;
+    locale: string;
+    sourceText: string;
+    format: string;
+  }): Promise<{ text: string }> => {
+    const res = await fetch(`/api/plugin/${translationFns.translate}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify(input),
+    });
+    if (!res.ok) {
+      const body = (await res.json().catch(() => null)) as { error?: string } | null;
+      throw new Error(body?.error ?? `translate failed (${res.status})`);
+    }
+    const result = (await res.json()) as { text: string };
+    await queryClient.invalidateQueries({ queryKey: ['translations'] });
+    return result;
+  };
+  // SAENA:translation:end
+
+  cached = {
+    businessProfile,
+    branding,
+    staff,
+    roles,
+    adminContext,
+    createStaff,
+    translations,
+    locales,
+    addLocale,
+    removeLocale,
+    saveTranslations,
+    setTranslationReviewed,
+    setMainLocale,
+    // SAENA:translation:start
+    services: { [MACHINE_TRANSLATE_SERVICE]: machineTranslate },
+    // SAENA:translation:end
+  };
+  return cached;
+}

package/template/base/src/admin/registry.ts

@@ -0,0 +1,6 @@
+import { adminExtensions } from '@/plugins-admin';
+import { buildAdminRegistry } from '@saena-io/admin';
+
+// Plugin admin extensions, composed from the project manifest (ADR-0006). The core's fixed nav lives in
+// @saena-io/admin's coreRegistry; this is the plugin layer. The shell reads the result and never names a plugin.
+export const pluginRegistry = buildAdminRegistry(adminExtensions);

package/template/base/src/router.tsx

@@ -0,0 +1,19 @@
+import { createRouter as createTanStackRouter } from '@tanstack/react-router';
+import { routeTree } from './routeTree.gen';
+
+export function getRouter() {
+  const router = createTanStackRouter({
+    routeTree,
+    scrollRestoration: true,
+    defaultPreload: 'intent',
+    defaultPreloadStaleTime: 0,
+  });
+
+  return router;
+}
+
+declare module '@tanstack/react-router' {
+  interface Register {
+    router: ReturnType<typeof getRouter>;
+  }
+}

package/template/base/src/routes/__root.tsx

@@ -0,0 +1,34 @@
+import appCss from '@saena-io/ui/globals.css?url';
+import { HeadContent, Scripts, createRootRoute } from '@tanstack/react-router';
+
+export const Route = createRootRoute({
+  head: () => ({
+    meta: [
+      { charSet: 'utf-8' },
+      { name: 'viewport', content: 'width=device-width, initial-scale=1' },
+      { title: 'SAENA' },
+    ],
+    links: [{ rel: 'stylesheet', href: appCss }],
+  }),
+  notFoundComponent: () => (
+    <main className="container mx-auto p-4 pt-16">
+      <h1>404</h1>
+      <p>The requested page could not be found.</p>
+    </main>
+  ),
+  shellComponent: RootDocument,
+});
+
+function RootDocument({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <head>
+        <HeadContent />
+      </head>
+      <body>
+        {children}
+        <Scripts />
+      </body>
+    </html>
+  );
+}

package/template/base/src/routes/admin/$.tsx

@@ -0,0 +1,17 @@
+import { pluginRegistry } from '@/admin/registry';
+import { coreRegistry } from '@saena-io/admin';
+import { createFileRoute } from '@tanstack/react-router';
+
+// /admin/<path> → the core or plugin screen mapped to that path.
+export const Route = createFileRoute('/admin/$')({ component: AdminScreen });
+
+function AdminScreen() {
+  const { _splat } = Route.useParams();
+  const path = _splat ?? '';
+  const match = coreRegistry.routes.get(path) ?? pluginRegistry.routes.get(path);
+  if (!match) {
+    return <div className="p-6 text-muted-foreground text-sm">Screen not found: {path}</div>;
+  }
+  const Screen = match.component;
+  return <Screen />;
+}

package/template/base/src/routes/admin/index.tsx

@@ -0,0 +1,8 @@
+import { pluginRegistry } from '@/admin/registry';
+import { Dashboard, coreRegistry } from '@saena-io/admin';
+import { createFileRoute } from '@tanstack/react-router';
+
+// /admin → the dashboard (core + plugin widgets).
+export const Route = createFileRoute('/admin/')({
+  component: () => <Dashboard widgets={[...coreRegistry.widgets, ...pluginRegistry.widgets]} />,
+});

package/template/base/src/routes/admin/route.tsx

@@ -0,0 +1,29 @@
+import { getAdminData } from '@/admin/data';
+import { pluginRegistry } from '@/admin/registry';
+import { AdminDataProvider, AppShell, AuthGate } from '@saena-io/admin';
+import { Outlet, createFileRoute } from '@tanstack/react-router';
+
+// The /admin layout: gate first, then the data provider (host-built collections) + the shell (core nav
+// built in, plugin nav/settings from the registry).
+export const Route = createFileRoute('/admin')({ component: AdminLayout });
+
+function AdminLayout() {
+  return (
+    <AuthGate>
+      <AdminShell />
+    </AuthGate>
+  );
+}
+
+// Rendered only once authed (as AuthGate's child), so the host collections are built — and begin
+// fetching — here, never on the public login page.
+function AdminShell() {
+  const adminData = getAdminData();
+  return (
+    <AdminDataProvider value={adminData}>
+      <AppShell pluginNav={pluginRegistry.nav} pluginSettings={pluginRegistry.settings}>
+        <Outlet />
+      </AppShell>
+    </AdminDataProvider>
+  );
+}

package/template/base/src/routes/api/assets/$.ts

@@ -0,0 +1,125 @@
+import { resolveRequestActor } from '@/server/auth';
+import { getCoreContext, getCoreDb } from '@/server/core';
+import { createRequestContext } from '@saena-io/core';
+import { IMAGE_WIDTH_LADDER, type ImageTransform } from '@saena-io/plugin-sdk';
+import { createFileRoute } from '@tanstack/react-router';
+
+// Asset serving (ADR-0002 + ADR-0009): GET /api/assets/<id> streams the stored bytes. Resolves by registry id
+// (never a raw path → no FS-layout leak / traversal). Public assets serve to anyone; private assets require a
+// staff actor (404, not 403, so existence isn't confirmed). nosniff always; public assets are immutably
+// cacheable (a replace mints a new id), private assets must never enter a shared cache.
+//
+// With image transform params (w/ar/fx/fy/fmt) the route serves a derived variant instead of the original —
+// cropped to a ratio centred on the focal point, resized, and re-encoded. Derivatives are content-stable (the
+// id + params fully determine the bytes), so public ones are immutable too. No params ⇒ the original, as before.
+
+const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+const clamp = (n: number, lo: number, hi: number): number => Math.min(hi, Math.max(lo, n));
+
+/** Parse + clamp the derivative params from the query string. Returns null when none are present (serve the
+ *  original). Oversized/garbage values clamp or drop rather than erroring. */
+function parseTransform(params: URLSearchParams): ImageTransform | null {
+  // Snap the requested width to the nearest ladder entry: the public reader only ever emits ladder widths
+  // (identity-snap), while a direct/hostile caller can't balloon the derivative cache with arbitrary widths.
+  let width: number | undefined;
+  const w = Number(params.get('w'));
+  if (Number.isFinite(w) && w > 0) {
+    width = IMAGE_WIDTH_LADDER.reduce((best, cand) =>
+      Math.abs(cand - w) < Math.abs(best - w) ? cand : best,
+    );
+  }
+
+  let ar: number | undefined;
+  const arRaw = params.get('ar');
+  if (arRaw) {
+    let parsed: number | undefined;
+    if (arRaw.includes(':')) {
+      const [a, b] = arRaw.split(':').map(Number);
+      if (Number.isFinite(a) && Number.isFinite(b) && a > 0 && b > 0) parsed = a / b;
+    } else {
+      const n = Number(arRaw);
+      if (Number.isFinite(n) && n > 0) parsed = n;
+    }
+    if (parsed !== undefined) ar = clamp(parsed, 0.05, 20);
+  }
+
+  const unit = (key: string): number | undefined => {
+    const raw = params.get(key);
+    if (raw === null) return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) ? clamp(n, 0, 1) : undefined;
+  };
+  const fx = unit('fx');
+  const fy = unit('fy');
+
+  const fmtRaw = params.get('fmt');
+  const format = fmtRaw === 'webp' || fmtRaw === 'avif' || fmtRaw === 'orig' ? fmtRaw : undefined;
+
+  let q: number | undefined;
+  const qRaw = Number(params.get('q'));
+  if (Number.isFinite(qRaw) && qRaw > 0) q = Math.round(clamp(qRaw, 1, 100));
+
+  // `q` only matters alongside a real transform (it's an encoder lever) — don't trigger a derive on its own.
+  if (width === undefined && ar === undefined && format === undefined) return null;
+  return { width, ar, fx, fy, format, q };
+}
+
+/** Build the byte response with the right caching posture. Copy into a fresh ArrayBuffer — a guaranteed
+ *  BodyInit regardless of the source Uint8Array's backing buffer. */
+function bytesResponse(bytes: Uint8Array, mime: string, isPublic: boolean): Response {
+  const body = new ArrayBuffer(bytes.byteLength);
+  new Uint8Array(body).set(bytes);
+  const headers: Record<string, string> = {
+    'content-type': mime,
+    'content-length': String(bytes.byteLength),
+    'cache-control': isPublic ? 'public, max-age=31536000, immutable' : 'private, no-store',
+    'x-content-type-options': 'nosniff',
+  };
+  if (!isPublic) headers.vary = 'Cookie';
+  return new Response(body, { status: 200, headers });
+}
+
+async function serve(request: Request): Promise<Response> {
+  const notFound = () => new Response('Not found', { status: 404 });
+
+  const url = new URL(request.url);
+  let id: string;
+  try {
+    id = decodeURIComponent(url.pathname.replace(/^\/api\/assets\//, ''));
+  } catch {
+    return notFound(); // malformed percent-encoding
+  }
+  // Guard the shape so a non-uuid never reaches the uuid column (→ a clean 404, not a 500).
+  if (!UUID_RE.test(id)) return notFound();
+
+  const core = getCoreContext();
+  const stored = await core.storage.get(id);
+  if (!stored) return notFound();
+
+  if (!stored.ref.public) {
+    const ctx = await createRequestContext({
+      core,
+      db: getCoreDb(),
+      resolveActor: resolveRequestActor,
+      headers: request.headers,
+    });
+    if (ctx.actor.kind !== 'staff') return notFound();
+  }
+
+  // Image derivative (ADR-0009): generated + cached behind the storage seam. `derive` returns null for a
+  // non-image or an unreadable/untransformable source — fall through to the original in that case.
+  const spec = parseTransform(url.searchParams);
+  if (spec) {
+    const derived = await core.storage.derive(id, spec);
+    if (derived) return bytesResponse(derived.bytes, derived.mime, stored.ref.public);
+  }
+
+  const bytes = await core.storage.read(stored.storageKey);
+  if (!bytes) return notFound();
+  return bytesResponse(bytes, stored.ref.mime, stored.ref.public);
+}
+
+export const Route = createFileRoute('/api/assets/$')({
+  server: { handlers: { GET: ({ request }: { request: Request }) => serve(request) } },
+});

package/template/base/src/routes/api/assets/upload.ts

@@ -0,0 +1,99 @@
+import { resolveRequestActor } from '@/server/auth';
+import { getCoreContext, getCoreDb } from '@/server/core';
+import { PermissionDeniedError, createRequestContext } from '@saena-io/core';
+import { createFileRoute } from '@tanstack/react-router';
+
+// Asset upload (ADR-0002): POST /api/assets/upload with a multipart `file`. Gated by `content.manage` (the only
+// uploader today is the content plugin). Uses a raw ServerRoute handler — `createServerFn` is JSON-RPC and can't
+// carry a File. Returns the AssetRef the editor stores in content config.
+
+const MAX_UPLOAD_BYTES = 10 * 1024 * 1024; // 10 MB
+// SVG is excluded deliberately — inline SVG is an XSS vector when served from our origin (ADR-0002 v1).
+const ALLOWED_MIME = new Set(['image/png', 'image/jpeg', 'image/webp', 'image/gif', 'image/avif']);
+
+/**
+ * Detect an image's real type from its magic bytes — the client-declared `file.type` is attacker-controlled
+ * and trivially spoofed (M7 security review). We store the SNIFFED type, never the declared one, so a file
+ * mislabeled as an allowed image can't slip through.
+ */
+function sniffImageMime(b: Uint8Array): string | null {
+  if (b.length >= 8 && b[0] === 0x89 && b[1] === 0x50 && b[2] === 0x4e && b[3] === 0x47)
+    return 'image/png';
+  if (b.length >= 3 && b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return 'image/jpeg';
+  if (b.length >= 6 && b[0] === 0x47 && b[1] === 0x49 && b[2] === 0x46 && b[3] === 0x38)
+    return 'image/gif';
+  if (
+    b.length >= 12 &&
+    b[0] === 0x52 &&
+    b[1] === 0x49 &&
+    b[2] === 0x46 &&
+    b[3] === 0x46 && // "RIFF"
+    b[8] === 0x57 &&
+    b[9] === 0x45 &&
+    b[10] === 0x42 &&
+    b[11] === 0x50 // "WEBP"
+  )
+    return 'image/webp';
+  if (
+    b.length >= 12 &&
+    b[4] === 0x66 &&
+    b[5] === 0x74 &&
+    b[6] === 0x79 &&
+    b[7] === 0x70 && // "ftyp"
+    b[8] === 0x61 &&
+    b[9] === 0x76 &&
+    b[10] === 0x69 &&
+    b[11] === 0x66 // "avif"
+  )
+    return 'image/avif';
+  return null;
+}
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+async function upload(request: Request): Promise<Response> {
+  const ctx = await createRequestContext({
+    core: getCoreContext(),
+    db: getCoreDb(),
+    resolveActor: resolveRequestActor,
+    headers: request.headers,
+  });
+  try {
+    ctx.requirePermission('content.manage');
+  } catch (err) {
+    if (err instanceof PermissionDeniedError) return json({ error: err.message }, 403);
+    throw err;
+  }
+
+  const form = await request.formData().catch(() => null);
+  const file = form?.get('file');
+  if (!(file instanceof File)) return json({ error: 'no file provided' }, 400);
+  if (file.size > MAX_UPLOAD_BYTES) return json({ error: 'file too large (max 10 MB)' }, 413);
+
+  try {
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    // Validate by content, not the spoofable declared type; store the sniffed mime.
+    const mime = sniffImageMime(bytes);
+    if (!mime || !ALLOWED_MIME.has(mime)) {
+      return json(
+        { error: 'unsupported or invalid image (allowed: png, jpeg, webp, gif, avif)' },
+        415,
+      );
+    }
+    const createdBy = ctx.actor.kind === 'staff' ? ctx.actor.userId : undefined;
+    const ref = await ctx.storage.put({ bytes, mime, isPublic: true, createdBy });
+    return json(ref, 201);
+  } catch (err) {
+    ctx.logger.error('asset upload failed', { err: String(err) });
+    return json({ error: 'upload failed' }, 500);
+  }
+}
+
+export const Route = createFileRoute('/api/assets/upload')({
+  server: { handlers: { POST: ({ request }: { request: Request }) => upload(request) } },
+});

package/template/base/src/routes/api/auth/staff/$.ts

@@ -0,0 +1,12 @@
+import { getStaffAuth } from '@/server/auth';
+import { createFileRoute } from '@tanstack/react-router';
+
+// Mounts the staff better-auth handler at /api/auth/staff/* (sign-in, get-session, sign-out, …).
+export const Route = createFileRoute('/api/auth/staff/$')({
+  server: {
+    handlers: {
+      GET: ({ request }: { request: Request }) => getStaffAuth().handler(request),
+      POST: ({ request }: { request: Request }) => getStaffAuth().handler(request),
+    },
+  },
+});

package/template/base/src/routes/api/plugin/$.ts

@@ -0,0 +1,51 @@
+import { resolveRequestActor } from '@/server/auth';
+import { getCoreContext, getCoreDb } from '@/server/core';
+import { getPluginHost } from '@/server/plugin-host';
+import { PermissionDeniedError, createRequestContext } from '@saena-io/core';
+import { createFileRoute } from '@tanstack/react-router';
+
+// Generic plugin API dispatch (ADR-0006): one catch-all route exposes every enabled plugin's `Plugin.api`
+// without the host app ever naming a plugin. POST /api/plugin/<fnId> → build a per-request RequestContext
+// (resolved actor + locale + requirePermission), resolve the function by id across the host's plugins,
+// enforce its declared permission (defense-in-depth on top of the handler's own checks), and run it.
+
+function json(body: unknown, status = 200): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  });
+}
+
+async function dispatch(request: Request): Promise<Response> {
+  const fnId = decodeURIComponent(new URL(request.url).pathname.replace(/^\/api\/plugin\//, ''));
+  const fn = getPluginHost()
+    .plugins.flatMap((p) => p.api ?? [])
+    .find((f) => f.id === fnId);
+  if (!fn) return json({ error: `unknown plugin function: ${fnId}` }, 404);
+
+  const input = await request.json().catch(() => undefined);
+  const ctx = await createRequestContext({
+    core: getCoreContext(),
+    db: getCoreDb(),
+    resolveActor: resolveRequestActor,
+    headers: request.headers,
+  });
+
+  try {
+    // Default-deny (M7 security review): a function with a declared permission enforces it; one without is
+    // still gated to a signed-in actor unless it explicitly opts `public: true`. Closes anonymous access to
+    // permission-less plugin functions.
+    if (fn.permission) ctx.requirePermission(fn.permission);
+    else if (!fn.public && ctx.actor.kind === 'anonymous')
+      return json({ error: 'authentication required' }, 401);
+    return json(await fn.handler(input, ctx));
+  } catch (err) {
+    if (err instanceof PermissionDeniedError) return json({ error: err.message }, 403);
+    ctx.logger.error('plugin dispatch failed', { fnId, err: String(err) });
+    return json({ error: 'internal error' }, 500);
+  }
+}
+
+export const Route = createFileRoute('/api/plugin/$')({
+  server: { handlers: { POST: ({ request }: { request: Request }) => dispatch(request) } },
+});