@threadlabs/looma 0.45.1 → 0.46.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -4,6 +4,12 @@ import { type LoomaReferenceMap } from "./reference-display.js";
4
4
  /** Conversion-time display snapshot, independent from the authored editor document. */
5
5
  export interface EditorMarkdownConversionOptions extends ConversionOptions {
6
6
  references?: LoomaReferenceMap;
7
+ /**
8
+ * The Markdown the document was read from. Its front matter, every block the editor left
9
+ * unchanged and the spacing between them are written back byte for byte; an edited block keeps
10
+ * the spellings it still reads as.
11
+ */
12
+ original?: string;
7
13
  }
8
14
  /**
9
15
  * A conversion cannot faithfully represent the named input at this document location.
@@ -16,26 +22,32 @@ export declare class EditorMarkdownConversionError extends Error {
16
22
  }
17
23
  /**
18
24
  * Maps an editor's saved JSON to the independent Expressive Markdown AST without DOM access.
19
- * @contract Unsupported nodes, marks and durable attributes throw with their location; input is never mutated.
25
+ * @contract Unsupported nodes, marks and durable attributes throw with their location; input is never
26
+ * mutated. Footnote and link definitions stay where they are, and a table of contents stays a
27
+ * placeholder unless it holds authored navigation.
20
28
  */
21
29
  export declare function editorDocumentToExpressmark(document: JSONContent, options?: EditorMarkdownConversionOptions): Document;
22
30
  /**
23
31
  * Maps supported Expressive Markdown content into the Looma editor's saved JSON shape.
24
- * @contract The editor schema cannot represent arbitrary format extensions; unsupported meanings fail explicitly.
32
+ * @contract The editor schema cannot represent arbitrary format extensions; unsupported meanings fail
33
+ * explicitly. A heading without an authored ID gets the anchor its text derives.
25
34
  */
26
35
  export declare function expressmarkToEditorDocument(document: Document): JSONContent;
27
36
  /**
28
37
  * Writes an editor document using Expressmark's shared parser/writer and safe HTML policy.
38
+ * @contract With `original`, an unedited document is written back byte for byte, and an edit
39
+ * leaves the source of every other block, the front matter and the spacing between them alone.
29
40
  * @failure Unsupported editor data raises EditorMarkdownConversionError before any input is changed.
30
41
  */
31
42
  export declare function editorDocumentToMarkdown(document: JSONContent, options?: EditorMarkdownConversionOptions): string;
32
43
  /**
33
- * Serializes the current editor, including its current display cache and concrete TOC entries.
44
+ * Serializes the current editor, including its current display cache.
34
45
  * @failure Unsupported content throws EditorMarkdownConversionError without changing the document.
35
46
  */
36
- export declare function editorToMarkdown(editor: Editor, options?: ConversionOptions): string;
47
+ export declare function editorToMarkdown(editor: Editor, options?: EditorMarkdownConversionOptions): string;
37
48
  /**
38
49
  * Parses Expressive Markdown into editable JSON for the supported editor schema.
39
- * @failure Unsupported content or root metadata stops conversion instead of being silently flattened.
50
+ * @contract Front matter stays in the Markdown: pass the Markdown as `original` when writing to keep it.
51
+ * @failure Unsupported content stops conversion instead of being silently flattened.
40
52
  */
41
53
  export declare function markdownToEditorDocument(markdown: string, options?: ConversionOptions): JSONContent;