@iksnerd/blazon 0.3.3 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (121) hide show
  1. package/CHANGELOG.md +375 -0
  2. package/dist/chunks/{site-builder-DlaZeZHi.js → site-builder-C8g2sfUv.js} +3471 -3650
  3. package/dist/cli/commands/approvals.d.ts +1 -1
  4. package/dist/cli/commands/approvals.d.ts.map +1 -1
  5. package/dist/cli/commands/mcp-check.d.ts +7 -4
  6. package/dist/cli/commands/mcp-check.d.ts.map +1 -1
  7. package/dist/cli/errors.d.ts +3 -1
  8. package/dist/cli/errors.d.ts.map +1 -1
  9. package/dist/cli/folder-first.d.ts +7 -0
  10. package/dist/cli/folder-first.d.ts.map +1 -0
  11. package/dist/cli/handlers/can.d.ts +1 -1
  12. package/dist/cli/handlers/can.d.ts.map +1 -1
  13. package/dist/cli/handlers/list.d.ts.map +1 -1
  14. package/dist/cli/index.js +1384 -1033
  15. package/dist/cli/json.d.ts +3 -2
  16. package/dist/cli/json.d.ts.map +1 -1
  17. package/dist/cli/operations.d.ts +1 -1
  18. package/dist/cli/operations.d.ts.map +1 -1
  19. package/dist/cli/read.d.ts +4 -1
  20. package/dist/cli/read.d.ts.map +1 -1
  21. package/dist/cli/where.d.ts +2 -0
  22. package/dist/cli/where.d.ts.map +1 -1
  23. package/dist/core/assets/representations.d.ts +44 -0
  24. package/dist/core/assets/representations.d.ts.map +1 -0
  25. package/dist/core/assets/scanner.d.ts.map +1 -1
  26. package/dist/core/assets/sidecar.d.ts.map +1 -1
  27. package/dist/core/blazon-pin.d.ts +19 -1
  28. package/dist/core/blazon-pin.d.ts.map +1 -1
  29. package/dist/core/brand/export.d.ts +13 -5
  30. package/dist/core/brand/export.d.ts.map +1 -1
  31. package/dist/core/brand/schema.d.ts +68 -0
  32. package/dist/core/brand/schema.d.ts.map +1 -1
  33. package/dist/core/checker/approvals.d.ts +5 -0
  34. package/dist/core/checker/approvals.d.ts.map +1 -1
  35. package/dist/core/checker/catalogue.d.ts +37 -7
  36. package/dist/core/checker/catalogue.d.ts.map +1 -1
  37. package/dist/core/checker/font-meta.d.ts.map +1 -1
  38. package/dist/core/checker/index.d.ts +5 -0
  39. package/dist/core/checker/index.d.ts.map +1 -1
  40. package/dist/core/checker/review.d.ts +19 -1
  41. package/dist/core/checker/review.d.ts.map +1 -1
  42. package/dist/core/docs/directives.d.ts +10 -0
  43. package/dist/core/docs/directives.d.ts.map +1 -1
  44. package/dist/core/docs/parser.d.ts.map +1 -1
  45. package/dist/core/font-roles.d.ts +11 -0
  46. package/dist/core/font-roles.d.ts.map +1 -0
  47. package/dist/core/index.d.ts.map +1 -1
  48. package/dist/core/init/from-site/fonts.d.ts.map +1 -1
  49. package/dist/core/logo/colorways.d.ts +29 -0
  50. package/dist/core/logo/colorways.d.ts.map +1 -0
  51. package/dist/core/logo/misuse.d.ts +18 -0
  52. package/dist/core/logo/misuse.d.ts.map +1 -0
  53. package/dist/core/mcp-config.d.ts +7 -0
  54. package/dist/core/mcp-config.d.ts.map +1 -1
  55. package/dist/core/operations/check.d.ts +1 -1
  56. package/dist/core/operations/check.d.ts.map +1 -1
  57. package/dist/core/operations/index.d.ts +1 -1
  58. package/dist/core/operations/index.d.ts.map +1 -1
  59. package/dist/core/operations/limits.d.ts +2 -0
  60. package/dist/core/operations/limits.d.ts.map +1 -1
  61. package/dist/core/operations/list.d.ts.map +1 -1
  62. package/dist/core/operations/types.d.ts +13 -0
  63. package/dist/core/operations/types.d.ts.map +1 -1
  64. package/dist/core/preflight.d.ts.map +1 -1
  65. package/dist/core/read/can.d.ts +14 -3
  66. package/dist/core/read/can.d.ts.map +1 -1
  67. package/dist/core/read/fonts.d.ts +2 -6
  68. package/dist/core/read/fonts.d.ts.map +1 -1
  69. package/dist/core/read/index.d.ts +3 -2
  70. package/dist/core/read/index.d.ts.map +1 -1
  71. package/dist/core/read/list.d.ts +15 -1
  72. package/dist/core/read/list.d.ts.map +1 -1
  73. package/dist/core/read/logo.d.ts +3 -3
  74. package/dist/core/read/logo.d.ts.map +1 -1
  75. package/dist/core/read/lookup.d.ts +2 -2
  76. package/dist/core/read/lookup.d.ts.map +1 -1
  77. package/dist/core/read/theme.d.ts +8 -0
  78. package/dist/core/read/theme.d.ts.map +1 -0
  79. package/dist/core/read/token.d.ts +6 -2
  80. package/dist/core/read/token.d.ts.map +1 -1
  81. package/dist/core/tokens/alias.d.ts +5 -3
  82. package/dist/core/tokens/alias.d.ts.map +1 -1
  83. package/dist/core/tokens/contexts.d.ts +11 -3
  84. package/dist/core/tokens/contexts.d.ts.map +1 -1
  85. package/dist/core/tokens/formatters/json.d.ts +4 -1
  86. package/dist/core/tokens/formatters/json.d.ts.map +1 -1
  87. package/dist/core/tokens/key-lines.d.ts.map +1 -1
  88. package/dist/core/tokens/merge.d.ts.map +1 -1
  89. package/dist/core/tokens/resolver/compile.d.ts.map +1 -1
  90. package/dist/core/tokens/resolver/parse.d.ts.map +1 -1
  91. package/dist/core/tokens/resolver/sources.d.ts.map +1 -1
  92. package/dist/core/tokens/walk.d.ts.map +1 -1
  93. package/dist/index.js +34 -34
  94. package/dist/plugins/host/call.d.ts.map +1 -1
  95. package/dist/plugins/roles/roles.d.ts.map +1 -1
  96. package/dist/server/plugin.d.ts.map +1 -1
  97. package/dist/types/assets.d.ts +19 -1
  98. package/dist/types/assets.d.ts.map +1 -1
  99. package/dist/types/parsed.d.ts +8 -0
  100. package/dist/types/parsed.d.ts.map +1 -1
  101. package/dist/types/tokens.d.ts +12 -0
  102. package/dist/types/tokens.d.ts.map +1 -1
  103. package/dist/ui/assets/index-b4HhGGrn.js +82 -0
  104. package/dist/ui/assets/index-pE1ku5gt.css +2 -0
  105. package/dist/ui/index.html +2 -2
  106. package/mcp/dist/index.js +358 -45
  107. package/package.json +3 -2
  108. package/plugins/blazon.brand-deck/README.md +1 -1
  109. package/plugins/blazon.brand-deck/bin/blazon-blazon.brand-deck./360/237/224/214 +106 -13
  110. package/plugins/blazon.favicons/bin/blazon-blazon.favicons./360/237/224/214 +120 -12
  111. package/plugins/blazon.logo-geometry/bin/blazon-blazon.logo-geometry./360/237/224/214 +45 -1
  112. package/plugins/blazon.logo-kit/bin/blazon-blazon.logo-kit./360/237/224/214 +45 -1
  113. package/plugins/blazon.office-template/bin/blazon-blazon.office-template./360/237/224/214 +66 -3
  114. package/plugins/blazon.platform-tokens/README.md +1 -1
  115. package/plugins/blazon.press-kit/README.md +17 -9
  116. package/plugins/blazon.press-kit/bin/blazon-blazon.press-kit./360/237/224/214 +621 -101
  117. package/plugins/blazon.print-book/README.md +16 -1
  118. package/plugins/blazon.social-cards/bin/blazon-blazon.social-cards./360/237/224/214 +59 -3
  119. package/plugins/shipped.lock +9 -9
  120. package/dist/ui/assets/index-Biy1hkeq.css +0 -2
  121. package/dist/ui/assets/index-dkJG6W9p.js +0 -82
@@ -8,7 +8,7 @@ The source is `src/shipped/brand-deck/`, and `npm run build` (`npm run build:plu
8
8
 
9
9
  The slide plan (`src/shipped/brand-deck/plan/`) is plain data from `brand.json`: which slides, in which order, with what on them. The drawing (`src/shipped/brand-deck/paint/`) turns each slide into HTML placed in points, and `render.ts` prints that page to PDF with Chrome, one slide to a page. Text and SVG stay vector. Every line of text is broken by the plugin and not by the browser, using the browser's own measure of each word, so an asset's text is fitted to its slide, and a long one continues on slides titled "(continued)", by the same arithmetic that draws it.
10
10
 
11
- Images are read from `site_dir`, beside `brand.json`. A file that cannot be read is exit `2` naming it, unless its category is kept out of git (`local` in the category): then the slide shows the category's sentence in place of the picture.
11
+ A logo with several files (`logos/mark.svg` and `logos/mark.png`) is one slide, drawn from the best format the deck can embed: SVG, then PNG, WebP, JPEG, GIF and AVIF. Images are read from `site_dir`, beside `brand.json`. A file that cannot be read is exit `2` naming it, unless its category is kept out of git (`local` in the category): then the slide shows the category's sentence in place of the picture.
12
12
 
13
13
  ## Fonts
14
14
 
@@ -428,16 +428,74 @@ function faviconSlides(favicons) {
428
428
  open: []
429
429
  }, ...slides];
430
430
  }
431
+ /** Compares two strings by UTF-16 code unit. It gives the same answer on every host, which a locale-aware compare does not. */
432
+ function compareText(a, b) {
433
+ return a < b ? -1 : a > b ? 1 : 0;
434
+ }
435
+ /** The order a reader follows when it has no preference of its own: vector first, then the rasters, then any other format by name. */
436
+ var DEFAULT_FORMAT_ORDER = [
437
+ "svg",
438
+ "png",
439
+ "webp",
440
+ "jpg",
441
+ "gif"
442
+ ];
443
+ var pathOf = (record) => record.filePath ?? record.file ?? "";
444
+ /** The file name of a representation, the last segment of its path. */
445
+ function fileNameOf(record) {
446
+ const path = pathOf(record);
447
+ return path.slice(path.lastIndexOf("/") + 1);
448
+ }
449
+ var defaultRank = (format) => {
450
+ const at = DEFAULT_FORMAT_ORDER.indexOf(format === "jpeg" ? "jpg" : format);
451
+ return at === -1 ? DEFAULT_FORMAT_ORDER.length : at;
452
+ };
453
+ /** The order of two representations of one id: the caller's formats first, then the default order, then the file name. */
454
+ function compareRepresentations(a, b, options = {}) {
455
+ const preferred = options.formats;
456
+ if (preferred) {
457
+ const rank = (r) => {
458
+ const at = preferred.indexOf(r.format);
459
+ return at === -1 ? preferred.length : at;
460
+ };
461
+ const byWish = rank(a) - rank(b);
462
+ if (byWish !== 0) return byWish;
463
+ }
464
+ return defaultRank(a.format) - defaultRank(b.format) || compareText(a.format, b.format) || compareText(fileNameOf(a), fileNameOf(b)) || compareText(pathOf(a), pathOf(b));
465
+ }
466
+ /**
467
+ * The one file an id means for a reader. With `formats`, the first of them that the id has (none when it has none of them: the
468
+ * caller says what to do, such as "needs an SVG: logos/mark has png only"); without, the first in the default order.
469
+ */
470
+ function pickRepresentation(records, id, options = {}) {
471
+ return records.filter((record) => record.id === id && (!options.formats || options.formats.includes(record.format))).sort((a, b) => compareRepresentations(a, b, options))[0];
472
+ }
431
473
  /** An asset's sidecar title, or its name made readable. */
432
474
  function assetTitle(asset) {
433
475
  const title = asset.meta?.title;
434
476
  return typeof title === "string" && title !== "" ? title : humanize(asset.name);
435
477
  }
436
478
  var backgroundOf = (asset) => typeof asset.meta?.background === "string" ? asset.meta.background : "light";
437
- /** The assets a directive lists: its category, narrowed and ordered by the names it gives */
479
+ /** The formats the deck can embed, best first: the browser that draws it takes each of them, and a vector stays sharp at any size. */
480
+ var DECK_FORMATS = [
481
+ "svg",
482
+ "png",
483
+ "webp",
484
+ "jpg",
485
+ "jpeg",
486
+ "gif",
487
+ "avif"
488
+ ];
489
+ /** The file the deck draws for an id: the best of the formats it embeds, else the first in the default order (the deck then reports it when it draws). */
490
+ var representationOf = (assets, id) => pickRepresentation(assets, id, { formats: DECK_FORMATS }) ?? pickRepresentation(assets, id);
491
+ /** One asset for each id of `assets`, in the order its ids first appear, each as the file the deck draws. */
492
+ function onePerId(assets) {
493
+ return [...new Set(assets.map((asset) => asset.id))].map((id) => representationOf(assets, id));
494
+ }
495
+ /** The assets a directive lists: its category, narrowed and ordered by the names it gives, one for each id */
438
496
  function membersOf(brand, directive) {
439
497
  const [key, ...names] = directive.args ?? [];
440
- const members = brand.assets.filter((asset) => asset.category === key);
498
+ const members = onePerId(brand.assets.filter((asset) => asset.category === key));
441
499
  if (names.length === 0) return members;
442
500
  const byName = new Map(members.map((asset) => [asset.name, asset]));
443
501
  return names.flatMap((name) => byName.has(name) ? [byName.get(name)] : []);
@@ -520,11 +578,13 @@ function logoRules(meta, titleOf = () => void 0) {
520
578
  };
521
579
  }
522
580
  function logoSlides(brand, skip = []) {
523
- const byId = new Map(brand.assets.map((asset) => [asset.id, asset]));
524
- const titleOf = (id) => byId.has(id) ? assetTitle(byId.get(id)) : void 0;
581
+ const titleOf = (id) => {
582
+ const asset = pickRepresentation(brand.assets, id);
583
+ return asset ? assetTitle(asset) : void 0;
584
+ };
525
585
  const slides = [];
526
- for (const asset of brand.assets) {
527
- if (asset.category !== "logos" || skip.includes("logos")) continue;
586
+ for (const asset of onePerId(brand.assets.filter((candidate) => candidate.category === "logos"))) {
587
+ if (skip.includes("logos")) continue;
528
588
  const meta = asset.meta ?? {};
529
589
  const { rules, clearPx } = logoRules(meta, titleOf);
530
590
  slides.push({
@@ -2571,6 +2631,44 @@ async function drawDeck(browser, drawing) {
2571
2631
  await context.close();
2572
2632
  }
2573
2633
  }
2634
+ /**
2635
+ * Writes `entries` into `dir`, leaving the other files in it. A file is never seen half written. Used where `dir` is the host's own
2636
+ * out_dir, which a plugin may not replace, so the set is staged in a folder inside it and moved up once it is all made.
2637
+ */
2638
+ function writeFolder(dir, entries) {
2639
+ const staged = node_path.default.join(dir, ".part");
2640
+ node_fs.default.rmSync(staged, {
2641
+ recursive: true,
2642
+ force: true
2643
+ });
2644
+ try {
2645
+ stage(staged, entries);
2646
+ for (const file of walk(staged)) {
2647
+ const target = node_path.default.join(dir, file);
2648
+ node_fs.default.mkdirSync(node_path.default.dirname(target), { recursive: true });
2649
+ node_fs.default.renameSync(node_path.default.join(staged, file), target);
2650
+ }
2651
+ } finally {
2652
+ node_fs.default.rmSync(staged, {
2653
+ recursive: true,
2654
+ force: true
2655
+ });
2656
+ }
2657
+ }
2658
+ function stage(folder, entries) {
2659
+ node_fs.default.mkdirSync(folder, { recursive: true });
2660
+ for (const [file, content] of entries) {
2661
+ const target = node_path.default.join(folder, file);
2662
+ node_fs.default.mkdirSync(node_path.default.dirname(target), { recursive: true });
2663
+ node_fs.default.writeFileSync(target, content);
2664
+ }
2665
+ }
2666
+ function walk(root, sub = "") {
2667
+ return node_fs.default.readdirSync(node_path.default.join(root, sub), { withFileTypes: true }).flatMap((item) => {
2668
+ const rel = node_path.default.join(sub, item.name);
2669
+ return item.isDirectory() ? walk(root, rel) : [rel];
2670
+ });
2671
+ }
2574
2672
  var say = (line) => void process.stderr.write(`${line}\n`);
2575
2673
  /** The fonts the brand's own text can be set in: the folders given and named by BLAZON_DECK_FONTS, then the config's */
2576
2674
  function fontsFor(brand, folders) {
@@ -2593,11 +2691,6 @@ async function draw(brand, siteDir, favicons, table, skip) {
2593
2691
  await browser.close();
2594
2692
  }
2595
2693
  }
2596
- /** Written once, whole, after the browser is done: a call that ends earlier leaves nothing behind */
2597
- function write(file, pdf) {
2598
- node_fs.default.writeFileSync(`${file}.part`, pdf);
2599
- node_fs.default.renameSync(`${file}.part`, file);
2600
- }
2601
2694
  async function build(text) {
2602
2695
  const job = jobFor(text);
2603
2696
  const brand = readBrand(job.brand);
@@ -2625,7 +2718,7 @@ async function build(text) {
2625
2718
  path: "brand-deck.pdf",
2626
2719
  message: `the deck planned ${deck.slides.length} slides, and the PDF has ${deck.pages} pages`
2627
2720
  });
2628
- write(node_path.default.join(job.outDir, "brand-deck.pdf"), deck.pdf);
2721
+ writeFolder(job.outDir, [["brand-deck.pdf", deck.pdf]]);
2629
2722
  return { findings };
2630
2723
  }
2631
2724
  var USAGE = "usage: blazon-blazon.brand-deck BRAND.json [-o deck.pdf] [--favicons DIR] [--skip CATEGORY]... [--fonts DIR]...";
@@ -2679,7 +2772,7 @@ async function cli(args) {
2679
2772
  try {
2680
2773
  const table = fontsFor(brand, folders);
2681
2774
  const deck = await draw(brand, node_path.default.dirname(node_path.default.resolve(brandFile)), favicons ? readFavicons(favicons, brand, say) : null, table, left);
2682
- write(output, deck.pdf);
2775
+ writeFolder(node_path.default.dirname(node_path.default.resolve(output)), [[node_path.default.basename(output), deck.pdf]]);
2683
2776
  process.stdout.write(`wrote ${output} (${deck.slides.length} slides)\n`);
2684
2777
  return 0;
2685
2778
  } catch (error) {
@@ -30,9 +30,9 @@ var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__ge
30
30
  }) : target, mod));
31
31
  let node_fs = require("node:fs");
32
32
  node_fs = __toESM(node_fs, 1);
33
+ let playwright_core = require("playwright-core");
33
34
  let node_path = require("node:path");
34
35
  node_path = __toESM(node_path, 1);
35
- let playwright_core = require("playwright-core");
36
36
  /** What the findings may take on the wire, in bytes. The limit is 65,536; the rest is the envelope, the summary finding and a newline, with room to spare. */
37
37
  var FINDINGS_BUDGET = 6e4;
38
38
  var RANK = {
@@ -8080,6 +8080,48 @@ function drawnSize(symbol, size, share) {
8080
8080
  height: symbol.height * scale
8081
8081
  };
8082
8082
  }
8083
+ /** Compares two strings by UTF-16 code unit. It gives the same answer on every host, which a locale-aware compare does not. */
8084
+ function compareText(a, b) {
8085
+ return a < b ? -1 : a > b ? 1 : 0;
8086
+ }
8087
+ /** The order a reader follows when it has no preference of its own: vector first, then the rasters, then any other format by name. */
8088
+ var DEFAULT_FORMAT_ORDER = [
8089
+ "svg",
8090
+ "png",
8091
+ "webp",
8092
+ "jpg",
8093
+ "gif"
8094
+ ];
8095
+ var pathOf = (record) => record.filePath ?? record.file ?? "";
8096
+ /** The file name of a representation, the last segment of its path. */
8097
+ function fileNameOf(record) {
8098
+ const path = pathOf(record);
8099
+ return path.slice(path.lastIndexOf("/") + 1);
8100
+ }
8101
+ var defaultRank = (format) => {
8102
+ const at = DEFAULT_FORMAT_ORDER.indexOf(format === "jpeg" ? "jpg" : format);
8103
+ return at === -1 ? DEFAULT_FORMAT_ORDER.length : at;
8104
+ };
8105
+ /** The order of two representations of one id: the caller's formats first, then the default order, then the file name. */
8106
+ function compareRepresentations(a, b, options = {}) {
8107
+ const preferred = options.formats;
8108
+ if (preferred) {
8109
+ const rank = (r) => {
8110
+ const at = preferred.indexOf(r.format);
8111
+ return at === -1 ? preferred.length : at;
8112
+ };
8113
+ const byWish = rank(a) - rank(b);
8114
+ if (byWish !== 0) return byWish;
8115
+ }
8116
+ return defaultRank(a.format) - defaultRank(b.format) || compareText(a.format, b.format) || compareText(fileNameOf(a), fileNameOf(b)) || compareText(pathOf(a), pathOf(b));
8117
+ }
8118
+ /**
8119
+ * The one file an id means for a reader. With `formats`, the first of them that the id has (none when it has none of them: the
8120
+ * caller says what to do, such as "needs an SVG: logos/mark has png only"); without, the first in the default order.
8121
+ */
8122
+ function pickRepresentation(records, id, options = {}) {
8123
+ return records.filter((record) => record.id === id && (!options.formats || options.formats.includes(record.format))).sort((a, b) => compareRepresentations(a, b, options))[0];
8124
+ }
8083
8125
  var KEYS = [
8084
8126
  "symbol",
8085
8127
  "ground",
@@ -8176,15 +8218,16 @@ function planFor(request) {
8176
8218
  const { options, brand } = request;
8177
8219
  for (const key of Object.keys(options)) if (!KEYS.includes(key)) throw new OptionError(`unknown option ${JSON.stringify(key)}; known: ${KEYS.join(", ")}`);
8178
8220
  const assets = Array.isArray(brand.assets) ? brand.assets.filter(isObject) : [];
8221
+ const records = assets.filter((asset) => typeof asset.id === "string" && typeof asset.format === "string");
8179
8222
  const named = asString(options.symbol, "symbol");
8180
8223
  const marks = assets.filter((asset) => isObject(asset.meta) && asset.meta.lockup === "mark" && asset.format === "svg");
8181
- const symbol = named ? assets.find((asset) => asset.id === named) : marks.length === 1 ? marks[0] : void 0;
8224
+ const symbol = named ? pickRepresentation(records, named, { formats: ["svg"] }) ?? pickRepresentation(records, named) : marks.length === 1 ? marks[0] : void 0;
8182
8225
  if (!symbol) {
8183
8226
  if (named) throw new OptionError(`symbol names the asset ${named}, and the brand has none with that id`);
8184
8227
  throw new Cannot(`no symbol to draw from: name an SVG asset in the option symbol (such as "logos/mark"), or give exactly one SVG asset the sidecar lockup "mark" (${marks.length} have it)`);
8185
8228
  }
8186
8229
  const symbolId = String(symbol.id);
8187
- if (symbol.format !== "svg") throw new Cannot(`the symbol ${symbolId} is a ${String(symbol.format)} file; the plugin draws from an SVG`);
8230
+ if (symbol.format !== "svg") throw new Cannot(`the symbol ${symbolId} needs an SVG: it has ${records.filter((asset) => asset.id === symbolId).map((asset) => asset.format).join(", ")} only`);
8188
8231
  const symbolSize = {
8189
8232
  width: Number(symbol.width),
8190
8233
  height: Number(symbol.height)
@@ -8220,7 +8263,7 @@ function planFor(request) {
8220
8263
  const supplied = /* @__PURE__ */ new Map();
8221
8264
  const category = asString(options.supplied, "supplied");
8222
8265
  if (category && request.type === "build") for (const [stem, want] of Object.entries(SUPPLIED)) {
8223
- const asset = assets.find((item) => item.id === `${category}/${stem}`);
8266
+ const asset = pickRepresentation(records, `${category}/${stem}`, { formats: [want.format] }) ?? pickRepresentation(records, `${category}/${stem}`);
8224
8267
  if (!asset) continue;
8225
8268
  const id = String(asset.id);
8226
8269
  if (asset.format !== want.format) throw new Cannot(`the supplied ${id} is a ${String(asset.format)} file; ${want.file} must be a ${want.format.toUpperCase()}`);
@@ -8723,6 +8766,77 @@ function ico(images) {
8723
8766
  });
8724
8767
  return Buffer.concat([head, ...images.map((image) => image.png)]);
8725
8768
  }
8769
+ /** Replaces `dir` with a folder holding exactly `entries`: what `dir` held before, such as a file of an earlier run, is gone. */
8770
+ function replaceFolder(dir, entries) {
8771
+ const staged = `${dir}.part`;
8772
+ const old = `${dir}.old`;
8773
+ node_fs.default.rmSync(staged, {
8774
+ recursive: true,
8775
+ force: true
8776
+ });
8777
+ node_fs.default.rmSync(old, {
8778
+ recursive: true,
8779
+ force: true
8780
+ });
8781
+ try {
8782
+ stage(staged, entries);
8783
+ const had = node_fs.default.lstatSync(dir, { throwIfNoEntry: false }) !== void 0;
8784
+ if (had) node_fs.default.renameSync(dir, old);
8785
+ try {
8786
+ node_fs.default.renameSync(staged, dir);
8787
+ } catch (error) {
8788
+ if (had) node_fs.default.renameSync(old, dir);
8789
+ throw error;
8790
+ }
8791
+ } finally {
8792
+ node_fs.default.rmSync(staged, {
8793
+ recursive: true,
8794
+ force: true
8795
+ });
8796
+ }
8797
+ node_fs.default.rmSync(old, {
8798
+ recursive: true,
8799
+ force: true
8800
+ });
8801
+ }
8802
+ /**
8803
+ * Writes `entries` into `dir`, leaving the other files in it. A file is never seen half written. Used where `dir` is the host's own
8804
+ * out_dir, which a plugin may not replace, so the set is staged in a folder inside it and moved up once it is all made.
8805
+ */
8806
+ function writeFolder(dir, entries) {
8807
+ const staged = node_path.default.join(dir, ".part");
8808
+ node_fs.default.rmSync(staged, {
8809
+ recursive: true,
8810
+ force: true
8811
+ });
8812
+ try {
8813
+ stage(staged, entries);
8814
+ for (const file of walk(staged)) {
8815
+ const target = node_path.default.join(dir, file);
8816
+ node_fs.default.mkdirSync(node_path.default.dirname(target), { recursive: true });
8817
+ node_fs.default.renameSync(node_path.default.join(staged, file), target);
8818
+ }
8819
+ } finally {
8820
+ node_fs.default.rmSync(staged, {
8821
+ recursive: true,
8822
+ force: true
8823
+ });
8824
+ }
8825
+ }
8826
+ function stage(folder, entries) {
8827
+ node_fs.default.mkdirSync(folder, { recursive: true });
8828
+ for (const [file, content] of entries) {
8829
+ const target = node_path.default.join(folder, file);
8830
+ node_fs.default.mkdirSync(node_path.default.dirname(target), { recursive: true });
8831
+ node_fs.default.writeFileSync(target, content);
8832
+ }
8833
+ }
8834
+ function walk(root, sub = "") {
8835
+ return node_fs.default.readdirSync(node_path.default.join(root, sub), { withFileTypes: true }).flatMap((item) => {
8836
+ const rel = node_path.default.join(sub, item.name);
8837
+ return item.isDirectory() ? walk(root, rel) : [rel];
8838
+ });
8839
+ }
8726
8840
  /** The folder of the site that holds the copy, and the file the viewer asks for in it */
8727
8841
  var SITE_FOLDER = "favicons";
8728
8842
  var DATA_FILE = "favicons.json";
@@ -8748,13 +8862,7 @@ function checkSite(siteDir) {
8748
8862
  }
8749
8863
  /** Replaces the site's favicons/ with the files the Favicons page shows, taken from the set just made. */
8750
8864
  function copyToSite(siteDir, files) {
8751
- const dir = node_path.default.join(siteDir, SITE_FOLDER);
8752
- node_fs.default.rmSync(dir, {
8753
- recursive: true,
8754
- force: true
8755
- });
8756
- node_fs.default.mkdirSync(dir, { recursive: true });
8757
- for (const file of [...SITE_FILES].sort()) node_fs.default.writeFileSync(node_path.default.join(dir, file), files.get(file));
8865
+ replaceFolder(node_path.default.join(siteDir, SITE_FOLDER), [...SITE_FILES].sort().map((file) => [file, files.get(file)]));
8758
8866
  }
8759
8867
  /** Files made once, whole, after the browser is done: a call that ends earlier leaves out_dir empty. */
8760
8868
  async function draw(plan) {
@@ -8830,7 +8938,7 @@ async function build(text) {
8830
8938
  path: file,
8831
8939
  message: `${file} is the project's own file, used in place of the one drawn from ${plan.symbolId}`
8832
8940
  });
8833
- for (const [file, data] of [...files].sort(([a], [b]) => a < b ? -1 : 1)) node_fs.default.writeFileSync(node_path.default.join(request.outDir, file), data);
8941
+ writeFolder(request.outDir, [...files].sort(([a], [b]) => a < b ? -1 : 1));
8834
8942
  copyToSite(request.siteDir, files);
8835
8943
  return { findings };
8836
8944
  }
@@ -188,6 +188,50 @@ function siteFile(siteDir, file) {
188
188
  const real = node_fs.default.realpathSync(full);
189
189
  return real.startsWith(root + node_path.default.sep) ? node_fs.default.readFileSync(real) : void 0;
190
190
  }
191
+ /** Compares two strings by UTF-16 code unit. It gives the same answer on every host, which a locale-aware compare does not. */
192
+ function compareText(a, b) {
193
+ return a < b ? -1 : a > b ? 1 : 0;
194
+ }
195
+ /** The order a reader follows when it has no preference of its own: vector first, then the rasters, then any other format by name. */
196
+ var DEFAULT_FORMAT_ORDER = [
197
+ "svg",
198
+ "png",
199
+ "webp",
200
+ "jpg",
201
+ "gif"
202
+ ];
203
+ var pathOf = (record) => record.filePath ?? record.file ?? "";
204
+ /** The file name of a representation, the last segment of its path. */
205
+ function fileNameOf(record) {
206
+ const path = pathOf(record);
207
+ return path.slice(path.lastIndexOf("/") + 1);
208
+ }
209
+ var defaultRank = (format) => {
210
+ const at = DEFAULT_FORMAT_ORDER.indexOf(format === "jpeg" ? "jpg" : format);
211
+ return at === -1 ? DEFAULT_FORMAT_ORDER.length : at;
212
+ };
213
+ /** The order of two representations of one id: the caller's formats first, then the default order, then the file name. */
214
+ function compareRepresentations(a, b, options = {}) {
215
+ const preferred = options.formats;
216
+ if (preferred) {
217
+ const rank = (r) => {
218
+ const at = preferred.indexOf(r.format);
219
+ return at === -1 ? preferred.length : at;
220
+ };
221
+ const byWish = rank(a) - rank(b);
222
+ if (byWish !== 0) return byWish;
223
+ }
224
+ return defaultRank(a.format) - defaultRank(b.format) || compareText(a.format, b.format) || compareText(fileNameOf(a), fileNameOf(b)) || compareText(pathOf(a), pathOf(b));
225
+ }
226
+ /**
227
+ * For a reader that keys a map by id while it reads the records: puts `record` in the map unless the map already holds a better
228
+ * representation of that id. A record in a format the caller does not list is kept only when the id has no other, so the caller
229
+ * can say what is wrong with it. The map ends the same whatever order the records come in.
230
+ */
231
+ function keepRepresentation(map, record, options = {}) {
232
+ const held = map.get(record.id);
233
+ if (!held || compareRepresentations(record, held, options) < 0) map.set(record.id, record);
234
+ }
191
235
  /** A non-empty string (not only whitespace), or undefined. */
192
236
  var text = (value) => typeof value === "string" && value.trim() !== "" ? value : void 0;
193
237
  /** An asset's id, file, format and category (the first segment of the id when the entry has none); undefined when the entry lacks one of the first three. */
@@ -217,7 +261,7 @@ function readBrand(brand) {
217
261
  const assets = /* @__PURE__ */ new Map();
218
262
  for (const raw of Array.isArray(root.assets) ? root.assets : []) {
219
263
  const asset = readBaseAsset(raw);
220
- if (asset) assets.set(asset.id, asset);
264
+ if (asset) keepRepresentation(assets, asset, { formats: MEASURED });
221
265
  }
222
266
  const accent = text((isObject(root.theme) && isObject(root.theme.roles) ? root.theme.roles : {}).accent);
223
267
  return {
@@ -217,6 +217,50 @@ function artworkSize(asset) {
217
217
  height: box[3]
218
218
  };
219
219
  }
220
+ /** Compares two strings by UTF-16 code unit. It gives the same answer on every host, which a locale-aware compare does not. */
221
+ function compareText(a, b) {
222
+ return a < b ? -1 : a > b ? 1 : 0;
223
+ }
224
+ /** The order a reader follows when it has no preference of its own: vector first, then the rasters, then any other format by name. */
225
+ var DEFAULT_FORMAT_ORDER = [
226
+ "svg",
227
+ "png",
228
+ "webp",
229
+ "jpg",
230
+ "gif"
231
+ ];
232
+ var pathOf = (record) => record.filePath ?? record.file ?? "";
233
+ /** The file name of a representation, the last segment of its path. */
234
+ function fileNameOf(record) {
235
+ const path = pathOf(record);
236
+ return path.slice(path.lastIndexOf("/") + 1);
237
+ }
238
+ var defaultRank = (format) => {
239
+ const at = DEFAULT_FORMAT_ORDER.indexOf(format === "jpeg" ? "jpg" : format);
240
+ return at === -1 ? DEFAULT_FORMAT_ORDER.length : at;
241
+ };
242
+ /** The order of two representations of one id: the caller's formats first, then the default order, then the file name. */
243
+ function compareRepresentations(a, b, options = {}) {
244
+ const preferred = options.formats;
245
+ if (preferred) {
246
+ const rank = (r) => {
247
+ const at = preferred.indexOf(r.format);
248
+ return at === -1 ? preferred.length : at;
249
+ };
250
+ const byWish = rank(a) - rank(b);
251
+ if (byWish !== 0) return byWish;
252
+ }
253
+ return defaultRank(a.format) - defaultRank(b.format) || compareText(a.format, b.format) || compareText(fileNameOf(a), fileNameOf(b)) || compareText(pathOf(a), pathOf(b));
254
+ }
255
+ /**
256
+ * For a reader that keys a map by id while it reads the records: puts `record` in the map unless the map already holds a better
257
+ * representation of that id. A record in a format the caller does not list is kept only when the id has no other, so the caller
258
+ * can say what is wrong with it. The map ends the same whatever order the records come in.
259
+ */
260
+ function keepRepresentation(map, record, options = {}) {
261
+ const held = map.get(record.id);
262
+ if (!held || compareRepresentations(record, held, options) < 0) map.set(record.id, record);
263
+ }
220
264
  /** A non-empty string (not only whitespace), or undefined. */
221
265
  var text = (value) => typeof value === "string" && value.trim() !== "" ? value : void 0;
222
266
  /** An asset's id, file, format and category (the first segment of the id when the entry has none); undefined when the entry lacks one of the first three. */
@@ -250,7 +294,7 @@ function readBrand(brand) {
250
294
  height: raw.height,
251
295
  viewBox: text(raw.viewBox)
252
296
  });
253
- assets.set(id, {
297
+ keepRepresentation(assets, {
254
298
  id,
255
299
  name: text(raw.name) ?? id.split("/").pop(),
256
300
  category,
@@ -191,6 +191,58 @@ function artworkSize(asset) {
191
191
  height: box[3]
192
192
  };
193
193
  }
194
+ /** Compares two strings by UTF-16 code unit. It gives the same answer on every host, which a locale-aware compare does not. */
195
+ function compareText(a, b) {
196
+ return a < b ? -1 : a > b ? 1 : 0;
197
+ }
198
+ /** The order a reader follows when it has no preference of its own: vector first, then the rasters, then any other format by name. */
199
+ var DEFAULT_FORMAT_ORDER = [
200
+ "svg",
201
+ "png",
202
+ "webp",
203
+ "jpg",
204
+ "gif"
205
+ ];
206
+ var pathOf = (record) => record.filePath ?? record.file ?? "";
207
+ /** The file name of a representation, the last segment of its path. */
208
+ function fileNameOf(record) {
209
+ const path = pathOf(record);
210
+ return path.slice(path.lastIndexOf("/") + 1);
211
+ }
212
+ var defaultRank = (format) => {
213
+ const at = DEFAULT_FORMAT_ORDER.indexOf(format === "jpeg" ? "jpg" : format);
214
+ return at === -1 ? DEFAULT_FORMAT_ORDER.length : at;
215
+ };
216
+ /** The order of two representations of one id: the caller's formats first, then the default order, then the file name. */
217
+ function compareRepresentations(a, b, options = {}) {
218
+ const preferred = options.formats;
219
+ if (preferred) {
220
+ const rank = (r) => {
221
+ const at = preferred.indexOf(r.format);
222
+ return at === -1 ? preferred.length : at;
223
+ };
224
+ const byWish = rank(a) - rank(b);
225
+ if (byWish !== 0) return byWish;
226
+ }
227
+ return defaultRank(a.format) - defaultRank(b.format) || compareText(a.format, b.format) || compareText(fileNameOf(a), fileNameOf(b)) || compareText(pathOf(a), pathOf(b));
228
+ }
229
+ /**
230
+ * For a reader that keys a map by id while it reads the records: puts `record` in the map unless the map already holds a better
231
+ * representation of that id. A record in a format the caller does not list is kept only when the id has no other, so the caller
232
+ * can say what is wrong with it. The map ends the same whatever order the records come in.
233
+ */
234
+ function keepRepresentation(map, record, options = {}) {
235
+ const held = map.get(record.id);
236
+ if (!held || compareRepresentations(record, held, options) < 0) map.set(record.id, record);
237
+ }
238
+ /**
239
+ * The record of one named file among all the records, for a logo or other setting that names a FILE and not an id: the file is that
240
+ * one, whatever else its id has, so the lookup runs over every record and never over the one a reader kept for the id. `file` is a
241
+ * path as brand.json writes it (`file`) or as the catalog does (`filePath`).
242
+ */
243
+ function findByFile(records, file) {
244
+ return records.find((record) => record.file === file || record.filePath === file);
245
+ }
194
246
  /** A non-empty string (not only whitespace), or undefined. */
195
247
  var text = (value) => typeof value === "string" && value.trim() !== "" ? value : void 0;
196
248
  /** An asset's id, file, format and category (the first segment of the id when the entry has none); undefined when the entry lacks one of the first three. */
@@ -226,6 +278,13 @@ function readLogo(root) {
226
278
  onDark: text(logo.onDark)
227
279
  };
228
280
  }
281
+ /** The formats an Office template takes, best first (`logoFor` in main.ts: SVG, PNG, JPEG, GIF); an id with none of them still keeps one file, so the plugin can say it is not supported. */
282
+ var OFFICE_FORMATS = [
283
+ "svg",
284
+ "png",
285
+ "jpg",
286
+ "gif"
287
+ ];
229
288
  var REM_PX = 16;
230
289
  var length = (value, unit) => isObject(value) && typeof value.value === "number" && Number.isFinite(value.value) && typeof value.unit === "string" && unit.includes(value.unit) ? value.value : void 0;
231
290
  function readStyle(path, parts) {
@@ -267,6 +326,7 @@ function readBrand(brand) {
267
326
  typography.push(readStyle(item.path, item.resolvedValue));
268
327
  }
269
328
  const assets = /* @__PURE__ */ new Map();
329
+ const files = [];
270
330
  for (const raw of Array.isArray(root.assets) ? root.assets : []) {
271
331
  const base = readBaseAsset(raw);
272
332
  if (!base || !isObject(raw)) continue;
@@ -276,13 +336,15 @@ function readBrand(brand) {
276
336
  height: raw.height,
277
337
  viewBox: text(raw.viewBox)
278
338
  });
279
- assets.set(id, {
339
+ const read = {
280
340
  id,
281
341
  file,
282
342
  format,
283
343
  ...size && { size },
284
344
  meta: readMeta(raw)
285
- });
345
+ };
346
+ files.push(read);
347
+ keepRepresentation(assets, read, { formats: OFFICE_FORMATS });
286
348
  }
287
349
  return {
288
350
  title: (isObject(root.brand) ? text(root.brand.title) : void 0) ?? "Brand",
@@ -291,6 +353,7 @@ function readBrand(brand) {
291
353
  named,
292
354
  typography,
293
355
  assets,
356
+ files,
294
357
  logo: readLogo(root)
295
358
  };
296
359
  }
@@ -442,7 +505,7 @@ function madeFor(asset, brand) {
442
505
  }
443
506
  /** The logo for each kind of surface: the one `logo` names first, then the pair brand.json names, then the logos folder. */
444
507
  function chooseLogos(brand, options) {
445
- const byFile = (file) => file ? [...brand.assets.values()].find((asset) => asset.file === file) : void 0;
508
+ const byFile = (file) => file ? findByFile(brand.files, file) : void 0;
446
509
  const pool = [
447
510
  options.logo ? brand.assets.get(options.logo) : void 0,
448
511
  byFile(brand.logo.onLight),
@@ -41,7 +41,7 @@ The Swift file type-checks with `swiftc -typecheck` for macOS 10.15 and iOS 13,
41
41
  }
42
42
  ```
43
43
 
44
- Run on blazon's own example brand with this entry, `blazon tokens` writes the same 39 files as with no options except for the iOS names below, and no `radius.*` dimension in any output.
44
+ Run on blazon's own example brand with this entry, `blazon tokens` writes the same files as with no options except for the iOS names below, and no `radius.*` dimension in any output.
45
45
 
46
46
  ## What the prefix reaches
47
47