@aeptus/aexeo-emdash 0.8.19 → 0.9.1

package/CHANGELOG.md

@@ -4,6 +4,118 @@ All notable changes to `@aeptus/aexeo-emdash` are listed here.
 The format follows [Keep a Changelog](https://keepachangelog.com/),
 and the project follows [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.9.1] - 2026-11-12
+
+### Added
+
+- Support host-provided component, inventory route and locale mappings, and preserve precise CMS source positions when available.
+- Report content assessment coverage and measurements, with opt-in external gate and link observation providers.
+
+### Fixed
+
+- Count body findings withheld due to incomplete CMS projections in aggregate telemetry, and test native family coverage against the rule registry.
+- Withhold native page and site rules unless their evidence is observable from the CMS body; preserve explicitly tagged content-preset findings and filter old stored results at read time.
+- Explain when no content-preset assessment was recorded and report aggregate assessment coverage in local telemetry.
+- Show whether each CMS evaluation had complete, partial, unavailable or unknown body coverage in both findings interfaces. Older findings without coverage are treated conservatively; a complete body does not establish rendered-page or overall editorial quality.
+- Preserve available prose while marking body coverage unverified when automatic selection encounters an unrecognized conventional body field. Hosts can still explicitly select the fields constituting the rendered body.
+- Preserve ordered Portable Text when it is mixed with custom components. Unmapped components leave coverage unverified; explicitly mapped components can be included or deliberately excluded from editorial body evaluation.
+
+## [0.9.0] - 2026-11-10
+
+### Added
+
+- Portable content presets with per-collection selection, typed body capabilities and explicit incomplete results.
+- Ordered mappings for multiple content fields and custom blocks, including nested repeats and heading levels, in configured and sandboxed modes.
+- Conservative CMS link inventory export, source locations and aggregate content coverage telemetry.
+- The configured dashboard reports evaluator failures without breaking the editor and tolerates older findings without secondary layers.
+
+### Compatibility
+
+- Supports EmDash `^1.2.0`. Deploy the matching sidecar when using sandboxed mode.
+- The intelligence widget reports facts and blockers instead of the removed composite score.
+- Existing site and CLI checks remain separate from optional content presets.
+
+### Changed
+
+- **The dashboard widget no longer shows a composite score.** The "Overall"
+  stat and the "Site score is N — below the 60 quality threshold" banner are
+  gone; blockers remain the call to action. `SiteIntelligenceScore` loses
+  `overall_score`, `answer_pack_score` and `elapsed_us` and gains
+  `answer_pack`, and `citation_readiness_score` and `truth_consistency_score`
+  may now be `null`, shown as "unknown", when nothing was measured.
+- **Entity presence resolves the newest Common Crawl index at runtime** from
+  `collinfo.json` instead of a pinned crawl, so a site first crawled after a
+  plugin release is no longer reported `not_found`. Failing to resolve the
+  index reports `unreachable`.
+- Support EmDash `^1.2.0` and run the plugin-host integration coverage against
+  EmDash `1.2.0`.
+
+### Added
+
+- **The sandboxed plugin warns when its sidecar is on another version.** The
+  Worker reports its version in the `x-aexeo-version` response header, and the
+  plugin logs a warning when it differs, since a Worker left behind on an upgrade
+  keeps evaluating with older rules.
+
+### Security
+
+- **EVAL_TOKEN never falls back to plaintext.** When the host cannot encrypt
+  the token (usually `EMDASH_ENCRYPTION_KEY` is unset), the Setup page now shows
+  an error and changes nothing, where it used to store the token in plaintext KV
+  with only a log line. **Behaviour change:** on such a host, saving the Setup
+  form fails until the key is set, even for a URL-only change. A token already
+  in KV keeps working, and the Setup page says it is unencrypted.
+- **A rotated token is no longer ignored.** Reads preferred settings, so a token
+  that fell back to KV during a rotation lost to the older one in settings. A KV
+  token is always the newer of the two, and is now read first.
+- **The Setup form rejects trailing-dot hosts** such as `https://localhost./`,
+  which passed the loopback check.
+
+### Changed
+
+- **`aexeo-crawl-worker` upgrade notes.** The Worker refuses every request when
+  `EVAL_TOKEN` is shorter than 32 characters, so rotate a shorter token before
+  redeploying. It answers `413` above 8 MiB, the limit of emdash's sandbox
+  bridge. Malformed bodies and initialization failures now return JSON errors, and
+  token comparison is constant-time. It is built with Wrangler 4 and a newer
+  compatibility date.
+- **Editors can read findings.** The configured plugin's `admin` and `data`
+  routes declare `plugins:read`; emdash otherwise requires `plugins:manage`.
+  Refresh, facts and presence stay admin-only, and the `admin` route refuses
+  `refresh_findings` for non-admins. The sandboxed entry stays admin-only because
+  its `admin` route also saves the Setup form.
+- **The configured plugin declares its network use**: `network:request` and the
+  presence sources' hosts, which it was using while declaring only `content:read`.
+
+### Fixed
+
+- **Concurrent writes no longer lose newer data.** A save older than the stored
+  revision is ignored, a slow evaluation does not overwrite the findings of a
+  later save or delete, and a Refresh does not overwrite a save that landed during
+  the sweep or remove a document created during it.
+- **Deleted content leaves the findings immediately**, through a
+  `content:afterDelete` hook, including when it is only trashed. Restoring an
+  entry brings it back at its next save or Refresh.
+- **Legacy `document:` entries are removed** by a Refresh that does not see their
+  route. They record no collection, so they were previously never removed.
+- **The sandboxed score widget reports the score as unavailable** instead of a
+  score of 0, which read as a measured result.
+- **Entity presence no longer reports false results.** Common Crawl searches the
+  whole domain, where an exact-URL match reported a site absent when the crawl
+  skipped only its home page. Wikipedia and Wikidata records must name the entity
+  or a declared alias, ignoring legal forms; a substring used to count, so
+  "Pineapple" matched "Apple".
+- **Saving a document no longer reports false site-graph findings or erases
+  real ones.** A save evaluates one document as a one-page site, so every
+  internal link was reported as broken (`LNK001`) and the page as an orphan
+  (`LNK002`), and those results replaced the route's stored findings until the
+  next Refresh. Rules that depend on other documents (`LNK001`-`LNK004`,
+  `SEO009`, `SEO012`, `SEO016`, `SEO017`, `CNT005`) are now computed by Refresh
+  only: a save keeps the route's stored findings for them, so a link fixed or
+  added in that save is reflected at the next Refresh.
+
 ## [0.8.19] - 2026-09-29
 
 Updates the EmDash integration to the current plugin and content APIs, and
@@ -126,8 +238,6 @@ version, since 0.8.19 had never been published.
   `deploy`, and only the two declaration files remain tracked. The package
   also gains a README, which it did not have.
 
-## [Unreleased]
-
 ## [0.8.18] - 2026-09-28
 
 ### Added

package/INSTALL.md

@@ -5,6 +5,194 @@ site. Findings show up as a Block Kit admin page; a sidebar widget
 shows the site's current intelligence score; saves auto-evaluate the
 changed document.
 
+## Restricting content presets to specific collections
+
+Content presets apply to all evaluated collections by default. Set
+`contentPreset.collections` to select only the collections that use the preset;
+existing site checks continue to run on all configured collections. Use
+`byCollection` to choose an alternate preset for a selected collection.
+For example:
+
+```js
+aexeoPlugin({
+  contentPreset: {
+    name: "article",
+    collections: ["blog_posts", "glossary_terms"],
+    byCollection: { glossary_terms: "glossary" },
+  },
+})
+```
+
+## External gates in configured mode
+
+The default descriptor loads no external code. Hosts that need custom gates can
+provide a trusted runtime entrypoint exporting `createPlugin(options)` and call
+Aexeo's configured entry with a runtime provider. Package this module under a
+specifier your EmDash build can import, then set the descriptor's `entrypoint`
+to that specifier. EmDash serializes descriptor options as JSON, so a callback
+cannot be placed in `aexeoPlugin` options.
+
+```ts
+// Example host-owned runtime module, published as @example/aexeo-runtime
+import { createPlugin as createAexeo } from "@aeptus/aexeo-emdash/configured";
+import type { ConfiguredPluginOptions, ExternalGateProvider } from "@aeptus/aexeo-emdash/configured";
+
+const externalGates: ExternalGateProvider = async ({ input }) => [{
+  extension: "example.rule",
+  parameters: {},
+  input,
+  diagnostics: [], // Replace with your trusted checker and its diagnostics.
+}];
+
+export function createPlugin(options: ConfiguredPluginOptions) {
+  return createAexeo(options, { externalGates });
+}
+```
+
+In the host's configuration, use
+`{ ...aexeoPlugin({ contentPreset: { name: "custom", sources: { custom: "..." } } }), entrypoint: "@example/aexeo-runtime" }`.
+The callback runs on save and refresh only when the resolved preset has a custom
+gate. It receives the selected document’s
+projected input, selected preset and collection, and returns results bound to
+the input and the gate's exact parameters. The preset must declare the matching
+custom gate. Aexeo reports stale or missing results as incomplete. If the
+provider fails, modern reports retain other findings and mark external gates as
+not checked; older sidecar clients that cannot represent coverage still fail.
+The input may include private content and
+evidence. The host owns provider trust, timeouts, resource limits and any
+network transfer. This runtime injection does not configure the sandbox worker.
+An optional `onExternalGateTelemetry` runtime callback receives only provider
+duration and success/error status, with no content or document identifiers.
+It measures projection, provider call and result evaluation, not whether the returned gates passed.
+
+## Content coverage
+
+Portable Text bodies provide text, headings, paragraphs and links to content
+presets. A plain text body provides text only. EmDash custom blocks are
+project-specific; their flattened text is available to the legacy site audit,
+but content-preset gates that require body capabilities are reported as
+`not_checked` until a faithful mapping is provided. The configured plugin
+persists available findings alongside each gate status and its reason. The
+sidecar also reports these assessments to updated clients; older clients retain
+the fail-closed behavior for incomplete presets. This avoids treating unobserved
+headings, paragraphs or links as absent. An explicitly empty body
+is distinct from an unavailable body. When an entry has several candidate
+content fields, the default first-field projection remains unverified because
+it cannot establish which fields appear in the rendered page.
+
+During a CMS refresh, failed collection listings, invalid pagination and
+incomplete bodies make sitewide and cross-document results unavailable. Aexeo
+hides old cross-document findings and shows the coverage reason in the admin
+views and `sitewideAssessment` in the findings API. `aexeo.sitewide_coverage`
+logs only an aggregate status. A complete CMS listing is not proof that the
+CMS inventory matches a rendered site or represents an atomic snapshot;
+concurrent edits and refreshes are not isolated by the host's KV interface.
+CMS-only evaluation does not assert that links are broken or pages are orphans;
+use a rendered-site audit with matched inventory and coverage evidence.
+
+For custom blocks in configured mode, declare the ordered rendered content
+fields for each block type in the plugin configuration:
+
+```js
+aexeoPlugin({
+  contentFieldsByCollection: { pages: ["introduction", "sections"] },
+  blockMappings: {
+    hero: [
+      { kind: "heading", field: "headline" },
+      { kind: "paragraph", field: "description", optional: true },
+      { kind: "link", field: "linkLabel", hrefField: "linkUrl", optional: true },
+      { kind: "richText", field: "body" },
+    ],
+    faq: [
+      { kind: "heading", field: "heading" },
+      { kind: "repeat", field: "faqs", fields: [
+        { kind: "heading", field: "question", level: 3 },
+        { kind: "paragraph", field: "answer" },
+      ] },
+    ],
+  },
+})
+```
+
+`contentFieldsByCollection` declares the body fields rendered by each selected
+collection, in order. It is an explicit assertion of completeness, so include
+all rendered fields. A selected field absent from the record makes the body
+incomplete, while an explicitly present `null` is treated as empty. If no selected
+field is present, the body remains unavailable. In sandboxed mode, enter this object in `Content fields by collection (JSON)`.
+If this setting is malformed or cannot be read, save and Refresh keep recognized
+prose but mark all body capabilities unavailable; check the plugin warning and
+repair the setting. An unset setting uses automatic detection as usual.
+
+Portable Text can also interleave text blocks and custom components. An
+unknown component keeps its surrounding text but marks body capabilities
+unverified. Best-effort text extracted from an unknown component is bounded to
+64 nesting levels, 50,000 visited values and 1,048,576 UTF-16 code units;
+it may therefore be incomplete and must not be treated as a complete body. A host may map a component to `[]` only when it has verified that
+the component contributes no content relevant to the evaluated body.
+
+For an inline object inside a Portable Text block, use an explicit `inline`
+mapping. It projects text and links in place without creating a new paragraph:
+
+```js
+blockMappings: {
+  badge: { inline: [
+    { kind: "text", field: "label" },
+    { kind: "link", field: "linkLabel", hrefField: "href", optional: true },
+  ] },
+}
+```
+
+An empty `inline` array asserts the component adds no relevant body content.
+An optional `capabilities` array limits the assertion just as for block mappings;
+omitting it asserts all body capabilities. Only declare these mappings after
+verifying the host renderer. Unknown components or invalid fields keep surrounding
+spans but leave the body unverified. Mapped spans do not have original CMS source
+locations because they are derived from component fields. Unchanged surrounding
+spans can retain their original paths even when component projection changes their
+position; ambiguous aliases and oversized or cyclic records remain unmapped.
+
+The array form asserts that all four capabilities are complete. If a host can
+only establish some capabilities, use the object form instead:
+
+```js
+blockMappings: {
+  card: {
+    fields: [{ kind: "paragraph", field: "body" }],
+    capabilities: ["text", "paragraphs"],
+  },
+}
+```
+
+List a capability only when the projected fields faithfully represent **all**
+of that component's rendered content relevant to it, including content outside
+the listed fields. An empty `fields` array in the object form asserts only the
+listed capabilities; for example, `fields: [], capabilities: ["headings"]`
+asserts that the component contributes no headings, but says nothing about its
+text, paragraphs or links. Aexeo intersects capabilities across every component,
+selected field and nested rich-text block. Unknown, malformed or missing input
+still removes the affected coverage conservatively. These assertions require
+validation against the host renderer; they do not prove the content is correct.
+
+A block mapping is the site's assertion that those fields cover the rendered content,
+in order. `richText` accepts Portable Text arrays, including text mixed with
+mapped custom components, or arrays of mapped custom components alone, and
+preserves their headings and links. Unmapped or
+malformed nested components and recursion beyond the mapping depth limit leave
+body coverage unverified; `heading` defaults to h2 and accepts levels 1 through 6. `repeat`
+maps each item in an array;
+`optional: true` permits an absent field without inventing content. Every
+encountered block type must be
+mapped and every mapped field must have the expected type. If not, capabilities
+remain unverified. These options apply to configured-mode saves and both
+refresh routes. In sandboxed mode, enter the same JSON object in the plugin
+settings field `Custom block mappings (JSON)`; it applies to save and Refresh.
+Invalid or unavailable settings leave custom blocks unverified.
+
+Adapters supplying an `EmdashDocument` can set `body_capabilities` to a subset
+of `text`, `headings`, `paragraphs` and `links`. Omit it only when all four
+are faithfully represented. These capability declarations describe input
+coverage; they do not validate the content itself.
+
 ## Two install paths
 
 The package exports two factories:
@@ -31,8 +219,8 @@ when it's actually needed.
   (`@astrojs/cloudflare` + `@emdash-cms/cloudflare`'s `sandbox()`
   runner is fine — sandboxed plugins use Worker Loader, configured
   plugins don't, but both adapters import cleanly).
-- EmDash `>=0.41.0 <0.42.0` as a peer dependency. The integration
-  coverage targets `0.41.0` with EmDash's official plugin test host.
+- EmDash `^1.2.0` as a peer dependency. The integration coverage targets
+  `1.2.0` with EmDash's official plugin test host.
 
 ### Install
 
@@ -371,8 +559,10 @@ Node adapter.
   evaluated document under `document:<route>`.
 - **Auto-evaluate on save**: emdash's `content:afterSave` hook fires
   for each save, re-evaluates that one document, and updates its
-  KV findings entry. The dashboard widget reflects the new score on
-  the next page load.
+  KV findings entry. Findings that depend on other documents, such as
+  broken internal links, keep their last Refresh result until the next
+  Refresh. The dashboard widget reflects the new score on the next page
+  load.
 
 ## Architecture in one paragraph
 
@@ -386,3 +576,95 @@ itself is the same `aexeo-emdash-bridge` Rust crate that powers the
 Aexeo CLI; it's compiled to WebAssembly via wasm-pack and imported
 by the host's bundler (Vite + `vite-plugin-wasm`). No separate
 service, no sidecar, no auth token.
+
+### Exporting a conservative link inventory
+
+For host code with access to EmDash's content API, the package exports
+`exportLinkInventory(content, options)`. Select the collections belonging to
+one publication explicitly and supply the observed site identity:
+
+```ts
+import { exportLinkInventory } from "@aeptus/aexeo-emdash";
+
+const result = await exportLinkInventory(ctx.content, {
+  collections: ["blog_posts", "pages"],
+  identity: { origin: "https://example.org", release: "release-id", surface: "public", snapshot: "snapshot-id" },
+});
+// result.inventory matches the link-graph input's inventory shape.
+// Inspect result.issues and result.omitted before using it.
+```
+
+The export resolves public URLs through EmDash and paginates each selected
+collection. Entries without public URLs are reported as omitted, and entries
+with URLs default to `unknown` disposition. A host may supply `classify` when
+it has authoritative indexability and alias information. Repeated or missing
+cursors, failures, malformed collection responses or entries, and page limits are reported.
+Malformed entries are omitted; a malformed collection page stops that collection
+without discarding other collections. The inventory is always marked
+incomplete because pagination alone cannot establish a transactional snapshot or
+include routes outside the chosen collections. No HTTP endpoint is installed by
+this API. It cannot by itself establish that a crawl and CMS view describe the
+same publication, release and point in time.
+
+Hosts whose rendered routes differ from EmDash's resolver can supply an async
+`resolveUrl(collection, item)` returning the actual public URL or `null` when
+no route is known. It replaces `getPublicUrl` for that export. The optional
+`classify(item, url, collection)` callback can use collection-specific rules
+and return `disposition`, `target`, and an explicit `locale` (including `null`
+for unknown); omitting `locale` retains the CMS value. Callback failures leave
+entries omitted or unclassified and are counted without exposing error details.
+These host-supplied values are assertions, not proof of rendered routes,
+publication state, snapshot identity, or inventory completeness.
+
+URL resolution runs at most eight CMS requests concurrently by default. Set
+`urlResolutionConcurrency` to an integer from 1 to 100 to suit the host's
+capacity; use 1 for sequential requests. Pagination remains sequential.
+
+An optional `onTelemetry` callback receives only elapsed milliseconds and aggregate counts. It is disabled by default and does not receive URLs or content.
+
+### CMS coverage and rendered pages
+
+The CMS integration evaluates content records, not the rendered page.
+It does not report legacy SEO, social metadata, accessibility, page-size,
+answer-block or citation-context findings as if generated HTML were observed.
+The CMS dashboard score widget is unavailable for the same reason: CMS records
+do not establish rendered-page coverage or a complete site inventory. Run Aexeo
+against the built site to assess those checks. The `aexeo.page_coverage`
+telemetry event marks rendered-page and generated-metadata coverage as not observed;
+`aexeo.content_coverage` describes body projection separately.
+
+The built-in `article` preset is a minimal non-empty text check, not a complete
+editorial or SEO assessment. Choose and compose the editorial presets appropriate
+to the content, or supply a project-specific preset.
+
+When the host renderer selects a description from collection fields, configure
+the same ordered fallback explicitly, for example:
+
+```ts
+aexeoPlugin({
+  descriptionFieldsByCollection: { blog_posts: ["seo_description", "excerpt"] },
+})
+```
+
+In sandboxed mode, enter the equivalent JSON object, for example
+`{"blog_posts":["seo_description","excerpt"]}`, in the plugin setting
+`Description fields by collection (JSON)`. It applies to saves and Refresh.
+
+The mapping projects source values; it does not prove what metadata the page
+renderer generated. Explicit null or empty fields are observed as absent. A
+missing, undefined or invalid field before the chosen fallback makes the source
+unverified; an unused later field need not be present. Invalid settings remain
+unverified. A `required_metadata` gate requesting `description` reports
+`not_checked` when that source was not observed; other known-missing fields
+can still produce findings. The `aexeo.description_coverage` log contains
+aggregate counts of observed and unverified source projections without content
+or identifiers.
+
+Content preset gate outcomes, including `not_checked` and their reasons, are
+stored with the current route findings and exposed in CMS views and the data
+route. The preset panel lists passed, failed and unchecked gates, whether they
+are blocking, and available measurements and thresholds. Older stored reports
+may not contain measurements; missing measurements are not shown as zero. A
+pass covers only the configured checks and is not an overall quality score. A failed evaluation clears findings for that revision and records an
+error; it must not be interpreted as a clean assessment. `aexeo.preset_coverage`
+logs aggregate counts without routes, gate identifiers, reasons or content.

package/README.md

@@ -3,7 +3,7 @@
 Aexeo SEO/GEO content evaluator as an emdash plugin.
 
 Adds a Findings admin page, per-document panel, and dashboard
-intelligence-score widget to an emdash site. Saves auto-evaluate the
+intelligence facts widget to an emdash site. Saves auto-evaluate the
 changed document; the Refresh button re-evaluates the whole site.
 
 ## Install
@@ -43,18 +43,25 @@ troubleshooting list, see [INSTALL.md](./INSTALL.md).
 - **Findings page** at `/_emdash/admin/plugins/aexeo-emdash/findings`:
   rule violations across the site, filterable by severity.
 - **Document panel** at `/document`: findings scoped to one document.
-- **Dashboard widget**: top-line intelligence score (citation, truth,
-  answer-pack, external-trust dimensions). Banner appears below 60.
+- **Dashboard widget**: citation readiness, truth consistency and answer
+  structure side by side, with the top blockers. There is no composite score
+  or quality threshold, and a dimension with nothing to measure reads
+  `unknown`.
+- **Entity presence**: Wikipedia is searched on `en.wikipedia.org` only, so
+  `not_found` says nothing about other language editions.
 - **Refresh button**: re-evaluate every document in the configured
   collections (`posts`, `pages` by default).
 - **Auto-evaluate on save**: EmDash's `content:afterSave` hook evaluates
   the saved document and updates its findings. Sandboxed installs need a
   configured evaluator sidecar; configured installs run evaluation in-process.
+  Findings that depend on other documents (broken and weak internal links,
+  inbound links, hreflang targets, shared canonicals, duplicate metadata and
+  text) stay as the last Refresh stored them until the next Refresh.
 
 ## Compatibility
 
-- EmDash `>= 0.41.0 < 0.42.0` (peer dependency; current supported range)
-- Runtime integration coverage targets EmDash `0.41.0` via the official
+- EmDash `^1.2.0` (peer dependency; current supported range)
+- Runtime integration coverage targets EmDash `1.2.0` via the official
   `@emdash-cms/plugin-test` host.
 - Cloudflare Workers via `@astrojs/cloudflare`. The plugin uses
   Cloudflare-specific APIs and silently no-ops on the Node adapter.
@@ -174,3 +181,11 @@ for the sandboxed setup runbook.
 ## License
 
 MIT — see [LICENSE](./LICENSE).
+
+### Host-supplied link observations
+
+The optional content API can evaluate explicitly supplied link reachability
+observations without network access in WASM. See [content gate documentation](https://github.com/schiste/Aexeo/blob/main/docs/content-gates.md#emdash-host-observations) for snapshot binding,
+privacy and incomplete-coverage behavior. Configured save and refresh hooks invoke
+a host observer only when it is explicitly installed and the selected preset requests
+the gate. The host owns its network policy and request limits.

package/dist/adapter.d.ts

@@ -1,10 +1,55 @@
 import type { EmdashDocument } from "./types.js";
+/** Ordered fields that the host declares constitute a custom block's content. */
+export type CustomBlockField = {
+    kind: "paragraph" | "richText";
+    field: string;
+    optional?: boolean;
+} | {
+    kind: "heading";
+    field: string;
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    optional?: boolean;
+} | {
+    kind: "link";
+    field: string;
+    hrefField: string;
+    optional?: boolean;
+} | {
+    kind: "repeat";
+    field: string;
+    fields: readonly CustomBlockField[];
+    optional?: boolean;
+};
+/** Capabilities that a host can establish for a component's rendered content. */
+export type BodyCapability = "text" | "headings" | "paragraphs" | "links";
+/** Ordered fields projected within the surrounding Portable Text block. */
+export type InlineComponentField = {
+    kind: "text";
+    field: string;
+    optional?: boolean;
+} | {
+    kind: "link";
+    field: string;
+    hrefField: string;
+    optional?: boolean;
+};
+/** The object form asserts coverage only for the listed capabilities. */
+export type CustomBlockMapping = readonly CustomBlockField[] | {
+    fields: readonly CustomBlockField[];
+    capabilities: readonly BodyCapability[];
+} | {
+    inline: readonly InlineComponentField[];
+    capabilities?: readonly BodyCapability[];
+};
+export type CustomBlockMappings = Record<string, CustomBlockMapping>;
 export interface EmdashContentItem {
     id: string;
     type: string;
     slug: string | null;
     status: string;
     locale: string | null;
+    /** Host write timestamp. Orders concurrent saves and Refresh sweeps. */
+    updatedAt?: string;
     translationGroup?: string | null;
     data: Record<string, unknown>;
     seo?: {
@@ -21,6 +66,14 @@ export interface EmdashContentMeta {
     title: string;
     /** Exact URL returned by EmDash, or null when this entry has no public route. */
     publicUrl: string | null;
+    /** The content could not be adapted; route and title are from the previous snapshot. */
+    adaptationFailed?: true;
+    /** Original paths for unchanged Portable Text blocks in this exact snapshot. */
+    bodySourcePaths?: Array<Array<string | number> | null>;
+    /** Original text paths for unchanged spans within projected blocks. */
+    bodySourceSpanPaths?: Array<Array<Array<string | number> | null> | null>;
+    /** The host's `updatedAt` for the row this entry was adapted from. */
+    updatedAt?: string;
 }
 export interface ContentUrlApi {
     getPublicUrl(collection: string, id: string): Promise<string | null>;
@@ -44,16 +97,21 @@ export interface AdaptedContent {
  * accounts for collection URL patterns, locale prefixes, and slash policy;
  * slug-derived paths are not equivalent to the site's actual public URLs.
  */
-export declare function adaptContentItemWithContext(content: EmdashContentItem, contentApi: ContentUrlApi, defaultLocale?: string): Promise<AdaptedContent>;
+export declare function adaptContentItemWithContext(content: EmdashContentItem, contentApi: ContentUrlApi, defaultLocale?: string, blockMappings?: CustomBlockMappings, contentFields?: readonly string[], descriptionFields?: readonly string[]): Promise<AdaptedContent>;
 /**
  * Synchronous adapter for callers that do not have a host content API.
  * It deliberately uses a stable identity route; callers should use
  * adaptContentItemWithContext whenever EmDash can resolve the public URL.
  */
-export declare function contentItemToEmdashDocument(content: EmdashContentItem): EmdashDocument;
-export declare function adaptContentItem(content: EmdashContentItem, options?: {
+export declare function contentItemToEmdashDocument(content: EmdashContentItem, blockMappings?: CustomBlockMappings): EmdashDocument;
+type AdaptContentOptions = {
     route?: string;
     publicUrl?: string | null;
     defaultLocale?: string;
-}): AdaptedContent;
+    blockMappings?: CustomBlockMappings | undefined;
+    contentFields?: readonly string[];
+    descriptionFields?: readonly string[];
+};
+export declare function adaptContentItem(content: EmdashContentItem, options?: AdaptContentOptions): AdaptedContent;
+export {};
 //# sourceMappingURL=adapter.d.ts.map

package/dist/adapter.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAqB,MAAM,YAAY,CAAC;AAEpE,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,gBAAgB,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,GAAG,CAAC,EAAE;QACJ,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QACtB,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;QAC5B,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;KAC3B,CAAC;CACH;AAED,MAAM,WAAW,iBAAiB;IAChC,EAAE,EAAE,MAAM,CAAC;IACX,UAAU,EAAE,MAAM,CAAC;IACnB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;IACd,iFAAiF;IACjF,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IACrE,eAAe,CACb,UAAU,EAAE,MAAM,EAClB,EAAE,EAAE,MAAM,GACT,OAAO,CAAC;QACT,gBAAgB,EAAE,MAAM,CAAC;QACzB,YAAY,EAAE,KAAK,CAAC;YAClB,EAAE,EAAE,MAAM,CAAC;YACX,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;YACtB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;YACpB,MAAM,EAAE,MAAM,CAAC;YACf,SAAS,EAAE,MAAM,CAAC;SACnB,CAAC,CAAC;KACJ,CAAC,CAAC;CACJ;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,cAAc,CAAC;IACzB,IAAI,EAAE,iBAAiB,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAsB,2BAA2B,CAC/C,OAAO,EAAE,iBAAiB,EAC1B,UAAU,EAAE,aAAa,EACzB,aAAa,CAAC,EAAE,MAAM,GACrB,OAAO,CAAC,cAAc,CAAC,CA2CzB;AAED;;;;GAIG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,iBAAiB,GACzB,cAAc,CAEhB;AAED,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,iBAAiB,EAC1B,OAAO,GAAE;IACP,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,aAAa,CAAC,EAAE,MAAM,CAAC;CACnB,GACL,cAAc,CAgChB"}
+{"version":3,"file":"adapter.d.ts","sourceRoot":"","sources":["../src/adapter.ts"],"names":[],"mappings":"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"}

package/dist/admin/Findings.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Findings.d.ts","sourceRoot":"","sources":["../../src/admin/Findings.tsx"],"names":[],"mappings":"AA2BA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAa/B,wBAAgB,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CA2L5C"}
+{"version":3,"file":"Findings.d.ts","sourceRoot":"","sources":["../../src/admin/Findings.tsx"],"names":[],"mappings":"AA2BA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAe/B,wBAAgB,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,OAAO,CAiN5C"}

package/dist/admin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../src/admin.tsx"],"names":[],"mappings":"AAkBA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,eAAO,MAAM,KAAK;;;;;;;;CAcjB,CAAC"}
+{"version":3,"file":"admin.d.ts","sourceRoot":"","sources":["../src/admin.tsx"],"names":[],"mappings":"AAkBA,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,aAAa,EAAE,MAAM,0BAA0B,CAAC;AACzD,OAAO,EAAE,UAAU,EAAE,MAAM,uBAAuB,CAAC;AACnD,OAAO,EAAE,gBAAgB,EAAE,MAAM,6BAA6B,CAAC;AAC/D,OAAO,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAE,QAAQ,EAAE,MAAM,qBAAqB,CAAC;AAC/C,OAAO,EAAE,cAAc,EAAE,MAAM,2BAA2B,CAAC;AAE3D,eAAO,MAAM,KAAK;IAEhB,iBAAiB;IACjB,aAAa;IACb,gBAAgB;IAChB,oBAAoB;IACpB,gBAAgB;IAIhB,WAAW;IAGX,QAAQ;CACT,CAAC"}