@citisen/dsh-font 0.1.0 → 0.2.0

package/README.md

@@ -3,7 +3,7 @@
 English | [中文](README.zh.md)
 
 Customize the DeepSeek Harness **Web GUI fonts** from Settings: the interface
-font family, the code font family, and three independent size axes.
+and code font stacks (each with its weight) and three independent size axes.
 
 This is a third-party [dsh](https://github.com/deepseek-ai/deepseek-harness)
 profile bundle. It ships as one dual-face package: a Node half that owns a
@@ -16,25 +16,197 @@ are present in the `latest` and `next` release channels.
 
 ## What it adds
 
-A **Fonts** row in *Settings → General*, with five controls:
+A **Fonts** row in *Settings → General*, with five fields: two font queries and
+three size axes.
 
-| Control | Effect | Range |
+| Field | Effect | Value |
 | --- | --- | --- |
-| Interface font | `--dsw-font-family` — all non-code UI text | any CSS `font-family` list |
-| Code font | `--ds-font-family-code` — code blocks, inline code, monospace | any CSS `font-family` list |
+| Interface font | `--dsw-font-family` — all non-code UI text | a font query: families, optionally with a weight |
+| Code font | `--ds-font-family-code` — code blocks, inline code, monospace | a font query |
 | Interface text size | Scales every hard-coded UI text size | 75% – 150%, step 5% |
 | Conversation text size | Message bodies, headings, and tables | 12 – 20 px |
 | Code text size | Code blocks and inline code | 10 – 20 px |
 
-Both family fields accept free text and offer one-click presets. Every value is
-saved through the host settings document (`$DSH_HOME/settings.yaml`,
-namespace `ui-font`), so settings survive a restart and are shared by every
-browser pointed at the same host.
+Both font fields are **editors for a small font-query language**, not plain text
+inputs: the whole stack is one piece of text you edit directly, with syntax
+colouring, soft wrapping, and a completion list built from the fonts actually on
+your machine. The weight is written *in* the query, next to the family it belongs
+to, so changing a font and its weight is one edit in one place:
+
+```
+Geist Mono medium, "Zhuque Fangsong (technical preview)", monospace
+└─────┬────┘ └──┬─┘
+    family    weight
+```
+
+- **Order is the text's order.** The first family the browser can resolve wins,
+  and reordering is an edit: cut and paste it, or put the caret in an entry and
+  press <kbd>Alt</kbd>+<kbd>↑</kbd>/<kbd>↓</kbd>. There are no chips to drag.
+- **The text belongs to you.** Nothing rewrites it: not quoting, not reordering,
+  not tidying, and not refilling an empty box. A new font goes exactly where the
+  caret is, because that is where you typed it — putting one in front of the
+  stack is `Inter, ` typed by hand, or a pick from the completion list at the
+  start of an entry.
+- **The list knows your fonts.** It completes family names, the generic keywords,
+  and — once a family is named — the weights *that family has*, read off its
+  faces. Any name can still be typed by hand; the catalogue is never presented as
+  complete.
+- **The box is always the same monospace.** The painted layer and the real
+  textarea share one box, and a textarea cannot style a substring, so the field
+  uses one fixed system monospace at weight 400 with ligatures and kerning turned
+  off — whatever font the query names. A face with ligatures (`->` in Fira Code)
+  would draw one glyph in the layer and two in the field, and a synthesized
+  weight would differ between them. The readout line under the field is rendered
+  in the axis's own font, so the family you picked is still visible there.
+- **Enter applies, it never completes.** The query is parsed and written on
+  <kbd>Enter</kbd> or when you leave the field; <kbd>Tab</kbd> (or a click) takes
+  the highlighted completion, which is the one case where the text is replaced —
+  because that is what picking a suggestion means.
+- **A wrong query is marked, not fixed.** A family this machine does not have, a
+  weight the family lacks, an unclosed quote, a stray word: each is reported
+  under the field, in warning or error colour, and the text is left as typed. An
+  empty box writes nothing at all and says so — the saved stack stays in use, and
+  *Reset to defaults* is how you go back to the shipped one.
+
+Every value is saved through the host settings document
+(`$DSH_HOME/settings.yaml`, namespace `ui-font`), so settings survive a restart
+and are shared by every browser pointed at the same host.
 
 The *Interface text size* and *Conversation text size* axes are independent on
 purpose: bumping the interface makes the surrounding chrome easier to read
 without changing how much message text fits on screen, and vice versa.
 
+### Choosing a weight: `Geist Mono medium`
+
+CSS cannot put a weight in a `font-family` — `font-family: "Geist Mono" 500,
+monospace` is simply an invalid declaration, and the whole stack would be
+dropped. The query language therefore writes the weight as a word beside the
+family, and the plugin reads the pair back into the two declarations that
+actually apply:
+
+```
+Geist Mono medium, monospace   →   font-family: "Geist Mono", monospace
+                               →   font-weight: 500
+```
+
+`Thin`, `ExtraLight`, `Light`, `Book`, `Regular`, `Medium`, `SemiBold`, `Bold`,
+`ExtraBold`, `Black` and their usual aliases (`Hairline`, `DemiBold`,
+`UltraBold`, …) are all recognized, case-insensitively. The weight belongs to the
+axis rather than to one family, so it is honoured wherever it is written and
+counted once; the canonical form puts it after the first family — the one in
+effect.
+
+The **shipped weight is implicit**: an axis at its factory 400 carries no word at
+all, because a `regular` that appears after every family is noise nobody asked
+for — and for the interface axis 400 literally means "no override". A word
+appears exactly when a weight is chosen, and deleting it returns the axis to 400.
+What the axis currently stands at is always stated in the line under the field
+(`Interface weight: Regular 400 (shipped, not overridden)`), so nothing is hidden
+by leaving the word out.
+
+The weight is a closed list rather than a free number, because a `font-weight`
+the chosen family does not have is *synthesized* by the browser, and offering
+faux-bold as a normal choice is worse than not offering it. When the faces could
+be read — the Local Font Access API reports them — the popup offers *that*
+family's weights, and a weight the family lacks is called out below the field:
+
+> Geist Mono has no 700 face on this machine (bold), so the browser will
+> synthesize it
+
+Deleting the word does not quietly reset anything: the axis keeps the weight it
+was set to, the line under the field states it, and the word comes back the next
+time the row is built from the stored values. To go back to the shipped weight,
+pick its row from the list (`Regular 400`) — a pick is an instruction, so it sets
+the value even though its text is just the family name.
+
+One deliberate escape hatch: if what you type is itself a family on your machine,
+the trailing word is read as part of the name. `Book Antiqua` and
+`Franklin Gothic Medium` are real families, and applying a weight to them instead
+of picking them would be silent misbehaviour. The price is that a name which is
+genuinely both — a family literally called `Geist Mono Medium` — is also read as
+a name. The catalogue decides, so the judgement uses the same font list the
+completion list shows you. Quoting is the way out: `"Book Antiqua"` always means
+the name, verbatim.
+
+### The interface weight is opt-in
+
+The code surface has no weight hierarchy to preserve, so its weight is simply the
+one written in the query. The interface does have one: headings are 700, table
+heads 500, body 400. Setting an interface weight therefore moves the base and
+carries the heading steps with it, keeping each step's shipped distance from 400
+instead of flattening them:
+
+```css
+/* --dsh-font-ui-weight: 500 */
+html body { font-weight: 500 }
+--dsh-font-markdown-base: 500 …          /* body text */
+--dsh-font-markdown-h1: 800 …            /* 700 + (500 - 400) */
+--dsh-font-markdown-table-head: 600 …    /* 500 + (500 - 400) */
+```
+
+Text that *inherits* its weight moves; a label or a button whose weight the
+design system fixes keeps it, because its own rule still wins. And the shipped
+400 emits **no rule at all**, so an untouched install paints exactly what the
+design system paints.
+
+### The query language
+
+```
+query  := entry ("," entry)*
+entry  := family | weight
+family := '"' … '"' | "'" … "'" | word (space word)*
+weight := thin | extralight | light | book | regular | roman | medium |
+          demibold | semibold | bold | extrabold | black | heavy | …
+```
+
+The grammar is the CSS `font-family` list plus the one thing the list cannot
+carry. Only the LAST word of an unquoted entry may be a weight, and only when the
+whole entry is not itself a catalogued family. A bare weight word (`medium`) sets
+the axis weight without naming a family. Commas inside quotes are not separators,
+so `"Foo, Bar"` is one family.
+
+The reader is forgiving on purpose — this text is typed by hand, not generated —
+so anything it cannot place is kept as written and reported under the field
+instead of being dropped: an unclosed quote, a stray word after a quoted name, a
+weight written twice, a family the machine does not list, a weight the family has
+no face for. The field also names the family that is in effect, which is the
+first one the browser can actually resolve.
+
+### How the font list is discovered
+
+Order matters in a CSS font stack — the first installed family wins — so the
+editor is built around the text rather than around a picker.
+
+Reading the real installed-font list needs the
+[Local Font Access API](https://developer.mozilla.org/en-US/docs/Web/API/Local_Font_Access_API)
+(`queryLocalFonts`), which is **Chromium-only, experimental, and
+permission-gated**; MDN also notes browsers are not obliged to return the
+complete list. So the catalogue is layered:
+
+1. **`queryLocalFonts()`** when the browser offers it — the machine's own list,
+   which needs no badge to explain itself. Its per-face `style` names (`Regular`,
+   `SemiBold`, `Bold Italic`) are kept alongside the families, which is what lets
+   the completion list offer a family's real weights and warn about one it lacks.
+   The first use shows a permission prompt; declining falls back silently rather
+   than erroring.
+2. **Measurement probing** everywhere else — each candidate family is rendered
+   off-screen and compared against a `monospace` baseline; a different width or
+   height means it is installed. No permission needed, works in every browser.
+   It only sees the curated probe list, so it under-reports by design and can say
+   nothing about weights — which is the one case worth calling out, so the row
+   then says so once, above the fields, and adds that any family can still be
+   typed.
+3. **Always** the curated catalogue plus the generic families, so a font that
+   neither source found can still be typed.
+
+The result is cached for the session, and discovery only runs when the row is
+actually rendered — never at startup.
+
+The editor also warns when a query has **no generic family at the end** (such as
+`sans-serif`), because a missing font then falls back unpredictably. Quoting is
+automatic: `Fira Code` is stored as `"Fira Code"`, and generic keywords are
+deliberately left unquoted, so `"sans-serif"` can never be written by accident.
+
 ## Install
 
 ```sh
@@ -162,10 +334,56 @@ theme change; the plugin re-asserts its own on every settings change. The row's
 help text tells the user this control wins over the *Font size* row in
 Appearance.
 
+### Where the code weight is written
+
+The design system has **no** weight token at all — every `font:` declaration in
+the interface is a literal, and the code ladder is literally `400`. So the
+weight cannot ride the family token the way a family does, and it is applied on
+two levels:
+
+```css
+/* the three code tokens carry it in their font: shorthand … */
+--dsw-font-markdown-code: var(--dsh-font-code-weight,400) var(--dsh-font-code-size,12px) / … ;
+
+/* … and everything styled directly with the code family is matched structurally */
+html body pre, html body code, html body [class*="code" i] {
+  font-family: var(--ds-font-family-code) !important;
+  font-weight: var(--dsh-font-code-weight,400) !important;
+}
+```
+
+The second rule exists because most code in the interface never reads a token:
+the tool I/O cards and the terminal output are styled with `font-family:
+var(--ds-font-family-code)` and their own literal weight inside a component
+stylesheet, so there is nothing to override but the element. The `!important` is
+what outranks `font: 500 12px/18px …`. It is deliberately **not** a universal
+rule: the surrounding labels keep the shipped hierarchy.
+
+### Where the interface weight is written
+
+The interface weight is opt-in, so the shipped `400` emits no rule at all and an
+untouched install paints exactly what the design system paints. Anything else is
+written on two levels:
+
+```css
+/* text that inherits its weight moves as a whole … */
+html body { font-weight: 500 }
+
+/* … while the Markdown ladder the plugin already owns is shifted by the same
+   distance from the shipped 400, so headings keep their contrast */
+--dsh-font-markdown-base: 500 …
+--dsh-font-markdown-h1: 800 …            /* 700 + (500 - 400) */
+--dsh-font-markdown-table-head: 600 …    /* 500 + (500 - 400) */
+```
+
+The ladder has to name the weight explicitly: a `font:` shorthand with no weight
+component resets `font-weight` to `normal`, so `html body` alone would be
+cancelled by the plugin's own tokens.
+
 ### Pre-paint
 
 The Node half answers `webserver/index-inject` with an inline `<script>` that
-installs the stylesheet and sets the two family variables before the shell
+installs the stylesheet and sets the family and weight variables before the shell
 mounts, so the first frame is already in the user's fonts. It reads the same
 `ui-font` settings section at render time, and falls back to the schema defaults
 when the settings provider is absent.
@@ -174,9 +392,10 @@ when the settings provider is absent.
 
 ```sh
 npm run build     # src/client.js -> lib/client.js
-npm run check     # fail if lib/client.js is stale
-node scripts/verify-host.mjs     # host half: schema, bootstrap, injection row
-node scripts/verify-client.mjs   # client half: envelope, sheet, stamping, row
+npm run check     # the release gate: bundle in sync, host and client verified
+npm run check:all # adds the profile-composition check (needs a local dsh)
+npm run verify    # just the host and client verifiers
+npm run watch     # rebuild on save, for dsh-client-hmr
 ```
 
 `src/client.js` is the single source of truth for the browser half. It is
@@ -194,6 +413,10 @@ its module table (`react`, `react/jsx-runtime`, `react-dom`,
 `@deepseek-ai/dsh-client-ui-dockkit`); anything else must be declared in
 `dsh.client.external` and shipped as its own graph row. The build enforces this.
 
+`verify-profile.mjs` needs a dsh installation and an initialized profile, so it
+**skips** (exit 0) when neither is present — a clean CI runner has no dsh. Set
+`DSH_REQUIRE=1` to turn that skip into a failure.
+
 To iterate on the browser half against a running host, run the watcher and let
 `dsh-client-hmr` swap the plugin in — it stat-polls client bundles every 500 ms,
 so a saved rebuild reaches the open page without a refresh:
@@ -209,15 +432,26 @@ dsh --profile web
 A page refresh always picks up a newly composed graph, so the watcher is a
 convenience rather than a requirement.
 
+### Releasing
+
+Releases are staged by GitHub Actions over npm trusted publishing and then
+approved by a maintainer, so no `NPM_TOKEN` exists in this repository and none
+should ever be added. [RELEASING.md](RELEASING.md) is the step-by-step runbook;
+[PUBLISHING.md](PUBLISHING.md) covers the one-time npm setup and what the
+arrangement does and does not protect against.
+
 ## Package layout
 
 | Path | Role |
 | --- | --- |
 | `lib/index.js` | Host half: settings namespace, pre-paint injection. Loaded by the loader. |
-| `lib/client.js` | Browser half, **generated** from `src/client.js`. Served at `/plugins/dsh-font/client.js`. |
+| `lib/client.js` | Browser half, **generated** from `src/client.js`. Served at `/plugins/@citisen/dsh-font/client.js`. |
 | `src/client.js` | Browser-half source. |
 | `cordis.patch.yml` | The profile layer this bundle contributes. |
 | `scripts/` | Build and verification scripts. |
+| `.github/workflows/stage.yml` | The CI half of the only publishing path. |
+| `PUBLISHING.md` | Trusted-publishing setup, and what it does not protect against. |
+| `RELEASING.md` | The runbook for shipping a change. |
 | `package.json` | Declares `dsh.bundle` (profile layer) and `dsh.client` (browser roster entry). |
 
 ## Known limitations
@@ -234,6 +468,32 @@ convenience rather than a requirement.
 - **Per-element stamping is proportional to the DOM.** The scale pass measures
   each element once and caches the result, and re-stamps on mutation, so it is
   bounded — but it is not free on a very large transcript.
+- **The code weight is not a per-surface choice.** It applies to every code
+  surface at once, and where it lands on `pre`, `code`, and any element with
+  `code` in its class name — so a `font-weight` a component sets inside a code
+  block (syntax highlighting, a bold diff line) is overridden too. The interface
+  weight is the mirror image: only text that *inherits* its weight moves, and a
+  label or button whose weight the design system fixes keeps it. A weight the
+  family lacks is still synthesized by the browser; the closed list and the
+  "no such face on this machine" warning only keep it out of reach.
+- **The query language is a convention, not CSS.** It lives only in this row's
+  two font fields; what is stored is still a valid CSS `font-family` list plus a
+  numeric `font-weight`, so disabling the plugin leaves nothing behind. Whether a
+  trailing word is a weight or part of the name is decided by the loaded
+  catalogue, so a family whose real name ends in a weight word (`Book Antiqua`,
+  `Franklin Gothic Medium`) is left intact only when that exact name was
+  discovered — both are curated, so this normally holds, but a name outside the
+  probe list can be split when the Local Font Access prompt is declined. Quoting
+  settles it: `"Book Antiqua"` is always the name.
+- **The heading shift is one formula, not a redesign.** Each step becomes
+  `shipped + (interface weight - 400)`, clamped at 900 — so an interface weight
+  of 900 flattens the ladder against that ceiling.
+- **The box is not a copy of the setting.** What is stored is the plugin's
+  serialization of the query (quoted, weight word after the first family); what
+  the box shows is your text, kept verbatim for as long as the row lives. A
+  reload rebuilds the box from the two stored values, so a weight word you
+  deleted can reappear there, and it may be spelled differently from what you
+  typed.
 - **The settings row is English/Chinese only**, matching the shipped locale pair.
 
 ## License

package/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-在设置里自定义 DeepSeek Harness **Web 界面字体**：界面字体、代码字体，以及三条互相独立的字号轴。
+在设置里自定义 DeepSeek Harness **Web 界面字体**：界面字体与代码字体两条字体栈（各带自己的字重），以及三条互相独立的字号轴。
 
 这是一个第三方 [dsh](https://github.com/deepseek-ai/deepseek-harness) profile bundle（插件包）。它是一个「双面」包：Node 半边负责持久化的设置命名空间与首屏绘制前的样式注入，浏览器半边负责实际绘制并注册设置项。
 
@@ -10,20 +10,84 @@
 
 ## 功能
 
-在 *设置 → 通用* 中新增一个 **字体** 行，包含五个控件：
+在 *设置 → 通用* 中新增一个 **字体** 行，包含五项：两个字体查询加三条字号轴。
 
-| 控件 | 作用 | 范围 |
+| 字段 | 作用 | 取值 |
 | --- | --- | --- |
-| 界面字体 | `--dsw-font-family`，所有非代码的界面文字 | 任意 CSS `font-family` 列表 |
-| 代码字体 | `--ds-font-family-code`，代码块、行内代码、等宽文本 | 任意 CSS `font-family` 列表 |
+| 界面字体 | `--dsw-font-family`，所有非代码的界面文字 | 字体查询：字体族，可带字重 |
+| 代码字体 | `--ds-font-family-code`，代码块、行内代码、等宽文本 | 字体查询 |
 | 界面字号 | 按比例缩放所有写死的界面文字尺寸 | 75% – 150%，步进 5% |
 | 会话正文字号 | 消息正文、标题与表格 | 12 – 20 px |
 | 代码字号 | 代码块与行内代码 | 10 – 20 px |
 
-两个字体输入框都支持自由填写，并提供一键预设。所有取值都通过宿主设置文档持久化（`$DSH_HOME/settings.yaml`，命名空间 `ui-font`），因此重启后依然生效，并且对指向同一台宿主的所有浏览器共享。
+两个字体框都是**一门小型字体查询语言的编辑器**，而不是普通输入框：整条字体栈就是一段可以逐字编辑的文本，带语法高亮、自动换行，以及一份来自本机实际字体的补全列表。字重写在查询**里面**、紧挨着它所属的字体族，所以换字体和换字重是同一处的同一次编辑：
+
+```
+Geist Mono medium, "Zhuque Fangsong (technical preview)", monospace
+└─────┬────┘ └──┬─┘
+    字体族      字重
+```
+
+- **顺序就是文本的顺序。** 浏览器能解析到的第一个字体族生效，排序靠编辑文本完成：剪切粘贴，或把光标放进某个词条按 <kbd>Alt</kbd>+<kbd>↑</kbd>/<kbd>↓</kbd>。没有需要拖动的胶囊了。
+- **这段文字归你。** 插件不会改写它：不加引号、不重排、不整理，也不会把清空的框重新填满。新字体就落在光标处——因为你是在那里打的字；把某个字体放到最前面，要么自己敲 `Inter, `，要么在词条开头从补全列表里选。
+- **列表认识你机器上的字体。** 它补全字体族、通用族，以及某个字体族**实际拥有**的字重（从它的字面读取）。本机字体读取不可用或被拒绝时，会退回"探测到的常用字体"名单，并在行上方说明一次；任何名字始终可以手写，目录从不自称完整。
+- **输入框永远是同一个等宽字体。** 高亮层和真正的 textarea 共用一个盒子，而 textarea 没法给不同的字符串设不同字体，所以这个框统一使用一套系统等宽字体、字重固定 400、并关闭连字与字距调整——无论查询里写的是什么字体。带连字的字体（Fira Code 的 `->`）会在高亮层画成一个字形、在输入框里画成两个，合成字重也会两边不一致。框下那行读数用的是这条轴自己的字体，所以你选的字体在那里仍然看得见。
+- **Enter 只负责应用，从不替你补全。** 查询在 <kbd>Enter</kbd> 或离开输入框时解析并写入；<kbd>Tab</kbd>（或点击）才会接受高亮的那条补全——那是唯一会替换文本的情况，因为"选中一条建议"本身就是这个意思。
+- **写错只标出来，不改。** 本机没有的字体族、字体族没有的字面、没闭合的引号、多出来的词，都会在框下分别以警告色或错误色标出，文本保持你写的样子。空输入框**什么都不写**并说明这一点：已保存的字体栈仍在生效，要回到出厂值按「恢复默认」。
+
+所有取值都通过宿主设置文档持久化（`$DSH_HOME/settings.yaml`，命名空间 `ui-font`），因此重启后依然生效，并且对指向同一台宿主的所有浏览器共享。
 
 *界面字号* 与 *会话正文字号* 刻意设计成两条独立的轴：放大界面可以让周围的控件更好读，而不改变屏幕上能显示多少正文；反过来也一样。
 
+### 如何选字重：`Geist Mono medium`
+
+CSS 没法把字重写进 `font-family` —— `font-family: "Geist Mono" 500, monospace` 本身就是非法声明，整条字体栈会被丢弃。所以这门查询语言把字重写成一个词，紧跟在它所属的字体族后面，插件再把这一对还原成真正生效的两条声明：
+
+```
+Geist Mono medium, monospace   →   font-family: "Geist Mono", monospace
+                               →   font-weight: 500
+```
+
+`Thin`、`ExtraLight`、`Light`、`Book`、`Regular`、`Medium`、`SemiBold`、`Bold`、`ExtraBold`、`Black` 以及常见别名（`Hairline`、`DemiBold`、`UltraBold` 等）都能识别，大小写不敏感。字重属于整条轴而不是某一个字体族，所以写在哪里都算数，但只算一次；规范形式把它写在第一个字体族（也就是生效的那个）后面。
+
+**出厂字重是隐含的**：某条轴停在出厂的 400 时，文本里不会出现任何字重词——每个字体族后面都跟一个 `regular` 是谁也没要求的噪音，而对界面轴来说 400 本来就等于"不做覆盖"。只有真正选了字重，这个词才会出现；把它删掉就回到 400。这条轴当前到底是多少，永远写在输入框下面那一行（`界面字重: 常规 400（出厂值，未覆盖）`），所以省掉那个词并没有藏起任何信息。
+
+字重是一个封闭列表而不是任意数字：所选字体族没有的字重会被浏览器**合成**（伪粗体），把伪粗体当成正常选项提供，比不提供更糟。在能读到字面的机器上（Local Font Access API 会报告每个字面），补全列表只给**这个字体族真正拥有**的字重，缺哪个会在框下点出来：
+
+> Geist Mono 在本机没有 700 这个字面（bold），浏览器会合成
+
+把字重词删掉不会悄悄重置任何东西：这条轴保持它被设成的值，输入框下面那行会写出来；等下次行组件按存储值重建时，那个词也会回来。要回到出厂字重，从列表里选它那一档（`常规 400`）——选中是一条指令，所以即使它的文本只是字体族名，也会把值设成 400。
+
+有一处刻意的例外：如果你输入的内容本身就是本机上的字体族，末尾那个词会被当成名字的一部分。`Book Antiqua`、`Franklin Gothic Medium` 都是真实存在的字体族，把它们当成"字体族 + 字重"处理会静默改错。代价是：真正两者皆是的名字（真有一个字体族叫 `Geist Mono Medium`）也会被当作名字。判断依据就是补全列表给出的那份字体目录。想明确表达"这就是名字"，加引号即可：`"Book Antiqua"` 永远是名字本身。
+
+### 界面字重是可选覆盖
+
+代码区域没有需要保留的字重层级，所以它的字重就是查询里写的那个数。界面有：标题 700、表头 500、正文 400。因此设置界面字重时，基准值会带着标题阶梯一起移动，每一级保持它与 400 的出厂间距，而不是被压平：
+
+```css
+/* --dsh-font-ui-weight: 500 */
+html body { font-weight: 500 }
+--dsh-font-markdown-base: 500 …          /* 正文 */
+--dsh-font-markdown-h1: 800 …            /* 700 + (500 - 400) */
+--dsh-font-markdown-table-head: 600 …    /* 500 + (500 - 400) */
+```
+
+会跟着变的是**继承**字重的那部分文字；设计系统自己写死字重的标签、按钮不受影响，因为它们自己的规则仍然胜出。而出厂的 400 **不产生任何规则**，所以未改动的安装画出来的就是设计系统原本的样子。
+
+### 这门查询语言
+
+```
+query  := entry ("," entry)*
+entry  := family | weight
+family := '"' … '"' | "'" … "'" | word (space word)*
+weight := thin | extralight | light | book | regular | roman | medium |
+          demibold | semibold | bold | extrabold | black | heavy | …
+```
+
+语法就是 CSS `font-family` 列表，加上列表本身装不下的那一样东西。只有**未加引号**词条的**最后一个**词可能是字重，而且整个词条本身不是已收录的字体族时才成立。单独一个 `medium` 也表示"只设字重、不改字体族"。引号里的逗号不是分隔符，所以 `"Foo, Bar"` 是一个字体族。
+
+解析器刻意宽容——这段文字是人手敲的，不是生成的——凡是放不下的东西都按原样保留并在框下报告，而不是悄悄丢掉：没闭合的引号、引号后面多出来的词、写了两次的字重、本机目录里没有的字体族、这个字体族没有的字面。框下同时会写出当前**生效**的字体族，也就是浏览器真正能用上的第一个。
+
 ## 安装
 
 ```sh
@@ -112,15 +176,49 @@ document.body.style.setProperty('--dsh-content-font-size', `${contentSize}px`)
 
 样式表随后以这个值为基准，用绝对 px 重新推导整条 Markdown 字号阶梯。变量仍然归 `ui-theme` 所有，它每次主题变化仍会写自己的值；插件在每次设置变化时重新写入自己的值。设置项的说明文字会告诉用户：这里的取值会盖过「外观」里的「字号大小」。
 
+### 代码字重写在哪里
+
+设计系统里**完全没有**字重 token——界面上每一处 `font:` 都是字面量，代码那条阶梯写死就是 `400`。所以字重没法像字体族那样搭在字体 token 上，它分两层生效：
+
+```css
+/* 三个代码 token 在各自的 font: 简写里带上它…… */
+--dsw-font-markdown-code: var(--dsh-font-code-weight,400) var(--dsh-font-code-size,12px) / … ;
+
+/* ……而直接用代码字体族写死的地方，按结构匹配 */
+html body pre, html body code, html body [class*="code" i] {
+  font-family: var(--ds-font-family-code) !important;
+  font-weight: var(--dsh-font-code-weight,400) !important;
+}
+```
+
+第二条规则的存在，是因为界面上大多数代码根本不读 token：工具 I/O 卡片和终端输出是在组件样式表里用 `font-family: var(--ds-font-family-code)` 加上自己的字面量字重写死的，除了覆盖元素本身没有别的地方可改。`!important` 正是为了压过 `font: 500 12px/18px …`。这条规则刻意**不是**通配规则：周围标签仍保留出厂的字重层级。
+
+### 界面字重写在哪里
+
+界面字重是**可选**的：出厂值 400 不产生任何规则，所以未改动的安装画出来的就是设计系统原本的样子。设成别的值时，插件做两件事：
+
+```css
+/* 会继承字重的界面文字整体移动…… */
+html body { font-weight: 500 }
+
+/* ……而插件自己已经接管的那条 Markdown 阶梯按出厂的相对差值整体平移 */
+--dsh-font-markdown-base: 500 …
+--dsh-font-markdown-h1: 800 …
+--dsh-font-markdown-table-head: 600 …
+```
+
+第二条必须显式写出字重，因为 `font:` 简写里不带字重分量时会把 `font-weight` 重置成 `normal`——只写 `html body` 会被这条简写悄悄抵消。平移而不是压平，是为了让标题相对正文的粗细关系保持出厂的距离。
+
 ### 首屏绘制前
 
-Node 半边响应 `webserver/index-inject`，注入一段内联 `<script>`，在 shell 挂载之前就装好样式表并设好两个字体变量，因此第一帧就已经是用户的字体。它在渲染时读取同一个 `ui-font` 设置段；当设置服务缺失时回退到 schema 默认值。
+Node 半边响应 `webserver/index-inject`，注入一段内联 `<script>`，在 shell 挂载之前就装好样式表并设好字体族与字重变量，因此第一帧就已经是用户的字体。它在渲染时读取同一个 `ui-font` 设置段；当设置服务缺失时回退到 schema 默认值。
 
 ## 开发
 
 ```sh
 npm run build     # src/client.js -> lib/client.js
-npm run check     # 检查 lib/client.js 是否过期，并跑两个校验脚本
+npm run check     # 发布闸门：产物同步 + host/client 校验
+npm run check:all # 再加上 profile 组合校验（需要本机有 dsh）
 npm run verify    # 只跑校验脚本
 npm run watch     # 保存即重建，配合 dsh-client-hmr
 ```
@@ -129,6 +227,8 @@ npm run watch     # 保存即重建，配合 dsh-client-hmr
 
 浏览器半边只允许请求 shell 注入模块表的那九个模块（`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`）；其它模块必须写进 `dsh.client.external` 并作为独立的图节点发布。构建会强制检查这一点。
 
+`verify-profile.mjs` 需要本机有 dsh 安装和已初始化的 profile，所以在两者都不存在时会**跳过**（exit 0）——干净的 CI runner 上没有 dsh。设 `DSH_REQUIRE=1` 可以把「跳过」变成失败。
+
 要在运行中的宿主上迭代浏览器半边，开一个 watcher，让 `dsh-client-hmr` 热替换插件——它每 500 ms 轮询一次客户端 bundle，因此保存后的重建无需刷新页面即可生效：
 
 ```sh
@@ -141,15 +241,22 @@ dsh --profile web
 
 刷新页面总能拿到新组合的图，所以 watcher 只是便利，不是必需。
 
+### 发布
+
+发布先由 GitHub Actions 通过 npm trusted publishing 完成**暂存（stage）**，再由维护者审批，因此本仓库里没有 `NPM_TOKEN`，也不应该出现。逐步流程见 [RELEASING.md](RELEASING.md)；一次性配置以及这套机制防不住什么见 [PUBLISHING.md](PUBLISHING.md)。
+
 ## 包结构
 
 | 路径 | 作用 |
 | --- | --- |
 | `lib/index.js` | Node 半边：设置命名空间、首屏绘制前的注入。由 loader 加载。 |
-| `lib/client.js` | 浏览器半边，**由 `src/client.js` 生成**。由 `/plugins/dsh-font/client.js` 提供。 |
+| `lib/client.js` | 浏览器半边，**由 `src/client.js` 生成**。由 `/plugins/@citisen/dsh-font/client.js` 提供。 |
 | `src/client.js` | 浏览器半边源码。 |
 | `cordis.patch.yml` | 本 bundle 贡献的 profile 层。 |
 | `scripts/` | 构建与校验脚本。 |
+| `.github/workflows/stage.yml` | 唯一发布路径的 CI 半边。 |
+| `PUBLISHING.md` | trusted publishing 一次性配置，以及这套机制防不住什么。 |
+| `RELEASING.md` | 改完代码之后怎么发布的完整流程。 |
 | `package.json` | 声明 `dsh.bundle`（profile 层）与 `dsh.client`（浏览器节点）。 |
 
 ## 已知限制
@@ -158,6 +265,10 @@ dsh --profile web
 - **正文字号会盖过 `ui-theme` 的字号设置项。** 两者都写 `--dsh-content-font-size`，后写者生效，而本插件在设置变化时总会写。请只用其中一个。
 - **字体不会被安装。** 只有浏览器或操作系统能解析到的字体名才会生效；插件不打包也不下载 webfont，因此写错名字只会静默回退到列表末尾的通用字体。
 - **逐元素盖章的开销与 DOM 规模成正比。** 缩放扫描对每个元素只测量一次并缓存结果，之后按 DOM 变化增量盖章，因此开销有界——但在超长会话里并非免费。
+- **代码字重不能按区域分别设置。** 它一次作用于所有代码区域，覆盖范围是 `pre`、`code` 以及类名里带 `code` 的元素——因此组件自己在代码块里设的字重（语法高亮、加粗的 diff 行）同样会被覆盖。界面字重同理，只是范围相反：只有会继承字重的那部分界面文字跟着变，设计系统写死字重的标签、按钮保持原样。字体族没有的字重浏览器仍会合成，封闭列表和"本机没有这个字面"的提示只是把它挡在选择之外。
+- **查询语言是本插件自己的约定，不是 CSS。** 它只存在于这一行的两个字体框里，存储的仍然是合法的 CSS `font-family` 列表加上一个 `font-weight` 数字，所以关掉插件不会有残留。末尾的词算字重还是算名字的一部分，由已加载的字体目录决定，所以本身就以字重词结尾的真实字体族（`Book Antiqua`、`Franklin Gothic Medium`）只有在目录里确实列出了这一整名时才会保持原样——这两个词都在探测列表里，因此正常都能保住；而列表之外的同类名字在拒绝字体权限提示时可能被拆开，用引号可以明确表达"这是名字"。
+- **界面字重的平移是固定公式，不是重新设计。** 标题按"出厂字重 +（界面字重 − 400）"平移并封顶在 900，所以界面字重设到 900 时所有阶梯都会撞到同一个上限。
+- **输入框不等于设置值。** 存储的是插件对查询的序列化结果（加了引号、字重词落在生效字体族后面）；框里显示的是你的文本，只要这一行还在就原样保留。重新加载页面时会用两个存储值重建输入框，所以你删掉的字重词可能又出现，拼写也可能和你写的不一样。
 - **设置项只有中英两种文案**，与官方内置的语言对一致。
 
 ## 许可证