dsh-diff-approval 0.27.0 → 0.29.0

package/README.md

@@ -92,4 +92,8 @@ corepack pnpm install
 pnpm run typecheck   # tsc over both faces
 pnpm run build       # emits lib/index.js and lib/client.js
 pnpm test
+pnpm run fonts:check # the bundled code font: 138 slices, every range covered exactly once
+pnpm run fonts:plan  # what a page actually downloads, by how many hanzi it shows
 ```
+
+The bundled font is [JetBrains Maple Mono](https://github.com/SpaceTimee/Fusion-JetBrainsMapleMono) (SIL OFL 1.1), subset and sliced by `scripts/fonts` — see [`assets/fonts/README.md`](assets/fonts/README.md) for the pipeline, the licence and what the slices cost.

package/README.zh.md

@@ -92,4 +92,8 @@ corepack pnpm install
 pnpm run typecheck   # 两个编译面的 tsc
 pnpm run build       # 产出 lib/index.js 与 lib/client.js
 pnpm test
+pnpm run fonts:check # 内置代码字体：138 个切片，每个码位恰好被覆盖一次
+pnpm run fonts:plan  # 页面上出现多少汉字时实际会下载多少
 ```
+
+内置字体是 [JetBrains Maple Mono](https://github.com/SpaceTimee/Fusion-JetBrainsMapleMono)（SIL OFL 1.1），由 `scripts/fonts` 子集化并切片——流水线、许可证与各切片的体积见 [`assets/fonts/README.md`](assets/fonts/README.md)。

package/assets/fonts/FONTLOG.md

@@ -0,0 +1,55 @@
+# FONTLOG
+
+What the bundled font is, where it came from, and what was done to it. The
+licence text is in `OFL.txt` next to this file; the machine-readable record of
+the exact upstream build and every slice is in `manifest.json`.
+
+## Upstream
+
+- **JetBrains Maple Mono 1.2304.79** — <https://github.com/SpaceTimee/Fusion-JetBrainsMapleMono>
+  - archive `JetBrainsMapleMono-XX-XX-XX-XX.zip`, sha256
+    `1998cf7047be954c781510d5a651e9d57fadb2ee00bebd80a0719d49eaa50513`
+  - the plain build: no Nerd Font icons (`XX`), no narrowed CJK (`XX` — that
+    variant is documented as breaking the 2:1 ratio), no hinting (`XX`)
+  - itself a fusion of **JetBrains Mono 2.304** (all non-CJK outlines) and
+    **Maple Mono 7.9** (the CJK outlines), assembled by FontForge
+  - CJK designs ultimately from Resource Han Rounded and Source Han Sans
+- Licence of everything above: **SIL Open Font License 1.1**, with no Reserved
+  Font Name declared by any of the three copyright holders. `OFL.txt` carries
+  JetBrains Mono (2020), Maple Mono (2022) and Space Time (2025) notices.
+
+## What this repository does to it
+
+A **modification** in OFL terms, and therefore recorded here:
+
+1. **Renamed** to `JetBrains Maple Mono for DSH` (the family the CSS declares).
+   The name says which face it is; the `for DSH` marker keeps it from colliding
+   with a copy of the upstream font the reader may have installed — a locally
+   installed font wins over a webfont of the same name, which would leave these
+   slices unused and render someone else's build. It also keeps the upstream
+   names out of a user-visible primary name, which is what the OFL asks of a
+   modified version (Maple Mono declares `Maple Mono` as a Reserved Font Name).
+2. **Subset** to the characters a code diff can render: Latin and Latin-1,
+   Latin Extended-A, general punctuation, arrows, box drawing, geometric shapes
+   and dingbats, CJK punctuation and fullwidth forms, and the 20,992 hanzi of
+   U+4E00-9FFF. Uncovered on purpose: Korean, CJK Ext-A/B, compatibility
+   ideographs — those fall back to the system stack.
+3. **Sliced** into woff2 files by frequency, so a page fetches the few hundred
+   kilobytes it needs instead of the whole block. The order is frozen in
+   `ranked-hanzi.txt`; the rule is in `scripts/fonts/build.py`.
+4. **Converted** to woff2 and stripped of hinting (`--no-hinting`), keeping every
+   OpenType feature (`--layout-features='*'`).
+
+Both weights are cut from the same slices: Regular for code, SemiBold for
+emphasis, matching `font-weight: 400` and `600`.
+
+## Reproducing
+
+```bash
+python -m scripts.fonts.build --download --extract
+python -m scripts.fonts.build
+python -m scripts.fonts.build --check
+```
+
+`--download` verifies the sha256 above before unpacking, so the slices cannot
+silently come from a different build of the font.

package/assets/fonts/OFL.txt

@@ -0,0 +1,95 @@
+Copyright 2020 The JetBrains Mono Project Authors (https://github.com/JetBrains/JetBrainsMono)
+Copyright 2022 The Maple Mono Project Authors (https://github.com/subframe7536/maple-font)
+Copyright 2025 Space Time (https://github.com/SpaceTimee/Fusion-JetBrainsMapleMono)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+https://openfontlicense.org
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded,
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/assets/fonts/README.md

@@ -0,0 +1,123 @@
+# The bundled code font
+
+The panel renders code and Chinese comments on one character grid, which needs a
+font where one CJK glyph is exactly twice one Latin glyph. No system stack does
+that on Windows or Android: the shell's own code font is
+`"SF Mono", "JetBrains Mono", …, "PingFang SC", "Microsoft YaHei"`, so Latin
+comes from a monospace face and hanzi from a proportional one, and every
+Chinese comment drifts out of column.
+
+So the font ships with the plugin. It is
+[JetBrains Maple Mono](https://github.com/SpaceTimee/Fusion-JetBrainsMapleMono)
+(JetBrains Mono for Latin, Maple Mono for CJK, fused upstream so the 2:1 ratio
+holds by construction), subset into sliced woff2 files and served by the host.
+
+## What is committed
+
+| path | what it is |
+| --- | --- |
+| `ranked-hanzi.txt` | the 20,992 hanzi of U+4E00-9FFF in frequency order — the input the slice plan is built on |
+| `regular-*.woff2`, `semibold-*.woff2` | the slices themselves (`regular-latin.woff2`, `regular-hanzi-000.woff2`, …) |
+| `manifest.json` | every slice's `unicode-range`, byte size, weight, and the pinned upstream archive |
+| `OFL.txt` | the font's licence, which must travel with it |
+
+The full TTFs and the upstream archive are **not** committed: they are 17 MB and
+141 MB, they are reproducible from the pinned URL and checksum in
+`manifest.json`, and `scripts/fonts/build.py` fetches them into `vendor/`
+(git-ignored) on demand. Keeping the whole font locally is still the point of
+that cache — re-slicing must never require a network round trip, and after one
+`--download` it does not.
+
+## Rebuilding
+
+```bash
+python -m pip install fonttools brotli wordfreq jieba
+python -m scripts.fonts.build --download --extract   # once: fills assets/fonts/vendor
+python -m scripts.fonts.build                        # writes the slices + manifest
+python -m scripts.fonts.build --check                # ranges cover U+4E00-9FFF exactly once
+python -m scripts.fonts.build --plan                 # what a page actually pulls
+```
+
+`--download` verifies the archive's sha256 before unpacking, so a re-slice
+cannot silently pick up a different font. `--check` is what CI-able confidence
+looks like here: it re-reads the committed manifest, re-derives the covered
+codepoints from every `unicode-range`, and fails on a gap, an overlap, or a byte
+size that no longer matches the file on disk.
+
+The frequency order is a separate, frozen input:
+
+```bash
+python -m scripts.fonts.rank --out assets/fonts/ranked-hanzi.txt   # regenerate (deliberate)
+python -m scripts.fonts.rank --check assets/fonts/ranked-hanzi.txt # verify coverage
+```
+
+## Why the slices look like this
+
+A browser downloads a whole `@font-face` slice as soon as **one** character in
+its `unicode-range` appears on the page. Measured on this font:
+
+- the whole hanzi block as one slice: **5,431,736 B** — one Chinese comment would
+  cost 5.4 MB;
+- four equal quarters by codepoint: **~5.8 MB total, and no better per page** —
+  the 60 commonest hanzi are scattered across all four, because codepoint order
+  has nothing to do with how often a character is used;
+- frequency order plus a byte cap: a page using the commonest 200 hanzi pulls
+  **one small slice** (the seed), a page using 3,000 pulls a few, and one rare
+  character costs at most one capped slice (120 KB).
+
+So the plan is a small seed slice (the 300 commonest hanzi) followed by slices
+capped at 120,000 B each. Both numbers live in `scripts/fonts/build.py`; raising
+the cap means fewer files, lowering it means a cheaper worst case. Changing
+either re-slices the same frozen order, which is the point of committing it.
+
+## What the CSS does with it
+
+One rule in `src/client/code-font.ts`: `.lines{font-family:<the bundled family>, <the
+shell's stack>}`. `.lines` is the diff's code table, so the grid lands on the code
+and nothing else — comment bubbles, the file list and the panel's chrome keep the
+shell's font stack.
+
+**Off until asked for.** The switch is in the plugin's DSH Settings section
+(`等宽 CJK 字体` / "Monospaced CJK font"), stored as `diff-approval:code-font`, and
+it defaults to off because the slices are traffic the reader pays for: tens of
+kilobytes for ordinary Chinese, at most ~120 KB per slice for a rare character,
+33 KB for pure ASCII. Off means nothing is fetched at all — no manifest request,
+no `@font-face` — so the default panel is exactly what it was before this
+existed. A browser fetches a `@font-face` only when a rule uses it, which is what
+keeps an enabled pure-ASCII file down to the one Latin slice.
+
+`font-display: swap` rather than `block`: the code is readable in the system font
+immediately, and swapping when the slices land changes the column width, never
+the row height that the virtual window and the jump math are built on.
+
+## Two things the font forces on the build
+
+- **The full feature set is kept when slicing.** `pyftsubset`'s default prunes a
+  code font down to `calt` and `locl` and drops GPOS entirely, which would take
+  the slashed zero (`zero`), the character variants (`cv*`, `ss*`) and accent
+  composition with it. `--layout-features='*'` costs ~20% on the Latin slice and
+  is why `scripts/fonts/build.py` does not use the defaults.
+- **The family name is our own** (`DSH Code Mono`), declared by
+  `src/font-slices.ts`. Two reasons: the upstream name embeds the JetBrains
+  trademark, which OFL does not grant rights to; and a separately installed copy
+  of the upstream font would otherwise win over the webfont, silently replacing
+  the slices the panel counts on. The copyright lines and the OFL text still
+  travel with the files.
+
+The face keeps its own `calt`, so `->` and `=>` draw as arrows — the same thing
+JetBrains Mono already does everywhere else in the UI. The upstream project also
+ships a no-ligature build (`…-NL-…`) if that ever changes; using it means
+re-slicing, not a CSS override, because `calt` is what carries the arrows.
+
+Unhinted on purpose: Windows browser rendering goes through DirectWrite, where
+Google Fonts ships unhinted too, and dropping `cvt `/`fpgm`/`prep` makes every
+slice smaller.
+
+## Licence
+
+SIL Open Font License 1.1, no Reserved Font Name declared by any of the three
+copyright holders (JetBrains Mono, Maple Mono, and the fusion project), so
+subsetting and redistribution are permitted provided `OFL.txt` and the
+copyright notices travel with the files — which is why `OFL.txt` sits here.
+`fontTools.subset` strips the license name records out of a woff2, so the file
+is not optional: the slices do not carry the notice themselves.