rapier-markdown-kit 1.2.45 → 1.2.48

package/dist/kit/ledger/transport.mjs

@@ -4,6 +4,7 @@ import {projectInverseSource} from './inverse-source.mjs';
 import {authoredBasis, authoredPlacement, authoredPlacements} from './authored-origin.mjs';
 import {sha256} from './hash.mjs';
 import {canonicalJSON} from './data.mjs';
+import {parseComments, commentSplices, derivedCommentEdits} from '../../spec/md-comments.mjs';
 
 const whole = text => typeof text === 'string' && !/[\uD800-\uDFFF]/u.test(text);
 function admitted(rows) {
@@ -59,7 +60,65 @@ function applyBatch(text, rows) {
   return {text: after, splices: exact};
 }
 
-export function transposeRecord(base, splices, id, records) {
+export function transposeRecord(base, splices, id, records, derivedCommentIndex) {
+  const comments = transposeCommentRecord(base, splices, id, records, derivedCommentIndex);
+  return comments || transposeTextRecord(base, splices, id, records);
+}
+
+function commentRecordProof(source, splices, index) {
+  if (typeof source !== 'string' || !source.includes('<!-- md-comments:') ||
+      !Array.isArray(splices) || !Number.isSafeInteger(index) || index !== splices.length - 1) return null;
+  try {
+    const parsed = parseComments(source), proof = derivedCommentEdits(source, splices);
+    if (!parsed.record || parsed.reason || !parsed.current || !proof || proof.edits.length !== index ||
+        canonicalJSON(proof.edits) !== canonicalJSON(splices.slice(0, index))) return null;
+    let start = parsed.record.start;
+    for (const row of proof.edits) {
+      if (row.pos >= start || row.pos + row.removed.length > start) return null;
+      start += row.inserted.length - row.removed.length;
+    }
+    const derived = commentSplices(source, proof.edits);
+    if (derived.length !== 1 || canonicalJSON(derived[0]) !== canonicalJSON(splices[index])) return null;
+    return {parsed, edits: proof.edits, text: _rapierTransformSplices(source, splices)};
+  } catch (_) { return null; }
+}
+
+function transposeCommentRecord(base, splices, id, records, derivedCommentIndex) {
+  if (!Array.isArray(records) || !records.length) return null;
+  const local = commentRecordProof(base, splices, derivedCommentIndex);
+  if (!local) return null;
+  const bodyRecords = []; let current = base;
+  for (const record of records) {
+    const proof = commentRecordProof(current, record.splices, record.derivedCommentIndex);
+    if (!proof) return null;
+    bodyRecords.push({...record, splices: proof.edits}); current = proof.text;
+  }
+  const moved = transposeTextRecord(local.parsed.body, local.edits, id, bodyRecords);
+  const derive = (source, rows) => {
+    const parsed = parseComments(source); let start = parsed.record?.start;
+    if (!parsed.record || parsed.reason || !parsed.current) throw new RangeError('canonical_act_rebase_conflict');
+    for (const row of rows) {
+      if (row.pos >= start || row.pos + row.removed.length > start) throw new RangeError('canonical_act_rebase_conflict');
+      start += row.inserted.length - row.removed.length;
+    }
+    const footer = commentSplices(source, rows), splices = [...rows, ...footer];
+    const text = _rapierTransformSplices(source, splices), after = text === null ? null : parseComments(text);
+    if (!after?.record || after.reason || !after.current) throw new RangeError('canonical_act_rebase_conflict');
+    return {text, splices, footer};
+  };
+  const accepted = derive(current, moved.splices);
+  let reciprocal = local.text;
+  const against = moved.against.map(record => {
+    const value = derive(reciprocal, record.splices); reciprocal = value.text;
+    return {...record, splices: value.splices};
+  });
+  if (reciprocal !== accepted.text || parseComments(accepted.text).body !== moved.text)
+    throw new RangeError('canonical_transport_invalid');
+  return {text: accepted.text, splices: accepted.splices, against,
+    sourceIndices: [...moved.sourceIndices, ...accepted.footer.map(() => derivedCommentIndex)]};
+}
+
+function transposeTextRecord(base, splices, id, records) {
   if (typeof base !== 'string' || !Array.isArray(splices) || typeof id !== 'string' || !Array.isArray(records))
     throw new RangeError('canonical_transport_invalid');
   let source = base, current = base;
@@ -305,7 +364,7 @@ function authoredReplay(base, records, append = null) {
           throw new RangeError('canonical_origin_invalid');
         const accepted = projectInverse(text, aligned.records, id);
         moved = {text: accepted.after, splices: accepted.splices};
-      } else moved = transposeRecord(basis.text, origin.splices, id, crossed);
+      } else moved = transposeRecord(basis.text, origin.splices, id, crossed, original.derivedCommentIndex);
       if (_rapierTransformSplices(text, moved.splices) !== moved.text) throw new RangeError('canonical_origin_invalid');
       placed.push({...original, splices: moved.splices}); text = moved.text; ids.add(id);
       if (original.derivedCommentIndex != null) sourceIndices.set(id, moved.sourceIndices);

package/dist/kit/ledger.d.mts

@@ -2,17 +2,32 @@
 // rapier-markdown-kit/rapier-ledger: a document's edit history with authorship, Undo of any act and offline merge.
 // Offsets count UTF-16 code units; splices run in their recorded order.
 export type ActorKind = 'human' | 'agent' | 'system';
-export interface Actor { kind: ActorKind; id: string; }
+export interface Actor { kind: ActorKind; id: string; name?: string; }
 export type DocKind = 'markdown' | 'text' | 'code';
 export interface Metadata { filename: string; docKind: DocKind; }
+export interface MetadataEffect {
+  filename?: {before: string; after: string};
+  docKind?: {before: DocKind; after: DocKind};
+}
+export type LedgerData = null | boolean | number | string | LedgerData[] | {[key: string]: LedgerData};
 export interface Splice { pos: number; removed: string; inserted: string; }
 export interface Transaction {
   id: string; documentAuthority: string; baseRevision: number; revision: number; actor: Actor;
-  transport: string; operation: string; requestId: string | null; sourceTransactionId: string | null;
-  affectedBlockIds: string[]; parent: string | null; reverts: string | null; reapplies: string | null;
-  createdAt: string | null; turnId?: string; sourceTransactionIds?: string[];
+  transport: 'platform' | 'webmcp'; operation: string; requestId: string | null; sourceTransactionId: string | null;
+  affectedBlockIds: number[]; parent: string | null; reverts: string | null; reapplies: string | null;
+  createdAt: number | null; turnId?: string | null; sourceTransactionIds?: string[];
+  label?: string | null; turnLabel?: string | null; turnBaseRevision?: number;
+  contribution?: string; contributionBaseRevision?: number; remoteTransactionId?: string;
+}
+export interface AuthoredPlacement { basis: string[]; source: string; splices: Splice[]; }
+/** A retained journal may omit navigation splices: the target's exact rows supply them. */
+export interface JournalRecord {
+  transaction: Transaction; splices?: Splice[]; beforeHash: string; afterHash: string;
+  metadata?: MetadataEffect; authored?: AuthoredPlacement; derivedCommentIndex?: number;
+  changeSet?: {[key: string]: LedgerData};
 }
-export interface LedgerRecord { transaction: Transaction; splices: Splice[]; beforeHash: string; afterHash: string; metadata?: Record<string, unknown>; authored?: unknown; }
+/** An exported envelope expands every navigation record to exact splices. */
+export interface LedgerRecord extends JournalRecord { splices: Splice[]; }
 /** rapier-ledger/2: plain JSON. */
 export interface LedgerEnvelope {
   format: 'rapier-ledger/2';
@@ -24,9 +39,9 @@ export interface LedgerEnvelope {
   sha256: string;
 }
 /** Runs of [start, end, actor kind, actor id, createdAt] over the current text. */
-export interface AuthorshipEnvelope { format: 'rapier-authorship/1'; sha256: string; runs: [number, number, ActorKind, string, string | number | null][]; }
+export interface AuthorshipEnvelope { format: 'rapier-authorship/1'; sha256: string; runs: [number, number, ActorKind, string, number | null][]; }
 export interface ReadLedger { ledger: LedgerEnvelope; text: string; metadata: Metadata; root: string; revision: number; complete: boolean; }
-export interface LedgerInput { text: string; metadata: Metadata; records: LedgerRecord[]; documentAuthority?: string; revision?: number; root?: string; complete?: boolean; }
+export interface LedgerInput { text: string; metadata: Metadata; records: JournalRecord[]; earlier?: JournalRecord[]; documentAuthority?: string; revision?: number; root?: string; complete?: boolean; }
 
 /** A new ledger with no history. Give every copy that may later merge the same documentAuthority. */
 export function openLedger(text: string, options?: {filename?: string; docKind?: DocKind; documentAuthority?: string}): LedgerEnvelope;
@@ -34,20 +49,31 @@ export function exportLedger(input: LedgerInput): LedgerEnvelope;
 /** Verifies the envelope (and, when given, that it describes this text and metadata); throws when it does not. */
 export function readLedger(input: LedgerEnvelope, expectedText?: string, expectedMetadata?: Metadata): ReadLedger;
 /** Records one replacement of the whole text as an act by `actor`. */
-export function replaceLedgerText(input: LedgerEnvelope, text: string, options?: {actor?: Actor; operation?: string; at?: string}): LedgerEnvelope;
+export function replaceLedgerText(input: LedgerEnvelope, text: string, options?: {actor?: Actor; operation?: string; at?: number | null}): LedgerEnvelope;
 export function ledgerWithStart(input: LedgerEnvelope, text: string): LedgerEnvelope;
-export function historyEnvelope(input: LedgerEnvelope, segmentIdentity?: unknown[], expectedText?: string, expectedMetadata?: Metadata): Record<string, unknown>;
+export interface HistoryEnvelope<Segment = unknown> {
+  schemaVersion: 5; documentAuthority: string; documentRevision: number;
+  ledger: LedgerRecord[]; branch: string[]; cursor: number; earliestRevision: number;
+  earliestHash: string; sourceRootId: string; earliestMetadata: Metadata; documentMetadata: Metadata;
+  segmentIdentity: Segment[]; historyComplete: boolean; trimReason: '' | 'carried_start'; trimmedBytes: 0;
+}
+export function historyEnvelope<Segment = unknown>(input: LedgerEnvelope, segmentIdentity?: Segment[], expectedText?: string, expectedMetadata?: Metadata): HistoryEnvelope<Segment>;
 /** The actor id an agent writes under, for a door and an agent name. */
-export function agentActorId(door: string, agent: string): string;
+export function agentActorId(door: string, agent?: {name: string} | null): string;
 export function textRoot(text: string): string;
 export function rootAfter(root: string, splice: Splice): string;
-export function sha256State(): {update(text: string): unknown; digest(): string};
+/** Feed bytes, then call finish once. `bytes` counts the input supplied so far. */
+export function sha256State(): {update(input: Uint8Array): void; finish(): string; readonly bytes: number};
 
 export function authorship(input: LedgerEnvelope): AuthorshipEnvelope;
 export function readAuthorship(input: AuthorshipEnvelope, text: string): AuthorshipEnvelope;
 export function ledgerFromAuthorship(input: AuthorshipEnvelope, text: string, documentAuthority: string, metadata: Metadata): LedgerEnvelope;
 
-export interface MergeConflict { kind: string; code?: string; actId?: string; [key: string]: unknown; }
+export type MergeConflict =
+  | {kind: 'identity'; code: 'act_identity_conflict' | 'act_order_conflict'; actId?: string}
+  | {kind: 'history'; code: 'record_transport_conflict'}
+  | {kind: 'metadata'; code: 'metadata_assignment_conflict' | 'inverse_target_unavailable' | 'record_transport_conflict'; fields?: (keyof Metadata)[]}
+  | (TextMergeConflict & {code: 'text_overlap_unpreserved'});
 export interface MergeResult {
   text: string; metadata: Metadata; ledger: LedgerEnvelope;
   /** False when a person must review: conflicts, or Will keep regions that differ. */
@@ -60,29 +86,109 @@ export function merge(first: LedgerEnvelope, second: LedgerEnvelope): MergeResul
 export function transportInterval(start: number, end: number, splices: Splice[]): {start: number; end: number} | null;
 export function transportTouchedInterval(start: number, end: number, splices: Splice[]): {start: number; end: number};
 
-export interface HistoryInput { source: string; metadata: Metadata; records: LedgerRecord[]; revision: number; earliestRevision: number; complete: boolean; }
-export interface HistoryFailure { ok?: false; code: string; [key: string]: unknown; }
+export type HistoryTransaction = Pick<Transaction, 'id' | 'baseRevision' | 'revision' | 'actor' | 'createdAt'> & Partial<Transaction>;
+export interface HistoryRecord {
+  transaction: HistoryTransaction; splices?: Splice[]; beforeHash?: string; afterHash?: string;
+  metadata?: MetadataEffect; authored?: AuthoredPlacement; derivedCommentIndex?: number;
+  changeSet?: {[key: string]: LedgerData};
+}
+export interface HistoryInput {
+  source: string; metadata: Metadata; records: HistoryRecord[];
+  revision?: number; earliestRevision?: number; earliestRoot?: string; complete?: boolean;
+}
+export interface HistoryFailure {
+  ok: false;
+  reason: 'history_invalid' | 'history_unavailable' | 'range_invalid' | 'act_unavailable' | 'act_invalid' | 'act_forbidden' | 'will_refused';
+}
+export interface HistoryAct {
+  id: string; actor: Actor; createdAt: number | null; baseRevision: number; revision: number; operation: string;
+  turnId?: string; contribution?: string; sourceTransactionId?: string; sourceTransactionIds?: string[];
+  reverts?: string; reapplies?: string; label?: LedgerData; affectedBlockIds?: number[];
+  metadata?: MetadataEffect; active?: boolean;
+}
+export interface HistoryGroup { id: string; actor: Actor; actIds: string[]; createdAt: number | null; turnId?: string; }
+export interface HistorySnapshot { source: string; revision: number; earliestRevision: number; complete: boolean; }
+export interface HistoryReplay extends HistorySnapshot {
+  ok: true; initialSource: string; metadata: Metadata; initialMetadata: Metadata;
+  acts: HistoryAct[]; effectiveActIds: string[]; groups: HistoryGroup[];
+}
+export interface HistorySourceBefore extends HistorySnapshot { ok: true; metadata: Metadata; act: HistoryAct; }
+export interface HistoryRange { from?: number; to?: number; actId?: string; }
+export interface HistorySourceRange { from: number; to: number; source: string; }
+export interface ProjectedHistoryAct extends HistoryAct { before: HistorySourceRange; after: HistorySourceRange; }
+export interface HistoryProjection extends HistorySnapshot, HistorySourceRange {
+  ok: true; acts: ProjectedHistoryAct[]; groups: HistoryGroup[]; before?: HistorySourceRange;
+}
+export interface HistoryBlock<Id = unknown> { id: Id; from: number; to: number; }
+export interface HistoryPlaces<Id = unknown> extends HistorySnapshot {
+  ok: true; initialSource: string; acts: HistoryAct[];
+  blocks: (HistoryBlock<Id> & {source: string; acts: ProjectedHistoryAct[]})[]; reversed: string[];
+}
+export interface UndoHunk {
+  actId: string; spliceIndex: number; hunkIndex: number; splice: Splice;
+  beforeSource: string; actSource: string; priorSplices: Splice[];
+}
+export interface SelectiveUndoOptions {
+  actor?: Actor;
+  /** Retain this exact hunk while reversing the other selected hunks. */
+  keepHunk?: (hunk: UndoHunk) => boolean;
+  /** Refinements must replay to the same exact text as the supplied splice. */
+  splitSplice?: (input: {actId: string; beforeSource: string; splice: Splice}) => Splice[];
+}
+export interface SupersededHunk { actId: string; hunk: string; laterActIds: string[]; reason: 'later_edit' | 'already_undone'; }
+export interface SelectiveUndo {
+  ok: true; splices: Splice[]; after: string; actIds: string[]; sourceTransactionIds: string[];
+  metadata: MetadataEffect | null; afterMetadata: Metadata; effectChanged: boolean; unchanged: boolean;
+  superseded: SupersededHunk[]; overlaps: SupersededHunk[];
+}
 /** Reverses chosen acts while later work stays. */
-export function selectiveUndo(input: HistoryInput, actIds: string[], options?: {actor?: Actor; splitSplice?: (...args: unknown[]) => unknown}): Record<string, unknown> | HistoryFailure;
-export function replayHistory(input: HistoryInput): unknown;
-export function sourceBefore(input: HistoryInput, actId: string): unknown;
-export function historyProjection(input: HistoryInput, range?: {from?: number; to?: number; actId?: string}): unknown;
-export function historyProjections(input: HistoryInput, ranges: unknown[]): unknown;
-export function historyPlaces(input: HistoryInput, blocks: unknown[]): unknown;
-export function groupHistoryActs(acts: unknown[]): unknown;
-export function pictureHistorySplices(input: unknown, target: unknown, redo: boolean): Splice[] | null;
-export function transposeSource(base: string, splices: Splice[], client: unknown, log: unknown): unknown;
-export function authoredBasis(...args: unknown[]): unknown;
-export function authoredPlacement(...args: unknown[]): unknown;
-export function authoredHistory(base: string, records: LedgerRecord[], selected?: unknown): unknown;
-export function transposeAuthored(base: string, records: LedgerRecord[], incoming: unknown, submitted: unknown): unknown;
+export function selectiveUndo(input: HistoryInput, actIds: string[], options?: SelectiveUndoOptions): SelectiveUndo | HistoryFailure;
+export function replayHistory(input: HistoryInput): HistoryReplay | HistoryFailure;
+export function sourceBefore(input: HistoryInput, actId: string): HistorySourceBefore | HistoryFailure;
+export function historyProjection(input: HistoryInput, range?: HistoryRange): HistoryProjection | HistoryFailure;
+export function historyProjections(input: HistoryInput, ranges: (HistoryRange | undefined)[]): {ok: true; projections: (HistoryProjection | HistoryFailure)[]} | HistoryFailure;
+export function historyPlaces<Id>(input: HistoryInput, blocks: HistoryBlock<Id>[]): HistoryPlaces<Id> | HistoryFailure;
+export function groupHistoryActs(acts: Pick<HistoryAct, 'id' | 'actor' | 'createdAt' | 'turnId'>[]): HistoryGroup[];
+export function pictureHistorySplices(input: Pick<HistoryInput, 'source' | 'records'>, target: HistoryRecord, redo: boolean): Splice[] | null;
+/** Canonical input splices use `pos/removed/inserted`; the host's reciprocal log uses `at/remove/insert`. */
+export interface SourceTransportEntry { client: string; splices: {at: number; remove: number; insert: string}[]; }
+export interface AuthoredRecord {
+  transaction: Pick<Transaction, 'id'> & Partial<Transaction>; splices: Splice[];
+  authored?: AuthoredPlacement; metadata?: MetadataEffect; derivedCommentIndex?: number;
+}
+export interface SourceTransposition {
+  text: string; splices: Splice[]; sourceIndices: number[];
+  against: {transaction: {id: string}; splices: Splice[]}[];
+}
+export interface AuthoredHistory<Record extends AuthoredRecord = AuthoredRecord> {
+  text: string; records: Record[]; origins: Map<string, AuthoredPlacement>;
+}
+export interface ProjectedAuthoredHistory<Record extends AuthoredRecord = AuthoredRecord> extends AuthoredHistory<Record> {
+  sourceIndices: Map<string, number[]>;
+}
+export interface AuthoredTransposition<Record extends AuthoredRecord = AuthoredRecord> {
+  text: string; splices: Splice[]; submittedBefore: string; submitted: string; against: Record[];
+}
+export function transposeSource(base: string, splices: Splice[], client: string, log: SourceTransportEntry[]): SourceTransposition;
+export function authoredBasis(records: Pick<AuthoredRecord, 'transaction' | 'authored'>[]): string[];
+export function authoredPlacement(source: string, splices: Splice[], basis: string[]): AuthoredPlacement;
+export function authoredHistory<Record extends AuthoredRecord>(base: string, records: Record[], selected: ReadonlySet<string>): ProjectedAuthoredHistory<Record>;
+export function authoredHistory<Record extends AuthoredRecord>(base: string, records: Record[], selected?: null): AuthoredHistory<Record>;
+export function authoredHistory<Record extends AuthoredRecord>(base: string, records: Record[], selected?: ReadonlySet<string> | null): AuthoredHistory<Record> | ProjectedAuthoredHistory<Record>;
+export function transposeAuthored<Record extends AuthoredRecord>(base: string, records: Record[], incoming: AuthoredRecord & {authored: AuthoredPlacement}, submitted: string[]): AuthoredTransposition<Record>;
 
 export {writeDocument, readDocument, writeParts, readParts} from './ledger/carried.mjs';
 
-export interface TextConflict { kind: 'text'; id: string; start: number; end: number; block: string; variants: string[]; }
-export interface TextMerge { text: string; clean: boolean; conflicts: (TextConflict | {kind: string; advisory?: boolean})[]; }
+export interface TextConflictVariant { device: string; text: string; }
+export interface TextConflictDescriptor { start: number; end: number; block: string; variants: TextConflictVariant[]; }
+export interface TextConflict extends TextConflictDescriptor { kind: 'text'; id: string; }
+export type TextMergeConflict =
+  | (TextConflictDescriptor & {kind: 'text' | 'no-ancestor' | 'will' | 'document-bindings' | 'ambiguous-alignment-or-budget'; base: string | null})
+  | {kind: 'existing-conflict'; advisory: true};
+export interface TextMerge { text: string; clean: boolean; conflicts: TextMergeConflict[]; }
+export interface TextMergeOptions { oursId: string; theirsId: string; }
 /** Exact three-way text merge; a region both sides changed becomes a marked choice in the text. */
-export function mergeText(base: string | null, ours: string, theirs: string, options?: Record<string, unknown>): TextMerge;
+export function mergeText(base: string | null, ours: string, theirs: string, options?: TextMergeOptions): TextMerge;
 export function inspectTextConflicts(text: string, options?: {nested?: boolean}): TextConflict[];
-export function resolveTextConflict(text: string, conflict: TextConflict | string, device: unknown): string;
+export function resolveTextConflict(text: string, conflict: TextConflictDescriptor, device: string | number): string;
 export function mapTextConflictVariants(text: string, mapper: (variant: string) => string): string;

package/dist/kit/markdown-it.d.mts

@@ -1,4 +1,4 @@
 // SPDX-License-Identifier: MIT
 // md.use(rapierMarkdown): Self-contained Markdown in markdown-it, with the reference style's markup.
-interface MarkdownItLike { use(plugin: (md: any, ...params: any[]) => unknown, ...params: any[]): any; renderer: {rules: Record<string, unknown>}; core: {ruler: {after(after: string, name: string, rule: (state: any) => unknown): void}}; }
-export function rapierMarkdown<T extends MarkdownItLike>(md: T): T;
+import type {MarkdownParser} from './marks.mjs';
+export function rapierMarkdown<T extends MarkdownParser>(md: T): T;

package/dist/kit/marks.d.mts

@@ -0,0 +1,241 @@
+// SPDX-License-Identifier: MIT
+export {};
+export interface MarkdownReference {href: string; title: string}
+/** Plugins may add their own entries; known references retain their concrete shape. */
+export interface MarkdownEnvironment {
+  references?: Record<string, MarkdownReference>;
+  [name: string | symbol]: unknown;
+}
+export interface MarkdownToken {
+  type: string;
+  tag: string;
+  nesting: -1 | 0 | 1;
+  attrs: [string, string | number][] | null;
+  map: [number, number] | null;
+  level: number;
+  children: MarkdownToken[] | null;
+  content: string;
+  markup: string;
+  info: string;
+  meta: Record<string, unknown> | null;
+  block: boolean;
+  hidden: boolean;
+  attrIndex(name: string): number;
+  attrPush(attr: [string, string | number]): void;
+  attrSet(name: string, value: string | number): void;
+  attrGet(name: string): string | number | null;
+  attrJoin(name: string, value: string | number): void;
+}
+export interface MarkdownOptions {
+  html?: boolean; xhtmlOut?: boolean; breaks?: boolean; langPrefix?: string;
+  linkify?: boolean; typographer?: boolean; quotes?: string | string[]; maxNesting?: number;
+  highlight?: ((source: string, language: string, attrs: string) => string) | null;
+}
+export interface MarkdownCoreState {
+  src: string;
+  env: MarkdownEnvironment;
+  tokens: MarkdownToken[];
+  inlineMode: boolean;
+  md: MarkdownParser;
+}
+export interface MarkdownInlineState {
+  src: string; env: MarkdownEnvironment; md: MarkdownParser; tokens: MarkdownToken[];
+  pos: number; posMax: number; level: number; pending: string; pendingLevel: number;
+  push(type: string, tag: string, nesting: -1 | 0 | 1): MarkdownToken;
+  pushPending(): MarkdownToken;
+}
+export interface MarkdownBlockState {
+  src: string; env: MarkdownEnvironment; md: MarkdownParser; tokens: MarkdownToken[];
+  bMarks: number[]; eMarks: number[]; tShift: number[]; sCount: number[]; bsCount: number[];
+  blkIndent: number; line: number; lineMax: number; tight: boolean; listIndent: number;
+  parentType: string; level: number;
+  push(type: string, tag: string, nesting: -1 | 0 | 1): MarkdownToken;
+  getLines(begin: number, end: number, indent: number, keepLastLF: boolean): string;
+  isEmpty(line: number): boolean;
+}
+// A parser may enrich these states. Rules receive the concrete state of their parser.
+export type MarkdownCoreRule = {run(state: MarkdownCoreState): void}['run'];
+export type MarkdownInlineRule = {run(state: MarkdownInlineState, silent: boolean): boolean}['run'];
+export type MarkdownBlockRule = {run(state: MarkdownBlockState, start: number, end: number, silent: boolean): boolean}['run'];
+export interface MarkdownRuler<Rule> {
+  /** Present on markdown-it at runtime; omitted by some upstream declaration versions. */
+  __rules__?: {name: string; fn: Rule; enabled: boolean; alt: string[]}[];
+  at(name: string, rule: Rule, options?: {alt: string[]}): void;
+  before(before: string, name: string, rule: Rule, options?: {alt: string[]}): void;
+  after(after: string, name: string, rule: Rule, options?: {alt: string[]}): void;
+  push(name: string, rule: Rule, options?: {alt: string[]}): void;
+  getRules(chain: string): Rule[];
+}
+export type MarkdownRenderRule = {render(tokens: MarkdownToken[], index: number, options: MarkdownOptions,
+  env: MarkdownEnvironment, renderer: MarkdownRenderer): string}['render'];
+export interface MarkdownRenderer {
+  rules: Record<string, MarkdownRenderRule | undefined>;
+  rapierTransformHtml?(html: string): string;
+  renderToken(tokens: MarkdownToken[], index: number, options: MarkdownOptions): string;
+  renderInline(tokens: MarkdownToken[], options: MarkdownOptions, env: MarkdownEnvironment): string;
+  renderInlineAsText(tokens: MarkdownToken[], options: MarkdownOptions, env: MarkdownEnvironment): string;
+  render(tokens: MarkdownToken[], options: MarkdownOptions, env: MarkdownEnvironment): string;
+}
+/** The markdown-it instance hooks used by the portable kit. No parser package is required for these types. */
+export interface MarkdownParser {
+  core: {ruler: MarkdownRuler<MarkdownCoreRule>};
+  inline: {
+    ruler: MarkdownRuler<MarkdownInlineRule>;
+    parse(source: string, parser: MarkdownParser, env: MarkdownEnvironment, tokens: MarkdownToken[]): void;
+  };
+  block: {ruler: MarkdownRuler<MarkdownBlockRule>};
+  renderer: MarkdownRenderer;
+  options: MarkdownOptions;
+  helpers: {
+    parseLinkDestination(source: string, start: number, end: number): {ok: boolean; pos: number; str: string};
+    parseLinkLabel(state: MarkdownInlineState, start: number, disableNested?: boolean): number;
+  };
+  utils: {unescapeAll(source: string): string; escapeHtml(source: string): string; normalizeReference(source: string): string};
+  validateLink(url: string): boolean;
+  normalizeLink(url: string): string;
+  parse(source: string, env: MarkdownEnvironment): MarkdownToken[];
+  parseInline(source: string, env: MarkdownEnvironment): MarkdownToken[];
+  render(source: string, env?: MarkdownEnvironment): string;
+  renderInline(source: string, env?: MarkdownEnvironment): string;
+}
+/** Direct parser-internal consumers require markdown-it's runtime state constructor and rule records. */
+export interface MarkdownParserInternals extends MarkdownParser {
+  core: {ruler: MarkdownRuler<MarkdownCoreRule> & {__rules__: {name: string; fn: MarkdownCoreRule; enabled: boolean; alt: string[]}[]}};
+  inline: MarkdownParser['inline'] & {
+    State: new (source: string, parser: MarkdownParser, env: MarkdownEnvironment, tokens: MarkdownToken[]) => MarkdownInlineState;
+    ruler: MarkdownRuler<MarkdownInlineRule> & {__rules__: {name: string; fn: MarkdownInlineRule; enabled: boolean; alt: string[]}[]};
+  };
+  block: {ruler: MarkdownRuler<MarkdownBlockRule> & {__rules__: {name: string; fn: MarkdownBlockRule; enabled: boolean; alt: string[]}[]}};
+}
+
+export const TEXT_COLOR_NAMES: Readonly<{
+  green: '#1c7547'; red: '#b32034'; blue: '#175dc4'; gold: '#865818'; purple: '#7924d7';
+}>;
+export const PAGE_BREAK_MARKER: '<!--md-break:v1 page-->';
+export interface FontStack {readonly stack: string; readonly css: string; readonly word: string}
+export const FONT_STACKS: Readonly<Record<'sans' | 'serif' | 'mono' | 'system' | 'hand', FontStack>>;
+export interface TypographyFamily {readonly name: string; readonly css: string; readonly custom: boolean}
+export interface TypographySize {
+  readonly css: string;
+  readonly unit: 'pt' | 'px';
+  readonly value: number;
+  readonly points: number;
+  readonly halfPoints: number;
+}
+export interface TypographyStyle {
+  readonly size?: string;
+  readonly color?: string;
+  readonly family?: TypographyFamily;
+}
+export interface TypographyInput {size?: string; color?: string; family?: string | TypographyFamily}
+export interface TypographyChanges {size?: string | null; color?: string | null; family?: string | TypographyFamily | null}
+export interface NormalizedTypographyChanges {
+  readonly size?: string | null;
+  readonly color?: string | null;
+  readonly family?: TypographyFamily | null;
+}
+export interface TypographySourceRange {start: number; innerStart: number; innerEnd: number; end: number; style: TypographyStyle}
+export interface TypographyRuns {text: string; paint: TypographyStyle[]; leaves: {start: number; end: number; blocked: boolean}[]}
+export interface TypographyGrammar {
+  normalizeFontFamily(value: unknown): string | null;
+  fontFamilyCss(value: unknown): string;
+  FONT_STACKS: Readonly<Record<string, FontStack>>;
+}
+export interface InlineTypography {
+  size(value: unknown): TypographySize | null;
+  color(value: unknown): string | null;
+  family(value: unknown): TypographyFamily | null;
+  familyCss(value: unknown): TypographyFamily | null;
+  normalize(value: TypographyInput, removals?: false): TypographyStyle;
+  normalize(value: TypographyChanges, removals: true): NormalizedTypographyChanges;
+  normalize(value: TypographyInput, removals: boolean): TypographyStyle;
+  parseStyle(value: unknown, editable?: false): TypographyStyle;
+  parseStyle(value: unknown, editable: boolean): TypographyStyle | null;
+  style(value: TypographyInput): string;
+  open(value: TypographyInput): string;
+  wrap(value: TypographyInput, content: string): string;
+  parseOpen(source: string, decode?: (source: string) => string, editable?: boolean): TypographyStyle | null;
+  nodeStyle(node: Pick<Element, 'getAttribute'> | null | undefined): TypographyStyle;
+  runs(root: Node): TypographyRuns;
+  install<P extends MarkdownParser>(parser: P): P;
+}
+export function normalizeFontFamily(value: unknown): string | null;
+export function fontFamilyCss(value: unknown): string;
+export function formatFontRun(family: string, content: string): string;
+export function formatColorRun(hex: string, content: string): string;
+/** This factory configures inline source typography, not DOM paragraph refinement. */
+export function createTypography(grammar: TypographyGrammar): Readonly<InlineTypography>;
+export const typography: Readonly<InlineTypography>;
+export function typographySourceRanges(source: string, parser: MarkdownParser): TypographySourceRange[];
+
+export type InkKind = 'under' | 'strike' | 'ring' | 'bracket' | 'free' | 'arrow' | 'end';
+export const INK_KINDS: readonly ['under', 'strike', 'ring', 'bracket', 'free', 'arrow', 'end'];
+export const INK_CLOSE: '<!--/ink-->';
+export const INK_PATH_MAX: 160;
+export const INK_INT_MAX: 999999;
+export const INK_OPEN_PATTERN: string;
+export type InkPoint = readonly [number, number];
+interface InkStroke {
+  hex?: string | null;
+  width?: number | null;
+  box?: InkPoint | null;
+  at?: InkPoint | null;
+}
+export type InkInput =
+  | (InkStroke & {kind: 'under' | 'strike'; id?: never; path?: readonly InkPoint[] | null})
+  | (InkStroke & {kind: 'ring' | 'bracket' | 'free'; id?: never; path: readonly [InkPoint, ...InkPoint[]]})
+  | (InkStroke & {kind: 'arrow'; id: number; path?: readonly InkPoint[] | null})
+  | {kind: 'end'; id: number; hex?: null; width?: null; box?: null; at?: null; path?: readonly [] | null};
+interface ParsedInkStroke {
+  readonly hex: string | null;
+  readonly width?: number;
+  readonly box: [number, number] | null;
+  readonly at: [number, number] | null;
+}
+export type ParsedInk =
+  | (ParsedInkStroke & {readonly kind: 'under' | 'strike'; readonly id?: never; readonly path: [number, number][]})
+  | (ParsedInkStroke & {readonly kind: 'ring' | 'bracket' | 'free'; readonly id?: never; readonly path: [[number, number], ...[number, number][]]})
+  | (ParsedInkStroke & {readonly kind: 'arrow'; readonly id: number; readonly path: [number, number][]})
+  | {readonly kind: 'end'; readonly id: number; readonly hex: null; readonly width?: never;
+      readonly box: null; readonly at: null; readonly path: []};
+export function readInkMatch(match: RegExpMatchArray): Readonly<ParsedInk> | null;
+export function parseInkOpen(comment: string): Readonly<ParsedInk> | null;
+export function parseInkBody(body: string): Readonly<ParsedInk> | null;
+export function formatInkOpen(mark: InkInput): string;
+export function formatInkRun(mark: InkInput, content: string): string;
+export function matchInkOpen(text: string): {mark: Readonly<ParsedInk>; length: number} | null;
+export function inkOpenBody(opener: string): string | null;
+export function formatInkOpenFromBody(body: string): string | null;
+export function isInkClose(comment: unknown): boolean;
+export interface InkSourceView {
+  readonly length: number;
+  contains(value: string): boolean;
+  readSlice(start: number, end: number): string;
+}
+export interface InkEdit {pos: number; removed: string; inserted: string}
+export function mayRetireInk(source: InkSourceView, rows: readonly InkEdit[]): boolean;
+export type InkMarker =
+  | {start: number; end: number; mark: Readonly<ParsedInk>; close: false}
+  | {start: number; end: number; mark: null; close: true; arrowId?: number};
+export interface InkRun {start: number; end: number; innerStart: number; innerEnd: number; mark: Readonly<ParsedInk>}
+export interface InkSpanPairs {runs: InkRun[]; strays: InkMarker[]}
+export interface InkArrow {
+  id: number;
+  tail: Omit<InkRun, 'mark'> & {mark: Extract<ParsedInk, {kind: 'arrow'}>};
+  head: Omit<InkRun, 'mark'> & {mark: Extract<ParsedInk, {kind: 'end'}>};
+}
+export interface InkPairs extends InkSpanPairs {arrows: InkArrow[]}
+export function scanInkMarkers(source: string): InkMarker[];
+export function pairInkMarkers(source: string, markers?: readonly InkMarker[] | null): InkPairs;
+export function pairInkSpans(source: string, markers?: readonly InkMarker[] | null): InkSpanPairs;
+export function pairMarkers(source: string, kind: 'ink', markers?: readonly InkMarker[] | null): InkPairs;
+export function quotedWillSpan(source: string, spans: readonly (readonly [number, number])[]): {
+  start: number; end: number; where: 'fence' | 'raw-pre' | 'raw-div' | 'raw-table' | 'raw-html' | 'frontmatter';
+} | null;
+export function sliceInkArrows(source: string, start?: number, end?: number, markers?: readonly InkMarker[] | null): string;
+export function prepareInkPaste(source: string, existing?: string, markers?: readonly InkMarker[] | null): string;
+export function stripInkMarkers(text: string): string;
+export function hasInkMarker(text: string): boolean;
+export function formatPageBreak(): typeof PAGE_BREAK_MARKER;
+export function isPageBreakLine(text: unknown): boolean;
+export function isPageBreakBlock(text: unknown): boolean;

package/dist/kit/marks.mjs

@@ -1,2 +1,40 @@
 // SPDX-License-Identifier: MIT
-export * from '../spec/md-marks.mjs';
+export {
+  FONT_STACKS,
+  INK_CLOSE,
+  INK_INT_MAX,
+  INK_KINDS,
+  INK_OPEN_PATTERN,
+  INK_PATH_MAX,
+  PAGE_BREAK_MARKER,
+  TEXT_COLOR_NAMES,
+  createTypography,
+  fontFamilyCss,
+  formatColorRun,
+  formatFontRun,
+  formatInkOpen,
+  formatInkOpenFromBody,
+  formatInkRun,
+  formatPageBreak,
+  hasInkMarker,
+  inkOpenBody,
+  isInkClose,
+  isPageBreakBlock,
+  isPageBreakLine,
+  matchInkOpen,
+  mayRetireInk,
+  normalizeFontFamily,
+  pairInkMarkers,
+  pairInkSpans,
+  pairMarkers,
+  parseInkBody,
+  parseInkOpen,
+  prepareInkPaste,
+  quotedWillSpan,
+  readInkMatch,
+  scanInkMarkers,
+  sliceInkArrows,
+  stripInkMarkers,
+  typography,
+  typographySourceRanges
+} from '../spec/md-marks.mjs';