dsh-fonttune 0.2.7 → 0.3.1

package/lib/client.js

@@ -143,11 +143,105 @@ var UI_FOLLOWS_FIELD = "uiFollowsDialog";
 var SIZE_MIN = -3;
 var SIZE_MAX = 6;
 
-/** Allowed font weight range, and the value meaning "do not touch". */
+/** Allowed CODE weight range (an absolute value), and "do not touch". */
 var WEIGHT_MIN = 300;
 var WEIGHT_MAX = 600;
 var WEIGHT_UNSET = 0;
 
+/**
+ * Allowed range of the two RELATIVE weight axes, in steps of 100-weight.
+ *
+ * The conversation and interface weight axes are offsets on each element's own
+ * weight, not replacements: a flat `font-weight` over the markdown subtree
+ * erased the heading hierarchy (measured on 0.1.7-rc.2, where every markdown
+ * weight lives inside its `font` shorthand — `._markdown_ h2{font:var(--dsw-font-markdown-h2)}`
+ * with `700` in it — and a long-handed `font-weight` with `!important` beat the
+ * shorthand). The delta window is the old absolute window shifted by −400, so
+ * `300…600` maps onto `−100…+200` one-to-one and `400` (normal) becomes 0, which
+ * is the value meaning "do not touch".
+ */
+var WEIGHT_DELTA_MIN = -100;
+var WEIGHT_DELTA_MAX = 200;
+
+/**
+ * The widest range a font-derived slider may use, either way.
+ *
+ * The nominal window above is what the axes can always express; a family with
+ * faces outside it (a black 900 cut, a hairline 100) earns a wider slider — see
+ * `weightProfileFrom` — and these are the hard bounds that keeps that in check.
+ */
+var WEIGHT_DELTA_FLOOR = -300;
+var WEIGHT_DELTA_CEIL = 600;
+
+/** The weight DSH gives an element that declares none of its own. */
+var WEIGHT_BASE = 400;
+
+/**
+ * The weight range CSS accepts at all.
+ *
+ * Named because it is easy to confuse with `WEIGHT_MIN…WEIGHT_MAX`, which is the
+ * window an ABSOLUTE weight from a pre-relative document occupies (300…600) and
+ * has nothing to do with what a font can render.
+ */
+var WEIGHT_CSS_MIN = 100;
+var WEIGHT_CSS_MAX = 900;
+
+/**
+ * The weight ladder of the conversation: each group carries the weight DSH's
+ * own stylesheet gives those elements, so an offset lands ON TOP of it.
+ *
+ * The bases are the measured ones (`--dsw-font-markdown-h*-font-weight` 700 /
+ * 600, `-base-strong-font-weight` 600, `-table-head-font-weight` 500, everything
+ * else 400).
+ */
+var DIALOG_WEIGHT_GROUPS = [
+  { base: 700, elements: "h1,h2,h3" },
+  { base: 600, elements: "h4,h5,h6" },
+  { base: 600, elements: "strong,b" },
+  { base: 500, elements: "th" },
+  {
+    base: 400,
+    elements: "p,li,td,dt,dd,blockquote,summary,em,i,a,label,small,div,span",
+  },
+];
+
+/**
+ * The heaviest base in the conversation ladder — the layer with the least room.
+ *
+ * Derived from the ladder so the two cannot drift apart.
+ */
+var WEIGHT_LADDER_TOP = DIALOG_WEIGHT_GROUPS.reduce(function (top, group) {
+  return group.base > top ? group.base : top;
+}, WEIGHT_BASE);
+
+/**
+ * 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.
+ *
+ * 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.
+ */
+var WEIGHT_DELTA_UP_LIMIT = WEIGHT_CSS_MAX - WEIGHT_LADDER_TOP;
+
+/**
+ * The heaviest layer a notch still has to move: bold text.
+ *
+ * The heading layer above it is deliberately left out of that requirement. A heavy
+ * family spaces its top faces far apart (a 700 cut next to a 900), so headings
+ * reach their heaviest rendering part-way up the range and would otherwise hold the
+ * whole control down to one wide step. Every notch must move the text you read and
+ * the text you emphasise; a heading that is already at its boldest face stays there.
+ */
+var WEIGHT_LADDER_STRONG = DIALOG_WEIGHT_GROUPS.reduce(function (strong, group) {
+  return group.base < WEIGHT_LADDER_TOP && group.base > strong ? group.base : strong;
+}, WEIGHT_BASE);
+
 /** Allowed line-height ratio range, in percent (100 = untouched). */
 var LINE_HEIGHT_MIN = 100;
 var LINE_HEIGHT_MAX = 160;
@@ -363,7 +457,7 @@ function normalizeField(field, value) {
     case WEIGHT_FIELD:
     case WEIGHT_DIALOG_FIELD:
     case CODE_WEIGHT_FIELD:
-      return clampWeight(value);
+      return clampWeightDelta(value);
     case LINE_HEIGHT_FIELD:
     case LINE_HEIGHT_DIALOG_FIELD:
       return clampRatio(value);
@@ -435,6 +529,33 @@ function clampWeight(value) {
   return Math.min(WEIGHT_MAX, Math.max(WEIGHT_MIN, weight));
 }
 
+/**
+ * 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.
+ *
+ * @param {unknown} value - candidate offset, or a pre-0.2.8 absolute weight.
+ * @returns {number} the offset the stylesheet may use.
+ */
+function clampWeightDelta(value) {
+  var delta = Number(value);
+  if (!isFinite(delta)) return WEIGHT_UNSET;
+  delta = Math.round(delta);
+  if (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.
+  if (delta > WEIGHT_DELTA_CEIL) return WEIGHT_DELTA_CEIL;
+  if (delta < WEIGHT_DELTA_FLOOR) return WEIGHT_DELTA_FLOOR;
+  return delta;
+}
+
 /**
  * Clamp one line-height ratio to the allowed percent range.
  * @param {unknown} value - candidate ratio in percent.
@@ -952,6 +1073,28 @@ var DELTA_PATTERN = /^--dsh-content-font-delta(?:-secondary)?$/;
 /** The whole official content-size chain (size / line height / delta). */
 var CONTENT_PATTERN = /^--dsh-content-font-(?:size|line-height|delta)(?:-secondary)?$/;
 
+/**
+ * The one property the conversation size offset is added to: the official
+ * "对话字号" source, which the app writes INLINE on `body`.
+ *
+ * Every other markdown size is derived from it (through
+ * `--dsh-content-font-delta` and the markdown shorthands), and custom properties
+ * resolve where they are DECLARED — so the offset has to land here, once, or a
+ * deeper override would leave the derived tokens at their body-computed values.
+ */
+var CONTENT_SIZE_SOURCE = "--dsh-content-font-size";
+
+/**
+ * Whether one declared value is a plain literal this plugin may wrap in
+ * `calc(… + Npx)`. A `var()` reference is NOT: it is either derived from a
+ * property this plugin already shifted, or it belongs to another axis.
+ * @param {unknown} value - a declared custom-property value.
+ * @returns {boolean}
+ */
+function isLiteralTokenValue(value) {
+  return typeof value === "string" && value !== "" && value.indexOf("var(") === -1;
+}
+
 /**
  * The PART-token suffixes DSH appends for single-axis consumers.
  */
@@ -1030,6 +1173,30 @@ function isMarkdownToken(name) {
   return typeof name === "string" && name.indexOf("--dsw-font-markdown-") === 0 && !isCodeToken(name);
 }
 
+/**
+ * The one markdown family whose sizes are LITERALS instead of following the
+ * official content-size chain: the `small` series (`12px/20px`, measured on
+ * 0.1.7-rc.2).
+ *
+ * Every other markdown size derives from `--dsh-content-font-size` through
+ * `--dsh-content-font-delta`, so shifting them as well applies the offset a
+ * second time. The value cannot tell the families apart: the page also carries
+ * `--dsw-font-markdown-h1` with its var() already substituted
+ * (`700 calc(21px + -2px)/…`), which reads exactly like a literal and made
+ * H1/H2 shrink while H3 stayed right (the asymmetric report that started this).
+ * The NAME is the only reliable discriminator, so this is a whitelist.
+ */
+var MARKDOWN_LITERAL_PREFIX = "--dsw-font-markdown-small";
+
+/**
+ * Whether a token belongs to the literal (non-derived) markdown family.
+ * @param {string} name - custom property name including the leading dashes.
+ * @returns {boolean}
+ */
+function isMarkdownLiteralToken(name) {
+  return typeof name === "string" && name.indexOf(MARKDOWN_LITERAL_PREFIX) === 0;
+}
+
 /**
  * Whether one NAME looks like a `font` shorthand token (a bare
  * `--dsw-font-…` name that is not a PART token or a family variable).
@@ -1267,8 +1434,7 @@ function codeSurfaceList() {
  * not free: an ancestor-walking selector costs about 0.03 s per 50-step drag on
  * 0.1.5-rc.3 (measured: stripping the ` *` forms from these two rules took the
  * drag from 0.89 s to 0.52 s of style recalculation). The weight family keeps
- * the code subtree right through `--dfp-interface-weight` instead — see
- * `weightRule`.
+ * the code subtree right through `--dfp-wdelta` instead — see `weightRule`.
  *
  * @param {{code?: string[], terminal?: string[]}|null} [hints] - unused; kept so
  *   the browser half can keep passing one harvest object to `buildFontCss`.
@@ -1360,16 +1526,19 @@ var WEIGHT_MARKDOWN_GUARD =
   "))";
 
 /**
- * The elements that carry a weight of their own in DSH.
+ * The elements that carry a weight of their own in the INTERFACE (the chrome).
  *
  * The weight is the one property that cannot ride inheritance alone: an element
  * whose own rule declares a weight ignores the value it would inherit, whatever
- * that value's importance. Measured on 0.1.5-rc.3, the elements that do declare
- * one are `button` / `span` / `div` in the chrome and `strong` / `th` in the
- * conversation; the rest of the list is the inline markup that could plausibly
- * join them. This replaces the old `body,body *` reach, which matched 1892
- * elements on every recalculation — the whole point of the table is that it
- * matches a fraction of that while still covering every pinned element.
+ * that value's importance. Measured on 0.1.5-rc.3, the chrome's pinned elements
+ * are `button` / `span` / `div`; the rest of the list is the inline markup that
+ * could plausibly join them. This replaces the old `body,body *` reach, which
+ * matched 1892 elements on every recalculation — the whole point of the table is
+ * that it matches a fraction of that while still covering every pinned element.
+ *
+ * The CONVERSATION is not covered here: it has its own ladder with per-element
+ * bases (`DIALOG_WEIGHT_GROUPS`), because one flat weight cannot preserve a
+ * heading hierarchy.
  */
 var WEIGHT_ELEMENT_TABLE = [
   "button",
@@ -1521,6 +1690,196 @@ function resolveAxes(config) {
  * the stylesheet builder
  * ------------------------------------------------------------------ */
 
+/**
+ * The steps a weight slider may use, finest first.
+ *
+ * A family ships a fixed set of faces and the browser rounds any requested
+ * weight to the nearest one, so a slider that runs in single units spends long
+ * stretches on one face. The control is therefore built from what the family can
+ * actually render: its range runs from the lightest face it has to the heaviest,
+ * and its notch is the family's own granularity.
+ */
+var WEIGHT_STEP_CANDIDATES = [1, 5, 10, 25, 50, 100, 200, 300];
+
+/** The weight grid the profile is measured on. */
+var WEIGHT_PROBE_LOW = 100;
+var WEIGHT_PROBE_HIGH = 900;
+var WEIGHT_PROBE_STEP = 10;
+
+/** Round down/up to a multiple of `step`. */
+function floorTo(value, step) {
+  return Math.floor(value / step) * step;
+}
+function ceilTo(value, step) {
+  return Math.ceil(value / step) * step;
+}
+
+/**
+ * Does every position of `[min..max]` in `step` increments render differently?
+ *
+ * Checked at every base the offset is added to: a step that is fine for body text
+ * can be a no-op one layer up, where the faces are further apart.
+ * @param {(weight: number) => string|number} sample - probe.
+ * @param {number[]} bases - the weights the offsets are added to.
+ * @param {number} min - first offset.
+ * @param {number} max - last offset.
+ * @param {number} step - offset increment.
+ * @returns {boolean} true when no two neighbours render the same at any base.
+ */
+function everyPositionDiffers(sample, bases, min, max, step) {
+  for (var index = 0; index < bases.length; index += 1) {
+    var base = bases[index];
+    var previous = null;
+    for (var position = min; position <= max; position += step) {
+      var signature = sample(base + position);
+      if (previous !== null && signature === previous) return false;
+      previous = signature;
+    }
+  }
+  return true;
+}
+
+/**
+ * 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:
+ *  - 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.
+ * @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}}
+ *   [options] overrides for the candidates, the widest allowed range and the
+ *   heaviest base the offset is added to (the ladder's, or the axis's own).
+ * @returns {{min: number, max: number, step: number}} the slider's shape; the
+ *   range always contains 0, which is the "leave DSH alone" position.
+ */
+function weightProfileFrom(sample, options) {
+  var settings = options || {};
+  var candidates =
+    Array.isArray(settings.candidates) && settings.candidates.length > 0
+      ? settings.candidates
+      : WEIGHT_STEP_CANDIDATES;
+  var floor = typeof settings.floor === "number" ? settings.floor : WEIGHT_DELTA_FLOOR;
+  var ceil = typeof settings.ceil === "number" ? settings.ceil : WEIGHT_DELTA_CEIL;
+  var top = typeof settings.top === "number" ? settings.top : WEIGHT_LADDER_STRONG;
+  var topSignature = sample(WEIGHT_PROBE_HIGH);
+  var bottomSignature = sample(WEIGHT_PROBE_LOW);
+  var heaviest = WEIGHT_PROBE_HIGH;
+  for (var weight = WEIGHT_PROBE_LOW; weight <= WEIGHT_PROBE_HIGH; weight += WEIGHT_PROBE_STEP) {
+    if (sample(weight) === topSignature) {
+      heaviest = weight;
+      break;
+    }
+  }
+  var lightest = WEIGHT_PROBE_LOW;
+  for (var back = WEIGHT_PROBE_HIGH; back >= WEIGHT_PROBE_LOW; back -= WEIGHT_PROBE_STEP) {
+    if (sample(back) === bottomSignature) {
+      lightest = back;
+      break;
+    }
+  }
+  // How far the offset can go before NO layer that must move can move any more:
+  // the widest horizon among those bases, since a layer that could still change
+  // must not be cut off by one that already sits at its heaviest face.
+  var headroom = Math.max(0, heaviest - WEIGHT_BASE);
+  if (top !== WEIGHT_BASE) {
+    for (var up = top; up <= WEIGHT_PROBE_HIGH; up += WEIGHT_PROBE_STEP) {
+      if (sample(up) === topSignature) {
+        headroom = Math.max(headroom, up - top);
+        break;
+      }
+    }
+  }
+  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 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 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 };
+}
+
+/**
+ * Turn a measured profile into the slider the card shows.
+ *
+ * The document keeps storing a weight offset (so nothing written before has to be
+ * migrated), but the CONTROL counts the family's own steps: a six-face family
+ * offers "-2 … +4" instead of "-200 … +400", which is what a reader can actually
+ * see. `unit` is how many weight units one step is worth.
+ * @param {{min: number, max: number, step: number}} profile - measured shape.
+ * @param {number} value - the stored offset, in weight units.
+ * @returns {{min: number, max: number, unit: number, value: number}} the slider
+ *   in step counts; a stored value outside the measured range widens it, so it is
+ *   never unreachable.
+ */
+function weightStepRange(profile, value) {
+  var unit = profile && profile.step > 0 ? profile.step : 1;
+  var count = Math.round(Number(value) / unit);
+  if (!isFinite(count)) count = 0;
+  var min = Math.floor(profile.min / unit);
+  var max = Math.ceil(profile.max / unit);
+  if (count < min) min = count;
+  if (count > max) max = count;
+  return { min: min, max: max, unit: unit, value: count };
+}
+
+/**
+ * What a slider's local (unconfirmed) value should do when a value arrives from
+ * the settings document.
+ *
+ * A slider keeps the value the user released until the document echoes it back;
+ * dropping it immediately would show the old number for a frame (the "bounce
+ * back, then settle" flicker). Two cases must NOT drop it:
+ *  - a confirmation for the PREVIOUS commit arriving after the user already
+ *    started a new drag — the document write is debounced and can land seconds
+ *    later (measured on 0.1.7-rc.2: 0.7–5 s), and clearing there snapped the
+ *    thumb back to the old value mid-drag;
+ *  - any unrelated outside value (another page, a reset) arriving mid-drag.
+ *
+ * @param {{pending: number|null, awaiting: number|null, confirmed: number}} state
+ *   the local value, the value a commit is waiting for (null when idle), and the
+ *   value the document currently reports.
+ * @returns {{pending: number|null, awaiting: number|null}} the state to keep.
+ */
+function reconcileSliderValue(state) {
+  var pending = state.pending;
+  var awaiting = state.awaiting;
+  var confirmed = state.confirmed;
+  if (awaiting !== null && confirmed === awaiting) {
+    awaiting = null;
+    if (pending === confirmed) pending = null;
+    return { pending: pending, awaiting: awaiting };
+  }
+  if (awaiting === null && pending !== null && pending === confirmed) pending = null;
+  return { pending: pending, awaiting: awaiting };
+}
+
 /**
  * Whether a normalized configuration asks for any change at all.
  * @param {unknown} config - candidate configuration.
@@ -1546,9 +1905,9 @@ function isDormant(config) {
     sanitize(axis[MONO_FIELD]) === "" &&
     clampOffset(axis[SIZE_DIALOG_FIELD]) === 0 &&
     clampOffset(axis[CODE_SIZE_FIELD]) === 0 &&
-    clampWeight(axis[WEIGHT_FIELD]) === WEIGHT_UNSET &&
-    clampWeight(axis[WEIGHT_DIALOG_FIELD]) === WEIGHT_UNSET &&
-    clampWeight(axis[CODE_WEIGHT_FIELD]) === WEIGHT_UNSET &&
+    clampWeightDelta(axis[WEIGHT_FIELD]) === WEIGHT_UNSET &&
+    clampWeightDelta(axis[WEIGHT_DIALOG_FIELD]) === WEIGHT_UNSET &&
+    clampWeightDelta(axis[CODE_WEIGHT_FIELD]) === WEIGHT_UNSET &&
     clampRatio(axis[LINE_HEIGHT_DIALOG_FIELD]) === LINE_HEIGHT_MIN &&
     clampLineOffset(axis[CODE_LINE_HEIGHT_FIELD]) === 0 &&
     clampLigatures(axis[LIGATURES_FIELD]) === LIGATURES_DEFAULT &&
@@ -1581,8 +1940,9 @@ function buildAxisCss(axis, baseTokens, isDark, hints) {
   var dialog = formatStack(parseStack(axis[STACK_DIALOG_FIELD]));
   // Normalised once: an expanded axis always carries a number, but a caller
   // handing in a raw object may leave the field out, and "absent" has to mean
-  // "unset" rather than "write the string undefined".
-  var dialogWeight = typeof axis[WEIGHT_DIALOG_FIELD] === "number" ? axis[WEIGHT_DIALOG_FIELD] : WEIGHT_UNSET;
+  // "unset" rather than "write the string undefined". The conversation's value
+  // is an OFFSET (see `clampWeightDelta`), not a weight.
+  var dialogDelta = typeof axis[WEIGHT_DIALOG_FIELD] === "number" ? axis[WEIGHT_DIALOG_FIELD] : WEIGHT_UNSET;
   var codeSurfaces = codeSelector(hints);
   var dialogSurfaces = dialogSelector(hints);
   var declarations = [];
@@ -1619,24 +1979,86 @@ function buildAxisCss(axis, baseTokens, isDark, hints) {
    * plus an element table for the tags DSH pins a weight on of their own (see
    * `WEIGHT_ELEMENT_TABLE`).
    *
-   * The value rides a custom property (`--dfp-interface-weight`, declared on
+   * The offset rides a custom property (`--dfp-wdelta`, declared on
    * `:root,body` by the caller) rather than a literal. That is what keeps the
    * code subtree right without a descendant selector: a highlight `<span>`
    * inside a `<pre>` IS matched by this rule's table, but it resolves the
-   * variable its code ancestor set (see the code weight rule), so it takes the
-   * code weight instead of the interface one. Naming `pre *` and friends here
+   * variable its code ancestor set (see the code weight rules), so it takes the
+   * code offset instead of the interface one. Naming `pre *` and friends here
    * or in the code rules instead cost 0.03 s per selector per drag.
    *
-   * The markdown guard only rides along when the conversation has NO weight of
-   * its own — with one set, the class-scoped dialog rule out-ranks this rule
-   * inside markdown anyway.
+   * The markdown guard only rides along when the conversation has NO offset of
+   * its own — with one set, the class-scoped conversation ladder out-ranks this
+   * rule inside markdown anyway.
    */
   function weightRule(declarations) {
     var base = isDark ? DARK_ATTR : "body";
     var selector = base + "," + base + " :where(" + WEIGHT_ELEMENT_TABLE + ")";
-    if (dialogWeight === WEIGHT_UNSET) selector += WEIGHT_MARKDOWN_GUARD;
+    if (dialogDelta === WEIGHT_UNSET) selector += WEIGHT_MARKDOWN_GUARD;
     return selector + "{" + declarations + "}";
   }
+  /**
+   * The weight one element group resolves to: its own base plus the offset that
+   * is in force where the element sits, clamped to the legal CSS range so an
+   * extreme offset cannot leave it (a weight below 100 is invalid, above 900 is
+   * ignored by the font).
+   * @param {number} base - the weight DSH gives this group.
+   * @returns {string} the `font-weight` value.
+   */
+  function ladderWeight(base) {
+    return (
+      "clamp(" + WEIGHT_CSS_MIN + ",calc(" + base + " + var(--dfp-wdelta,0))," + WEIGHT_CSS_MAX + ")"
+    );
+  }
+  /**
+   * The scope the conversation WEIGHT rules hang on: the cheap markdown wrapper
+   * (the harvested hint when the page has one, the substring form otherwise).
+   *
+   * Not the family rule's `dialogSurfaces` list: that one has to reach every
+   * descendant because it overrides an inherited family, while the ladder names
+   * its own elements — and reusing that list would multiply its ancestor-walking
+   * `… *` selectors by five groups, which is exactly the cost the element table
+   * was introduced to remove. Code surfaces need no exclusion here either: the
+   * code rules pin `--dfp-wdelta` on themselves, so an element inside one adds
+   * the offset in force THERE (the code's), which is the value it should get.
+   * @returns {string} one selector.
+   */
+  function weightScopeSelector() {
+    return hints !== null && typeof hints === "object" && typeof hints.markdown === "string"
+      ? hints.markdown
+      : '[class*="_markdown_" i]';
+  }
+  /**
+   * A rule for the conversation scope itself, so text sitting directly in the
+   * container moves with the axis (and so `--dfp-wdelta` is pinned for the
+   * ladder below before any child resolves it).
+   * @param {string} declarations - the declarations to write.
+   * @returns {string} the rule.
+   */
+  function weightScopeRule(declarations) {
+    var scope = weightScopeSelector();
+    return (isDark ? DARK_ATTR + " " : "") + scope + "{" + declarations + "}";
+  }
+  /**
+   * The conversation ladder: one rule per group in `DIALOG_WEIGHT_GROUPS`, each
+   * scoped under the conversation.
+   * @param {string} surfaceList - a comma-separated selector list.
+   * @returns {string[]} one rule per group.
+   */
+  function weightLadderRules(surfaceList) {
+    var rules = [];
+    var surfaces = splitSelectorList(surfaceList);
+    for (var groupIndex = 0; groupIndex < DIALOG_WEIGHT_GROUPS.length; groupIndex += 1) {
+      var group = DIALOG_WEIGHT_GROUPS[groupIndex];
+      var scoped = [];
+      for (var surfaceIndex = 0; surfaceIndex < surfaces.length; surfaceIndex += 1) {
+        var one = surfaces[surfaceIndex] + " :is(" + group.elements + ")";
+        scoped.push(isDark ? DARK_ATTR + " " + one : one);
+      }
+      rules.push(scoped.join(",") + "{font-weight:" + ladderWeight(group.base) + " !important}");
+    }
+    return rules;
+  }
   /**
    * Re-assert the code family inside the dialog: scoped under the markdown
    * container, after the dialog rule and above it in specificity, so a
@@ -1694,39 +2116,35 @@ function buildAxisCss(axis, baseTokens, isDark, hints) {
   // page-wide `font-family` on body plus the theme variable) and the weight
   // (below).
 
-  // ---- interface weight ----
+  // ---- interface weight (a relative offset) ----
   // A `body{font-weight}` rule only reaches the elements that INHERIT their
   // weight; the chrome's `button` / `span` / `div` class rules pin their own
   // (measured on 0.1.5-rc.3), which is why the second reach exists. The
   // conversation is held apart by `weightRule`'s guard (or by the class-scoped
-  // dialog rule when the conversation has a weight of its own).
-  var interfaceWeight = typeof axis[WEIGHT_FIELD] === "number" ? axis[WEIGHT_FIELD] : WEIGHT_UNSET;
+  // conversation ladder when the conversation has an offset of its own).
+  //
+  // The value is an OFFSET on the element's own weight, never a replacement, so
+  // raising the interface weight cannot flatten anything that shipped heavier
+  // than the base. The offset rides `--dfp-wdelta` so the code rules can pin it
+  // back to zero (or to the code offset) on their surfaces without any
+  // descendant selector.
+  var interfaceDelta = typeof axis[WEIGHT_FIELD] === "number" ? axis[WEIGHT_FIELD] : WEIGHT_UNSET;
   var codeWeight = typeof axis[CODE_WEIGHT_FIELD] === "number" ? axis[CODE_WEIGHT_FIELD] : WEIGHT_UNSET;
-  if (interfaceWeight !== WEIGHT_UNSET) {
-    // The variable the weight rule resolves; the code rules below override it
-    // on their surfaces so everything inside them inherits the code weight.
-    declarations.push(
-      (isDark ? DARK_ATTR : ":root,body") +
-        "{--dfp-interface-weight:" +
-        interfaceWeight +
-        "}"
-    );
+  if (interfaceDelta !== WEIGHT_UNSET) {
     declarations.push(
-      weightRule(
-        "font-weight:var(--dfp-interface-weight," + interfaceWeight + ") !important"
-      )
+      (isDark ? DARK_ATTR : ":root,body") + "{--dfp-wdelta:" + interfaceDelta + "}"
     );
+    declarations.push(weightRule("font-weight:" + ladderWeight(WEIGHT_BASE) + " !important"));
     if (codeWeight === WEIGHT_UNSET) {
       // The code rules come after this one and win on their own (class hooks by
       // specificity, element selectors by order), so code surfaces — which
       // inherit nothing but start from the body weight — are reset here.
       // `normal` is what DSH computes for them (the code `font` shorthands
       // carry no weight), so an unset code weight keeps code exactly as DSH
-      // shipped it. The variable is reset alongside so an element INSIDE a code
-      // surface (which the interface table matches) lands on `normal` too.
-      declarations.push(
-        codeRule("font-weight:normal !important;--dfp-interface-weight:normal")
-      );
+      // shipped it. The offset is pinned to zero alongside so an element INSIDE
+      // a code surface (which the interface table matches) lands on `normal`
+      // too.
+      declarations.push(codeRule("font-weight:normal !important;--dfp-wdelta:0"));
     }
   }
 
@@ -1739,17 +2157,55 @@ function buildAxisCss(axis, baseTokens, isDark, hints) {
     }
   }
 
-  // ---- dialog weight (uniform inside the conversation) ----
-  if (dialogWeight !== WEIGHT_UNSET) {
-    declarations.push(dialogRule("font-weight:" + dialogWeight + " !important"));
+  // ---- dialog weight (a relative offset, applied element by element) ----
+  // The conversation cannot take one flat weight: DSH gives h1..h3 700,
+  // h4..h6/strong 600, th 500 and the rest 400, all inside `font` shorthands, so
+  // a single `font-weight: <value> !important` on the markdown scope replaced
+  // every one of them with that value — setting the axis at all flattened the
+  // headings (measured on 0.1.7-rc.2: `##` came out at the body weight). The
+  // ladder below re-states each group's own base PLUS the offset, so the
+  // hierarchy survives any offset, in both directions, and `d = 0` injects
+  // nothing at all.
+  if (dialogDelta === WEIGHT_UNSET && interfaceDelta !== WEIGHT_UNSET) {
+    // The conversation has NO offset of its own — which is exactly why it has to
+    // say so. The interface axis declares `--dfp-wdelta` on `:root,body`, so an
+    // unset conversation INHERITED it: with the interface at +80 the card showed 0
+    // for the conversation while the page rendered +80, and the first notch above
+    // it only added 20 units — a step nobody can see (measured on 0.1.7-rc.2:
+    // `delta` read 80 at the "0" position and 100 at "+1"). Pinning zero keeps
+    // "0 = leave DSH alone" true no matter what the other axes are set to.
+    declarations.push(weightScopeRule("--dfp-wdelta:0"));
+  }
+  if (dialogDelta !== WEIGHT_UNSET) {
+    // Every ladder rule reads `--dfp-wdelta`, so the conversation pins it to its
+    // own offset: the interface's value must not leak in, and an element inside
+    // a code surface inside the conversation still resolves the code offset that
+    // the code rules pin on their own surfaces. The scope itself takes the base
+    // group's weight, so text sitting directly in the container moves with the
+    // axis exactly as it did when the axis was absolute.
+    declarations.push(
+      weightScopeRule(
+        "--dfp-wdelta:" + dialogDelta + ";font-weight:" + ladderWeight(WEIGHT_BASE) + " !important"
+      )
+    );
+    var dialogLadder = weightLadderRules(weightScopeSelector());
+    for (var ladderIndex = 0; ladderIndex < dialogLadder.length; ladderIndex += 1) {
+      declarations.push(dialogLadder[ladderIndex]);
+    }
     // The card's conversation preview simulates this surface, so it takes the
-    // same weight (and is excluded from the interface rule above).
+    // same ladder (and is excluded from the interface rule above).
     declarations.push(
       (isDark ? DARK_ATTR + " " : "") +
-        ".dfp-previewDialog{font-weight:" +
-        dialogWeight +
+        ".dfp-previewDialog{--dfp-wdelta:" +
+        dialogDelta +
+        ";font-weight:" +
+        ladderWeight(WEIGHT_BASE) +
         " !important}"
     );
+    var previewLadder = weightLadderRules(".dfp-previewDialog");
+    for (var previewIndex = 0; previewIndex < previewLadder.length; previewIndex += 1) {
+      declarations.push(previewLadder[previewIndex]);
+    }
   }
 
   // ---- dialog size offset (additive, on the official content-size source) ----
@@ -1766,32 +2222,33 @@ function buildAxisCss(axis, baseTokens, isDark, hints) {
   var dialogOffsetValue = axis[SIZE_DIALOG_FIELD];
   if (dialogOffsetValue !== 0) {
     var contentSources = tokenNames(baseTokens).filter(function (name) {
-      if (!isContentToken(name)) return false;
-      var base = baseTokens[name];
-      // The source token only: the derived ones carry var()/calc() and would
-      // add the offset a second time if they were shifted as well.
-      return (
-        typeof base === "string" &&
-        base !== "" &&
-        base.indexOf("var(") === -1 &&
-        base.indexOf("calc(") === -1
-      );
+      // The source property, by NAME: `--dsh-content-font-size`. The derived
+      // members of the chain (`-delta`, `-size-secondary`, the markdown
+      // shorthands) all read it, so shifting them as well would count the offset
+      // twice.
+      if (name !== CONTENT_SIZE_SOURCE) return false;
+      return isLiteralTokenValue(baseTokens[name]);
     });
     var contentShift = shiftTokens(contentSources, baseTokens, dialogOffsetValue);
     if (contentShift.length > 0) declarations.push(rootRule(contentShift.join(";")));
-    // The `small` series is the only markdown family with literal sizes: it
-    // does not derive from the chain, so its parts and shorthands shift here.
+    // The `small` series is the only markdown family with literal sizes: it does
+    // not derive from the chain, so its parts and shorthands shift here — and
+    // ONLY it, by name. A value test cannot stand in for the name: the page also
+    // carries `--dsw-font-markdown-h1` with its var() already substituted, which
+    // looks like a literal and used to take the offset a second time (H1/H2
+    // shrank, H3 did not).
     var literals = markdownTokenNames(baseTokens).filter(function (name) {
-      var base = baseTokens[name];
-      return name.indexOf("-font-size") >= 0 && typeof base === "string" && base.indexOf("var(") === -1;
+      return (
+        isMarkdownLiteralToken(name) &&
+        name.indexOf("-font-size") >= 0 &&
+        isLiteralTokenValue(baseTokens[name])
+      );
     });
     var literalShift = shiftTokens(literals, baseTokens, dialogOffsetValue);
     if (literalShift.length > 0) declarations.push(rootRule(literalShift.join(";")));
-    // The shorthands whose size is a literal (the small series) must ride the
-    // shift too; the delta-derived shorthands flow through the chain above.
     var sizeShifted = [];
     var markdownEntries = shorthandTokens(baseTokens).filter(function (entry) {
-      return isMarkdownToken(entry.name) && entry.parts.size.indexOf("var(") === -1;
+      return isMarkdownLiteralToken(entry.name) && isLiteralTokenValue(entry.parts.size);
     });
     for (var mIndex = 0; mIndex < markdownEntries.length; mIndex += 1) {
       var mEntry = markdownEntries[mIndex];
@@ -1846,12 +2303,16 @@ function buildAxisCss(axis, baseTokens, isDark, hints) {
     if (codeScaled.length > 0) declarations.push(rootRule(codeScaled.join(";")));
   }
   if (codeWeight !== WEIGHT_UNSET) {
-    // The variable rides along so the elements INSIDE a code surface — which the
-    // interface weight rule's element table matches — resolve the code weight
-    // instead of the interface one, without any `… *` selector.
+    // The code axis is a relative offset too (all three weight axes share one
+    // scale, so the card shows one kind of control). Pinning the offset here
+    // instead of writing a flat `font-weight` keeps whatever weight a code
+    // surface ships with AND is what makes the elements INSIDE a code surface —
+    // which the interface table and the conversation ladder both match — resolve
+    // the code offset rather than the surrounding one, without any `… *`
+    // selector. `WEIGHT_BASE` is what DSH's code `font` shorthands carry.
     declarations.push(
       codeRule(
-        "font-weight:" + codeWeight + " !important;--dfp-interface-weight:" + codeWeight
+        "font-weight:" + ladderWeight(WEIGHT_BASE) + " !important;--dfp-wdelta:" + codeWeight
       )
     );
   }
@@ -2406,7 +2867,27 @@ var shared = {
   isFontToken: isFontToken,
   isCodeToken: isCodeToken,
   isMarkdownToken: isMarkdownToken,
+  isMarkdownLiteralToken: isMarkdownLiteralToken,
+  MARKDOWN_LITERAL_PREFIX: MARKDOWN_LITERAL_PREFIX,
+  CONTENT_SIZE_SOURCE: CONTENT_SIZE_SOURCE,
+  isLiteralTokenValue: isLiteralTokenValue,
+  clampWeightDelta: clampWeightDelta,
+  WEIGHT_DELTA_MIN: WEIGHT_DELTA_MIN,
+  WEIGHT_DELTA_MAX: WEIGHT_DELTA_MAX,
+  WEIGHT_BASE: WEIGHT_BASE,
+  DIALOG_WEIGHT_GROUPS: DIALOG_WEIGHT_GROUPS,
   isDeltaToken: isDeltaToken,
+  reconcileSliderValue: reconcileSliderValue,
+  WEIGHT_STEP_CANDIDATES: WEIGHT_STEP_CANDIDATES,
+  WEIGHT_DELTA_FLOOR: WEIGHT_DELTA_FLOOR,
+  WEIGHT_DELTA_CEIL: WEIGHT_DELTA_CEIL,
+  WEIGHT_LADDER_TOP: WEIGHT_LADDER_TOP,
+  WEIGHT_LADDER_STRONG: WEIGHT_LADDER_STRONG,
+  WEIGHT_DELTA_UP_LIMIT: WEIGHT_DELTA_UP_LIMIT,
+  WEIGHT_CSS_MIN: WEIGHT_CSS_MIN,
+  WEIGHT_CSS_MAX: WEIGHT_CSS_MAX,
+  weightProfileFrom: weightProfileFrom,
+  weightStepRange: weightStepRange,
   isShorthandName: isShorthandName,
   isScaledToken: isScaledToken,
   tokenNames: tokenNames,
@@ -2492,6 +2973,8 @@ var SIZE_MAX = shared.SIZE_MAX;
 var WEIGHT_MIN = shared.WEIGHT_MIN;
 var WEIGHT_MAX = shared.WEIGHT_MAX;
 var WEIGHT_UNSET = shared.WEIGHT_UNSET;
+var WEIGHT_DELTA_MIN = shared.WEIGHT_DELTA_MIN;
+var WEIGHT_DELTA_MAX = shared.WEIGHT_DELTA_MAX;
 var LINE_HEIGHT_MIN = shared.LINE_HEIGHT_MIN;
 var LINE_HEIGHT_MAX = shared.LINE_HEIGHT_MAX;
 var CODE_LINE_HEIGHT_MIN = shared.CODE_LINE_HEIGHT_MIN;
@@ -2514,6 +2997,9 @@ var normalizePresets = shared.normalizePresets;
 var normalizeValueSet = shared.normalizeValueSet;
 var parseStack = shared.parseStack;
 var quoteFamily = shared.quoteFamily;
+var reconcileSliderValue = shared.reconcileSliderValue;
+var weightProfileFrom = shared.weightProfileFrom;
+var weightStepRange = shared.weightStepRange;
 var resolveAxes = shared.resolveAxes;
 var sanitizeFamily = shared.sanitizeFamily;
 var isGenericFamilyName = shared.isGenericFamilyName;
@@ -2541,8 +3027,22 @@ var inject = ["slots", "locale"];
 var cardScope = null;
 var cardT = null;
 
-/** The weight DSH uses for body text; choosing it means "leave it alone". */
-var NEUTRAL_WEIGHT = 400;
+/**
+ * The neutral value of the two RELATIVE weight axes: an offset of zero, which
+ * means "leave every element at its own weight" and is what the slider's middle
+ * position and the "unset" state share.
+ */
+var NEUTRAL_WEIGHT = 0;
+
+/**
+ * Print a weight offset the way the slider reads it: a signed number, so `+60`
+ * and `-40` are distinguishable at a glance (plain `String(0)` for neutral).
+ * @param {number} value - the offset.
+ * @returns {string}
+ */
+function weightOffsetText(value) {
+  return value > 0 ? "+" + value : String(value);
+}
 
 /** Panel width, kept in one place because positioning reads it too. */
 var PANEL_WIDTH = 320;
@@ -2711,15 +3211,15 @@ var DICTS = {
       "Adds {offset} to code blocks and inline code only; the interface offset does not reach them. 0 keeps DSH's sizes.",
     "size.unit": "px",
 
-    "weight.uiLabel": "Interface font weight",
+    "weight.uiLabel": "Interface font-weight offset",
     "weight.uiHint":
-      "Sets the weight of the whole interface (sidebars, settings, buttons, headings). The conversation keeps its own.",
-    "weight.dialogLabel": "Conversation font weight",
+      "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.",
+    "weight.dialogLabel": "Conversation font-weight offset",
     "weight.dialogHint":
-      "Sets the weight of the conversation markdown; unset keeps DSH's own weights.",
-    "weight.codeLabel": "Code font weight",
+      "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.",
+    "weight.codeLabel": "Code font-weight offset",
     "weight.codeHint":
-      "Overrides code blocks, inline code and terminal output only. 400 or unset keeps DSH's own weight.",
+      "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.",
 
     "line.dialogLabel": "Conversation line height",
     "line.dialogHint":
@@ -2855,14 +3355,15 @@ var DICTS = {
       "只作用于代码块与行内代码，与界面字号互不影响；0 表示保持原样。",
     "size.unit": "px",
 
-    "weight.uiLabel": "界面字重",
+    "weight.uiLabel": "界面字重偏移",
     "weight.uiHint":
-      "设置整个界面的字重（侧栏、设置、按钮、标题）；对话 Markdown 不受影响。",
-    "weight.dialogLabel": "对话字重",
-    "weight.dialogHint": "设置对话 Markdown 的粗细；未设置时保持 DSH 原本的粗细。",
-    "weight.codeLabel": "代码字重",
+      "在整个界面自身的字重上叠加（侧栏、设置、按钮、标题）：正数更粗、负数更细；对话 Markdown 不受影响。滑块按当前字体实际能渲染的粗细分档，读数是档数（0 = 保持 DSH 原样）：每挪一格，正文与标题都会换一张字形；换个字体，档数也会跟着变。",
+    "weight.dialogLabel": "对话字重偏移",
+    "weight.dialogHint":
+      "在每个元素自身的字重上叠加，所以标题依旧比正文粗、加粗文字依旧加粗；未设置时保持 DSH 原本的粗细。滑块按当前字体实际能渲染的粗细分档，读数是档数（0 = 保持 DSH 原样）：每挪一格，正文与标题都会换一张字形；换个字体，档数也会跟着变。",
+    "weight.codeLabel": "代码字重偏移",
     "weight.codeHint":
-      "只覆盖代码块、行内代码与终端输出；400 或未设置表示保持 DSH 原样。",
+      "在每个代码面自身的字重上叠加（代码块、行内代码、终端输出）；0 或未设置表示保持 DSH 原样。滑块按当前字体实际能渲染的粗细分档，读数是档数（0 = 保持 DSH 原样）：每挪一格，正文与标题都会换一张字形；换个字体，档数也会跟着变。",
 
     "line.dialogLabel": "对话行高",
     "line.dialogHint": "把对话行高整体缩放为 {ratio}；100% 表示保持 DSH 原样。",
@@ -3309,6 +3810,180 @@ function readDefaultFamily(name) {
   }
 }
 
+/* ------------------------------------------------------------------ *
+ * weight granularity
+ * ------------------------------------------------------------------ */
+
+/** Sample drawn to compare two weights; mixed scripts, like the UI. */
+var WEIGHT_SAMPLE_TEXT = "对话 Aa 字重 0189";
+
+/** Canvas used for the granularity probe, created on first use. */
+var weightProbeCanvas = null;
+
+/** Cache of measured slider shapes, keyed by the resolved family stack. */
+var weightProfileCache = {};
+
+/**
+ * Render the sample at one weight and describe the result.
+ *
+ * The signature is the total ink (summed alpha) plus the advance width at high
+ * precision. Counting only fully-covered pixels would miss what a variable axis
+ * does between two named instances — a couple of units of extra alpha per glyph
+ * — and report a coarse family where the weights are in fact continuous.
+ * @param {string} stack - resolved `font-family` value.
+ * @param {number} weight - CSS weight to draw with.
+ * @returns {string} the signature; equal signatures mean identical rendering.
+ */
+function sampleWeightSignature(stack, weight) {
+  if (weightProbeCanvas === null) {
+    weightProbeCanvas = document.createElement("canvas");
+    weightProbeCanvas.width = 260;
+    weightProbeCanvas.height = 56;
+  }
+  // `willReadFrequently` matters here: the profile probe reads the canvas back once
+// per sampled weight (~80 times on the first measurement), and without it the
+// browser keeps a GPU-backed surface and warns about the readbacks — which is part
+// of why dragging the weight felt heavy.
+var context = weightProbeCanvas.getContext("2d", { willReadFrequently: true });
+  context.clearRect(0, 0, weightProbeCanvas.width, weightProbeCanvas.height);
+  context.font = weight + " 32px " + stack;
+  context.textBaseline = "top";
+  context.fillStyle = "#000";
+  context.fillText(WEIGHT_SAMPLE_TEXT, 2, 6);
+  var advance = Math.round(context.measureText(WEIGHT_SAMPLE_TEXT).width * 1000);
+  var pixels = context.getImageData(0, 0, weightProbeCanvas.width, weightProbeCanvas.height).data;
+  var ink = 0;
+  for (var index = 3; index < pixels.length; index += 4) ink += pixels[index];
+  return ink + "/" + advance;
+}
+
+/**
+ * The slider shape to use for one family: its range and its notch.
+ *
+ * A family can only be made as light or as heavy as the faces it ships, so the
+ * range is measured rather than fixed (`weightProfileFrom`), which also makes
+ * every notch a change — for every layer of the ladder, so the measurement is
+ * told which base is the heaviest one the offset lands on. Measured once per
+ * family and base and cached; any failure (no canvas, no 2D context) falls back
+ * to the nominal window with single units.
+ * @param {string} stack - resolved `font-family` value, "" for the page default.
+ * @param {number} [top] - the heaviest base the offset is added to; the ladder's
+ *   own top for the conversation and interface axes, the axis's base for code.
+ * @returns {{min: number, max: number, step: number}} the slider shape.
+ */
+function weightProfileFor(stack, top) {
+  var base = typeof top === "number" ? top : shared.WEIGHT_LADDER_TOP;
+  var key = String(stack) + "\u0000" + base;
+  if (Object.prototype.hasOwnProperty.call(weightProfileCache, key)) {
+    return weightProfileCache[key];
+  }
+  var profile = { min: WEIGHT_DELTA_MIN, max: WEIGHT_DELTA_MAX, step: 1 };
+  try {
+    var resolved = String(stack) === "" ? liveFamily() : String(stack);
+    profile = weightProfileFrom(function (weight) {
+      return sampleWeightSignature(resolved, weight);
+    }, { top: base });
+  } catch (error) {
+    profile = { min: WEIGHT_DELTA_MIN, max: WEIGHT_DELTA_MAX, step: 1 };
+  }
+  weightProfileCache[key] = profile;
+  return profile;
+}
+
+/**
+ * The family the page actually renders with, as a `font-family` value.
+ * @returns {string} the computed family, or "" when unreadable.
+ */
+function liveFamily() {
+  if (typeof document === "undefined") return "";
+  try {
+    return document.defaultView.getComputedStyle(document.body).fontFamily || "";
+  } catch (error) {
+    return "";
+  }
+}
+
+/**
+ * The conversation's own line-height ratio, measured once.
+ *
+ * The dialog line-height axis is a percentage OF DSH's own height (`28px × 1.05`),
+ * so a preview that used the percentage as an ABSOLUTE ratio was wrong twice over:
+ * at 100% it fell back to DSH's real (taller) default, while 105% asked for 1.05 —
+ * shorter than that default and out of order with the notches above it.
+ *
+ * The base is read from a hidden node carrying the markdown class whose rule
+ * consumes DSH's markdown shorthand, so it is the same ratio the page multiplies.
+ * @returns {number} line height ÷ font size; a plain default when unmeasurable.
+ */
+var DIALOG_LINE_RATIO_FALLBACK = 1.5;
+var dialogLineRatioCache = null;
+function dialogLineRatio() {
+  if (typeof dialogLineRatioCache === "number") return dialogLineRatioCache;
+  if (typeof document === "undefined" || typeof document.defaultView === "undefined") {
+    return DIALOG_LINE_RATIO_FALLBACK;
+  }
+  try {
+    var className = "";
+    var sheets = document.styleSheets || [];
+    for (var index = 0; index < sheets.length && className === ""; index += 1) {
+      var rules = null;
+      try {
+        rules = sheets[index].cssRules;
+      } catch (error) {
+        rules = null;
+      }
+      if (!rules) continue;
+      for (var ruleIndex = 0; ruleIndex < rules.length; ruleIndex += 1) {
+        var selector = rules[ruleIndex].selectorText || "";
+        var body = rules[ruleIndex].style ? rules[ruleIndex].style.cssText : "";
+        if (selector.indexOf("_markdown_") < 0) continue;
+        if (body.indexOf("--dsw-font-markdown-base") < 0) continue;
+        var found = selector.match(/\.(_markdown_[A-Za-z0-9_-]+)/);
+        if (found) className = found[1];
+      }
+    }
+    if (className !== "") {
+      var host = document.createElement("div");
+      host.className = className;
+      host.setAttribute("data-dss-prose", "");
+      host.style.position = "absolute";
+      host.style.visibility = "hidden";
+      host.style.left = "-9999px";
+      var probe = document.createElement("p");
+      probe.textContent = "line";
+      probe.style.margin = "0";
+      host.appendChild(probe);
+      document.body.appendChild(host);
+      var style = document.defaultView.getComputedStyle(probe);
+      var size = parseFloat(style.fontSize);
+      var height = parseFloat(style.lineHeight);
+      if (isFinite(size) && size > 0 && isFinite(height) && height > 0) {
+        dialogLineRatioCache = Math.round((height / size) * 10000) / 10000;
+      }
+      if (host.parentNode) host.parentNode.removeChild(host);
+    }
+  } catch (error) {
+    /* the fallback stands */
+  }
+  if (typeof dialogLineRatioCache !== "number") dialogLineRatioCache = DIALOG_LINE_RATIO_FALLBACK;
+  return dialogLineRatioCache;
+}
+
+/**
+ * The family code surfaces render with when the code axis sets none.
+ * @returns {string} the computed family, or "" when unreadable.
+ */
+function liveCodeFamily() {
+  if (typeof document === "undefined") return "";
+  try {
+    var sample = document.querySelector("pre, code, kbd, samp");
+    if (sample === null) return liveFamily();
+    return document.defaultView.getComputedStyle(sample).fontFamily || liveFamily();
+  } catch (error) {
+    return "";
+  }
+}
+
 /* ------------------------------------------------------------------ *
  * hooks and controls
  * ------------------------------------------------------------------ */
@@ -3441,17 +4116,25 @@ function NumberSlider(props) {
   // (the "bounce back, then settle" the user saw), so the local value stays
   // on screen until the confirmed value arrives.
   var awaitingRef = useRef(null);
+  // The same value as `pending`, readable without a render: the reconciliation
+  // below runs from an effect that only depends on the incoming value.
+  var pendingRef = useRef(null);
+  var setLocal = function (value) {
+    pendingRef.current = value;
+    setPending(value);
+  };
   useEffect(
     function () {
-      if (awaitingRef.current === null) {
-        // idle: any value that arrives from outside (reset, another page) wins
-        setPending(null);
-        return undefined;
-      }
-      if (props.value === awaitingRef.current) {
-        awaitingRef.current = null;
-        setPending(null);
-      }
+      // `reconcileSliderValue` owns the decision (and is unit-tested): keeping
+      // the local value while the user is mid-drag is what stops a late
+      // confirmation from snapping the thumb back to the previous value.
+      var next = reconcileSliderValue({
+        pending: pendingRef.current,
+        awaiting: awaitingRef.current,
+        confirmed: props.value,
+      });
+      awaitingRef.current = next.awaiting;
+      setLocal(next.pending);
       return undefined;
     },
     [props.value]
@@ -3460,12 +4143,39 @@ function NumberSlider(props) {
     awaitingRef.current = value;
     props.onChange(value);
   };
+  /**
+   * Stop holding a value the host never confirmed.
+   *
+   * The local value is kept until the document echoes it back, which is what
+   * stops the "bounce back, then settle" flicker — but a write the host REFUSES
+   * (an out-of-range value against an older schema, a read-only deployment) never
+   * echoes, and the slider would then sit on a value the document does not have,
+   * i.e. it would look like it jumped somewhere else and stayed there. The
+   * document is the truth, so after a few seconds the local value yields to it.
+   */
+  var COMMIT_PATIENCE_MS = 6000;
+  useEffect(
+    function () {
+      if (awaitingRef.current === null) return undefined;
+      var timer = setTimeout(function () {
+        awaitingRef.current = null;
+        setLocal(null);
+      }, COMMIT_PATIENCE_MS);
+      return function () {
+        clearTimeout(timer);
+      };
+    },
+    [pending]
+  );
   useEffect(
     function () {
       if (pending === null) return undefined;
       var release = function () {
-        // one release per drag; a late pointerup must not rewrite the same value
-        if (awaitingRef.current !== null) return;
+        // One release per drag: a late pointerup must not rewrite the SAME value.
+        // The guard compares values instead of "is anything outstanding" — a
+        // commit still waiting for the document must not swallow the next drag's
+        // release, which silently dropped that adjustment on a slow host.
+        if (awaitingRef.current === pending) return;
         commit(pending);
       };
       window.addEventListener("pointerup", release, true);
@@ -4445,11 +5155,19 @@ function SimpleFamilyField(props) {
  * @param {boolean} uiFollows - whether the interface follows the conversation.
  * @param {(key: string, params?: object) => string} t - translate seat.
  * @returns {{ui: string, dialog: string, code: string}}
+ * @param {(field: string, value: number) => number} [weightCount] - turns a
+ *   stored weight offset into the number of font steps the sliders show, so a
+ *   collapsed section reads "+2" exactly like the open slider does.
  */
-function sectionSummaries(axis, uiFollows, t) {
+function sectionSummaries(axis, uiFollows, t, weightCount) {
   var sign = function (value) {
     return value > 0 ? "+" + value : String(value);
   };
+  var weight = function (field, value) {
+    return typeof weightCount === "function"
+      ? weightOffsetText(weightCount(field, value))
+      : weightOffsetText(value);
+  };
   // The conversation owns every axis, so its summary is always its values.
   var dialogParts = [];
   if (axis[STACK_DIALOG_FIELD] !== "") dialogParts.push(firstFamily(axis[STACK_DIALOG_FIELD]));
@@ -4458,7 +5176,7 @@ function sectionSummaries(axis, uiFollows, t) {
     dialogParts.push(axis[LINE_HEIGHT_DIALOG_FIELD] + "%");
   }
   if (axis[WEIGHT_DIALOG_FIELD] !== WEIGHT_UNSET) {
-    dialogParts.push(String(axis[WEIGHT_DIALOG_FIELD]));
+    dialogParts.push(weight(WEIGHT_DIALOG_FIELD, axis[WEIGHT_DIALOG_FIELD]));
   }
   // The interface either follows (nothing of its own to report) or shows the
   // two axes it owns.
@@ -4466,13 +5184,15 @@ function sectionSummaries(axis, uiFollows, t) {
   if (!uiFollows) {
     var family = axis[SANS_FIELD] === "" ? null : firstFamily(axis[SANS_FIELD]);
     if (family !== null) uiParts.push(family);
-    if (axis[WEIGHT_FIELD] !== WEIGHT_UNSET) uiParts.push(String(axis[WEIGHT_FIELD]));
+    if (axis[WEIGHT_FIELD] !== WEIGHT_UNSET) uiParts.push(weight(WEIGHT_FIELD, axis[WEIGHT_FIELD]));
   }
   var codeParts = [];
   if (axis[MONO_FIELD] !== "") codeParts.push(firstFamily(axis[MONO_FIELD]));
   if (axis[CODE_SIZE_FIELD] !== 0) codeParts.push(sign(axis[CODE_SIZE_FIELD]) + "px");
   if (axis[CODE_LINE_HEIGHT_FIELD] !== 0) codeParts.push(sign(axis[CODE_LINE_HEIGHT_FIELD]) + "px");
-  if (axis[CODE_WEIGHT_FIELD] !== WEIGHT_UNSET) codeParts.push(String(axis[CODE_WEIGHT_FIELD]));
+  if (axis[CODE_WEIGHT_FIELD] !== WEIGHT_UNSET) {
+    codeParts.push(weight(CODE_WEIGHT_FIELD, axis[CODE_WEIGHT_FIELD]));
+  }
   if (axis[LIGATURES_FIELD] !== LIGATURES_DEFAULT) {
     codeParts.push(t(axis[LIGATURES_FIELD] === LIGATURES_OFF ? "lig.off" : "lig.on"));
   }
@@ -4760,7 +5480,28 @@ function FontCard(props) {
   };
 
   // ---- weight slider ----
+  // All three weight axes share one shape: an offset added to each element's own
+  // weight, centred on zero (code included — its surfaces ship their own weight
+  // too, and an offset keeps any bold element inside them bold).
+  //
+  // The CONTROL counts the family's own steps ("-2 -1 0 +1 +2 +3 +4"), because a
+  // family can only be made as light or as heavy as the faces it ships and only
+  // in steps between them: how many positions there are is a property of the font,
+  // measured on the page. The VALUE written to the document stays a weight offset,
+  // so nothing stored before has to be migrated and the stylesheet is unchanged.
   var weightField = function (props) {
+    var profile = weightProfileFor(
+      props.stack === undefined ? "" : props.stack,
+      props.top === undefined ? shared.WEIGHT_LADDER_STRONG : props.top
+    );
+    var stored = props.value === WEIGHT_UNSET ? NEUTRAL_WEIGHT : props.value;
+    // A stored offset outside the measured range (the font changed since it was
+    // set) widens the control, so it is never unreachable.
+    var shape = weightStepRange(
+      { min: Math.min(profile.min, stored), max: Math.max(profile.max, stored), step: profile.step },
+      stored
+    );
+    var text = weightOffsetText;
     return h(
       FieldShell,
       {
@@ -4774,22 +5515,27 @@ function FontCard(props) {
         },
       },
       h(NumberSlider, {
-        min: WEIGHT_MIN,
-        max: WEIGHT_MAX,
-        value: props.value === WEIGHT_UNSET ? NEUTRAL_WEIGHT : props.value,
+        min: shape.min,
+        max: shape.max,
+        value: shape.value,
         disabled: !writable,
         label: t(props.labelKey),
-        // "Unset" IS 400 here: that is the weight DSH uses for body text, the
-        // slider already sits at 400, and the hint says 400 keeps DSH's own.
-        // Printing "unset" made the readout disagree with the control.
-        readout: String(props.value === WEIGHT_UNSET ? NEUTRAL_WEIGHT : props.value),
-        minLabel: String(WEIGHT_MIN),
-        maxLabel: String(WEIGHT_MAX),
-        onChange: function (value) {
-          // 400 is DSH's own body weight, so choosing it means "leave the axis
-          // alone" rather than "write 400 on every element".
-          if (value === NEUTRAL_WEIGHT) resetField(props.field);
-          else setField(props.field, value);
+        // 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
+        // bolder, and the numbers stay small whatever the family is.
+        readout: text(shape.value),
+        minLabel: text(shape.min),
+        maxLabel: text(shape.max),
+        // The pending readout goes through the same formatter: without it the
+        // sign only appeared on release ("80" while dragging, then "+80" once
+        // the document confirmed it).
+        pendingText: text,
+        onChange: function (count) {
+          // The neutral position means "leave the axis alone" rather than "write
+          // it on every element".
+          if (count === 0) resetField(props.field);
+          else setField(props.field, count * shape.unit);
         },
       })
     );
@@ -5146,33 +5892,59 @@ function FontCard(props) {
   // fallback. The switch lives in the interface section.
   var uiFollows = config[UI_FOLLOWS_FIELD] !== false;
 
-  var summaries = sectionSummaries(editing, uiFollows, t);
+  // The family each weight axis is measured against: the configured stack when
+  // there is one, the page's own family otherwise. Resolved once, so the
+  // collapsed summaries, the sliders and the previews all agree on the count.
+  var uiStack =
+    editing[SANS_FIELD] !== "" ? formatStack(parseStack(editing[SANS_FIELD])) : "";
+  var dialogFallbackFamily =
+    typeof FALLBACK_TOKENS["--dsw-font-family"] === "string" ? FALLBACK_TOKENS["--dsw-font-family"] : "";
+  var dialogStack =
+    editing[STACK_DIALOG_FIELD] !== ""
+      ? formatStack(parseStack(editing[STACK_DIALOG_FIELD]))
+      : dialogFallbackFamily;
+  var codeStack =
+    editing[MONO_FIELD] !== "" ? formatStack(parseStack(editing[MONO_FIELD])) : liveCodeFamily();
+  /**
+   * One weight offset, as the number of family steps the reader sees.
+   * @param {string} field - which weight axis.
+   * @param {number} value - the stored offset.
+   * @returns {number} the step count.
+   */
+  var weightCount = function (field, value) {
+    var isCode = field === CODE_WEIGHT_FIELD;
+    var stack =
+      field === WEIGHT_DIALOG_FIELD ? dialogStack : isCode ? codeStack : uiStack;
+    var profile = weightProfileFor(stack, isCode ? shared.WEIGHT_BASE : shared.WEIGHT_LADDER_STRONG);
+    return weightStepRange(profile, value === WEIGHT_UNSET ? 0 : value).value;
+  };
+
+  var summaries = sectionSummaries(editing, uiFollows, t, weightCount);
 
   // The interface owns one axis now (its family); its preview shows that and
   // nothing else — the weight, size and line height all come from the
   // conversation section.
   var previewUiStyle = {};
-  if (editing[SANS_FIELD] !== "") {
-    previewUiStyle.fontFamily = formatStack(parseStack(editing[SANS_FIELD]));
-  }
+  if (uiStack !== "") previewUiStyle.fontFamily = uiStack;
   var previewDialogStyle = {};
-  if (editing[STACK_DIALOG_FIELD] !== "") {
-    previewDialogStyle.fontFamily = formatStack(parseStack(editing[STACK_DIALOG_FIELD]));
-  } else {
-    // Independent and unset: the conversation keeps DSH's own family, so the
-    // preview shows the theme's default rather than the interface stack the
-    // page rule would otherwise paint into this box.
-    var dialogFallback = FALLBACK_TOKENS["--dsw-font-family"];
-    if (typeof dialogFallback === "string" && dialogFallback !== "") {
-      previewDialogStyle.fontFamily = dialogFallback;
-    }
-  }
+  // Independent and unset: the conversation keeps DSH's own family, so the
+  // preview shows the theme's default rather than the interface stack the page
+  // rule would otherwise paint into this box.
+  if (dialogStack !== "") previewDialogStyle.fontFamily = dialogStack;
   previewDialogStyle.fontSize = 13 + editing[SIZE_DIALOG_FIELD] + "px";
-  if (editing[LINE_HEIGHT_DIALOG_FIELD] !== LINE_HEIGHT_MIN) {
-    previewDialogStyle.lineHeight = String(editing[LINE_HEIGHT_DIALOG_FIELD] / 100);
-  }
+  // The axis is a percentage OF DSH's own line height, so the preview multiplies the
+  // measured base by the same percentage — and does it at every notch including 100,
+  // or the preview would show a shorter line at 105% than at 100%.
+  previewDialogStyle.lineHeight = String(
+    Math.round(dialogLineRatio() * (editing[LINE_HEIGHT_DIALOG_FIELD] / LINE_HEIGHT_MIN) * 10000) /
+      10000
+  );
   if (editing[WEIGHT_DIALOG_FIELD] !== WEIGHT_UNSET) {
-    previewDialogStyle.fontWeight = editing[WEIGHT_DIALOG_FIELD];
+    // The offset, not a weight: the injected stylesheet's conversation ladder
+    // reads `--dfp-wdelta` on this very class and re-states each element's own
+    // base plus the offset, so the preview shows the same hierarchy the
+    // conversation does instead of one flat weight.
+    previewDialogStyle["--dfp-wdelta"] = editing[WEIGHT_DIALOG_FIELD];
   }
   var previewCodeStyle = {};
   if (editing[MONO_FIELD] !== "") {
@@ -5423,6 +6195,7 @@ function FontCard(props) {
               labelKey: "weight.dialogLabel",
               hintKey: "weight.dialogHint",
               value: editing[WEIGHT_DIALOG_FIELD],
+              stack: dialogStack,
             }),
             h(
               "div",
@@ -5509,6 +6282,7 @@ function FontCard(props) {
                   labelKey: "weight.uiLabel",
                   hintKey: "weight.uiHint",
                   value: editing[WEIGHT_FIELD],
+                  stack: uiStack,
                 }),
             h(
               "div",
@@ -5551,6 +6325,11 @@ function FontCard(props) {
               labelKey: "weight.codeLabel",
               hintKey: "weight.codeHint",
               value: editing[CODE_WEIGHT_FIELD],
+              // The code axis puts one weight on the whole surface, so its own base
+              // is the heaviest layer there is: any lower base would cap the range
+              // short of what code text can actually reach.
+              top: shared.WEIGHT_BASE,
+              stack: codeStack,
             }),
             ligatureField(),
             view === "advanced" ? featuresField() : null,