dsh-fonttune 0.2.7 → 0.3.1

package/lib/shared.cjs

@@ -134,11 +134,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;
@@ -354,7 +448,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);
@@ -426,6 +520,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.
@@ -943,6 +1064,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.
  */
@@ -1021,6 +1164,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).
@@ -1258,8 +1425,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`.
@@ -1351,16 +1517,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",
@@ -1512,6 +1681,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.
@@ -1537,9 +1896,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 &&
@@ -1572,8 +1931,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 = [];
@@ -1610,24 +1970,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
@@ -1685,39 +2107,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.
+  if (interfaceDelta !== WEIGHT_UNSET) {
     declarations.push(
-      (isDark ? DARK_ATTR : ":root,body") +
-        "{--dfp-interface-weight:" +
-        interfaceWeight +
-        "}"
-    );
-    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"));
     }
   }
 
@@ -1730,17 +2148,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) ----
@@ -1757,32 +2213,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];
@@ -1837,12 +2294,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
       )
     );
   }
@@ -2397,7 +2858,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,