@seedprotocol/mapping 0.5.3 → 0.6.1

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## 0.7.0
+
+- Relation lookup is an edge-local stored intent: `FieldMapping.lookup.entries` as `{ value, ref }[]`. `ref` is opaque (`seedLocalId` or `seedUid`). Empty entries are a valid unassigned map.
+- `applyMapping` (sync) applies lookup entries and emits refs. Unmatched values are omitted. `applyMappingAsync` reports unmatched on `errors[]` and no longer calls the host `resolve` callback for lookup.
+- `autoMap` pairs alias matches such as `author` → List-of-Relation `authors` with `resolve: 'lookup'` and no invented refs.
+- `FieldMapper` `renderLookup?: (row: FieldMapperLookupRow) => ReactNode` — host picker on lookup rows (same split as `renderRowAccessory`). Package uid editor is a fallback only.
+- `useFieldMapper.setLookupEntries`. Row `sampleValue` and `data-state="needsLookup"` when the current sample has no matching entry.
+- `TargetProperty` stays Seed-accurate (`List` + `refValueType: 'Relation'` + `ref`). No `multiple` flag.
+- `MappingDocument.lookups` / `lookups` + `onLookupsChange` are deprecated read/write fallbacks for 0.6.0 documents.
+- `_pendingResolve` is extract/file only; lookup hits appear in the preview bag.
+
+## 0.6.1
+
+- `FieldMapper` `renderRowAccessory?: (row: FieldMapperRow) => ReactNode` — host chrome slot on each rows-layout row (`.fm-row-accessory` / `classNames.rowAccessory`), after the transform control and before remove. Package does not fetch or preview; hosts return `null` when idle (e.g. show **Preview** only for `resolve: 'extract' | 'file'`).
+- Optional `SourceNode.subtitle` for a secondary display line (inspector, wires card, source option labels). Prefer this over stuffing origin into `label`. Display-only — not part of `MappingDocument`.
+
+## 0.6.0
+
+- `FieldMapper` Phase 5: `layout` defaults to `'rows'`; `'wires'` is deprecated but still supported.
+- `FieldMapper` Phase 4: per-row lookup editors (`slots.lookups: 'row'`), row/JSON preview parity with sync `applyMapping` (+ `_pendingResolve`), JSON behind a `<details>` disclosure. Rows layout defaults `lookups` to `'row'`; wires keep `'section'`.
+- Shared `LookupEditor` + `buildSyncPreviewBag` / upgraded `previewForEdge` (lookup table hits, coerced copy values).
+- `FieldMapper` Phase 3 theming contract: `--sfm-*` tokens (with `--fm-*` aliases), `theme="default" | "structural" | "none"` (`unstyled` shim), `classNames` / `components` / `slots`, `@layer seed-field-mapper`, document-once CSS injection, row `data-source-kind`.
+- Deprecated (still work): `layout="wires"`, `theme="unstyled"`, `showPreview`, `connectionColors` — prefer `layout="rows"`, `theme="none"`, `slots.preview`, and CSS map tokens.
+- `FieldMapper` row layout (Phase 1–2 of the redesign): `layout="rows" | "wires"`, `rowKey="property" | "source"`, `defaultRows`, optional `TargetProperty.required` for coverage.
+- Headless `useFieldMapper` hook + shared core (`setSource` / `setTransform` / coverage / conflicts); wires UI refactored to consume the hook.
+- Rows UI: transform control on the edge (no `buildResolvedSourceNodes` in the rows path), coverage toolbar, mapped+required filter, add-mapping flow, source inspector; source mode conflict + coverage banners.
+- **Breaking:** `FieldMapper` and related UI exports moved to `@seedprotocol/mapping/react`. The default entry is headless-only (no React import or required peer) so Node sidecars can load without React. Install `react` / `react-dom` only when using `/react`.
+- **Breaking:** `FieldMapper` `layout` default flipped from `'wires'` to `'rows'`. Pass `layout="wires"` explicitly if you still need the two-pane connector UI. For rows, pass origin sources only (not `buildResolvedSourceNodes`).
+- `resolve: 'lookup'` for Relation / List-of-Relation targets: persistable `MappingDocument.lookups` (string → seed uid), `applyMappingAsync` table hit + optional host callback on miss; sync apply skips lookup edges.
+- `TargetProperty.ref` / `refValueType`; `isRelationLookupTarget` helper; `autoMap` never plain-copies onto lookup-capable targets (author → authors no longer writes a string into a relation list).
+- `FieldMapper`: connecting to a lookup-capable target sets `resolve: 'lookup'`; optional `lookups` / `onLookupsChange` panel edits string → uid maps (comma-separated for multi).
+- `FieldMapper`: `theme="default" | "unstyled"`, CSS-var connector strokes (`--fm-map-1…8` / `--map-1…8`), optional `connectionColors`, `data-mapping-index` / `data-pair` on wells and paths; pending `.active` only on the selected source.
+- `FieldMapping.resolve?: 'extract' | 'file' | 'lookup'`; sync `applyMapping` skips resolve edges; new `applyMappingAsync` with host callback.
+- `classifyUrl`, `buildResolvedSourceNodes`, `normalizeMappingFromSourceId` for package-owned extract/file candidates.
+- RSS adapter exposes enclosure / media:content as `url` + `contentType` in `meta` (stable `rss-enclosure-N` ids).
+- `autoMap` never maps a raw URL onto html/Image/File without `resolve`; prefers full-text → html, then extract, then file jobs.
+- Allow one source to map to multiple properties (edge-list fan-out); each property remains exclusive.
+- `autoMap` fans `link` / `url` sources out to matching URL-ish targets (`importUrl`, `canonicalUrl`, `url`, `link`, `permalink`).
+- `FieldMapper` supports attaching multiple properties from an active source without clearing prior edges; normalizes `@extract`/`@file` nodes to `resolve` on persist.
+
 ## 0.5.1
 
 - Initial Phase 1 release: headless mapping core, markdown + RSS adapters, `FieldMapper` UI.

package/README.md

@@ -5,8 +5,15 @@ Source → Seed model property mapping helpers and a props-driven React UI.
 Use this package to:
 
 1. Parse markdown or RSS/Atom into `SourceNode[]`
-2. Author 1:1 `FieldMapping`s (manually, via `autoMap`, or via `FieldMapper`)
-3. `applyMapping` to a coerced property bag for `createItem` / publish
+2. Optionally expand URL sources with `buildResolvedSourceNodes` (extract / file candidates)
+3. Author `FieldMapping` edges (manually, via `autoMap`, or via `FieldMapper`)
+4. `applyMapping` (sync copy + stored lookup) or `applyMappingAsync` (host extract/file callback) → property bag
+
+Mappings are an edge list: one source may fan out to multiple properties (e.g. RSS
+`link` → `importUrl` and `canonicalUrl`). Each property is exclusive — at most one
+source may map to it. `resolve: 'extract' | 'file'` is applied by the host callback.
+`resolve: 'lookup'` is a stored string → ref table on the edge — the package never
+fetches, runs Readability, or loads Seed Identity items.
 
 ## Install
 
@@ -14,7 +21,11 @@ Use this package to:
 bun add @seedprotocol/mapping
 ```
 
-Peers: `react`, `react-dom`. RSS parsing uses `rss-parser` with the same custom fields as `@seedprotocol/feed` `parseRssString` (aligned, no hard dependency on the feed package barrel).
+The default entry (`@seedprotocol/mapping`) is headless — no React peer required.
+For `FieldMapper`, also install React peers and import from `@seedprotocol/mapping/react`.
+
+RSS parsing uses `rss-parser` with the same custom fields as `@seedprotocol/feed`
+`parseRssString` (aligned, no hard dependency on the feed package barrel).
 
 ## Headless API
 
@@ -24,6 +35,9 @@ import {
   rssXmlToSources,
   autoMap,
   applyMapping,
+  applyMappingAsync,
+  buildResolvedSourceNodes,
+  classifyUrl,
   type TargetProperty,
   type MappingDocument,
 } from '@seedprotocol/mapping'
@@ -43,63 +57,226 @@ const doc: MappingDocument = {
 }
 ```
 
-RSS:
+RSS with resolve jobs:
 
 ```ts
-const { channel, items } = await rssXmlToSources(xml)
+const { items } = await rssXmlToSources(xml)
 const itemSources = items[0]!
+const expanded = buildResolvedSourceNodes(itemSources)
+const postTargets: TargetProperty[] = [
+  { name: 'importUrl', dataType: 'String' },
+  { name: 'canonicalUrl', dataType: 'String' },
+  { name: 'html', dataType: 'Html' },
+  { name: 'featureImage', dataType: 'Image' },
+  { name: 'title', dataType: 'String' },
+]
 const mappings = autoMap(itemSources, postTargets)
-const properties = applyMapping(itemSources, mappings, postTargets)
+// link → importUrl/canonicalUrl (copy); missing body → link extract→html;
+// image URLs → featureImage with resolve:'file'
+
+// Sync preview applies lookup entries; extract/file stay pending:
+const preview = applyMapping(itemSources, mappings, postTargets)
+
+// Publish path — host owns HTTP / extract / store:
+const { properties, errors } = await applyMappingAsync(
+  itemSources,
+  mappings,
+  postTargets,
+  {
+    resolve: async ({ job, url, contentType, rawValue }) => {
+      if (job === 'extract') return await hostExtractHtml(url!)
+      if (job === 'lookup') return await hostLookupIdentity(rawValue!)
+      return await hostFetchAndStoreFile(url!, contentType)
+    },
+  },
+)
 ```
 
+### Relation lookup (`resolve: 'lookup'`)
+
+Map a string source (e.g. RSS `author`) onto a Relation or List-of-Relation
+target (e.g. `authors` → Identity) via **stored entries on the edge**. Use Seed
+model vocabulary — not a `multiple` flag:
+
+```ts
+const postTargets: TargetProperty[] = [
+  {
+    name: 'authors',
+    dataType: 'List',
+    refValueType: 'Relation',
+    ref: 'Identity',
+  },
+]
+
+const mappings = [
+  {
+    sourceId: 'rss-author',
+    propertyName: 'authors',
+    resolve: 'lookup' as const,
+    lookup: {
+      entries: [{ value: 'Jane Doe', ref: 'identity-seed-uid' }],
+    },
+  },
+]
+
+const doc: MappingDocument = {
+  version: 1,
+  sourceKind: 'rss',
+  mappings,
+}
+
+// Sync apply emits refs from stored entries (extract/file still skipped):
+const bag = applyMapping(itemSources, mappings, postTargets)
+// bag.authors === ['identity-seed-uid']
+
+const { properties, errors } = await applyMappingAsync(
+  itemSources,
+  mappings,
+  postTargets,
+)
+// Unmatched values are omitted from the bag and listed in errors[].
+// Do not fetch identities inside apply — persist the assignment, then apply.
+```
+
+`autoMap` pairs alias matches such as `author` → `authors` with
+`resolve: 'lookup'` and **empty** entries. It never invents refs.
+
+`MappingDocument.lookups` / `applyMappingAsync({ lookups })` remain a read-only
+fallback for 0.6.0 documents. Prefer `FieldMapping.lookup.entries`.
+
+`classifyUrl({ url, contentType? })` is a pure MIME/extension classifier
+(`html` | `image` | `audio` | `video` | `unknown`). Enclosure nodes expose
+`meta.url`, `meta.contentType`, and `meta.class` (not a stringified object).
+
 ## FieldMapper UI
 
-Props-driven only — no Seed hooks or routing. The host app supplies sources/targets and handles create/navigate.
+Props-driven only — no Seed hooks or routing. Import from `@seedprotocol/mapping/react`.
+
+Two layouts share the same persisted `FieldMapping[]`. **`layout` defaults to `"rows"`.**
+
+| `layout` | Behavior |
+|----------|----------|
+| `"rows"` (default) | Row-based authoring. Pass **origin** sources only — transforms are chosen per row (no `@extract`/`@file` cards). |
+| `"wires"` (**deprecated**) | Two-pane click-to-connect with SVG connectors. Pass `buildResolvedSourceNodes(sources)` so extract/file candidates appear as source cards. Still supported for one minor. |
+
+When `layout="rows"`, `rowKey` picks orientation:
+
+| `rowKey` | Behavior |
+|----------|----------|
+| `"property"` (default) | One row per target property; source + transform inside the row. Structurally property-exclusive. |
+| `"source"` | One row per edge (insertion order); conflict banner when two rows claim one property; coverage banner for missing `required` targets. |
+
+Mark targets with `required: true` so coverage / default filters surface missing fields. Default visible set for property mode is mapped + required (`defaultRows="requiredAndMapped"`).
 
 ```tsx
 import { useState } from 'react'
 import {
-  FieldMapper,
+  buildResolvedSourceNodes,
   markdownToSources,
-  applyMapping,
+  rssItemToSources,
+  applyMappingAsync,
   type FieldMapping,
 } from '@seedprotocol/mapping'
+import { FieldMapper, useFieldMapper } from '@seedprotocol/mapping/react'
 
-function ImportMap({ markdown, targets, onSubmit }) {
-  const sources = markdownToSources(markdown)
-  const [mappings, setMappings] = useState<FieldMapping[]>([])
-
-  return (
-    <>
-      <FieldMapper
-        sources={sources}
-        targets={targets}
-        mappings={mappings}
-        onChange={setMappings}
-      />
-      <button
-        onClick={() => onSubmit(applyMapping(sources, mappings, targets))}
-      >
-        Create
-      </button>
-    </>
-  )
-}
+// Rows — property-keyed (default layout; recommended)
+<FieldMapper
+  rowKey="property"
+  sources={rssItemToSources(item)} // origin sources; no buildResolvedSourceNodes
+  targets={postTargets} // e.g. { name: 'html', dataType: 'Html', required: true }
+  mappings={mappings}
+  onChange={setMappings}
+  slots={{ lookups: 'row', preview: 'row' }}
+  renderRowAccessory={(row) =>
+    row.mapping?.resolve === 'extract' || row.mapping?.resolve === 'file'
+      ? <button type="button">Preview</button>
+      : null
+  }
+  renderLookup={(row) => (
+    <IdentityLookup
+      sampleValue={row.sampleValue}
+      entries={row.mapping?.lookup?.entries ?? []}
+      onChange={row.onLookupChange}
+    />
+  )}
+/>
+
+// Rows — source-keyed
+<FieldMapper rowKey="source" sources={itemSources} targets={targets} mappings={mappings} onChange={setMappings} />
+
+// Wires (deprecated — opt in explicitly)
+<FieldMapper
+  layout="wires"
+  sources={buildResolvedSourceNodes(markdownToSources(markdown))}
+  targets={targets}
+  mappings={mappings}
+  onChange={setMappings}
+  theme="none"
+/>
+```
+
+Headless mechanics (same package):
+
+```tsx
+const mapper = useFieldMapper({
+  sources,
+  targets,
+  mappings,
+  onChange: setMappings,
+  rowKey: 'property',
+})
+// mapper.rows, mapper.coverage, mapper.setSource, mapper.setTransform, …
 ```
 
+Connecting a source to a Relation / List-of-Relation target sets `resolve: 'lookup'`.
+Pass `renderLookup` to paint the host picker (Identity, etc.) on that row. Without
+`renderLookup`, `onLookupsChange` still enables the package uid-text fallback.
+`lookups` / `onLookupsChange` are deprecated — persist `lookup.entries` on the edge.
+
+Row and JSON previews match sync `applyMapping` output. Lookup hits appear in the
+bag; only extract/file stay under `_pendingResolve`. JSON sits behind a disclosure.
+
+**Theming**
+
+| Prop | Behavior |
+|------|----------|
+| `theme="default"` (default) | Injects structural + paint CSS once into `document.head` (`@layer seed-field-mapper`) with `--sfm-*` tokens (`--fm-*` aliases kept for one minor) |
+| `theme="structural"` | Layout / spacing only — no color paint; inherits host colors |
+| `theme="none"` | No injection — structural classes only (`fm-card`, `fm-row`, `fm-grid`, …); keeps `seed-field-mapper--unstyled` |
+| `theme="unstyled"` | **Deprecated** shim for `none` |
+| `classNames` | Per-slot host classes merged with package classes (`root`, `toolbar`, `row`, `rowAccessory`, …) |
+| `components` | Optional host `Select` / `Button` / `Pill` (defaults are native controls) |
+| `slots` | Toggle chrome: `autoMap`, `filter`, `inspector`, `preview` (`'row' \| 'json' \| 'both' \| false`), `lookups` (`'row' \| 'section' \| false`; rows layout defaults to `'row'`, wires to `'section'`) |
+| `renderRowAccessory` | Optional `(row: FieldMapperRow) => ReactNode` for host chrome (e.g. extract/file **Preview**) in `.fm-row-accessory`. Unrelated to `slots.preview`. Package does not fetch. |
+| `renderLookup` | Optional `(row: FieldMapperLookupRow) => ReactNode` for host lookup chrome on `resolve: 'lookup'` rows. Package does not fetch or list identities. |
+| `showPreview` | **Deprecated** — prefer `slots.preview` |
+| `connectionColors` | **Deprecated** optional stroke palette for wires; prefer `--sfm-map-*` / `--fm-map-*` / `--map-*` |
+| `layout="wires"` | **Deprecated** — prefer `layout="rows"` (now the default) |
+
+`SourceNode` may include optional `subtitle` (display-only). Prefer `subtitle` over stuffing a secondary fact into `label` (e.g. origin field name on a resolved well).
+
+**DOM hooks for host CSS**
+
+- Wires: mapped wells expose `data-mapping-index` / `data-pair={index % 8}` (kept for host CSS); pending `.active` only on the selected source.
+- Rows: `data-state="empty|mapped|needsResolve|needsLookup|conflict"`, `data-property-name`, `data-resolve`, `data-required`, `data-source-kind`.
+
+Sync `applyMapping` preview lists pending **extract/file** edges under `_pendingResolve`. Lookup refs from stored entries appear in the bag.
+
+See [FIELD_MAPPER_REDESIGN.md](../../docs/FIELD_MAPPER_REDESIGN.md) for the row-layout design study (Phases 1–5 shipped). PermaPress: [FIELD_MAPPER_PERMAPRESS_HANDOFF.md](../../docs/FIELD_MAPPER_PERMAPRESS_HANDOFF.md).
+
 ## Relationship to `FeedFieldManifest`
 
 | Type | Package | Meaning |
 |------|---------|---------|
-| `FieldMapping` / `MappingDocument` | `@seedprotocol/mapping` | Source id → **model property name** |
-| `FeedFieldManifest` | `@seedprotocol/sdk` | Property/key → **role** (`image` / `html` / `text`) for `normalizeFeedItemFields` |
+| `FieldMapping` / `MappingDocument` | `@seedprotocol/mapping` | Source id → **model property name** (1→N edges; optional `resolve`; optional `lookup.entries`) |
+| `FeedFieldManifest` | `@seedprotocol/sdk` | Property/key → **role** (`image` / `audio` / `video` / `file` / `html` / `text`) for display |
 
-Compose them: map external fields into a plain item, then optionally normalize roles for media/HTML display.
+Compose them: map + resolve into a plain item, then optionally normalize roles for media/HTML display. Storage stays `Image` / `File` schema types — no separate Audio/Video dataTypes.
 
-## Phase 1 limits
+## Limits
 
 - Markdown: flat YAML frontmatter; `#` / `##` sections only
-- RSS: top-level item fields via `parseRssString` (no general XPath)
-- UI: self-contained dark theme; no desktop/Tailwind coupling
+- RSS: top-level item fields via `parseRssString` (no general XPath); structured enclosure / media:content
+- UI: self-contained dark theme (or `theme="none"` / `"structural"` for host paint); `layout` defaults to `rows` (`wires` deprecated); no desktop/Tailwind coupling; no media preview player
 
-See [MAPPING_PHASE2.md](../../docs/MAPPING_PHASE2.md) for consumer migration and hardening.
+See [MAPPING_PHASE2.md](../../docs/MAPPING_PHASE2.md) for remaining consumer work (desktop migration, npm publish), [FIELD_MAPPER_REDESIGN.md](../../docs/FIELD_MAPPER_REDESIGN.md) for the row-layout study, and [FIELD_MAPPER_PERMAPRESS_HANDOFF.md](../../docs/FIELD_MAPPER_PERMAPRESS_HANDOFF.md) for PermaPress.

package/dist/adapters/rss.d.ts

@@ -8,7 +8,8 @@ export type ParsedRssChannel = {
 };
 /**
  * Flatten a parsed RSS/Atom item into SourceNodes (one per string-coercible key).
- * Stable ids: `rss-{key}`.
+ * Enclosure / media:content become url + type in `meta` (not stringified objects).
+ * Stable ids: `rss-{key}`, `rss-enclosure-0`, …
  */
 export declare function rssItemToSources(item: Record<string, unknown>): SourceNode[];
 export type RssXmlSourcesResult = {

package/dist/adapters/rss.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rss.d.ts","sourceRoot":"","sources":["../../src/adapters/rss.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE1C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;CACjC,CAAA;AAiED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,EAAE,CAoB5E;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE;QACP,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,CAAA;IACD,0DAA0D;IAC1D,KAAK,EAAE,UAAU,EAAE,EAAE,CAAA;CACtB,CAAA;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,mBAAmB,CAAC,CAU9B"}
+{"version":3,"file":"rss.d.ts","sourceRoot":"","sources":["../../src/adapters/rss.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,UAAU,CAAA;AAE1C,MAAM,MAAM,gBAAgB,GAAG;IAC7B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,kEAAkE;IAClE,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAA;CACjC,CAAA;AA8JD;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,UAAU,EAAE,CAoD5E;AAED,MAAM,MAAM,mBAAmB,GAAG;IAChC,OAAO,EAAE;QACP,KAAK,CAAC,EAAE,MAAM,CAAA;QACd,IAAI,CAAC,EAAE,MAAM,CAAA;QACb,WAAW,CAAC,EAAE,MAAM,CAAA;KACrB,CAAA;IACD,0DAA0D;IAC1D,KAAK,EAAE,UAAU,EAAE,EAAE,CAAA;CACtB,CAAA;AAED;;;GAGG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,mBAAmB,CAAC,CAU9B"}

package/dist/applyMapping.d.ts

@@ -1,4 +1,4 @@
-import type { FieldMapping, PropertyBag, SourceNode, TargetProperty } from './types';
+import type { ApplyMappingAsyncResult, FieldMapping, MappingLookups, PropertyBag, ResolveCallback, SourceNode, TargetProperty } from './types';
 /**
  * Coerce a raw string value to the Seed model property dataType.
  */
@@ -6,6 +6,25 @@ export declare function coerceValue(rawValue: string, dataType: string): unknown
 /**
  * Apply field mappings to produce a property bag for createItem / publish.
  * Missing sources or unknown target properties are skipped (no throw).
+ * `resolve: 'extract' | 'file'` edges are skipped — use `applyMappingAsync`.
+ * `resolve: 'lookup'` is applied from stored entries (or deprecated document lookups).
  */
-export declare function applyMapping(sources: SourceNode[], mappings: FieldMapping[], targets: TargetProperty[]): PropertyBag;
+export declare function applyMapping(sources: SourceNode[], mappings: FieldMapping[], targets: TargetProperty[], options?: {
+    lookups?: MappingLookups;
+}): PropertyBag;
+export type ApplyMappingAsyncOptions = {
+    /** Required for extract/file edges. Not called for lookup. */
+    resolve?: ResolveCallback;
+    /**
+     * String → seed uid dictionaries keyed by property name.
+     * @deprecated Prefer `FieldMapping.lookup.entries`. Read as a fallback only.
+     */
+    lookups?: MappingLookups;
+};
+/**
+ * Async apply: copy+coerce plain edges; apply lookup entries; for extract/file
+ * call the host callback then coerce. Partial success — failed resolve edges
+ * are listed in `errors` and omitted from `properties`.
+ */
+export declare function applyMappingAsync(sources: SourceNode[], mappings: FieldMapping[], targets: TargetProperty[], options?: ApplyMappingAsyncOptions): Promise<ApplyMappingAsyncResult>;
 //# sourceMappingURL=applyMapping.d.ts.map

package/dist/applyMapping.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"applyMapping.d.ts","sourceRoot":"","sources":["../src/applyMapping.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EACZ,WAAW,EACX,UAAU,EACV,cAAc,EACf,MAAM,SAAS,CAAA;AAEhB;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAuBvE;AAED;;;GAGG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,UAAU,EAAE,EACrB,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,cAAc,EAAE,GACxB,WAAW,CAeb"}
+{"version":3,"file":"applyMapping.d.ts","sourceRoot":"","sources":["../src/applyMapping.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EACV,uBAAuB,EACvB,YAAY,EACZ,cAAc,EACd,WAAW,EACX,eAAe,EAEf,UAAU,EACV,cAAc,EAEf,MAAM,SAAS,CAAA;AAEhB;;GAEG;AACH,wBAAgB,WAAW,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAuBvE;AA8DD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,OAAO,EAAE,UAAU,EAAE,EACrB,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,cAAc,EAAE,EACzB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,cAAc,CAAA;CAAE,GACrC,WAAW,CA4Bb;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,8DAA8D;IAC9D,OAAO,CAAC,EAAE,eAAe,CAAA;IACzB;;;OAGG;IACH,OAAO,CAAC,EAAE,cAAc,CAAA;CACzB,CAAA;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,OAAO,EAAE,UAAU,EAAE,EACrB,QAAQ,EAAE,YAAY,EAAE,EACxB,OAAO,EAAE,cAAc,EAAE,EACzB,OAAO,GAAE,wBAA6B,GACrC,OAAO,CAAC,uBAAuB,CAAC,CAwFlC"}