dsh-theme-studio 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,40 @@
 # 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.

package/README.md

@@ -1,22 +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
 
-- **10 pre-built presets**: Ocean, Forest, Sunset, Monochrome, Nord, Dracula, Gruvbox, Solarized, Tokyo Night, Catppuccin
-- **Dark-mode aware presets** — presets that ship a `darkTokens` palette switch automatically when dsh enters dark mode (watched via `MutationObserver` on `body[data-ds-dark-theme]`)
-- **Custom accent color** picker with hex input, plus a **separate dark-mode accent**
-- **Contrast guard** — a dark-mode accent that would be illegible on a dark surface is lightened in steps until it clears a WCAG luminance floor, and the panel says so rather than silently changing your pick
-- **Density** control: Compact / Comfortable / Spacious
-- **Border radius** control: Sharp / Rounded / Soft
-- **Font family** selection: System / Monospace / Serif
-- **Animation toggle** — turn off UI transitions for a snappier, low-motion interface
-- **Custom CSS** textarea for advanced `--property: value;` overrides
-- **Import / export** — copy a theme to the clipboard as JSON, or paste / upload one back
-- **Live preview** with badges, cards, and buttons, labelled with the current light/dark mode
-- **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
 
@@ -24,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
@@ -35,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.js

@@ -18,7 +18,6 @@ export function exportTheme(prefs, name) {
     return JSON.stringify(payload, null, 2);
 }
 const DENSITIES = new Set(['compact', 'comfortable', 'spacious']);
-const RADII = new Set(['sharp', 'rounded', 'soft']);
 const FONTS = new Set(['system', 'mono', 'serif']);
 function asColor(value) {
     if (typeof value !== 'string')
@@ -60,9 +59,6 @@ export function parseTheme(raw) {
     if (typeof source['density'] === 'string' && DENSITIES.has(source['density'])) {
         result.density = source['density'];
     }
-    if (typeof source['radius'] === 'string' && RADII.has(source['radius'])) {
-        result.radius = source['radius'];
-    }
     if (typeof source['fontFamily'] === 'string' && FONTS.has(source['fontFamily'])) {
         result.fontFamily = source['fontFamily'];
     }