@caelo-cms/shared 0.10.58 → 0.10.59

package/src/bug-intake.ts

@@ -0,0 +1,256 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * The wire contract between a Caelo install and the Caelo-operated bug
+ * intake (epic #901). Both sides import this module, so the request shapes,
+ * the signature, the fingerprint and the redaction can never drift apart.
+ *
+ * Flow:
+ *   1. On opt-in the install generates an Ed25519 keypair and registers the
+ *      public key under its `install_id` (`POST /v1/installs`). The intake
+ *      pins the first key it sees for an id (trust on first use).
+ *   2. Every later request is signed: the install signs
+ *      {@link bugIntakeSigningString} and sends the three
+ *      {@link BUG_INTAKE_HEADERS}. The intake verifies against the pinned key
+ *      and refuses timestamps outside {@link BUG_INTAKE_MAX_CLOCK_SKEW_MS}.
+ *   3. A report (`POST /v1/reports`) is answered with the status of the
+ *      cluster it joined; `POST /v1/clusters/status` refreshes those
+ *      statuses later, so the install learns "fixed in vX" without polling
+ *      GitHub itself.
+ *
+ * Redaction runs on the install BEFORE a report is queued (the Owner's
+ * preview shows the redacted bytes) and again on the intake before anything
+ * reaches the public issue tracker.
+ */
+
+import { z } from "zod";
+
+/** Bumped on any breaking change to the request or response shapes below. */
+export const BUG_INTAKE_PROTOCOL_VERSION = 1;
+
+/** Header names carrying the install's identity and request signature. */
+export const BUG_INTAKE_HEADERS = {
+  installId: "x-caelo-install-id",
+  timestamp: "x-caelo-timestamp",
+  signature: "x-caelo-signature",
+} as const;
+
+/** Requests signed further than this from the intake's clock are refused (replay window). */
+export const BUG_INTAKE_MAX_CLOCK_SKEW_MS = 5 * 60 * 1000;
+
+/** Hard caps on what a report may carry once redacted. */
+export const BUG_INTAKE_LIMITS = {
+  title: 200,
+  whatHappened: 4000,
+  expected: 4000,
+  evidence: 4000,
+} as const;
+
+const fingerprintSchema = z.string().regex(/^[0-9a-f]{64}$/, "fingerprint must be 64 hex chars");
+
+/** `POST /v1/installs` — registers the install's public key (unsigned; TOFU). */
+export const bugIntakeRegisterRequest = z
+  .object({
+    protocolVersion: z.literal(BUG_INTAKE_PROTOCOL_VERSION),
+    installId: z.string().uuid(),
+    /** Raw 32-byte Ed25519 public key, base64. */
+    publicKey: z.string().regex(/^[A-Za-z0-9+/]{43}=$/, "publicKey must be a base64 Ed25519 key"),
+    caeloVersion: z.string().min(1).max(64),
+  })
+  .strict();
+export type BugIntakeRegisterRequest = z.infer<typeof bugIntakeRegisterRequest>;
+
+/** `POST /v1/reports` — one redacted bug report (signed). */
+export const bugIntakeReport = z
+  .object({
+    protocolVersion: z.literal(BUG_INTAKE_PROTOCOL_VERSION),
+    /** The install's own `ai_bug_reports.id`; the intake dedups retries on it. */
+    reportId: z.string().uuid(),
+    caeloVersion: z.string().min(1).max(64),
+    fingerprint: fingerprintSchema,
+    source: z.enum(["ai", "auto"]),
+    severity: z.enum(["blocking", "degraded", "cosmetic"]),
+    blockedTask: z.boolean(),
+    suspectedTool: z.string().max(200).nullable(),
+    title: z.string().min(1).max(BUG_INTAKE_LIMITS.title),
+    whatHappened: z.string().min(1).max(BUG_INTAKE_LIMITS.whatHappened),
+    expected: z.string().min(1).max(BUG_INTAKE_LIMITS.expected),
+    evidence: z.string().max(BUG_INTAKE_LIMITS.evidence).nullable(),
+  })
+  .strict();
+export type BugIntakeReport = z.infer<typeof bugIntakeReport>;
+
+/**
+ * Upstream state of the defect a report belongs to.
+ *   open       — known, not fixed yet
+ *   fixed      — the issue was closed as fixed; `fixedInVersion` names the
+ *                first release carrying the fix when it is known
+ *   regression — fixed once, reported again from a version that has the fix
+ *   wontfix    — closed as not planned
+ */
+export const bugClusterStatus = z.enum(["open", "fixed", "regression", "wontfix"]);
+export type BugClusterStatus = z.infer<typeof bugClusterStatus>;
+
+/**
+ * What the intake knows about one cluster (= one upstream issue). Also the
+ * `POST /v1/reports` response body: the cluster the report joined.
+ */
+export const bugIntakeClusterInfo = z
+  .object({
+    clusterId: z.string().min(1).max(100),
+    status: bugClusterStatus,
+    /** Public issue URL; null while the cluster is below the issue threshold. */
+    issueUrl: z.string().url().nullable(),
+    fixedInVersion: z.string().max(64).nullable(),
+  })
+  .strict();
+export type BugIntakeClusterInfo = z.infer<typeof bugIntakeClusterInfo>;
+
+/** `POST /v1/clusters/status` — refresh the status of clusters this install reported into (signed). */
+export const bugIntakeStatusRequest = z
+  .object({
+    protocolVersion: z.literal(BUG_INTAKE_PROTOCOL_VERSION),
+    clusterIds: z.array(z.string().min(1).max(100)).min(1).max(100),
+  })
+  .strict();
+export type BugIntakeStatusRequest = z.infer<typeof bugIntakeStatusRequest>;
+
+export const bugIntakeStatusResponse = z
+  .object({ clusters: z.array(bugIntakeClusterInfo) })
+  .strict();
+export type BugIntakeStatusResponse = z.infer<typeof bugIntakeStatusResponse>;
+
+/** Error body every non-2xx intake response carries. */
+export const bugIntakeErrorResponse = z
+  .object({
+    error: z.string(),
+    /** true = retrying the same request later can succeed (rate limit, outage). */
+    retryable: z.boolean(),
+  })
+  .strict();
+export type BugIntakeErrorResponse = z.infer<typeof bugIntakeErrorResponse>;
+
+const encoder = new TextEncoder();
+
+function bytesToHex(bytes: Uint8Array): string {
+  return Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+}
+
+async function sha256Hex(text: string): Promise<string> {
+  const digest = await crypto.subtle.digest("SHA-256", encoder.encode(text) as BufferSource);
+  return bytesToHex(new Uint8Array(digest));
+}
+
+/**
+ * The exact bytes an install signs for a request. Binding method, path and
+ * body hash means a captured signature cannot be replayed against another
+ * endpoint or with another body; the timestamp bounds replay in time.
+ */
+export async function bugIntakeSigningString(args: {
+  method: string;
+  path: string;
+  timestamp: string;
+  body: string;
+}): Promise<string> {
+  return `${args.method.toUpperCase()}\n${args.path}\n${args.timestamp}\n${await sha256Hex(args.body)}`;
+}
+
+/**
+ * Collapse the parts of an error text that differ between occurrences of the
+ * same defect (ids, numbers, quoted values, URLs, paths) so the same bug on
+ * two installs yields the same text.
+ */
+export function normalizeBugText(text: string): string {
+  return (
+    text
+      .toLowerCase()
+      .replace(/https?:\/\/\S+/g, "<url>")
+      .replace(/[\w.+-]+@[\w-]+(\.[\w-]+)+/g, "<email>")
+      .replace(/[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/g, "<id>")
+      .replace(/\b[0-9a-f]{12,}\b/g, "<id>")
+      // Quoted values (a slug, a title) vary per occurrence; a quoted field
+      // path or tool name (`page.slug`, `build_page`) tells two defects apart,
+      // so identifiers carrying `.`, `_` or `[` stay.
+      .replace(/(["'`])((?:(?!\1).){0,200})\1/g, (m, _q: string, inner: string) =>
+        /^[A-Za-z][\w.[\]-]{0,59}$/.test(inner) && /[._[]/.test(inner) ? m : "<v>",
+      )
+      .replace(/(?:\/[\w.-]+){2,}/g, "<path>")
+      .replace(/\d+(\.\d+)?/g, "<n>")
+      .replace(/\s+/g, " ")
+      .trim()
+      .slice(0, 300)
+  );
+}
+
+/**
+ * Deterministic identity of a defect, computed on the install. The Caelo
+ * version is deliberately NOT part of it, so one defect stays one cluster
+ * across releases (that is how a regression is recognised).
+ *
+ * Auto-captured reports carry the failing tool's error text as
+ * `whatHappened`, which is stable once normalised. AI-filed reports are free
+ * prose, so their fingerprint (tool + normalised title) only catches exact
+ * repeats; the intake clusters the rest semantically.
+ */
+export async function computeBugFingerprint(args: {
+  source: "ai" | "auto";
+  suspectedTool: string | null;
+  title: string;
+  whatHappened: string;
+}): Promise<string> {
+  const tool = (args.suspectedTool ?? "").trim().toLowerCase();
+  const signal = args.source === "auto" ? args.whatHappened : args.title;
+  return sha256Hex(`${args.source}\n${tool}\n${normalizeBugText(signal)}`);
+}
+
+/**
+ * Remove what must never leave an install inside a bug report: contact
+ * data, credentials, network addresses, and links (which name the site and
+ * its pages). Conservative by design: a report that lost a URL is still
+ * triageable, a leaked key is not recoverable.
+ */
+export function redactBugText(text: string): string {
+  return (
+    text
+      // Credentials first, before the generic long-token rule eats their prefix.
+      .replace(/\beyJ[\w-]+\.[\w-]+\.[\w-]+/g, "[redacted-token]")
+      .replace(
+        /\b(?:sk|pk|rk)-[\w-]{16,}|\bgh[pousr]_[A-Za-z0-9]{20,}|\bAKIA[0-9A-Z]{16}\b|\bAIza[\w-]{30,}|\bxox[abpr]-[\w-]{10,}/g,
+        "[redacted-secret]",
+      )
+      .replace(/\b(Bearer|Basic)\s+[\w.~+/=-]{8,}/gi, "$1 [redacted-secret]")
+      .replace(
+        /\b(password|passwd|secret|token|api[_-]?key)(["']?\s*[:=]\s*["']?)[^\s"',}]+/gi,
+        "$1$2[redacted-secret]",
+      )
+      .replace(/https?:\/\/[^\s"'<>)]+/g, "[url]")
+      .replace(/[\w.+-]+@[\w-]+(\.[\w-]+)+/g, "[email]")
+      .replace(/\b(?:\d{1,3}\.){3}\d{1,3}\b/g, "[ip]")
+      // International (+49 …) or trunk-prefixed (030 …) numbers; plain digit
+      // runs and ISO dates are left alone.
+      .replace(/\+\d[\d\s()/-]{7,}\d|\b0\d{2,5}[\s/-]?\d{3,}[\d\s-]*\d/g, "[phone]")
+      // Long mixed-case alphanumerics are keys or encoded payloads; source
+      // paths and snake_case names (no uppercase+digit mix) survive.
+      .replace(
+        /\b(?=[A-Za-z0-9+/_-]*\d)(?=[A-Za-z0-9+/_-]*[A-Z])[A-Za-z0-9+/_-]{40,}={0,2}/g,
+        "[redacted-blob]",
+      )
+  );
+}
+
+/** Redact and cap one report's free-text fields (both sides run this). */
+export function redactBugReportFields<
+  T extends { title: string; whatHappened: string; expected: string; evidence: string | null },
+>(report: T): T {
+  const cap = (s: string, n: number) => (s.length > n ? `${s.slice(0, n - 1)}…` : s);
+  return {
+    ...report,
+    title: cap(redactBugText(report.title), BUG_INTAKE_LIMITS.title),
+    whatHappened: cap(redactBugText(report.whatHappened), BUG_INTAKE_LIMITS.whatHappened),
+    expected: cap(redactBugText(report.expected), BUG_INTAKE_LIMITS.expected),
+    evidence:
+      report.evidence === null
+        ? null
+        : cap(redactBugText(report.evidence), BUG_INTAKE_LIMITS.evidence),
+  };
+}

package/src/content.ts

@@ -609,14 +609,14 @@ export const pageUpdateSchema = z
     templateId: z.string().uuid().optional(),
     status: pageStatusSchema.optional(),
     /**
-     * Only meaningful together with `slug`. A slug change rewrites the page's
-     * public URL, so the op creates a 301 from the old path by default and
-     * rewrites every nav-menu / link-list / module-body link that pointed at
-     * it — all inside the same transaction as the slug write.
+     * Only meaningful together with `slug`. A slug change moves the page's
+     * public URL, so the op creates a 301 from the old path by default,
+     * inside the same transaction as the slug write. Links on the site are
+     * page references (epic #724) and follow the page without a rewrite;
+     * the 301 is for links from outside the site.
      *
-     * `'skip'` suppresses ONLY the redirect (the link rewrites still run) and
-     * is for the rare case where the operator explicitly says the old URL
-     * should 404. Defaults to `'auto'`: silently dropping the 301 would strand
+     * `'skip'` suppresses the redirect and is for the rare case where the
+     * operator explicitly says the old URL should 404. Defaults to `'auto'`: silently dropping the 301 would strand
      * every inbound link, which is never a safe default (CLAUDE.md §2).
      */
     redirectFromOld: z.enum(["auto", "skip"]).optional(),

package/src/edit-markers.test.ts

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: MPL-2.0
+
+import { describe, expect, it } from "bun:test";
+import { finalizeEditMarkers, wrapEditableValues } from "./edit-markers.js";
+import { renderTemplate } from "./template-engine.js";
+
+const FIELDS = [
+  { name: "title", kind: "text" },
+  { name: "tags", kind: "text-list" },
+  { name: "links", kind: "link-list" },
+  { name: "photo", kind: "image" },
+] as const;
+
+function render(html: string, values: Record<string, unknown>, sharedPages = 0): string {
+  const wrapped = wrapEditableValues(values, FIELDS);
+  const rendered = renderTemplate({ html, fields: [...FIELDS], contentValues: wrapped }).html;
+  return finalizeEditMarkers(rendered, "content#2", sharedPages);
+}
+
+const marked = (fields: string, shared = 0) =>
+  ` data-caelo-fields="${fields}" data-caelo-placement="content%232" data-caelo-shared="${shared}"`;
+
+const open = (f: string, s = 0) => `<!--caelo:f p=content%232 s=${s} f=${f}-->`;
+const close = "<!--/caelo:f-->";
+
+describe("edit markers (#917)", () => {
+  it("marks a text field in text content", () => {
+    expect(render("<h1>{{title}}</h1>", { title: "Hello & welcome" })).toBe(
+      `<h1>${open("title")}Hello & welcome${close}</h1>`,
+    );
+  });
+
+  it("carries how many pages share a synced placement", () => {
+    expect(render("<h1>{{title}}</h1>", { title: "Hi" }, 4)).toContain(open("title", 4));
+  });
+
+  it("marks text-list items and link-list labels with their index", () => {
+    const html = render(
+      '<ul>{{#tags}}<li>{{.}}</li>{{/tags}}</ul><nav>{{#links}}<a href="{{href}}">{{label}}</a>{{/links}}</nav>',
+      {
+        tags: ["a", "b"],
+        links: [{ label: "Docs", href: "/docs" }],
+      },
+    );
+    expect(html).toContain(`<li>${open("tags.1")}b${close}</li>`);
+    expect(html).toContain(
+      `<a href="/docs"${marked("href=links.0.href")}>${open("links.0.label")}Docs${close}</a>`,
+    );
+  });
+
+  it("leaves other attributes, scripts, styles and titles byte-identical", () => {
+    const html = render(
+      '<div data-x=\'{{title}}\' title="{{title}}"></div><script>var t = "{{title}}";</script><style>/* {{title}} */</style><title>{{title}}</title><!-- {{title}} -->',
+      { title: "Hi > there" },
+    );
+    expect(html).toBe(
+      '<div data-x=\'Hi > there\' title="Hi > there"></div><script>var t = "Hi > there";</script><style>/* Hi > there */</style><title>Hi > there</title><!-- Hi > there -->',
+    );
+    expect(html).not.toMatch(/[\uE000-\uE002]/);
+  });
+
+  it("marks link targets, images and alt text on their tag (#918)", () => {
+    const html = render(
+      '{{#links}}<a href="{{href}}">{{label}}</a>{{/links}}<img src="{{photo}}" alt="{{title}}"/>',
+      { links: [{ label: "Docs", href: "/docs" }], photo: "/m/cup.webp", title: "A cup" },
+      2,
+    );
+    expect(html).toContain(
+      `<a href="/docs"${marked("href=links.0.href", 2)}>${open("links.0.label", 2)}Docs${close}</a>`,
+    );
+    expect(html).toContain(
+      `<img src="/m/cup.webp" alt="A cup"${marked("src=photo alt=title", 2)}/>`,
+    );
+  });
+
+  it("does not mark an attribute assembled from several parts", () => {
+    expect(render('<a href="/tags/{{title}}">x</a>', { title: "cups" })).toBe(
+      '<a href="/tags/cups">x</a>',
+    );
+  });
+
+  it("does not mark values that carry markup, empty values, or non-text kinds", () => {
+    const html = render("<h1>{{title}}</h1><p>{{#tags}}{{.}}{{/tags}}</p>", {
+      title: "<b>Bold</b>",
+      tags: [" "],
+    });
+    expect(html).toBe("<h1><b>Bold</b></h1><p> </p>");
+    expect(wrapEditableValues({ n: 3 }, [{ name: "n", kind: "number" }])).toEqual({ n: 3 });
+  });
+
+  it("keeps conditional sections working on wrapped values", () => {
+    expect(render("{{#title}}<p>{{title}}</p>{{/title}}", { title: "Hi" })).toBe(
+      `<p>${open("title")}Hi${close}</p>`,
+    );
+    expect(render("{{#title}}<p>{{title}}</p>{{/title}}", {})).toBe("");
+  });
+
+  it("encodes placement and field so a comment can never close early", () => {
+    const out = finalizeEditMarkers(
+      wrapEditableValues({ "a--b": "x" }, [{ name: "a--b", kind: "text" }])["a--b"] as string,
+      "main--slot#0",
+      0,
+    );
+    expect(out).toBe("<!--caelo:f p=main%2D%2Dslot%230 s=0 f=a%2D%2Db-->x<!--/caelo:f-->");
+  });
+
+  it("is a no-op on HTML without sentinels", () => {
+    const html = "<h1>Plain</h1><!-- caelo:missing reason=x -->";
+    expect(finalizeEditMarkers(html, "content#0", 0)).toBe(html);
+  });
+});

package/src/edit-markers.ts

@@ -0,0 +1,244 @@
+// SPDX-License-Identifier: MPL-2.0
+
+/**
+ * #917 — field markers for the Live Edit preview. They let the preview
+ * iframe tell which placement + field a piece of visible text came from,
+ * so the operator can edit that text in place.
+ *
+ * Two steps around the normal module render:
+ *
+ *   1. {@link wrapEditableValues} wraps every plain-text value of a
+ *      placement's content instance in private-use sentinels that carry
+ *      the field path. The template engine substitutes the wrapped value
+ *      like any other string (its escape is the identity), so the
+ *      sentinels land wherever the module author put `{{field}}`.
+ *   2. {@link finalizeEditMarkers} scans the rendered HTML. A sentinel in
+ *      text content becomes a pair of HTML comments around the value:
+ *      `<!--caelo:f p=<placement> s=<0|1> f=<path>-->value<!--/caelo:f-->`.
+ *      Comments do not affect layout or CSS selectors. A sentinel in a
+ *      comment or a raw-text element (`<script>`, `<style>`, `<title>`,
+ *      `<textarea>`) is removed and the value stays as it was. In a tag
+ *      it is removed too; an `href` / `src` / `alt` that is exactly one
+ *      marked value also gets `data-caelo-fields` on its tag (#918).
+ *
+ * Only the editor preview runs this. Published output never carries
+ * markers: the static generator and every other caller of
+ * `pages.render_preview` leave `editMarkers` off.
+ *
+ * Only values without `<` are wrapped: a value that carries markup cannot
+ * be edited as plain text without destroying that markup.
+ */
+
+const START = "\uE000";
+const SEP = "\uE001";
+const END = "\uE002";
+const SENTINELS = /[\uE000-\uE002]/g;
+
+/** Comment prefix of an opening marker; the closing marker is `/caelo:f`. */
+export const EDIT_MARKER_PREFIX = "caelo:f";
+
+/**
+ * Field kinds the preview marks: text (`text`, `text-list` items,
+ * `link-list` labels) and link / image targets (`url`, `image`,
+ * `link-list` hrefs, #918) — the latter usually land in `href` / `src`.
+ */
+const EDITABLE_KINDS = new Set(["text", "text-list", "link-list", "url", "image"]);
+
+/** Attributes whose marked value the editor can change (link target, image, alt text). */
+const MARKABLE_ATTRIBUTES = new Set(["href", "src", "alt"]);
+
+/** Field shape {@link wrapEditableValues} needs: name + kind. */
+export interface EditableFieldDef {
+  readonly name: string;
+  readonly kind?: string;
+}
+
+function editable(value: unknown): value is string {
+  return typeof value === "string" && value.trim().length > 0 && !value.includes("<");
+}
+
+function wrap(path: string, value: string): string {
+  return `${START}${path}${SEP}${value.replace(SENTINELS, "")}${END}`;
+}
+
+/**
+ * Wrap the editable text of a content instance's values in sentinels.
+ * Returns a new object; non-editable values pass through untouched.
+ *
+ * Paths: `<field>` for a `text` / `url` / `image` field, `<field>.<i>`
+ * for a `text-list` item, `<field>.<i>.label` / `<field>.<i>.href` for a
+ * `link-list` item's label / target.
+ *
+ * @example
+ * wrapEditableValues({ hero_title: "Hi" }, [{ name: "hero_title", kind: "text" }]);
+ * // → { hero_title: "\uE000hero_title\uE001Hi\uE002" }
+ */
+export function wrapEditableValues(
+  values: Readonly<Record<string, unknown>>,
+  fields: readonly EditableFieldDef[],
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...values };
+  for (const f of fields) {
+    const kind = f.kind ?? "text";
+    if (!EDITABLE_KINDS.has(kind)) continue;
+    const v = values[f.name];
+    if (kind === "text" || kind === "url" || kind === "image") {
+      if (editable(v)) out[f.name] = wrap(f.name, v);
+    } else if (kind === "text-list" && Array.isArray(v)) {
+      out[f.name] = v.map((item, i) => (editable(item) ? wrap(`${f.name}.${i}`, item) : item));
+    } else if (kind === "link-list" && Array.isArray(v)) {
+      out[f.name] = v.map((item, i) => {
+        if (typeof item !== "object" || item === null) return item;
+        const { label, href } = item as { label?: unknown; href?: unknown };
+        return {
+          ...item,
+          ...(editable(label) ? { label: wrap(`${f.name}.${i}.label`, label) } : {}),
+          ...(editable(href) ? { href: wrap(`${f.name}.${i}.href`, href) } : {}),
+        };
+      });
+    }
+  }
+  return out;
+}
+
+/** Comment-safe encoding: no `--`, no `>`, no whitespace. */
+function attr(value: string): string {
+  return encodeURIComponent(value).replace(/-/g, "%2D");
+}
+
+const RAW_TEXT_ELEMENTS = new Set(["script", "style", "title", "textarea"]);
+
+/** End index (exclusive) of the tag starting at `i`, honouring quoted attribute values. */
+function tagEnd(html: string, i: number): number {
+  let quote: string | null = null;
+  for (let j = i + 1; j < html.length; j += 1) {
+    const c = html[j];
+    if (quote) {
+      if (c === quote) quote = null;
+    } else if (c === '"' || c === "'") {
+      quote = c;
+    } else if (c === ">") {
+      return j + 1;
+    }
+  }
+  return html.length;
+}
+
+/**
+ * Turn sentinels in rendered module HTML into marker comments (text
+ * content) or drop them (everywhere else). See the file header.
+ *
+ * A tag whose `href` / `src` / `alt` value is exactly one marked value
+ * gets `data-caelo-fields="href=<path> …"` plus the placement
+ * (`data-caelo-placement`, `data-caelo-shared`), so the editor can offer
+ * "Edit link" / "Replace image" (#918). A value assembled from several
+ * parts (`href="/blog/{{slug}}"`) is not editable and is not marked.
+ *
+ * @param placement The placement key, `<blockName>#<position>`.
+ * @param sharedPages 0 for a placement with its own content; for a synced
+ *   (shared) one, the number of pages that show the same content.
+ */
+export function finalizeEditMarkers(html: string, placement: string, sharedPages: number): string {
+  if (!html.includes(START)) return html;
+  const open = (path: string) =>
+    `<!--${EDIT_MARKER_PREFIX} p=${attr(placement)} s=${sharedPages} f=${attr(path)}-->`;
+  const close = `<!--/${EDIT_MARKER_PREFIX}-->`;
+  let out = "";
+  let i = 0;
+  while (i < html.length) {
+    const c = html[i];
+    if (c === "<" && html.startsWith("<!--", i)) {
+      const end = html.indexOf("-->", i + 4);
+      const stop = end === -1 ? html.length : end + 3;
+      out += stripSentinels(html.slice(i, stop));
+      i = stop;
+      continue;
+    }
+    if (c === "<" && /[a-zA-Z/!?]/.test(html[i + 1] ?? "")) {
+      const stop = tagEnd(html, i);
+      const tag = html.slice(i, stop);
+      out += markTag(tag, placement, sharedPages);
+      i = stop;
+      const name = /^<([a-zA-Z][a-zA-Z0-9-]*)/.exec(tag)?.[1]?.toLowerCase();
+      if (name && RAW_TEXT_ELEMENTS.has(name) && !tag.endsWith("/>")) {
+        const closeAt = html.toLowerCase().indexOf(`</${name}`, i);
+        const rawStop = closeAt === -1 ? html.length : closeAt;
+        out += stripSentinels(html.slice(i, rawStop));
+        i = rawStop;
+      }
+      continue;
+    }
+    if (c === START) {
+      const sep = html.indexOf(SEP, i);
+      const end = html.indexOf(END, i);
+      if (sep !== -1 && end !== -1 && sep < end) {
+        out += `${open(html.slice(i + 1, sep))}${html.slice(sep + 1, end)}${close}`;
+        i = end + 1;
+        continue;
+      }
+    }
+    if (c !== SEP && c !== END && c !== START) out += c;
+    i += 1;
+  }
+  return out;
+}
+
+const ATTRIBUTE = /([^\s"'=<>/]+)(\s*=\s*)(?:"([^"]*)"|'([^']*)')/g;
+const WHOLE_VALUE = /^\uE000([^\uE001]*)\uE001[^\uE002]*\uE002$/;
+
+/** Strip sentinels from a tag and mark its editable attributes (see finalizeEditMarkers). */
+function markTag(tag: string, placement: string, sharedPages: number): string {
+  if (!tag.includes(START)) return tag;
+  const marks: string[] = [];
+  const cleaned = stripSentinels(
+    tag.replace(ATTRIBUTE, (m, name: string, eq: string, dq?: string, sq?: string) => {
+      const value = dq ?? sq ?? "";
+      if (!value.includes(START)) return m;
+      const whole = WHOLE_VALUE.exec(value);
+      const lower = name.toLowerCase();
+      if (whole?.[1] && MARKABLE_ATTRIBUTES.has(lower)) marks.push(`${lower}=${attr(whole[1])}`);
+      const quote = dq !== undefined ? '"' : "'";
+      return `${name}${eq}${quote}${stripSentinels(value)}${quote}`;
+    }),
+  );
+  if (marks.length === 0) return cleaned;
+  const extra = ` data-caelo-fields="${marks.join(" ")}" data-caelo-placement="${attr(placement)}" data-caelo-shared="${sharedPages}"`;
+  const at = cleaned.endsWith("/>") ? cleaned.length - 2 : cleaned.length - 1;
+  return `${cleaned.slice(0, at)}${extra}${cleaned.slice(at)}`;
+}
+
+/** Drop sentinels and the path they carry, keeping the wrapped value. */
+function stripSentinels(s: string): string {
+  return s.replace(/\uE000[^\uE001]*\uE001/g, "").replace(SENTINELS, "");
+}
+
+/** A parsed opening marker. */
+export interface EditMarker {
+  readonly blockName: string;
+  readonly position: number;
+  readonly synced: boolean;
+  readonly field: string;
+  readonly index?: number;
+}
+
+/**
+ * Parse an opening marker's comment text (without `<!--`/`-->`), or null.
+ * Mirrors what the preview runtime does in the browser.
+ */
+export function parseEditMarker(comment: string): EditMarker | null {
+  const m = /^caelo:f p=(\S+) s=([01]) f=(\S+)$/.exec(comment.trim());
+  if (!m?.[1] || !m[2] || !m[3]) return null;
+  const placement = decodeURIComponent(m[1]);
+  const hash = placement.lastIndexOf("#");
+  const position = Number(placement.slice(hash + 1));
+  if (hash <= 0 || !Number.isInteger(position)) return null;
+  const [field, index] = decodeURIComponent(m[3]).split(".");
+  if (!field) return null;
+  return {
+    blockName: placement.slice(0, hash),
+    position,
+    synced: m[2] === "1",
+    field,
+    ...(index !== undefined ? { index: Number(index) } : {}),
+  };
+}

package/src/index.ts

@@ -6,6 +6,7 @@ export * from "./ai-tools.js";
 export * from "./auth-forms.js";
 export * from "./auto-update.js";
 export * from "./base-css.js";
+export * from "./bug-intake.js";
 export * from "./build-page.js";
 export * from "./cap-failures.js";
 export * from "./cloud-shell-install.js";
@@ -16,6 +17,7 @@ export * from "./css-var-scan.js";
 export * from "./database-url.js";
 export * from "./design-draft-shell.js";
 export * from "./document-language.js";
+export * from "./edit-markers.js";
 export * from "./font-assets.js";
 export * from "./font-axis-policy.js";
 export * from "./font-usage.js";

package/src/version.ts

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