@syncfusion/ej2-office-common 35.1.37

package/src/features/ink/ink-model.d.ts

@@ -0,0 +1,237 @@
+/**
+ * Ink DOM model and authoring API (office-common).
+ *
+ * Contract: `docs/specs/ink-shared-codec.md` / cross-repo
+ * `ej2-docx/docs/specs/ink-dom-parse-serialize.md` § Internal semantic model,
+ * § Mutation behavior.
+ *
+ * Trace-group decision (TASK-9002): `OfficeInk.traces` is flat document-order.
+ * Nested `traceGroup` structure is reserved for TASK-9003 via an optional
+ * internal ordered tree field (`traceTree`) that 9003 may populate; when
+ * absent, serialize emits a flat sequence of traces. Consumers of 9002 only
+ * see the flat `traces` array.
+ */
+import { InkPoint } from './trace-codec';
+import { computeInkBounds } from './trace-codec';
+/**
+ * Visual effect applied to an ink stroke.
+ *
+ * Source: [MS-ODRAWXML] ink effect tokens + cross-repo effect→color table.
+ *
+ * @public
+ */
+export declare type InkEffectType = 'none' | 'pencil' | 'rainbow' | 'galaxy' | 'lava' | 'ocean' | 'roseGold' | 'gold' | 'silver' | 'bronze';
+/**
+ * A single ink stroke with decoded plane points and brush/context references.
+ *
+ * @private
+ */
+export interface InkTrace {
+    /** Decoded plane coordinates in document trace order. */
+    readonly points: ReadonlyArray<InkPoint>;
+    /** Brush reference key (for example `"#br0"`). */
+    readonly brushRef: string;
+    /** Context reference key (for example `"#ctx0"`). */
+    readonly contextRef: string;
+    /** Optional time-offset attribute preserved when present on the source. */
+    readonly timeOffset?: string;
+}
+/**
+ * Channel definition under a context trace format ([MS-ODRAWXML] §2.1.4).
+ *
+ * @private
+ */
+export interface InkChannel {
+    /** Channel name token such as `X` or `Y`. */
+    readonly name: string;
+    /** Optional channel value type such as `integer` or `decimal`. */
+    readonly type?: string;
+    /** Optional minimum value as the authored string. */
+    readonly min?: string;
+    /** Optional maximum value as the authored string. */
+    readonly max?: string;
+    /** Optional units token such as `cm` or `dev`. */
+    readonly units?: string;
+}
+/**
+ * InkML context under definitions, including channels and optional ink source id.
+ *
+ * @private
+ */
+export interface InkContext {
+    /** Context key (for example `"#ctx0"`). */
+    readonly id: string;
+    /** Optional inkSource `@xml:id`, normalized with or without a leading `#` on write. */
+    readonly inkSourceId?: string;
+    /** Ordered channel definitions for this context. */
+    readonly channels: ReadonlyArray<InkChannel>;
+}
+/**
+ * Brush settings used to render ink strokes.
+ *
+ * Authoring defaults: color `#000000`, size `1.42pt × 1.42pt`, units `'pt'`,
+ * effect `'none'`, and `ignorePressure` `true`. Parse-time [MS-ODRAWXML] §2.1.4
+ * defaults (width `.053 cm`, height `.001 cm`, tip `ellipse`, rasterOp `copyPen`)
+ * apply during parse, not createInk authoring.
+ *
+ * After parse, size values are stored in **points** with `units` retained for
+ * re-emit. After authoring, size values use the brush `units` (default `pt`).
+ *
+ * @private
+ */
+export interface InkBrush {
+    /** Stroke color in `#RRGGBB` form. Default is black (`#000000`). */
+    color: string;
+    /**
+     * Brush width and height.
+     * After parse: values are in points.
+     * After authoring (`createInk` / `addInkTrace`): values use `units` (default `pt`).
+     */
+    size: {
+        width: number;
+        height: number;
+    };
+    /** Length unit key (`cm`, `mm`, `pt`, `px`, `in`, or `emu`). Default is `pt`. */
+    units: string;
+    /** Visual ink effect. Default is `'none'`. */
+    inkEffect: InkEffectType;
+    /** Optional pen tip token such as `ellipse` or `rectangle`, or a preserved value. */
+    tip?: string;
+    /** Optional raster operation token from [MS-ODRAWXML] §2.1.4. */
+    rasterOp?: string;
+    /** When true, pressure channel input is ignored. Authoring default is `true`. */
+    ignorePressure: boolean;
+    /** Optional effect texture horizontal anchor for authored strokes. */
+    anchorX?: string;
+    /** Optional effect texture vertical anchor for authored strokes. */
+    anchorY?: string;
+    /** Optional effect texture scale factor for authored strokes. */
+    scaleFactor?: string;
+    /** Optional transparency from 0 through 1 when present as a brush property. */
+    transparency?: number;
+    /** Optional anti-alias flag when present as a brush property. */
+    antiAliased?: boolean;
+    /** Optional fit-to-curve flag when present as a brush property. */
+    fitToCurve?: boolean;
+    /** Brush key on the owning ink object (for example `"#br0"`). */
+    readonly id: string;
+}
+/**
+ * Optional nesting node for TASK-9003 group preservation.
+ * 9002 keeps this internal / absent for authored ink.
+ *
+ * @private
+ */
+export declare type InkTraceTreeNode = {
+    readonly kind: 'trace';
+    readonly traceIndex: number;
+} | {
+    readonly kind: 'group';
+    readonly children: ReadonlyArray<InkTraceTreeNode>;
+};
+/**
+ * One InkML part: ordered traces + brush table.
+ *
+ * @public
+ */
+export interface OfficeInk {
+    /**
+     * Ordered traces in document order (root-level and, flattened, from groups).
+     */
+    readonly traces: ReadonlyArray<InkTrace>;
+    /** Brush table; ids are `"#br{N}"`-style keys. */
+    readonly brushes: ReadonlyArray<InkBrush>;
+    /**
+     * Parsed contexts under `definitions` (TASK-9003). When empty/undefined,
+     * serializer emits the default `#ctx0` channel set when needed.
+     *
+     * @public
+     */
+    readonly contexts?: ReadonlyArray<InkContext>;
+    /**
+     * Optional nested group tree for TASK-9003. When undefined, traces are a
+     * flat sequence. Not part of the public authoring surface for 9002.
+     *
+     * @private
+     */
+    readonly traceTree?: ReadonlyArray<InkTraceTreeNode>;
+    /**
+     * Scale intent for {@link inkPathPoints}: `'authored'` stretch-to-fit
+     * (re-zero); `'decoded'` uniform (no re-zero). Defaults to `'authored'`
+     * for ink created via {@link createInk}.
+     *
+     * @private
+     */
+    readonly scaleMode?: 'authored' | 'decoded';
+}
+/**
+ * Build a branded ink from parsed InkML state (`scaleMode: 'decoded'`).
+ *
+ * @private
+ */
+export declare function createDecodedInk(init: {
+    traces: InkTrace[];
+    brushes: InkBrush[];
+    contexts?: InkContext[];
+    traceTree?: InkTraceTreeNode[];
+}): OfficeInk;
+/**
+ * Allocate a fresh, empty ink DOM for authoring.
+ *
+ * Empty traces; no brushes until the first {@link addInkTrace}. Scale mode
+ * is `'authored'` (stretch-to-fit for {@link inkPathPoints}).
+ *
+ * @private
+ */
+export declare function createInk(): OfficeInk;
+/**
+ * Add a trace to an ink DOM.
+ *
+ * Brush selection (spec mutation §):
+ * - If `brush` partial is provided, clone previous brush (or default) then
+ *   apply the partial onto a **new** brush id.
+ * - Else if a previous trace exists, clone that trace's brush under a new id.
+ * - Else allocate the default black `1.42pt × 1.42pt` authored brush as `#br0`.
+ *
+ * Returns the new trace. Mutates `ink` in place (traces/brushes arrays grow).
+ *
+ * @private
+ */
+export declare function addInkTrace(ink: OfficeInk, points: ReadonlyArray<{
+    readonly x: number;
+    readonly y: number;
+}>, brush?: Partial<InkBrush>): InkTrace;
+/**
+ * Deep-copy an ink DOM (independent traces, points, brushes, and contexts).
+ *
+ * @private
+ */
+export declare function cloneInk(ink: OfficeInk): OfficeInk;
+/**
+ * Convert ink traces into plane point paths scaled to a drawing extent.
+ *
+ * Authored ink (`scaleMode === 'authored'`, default from {@link createInk})
+ * uses stretch-to-fit (re-zero). Decoded ink uses uniform scale (no re-zero).
+ * Bounds are computed over **all** points in the ink, then each path is scaled
+ * with the same transform.
+ *
+ * @private
+ */
+export declare function inkPathPoints(ink: OfficeInk, extent: {
+    readonly width: number;
+    readonly height: number;
+}): ReadonlyArray<ReadonlyArray<InkPoint>>;
+/**
+ * Type guard for {@link OfficeInk} instances produced by this module.
+ *
+ * @private
+ */
+export declare function isOfficeInk(value: unknown): value is OfficeInk;
+/**
+ * Mark an ink as authored or decoded (uniform scale path).
+ * Hosts and tests use this to select the scale mode for bounds/path computation.
+ *
+ * @private
+ */
+export declare function setInkScaleMode(ink: OfficeInk, mode: 'authored' | 'decoded'): void;
+export { computeInkBounds };

package/src/features/ink/ink-model.js

@@ -0,0 +1,406 @@
+/**
+ * Ink DOM model and authoring API (office-common).
+ *
+ * Contract: `docs/specs/ink-shared-codec.md` / cross-repo
+ * `ej2-docx/docs/specs/ink-dom-parse-serialize.md` § Internal semantic model,
+ * § Mutation behavior.
+ *
+ * Trace-group decision (TASK-9002): `OfficeInk.traces` is flat document-order.
+ * Nested `traceGroup` structure is reserved for TASK-9003 via an optional
+ * internal ordered tree field (`traceTree`) that 9003 may populate; when
+ * absent, serialize emits a flat sequence of traces. Consumers of 9002 only
+ * see the flat `traces` array.
+ */
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __read = (this && this.__read) || function (o, n) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator];
+    if (!m) return o;
+    var i = m.call(o), r, ar = [], e;
+    try {
+        while ((n === void 0 || n-- > 0) && !(r = i.next()).done) ar.push(r.value);
+    }
+    catch (error) { e = { error: error }; }
+    finally {
+        try {
+            if (r && !r.done && (m = i["return"])) m.call(i);
+        }
+        finally { if (e) throw e.error; }
+    }
+    return ar;
+};
+var __spread = (this && this.__spread) || function () {
+    for (var ar = [], i = 0; i < arguments.length; i++) ar = ar.concat(__read(arguments[i]));
+    return ar;
+};
+var __values = (this && this.__values) || function (o) {
+    var m = typeof Symbol === "function" && o[Symbol.iterator], i = 0;
+    if (m) return m.call(o);
+    return {
+        next: function () {
+            if (o && i >= o.length) o = void 0;
+            return { value: o && o[i++], done: !o };
+        }
+    };
+};
+import { computeInkBounds, scalePointsStretch, scalePointsUniform } from './trace-codec';
+/** Marker used by {@link isOfficeInk}. */
+var OFFICE_INK_BRAND = Symbol.for('@syncfusion/ej2-office-common.OfficeInk');
+/** Default authored brush size (spec mutation §): 1.42pt × 1.42pt. */
+var DEFAULT_AUTHORED_BRUSH_SIZE = 1.42;
+var DEFAULT_AUTHORED_COLOR = '#000000';
+var DEFAULT_AUTHORED_UNITS = 'pt';
+var DEFAULT_CONTEXT_REF = '#ctx0';
+function isInkEffectType(value) {
+    return (value === 'none' ||
+        value === 'pencil' ||
+        value === 'rainbow' ||
+        value === 'galaxy' ||
+        value === 'lava' ||
+        value === 'ocean' ||
+        value === 'roseGold' ||
+        value === 'gold' ||
+        value === 'silver' ||
+        value === 'bronze');
+}
+function cloneBrush(source, id) {
+    var next = {
+        color: source.color,
+        size: { width: source.size.width, height: source.size.height },
+        units: source.units,
+        inkEffect: source.inkEffect,
+        ignorePressure: source.ignorePressure,
+        id: id,
+    };
+    if (source.tip !== undefined) {
+        next.tip = source.tip;
+    }
+    if (source.rasterOp !== undefined) {
+        next.rasterOp = source.rasterOp;
+    }
+    if (source.anchorX !== undefined) {
+        next.anchorX = source.anchorX;
+    }
+    if (source.anchorY !== undefined) {
+        next.anchorY = source.anchorY;
+    }
+    if (source.scaleFactor !== undefined) {
+        next.scaleFactor = source.scaleFactor;
+    }
+    if (source.transparency !== undefined) {
+        next.transparency = source.transparency;
+    }
+    if (source.antiAliased !== undefined) {
+        next.antiAliased = source.antiAliased;
+    }
+    if (source.fitToCurve !== undefined) {
+        next.fitToCurve = source.fitToCurve;
+    }
+    return next;
+}
+function cloneContext(source) {
+    var next = {
+        id: source.id,
+        channels: source.channels.map(function (ch) {
+            var c = { name: ch.name };
+            if (ch.type !== undefined) {
+                c.type = ch.type;
+            }
+            if (ch.min !== undefined) {
+                c.min = ch.min;
+            }
+            if (ch.max !== undefined) {
+                c.max = ch.max;
+            }
+            if (ch.units !== undefined) {
+                c.units = ch.units;
+            }
+            return c;
+        }),
+    };
+    if (source.inkSourceId !== undefined) {
+        next.inkSourceId = source.inkSourceId;
+    }
+    return next;
+}
+function defaultAuthoredBrush(id) {
+    return {
+        color: DEFAULT_AUTHORED_COLOR,
+        size: { width: DEFAULT_AUTHORED_BRUSH_SIZE, height: DEFAULT_AUTHORED_BRUSH_SIZE },
+        units: DEFAULT_AUTHORED_UNITS,
+        inkEffect: 'none',
+        ignorePressure: true,
+        id: id,
+    };
+}
+function applyBrushPartial(target, partial) {
+    if (partial.color !== undefined) {
+        target.color = partial.color;
+    }
+    if (partial.size !== undefined) {
+        target.size = {
+            width: partial.size.width,
+            height: partial.size.height,
+        };
+    }
+    if (partial.units !== undefined) {
+        target.units = partial.units;
+    }
+    if (partial.inkEffect !== undefined && isInkEffectType(partial.inkEffect)) {
+        target.inkEffect = partial.inkEffect;
+    }
+    if (partial.ignorePressure !== undefined) {
+        target.ignorePressure = partial.ignorePressure;
+    }
+    if (partial.tip !== undefined) {
+        target.tip = partial.tip;
+    }
+    if (partial.rasterOp !== undefined) {
+        target.rasterOp = partial.rasterOp;
+    }
+    if (partial.anchorX !== undefined) {
+        target.anchorX = partial.anchorX;
+    }
+    if (partial.anchorY !== undefined) {
+        target.anchorY = partial.anchorY;
+    }
+    if (partial.scaleFactor !== undefined) {
+        target.scaleFactor = partial.scaleFactor;
+    }
+}
+/**
+ * Allocate the next `#br{N}` key that does not collide with existing brushes.
+ */
+function allocateBrushId(brushes) {
+    var used = new Set(brushes.map(function (b) { return b.id; }));
+    var n = 0;
+    for (;;) {
+        var id = "#br" + String(n);
+        if (!used.has(id)) {
+            return id;
+        }
+        n += 1;
+    }
+}
+function brandInk(ink) {
+    var internal = ink;
+    Object.defineProperty(internal, OFFICE_INK_BRAND, {
+        value: true,
+        enumerable: false,
+        configurable: false,
+        writable: false,
+    });
+    return internal;
+}
+/**
+ * Build a branded ink from parsed InkML state (`scaleMode: 'decoded'`).
+ *
+ * @private
+ */
+export function createDecodedInk(init) {
+    return brandInk(__assign({ traces: init.traces, brushes: init.brushes, scaleMode: 'decoded' }, (init.contexts !== undefined ? { contexts: init.contexts } : {}), (init.traceTree !== undefined ? { traceTree: init.traceTree } : {})));
+}
+/**
+ * Allocate a fresh, empty ink DOM for authoring.
+ *
+ * Empty traces; no brushes until the first {@link addInkTrace}. Scale mode
+ * is `'authored'` (stretch-to-fit for {@link inkPathPoints}).
+ *
+ * @private
+ */
+export function createInk() {
+    return brandInk({
+        traces: [],
+        brushes: [],
+        scaleMode: 'authored',
+    });
+}
+/**
+ * Add a trace to an ink DOM.
+ *
+ * Brush selection (spec mutation §):
+ * - If `brush` partial is provided, clone previous brush (or default) then
+ *   apply the partial onto a **new** brush id.
+ * - Else if a previous trace exists, clone that trace's brush under a new id.
+ * - Else allocate the default black `1.42pt × 1.42pt` authored brush as `#br0`.
+ *
+ * Returns the new trace. Mutates `ink` in place (traces/brushes arrays grow).
+ *
+ * @private
+ */
+export function addInkTrace(ink, points, brush) {
+    if (!isOfficeInk(ink)) {
+        throw new TypeError('addInkTrace: expected OfficeInk from createInk/cloneInk');
+    }
+    var internal = ink;
+    var pointCopy = points.map(function (p) { return ({ x: p.x, y: p.y }); });
+    var sourceBrush;
+    var lastTrace = internal.traces[internal.traces.length - 1];
+    if (lastTrace !== undefined) {
+        sourceBrush = internal.brushes.find(function (b) { return b.id === lastTrace.brushRef; });
+    }
+    var newId = allocateBrushId(internal.brushes);
+    var newBrush = sourceBrush !== undefined
+        ? cloneBrush(sourceBrush, newId)
+        : defaultAuthoredBrush(newId);
+    if (brush !== undefined) {
+        applyBrushPartial(newBrush, brush);
+    }
+    internal.brushes.push(newBrush);
+    var trace = {
+        points: pointCopy,
+        brushRef: newBrush.id,
+        contextRef: DEFAULT_CONTEXT_REF,
+    };
+    var traceIndex = internal.traces.length;
+    internal.traces.push(trace);
+    // Keep ordered tree in sync so serializeInkXml (tree-preferring) emits new traces.
+    if (internal.traceTree !== undefined) {
+        internal.traceTree = __spread(internal.traceTree, [{ kind: 'trace', traceIndex: traceIndex }]);
+    }
+    return trace;
+}
+/**
+ * Deep-copy an ink DOM (independent traces, points, brushes, and contexts).
+ *
+ * @private
+ */
+export function cloneInk(ink) {
+    if (!isOfficeInk(ink)) {
+        throw new TypeError('cloneInk: expected OfficeInk from createInk/cloneInk');
+    }
+    var internal = ink;
+    var brushes = internal.brushes.map(function (b) { return cloneBrush(b, b.id); });
+    var traces = internal.traces.map(function (t) {
+        var copy = {
+            points: t.points.map(function (p) { return ({ x: p.x, y: p.y }); }),
+            brushRef: t.brushRef,
+            contextRef: t.contextRef,
+        };
+        if (t.timeOffset !== undefined) {
+            copy.timeOffset = t.timeOffset;
+        }
+        return copy;
+    });
+    var next = {
+        traces: traces,
+        brushes: brushes,
+        scaleMode: internal.scaleMode,
+    };
+    if (internal.contexts !== undefined) {
+        next.contexts = internal.contexts.map(cloneContext);
+    }
+    if (internal.traceTree !== undefined) {
+        next.traceTree = cloneTraceTree(internal.traceTree);
+    }
+    return brandInk(next);
+}
+function cloneTraceTree(nodes) {
+    return nodes.map(function (n) {
+        if (n.kind === 'trace') {
+            return { kind: 'trace', traceIndex: n.traceIndex };
+        }
+        return { kind: 'group', children: cloneTraceTree(n.children) };
+    });
+}
+/**
+ * Convert ink traces into plane point paths scaled to a drawing extent.
+ *
+ * Authored ink (`scaleMode === 'authored'`, default from {@link createInk})
+ * uses stretch-to-fit (re-zero). Decoded ink uses uniform scale (no re-zero).
+ * Bounds are computed over **all** points in the ink, then each path is scaled
+ * with the same transform.
+ *
+ * @private
+ */
+export function inkPathPoints(ink, extent) {
+    var e_1, _a, e_2, _b, e_3, _c;
+    if (!isOfficeInk(ink)) {
+        throw new TypeError('inkPathPoints: expected OfficeInk from createInk/cloneInk');
+    }
+    var internal = ink;
+    var allPoints = [];
+    try {
+        for (var _d = __values(internal.traces), _e = _d.next(); !_e.done; _e = _d.next()) {
+            var t = _e.value;
+            try {
+                for (var _f = __values(t.points), _g = _f.next(); !_g.done; _g = _f.next()) {
+                    var p = _g.value;
+                    allPoints.push(p);
+                }
+            }
+            catch (e_2_1) { e_2 = { error: e_2_1 }; }
+            finally {
+                try {
+                    if (_g && !_g.done && (_b = _f.return)) _b.call(_f);
+                }
+                finally { if (e_2) throw e_2.error; }
+            }
+        }
+    }
+    catch (e_1_1) { e_1 = { error: e_1_1 }; }
+    finally {
+        try {
+            if (_e && !_e.done && (_a = _d.return)) _a.call(_d);
+        }
+        finally { if (e_1) throw e_1.error; }
+    }
+    if (allPoints.length === 0) {
+        return internal.traces.map(function () { return []; });
+    }
+    // Build a single scaled cloud, then slice back per trace by index.
+    var scaledAll = internal.scaleMode === 'decoded'
+        ? scalePointsUniform(allPoints, extent)
+        : scalePointsStretch(allPoints, extent);
+    var offset = 0;
+    var paths = [];
+    try {
+        for (var _h = __values(internal.traces), _j = _h.next(); !_j.done; _j = _h.next()) {
+            var t = _j.value;
+            var slice = scaledAll.slice(offset, offset + t.points.length);
+            offset += t.points.length;
+            paths.push(__spread(slice));
+        }
+    }
+    catch (e_3_1) { e_3 = { error: e_3_1 }; }
+    finally {
+        try {
+            if (_j && !_j.done && (_c = _h.return)) _c.call(_h);
+        }
+        finally { if (e_3) throw e_3.error; }
+    }
+    return paths;
+}
+/**
+ * Type guard for {@link OfficeInk} instances produced by this module.
+ *
+ * @private
+ */
+export function isOfficeInk(value) {
+    if (value === null || typeof value !== 'object') {
+        return false;
+    }
+    return value[OFFICE_INK_BRAND] === true;
+}
+/**
+ * Mark an ink as authored or decoded (uniform scale path).
+ * Hosts and tests use this to select the scale mode for bounds/path computation.
+ *
+ * @private
+ */
+export function setInkScaleMode(ink, mode) {
+    if (!isOfficeInk(ink)) {
+        throw new TypeError('setInkScaleMode: expected OfficeInk');
+    }
+    ink.scaleMode = mode;
+}
+export { computeInkBounds };

package/src/features/ink/ink-parser.d.ts

@@ -0,0 +1,59 @@
+/**
+ * InkML element-tree → {@link OfficeInk} parser ([MS-ODRAWXML] §2.1.4).
+ *
+ * The caller supplies an OpenXml element tree; this module never reads bytes
+ * and never expands entities. Count guards are surfaced via
+ * {@link getLastInkParseDiagnostics} for consumer limits policy.
+ */
+import { OpenXmlElement } from '../../core/xml/model';
+import { OfficeInk } from './ink-model';
+/**
+ * Diagnostic code for untokenizable / empty-result malformed traces.
+ *
+ * @public
+ */
+export declare const DIAG_INVALID_INK_TRACE = "content/invalid-ink-trace";
+/**
+ * Single diagnostic entry from an ink parse pass.
+ *
+ * @private
+ */
+export interface InkParseDiagnostic {
+    /** Diagnostic code identifying the issue class. */
+    readonly code: string;
+    /** Human-readable description of the diagnostic. */
+    readonly message: string;
+    /** Optional zero-based index of the related trace when applicable. */
+    readonly traceIndex?: number;
+}
+/**
+ * Aggregate diagnostics and guard counters from the most recent {@link parseInkXml} call.
+ *
+ * @private
+ */
+export interface InkParseDiagnostics {
+    /** Ordered diagnostic items collected during the parse pass. */
+    readonly items: ReadonlyArray<InkParseDiagnostic>;
+    /** Number of traces observed during the parse pass. */
+    readonly traceCount: number;
+    /** Number of packets observed across traces. */
+    readonly packetCount: number;
+    /** Number of plane points produced during decode. */
+    readonly pointCount: number;
+    /** Number of channel values processed during decode. */
+    readonly channelValueCount: number;
+}
+/**
+ * Diagnostics from the most recent {@link parseInkXml} invocation.
+ *
+ * @public
+ */
+export declare function getLastInkParseDiagnostics(): InkParseDiagnostics;
+/**
+ * Parse an InkML `ink` root element tree into a branded {@link OfficeInk}.
+ *
+ * Source: [MS-ODRAWXML] §2.1.4; W3C InkML 1.0; `docs/specs/ink-shared-codec.md`.
+ *
+ * @public
+ */
+export declare function parseInkXml(root: OpenXmlElement): OfficeInk;