ntk 8.17.4 → 8.17.6

package/lib/fontconfig.js

@@ -93,18 +93,29 @@ export function noFontsError(reason, cause) {
   return err;
 }
 
-// css weight -> fontconfig weight constants
-const cssToFcWeight = {
-  100: 0, // thin
-  200: 40, // extralight
-  300: 50, // light
-  400: 80, // regular
-  500: 100, // medium
-  600: 180, // demibold
-  700: 200, // bold
-  800: 205, // extrabold
-  900: 210 // black
-};
+// css weight -> fontconfig weight: fontconfig's own table
+// (FcWeightFromOpenTypeDouble), the one it reads every face's OS/2 weight
+// through, so a pattern's weight sits where a face of that CSS weight does
+const cssToFcWeight = [
+  [0, 0],
+  [100, 0], // thin
+  [200, 40], // extralight
+  [300, 50], // light
+  [350, 55], // demilight
+  [380, 75], // book
+  [400, 80], // regular
+  [500, 100], // medium
+  [600, 180], // demibold
+  [700, 200], // bold
+  [800, 205], // extrabold
+  [900, 210], // black
+  [1000, 215] // extrablack
+];
+
+// CSS's 400 and 500, and the heaviest weight there is, on fontconfig's scale
+const REGULAR = 80;
+const MEDIUM = 100;
+const HEAVIEST = 215;
 
 // formats fontkit can parse. Exported so the font-spec resolver filters a
 // directory listing by exactly the same rule fc-match output is filtered by —
@@ -239,17 +250,27 @@ function fcName(name) {
   return name.replace(/[\\\-:,]/g, '\\$&');
 }
 
-function patternFor({ family, weight, style }) {
-  let fc = String(platformFamilies(family || 'sans-serif'))
+/**
+ * A pattern as fc-match is handed it (`fc`, which is also its cache key),
+ * with what CSS's matching needs of it besides: the family names it asks
+ * for, the weight on fontconfig's scale (its default, regular, where none
+ * is asked for) and whether it asks for italic.
+ */
+function specFor({ family, weight, style }) {
+  const names = String(platformFamilies(family || 'sans-serif'))
     .split(',')
     .map((name) => name.trim().replace(/^["']|["']$/g, ''))
-    .filter(Boolean)
-    .map(fcName)
-    .join(',');
+    .filter(Boolean);
+  let fc = names.map(fcName).join(',');
   const fcWeight = normalizeWeight(weight);
   if (fcWeight !== undefined) fc += `:weight=${fcWeight}`;
-  if (style && style.includes('italic')) fc += ':slant=italic';
-  return fc;
+  const italic = Boolean(style && style.includes('italic'));
+  if (italic) fc += ':slant=italic';
+  return { fc, names, weight: fcWeight ?? REGULAR, italic };
+}
+
+function patternFor(pattern) {
+  return specFor(pattern).fc;
 }
 
 // One command shared by the sync and async paths, so a prewarmed cache entry
@@ -259,52 +280,320 @@ function patternFor({ family, weight, style }) {
 // localized aliases included (`Hiragino Sans`, `ヒラギノ角ゴシック`, and the
 // style-suffixed forms of both are one face), and `--format` joins them with
 // commas. The fields are tab-separated so a comma inside one costs nothing,
-// and `charset` stays last because it is by far the longest.
+// and `charset` stays last because it is by far the longest. Weight, slant
+// and width are what CSS's matching reads (`cssFace`).
 const fcMatchArgs = [
   '-s',
   '--format',
-  '%{file}\t%{postscriptname}\t%{family}\t%{charset}\n'
+  '%{file}\t%{postscriptname}\t%{family}\t%{weight}\t%{slant}\t%{width}\t%{charset}\n'
 ];
 const fcMatchOpts = { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 };
 
+/**
+ * A weight, slant or width as fontconfig prints it, as `[lo, hi]`: a number
+ * is both ends, and a variable font's range, `[80 200]`, its own. Null where
+ * there is none.
+ */
+function valueRange(text) {
+  const n = text ? Number(text) : NaN;
+  if (!Number.isNaN(n)) return [n, n];
+  const values = String(text ?? '')
+    .replace(/[[\]]/g, ' ')
+    .split(/[\s,]+/)
+    .filter(Boolean)
+    .map(Number);
+  if (values.length === 0 || values.some(Number.isNaN)) return null;
+  return [Math.min(...values), Math.max(...values)];
+}
+
+/**
+ * One face fontconfig named, as a candidate. `charset` is null where it was
+ * not asked for (the census's faces) — the face's coverage is not known, and
+ * `charsetHas` answers yes, so a fallback opens it and asks the font.
+ */
+function candidate(path, postscriptName, family, weight, slant, width, charset) {
+  // `families` keeps fontconfig's whole list, in its order; `family` is
+  // the first of them, which is the name fontconfig leads with for the
+  // current locale and the one to show in a UI.
+  const families = family ? family.split(',').filter(Boolean) : [];
+  return {
+    path,
+    postscriptName,
+    family: families[0] || '',
+    families,
+    charset,
+    _ranges: null,
+    _style: [weight, slant, width]
+  };
+}
+
+/**
+ * A candidate's weight, slant and width as ranges (`valueRange`), read the
+ * first time they are asked for — a chain's head is, the 150 faces behind
+ * it never are. Null where fontconfig did not say.
+ */
+function styleOf(face) {
+  if (Array.isArray(face._style)) {
+    const [weight, slant, width] = face._style.map(valueRange);
+    face._style = weight && slant && width ? { weight, slant, width } : null;
+  }
+  return face._style;
+}
+
 /** fc-match -s output -> candidates, filtered to formats fontkit can parse */
 function parseMatches(out) {
   const list = [];
   for (const line of out.split('\n')) {
-    const [path, postscriptName, family, charset] = line.split('\t');
+    const [path, postscriptName, family, weight, slant, width, charset] = line.split('\t');
     if (path && supported.test(path)) {
-      // `families` keeps fontconfig's whole list, in its order; `family` is
-      // the first of them, which is the name fontconfig leads with for the
-      // current locale and the one to show in a UI.
-      const families = family ? family.split(',').filter(Boolean) : [];
-      list.push({
-        path,
-        postscriptName,
-        family: families[0] || '',
-        families,
-        charset: charset || '',
-        _ranges: null
-      });
+      list.push(candidate(path, postscriptName, family, weight, slant, width, charset || ''));
     }
   }
   return list;
 }
 
 /**
- * fc-match output -> the cached candidate list for a pattern. Throws for
- * output that parses to nothing usable, which is a fontconfig answer rather
- * than a fontconfig failure and so is diagnosed separately.
+ * fc-match output -> the cached candidate list for a pattern, its head the
+ * face CSS picks (`cssChain`). Throws for output that parses to nothing
+ * usable, which is a fontconfig answer rather than a fontconfig failure and
+ * so is diagnosed separately.
  */
-function cacheMatches(fc, out) {
+function cacheMatches(spec, out) {
   const list = parseMatches(out);
   if (list.length === 0) {
     throw noFontsError(
-      `fontconfig matched no font ntk can parse for "${fc}" (needs ` +
+      `fontconfig matched no font ntk can parse for "${spec.fc}" (needs ` +
         '.ttf/.otf/.woff/.woff2/.ttc/.dfont — bitmap .pcf/.bdf fonts are not usable)'
     );
   }
-  sortedCache.set(fc, list);
-  return list;
+  const chain = cssChain(spec, list);
+  sortedCache.set(spec.fc, chain);
+  return chain;
+}
+
+// The census: every face fontconfig knows, a line each — file, PostScript
+// name, families, weight, slant and width — from one fc-list a process,
+// started beside the first prewarm's fc-matches (`spawnToFiles`) and read
+// the first time a weight needs it (`cssFace`). 357 KB for 1,900 faces on a
+// Mac, 45 ms to list. It is kept as the bytes it was read as and a family's
+// lines found in it by a byte search: decoded whole, it was a millisecond of
+// the layout that first needed it, and a family is a dozen of its lines.
+const CENSUS_FORMAT = '%{file}\t%{postscriptname}\t%{family}\t%{weight}\t%{slant}\t%{width}\n';
+
+// undefined until a prewarm starts it; then its prewarm entry, with `bytes`
+// (undefined until read, null where there is none to read) and `faces`, the
+// family -> faces lookups already made in it
+let census;
+
+/**
+ * The census's bytes — waited for synchronously while its child runs. Null
+ * where it failed, took too long, or never ran (no shell to run it in), and
+ * then for good: a face answered without it must not be answered otherwise
+ * a moment later.
+ */
+function censusBytes() {
+  if (!census) return null;
+  if (census.bytes !== undefined) return census.bytes;
+  const deadline = performance.now() + PREWARM_WAIT_MS;
+  let status = prewarmStatus(census.base);
+  while (status === null && !census.exited && performance.now() < deadline) {
+    Atomics.wait(nap, 0, 0, 1);
+    status = prewarmStatus(census.base);
+  }
+  census.bytes = null;
+  if (status === 0) {
+    try {
+      census.bytes = builtin('node:fs').readFileSync(`${census.base}.out`);
+    } catch {
+      // gone from under us: no census, as if it had failed
+    }
+  }
+  removePrewarm(census.base);
+  return census.bytes;
+}
+
+/** once the census can be read without waiting: for a caller that awaits */
+function censusSettled() {
+  return census && census.bytes === undefined && !census.exited ? census.promise : undefined;
+}
+
+// a family name as fontconfig compares one: case and blanks aside
+const folded = (name) => name.replace(/\s+/g, '').toLowerCase();
+
+/**
+ * The faces of the family fontconfig matched a pattern to, as the census has
+ * them — those ntk can open. Null where there is no census.
+ *
+ * The family is the name `head` was matched by: the first of the pattern's
+ * that the face answers to, or — for a generic, or a family fontconfig put
+ * another in place of — the name it leads with. Which name matters: `Avenir
+ * Next Ultra Light` is a family of two faces, and `Avenir Next` one of
+ * twelve that holds both.
+ */
+function familyFaces(names, head) {
+  const bytes = censusBytes();
+  if (bytes === null) return null;
+  let name;
+  for (const asked of names.map(folded)) {
+    name = head.families.find((f) => folded(f) === asked);
+    if (name) break;
+  }
+  name ??= head.families[0];
+  if (!name) return null;
+  const key = folded(name);
+  let faces = census.faces.get(key);
+  if (faces) return faces;
+  faces = [];
+  // fontconfig spells a name alike in both answers, so a search for it finds
+  // every line it is on, and the line's own family list says whether it is
+  // one of the face's names or only part of a longer one
+  for (let at = bytes.indexOf(name); at !== -1; ) {
+    const start = bytes.lastIndexOf(10, at) + 1;
+    let end = bytes.indexOf(10, at);
+    if (end === -1) end = bytes.length;
+    const line = bytes.toString('utf8', start, end);
+    const [path, postscriptName, family, weight, slant, width] = line.split('\t');
+    const face = candidate(path, postscriptName, family, weight, slant, width, null);
+    if (path && supported.test(path) && face.families.some((f) => folded(f) === key)) faces.push(face);
+    at = bytes.indexOf(name, end);
+  }
+  census.faces.set(key, faces);
+  return faces;
+}
+
+// CSS Fonts 4 §5.2's order, as ranks on fontconfig's scale, lowest first.
+// Width (font-stretch, normal being 100): the normal width, then narrower
+// ones nearest first, then wider ones.
+function widthRank([lo, hi]) {
+  if (lo <= 100 && hi >= 100) return 0;
+  return hi < 100 ? 100 - hi : 1000 + lo - 100;
+}
+
+// Slant: the one asked for, then oblique (fontconfig's 110), then the other.
+function slantRank(italic, [lo, hi]) {
+  const asked = italic ? 100 : 0;
+  if (lo <= asked && hi >= asked) return 0;
+  return lo >= 105 ? 1 : 2;
+}
+
+// Weight, for `weight` asked: between 400 and 500, up to 500 ascending, then
+// lighter descending, then past 500 ascending; below 400 lighter first, above
+// 500 heavier first. A variable face's range holds every weight in it.
+// `regular` and `medium` are 400 and 500 on the scale the weights are on —
+// fontconfig's here, CSS's in StaticFontSource, where an OS/2 weight class can
+// be anything up to 65535 and so each direction is a million past the last.
+export function weightRank(weight, [lo, hi], regular = REGULAR, medium = MEDIUM) {
+  if (lo <= weight && hi >= weight) return 0;
+  const x = hi < weight ? hi : lo;
+  if (weight >= regular && weight <= medium) {
+    if (x > weight && x <= medium) return x - weight;
+    return x < weight ? 1e6 + weight - x : 2e6 + x - weight;
+  }
+  if (weight < regular) return x < weight ? weight - x : 1e6 + x - weight;
+  return x > weight ? x - weight : 1e6 + weight - x;
+}
+
+/**
+ * Is `head`, the face fontconfig picked, the one CSS picks — whatever else
+ * the family holds?
+ *
+ * Fontconfig picks the face nearest in weight, after the slant: so no face
+ * of the head's slant is nearer the weight asked for than the head, and that
+ * is all one answer says about the family. The head is CSS's pick when every
+ * weight CSS would try before the head's lies nearer — 500 in Helvetica,
+ * whose regular is 80 against 100 asked, where CSS tries 500 alone first.
+ * 450 in Arial is not: 500 is as near as its regular, so a medium could be
+ * there, and CSS would take it. Then the census decides.
+ *
+ * Fontconfig ranks width after weight and CSS before it, so a head of
+ * another width than normal is never shown to be CSS's: 900 in Helvetica
+ * Neue is its condensed black. Nor is an italic head for an upright ask,
+ * where CSS tries oblique first.
+ */
+function provenPick(weight, italic, head) {
+  const style = styleOf(head);
+  if (!style) return false;
+  if (widthRank(style.width) !== 0) return false;
+  if (!italic && slantRank(false, style.slant) === 2) return false;
+  const [lo, hi] = style.weight;
+  if (lo <= weight && hi >= weight) return true;
+  const x = hi < weight ? hi : lo;
+  const near = Math.abs(x - weight);
+  // the weights CSS tries before x: from, whether it is open, to, whether it is
+  let from, fromOpen, to, toOpen;
+  if (weight >= REGULAR && weight <= MEDIUM) {
+    if (x > weight && x <= MEDIUM) [from, fromOpen, to, toOpen] = [weight, false, x, true];
+    else if (x < weight) [from, fromOpen, to, toOpen] = [x, true, MEDIUM, false];
+    else [from, fromOpen, to, toOpen] = [0, false, x, true];
+  } else if (weight < REGULAR) {
+    if (x < weight) [from, fromOpen, to, toOpen] = [x, true, weight, false];
+    else [from, fromOpen, to, toOpen] = [0, false, x, true];
+  } else if (x > weight) [from, fromOpen, to, toOpen] = [weight, false, x, true];
+  else [from, fromOpen, to, toOpen] = [x, true, HEAVIEST, false];
+  return (
+    (from > weight - near || (fromOpen && from >= weight - near)) &&
+    (to < weight + near || (toOpen && to <= weight + near))
+  );
+}
+
+/** a < b, comparing [width, slant, weight] ranks in turn */
+function ranksBefore(a, b) {
+  for (let i = 0; i < a.length; i++) if (a[i] !== b[i]) return a[i] < b[i];
+  return false;
+}
+
+/**
+ * The face CSS's matching (CSS Fonts 4 §5.2) picks for a pattern, given
+ * `head`, the face fontconfig picked: the head itself where it can be shown
+ * to be CSS's (`provenPick`), or where there is no census to say otherwise,
+ * and the family's best face by width, slant and weight in that order where
+ * there is one. Fontconfig picks the face nearest in weight, after the
+ * slant and before the width, so 520 in Arial was the regular, which a
+ * browser sets in the bold.
+ *
+ * The head wins ties: a face like it is fontconfig's to choose between. So
+ * does a head that is a variable font's instance where CSS picks the font —
+ * a weight its axis holds is set on the axis (`instantiate`) whichever face
+ * of the file it is opened through.
+ *
+ * The head is ranked as the census lists it, because an answer describes
+ * the face as fontconfig will render it: an upright face matched for an
+ * italic ask comes back oblique (90-synthetic.conf slants it), and ranked
+ * by that it beat its own family's upright faces — W1 of Hiragino Sans,
+ * which has no italics, at 160, where CSS takes W0.
+ */
+function cssFace(spec, head) {
+  if (!head || provenPick(spec.weight, spec.italic, head)) return head;
+  const faces = familyFaces(spec.names, head);
+  if (!faces || faces.length === 0) return head;
+  const ranks = (face) => {
+    const style = styleOf(face);
+    return style && [widthRank(style.width), slantRank(spec.italic, style.slant), weightRank(spec.weight, style.weight)];
+  };
+  const listed = faces.find((f) => f.path === head.path && f.postscriptName === head.postscriptName);
+  let best = null;
+  let bestRanks = ranks(listed ?? head);
+  for (const face of faces) {
+    const r = ranks(face);
+    if (r && (bestRanks === null || ranksBefore(r, bestRanks))) [best, bestRanks] = [face, r];
+  }
+  if (best === null) return head;
+  const [lo, hi] = styleOf(best).weight;
+  if (lo < hi && best.path === head.path) return head;
+  return best;
+}
+
+/**
+ * A fallback chain with the face CSS picks at its head (`cssFace`). Where
+ * that is not fontconfig's head it is moved up from where the chain has it,
+ * or, as `-s` trims a face whose coverage the faces before it already give —
+ * a family's bold, behind its regular — put there from the census.
+ */
+function cssChain(spec, list) {
+  const face = cssFace(spec, list[0]);
+  if (face === list[0]) return list;
+  const same = (c) => c.path === face.path && c.postscriptName === face.postscriptName;
+  return [list.find(same) ?? face, ...list.filter((c) => !same(c))];
 }
 
 // fc -> { promise, base }: one child per pattern however many callers ask.
@@ -356,14 +645,18 @@ function runFcMatch(fc) {
 // flag first), then a file base, a kind and a pattern for each job: `sorted`
 // asks for the whole fallback chain, `best` for the one face fontconfig
 // would pick, which it answers in half the time, since it sorts nothing and
-// writes one line (`bestOfPrewarm`). The shell exits once every job has.
-// Nothing but shell builtins runs besides fc-match, so a PATH that holds
-// fc-match alone is enough.
+// writes one line (`bestOfPrewarm`). `census` lists every face, with the
+// format in the pattern's place (`CENSUS_FORMAT`). The shell exits once
+// every job has. Nothing but shell builtins runs besides fc-match and
+// fc-list, so a PATH that holds those is enough; without fc-list there is no
+// census, and fontconfig's own picks stand.
 const PREWARM_SCRIPT = [
   ...fcMatchArgs.map((_, i) => `a${i}=\${${i + 1}}`),
   `shift ${fcMatchArgs.length}`,
   'while [ $# -gt 2 ]; do ' +
-    'if [ "$2" = best ]; then ' +
+    'if [ "$2" = census ]; then ' +
+    '(fc-list --format "$3" > "$1.out" 2> "$1.err"; echo $? > "$1.done") & ' +
+    'elif [ "$2" = best ]; then ' +
     `(fc-match ${fcMatchArgs
       .slice(1)
       .map((_, i) => `"$a${i + 1}"`)
@@ -472,16 +765,22 @@ function removePrewarm(base) {
  * set up: 634 KB apiece, most of it the coverage of every face fontconfig
  * sorts behind the first.
  *
+ * The first child also lists every face, once a process (the census, see
+ * `CENSUS_FORMAT`): a job of its own beside the matches, so a weight CSS
+ * matches differently from fontconfig costs no spawn of the app's.
+ *
  * An entry a pattern, in order; null where files cannot be used, and the
  * caller prewarms the old way.
  */
 function spawnToFiles(fcs, bests = []) {
   const cp = childProcess();
   const all = [...fcs, ...bests];
-  const bases = cp ? all.map(() => prewarmBase()) : [];
+  const listing = census === undefined;
+  const bases = cp ? Array.from({ length: all.length + (listing ? 1 : 0) }, () => prewarmBase()) : [];
   if (bases.length === 0 || bases[0] === null) return null;
   const jobs = [];
   all.forEach((fc, i) => jobs.push(bases[i], i < fcs.length ? 'sorted' : 'best', fc));
+  if (listing) jobs.push(bases[all.length], 'census', CENSUS_FORMAT);
   let child;
   try {
     child = cp.spawn('/bin/sh', ['-c', PREWARM_SCRIPT, 'ntk-fc-match', ...fcMatchArgs, ...jobs], {
@@ -492,14 +791,22 @@ function spawnToFiles(fcs, bests = []) {
   }
   // `promise` resolves once the child is gone, with what it left in the
   // files; `exited` tells a synchronous caller there is nothing to wait for
-  const entries = all.map((fc, i) => {
-    const entry = { promise: null, base: bases[i], answer: undefined, exited: false, gone: null };
-    entry.promise = new Promise((resolve) => {
-      entry.gone = resolve;
+  const entry = (base) => {
+    const e = { promise: null, base, answer: undefined, exited: false, gone: null };
+    e.promise = new Promise((resolve) => {
+      e.gone = resolve;
     });
-    (i < fcs.length ? inflight : bestInflight).set(fc, entry);
-    return entry;
+    return e;
+  };
+  const entries = all.map((fc, i) => {
+    const e = entry(bases[i]);
+    (i < fcs.length ? inflight : bestInflight).set(fc, e);
+    return e;
   });
+  if (listing) {
+    census = Object.assign(entry(bases[all.length]), { bytes: undefined, faces: new Map() });
+    entries.push(census);
+  }
   const gone = () => {
     for (const entry of entries) {
       entry.exited = true;
@@ -551,8 +858,10 @@ function answerSync(fc, entry) {
  * layout setting text in the face needs its first line. The rest waits in
  * the file for the first character that falls back, which Latin text in a
  * face that covers it never has.
+ *
+ * The face is the one CSS picks (`cssFace`), as the chain's head will be.
  */
-function firstOfPrewarm(entry) {
+function firstOfPrewarm(spec, entry) {
   if (entry.first !== undefined) return entry.first;
   const deadline = performance.now() + PREWARM_WAIT_MS;
   let status = prewarmStatus(entry.base);
@@ -562,7 +871,7 @@ function firstOfPrewarm(entry) {
   }
   // not answered, or not yet: the whole read is what decides, and reports
   if (status !== 0) return null;
-  entry.first = firstCandidate(`${entry.base}.out`);
+  entry.first = cssFace(spec, firstCandidate(`${entry.base}.out`));
   return entry.first;
 }
 
@@ -576,9 +885,10 @@ function firstOfPrewarm(entry) {
  * in about half the time the whole chain takes (15 ms against 30 on a Linux
  * desktop): no sort, one line. A layout that asks for a family warmed while
  * its component rendered waits on the prewarm, and the chain was most of
- * that wait.
+ * that wait. Fontconfig's face, that is: the one CSS picks may be another
+ * (`cssFace`).
  */
-function bestOfPrewarm(entry) {
+function bestOfPrewarm(spec, entry) {
   if (entry.first !== undefined) return entry.first;
   const deadline = performance.now() + PREWARM_WAIT_MS;
   let left = readPrewarm(entry.base);
@@ -589,7 +899,7 @@ function bestOfPrewarm(entry) {
   if (left === null) return null;
   removePrewarm(entry.base);
   const [best] = left.status === 0 ? parseMatches(left.out) : [];
-  entry.first = best ?? null;
+  entry.first = best ? cssFace(spec, best) : null;
   return entry.first;
 }
 
@@ -665,7 +975,7 @@ function firstCandidate(file) {
  *   attempt abandoned
  */
 export function prewarm(pattern = {}) {
-  return warm([patternFor(pattern)])[0];
+  return warm([specFor(pattern)])[0];
 }
 
 /**
@@ -677,36 +987,39 @@ export function prewarm(pattern = {}) {
  *   up on; never rejects
  */
 export function prewarmPatterns(patterns) {
-  return Promise.all(warm(patterns.map(patternFor))).then(() => {});
+  return Promise.all(warm(patterns.map(specFor))).then(() => {});
 }
 
 /**
- * `prewarm` for a list of fontconfig patterns: the ones neither cached nor
+ * `prewarm` for a list of patterns (`specFor`): the ones neither cached nor
  * already running start together, in one child (`spawnToFiles`). A promise a
  * pattern, resolving once its answer is ready or given up on; none rejects.
  */
-function warm(fcs, best = null) {
-  if (unavailable) return fcs.map(() => Promise.resolve());
+function warm(specs, best = null) {
+  if (unavailable) return specs.map(() => Promise.resolve());
+  const fcs = specs.map((spec) => spec.fc);
   const fresh = [...new Set(fcs)].filter((fc) => !sortedCache.has(fc) && !inflight.has(fc));
   // the best face only beside its own chain: once that is running or read,
   // the chain's head answers as soon as a best job would
   const bests = best !== null && fresh.includes(best) && !bestInflight.has(best) ? [best] : [];
   if (fresh.length > 0) spawnToFiles(fresh, bests);
-  return fcs.map((fc) => {
+  return specs.map((spec) => {
+    const { fc } = spec;
     if (sortedCache.has(fc)) return Promise.resolve();
     // a prewarm's answer waits in its files for the first ask
     const running = inflight.get(fc);
     if (running?.base) return running.promise;
     const pending = running?.promise ?? runFcMatch(fc);
-    return pending.then(
-      (out) => {
+    return pending
+      .then(async (out) => {
+        // the census decides the head: read once it is in, never waited on
+        await censusSettled();
         if (!sortedCache.has(fc)) {
           const list = parseMatches(out);
-          if (list.length > 0) sortedCache.set(fc, list);
+          if (list.length > 0) sortedCache.set(fc, cssChain(spec, list));
         }
-      },
-      () => {}
-    );
+      })
+      .catch(() => {});
   });
 }
 
@@ -736,7 +1049,7 @@ export function prewarmFaces(pattern = {}) {
   // the one being asked for, or, warmed ahead, the regular
   const first = patternFor(pattern.weight === undefined && pattern.style === undefined ? { family, weight: 400, style: 'normal' } : pattern);
   warm(
-    FACES.map(([weight, style]) => patternFor({ family, weight, style })),
+    FACES.map(([weight, style]) => specFor({ family, weight, style })),
     first
   );
 }
@@ -757,14 +1070,18 @@ export function prewarmFaces(pattern = {}) {
  * sync throws do.
  *
  * @returns {Promise<Array<{path, postscriptName, family: string,
- *   families: string[], charset: string}>>}
+ *   families: string[], charset: string|null}>>}
  */
 export async function matchSorted(pattern = {}) {
-  const fc = patternFor(pattern);
+  const spec = specFor(pattern);
+  const { fc } = spec;
   const cached = sortedCache.get(fc);
   if (cached) return cached;
   if (unavailable) throw noFontsError(unavailable);
 
+  // A caller that awaits may be the first to ask anything — a font picker
+  // with no source constructed — and nothing else would start the census
+  if (census === undefined) spawnToFiles([]);
   let out;
   const pending = inflight.get(fc);
   if (pending?.base) {
@@ -780,17 +1097,22 @@ export async function matchSorted(pattern = {}) {
       throw fcMatchError(err);
     }
   }
+  // the census decides the head where fontconfig's own cannot be shown to be
+  // CSS's (`cssChain`): read once it is in, so that this never waits on it
+  await censusSettled();
   // A sync call may have answered this pattern while the child ran. Its list
   // is the cached one, and candidates memoize their parsed charset, so hand
   // back what everyone else already holds rather than a fresh copy.
-  return sortedCache.get(fc) ?? cacheMatches(fc, out);
+  return sortedCache.get(fc) ?? cacheMatches(spec, out);
 }
 
 /**
  * Full fontconfig match list for a pattern, best match first — this is the
- * system's font fallback chain. Each candidate carries the unicode coverage
- * fontconfig knows about (`charset`, lazily parsed via `charsetHas`), so a
- * fallback font for a codepoint can be chosen without opening font files —
+ * system's font fallback chain, headed by the face CSS's font matching picks
+ * (`cssChain`). Each candidate carries the unicode coverage fontconfig knows
+ * about (`charset`, lazily parsed via `charsetHas`; null for a head the
+ * chain did not have), so a fallback font for a codepoint can be chosen
+ * without opening font files —
  * and the family name fontconfig already knows, so a *list* of matches can be
  * shown without opening them either (issue #273: `sans-serif` returns 139
  * candidates here, and `Font.loadSync` is ~1.2ms a file).
@@ -800,10 +1122,11 @@ export async function matchSorted(pattern = {}) {
  * a caller that can should use `matchSorted` and not block on the spawn.
  *
  * @returns {Array<{path, postscriptName, family: string, families: string[],
- *   charset: string}>}
+ *   charset: string|null}>}
  */
 export function matchSortedSync(pattern) {
-  const fc = patternFor(pattern);
+  const spec = specFor(pattern);
+  const { fc } = spec;
   const cached = sortedCache.get(fc);
   if (cached) return cached;
   if (unavailable) throw noFontsError(unavailable);
@@ -814,7 +1137,7 @@ export function matchSortedSync(pattern) {
   const pending = inflight.get(fc);
   if (pending?.base) {
     const out = answerSync(fc, pending);
-    if (out !== null) return sortedCache.get(fc) ?? cacheMatches(fc, out);
+    if (out !== null) return sortedCache.get(fc) ?? cacheMatches(spec, out);
   }
   let out;
   try {
@@ -822,7 +1145,7 @@ export function matchSortedSync(pattern) {
   } catch (err) {
     throw fcMatchError(err);
   }
-  return cacheMatches(fc, out);
+  return cacheMatches(spec, out);
 }
 
 /**
@@ -832,22 +1155,23 @@ export function matchSortedSync(pattern) {
  * the first character it has to fall back for reads the chain whole.
  *
  * @returns {{path, postscriptName, family: string, families: string[],
- *   charset: string}}
+ *   charset: string|null}}
  */
 export function matchFirstSync(pattern) {
-  const fc = patternFor(pattern);
+  const spec = specFor(pattern);
+  const { fc } = spec;
   const cached = sortedCache.get(fc);
   if (cached) return cached[0];
   if (unavailable) throw noFontsError(unavailable);
   prewarmFaces(pattern);
   const best = bestInflight.get(fc);
   if (best) {
-    const first = bestOfPrewarm(best);
+    const first = bestOfPrewarm(spec, best);
     if (first) return first;
   }
   const pending = inflight.get(fc);
   if (pending?.base) {
-    const first = firstOfPrewarm(pending);
+    const first = firstOfPrewarm(spec, pending);
     if (first) return first;
   }
   return matchSortedSync(pattern)[0];
@@ -873,8 +1197,12 @@ export function listFontsSync(pattern) {
 /**
  * Does a fc-match candidate's charset cover a codepoint?
  * The charset string is fontconfig's range format: "20-7e a0-ff 131 ...".
+ * A face whose coverage is not known here — one CSS's matching put at a
+ * chain's head, which `-s` had trimmed (`cssChain`) — may: it is opened and
+ * the font asked.
  */
 export function charsetHas(candidate, codepoint) {
+  if (candidate.charset === null) return true;
   if (candidate._ranges === null) {
     const ranges = [];
     for (const part of candidate.charset.split(' ')) {
@@ -903,15 +1231,18 @@ export function charsetHas(candidate, codepoint) {
 
 /**
  * A CSS font weight on fontconfig's scale, which is not CSS's: regular is 80
- * there and black is 210. The hundreds are the table's; a weight between two
- * of them is as far between their fontconfig weights, so 450 is 90, halfway
- * from regular to medium. CSS takes 1 to 1000, and what is outside the table
- * is its nearest end.
+ * there and black is 210. The table is fontconfig's own, and a weight between
+ * two of its entries is as far between their fontconfig weights, so 450 is
+ * 90, halfway from regular to medium. CSS takes 1 to 1000.
  *
  * Handed over as it was, 450 was a weight past twice black, and fontconfig
  * answered with the heaviest face a family has: Arial Bold, where a browser
- * sets 450 in Arial Regular. At 90 fontconfig picks the face nearest in
- * weight, which is the regular's 80 and not the bold's 200.
+ * sets 450 in Arial Regular.
+ *
+ * Fontconfig's table rather than one of the hundreds alone, because it is
+ * the one a face's own weight went through: a face whose OS/2 weight is 350
+ * is 55 in every fc-match answer, and only the same table puts a pattern
+ * asking for 340 on the lighter side of it (`cssFace`).
  *
  * A whole number, because a pattern is a cache key and an fc-match of its
  * own: the weights an axis is animated through then share the ones they
@@ -919,13 +1250,14 @@ export function charsetHas(candidate, codepoint) {
  */
 function normalizeWeight(weight) {
   if (weight === undefined) return undefined;
-  if (weight === 'normal') return cssToFcWeight[400];
-  if (weight === 'bold') return cssToFcWeight[700];
+  if (weight === 'normal') return REGULAR;
+  if (weight === 'bold') return 200;
   const n = parseInt(weight, 10);
   if (Number.isNaN(n)) return undefined;
-  const css = Math.min(900, Math.max(100, n));
-  const below = Math.floor(css / 100) * 100;
-  const lighter = cssToFcWeight[below];
-  if (css === below) return lighter;
-  return Math.round(lighter + ((cssToFcWeight[below + 100] - lighter) * (css - below)) / 100);
+  const css = Math.min(1000, Math.max(1, n));
+  let i = 1;
+  while (css > cssToFcWeight[i][0]) i++;
+  const [lighterCss, lighter] = cssToFcWeight[i - 1];
+  const [heavierCss, heavier] = cssToFcWeight[i];
+  return Math.round(lighter + ((heavier - lighter) * (css - lighterCss)) / (heavierCss - lighterCss));
 }