@deepseek-ai/dsh-client-ui-theme 0.0.1-rc.1

package/lib/styles/scrollbar.css

@@ -0,0 +1,85 @@
+/* Scrollbar skin: the sole consumer of the four --dsw-alias-scrollbar-*
+ * tokens. Without it every scrolling region renders the UA scrollbar, which
+ * ignores the theme — a light native bar over the dark palette.
+ *
+ * The rules sit on `body`, not `html`: design-platform.css declares the
+ * --dsw-alias-* tokens on `body` (and the dark overrides on
+ * `body[data-ds-dark-theme]`), and custom properties only inherit downward,
+ * so an `html` rule resolves them to the guaranteed-invalid value and
+ * `scrollbar-color` falls back to `auto`.
+ *
+ * Surfaces pick their elevation by rebinding --dsh-scrollbar-thumb{,-hover}:
+ * the l1 pair here is the base-surface default, and an elevated surface
+ * (menu, popover, dialog) rebinds to the l2 pair on its own container. Both
+ * rendering paths below read the indirection, so one rebind reaches whichever
+ * path the engine took. */
+
+body {
+  --dsh-scrollbar-thumb: var(--dsw-alias-scrollbar-bg-l1);
+  --dsh-scrollbar-thumb-hover: var(--dsw-alias-scrollbar-hover-l1);
+}
+
+/* The two paths are mutually exclusive, and the gate is load-bearing rather
+   than defensive. A non-`auto` `scrollbar-width` or `scrollbar-color` makes
+   Chromium and Safari drop every `::-webkit-scrollbar*` rule for that
+   element, including `::-webkit-scrollbar-thumb:hover` — measured in chromium
+   as an 8px `::-webkit-scrollbar` width taking effect on its own and being
+   ignored as soon as `scrollbar-width: thin` is added. Declaring both
+   unconditionally therefore leaves the hover tokens with no rendering at all,
+   because the engines that implement the hover pseudo-element are exactly the
+   ones the standard properties silence, and Firefox has no hover
+   pseudo-element to fall back on.
+
+   `not selector(::-webkit-scrollbar)` is true only where the pseudo-element
+   is unimplemented, so Firefox takes the standard path and WebKit-based
+   engines take the pseudo-element path. An engine too old for the
+   `selector()` function makes the condition invalid, which evaluates false
+   and selects the pseudo-element path — the correct side for the pre-16.4
+   Safari that is the realistic case. */
+@supports not selector(::-webkit-scrollbar) {
+  /* Declared on every element rather than inherited from `body`. Inheriting
+     would pass down the COLOUR already substituted at `body`, so a descendant
+     rebinding --dsh-scrollbar-thumb could not change it; re-declaring makes
+     each element substitute the variable as it sees it, which is what gives
+     an elevated surface a working rebind. `scrollbar-width` is not an
+     inherited property at all, so it needs the per-element declaration
+     regardless.
+
+     No hover counterpart exists on this path: `scrollbar-color` states one
+     thumb colour and the engine derives its own hover treatment. */
+  body,
+  body * {
+    scrollbar-width: thin;
+    scrollbar-color: var(--dsh-scrollbar-thumb) transparent;
+  }
+}
+
+/* Not gated in turn: an engine that does not implement these pseudo-elements
+   drops the rules as unknown selectors, so the gate would only restate what
+   selector matching already does. Not inherited either, hence the unscoped
+   selectors. */
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+/* Track stays transparent so the thumb reads against whatever surface scrolls
+   under it; only the thumb carries a token colour. */
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+
+::-webkit-scrollbar-thumb {
+  border-radius: 4px;
+  background: var(--dsh-scrollbar-thumb);
+}
+
+::-webkit-scrollbar-thumb:hover {
+  background: var(--dsh-scrollbar-thumb-hover);
+}
+
+/* Both scrollbars meeting in a corner: no separate token, so the corner
+   matches the transparent track rather than the UA's opaque default. */
+::-webkit-scrollbar-corner {
+  background: transparent;
+}

package/lib/styles/shiki.css

@@ -0,0 +1,31 @@
+/* Syntax-highlight token palette: the values behind shiki's css-variables
+   theme (--shiki-* custom properties emitted by the ui-primitives CodeBlock).
+   Light values on :root, dark overrides on the body attribute — the same
+   cascade as every other token sheet. Background/foreground deliberately
+   alias the markdown code-block tokens so highlighted and plain blocks agree. */
+
+:root {
+  --shiki-foreground: var(--dsw-alias-label-primary);
+  --shiki-background: var(--dsw-alias-markdown-code-block);
+  --shiki-token-constant: #1c7ed6;
+  --shiki-token-string: #2f9e44;
+  --shiki-token-comment: #868e96;
+  --shiki-token-keyword: #d6336c;
+  --shiki-token-parameter: #e8590c;
+  --shiki-token-function: #6741d9;
+  --shiki-token-string-expression: #2b8a3e;
+  --shiki-token-punctuation: #495057;
+  --shiki-token-link: #1971c2;
+}
+
+body[data-ds-dark-theme] {
+  --shiki-token-constant: #4dabf7;
+  --shiki-token-string: #69db7c;
+  --shiki-token-comment: #adb5bd;
+  --shiki-token-keyword: #faa2c1;
+  --shiki-token-parameter: #ffa94d;
+  --shiki-token-function: #b197fc;
+  --shiki-token-string-expression: #8ce99a;
+  --shiki-token-punctuation: #ced4da;
+  --shiki-token-link: #74c0fc;
+}

package/lib/types/client/AppearanceRow.d.ts

@@ -0,0 +1,17 @@
+import type { PropsLocale, PropsRuntime, PropsStore } from '@deepseek-ai/dsh-client-ui-slots';
+import type { ThemePreference } from '../theme-settings.ts';
+import type { createAppearanceRowStore } from './settings-store.ts';
+/** Injected business face: the preference write (t rides the standard locale seat). */
+export interface AppearanceRowInjected {
+    /** Switch the theme preference. */
+    setTheme: (id: ThemePreference) => void;
+}
+/** Full component props: runtime share + store share + locale seat + injected face. */
+export type AppearanceRowComponentProps = PropsRuntime<'settings.general.item'> & PropsStore<ReturnType<typeof createAppearanceRowStore>> & PropsLocale<'settings.theme'> & AppearanceRowInjected;
+/**
+ * Render the Appearance row.
+ * @param props - composed slot props.
+ * @returns the row element tree.
+ */
+export declare function AppearanceRow({ t, setTheme, useStore }: AppearanceRowComponentProps): import("react").JSX.Element;
+//# sourceMappingURL=AppearanceRow.d.ts.map

package/lib/types/client/index.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Browser theme registry over the `--dsw-*` token stylesheets. The service
+ * owns the live theme preference (light/dark/system), resolves `system` through
+ * `prefers-color-scheme`, and publishes immutable snapshots; it never touches
+ * the DOM — ui-layout's presenter consumes the resolved snapshot. The Host
+ * settings scope loads and stores the preference in the user-settings
+ * document. The plugin also registers the Appearance preference row into the
+ * settings General section — the theme feature owns its own settings surface.
+ */
+import type { Context } from '@deepseek-ai/cordis';
+import { type ClientContext, type SettingsScope } from '@deepseek-ai/dsh-client-runtime/client';
+import { type ThemeKey } from './locales.ts';
+import { type ThemePreference, type ThemeSettings } from '../theme-settings.ts';
+export type { AppearanceRowComponentProps, AppearanceRowInjected } from './AppearanceRow.tsx';
+export type { AppearanceRowState } from './settings-store.ts';
+export type { ThemeKey } from './locales.ts';
+export type { ThemePreference, ThemeSettings } from '../theme-settings.ts';
+/** Namespace owning this feature's settings-row copy. */
+export declare const SETTINGS_NS = "settings.theme";
+declare module '@deepseek-ai/dsh-client-ui-slots' {
+    interface LocaleNamespaceMap {
+        /** The Appearance settings row's copy. */
+        'settings.theme': ThemeKey;
+    }
+}
+/** Theme token dictionary: --dsw-alias-* overrides keyed by variable name. */
+export type ThemeTokens = Record<string, string>;
+/** One selectable theme: id, dark/light semantics, and alias-token overrides. */
+export interface ThemeDefinition {
+    /** Theme id (the setTheme argument for concrete themes). */
+    id: string;
+    /**
+     * Which base palette this theme builds on. The presenter switches
+     * `body[data-ds-dark-theme]` from this field — never from the id.
+     */
+    colorScheme: 'light' | 'dark';
+    /** Alias-layer overrides applied as inline CSS variables over the base palette. */
+    tokens: ThemeTokens;
+}
+/** Immutable theme state published on every change. */
+export interface ThemeSnapshot {
+    /** The persisted preference (may be `system`). */
+    preference: ThemePreference;
+    /** The resolved active theme (`system` resolved via prefers-color-scheme). */
+    active: ThemeDefinition;
+    /** Registered themes in registration order. */
+    themes: readonly ThemeDefinition[];
+    /** Monotonic change counter (registry or active changes). */
+    revision: number;
+}
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        theme: ThemeService;
+    }
+    interface Events {
+        /**
+         * Theme state changed (preference switched, registry updated, or the OS
+         * color scheme changed while the preference is `system`).
+         * @param snapshot - Current immutable theme snapshot.
+         * @mode emit
+         */
+        'theme/change'(snapshot: ThemeSnapshot): void;
+    }
+}
+/**
+ * Theme registry and preference owner. `light`/`dark` are built in (the base
+ * stylesheets carry both palettes); third-party themes register alias-layer
+ * overrides. Reads go through {@link getTheme}; writes only through
+ * {@link setTheme}; continuous sync only through the `theme/change` event.
+ * The service holds the `prefers-color-scheme` media query (environment
+ * sensing, not presentation) and re-emits when the OS scheme flips while the
+ * preference is `system`.
+ */
+export declare class ThemeService {
+    private readonly ctx;
+    private readonly host;
+    private themes;
+    private preference;
+    private revision;
+    private snapshot;
+    private readonly media;
+    /**
+     * @param ctx - owning context (change events are emitted on it; the
+     * media-query and scope listeners are released through ctx.effect on dispose).
+     * @param host - durable preference scope owned by the same plugin.
+     */
+    constructor(ctx: Context, host: SettingsScope<ThemeSettings>);
+    /**
+     * Read the current immutable theme snapshot.
+     * @returns the current snapshot (stable reference until the next change).
+     */
+    getTheme(): ThemeSnapshot;
+    /**
+     * Switch the theme preference — the only user preference write entry.
+     * Built-in preferences are written through the settings scope and every
+     * accepted value emits `theme/change`.
+     * @param id - a registered theme id or `system`; unknown ids throw.
+     */
+    setTheme(id: string): void;
+    /** Adopt the scope's accepted durable preference without writing it back. */
+    private adopt;
+    /**
+     * Register a theme. Duplicate id throws (single occupant per id; the
+     * built-in pair counts; `system` is a preference, not a registrable id).
+     * @param definition - theme id, colorScheme, and alias-token overrides.
+     * @returns disposer. Disposing the theme backing the active preference
+     * resets the preference to the default so the UI never keeps tokens of an
+     * unregistered theme.
+     */
+    register(definition: ThemeDefinition): () => void;
+    private buildSnapshot;
+    private publish;
+}
+/** Required services: settings transport plus slots/locale for the Appearance row. */
+export declare const inject: string[];
+/**
+ * Client plugin body: provide the theme service and register the
+ * feature-owned Appearance preference row into the General section's item
+ * slot (a feature owns its settings surface).
+ * @param ctx - client cordis context.
+ */
+export declare function apply(ctx: ClientContext): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/client/locales.d.ts

@@ -0,0 +1,18 @@
+/** `settings.theme` namespace dictionaries (the Appearance row's copy). */
+/** Simplified Chinese dictionary (the key-set source of truth). */
+export declare const zh: {
+    'appearance.title': string;
+    'appearance.light': string;
+    'appearance.dark': string;
+    'appearance.system': string;
+};
+/** The settings.theme namespace key union. */
+export type ThemeKey = keyof typeof zh;
+/** English dictionary, checked complete against the zh key set. */
+export declare const en: {
+    'appearance.title': string;
+    'appearance.light': string;
+    'appearance.dark': string;
+    'appearance.system': string;
+};
+//# sourceMappingURL=locales.d.ts.map

package/lib/types/client/settings-contract.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Re-export outlet for the `settings.general.item` slot type consumed by this
+ * package's Appearance row. The canonical home is the locale package (the
+ * common dependency of every item registrant); this file exists so row
+ * modules import the type from within their own package.
+ */
+export type { SettingsGeneralItemOwnerProps } from '@deepseek-ai/dsh-client-locale/client';
+//# sourceMappingURL=settings-contract.d.ts.map

package/lib/types/client/settings-store.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Appearance row slot store: a mirror of the theme service snapshot. The
+ * plugin's apply-world change listener is the only writer; the row component
+ * reads via props.useStore.
+ */
+import { type EngineStoreHandle } from '@deepseek-ai/dsh-client-runtime/client';
+import type { ThemePreference } from '../theme-settings.ts';
+/** Store state mirrored from the theme snapshot. */
+export interface AppearanceRowState {
+    /** Persisted preference (selection state reads this, never the resolved active theme). */
+    preference: ThemePreference;
+    /** Service revision; -1 until first sync so revision 0 lands as a change. */
+    revision: number;
+}
+/** Declared action shape giving the exported factory a stable return type. */
+type AppearanceRowActions = {
+    sync: (draft: AppearanceRowState, preference: ThemePreference, revision: number) => void;
+};
+/**
+ * Declares the Appearance row state and write surface.
+ * @returns the store handle.
+ */
+export declare function createAppearanceRowStore(): EngineStoreHandle<AppearanceRowState, AppearanceRowActions>;
+export {};
+//# sourceMappingURL=settings-store.d.ts.map

package/lib/types/index.d.ts

@@ -0,0 +1,9 @@
+/** Host registration for the browser theme preference. */
+import type { Context } from '@deepseek-ai/cordis';
+export { DEFAULT_PREFERENCE, THEME_PREFERENCE_FIELD, THEME_PREFERENCES, THEME_SETTINGS_NAMESPACE, type ThemePreference, type ThemeSettings, } from './theme-settings.ts';
+/**
+ * Register the durable theme section when a settings provider exists.
+ * @param ctx - Host context whose optional settings service owns the section.
+ */
+export declare function apply(ctx: Context): void;
+//# sourceMappingURL=index.d.ts.map

package/lib/types/invariant.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-client-ui-theme`.
+ * @module @deepseek-ai/dsh-client-ui-theme/invariant
+ */
+import type { Context } from '@deepseek-ai/cordis';
+/** Cordis companion plugin name. */
+export declare const name = "client-ui-theme-invariant";
+/** Service required before the companion can reserve package ownership. */
+export declare const inject: string[];
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export declare const apply: (ctx: Context) => Promise<() => void>;
+//# sourceMappingURL=invariant.d.ts.map

package/lib/types/theme-settings.d.ts

@@ -0,0 +1,26 @@
+/** Theme preferences stored in the Host user-settings document. */
+import z from '@deepseek-ai/schemastery';
+/** Built-in preferences accepted at the registry and settings boundaries. */
+export declare const THEME_PREFERENCES: readonly ["light", "dark", "system"];
+/** Settings namespace owned by the theme plugin. */
+export declare const THEME_SETTINGS_NAMESPACE = "ui-theme";
+/** Field carrying the selected built-in theme preference. */
+export declare const THEME_PREFERENCE_FIELD = "preference";
+/** Theme preference persisted by the product Appearance row. */
+export type ThemePreference = typeof THEME_PREFERENCES[number];
+/** Default preference when the user-settings document has no override. */
+export declare const DEFAULT_PREFERENCE: ThemePreference;
+/** Durable theme section shared by the Host schema and the browser scope. */
+export interface ThemeSettings {
+    /** Selected built-in preference. */
+    preference: ThemePreference;
+}
+/** Durable theme schema; also the wire envelope the browser scope validates against. */
+export declare const ThemeSettingsSchema: z<ThemeSettings>;
+/**
+ * Narrow one wire or registry value to a persistable preference.
+ * @param value - value crossing the settings or registry boundary.
+ * @returns whether the value is a built-in preference.
+ */
+export declare function isThemePreference(value: unknown): value is ThemePreference;
+//# sourceMappingURL=theme-settings.d.ts.map

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@deepseek-ai/dsh-client-ui-theme",
+  "description": "Theme plugin: ThemeService (light/dark/system preference, prefers-color-scheme resolution, theme/change snapshots; no DOM), --dsw-* token base stylesheets; registers the Appearance settings row",
+  "version": "0.0.1-rc.1",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "packages/client/ui-theme"
+  },
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./client": {
+      "types": "./lib/types/client/index.d.ts",
+      "default": "./lib/client.js"
+    },
+    "./styles/*": "./lib/styles/*",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "dsh": {
+    "client": {
+      "inject": [
+        "@deepseek-ai/dsh-client-connection",
+        "@deepseek-ai/dsh-client-runtime",
+        "@deepseek-ai/dsh-client-locale"
+      ],
+      "platform": "web",
+      "immediately": true
+    }
+  },
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-client-connection": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "devDependencies": {
+    "@types/react": "~18.3.1",
+    "react": "^18.2.0",
+    "@deepseek-ai/dsh-client-runtime": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-test-runtime": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-primitives": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-client-ui-slots": "^0.0.1-rc.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1-rc.1",
+    "@deepseek-ai/cordis": "^4.0.1-rc.1"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/client.js",
+    "lib/styles",
+    "lib/types/**/*.d.ts"
+  ],
+  "dependencies": {
+    "clsx": "^2.0.0",
+    "@deepseek-ai/dsh-settings": "^0.0.1-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.1-rc.1"
+  },
+  "scripts": {
+    "bundle": "tsdown",
+    "watch": "tsdown --watch"
+  }
+}