@cbortech/cbor 0.27.0 → 0.27.2

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.
  *
@@ -153,8 +341,10 @@ export declare abstract class CborItem {
      * (`h'...'`, `b64'...'`, ...) depends on the `sqstr` option.
      *
      * This method deliberately does *not* also cover the "is this (or does
-     * it wrap) a prefixed literal" question — a prefixed literal has no word
-     * count to check, but still disqualifies under the strict rule (and, per
+     * it wrap) a prefixed literal" question — a byte-string literal has no
+     * word count to check, and an app-string literal (`dt'...'`) is
+     * word-counted from its rendered content, but either disqualifies only
+     * under the strict rule (and, per
      * `strict`, is an ordinary leaf under the loose one). That's handled
      * generically elsewhere instead, from the *actual rendered text* rather
      * than predicted from this node's type: `isPrefixedLiteralText` for a
@@ -178,8 +368,32 @@ 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;
+    /**
+     * @internal
+     * Optional override: an alternate plain-string spelling to use as this
+     * node's `toJS()` object key, in place of `CborMap.toObject()`'s generic
+     * `toCDN()` fallback for a non-text-string key. Returns `undefined` to use
+     * that default. The base class implements no such override; a subclass
+     * that carries an alternate key spelling for a non-text key (e.g. a CDDL
+     * e-ref annotated integer key — see `extensions/eref.ts`) overrides this
+     * instead of `CborMap` special-casing that subclass directly. Takes the
+     * full `ToJSOptions` (unlike `_toCDN`'s options) since a key-naming choice
+     * like e-ref's `eRefKeys` is a `toJS()`-only concept with no CDN analogue.
+     */
+    _jsObjectKey(_options: ToJSOptions | undefined): string | undefined;
     /** Serialize this node to CBOR binary. */
     toCBOR(options?: ToCBOROptions): Uint8Array;
     /** Serialize this node to a CDN text string. */
@@ -246,17 +460,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): string;
+    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.
+     */
+    _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 {
@@ -13,6 +13,14 @@ export declare class CborTag extends CborItem {
      * (`0x3e7`, decimal, …) when `preserveNumberFormat` is set.
      */
     ednSource?: string;
+    /**
+     * Set by `cddl`-validated decoding/parsing/conversion when the schema
+     * itself implies this tag at its position (see `cddl/implicitTags.ts`),
+     * so `toJS()` can leave it off the JS value — see
+     * `ToJSOptions.implicitTags`.
+     * @internal
+     */
+    _implicit: boolean;
     constructor(tag: number | bigint, content: CborItem, options?: {
         encodingWidth?: EncodingWidth;
         ednSource?: string;
@@ -44,9 +52,23 @@ 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;
+    /**
+     * The hex-dump comment for this tag's head: `Tag N`, followed by an
+     * RFC 9277 label when there is one — `Tag 55799 (self-described CBOR)`,
+     * `Tag 1668546929 (CoAP Content-Format 112)`, `Tag 1330664270 ("OPSN")`
+     * for a protocol-specific tag spelling four printable ASCII characters.
+     */
+    hexDumpComment(): string;
     _toHexDump(depth: number, options?: ToCDNOptions): AnnotatedLine[];
-    _toJS(options?: ToJSOptions): unknown;
+    _toJS(options?: ToJSOptions, path?: readonly unknown[], occurrence?: Occurrence): unknown;
+    /**
+     * Attach this tag to the converted content `value` — unless `stripTags`,
+     * or the tag is schema-implied (`_implicit`) and `implicitTags` isn't
+     * `false`.
+     * @internal
+     */
+    _tagJS(value: unknown, options?: ToJSOptions): unknown;
 }

package/dist/ast/CborTextString.d.ts

@@ -57,8 +57,8 @@ export declare class CborTextString extends CborItem {
             end: number;
         }[];
     });
-    _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/CborUint.d.ts

@@ -17,6 +17,6 @@ export declare class CborUint extends CborItem {
         ednSource?: 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/CborUnresolvedAppExt.d.ts

@@ -12,5 +12,14 @@ export declare const CPA999_TAG = 999n;
  */
 export declare class CborUnresolvedAppExt extends CborTag {
     constructor(prefix: string, items: CborItem[]);
+    /** App-string form (`prefix'text'`), as opposed to an app-sequence. */
+    private get _isAppString();
+    /**
+     * An app-string (`e'alg'`) renders as a plain literal, not the
+     * `[prefix, text]` array it wraps, so it's a leaf for
+     * `inlineLeafContainers` — word-counted like a text string instead (via
+     * `CborTag._isMultiWordText`'s tokenizing of the rendered output).
+     */
+    get _containsCdnContainer(): boolean;
     _toCDN(options: ToCDNOptions | undefined, depth: number): string;
 }

package/dist/ast/index.cjs

@@ -1 +1 @@
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../mapEntries-C1f7G0AM.cjs");exports.CborArray=e.E,exports.CborBigNint=e._,exports.CborBigUint=e.v,exports.CborByteString=e.k,exports.CborEmbeddedCBOR=e.C,exports.CborFloat=e.j,exports.CborIndefiniteByteString=e.O,exports.CborIndefiniteTextString=e.D,exports.CborItem=e.F,exports.CborMap=e.T,exports.CborNint=e.N,exports.CborSimple=e.w,exports.CborTag=e.A,exports.CborTextString=e.h,exports.CborUint=e.P;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../mapEntries-DwHPAzCN.cjs");exports.CborArray=e.I,exports.CborBigNint=e.O,exports.CborBigUint=e.k,exports.CborByteString=e.z,exports.CborEmbeddedCBOR=e.N,exports.CborFloat=e.V,exports.CborIndefiniteByteString=e.R,exports.CborIndefiniteTextString=e.L,exports.CborItem=e.W,exports.CborMap=e.F,exports.CborNint=e.H,exports.CborSimple=e.P,exports.CborTag=e.B,exports.CborTextString=e.E,exports.CborUint=e.U;

package/dist/ast/index.js

@@ -1,2 +1,2 @@
-import { A as e, C as t, D as n, E as r, F as i, N as a, O as o, P as s, T as c, _ as l, h as u, j as d, k as f, v as p, w as m } from "../mapEntries-CvLdiN0h.js";
-export { r as CborArray, l as CborBigNint, p as CborBigUint, f as CborByteString, t as CborEmbeddedCBOR, d as CborFloat, o as CborIndefiniteByteString, n as CborIndefiniteTextString, i as CborItem, c as CborMap, a as CborNint, m as CborSimple, e as CborTag, u as CborTextString, s as CborUint };
+import { B as e, E as t, F as n, H as r, I as i, L as a, N as o, O as s, P as c, R as l, U as u, V as d, W as f, k as p, z as m } from "../mapEntries-8zshEr-t.js";
+export { i as CborArray, s as CborBigNint, p as CborBigUint, m as CborByteString, o as CborEmbeddedCBOR, d as CborFloat, l as CborIndefiniteByteString, a as CborIndefiniteTextString, f as CborItem, n as CborMap, r as CborNint, c as CborSimple, e as CborTag, t as CborTextString, u as CborUint };

package/dist/cbor/tagLabels.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Human-readable labels for tag numbers defined by RFC 9277 (On Stable
+ * Storage for Items in CBOR), used to annotate `Tag N` hex-dump comments.
+ */
+/**
+ * Inverse of RFC 9277 Appendix B's `TN(ct) = 0x63740101 + (ct / 255) *
+ * 256 + ct % 255`: returns the CoAP Content-Format number `tag` stands for, or
+ * `undefined` when `tag` isn't in that range. The mapping never produces a
+ * zero byte, so a tag with a zero in either of its low two bytes isn't one.
+ */
+export declare function coapContentFormatOfTag(tag: bigint): number | undefined;
+/**
+ * The four ASCII characters spelled by a protocol-specific tag number
+ * (RFC 9277 §2.1 encourages a mnemonic of four ASCII codes, e.g.
+ * `1330664270` = `0x4F50534E` = `"OPSN"`), or `undefined` when `tag` is
+ * outside `0x01000000`..`0xFFFFFFFF` or any byte isn't printable ASCII
+ * (`0x20`..`0x7E`).
+ */
+export declare function asciiMnemonicOfTag(tag: bigint): string | undefined;
+/**
+ * RFC 9277 label for `tag`, for a hex-dump comment — `self-described CBOR`,
+ * `CoAP Content-Format 112`, `"OPSN"` — or `undefined` when there's none.
+ * The CoAP range is checked before the ASCII mnemonic: it is a specific
+ * allocation, and its `"ct"` prefix would otherwise read as a mnemonic.
+ */
+export declare function rfc9277TagLabel(tag: bigint): string | undefined;