@caretcms/caretize 0.1.0

package/dist/parse.d.ts

@@ -0,0 +1,86 @@
+/**
+ * Thin wrapper over `@astrojs/compiler` for caretize: parse a `.astro` source,
+ * walk its tag nodes, and tag-then-verify an element.
+ *
+ * Minimal structural node types are declared locally rather than imported from
+ * the compiler's type barrels, so we stay decoupled from which entrypoint
+ * happens to re-export the AST interfaces. We only need a handful of fields.
+ */
+/** A single attribute on a tag node. `kind` distinguishes a static `quoted`
+ *  value from a dynamic one (`expression`, `template-literal`, `shorthand`,
+ *  `spread`) — the usage classifier needs that to know whether a value could
+ *  carry an editable field reference. */
+export interface TagAttr {
+    type: string;
+    /** Compiler attribute kind: quoted | expression | template-literal | shorthand | spread | empty. */
+    kind?: string;
+    name: string;
+    value: string;
+    /** Original source text (populated for some kinds, e.g. quoted/template). */
+    raw?: string;
+}
+/** A tag-like AST node (element / component / custom-element / fragment). */
+export interface TagNode {
+    type: "element" | "component" | "custom-element" | "fragment";
+    name: string;
+    attributes: TagAttr[];
+    children: AstroNode[];
+    position?: {
+        start: {
+            offset: number;
+        };
+        end?: {
+            offset: number;
+        };
+    };
+}
+export interface ContainerNode {
+    type: string;
+    children?: AstroNode[];
+    position?: {
+        start: {
+            offset: number;
+        };
+        end?: {
+            offset: number;
+        };
+    };
+}
+export type AstroNode = (TagNode | ContainerNode) & {
+    type: string;
+    children?: AstroNode[];
+};
+export declare function isTagNode(node: AstroNode): node is TagNode;
+/** Parse a `.astro` source into its AST root with byte positions populated. */
+export declare function parseAstro(source: string): Promise<AstroNode>;
+/**
+ * Depth-first walk over every tag-like node in document order. The callback
+ * receives the node and its chain of ancestor nodes (root-first), so callers
+ * can answer "am I inside an expression / iterator / a given scope?" without
+ * re-walking.
+ */
+export declare function walkTags(root: AstroNode, visit: (node: TagNode, ancestors: AstroNode[]) => void): void;
+export interface TagResult {
+    /** The spliced source (only meaningful when `ok` is true). */
+    output: string;
+    /** True when the attribute was inserted AND the result re-parses with the
+     *  attribute present on the intended element. */
+    ok: boolean;
+    /** Populated when `ok` is false, explaining why the splice was rejected. */
+    reason?: string;
+}
+/**
+ * Splice ` ${attribute}` into the opening tag of the element at `startOffset`,
+ * then re-parse the result to confirm (a) it still parses and (b) the intended
+ * element now carries the attribute. This converts a bad offset from "silent
+ * file corruption" into a rejected, recoverable result — the safety net the
+ * writer wraps every change in.
+ *
+ * `attribute` is the full attribute text WITHOUT a leading space, e.g.
+ * `data-caret="pages::home::headline"`.
+ */
+export declare function tagElementAndVerify(source: string, element: {
+    name: string;
+    startOffset: number;
+}, attribute: string, attrName?: string): Promise<TagResult>;
+//# sourceMappingURL=parse.d.ts.map

package/dist/parse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.d.ts","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAKH;;;yCAGyC;AACzC,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,oGAAoG;IACpG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,6EAA6E;IAC7E,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,6EAA6E;AAC7E,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,SAAS,GAAG,WAAW,GAAG,gBAAgB,GAAG,UAAU,CAAC;IAC9D,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,OAAO,EAAE,CAAC;IACtB,QAAQ,EAAE,SAAS,EAAE,CAAC;IACtB,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,GAAG,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CACpE;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;IACvB,QAAQ,CAAC,EAAE;QAAE,KAAK,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QAAC,GAAG,CAAC,EAAE;YAAE,MAAM,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;CACpE;AAED,MAAM,MAAM,SAAS,GAAG,CAAC,OAAO,GAAG,aAAa,CAAC,GAAG;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,SAAS,EAAE,CAAC;CACxB,CAAC;AAIF,wBAAgB,SAAS,CAAC,IAAI,EAAE,SAAS,GAAG,IAAI,IAAI,OAAO,CAE1D;AAED,+EAA+E;AAC/E,wBAAsB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAGnE;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CACtB,IAAI,EAAE,SAAS,EACf,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,KAAK,IAAI,GACrD,IAAI,CAaN;AAED,MAAM,WAAW,SAAS;IACxB,8DAA8D;IAC9D,MAAM,EAAE,MAAM,CAAC;IACf;qDACiD;IACjD,EAAE,EAAE,OAAO,CAAC;IACZ,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;GASG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EAC9C,SAAS,EAAE,MAAM,EACjB,QAAQ,SAAe,GACtB,OAAO,CAAC,SAAS,CAAC,CA0CpB"}

package/dist/parse.js

@@ -0,0 +1,92 @@
+/**
+ * Thin wrapper over `@astrojs/compiler` for caretize: parse a `.astro` source,
+ * walk its tag nodes, and tag-then-verify an element.
+ *
+ * Minimal structural node types are declared locally rather than imported from
+ * the compiler's type barrels, so we stay decoupled from which entrypoint
+ * happens to re-export the AST interfaces. We only need a handful of fields.
+ */
+import { parse } from "@astrojs/compiler";
+import { findOpenTagEnd, spliceAttribute } from "./splice.js";
+const TAG_TYPES = new Set(["element", "component", "custom-element", "fragment"]);
+export function isTagNode(node) {
+    return TAG_TYPES.has(node.type);
+}
+/** Parse a `.astro` source into its AST root with byte positions populated. */
+export async function parseAstro(source) {
+    const result = await parse(source, { position: true });
+    return result.ast;
+}
+/**
+ * Depth-first walk over every tag-like node in document order. The callback
+ * receives the node and its chain of ancestor nodes (root-first), so callers
+ * can answer "am I inside an expression / iterator / a given scope?" without
+ * re-walking.
+ */
+export function walkTags(root, visit) {
+    const stack = [];
+    const recurse = (node) => {
+        if (!node || typeof node !== "object")
+            return;
+        if (isTagNode(node))
+            visit(node, [...stack]);
+        const children = node.children;
+        if (Array.isArray(children)) {
+            stack.push(node);
+            for (const child of children)
+                recurse(child);
+            stack.pop();
+        }
+    };
+    recurse(root);
+}
+/**
+ * Splice ` ${attribute}` into the opening tag of the element at `startOffset`,
+ * then re-parse the result to confirm (a) it still parses and (b) the intended
+ * element now carries the attribute. This converts a bad offset from "silent
+ * file corruption" into a rejected, recoverable result — the safety net the
+ * writer wraps every change in.
+ *
+ * `attribute` is the full attribute text WITHOUT a leading space, e.g.
+ * `data-caret="pages::home::headline"`.
+ */
+export async function tagElementAndVerify(source, element, attribute, attrName = "data-caret") {
+    const buf = Buffer.from(source, "utf8");
+    const found = findOpenTagEnd(buf, element.startOffset);
+    if (!found) {
+        return { output: source, ok: false, reason: "could not locate end of opening tag" };
+    }
+    const spliced = spliceAttribute(buf, found.insertAt, ` ${attribute}`);
+    const output = spliced.toString("utf8");
+    // Re-parse and confirm the intended element (still at the same start offset,
+    // since we inserted strictly after the tag's `<`) now has the attribute.
+    let verifiedNode;
+    try {
+        const reAst = await parseAstro(output);
+        walkTags(reAst, (node) => {
+            if (verifiedNode)
+                return;
+            if (node.name === element.name &&
+                node.position?.start.offset === element.startOffset &&
+                node.attributes.some((a) => a.name === attrName)) {
+                verifiedNode = node;
+            }
+        });
+    }
+    catch (err) {
+        return {
+            output: source,
+            ok: false,
+            reason: `re-parse threw: ${err.message}`,
+        };
+    }
+    if (!verifiedNode) {
+        return {
+            output: source,
+            ok: false,
+            reason: "attribute not present on intended element after re-parse",
+        };
+    }
+    return { output, ok: true };
+}
+//# sourceMappingURL=parse.js.map

package/dist/parse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse.js","sourceRoot":"","sources":["../src/parse.ts"],"names":[],"mappings":"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"}

package/dist/plan.d.ts

@@ -0,0 +1,46 @@
+/**
+ * Planning: turn a `.astro` source + its path into a reviewable plan — the list
+ * of concrete `data-caret` bindings to propose, plus what was skipped and
+ * flagged. This is the integration point the CLI and the test harness drive.
+ *
+ * v1 emits self-contained full-triple bindings (`data-caret="collection::id::
+ * field"`) rather than scope-on-wrapper + field-only, because a full triple
+ * never depends on locating a common ancestor to host the scope — it is always
+ * valid wherever it lands. (Scope-on-wrapper is a later readability pass.)
+ */
+import { type AstroNode } from "./parse.js";
+import { type Candidate, type Confidence, type IteratorFlag, type Skipped } from "./detect.js";
+import { type Scope, type ScopeReason } from "./name.js";
+export interface PlannedTag {
+    candidate: Candidate;
+    collection: string;
+    id: string;
+    field: string;
+    /** Full binding value, `collection::id::field`. */
+    binding: string;
+    /** Attribute text without leading space, e.g. `data-caret="a::b::c"`. */
+    attribute: string;
+    startOffset: number;
+    confidence: Confidence;
+}
+export interface FilePlan {
+    relPath: string;
+    scope?: Scope;
+    /** Set when the whole file is skipped (dynamic route / unsupported location). */
+    scopeSkip?: ScopeReason;
+    tags: PlannedTag[];
+    skipped: Skipped[];
+    flags: IteratorFlag[];
+}
+export interface PlanOptions {
+    /** Minimum confidence to include as a proposed tag (default "high"). */
+    minConfidence?: Confidence;
+    /** Skip image candidates entirely (--no-images). */
+    noImages?: boolean;
+    /** Override the derived scope, e.g. { collection: "pages", id: "about" }. */
+    scope?: Scope;
+    /** Promote sanitizer-safe mixed-content blocks to data-caret-rich (--rich). */
+    rich?: boolean;
+}
+export declare function planFile(source: string, relPath: string, options?: PlanOptions, root?: AstroNode): Promise<FilePlan>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAwB,KAAK,SAAS,EAAgB,MAAM,YAAY,CAAC;AAChF,OAAO,EAEL,KAAK,SAAS,EACd,KAAK,UAAU,EACf,KAAK,YAAY,EACjB,KAAK,OAAO,EACb,MAAM,aAAa,CAAC;AACrB,OAAO,EAA6B,KAAK,KAAK,EAAE,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AAEpF,MAAM,WAAW,UAAU;IACzB,SAAS,EAAE,SAAS,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;IAChB,yEAAyE;IACzE,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,UAAU,CAAC;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,iFAAiF;IACjF,SAAS,CAAC,EAAE,WAAW,CAAC;IACxB,IAAI,EAAE,UAAU,EAAE,CAAC;IACnB,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,KAAK,EAAE,YAAY,EAAE,CAAC;CACvB;AAED,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,aAAa,CAAC,EAAE,UAAU,CAAC;IAC3B,oDAAoD;IACpD,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,KAAK,CAAC;IACd,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAoBD,wBAAsB,QAAQ,CAC5B,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,WAAgB,EACzB,IAAI,CAAC,EAAE,SAAS,GACf,OAAO,CAAC,QAAQ,CAAC,CA+CnB"}

package/dist/plan.js

@@ -0,0 +1,76 @@
+/**
+ * Planning: turn a `.astro` source + its path into a reviewable plan — the list
+ * of concrete `data-caret` bindings to propose, plus what was skipped and
+ * flagged. This is the integration point the CLI and the test harness drive.
+ *
+ * v1 emits self-contained full-triple bindings (`data-caret="collection::id::
+ * field"`) rather than scope-on-wrapper + field-only, because a full triple
+ * never depends on locating a common ancestor to host the scope — it is always
+ * valid wherever it lands. (Scope-on-wrapper is a later readability pass.)
+ */
+import { parseAstro, walkTags } from "./parse.js";
+import { detect, } from "./detect.js";
+import { assignFields, deriveScope } from "./name.js";
+const RANK = { high: 3, medium: 2, low: 1 };
+/** Field name carried by an existing data-caret value (full-triple or field-only). */
+function fieldOf(value) {
+    const parts = value.split("::");
+    return parts.length === 3 ? parts[2] : parts[0];
+}
+/** Collect field names already bound in the file, to seed unique naming. */
+function existingFields(root) {
+    const fields = [];
+    walkTags(root, (node) => {
+        const v = node.attributes.find((a) => a.name === "data-caret")?.value;
+        if (v)
+            fields.push(fieldOf(v));
+    });
+    return fields;
+}
+export async function planFile(source, relPath, options = {}, root) {
+    const minRank = RANK[options.minConfidence ?? "high"];
+    const ast = root ?? (await parseAstro(source));
+    const { candidates, skipped, flags } = detect(ast, walkTags, { rich: options.rich });
+    // Resolve scope (explicit override wins; otherwise derive from path).
+    let scope;
+    if (options.scope) {
+        scope = options.scope;
+    }
+    else {
+        const derived = deriveScope(relPath);
+        if ("skip" in derived) {
+            return { relPath, scopeSkip: derived.skip, tags: [], skipped, flags };
+        }
+        scope = derived.scope;
+    }
+    // Filter candidates by confidence + image policy, preserving document order.
+    // Rich candidates only exist when --rich was requested, so they're always
+    // accepted (the confidence floor doesn't gate the explicit opt-in).
+    const accepted = candidates.filter((c) => {
+        if (options.noImages && c.kind === "image")
+            return false;
+        if (c.rich)
+            return true;
+        return RANK[c.confidence] >= minRank;
+    });
+    const fields = assignFields(accepted, existingFields(ast));
+    const tags = accepted.map((candidate) => {
+        const field = fields.get(candidate);
+        const binding = `${scope.collection}::${scope.id}::${field}`;
+        const attribute = candidate.rich
+            ? `data-caret="${binding}" data-caret-rich`
+            : `data-caret="${binding}"`;
+        return {
+            candidate,
+            collection: scope.collection,
+            id: scope.id,
+            field,
+            binding,
+            attribute,
+            startOffset: candidate.startOffset,
+            confidence: candidate.confidence,
+        };
+    });
+    return { relPath, scope, tags, skipped, flags };
+}
+//# sourceMappingURL=plan.js.map

package/dist/plan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.js","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"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"}

package/dist/preflight.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Preflight: cheap sanity checks before scanning. Tagging works perfectly yet
+ * nothing is editable if CaretCMS isn't actually wired into the project, so we
+ * surface that up front. Git cleanliness is advisory — git is the real undo.
+ */
+export interface Preflight {
+    isAstroProject: boolean;
+    hasCaretCore: boolean;
+    /** caret() actually referenced in astro.config (not just installed). */
+    caretWired: boolean;
+    /** Output mode parsed from astro.config: "server" | "hybrid" | "static". */
+    outputMode: string;
+    gitRepo: boolean;
+    gitClean: boolean | null;
+    errors: string[];
+    warnings: string[];
+}
+export declare function preflight(rootDir: string): Preflight;
+//# sourceMappingURL=preflight.d.ts.map

package/dist/preflight.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.d.ts","sourceRoot":"","sources":["../src/preflight.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAMH,MAAM,WAAW,SAAS;IACxB,cAAc,EAAE,OAAO,CAAC;IACxB,YAAY,EAAE,OAAO,CAAC;IACtB,wEAAwE;IACxE,UAAU,EAAE,OAAO,CAAC;IACpB,4EAA4E;IAC5E,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,GAAG,IAAI,CAAC;IACzB,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAuCD,wBAAgB,SAAS,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAyDpD"}

package/dist/preflight.js

@@ -0,0 +1,95 @@
+/**
+ * Preflight: cheap sanity checks before scanning. Tagging works perfectly yet
+ * nothing is editable if CaretCMS isn't actually wired into the project, so we
+ * surface that up front. Git cleanliness is advisory — git is the real undo.
+ */
+import { existsSync, readFileSync, readdirSync } from "node:fs";
+import { resolve } from "node:path";
+import { execFileSync } from "node:child_process";
+function readPkg(rootDir) {
+    const p = resolve(rootDir, "package.json");
+    if (!existsSync(p))
+        return null;
+    try {
+        return JSON.parse(readFileSync(p, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function deps(pkg) {
+    if (!pkg)
+        return {};
+    return {
+        ...pkg.dependencies,
+        ...pkg.devDependencies,
+    };
+}
+function findAstroConfig(rootDir) {
+    try {
+        const name = readdirSync(rootDir).find((f) => /^astro\.config\.(m?[jt]s|cjs)$/.test(f));
+        return name ? resolve(rootDir, name) : null;
+    }
+    catch {
+        return null;
+    }
+}
+function readConfig(rootDir) {
+    const path = findAstroConfig(rootDir);
+    if (!path)
+        return null;
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch {
+        return null;
+    }
+}
+export function preflight(rootDir) {
+    const pkg = readPkg(rootDir);
+    const d = deps(pkg);
+    const config = readConfig(rootDir);
+    const isAstroProject = "astro" in d || config !== null;
+    const hasCaretCore = "@caretcms/core" in d;
+    // caret() is wired only if the config actually references it (imports the
+    // package or calls caret(...) in the integrations array).
+    const caretWired = config !== null && (/\bcaret\s*\(/.test(config) || /@caretcms\/core/.test(config));
+    // Output mode (Astro defaults to "static" when unset). "hybrid" was removed
+    // in Astro 5 — a config still carrying it is treated as unknown/static so
+    // the warning below points the user at a mode that exists.
+    const outputMatch = config?.match(/output\s*:\s*["'](server|static)["']/);
+    const outputMode = outputMatch ? outputMatch[1] : "static";
+    let gitRepo = false;
+    let gitClean = null;
+    try {
+        const out = execFileSync("git", ["status", "--porcelain"], {
+            cwd: rootDir,
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+        });
+        gitRepo = true;
+        gitClean = out.trim() === "";
+    }
+    catch {
+        gitRepo = false;
+    }
+    const errors = [];
+    const warnings = [];
+    if (!isAstroProject) {
+        errors.push("This does not look like an Astro project (no astro dependency or astro.config).");
+    }
+    if (!hasCaretCore) {
+        warnings.push("@caretcms/core is not installed — tags will be added, but nothing is editable until CaretCMS is set up.");
+    }
+    else if (!caretWired) {
+        warnings.push("@caretcms/core is installed but caret() is not in astro.config — tags will be inert until you add it to integrations.");
+    }
+    if (hasCaretCore && outputMode === "static") {
+        warnings.push(`output is "static" — embedded inline editing needs output: "server" plus an SSR adapter (e.g. @astrojs/node).`);
+    }
+    if (gitRepo && gitClean === false) {
+        warnings.push("Working tree has uncommitted changes — commit first so you can `git checkout` to undo.");
+    }
+    return { isAstroProject, hasCaretCore, caretWired, outputMode, gitRepo, gitClean, errors, warnings };
+}
+//# sourceMappingURL=preflight.js.map

package/dist/preflight.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"preflight.js","sourceRoot":"","sources":["../src/preflight.ts"],"names":[],"mappings":"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"}

package/dist/prop-hoist.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Tier-4 prop hoisting — a guarded REWRITE (not pure insertion).
+ *
+ * The most common pattern caretize couldn't touch is a static string passed to a
+ * shared component as a prop:
+ *
+ *   <PageHero title="ABOUT US" description="Since 2010 …" />
+ *
+ * The text never appears as a tag-able text leaf (it's an attribute on a
+ * component), and `data-caret` can't ride a component boundary. The fix is to
+ * hoist each literal into an `editable()` frontmatter const and reference it:
+ *
+ *   const pageHeroTitle = await editable("pages::about::title", "ABOUT US");
+ *   …
+ *   <PageHero title={pageHeroTitle} description={pageHeroDesc} />
+ *
+ * Unlike the other tiers this DELETES bytes (the attribute literal), so it can't
+ * use the subsequence gate. Instead it is verified by an INVERSE check: undo
+ * every edit (swap the reference back to the literal, strip the const lines) and
+ * assert the result is byte-identical to the input — proving the only changes
+ * were the intended hoists. A hand-off is rewritten only on positive proof the
+ * child renders the prop as text (reusing the Tier-2 cross-file verifier), and
+ * only when the exact `prop="value"` token occurs exactly once (unambiguous).
+ */
+import { type AstroNode } from "./parse.js";
+import { type FileReader } from "./props.js";
+/** One prop literal to hoist, with the exact tokens needed to apply + invert. */
+export interface HoistProp {
+    propName: string;
+    literalValue: string;
+    key: string;
+    constName: string;
+    isRich: boolean;
+    /** Exact source token being replaced, e.g. `title="ABOUT US"`. */
+    attrBefore: string;
+    /** Replacement token, e.g. `title={pageHeroTitle}`. */
+    attrAfter: string;
+    /** Exact text inserted into frontmatter (leading newline included). */
+    constInsert: string;
+}
+export interface PropHoistTarget {
+    componentName: string;
+    props: HoistProp[];
+}
+export interface HoistResult {
+    output: string;
+    ok: boolean;
+    reason?: string;
+    propsRewritten: number;
+    constsDeclared: string[];
+    /** True when this transform added the `editable` import. */
+    addedImport: boolean;
+}
+/**
+ * Detect prop-hoist targets: component invocations with static string props
+ * whose child provably renders them as text. `readFile` resolves sibling files.
+ */
+export declare function detectPropHoistTargets(source: string, relPath: string, readFile: FileReader, root?: AstroNode): Promise<PropHoistTarget[]>;
+/** Apply the hoist rewrite. Self-locating: finds each `attrBefore` token by content. */
+export declare function hoistPropLiterals(source: string, targets: PropHoistTarget[]): HoistResult;
+/**
+ * Inverse gate: undo every hoist edit on `output` and assert the result is
+ * byte-identical to `intermediate` (the source the hoist was applied to). This
+ * proves the ONLY changes were the intended hoists — no collateral edits.
+ */
+export declare function verifyHoistResult(intermediate: string, output: string, targets: PropHoistTarget[], addedImport: boolean): boolean;
+//# sourceMappingURL=prop-hoist.d.ts.map

package/dist/prop-hoist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prop-hoist.d.ts","sourceRoot":"","sources":["../src/prop-hoist.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,EAAwB,KAAK,SAAS,EAAgB,MAAM,YAAY,CAAC;AAGhF,OAAO,EAAiB,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAK5D,iFAAiF;AACjF,MAAM,WAAW,SAAS;IACxB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,MAAM,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,OAAO,CAAC;IAChB,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAC;IACnB,uDAAuD;IACvD,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,KAAK,EAAE,SAAS,EAAE,CAAC;CACpB;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,cAAc,EAAE,MAAM,CAAC;IACvB,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,4DAA4D;IAC5D,WAAW,EAAE,OAAO,CAAC;CACtB;AAuDD;;;GAGG;AACH,wBAAsB,sBAAsB,CAC1C,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,QAAQ,EAAE,UAAU,EACpB,IAAI,CAAC,EAAE,SAAS,GACf,OAAO,CAAC,eAAe,EAAE,CAAC,CAyF5B;AAED,wFAAwF;AACxF,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,WAAW,CAsCzF;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,YAAY,EAAE,MAAM,EACpB,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,eAAe,EAAE,EAC1B,WAAW,EAAE,OAAO,GACnB,OAAO,CAYT"}