@stacksjs/defaults 0.75.361 → 0.75.362

package/ai/skills/stacks-technical-diagrams/renderers/shared/automatic-labels.mjs

@@ -0,0 +1,290 @@
+import { normalizeRoutePoints, rectsOverlap, segmentRectClearanceWithin } from './geometry.mjs';
+import { createSpatialGrid } from './spatial-grid.mjs';
+
+// A bounded fallback for an unpinned label whose usual position collides.
+// It never routes an edge, moves a node, expands the canvas, or rewrites input.
+export function placeAutomaticLabels({
+  labels, routes, components, titles, viewBox, placementBottom = viewBox[1], fallbackRing = true, keepFallbackNearRoute = false,
+  gridSweep = false, maxOwnRouteDistance = Infinity,
+}) {
+  const placed = [...labels];
+  const obstacles = [...components, ...titles];
+  const segments = routes.flatMap(({ relationIndex, points }) => {
+    const normalized = normalizeRoutePoints(points);
+    return normalized.slice(1).map((end, index) => ({ relationIndex, start: normalized[index], end }));
+  });
+  const inside = rect => (
+    rect.x >= 0 && rect.y >= 0
+    && rect.x + rect.width <= viewBox[0] && rect.y + rect.height <= viewBox[1]
+  );
+  // The mask test asked every segment about every candidate position. Segments
+  // go into a uniform grid once, and a candidate only asks the cells it covers.
+  const SEGMENT_CELL = 120;
+  const segmentGrid = createSpatialGrid(SEGMENT_CELL);
+  for (const segment of segments) {
+    const [sx, sy] = segment.start;
+    const [ex, ey] = segment.end;
+    segmentGrid.insert({
+      minX: Math.min(sx, ex), maxX: Math.max(sx, ex),
+      minY: Math.min(sy, ey), maxY: Math.max(sy, ey),
+    }, segment);
+  }
+  const segmentsNear = (rect, margin) => segmentGrid.query({
+    minX: rect.x - margin, maxX: rect.x + rect.width + margin,
+    minY: rect.y - margin, maxY: rect.y + rect.height + margin,
+  });
+  const masksRoute = rect => {
+    for (const segment of segmentsNear(rect, 4)) {
+      if (segment.relationIndex === rect.relationIndex) continue;
+      if (segmentRectClearanceWithin(segment, rect, 4) + 0.0001 < 4) return true;
+    }
+    return false;
+  };
+  const overlapsLabel = (rect, index, gap = 0) => placed.some((other, otherIndex) => (
+    otherIndex !== index && rectsOverlap(rect, other, gap)
+  ));
+  const clear = (rect, index) => (
+    inside(rect) && rect.y + rect.height <= placementBottom
+    && !obstacles.some(obstacle => rectsOverlap(rect, obstacle, 2))
+    && !overlapsLabel(rect, index, 2) && !masksRoute(rect)
+    && (!Number.isFinite(maxOwnRouteDistance) || segments.some(segment =>
+      segment.relationIndex === rect.relationIndex
+      && segmentRectClearanceWithin(segment, rect, maxOwnRouteDistance) <= maxOwnRouteDistance))
+  );
+  const rectAt = (label, lx, ly) => ({
+    ...label, lx, ly, x: lx - label.width / 2, y: ly - 10,
+  });
+  // Fixed fractions can miss a narrow free slot. Try the ends of the free
+  // intervals beside an orthogonal segment, using obstacle edges rather
+  // than a finer sampling grid. The ordinary clearance test still decides
+  // whether a candidate is usable; this search never changes geometry.
+  const slidingCandidates = (label, index, { start: a, end: b }) => {
+    const horizontal = Math.abs(a[1] - b[1]) < 0.0001;
+    if (!horizontal && Math.abs(a[0] - b[0]) >= 0.0001) return [];
+    const axis = horizontal ? 'x' : 'y';
+    const size = horizontal ? 'width' : 'height';
+    const across = horizontal ? 'y' : 'x';
+    const crossSize = horizontal ? 'height' : 'width';
+    const low = Math.min(a[horizontal ? 0 : 1], b[horizontal ? 0 : 1]) + 8;
+    const high = Math.max(a[horizontal ? 0 : 1], b[horizontal ? 0 : 1]) - label[size] - 8;
+    if (high < low) return [];
+    const offsets = horizontal
+      ? [a[1] - 20, a[1] + 10, a[1] - 28, a[1] + 18]
+      : [a[0] - label.width - 6, a[0] + 6, a[0] - label.width - 14, a[0] + 14];
+    return offsets.flatMap(offset => {
+      const band = { ...label, [axis]: low, [size]: high - low + label[size], [across]: offset };
+      const blockers = [
+        ...obstacles.map(rect => ({ rect, gap: 2 })),
+        ...placed.filter((_, otherIndex) => otherIndex !== index).map(rect => ({ rect, gap: 2 })),
+        ...segmentsNear(band, 4).filter(segment => segment.relationIndex !== label.relationIndex).map(segment => ({
+          rect: {
+            x: Math.min(segment.start[0], segment.end[0]), y: Math.min(segment.start[1], segment.end[1]),
+            width: Math.abs(segment.end[0] - segment.start[0]), height: Math.abs(segment.end[1] - segment.start[1]),
+          }, gap: 4,
+        })),
+      ];
+      const positions = [Math.max(low, Math.min(high, label[axis])), low, high];
+      for (const { rect, gap } of blockers) {
+        if (offset + label[crossSize] + gap <= rect[across]
+          || rect[across] + rect[crossSize] + gap <= offset) continue;
+        positions.push(rect[axis] - gap - label[size], rect[axis] + rect[size] + gap);
+      }
+      return [...new Set(positions)].filter(position => position >= low && position <= high)
+        .sort((left, right) => Math.abs(left - label[axis]) - Math.abs(right - label[axis]))
+        .map(position => {
+          const rect = { ...label, [axis]: position, [across]: offset };
+          return rectAt(label, rect.x + label.width / 2, rect.y + 10);
+        });
+    });
+  };
+  // An opted-in grid layout runs parallel lines through shared gaps. Rank
+  // every position along all of the label's own segments: beside the line
+  // first, then centred on its own line (the plate interrupts only that
+  // line), then stepping outward past neighbouring parallels.
+  const gridCandidates = (label) => {
+    const fractions = [0.5, 0.25, 0.75, 0.375, 0.625, 0.125, 0.875];
+    const ranked = [];
+    // A close parallel of another relationship on one side (a reciprocal
+    // pair) makes a label on that side read as the neighbour's: prefer the
+    // far side.
+    const parallelOnLowSide = (a, b, axis) => {
+      const across = 1 - axis;
+      const [low, high] = [Math.min(a[axis], b[axis]), Math.max(a[axis], b[axis])];
+      let nearest = null;
+      for (const other of segments) {
+        if (other.relationIndex === label.relationIndex) continue;
+        if (Math.abs(other.start[across] - other.end[across]) > 0.0001) continue;
+        const distance = other.start[across] - a[across];
+        if (Math.abs(distance) < 0.0001 || Math.abs(distance) > 36) continue;
+        const overlap = Math.min(high, Math.max(other.start[axis], other.end[axis]))
+          - Math.max(low, Math.min(other.start[axis], other.end[axis]));
+        if (overlap <= 0) continue;
+        if (nearest === null || Math.abs(distance) < Math.abs(nearest)) nearest = distance;
+      }
+      return nearest !== null && nearest < 0;
+    };
+    for (const { start: a, end: b } of segments.filter(segment => segment.relationIndex === label.relationIndex)) {
+      if (Math.abs(a[1] - b[1]) < 0.0001 && Math.abs(a[0] - b[0]) >= label.width + 16) {
+        const [above, below] = parallelOnLowSide(a, b, 0) ? [1, 0] : [0, 1];
+        for (const fraction of fractions) {
+          const x = a[0] + (b[0] - a[0]) * fraction;
+          if (Math.min(Math.abs(x - a[0]), Math.abs(x - b[0])) < label.width / 2 + 6) continue;
+          ranked.push([above, x, a[1] - 10], [below, x, a[1] + 20], [2, x, a[1] + 3], [3, x, a[1] - 18], [3, x, a[1] + 28]);
+        }
+      } else if (Math.abs(a[0] - b[0]) < 0.0001 && Math.abs(a[1] - b[1]) >= label.height + 16) {
+        const leftFirst = !parallelOnLowSide(a, b, 1);
+        for (const fraction of fractions) {
+          const y = a[1] + (b[1] - a[1]) * fraction;
+          if (Math.min(Math.abs(y - a[1]), Math.abs(y - b[1])) < label.height / 2 + 6) continue;
+          ranked.push([2, a[0], y + 3]);
+          [6, 14, 22, 30, 38, 46, 54].forEach((offset, step) => {
+            const tier = step === 0 ? 0 : step === 1 ? 1 : 2 + step;
+            const left = [tier + (leftFirst ? 0 : 0.5), a[0] - label.width / 2 - offset, y + 3];
+            const right = [tier + (leftFirst ? 0.5 : 0), a[0] + label.width / 2 + offset, y + 3];
+            ranked.push(left, right);
+          });
+        }
+      }
+    }
+    return ranked.map((entry, order) => [...entry, order])
+      .sort((left, right) => left[0] - right[0] || left[3] - right[3])
+      .map(([, lx, ly]) => [lx, ly]);
+  };
+
+  const pinned = label => ['labelAt', 'labelDx', 'labelDy', 'labelSegment']
+    .some(key => label.relation[key] !== undefined);
+  const needsPlacement = (label, index) => !inside(label)
+    || components.some(component => rectsOverlap(label, component, -2))
+    || titles.some(title => rectsOverlap(label, title))
+    || overlapsLabel(label, index) || masksRoute(label);
+  const placeLabel = (index, rerank) => {
+    const label = placed[index];
+    // Match actual defect thresholds before searching; a valid placement is
+    // not a reason to restyle the diagram. New placements leave extra space.
+    // The grid ranking already starts from the preferred position, so it
+    // also re-ranks labels whose default spot is merely valid.
+    if (!rerank && !needsPlacement(label, index)) return;
+    if (rerank) {
+      // Callers measure the plate one pixel higher than rectAt; test with a
+      // pixel of slack so the chosen position also passes their clearance.
+      const replacement = gridCandidates(label).map(([lx, ly]) => rectAt(label, lx, ly))
+        .find(rect => clear({ ...rect, x: rect.x - 1, y: rect.y - 1, width: rect.width + 2, height: rect.height + 2 }, index));
+      if (replacement) {
+        placed[index] = replacement;
+        return;
+      }
+    }
+    for (const segment of segments.filter(segment => segment.relationIndex === label.relationIndex)) {
+      const [a, b] = [segment.start, segment.end];
+      let candidates = [];
+      // These candidates sit beside the line. They need the same 2px node
+      // clearance checked by clear(), not 8px reserved at each endpoint.
+      // Extra endpoint padding can hide a valid outer slot for a reciprocal
+      // pair and make the planner send its other arrow around both nodes.
+      if (Math.abs(a[1] - b[1]) < 0.0001 && Math.abs(a[0] - b[0]) >= label.width + 4) {
+        candidates = [0.5, 0.25, 0.75, 0.125, 0.875].flatMap(fraction => {
+          const x = a[0] + (b[0] - a[0]) * fraction;
+          if (Math.min(Math.abs(x - a[0]), Math.abs(x - b[0])) < 8) return [];
+          return [
+            [x, a[1] - 10],
+            [x, a[1] + 20],
+            [x, a[1] - 18],
+            [x, a[1] + 28],
+          ];
+        });
+      } else if (Math.abs(a[0] - b[0]) < 0.0001 && Math.abs(a[1] - b[1]) >= label.height + 16) {
+        candidates = [0.5, 0.25, 0.75, 0.125, 0.875].flatMap(fraction => {
+          const y = a[1] + (b[1] - a[1]) * fraction;
+          if (Math.min(Math.abs(y - a[1]), Math.abs(y - b[1])) < 8) return [];
+          return [
+            [a[0] - label.width / 2 - 6, y + 3],
+            [a[0] + label.width / 2 + 6, y + 3],
+            [a[0] - label.width / 2 - 14, y + 3],
+            [a[0] + label.width / 2 + 14, y + 3],
+          ];
+        });
+      }
+      const replacement = candidates.map(([lx, ly]) => rectAt(label, lx, ly))
+        .find(rect => clear(rect, index));
+      if (replacement) {
+        placed[index] = replacement;
+        break;
+      }
+    }
+    if (placed[index] !== label) return;
+    const sliding = segments.filter(segment => segment.relationIndex === label.relationIndex)
+      .flatMap(segment => slidingCandidates(label, index, segment)).find(rect => clear(rect, index));
+    if (sliding) {
+      placed[index] = sliding;
+      return;
+    }
+    if (!fallbackRing) return;
+
+    // Dense but valid topologies can leave every point directly beside the
+    // relationship occupied by another route. Search a small deterministic
+    // ring around the current anchor and the relationship's segment centres.
+    // A collision-free island above a node is not a readable edge label.
+    // Architecture opts into keeping the mask within two label heights of
+    // its own route; shared callers retain their existing policy. If no nearby
+    // slot fits, retain the collision so validation can request more space.
+    const ownSegments = segments.filter(segment => segment.relationIndex === label.relationIndex);
+    const baseAnchors = [
+      [label.lx, label.ly],
+      ...ownSegments.map(segment => [
+        (segment.start[0] + segment.end[0]) / 2,
+        (segment.start[1] + segment.end[1]) / 2,
+      ]),
+    ];
+    const horizontalStep = label.width / 2 + 12;
+    const ringOffsets = [
+      [0, -28], [0, 38],
+      [-horizontalStep, -28], [horizontalStep, -28],
+      [-horizontalStep, 38], [horizontalStep, 38],
+      [-(label.width + 20), -52], [label.width + 20, -52],
+      [-(label.width + 20), 62], [label.width + 20, 62],
+      [-(label.width + 20), -76], [label.width + 20, -76],
+      [-(label.width + 20), 86], [label.width + 20, 86],
+    ];
+    const fallback = baseAnchors.flatMap(([baseX, baseY]) => (
+      ringOffsets.map(([dx, dy]) => rectAt(label, baseX + dx, baseY + dy))
+    )).find(rect => clear(rect, index) && (!keepFallbackNearRoute || ownSegments.some(segment => (
+      segmentRectClearanceWithin(segment, rect, label.height * 2) <= label.height * 2
+    ))));
+    if (fallback) placed[index] = fallback;
+  };
+  let pending = placed.map((_, index) => index).filter(index => !pinned(placed[index]));
+  // A later label can vacate the only slot available to an earlier one.
+  // Retry only unresolved labels after a move; accepted placements clear all
+  // current labels and fixed geometry, so each success retires one label.
+  // A stalled pass ends the search, with at most one pass per input label.
+  for (let pass = 0; pass < labels.length && pending.length; pass++) {
+    let moved = false;
+    for (const index of pending) {
+      const before = placed[index];
+      placeLabel(index, gridSweep && pass === 0);
+      moved ||= placed[index] !== before;
+    }
+    if (!moved) break;
+    pending = pending.filter(index => needsPlacement(placed[index], index));
+  }
+  return placed;
+}
+
+// The rect a single unpinned label would occupy given only its own route and
+// the nodes: what the planner reserves before the remaining routes are laid.
+// Only a placement beside the route itself is worth reserving; a label that
+// would already need the fallback ring is left to the final placement pass.
+export function reservedLabelRect({
+  label, points, routes = [], labels = [], components, viewBox = [Infinity, Infinity], placementBottom = Infinity,
+}) {
+  const [rect] = placeAutomaticLabels({
+    labels: [{ ...label, relationIndex: -1 }, ...labels.map(other => ({ ...other, relationIndex: -2 }))],
+    routes: [{ relationIndex: -1, points }, ...routes],
+    components,
+    titles: [],
+    viewBox,
+    placementBottom,
+    fallbackRing: false,
+  });
+  return components.some(component => rectsOverlap(rect, component, -2)) ? null : rect;
+}

package/ai/skills/stacks-technical-diagrams/renderers/shared/brand-marks.mjs

@@ -22,7 +22,7 @@ const MAX_HTML_BYTES = 256 * 1024;
 const MAX_IMAGE_BYTES = 1024 * 1024;
 const MAX_CAPTURE_CONCURRENCY = 3;
 const DEFAULT_CAPTURE_TIMEOUT_MS = 8000;
-const USER_AGENT = 'stacks-technical-diagrams brand-preview';
+const USER_AGENT = 'Archify/2.15 brand-preview';
 
 function lookupForms(value) {
   const raw = String(value ?? '').trim().toLocaleLowerCase('en-US');
@@ -50,6 +50,17 @@ function asUrl(value) {
   }
 }
 
+// Public provenance is separate from the URL used to reproduce a pinned asset.
+export function normalizeBrandSourceUrl(value) {
+  const url = asUrl(value);
+  if (!url) return null;
+  url.username = '';
+  url.password = '';
+  url.search = '';
+  url.hash = '';
+  return url.href;
+}
+
 function domainMark(hostname) {
   const host = hostname.toLocaleLowerCase('en-US').replace(/\.$/, '');
   const candidates = [...MARK_BY_DOMAIN.entries()]
@@ -181,7 +192,7 @@ function requestPinned(url, accept, target, deadline) {
     const request = transport.request(url, {
       method: 'GET',
       signal: timeoutSignal(Math.max(1, Math.min(4500, deadline - Date.now()))),
-      headers: { accept, 'user-agent': USER_AGENT },
+      headers: { accept, 'accept-encoding': 'identity', 'user-agent': USER_AGENT },
       // Reuse the exact public address that passed validation. This closes the
       // DNS-rebinding gap between checking a hostname and opening its socket.
       lookup(_hostname, options, callback) {
@@ -224,6 +235,13 @@ async function checkedFetch(input, accept, deadline) {
       response.body.resume();
       throw new Error(`brand link returned HTTP ${response.status}`);
     }
+    // Raw HTTP responses are not decompressed. Check successful bodies before
+    // HTML discovery or image validation so byte limits and digests stay valid.
+    const contentEncoding = (response.headers.get('content-encoding') || '').trim().toLowerCase();
+    if (contentEncoding && contentEncoding !== 'identity') {
+      response.body.destroy();
+      throw new Error(`unsupported brand content encoding ${contentEncoding}`);
+    }
     return { response, finalUrl: current };
   }
   throw new Error('brand link redirected too many times');
@@ -269,24 +287,135 @@ async function readLimited(response, maximum) {
   return Buffer.concat(chunks, total);
 }
 
-function attribute(tag, name) {
-  const match = tag.match(new RegExp(`\\b${name}\\s*=\\s*(?:"([^"]*)"|'([^']*)'|([^\\s>]+))`, 'i'));
-  return match ? (match[1] ?? match[2] ?? match[3] ?? '') : '';
+// Read only the bounded head, independent of network chunk boundaries. Scan
+// bytes once so many tiny chunks cannot cause repeated concatenation/rescanning.
+// Collect link tags in the same pass: markup in comments, raw text, attributes
+// or templates must not become an icon candidate or an early head ending.
+async function readHtmlHeadLinks(response, maximum, mediaType) {
+  const chunks = response.body && typeof response.body[Symbol.asyncIterator] === 'function'
+    ? response.body : [await readLimited(response, maximum)];
+  const buffer = Buffer.alloc(maximum);
+  const links = [];
+  let total = 0;
+  let tagStart = -1;
+  let quote = 0;
+  let comment = false;
+  let rawClosing = '';
+  let matched = 0;
+  let templateDepth = 0;
+  for await (const value of chunks) {
+    const chunk = Buffer.from(value);
+    const length = Math.min(chunk.length, maximum - total);
+    chunk.copy(buffer, total, 0, length);
+    for (let offset = 0; offset < length; offset++) {
+      const byte = chunk[offset];
+      const position = total + offset;
+      if (comment) {
+        if (byte === 0x3e && buffer[position - 1] === 0x2d && buffer[position - 2] === 0x2d) comment = false;
+        continue;
+      }
+      if (rawClosing) {
+        const lower = byte >= 65 && byte <= 90 ? byte + 32 : byte;
+        if (matched === rawClosing.length && [9, 10, 12, 13, 32, 47, 62].includes(byte)) {
+          tagStart = position - matched;
+          rawClosing = '';
+          matched = 0;
+        } else {
+          matched = lower === rawClosing.charCodeAt(matched) ? matched + 1 : (byte === 0x3c ? 1 : 0);
+          continue;
+        }
+      }
+      if (tagStart < 0) {
+        if (byte === 0x3c) tagStart = position;
+        continue;
+      }
+      if (position === tagStart + 1 && !((byte >= 65 && byte <= 90) || (byte >= 97 && byte <= 122) || [33, 47, 63].includes(byte))) {
+        tagStart = byte === 0x3c ? position : -1;
+        continue;
+      }
+      if (position === tagStart + 3 && buffer[tagStart + 1] === 0x21 && buffer[tagStart + 2] === 0x2d && byte === 0x2d) {
+        comment = true;
+        tagStart = -1;
+        continue;
+      }
+      if (quote) {
+        if (byte === quote) quote = 0;
+        continue;
+      }
+      if (byte === 0x22 || byte === 0x27) {
+        quote = byte;
+        continue;
+      }
+      if (byte === 0x3e) {
+        const tag = buffer.toString('utf8', tagStart, position + 1);
+        if (!templateDepth && /^<\/head[\t\n\f\r ]*>$/i.test(tag)) {
+          response.body?.destroy?.();
+          return links;
+        }
+        const emptyXhtmlElement = mediaType === 'application/xhtml+xml' && tag.endsWith('/>');
+        if (!emptyXhtmlElement && /^<template(?=[\t\n\f\r />])/i.test(tag)) templateDepth += 1;
+        else if (/^<\/template(?=[\t\n\f\r />])/i.test(tag)) templateDepth = Math.max(0, templateDepth - 1);
+        else if (!templateDepth && /^<link(?=[\t\n\f\r />])/i.test(tag)) links.push(tag);
+        const raw = /^<(script|style|title|textarea|xmp|iframe|noembed|noframes)(?=[\t\n\f\r />])/i.exec(tag)
+          || (mediaType === 'text/html' && /^<(noscript)(?=[\t\n\f\r />])/i.exec(tag));
+        if (raw && !emptyXhtmlElement) rawClosing = `</${raw[1].toLowerCase()}`;
+        tagStart = -1;
+      }
+    }
+    total += length;
+    if (chunk.length > length) {
+      response.body?.destroy?.();
+      throw new Error('brand asset is too large');
+    }
+  }
+  return links;
+}
+
+function linkAttribute(tag, name) {
+  // Consume entire attributes so data-href and quoted examples cannot supply
+  // a real href. As in HTML, the first occurrence wins, even when valueless.
+  const attributes = tag.slice(5, -1).matchAll(/([^\t\n\f\r />=]+)(?:[\t\n\f\r ]*=[\t\n\f\r ]*(?:"([^"]*)"|'([^']*)'|([^\t\n\f\r >]+)))?/g);
+  for (const match of attributes) {
+    if (match[1].toLowerCase() === name) return match[2] ?? match[3] ?? match[4] ?? '';
+  }
+  return '';
+}
+
+// HTML numeric references in the C1 range use the legacy Windows-1252 mapping.
+// https://html.spec.whatwg.org/multipage/parsing.html#numeric-character-reference-end-state
+const HTML_C1_REFERENCES = [
+  0x20ac, 0x81, 0x201a, 0x192, 0x201e, 0x2026, 0x2020, 0x2021,
+  0x2c6, 0x2030, 0x160, 0x2039, 0x152, 0x8d, 0x17d, 0x8f,
+  0x90, 0x2018, 0x2019, 0x201c, 0x201d, 0x2022, 0x2013, 0x2014,
+  0x2dc, 0x2122, 0x161, 0x203a, 0x153, 0x9d, 0x17e, 0x178,
+];
+const BASIC_HTML_REFERENCES = { amp: '&', quot: '"', apos: "'", lt: '<', gt: '>' };
+
+function decodeIconHref(value) {
+  // Decode only after extracting the attribute, in one pass. Leave percent
+  // escapes to URL parsing and do not reinterpret decoded quotes as markup.
+  return value.replace(/&#(?:[xX]([0-9a-fA-F]+)|([0-9]+));?|&(amp|AMP|quot|QUOT|lt|LT|gt|GT)(?:;|(?![A-Za-z0-9=]))|&(apos);/g,
+    (_match, hex, decimal, named, apostrophe) => {
+      if (named || apostrophe) return BASIC_HTML_REFERENCES[(named || apostrophe).toLowerCase()];
+      let point = Number.parseInt(hex || decimal, hex ? 16 : 10);
+      if (point === 0 || point > 0x10ffff || (point >= 0xd800 && point <= 0xdfff)) return '\uFFFD';
+      if (point >= 0x80 && point <= 0x9f) point = HTML_C1_REFERENCES[point - 0x80];
+      return String.fromCodePoint(point);
+    });
 }
 
-function iconCandidates(html, pageUrl) {
+function iconCandidates(links, pageUrl) {
   const candidates = [];
-  for (const match of html.matchAll(/<link\b[^>]*>/gi)) {
-    const tag = match[0];
-    const rel = attribute(tag, 'rel').toLocaleLowerCase('en-US').split(/\s+/);
+  for (const tag of links) {
+    const rel = linkAttribute(tag, 'rel').toLocaleLowerCase('en-US').split(/\s+/);
     if (!rel.some((value) => value === 'icon' || value === 'apple-touch-icon' || value === 'mask-icon')) continue;
-    const href = attribute(tag, 'href');
+    const href = decodeIconHref(linkAttribute(tag, 'href'));
     if (!href) continue;
     try {
       const url = new URL(href, pageUrl);
       if (!['https:', 'http:'].includes(url.protocol)) continue;
-      const type = attribute(tag, 'type').toLocaleLowerCase('en-US');
-      const sizes = attribute(tag, 'sizes');
+      const type = linkAttribute(tag, 'type').toLocaleLowerCase('en-US');
+      const sizes = linkAttribute(tag, 'sizes');
       const area = [...sizes.matchAll(/(\d+)x(\d+)/gi)]
         .reduce((best, size) => Math.max(best, Number(size[1]) * Number(size[2])), 0);
       const score = (type.includes('svg') || /\.svg(?:$|[?#])/i.test(url.href) ? 1000000 : 0)
@@ -304,6 +433,20 @@ function iconCandidates(html, pageUrl) {
   return [...unique.values()].slice(0, 5).concat({ url: fallback, score: -1 });
 }
 
+function validIcoImageRanges(buffer) {
+  if (buffer.length < 6 || buffer.readUInt16LE(0) !== 0 || buffer.readUInt16LE(2) !== 1) return false;
+  const count = buffer.readUInt16LE(4);
+  const directoryEnd = 6 + count * 16;
+  if (count === 0 || directoryEnd > buffer.length) return false;
+  for (let index = 0; index < count; index += 1) {
+    const entry = 6 + index * 16;
+    const size = buffer.readUInt32LE(entry + 8);
+    const offset = buffer.readUInt32LE(entry + 12);
+    if (size === 0 || offset < directoryEnd || offset + size > buffer.length) return false;
+  }
+  return true;
+}
+
 async function imageData(response) {
   const contentType = (response.headers.get('content-type') || '').split(';')[0].trim().toLocaleLowerCase('en-US');
   const allowed = new Set([
@@ -335,10 +478,7 @@ async function imageData(response) {
           && buffer.toString('ascii', 0, 4) === 'RIFF'
           && buffer.toString('ascii', 8, 12) === 'WEBP'
           && buffer.readUInt32LE(4) + 8 <= buffer.length
-        : buffer.length >= 22
-          && buffer[0] === 0 && buffer[1] === 0 && buffer[2] === 1 && buffer[3] === 0
-          && buffer.readUInt16LE(4) > 0
-          && 6 + buffer.readUInt16LE(4) * 16 <= buffer.length));
+        : validIcoImageRanges(buffer)));
   if (!signatureMatches) throw new Error(`brand asset bytes do not match ${contentType}`);
   return {
     dataUrl: `data:${contentType};base64,${buffer.toString('base64')}`,
@@ -349,13 +489,14 @@ async function imageData(response) {
 
 async function captureRemoteBrand(value, deadline = Date.now() + captureTimeoutMilliseconds()) {
   const sourceUrl = new URL(value);
+  const publicSourceUrl = normalizeBrandSourceUrl(sourceUrl);
   const fallback = (reason) => ({
     id: sourceUrl.hostname,
     title: sourceUrl.hostname,
     category: 'link',
     kind: 'fallback',
     status: 'unavailable',
-    sourceUrl: sourceUrl.href,
+    sourceUrl: publicSourceUrl,
     reason,
   });
   try {
@@ -369,7 +510,7 @@ async function captureRemoteBrand(value, deadline = Date.now() + captureTimeoutM
         category: 'link',
         kind: 'remote',
         status: 'captured',
-        sourceUrl: sourceUrl.href,
+        sourceUrl: publicSourceUrl,
         resolvedUrl: page.finalUrl.href,
         ...image,
       };
@@ -378,9 +519,11 @@ async function captureRemoteBrand(value, deadline = Date.now() + captureTimeoutM
       page.response.body?.destroy?.();
       return fallback('linked page is not HTML');
     }
-    const html = (await readLimited(page.response, MAX_HTML_BYTES)).toString('utf8');
+    // Distinguish HTML noscript and XHTML empty elements without executing scripts.
+    const mediaType = pageType.split(';')[0].trim();
+    const links = await readHtmlHeadLinks(page.response, MAX_HTML_BYTES, mediaType);
     const iconErrors = [];
-    for (const candidate of iconCandidates(html, page.finalUrl)) {
+    for (const candidate of iconCandidates(links, page.finalUrl)) {
       try {
         const fetched = await checkedFetch(candidate.url, 'image/*', deadline);
         const image = await imageData(fetched.response);
@@ -390,7 +533,7 @@ async function captureRemoteBrand(value, deadline = Date.now() + captureTimeoutM
           category: 'link',
           kind: 'remote',
           status: 'captured',
-          sourceUrl: sourceUrl.href,
+          sourceUrl: publicSourceUrl,
           resolvedUrl: fetched.finalUrl.href,
           ...image,
         };
@@ -399,7 +542,7 @@ async function captureRemoteBrand(value, deadline = Date.now() + captureTimeoutM
         // Try the next declared favicon before using the generic link mark.
       }
     }
-    const usefulError = iconErrors.find((error) => /unsupported brand image type/i.test(error?.message))
+    const usefulError = iconErrors.find((error) => /unsupported brand (?:image type|content encoding)/i.test(error?.message))
       || iconErrors.at(-1);
     return fallback(usefulError?.message || 'no usable site icon was found');
   } catch (error) {
@@ -483,7 +626,7 @@ export async function prepareDiagramBrandMarks(diagramType, diagram) {
     }
     const url = asUrl(node.brand);
     if (url) {
-      unknown.push(`/${collection}/${index}/brand ${JSON.stringify(node.brand)} is an unpinned URL; capture it first with \`diagrams brands capture ${url.href} --json\``);
+      unknown.push(`/${collection}/${index}/brand ${JSON.stringify(node.brand)} is an unpinned URL; capture it first with \`archify brands capture ${url.href} --json\``);
       return;
     }
     unknown.push(`/${collection}/${index}/brand ${JSON.stringify(node.brand)} is not a built-in brand; closest IDs: ${suggestions(node.brand).join(', ')}`);
@@ -498,8 +641,8 @@ export async function prepareDiagramBrandMarks(diagramType, diagram) {
       subject: { diagramType, collection },
       evidence: {},
       supportedFixes: message.includes('is an unpinned URL')
-        ? ['run `diagrams brands capture <url> --json` and author the returned digest-pinned brand object']
-        : ['choose an ID from `diagrams brands`', 'run `diagrams brands capture <url> --json` for an unknown official site'],
+        ? ['run `archify brands capture <url> --json` and author the returned digest-pinned brand object']
+        : ['choose an ID from `archify brands`', 'run `archify brands capture <url> --json` for an unknown official site'],
     })));
   }
 }
@@ -528,7 +671,7 @@ export function brandTopRailProblem(node, width, minimumFontSize, subject = 'Nod
   const required = textUnits(node.label) * minimumFontSize * 0.6;
   if (available >= required) return null;
   return `${subject} "${node.id}" brand top rail leaves ${Math.max(0, available)}px for its label, but `
-    + `"${node.label}" needs ~${Math.ceil(required)}px at the ${minimumFontSize}px legible minimum - widen the node or shorten the label.`;
+    + `"${node.label}" needs ~${Math.ceil(required)}px at the ${minimumFontSize}px legible minimum — widen the node or shorten the label.`;
 }
 
 function markAttrs(mark) {