@citisen/dsh-font 0.1.0

package/lib/index.js

@@ -0,0 +1,239 @@
+/**
+ * Host half of `dsh-font`.
+ *
+ * A dsh Web profile bundle has two halves. This file is the Node half: it owns
+ * the durable `ui-font` settings namespace (so every value the Settings row
+ * writes survives a restart inside `$DSH_HOME/settings.yaml`) and it
+ * contributes a pre-paint `<style>` row to the served index document, so the
+ * chosen families and sizes apply to the very first frame instead of flashing
+ * the shipped defaults while the browser plugin tree activates.
+ *
+ * The browser half lives in `./client` (`src/client.js` -> `lib/client.js`) and
+ * owns the actual presentation: it stacks the families onto the design system's
+ * font tokens through the theme service and registers the Settings row.
+ *
+ * @module dsh-font
+ */
+
+import z from '@deepseek-ai/schemastery'
+
+/**
+ * Settings namespace owned by this plugin. Lowercase-hyphenated, matching the
+ * sibling `ui-theme` namespace the Web surface already ships.
+ */
+export const FONT_SETTINGS_NAMESPACE = 'ui-font'
+
+/** Field: CSS font-family list for interface (non-code) text. */
+export const UI_FONT_FAMILY_FIELD = 'uiFontFamily'
+/** Field: CSS font-family list for code, terminal, and monospace text. */
+export const CODE_FONT_FAMILY_FIELD = 'codeFontFamily'
+/** Field: scale applied to every interface font size, as a unitless number. */
+export const UI_FONT_SCALE_FIELD = 'uiFontScale'
+/** Field: conversation content font size in px (owns `--dsh-content-font-size`). */
+export const CONTENT_FONT_SIZE_FIELD = 'contentFontSize'
+/** Field: conversation code font size in px. */
+export const CODE_FONT_SIZE_FIELD = 'codeFontSize'
+
+/** Shipped interface family, mirroring `ui-theme`'s `--dsw-font-family`. */
+export const DEFAULT_UI_FONT_FAMILY =
+  '-apple-system, BlinkMacSystemFont, "Segoe UI", "PingFang SC", "Hiragino Sans GB", "Microsoft YaHei", "Helvetica Neue", Helvetica, Arial, sans-serif'
+/** Shipped code family, mirroring `ui-theme`'s `--ds-font-family-code`. */
+export const DEFAULT_CODE_FONT_FAMILY =
+  '"SF Mono", "JetBrains Mono", "Fira Code", Consolas, "Liberation Mono", Menlo, Courier, "PingFang SC", "Microsoft YaHei"'
+
+/** Accepted interface scale range (1 = the shipped sizes). */
+export const UI_FONT_SCALE_MIN = 0.75
+/** Accepted interface scale range upper bound. */
+export const UI_FONT_SCALE_MAX = 1.5
+/** Accepted conversation content font size range in px. */
+export const CONTENT_FONT_SIZE_MIN = 12
+/** Accepted conversation content font size range in px. */
+export const CONTENT_FONT_SIZE_MAX = 20
+/** Accepted code font size range in px. */
+export const CODE_FONT_SIZE_MIN = 10
+/** Accepted code font size range in px. */
+export const CODE_FONT_SIZE_MAX = 20
+
+/** The one stylesheet id the pre-paint bootstrap and the browser half share. */
+export const FONT_STYLE_ID = 'dsh-font/variables'
+
+/**
+ * Durable font preferences. Every field defaults to the shipped value, so an
+ * empty (or absent) `ui-font` section resolves to "no customization".
+ *
+ * The schema is the wire contract: the settings domain validates every write
+ * from the Settings row against it, and the configuration surface renders it.
+ */
+export const FontSettingsSchema = z.object({
+  [UI_FONT_FAMILY_FIELD]: z.string().default(DEFAULT_UI_FONT_FAMILY),
+  [CODE_FONT_FAMILY_FIELD]: z.string().default(DEFAULT_CODE_FONT_FAMILY),
+  [UI_FONT_SCALE_FIELD]: z
+    .number()
+    .min(UI_FONT_SCALE_MIN)
+    .max(UI_FONT_SCALE_MAX)
+    .default(1),
+  [CONTENT_FONT_SIZE_FIELD]: z
+    .number()
+    .step(1)
+    .min(CONTENT_FONT_SIZE_MIN)
+    .max(CONTENT_FONT_SIZE_MAX)
+    .default(14),
+  [CODE_FONT_SIZE_FIELD]: z
+    .number()
+    .step(1)
+    .min(CODE_FONT_SIZE_MIN)
+    .max(CODE_FONT_SIZE_MAX)
+    .default(12),
+})
+
+/** The interface font sizes the shipped components hard-code, in px. */
+const UI_TEXT_STEPS = [11, 12, 13, 14, 16, 20, 24]
+
+/**
+ * The interface-scale rules: every hard-coded UI text size is re-derived from
+ * the user's scale. Sizes outside {@link UI_TEXT_STEPS} (display headings, the
+ * SVG labels baked into file-type icons) are deliberately left alone.
+ *
+ * @param scale - unitless multiplier, 1 = shipped sizes.
+ * @returns one CSS declaration block body.
+ */
+function uiScaleRules(scale) {
+  return UI_TEXT_STEPS.map(
+    (step) =>
+      `font-size:calc(${step}px * var(--dsh-font-ui-scale,1)) !important`,
+  ).join(';')
+}
+
+/**
+ * Build the pre-paint stylesheet for one resolved settings section.
+ *
+ * This is the subset of the browser half's sheet that must exist before any
+ * plugin runs: the interface scale and the conversation text size. Families are
+ * handled separately (see {@link fontBootstrapScript}) because the design
+ * system resolves them through `var()` chains the shell's own `body` rule
+ * already reads.
+ *
+ * Written as a `<style>` element rather than inline custom properties because
+ * `ui-layout`'s theme presenter owns `document.body.style` and rewrites the
+ * token set on every theme change; a stylesheet cannot be clobbered by it.
+ * The selectors are `html body ...` so they outrank the shipped component
+ * rules regardless of stylesheet order.
+ *
+ * @param section - resolved `ui-font` value (validated or schema-defaulted).
+ * @returns the complete stylesheet text.
+ */
+export function fontStyleSheet(section) {
+  const uiScale = section[UI_FONT_SCALE_FIELD]
+  const contentSize = section[CONTENT_FONT_SIZE_FIELD]
+  const codeSize = section[CODE_FONT_SIZE_FIELD]
+
+  return [
+    '/* dsh-font: pre-paint variables and interface scale */',
+    'html body{',
+    `--dsh-font-ui-scale:${String(uiScale)};`,
+    `--dsh-font-content-size:${String(contentSize)}px;`,
+    `--dsh-font-code-size:${String(codeSize)}px;`,
+    '}',
+    'html body,html body *{',
+    uiScaleRules(uiScale),
+    '}',
+  ].join('\n')
+}
+
+/**
+ * Escape a stylesheet for embedding inside an inline `<script>` element.
+ * @param text - raw stylesheet text.
+ * @returns the text safe to place in a script body.
+ */
+function escapeForScript(text) {
+  return text.replaceAll('</', '<\\/')
+}
+
+/**
+ * The pre-paint bootstrap: inject the stylesheet, then mirror the two family
+ * values onto the design system's own tokens so pre-existing CSS that reads
+ * `var(--dsw-font-family)` (the shell's `body` rule, for instance) agrees with
+ * the hard-coded variable set before the browser half ever runs.
+ *
+ * @param section - resolved `ui-font` value.
+ * @returns inline script text.
+ */
+export function fontBootstrapScript(section) {
+  const uiFamily = JSON.stringify(section[UI_FONT_FAMILY_FIELD])
+  const codeFamily = JSON.stringify(section[CODE_FONT_FAMILY_FIELD])
+  // Keep the stylesheet after the user-controlled family strings so the
+  // `</`-escaping cannot be defeated by a family value that itself contains a
+  // script-closing sequence.
+  const css = escapeForScript(fontStyleSheet(section))
+
+  return `(() => {
+  try {
+    const css = ${JSON.stringify(css)}
+    const existing = document.getElementById(${JSON.stringify(FONT_STYLE_ID)})
+    const tag = existing !== null ? existing : document.createElement('style')
+    if (existing === null) {
+      tag.id = ${JSON.stringify(FONT_STYLE_ID)}
+      tag.dataset.plugin = 'dsh-font'
+      const parent = document.head || document.documentElement
+      parent.appendChild(tag)
+    }
+    tag.textContent = css
+    const root = document.documentElement.style
+    root.setProperty('--dsw-font-family', ${uiFamily})
+    root.setProperty('--ds-font-family-code', ${codeFamily})
+  } catch (error) {
+    console.warn('dsh-font: pre-paint bootstrap failed', error)
+  }
+})()`
+}
+
+/**
+ * The bootstrap as a webserver index-injection row.
+ * @param section - resolved `ui-font` value.
+ * @returns the head script row.
+ */
+export function fontInjection(section) {
+  return {
+    kind: 'script',
+    placement: 'head',
+    text: fontBootstrapScript(section),
+  }
+}
+
+/**
+ * Read the registered `ui-font` section, or the schema defaults when the
+ * settings provider is absent or the section is unreadable.
+ * @param ctx - host context.
+ * @returns a complete settings section.
+ */
+function readSection(ctx) {
+  const fallback = {
+    [UI_FONT_FAMILY_FIELD]: DEFAULT_UI_FONT_FAMILY,
+    [CODE_FONT_FAMILY_FIELD]: DEFAULT_CODE_FONT_FAMILY,
+    [UI_FONT_SCALE_FIELD]: 1,
+    [CONTENT_FONT_SIZE_FIELD]: 14,
+    [CODE_FONT_SIZE_FIELD]: 12,
+  }
+  const settings = ctx.get('settings')
+  if (settings === null || typeof settings !== 'object') return fallback
+  if (typeof settings.get !== 'function') return fallback
+  const section = settings.get(FONT_SETTINGS_NAMESPACE)
+  if (section === null || typeof section !== 'object') return fallback
+  return { ...fallback, ...section }
+}
+
+/**
+ * Host plugin body: register the durable namespace when the optional settings
+ * provider is composed, and answer every index-injection collection with the
+ * current pre-paint bootstrap.
+ * @param ctx - host context that may acquire the settings service.
+ */
+export function apply(ctx) {
+  ctx.inject(['settings'], (settingsCtx) => {
+    settingsCtx.settings.register(FONT_SETTINGS_NAMESPACE, FontSettingsSchema)
+  })
+
+  ctx.on('webserver/index-inject', (table) => {
+    table.push(fontInjection(readSection(ctx)))
+  })
+}

package/package.json

@@ -0,0 +1,76 @@
+{
+  "name": "@citisen/dsh-font",
+  "version": "0.1.0",
+  "description": "DeepSeek Harness plugin: customize the Web GUI fonts (interface family, code family, and three font-size axes) from Settings",
+  "type": "module",
+  "license": "MIT",
+  "author": "citisen",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/citisen/dsh-font.git"
+  },
+  "homepage": "https://github.com/citisen/dsh-font#readme",
+  "bugs": {
+    "url": "https://github.com/citisen/dsh-font/issues"
+  },
+  "main": "lib/index.js",
+  "exports": {
+    ".": "./lib/index.js",
+    "./client": "./lib/client.js",
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/client.js",
+    "cordis.patch.yml",
+    "src",
+    "scripts",
+    "README.md",
+    "README.zh.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dsh": {
+    "bundle": {
+      "patch": "./cordis.patch.yml"
+    },
+    "client": {
+      "platform": "web",
+      "immediately": true,
+      "inject": [
+        "@deepseek-ai/dsh-client-ui-theme"
+      ]
+    }
+  },
+  "scripts": {
+    "build": "node scripts/build-client.mjs",
+    "watch": "node scripts/build-client.mjs --watch",
+    "verify": "node scripts/verify-host.mjs && node scripts/verify-client.mjs",
+    "check": "node scripts/build-client.mjs --check && npm run verify"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "^4.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@deepseek-ai/cordis": {
+      "optional": true
+    }
+  },
+  "keywords": [
+    "deepseek-harness",
+    "deepseek",
+    "dsh",
+    "dsh-plugin",
+    "dsh-bundle",
+    "font",
+    "fonts",
+    "font-family",
+    "font-size",
+    "theme",
+    "web-ui",
+    "web-gui"
+  ]
+}

package/scripts/build-client.mjs

@@ -0,0 +1,297 @@
+/**
+ * Build `lib/client.js` from `src/client.js`.
+ *
+ * DSH client bundles are classic scripts, not ES modules: the browser shell
+ * loads them with a plain `<script>` element and they may only register a lazy
+ * CJS factory with `window.__ModuleLoader__`. This script applies that envelope
+ * and rewrites the template's static ESM imports into the factory's CommonJS
+ * `require` form.
+ *
+ * The transformation is deliberately narrow — it supports exactly the import
+ * shapes the template uses — because a hand-rolled client bundle has no
+ * bundler to catch a mistake. Any unsupported syntax fails the build loudly.
+ *
+ * Usage:
+ *   node scripts/build-client.mjs           # write lib/client.js
+ *   node scripts/build-client.mjs --watch   # rebuild on save (for dsh-client-hmr)
+ *   node scripts/build-client.mjs --check   # fail if lib/client.js is stale
+ */
+
+import { readFileSync, watch, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const root = join(dirname(fileURLToPath(import.meta.url)), '..')
+const sourcePath = join(root, 'src', 'client.js')
+const outputPath = join(root, 'lib', 'client.js')
+
+/**
+ * The bundle id the shell's module table keys on. It must equal the package
+ * name: `dsh-client-modules` resolves a roster row by the loader entry name and
+ * matches it against the id the bundle registers. Read from package.json rather
+ * than duplicated here, so a rename cannot desynchronize the two.
+ */
+const PACKAGE_NAME = JSON.parse(readFileSync(join(root, 'package.json'), 'utf8')).name
+
+/**
+ * The names the envelope exports from the compiled factory. The first entry is
+ * what the loader consumes; the rest exist so the verifier can unit-test the
+ * pure builders without re-parsing the source.
+ */
+const ENVELOPE_EXPORTS = ['apply', 'inject', 'fontStyleSheet', 'applyFonts']
+
+/**
+ * `import [default][, { named }] from 'spec'`, with no nested braces.
+ * Matches the whole line so no stray `import` survives the rewrite.
+ */
+const IMPORT_PATTERN =
+  /^import\s+(?:(?<default>[A-Za-z_$][\w$]*)\s*,\s*)?(?:\{\s*(?<named>[^{}]*?)\s*\})?\s*from\s*'(?<spec>[^']+)'\s*$/gm
+
+/**
+ * The only specifiers the shell seeds into the browser module table. Anything
+ * else has to be declared in `dsh.client.external` and shipped as its own
+ * graph row; a mistake would otherwise surface only at runtime in the browser.
+ */
+const PLATFORM_SINGLETONS = new Set([
+  'react',
+  'react/jsx-runtime',
+  'react-dom',
+  'react-dom/client',
+  '@deepseek-ai/cordis',
+  '@deepseek-ai/dsh-client-store',
+  '@deepseek-ai/dsh-client-ui-slots',
+  '@deepseek-ai/dsh-client-ui-primitives',
+  '@deepseek-ai/dsh-client-ui-dockkit',
+])
+
+/**
+ * Turn one specifier into the alias the compiled bundle binds it to, matching
+ * the naming convention DSH's own bundles are emitted with.
+ * @param spec - module specifier, e.g. `react/jsx-runtime`.
+ * @returns the bound identifier.
+ */
+function aliasFor(spec) {
+  return `_${spec.replace(/^@/, '').replace(/[^A-Za-z0-9]+/g, '_').replace(/_+$/, '')}`
+}
+
+/**
+ * Rewrite every static import into a `let <alias> = require('<spec>')`
+ * binding, exactly as the shipped bundles are emitted.
+ * @param source - the template source.
+ * @returns the transformed source and the specifiers it requests.
+ */
+function rewriteImports(source) {
+  const requested = []
+  const namedBindings = []
+  const defaultBindings = []
+  let matched = 0
+
+  const body = source.replace(IMPORT_PATTERN, (...args) => {
+    const groups = args.at(-1)
+    const { default: defaultName, named, spec } = groups
+    matched += 1
+    requested.push(spec)
+
+    const generated = aliasFor(spec)
+    // A default import binds the alias itself (`let _react = require("react")`
+    // is the whole module object); a named one reaches through a property read.
+    // Both are resolved to the alias so the emitted body never mentions the
+    // original local name.
+    if (defaultName !== undefined) {
+      if (!/^[A-Za-z_$][\w$]*$/.test(defaultName)) {
+        throw new Error(`build-client: unsupported default import name "${defaultName}"`)
+      }
+      defaultBindings.push([spec, defaultName])
+    }
+    for (const entry of (named ?? '').split(',')) {
+      const trimmed = entry.trim()
+      if (trimmed === '') continue
+      if (!/^[A-Za-z_$][\w$]*$/.test(trimmed)) {
+        throw new Error(
+          `build-client: unsupported named import "${trimmed}" from "${spec}" — write the local name identical to the exported name`,
+        )
+      }
+      namedBindings.push([spec, trimmed])
+    }
+    return `\t\tlet ${generated} = require(${JSON.stringify(spec)});`
+  })
+
+  if (matched === 0) throw new Error('build-client: no static imports found in src/client.js')
+  return { body, requested, namedBindings, defaultBindings }
+}
+
+/**
+ * Resolve every imported identifier to its `require` alias, matching how DSH's
+ * own bundles consume the module table. The replacement is anchored so it can
+ * never touch an already-qualified access, a string, or a property name.
+ * @param body - source whose imports have been rewritten.
+ * @param bindings - the `rewriteImports` binding lists.
+ * @returns the rewritten source.
+ */
+function qualifyImports(body, { namedBindings, defaultBindings }) {
+  let out = body
+  const seen = new Set()
+  const replaceIdentifier = (name, replacement) => {
+    if (seen.has(name)) return
+    seen.add(name)
+    const pattern = new RegExp(`(?<![.\\w$'"\`])${name}(?=[\\s(.,;)\\]}])`, 'g')
+    out = out.replace(pattern, replacement)
+  }
+  for (const [spec, name] of defaultBindings) replaceIdentifier(name, aliasFor(spec))
+  for (const [spec, name] of namedBindings) replaceIdentifier(name, `${aliasFor(spec)}.${name}`)
+  return out
+}
+
+/**
+ * The plugin-identity declaration the template carries. The build substitutes
+ * the real package name, which is the value the theme registry pins an override
+ * layer to and the roster keys a bundle on. Keeping it single-sourced in
+ * package.json means a rename cannot desynchronize the bundle id, the theme
+ * layer, and the loader row.
+ */
+const IDENTITY_PATTERN = /\/\* dsh:plugin-id \*\/\s*(['"])[^'"]*\1/
+
+/** The CSS namespace prefix. Purely cosmetic; never compared against npm. */
+const STYLE_PREFIX = 'dsh-font'
+
+/**
+ * Substitute the template's identity declaration with the real package name.
+ * @param body - source after import rewriting.
+ * @returns the source with the single declaration substituted.
+ * @throws {Error} when the declaration is missing or repeated.
+ */
+function substituteIdentity(body) {
+  const matches = body.match(new RegExp(IDENTITY_PATTERN.source, 'g')) ?? []
+  if (matches.length !== 1) {
+    throw new Error(
+      `build-client: src/client.js must contain exactly one /* dsh:plugin-id */ identity declaration (found ${String(matches.length)})`,
+    )
+  }
+  return body.replace(IDENTITY_PATTERN, JSON.stringify(PACKAGE_NAME))
+}
+
+/**
+ * Strip the template's `export` keywords. The envelope re-exports
+ * {@link ENVELOPE_EXPORTS} from the factory, so each of those only has to be a
+ * top-level declaration — exporting it is optional and is removed either way.
+ * @param body - transformed template source.
+ * @returns source without declaration exports.
+ */
+function stripExports(body) {
+  for (const name of ENVELOPE_EXPORTS) {
+    const declaration = new RegExp(
+      `^(?:export )?(?:const|let|var|function|class) ${name}\\b`,
+      'm',
+    )
+    if (!declaration.test(body)) {
+      throw new Error(
+        `build-client: src/client.js must declare \`${name}\` at the top level for the envelope to re-export`,
+      )
+    }
+  }
+  const stripped = body.replace(/^export (const|let|var|function|class) /gm, '$1 ')
+  if (/^\s*export\s/m.test(stripped)) {
+    throw new Error(
+      'build-client: src/client.js contains an export form the build cannot strip (only top-level declarations may be exported)',
+    )
+  }
+  return stripped
+}
+
+/**
+ * Wrap the transformed source in the DSH client-bundle envelope.
+ * @param body - transformed, export-stripped template source.
+ * @returns the complete bundle text.
+ */
+function wrap(body) {
+  const exports = ENVELOPE_EXPORTS.map((name) => `\t\texports.${name} = ${name};`).join('\n')
+  return `window.__ModuleLoader__.load({
+\tid: ${JSON.stringify(PACKAGE_NAME)},
+\tfactory: (require) => {
+\t\tvar module = { exports: {} };
+\t\tvar exports = module.exports;
+\t\tObject.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+${body.trimEnd()}
+${exports}
+\t\treturn module.exports;
+\t}
+});
+`
+}
+
+/**
+ * Compile the template into the complete bundle text.
+ * @returns the bundle and the specifiers it requests.
+ * @throws {Error} on any import shape the transformation cannot express.
+ */
+function compile() {
+  const template = readFileSync(sourcePath, 'utf8')
+  const { body, requested, namedBindings, defaultBindings } = rewriteImports(template)
+
+  for (const spec of requested) {
+    if (!PLATFORM_SINGLETONS.has(spec)) {
+      throw new Error(
+        `build-client: src/client.js imports "${spec}", which is not a platform singleton; declare it in dsh.client.external and ship it as its own client bundle`,
+      )
+    }
+  }
+
+  return {
+    bundle: wrap(
+      substituteIdentity(qualifyImports(stripExports(body), { namedBindings, defaultBindings })),
+    ),
+    requested,
+  }
+}
+
+/** Compile and write, reporting what changed. @returns whether the file changed. */
+function build() {
+  const { bundle, requested } = compile()
+  let existing
+  try {
+    existing = readFileSync(outputPath, 'utf8')
+  } catch {
+    existing = undefined
+  }
+  if (existing === bundle) {
+    console.log('build-client: lib/client.js already up to date')
+    return false
+  }
+  writeFileSync(outputPath, bundle, 'utf8')
+  console.log(
+    `build-client: wrote lib/client.js (${String(bundle.length)} bytes, requires ${requested.join(', ')})`,
+  )
+  return true
+}
+
+if (process.argv.includes('--check')) {
+  let existing
+  try {
+    existing = readFileSync(outputPath, 'utf8')
+  } catch {
+    console.error('build-client: lib/client.js is missing; run `node scripts/build-client.mjs`')
+    process.exit(1)
+  }
+  if (existing !== compile().bundle) {
+    console.error('build-client: lib/client.js is stale; run `node scripts/build-client.mjs`')
+    process.exit(1)
+  }
+  console.log('build-client: lib/client.js is up to date')
+} else if (process.argv.includes('--watch')) {
+  build()
+  console.log('build-client: watching src/client.js (Ctrl-C to stop)')
+  let timer
+  watch(sourcePath, () => {
+    clearTimeout(timer)
+    timer = setTimeout(() => {
+      try {
+        build()
+      } catch (error) {
+        // Keep watching: a syntax error mid-edit must not kill the watcher.
+        console.error(String(error instanceof Error ? error.message : error))
+      }
+    }, 50)
+  })
+} else {
+  build()
+}