dsh-fonttune 0.3.3 → 0.3.5

package/lib/client.js

@@ -86,6 +86,23 @@ var WEIGHT_DIALOG_FIELD = "weightDialog";
 /** Field carrying the code font weight (0 = leave DSH alone). */
 var CODE_WEIGHT_FIELD = "weightCode";
 
+/**
+ * Marks a document whose weight fields are OFFSETS, not absolute weights.
+ *
+ * Before 0.2.8 the three weight axes stored an absolute CSS weight (`300…600`,
+ * `400` = normal) and `clampWeightDelta` converted one on sight. That inference
+ * only works while offsets never land inside the absolute window, which capped
+ * the offset range at +200 — and +200 is not enough room for a step the eye can
+ * see on a family with few faces (measured: one 200-weight step is a +30% change
+ * on Noto Serif SC, one 100-weight step only +16%).
+ *
+ * So the document says which scale it is on, and the inference is borrowed for
+ * exactly one write: the first time 0.3.5+ writes a weight, the card converts any
+ * remaining absolute value, converts the saved presets the same way, and sets
+ * this field. From then on a stored weight is an offset, whatever its size.
+ */
+var WEIGHT_OFFSETS_FIELD = "weightOffsets";
+
 /**
  * Field carrying the interface line-height ratio in percent (100 = untouched).
  * A ratio rather than a px offset: interface line heights form a design ladder
@@ -217,17 +234,18 @@ var WEIGHT_LADDER_TOP = DIALOG_WEIGHT_GROUPS.reduce(function (top, group) {
 /**
  * How far above its base an offset may reach at all.
  *
- * Every axis applies the offset to each element's OWN weight, and the heaviest
- * layer of the ladder sits at `WEIGHT_LADDER_TOP`; past `WEIGHT_CSS_MAX` minus
- * that, the heaviest layer cannot move any further, so a longer range would only
- * add positions that change nothing for the boldest text on screen.
+ * The ceiling comes from the layer a notch MUST move: body text sits at
+ * `WEIGHT_BASE`, so the range runs as far as the text a reader is reading can
+ * still change — measured up to +400 on a family whose faces reach 900. Bold text
+ * stops moving at +300 and headings at +200; that is accepted, because a heading
+ * already at its heaviest face stays there (see `WEIGHT_LADDER_STRONG`).
  *
- * Staying inside it has a second, load-bearing effect: offsets then never land in
- * `WEIGHT_MIN…WEIGHT_MAX`, the range an ABSOLUTE weight from a pre-relative
- * document occupies (see `clampWeightDelta`). The two meanings cannot be confused,
- * so a stored offset is never rescaled into a different one.
+ * It used to stop at `WEIGHT_CSS_MAX - WEIGHT_LADDER_TOP` (= +200) so an offset
+ * could never land inside `WEIGHT_MIN…WEIGHT_MAX`, the window an ABSOLUTE weight
+ * from a pre-relative document occupies. The document's own marker resolves that
+ * window now (`WEIGHT_OFFSETS_FIELD`), so the range is free to grow.
  */
-var WEIGHT_DELTA_UP_LIMIT = WEIGHT_CSS_MAX - WEIGHT_LADDER_TOP;
+var WEIGHT_DELTA_UP_LIMIT = WEIGHT_CSS_MAX - WEIGHT_BASE;
 
 /**
  * The heaviest layer a notch still has to move: bold text.
@@ -323,9 +341,12 @@ var VALUE_FIELDS = [
 var RETIRED_FIELDS = [SIZE_FIELD, LINE_HEIGHT_FIELD];
 
 /**
- * Every durable axis field, live and retired: what normalization covers.
+ * Every durable field normalization covers: the live axes, the retired pair, and
+ * the scale marker (`WEIGHT_OFFSETS_FIELD`, which is deliberately NOT a value
+ * axis — a preset must never carry it, or applying that preset would re-label a
+ * document still holding absolute weights).
  */
-var DURABLE_FIELDS = VALUE_FIELDS.concat(RETIRED_FIELDS);
+var DURABLE_FIELDS = VALUE_FIELDS.concat(RETIRED_FIELDS, [WEIGHT_OFFSETS_FIELD]);
 
 /**
  * Longest accepted font stack, in characters (mirrored by the host schema).
@@ -444,7 +465,7 @@ var FEATURES_UNSAFE = /[^a-zA-Z0-9"' ,]/g;
  * ------------------------------------------------------------------ */
 
 /** Clamp/validate one field by name (shared by config and value sets). */
-function normalizeField(field, value) {
+function normalizeField(field, value, relative) {
   switch (field) {
     case SANS_FIELD:
     case STACK_DIALOG_FIELD:
@@ -457,7 +478,7 @@ function normalizeField(field, value) {
     case WEIGHT_FIELD:
     case WEIGHT_DIALOG_FIELD:
     case CODE_WEIGHT_FIELD:
-      return clampWeightDelta(value);
+      return clampWeightDelta(value, relative);
     case LINE_HEIGHT_FIELD:
     case LINE_HEIGHT_DIALOG_FIELD:
       return clampRatio(value);
@@ -465,6 +486,9 @@ function normalizeField(field, value) {
       return clampLineOffset(value);
     case LIGATURES_FIELD:
       return clampLigatures(value);
+    case WEIGHT_OFFSETS_FIELD:
+      // The document's own scale marker: false/absent = the pre-relative scale.
+      return toBool(value);
     case FEATURES_FIELD:
       return sanitizeFeatures(value);
     case NO_SYNTHETIC_ITALIC_FIELD:
@@ -488,14 +512,17 @@ function normalizeField(field, value) {
  */
 function normalizeConfig(value) {
   var source = value !== null && typeof value === "object" ? value : {};
+  // The scale marker is read BEFORE the axes: it decides whether a weight inside
+  // `300…600` is a legacy absolute value or an offset (see `clampWeightDelta`).
+  var relative = toBool(source[WEIGHT_OFFSETS_FIELD]);
   var config = {};
   for (var index = 0; index < DURABLE_FIELDS.length; index += 1) {
     var field = DURABLE_FIELDS[index];
-    config[field] = normalizeField(field, source[field]);
+    config[field] = normalizeField(field, source[field], relative);
   }
   config[PER_THEME_FIELD] = toBool(source[PER_THEME_FIELD]);
-  config[DARK_VALUES_FIELD] = normalizeDarkValues(source[DARK_VALUES_FIELD]);
-  config[PRESETS_FIELD] = normalizePresets(source[PRESETS_FIELD]);
+  config[DARK_VALUES_FIELD] = normalizeDarkValues(source[DARK_VALUES_FIELD], relative);
+  config[PRESETS_FIELD] = normalizePresets(source[PRESETS_FIELD], relative);
   config[ACTIVE_PRESET_FIELD] = sanitize(source[ACTIVE_PRESET_FIELD]).slice(0, MAX_PRESET_NAME);
   return config;
 }
@@ -533,21 +560,21 @@ function clampWeight(value) {
  * Clamp one RELATIVE weight to its allowed range, migrating an absolute value.
  *
  * A document written before the axes became relative stores an absolute weight
- * (`300…600`, `400` = normal). That window sits entirely outside the delta
- * window, so the conversion is unambiguous and idempotent: a value inside
- * `300…600` is old and becomes its distance from normal (`400 → 0`, `560 → +160`,
- * `300 → −100`), while a value already inside `−100…200` is a delta and is left
- * alone. The user's saved setup therefore keeps meaning "as bold as before"
- * instead of jumping to the top of the new scale.
+ * (`300…600`, `400` = normal) and has no marker, so a value inside `300…600` is
+ * converted to its distance from normal (`400 → 0`, `560 → +160`, `300 → −100`).
+ * A marked document is on the offset scale already and is never converted — that
+ * is what lets an offset grow past `+200` without being mistaken for one of those
+ * absolute values (the two windows overlap; see `WEIGHT_OFFSETS_FIELD`).
  *
  * @param {unknown} value - candidate offset, or a pre-0.2.8 absolute weight.
+ * @param {boolean} [relative] - true when the document carries the offset marker.
  * @returns {number} the offset the stylesheet may use.
  */
-function clampWeightDelta(value) {
+function clampWeightDelta(value, relative) {
   var delta = Number(value);
   if (!isFinite(delta)) return WEIGHT_UNSET;
   delta = Math.round(delta);
-  if (delta >= WEIGHT_MIN && delta <= WEIGHT_MAX) delta -= WEIGHT_BASE;
+  if (relative !== true && delta >= WEIGHT_MIN && delta <= WEIGHT_MAX) delta -= WEIGHT_BASE;
   // The slider's own range comes from the font (see `weightProfileFrom`) and can
   // reach further than the nominal one, so the hard bounds are the widest range
   // any font-derived slider may use.
@@ -595,13 +622,13 @@ function clampLigatures(value) {
  * @param {unknown} values - candidate map.
  * @returns {Record<string, string|number|boolean>} the safe subset.
  */
-function normalizeValueSet(values) {
+function normalizeValueSet(values, relative) {
   var out = {};
   if (values === null || typeof values !== "object" || Array.isArray(values)) return out;
   for (var index = 0; index < VALUE_FIELDS.length; index += 1) {
     var field = VALUE_FIELDS[index];
     if (!Object.prototype.hasOwnProperty.call(values, field)) continue;
-    out[field] = normalizeField(field, values[field]);
+    out[field] = normalizeField(field, values[field], relative);
   }
   return out;
 }
@@ -611,7 +638,7 @@ function normalizeValueSet(values) {
  * @param {unknown} value - candidate JSON text or object.
  * @returns {Record<string, string|number|boolean>} the sparse override map.
  */
-function normalizeDarkValues(value) {
+function normalizeDarkValues(value, relative) {
   if (typeof value === "string") {
     if (value.trim() === "") return {};
     try {
@@ -620,7 +647,70 @@ function normalizeDarkValues(value) {
       return {};
     }
   }
-  return normalizeValueSet(value);
+  return normalizeValueSet(value, relative);
+}
+
+/** The three axes that share the weight scale (and its marker). */
+var WEIGHT_FIELDS = [WEIGHT_FIELD, WEIGHT_DIALOG_FIELD, CODE_WEIGHT_FIELD];
+
+/**
+ * Convert the weight fields of saved preset snapshots to offsets.
+ *
+ * Runs exactly once per document, right before the card sets
+ * `WEIGHT_OFFSETS_FIELD`: a snapshot saved before 0.2.8 holds an absolute weight,
+ * and once the document is marked a stored weight is an offset, so applying that
+ * snapshot later would read `450` as +450 instead of +50. Converting the snapshots
+ * in the same breath as the document keeps the two on one scale.
+ *
+ * Only values inside the legacy absolute window are touched, so a snapshot that
+ * already holds offsets (any 0.3.x one) comes back unchanged and `changed` stays
+ * false — the caller then writes nothing.
+ *
+ * @param {unknown} presets - normalized presets, or anything shaped like them.
+ * @returns {{presets: object[], changed: boolean}} the converted list.
+ */
+function migratePresetWeights(presets) {
+  if (!Array.isArray(presets)) return { presets: [], changed: false };
+  var changed = false;
+  var out = [];
+  for (var index = 0; index < presets.length; index += 1) {
+    var entry = presets[index];
+    if (entry === null || typeof entry !== "object" || entry.values === null) {
+      out.push(entry);
+      continue;
+    }
+    var values = entry.values;
+    if (typeof values !== "object") {
+      out.push(entry);
+      continue;
+    }
+    var converted = null;
+    for (var axis = 0; axis < WEIGHT_FIELDS.length; axis += 1) {
+      var field = WEIGHT_FIELDS[axis];
+      if (!Object.prototype.hasOwnProperty.call(values, field)) continue;
+      var stored = Number(values[field]);
+      if (!isFinite(stored) || stored < WEIGHT_MIN || stored > WEIGHT_MAX) continue;
+      if (converted === null) {
+        converted = {};
+        for (var key in values) {
+          if (Object.prototype.hasOwnProperty.call(values, key)) converted[key] = values[key];
+        }
+      }
+      converted[field] = stored - WEIGHT_BASE;
+    }
+    if (converted === null) {
+      out.push(entry);
+      continue;
+    }
+    changed = true;
+    var copy = {};
+    for (var name in entry) {
+      if (Object.prototype.hasOwnProperty.call(entry, name)) copy[name] = entry[name];
+    }
+    copy.values = converted;
+    out.push(copy);
+  }
+  return { presets: out, changed: changed };
 }
 
 /**
@@ -628,7 +718,7 @@ function normalizeDarkValues(value) {
  * @param {unknown} value - candidate JSON text or array.
  * @returns {{name: string, values: object, savedAt: number}[]}
  */
-function normalizePresets(value) {
+function normalizePresets(value, relative) {
   var list = value;
   if (typeof value === "string") {
     if (value.trim() === "") return [];
@@ -648,7 +738,7 @@ function normalizePresets(value) {
     var stamp = Math.round(Number(entry.savedAt));
     out.push({
       name: name,
-      values: normalizeValueSet(entry.values),
+      values: normalizeValueSet(entry.values, relative),
       savedAt: isFinite(stamp) && stamp > 0 ? stamp : 0,
     });
   }
@@ -1701,6 +1791,17 @@ function resolveAxes(config) {
  */
 var WEIGHT_STEP_CANDIDATES = [1, 5, 10, 25, 50, 100, 200, 300];
 
+/**
+ * How many positions a slider must still offer before a coarser step is refused.
+ *
+ * Coarseness is the point (see `weightProfileFrom`), but a control with two
+ * positions is not a slider. Four is the smallest count that still lets a reader
+ * go one notch either side of the neutral position and one further up — and on
+ * the measured seven-face family it lands on a 200-weight step, where one notch is
+ * a +30% change in ink, against +16% at 100 (which is why 100 was not enough).
+ */
+var WEIGHT_MIN_POSITIONS = 4;
+
 /** The weight grid the profile is measured on. */
 var WEIGHT_PROBE_LOW = 100;
 var WEIGHT_PROBE_HIGH = 900;
@@ -1742,19 +1843,28 @@ function everyPositionDiffers(sample, bases, min, max, step) {
 /**
  * The slider a family deserves: how far it can go, and by how much.
  *
- * A font with six faces can be made lighter or heavier only as far as those faces
- * reach, and only in steps between them; a family with a continuous axis gets a
- * fine step and a wide range. Measured on a weight grid:
+ * A font can be made lighter or heavier only as far as its faces reach, and only
+ * in jumps between them. Measured on a weight grid:
  *  - the downward reach is the highest weight that still renders as light as the
  *    family can (asking for less cannot change anything);
- *  - the upward reach is the LOWEST weight at or above the layer a notch has to
- *    move that already renders as heavy as the family can, so the range ends where
- *    bold text stops changing instead of running past it (see `WEIGHT_DELTA_UP_LIMIT`
- *    for why that ceiling is also the widest one allowed);
- *  - the step is the finest candidate whose positions all differ at every base a
- *    notch has to move, so no notch is a no-op for body text or bold text. A family whose faces are unevenly spaced
- *    (a 700 next to a 900) may end up with one repeated position whichever uniform
- *    step is used — the coarsest candidate is then the honest answer, never a crash.
+ *  - the upward reach is the LOWEST weight at or above body text that already
+ *    renders as heavy as the family can, so the range ends where the text a reader
+ *    is reading stops changing (see `WEIGHT_DELTA_UP_LIMIT` for the ceiling);
+ *  - the step is the COARSEST candidate that still leaves `WEIGHT_MIN_POSITIONS`
+ *    positions with body text changing at every one of them. Coarse is the point:
+ *    a finer step splits one face into several positions that all render the same,
+ *    so the control feels dead (measured on Noto Serif SC, whose faces are
+ *    100-250 / 300 / 400 / 500 / 600 / 700 / 800-900: one 100-weight step is a
+ *    +16% change in ink, one 200-weight step +30%).
+ *
+ * Bold text and headings are deliberately NOT required to change at every
+ * position: the heaviest ladder layer sits at 600 and reaches the ceiling at +300,
+ * so no range can move it further. Body text is what a reader reads, so it carries
+ * the requirement, and a heading already at its boldest face stays there.
+ *
+ * Every position is a whole number of steps from 0, so the card's step counts map
+ * back onto exactly the offsets the document stores.
+ *
  * @param {(weight: number) => string|number} sample - renders a probe at one
  *   weight and returns a signature; equal signatures mean identical rendering.
  * @param {{candidates?: number[], floor?: number, ceil?: number, top?: number}}
@@ -1802,27 +1912,49 @@ function weightProfileFrom(sample, options) {
   }
   var reachUp = Math.min(ceil, WEIGHT_DELTA_UP_LIMIT, headroom);
   var reachDown = Math.max(floor, Math.min(0, lightest - WEIGHT_BASE));
-  var bases = top === WEIGHT_BASE ? [WEIGHT_BASE] : [WEIGHT_BASE, top];
-  for (var index = 0; index < candidates.length; index += 1) {
+  var cap = Math.min(reachUp, WEIGHT_DELTA_UP_LIMIT);
+  /**
+   * The shape one candidate step describes.
+   *
+   * Every position is a whole number of steps from 0, so the card's step counts
+   * multiply back into exactly the offsets the document stores. The reach is
+   * snapped to that grid without ever passing the hard floor or the ceiling —
+   * rounding the top UP (which the first version did) put a position past the
+   * widest allowed offset, and rounding the bottom DOWN could pass the floor.
+   */
+  var shapeAt = function (step) {
+    var down = Math.min(ceilTo(-reachDown, step), floorTo(-floor, step));
+    return { min: -down, max: floorTo(cap, step), step: step };
+  };
+  var best = null;
+  var bestCount = 0;
+  // Coarsest candidate first: the coarsest step that still leaves enough visible
+  // positions is the one a reader can actually work with.
+  for (var index = candidates.length - 1; index >= 0; index -= 1) {
     var step = candidates[index];
     if (!(step > 0)) continue;
-    var min = floorTo(reachDown, step);
-    // Rounding up to the step must not push the range past the limit: the widest
-    // offset has to stay out of the absolute-weight window.
-    var max = Math.min(ceilTo(reachUp, step), WEIGHT_DELTA_UP_LIMIT);
-    // A step wider than the range would leave only one reachable position.
-    if (max > min && step > max - min) continue;
-    if (everyPositionDiffers(sample, bases, min, max, step)) {
-      return { min: min, max: max, step: step };
+    var shape = shapeAt(step);
+    if (shape.max < shape.min) continue;
+    if (!everyPositionDiffers(sample, [WEIGHT_BASE], shape.min, shape.max, step)) continue;
+    var count = (shape.max - shape.min) / step + 1;
+    if (count >= WEIGHT_MIN_POSITIONS) return shape;
+    if (count > bestCount) {
+      best = shape;
+      bestCount = count;
     }
   }
+  if (best !== null) {
+    // Fewer positions than asked for is still usable; one position is the whole
+    // range, and any step describes it, so use the finest and keep the unit small.
+    if (best.max === best.min) return { min: best.min, max: best.max, step: 1 };
+    return best;
+  }
+  // No step kept body text alive: the coarsest one that still fits is the honest
+  // answer, never a step the control cannot reach.
   var coarsest = candidates[candidates.length - 1];
-  var min = floorTo(reachDown, coarsest);
-  var max = Math.min(ceilTo(reachUp, coarsest), WEIGHT_DELTA_UP_LIMIT);
-  // Nothing kept every position alive: the coarsest step that still fits is the
-  // honest answer, never a step the control cannot reach.
-  var span = max - min;
-  return { min: min, max: max, step: span > 0 ? Math.min(coarsest, span) : 1 };
+  var plain = shapeAt(coarsest);
+  var span = plain.max - plain.min;
+  return { min: plain.min, max: plain.max, step: span > 0 ? Math.min(coarsest, span) : 1 };
 }
 
 /**
@@ -1905,9 +2037,11 @@ function isDormant(config) {
     sanitize(axis[MONO_FIELD]) === "" &&
     clampOffset(axis[SIZE_DIALOG_FIELD]) === 0 &&
     clampOffset(axis[CODE_SIZE_FIELD]) === 0 &&
-    clampWeightDelta(axis[WEIGHT_FIELD]) === WEIGHT_UNSET &&
-    clampWeightDelta(axis[WEIGHT_DIALOG_FIELD]) === WEIGHT_UNSET &&
-    clampWeightDelta(axis[CODE_WEIGHT_FIELD]) === WEIGHT_UNSET &&
+    // These arrive normalized, so they are offsets already: converting them again
+    // would rescale an offset that legitimately sits inside `300…600`.
+    clampWeightDelta(axis[WEIGHT_FIELD], true) === WEIGHT_UNSET &&
+    clampWeightDelta(axis[WEIGHT_DIALOG_FIELD], true) === WEIGHT_UNSET &&
+    clampWeightDelta(axis[CODE_WEIGHT_FIELD], true) === WEIGHT_UNSET &&
     clampRatio(axis[LINE_HEIGHT_DIALOG_FIELD]) === LINE_HEIGHT_MIN &&
     clampLineOffset(axis[CODE_LINE_HEIGHT_FIELD]) === 0 &&
     clampLigatures(axis[LIGATURES_FIELD]) === LIGATURES_DEFAULT &&
@@ -2787,6 +2921,9 @@ var shared = {
   WEIGHT_FIELD: WEIGHT_FIELD,
   WEIGHT_DIALOG_FIELD: WEIGHT_DIALOG_FIELD,
   CODE_WEIGHT_FIELD: CODE_WEIGHT_FIELD,
+  WEIGHT_OFFSETS_FIELD: WEIGHT_OFFSETS_FIELD,
+  WEIGHT_FIELDS: WEIGHT_FIELDS,
+  migratePresetWeights: migratePresetWeights,
   LINE_HEIGHT_FIELD: LINE_HEIGHT_FIELD,
   LINE_HEIGHT_DIALOG_FIELD: LINE_HEIGHT_DIALOG_FIELD,
   CODE_LINE_HEIGHT_FIELD: CODE_LINE_HEIGHT_FIELD,
@@ -2881,6 +3018,7 @@ var shared = {
   WEIGHT_STEP_CANDIDATES: WEIGHT_STEP_CANDIDATES,
   WEIGHT_DELTA_FLOOR: WEIGHT_DELTA_FLOOR,
   WEIGHT_DELTA_CEIL: WEIGHT_DELTA_CEIL,
+  WEIGHT_MIN_POSITIONS: WEIGHT_MIN_POSITIONS,
   WEIGHT_LADDER_TOP: WEIGHT_LADDER_TOP,
   WEIGHT_LADDER_STRONG: WEIGHT_LADDER_STRONG,
   WEIGHT_DELTA_UP_LIMIT: WEIGHT_DELTA_UP_LIMIT,
@@ -2964,6 +3102,7 @@ var NO_SYNTHETIC_BOLD_FIELD = shared.NO_SYNTHETIC_BOLD_FIELD;
 var PER_THEME_FIELD = shared.PER_THEME_FIELD;
 var DARK_VALUES_FIELD = shared.DARK_VALUES_FIELD;
 var PRESETS_FIELD = shared.PRESETS_FIELD;
+var WEIGHT_OFFSETS_FIELD = shared.WEIGHT_OFFSETS_FIELD;
 var ACTIVE_PRESET_FIELD = shared.ACTIVE_PRESET_FIELD;
 var UI_FOLLOWS_FIELD = shared.UI_FOLLOWS_FIELD;
 var VALUE_FIELDS = shared.VALUE_FIELDS;
@@ -3213,13 +3352,13 @@ var DICTS = {
 
     "weight.uiLabel": "Interface font-weight offset",
     "weight.uiHint":
-      "Adds to the weight of the whole interface (sidebars, settings, buttons, headings): a positive value is bolder, a negative one lighter. The conversation keeps its own. The slider is divided into the weights the current font can actually render, so the readout counts STEPS (0 = leave DSH alone); every notch swaps in a different face for body text and headings alike, and another font offers a different number of steps.",
+      "Adds to the weight of the whole interface (sidebars, settings, buttons, headings): a positive value is bolder, a negative one lighter. The conversation keeps its own. The slider is divided into the weights the current font can actually render, so the readout counts STEPS (0 = leave DSH alone); every notch swaps in a different face for body text and headings alike, and another font offers a different number of steps. The step is measured for the current font, and its smallest step is the one that looks weakest.",
     "weight.dialogLabel": "Conversation font-weight offset",
     "weight.dialogHint":
-      "Adds to the weight of each conversation element, so headings stay bolder than body text and bold text stays bold. Unset keeps DSH's own weights. The slider is divided into the weights the current font can actually render, so the readout counts STEPS (0 = leave DSH alone); every notch swaps in a different face for body text and headings alike, and another font offers a different number of steps.",
+      "Adds to the weight of each conversation element, so headings stay bolder than body text and bold text stays bold. Unset keeps DSH's own weights. The slider is divided into the weights the current font can actually render, so the readout counts STEPS (0 = leave DSH alone); every notch swaps in a different face for body text and headings alike, and another font offers a different number of steps. The step is measured for the current font, and its smallest step is the one that looks weakest.",
     "weight.codeLabel": "Code font-weight offset",
     "weight.codeHint":
-      "Adds to the weight of each code surface (code blocks, inline code, terminal output); 0 or unset keeps DSH's own weight. The slider is divided into the weights the current font can actually render, so the readout counts STEPS (0 = leave DSH alone); every notch swaps in a different face for body text and headings alike, and another font offers a different number of steps.",
+      "Adds to the weight of each code surface (code blocks, inline code, terminal output); 0 or unset keeps DSH's own weight. The slider is divided into the weights the current font can actually render, so the readout counts STEPS (0 = leave DSH alone); every notch swaps in a different face for body text and headings alike, and another font offers a different number of steps. The step is measured for the current font, and its smallest step is the one that looks weakest.",
 
     "line.dialogLabel": "Conversation line height",
     "line.dialogHint":
@@ -3242,13 +3381,13 @@ var DICTS = {
 
     "synth.italic": "No faux italic",
     "synth.italicHint":
-      "CJK faces have no italic, so the browser tilts them. On keeps marked text upright.",
+      "CJK faces have no italic, so the browser tilts them. On keeps marked text upright. (Same as faux bold: one extra step at most.)",
     "synth.bold": "No faux bold",
     "synth.boldHint":
-      "For faces without a real bold: bold text stops being thickened artificially.",
+      "For faces without a real bold: bold text stops being thickened artificially. (Disabling it lets the browser fake a bold face, which adds one extra step for a font that ships none — it cannot invent the middle ones.)",
     "synth.simple": "No faux italic / faux bold",
     "synth.simpleHint":
-      "Stops synthetic italic and synthetic bold everywhere; switch to Advanced to set them apart.",
+      "Stops synthetic italic and synthetic bold everywhere; switch to Advanced to set them apart. (Both switches: one extra step at most, no middle ones.)",
 
     "section.ui": "Interface",
     "section.dialog": "Conversation",
@@ -3257,7 +3396,8 @@ var DICTS = {
     "section.close": "Collapse {name}",
 
     "ui.follow": "Follows the conversation",
-    "ui.followHint": "Font and weight",
+    "ui.followHint": "Font and weight. While this is on, the interface section's own values are ignored.",
+    "write.reverted": "The setting did not reach the document, so it fell back to what the document holds.",
     "ui.own": "Own values",
     "dialog.default": "DSH defaults",
 
@@ -3357,13 +3497,13 @@ var DICTS = {
 
     "weight.uiLabel": "界面字重偏移",
     "weight.uiHint":
-      "在整个界面自身的字重上叠加（侧栏、设置、按钮、标题）：正数更粗、负数更细；对话 Markdown 不受影响。滑块按当前字体实际能渲染的粗细分档，读数是档数（0 = 保持 DSH 原样）：每挪一格，正文与标题都会换一张字形；换个字体，档数也会跟着变。",
+      "在整个界面自身的字重上叠加（侧栏、设置、按钮、标题）：正数更粗、负数更细；对话 Markdown 不受影响。滑块按当前字体实际能渲染的粗细分档，读数是档数（0 = 保持 DSH 原样）：每挪一格，正文与标题都会换一张字形；换个字体，档数也会跟着变。档距按当前字体实测，其中幅度最小的一档看起来最弱。",
     "weight.dialogLabel": "对话字重偏移",
     "weight.dialogHint":
-      "在每个元素自身的字重上叠加，所以标题依旧比正文粗、加粗文字依旧加粗；未设置时保持 DSH 原本的粗细。滑块按当前字体实际能渲染的粗细分档，读数是档数（0 = 保持 DSH 原样）：每挪一格，正文与标题都会换一张字形；换个字体，档数也会跟着变。",
+      "在每个元素自身的字重上叠加，所以标题依旧比正文粗、加粗文字依旧加粗；未设置时保持 DSH 原本的粗细。滑块按当前字体实际能渲染的粗细分档，读数是档数（0 = 保持 DSH 原样）：每挪一格，正文与标题都会换一张字形；换个字体，档数也会跟着变。档距按当前字体实测，其中幅度最小的一档看起来最弱。",
     "weight.codeLabel": "代码字重偏移",
     "weight.codeHint":
-      "在每个代码面自身的字重上叠加（代码块、行内代码、终端输出）；0 或未设置表示保持 DSH 原样。滑块按当前字体实际能渲染的粗细分档，读数是档数（0 = 保持 DSH 原样）：每挪一格，正文与标题都会换一张字形；换个字体，档数也会跟着变。",
+      "在每个代码面自身的字重上叠加（代码块、行内代码、终端输出）；0 或未设置表示保持 DSH 原样。滑块按当前字体实际能渲染的粗细分档，读数是档数（0 = 保持 DSH 原样）：每挪一格，正文与标题都会换一张字形；换个字体，档数也会跟着变。档距按当前字体实测，其中幅度最小的一档看起来最弱。",
 
     "line.dialogLabel": "对话行高",
     "line.dialogHint": "把对话行高整体缩放为 {ratio}；100% 表示保持 DSH 原样。",
@@ -3384,12 +3524,12 @@ var DICTS = {
 
     "synth.italic": "禁用伪斜体",
     "synth.italicHint":
-      "中文字体没有斜体，浏览器会把标记文本硬掰歪；开启后保持直立。",
+      "中文字体没有斜体，浏览器会把标记文本硬掰歪；开启后保持直立。（与伪粗体同理：最多多出一档。）",
     "synth.bold": "禁用伪粗体",
-    "synth.boldHint": "没有真实粗体的字体不再被人为加粗。",
+    "synth.boldHint": "没有真实粗体的字体不再被人为加粗。（关掉它，浏览器会为没有粗体字形的字体自己造粗体：能多出一档，但变不出中间档。）",
     "synth.simple": "禁用伪斜体/伪粗体",
     "synth.simpleHint":
-      "整页停用合成斜体与合成粗体；切到高级模式可分开设置。",
+      "整页停用合成斜体与合成粗体；切到高级模式可分开设置。（两项一起关：最多多出一档，变不出中间档。）",
 
     "section.ui": "界面",
     "section.dialog": "对话",
@@ -3399,7 +3539,8 @@ var DICTS = {
 
 
     "ui.follow": "跟随对话设置",
-    "ui.followHint": "字体与字重",
+    "ui.followHint": "字体与字重跟随开启时，界面分区自己的取值会被忽略。",
+    "write.reverted": "设置没写进文档，已恢复为文档里的值。",
     "ui.own": "独立数值",
     "dialog.default": "DSH 默认",
 
@@ -3597,6 +3738,8 @@ var CARD_CSS = [
   ".dfp-slider{flex:1;min-width:0;height:20px;accent-color:var(--dsw-alias-brand-primary)}",
   ".dfp-value{flex:none;min-width:56px;text-align:right;color:var(--dsw-alias-label-primary);font-size:13px;line-height:20px;font-variant-numeric:tabular-nums}",
   ".dfp-scale{color:var(--dsw-alias-label-tertiary);font-size:11px;line-height:16px;display:flex;justify-content:space-between}",
+  // a write the document never took: visible, but quieter than the field label
+  ".dfp-sliderNotice{margin-top:6px;color:var(--dsw-alias-label-secondary);font-size:11px;line-height:16px}",
 
   // the per-section preview: an inline box at the end of the expanded
   // section body, showing only that section's own sample
@@ -4109,6 +4252,9 @@ function Section(props) {
  */
 function NumberSlider(props) {
   var [pending, setPending] = useState(null);
+  // A write the document never took: the readout falls back to the document and
+  // this says so once, instead of the thumb looking like it moved on its own.
+  var [reverted, setReverted] = useState(false);
   var step = typeof props.step === "number" && props.step > 0 ? props.step : 1;
   // The value the host has not confirmed yet. Between the release and the
   // settings round-trip the committed prop is still the OLD number — clearing
@@ -4141,6 +4287,7 @@ function NumberSlider(props) {
   );
   var commit = function (value) {
     awaitingRef.current = value;
+    setReverted(false);
     props.onChange(value);
   };
   /**
@@ -4160,6 +4307,8 @@ function NumberSlider(props) {
       var timer = setTimeout(function () {
         awaitingRef.current = null;
         setLocal(null);
+        // The document is the truth and it never took this value: say so once.
+        setReverted(true);
       }, COMMIT_PATIENCE_MS);
       return function () {
         clearTimeout(timer);
@@ -4221,6 +4370,9 @@ function NumberSlider(props) {
       }),
       h("span", { className: "dfp-value" }, readout)
     ),
+    reverted && props.revertedText
+      ? h("div", { className: "dfp-sliderNotice" }, props.revertedText)
+      : null,
     h(
       "div",
       { className: "dfp-scale" },
@@ -5466,6 +5618,7 @@ function FontCard(props) {
         value: props.value,
         disabled: !writable,
         label: t(props.labelKey),
+        revertedText: t("write.reverted"),
         readout: props.text + " " + t("size.unit"),
         minLabel: SIZE_MIN + " " + t("size.unit"),
         maxLabel: "+" + SIZE_MAX + " " + t("size.unit"),
@@ -5520,6 +5673,7 @@ function FontCard(props) {
         value: shape.value,
         disabled: !writable,
         label: t(props.labelKey),
+        revertedText: t("write.reverted"),
         // One notch is one family step, so every notch changes what is on screen.
         step: 1,
         // The readout is the STEP COUNT, not the weight: "+2" is two faces
@@ -5532,6 +5686,8 @@ function FontCard(props) {
         // the document confirmed it).
         pendingText: text,
         onChange: function (count) {
+          // Once per document, before anything is written on the new scale.
+          adoptWeightScale();
           // The neutral position means "leave the axis alone" rather than "write
           // it on every element".
           if (count === 0) resetField(props.field);
@@ -5562,6 +5718,7 @@ function FontCard(props) {
         value: props.value,
         disabled: !writable,
         label: t(props.labelKey),
+        revertedText: t("write.reverted"),
         readout: props.value + " " + t("line.unit"),
         minLabel: LINE_HEIGHT_MIN + " " + t("line.unit"),
         maxLabel: LINE_HEIGHT_MAX + " " + t("line.unit"),
@@ -5598,6 +5755,7 @@ function FontCard(props) {
         value: value,
         disabled: !writable,
         label: t("line.codeLabel"),
+        revertedText: t("write.reverted"),
         readout: (value > 0 ? "+" + value : String(value)) + "px",
         minLabel: CODE_LINE_HEIGHT_MIN + "px",
         maxLabel: "+" + CODE_LINE_HEIGHT_MAX + "px",
@@ -5742,6 +5900,40 @@ function FontCard(props) {
     submit(PRESETS_FIELD, JSON.stringify(next));
   };
 
+  /**
+   * Adopt the offset scale, once per document.
+   *
+   * A document written before the weight axes became relative stores absolute
+   * weights inside `300…600`, and once a document is marked a stored `450` means
+   * +450 — the two scales overlap, so the conversion must happen exactly once and
+   * never again. This is that moment: before the first weight this card writes,
+   * convert whatever is still absolute (the three fields and every saved snapshot),
+   * then set the marker.
+   *
+   * Values first, marker last: a stylesheet rebuild between the two still sees
+   * values that render exactly as before, and a marked document is never left
+   * holding an unconverted absolute weight.
+   *
+   * The three fields are read from `config`, not from the expanded `editing` set:
+   * while the interface follows the conversation, `editing` mirrors the
+   * conversation's weight into the interface's own field, and writing that back
+   * would silently freeze the follow.
+   */
+  var adoptWeightScale = function () {
+    if (config[WEIGHT_OFFSETS_FIELD] === true) return;
+    for (var index = 0; index < shared.WEIGHT_FIELDS.length; index += 1) {
+      var field = shared.WEIGHT_FIELDS[index];
+      var stored = Number(config[field]);
+      if (!isFinite(stored) || stored < shared.WEIGHT_MIN || stored > shared.WEIGHT_MAX) {
+        continue;
+      }
+      submit(field, stored - shared.WEIGHT_BASE);
+    }
+    var migrated = shared.migratePresetWeights(config[PRESETS_FIELD]);
+    if (migrated.changed) writePresets(migrated.presets);
+    submit(WEIGHT_OFFSETS_FIELD, true);
+  };
+
   /**
    * Switch presets: the entry becomes the auto-save target and its stored
    * values are applied over the set currently being edited — every axis the

package/lib/index.js

@@ -217,6 +217,12 @@ export const Config = volatileWhenSupported(z.object({
     .description(
       `Code font-weight offset; added to each code surface's own weight and independent of the interface weight (the slider spans whatever weights the chosen font can render), ${shared.WEIGHT_UNSET} keeps DSH's own weights. A legacy absolute weight (${shared.WEIGHT_MIN}..${shared.WEIGHT_MAX}) is accepted and converted to its offset.`
     ),
+  [shared.WEIGHT_OFFSETS_FIELD]: z
+    .boolean()
+    .default(false)
+    .description(
+      "Scale marker: the three weight fields hold offsets, not legacy absolute weights (set automatically the first time the card writes a weight)"
+    ),
   [LINE_HEIGHT_FIELD]: z
     .number()
     .min(shared.LINE_HEIGHT_MIN)