lumiverse-spindle-types 0.3.2 → 0.3.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/api.ts

@@ -500,8 +500,8 @@ export interface PermissionDeniedDetail {
  */
 export interface ThemeOverrideDTO {
   /**
-   * Direct CSS variable overrides. Keys are CSS custom property names
-   * (e.g. `--lumiverse-primary`, `--lumiverse-bg`, `--lcs-glass-bg`).
+   * Direct CSS variable overrides applied regardless of light/dark mode.
+   * Keys are CSS custom property names (e.g. `--lumiverse-primary`).
    * Values must be valid CSS values.
    *
    * Common variable groups:
@@ -522,6 +522,66 @@ export interface ThemeOverrideDTO {
    * - **Transitions**: `--lumiverse-transition`, `--lumiverse-transition-fast`, `--lcs-transition`, `--lcs-transition-fast`
    */
   variables?: Record<string, string>;
+
+  /**
+   * Mode-specific CSS variable overrides. When the user switches between
+   * light and dark mode, the frontend selects the matching set.
+   * Mode-specific values override flat `variables` for the same key.
+   */
+  variablesByMode?: {
+    dark?: Record<string, string>;
+    light?: Record<string, string>;
+  };
+}
+
+/**
+ * RGB color value (0–255 per channel).
+ */
+export interface ColorRGB {
+  r: number;
+  g: number;
+  b: number;
+}
+
+/**
+ * HSL color value (h: 0–360, s: 0–100, l: 0–100).
+ */
+export interface ColorHSL {
+  h: number;
+  s: number;
+  l: number;
+}
+
+/**
+ * Result of extracting colors from an image.
+ * Each region's dominant color is returned along with metadata.
+ */
+export interface ColorExtractionResult {
+  /** Overall dominant color of the full image */
+  dominant: ColorRGB;
+  /** Dominant color per sampled region */
+  regions: {
+    top: ColorRGB;
+    center: ColorRGB;
+    bottom: ColorRGB;
+    left: ColorRGB;
+    right: ColorRGB;
+  };
+  /** Per-region flatness score (0–1). High values = monotone/solid region. */
+  flatness: {
+    top: number;
+    center: number;
+    bottom: number;
+    left: number;
+    right: number;
+    full: number;
+  };
+  /** Simple average color across all sampled pixels */
+  average: ColorRGB;
+  /** Whether the dominant color is perceived as light (luminance > 152) */
+  isLight: boolean;
+  /** HSL representation of the dominant color */
+  dominantHsl: ColorHSL;
 }
 
 /**
@@ -784,7 +844,9 @@ export type WorkerToHost =
   // ─── Theme (gated: "app_manipulation") ──────────────────────────────────
   | { type: "theme_apply"; requestId: string; overrides: ThemeOverrideDTO; userId?: string }
   | { type: "theme_clear"; requestId: string; userId?: string }
-  | { type: "theme_get_current"; requestId: string; userId?: string };
+  | { type: "theme_get_current"; requestId: string; userId?: string }
+  // ─── Color Extraction (gated: "app_manipulation") ─────────────────────
+  | { type: "color_extract"; requestId: string; imageId: string; userId?: string };
 
 // ─── Host → Worker messages ──────────────────────────────────────────────
 

package/src/index.ts

@@ -52,6 +52,9 @@ export type {
   ImageGenResultDTO,
   ThemeOverrideDTO,
   ThemeInfoDTO,
+  ColorExtractionResult,
+  ColorRGB,
+  ColorHSL,
   WorkerToHost,
   HostToWorker,
 } from "./api";

package/src/spindle-api.ts

@@ -31,6 +31,7 @@ import type {
   ImageGenProviderDTO,
   ThemeOverrideDTO,
   ThemeInfoDTO,
+  ColorExtractionResult,
 } from "./api";
 
 /** The global `spindle` object available in backend extension workers */
@@ -557,16 +558,27 @@ export interface SpindleAPI {
    *
    * @example
    * ```ts
-   * // Apply a blue-tinted theme
+   * // Apply a blue-tinted theme with mode-aware backgrounds
    * await spindle.theme.apply({
    *   variables: {
    *     '--lumiverse-primary': 'hsl(210, 80%, 60%)',
-   *     '--lumiverse-bg': 'hsl(210, 12%, 11%)',
-   *     '--lumiverse-bg-elevated': 'hsl(210, 12%, 14%)',
-   *     '--lcs-glass-bg': 'hsla(210, 12%, 6%, 0.55)',
+   *   },
+   *   variablesByMode: {
+   *     dark: {
+   *       '--lumiverse-bg': 'hsl(210, 12%, 11%)',
+   *       '--lumiverse-bg-elevated': 'hsl(210, 12%, 14%)',
+   *     },
+   *     light: {
+   *       '--lumiverse-bg': 'hsl(210, 20%, 96%)',
+   *       '--lumiverse-bg-elevated': 'hsl(210, 20%, 100%)',
+   *     },
    *   },
    * })
    *
+   * // Extract colors from an image, then apply as theme
+   * const palette = await spindle.theme.extractColors('image-id-here')
+   * console.log(palette.dominant, palette.regions, palette.dominantHsl)
+   *
    * // Read current theme state
    * const info = await spindle.theme.getCurrent()
    * console.log(info.mode, info.accent)
@@ -581,6 +593,9 @@ export interface SpindleAPI {
      * Subsequent calls merge with (and overwrite) any previously applied
      * overrides from this extension. The frontend applies overrides
      * immediately via a WebSocket event.
+     *
+     * Use `variablesByMode` to specify different values for light/dark mode.
+     * Mode-specific values take precedence over flat `variables` for the same key.
      */
     apply(overrides: ThemeOverrideDTO): Promise<void>;
     /**
@@ -593,6 +608,15 @@ export interface SpindleAPI {
      * Returns the base theme info (not including any extension overrides).
      */
     getCurrent(userId?: string): Promise<ThemeInfoDTO>;
+    /**
+     * Extract colors from an image stored in Lumiverse's image system.
+     * Returns dominant, regional, and average colors with flatness scores.
+     * Useful for building mode-aware theme overrides from character avatars
+     * or other images.
+     *
+     * @param imageId - ID of an image in the images table
+     */
+    extractColors(imageId: string, userId?: string): Promise<ColorExtractionResult>;
   };
 
   /** This extension's manifest */