@cbortech/cbor 0.27.0 → 0.27.1

package/README.ja.md

@@ -708,6 +708,79 @@ console.log(text);
 // DT'2026-05-06T00:00:00Z'
 ```
 
+### 項目ごとのオプション上書き
+
+`toJS()` の `itemOptions` は、各ノードが変換される直前にすべてのノードに対して呼ばれるため、
+ドキュメントの一部だけを他と異なる方法で変換できます。そのノードとその子孫に適用する
+オプションを部分的なオプションオブジェクトとして返すか、変更しない場合は `undefined` を
+返します。`ctx.path` は配列インデックスとマップキーからなる列でノードを識別し、
+ルートでは空になります。
+
+同じノードに対して複数回呼ばれることがあります —— `reviver` も併用している場合、配列や
+object-mode の map は各子要素を少なくとも2回変換します。1回は、先行する兄弟要素自身の
+`reviver` 呼び出しから見える値を構築するため、もう1回は実際に保持される値を計算するため
+です。このコールバックは `node`/`ctx` のみに依存する純粋関数として書き、呼ばれる回数には
+依存しないようにしてください。
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const item = CBOR.fromCDN(
+  `{"date1": DT'2026-08-23T00:00:00Z', "date2": DT'2026-08-23T00:00:00Z'}`
+);
+
+const value = item.toJS({
+  stripTags: true,
+  itemOptions: (_node, ctx) =>
+    ctx.path.length === 1 && ctx.path[0] === 'date1'
+      ? { extensions: [CBOR.dt_as_Date] }
+      : undefined,
+});
+
+console.log(value);
+// { date1: Date(...), date2: 1787443200 }
+```
+
+`ToJSOptions` の `extensions` は `itemOptions` なしでも単体で機能し、ツリー全体を
+再解釈できます —— デフォルトの `dt` extension でパースされた値も、`toJS()` に
+`extensions` を渡すことで `dt_as_Date`（またはその逆）に変換し直せます。
+
+`ctx.options` には、そのノードにおいて現在有効なオプション —— ルートのオプションに
+祖先の `itemOptions` がすでに返した上書きをマージしたもの —— が渡されます。これにより、
+コールバックはオプションを丸ごと置き換えるのではなく、現在の値を土台にして組み立てる
+ことができます。
+
+```ts
+itemOptions: (_node, ctx) => ({
+  extensions: [...(ctx.options.extensions ?? []), CBOR.dt_as_Date],
+});
+```
+
+`toCDN()` にも同じ `itemOptions` オプションがあり、ドキュメントの一部だけを
+他と異なる方法でフォーマットできます。
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const item = CBOR.fromCDN('{"raw": 255, "count": 255}');
+
+const text = item.toCDN({
+  itemOptions: (_node, ctx) =>
+    ctx.path.length === 1 && ctx.path[0] === 'raw'
+      ? { intFormat: 'hex' }
+      : undefined,
+});
+
+console.log(text);
+// {"raw":0xff,"count":255}
+```
+
+`toCDN()` には `reviver` に相当するものがないため、それを理由に複数回呼ばれる
+ことはありません —— ただし `toCDN()` 自体のレイアウト判定（`inlineLeafContainers`
+の1行収まるかの判定、あるいはタグ/app-sequence 値自身の複数語判定）が実際の
+出力より前にエントリを再描画してその答えを得ることがあるため、その場合には
+やはり複数回呼ばれ得ます。こちらも純粋な関数として書いてください。
+
 ## 文字列連結と不定長文字列
 
 draft-ietf-cbor-edn-literals-27(§3.5 / §3.6)の app-extension

package/README.md

@@ -719,6 +719,81 @@ console.log(text);
 // DT'2026-05-06T00:00:00Z'
 ```
 
+### Per-item option overrides
+
+`itemOptions` on `toJS()` is called for every node before it is converted, so
+one part of a document can be converted differently from the rest. Return a
+partial options object to override options for that node and its descendants,
+or `undefined` to leave them unchanged. `ctx.path` identifies the node as a
+sequence of array indices and map keys, empty at the root.
+
+It can be called more than once for the same node — when a `reviver` is also
+present, arrays and object-mode maps convert each child at least twice: once
+to build a value visible to an earlier sibling's own `reviver` call, and once
+more for the value that's actually kept. Write it as a pure function of
+`node`/`ctx`, not relying on how many times it runs.
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const item = CBOR.fromCDN(
+  `{"date1": DT'2026-08-23T00:00:00Z', "date2": DT'2026-08-23T00:00:00Z'}`
+);
+
+const value = item.toJS({
+  stripTags: true,
+  itemOptions: (_node, ctx) =>
+    ctx.path.length === 1 && ctx.path[0] === 'date1'
+      ? { extensions: [CBOR.dt_as_Date] }
+      : undefined,
+});
+
+console.log(value);
+// { date1: Date(...), date2: 1787443200 }
+```
+
+`extensions` on `ToJSOptions` also works on its own, without `itemOptions`, to
+reinterpret an entire tree: a value parsed with the default `dt` extension can
+still be converted with `dt_as_Date` (or vice versa) by passing `extensions`
+directly to `toJS()`.
+
+`ctx.options` carries the options already in effect for the node — the root
+options merged with whatever an ancestor's `itemOptions` already returned —
+so a callback can build on the current value of an option instead of
+overriding it outright:
+
+```ts
+itemOptions: (_node, ctx) => ({
+  extensions: [...(ctx.options.extensions ?? []), CBOR.dt_as_Date],
+});
+```
+
+`toCDN()` takes the same `itemOptions` option, formatting one part of a
+document differently from the rest:
+
+```ts
+import { CBOR } from '@cbortech/cbor';
+
+const item = CBOR.fromCDN('{"raw": 255, "count": 255}');
+
+const text = item.toCDN({
+  itemOptions: (_node, ctx) =>
+    ctx.path.length === 1 && ctx.path[0] === 'raw'
+      ? { intFormat: 'hex' }
+      : undefined,
+});
+
+console.log(text);
+// {"raw":0xff,"count":255}
+```
+
+There is no `reviver` for `toCDN()`, so it can't be called more than once for
+that reason — but it can still be called more than once for a node that's
+also a `toCDN()` layout decision (`inlineLeafContainers`'s one-line collapse
+check, or a tag/app-sequence value's own multi-word check re-render an entry
+purely to answer that question before the real render). Write it as a pure
+function here too.
+
 ## String Concatenation and Indefinite-Length Strings
 
 The `t1` / `b1` / `ilbs` / `ilts` app-extensions from

package/dist/ast/CborAppSeqResult.d.ts

@@ -1,5 +1,5 @@
 import { ToCDNOptions, ToCBOROptions, ToJSOptions } from '../types';
-import { CborItem } from './CborItem';
+import { CborItem, Occurrence } from './CborItem';
 import { CborWriter } from '../cbor/encode';
 /**
  * Wraps a resolved app-sequence result and preserves the original EDN source
@@ -13,6 +13,39 @@ import { CborWriter } from '../cbor/encode';
  * lines also delegates to the inner item, since it cannot be re-emitted
  * without breaking the single-line guarantee.
  *
+ * When `toCDN()`'s `itemOptions` is configured (see `needsCdnItemDispatch`),
+ * the verbatim `ednSource` fast path alone can't be trusted: it was produced
+ * without ever visiting `this.inner`'s own descendants, so an override
+ * targeting one of them (e.g. one chunk of an `ilbs<<...>>`) would otherwise
+ * never even be offered the chance to apply. But merely *having* `itemOptions`
+ * configured must not by itself change the output — many callers set it
+ * without it ever matching anything in this particular subtree, and
+ * `itemOptions` returning `undefined` everywhere is documented to mean "no
+ * change" (see `CdnItemContext`). So this renders through the normal
+ * recursive path while tracking, via `CDN_OVERRIDE_TRACKER` (an out-of-band
+ * symbol key, *not* a wrapped `itemOptions` — wrapping it would make
+ * `ctx.options.itemOptions` a different function for every descendant here
+ * than everywhere else in the tree, observable even to a pure callback),
+ * whether any call in the subtree actually returned an override, and only
+ * swaps in that freshly rendered text when one did; otherwise the exact
+ * preserved `ednSource` is still returned.
+ *
+ * Each `_toCDN()` call installs its *own fresh* tracker box before
+ * recursing, rather than reusing whatever tracker it was handed — reusing
+ * one directly would let an override applied by some unrelated part of the
+ * tree that merely happens to share the same ambient `options` object (a
+ * later sibling reached through the same `itemOptions`, say) falsely mark
+ * *this* wrapper's own verbatim source as stale. But a genuinely *nested*
+ * app-sequence (e.g. a custom `wrap<<ilbs<<h'61'>>>>` extension wrapping an
+ * `ilbs<<...>>` result) must still have its own outer verbatim source
+ * abandoned when the inner wrapper's own tracked render found something to
+ * apply — an inner override changes what the outer source would need to
+ * embed too. So once this call's own local tracker comes back `applied`,
+ * that fact is additionally bubbled up to whichever ancestor tracker (if
+ * any) this call itself received via `options` — the exact wrapper this
+ * call is nested inside, never a sibling reached only through shared
+ * top-level `options`.
+ *
  * CBOR encoding and JS conversion always delegate to the inner item so the
  * wrapper is fully transparent for those operations.
  */
@@ -42,8 +75,8 @@ export declare class CborAppSeqResult extends CborItem {
      * already produced a `\n` in that string, which the caller's own
      * `s.includes('\n')` check picks up independently either way).
      */
-    _isMultiWordText(options: ToCDNOptions | undefined, strict?: boolean): boolean;
+    _isMultiWordText(options: ToCDNOptions | undefined, strict?: boolean, path?: readonly unknown[]): boolean;
     _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
-    _toCDN(options: ToCDNOptions | undefined, depth: number): string;
-    _toJS(options?: ToJSOptions): unknown;
+    _toCDN(options: ToCDNOptions | undefined, depth: number, path?: readonly unknown[]): string;
+    _toJS(options?: ToJSOptions, path?: readonly unknown[], occurrence?: Occurrence): unknown;
 }

package/dist/ast/CborArray.d.ts

@@ -12,7 +12,7 @@ export declare class CborArray extends CborItem {
     });
     get _containsCdnContainer(): boolean;
     _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
-    _toCDN(options: ToCDNOptions | undefined, depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, depth: number, path?: readonly unknown[]): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
-    _toJS(options?: ToJSOptions): unknown;
+    _toJS(options?: ToJSOptions, path?: readonly unknown[], occurrence?: readonly unknown[]): unknown;
 }

package/dist/ast/CborByteString.d.ts

@@ -63,8 +63,8 @@ export declare class CborByteString extends CborItem {
      * needed here at all now — it's accepted purely for interface
      * consistency with the base class.
      */
-    _isMultiWordText(options: ToCDNOptions | undefined, _strict?: boolean): boolean;
+    _isMultiWordText(options: ToCDNOptions | undefined, _strict?: boolean, _path?: readonly unknown[]): boolean;
     _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
-    _toCDN(options: ToCDNOptions | undefined, _depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, _depth: number, _path?: readonly unknown[]): string;
     _toJS(_options?: ToJSOptions): unknown;
 }

package/dist/ast/CborEmbeddedCBOR.d.ts

@@ -21,7 +21,7 @@ export declare class CborEmbeddedCBOR extends CborItem {
     /** The raw concatenated CBOR bytes of all contained items. */
     private _content;
     _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
-    _toCDN(options: ToCDNOptions | undefined, depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, depth: number, path?: readonly unknown[]): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
     _toJS(_options?: ToJSOptions): unknown;
 }

package/dist/ast/CborFloat.d.ts

@@ -48,6 +48,6 @@ export declare class CborFloat extends CborItem {
         literalSource?: string;
     });
     _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
-    _toCDN(options: ToCDNOptions | undefined, _depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, _depth: number, _path?: readonly unknown[]): string;
     _toJS(_options?: ToJSOptions): unknown;
 }

package/dist/ast/CborIndefiniteByteString.d.ts

@@ -32,7 +32,7 @@ export declare class CborIndefiniteByteString extends CborItem {
      * was removed there too).
      */
     _isMultiWordText(options: ToCDNOptions | undefined, _strict?: boolean): boolean;
-    _toCDN(options: ToCDNOptions | undefined, depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, depth: number, path?: readonly unknown[]): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
     _toJS(_options?: ToJSOptions): unknown;
 }

package/dist/ast/CborIndefiniteTextString.d.ts

@@ -24,7 +24,7 @@ export declare class CborIndefiniteTextString extends CborItem {
      * depend on it.
      */
     _isMultiWordText(options: ToCDNOptions | undefined, _strict?: boolean): boolean;
-    _toCDN(options: ToCDNOptions | undefined, depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, depth: number, path?: readonly unknown[]): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
     _toJS(_options?: ToJSOptions): unknown;
 }

package/dist/ast/CborItem.d.ts

@@ -1,4 +1,4 @@
-import { CBOROptions, ToCDNOptions, ToJSOptions, ToHexDumpOptions, ToCBOROptions, CborComment, CborComments, DecodeWarning, ParseWarning } from '../types';
+import { CBOROptions, ToCDNOptions, ToJSOptions, ToHexDumpOptions, ToCBOROptions, CborComment, CborComments, DecodeWarning, ParseWarning, ItemContext, ReadonlyToJSNodeOptions, CdnItemContext, ReadonlyToCDNOptions } from '../types';
 import { CborWriter } from '../cbor/encode';
 /** @internal One line of an annotated hex dump. */
 export interface AnnotatedLine {
@@ -27,6 +27,194 @@ export interface AppSeqSourceFeatures {
     rawString?: boolean;
     concatenation?: boolean;
 }
+/**
+ * @internal
+ * Cheap upfront check for whether per-node option/extension resolution is
+ * needed at all for a given `toJS()` options object. Container nodes use
+ * this to choose between the plain `child._toJS(options)` recursion (when
+ * `false`, identical cost to before `itemOptions`/`extensions` existed) and
+ * `child._toJSChild(options, path, ctx)` (when `true`).
+ */
+export declare function needsItemDispatch(options: ToJSOptions | undefined): boolean;
+/**
+ * @internal
+ * Options for a reviver-driven container's "raw" structural pre-population
+ * pass (see `CborArray`/`CborMap.toObject`) — `reviver` removed, everything
+ * else (including `itemOptions`/`extensions`) left as-is.
+ *
+ * This pass's output is never returned to the caller as the final result —
+ * every position it computes is unconditionally overwritten by the *real*
+ * (revived) pass's own result before `toJS()` returns — but it is not
+ * write-only scaffolding either: a `reviver` reads it directly, as `this[j]`
+ * for a not-yet-processed sibling `j`, while deciding how to revive an
+ * *earlier* sibling (matching `JSON.parse`'s own reviver contract, which
+ * this replicates). That value must reflect `itemOptions`/`extensions`
+ * exactly as the real pass would — e.g. an `integerAs: 'bigint'` override
+ * for position `j` — or a reviver reading `this[j]` would see the wrong
+ * type. So `itemOptions`/`extensions` stay active here, unlike `reviver`
+ * itself.
+ *
+ * Running dispatch during this pass is safe only because callers building
+ * a child's occurrence for it — `CborArray`/`CborMap.toObject` — insert
+ * `RAW_PASS_MARKER` into that occurrence (see `Occurrence`), so its
+ * resolutions are filed under a different `DispatchCache` key than the
+ * real pass's and can never be reused *by* the real pass, however many
+ * ancestor levels apart the two passes are. That distinction matters for
+ * more than consistency — a composite (non-scalar) map key is itself
+ * revived differently between the two passes (this pass leaves its own
+ * nested content entirely unrevived, matching `this[j]`'s contract above;
+ * the real pass revives it normally), so a value node whose
+ * `ItemContext.path` is built from that key's converted JS value would
+ * otherwise see a stale, pre-revival path if the real pass reused this
+ * pass's cached decision.
+ */
+export declare function withoutReviver(options: ToJSOptions | undefined): ToJSOptions | undefined;
+/**
+ * @internal
+ * Build the `reviver`-free, `extensions`-copied view of `options` handed
+ * to code that must not be able to mutate options actually in effect
+ * elsewhere in the tree — `ItemContext.options` and the `options`
+ * parameter of `CborExtension.toJS()` — see `ReadonlyToJSNodeOptions`.
+ *
+ * A plain `{ ...options, reviver: undefined }` spread (as `withoutReviver`
+ * does) is not enough here: `extensions`, if present, would still be the
+ * *same array* `options.extensions` is, so `.push()`/`.splice()`/etc. on
+ * the copy would still mutate the original in place — corrupting it for
+ * this node's own later use, its siblings, and the caller. `extensions` is
+ * the only field on `ToJSOptions` that's an ordinary mutable container, so
+ * it's the only one that needs its own copy here.
+ */
+export declare function toReadonlyNodeOptions(options: ToJSOptions): ReadonlyToJSNodeOptions;
+/**
+ * @internal
+ * Stable, allocation-light identifier for "this occurrence of a node" —
+ * used only to key `DispatchCache` lookups, never exposed via
+ * `ItemContext`. Built exactly the way `ItemContext.path` is (accumulated
+ * from the root, one element per container level, unchanged through a
+ * tag/app-sequence wrapper), but from *structural* container positions —
+ * an array index, or a map entry's ordinal paired with a `'k'`/`'v'` role
+ * tag (see `CborArray`/`CborMap`) — rather than from the JS values `path`
+ * is built from.
+ *
+ * That distinction matters in two ways `path` alone (or even `path` plus
+ * only the *immediate* container's identity) does not cover:
+ *
+ * - A composite (non-scalar) map key re-converts to a *new* array/object
+ *   every time its JS value is asked for, so two visits to the very same
+ *   logical position produce `path`s that are structurally equal but not
+ *   reference-equal at that segment — unusable for matching.
+ * - Two different positions can legitimately produce the very same `path`,
+ *   when duplicate map entries carry equal keys (e.g. two `"a"` entries).
+ * - A *container* (not just a leaf) can itself be a shared node instance
+ *   reused at two positions (e.g. the same `CborArray` placed at two
+ *   different indices of an outer array). Matching only on `{immediate
+ *   parent identity, local slot}` — as an earlier version of this type
+ *   did — correctly distinguishes the *container's own* two occurrences,
+ *   but not its *descendants'*: each of the shared container's children
+ *   would resolve `{parent: <the shared container>, slot: <local index>}`
+ *   identically regardless of which of the container's own two
+ *   occurrences was being converted, silently conflating them. Chaining
+ *   the full occurrence from the root — rather than just one level —
+ *   avoids this: the shared container's own two occurrences differ
+ *   earlier in the chain, so appending the same local slot to each still
+ *   yields two different full chains for its children.
+ *
+ * A local slot only needs to be unique among its own container's direct
+ * children — `CborArray` uses the element index (`number`) directly;
+ * `CborMap` prefixes a map entry's ordinal with `'k'`/`'v'`
+ * (`` `k${i}` ``/`` `v${i}` ``) so a key and its own value, which share an
+ * ordinal, don't collide.
+ *
+ * `RAW_PASS_MARKER` (see below) is the one non-structural element this
+ * chain can contain: `CborArray`/`CborMap.toObject` insert it — once,
+ * immediately before that level's own local slot — only when building a
+ * child's occurrence for their raw structural pre-population pass (see
+ * `withoutReviver`), never for the real, revived pass. That's what lets
+ * `_toJSChild`'s cache correctly tell apart the *distinct* raw-pass
+ * resolutions a single occurrence can otherwise receive when more than one
+ * ancestor level forks — e.g. the very same value node visited once
+ * through an outer container's own raw pass (before *any* ancestor has
+ * revived anything) and once more through a different, inner container's
+ * own raw pass nested inside the outer's real pass (after some ancestor,
+ * such as a composite map key, *has* already been revived) — two visits
+ * that share every structural coordinate yet must not share a cached
+ * decision, since what a reviver-sensitive value like that key converts to
+ * differs between them (see `DispatchCacheEntry`). A container that isn't
+ * itself forking (no `reviver` in its own options, so it takes the plain,
+ * unsplit path) never inserts the marker — it simply passes the
+ * occurrence chain it was given through unchanged before extending it with
+ * its own children's local slots, the same way it always did.
+ */
+export type Occurrence = readonly unknown[];
+/**
+ * @internal
+ * Sentinel inserted into an `Occurrence` chain by `CborArray`/
+ * `CborMap.toObject` when building a child's occurrence for their own raw
+ * structural pre-population pass — see `Occurrence`'s own note. A
+ * dedicated symbol rather than a string/number so it can never collide
+ * with an ordinary local slot value (an array index or a `` `k${i}` ``/
+ * `` `v${i}` `` map-entry tag).
+ */
+export declare const RAW_PASS_MARKER: unique symbol;
+/**
+ * @internal
+ * The root value's occurrence, for `toJS()`'s own top-level `_toJSChild()`
+ * call — empty, the same way `ItemContext.path` is empty at the root. Also
+ * used by `CborTag`/`CborAppSeqResult` as a defensive fallback if `_toJS()`
+ * is ever invoked without an `occurrence` (only possible via a direct,
+ * non-`toJS()` call to `_toJS()`, which the dispatch cache never sees).
+ */
+export declare const ROOT_OCCURRENCE: Occurrence;
+/**
+ * @internal
+ * Cheap upfront check for whether per-node option resolution is needed at
+ * all for a given `toCDN()` options object — the `toCDN()` analogue of
+ * `needsItemDispatch`.
+ */
+export declare function needsCdnItemDispatch(options: ToCDNOptions | undefined): boolean;
+/**
+ * @internal
+ * Build the copied-`textStringFormat` view of `options` handed to
+ * `CdnItemContext.options` — the `toCDN()` analogue of
+ * `toReadonlyNodeOptions`; see `ReadonlyToCDNOptions`. Also strips
+ * `CDN_OVERRIDE_TRACKER` (see there) — `ctx.options` is documented as
+ * reflecting the current *effective options*, so it should never expose an
+ * internal, out-of-band bookkeeping key that isn't part of `ToCDNOptions` at
+ * all, even though it isn't otherwise observable through any named field.
+ */
+export declare function toReadonlyCdnOptions(options: ToCDNOptions): ReadonlyToCDNOptions;
+/**
+ * @internal
+ * Out-of-band symbol key that lets a caller (currently only
+ * `CborAppSeqResult._toCDN`) track, across an entire `_resolveCdnOptions()`
+ * subtree, whether `itemOptions` ever actually returned an override —
+ * without touching `options.itemOptions` itself.
+ *
+ * `CborAppSeqResult` needs to know whether its preserved verbatim source is
+ * still exactly right after offering `itemOptions` a chance to override one
+ * of its descendants (see its own doc). Wrapping `options.itemOptions` in a
+ * tracking function was tried first, but that function becomes
+ * `ctx.options.itemOptions` for every descendant (`_resolveCdnOptions`
+ * builds `ctx.options` from the very `options` it was given) — a pure
+ * `itemOptions` callback could tell it apart from the caller's own function
+ * by identity, observing a difference between an ordinary subtree and one
+ * reached through an app-sequence wrapper that `ctx.options`'s "current
+ * effective options" contract never promises.
+ *
+ * A symbol-keyed property on `options` instead survives every
+ * `{...options, ...override}` merge `_resolveCdnOptions` performs exactly
+ * the same way `itemOptions` itself does (object spread copies symbol keys
+ * too, and by reference — the same tracker box is shared, never cloned, by
+ * every node in the subtree), while never being part of the public
+ * `ToCDNOptions` shape or observable through any named field — see
+ * `toReadonlyCdnOptions`, which explicitly strips it before building
+ * `ctx.options`.
+ */
+export declare const CDN_OVERRIDE_TRACKER: unique symbol;
+/** @internal Mutable box referenced (never copied) via `CDN_OVERRIDE_TRACKER`. */
+export interface CdnOverrideTrackerBox {
+    applied: boolean;
+}
 /**
  * Abstract base class for all CBOR AST nodes.
  *
@@ -178,8 +366,19 @@ export declare abstract class CborItem {
      * string's, or byte string's own sqstr-text, word count is unaffected by
      * it either way) — only `CborTag` (and, transitively, `CborAppSeqResult`
      * delegating to its inner value) actually consult it.
+     *
+     * `path` is this entry's own full path (see `CdnItemContext.path`),
+     * passed down by the same caller for the same reason `renderEntry`
+     * receives it: `CborTag`/`CborAppSeqResult` re-render `this` here (see
+     * their own overrides) purely to answer this method's question, and that
+     * re-render must resolve any of *its own* descendants' `itemOptions`
+     * against the entry's real path — not an empty one — or a descendant
+     * several levels inside a tag-wrapped entry could see a different
+     * `ctx.path` here than the real render further down gives it. Only
+     * `CborTag`/`CborAppSeqResult` consult it; every other override ignores
+     * it, the same as `strict`.
      */
-    _isMultiWordText(_options: ToCDNOptions | undefined, _strict?: boolean): boolean;
+    _isMultiWordText(_options: ToCDNOptions | undefined, _strict?: boolean, _path?: readonly unknown[]): boolean;
     /** Serialize this node to CBOR binary. */
     toCBOR(options?: ToCBOROptions): Uint8Array;
     /** Serialize this node to a CDN text string. */
@@ -246,17 +445,108 @@ export declare abstract class CborItem {
      * @internal
      * Depth-aware CDN serialization.
      * Leaf nodes receive `depth` but may ignore it.
-     * Container nodes use `depth` for indentation and call
-     * `child._toCDN(options, depth + 1)` when recursing.
+     * Container nodes use `depth` for indentation and, when recursing, must
+     * resolve each child's options via `child._resolveCdnOptions()` first
+     * (rather than passing `options` straight through) so `itemOptions` is
+     * honored for every node, not just the root — see `_resolveCdnOptions`.
+     * `path` is this node's own full path from the root (see
+     * `CdnItemContext.path`); only meaningful when `needsCdnItemDispatch()`
+     * is `true` for the options in effect — leaf implementations that don't
+     * recurse can ignore it, as can any implementation when dispatch isn't
+     * in play.
+     */
+    abstract _toCDN(options: ToCDNOptions | undefined, depth: number, path?: readonly unknown[]): string;
+    /**
+     * @internal
+     * Resolve `options.itemOptions` for this node (if any), returning the
+     * options a caller should use for both this node's own `_toCDN()` call
+     * and (via `_isMultiWordText()`) any layout probe of it — see
+     * `CdnItemContext`. Unlike `toJS()`'s `_toJSChild()`, this never caches:
+     * see the "toCDN() per-item dispatch" note above `needsCdnItemDispatch`
+     * for why that's both unnecessary and, per this codebase's own prior
+     * experience with `CborTag._isMultiWordText`, unsafe here specifically.
+     *
+     * `ctx` follows the same "no `key`, derived from `path`'s last element"
+     * convention `_toJSChild()` uses (see there) — a caller passes
+     * `parent`/`keyNode`/`isMapKey` only; `key` is filled in here.
      */
-    abstract _toCDN(options: ToCDNOptions | undefined, depth: number): string;
+    _resolveCdnOptions(options: ToCDNOptions | undefined, path: readonly unknown[], ctx: Omit<CdnItemContext, 'path' | 'key' | 'options'>): ToCDNOptions | undefined;
     /**
      * @internal
      * Core conversion logic implemented by each subclass.
-     * Container nodes apply `options.reviver` to their direct children.
+     * Container nodes apply `options.reviver` to their direct children, and
+     * must recurse via `child._toJSChild()` (never `child._toJS()` directly)
+     * so that `options.itemOptions`/`options.extensions` are honored for
+     * every node, not just the root — see `_toJSChild`.
+     * `path` is this node's own full path from the root (see `ItemContext.path`);
+     * only meaningful, and only ever non-empty, when `needsItemDispatch()` is
+     * `true` for the options in effect — leaf implementations that don't
+     * recurse can ignore it. `occurrence` is this node's own cache-matching
+     * identity (see `Occurrence`) — `CborArray`/`CborMap` build on it to
+     * derive their children's own occurrences, and `CborTag`/`CborAppSeqResult`
+     * pass it through unchanged to their content's `_toJSChild()` call; leaf
+     * implementations that don't recurse can ignore it.
      * Do not call this directly — use `toJS()` instead.
      */
-    abstract _toJS(options?: ToJSOptions): unknown;
+    abstract _toJS(options?: ToJSOptions, path?: readonly unknown[], occurrence?: Occurrence): unknown;
+    /**
+     * @internal
+     * Entry point container nodes must use when recursing into a child during
+     * `toJS()`, instead of calling `child._toJS(options)` directly, so that
+     * `options.itemOptions` and `options.extensions` (toJS hooks) are honored
+     * for every node in the tree, not just the root.
+     *
+     * Guarded by `needsItemDispatch()` at each call site rather than
+     * internally, so that containers can skip straight to the cheap
+     * `child._toJS(options)` call — matching pre-`itemOptions` behavior
+     * exactly, with no extra allocation — whenever neither option is in play
+     * for the whole conversion.
+     *
+     * `path` is this child's own full path from the root, already computed by
+     * the caller: `[...parentPath, key]` for an array element or map
+     * entry/key, or the parent's own `path` unchanged for a transparent
+     * wrapper's content (`CborTag`, `CborAppSeqResult`) — see
+     * `ItemContext.path`. `ctx.key` is *not* supplied by the caller — it's
+     * derived here from `path`'s own last element (or left `undefined` for
+     * the root and for `isMapKey` visits), which is what keeps a wrapper's
+     * content correctly reporting its outer key: since `CborTag`/
+     * `CborAppSeqResult` pass their own unmodified `path` straight through,
+     * that derivation naturally recovers the tag's own key for its content
+     * too, matching `ItemContext.key`'s documented invariant of always
+     * equalling `path`'s last element outside those two exceptions.
+     *
+     * `occurrence` identifies this child's position for cache-matching
+     * purposes only (see `Occurrence`) — deliberately separate from `path`,
+     * which is built from *converted JS values* and so is unreliable for
+     * that: matching on `path` alone either double-resolves the same position
+     * (a composite map key converts to a fresh, non-`===` array/object every
+     * time) or wrongly conflates two different positions that happen to
+     * convert to equal `path`s (duplicate map entries with equal keys).
+     * `occurrence` avoids both by construction — see `Occurrence`.
+     *
+     * A single node can be visited more than once *at the same occurrence* in
+     * one `toJS()` call — a `reviver`-driven `CborArray`/`CborMap` converts
+     * each child once to pre-populate an unrevived holder and once more to
+     * compute the revived value (see their own `_toJS()`), and either pass
+     * may itself recurse through a `CborTag`/`CborAppSeqResult` wrapper that
+     * adds no occurrence of its own (content shares the wrapper's). The raw
+     * pre-population pass's own occurrence for a child is distinguished from
+     * the real pass's by `RAW_PASS_MARKER` (see `Occurrence`), so that even
+     * distinct, *nested* raw passes reaching the same node — one from an
+     * outer container's own split, one from a different, inner container's
+     * own split nested inside the outer's real pass — resolve independently
+     * rather than colliding with each other. Neither `options.itemOptions`
+     * nor an `extensions` `toJS()` hook may run more than once for the same
+     * occurrence despite all that, since either may be stateful — so the
+     * *decision* (not the reviver-dependent application of an `itemOptions`
+     * override — see `DispatchOutcome`) is cached in `options`'s dispatch
+     * cache, when one is present, and reused on a later visit to that exact
+     * occurrence. A node *reused* at more than one occurrence (the same
+     * `CborItem` instance placed at two positions in a hand-built tree)
+     * still resolves once per occurrence, never conflating two different
+     * ones.
+     */
+    _toJSChild(options: ToJSOptions | undefined, path: readonly unknown[], occurrence: Occurrence, ctx: Omit<ItemContext, 'path' | 'key' | 'options'>): unknown;
     /**
      * @internal
      * Collect annotated-hex lines for this node.

package/dist/ast/CborMap.d.ts

@@ -12,7 +12,7 @@ export declare class CborMap extends CborItem {
     });
     get _containsCdnContainer(): boolean;
     _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
-    _toCDN(options: ToCDNOptions | undefined, depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, depth: number, path?: readonly unknown[]): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
-    _toJS(options?: ToJSOptions): unknown;
+    _toJS(options?: ToJSOptions, path?: readonly unknown[], occurrence?: readonly unknown[]): unknown;
 }

package/dist/ast/CborNint.d.ts

@@ -31,6 +31,6 @@ export declare class CborNint extends CborItem {
     /** The actual decoded negative value (−1 − argument). */
     get value(): bigint;
     _encodeTo(writer: CborWriter, _options?: ToCBOROptions): void;
-    _toCDN(options: ToCDNOptions | undefined, _depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, _depth: number, _path?: readonly unknown[]): string;
     _toJS(options?: ToJSOptions): unknown;
 }

package/dist/ast/CborTag.d.ts

@@ -1,5 +1,5 @@
 import { ToCDNOptions, ToJSOptions, ToCBOROptions } from '../types';
-import { CborItem, AnnotatedLine } from './CborItem';
+import { CborItem, AnnotatedLine, Occurrence } from './CborItem';
 import { CborWriter, EncodingWidth } from '../cbor/encode';
 /** CBOR Major Type 6 — tagged data item. */
 export declare class CborTag extends CborItem {
@@ -44,9 +44,9 @@ export declare class CborTag extends CborItem {
      * entry — an accepted, narrow cost (only tag-wrapped entries reach this
      * at all).
      */
-    _isMultiWordText(options: ToCDNOptions | undefined, strict?: boolean): boolean;
+    _isMultiWordText(options: ToCDNOptions | undefined, strict?: boolean, path?: readonly unknown[]): boolean;
     _encodeTo(writer: CborWriter, options?: ToCBOROptions): void;
-    _toCDN(options: ToCDNOptions | undefined, depth: number): string;
+    _toCDN(options: ToCDNOptions | undefined, depth: number, path?: readonly unknown[]): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
-    _toJS(options?: ToJSOptions): unknown;
+    _toJS(options?: ToJSOptions, path?: readonly unknown[], occurrence?: Occurrence): unknown;
 }