@caelo-cms/shared 0.10.64 → 0.10.66

package/src/build-page.ts

@@ -20,6 +20,7 @@
  */
 
 import { z } from "zod";
+import { positionInputSchema } from "./ai-tools.js";
 import {
   contentInstanceCreateSchema,
   MODULE_CSS_MAX,
@@ -31,6 +32,7 @@ import {
   slugSchema,
   syncModeSchema,
 } from "./content.js";
+import { SEO_DESCRIPTION_HARD_MAX } from "./seo.js";
 
 /** Content values keyed by the module's declared field names. */
 const contentValuesSchema = z.record(z.string(), z.unknown());
@@ -106,11 +108,25 @@ export const buildPageModuleSchema = z
      * module / module-list field value. A detached entry requires `ref`.
      */
     blockName: slugSchema.optional(),
+    /**
+     * Where in its block the entry lands — the same grammar as
+     * add_module's `position` ("top", "bottom", or a 0-based index).
+     * Omitted = "bottom": entries append in array order, so a new page
+     * needs none. Entries are inserted in array order, each into the
+     * block as it stands after the entries before it; an index past the
+     * end appends. Meaningless (and rejected) on a detached entry.
+     *
+     * Accepted because the AI carries `position` over from add_module,
+     * and on an existing page "put this at the top" is a real intent a
+     * pure append cannot express (e2e-livedit detected bugs).
+     */
+    position: positionInputSchema.optional(),
     /**
      * Local handle other entries in the SAME call can reference: a
-     * module/module-list field value of `{"$ref": "<ref>"}` resolves to
-     * this entry's `{moduleId, contentInstanceId}`. Entries resolve in
-     * array order, so referenced entries must come FIRST.
+     * module/module-list field value of `{"$ref": "<ref>"}` (or a
+     * `moduleId: {"$ref"}`) resolves to this entry's `{moduleId,
+     * contentInstanceId}`. Array position does not matter: the op mints
+     * referenced entries before the entries that embed them.
      */
     ref: z
       .string()
@@ -149,6 +165,14 @@ export const buildPageModuleSchema = z
   })
   .strict()
   .superRefine((entry, ctx) => {
+    if (entry.blockName === undefined && entry.position !== undefined) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message:
+          "`position` places an entry inside its block, but this entry has no `blockName` (a DETACHED, " +
+          "nested-only module is not placed). Drop `position`, or pass `blockName` to place it.",
+      });
+    }
     if (entry.blockName === undefined && entry.ref === undefined) {
       ctx.addIssue({
         code: z.ZodIssueCode.custom,
@@ -211,6 +235,15 @@ export const buildPageTargetSchema = z
      * Compatible with either target shape (create OR existing pageId).
      */
     importPageId: z.string().uuid().optional(),
+    /**
+     * The new page's meta description, written in the same transaction
+     * with the fill-once semantics of `pages_seo.autofill` (CLAUDE.md §2).
+     * A staging build refuses a published page without one, so the page
+     * is Stage-ready from the call that creates it. Create mode (or an
+     * importPageId rebuild) only — an existing page gets its first
+     * description from `autofill_page_seo`.
+     */
+    metaDescription: z.string().trim().min(1).max(SEO_DESCRIPTION_HARD_MAX).optional(),
   })
   .strict()
   .superRefine((page, ctx) => {
@@ -218,6 +251,13 @@ export const buildPageTargetSchema = z
       ["slug", "title", "name", "templateId", "status", "parentPageId"] as const
     ).filter((k) => page[k] !== undefined);
     if (page.pageId !== undefined) {
+      if (page.metaDescription !== undefined) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message:
+            "page.metaDescription is written only for a page this call CREATES — drop it with pageId; an existing page without a description gets one via autofill_page_seo.",
+        });
+      }
       if (createKeys.length > 0) {
         ctx.addIssue({
           code: z.ZodIssueCode.custom,
@@ -250,8 +290,8 @@ export const buildPageInputSchema = z
   })
   .strict()
   .superRefine((input, ctx) => {
-    // `ref` handles must be unique — a duplicate would silently shadow
-    // the earlier entry when a later {"$ref"} resolves.
+    // `ref` handles must be unique — a duplicate would make a {"$ref"}
+    // ambiguous.
     const seen = new Set<string>();
     for (const [i, entry] of input.modules.entries()) {
       if (entry.ref === undefined) continue;

package/src/google-oauth.ts

@@ -25,3 +25,13 @@ export const GOOGLE_OAUTH_CLIENT_ID = /^[0-9]+-[a-z0-9]+\.apps\.googleuserconten
 export function iapRedirectUri(clientId: string): string {
   return `https://iap.googleapis.com/v1/oauth/clientIds/${clientId}:handleRedirect`;
 }
+
+/**
+ * #967 — the Google console page of one OAuth client, where its authorized
+ * redirect URIs and client secrets are edited. Shared so the setup page can
+ * link it as the Owner types the client ID, and the preflight can name it
+ * in every fix.
+ */
+export function oauthClientConsoleUrl(projectId: string, clientId: string): string {
+  return `https://console.cloud.google.com/auth/clients/${encodeURIComponent(clientId)}?project=${encodeURIComponent(projectId)}`;
+}

package/src/index.ts

@@ -43,6 +43,7 @@ export {
   type StructuredLogEntry,
 } from "./logger.js";
 export * from "./markup-structure.js";
+export * from "./mcp-access.js";
 export * from "./media.js";
 export * from "./nested-module-render.js";
 export * from "./page-log.js";
@@ -64,6 +65,7 @@ export * from "./release-manifest.js";
 export * from "./responsive-images.js";
 export * from "./result.js";
 export * from "./safe-keys.js";
+export * from "./screenshot-capture.js";
 export * from "./seo.js";
 export * from "./skills.js";
 export * from "./snapshots.js";

package/src/link-canonicalise.test.ts

@@ -180,6 +180,35 @@ describe("canonicaliseUrl", () => {
     expect(strict.issues.map((i) => i.kind)).toEqual(["unknown-page-path"]);
   });
 
+  // e2e-livedit detected bugs: the site header (brand link "/", nav
+  // "/#features") is built before the homepage exists and was refused.
+  it("keeps the site root literal while no page serves it, never an issue", () => {
+    const noRoot: LinkTargetLookup = {
+      ...lookup,
+      pageIdForPath: (p) => (p === "/" ? null : lookup.pageIdForPath(p)),
+    };
+    const r = linkCanonicaliseRun(noRoot);
+    expect(canonicaliseUrl("/", r, "html")).toBe("/");
+    expect(canonicaliseUrl("/#features", r, "fields.nav.default[1].href")).toBe("/#features");
+    expect(canonicaliseUrl("https://example.com/?ref=nav", r, "x")).toBe(
+      "https://example.com/?ref=nav",
+    );
+    expect(canonicaliseHtmlLinks('<a href="/">Home</a><a href="/#features">F</a>', r, "html")).toBe(
+      '<a href="/">Home</a><a href="/#features">F</a>',
+    );
+    expect(r.issues).toEqual([]);
+    // A suffix the stored grammar cannot carry is still refused, and any
+    // other unknown path still is an issue: only the root is guaranteed.
+    canonicaliseUrl('/#bad"anchor', r, "y");
+    canonicaliseUrl("/get-started", r, "z");
+    expect(r.issues.map((i) => [i.kind, i.value])).toEqual([
+      ["unsupported-link-form", '/#bad"anchor'],
+      ["unknown-page-path", "/get-started"],
+    ]);
+    // Once the homepage exists the root becomes its reference as usual.
+    expect(canonicaliseUrl("/#features", run(), "x")).toBe(`caelo:page/${HOME}#features`);
+  });
+
   it("reports a malformed reference instead of passing it through", () => {
     const r = run();
     const bad = [

package/src/link-canonicalise.ts

@@ -39,6 +39,12 @@
  *     that run not built yet is kept and listed in `run.pending`; the
  *     caller records it and the run's finalisation converts it (or
  *     reports it) once the run's pages exist.
+ *   - the site root: `/` (with an optional `#anchor` / `?query`) while no
+ *     page serves it yet is kept literal, not refused. Every site has a
+ *     root page by the time it ships — the staged build refuses one
+ *     without — so the link cannot dangle, and site chrome (the brand
+ *     link, `/#features` nav items) is routinely written before the
+ *     homepage. Once the homepage exists, `/` canonicalises as usual.
  */
 
 import {
@@ -322,6 +328,16 @@ export function canonicaliseUrl(
     run.pending.push({ value: v, path: normalised, where });
     return value;
   }
+  if (pageId === null && normalised === "/") {
+    // The site root before its page exists (a header built ahead of the
+    // homepage). It cannot dangle: the staged build refuses a site with
+    // no page at "/" (CLAUDE.md §2: loud there, not here). Kept literal;
+    // the next save after the homepage exists stores its reference.
+    if ((query !== null && !QUERY_OK.test(query)) || (anchor !== null && !ANCHOR_OK.test(anchor))) {
+      if (!run.grandfathered.has(v)) issue(run, "unsupported-link-form", v, where);
+    }
+    return value;
+  }
   if (pageId === null) {
     const lastSegment = path.slice(path.lastIndexOf("/") + 1);
     const isFile = FILE_EXT_RE.test(lastSegment);
@@ -592,7 +608,8 @@ export function describeLinkIssues(issues: readonly LinkCanonicaliseIssue[]): st
     `Internal link check failed — ${lines.join("; ")}${more}. ` +
     "Internal links must point at an existing page or media asset. Next step: use the exact path " +
     "of an existing page (list_pages shows every page's path) or an existing media URL (find_media); " +
-    "if the page does not exist yet, create it first (or leave the link out and add it once the page " +
-    "exists). For a link to another site, write the full https:// URL."
+    "if the page does not exist yet, create it first (build_page with `modules: []` makes an empty page " +
+    "shell) or leave the link out and add it once the page exists. The site root `/` is always valid. " +
+    "For a link to another site, write the full https:// URL."
   );
 }

package/src/markup-structure.test.ts

@@ -14,6 +14,7 @@ import {
   stripMustache,
   templateShape,
 } from "./markup-structure.js";
+import { tagModuleId } from "./module-id-tag.js";
 
 const chain = (steps: string[]) =>
   `<div class="chain">${steps
@@ -164,6 +165,90 @@ describe("templates and free regions", () => {
   });
 });
 
+describe("#1027 — template children are matched by best fit, not first fit", () => {
+  // The three templates from the searchVIU audit: a classless (or less
+  // specific) left column before a classed right column. First-fit paired
+  // the left column's template node with the right column and reported
+  // the right column's own template markup as free HTML.
+  const DEMO_FORM =
+    '<div class="wrapc ctaform"><div><h2>{{title}}</h2><p>{{intro}}</p></div>' +
+    '<div class="box steps" data-steps data-topic="{{preselected_topic}}">' +
+    '<ol class="sbar"><li class="on">Thema</li><li>Kontakt</li><li>Termin</li></ol>' +
+    '<div class="step"><label>Thema</label><select name="topic"><option>SEO</option></select></div>' +
+    '<div class="step"><label>E-Mail</label><input type="email" name="email"></div>' +
+    '<div class="step"><button type="submit">Demo anfragen</button></div></div></div>';
+  const SPLIT_CHAT =
+    '<section class="split"><div class="rv"><h2>{{title}}</h2><p>{{lead}}</p></div>' +
+    '<div class="chat rv"><div class="q"><p>Wie steht meine Seite?</p></div>' +
+    '<div class="a"><p>Drei Seiten haben neue 404-Fehler.</p><ul><li>/a</li></ul></div></div></section>';
+  const HERO_WINDOW =
+    '<section class="hero"><div><h1>{{title}}</h1><p>{{lead}}</p><a class="btn" href="{{cta_href}}">{{cta}}</a></div>' +
+    '<div class="win"><div class="bar"><span></span><span></span></div>' +
+    '<div class="bd"><img src="{{image}}" alt=""><p class="cap">Monitoring</p></div></div></section>';
+
+  /** The rendered module: placeholders filled, root tagged as the composer does. */
+  const render = (template: string, fill = "x") =>
+    tagModuleId(template.replace(/\{\{\{?\w+\}?\}\}/g, fill), "m1");
+  const free = (template: string, rendered: string) => {
+    const root = moduleRoots(parseMarkup(rendered))[0];
+    if (!root) throw new Error("no module root");
+    return freeRegions(root, parseMarkup(stripMustache(template)));
+  };
+
+  for (const [name, template] of [
+    ["Demo-Formular in drei Schritten (div before div.box.steps)", DEMO_FORM],
+    ["Split mit KI-Chat (div.rv before div.chat.rv)", SPLIT_CHAT],
+    ["Hero Produktseite mit Fenster (div before div.win)", HERO_WINDOW],
+  ] as const) {
+    it(`${name}: its own rendered output has no free regions`, () => {
+      expect(free(template, render(template))).toEqual([]);
+    });
+  }
+
+  it("a classless div before a div.card sibling: no free regions", () => {
+    const template =
+      '<div class="pair"><div><p>{{a}}</p></div><div class="card"><h3>{{t}}</h3><ul class="pts"><li>{{p}}</li></ul></div></div>';
+    expect(free(template, render(template))).toEqual([]);
+  });
+
+  it("two classless siblings with different insides: the one that accounts wins", () => {
+    const template =
+      '<div class="two"><div><h2>{{t}}</h2><p>{{p}}</p></div><div><ul class="x"><li>{{i}}</li></ul></div></div>';
+    expect(free(template, render(template))).toEqual([]);
+  });
+
+  it("a section repeating a classed child still matches every iteration", () => {
+    const template =
+      '<div class="grid"><div><h2>{{title}}</h2></div>{{#cards}}<div class="card"><p>{{.}}</p></div>{{/cards}}</div>';
+    const rendered = tagModuleId(
+      '<div class="grid"><div><h2>T</h2></div><div class="card"><p>a</p></div><div class="card"><p>b</p></div></div>',
+      "m1",
+    );
+    expect(free(template, rendered)).toEqual([]);
+  });
+
+  it("stays fast when many rendered children each fit several template children", () => {
+    // Every rendered <div> fits all eight classless template <div>s, so the
+    // best-fit choice weighs each candidate; the per-pair memo keeps that
+    // linear in the rendered size.
+    const template = `<div class="wide">${"<div><div><p>{{t}}</p></div></div>".repeat(8)}</div>`;
+    const rendered = tagModuleId(
+      `<div class="wide">${"<div><div><p>x</p><span>y</span></div></div>".repeat(5000)}</div>`,
+      "m1",
+    );
+    const started = performance.now();
+    expect(free(template, rendered)?.length).toBe(5000);
+    expect(performance.now() - started).toBeLessThan(1000);
+  });
+
+  it("markup pasted into a field value of such a template is still free (#820)", () => {
+    const pasted = chain(["a", "b"]);
+    const rendered = render(HERO_WINDOW).replace("<p>x</p>", `<p>x</p>${pasted}`);
+    const regions = free(HERO_WINDOW, rendered) ?? [];
+    expect(outermostPatterns(regions).map((f) => f.node.classes[0])).toEqual(["chain"]);
+  });
+});
+
 describe("bounds", () => {
   it("stops collecting elements at MAX_NODES", () => {
     const html = "<div>".repeat(10) + "<i></i>".repeat(MAX_NODES + 100) + "</div>".repeat(10);

package/src/markup-structure.ts

@@ -256,7 +256,15 @@ export function templateShape(templateHtml: string): SubtreeShape | null {
  * 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.
+ * section renders the same template child. Nested module roots
+ * (`data-caelo-module-id`) are skipped: their own template accounts for
+ * them.
+ *
+ * Several template children can account for one rendered child — a
+ * classless `<div>` accounts for any `<div>` — so the walk picks the best
+ * one ({@link pickTemplateChild}), not the first: taking the first paired
+ * a classless left column with the classed right column and reported the
+ * right column's template markup as free (#1027).
  *
  * @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
@@ -268,17 +276,103 @@ export function freeRegions(
 ): MarkupNode[] | null {
   const tRoot = templateRoots[0];
   if (!tRoot || !accounts(tRoot, rendered)) return null;
+  return [...attribute(rendered, tRoot, new Map()).free];
+}
+
+/** How one rendered subtree attributes against one template subtree. */
+interface Attribution {
+  /** The free region roots below the rendered node. */
+  readonly free: readonly MarkupNode[];
+  /** Elements inside those regions: the cost the best match minimises. */
+  readonly freeNodes: number;
+}
+
+type AttributionMemo = Map<MarkupNode, Map<MarkupNode, Attribution>>;
+
+/**
+ * Attribute the children of `r`, rendered from template node `t`.
+ * Memoised per (rendered, template) pair, because the best-match choice
+ * evaluates a rendered child against every candidate that accounts for
+ * it; each pair is computed once, so the walk stays polynomial.
+ */
+function attribute(r: MarkupNode, t: MarkupNode, memo: AttributionMemo): Attribution {
+  let byTemplate = memo.get(r);
+  const hit = byTemplate?.get(t);
+  if (hit) return hit;
   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);
+  let freeNodes = 0;
+  // Template index of the previous rendered child's match: siblings
+  // render in template order (a section repeats one child in place).
+  let cursor = 0;
+  for (const c of r.children) {
+    if (c.moduleId !== null) continue;
+    const match = pickTemplateChild(c, t.children, cursor, memo);
+    if (match) {
+      cursor = match.index;
+      for (const f of match.attribution.free) free.push(f);
+      freeNodes += match.attribution.freeNodes;
+    } else {
+      free.push(c);
+      freeNodes += countNodes(c);
     }
-  };
-  walk(rendered, tRoot);
-  return free;
+  }
+  const out: Attribution = { free, freeNodes };
+  if (!byTemplate) {
+    byTemplate = new Map();
+    memo.set(r, byTemplate);
+  }
+  byTemplate.set(t, out);
+  return out;
+}
+
+/**
+ * The template child that rendered `c`, among those that account for it:
+ *   1. the exact class set wins over a subset (`div.chat.rv` over `div.rv`),
+ *   2. then the most classes in common, so a classless template child
+ *      wins only when no classed one accounts for `c`,
+ *   3. then the one whose subtree leaves the fewest elements unaccounted,
+ *   4. then sibling order: at or after the previous match, nearest first.
+ */
+function pickTemplateChild(
+  c: MarkupNode,
+  candidates: readonly MarkupNode[],
+  cursor: number,
+  memo: AttributionMemo,
+): { readonly index: number; readonly attribution: Attribution } | null {
+  let best: {
+    readonly index: number;
+    readonly attribution: Attribution;
+    readonly rank: readonly number[];
+  } | null = null;
+  for (const [index, tc] of candidates.entries()) {
+    if (!accounts(tc, c)) continue;
+    const attribution = attribute(c, tc, memo);
+    const rank = [
+      tc.classes.length === c.classes.length ? 1 : 0,
+      tc.classes.length,
+      -attribution.freeNodes,
+      index >= cursor ? 1 : 0,
+      -Math.abs(index - cursor),
+    ];
+    if (!best || outranks(rank, best.rank)) best = { index, attribution, rank };
+  }
+  return best;
+}
+
+function outranks(a: readonly number[], b: readonly number[]): boolean {
+  for (let i = 0; i < a.length; i++) {
+    const x = a[i] ?? 0;
+    const y = b[i] ?? 0;
+    if (x !== y) return x > y;
+  }
+  return false;
+}
+
+/** Elements in a subtree, nested module roots excluded (they are not free). */
+function countNodes(n: MarkupNode): number {
+  let count = 1;
+  for (const c of n.children) if (c.moduleId === null) count += countNodes(c);
+  return count;
 }
 
 function accounts(template: MarkupNode, rendered: MarkupNode): boolean {

package/src/mcp-access.ts

@@ -0,0 +1,73 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * Issue #968 — the facts about Caelo's MCP access paths that the admin UI,
+ * the remote resolver's error messages and the docs must agree on: which
+ * surface needs which permission, what each surface is for in plain words,
+ * and how a client app's key reads to a person. Client-safe (no server
+ * imports): Settings → MCP renders it, admin-core words refusals with it.
+ * The concept is docs/dev/mcp-access.md.
+ */
+
+/** A remote MCP surface: talk to the site's AI, or drive its admin tools. */
+export type McpSurfaceName = "chat" | "admin";
+
+/**
+ * The permission each remote surface needs. Chat writes content through
+ * Caelo's own AI; admin exposes every tool the AI has, so it needs what an
+ * admin-scoped MCP token needs. Owners have both.
+ */
+export const MCP_SURFACE_PERMISSION: Readonly<
+  Record<McpSurfaceName, "content.write" | "settings.write">
+> = {
+  chat: "content.write",
+  admin: "settings.write",
+};
+
+/** What a surface does and who may use it, in the words the UI and errors use. */
+export const MCP_SURFACE_COPY: Readonly<
+  Record<McpSurfaceName, { readonly title: string; readonly does: string; readonly who: string }>
+> = {
+  chat: {
+    title: "Chat with this site's AI",
+    does: "The AI tool sends requests to Caelo's own AI, which builds and edits the site like the Live Edit chat does.",
+    who: "Everyone who may edit content (content.write).",
+  },
+  admin: {
+    title: "Full admin access",
+    does: "The AI tool gets every tool Caelo's AI has and does the work itself, on a preview branch. Approval-gated actions still wait for an Owner's click.",
+    who: "Owners and roles that may change settings (settings.write).",
+  },
+};
+
+/**
+ * A suggested connector name, so two connectors to one site in the same AI
+ * tool are told apart: "Caelo viu.one (Chat)", "Caelo viu.one (Admin)".
+ */
+export function mcpConnectorName(siteHost: string, surface: McpSurfaceName): string {
+  return `Caelo ${siteHost} (${surface === "admin" ? "Admin" : "Chat"})`;
+}
+
+/**
+ * How a client app's key (the gateway's `mcpClientKey`) reads to a person.
+ * Known CIMD documents get their product name; a DCR key shows the name the
+ * app registered with (unverified — anyone can register any name).
+ */
+export function describeMcpClient(clientKey: string | null): string {
+  if (clientKey === null) return "An app from before per-app connections";
+  if (clientKey.startsWith("dcr:sha256:") || clientKey.startsWith("sha256:")) {
+    return "An app that did not give its name";
+  }
+  if (clientKey.startsWith("dcr:")) return clientKey.slice(4);
+  let url: URL;
+  try {
+    url = new URL(clientKey);
+  } catch {
+    return clientKey;
+  }
+  if (url.hostname === "chatgpt.com") return "ChatGPT";
+  if (url.hostname === "claude.ai") {
+    return url.pathname.includes("claude-code") ? "Claude Code" : "Claude";
+  }
+  return url.hostname;
+}

package/src/module-id-tag.ts

@@ -0,0 +1,38 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The `data-caelo-module-id` stamp on a module's root element. Every
+ * module root carries it, page placements (the composer) and nested
+ * modules in `module` / `module-list` fields (nested-module-render.ts)
+ * alike, so anything reading rendered HTML — the live-edit overlay, the
+ * core `structure` and `links` quality checks — can tell which module
+ * rendered which element without another mapping (#1027).
+ *
+ * Its own file because both the composer and the nested renderer use
+ * it, and the composer already imports the nested renderer.
+ */
+
+/** The attribute every module root carries. */
+export const MODULE_ID_ATTRIBUTE = "data-caelo-module-id";
+
+/**
+ * Insert `data-caelo-module-id="<id>"` into the first opening tag of
+ * the module's HTML. Idempotent — an already-tagged first element keeps
+ * its id, so a nested module that renders as its parent's first element
+ * stays attributed to itself. Comments / DOCTYPE / leading whitespace
+ * before the first tag are tolerated. HTML without an opening tag (pure
+ * text, a failure comment) returns unchanged because there's nothing to
+ * attach to.
+ *
+ * @example tagModuleId("<p>hi</p>", "abc") // '<p data-caelo-module-id="abc">hi</p>'
+ */
+export function tagModuleId(html: string, moduleId: string): string {
+  if (!html) return html;
+  const firstOpen = /<([a-zA-Z][a-zA-Z0-9-]*)\b([^>]*)>/;
+  const m = firstOpen.exec(html);
+  if (!m) return html;
+  const tagAttrs = m[2] ?? "";
+  if (/\sdata-caelo-module-id\s*=/.test(tagAttrs)) return html;
+  const replaced = `<${m[1]}${tagAttrs} ${MODULE_ID_ATTRIBUTE}="${moduleId}">`;
+  return html.slice(0, m.index) + replaced + html.slice(m.index + m[0].length);
+}