@podosoft/podokit 0.17.4 → 1.0.2

package/dist/templates/modules/admin-dashboard/files/apps/api/src/admin.module.ts

@@ -0,0 +1,153 @@
+import {
+  AppException,
+  PROFILE_IMAGE_REQUIRED,
+  PROFILE_IMAGE_TOO_LARGE,
+} from "@podosoft/podokit-contracts";
+import { Elysia, t } from "elysia";
+import { AUTH } from "./auth/auth.module";
+import {
+  ACCESS_POLICY,
+  DATABASE,
+  LOGGER,
+  type AppPlugin,
+  type PodokitModule,
+  type ServiceKey,
+} from "./core/services";
+import { ProfileImageService } from "./profile-image/profile-image.service";
+import { PROFILE_IMAGE_POLICY } from "@podosoft/podokit-contracts";
+import {
+  PUBLIC_SITE_KEYS,
+  SiteSettingsService,
+} from "./site-settings/site-settings.service";
+import { validateSiteSetting } from "./site-settings/site-settings.validation";
+import { STORAGE } from "./storage/storage.module";
+
+export const SITE_SETTINGS = Symbol("site-settings") as ServiceKey<SiteSettingsService>;
+export const PROFILE_IMAGES = Symbol("profile-images") as ServiceKey<ProfileImageService>;
+
+const ICON_TYPES = new Set([
+  "image/svg+xml",
+  "image/png",
+  "image/x-icon",
+  "image/vnd.microsoft.icon",
+]);
+const MAX_ICON_BYTES = 1024 * 1024;
+
+function currentImage(user: Record<string, unknown>): string | null {
+  return typeof user.image === "string" ? user.image : null;
+}
+
+function responseBody(buffer: Buffer): ArrayBuffer {
+  return buffer.buffer.slice(
+    buffer.byteOffset,
+    buffer.byteOffset + buffer.byteLength,
+  ) as ArrayBuffer;
+}
+
+const adminPlugin: AppPlugin = ({ services }) => {
+  const auth = services.resolve(AUTH);
+  const site = services.resolve(SITE_SETTINGS);
+  const profileImages = services.resolve(PROFILE_IMAGES);
+
+  return new Elysia({ name: "podokit.admin" })
+    .get("/site/settings", async () => {
+      const all = await site.getAll();
+      const response: Record<string, string | boolean | null> = {};
+      for (const key of PUBLIC_SITE_KEYS) response[key] = all[key] ?? null;
+      response.hasFavicon = (await site.get("faviconContentType")) !== null;
+      response.faviconVersion = await site.faviconVersion();
+      return response;
+    }, {
+      detail: { tags: ["site"], summary: "Get public site settings" },
+    })
+    .put("/site/settings", async ({ request, body }) => {
+      await auth.requireAdmin(request);
+      const update: Record<string, string> = {};
+      for (const [key, value] of Object.entries(body)) {
+        update[key] = validateSiteSetting(key, value);
+      }
+      return site.setMany(update);
+    }, {
+      body: t.Record(t.String(), t.String()),
+      detail: { tags: ["site"], summary: "Update site settings" },
+    })
+    .post("/site/favicon", async ({ request, body, set }) => {
+      await auth.requireAdmin(request);
+      const file = body.file;
+      if (file.size > MAX_ICON_BYTES) {
+        throw new AppException("FAVICON_TOO_LARGE", "Icon must be 1 MB or smaller", 413);
+      }
+      if (!ICON_TYPES.has(file.type)) {
+        throw new AppException("FAVICON_TYPE_INVALID", "Icon must be SVG, PNG, or ICO", 400);
+      }
+      await site.setFavicon(new Uint8Array(await file.arrayBuffer()), file.type);
+      set.status = 201;
+      return { version: await site.faviconVersion() };
+    }, {
+      body: t.Object({ file: t.File() }),
+      detail: { tags: ["site"], summary: "Upload the site favicon" },
+    })
+    .get("/site/favicon", async () => {
+      const icon = await site.getFavicon();
+      if (!icon) throw new AppException("FAVICON_NOT_FOUND", "No favicon set", 404);
+      return new Response(responseBody(icon.body), {
+        headers: { "content-type": icon.contentType },
+      });
+    }, {
+      detail: { tags: ["site"], summary: "Get the site favicon" },
+    })
+    .post("/account/profile-image", async ({ request, body, set }) => {
+      const session = await auth.requireSession(request);
+      const file = body.file;
+      if (!file) {
+        throw new AppException(PROFILE_IMAGE_REQUIRED, "A profile image file is required.", 400);
+      }
+      if (file.size > PROFILE_IMAGE_POLICY.maxBytes) {
+        throw new AppException(PROFILE_IMAGE_TOO_LARGE, "Profile image must be 2 MB or smaller.", 413);
+      }
+      const buffer = Buffer.from(await file.arrayBuffer());
+      const result = await profileImages.upload(currentImage(session.user), {
+        buffer,
+        mimetype: file.type,
+        size: file.size,
+      }, request.headers);
+      set.status = 201;
+      return result;
+    }, {
+      body: t.Object({ file: t.File() }),
+      detail: { tags: ["account"], summary: "Upload the current user's profile image" },
+    })
+    .delete("/account/profile-image", async ({ request }) => {
+      const session = await auth.requireSession(request);
+      return profileImages.remove(currentImage(session.user), request.headers);
+    }, {
+      detail: { tags: ["account"], summary: "Remove the current user's profile image" },
+    })
+    .get("/profile-images/:fileName", async ({ params, set }) => {
+      const image = await profileImages.get(params.fileName);
+      set.headers["cache-control"] = "public, max-age=31536000, immutable";
+      return new Response(responseBody(image.body), {
+        headers: { "content-type": image.contentType },
+      });
+    }, {
+      params: t.Object({ fileName: t.String({ minLength: 1 }) }),
+      detail: { tags: ["account"], summary: "Get a public profile image" },
+    });
+};
+
+export const adminModule: PodokitModule = {
+  name: "admin-dashboard",
+  configure: (_env, services): void => {
+    const storage = services.resolve(STORAGE);
+    const site = new SiteSettingsService(services.resolve(DATABASE).sql, storage);
+    const profileImages = new ProfileImageService(storage, services.resolve(LOGGER));
+    services.register(SITE_SETTINGS, site);
+    services.register(PROFILE_IMAGES, profileImages, () => profileImages.close());
+    services.onStart(() => profileImages.connect());
+    const policy = services.resolve(ACCESS_POLICY);
+    policy.register("GET", "/site/settings", "public");
+    policy.register("GET", "/site/favicon", "public");
+    policy.register("GET", "/profile-images/:fileName", "public");
+  },
+  plugin: adminPlugin,
+};

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.service.spec.ts

@@ -1,30 +1,30 @@
-import { afterAll, afterEach, describe, expect, it, jest } from "@jest/globals";
+import { afterAll, afterEach, describe, expect, mock, test } from "bun:test";
+import type { Logger } from "pino";
 import { runUserDeletedHandlers } from "../auth/user-delete-handlers";
 import { StorageService } from "../storage/storage.service";
 import { ProfileImageService } from "./profile-image.service";
 
-jest.mock("../auth/auth-provider", () => ({ getAuth: jest.fn() }));
-
 describe("ProfileImageService account deletion cleanup", () => {
   const storage = {
-    put: jest.fn(async () => undefined),
-    get: jest.fn(async () => Buffer.alloc(0)),
-    presignedGetUrl: jest.fn(async () => "https://example.com/image"),
-    delete: jest.fn(async () => undefined),
+    put: mock(async () => undefined),
+    get: mock(async () => Buffer.alloc(0)),
+    presignedGetUrl: mock(async () => "https://example.com/image"),
+    delete: mock(async () => undefined),
   };
-  const service = new ProfileImageService(storage as unknown as StorageService);
+  const logger = { warn: mock(() => undefined) } as unknown as Logger;
+  const service = new ProfileImageService(storage as unknown as StorageService, logger);
 
-  service.onModuleInit();
+  service.connect();
 
   afterEach(() => {
-    jest.clearAllMocks();
+    for (const operation of Object.values(storage)) operation.mockClear();
   });
 
   afterAll(() => {
-    service.onModuleDestroy();
+    service.close();
   });
 
-  it("deletes a managed image after the account is deleted", async () => {
+  test("deletes a managed image after the account is deleted", async () => {
     await runUserDeletedHandlers({
       id: "user-1",
       image: "/api/profile-images/123e4567-e89b-42d3-a456-426614174000.webp",
@@ -35,7 +35,7 @@ describe("ProfileImageService account deletion cleanup", () => {
     );
   });
 
-  it("does not delete an external identity-provider image", async () => {
+  test("does not delete an external identity-provider image", async () => {
     await runUserDeletedHandlers({ id: "user-1", image: "https://example.com/avatar.png" });
 
     expect(storage.delete).not.toHaveBeenCalled();

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.service.ts

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { Injectable, Logger, type OnModuleDestroy, type OnModuleInit } from "@nestjs/common";
+import type { Logger } from "pino";
 import {
   AppException,
   PROFILE_IMAGE_NOT_FOUND,
@@ -7,7 +7,7 @@ import {
 } from "@podosoft/podokit-contracts";
 import { getAuth } from "../auth/auth-provider";
 import { registerUserDeletedHandler } from "../auth/user-delete-handlers";
-import { StorageService } from "../storage/storage.service";
+import type { StorageService } from "../storage/storage.service";
 import { validateProfileImage, type ProfileImageUpload } from "./profile-image.validation";
 
 const FILE_NAME = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\.(?:jpg|png|webp)$/;
@@ -25,21 +25,32 @@ export interface StoredProfileImage {
   contentType: string;
 }
 
-@Injectable()
-export class ProfileImageService implements OnModuleInit, OnModuleDestroy {
-  private readonly logger = new Logger(ProfileImageService.name);
+export type UpdateAuthUser = (
+  image: string | null,
+  headers: Headers,
+) => Promise<unknown>;
+
+const updateAuthUser: UpdateAuthUser = (image, headers) =>
+  getAuth().api.updateUser({ body: { image }, headers });
+
+export class ProfileImageService {
   private unregisterUserDeleted?: () => void;
 
-  constructor(private readonly storage: StorageService) {}
+  constructor(
+    private readonly storage: StorageService,
+    private readonly logger: Logger,
+    private readonly updateUser: UpdateAuthUser = updateAuthUser,
+  ) {}
 
-  onModuleInit(): void {
-    this.unregisterUserDeleted = registerUserDeletedHandler(async (user) => {
+  connect(): void {
+    this.unregisterUserDeleted ??= registerUserDeletedHandler(async (user) => {
       await this.deleteManagedImage(user.image ?? null);
     });
   }
 
-  onModuleDestroy(): void {
+  close(): void {
     this.unregisterUserDeleted?.();
+    this.unregisterUserDeleted = undefined;
   }
 
   async upload(
@@ -54,7 +65,7 @@ export class ProfileImageService implements OnModuleInit, OnModuleDestroy {
 
     await this.storage.put(key, file.buffer, metadata.contentType);
     try {
-      await getAuth().api.updateUser({ body: { image }, headers });
+      await this.updateUser(image, headers);
     } catch (error: unknown) {
       await this.deleteKeyBestEffort(key);
       throw error;
@@ -64,19 +75,20 @@ export class ProfileImageService implements OnModuleInit, OnModuleDestroy {
   }
 
   async remove(currentImage: string | null, headers: Headers): Promise<ProfileImageResponse> {
-    await getAuth().api.updateUser({ body: { image: null }, headers });
+    await this.updateUser(null, headers);
     await this.deleteManagedImage(currentImage);
     return { image: null };
   }
 
   async get(fileName: string): Promise<StoredProfileImage> {
     const key = this.keyFromFileName(fileName);
-    if (!key) {
-      throw new AppException(PROFILE_IMAGE_NOT_FOUND, "Profile image not found.", 404);
-    }
+    if (!key) throw new AppException(PROFILE_IMAGE_NOT_FOUND, "Profile image not found.", 404);
     try {
       const extension = fileName.slice(fileName.lastIndexOf(".") + 1);
-      return { body: await this.storage.get(key), contentType: CONTENT_TYPES[extension] ?? "application/octet-stream" };
+      return {
+        body: await this.storage.get(key),
+        contentType: CONTENT_TYPES[extension] ?? "application/octet-stream",
+      };
     } catch {
       throw new AppException(PROFILE_IMAGE_NOT_FOUND, "Profile image not found.", 404);
     }
@@ -87,8 +99,9 @@ export class ProfileImageService implements OnModuleInit, OnModuleDestroy {
   }
 
   private keyFromPublicUrl(image: string | null): string | null {
-    if (!image?.startsWith(PUBLIC_PREFIX)) return null;
-    return this.keyFromFileName(image.slice(PUBLIC_PREFIX.length));
+    return image?.startsWith(PUBLIC_PREFIX)
+      ? this.keyFromFileName(image.slice(PUBLIC_PREFIX.length))
+      : null;
   }
 
   private async deleteManagedImage(image: string | null): Promise<void> {
@@ -100,11 +113,10 @@ export class ProfileImageService implements OnModuleInit, OnModuleDestroy {
     try {
       await this.storage.delete(key);
     } catch (error: unknown) {
-      this.logger.warn({
-        message: "Delete profile image object failed",
-        key,
-        error: error instanceof Error ? error.message : String(error),
-      });
+      this.logger.warn(
+        { key, error: error instanceof Error ? error.message : String(error) },
+        "Delete profile image object failed",
+      );
     }
   }
 }

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.validation.spec.ts

@@ -1,4 +1,4 @@
-import { describe, expect, it } from "@jest/globals";
+import { describe, expect, test } from "bun:test";
 import {
   AppException,
   PROFILE_IMAGE_DIMENSIONS_INVALID,
@@ -35,7 +35,7 @@ describe("validateProfileImage", () => {
     [WEBP, "image/webp", "webp", 2, 3],
   ];
 
-  it.each(supported)("accepts a valid supported image", (base64, mimetype, extension, width, height) => {
+  test.each(supported)("accepts a valid supported image", (base64, mimetype, extension, width, height) => {
     expect(validateProfileImage(upload(base64, mimetype))).toMatchObject({
       contentType: mimetype,
       extension,
@@ -44,21 +44,21 @@ describe("validateProfileImage", () => {
     });
   });
 
-  it("rejects a MIME type that does not match the bytes", () => {
+  test("rejects a MIME type that does not match the bytes", () => {
     expectAppException(
       () => validateProfileImage(upload(PNG, "image/jpeg")),
       PROFILE_IMAGE_TYPE_INVALID,
     );
   });
 
-  it("rejects unsupported or malformed bytes", () => {
+  test("rejects unsupported or malformed bytes", () => {
     expectAppException(
       () => validateProfileImage(upload(Buffer.from("not an image").toString("base64"), "image/png")),
       PROFILE_IMAGE_TYPE_INVALID,
     );
   });
 
-  it("rejects a file larger than the shared byte limit", () => {
+  test("rejects a file larger than the shared byte limit", () => {
     expectAppException(
       () => validateProfileImage(upload(PNG, "image/png", PROFILE_IMAGE_POLICY.maxBytes + 1)),
       PROFILE_IMAGE_TOO_LARGE,
@@ -66,11 +66,11 @@ describe("validateProfileImage", () => {
     );
   });
 
-  it("accepts arbitrary aspect ratios within the limit", () => {
+  test("accepts arbitrary aspect ratios within the limit", () => {
     expect(validateProfileImage(upload(PNG, "image/png"))).toMatchObject({ width: 2, height: 3 });
   });
 
-  it("rejects a dimension above 2048 pixels", () => {
+  test("rejects a dimension above 2048 pixels", () => {
     expectAppException(
       () => validateProfileImage(upload(TOO_WIDE_PNG, "image/png")),
       PROFILE_IMAGE_DIMENSIONS_INVALID,

package/dist/templates/modules/admin-dashboard/files/apps/api/src/profile-image/profile-image.validation.ts

@@ -6,7 +6,7 @@ import {
   PROFILE_IMAGE_TYPE_INVALID,
   type ProfileImageMimeType,
 } from "@podosoft/podokit-contracts";
-import { imageSize } from "image-size";
+import probe from "probe-image-size";
 
 export interface ProfileImageUpload {
   buffer: Buffer;
@@ -37,9 +37,9 @@ export function validateProfileImage(file: ProfileImageUpload): ProfileImageMeta
     );
   }
 
-  let dimensions: ReturnType<typeof imageSize>;
+  let dimensions: ReturnType<typeof probe.sync>;
   try {
-    dimensions = imageSize(file.buffer);
+    dimensions = probe.sync(file.buffer);
   } catch {
     throw new AppException(
       PROFILE_IMAGE_TYPE_INVALID,
@@ -47,7 +47,7 @@ export function validateProfileImage(file: ProfileImageUpload): ProfileImageMeta
     );
   }
 
-  const detected = dimensions.type ? DETECTED_TYPES[dimensions.type] : undefined;
+  const detected = dimensions ? DETECTED_TYPES[dimensions.type] : undefined;
   if (!detected || detected.contentType !== file.mimetype) {
     throw new AppException(
       PROFILE_IMAGE_TYPE_INVALID,
@@ -55,8 +55,7 @@ export function validateProfileImage(file: ProfileImageUpload): ProfileImageMeta
     );
   }
   if (
-    dimensions.width === undefined
-    || dimensions.height === undefined
+    !dimensions
     || dimensions.width > PROFILE_IMAGE_POLICY.maxWidth
     || dimensions.height > PROFILE_IMAGE_POLICY.maxHeight
   ) {

package/dist/templates/modules/admin-dashboard/files/apps/api/src/site-settings/site-settings.service.ts

@@ -1,17 +1,9 @@
-import { Injectable } from "@nestjs/common";
-import { InjectRepository } from "@nestjs/typeorm";
-import { Repository } from "typeorm";
-import { AppSetting } from "../settings/app-setting.entity";
-import { StorageService } from "../storage/storage.service";
-
-/** Public, admin-editable site settings (name, description, favicon, …). Stored
- *  as `site.*` string keys in the shared `app_setting` table; the favicon binary
- *  lives in object storage (MinIO/S3) and is served from a stable endpoint. */
+import type { SQL } from "bun";
+import type { StorageService } from "../storage/storage.service";
 
 const PREFIX = "site.";
-const FAVICON_KEY = "site/favicon"; // object-storage key
+const FAVICON_KEY = "site/favicon";
 
-/** Keys exposed publicly (read by every page for title/branding). */
 export const PUBLIC_SITE_KEYS = [
   "name",
   "description",
@@ -29,45 +21,56 @@ export const PUBLIC_SITE_KEYS = [
   "allowSignup",
 ] as const;
 
+interface SiteSettingRow {
+  key: string;
+  value: string;
+}
+
 export interface SiteFavicon {
   body: Buffer;
   contentType: string;
 }
 
-@Injectable()
 export class SiteSettingsService {
   constructor(
-    @InjectRepository(AppSetting) private readonly repo: Repository<AppSetting>,
+    private readonly sql: SQL,
     private readonly storage: StorageService,
   ) {}
 
-  /** All `site.*` values as a plain map (keys without the prefix). */
   async getAll(): Promise<Record<string, string>> {
-    const rows = await this.repo.find();
-    const out: Record<string, string> = {};
-    for (const row of rows) {
-      if (row.key.startsWith(PREFIX)) out[row.key.slice(PREFIX.length)] = row.value;
-    }
-    return out;
+    const rows = await this.sql<SiteSettingRow[]>`
+      SELECT "key", "value" FROM "app_setting" WHERE "key" LIKE 'site.%'
+    `;
+    const result: Record<string, string> = {};
+    for (const row of rows) result[row.key.slice(PREFIX.length)] = row.value;
+    return result;
   }
 
   async get(key: string): Promise<string | null> {
-    const row = await this.repo.findOne({ where: { key: PREFIX + key } });
-    return row?.value ?? null;
+    const rows = await this.sql<SiteSettingRow[]>`
+      SELECT "key", "value" FROM "app_setting" WHERE "key" = ${PREFIX + key}
+    `;
+    return rows[0]?.value ?? null;
   }
 
-  /** Upsert several site settings at once. Returns the full updated map. */
   async setMany(update: Record<string, string>): Promise<Record<string, string>> {
     for (const [key, value] of Object.entries(update)) {
-      await this.repo.upsert({ key: PREFIX + key, value }, ["key"]);
+      await this.sql`
+        INSERT INTO "app_setting" ("key", "value", "updatedAt")
+        VALUES (${PREFIX + key}, ${value}, CURRENT_TIMESTAMP)
+        ON CONFLICT ("key") DO UPDATE
+        SET "value" = EXCLUDED."value", "updatedAt" = CURRENT_TIMESTAMP
+      `;
     }
     return this.getAll();
   }
 
-  /** Store an uploaded favicon in object storage and record its metadata. */
-  async setFavicon(body: Buffer, contentType: string): Promise<void> {
+  async setFavicon(body: Uint8Array, contentType: string): Promise<void> {
     await this.storage.put(FAVICON_KEY, body, contentType);
-    await this.setMany({ faviconContentType: contentType, faviconUpdatedAt: `${Date.now()}` });
+    await this.setMany({
+      faviconContentType: contentType,
+      faviconUpdatedAt: String(Date.now()),
+    });
   }
 
   async getFavicon(): Promise<SiteFavicon | null> {
@@ -80,8 +83,7 @@ export class SiteSettingsService {
     }
   }
 
-  /** Cache-busting version token so the browser refetches the favicon after a change. */
-  async faviconVersion(): Promise<string | null> {
+  faviconVersion(): Promise<string | null> {
     return this.get("faviconUpdatedAt");
   }
 }

package/dist/templates/modules/admin-dashboard/files/apps/api/src/site-settings/site-settings.validation.spec.ts

@@ -0,0 +1,22 @@
+import { describe, expect, test } from "bun:test";
+import { validateSiteSetting } from "./site-settings.validation";
+
+describe("validateSiteSetting", () => {
+  test("normalizes safe theme and locale values", () => {
+    expect(validateSiteSetting("locale", "ko-kr")).toBe("ko-KR");
+    expect(validateSiteSetting("themeRadius", "2.0")).toBe("2");
+    expect(validateSiteSetting(
+      "themeOverrides",
+      JSON.stringify({ light: { primary: "#112233" } }),
+    )).toBe('{"light":{"primary":"#112233"}}');
+  });
+
+  test("rejects unknown keys and CSS injection values", () => {
+    expect(() => validateSiteSetting("unknown", "value")).toThrow("Unknown setting");
+    expect(() => validateSiteSetting("brandColor", "red;display:none")).toThrow("hex color");
+    expect(() => validateSiteSetting(
+      "themeOverrides",
+      JSON.stringify({ light: { unknown: "#fff" } }),
+    )).toThrow("Unknown theme token");
+  });
+});

package/dist/templates/modules/admin-dashboard/files/apps/api/src/site-settings/site-settings.validation.ts

@@ -0,0 +1,73 @@
+import { AppException } from "@podosoft/podokit-contracts";
+import { PUBLIC_SITE_KEYS } from "./site-settings.service";
+
+const ALLOWED = new Set<string>(PUBLIC_SITE_KEYS);
+const HEX = /^#(?:[0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/;
+const PRESET = /^[a-z0-9-]{1,32}$/;
+const LOCALE = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/;
+const THEME_TOKEN_KEYS = new Set([
+  "background",
+  "card",
+  "foreground",
+  "mutedForeground",
+  "border",
+  "secondary",
+  "accent",
+  "primary",
+  "primaryForeground",
+]);
+
+function invalid(message: string): never {
+  throw new AppException("SITE_SETTING_INVALID", message, 400);
+}
+
+export function validateSiteSetting(key: string, value: string): string {
+  if (!ALLOWED.has(key)) invalid(`Unknown setting: ${key}`);
+  if (value === "") return "";
+  if (key === "locale") {
+    if (!LOCALE.test(value)) invalid("locale must be a valid BCP 47 language tag");
+    try {
+      return Intl.getCanonicalLocales(value)[0] ?? value;
+    } catch {
+      return invalid("locale must be a valid BCP 47 language tag");
+    }
+  }
+  if (key === "brandColor") {
+    if (!HEX.test(value)) invalid("brandColor must be a hex color");
+  } else if (key === "themePreset") {
+    if (!PRESET.test(value)) invalid("Invalid themePreset");
+  } else if (key === "themeRadius") {
+    const radius = Number(value);
+    if (!Number.isFinite(radius) || radius < 0 || radius > 4) invalid("themeRadius must be 0–4");
+    return String(radius);
+  } else if (key === "themeOverrides") {
+    let parsed: unknown;
+    try {
+      parsed = JSON.parse(value);
+    } catch {
+      return invalid("themeOverrides must be valid JSON");
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      return invalid("themeOverrides must be an object");
+    }
+    const result: Record<string, Record<string, string>> = {};
+    for (const mode of ["light", "dark"] as const) {
+      const block = (parsed as Record<string, unknown>)[mode];
+      if (block === undefined) continue;
+      if (!block || typeof block !== "object" || Array.isArray(block)) {
+        return invalid(`themeOverrides.${mode} must be an object`);
+      }
+      const clean: Record<string, string> = {};
+      for (const [token, tokenValue] of Object.entries(block)) {
+        if (!THEME_TOKEN_KEYS.has(token)) invalid(`Unknown theme token: ${token}`);
+        if (typeof tokenValue !== "string" || !HEX.test(tokenValue)) {
+          invalid(`themeOverrides.${mode}.${token} must be a hex color`);
+        }
+        clean[token] = tokenValue;
+      }
+      if (Object.keys(clean).length > 0) result[mode] = clean;
+    }
+    return JSON.stringify(result);
+  }
+  return value;
+}

package/dist/templates/modules/admin-dashboard/files/apps/web/src/app.d.ts

@@ -1,5 +1,5 @@
-import type { Locale } from "$lib/i18n/messages";
-import type { SiteSettings } from "$lib/site.svelte";
+import type { Locale } from "#lib/i18n/messages.js";
+import type { SiteSettings } from "#lib/site.svelte.js";
 
 export type SessionUser = {
   id: string;

package/dist/templates/modules/admin-dashboard/files/apps/web/src/hooks.server.ts

@@ -1,9 +1,10 @@
-import { error, type Handle } from "@sveltejs/kit";
-import { serverApiClient } from "$lib/server/api";
-import { resolveLocale } from "$lib/i18n/messages";
-import { applySearchIndexingHeaders } from "$lib/server/search-indexing";
-import { isPublicPath } from "$lib/server/guards";
-import type { SiteSettings } from "$lib/site.svelte";
+import { error } from "@sveltejs/kit";
+import type { Handle } from "@sveltejs/kit/hooks";
+import { serverApiClient } from "#lib/server/api.js";
+import { resolveLocale } from "#lib/i18n/messages.js";
+import { applySearchIndexingHeaders } from "#lib/server/search-indexing.js";
+import { isPublicPath } from "#lib/server/guards.js";
+import type { SiteSettings } from "#lib/site.svelte.js";
 import { ApiError } from "@podosoft/podokit-api-client";
 
 function isTemporaryServiceFailure(cause: unknown): boolean {

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/admin/registry.svelte.ts

@@ -1,5 +1,5 @@
 import type { Component } from "svelte";
-import type { Messages } from "$lib/i18n/messages";
+import type { Messages } from "#lib/i18n/messages.js";
 // Modules import their nav-entry icons here.
 // podokit:begin:admin-nav-imports
 // podokit:end:admin-nav-imports

package/dist/templates/modules/admin-dashboard/files/apps/web/src/lib/auth-redirect.ts

@@ -16,7 +16,7 @@ export function safeAuthRedirect(value: string | null | undefined, fallback = "/
 }
 
 /** Current same-site path, suitable for a login return target. */
-export function currentPath(url: URL): string {
+export function currentPath(url: Pick<URL, "pathname" | "search" | "hash">): string {
   return safeAuthRedirect(`${url.pathname}${url.search}${url.hash}`);
 }