@caelo-cms/shared 0.10.52 → 0.10.53

package/src/markup-structure.ts

@@ -0,0 +1,304 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Issue #820 — structural fingerprints of HTML, for telling "this markup is
+ * a reusable pattern that already exists elsewhere" from one-off content.
+ *
+ * Free HTML (a step chain, a comparison table, a timeline pasted into a
+ * richtext value, or minted as a one-off module per page) is cheap to
+ * write and expensive to keep: every copy is edited separately, the copies
+ * drift, and the pattern's CSS has to live in the layout where it ships on
+ * every page. The fix is to make the second copy a module. This file gives
+ * the write-time guard and the core `structure` quality check one shared
+ * notion of "the same markup":
+ *
+ * - A node's SIGNATURE is its tag plus sorted class tokens plus the
+ *   signatures of its distinct children (first-occurrence order). Text,
+ *   attribute values and repetition are ignored, so a 5-step chain and a
+ *   7-step chain with different copy are the same pattern.
+ * - A subtree QUALIFIES as a pattern when it is big enough to be a
+ *   component (MIN_PATTERN_NODES distinct nodes over MIN_PATTERN_DEPTH
+ *   levels) and carries at least one class. Prose converted from Markdown
+ *   (`<ul><li><a>`, plain tables) has no classes and never qualifies; an
+ *   authored component always has them.
+ * - SIMILARITY is the Jaccard index over parent→child edges, for near
+ *   matches that are not exact (a pattern with one extra element).
+ *
+ * The site importer's boilerplate walker (site-importer/boilerplate.ts)
+ * stays separate on purpose: it streams byte ranges, hashes text into a
+ * content signature, and its signatures are persisted and replayed
+ * (#424), so its output must stay byte-stable.
+ *
+ * Every walk is bounded (MAX_NODES) so an adversarial body cannot blow it up.
+ */
+
+import { Parser } from "htmlparser2";
+
+/** One element of parsed markup. Text is dropped; it never matters here. */
+export interface MarkupNode {
+  readonly tag: string;
+  readonly classes: readonly string[];
+  /** The `data-caelo-module-id` the composer stamps on every module root. */
+  readonly moduleId: string | null;
+  readonly children: MarkupNode[];
+  readonly parent: MarkupNode | null;
+}
+
+/** Most elements one parse keeps; the rest of the document is ignored. */
+export const MAX_NODES = 50_000;
+/** A pattern has at least this many distinct nodes… */
+export const MIN_PATTERN_NODES = 4;
+/** …spread over at least this many levels (root, child, grandchild). */
+export const MIN_PATTERN_DEPTH = 3;
+/** Jaccard similarity at or above which two patterns are "near" matches. */
+export const NEAR_MATCH_THRESHOLD = 0.8;
+
+/** Elements whose inside is not markup structure (icons, raw text). */
+const LEAF_TAGS = new Set(["svg", "math", "script", "style", "noscript", "iframe"]);
+
+/** Parse markup into a forest of element nodes. */
+export function parseMarkup(html: string): MarkupNode[] {
+  const roots: MarkupNode[] = [];
+  const stack: (MarkupNode | null)[] = [];
+  let count = 0;
+  let leafDepth = 0;
+  const parser = new Parser(
+    {
+      onopentag(name, attribs) {
+        if (leafDepth > 0 || count >= MAX_NODES) {
+          stack.push(null);
+          if (leafDepth > 0) leafDepth++;
+          return;
+        }
+        const tag = name.toLowerCase();
+        const parent = findOpen(stack);
+        const node: MarkupNode = {
+          tag,
+          classes: splitClasses(attribs.class),
+          moduleId: attribs["data-caelo-module-id"] ?? null,
+          children: [],
+          parent,
+        };
+        count++;
+        if (parent) parent.children.push(node);
+        else roots.push(node);
+        stack.push(node);
+        if (LEAF_TAGS.has(tag)) leafDepth = 1;
+      },
+      onclosetag() {
+        stack.pop();
+        if (leafDepth > 0) leafDepth--;
+      },
+    },
+    { decodeEntities: true, lowerCaseTags: true },
+  );
+  parser.write(html);
+  parser.end();
+  return roots;
+}
+
+function findOpen(stack: readonly (MarkupNode | null)[]): MarkupNode | null {
+  for (let i = stack.length - 1; i >= 0; i--) {
+    const n = stack[i];
+    if (n) return n;
+  }
+  return null;
+}
+
+function splitClasses(raw: string | undefined): string[] {
+  if (!raw) return [];
+  return [...new Set(raw.split(/\s+/).filter((c) => c.length > 0))].sort();
+}
+
+/**
+ * Remove Mustache tags (`{{x}}`, `{{{x}}}`, `{{#s}}`, `{{/s}}`, `{{>p}}`)
+ * from a module template so it parses as the markup it renders: a section
+ * body stays once, a placeholder becomes empty.
+ */
+export function stripMustache(template: string): string {
+  return stripDelimited(stripDelimited(template, 3), 2);
+}
+
+/**
+ * Removes every `{`×n + non-`}` run + `}`×n span, leftmost first — the
+ * same result as `replace(/\{{n}[^}]*\}{n}/g, "")`, in linear time. The
+ * regex form backtracks quadratically on long `{{{{…` runs in module HTML
+ * (CodeQL js/polynomial-redos); here, when the first `}` after an opener
+ * does not start the closer, no opener before that `}` can match either
+ * (they all hit the same `}`), so the scan resumes there.
+ */
+function stripDelimited(text: string, n: number): string {
+  const opener = "{".repeat(n);
+  const closer = "}".repeat(n);
+  let out = "";
+  let i = 0;
+  while (i < text.length) {
+    const open = text.indexOf(opener, i);
+    if (open < 0) break;
+    const brace = text.indexOf("}", open + n);
+    if (brace < 0) break;
+    if (text.startsWith(closer, brace)) {
+      out += text.slice(i, open);
+      i = brace + n;
+    } else {
+      out += text.slice(i, brace);
+      i = brace;
+    }
+  }
+  return out + text.slice(i);
+}
+
+/** The node's key without its children: `div.card.card--wide`. */
+export function nodeKey(n: Pick<MarkupNode, "tag" | "classes">): string {
+  return n.classes.length === 0 ? n.tag : `${n.tag}.${n.classes.join(".")}`;
+}
+
+/** Structural facts about one subtree. */
+export interface SubtreeShape {
+  /** Repetition- and text-independent structural signature. */
+  readonly signature: string;
+  /** Distinct nodes after repetition collapse. */
+  readonly nodeCount: number;
+  /** Levels, the subtree root counting as 1. */
+  readonly depth: number;
+  /** Whether any node in it carries a class. */
+  readonly hasClass: boolean;
+  /** Parent→child edges, for near-match similarity. */
+  readonly edges: ReadonlySet<string>;
+}
+
+/**
+ * Compute the shapes of a subtree and all its descendants in one pass.
+ * Nested module roots are opaque: their own module owns them.
+ */
+export function shapeTree(root: MarkupNode, out = new Map<MarkupNode, SubtreeShape>()) {
+  const visit = (n: MarkupNode): SubtreeShape => {
+    const seen = new Set<string>();
+    const parts: string[] = [];
+    let nodeCount = 1;
+    let depth = 1;
+    let hasClass = n.classes.length > 0;
+    const edges = new Set<string>();
+    const key = nodeKey(n);
+    for (const c of n.children) {
+      if (c.moduleId !== null) continue;
+      const s = visit(c);
+      if (seen.has(s.signature)) continue;
+      seen.add(s.signature);
+      parts.push(s.signature);
+      nodeCount += s.nodeCount;
+      depth = Math.max(depth, s.depth + 1);
+      hasClass ||= s.hasClass;
+      edges.add(`${key}>${nodeKey(c)}`);
+      for (const e of s.edges) edges.add(e);
+    }
+    const shape: SubtreeShape = {
+      signature: parts.length === 0 ? key : `${key}(${parts.join(",")})`,
+      nodeCount,
+      depth,
+      hasClass,
+      edges,
+    };
+    out.set(n, shape);
+    return shape;
+  };
+  visit(root);
+  return out;
+}
+
+/** Whether a subtree is big and specific enough to count as a pattern. */
+export function isPattern(shape: SubtreeShape): boolean {
+  return shape.hasClass && shape.nodeCount >= MIN_PATTERN_NODES && shape.depth >= MIN_PATTERN_DEPTH;
+}
+
+/** Jaccard similarity of two shapes' edge sets, 0…1. */
+export function shapeSimilarity(a: SubtreeShape, b: SubtreeShape): number {
+  if (a.signature === b.signature) return 1;
+  let shared = 0;
+  for (const e of a.edges) if (b.edges.has(e)) shared++;
+  const union = a.edges.size + b.edges.size - shared;
+  return union === 0 ? 0 : shared / union;
+}
+
+/** A qualifying pattern found in a piece of markup. */
+export interface FoundPattern {
+  readonly node: MarkupNode;
+  readonly shape: SubtreeShape;
+}
+
+/**
+ * The outermost qualifying patterns in a forest: a pattern inside a bigger
+ * pattern is part of it and not reported on its own.
+ */
+export function outermostPatterns(roots: readonly MarkupNode[]): FoundPattern[] {
+  const found: FoundPattern[] = [];
+  const walk = (n: MarkupNode, shapes: Map<MarkupNode, SubtreeShape>) => {
+    const shape = shapes.get(n);
+    if (shape && isPattern(shape)) {
+      found.push({ node: n, shape });
+      return;
+    }
+    for (const c of n.children) if (c.moduleId === null) walk(c, shapes);
+  };
+  for (const r of roots) walk(r, shapeTree(r));
+  return found;
+}
+
+/** The shape of a whole module template (its first element), or null. */
+export function templateShape(templateHtml: string): SubtreeShape | null {
+  const root = parseMarkup(stripMustache(templateHtml))[0];
+  return root ? (shapeTree(root).get(root) ?? null) : null;
+}
+
+/**
+ * The parts of a rendered module that did NOT come from its template: the
+ * markup field values injected (richtext, text). The rendered tree is
+ * walked in step with the template tree; a rendered child that no template
+ * child can account for (same tag, template's classes all present) starts
+ * a free region. List sections still match, because every iteration of a
+ * section renders the same template child.
+ *
+ * @returns the free region roots, or null when the rendered root does not
+ * match the template root at all (a module the composer renders from
+ * other data, such as a navigation menu) — nothing can be attributed then.
+ */
+export function freeRegions(
+  rendered: MarkupNode,
+  templateRoots: readonly MarkupNode[],
+): MarkupNode[] | null {
+  const tRoot = templateRoots[0];
+  if (!tRoot || !accounts(tRoot, rendered)) return null;
+  const free: MarkupNode[] = [];
+  const walk = (r: MarkupNode, t: MarkupNode) => {
+    for (const c of r.children) {
+      if (c.moduleId !== null) continue;
+      const match = t.children.find((tc) => accounts(tc, c));
+      if (match) walk(c, match);
+      else free.push(c);
+    }
+  };
+  walk(rendered, tRoot);
+  return free;
+}
+
+function accounts(template: MarkupNode, rendered: MarkupNode): boolean {
+  return (
+    template.tag === rendered.tag && template.classes.every((k) => rendered.classes.includes(k))
+  );
+}
+
+/** Every module root (`data-caelo-module-id`) in a forest, nested ones included. */
+export function moduleRoots(roots: readonly MarkupNode[]): MarkupNode[] {
+  const out: MarkupNode[] = [];
+  const walk = (n: MarkupNode) => {
+    if (n.moduleId !== null) out.push(n);
+    for (const c of n.children) walk(c);
+  };
+  for (const r of roots) walk(r);
+  return out;
+}
+
+/** A short operator-readable name for a pattern: its root key, e.g. `div.chain`. */
+export function patternLabel(p: Pick<MarkupNode, "tag" | "classes">): string {
+  return nodeKey(p);
+}

package/src/media.ts

@@ -123,6 +123,49 @@ export function buildMediaUrl(slug: string, variant: MediaVariantTag | string):
     : `${MEDIA_URL_PREFIX}/${slug}/${variant}`;
 }
 
+/**
+ * The favicon rendition of a raster image bound to the theme's favicon
+ * slot: a square PNG, `FAVICON_VARIANT_PX` on each side. Browsers show a
+ * favicon at 16-32 CSS px (64 covers 2x screens). The `orig` of a raster
+ * favicon is often an AI-generated 1024 px PNG of 1-2 MB, and the browser
+ * fetches the `<link rel="icon">` while the page loads: under Lighthouse's
+ * throttled network that download pushed LCP from 0.9 s to 4.7 s on an
+ * otherwise perfect page (real-AI run 39038927234). Created when the
+ * favicon is bound (`themes.set_asset`), not on every upload.
+ */
+export const FAVICON_VARIANT = "icon-64";
+
+/** Edge length in px of {@link FAVICON_VARIANT}. */
+export const FAVICON_VARIANT_PX = 64;
+
+/** Raster mimes: the ones the image pipeline decodes (sharp) and resizes. */
+const RASTER_IMAGE_MIMES: ReadonlySet<string> = new Set([
+  "image/jpeg",
+  "image/png",
+  "image/webp",
+  "image/avif",
+  "image/gif",
+]);
+
+/** Whether `mime` is a raster image the pipeline can decode and resize. */
+export function isRasterImageMime(mime: string): boolean {
+  return RASTER_IMAGE_MIMES.has(mime);
+}
+
+/**
+ * The URL + content type the `<link rel="icon">` of a bound favicon uses.
+ * A raster favicon ships its {@link FAVICON_VARIANT} PNG; ICO and SVG are
+ * favicon formats already and ship as uploaded (`orig`).
+ */
+export function themeFaviconRendition(
+  slug: string,
+  mime: string,
+): { readonly url: string; readonly mime: string } {
+  return isRasterImageMime(mime)
+    ? { url: buildMediaUrl(slug, FAVICON_VARIANT), mime: "image/png" }
+    : { url: buildMediaUrl(slug, "orig"), mime };
+}
+
 /**
  * Turn a human/asset label into a URL-safe media slug: lowercase ascii,
  * kebab-case, extension + junk stripped, capped at 60 chars. NOT

package/src/preview-compose.ts

@@ -108,9 +108,10 @@ export interface ComposeThemeAsset {
   readonly mediaId: string;
   readonly url: string;
   /**
-   * `media_assets.mime` of the bound asset — the content type of the
-   * `orig` bytes the URL serves. Carried so `<head>` metadata that
-   * declares a type (`<link rel="icon" type=…>`) states the real one.
+   * Content type of the bytes the URL serves: `media_assets.mime` for the
+   * `orig` URL, `image/png` for a raster favicon's rendition (see
+   * `themeFaviconRendition`). Carried so `<head>` metadata that declares
+   * a type (`<link rel="icon" type=…>`) states the real one.
    */
   readonly mime: string;
 }
@@ -239,7 +240,8 @@ export function fontsHeadFragment(fonts: ComposeFonts | undefined): string | nul
  * regardless of which layout or chrome modules the page uses, so the
  * composer emits it from the theme binding instead of relying on a
  * module to carry the tag. The href is the media URL as composed
- * (`/_caelo/media/<slug>`); the static generator's media pass rewrites
+ * (`/_caelo/media/<slug>/icon-64` for a raster favicon, the `orig` URL
+ * for ICO/SVG — see `themeFaviconRendition`); the static generator's media pass rewrites
  * it to the published `/_assets/<slug>.<hash>.<ext>` and copies the bytes, the
  * same as any other media reference. Returns null when no theme is
  * threaded or no favicon is bound (nothing to declare; browsers fall

package/src/publish-live-parity.ts

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #834 / #835 — the wording Publish live's parity refusal shares between
+ * the server that writes it (admin-core `build-parity.ts`) and the Live
+ * edit toolbar that renders it. The toolbar truncates long errors, so it
+ * recognises a parity refusal by its prefix and shows the next step
+ * ("Stage again") as its own, untruncated hint next to the button.
+ */
+
+/** Every parity refusal starts with this. */
+export const PARITY_REFUSAL_PREFIX = "Publish live stopped:";
+
+/**
+ * The next step every parity refusal ends with. Operators use the
+ * toolbar's "Stage again" button next to Publish live; the AI re-stages
+ * with its tools.
+ */
+export const RESTAGE_NEXT_STEP =
+  'Next step: Stage again (the "Stage again" button next to Publish live, or stage_changes / deploy_staging in chat), check staging, then Publish live.';
+
+/** True when `message` is a Publish-live parity refusal. */
+export function isParityRefusal(message: string): boolean {
+  return message.startsWith(PARITY_REFUSAL_PREFIX);
+}

package/src/version.ts

@@ -22,7 +22,7 @@
  * follow standard SemVer.
  */
 
-export const CAELO_VERSION = "0.10.52";
+export const CAELO_VERSION = "0.10.53";
 
 /**
  * Deprecated alias for back-compat — early P17 work spelled this