@d0nj/dsh-ui-custom 0.0.0-stage → 0.2.0

package/dist/index.js

@@ -0,0 +1,141 @@
+/**
+ * Host half: the customization document and its validation.
+ *
+ * The plugin does no rendering and holds no state of its own on the Host. It
+ * contributes one Config schema, which the profile stores and the browser half
+ * reads through its settings namespace, so a choice made in the panel survives a
+ * reload and a machine switch without this process tracking anything.
+ *
+ * `Config` is the contract; `resolve.ts` is the meaning. Keeping them apart means
+ * the panel can preview a change with the same resolver the stored document
+ * goes through, instead of reimplementing the merge rules in the browser.
+ *
+ * @module @d0nj/dsh-ui-custom
+ */
+import z from '@deepseek-ai/schemastery';
+import { DENSITIES, FONT_SIZE_RANGES, PRESET_IDS, RADIUS_MAX, RADIUS_MIN } from './spec.js';
+/** Cordis plugin name used by Loader diagnostics. */
+export const name = 'ui-custom';
+/** No services are required: this plugin only contributes configuration. */
+export const inject = [];
+/** One token override, with both palette modes required. */
+const TokenModesConfig = z.object({
+    light: z.string().description('Value used while the light palette is active.'),
+    dark: z.string().description('Value used while the dark palette is active.'),
+});
+/** Font stacks and sizes. */
+const TypographyConfig = z.object({
+    textFontFamily: z
+        .string()
+        .description('Interface and body font stack. Empty keeps the built-in stack.'),
+    codeFontFamily: z.string().description('Code font stack. Empty keeps the built-in stack.'),
+    terminalFontFamily: z
+        .string()
+        .description('Sidebar terminal font stack. Empty keeps the built-in stack.'),
+    fontSize: z
+        .number()
+        .step(1)
+        .min(FONT_SIZE_RANGES.text.min)
+        .max(FONT_SIZE_RANGES.text.max)
+        .default(FONT_SIZE_RANGES.text.fallback)
+        .description('Conversation text size in px.'),
+    codeFontSize: z
+        .number()
+        .step(1)
+        .min(FONT_SIZE_RANGES.code.min)
+        .max(FONT_SIZE_RANGES.code.max)
+        .default(FONT_SIZE_RANGES.code.fallback)
+        .description('Code block size in px.'),
+    terminalFontSize: z
+        .number()
+        .step(1)
+        .min(FONT_SIZE_RANGES.terminal.min)
+        .max(FONT_SIZE_RANGES.terminal.max)
+        .default(FONT_SIZE_RANGES.terminal.fallback)
+        .description('Sidebar terminal size in px.'),
+});
+/** Corner radius and spacing density. */
+const GeometryConfig = z.object({
+    radius: z
+        .number()
+        .step(1)
+        .min(RADIUS_MIN)
+        .max(RADIUS_MAX)
+        .default(8)
+        .description('Corner radius in px.'),
+    density: z
+        .union([z.const('compact'), z.const('comfortable'), z.const('spacious')])
+        .default('comfortable')
+        .description('Spacing density.'),
+});
+/**
+ * The plugin's config: one customization document.
+ *
+ * `basePreset` accepts any preset id or `none`. The resolver reports an unknown
+ * id as a warning rather than failing validation, because a stored document
+ * naming a preset from a newer version must not stop the plugin mounting.
+ */
+// Typed as the schema base so the emitted declaration stays portable: the fully
+// inferred type of a z.object chain names cosmokit through a pnpm store path.
+export const Config = z.object({
+    basePreset: z
+        .union([z.const('none'), ...PRESET_IDS.map((id) => z.const(id))])
+        .default('none')
+        .volatile()
+        .description(`Preset to build on: one of ${PRESET_IDS.join(', ')}, or none.`),
+    tokens: z
+        .dict(TokenModesConfig)
+        .volatile()
+        .description('Per-token overrides applied over the preset, keyed by CSS custom property name.'),
+    typography: TypographyConfig.volatile(),
+    geometry: GeometryConfig.volatile(),
+});
+/**
+ * Project a stored config into a complete customization document.
+ *
+ * The schema defaults every field, but a config read back from a partially
+ * written document may still be missing sections, so this fills them once here
+ * rather than at each use site.
+ * @param config - the config handed to `apply`.
+ * @returns a complete document.
+ */
+export function toDocument(input) {
+    const config = (input ?? {});
+    const read = (value) => {
+        if (value !== null && typeof value === 'object' && 'get' in value) {
+            return value.get();
+        }
+        return value;
+    };
+    const geometry = read(config.geometry);
+    const typography = read(config.typography);
+    const density = geometry?.density;
+    return {
+        basePreset: read(config.basePreset) ?? 'none',
+        tokens: read(config.tokens) ?? {},
+        typography: {
+            textFontFamily: typography?.textFontFamily ?? '',
+            codeFontFamily: typography?.codeFontFamily ?? '',
+            terminalFontFamily: typography?.terminalFontFamily ?? '',
+            fontSize: typography?.fontSize ?? FONT_SIZE_RANGES.text.fallback,
+            codeFontSize: typography?.codeFontSize ?? FONT_SIZE_RANGES.code.fallback,
+            terminalFontSize: typography?.terminalFontSize ?? FONT_SIZE_RANGES.terminal.fallback,
+        },
+        geometry: {
+            radius: geometry?.radius ?? 8,
+            density: density !== undefined && DENSITIES.includes(density)
+                ? density
+                : 'comfortable',
+        },
+    };
+}
+/**
+ * Host plugin body.
+ *
+ * The Host contributes nothing at runtime: the browser half owns the theme
+ * layer and fonts, and the settings service owns persistence.
+ */
+export function apply() { }
+export { PRESETS, TOKEN_SPECS, TOKEN_GROUPS, PRESET_IDS } from './spec.js';
+export { resolveCustomization } from './resolve.js';
+//# sourceMappingURL=index.js.map

package/dist/resolve.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Resolving a customization document into theme tokens.
+ *
+ * Three inputs combine, in this order:
+ *
+ * 1. A **preset**, which is a complete token set.
+ * 2. **Per-token overrides**, applied on top of the preset.
+ * 3. **Geometry**, expanded into whichever tokens it can express.
+ *
+ * The result is one `ThemeTokenOverrides` object — token name to `{light, dark}` —
+ * which is exactly what `ctx.theme.overrideTokens` accepts. Keeping the merge
+ * here, as a pure function, is what lets the panel preview a change and the Host
+ * validate one from the same code.
+ *
+ * @module @d0nj/dsh-ui-custom/resolve
+ */
+import { TOKEN_NAMES } from './spec.js';
+import type { Density, FontRole, TokenModes } from './spec.js';
+/** Geometry knobs the panel exposes. */
+export interface Geometry {
+    /** Corner radius in CSS pixels, 0–24. */
+    readonly radius: number;
+    /** Spacing density. */
+    readonly density: Density;
+}
+/** Typography settings the plugin applies through the theme service. */
+export interface Typography {
+    /** Interface and body font stack; empty keeps the built-in stack. */
+    readonly textFontFamily: string;
+    /** Code font stack; empty keeps the built-in stack. */
+    readonly codeFontFamily: string;
+    /** Sidebar terminal font stack; empty keeps the built-in stack. */
+    readonly terminalFontFamily: string;
+    /** Font sizes per role, each within its own range. */
+    readonly fontSize: number;
+    readonly codeFontSize: number;
+    readonly terminalFontSize: number;
+}
+/** The customization document, as the Host config carries it. */
+export interface CustomizationDocument {
+    /** Preset id, or `none` for no base. */
+    readonly basePreset: string;
+    /** Per-token overrides applied over the preset. */
+    readonly tokens: Readonly<Record<string, TokenModes>>;
+    /** Typography applied through the theme service. */
+    readonly typography: Typography;
+    /** Geometry applied as derived tokens. */
+    readonly geometry: Geometry;
+}
+/** Result of resolving a document. */
+export interface ResolvedCustomization {
+    /** Complete token overrides for `ctx.theme.overrideTokens`. */
+    readonly tokens: Readonly<Record<string, TokenModes>>;
+    /** Typography to apply, with out-of-range sizes corrected. */
+    readonly typography: Typography;
+    /** Problems found while resolving, for the panel to show. */
+    readonly warnings: readonly string[];
+}
+/**
+ * Whether a value is a plausible CSS colour.
+ *
+ * Colour tokens are rendered straight into CSS custom properties, so an
+ * arbitrary string would not be a security hole but would silently produce an
+ * unstyled surface. Rejecting it here turns that into a visible warning.
+ * @param value - candidate colour value.
+ * @returns true when the value looks like a CSS colour.
+ */
+export declare function isColor(value: string): boolean;
+/**
+ * Clamp a number into a closed range.
+ * @param value - candidate value.
+ * @param min - lower bound.
+ * @param max - upper bound.
+ * @returns the clamped integer.
+ */
+export declare function clamp(value: number, min: number, max: number): number;
+/**
+ * Expand geometry into token values.
+ *
+ * The documented token set has no radius or spacing tokens, so geometry is
+ * expressed as a *shadow layer* of `--d0nj-*` variables the panel's own styles
+ * consume, plus any `--dsw-*` tokens that exist. Emitting our own names keeps
+ * this additive: a token the harness does not define cannot break a surface,
+ * and the panel styles read ours.
+ *
+ * @param geometry - the requested geometry.
+ * @returns derived custom properties with identical light and dark values.
+ */
+export declare function geometryTokens(geometry: Geometry): Record<string, TokenModes>;
+/**
+ * Correct one role's font size into its accepted range.
+ * @param role - font role.
+ * @param px - requested size.
+ * @returns the in-range size.
+ */
+export declare function correctFontSize(role: FontRole, px: number): number;
+/**
+ * Whether a string names a known density.
+ * @param value - candidate density.
+ * @returns true for a known density.
+ */
+export declare function isDensity(value: string): value is Density;
+/**
+ * @param stack - comma-separated font stack.
+ * @returns the concrete family names, in order, without generics.
+ */
+export declare function familyNames(stack: string): string[];
+/**
+ * Resolve a customization document into theme tokens and typography.
+ *
+ * Merge order is preset, then explicit overrides, then geometry, so a user who
+ * picks a preset and then tweaks one token keeps the tweak, and geometry always
+ * wins over a token of the same name (it is the more specific control).
+ *
+ * @param document - the customization document.
+ * @returns the token overrides, corrected typography, and any warnings.
+ */
+export declare function resolveCustomization(document: CustomizationDocument): ResolvedCustomization;
+/** Every documented token name, re-exported for the panel's reset action. */
+export { TOKEN_NAMES };
+//# sourceMappingURL=resolve.d.ts.map

package/dist/resolve.js

@@ -0,0 +1,166 @@
+/**
+ * Resolving a customization document into theme tokens.
+ *
+ * Three inputs combine, in this order:
+ *
+ * 1. A **preset**, which is a complete token set.
+ * 2. **Per-token overrides**, applied on top of the preset.
+ * 3. **Geometry**, expanded into whichever tokens it can express.
+ *
+ * The result is one `ThemeTokenOverrides` object — token name to `{light, dark}` —
+ * which is exactly what `ctx.theme.overrideTokens` accepts. Keeping the merge
+ * here, as a pure function, is what lets the panel preview a change and the Host
+ * validate one from the same code.
+ *
+ * @module @d0nj/dsh-ui-custom/resolve
+ */
+import { DENSITIES, FONT_SIZE_RANGES, RADIUS_MAX, RADIUS_MIN, TOKEN_NAMES, findPreset, tokenSpec, } from './spec.js';
+/** A colour in one of the forms the theme service and browsers accept. */
+const COLOR_PATTERN = /^(#(?:[0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})|(?:rgb|hsl|oklch|lab|lch|color)\([^)]*\)|[a-z]+)$/iu;
+/** CSS generic families, which always resolve and so never need a local match. */
+const GENERIC_FAMILIES = new Set([
+    'serif', 'sans-serif', 'monospace', 'cursive', 'fantasy', 'system-ui',
+    'ui-serif', 'ui-sans-serif', 'ui-monospace', 'ui-rounded', 'emoji', 'math',
+    'fangsong', '-apple-system', 'blinkmacsystemfont',
+    'inherit', 'initial', 'unset',
+]);
+/**
+ * Whether a value is a plausible CSS colour.
+ *
+ * Colour tokens are rendered straight into CSS custom properties, so an
+ * arbitrary string would not be a security hole but would silently produce an
+ * unstyled surface. Rejecting it here turns that into a visible warning.
+ * @param value - candidate colour value.
+ * @returns true when the value looks like a CSS colour.
+ */
+export function isColor(value) {
+    return COLOR_PATTERN.test(value.trim());
+}
+/**
+ * Clamp a number into a closed range.
+ * @param value - candidate value.
+ * @param min - lower bound.
+ * @param max - upper bound.
+ * @returns the clamped integer.
+ */
+export function clamp(value, min, max) {
+    if (!Number.isFinite(value))
+        return min;
+    return Math.min(max, Math.max(min, Math.round(value)));
+}
+/**
+ * Expand geometry into token values.
+ *
+ * The documented token set has no radius or spacing tokens, so geometry is
+ * expressed as a *shadow layer* of `--d0nj-*` variables the panel's own styles
+ * consume, plus any `--dsw-*` tokens that exist. Emitting our own names keeps
+ * this additive: a token the harness does not define cannot break a surface,
+ * and the panel styles read ours.
+ *
+ * @param geometry - the requested geometry.
+ * @returns derived custom properties with identical light and dark values.
+ */
+export function geometryTokens(geometry) {
+    const radius = clamp(geometry.radius, RADIUS_MIN, RADIUS_MAX);
+    const scale = geometry.density === 'compact' ? 0.8 : geometry.density === 'spacious' ? 1.25 : 1;
+    const value = (px) => ({ light: px, dark: px });
+    return {
+        '--d0nj-radius-sm': value(`${String(Math.round(radius * 0.5))}px`),
+        '--d0nj-radius-md': value(`${String(radius)}px`),
+        '--d0nj-radius-lg': value(`${String(Math.round(radius * 1.5))}px`),
+        '--d0nj-space-1': value(`${String(Math.round(4 * scale))}px`),
+        '--d0nj-space-2': value(`${String(Math.round(8 * scale))}px`),
+        '--d0nj-space-3': value(`${String(Math.round(12 * scale))}px`),
+        '--d0nj-space-4': value(`${String(Math.round(16 * scale))}px`),
+    };
+}
+/**
+ * Correct one role's font size into its accepted range.
+ * @param role - font role.
+ * @param px - requested size.
+ * @returns the in-range size.
+ */
+export function correctFontSize(role, px) {
+    const range = FONT_SIZE_RANGES[role];
+    return clamp(px, range.min, range.max);
+}
+/**
+ * Whether a string names a known density.
+ * @param value - candidate density.
+ * @returns true for a known density.
+ */
+export function isDensity(value) {
+    return DENSITIES.includes(value);
+}
+/**
+ * @param stack - comma-separated font stack.
+ * @returns the concrete family names, in order, without generics.
+ */
+export function familyNames(stack) {
+    return stack
+        .split(',')
+        .map((part) => part.trim().replace(/^["']|["']$/gu, '').trim())
+        .filter((name) => name !== '' && !GENERIC_FAMILIES.has(name.toLowerCase()));
+}
+/**
+ * Resolve a customization document into theme tokens and typography.
+ *
+ * Merge order is preset, then explicit overrides, then geometry, so a user who
+ * picks a preset and then tweaks one token keeps the tweak, and geometry always
+ * wins over a token of the same name (it is the more specific control).
+ *
+ * @param document - the customization document.
+ * @returns the token overrides, corrected typography, and any warnings.
+ */
+export function resolveCustomization(document) {
+    const warnings = [];
+    const tokens = {};
+    if (document.basePreset !== 'none') {
+        const preset = findPreset(document.basePreset);
+        if (preset === undefined) {
+            warnings.push(`unknown preset "${document.basePreset}"; no base tokens applied`);
+        }
+        else {
+            for (const [name, modes] of Object.entries(preset.tokens))
+                tokens[name] = modes;
+        }
+    }
+    for (const [name, modes] of Object.entries(document.tokens)) {
+        const spec = tokenSpec(name);
+        if (spec === undefined) {
+            // A hand-edited document can name a token this build does not document.
+            // Skipping it with a warning beats applying a property nothing reads.
+            warnings.push(`ignoring undocumented token "${name}"`);
+            continue;
+        }
+        const light = modes.light.trim();
+        const dark = modes.dark.trim();
+        if (light.length === 0 || dark.length === 0) {
+            warnings.push(`token "${name}" needs both a light and a dark value`);
+            continue;
+        }
+        if (spec.kind === 'color' && (!isColor(light) || !isColor(dark))) {
+            warnings.push(`token "${name}" is not a valid CSS colour`);
+            continue;
+        }
+        tokens[name] = { light, dark };
+    }
+    for (const [name, modes] of Object.entries(geometryTokens(document.geometry))) {
+        tokens[name] = modes;
+    }
+    const typography = {
+        textFontFamily: document.typography.textFontFamily,
+        codeFontFamily: document.typography.codeFontFamily,
+        terminalFontFamily: document.typography.terminalFontFamily,
+        fontSize: correctFontSize('text', document.typography.fontSize),
+        codeFontSize: correctFontSize('code', document.typography.codeFontSize),
+        terminalFontSize: correctFontSize('terminal', document.typography.terminalFontSize),
+    };
+    if (typography.fontSize !== document.typography.fontSize) {
+        warnings.push(`text font size corrected to ${String(typography.fontSize)}px (allowed ${String(FONT_SIZE_RANGES.text.min)}–${String(FONT_SIZE_RANGES.text.max)})`);
+    }
+    return { tokens, typography, warnings };
+}
+/** Every documented token name, re-exported for the panel's reset action. */
+export { TOKEN_NAMES };
+//# sourceMappingURL=resolve.js.map

package/dist/spec.d.ts

@@ -0,0 +1,101 @@
+/**
+ * The token catalog and the shipped presets.
+ *
+ * Every override must supply **both** palette modes. The theme runtime requires
+ * it (`ThemeTokenModes`), because a token defined for only one scheme goes
+ * illegible when the user flips to the other — so this module represents that
+ * requirement in the type rather than trusting each caller to remember it.
+ *
+ * @module @d0nj/dsh-ui-custom/spec
+ */
+/** One token's value in each palette mode. */
+export interface TokenModes {
+    readonly light: string;
+    readonly dark: string;
+}
+/** Whether a token is a colour (validated as a colour) or an arbitrary CSS value. */
+export type TokenKind = 'color' | 'length' | 'shadow' | 'font';
+/** One documented token the editor can change. */
+export interface TokenSpec {
+    /** CSS custom property name, such as `--dsw-alias-bg-base`. */
+    readonly name: string;
+    /** Short human label for the editor row. */
+    readonly label: string;
+    /** Grouping in the editor. */
+    readonly group: TokenGroup;
+    /** How the value is validated and rendered. */
+    readonly kind: TokenKind;
+    /** What the token affects, shown as the row hint. */
+    readonly description: string;
+}
+/** Editor grouping, ordered as the panel renders them. */
+export type TokenGroup = 'surface' | 'border' | 'text' | 'accent' | 'state';
+/** Groups in display order, with their headings. */
+export declare const TOKEN_GROUPS: readonly {
+    readonly id: TokenGroup;
+    readonly label: string;
+}[];
+/**
+ * The documented alias tokens.
+ *
+ * These are the tokens the theme Inspect provider reports for this build, so the
+ * editor never offers a row that would silently do nothing.
+ */
+export declare const TOKEN_SPECS: readonly TokenSpec[];
+/** Every documented token name, for validation. */
+export declare const TOKEN_NAMES: readonly string[];
+/**
+ * Look up one token's specification.
+ * @param name - CSS custom property name.
+ * @returns the specification, or `undefined` when the token is not documented.
+ */
+export declare function tokenSpec(name: string): TokenSpec | undefined;
+/** One shipped preset: a complete, legible theme in both modes. */
+export interface ThemePreset {
+    /** Stable id, used as the `basePreset` config value. */
+    readonly id: string;
+    /** Display name. */
+    readonly label: string;
+    /** One-line description shown on the preset card. */
+    readonly description: string;
+    /** The base palette this preset reads as. */
+    readonly colorScheme: 'light' | 'dark';
+    /** Complete token set — every documented token, in both modes. */
+    readonly tokens: Readonly<Record<string, TokenModes>>;
+}
+/**
+ * Shipped presets.
+ *
+ * Each is a complete token set rather than a partial overlay, so selecting one
+ * gives a predictable result no matter what the generated base palette does.
+ * The colours are chosen to keep body text at or above WCAG AA contrast against
+ * their own surfaces, which the tests check.
+ */
+export declare const PRESETS: readonly ThemePreset[];
+/** Every preset id, for validation. */
+export declare const PRESET_IDS: readonly string[];
+/**
+ * Look up one preset by id.
+ * @param id - preset id.
+ * @returns the preset, or `undefined` for an unknown or `none` id.
+ */
+export declare function findPreset(id: string): ThemePreset | undefined;
+/** The role names the theme runtime accepts for typography. */
+export declare const FONT_ROLES: readonly ["text", "code", "terminal"];
+/** One font role. */
+export type FontRole = (typeof FONT_ROLES)[number];
+/** Accepted font-size range per role, mirroring the shipped Appearance rows. */
+export declare const FONT_SIZE_RANGES: Readonly<Record<FontRole, {
+    readonly min: number;
+    readonly max: number;
+    readonly fallback: number;
+}>>;
+/** Density presets, expressed as a spacing multiplier applied to derived tokens. */
+export declare const DENSITIES: readonly ["compact", "comfortable", "spacious"];
+/** One density option. */
+export type Density = (typeof DENSITIES)[number];
+/** Radius bounds in pixels. */
+export declare const RADIUS_MIN = 0;
+/** Upper radius bound in pixels. */
+export declare const RADIUS_MAX = 24;
+//# sourceMappingURL=spec.d.ts.map