@mosetta/editor 0.0.0-stage → 0.0.28

package/tiles/pageModules/servedPage.ts

@@ -0,0 +1,465 @@
+// THE PAGE AS A READER GETS IT (ADR-0062) — plain logic over what the server answers for a
+// document's clean preview: the files its HTML makes the browser fetch (scripts, styles, images),
+// the modules they belong to, what each module ASKED for against what the page LOADS, and the
+// sums. The server already settled the page's framework (one copy of each package, ADR-0061), so
+// nothing here re-computes that: an edge whose asked version is not among the loaded ones, while
+// another version of the same package is, was taken over by a rule.
+import { compareVersions } from '@mosetta/content';
+
+export type TFileKind = 'js' | 'css' | 'image' | 'font' | 'other';
+
+/** a file the page makes the browser fetch */
+export interface IServedFile {
+  /** absolute, as the page names it */
+  readonly url: string;
+  readonly kind: TFileKind;
+  /** the module whose folder holds it (`…/modules/<id>/…`), or null for media and the like */
+  readonly moduleId: string | null;
+  /** an image the browser fetches only when it comes near the screen */
+  readonly lazy?: boolean;
+  /** a font the styles declare and the page's text never asks for — the browser never fetches it */
+  readonly unused?: boolean;
+}
+
+/** a catalog entry, as much of it as is read here */
+export interface ICatalogItem {
+  readonly id: string;
+  readonly reference: {
+    readonly type?: string;
+    readonly namespace?: string;
+    readonly name?: string;
+    readonly version?: string;
+    readonly specifier?: string;
+  };
+  readonly dependencies?: readonly string[];
+}
+
+const EXTENSION_KINDS: Readonly<Record<string, TFileKind>> = {
+  js: 'js', mjs: 'js', css: 'css',
+  png: 'image', jpg: 'image', jpeg: 'image', gif: 'image', webp: 'image', avif: 'image', svg: 'image', ico: 'image',
+  woff: 'font', woff2: 'font', ttf: 'font', otf: 'font', eot: 'font',
+};
+
+const AS_KINDS: Readonly<Record<string, TFileKind>> = { script: 'js', style: 'css', image: 'image', font: 'font' };
+
+function kindOf(url: URL, as?: string): TFileKind {
+  const extension = /\.([a-z0-9]+)$/i.exec(url.pathname)?.[1]?.toLowerCase();
+  return (extension ? EXTENSION_KINDS[extension] : undefined) ?? (as ? AS_KINDS[as] : undefined) ?? 'other';
+}
+
+/** the module a file's folder names: `…/modules/<id>/<file>` */
+function moduleIdOf(url: URL): string | null {
+  const match = /\/modules\/([^/]+)\/[^/]+$/.exec(url.pathname);
+  return match ? decodeURIComponent(match[1]) : null;
+}
+
+const decodeEntities = (value: string): string => value
+  .replace(/&quot;/g, '"').replace(/&#39;/g, '\'').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/&amp;/g, '&');
+
+function attributesOf(tag: string): Record<string, string> {
+  const attributes: Record<string, string> = {};
+  for (const match of tag.matchAll(/([a-zA-Z][\w:-]*)\s*=\s*("([^"]*)"|'([^']*)')/g)) {
+    attributes[match[1].toLowerCase()] = decodeEntities(match[3] ?? match[4] ?? '');
+  }
+  return attributes;
+}
+
+/** one key per file: the same file under another cache-busting query is the same file */
+const fileKey = (url: URL): string => `${url.origin}${url.pathname}`;
+
+/**
+ * The files a page's HTML makes the browser fetch — preloads, stylesheets, scripts, images (the
+ * address the browser falls back to, `src`) — each once, and the page's own document (the
+ * `pageContent` the server put in, its version rules resolved) when there is one.
+ */
+export function readServedPage(html: string, pageUrl: string): { files: IServedFile[]; doc: Record<string, unknown> | null } {
+  const files = new Map<string, IServedFile>();
+  const add = (href: string | undefined, as?: string, lazy?: boolean) => {
+    if (!href || href.startsWith('data:')) return;
+    let url: URL;
+    try {
+      url = new URL(href, pageUrl);
+    } catch {
+      return;
+    }
+    const key = fileKey(url);
+    if (files.has(key)) return;
+    files.set(key, { url: url.href, kind: kindOf(url, as), moduleId: moduleIdOf(url), ...(lazy ? { lazy } : {}) });
+  };
+  for (const [tag] of html.matchAll(/<link\b[^>]*>/gi)) {
+    const a = attributesOf(tag);
+    const rel = (a.rel ?? '').toLowerCase().split(/\s+/);
+    if (rel.includes('preload') || rel.includes('modulepreload') || rel.includes('stylesheet')) add(a.href, a.as ?? (rel.includes('stylesheet') ? 'style' : undefined));
+  }
+  for (const [tag] of html.matchAll(/<script\b[^>]*>/gi)) add(attributesOf(tag).src, 'script');
+  for (const [tag] of html.matchAll(/<img\b[^>]*>/gi)) {
+    const a = attributesOf(tag);
+    add(a.src, 'image', a.loading === 'lazy');
+  }
+  const content = /<script\b[^>]*\bid="pageContent"[^>]*>([\s\S]*?)<\/script>/i.exec(html)?.[1];
+  let doc: Record<string, unknown> | null = null;
+  if (content) {
+    try {
+      doc = JSON.parse(content) as Record<string, unknown>;
+    } catch {
+      doc = null;
+    }
+  }
+  return { files: [...files.values()], doc };
+}
+
+/** the files a stylesheet fetches in its turn — fonts and images of its `url(…)`s */
+export function readStylesheet(css: string, cssUrl: string): IServedFile[] {
+  const files = new Map<string, IServedFile>();
+  for (const match of css.matchAll(/url\(\s*(?:"([^"]*)"|'([^']*)'|([^)'"]*))\s*\)/gi)) {
+    const href = (match[1] ?? match[2] ?? match[3] ?? '').trim();
+    if (!href || href.startsWith('data:') || href.startsWith('#')) continue;
+    let url: URL;
+    try {
+      url = new URL(href, cssUrl);
+    } catch {
+      continue;
+    }
+    if (!files.has(fileKey(url))) files.set(fileKey(url), { url: url.href, kind: kindOf(url), moduleId: moduleIdOf(url) });
+  }
+  return [...files.values()];
+}
+
+/** a font face a stylesheet declares: what it is for, and its files in the order a browser tries them */
+export interface IFontFace {
+  readonly family: string;
+  readonly weight: string;
+  readonly style: string;
+  /** canonical: `0-ff,131` */
+  readonly unicodeRange: string;
+  readonly urls: readonly string[];
+}
+
+/** a face the page's document has loaded (`document.fonts`, status loaded) */
+export interface ILoadedFont {
+  readonly family: string;
+  readonly weight: string;
+  readonly style: string;
+  readonly unicodeRange: string;
+}
+
+const FULL_RANGE = 'U+0-10FFFF';
+
+/** `U+0000-00FF, U+0131, U+4??` and `U+0-FF,U+131` alike → `0-ff,131,400-4ff` */
+function canonicalRange(range: string): string {
+  return (range.trim() || FULL_RANGE).split(',').map((token) => {
+    const body = token.trim().replace(/^u\+/i, '');
+    if (body.includes('?')) {
+      return `${parseInt(body.replace(/\?/g, '0'), 16).toString(16)}-${parseInt(body.replace(/\?/g, 'f'), 16).toString(16)}`;
+    }
+    const [from, to] = body.split('-').map((hex) => parseInt(hex, 16).toString(16));
+    return to && to !== from ? `${from}-${to}` : from;
+  }).join(',');
+}
+
+const canonicalWeight = (weight: string): string => ({ normal: '400', bold: '700' }[weight.trim().toLowerCase()] ?? weight.trim().toLowerCase());
+const canonicalFamily = (family: string): string => family.trim().replace(/^["']|["']$/g, '').toLowerCase();
+const faceKey = (face: ILoadedFont): string => [canonicalFamily(face.family), canonicalWeight(face.weight), (face.style || 'normal').trim().toLowerCase(), canonicalRange(face.unicodeRange)].join('|');
+
+/** the font faces a stylesheet declares */
+export function readFontFaces(css: string, cssUrl: string): IFontFace[] {
+  const faces: IFontFace[] = [];
+  for (const [, body] of css.matchAll(/@font-face\s*\{([^}]*)\}/gi)) {
+    const descriptor = (name: string): string => new RegExp(`(?:^|;)\\s*${name}\\s*:\\s*([^;]*)`, 'i').exec(body)?.[1]?.trim() ?? '';
+    const urls = readStylesheet(descriptor('src'), cssUrl).filter((file) => file.kind === 'font').map((file) => file.url);
+    if (!urls.length) continue;
+    faces.push({
+      family: descriptor('font-family'),
+      weight: descriptor('font-weight') || '400',
+      style: descriptor('font-style') || 'normal',
+      unicodeRange: canonicalRange(descriptor('unicode-range')),
+      urls,
+    });
+  }
+  return faces;
+}
+
+/**
+ * The fonts the page's styles declare, against the faces its preview loaded: a browser fetches a
+ * face its text needs — the first format of it it can read — and never the others, nor the faces
+ * (weights, character subsets) the text does not ask for. With no word from the preview every
+ * face counts once: at most.
+ */
+export function markUnusedFonts(files: readonly IServedFile[], faces: readonly IFontFace[], loaded: readonly ILoadedFont[]): IServedFile[] {
+  const loadedKeys = new Set(loaded.map(faceKey));
+  const fetched = new Set(faces
+    .filter((face) => !loadedKeys.size || loadedKeys.has(faceKey(face)))
+    .map((face) => fileKey(new URL(face.urls[0]))));
+  return files.map((file) => (file.kind === 'font' && !fetched.has(fileKey(new URL(file.url))) ? { ...file, unused: true } : file));
+}
+
+// ---- the modules -------------------------------------------------------------------------------
+
+const PACKAGE_PREFIX = '_ns_package_t_package_n_';
+const MODULE_ID_RE = /^_ns_(.+?)_t_([a-z][A-Za-z0-9]*)_n_(.+)_v_([A-Za-z0-9_]+)$/;
+
+/** a package id's normalized specifier and version, or null for a block's module */
+function packagePartsOf(id: string): { specifier: string; version: string } | null {
+  if (!id.startsWith(PACKAGE_PREFIX)) return null;
+  const body = id.slice(PACKAGE_PREFIX.length);
+  const at = body.lastIndexOf('_v_');
+  return at < 0 ? null : { specifier: body.slice(0, at), version: body.slice(at + 3) };
+}
+
+const dotted = (version: string): string => version.replace(/_/g, '.');
+
+/** an edge of a module: what it asked for, and what the page gives it */
+export interface IDependencyEdge {
+  readonly id: string;
+  /** the package as people spell it (`@mosetta/react`) */
+  readonly label: string;
+  readonly asked: string;
+  /** the version the page loads, or null when it loads none (not fetched up front) */
+  readonly given: string | null;
+  /** another version is loaded in place of the asked one — a rule took the edge over */
+  readonly crossed: boolean;
+  /** …and it is OLDER than the one asked for */
+  readonly lower: boolean;
+  /** the module the page loads for it — what opening the edge shows; null when it loads none */
+  readonly loadedId: string | null;
+}
+
+/** a module the page fetches */
+export interface IModuleRow {
+  readonly id: string;
+  readonly kind: 'block' | 'package';
+  /** a block's name (with its facet when not the component), a package entry's specifier */
+  readonly title: string;
+  readonly version: string;
+  /** what of it the page fetches */
+  readonly files: readonly IServedFile[];
+  readonly dependencies: readonly IDependencyEdge[];
+}
+
+/** the modules of one package: a distribution's blocks (`mosetta-ui@0.0.1`), a package's entries (`react@19.2.0`) */
+export interface IPackageGroup {
+  readonly key: string;
+  readonly kind: 'distribution' | 'package';
+  readonly name: string;
+  readonly version: string;
+  readonly modules: readonly IModuleRow[];
+}
+
+export interface IPageModules {
+  /** the distributions first, then the packages — each as the page first names it */
+  readonly groups: readonly IPackageGroup[];
+  /** every module of the page, by id — where an edge leads */
+  readonly byId: ReadonlyMap<string, IModuleRow>;
+  /** files of no module: the loader, the page's images, fonts and images its styles name */
+  readonly assets: readonly IServedFile[];
+}
+
+/** the package an entry belongs to: `@scope/name` of `@scope/name/sub`, `name` of `name/sub` */
+export function packageNameOf(specifier: string): string {
+  const parts = specifier.split('/');
+  return specifier.startsWith('@') ? parts.slice(0, 2).join('/') : parts[0];
+}
+
+/** the modules of the page, by package — what it fetches, with each module's edges */
+export function pageModules(files: readonly IServedFile[], catalog: ReadonlyMap<string, ICatalogItem>): IPageModules {
+  const byModule = new Map<string, IServedFile[]>();
+  const assets: IServedFile[] = [];
+  for (const file of files) {
+    // the loader (system.js) sits in the root script's folder but is no module of it
+    if (file.moduleId && !/\/system(\.min)?\.js$/.test(new URL(file.url).pathname)) {
+      byModule.set(file.moduleId, [...(byModule.get(file.moduleId) ?? []), file]);
+    } else {
+      assets.push(file);
+    }
+  }
+  // the loaded version of each package entry, by its normalized specifier
+  const loaded = new Map<string, string>();
+  for (const id of byModule.keys()) {
+    const parts = packagePartsOf(id);
+    if (parts) loaded.set(parts.specifier, parts.version);
+  }
+  const labelOf = (id: string): string => catalog.get(id)?.reference.specifier ?? packagePartsOf(id)?.specifier ?? id;
+  const edgesOf = (id: string): IDependencyEdge[] => (catalog.get(id)?.dependencies ?? []).flatMap((dep) => {
+    const parts = packagePartsOf(dep);
+    if (!parts) return [];
+    const given = loaded.get(parts.specifier) ?? null;
+    const crossed = given !== null && given !== parts.version;
+    return [{
+      id: dep,
+      label: labelOf(dep),
+      asked: dotted(parts.version),
+      given: given === null ? null : dotted(given),
+      crossed,
+      lower: crossed && compareVersions(given, parts.version) < 0,
+      loadedId: given === null ? null : `${PACKAGE_PREFIX}${parts.specifier}_v_${given}`,
+    }];
+  });
+  const groups = new Map<string, { key: string; kind: 'distribution' | 'package'; name: string; version: string; modules: IModuleRow[] }>();
+  const byId = new Map<string, IModuleRow>();
+  for (const [id, own] of byModule) {
+    const parts = packagePartsOf(id);
+    const match = MODULE_ID_RE.exec(id);
+    const version = dotted(parts?.version ?? match?.[4] ?? '');
+    const title = parts ? labelOf(id) : match ? (match[2] === 'component' ? match[3] : `${match[3]} · ${match[2]}`) : id;
+    const row: IModuleRow = { id, kind: parts ? 'package' : 'block', title, version, files: own, dependencies: edgesOf(id) };
+    byId.set(id, row);
+    const name = parts ? packageNameOf(title) : match?.[1] ?? id;
+    const key = `${name}@${version}`;
+    const group = groups.get(key) ?? { key, kind: parts ? 'package' as const : 'distribution' as const, name, version, modules: [] };
+    group.modules.push(row);
+    groups.set(key, group);
+  }
+  const all = [...groups.values()];
+  return { groups: [...all.filter((g) => g.kind === 'distribution'), ...all.filter((g) => g.kind === 'package')], byId, assets };
+}
+
+// ---- the sums ----------------------------------------------------------------------------------
+
+/** what a file weighs: as fetched, and gzipped when it is text (null: not measured) */
+export interface IFileSize {
+  readonly bytes: number;
+  readonly gzip: number | null;
+}
+
+export interface IWeight {
+  readonly count: number;
+  readonly bytes: number;
+  /** gzipped text, binary as it is; null while any part of it is not measured */
+  readonly gzip: number | null;
+}
+
+/** a file's kind compresses as text — images other than svg and fonts are compressed already */
+export const isText = (file: IServedFile): boolean => file.kind === 'js' || file.kind === 'css' || /\.svg$/i.test(new URL(file.url).pathname);
+
+export function weightOf(files: readonly IServedFile[], sizes: ReadonlyMap<string, IFileSize>): IWeight {
+  let bytes = 0;
+  let gzip: number | null = 0;
+  let count = 0;
+  for (const file of files) {
+    const size = sizes.get(file.url);
+    if (!size) continue;
+    count += 1;
+    bytes += size.bytes;
+    const packed = isText(file) ? size.gzip : size.bytes;
+    gzip = gzip === null || packed === null ? null : gzip + packed;
+  }
+  return { count, bytes, gzip };
+}
+
+export const addWeights = (a: IWeight, b: IWeight): IWeight => ({
+  count: a.count + b.count,
+  bytes: a.bytes + b.bytes,
+  gzip: a.gzip === null || b.gzip === null ? null : a.gzip + b.gzip,
+});
+
+export function formatBytes(bytes: number): string {
+  if (bytes < 1024) return `${bytes} B`;
+  const kb = bytes / 1024;
+  if (kb < 1024) return `${kb < 100 ? kb.toFixed(1) : Math.round(kb)} KB`;
+  const mb = kb / 1024;
+  return `${mb < 100 ? mb.toFixed(1) : Math.round(mb)} MB`;
+}
+
+// ---- the order and the bars -------------------------------------------------------------------
+
+/** how the rows of the tree are ordered — by name or weight, either way; null: as the page names them */
+export interface IOrder {
+  readonly by: 'name' | 'size' | 'gzip';
+  readonly descending: boolean;
+}
+
+/** the next order a click on a column gives: its own way first (names A→Z, weights heaviest first), then the other */
+export function nextOrder(order: IOrder | null, by: IOrder['by']): IOrder {
+  if (order?.by === by) return { by, descending: !order.descending };
+  return { by, descending: by !== 'name' };
+}
+
+/** the rows in an order; null keeps them as they are */
+export function ordered<T>(rows: readonly T[], order: IOrder | null, nameOf: (row: T) => string, weightOf: (row: T) => IWeight): T[] {
+  if (!order) return [...rows];
+  const sign = order.descending ? -1 : 1;
+  const key = (row: T): number => {
+    const weight = weightOf(row);
+    return order.by === 'gzip' ? weight.gzip ?? weight.bytes : weight.bytes;
+  };
+  return [...rows].sort((a, b) => sign * (order.by === 'name'
+    ? nameOf(a).localeCompare(nameOf(b), undefined, { numeric: true, sensitivity: 'base' })
+    : key(a) - key(b)));
+}
+
+/**
+ * The tool's state as the address keeps it: the order (`order:size-down`) and the key of every
+ * open row, comma-joined — `order:size-down,packages,mosetta-ui@0.0.1,mosetta-ui@0.0.1/theme`.
+ * Nothing open and no order: null.
+ */
+export function writeToolState(order: IOrder | null, opened: Iterable<string>): string | null {
+  const parts = [...(order ? [`order:${order.by}-${order.descending ? 'down' : 'up'}`] : []), ...[...opened].sort()];
+  return parts.length ? parts.join(',') : null;
+}
+
+export function readToolState(state: string | null): { order: IOrder | null; opened: Set<string> } {
+  let order: IOrder | null = null;
+  const opened = new Set<string>();
+  for (const part of (state ?? '').split(',')) {
+    const said = /^order:(name|size|gzip)-(down|up)$/.exec(part);
+    if (said) order = { by: said[1] as IOrder['by'], descending: said[2] === 'down' };
+    else if (part) opened.add(part);
+  }
+  return { order, opened };
+}
+
+/**
+ * The colour of a row's bar — the share of the page it weighs: green for a crumb, through yellow,
+ * to red for a third of the page and more.
+ */
+export function shareHue(share: number): number {
+  const heavy = Math.min(1, Math.max(0, share) / 0.33);
+  return Math.round(120 * (1 - heavy));
+}
+
+// ---- the rules ---------------------------------------------------------------------------------
+
+/** a rule of the page's `settings.versions.shared` */
+export interface IVersionRule {
+  readonly singleton?: boolean;
+  readonly version?: string;
+  readonly pin?: string;
+}
+
+/**
+ * The rule every page has without saying so — the server's DEFAULT_SHARED, copied (the unit test
+ * keeps the two equal; moving it into a shared package would release the framework for a line).
+ */
+export const BUILT_IN_RULES: Readonly<Record<string, IVersionRule>> = { '@mosetta/*': { singleton: true, version: 'highest' } };
+
+/** a rule as people read it */
+export function describeRule(rule: IVersionRule): string {
+  const version = rule.pin ?? rule.version;
+  if (version === 'highest') return 'one copy, the newest any block asks for';
+  if (version) return `one copy, exactly ${version}`;
+  return rule.singleton ? 'one copy' : 'no constraint';
+}
+
+/** the page's own rules, from its root's settings */
+export function pageRulesOf(settings: Record<string, unknown> | undefined): Record<string, IVersionRule> {
+  const shared = (settings?.versions as { shared?: unknown } | undefined)?.shared;
+  return shared && typeof shared === 'object' ? shared as Record<string, IVersionRule> : {};
+}
+
+/** the root's settings patch that sets (or, with null, removes) one rule */
+export function withRule(settings: Record<string, unknown> | undefined, key: string, rule: IVersionRule | null): Record<string, unknown> {
+  const versions = (settings?.versions && typeof settings.versions === 'object' ? settings.versions : {}) as Record<string, unknown>;
+  const shared = { ...pageRulesOf(settings) };
+  if (rule) shared[key] = rule;
+  else delete shared[key];
+  return { versions: { ...versions, shared } };
+}
+
+/** the versions of a package the catalog holds, the newest first */
+export function versionsOf(catalog: Iterable<ICatalogItem>, specifier: string): string[] {
+  const found = new Set<string>();
+  for (const item of catalog) {
+    if (item.reference.specifier === specifier && item.reference.version) found.add(item.reference.version);
+  }
+  return [...found].sort((a, b) => compareVersions(b, a));
+}