dsh-theme-studio 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 0.3.0
+
+**Fixed: the plugin previously had no effect on the UI.**
+
+Two independent bugs, both invisible in the panel:
+
+1. Every property was written to `document.documentElement`. dsh defines its
+   palette on `body` and `body[data-ds-dark-theme]`, and body's own declaration
+   wins over the value inherited from html — so all writes were overridden.
+2. The token names were invented. Only 3 of 16 (`--dsw-alias-state-business-primary`,
+   `--dsw-alias-interactive-bg-hover`, `--dsh-content-font-size`) exist in dsh;
+   `--accent`, `--border`, `--dsh-radius-*`, `--dsh-transition-*` and
+   `--dsw-alias-state-business-secondary` do not.
+
+The panel's preview read the same invented names with fallbacks, so it changed
+color and made the misconfiguration look like success.
+
+Also in this release:
+
+- Every name now comes from `src/tokens.ts`, verified against the shipped dsh
+  stylesheets, and `tests/tokens.test.mjs` fails if an unverified name is written.
+- Properties go to `document.body` (`tests/apply.test.mjs` asserts documentElement
+  is never touched).
+- Border-radius control removed: dsh hardcodes radii per component and ships no
+  radius token, so there was no honest implementation.
+- Animation toggle reimplemented as a stylesheet using `0.001ms` rather than `0s`,
+  so `transitionend` and `animationend` still fire.
+- Accent now drives the whole family (business, brand, link, primary button,
+  hover tint) instead of a single token.
+- Switching a preset off clears the properties it had set.
+- Custom CSS parse rejects braces and comments and only accepts `--dsw-*` /
+  `--dsh-*` names, so a typo cannot write arbitrary CSS.
+- 12 presets (was 10); 47 tests (was 26), including a DOM double that tests the
+  real apply path.
+
+## 0.2.0
+
+- 4 new presets: Gruvbox, Solarized, Tokyo Night, Catppuccin.
+- Dark-mode aware presets via `darkTokens`; the panel watches `body[data-ds-dark-theme]`.
+- Separate dark-mode accent color.
+- Contrast guard: a dark accent below the WCAG luminance floor is lightened in
+  steps, and the panel reports that it was adjusted.
+- Animation toggle (disables UI transitions).
+- Theme import/export as JSON, with validation; accepts both the envelope and a
+  bare preferences object, and reports a real error for non-theme input.
+- Unified token resolution: switching a preset off now clears the properties it
+  had set instead of leaving them behind.
+- 26 tests across theme data and color/IO logic.
+
 ## 0.1.0
 
 - Initial release.

package/README.md

@@ -1,18 +1,28 @@
 # dsh-theme-studio
 
-A [dsh](https://github.com/deepseek-ai/deepseek-harness) plugin that lets you customize the UI theme: pick pre-built color presets, set a custom accent color, adjust density, border radius, and font family, or write custom CSS variable overrides.
+A [dsh](https://github.com/deepseek-ai/deepseek-harness) plugin that customizes the UI theme: accent presets, a custom accent color, content density, font family, an animation toggle, and raw design-token overrides.
+
+## What it can and cannot change
+
+This plugin only writes design tokens that **actually exist in dsh**, verified by reading the shipped stylesheets (`@deepseek-ai/dsh-client-ui-theme/lib/client.js`). Every token it writes is listed in `src/tokens.ts` and enforced by `tests/tokens.test.mjs`.
+
+That constraint has two visible consequences:
+
+- **No border-radius control.** dsh hardcodes `border-radius` per component — including `50%` circles and `corner-shape: round` — and ships no radius token. There is no faithful way to offer this, so it is not offered.
+- **The animation toggle is a stylesheet, not a token.** dsh ships no motion tokens, so disabling animations injects a rule compressing transition and animation durations to `0.001ms` rather than `0s` — a zero duration can stop `transitionend` / `animationend` from firing and hang components that wait on them.
 
 ## Features
 
-- **6 pre-built presets**: Ocean, Forest, Sunset, Monochrome, Nord, Dracula
-- **Custom accent color** picker with hex input
-- **Density** control: Compact / Comfortable / Spacious
-- **Border radius** control: Sharp / Rounded / Soft
-- **Font family** selection: System / Monospace / Serif
-- **Custom CSS** textarea for advanced `--property: value;` overrides
-- **Live preview** with badges, cards, and buttons
-- **Instant apply** — changes take effect immediately via CSS custom properties
-- **Persistent** — preferences saved in `localStorage`, no server round-trips
+- **12 presets**: Ocean, Forest, Sunset, Monochrome, Nord, Dracula, Gruvbox, Solarized, Tokyo Night, Catppuccin, Rosé, Ember
+- **Dark-aware presets** — a preset whose dark accent differs from its light one adapts automatically when dsh enters dark mode
+- **Custom accent color**, plus a separate dark-mode accent
+- **Contrast guard** — a dark-mode accent below a WCAG luminance floor is lightened in steps, and the panel reports that it was adjusted
+- **Density**: Compact / Comfortable / Spacious (via the verified `--dsh-content-font-size` token)
+- **Font family**: System / Monospace / Serif
+- **Animation toggle**
+- **Custom CSS** — override any `--dsw-*` or `--dsh-*` token
+- **Import / export** themes as validated JSON
+- **Live preview** rendering the real tokens, showing the accent value currently in effect
 
 ## Install
 
@@ -20,7 +30,7 @@ A [dsh](https://github.com/deepseek-ai/deepseek-harness) plugin that lets you cu
 dsh plugin add dsh-theme-studio
 ```
 
-Or from source:
+From source:
 
 ```bash
 git clone https://github.com/hj01857655/dsh-theme-studio.git
@@ -31,9 +41,12 @@ dsh plugin add link:.
 
 ## How it works
 
-The plugin registers a `settings.section` slot (order 47) that renders a Theme Studio page in the dsh Settings panel. All theme state is client-side: preferences persist in `localStorage` and are applied by setting CSS custom properties on `document.documentElement.style`.
+The plugin registers a `settings.section` slot (order 47). Preferences persist in `localStorage`.
+
+Two implementation details are load-bearing:
 
-The overrides target dsh's `--dsw-alias-*` semantic token layer, so they cascade through every component that reads the design tokens — no component patching required.
+1. **Properties are written to `document.body`, not `documentElement`.** dsh defines its palette on `body` and `body[data-ds-dark-theme]`. A custom property set on `documentElement` is inherited into `body`, but body's own declaration for the same property wins — so writing to `documentElement` changes nothing at all. An earlier version made exactly that mistake.
+2. **The preview is not a mock.** It renders with the same variable names the application uses, so a wrong token looks wrong in the preview too, rather than being masked by a fallback color.
 
 ## License
 

package/lib/apply.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Applying a theme to the live document.
+ *
+ * The important detail here is WHERE the properties are written. dsh defines
+ * its whole palette on `body` and `body[data-ds-dark-theme]`
+ * (`@deepseek-ai/dsh-client-ui-theme/lib/client.js`). Custom properties set on
+ * `documentElement` are inherited into `body`, but body's own declaration for
+ * the same property wins — so writing to `documentElement` produces exactly
+ * zero visible change. Everything is therefore written to `document.body`.
+ *
+ * Dark mode is read from the same attribute dsh's theme plugin toggles, so a
+ * preset's dark palette follows the host without a separate user action.
+ *
+ * These functions touch the DOM, so the pure resolution logic lives in
+ * `resolve.ts` and is what the tests exercise.
+ *
+ * @module apply
+ */
+import type { ThemePreferences } from './types.js';
+/**
+ * True when a custom-CSS property name belongs to dsh's own token namespaces.
+ *
+ * This is the boundary for the escape hatch: users may override any token dsh
+ * actually owns, but not arbitrary CSS (`position`, `display`, …) which could
+ * break layout in ways the panel can't undo.
+ */
+export declare function isDshToken(name: string): boolean;
+/** dsh marks dark mode with this attribute on <body>. */
+export declare function isDarkMode(): boolean;
+/** Watch the dark-mode attribute; returns an unsubscribe function. */
+export declare function observeDarkMode(onChange: (dark: boolean) => void): () => void;
+/**
+ * Resolve the accent color for the current mode.
+ *
+ * In dark mode the accent is pushed through the contrast guard, because a color
+ * that reads well on white can sink into a dark surface. Returns whether the
+ * guard changed anything so the panel can say so instead of silently swapping
+ * the user's pick.
+ */
+export declare function resolveAccent(prefs: ThemePreferences, dark: boolean): {
+    accent: string | null;
+    adjusted: boolean;
+};
+/**
+ * Parse `--property: value;` lines from the custom CSS textarea.
+ *
+ * Only names approved by the caller are kept, so a typo or a deliberately
+ * broad override can't reach the document.
+ */ export declare function parseCustomCss(css: string, allow: (name: string) => boolean): Record<string, string>;
+/** Remove every property this plugin may have set on the target. */
+export declare function clearManagedProperties(fullCustomCss?: string): void;
+/**
+ * Apply a preference set to the document.
+ *
+ * Returns whether the dark-mode contrast guard changed the accent, so the panel
+ * can report a real adjustment rather than an assumed one.
+ */
+export declare function applyTheme(prefs: ThemePreferences, dark?: boolean): boolean;
+/** Remove everything the plugin applied, including the motion stylesheet. */
+export declare function resetTheme(): void;

package/lib/apply.js

@@ -0,0 +1,172 @@
+/**
+ * Applying a theme to the live document.
+ *
+ * The important detail here is WHERE the properties are written. dsh defines
+ * its whole palette on `body` and `body[data-ds-dark-theme]`
+ * (`@deepseek-ai/dsh-client-ui-theme/lib/client.js`). Custom properties set on
+ * `documentElement` are inherited into `body`, but body's own declaration for
+ * the same property wins — so writing to `documentElement` produces exactly
+ * zero visible change. Everything is therefore written to `document.body`.
+ *
+ * Dark mode is read from the same attribute dsh's theme plugin toggles, so a
+ * preset's dark palette follows the host without a separate user action.
+ *
+ * These functions touch the DOM, so the pure resolution logic lives in
+ * `resolve.ts` and is what the tests exercise.
+ *
+ * @module apply
+ */
+import { STYLE_ELEMENT_ID } from './types.js';
+import { DENSITY_TOKENS, FONT_TOKENS, MOTION_OFF_CSS, accentTokens } from './tokens.js';
+import { getPreset } from './themes.js';
+import { ensureDarkContrast } from './io.js';
+/** The element dsh defines its palette on — writing anywhere else is ignored. */
+function themeTarget() {
+    if (typeof document === 'undefined')
+        return null;
+    return document.body ?? null;
+}
+/**
+ * True when a custom-CSS property name belongs to dsh's own token namespaces.
+ *
+ * This is the boundary for the escape hatch: users may override any token dsh
+ * actually owns, but not arbitrary CSS (`position`, `display`, …) which could
+ * break layout in ways the panel can't undo.
+ */
+export function isDshToken(name) {
+    return /^--dsh-\S+$/.test(name) || /^--dsw-\S+$/.test(name);
+}
+/** dsh marks dark mode with this attribute on <body>. */
+export function isDarkMode() {
+    if (typeof document === 'undefined')
+        return false;
+    return document.body.hasAttribute('data-ds-dark-theme');
+}
+/** Watch the dark-mode attribute; returns an unsubscribe function. */
+export function observeDarkMode(onChange) {
+    if (typeof document === 'undefined' || typeof MutationObserver === 'undefined') {
+        return () => { };
+    }
+    const observer = new MutationObserver(() => onChange(isDarkMode()));
+    observer.observe(document.body, {
+        attributes: true,
+        attributeFilter: ['data-ds-dark-theme'],
+    });
+    return () => observer.disconnect();
+}
+/**
+ * Resolve the accent color for the current mode.
+ *
+ * In dark mode the accent is pushed through the contrast guard, because a color
+ * that reads well on white can sink into a dark surface. Returns whether the
+ * guard changed anything so the panel can say so instead of silently swapping
+ * the user's pick.
+ */
+export function resolveAccent(prefs, dark) {
+    const chosen = dark ? (prefs.darkAccentColor ?? prefs.accentColor) : prefs.accentColor;
+    if (chosen === null || chosen.trim() === '')
+        return { accent: null, adjusted: false };
+    if (!dark)
+        return { accent: chosen, adjusted: false };
+    const guarded = ensureDarkContrast(chosen);
+    return { accent: guarded.color, adjusted: guarded.adjusted };
+}
+/**
+ * Parse `--property: value;` lines from the custom CSS textarea.
+ *
+ * Only names approved by the caller are kept, so a typo or a deliberately
+ * broad override can't reach the document.
+ */ export function parseCustomCss(css, allow) {
+    const out = {};
+    for (const line of css.split('\n')) {
+        // Reject values containing braces or a comment opener so a line can't
+        // smuggle in a new rule or escape the declaration it looks like.
+        const match = line.match(/^\s*(--[\w-]+)\s*:\s*([^;{}/*]+?)\s*;?\s*$/);
+        if (match === null)
+            continue;
+        if (!allow(match[1]))
+            continue;
+        out[match[1]] = match[2];
+    }
+    return out;
+}
+/** Remove every property this plugin may have set on the target. */
+export function clearManagedProperties(fullCustomCss = '') {
+    const target = themeTarget();
+    if (target === null)
+        return;
+    const names = new Set([
+        ...Object.keys(accentTokens('#000000')),
+        ...Object.values(DENSITY_TOKENS).flatMap((t) => Object.keys(t)),
+        ...Object.values(FONT_TOKENS).flatMap((t) => Object.keys(t)),
+    ]);
+    for (const line of fullCustomCss.split('\n')) {
+        const match = line.match(/^\s*(--[\w-]+)\s*:/);
+        if (match !== null)
+            names.add(match[1]);
+    }
+    for (const name of names)
+        target.style.removeProperty(name);
+}
+/** Ensure the plugin's own stylesheet exists; returns it or null. */
+function motionStylesheet() {
+    if (typeof document === 'undefined')
+        return null;
+    let el = document.getElementById(STYLE_ELEMENT_ID);
+    if (el === null) {
+        el = document.createElement('style');
+        el.id = STYLE_ELEMENT_ID;
+        document.head.appendChild(el);
+    }
+    return el;
+}
+/**
+ * Apply a preference set to the document.
+ *
+ * Returns whether the dark-mode contrast guard changed the accent, so the panel
+ * can report a real adjustment rather than an assumed one.
+ */
+export function applyTheme(prefs, dark = isDarkMode()) {
+    const target = themeTarget();
+    if (target === null)
+        return false;
+    clearManagedProperties(prefs.customCss);
+    const tokens = {};
+    // Preset accents first, so an explicit accent color overrides its preset.
+    if (prefs.preset !== null) {
+        const found = getPreset(prefs.preset);
+        if (found !== undefined) {
+            Object.assign(tokens, found.tokens);
+            if (dark && found.darkTokens !== undefined)
+                Object.assign(tokens, found.darkTokens);
+        }
+    }
+    const { accent, adjusted } = resolveAccent(prefs, dark);
+    if (accent !== null)
+        Object.assign(tokens, accentTokens(accent));
+    Object.assign(tokens, DENSITY_TOKENS[prefs.density] ?? {});
+    Object.assign(tokens, FONT_TOKENS[prefs.fontFamily] ?? {});
+    for (const [name, value] of Object.entries(tokens)) {
+        target.style.setProperty(name, value);
+    }
+    // Custom CSS is user-authored, so it goes last and wins — but it stays
+    // inside dsh's own variable namespaces, so a typo can't write arbitrary
+    // properties onto the element.
+    const custom = parseCustomCss(prefs.customCss, isDshToken);
+    for (const [name, value] of Object.entries(custom)) {
+        target.style.setProperty(name, value);
+    }
+    const sheet = motionStylesheet();
+    if (sheet !== null)
+        sheet.textContent = prefs.animations ? '' : MOTION_OFF_CSS;
+    return adjusted;
+}
+/** Remove everything the plugin applied, including the motion stylesheet. */
+export function resetTheme() {
+    clearManagedProperties();
+    const sheet = typeof document !== 'undefined'
+        ? document.getElementById(STYLE_ELEMENT_ID)
+        : null;
+    if (sheet !== null)
+        sheet.textContent = '';
+}

package/lib/io.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Theme import/export and color utilities for dsh-theme-studio.
+ *
+ * Kept free of DOM access so the logic is testable outside a browser.
+ *
+ * @module io
+ */
+import type { ThemePreferences } from './types.js';
+/** The wire format for exported themes. */
+export interface ExportedTheme {
+    $schema: 'dsh-theme-studio/v1';
+    name?: string;
+    preferences: ThemePreferences;
+    exportedAt: string;
+}
+/** Serialize preferences into a portable JSON string. */
+export declare function exportTheme(prefs: ThemePreferences, name?: string): string;
+/**
+ * Parse a theme JSON document.
+ *
+ * Every field is validated and falls back to the default rather than throwing,
+ * so a partially-hand-edited file still applies what it can. The only hard
+ * failure is input that is not a JSON object at all — that returns `null` so
+ * the caller can report a real import error instead of silently applying defaults.
+ */
+export declare function parseTheme(raw: string): ThemePreferences | null;
+/** Parse `#rgb` or `#rrggbb` into RGB components; `null` when unparseable. */
+export declare function hexToRgb(hex: string): [number, number, number] | null;
+/** WCAG relative luminance, 0 (black) → 1 (white). */
+export declare function luminance(hex: string): number;
+/** Convert RGB components back into a `#rrggbb` string. */
+export declare function rgbToHex(r: number, g: number, b: number): string;
+/** Blend a color toward white by `amount` (0–1). */
+export declare function lighten(hex: string, amount: number): string;
+/** Blend a color toward black by `amount` (0–1). */
+export declare function darken(hex: string, amount: number): string;
+/**
+ * Ensure an accent color stays legible on a dark background.
+ *
+ * A mid-tone accent that reads well on white can sit too close to a dark
+ * surface. Rather than silently swapping the user's color, we lighten it in
+ * steps until it clears a luminance floor and report whether we changed it, so
+ * the panel can say so instead of the user wondering why their pick looks off.
+ */
+export declare function ensureDarkContrast(hex: string): {
+    color: string;
+    adjusted: boolean;
+};

package/lib/io.js

@@ -0,0 +1,142 @@
+/**
+ * Theme import/export and color utilities for dsh-theme-studio.
+ *
+ * Kept free of DOM access so the logic is testable outside a browser.
+ *
+ * @module io
+ */
+import { DEFAULT_PREFERENCES } from './types.js';
+/** Serialize preferences into a portable JSON string. */
+export function exportTheme(prefs, name) {
+    const payload = {
+        $schema: 'dsh-theme-studio/v1',
+        preferences: prefs,
+        exportedAt: new Date().toISOString(),
+    };
+    if (name !== undefined)
+        payload.name = name;
+    return JSON.stringify(payload, null, 2);
+}
+const DENSITIES = new Set(['compact', 'comfortable', 'spacious']);
+const FONTS = new Set(['system', 'mono', 'serif']);
+function asColor(value) {
+    if (typeof value !== 'string')
+        return null;
+    const trimmed = value.trim();
+    if (trimmed === '')
+        return null;
+    return /^#[0-9a-fA-F]{3,8}$/.test(trimmed) ? trimmed : null;
+}
+/**
+ * Parse a theme JSON document.
+ *
+ * Every field is validated and falls back to the default rather than throwing,
+ * so a partially-hand-edited file still applies what it can. The only hard
+ * failure is input that is not a JSON object at all — that returns `null` so
+ * the caller can report a real import error instead of silently applying defaults.
+ */
+export function parseTheme(raw) {
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed))
+        return null;
+    const doc = parsed;
+    // Accept both the envelope and a bare preferences object.
+    const source = (doc['preferences'] !== null && typeof doc['preferences'] === 'object' && !Array.isArray(doc['preferences']))
+        ? doc['preferences']
+        : doc;
+    const result = { ...DEFAULT_PREFERENCES };
+    if (typeof source['preset'] === 'string' || source['preset'] === null) {
+        result.preset = source['preset'];
+    }
+    result.accentColor = asColor(source['accentColor']);
+    result.darkAccentColor = asColor(source['darkAccentColor']);
+    if (typeof source['density'] === 'string' && DENSITIES.has(source['density'])) {
+        result.density = source['density'];
+    }
+    if (typeof source['fontFamily'] === 'string' && FONTS.has(source['fontFamily'])) {
+        result.fontFamily = source['fontFamily'];
+    }
+    if (typeof source['animations'] === 'boolean')
+        result.animations = source['animations'];
+    if (typeof source['customCss'] === 'string')
+        result.customCss = source['customCss'];
+    return result;
+}
+/** Parse `#rgb` or `#rrggbb` into RGB components; `null` when unparseable. */
+export function hexToRgb(hex) {
+    const value = hex.trim().replace(/^#/, '');
+    if (value.length === 3) {
+        const [r, g, b] = value.split('');
+        return [parseInt(r + r, 16), parseInt(g + g, 16), parseInt(b + b, 16)];
+    }
+    if (value.length === 6) {
+        return [
+            parseInt(value.slice(0, 2), 16),
+            parseInt(value.slice(2, 4), 16),
+            parseInt(value.slice(4, 6), 16),
+        ];
+    }
+    return null;
+}
+/** WCAG relative luminance, 0 (black) → 1 (white). */
+export function luminance(hex) {
+    const rgb = hexToRgb(hex);
+    if (rgb === null)
+        return 0;
+    const [r, g, b] = rgb.map((c) => {
+        const s = c / 255;
+        return s <= 0.03928 ? s / 12.92 : ((s + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/** Convert RGB components back into a `#rrggbb` string. */
+export function rgbToHex(r, g, b) {
+    const clamp = (n) => Math.max(0, Math.min(255, Math.round(n)));
+    return '#' + [r, g, b].map((n) => clamp(n).toString(16).padStart(2, '0')).join('');
+}
+/** Blend a color toward white by `amount` (0–1). */
+export function lighten(hex, amount) {
+    const rgb = hexToRgb(hex);
+    if (rgb === null)
+        return hex;
+    const [r, g, b] = rgb;
+    return rgbToHex(r + (255 - r) * amount, g + (255 - g) * amount, b + (255 - b) * amount);
+}
+/** Blend a color toward black by `amount` (0–1). */
+export function darken(hex, amount) {
+    const rgb = hexToRgb(hex);
+    if (rgb === null)
+        return hex;
+    const [r, g, b] = rgb;
+    return rgbToHex(r * (1 - amount), g * (1 - amount), b * (1 - amount));
+}
+/**
+ * Ensure an accent color stays legible on a dark background.
+ *
+ * A mid-tone accent that reads well on white can sit too close to a dark
+ * surface. Rather than silently swapping the user's color, we lighten it in
+ * steps until it clears a luminance floor and report whether we changed it, so
+ * the panel can say so instead of the user wondering why their pick looks off.
+ */
+export function ensureDarkContrast(hex) {
+    const MIN_LUMINANCE = 0.18;
+    // An unparseable value can't be measured, so it can't be corrected either —
+    // returning it unadjusted keeps the panel from claiming it fixed something.
+    if (hexToRgb(hex) === null)
+        return { color: hex, adjusted: false };
+    if (luminance(hex) >= MIN_LUMINANCE)
+        return { color: hex, adjusted: false };
+    let current = hex;
+    for (let i = 0; i < 10; i += 1) {
+        current = lighten(current, 0.12);
+        if (luminance(current) >= MIN_LUMINANCE)
+            return { color: current, adjusted: true };
+    }
+    return { color: current, adjusted: true };
+}