@growth-labs/seo 0.1.5 → 0.2.0

package/dist/utils/aeo-twin-emitter.d.ts

@@ -0,0 +1,79 @@
+import type { ContentItem } from '../types.js';
+export type RenderBody = (item: ContentItem) => string | Promise<string>;
+export interface EmitAeoTwinsOptions {
+    items: ContentItem[];
+    publisherName: string;
+    schemaType: string;
+    /** Resolver that returns the article body in markdown. Required; the emitter
+     *  can't synthesize content. Consumers typically produce this from their CMS. */
+    renderBody: RenderBody;
+    /** Map item.url → primary twin URL. Default: append '.md'. */
+    twinUrl?: (articleUrl: string) => string;
+    /** Predicate applied after the default members filter. Default: always true. */
+    include?: (item: ContentItem) => boolean;
+    /** Emit a summary twin alongside the primary. Default true. */
+    summaryTwin?: boolean;
+    /** Wrap semantic sections in <!-- aeo:section --> markers. Default true. */
+    ragChunkMarkers?: boolean;
+    /** Stale-hash metadata mode. */
+    stalenessCheck?: 'content-hash' | 'dateModified' | 'none';
+    /** Called when the summary generator falls back to tier 4. Used for build telemetry. */
+    onSummaryMinimalFallback?: (item: ContentItem) => void;
+}
+export interface EmittedTwin {
+    /** URL path this file will be served at (used by the writer to derive the filesystem path). */
+    urlPath: string;
+    /** Full URL (for frontmatter). */
+    url: string;
+    /** File body. */
+    content: string;
+    /** Content-type for HTTP response headers when this file is served. */
+    contentType: string;
+    /** If this emission is the primary twin for an item, the item is populated. */
+    item?: ContentItem;
+    /** If this emission is a summary twin, the corresponding primary URL. */
+    primaryUrl?: string;
+    /** Primary twins carry a stable content hash for staleness validation; absent on summaries. */
+    contentHash?: string;
+}
+export interface EmitAeoTwinsResult {
+    twins: EmittedTwin[];
+    /** Map of item.url → contentHash. Persist to disk for staleness validation. */
+    contentHashes: Map<string, string>;
+    /** Number of items filtered out (either by access rule or consumer predicate). */
+    skipped: number;
+}
+/**
+ * Compute all twin files for a given contentProvider output, without touching
+ * the filesystem. Callers (index.ts at astro:build:done time) write the returned
+ * twins to disk and record content hashes for later staleness validation.
+ *
+ * Filtering:
+ *   - Members items excluded unconditionally (via forMarkdownTwin).
+ *   - Consumer-supplied `include` predicate applied after the access filter.
+ *
+ * For each surviving item we emit:
+ *   - Primary twin at twinUrl(item.url).
+ *   - Summary twin at <primary>.summary.md (when summaryTwin: true).
+ *
+ * Aliases (spec twinAliases) are NOT emitted as static files in v7 — they're
+ * middleware-only redirects. Static-mode twins live at the primary URL only.
+ */
+export declare function emitAeoTwins(options: EmitAeoTwinsOptions): Promise<EmitAeoTwinsResult>;
+/**
+ * Default twinUrl: strip trailing slashes and append '.md'.
+ * `/article/midway/` -> `/article/midway.md`
+ * `/article/midway`  -> `/article/midway.md`
+ */
+declare function defaultTwinUrl(articleUrl: string): string;
+/**
+ * Extract the URL-path portion of an absolute or relative URL.
+ * Used by the caller to derive the filesystem write path under dist/client/.
+ */
+declare function urlPath(url: string): string;
+export declare const _internals: {
+    defaultTwinUrl: typeof defaultTwinUrl;
+    urlPath: typeof urlPath;
+};
+export {};
+//# sourceMappingURL=aeo-twin-emitter.d.ts.map

package/dist/utils/aeo-twin-emitter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"aeo-twin-emitter.d.ts","sourceRoot":"","sources":["../../src/utils/aeo-twin-emitter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAQ9C,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,WAAW,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;AAExE,MAAM,WAAW,mBAAmB;IACnC,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,aAAa,EAAE,MAAM,CAAA;IACrB,UAAU,EAAE,MAAM,CAAA;IAClB;qFACiF;IACjF,UAAU,EAAE,UAAU,CAAA;IACtB,8DAA8D;IAC9D,OAAO,CAAC,EAAE,CAAC,UAAU,EAAE,MAAM,KAAK,MAAM,CAAA;IACxC,gFAAgF;IAChF,OAAO,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,OAAO,CAAA;IACxC,+DAA+D;IAC/D,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,gCAAgC;IAChC,cAAc,CAAC,EAAE,cAAc,GAAG,cAAc,GAAG,MAAM,CAAA;IACzD,wFAAwF;IACxF,wBAAwB,CAAC,EAAE,CAAC,IAAI,EAAE,WAAW,KAAK,IAAI,CAAA;CACtD;AAED,MAAM,WAAW,WAAW;IAC3B,+FAA+F;IAC/F,OAAO,EAAE,MAAM,CAAA;IACf,kCAAkC;IAClC,GAAG,EAAE,MAAM,CAAA;IACX,iBAAiB;IACjB,OAAO,EAAE,MAAM,CAAA;IACf,uEAAuE;IACvE,WAAW,EAAE,MAAM,CAAA;IACnB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,WAAW,CAAA;IAClB,yEAAyE;IACzE,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,+FAA+F;IAC/F,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED,MAAM,WAAW,kBAAkB;IAClC,KAAK,EAAE,WAAW,EAAE,CAAA;IACpB,+EAA+E;IAC/E,aAAa,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;IAClC,kFAAkF;IAClF,OAAO,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,YAAY,CAAC,OAAO,EAAE,mBAAmB,GAAG,OAAO,CAAC,kBAAkB,CAAC,CAuE5F;AAID;;;;GAIG;AACH,iBAAS,cAAc,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAElD;AAED;;;GAGG;AACH,iBAAS,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAOpC;AAED,eAAO,MAAM,UAAU;;;CAGtB,CAAA"}

package/dist/utils/aeo-twin-emitter.js

@@ -0,0 +1,99 @@
+import { generateAeoMarkdown } from './aeo.js';
+import { generateSummaryTwin } from './aeo-summary.js';
+import { forMarkdownTwin } from './content-filter.js';
+import { computeContentHash } from './staleness.js';
+/**
+ * Compute all twin files for a given contentProvider output, without touching
+ * the filesystem. Callers (index.ts at astro:build:done time) write the returned
+ * twins to disk and record content hashes for later staleness validation.
+ *
+ * Filtering:
+ *   - Members items excluded unconditionally (via forMarkdownTwin).
+ *   - Consumer-supplied `include` predicate applied after the access filter.
+ *
+ * For each surviving item we emit:
+ *   - Primary twin at twinUrl(item.url).
+ *   - Summary twin at <primary>.summary.md (when summaryTwin: true).
+ *
+ * Aliases (spec twinAliases) are NOT emitted as static files in v7 — they're
+ * middleware-only redirects. Static-mode twins live at the primary URL only.
+ */
+export async function emitAeoTwins(options) {
+    const { items, publisherName, schemaType, renderBody, twinUrl = defaultTwinUrl, include = () => true, summaryTwin = true, ragChunkMarkers = true, stalenessCheck = 'content-hash', onSummaryMinimalFallback, } = options;
+    const filtered = forMarkdownTwin(items).filter(include);
+    const skipped = items.length - filtered.length;
+    const twins = [];
+    const contentHashes = new Map();
+    for (const item of filtered) {
+        const primaryUrl = twinUrl(item.url);
+        const primaryUrlPath = urlPath(primaryUrl);
+        const body = await renderBody(item);
+        const contentHash = stalenessCheck === 'content-hash' ? await computeContentHash(item, body) : undefined;
+        if (contentHash)
+            contentHashes.set(item.url, contentHash);
+        const summaryUrl = summaryTwin ? `${primaryUrl}.summary.md` : undefined;
+        const aeoOpts = {
+            publisherName,
+            schemaType,
+            content: body,
+            ragChunkMarkers,
+            canonical: item.url,
+            twinUrl: primaryUrl,
+            summaryUrl,
+            contentHash,
+        };
+        const primaryContent = generateAeoMarkdown(item, aeoOpts);
+        twins.push({
+            urlPath: primaryUrlPath,
+            url: primaryUrl,
+            content: primaryContent,
+            contentType: 'text/markdown; charset=utf-8',
+            item,
+            contentHash,
+        });
+        if (summaryTwin && summaryUrl) {
+            const summary = generateSummaryTwin(item, {
+                publisherName,
+                schemaType,
+                content: body,
+                fullUrl: primaryUrl,
+                onMinimalFallback: onSummaryMinimalFallback,
+            });
+            twins.push({
+                urlPath: urlPath(summaryUrl),
+                url: summaryUrl,
+                content: summary.markdown,
+                contentType: 'text/markdown; charset=utf-8',
+                primaryUrl,
+            });
+        }
+    }
+    return { twins, contentHashes, skipped };
+}
+// ─── Defaults ───
+/**
+ * Default twinUrl: strip trailing slashes and append '.md'.
+ * `/article/midway/` -> `/article/midway.md`
+ * `/article/midway`  -> `/article/midway.md`
+ */
+function defaultTwinUrl(articleUrl) {
+    return `${articleUrl.replace(/\/+$/, '')}.md`;
+}
+/**
+ * Extract the URL-path portion of an absolute or relative URL.
+ * Used by the caller to derive the filesystem write path under dist/client/.
+ */
+function urlPath(url) {
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        // Relative URL — assume it's already a path.
+        return url.startsWith('/') ? url : `/${url}`;
+    }
+}
+export const _internals = {
+    defaultTwinUrl,
+    urlPath,
+};
+//# sourceMappingURL=aeo-twin-emitter.js.map

package/dist/utils/aeo-twin-emitter.js.map

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

package/dist/utils/aeo.d.ts

@@ -1,16 +1,66 @@
+import type { ContentItem } from '../types.js';
+export interface GenerateAeoMarkdownOptions {
+    /** Publisher organization name for the frontmatter `publisher` field. */
+    publisherName: string;
+    /** Schema.org type (e.g. 'Article', 'NewsArticle'). */
+    schemaType: string;
+    /** Rendered article body in clean markdown (no HTML chrome). */
+    content: string;
+    /** If true, wraps semantic sections in `<!-- aeo:section start/end -->` comments. */
+    ragChunkMarkers?: boolean;
+    /** Canonical HTML URL to reference from the twin frontmatter. Defaults to item.url. */
+    canonical?: string;
+    /** The primary twin URL (what this file will be served at). Stored in frontmatter as `url`. */
+    twinUrl?: string;
+    /** Optional summary-twin URL to cross-link from the full twin frontmatter. */
+    summaryUrl?: string;
+    /** Pre-computed SHA-256 content hash for staleness validation. */
+    contentHash?: string;
+}
 /**
- * AEO (Answer Engine Optimization) utilities
- * Generates AI-friendly markdown with YAML frontmatter
+ * Cheap token count estimate: 1 token ≈ 4 characters. Used for the `x-markdown-tokens`
+ * response header and the `tokens` frontmatter field.
  */
 export declare function estimateTokenCount(text: string): number;
-export declare function generateAeoMarkdown(item: {
-    url: string;
-    title: string;
-    description?: string;
-    datePublished?: string;
-    dateModified?: string;
-    authors?: Array<{
-        name: string;
-    }>;
-}, content: string, schemaType: string, publisherName: string): string;
+/**
+ * Generate an AEO markdown twin for a ContentItem.
+ *
+ * Produces: frontmatter (YAML) + body. When `ragChunkMarkers: true`, inserts
+ * `<!-- aeo:section start="<slug>" -->` / `<!-- aeo:section end="<slug>" -->` pairs
+ * around semantic sections (identified by `## ` headings) to guide RAG retrievers
+ * toward boundaries we control.
+ *
+ * Sanitization:
+ *   - Slugs are forced to `[a-z0-9-]{1,64}`; empty results fall back to `section-N`.
+ *   - Any author-supplied `<!--` / `-->` in the body is escaped (`&lt;!--` / `--&gt;`)
+ *     before wrapping, so forged markers can't close real ones.
+ */
+export declare function generateAeoMarkdown(item: ContentItem, options: GenerateAeoMarkdownOptions): string;
+/**
+ * Emit a value safely for YAML. Unquoted when possible; quoted (with escapes) when
+ * the value would otherwise parse ambiguously.
+ */
+declare function yamlValue(v: string): string;
+/**
+ * Wrap each `##` section in `<!-- aeo:section start="..." -->` / `<!-- end -->`.
+ * Content before the first `##` is wrapped as `lede`; content after the last `##`
+ * terminates with an end marker for that section.
+ */
+declare function wrapSectionMarkers(body: string): string;
+/** Strict slug sanitization — [a-z0-9-]{1,64}, no leading/trailing/repeated dashes. */
+declare function sanitizeSlug(text: string): string;
+declare function uniqueSlug(base: string, used: Set<string>): string;
+/**
+ * Escape any author-supplied `<!--` / `-->` in the body so forged markers can't
+ * close real ones. Applied BEFORE wrapping (spec "Marker sanitization").
+ */
+declare function escapeHtmlComments(body: string): string;
+export declare const _internals: {
+    sanitizeSlug: typeof sanitizeSlug;
+    uniqueSlug: typeof uniqueSlug;
+    escapeHtmlComments: typeof escapeHtmlComments;
+    wrapSectionMarkers: typeof wrapSectionMarkers;
+    yamlValue: typeof yamlValue;
+};
+export {};
 //# sourceMappingURL=aeo.d.ts.map

package/dist/utils/aeo.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"aeo.d.ts","sourceRoot":"","sources":["../../src/utils/aeo.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED,wBAAgB,mBAAmB,CAClC,IAAI,EAAE;IACL,GAAG,EAAE,MAAM,CAAA;IACX,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,YAAY,CAAC,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAA;CACjC,EACD,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,MAAM,EAClB,aAAa,EAAE,MAAM,GACnB,MAAM,CA8BR"}
+{"version":3,"file":"aeo.d.ts","sourceRoot":"","sources":["../../src/utils/aeo.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAI9C,MAAM,WAAW,0BAA0B;IAC1C,yEAAyE;IACzE,aAAa,EAAE,MAAM,CAAA;IACrB,uDAAuD;IACvD,UAAU,EAAE,MAAM,CAAA;IAClB,gEAAgE;IAChE,OAAO,EAAE,MAAM,CAAA;IACf,qFAAqF;IACrF,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,uFAAuF;IACvF,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,+FAA+F;IAC/F,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,8EAA8E;IAC9E,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,kEAAkE;IAClE,WAAW,CAAC,EAAE,MAAM,CAAA;CACpB;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAClC,IAAI,EAAE,WAAW,EACjB,OAAO,EAAE,0BAA0B,GACjC,MAAM,CAKR;AAqED;;;GAGG;AACH,iBAAS,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAUpC;AAID;;;;GAIG;AACH,iBAAS,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CA0ChD;AAED,uFAAuF;AACvF,iBAAS,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAQ1C;AAED,iBAAS,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,MAAM,CAK3D;AAED;;;GAGG;AACH,iBAAS,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAEhD;AAID,eAAO,MAAM,UAAU;;;;;;CAMtB,CAAA"}

package/dist/utils/aeo.js

@@ -1,38 +1,199 @@
 /**
- * AEO (Answer Engine Optimization) utilities
- * Generates AI-friendly markdown with YAML frontmatter
+ * Cheap token count estimate: 1 token ≈ 4 characters. Used for the `x-markdown-tokens`
+ * response header and the `tokens` frontmatter field.
  */
 export function estimateTokenCount(text) {
     return Math.ceil(text.length / 4);
 }
-export function generateAeoMarkdown(item, content, schemaType, publisherName) {
-    const frontmatter = {
-        title: item.title,
-        url: item.url,
-        schemaType,
-        publisher: publisherName,
-    };
+/**
+ * Generate an AEO markdown twin for a ContentItem.
+ *
+ * Produces: frontmatter (YAML) + body. When `ragChunkMarkers: true`, inserts
+ * `<!-- aeo:section start="<slug>" -->` / `<!-- aeo:section end="<slug>" -->` pairs
+ * around semantic sections (identified by `## ` headings) to guide RAG retrievers
+ * toward boundaries we control.
+ *
+ * Sanitization:
+ *   - Slugs are forced to `[a-z0-9-]{1,64}`; empty results fall back to `section-N`.
+ *   - Any author-supplied `<!--` / `-->` in the body is escaped (`&lt;!--` / `--&gt;`)
+ *     before wrapping, so forged markers can't close real ones.
+ */
+export function generateAeoMarkdown(item, options) {
+    const frontmatter = buildFrontmatter(item, options);
+    const safeBody = escapeHtmlComments(options.content);
+    const body = options.ragChunkMarkers ? wrapSectionMarkers(safeBody) : safeBody;
+    return `---\n${frontmatter}\n---\n\n${body}`;
+}
+// ─── Frontmatter ───
+function buildFrontmatter(item, options) {
+    const canonical = options.canonical ?? item.url;
+    const twinUrl = options.twinUrl ?? item.url;
+    const firstImage = Array.isArray(item.image) ? item.image[0] : item.image;
+    const authorEntries = (item.authors ?? []).map((a) => {
+        const o = { name: a.name };
+        if (a.url)
+            o.url = a.url;
+        if (a.jobTitle)
+            o.jobTitle = a.jobTitle;
+        if (a.knowsAbout?.length)
+            o.knowsAbout = a.knowsAbout;
+        if (a.sameAs?.length)
+            o.sameAs = a.sameAs;
+        return o;
+    });
+    const alternateLanguages = (item.alternateLocales ?? []).map((l) => ({
+        lang: l.lang,
+        url: l.url,
+    }));
+    const lines = [];
+    lines.push(yamlScalar('title', item.title));
     if (item.description)
-        frontmatter.description = item.description;
+        lines.push(yamlScalar('description', item.description));
+    lines.push(yamlScalar('url', twinUrl));
+    lines.push(yamlScalar('canonical', canonical));
     if (item.datePublished)
-        frontmatter.datePublished = item.datePublished;
+        lines.push(yamlScalar('datePublished', item.datePublished));
     if (item.dateModified)
-        frontmatter.dateModified = item.dateModified;
-    if (item.authors?.length) {
-        frontmatter.authors = item.authors.map((a) => a.name);
+        lines.push(yamlScalar('dateModified', item.dateModified));
+    if (authorEntries.length) {
+        lines.push('author:');
+        for (const a of authorEntries) {
+            lines.push(`  - name: ${yamlValue(a.name)}`);
+            if (a.url)
+                lines.push(`    url: ${yamlValue(a.url)}`);
+            if (a.jobTitle)
+                lines.push(`    jobTitle: ${yamlValue(a.jobTitle)}`);
+            if (a.knowsAbout) {
+                lines.push('    knowsAbout:');
+                for (const k of a.knowsAbout)
+                    lines.push(`      - ${yamlValue(k)}`);
+            }
+            if (a.sameAs) {
+                lines.push('    sameAs:');
+                for (const s of a.sameAs)
+                    lines.push(`      - ${yamlValue(s)}`);
+            }
+        }
     }
-    const yamlLines = Object.entries(frontmatter).map(([key, value]) => {
-        if (Array.isArray(value)) {
-            return `${key}:\n${value.map((v) => `  - ${v}`).join('\n')}`;
+    lines.push(yamlScalar('publisher', options.publisherName));
+    if (firstImage)
+        lines.push(yamlScalar('image', firstImage));
+    lines.push(yamlScalar('type', options.schemaType));
+    if (item.locale)
+        lines.push(yamlScalar('language', item.locale));
+    if (item.audio)
+        lines.push(yamlScalar('audio', item.audio.url));
+    if (alternateLanguages.length) {
+        lines.push('alternateLanguages:');
+        for (const l of alternateLanguages) {
+            lines.push(`  - lang: ${yamlValue(l.lang)}`);
+            lines.push(`    url: ${yamlValue(l.url)}`);
         }
-        // Wrap in quotes only when truly needed for YAML validity
-        // URLs with :// are fine unquoted; dates with colons need quoting if they'd be ambiguous
-        const str = String(value);
-        const isUrl = /^https?:\/\//.test(str);
-        const isDate = /^\d{4}-\d{2}-\d{2}/.test(str);
-        const hasYamlSpecial = /[#[\]{},&*?|>'"!%@`]/.test(str) || (!isUrl && !isDate && str.includes(':'));
-        return `${key}: ${hasYamlSpecial ? `"${str.replace(/"/g, '\\"')}"` : str}`;
-    });
-    return `---\n${yamlLines.join('\n')}\n---\n\n${content}`;
+    }
+    if (options.contentHash)
+        lines.push(yamlScalar('contentHash', options.contentHash));
+    const tokens = estimateTokenCount(options.content);
+    lines.push(`tokens: ${tokens}`);
+    if (options.summaryUrl)
+        lines.push(yamlScalar('summaryUrl', options.summaryUrl));
+    return lines.join('\n');
+}
+function yamlScalar(key, value) {
+    return `${key}: ${yamlValue(value)}`;
+}
+/**
+ * Emit a value safely for YAML. Unquoted when possible; quoted (with escapes) when
+ * the value would otherwise parse ambiguously.
+ */
+function yamlValue(v) {
+    // Whitelisted forms that can be emitted unquoted even though they contain `:`.
+    const isUrl = /^https?:\/\//.test(v);
+    const isDate = /^\d{4}-\d{2}-\d{2}/.test(v);
+    // Always quote if contains chars with YAML special meaning (excluding `:` which
+    // is handled separately below), or if starts with a character that could be misread.
+    const needsQuotes = /^[\s-]/.test(v) || /[#{}[\],&*?|>!%@`'"\n\r]/.test(v) || (v.includes(':') && !isUrl && !isDate);
+    if (!needsQuotes)
+        return v;
+    return `"${v.replace(/\\/g, '\\\\').replace(/"/g, '\\"').replace(/\n/g, '\\n')}"`;
+}
+// ─── RAG chunk markers ───
+/**
+ * Wrap each `##` section in `<!-- aeo:section start="..." -->` / `<!-- end -->`.
+ * Content before the first `##` is wrapped as `lede`; content after the last `##`
+ * terminates with an end marker for that section.
+ */
+function wrapSectionMarkers(body) {
+    const lines = body.split('\n');
+    const out = [];
+    let currentSlug = null;
+    const usedSlugs = new Set();
+    let ordinal = 0;
+    let sawContent = false;
+    // Open with `lede` if we hit body content before any heading.
+    const openSection = (slug) => {
+        out.push(`<!-- aeo:section start="${slug}" -->`);
+        currentSlug = slug;
+    };
+    const closeSection = () => {
+        if (currentSlug) {
+            out.push(`<!-- aeo:section end="${currentSlug}" -->`);
+            currentSlug = null;
+        }
+    };
+    for (const line of lines) {
+        const headingMatch = /^##\s+(.+)$/.exec(line);
+        if (headingMatch) {
+            closeSection();
+            ordinal++;
+            const slug = sanitizeSlug(headingMatch[1]) || `section-${ordinal}`;
+            const unique = uniqueSlug(slug, usedSlugs);
+            usedSlugs.add(unique);
+            openSection(unique);
+            out.push(line);
+            sawContent = true;
+            continue;
+        }
+        if (!currentSlug && line.trim() !== '' && !sawContent) {
+            openSection('lede');
+            usedSlugs.add('lede');
+            sawContent = true;
+        }
+        out.push(line);
+    }
+    closeSection();
+    return out.join('\n');
+}
+/** Strict slug sanitization — [a-z0-9-]{1,64}, no leading/trailing/repeated dashes. */
+function sanitizeSlug(text) {
+    const lowered = text.toLowerCase();
+    const ascii = lowered.normalize('NFKD').replace(/[\u0300-\u036f]/g, '');
+    const cleaned = ascii
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 64);
+    return cleaned;
+}
+function uniqueSlug(base, used) {
+    if (!used.has(base))
+        return base;
+    let n = 2;
+    while (used.has(`${base}-${n}`))
+        n++;
+    return `${base}-${n}`;
+}
+/**
+ * Escape any author-supplied `<!--` / `-->` in the body so forged markers can't
+ * close real ones. Applied BEFORE wrapping (spec "Marker sanitization").
+ */
+function escapeHtmlComments(body) {
+    return body.replace(/<!--/g, '&lt;!--').replace(/-->/g, '--&gt;');
 }
+// ─── Exports for testing ───
+export const _internals = {
+    sanitizeSlug,
+    uniqueSlug,
+    escapeHtmlComments,
+    wrapSectionMarkers,
+    yamlValue,
+};
 //# sourceMappingURL=aeo.js.map

package/dist/utils/aeo.js.map

@@ -1 +1 @@
-{"version":3,"file":"aeo.js","sourceRoot":"","sources":["../../src/utils/aeo.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC9C,OAAO,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,GAAG,CAAC,CAAC,CAAA;AAClC,CAAC;AAED,MAAM,UAAU,mBAAmB,CAClC,IAOC,EACD,OAAe,EACf,UAAkB,EAClB,aAAqB;IAErB,MAAM,WAAW,GAAsC;QACtD,KAAK,EAAE,IAAI,CAAC,KAAK;QACjB,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,UAAU;QACV,SAAS,EAAE,aAAa;KACxB,CAAA;IAED,IAAI,IAAI,CAAC,WAAW;QAAE,WAAW,CAAC,WAAW,GAAG,IAAI,CAAC,WAAW,CAAA;IAChE,IAAI,IAAI,CAAC,aAAa;QAAE,WAAW,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAA;IACtE,IAAI,IAAI,CAAC,YAAY;QAAE,WAAW,CAAC,YAAY,GAAG,IAAI,CAAC,YAAY,CAAA;IACnE,IAAI,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,CAAC;QAC1B,WAAW,CAAC,OAAO,GAAG,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAA;IACtD,CAAC;IAED,MAAM,SAAS,GAAG,MAAM,CAAC,OAAO,CAAC,WAAW,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,KAAK,CAAC,EAAE,EAAE;QAClE,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;YAC1B,OAAO,GAAG,GAAG,MAAM,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAA;QAC7D,CAAC;QACD,0DAA0D;QAC1D,yFAAyF;QACzF,MAAM,GAAG,GAAG,MAAM,CAAC,KAAK,CAAC,CAAA;QACzB,MAAM,KAAK,GAAG,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QACtC,MAAM,MAAM,GAAG,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAA;QAC7C,MAAM,cAAc,GACnB,sBAAsB,CAAC,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,KAAK,IAAI,CAAC,MAAM,IAAI,GAAG,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAA;QAC7E,OAAO,GAAG,GAAG,KAAK,cAAc,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,EAAE,CAAA;IAC3E,CAAC,CAAC,CAAA;IAEF,OAAO,QAAQ,SAAS,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,OAAO,EAAE,CAAA;AACzD,CAAC"}
+{"version":3,"file":"aeo.js","sourceRoot":"","sources":["../../src/utils/aeo.ts"],"names":[],"mappings":"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"}

package/dist/utils/apple-news-anf.d.ts

@@ -0,0 +1,38 @@
+import type { ContentItem } from '../types.js';
+export interface GenerateAnfOptions {
+    channelId: string;
+    byline?: string;
+    language?: string;
+}
+export interface AnfComponent {
+    role: string;
+    [key: string]: unknown;
+}
+export type AnfLayoutMap = Record<string, Record<string, unknown>>;
+export type AnfStyleMap = Record<string, Record<string, unknown>>;
+export interface AnfDocument {
+    version: string;
+    identifier: string;
+    title: string;
+    subtitle?: string;
+    language: string;
+    layout: Record<string, unknown>;
+    documentStyle?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+    components: AnfComponent[];
+    componentLayouts?: AnfLayoutMap;
+    componentStyles?: AnfStyleMap;
+}
+/**
+ * Generate an Apple News Format document for a ContentItem. The returned value
+ * is a JSON-serializable object; consumers submit it as the `article.json` part
+ * of a News Publisher multipart POST.
+ *
+ * The generated document uses a conservative default layout (7-column grid),
+ * standard component styles, and a body composed of: title, byline, hero image,
+ * then one body component per paragraph-separated block of the article's
+ * description. Consumers producing real articles should replace the body
+ * components with their rendered content before submitting.
+ */
+export declare function generateAppleNewsAnf(item: ContentItem, options: GenerateAnfOptions): AnfDocument;
+//# sourceMappingURL=apple-news-anf.d.ts.map

package/dist/utils/apple-news-anf.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apple-news-anf.d.ts","sourceRoot":"","sources":["../../src/utils/apple-news-anf.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAiB9C,MAAM,WAAW,kBAAkB;IAClC,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,QAAQ,CAAC,EAAE,MAAM,CAAA;CAGjB;AAED,MAAM,WAAW,YAAY;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACtB;AAID,MAAM,MAAM,YAAY,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAClE,MAAM,MAAM,WAAW,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAAA;AAEjE,MAAM,WAAW,WAAW;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,UAAU,EAAE,MAAM,CAAA;IAClB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,EAAE,MAAM,CAAA;IAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAClC,UAAU,EAAE,YAAY,EAAE,CAAA;IAC1B,gBAAgB,CAAC,EAAE,YAAY,CAAA;IAC/B,eAAe,CAAC,EAAE,WAAW,CAAA;CAC7B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,kBAAkB,GAAG,WAAW,CAsFhG"}