@cbortech/cbor 0.26.8 → 0.27.1

package/dist/types.d.ts

@@ -1,4 +1,5 @@
 import { CborExtension } from './extensions/types';
+import { CborItem } from './ast/CborItem';
 import { CddlSchema } from './cddl/schema';
 import { ValidateOptions as CddlValidateOptions } from './cddl/validator';
 import { CddlValidationError, CddlValidationWarning } from './cddl/errors';
@@ -14,6 +15,114 @@ import { CddlValidationError, CddlValidationWarning } from './cddl/errors';
  */
 export declare const CBOR_OMIT: unique symbol;
 export type { CborExtension } from './extensions/types';
+/**
+ * Context passed to an `itemOptions` callback (see `ToJSOptions.itemOptions`)
+ * describing where the node being visited sits in the tree.
+ */
+export interface ItemContext {
+    /**
+     * The direct parent AST node. `undefined` for the root value being
+     * converted. A tag or app-sequence wrapper is its content's `parent` —
+     * see `path` for how wrappers affect addressing.
+     */
+    parent?: CborItem;
+    /**
+     * The path segment identifying this node: an array index (`number`), or a
+     * map key's JS value (any type — CBOR keys are not limited to strings).
+     * Always equal to the last element of `path`, except `undefined` for the
+     * root value and while converting a map key itself (`isMapKey: true`),
+     * since a key has no path of its own — it names its sibling value's
+     * segment instead. A tag or app-sequence wrapper's content inherits the
+     * wrapper's own `key` (and `path`) unchanged, since the wrapper adds no
+     * segment of its own — see `path`.
+     */
+    key?: unknown;
+    /**
+     * The map key's own AST node, present when this node is a map entry's key
+     * or value — but *not* inherited into a tag/app-sequence wrapper's
+     * content the way `key`/`path` are, so it is only reliable at the map
+     * entry itself. Lets a callback inspect a non-scalar key structurally
+     * (e.g. via `keyNode._toCDN()`) instead of relying only on `key`'s
+     * computed JS value.
+     */
+    keyNode?: CborItem;
+    /**
+     * `true` when this invocation is for converting a map key itself, rather
+     * than one of that key's sibling value's descendants.
+     */
+    isMapKey?: boolean;
+    /**
+     * Path from the root to this node, as a sequence of array indices and map
+     * key JS values. Empty for the root value. A tag or app-sequence wrapper
+     * does not add a segment of its own — its content shares the wrapper's own
+     * path.
+     */
+    readonly path: readonly unknown[];
+    /**
+     * The options in effect for this node going into this call — i.e. the
+     * root options merged with whatever overrides its ancestors already
+     * returned, *before* this callback's own return value is merged on top.
+     * Read from this to build on the current value of an option (e.g. add an
+     * extension to whatever list is already in effect) instead of overriding
+     * it outright, or to make a decision based on an option's current value.
+     *
+     * A mutable-looking field here (currently just `extensions`) is a fresh
+     * copy, not the live array in effect elsewhere — mutating it in place
+     * (e.g. `ctx.options.extensions.push(ext)`) has no effect on this node,
+     * its siblings, or the caller's own options; return an override instead.
+     *
+     * Has no `reviver` — its type is `ReadonlyToJSNodeOptions`, not
+     * `ToJSOptions` — for the same reason this callback's own return value
+     * can't set one:
+     * since this callback may run more than once for the same node (see
+     * `ToJSOptions.itemOptions`), always reflecting only the reviver-
+     * independent options keeps what it reads consistent with what it can
+     * write, and keeps a callback that only inspects `options` pure across
+     * every one of those calls.
+     *
+     * @example
+     * // Add `dt_as_Date` to whatever extensions are already configured,
+     * // rather than replacing them.
+     * itemOptions: (_node, ctx) => ({
+     *   extensions: [...(ctx.options.extensions ?? []), dt_as_Date],
+     * })
+     */
+    readonly options: ReadonlyToJSNodeOptions;
+}
+/**
+ * `ToJSOptions` with `reviver` removed. Used wherever an API only ever
+ * needs to see the reviver-*independent* part of the options in effect for
+ * a node — an `itemOptions` callback's return value, and the `options`
+ * parameter of `CborExtension.toJS()` — because reviving the value a node
+ * converts to always happens afterwards, exactly once per visit, in the
+ * container holding it (see `CborArray`/`CborMap`); it is never something
+ * the conversion of the node itself should (or, for `CborExtension.toJS()`,
+ * even can) branch on. Keeping `reviver` out of both signatures — rather
+ * than merely documenting that it should be ignored — means neither can
+ * observe whether one is present, which is what makes it safe for a
+ * `reviver`-driven `CborArray`/`CborMap` to convert a child more than once
+ * (see `ToJSOptions.itemOptions`) without either one's result depending on
+ * *which* of those conversions it was called for.
+ */
+export type ToJSNodeOptions = Omit<ToJSOptions, 'reviver'>;
+/**
+ * `ToJSNodeOptions`, as handed to code that must not mutate it in place:
+ * `ItemContext.options` and the `options` parameter of
+ * `CborExtension.toJS()`. Both describe options actually in effect
+ * elsewhere in the tree, so mutating what's handed out here must not be
+ * able to reach that: reassigning a top-level property is a type error
+ * (`Readonly<...>`), and `extensions`, the one field on `ToJSOptions`
+ * that's an ordinary mutable array, is narrowed to a readonly array so an
+ * in-place mutation like `.push()` is one too. This only guards against
+ * *accidental* mutation via the type system — the implementation
+ * additionally hands out a fresh snapshot, with its own copy of
+ * `extensions`, on every call, so even a deliberate cast past this type
+ * can't corrupt what another node, sibling, hook, or pass sees (see
+ * `_toJSChild`'s `toReadonlyNodeOptions`).
+ */
+export type ReadonlyToJSNodeOptions = Readonly<Omit<ToJSNodeOptions, 'extensions'>> & {
+    readonly extensions?: readonly CborExtension[];
+};
 export interface ToHexDumpOptions {
     /**
      * Indentation per nesting level.
@@ -43,7 +152,7 @@ export interface ToJSOptions {
      * - `'object'`: always `Record<string, unknown>` — non-string keys are
      *   converted via `String()`. Duplicate keys are overwritten (last wins).
      * - `'entries'`: always `MapEntries` (a typed `Array` subclass) — preserves all
-     *   entries including duplicate keys (§2.6.3 of draft-ietf-cbor-edn-literals-25).
+     *   entries including duplicate keys (§2.4.2 of draft-ietf-cbor-edn-literals-27).
      *   `fromJS()` recognises `MapEntries` instances and converts them back to `CborMap`.
      * @default 'auto'
      */
@@ -80,6 +189,66 @@ export interface ToJSOptions {
      * @default false
      */
     undefinedOmits?: boolean;
+    /**
+     * Extension plugins consulted during `toJS()`, tried in order for every
+     * node before its own default conversion. An extension takes part by
+     * implementing `CborExtension.toJS()`; the first one to return a result
+     * for a given node wins and that node's own `_toJS()` is not called.
+     *
+     * Unlike the `extensions` option on `FromCDNOptions`/`FromCBOROptions`,
+     * this does not affect parsing — it only lets `toJS()` reinterpret nodes
+     * that a *different* extension configuration already produced. For
+     * example, a tree parsed with the plain `dt` extension (`DT'...'` →
+     * `number`) can still be converted with `dt_as_Date` selected here
+     * (`DT'...'` → `Date`), and vice versa — see `itemOptions` below to apply
+     * this to only part of a tree.
+     *
+     * There is no `builtinExtensions` equivalent for `toJS()`: leaving this
+     * unset (the default) keeps every node's own built-in conversion
+     * behavior, so no bundled extension needs to be "re-added" here just to
+     * get default output.
+     */
+    extensions?: CborExtension[];
+    /**
+     * Called for every node during `toJS()`, before that node is converted,
+     * to override the options used for its subtree. Return a partial options
+     * object to merge over the options in effect for this node (they apply to
+     * this node and are inherited by its descendants, who may override them
+     * again); return `undefined` to make no change.
+     *
+     * This is the mechanism for applying an option — including `extensions`,
+     * to select a different conversion for one node without affecting its
+     * siblings — to only part of a document, keyed off `ctx.path` or the
+     * node's own shape (`item instanceof ...`).
+     *
+     * **May be called more than once for the same AST node.** With a
+     * `reviver` present, `CborArray`/`CborMap` convert each child at least
+     * twice: once (with `reviver` itself withheld from the options this
+     * callback sees, though its own return value is honoured as normal) to
+     * build a holder a `reviver` call can inspect via `this[j]` for a
+     * not-yet-processed sibling `j`, and once more, for real, to compute the
+     * value the container actually keeps — and a node several levels down
+     * can in principle be offered to this callback more than twice, if a
+     * container at some intermediate level runs a pre-population pass of its
+     * own while itself sitting inside an *outer* container's. Each call is
+     * independent and reflects only the state relevant to *that* particular
+     * conversion (e.g. `ctx.path` for a value under a composite map key
+     * shows whatever that key currently converts to, which can differ
+     * between an earlier, not-yet-revived call and a later one after the
+     * key's own `reviver` has run). Write this callback as a pure function of
+     * `item`/`ctx` — it must not assume, or count, how many times it runs.
+     *
+     * @example
+     * // Convert only `date1` with `dt_as_Date`, leaving other DT values as
+     * // the epoch numbers the tree was originally parsed with.
+     * item.toJS({
+     *   itemOptions: (node, ctx) =>
+     *     ctx.path.length === 1 && ctx.path[0] === 'date1'
+     *       ? { extensions: [dt_as_Date] }
+     *       : undefined,
+     * });
+     */
+    itemOptions?: (item: CborItem, ctx: ItemContext) => Partial<ToJSNodeOptions> | undefined;
 }
 export interface ToCBOROptions {
 }
@@ -165,7 +334,7 @@ export interface FromCBOROptions {
      */
     extensions?: CborExtension[];
     /**
-     * Override the default set of bundled application-oriented extensions
+     * Override the default set of bundled app-extensions
      * (`dt`, `ip`, `cri`, `t1`, `b1`, `ilbs`, `ilts`, `float`).
      *
      * - omitted (default): use the standard bundled set.
@@ -173,13 +342,13 @@ export interface FromCBOROptions {
      * - `false`: disable all of them.
      *
      * `bignum` (tags 2/3) and embedded-CBOR (tag 24) support are core RFC 8949
-     * representation features, not application-oriented extensions, and are
-     * always active regardless of this option.
+     * representation features, not app-extensions, and are always active
+     * regardless of this option.
      *
-     * `dt`, `ip`, `t1`, and `b1` are mandatory-to-implement per §2.1 of
-     * draft-ietf-cbor-edn-literals-26; disabling them produces a decoder that
+     * `dt`, `ip`, `t1`, and `b1` are mandatory-to-implement per §3 of
+     * draft-ietf-cbor-edn-literals-27; disabling them produces a decoder that
      * no longer conforms to that recommendation. This is intended for
-     * allowlisting scenarios (see §7 Security considerations of the same
+     * allowlisting scenarios (see §8 Security considerations of the same
      * draft) where an application wants explicit control over which
      * extensions it accepts.
      */
@@ -254,7 +423,7 @@ export interface FromHexDumpOptions {
      */
     extensions?: CborExtension[];
     /**
-     * Override the default set of bundled application-oriented extensions.
+     * Override the default set of bundled app-extensions.
      * Mirrors `FromCBOROptions.builtinExtensions`.
      */
     builtinExtensions?: CborExtension[] | false;
@@ -332,7 +501,7 @@ export interface FromCDNOptions {
      */
     extensions?: CborExtension[];
     /**
-     * Override the default set of bundled application-oriented extensions
+     * Override the default set of bundled app-extensions
      * (`dt`, `ip`, `cri`, `t1`, `b1`, `ilbs`, `ilts`, `float`).
      *
      * - omitted (default): use the standard bundled set.
@@ -340,10 +509,10 @@ export interface FromCDNOptions {
      * - `false`: disable all of them; app-string literals using their
      *   prefixes then fall through to `unresolvedExtension` handling.
      *
-     * `dt`, `ip`, `t1`, and `b1` are mandatory-to-implement per §2.1 of
-     * draft-ietf-cbor-edn-literals-26; disabling them produces a parser that
+     * `dt`, `ip`, `t1`, and `b1` are mandatory-to-implement per §3 of
+     * draft-ietf-cbor-edn-literals-27; disabling them produces a parser that
      * no longer conforms to that recommendation. This is intended for
-     * allowlisting scenarios (see §7 Security considerations of the same
+     * allowlisting scenarios (see §8 Security considerations of the same
      * draft) where an application wants explicit control over which
      * extensions it accepts from untrusted CDN input.
      *
@@ -354,8 +523,8 @@ export interface FromCDNOptions {
      */
     builtinExtensions?: CborExtension[] | false;
     /**
-     * How to handle unrecognised application-extension identifiers
-     * (§4.1 of draft-ietf-cbor-edn-literals-25).
+     * How to handle unrecognised app-extension identifiers
+     * (§5.1 of draft-ietf-cbor-edn-literals-27).
      *
      * - `'cpa999'`: wrap the literal in a `CPA999` tag
      *   (`CborUnresolvedAppExt`) instead of failing. The resulting node
@@ -381,14 +550,28 @@ export interface FromCDNOptions {
      *
      * Comments are metadata only: they are ignored by CBOR binary encoding and
      * JavaScript conversion. Use together with `ToCDNOptions.preserveComments`
-     * to include them when formatting back to CDN.
+     * (or `comments`) to include them when formatting back to CDN.
      *
-     * The string values `'c-style'` and `'cdn-style'` are treated as `true`
-     * for parsing purposes; they become meaningful when passed to `toCDN()`.
+     * Passing `'c-style'`/`'cdn-style'` directly is a deprecated shorthand for
+     * `true` plus the equivalent `comments` — still accepted, but prefer
+     * `comments` for the output style going forward.
      *
      * @default false
      */
     preserveComments?: boolean | 'c-style' | 'cdn-style';
+    /**
+     * Companion to `preserveComments` for a single options object shared with
+     * `toCDN()` (as `CBOR.format()` does internally) — see
+     * `ToCDNOptions.comments` for what each value means there. On the
+     * parse side, only *whether* a style other than `'strip'` was requested
+     * matters: comments are captured when `preserveComments` is `true`, or
+     * when `comments` is set to anything other than `'strip'`. Left
+     * unset alongside an unset/`false` `preserveComments`, nothing is
+     * captured.
+     *
+     * @default undefined
+     */
+    comments?: 'strip' | 'c-style' | 'cdn-style';
     /**
      * Shorthand for `ToCDNOptions.preserveAll`, so a single option enables
      * round-tripping through both `fromCDN()` and `toCDN()` (as
@@ -457,10 +640,10 @@ export interface FromJSOptions {
      */
     extensions?: CborExtension[];
     /**
-     * Override the default set of bundled application-oriented extensions.
+     * Override the default set of bundled app-extensions.
      * Mirrors `FromCDNOptions.builtinExtensions`. Only affects builtins that
-     * implement `fromJS()` / `parseTag()` (none of the bundled application
-     * extensions implement `fromJS()` by default — use `dt_as_Date` via
+     * implement `fromJS()` / `parseTag()` (none of the bundled app-extensions
+     * implement `fromJS()` by default — use `dt_as_Date` via
      * `extensions` for `Date` round-tripping).
      */
     builtinExtensions?: CborExtension[] | false;
@@ -512,6 +695,77 @@ export interface FromJSOptions {
      */
     cddlValidationOptions?: CddlValidateOptions;
 }
+/**
+ * Context passed to a `toCDN()` `itemOptions` callback (see
+ * `ToCDNOptions.itemOptions`) describing where the node being visited sits
+ * in the tree. Structurally the same shape as `ItemContext` (`toJS()`'s
+ * own per-item context — see there for the full rationale behind each
+ * field), but `path`'s map-key segments are derived the CDN way: a
+ * text-string key contributes its string value, any other key contributes
+ * its own `toCDN()` rendering — there is no "JS value" for a CDN key to
+ * contribute instead, since converting to JS is not what this call is
+ * doing.
+ *
+ * Unlike `ItemContext`, a node's `toCDN()` `itemOptions` callback can run
+ * more than once for reasons `toJS()`'s never does: `inlineLeafContainers`
+ * (and a tag/app-sequence value's own multi-word check) render an entry a
+ * second time, at the *same* depth and options, purely to answer a layout
+ * question (does it fit on one line? is it multi-word?) before the real
+ * render — an existing, deliberate characteristic of `toCDN()` itself (see
+ * `serializeContainer` in `cdn/serialize-utils.ts`), not something
+ * `itemOptions` introduces. Write this callback as a pure function of
+ * `item`/`ctx`, the same guidance as `ItemContext`'s own, for the same
+ * reason: it must not assume, or count, how many times it runs.
+ */
+export interface CdnItemContext {
+    /** The direct parent AST node. `undefined` for the root value being converted. */
+    parent?: CborItem;
+    /**
+     * The path segment identifying this node: an array index (`number`), or
+     * a map key's string value/`toCDN()` rendering (see `CdnItemContext`'s
+     * own note). Always equal to the last element of `path`, except
+     * `undefined` for the root value and while converting a map key itself
+     * (`isMapKey: true`). A tag or app-sequence wrapper's content inherits
+     * the wrapper's own `key` (and `path`) unchanged, since the wrapper adds
+     * no segment of its own.
+     */
+    key?: unknown;
+    /** The map key's own AST node, present when this node is a map entry's key or value. */
+    keyNode?: CborItem;
+    /**
+     * `true` when this invocation is for converting a map key itself, rather
+     * than one of that key's sibling value's descendants.
+     */
+    isMapKey?: boolean;
+    /**
+     * Path from the root to this node, as a sequence of array indices and
+     * map key identifiers (see `CdnItemContext`'s own note). Empty for the
+     * root value. A tag or app-sequence wrapper does not add a segment of
+     * its own — its content shares the wrapper's own path.
+     */
+    readonly path: readonly unknown[];
+    /**
+     * The options in effect for this node going into this call — the root
+     * options merged with whatever overrides its ancestors already
+     * returned, *before* this callback's own return value is merged on top.
+     * A mutable-looking field here (currently just the deprecated
+     * `textStringFormat`) is a fresh copy, not the live array in effect
+     * elsewhere — mutating it in place has no effect on this node, its
+     * siblings, or the caller's own options; return an override instead.
+     */
+    readonly options: ReadonlyToCDNOptions;
+}
+/**
+ * `ToCDNOptions`, as handed to code that must not mutate it in place —
+ * `CdnItemContext.options` — the `toCDN()` counterpart of
+ * `ReadonlyToJSNodeOptions`. `textStringFormat` (the one field on
+ * `ToCDNOptions` that's an ordinary mutable array, and already deprecated)
+ * is narrowed to a readonly array for the same reason `extensions` is
+ * there; see `ReadonlyToJSNodeOptions`'s own doc for the full rationale.
+ */
+export type ReadonlyToCDNOptions = Readonly<Omit<ToCDNOptions, 'textStringFormat'>> & {
+    readonly textStringFormat?: readonly TextStringFormat[];
+};
 export interface ToCDNOptions {
     /**
      * Indentation for pretty-printing.
@@ -530,7 +784,7 @@ export interface ToCDNOptions {
      * Master switch that turns on every `preserve*` option below at once,
      * except the deprecated `preserveTextString` — `preserveComments`,
      * `preserveByteString`, `preserveRawString`, `preserveConcatenation`,
-     * `preserveNumberFormat`, `preserveAppSequence`, and
+     * `preserveNumberFormat`, `preserveAppPrefix`, and
      * `preserveBlankLines` — for reformatting CDN text (e.g. on save in an
      * editor) with minimal changes: only whitespace/indentation, plus
      * anything an explicitly-set individual option overrides.
@@ -538,7 +792,11 @@ export interface ToCDNOptions {
      * An option explicitly set to a value (including `false`) is left as-is;
      * `preserveAll` only fills in the ones left `undefined`. So
      * `{ preserveAll: true, preserveNumberFormat: false }` preserves
-     * everything except number literal spelling.
+     * everything except number literal spelling. `preserveComments` is filled
+     * in with `true` only when `comments` is *also* left unset — an
+     * explicit `comments` with no `preserveComments` still normalizes
+     * comments to that style under `preserveAll`, instead of being overridden
+     * by the verbatim fill-in.
      *
      * When parsing via `CBOR.fromCDN()` separately from `toCDN()` (rather
      * than through `CBOR.format()`, which passes the same options to both),
@@ -551,24 +809,45 @@ export interface ToCDNOptions {
      */
     preserveAll?: boolean;
     /**
-     * Emit comments previously captured by `FromCDNOptions.preserveComments`.
+     * Emit comments previously captured by `FromCDNOptions.preserveComments`,
+     * with their original markers kept as-is (no normalization) — takes
+     * precedence over `comments` when `true`.
+     *
+     * - `true`: emit comments verbatim, with whichever marker each one was
+     *   originally written with.
+     * - `false` / omitted: defer to `comments` (see below) — `'strip'` (the
+     *   default when that's also unset) or unset means no comments are
+     *   emitted.
+     * - `'c-style'` / `'cdn-style'`: deprecated shorthand for `false` plus the
+     *   equivalent `comments`; still accepted, but prefer setting
+     *   `comments` directly.
+     *
+     * Only effective when `indent` enables pretty-printing: single-line
+     * output strips all comments regardless, since line comments (`#`, `//`)
+     * can only be terminated by a newline.
+     *
+     * @default false
+     */
+    preserveComments?: boolean | 'c-style' | 'cdn-style';
+    /**
+     * Style to normalize comment markers to when emitting comments previously
+     * captured by `FromCDNOptions.preserveComments` — only consulted when
+     * `preserveComments` is not `true` (see there).
      *
-     * - `true`: emit comments with their original markers.
+     * - `'strip'` / omitted: don't emit comments at all.
      * - `'c-style'`: emit comments, normalising line comments to `//` and block
      *   comments to `/* … *\/`.
      * - `'cdn-style'`: emit comments, normalising line comments to `#` and block
      *   comments to `/ … /`. When a `/* … *\/` comment's content contains `/`
      *   (which cannot be represented inside `/ … /`), the `/* … *\/` form is
      *   kept as-is.
-     * - `false` / omitted: strip all comments from the output.
      *
-     * Only effective when `indent` enables pretty-printing: single-line
-     * output strips all comments, since line comments (`#`, `//`) can only
-     * be terminated by a newline.
+     * Only effective when `indent` enables pretty-printing; see
+     * `preserveComments`.
      *
-     * @default false
+     * @default 'strip'
      */
-    preserveComments?: boolean | 'c-style' | 'cdn-style';
+    comments?: 'strip' | 'c-style' | 'cdn-style';
     /**
      * Re-emit a blank line above an array/map entry (or indefinite-length
      * string chunk) that had one before it anywhere in the parsed CDN source,
@@ -594,7 +873,7 @@ export interface ToCDNOptions {
      * This preserves the spelling and interior layout of non-concatenated
      * `h'...'`, `b64'...'`, `b32'...'`, `h32'...'`, raw-backtick byte strings,
      * and single-quoted byte strings — including a `h'xx...yy'`-family elided
-     * literal (§4.2), whose spelling is kept independently of
+     * literal (§5.2), whose spelling is kept independently of
      * `preserveConcatenation` when it has no `+` of its own (see that
      * option). Byte strings produced by `+` concatenation are normalised as
      * usual; combine with `preserveConcatenation` to keep both the part
@@ -710,16 +989,29 @@ export interface ToCDNOptions {
      */
     sqstr?: 'printable-string' | 'string' | 'none';
     /**
-     * Whether to use application-string / app-sequence notation for built-in
-     * extensions (e.g. `dt'...'`, `DT'...'`, `ip'...'`, `IP'...'`).
+     * Whether to use app-prefix notation — app-string (`dt'...'`, `` dt`...` ``)
+     * or app-sequence (`dt<<...>>`) — for built-in extensions.
      * - `true`: emit extension notation (`DT'2023-01-01T12:00:00Z'`)
      * - `false`: emit raw CBOR notation (`1(-14159024)`, `52(h'c000022a')`)
+     *
+     * Named after `app-prefix` (§6.1 of draft-ietf-cbor-edn-literals-27), the
+     * identifier both notations are built from — not just the app-string form,
+     * despite the old `appStrings` name (`false` also falls back to raw tag
+     * notation for a preserved app-sequence spelling; see `preserveAppPrefix`).
+     *
      * @default true
      */
+    appPrefix?: boolean;
+    /**
+     * @deprecated Renamed to `appPrefix` — the old name only described the
+     *   app-string form even though this option also gates app-sequence
+     *   (`<<...>>`) notation. Still honoured when `appPrefix` is left unset,
+     *   but `appPrefix` wins if both are set.
+     */
     appStrings?: boolean;
     /**
-     * For built-in extensions that support application-string notation
-     * (`prefix'...'` or `` prefix`...` ``), application-sequence notation
+     * For built-in extensions that support app-string notation
+     * (`prefix'...'` or `` prefix`...` ``), app-sequence notation
      * (`prefix<<...>>`), and/or a raw tag literal (`N(...)`), re-emit a value
      * using its exact original spelling instead of normalizing it to the
      * regenerated `prefix'...'` form.
@@ -729,10 +1021,10 @@ export interface ToCDNOptions {
      * `` DT`1969-07-21T02:56:16Z` ``, `DT<<'1969-07-21T02:56:16Z'>>`, and even
      * the raw tag form `1(1749772800)` all become
      * `DT'2025-06-13T00:00:00Z'`-style `prefix'...'` notation, even though all
-     * of these denote the same value. `preserveAppSequence` keeps the
+     * of these denote the same value. `preserveAppPrefix` keeps the
      * original spelling instead — whichever quoting (`'...'` vs `` `...` ``),
      * bracketing (`<<...>>`), or raw tag form was used. Has no effect when
-     * `appStrings` is `false` (raw tag notation is used either way regardless
+     * `appPrefix` is `false` (raw tag notation is used either way regardless
      * of the original spelling), or on values not parsed from one of these
      * forms.
      *
@@ -740,13 +1032,34 @@ export interface ToCDNOptions {
      * lines falls back to normal (regenerated) notation; single-line
      * spellings are kept.
      *
-     * An explicit `preserveComments` setting is still applied to comments
-     * inside a preserved application-sequence spelling: marker styles are
-     * normalised without changing the notation family, and `false` removes
-     * the comments while retaining the surrounding source spelling.
+     * An explicit `preserveComments`/`comments` setting is still applied
+     * to comments inside a preserved app-sequence spelling: marker styles are
+     * normalised without changing the notation family, and stripping comments
+     * (`preserveComments: false` with `comments` unset or `'strip'`)
+     * removes them while retaining the surrounding source spelling. Leaving
+     * *both* unset keeps the spelling's comments exactly as originally
+     * written, since nothing was explicitly requested.
+     *
+     * Named after `app-prefix` (§6.1 of draft-ietf-cbor-edn-literals-27; e.g.
+     * `dt`, `DT`, `ip`, `IP`), the identifier that `app-string`/`app-sequence`
+     * notation is built from. The raw tag literal case is still covered: it's
+     * the source spelling that used *no* app-prefix at all, and this option
+     * preserves that choice too, not just spellings that did use one.
+     * `preserveAppSequence` was the old, narrower name for this same option,
+     * since it also preserves app-string and raw-tag spellings, not just
+     * `<<...>>` sequences.
      *
      * @default false
      */
+    preserveAppPrefix?: boolean;
+    /**
+     * @deprecated Renamed to `preserveAppPrefix` — the old name only
+     *   described the `<<...>>` form even though this option also preserves
+     *   `prefix'...'` / `` prefix`...` `` and raw tag (`N(...)`) spellings.
+     *   Still honoured when `preserveAppPrefix` is left unset, but
+     *   `preserveAppPrefix` wins if both are set, and it no longer
+     *   participates in `preserveAll` (use `preserveAppPrefix` for that).
+     */
     preserveAppSequence?: boolean;
     /**
      * Numeric format for integer values in CDN output.
@@ -761,9 +1074,25 @@ export interface ToCDNOptions {
      * Numeric format for floating-point values in CDN output.
      * - `'decimal'`: standard decimal notation (e.g. `1.5`, `145544.0_3`)
      * - `'hex'`: C99-style hex float notation (e.g. `0x1.8p+0`, `0x1.1c54p+17_3`)
+     * - `'app-extension'`: `float'...'` app-string notation carrying the
+     *   value's exact IEEE 754 bit pattern (e.g. `float'3fc00000'`), per §3.8
+     *   of draft-ietf-cbor-edn-literals-27. Unlike `'decimal'`/`'hex'`, this
+     *   is derived from the value's actual encoded bytes rather than its
+     *   numeric text, so it losslessly represents NaN payloads and
+     *   ±Infinity too (not just finite values). Falls back to `'decimal'`
+     *   when `appPrefix` is `false`, matching how other built-in extensions
+     *   fall back to raw notation.
+     *
+     * A value originally parsed from a `float'...'`/`float<<...>>` literal
+     * normally re-emits that exact source spelling regardless of this option
+     * (so its own encoding-width choice, or a non-canonical bit pattern, isn't
+     * silently normalized away) — leaving `floatFormat` unset, or setting it
+     * to `'app-extension'`, keeps that round-trip. Explicitly requesting
+     * `'decimal'` or `'hex'` opts out of it and reformats the value like any
+     * other float, since that's the point of asking for a different format.
      * @default 'decimal'
      */
-    floatFormat?: 'decimal' | 'hex';
+    floatFormat?: 'decimal' | 'hex' | 'app-extension';
     /**
      * Split long text strings using CDN string concatenation syntax (`"a" + "b"`).
      * Only effective when `indent` enables pretty-printing.
@@ -790,6 +1119,11 @@ export interface ToCDNOptions {
      * `preserveConcatenation`; when it does not, the original concatenation
      * is preserved as usual.
      *
+     * `inlineLeafContainers` applies to the embedded CDN structure too: an
+     * array/map/`<<...>>` in the string content that would stay on one line
+     * as a real value keeps its split points collapsed here as well (e.g.
+     * `"[1, 2, 3]"` stays a single literal instead of splitting per element).
+     *
      * Replaces the deprecated `textStringFormat: ['cdn']`.
      *
      * @default false
@@ -825,8 +1159,8 @@ export interface ToCDNOptions {
      * concatenation, and only takes effect when `indent` enables
      * pretty-printing (single-line output joins the parts into one literal).
      *
-     * Also applies within an elision (`...`, §4.2 of
-     * draft-ietf-cbor-edn-literals-25): a `+`-joined fragment on either side of
+     * Also applies within an elision (`...`, §5.2 of
+     * draft-ietf-cbor-edn-literals-27): a `+`-joined fragment on either side of
      * an ellipsis keeps its own part boundaries too (e.g. `'test' +
      * h'1234...abcd' + ...` stays exactly as written instead of merging
      * `'test'` into the byte fragment before it), and byte-string elision
@@ -842,17 +1176,100 @@ export interface ToCDNOptions {
      */
     preserveConcatenation?: boolean;
     /**
-     * When pretty-printing with `indent`, keep a container on a single line
-     * when none of its entries contains an array or map (even wrapped in a
-     * tag) and every entry serializes without a line break (e.g. `[1, 2, 3]`,
-     * `{"a": 1}`, `(_ "a", "b")`). Nested leaf containers still collapse
-     * individually: `[[1, 2], [3, 4]]` renders with one inner array per line.
+     * Render preserved `+` string concatenation (see `preserveConcatenation`)
+     * or an elision chain (`...`, §5.2) using `t1<<...>>` / `b1<<...>>`
+     * app-sequence notation (draft-ietf-cbor-edn-literals-27 §3.5)
+     * instead of the legacy `+` operator.
+     *
+     * - `false` (default): `"a" + "b"` / `'test' + h'1234...abcd' + ...`.
+     * - `true`: `t1<<"a", "b">>` / `b1<<h'1234', h'..abcd'>>`. Falls back to
+     *   `false`'s rendering when `appPrefix` is `false`, since this notation
+     *   is itself an app-string form.
+     *
+     * For a plain (non-elision) concatenation, only changes the spelling used
+     * where `preserveConcatenation` already causes multi-part rendering; has
+     * no effect when concatenation collapses into a single merged literal
+     * (e.g. `preserveConcatenation` unset, or a text string whose content is
+     * reflowed by `splitCdn` instead). An elision chain is different: `...`
+     * denotes genuinely unknown content, so it always renders as multiple
+     * parts regardless of `preserveConcatenation` — `modernConcat` therefore
+     * also applies to it unconditionally (`preserveConcatenation` there only
+     * controls how much of a fragment's *own* internal boundary is shown, not
+     * whether the chain itself is shown as multiple parts).
+     *
+     * Has no effect on a value that was itself parsed from `t1<<...>>` /
+     * `b1<<...>>` source: when `appPrefix` is not `false`, `encodingIndicators`
+     * is `'auto'` (both defaults), and the source is either single-line or
+     * being rendered with `indent` enabled, that spelling is kept verbatim
+     * regardless of `modernConcat` (see `t1`/`b1` in
+     * [String Concatenation and Indefinite-Length Strings](../README.md#string-concatenation-and-indefinite-length-strings)).
+     * A multi-line source falls back to normalized (collapsed) output in
+     * single-line mode, since that layout can't be reproduced without
+     * `indent`. `modernConcat` only affects values reconstructed from a `+`
+     * chain.
      *
-     * `<<...>>` (CBOR Sequence Literal / embedded CBOR) is the one exception:
-     * since it's a flat sequence of encoded items rather than a
-     * nested-structure display, an entry that is itself an array/map still
-     * inlines there as long as its own rendering fits on one line — e.g.
-     * `<<{1: -7}>>` stays on one line, even though `[{1: -7}]` would not.
+     * @default false
+     */
+    modernConcat?: boolean;
+    /**
+     * Render an indefinite-length string using `ilts<<...>>` / `ilbs<<...>>`
+     * app-sequence notation (draft-ietf-cbor-edn-literals-27 §3.6)
+     * instead of the legacy `(_ "a", "b")` streamstring form.
+     *
+     * - `false` (default): `(_ "a", "b")`.
+     * - `true`: `ilts<<"a", "b">>` / `ilbs<<h'..', h'..'>>`. Falls back to
+     *   `false`'s rendering when `appPrefix` is `false`, since this notation
+     *   is itself an app-string form.
+     *
+     * Applies whenever an indefinite-length string is rendered as chunks;
+     * unaffected by `encodingIndicators: 'never'`, which merges the chunks
+     * into a single definite-length literal regardless of this option.
+     *
+     * Has no effect on a value that was itself parsed from `ilts<<...>>` /
+     * `ilbs<<...>>` source: when `appPrefix` is not `false`, `encodingIndicators`
+     * is `'auto'` (both defaults), and the source is either single-line or
+     * being rendered with `indent` enabled, that spelling is kept verbatim
+     * regardless of `modernStreamSyntax`. A multi-line source falls back to
+     * normalized (collapsed) output in single-line mode, since that layout
+     * can't be reproduced without `indent`. `modernStreamSyntax` only affects
+     * values reconstructed from a legacy `(_ ...)` chunk list.
+     *
+     * @default false
+     */
+    modernStreamSyntax?: boolean;
+    /**
+     * When pretty-printing with `indent`, keep an array, map, or
+     * indefinite-length string group (`(_ "a", "b")`) on a single line when
+     * none of its entries contains an array or map (even wrapped in a tag),
+     * none of its entries is a text string with two or more words (also even
+     * wrapped in a tag), and every entry serializes without a line break
+     * (e.g. `[1, 2, 3]`, `{"a": 1}`, `(_ "a", "b")`). Word boundaries follow
+     * `Intl.Segmenter`'s word-break rules, so `["hello", "world"]` still
+     * collapses to one line (each entry is a single word) while `["Hello,
+     * World!", "This is the CBOR library."]` renders one entry per line (each
+     * has two or more) — space-less scripts (Japanese, Chinese, ...) are still
+     * split on their own dictionary-based word boundaries. Nested leaf
+     * containers still collapse individually: `[[1, 2], [3, 4]]` renders with
+     * one inner array per line.
+     *
+     * `<<...>>` (CBOR Sequence Literal / embedded CBOR) is not governed by
+     * this option at all: its own parens never require an additional line
+     * break by themselves, regardless of `inlineLeafContainers`'s value,
+     * since (unlike an array, map, or indefinite-length string group) it has
+     * no nested-structure display of its own to spread out — it's a flat
+     * sequence of encoded items. Instead it stays on one line exactly when
+     * every entry's own actual rendering already does — an entry that is
+     * itself an array/map is not disqualified just for being one, unlike in
+     * an outer array/map. Concretely: `<<{1: -7}>>` renders as `<<{1: -7}>>`
+     * when `inlineLeafContainers` lets the inner map collapse to one line,
+     * but as `<<\n  {\n    1: -7\n  }\n>>` when it doesn't (the map itself
+     * still spreads one entry per line without the option, same as it would
+     * anywhere else — `<<...>>` just doesn't add a break of its own on top
+     * of that). `[{1: -7}]`, by contrast, always spreads its `{1: -7}` entry
+     * onto its own line regardless of whether the map itself collapses,
+     * since a nested array/map always disqualifies an outer array/map's
+     * entry. A two-or-more-word text entry still forces a break inside
+     * `<<...>>` either way, irrespective of `inlineLeafContainers`.
      *
      * Containers with preserved comments are always emitted in multi-line
      * form. Has no effect when `indent` is omitted.
@@ -872,6 +1289,39 @@ export interface ToCDNOptions {
      * @default 'auto'
      */
     encodingIndicators?: 'always' | 'auto' | 'never';
+    /**
+     * Called for every node during `toCDN()`, before that node is rendered,
+     * to override the options used for its subtree. Return a partial options
+     * object to merge over the options in effect for this node (they apply to
+     * this node and are inherited by its descendants, who may override them
+     * again); return `undefined` to make no change.
+     *
+     * This is the mechanism for applying an option to only part of a
+     * document — e.g. rendering one array element in hex while the rest stay
+     * decimal — keyed off `ctx.path` or the node's own shape
+     * (`item instanceof ...`).
+     *
+     * **May be called more than once for the same AST node** — see
+     * `CdnItemContext`'s own note on why, and why this callback should be a
+     * pure function of `item`/`ctx` rather than relying on how many times it
+     * runs.
+     *
+     * Not called for keys of an indefinite-length string's chunks or a
+     * `<<...>>` sequence's items, which have no key of their own to convert
+     * (only array elements and map entries/keys have a `path` segment).
+     *
+     * @example
+     * // Render only the value at key "raw" using hex integers, leaving the
+     * // rest of the document in the default decimal format.
+     * item.toCDN({
+     *   indent: 2,
+     *   itemOptions: (_node, ctx) =>
+     *     ctx.path.length === 1 && ctx.path[0] === 'raw'
+     *       ? { intFormat: 'hex' }
+     *       : undefined,
+     * });
+     */
+    itemOptions?: (item: CborItem, ctx: CdnItemContext) => Partial<ToCDNOptions> | undefined;
 }
 export type TextStringFormat = 'newline' | 'cdn' | DeprecatedTextStringFormat;
 /** @deprecated Use `'cdn'` instead. */
@@ -923,12 +1373,12 @@ export interface ValidateOptions {
      */
     extensions?: CborExtension[];
     /**
-     * Override the default set of bundled application-oriented extensions.
+     * Override the default set of bundled app-extensions.
      * Mirrors `FromCBOROptions.builtinExtensions`.
      */
     builtinExtensions?: CborExtension[] | false;
     /**
-     * How to handle unrecognised application-extension identifiers.
+     * How to handle unrecognised app-extension identifiers.
      * Only applies when `type` is `'cdn'`; mirrors `FromCDNOptions.unresolvedExtension`.
      * @default 'cpa999'
      */
@@ -1003,9 +1453,9 @@ export interface ValidateResult {
      */
     cddlWarnings?: CddlValidationWarning[];
 }
-/** `fromCBORSeq()` の options（`offset`/`allowTrailing` はジェネレータが管理するため除外）。 */
+/** Options for `fromCBORSeq()` (`offset`/`allowTrailing` are excluded — the generator manages them). */
 export type FromCBORSeqOptions = Omit<FromCBOROptions, 'offset' | 'allowTrailing'>;
-/** `fromCDNSeq()` の options（`offset`/`allowTrailing` はジェネレータが管理するため除外）。 */
+/** Options for `fromCDNSeq()` (`offset`/`allowTrailing` are excluded — the generator manages them). */
 export type FromCDNSeqOptions = Omit<FromCDNOptions, 'offset' | 'allowTrailing'>;
 /**
  * Combined options for the `CBOR` constructor.