feat: add shared toolbox header and appearance

packages/contract/README.md

@@ -13,6 +13,10 @@ const app = parseToolboxApp(await response.json());
 const result = await loadToolboxContext();
 ```
 
+The package also owns the versioned same-origin browser preference contract. Use
+`readToolboxPreferences()` and `writeToolboxPreferences()` to share pinned apps,
+ordering, visibility, and light/dark/system mode with the Toolbox portal.
+
 See the workspace [README](https://git.add-ideas.de/zemion/toolbox-sdk#readme)
 for the v1 document formats and full API.
 

packages/contract/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@add-ideas/toolbox-contract",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "Runtime-validated manifests, catalogs, discovery, and URL helpers for toolbox applications.",
   "license": "Apache-2.0",
   "repository": {

packages/contract/src/index.ts

@@ -53,6 +53,18 @@ export {
   loadToolboxCatalog,
   loadToolboxContext,
 } from "./load.js";
+export {
+  TOOLBOX_PREFERENCES_KEY,
+  defaultToolboxPreferences,
+  parseToolboxPreferences,
+  readToolboxPreferences,
+  writeToolboxPreferences,
+} from "./preferences.js";
+export type {
+  ToolboxPreferences,
+  ToolboxPreferenceStorage,
+  ToolboxThemeMode,
+} from "./preferences.js";
 export type {
   ToolboxContextLoadOptions,
   ToolboxFetch,

packages/contract/src/preferences.ts

@@ -0,0 +1,94 @@
+import type { ToolboxCatalogTheme } from "./types.js";
+
+export const TOOLBOX_PREFERENCES_KEY =
+  "@add-ideas/toolbox-portal:v1:preferences" as const;
+
+export type ToolboxThemeMode = ToolboxCatalogTheme["mode"];
+
+export interface ToolboxPreferences {
+  version: 1;
+  pinned: string[];
+  order: string[];
+  hidden: string[];
+  theme: ToolboxThemeMode;
+}
+
+export interface ToolboxPreferenceStorage {
+  getItem(key: string): string | null;
+  setItem(key: string, value: string): void;
+}
+
+export const defaultToolboxPreferences: Readonly<ToolboxPreferences> = {
+  version: 1,
+  pinned: [],
+  order: [],
+  hidden: [],
+  theme: "system",
+};
+
+function freshDefaults(): ToolboxPreferences {
+  return {
+    ...defaultToolboxPreferences,
+    pinned: [],
+    order: [],
+    hidden: [],
+  };
+}
+
+function uniqueStrings(value: unknown, field: string): string[] {
+  if (
+    !Array.isArray(value) ||
+    value.some((item) => typeof item !== "string" || item.length === 0)
+  ) {
+    throw new Error(`${field} must be an array of non-empty strings.`);
+  }
+  return [...new Set(value)];
+}
+
+export function parseToolboxPreferences(value: unknown): ToolboxPreferences {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error("Preferences must be a JSON object.");
+  }
+
+  const candidate = value as Record<string, unknown>;
+  if (candidate.version !== 1) {
+    throw new Error("Unsupported preferences version.");
+  }
+
+  const theme = candidate.theme;
+  if (theme !== "light" && theme !== "dark" && theme !== "system") {
+    throw new Error("Invalid theme preference.");
+  }
+
+  return {
+    version: 1,
+    pinned: uniqueStrings(candidate.pinned, "pinned"),
+    order: uniqueStrings(candidate.order, "order"),
+    hidden: uniqueStrings(candidate.hidden, "hidden"),
+    theme,
+  };
+}
+
+export function readToolboxPreferences(
+  storage?: ToolboxPreferenceStorage,
+): ToolboxPreferences {
+  if (!storage) return freshDefaults();
+  const value = storage.getItem(TOOLBOX_PREFERENCES_KEY);
+  if (!value) return freshDefaults();
+
+  try {
+    return parseToolboxPreferences(JSON.parse(value));
+  } catch {
+    return freshDefaults();
+  }
+}
+
+export function writeToolboxPreferences(
+  preferences: ToolboxPreferences,
+  storage: ToolboxPreferenceStorage,
+): void {
+  storage.setItem(
+    TOOLBOX_PREFERENCES_KEY,
+    JSON.stringify(parseToolboxPreferences(preferences)),
+  );
+}

packages/contract/test/preferences.test.ts

@@ -0,0 +1,63 @@
+import {
+  TOOLBOX_PREFERENCES_KEY,
+  defaultToolboxPreferences,
+  parseToolboxPreferences,
+  readToolboxPreferences,
+  writeToolboxPreferences,
+} from "../src/index.js";
+import { describe, expect, it } from "vitest";
+
+function memoryStorage(initial?: string) {
+  const values = new Map<string, string>();
+  if (initial !== undefined) values.set(TOOLBOX_PREFERENCES_KEY, initial);
+  return {
+    getItem: (key: string) => values.get(key) ?? null,
+    setItem: (key: string, value: string) => values.set(key, value),
+  };
+}
+
+describe("shared toolbox preferences", () => {
+  it("parses version 1 and removes duplicate ids", () => {
+    expect(
+      parseToolboxPreferences({
+        version: 1,
+        pinned: ["pdf", "pdf"],
+        order: ["pdf", "xslt"],
+        hidden: [],
+        theme: "dark",
+      }),
+    ).toEqual({
+      version: 1,
+      pinned: ["pdf"],
+      order: ["pdf", "xslt"],
+      hidden: [],
+      theme: "dark",
+    });
+  });
+
+  it("returns independent defaults for missing or corrupt storage", () => {
+    const missing = readToolboxPreferences(memoryStorage());
+    const corrupt = readToolboxPreferences(memoryStorage("not json"));
+    missing.pinned.push("pdf");
+    expect(corrupt).toEqual(defaultToolboxPreferences);
+    expect(corrupt.pinned).toEqual([]);
+  });
+
+  it("writes validated preferences under the compatible portal key", () => {
+    const storage = memoryStorage();
+    writeToolboxPreferences(
+      {
+        version: 1,
+        pinned: ["pdf"],
+        order: ["pdf"],
+        hidden: [],
+        theme: "light",
+      },
+      storage,
+    );
+    expect(readToolboxPreferences(storage)).toMatchObject({
+      pinned: ["pdf"],
+      theme: "light",
+    });
+  });
+});