dsh-fonttune 0.3.4 → 0.3.5

package/lib/index.js

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

package/lib/shared.cjs

@@ -77,6 +77,23 @@ var WEIGHT_DIALOG_FIELD = "weightDialog";
 /** Field carrying the code font weight (0 = leave DSH alone). */
 var CODE_WEIGHT_FIELD = "weightCode";
 
+/**
+ * Marks a document whose weight fields are OFFSETS, not absolute weights.
+ *
+ * Before 0.2.8 the three weight axes stored an absolute CSS weight (`300…600`,
+ * `400` = normal) and `clampWeightDelta` converted one on sight. That inference
+ * only works while offsets never land inside the absolute window, which capped
+ * the offset range at +200 — and +200 is not enough room for a step the eye can
+ * see on a family with few faces (measured: one 200-weight step is a +30% change
+ * on Noto Serif SC, one 100-weight step only +16%).
+ *
+ * So the document says which scale it is on, and the inference is borrowed for
+ * exactly one write: the first time 0.3.5+ writes a weight, the card converts any
+ * remaining absolute value, converts the saved presets the same way, and sets
+ * this field. From then on a stored weight is an offset, whatever its size.
+ */
+var WEIGHT_OFFSETS_FIELD = "weightOffsets";
+
 /**
  * Field carrying the interface line-height ratio in percent (100 = untouched).
  * A ratio rather than a px offset: interface line heights form a design ladder
@@ -208,17 +225,18 @@ var WEIGHT_LADDER_TOP = DIALOG_WEIGHT_GROUPS.reduce(function (top, group) {
 /**
  * How far above its base an offset may reach at all.
  *
- * Every axis applies the offset to each element's OWN weight, and the heaviest
- * layer of the ladder sits at `WEIGHT_LADDER_TOP`; past `WEIGHT_CSS_MAX` minus
- * that, the heaviest layer cannot move any further, so a longer range would only
- * add positions that change nothing for the boldest text on screen.
+ * The ceiling comes from the layer a notch MUST move: body text sits at
+ * `WEIGHT_BASE`, so the range runs as far as the text a reader is reading can
+ * still change — measured up to +400 on a family whose faces reach 900. Bold text
+ * stops moving at +300 and headings at +200; that is accepted, because a heading
+ * already at its heaviest face stays there (see `WEIGHT_LADDER_STRONG`).
  *
- * Staying inside it has a second, load-bearing effect: offsets then never land in
- * `WEIGHT_MIN…WEIGHT_MAX`, the range an ABSOLUTE weight from a pre-relative
- * document occupies (see `clampWeightDelta`). The two meanings cannot be confused,
- * so a stored offset is never rescaled into a different one.
+ * It used to stop at `WEIGHT_CSS_MAX - WEIGHT_LADDER_TOP` (= +200) so an offset
+ * could never land inside `WEIGHT_MIN…WEIGHT_MAX`, the window an ABSOLUTE weight
+ * from a pre-relative document occupies. The document's own marker resolves that
+ * window now (`WEIGHT_OFFSETS_FIELD`), so the range is free to grow.
  */
-var WEIGHT_DELTA_UP_LIMIT = WEIGHT_CSS_MAX - WEIGHT_LADDER_TOP;
+var WEIGHT_DELTA_UP_LIMIT = WEIGHT_CSS_MAX - WEIGHT_BASE;
 
 /**
  * The heaviest layer a notch still has to move: bold text.
@@ -314,9 +332,12 @@ var VALUE_FIELDS = [
 var RETIRED_FIELDS = [SIZE_FIELD, LINE_HEIGHT_FIELD];
 
 /**
- * Every durable axis field, live and retired: what normalization covers.
+ * Every durable field normalization covers: the live axes, the retired pair, and
+ * the scale marker (`WEIGHT_OFFSETS_FIELD`, which is deliberately NOT a value
+ * axis — a preset must never carry it, or applying that preset would re-label a
+ * document still holding absolute weights).
  */
-var DURABLE_FIELDS = VALUE_FIELDS.concat(RETIRED_FIELDS);
+var DURABLE_FIELDS = VALUE_FIELDS.concat(RETIRED_FIELDS, [WEIGHT_OFFSETS_FIELD]);
 
 /**
  * Longest accepted font stack, in characters (mirrored by the host schema).
@@ -435,7 +456,7 @@ var FEATURES_UNSAFE = /[^a-zA-Z0-9"' ,]/g;
  * ------------------------------------------------------------------ */
 
 /** Clamp/validate one field by name (shared by config and value sets). */
-function normalizeField(field, value) {
+function normalizeField(field, value, relative) {
   switch (field) {
     case SANS_FIELD:
     case STACK_DIALOG_FIELD:
@@ -448,7 +469,7 @@ function normalizeField(field, value) {
     case WEIGHT_FIELD:
     case WEIGHT_DIALOG_FIELD:
     case CODE_WEIGHT_FIELD:
-      return clampWeightDelta(value);
+      return clampWeightDelta(value, relative);
     case LINE_HEIGHT_FIELD:
     case LINE_HEIGHT_DIALOG_FIELD:
       return clampRatio(value);
@@ -456,6 +477,9 @@ function normalizeField(field, value) {
       return clampLineOffset(value);
     case LIGATURES_FIELD:
       return clampLigatures(value);
+    case WEIGHT_OFFSETS_FIELD:
+      // The document's own scale marker: false/absent = the pre-relative scale.
+      return toBool(value);
     case FEATURES_FIELD:
       return sanitizeFeatures(value);
     case NO_SYNTHETIC_ITALIC_FIELD:
@@ -479,14 +503,17 @@ function normalizeField(field, value) {
  */
 function normalizeConfig(value) {
   var source = value !== null && typeof value === "object" ? value : {};
+  // The scale marker is read BEFORE the axes: it decides whether a weight inside
+  // `300…600` is a legacy absolute value or an offset (see `clampWeightDelta`).
+  var relative = toBool(source[WEIGHT_OFFSETS_FIELD]);
   var config = {};
   for (var index = 0; index < DURABLE_FIELDS.length; index += 1) {
     var field = DURABLE_FIELDS[index];
-    config[field] = normalizeField(field, source[field]);
+    config[field] = normalizeField(field, source[field], relative);
   }
   config[PER_THEME_FIELD] = toBool(source[PER_THEME_FIELD]);
-  config[DARK_VALUES_FIELD] = normalizeDarkValues(source[DARK_VALUES_FIELD]);
-  config[PRESETS_FIELD] = normalizePresets(source[PRESETS_FIELD]);
+  config[DARK_VALUES_FIELD] = normalizeDarkValues(source[DARK_VALUES_FIELD], relative);
+  config[PRESETS_FIELD] = normalizePresets(source[PRESETS_FIELD], relative);
   config[ACTIVE_PRESET_FIELD] = sanitize(source[ACTIVE_PRESET_FIELD]).slice(0, MAX_PRESET_NAME);
   return config;
 }
@@ -524,21 +551,21 @@ function clampWeight(value) {
  * Clamp one RELATIVE weight to its allowed range, migrating an absolute value.
  *
  * A document written before the axes became relative stores an absolute weight
- * (`300…600`, `400` = normal). That window sits entirely outside the delta
- * window, so the conversion is unambiguous and idempotent: a value inside
- * `300…600` is old and becomes its distance from normal (`400 → 0`, `560 → +160`,
- * `300 → −100`), while a value already inside `−100…200` is a delta and is left
- * alone. The user's saved setup therefore keeps meaning "as bold as before"
- * instead of jumping to the top of the new scale.
+ * (`300…600`, `400` = normal) and has no marker, so a value inside `300…600` is
+ * converted to its distance from normal (`400 → 0`, `560 → +160`, `300 → −100`).
+ * A marked document is on the offset scale already and is never converted — that
+ * is what lets an offset grow past `+200` without being mistaken for one of those
+ * absolute values (the two windows overlap; see `WEIGHT_OFFSETS_FIELD`).
  *
  * @param {unknown} value - candidate offset, or a pre-0.2.8 absolute weight.
+ * @param {boolean} [relative] - true when the document carries the offset marker.
  * @returns {number} the offset the stylesheet may use.
  */
-function clampWeightDelta(value) {
+function clampWeightDelta(value, relative) {
   var delta = Number(value);
   if (!isFinite(delta)) return WEIGHT_UNSET;
   delta = Math.round(delta);
-  if (delta >= WEIGHT_MIN && delta <= WEIGHT_MAX) delta -= WEIGHT_BASE;
+  if (relative !== true && delta >= WEIGHT_MIN && delta <= WEIGHT_MAX) delta -= WEIGHT_BASE;
   // The slider's own range comes from the font (see `weightProfileFrom`) and can
   // reach further than the nominal one, so the hard bounds are the widest range
   // any font-derived slider may use.
@@ -586,13 +613,13 @@ function clampLigatures(value) {
  * @param {unknown} values - candidate map.
  * @returns {Record<string, string|number|boolean>} the safe subset.
  */
-function normalizeValueSet(values) {
+function normalizeValueSet(values, relative) {
   var out = {};
   if (values === null || typeof values !== "object" || Array.isArray(values)) return out;
   for (var index = 0; index < VALUE_FIELDS.length; index += 1) {
     var field = VALUE_FIELDS[index];
     if (!Object.prototype.hasOwnProperty.call(values, field)) continue;
-    out[field] = normalizeField(field, values[field]);
+    out[field] = normalizeField(field, values[field], relative);
   }
   return out;
 }
@@ -602,7 +629,7 @@ function normalizeValueSet(values) {
  * @param {unknown} value - candidate JSON text or object.
  * @returns {Record<string, string|number|boolean>} the sparse override map.
  */
-function normalizeDarkValues(value) {
+function normalizeDarkValues(value, relative) {
   if (typeof value === "string") {
     if (value.trim() === "") return {};
     try {
@@ -611,7 +638,70 @@ function normalizeDarkValues(value) {
       return {};
     }
   }
-  return normalizeValueSet(value);
+  return normalizeValueSet(value, relative);
+}
+
+/** The three axes that share the weight scale (and its marker). */
+var WEIGHT_FIELDS = [WEIGHT_FIELD, WEIGHT_DIALOG_FIELD, CODE_WEIGHT_FIELD];
+
+/**
+ * Convert the weight fields of saved preset snapshots to offsets.
+ *
+ * Runs exactly once per document, right before the card sets
+ * `WEIGHT_OFFSETS_FIELD`: a snapshot saved before 0.2.8 holds an absolute weight,
+ * and once the document is marked a stored weight is an offset, so applying that
+ * snapshot later would read `450` as +450 instead of +50. Converting the snapshots
+ * in the same breath as the document keeps the two on one scale.
+ *
+ * Only values inside the legacy absolute window are touched, so a snapshot that
+ * already holds offsets (any 0.3.x one) comes back unchanged and `changed` stays
+ * false — the caller then writes nothing.
+ *
+ * @param {unknown} presets - normalized presets, or anything shaped like them.
+ * @returns {{presets: object[], changed: boolean}} the converted list.
+ */
+function migratePresetWeights(presets) {
+  if (!Array.isArray(presets)) return { presets: [], changed: false };
+  var changed = false;
+  var out = [];
+  for (var index = 0; index < presets.length; index += 1) {
+    var entry = presets[index];
+    if (entry === null || typeof entry !== "object" || entry.values === null) {
+      out.push(entry);
+      continue;
+    }
+    var values = entry.values;
+    if (typeof values !== "object") {
+      out.push(entry);
+      continue;
+    }
+    var converted = null;
+    for (var axis = 0; axis < WEIGHT_FIELDS.length; axis += 1) {
+      var field = WEIGHT_FIELDS[axis];
+      if (!Object.prototype.hasOwnProperty.call(values, field)) continue;
+      var stored = Number(values[field]);
+      if (!isFinite(stored) || stored < WEIGHT_MIN || stored > WEIGHT_MAX) continue;
+      if (converted === null) {
+        converted = {};
+        for (var key in values) {
+          if (Object.prototype.hasOwnProperty.call(values, key)) converted[key] = values[key];
+        }
+      }
+      converted[field] = stored - WEIGHT_BASE;
+    }
+    if (converted === null) {
+      out.push(entry);
+      continue;
+    }
+    changed = true;
+    var copy = {};
+    for (var name in entry) {
+      if (Object.prototype.hasOwnProperty.call(entry, name)) copy[name] = entry[name];
+    }
+    copy.values = converted;
+    out.push(copy);
+  }
+  return { presets: out, changed: changed };
 }
 
 /**
@@ -619,7 +709,7 @@ function normalizeDarkValues(value) {
  * @param {unknown} value - candidate JSON text or array.
  * @returns {{name: string, values: object, savedAt: number}[]}
  */
-function normalizePresets(value) {
+function normalizePresets(value, relative) {
   var list = value;
   if (typeof value === "string") {
     if (value.trim() === "") return [];
@@ -639,7 +729,7 @@ function normalizePresets(value) {
     var stamp = Math.round(Number(entry.savedAt));
     out.push({
       name: name,
-      values: normalizeValueSet(entry.values),
+      values: normalizeValueSet(entry.values, relative),
       savedAt: isFinite(stamp) && stamp > 0 ? stamp : 0,
     });
   }
@@ -1692,6 +1782,17 @@ function resolveAxes(config) {
  */
 var WEIGHT_STEP_CANDIDATES = [1, 5, 10, 25, 50, 100, 200, 300];
 
+/**
+ * How many positions a slider must still offer before a coarser step is refused.
+ *
+ * Coarseness is the point (see `weightProfileFrom`), but a control with two
+ * positions is not a slider. Four is the smallest count that still lets a reader
+ * go one notch either side of the neutral position and one further up — and on
+ * the measured seven-face family it lands on a 200-weight step, where one notch is
+ * a +30% change in ink, against +16% at 100 (which is why 100 was not enough).
+ */
+var WEIGHT_MIN_POSITIONS = 4;
+
 /** The weight grid the profile is measured on. */
 var WEIGHT_PROBE_LOW = 100;
 var WEIGHT_PROBE_HIGH = 900;
@@ -1733,19 +1834,28 @@ function everyPositionDiffers(sample, bases, min, max, step) {
 /**
  * The slider a family deserves: how far it can go, and by how much.
  *
- * A font with six faces can be made lighter or heavier only as far as those faces
- * reach, and only in steps between them; a family with a continuous axis gets a
- * fine step and a wide range. Measured on a weight grid:
+ * A font can be made lighter or heavier only as far as its faces reach, and only
+ * in jumps between them. Measured on a weight grid:
  *  - the downward reach is the highest weight that still renders as light as the
  *    family can (asking for less cannot change anything);
- *  - the upward reach is the LOWEST weight at or above the layer a notch has to
- *    move that already renders as heavy as the family can, so the range ends where
- *    bold text stops changing instead of running past it (see `WEIGHT_DELTA_UP_LIMIT`
- *    for why that ceiling is also the widest one allowed);
- *  - the step is the finest candidate whose positions all differ at every base a
- *    notch has to move, so no notch is a no-op for body text or bold text. A family whose faces are unevenly spaced
- *    (a 700 next to a 900) may end up with one repeated position whichever uniform
- *    step is used — the coarsest candidate is then the honest answer, never a crash.
+ *  - the upward reach is the LOWEST weight at or above body text that already
+ *    renders as heavy as the family can, so the range ends where the text a reader
+ *    is reading stops changing (see `WEIGHT_DELTA_UP_LIMIT` for the ceiling);
+ *  - the step is the COARSEST candidate that still leaves `WEIGHT_MIN_POSITIONS`
+ *    positions with body text changing at every one of them. Coarse is the point:
+ *    a finer step splits one face into several positions that all render the same,
+ *    so the control feels dead (measured on Noto Serif SC, whose faces are
+ *    100-250 / 300 / 400 / 500 / 600 / 700 / 800-900: one 100-weight step is a
+ *    +16% change in ink, one 200-weight step +30%).
+ *
+ * Bold text and headings are deliberately NOT required to change at every
+ * position: the heaviest ladder layer sits at 600 and reaches the ceiling at +300,
+ * so no range can move it further. Body text is what a reader reads, so it carries
+ * the requirement, and a heading already at its boldest face stays there.
+ *
+ * Every position is a whole number of steps from 0, so the card's step counts map
+ * back onto exactly the offsets the document stores.
+ *
  * @param {(weight: number) => string|number} sample - renders a probe at one
  *   weight and returns a signature; equal signatures mean identical rendering.
  * @param {{candidates?: number[], floor?: number, ceil?: number, top?: number}}
@@ -1793,27 +1903,49 @@ function weightProfileFrom(sample, options) {
   }
   var reachUp = Math.min(ceil, WEIGHT_DELTA_UP_LIMIT, headroom);
   var reachDown = Math.max(floor, Math.min(0, lightest - WEIGHT_BASE));
-  var bases = top === WEIGHT_BASE ? [WEIGHT_BASE] : [WEIGHT_BASE, top];
-  for (var index = 0; index < candidates.length; index += 1) {
+  var cap = Math.min(reachUp, WEIGHT_DELTA_UP_LIMIT);
+  /**
+   * The shape one candidate step describes.
+   *
+   * Every position is a whole number of steps from 0, so the card's step counts
+   * multiply back into exactly the offsets the document stores. The reach is
+   * snapped to that grid without ever passing the hard floor or the ceiling —
+   * rounding the top UP (which the first version did) put a position past the
+   * widest allowed offset, and rounding the bottom DOWN could pass the floor.
+   */
+  var shapeAt = function (step) {
+    var down = Math.min(ceilTo(-reachDown, step), floorTo(-floor, step));
+    return { min: -down, max: floorTo(cap, step), step: step };
+  };
+  var best = null;
+  var bestCount = 0;
+  // Coarsest candidate first: the coarsest step that still leaves enough visible
+  // positions is the one a reader can actually work with.
+  for (var index = candidates.length - 1; index >= 0; index -= 1) {
     var step = candidates[index];
     if (!(step > 0)) continue;
-    var min = floorTo(reachDown, step);
-    // Rounding up to the step must not push the range past the limit: the widest
-    // offset has to stay out of the absolute-weight window.
-    var max = Math.min(ceilTo(reachUp, step), WEIGHT_DELTA_UP_LIMIT);
-    // A step wider than the range would leave only one reachable position.
-    if (max > min && step > max - min) continue;
-    if (everyPositionDiffers(sample, bases, min, max, step)) {
-      return { min: min, max: max, step: step };
+    var shape = shapeAt(step);
+    if (shape.max < shape.min) continue;
+    if (!everyPositionDiffers(sample, [WEIGHT_BASE], shape.min, shape.max, step)) continue;
+    var count = (shape.max - shape.min) / step + 1;
+    if (count >= WEIGHT_MIN_POSITIONS) return shape;
+    if (count > bestCount) {
+      best = shape;
+      bestCount = count;
     }
   }
+  if (best !== null) {
+    // Fewer positions than asked for is still usable; one position is the whole
+    // range, and any step describes it, so use the finest and keep the unit small.
+    if (best.max === best.min) return { min: best.min, max: best.max, step: 1 };
+    return best;
+  }
+  // No step kept body text alive: the coarsest one that still fits is the honest
+  // answer, never a step the control cannot reach.
   var coarsest = candidates[candidates.length - 1];
-  var min = floorTo(reachDown, coarsest);
-  var max = Math.min(ceilTo(reachUp, coarsest), WEIGHT_DELTA_UP_LIMIT);
-  // Nothing kept every position alive: the coarsest step that still fits is the
-  // honest answer, never a step the control cannot reach.
-  var span = max - min;
-  return { min: min, max: max, step: span > 0 ? Math.min(coarsest, span) : 1 };
+  var plain = shapeAt(coarsest);
+  var span = plain.max - plain.min;
+  return { min: plain.min, max: plain.max, step: span > 0 ? Math.min(coarsest, span) : 1 };
 }
 
 /**
@@ -1896,9 +2028,11 @@ function isDormant(config) {
     sanitize(axis[MONO_FIELD]) === "" &&
     clampOffset(axis[SIZE_DIALOG_FIELD]) === 0 &&
     clampOffset(axis[CODE_SIZE_FIELD]) === 0 &&
-    clampWeightDelta(axis[WEIGHT_FIELD]) === WEIGHT_UNSET &&
-    clampWeightDelta(axis[WEIGHT_DIALOG_FIELD]) === WEIGHT_UNSET &&
-    clampWeightDelta(axis[CODE_WEIGHT_FIELD]) === WEIGHT_UNSET &&
+    // These arrive normalized, so they are offsets already: converting them again
+    // would rescale an offset that legitimately sits inside `300…600`.
+    clampWeightDelta(axis[WEIGHT_FIELD], true) === WEIGHT_UNSET &&
+    clampWeightDelta(axis[WEIGHT_DIALOG_FIELD], true) === WEIGHT_UNSET &&
+    clampWeightDelta(axis[CODE_WEIGHT_FIELD], true) === WEIGHT_UNSET &&
     clampRatio(axis[LINE_HEIGHT_DIALOG_FIELD]) === LINE_HEIGHT_MIN &&
     clampLineOffset(axis[CODE_LINE_HEIGHT_FIELD]) === 0 &&
     clampLigatures(axis[LIGATURES_FIELD]) === LIGATURES_DEFAULT &&
@@ -2778,6 +2912,9 @@ var shared = {
   WEIGHT_FIELD: WEIGHT_FIELD,
   WEIGHT_DIALOG_FIELD: WEIGHT_DIALOG_FIELD,
   CODE_WEIGHT_FIELD: CODE_WEIGHT_FIELD,
+  WEIGHT_OFFSETS_FIELD: WEIGHT_OFFSETS_FIELD,
+  WEIGHT_FIELDS: WEIGHT_FIELDS,
+  migratePresetWeights: migratePresetWeights,
   LINE_HEIGHT_FIELD: LINE_HEIGHT_FIELD,
   LINE_HEIGHT_DIALOG_FIELD: LINE_HEIGHT_DIALOG_FIELD,
   CODE_LINE_HEIGHT_FIELD: CODE_LINE_HEIGHT_FIELD,
@@ -2872,6 +3009,7 @@ var shared = {
   WEIGHT_STEP_CANDIDATES: WEIGHT_STEP_CANDIDATES,
   WEIGHT_DELTA_FLOOR: WEIGHT_DELTA_FLOOR,
   WEIGHT_DELTA_CEIL: WEIGHT_DELTA_CEIL,
+  WEIGHT_MIN_POSITIONS: WEIGHT_MIN_POSITIONS,
   WEIGHT_LADDER_TOP: WEIGHT_LADDER_TOP,
   WEIGHT_LADDER_STRONG: WEIGHT_LADDER_STRONG,
   WEIGHT_DELTA_UP_LIMIT: WEIGHT_DELTA_UP_LIMIT,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-fonttune",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "Font plugin for the DeepSeek Harness Web GUI: the conversation gets its own font, size, line height and weight, the interface font and weight follow it, code keeps its own axis with ligature control, and whole setups save as presets.",
   "type": "module",
   "main": "lib/index.js",