@ai-matrx/print 0.8.8 → 0.8.9

package/dist/markdown-html.d.cts

@@ -0,0 +1,87 @@
+import { PrepareDocumentOptions, DocTree } from './document.cjs';
+
+/**
+ * @ai-matrx/print/markdown-html — THE ONE Markdown→HTML engine (Matrx Alchemy
+ * CONTRACT §1.9, ALC-16).
+ *
+ * ONE parse:
+ *   1. The platform's one reading of our syntax (`@ai-matrx/content-ir/source`
+ *      `tokenizeSource`) marks every kind island — a `__kind` JSON block, an
+ *      inline `__kind` JSON span, and any XML element a projector is
+ *      registered for. Each island is replaced IN PLACE by an opaque atom
+ *      placeholder, so an inline island never splits a paragraph, a list item
+ *      or a table cell.
+ *   2. mdast parses the whole text once (`prepareDocument`: the same tree PDF,
+ *      DOCX and EPUB render from; math is typeset, citations resolved).
+ *   3. print's escape-by-construction renderer writes the HTML; each atom is
+ *      rendered by the `KindHtmlProjector` registered for its kind, or — when
+ *      none is — as escaped source with a notice.
+ *   4. EVERY string this module returns ends in the allow-list
+ *      (`sanitizeEngineHtml`, `@ai-matrx/print/safe-html`): no raw author
+ *      HTML, no author style, and each drop is announced by the parse.
+ *
+ * Skins: `document` / `article` keep print's class vocabulary (styled by the
+ * page CSS); `inline` writes every style onto the element (Google Docs and
+ * Word drop `<style>` and classes on paste). The inline styles are constants
+ * of this module and the allow-list admits exactly those values.
+ *
+ * Pure and DOM-free: runs in the browser, Node, a worker, the extension
+ * service worker and Tauri alike.
+ */
+
+/** A sentence a person reads, and what they can do about it. */
+interface EngineNotice {
+    code: string;
+    sentence: string;
+    remedy: string;
+}
+/** Private or signed images → share-safe URLs before the HTML is sealed. */
+interface EngineAssetResolver {
+    resolve(url: string, signal: AbortSignal): Promise<{
+        url: string;
+    } | null>;
+}
+/** A kind renders into the HTML through its projector; none = escaped source + notice. */
+interface KindHtmlProjector {
+    kindKey: string;
+    toHtml(value: unknown, escape: (s: string) => string): string;
+    toPlainText(value: unknown): string;
+}
+type EngineSkin = "document" | "article" | "inline";
+type EngineProfile = "generic" | "google-docs" | "word";
+/** One parse. Opaque to callers; hand it back to `fragment` / `document` / `plainText`. */
+interface EngineTree {
+    readonly doc: DocTree;
+    readonly atoms: readonly EngineAtom[];
+    readonly images: ReadonlyMap<string, string | null>;
+    readonly notices: readonly EngineNotice[];
+}
+interface EngineAtom {
+    kindKey: string;
+    raw: string;
+    inline: boolean;
+    value: unknown;
+    projector: KindHtmlProjector | null;
+}
+interface EngineParseOptions extends Omit<PrepareDocumentOptions, "onNotice"> {
+    onNotice?(notice: EngineNotice): void;
+    assets?: EngineAssetResolver;
+    signal?: AbortSignal;
+}
+interface MarkdownHtmlEngine {
+    parse(markdown: string, options?: EngineParseOptions): Promise<EngineTree>;
+    fragment(tree: EngineTree, options?: {
+        skin?: EngineSkin;
+        profile?: EngineProfile;
+    }): string;
+    document(tree: EngineTree, options?: {
+        title?: string;
+    }): string;
+    plainText(tree: EngineTree): string;
+}
+/** Create the engine. Projectors are keyed by kind; a second one for the same kind is refused. */
+declare function createMarkdownHtmlEngine(options?: {
+    projectors?: readonly KindHtmlProjector[];
+}): MarkdownHtmlEngine;
+
+export { type EngineAssetResolver, type EngineNotice, type EngineParseOptions, type EngineProfile, type EngineSkin, type EngineTree, type KindHtmlProjector, type MarkdownHtmlEngine, createMarkdownHtmlEngine };

package/dist/markdown-html.d.ts

@@ -0,0 +1,87 @@
+import { PrepareDocumentOptions, DocTree } from './document.js';
+
+/**
+ * @ai-matrx/print/markdown-html — THE ONE Markdown→HTML engine (Matrx Alchemy
+ * CONTRACT §1.9, ALC-16).
+ *
+ * ONE parse:
+ *   1. The platform's one reading of our syntax (`@ai-matrx/content-ir/source`
+ *      `tokenizeSource`) marks every kind island — a `__kind` JSON block, an
+ *      inline `__kind` JSON span, and any XML element a projector is
+ *      registered for. Each island is replaced IN PLACE by an opaque atom
+ *      placeholder, so an inline island never splits a paragraph, a list item
+ *      or a table cell.
+ *   2. mdast parses the whole text once (`prepareDocument`: the same tree PDF,
+ *      DOCX and EPUB render from; math is typeset, citations resolved).
+ *   3. print's escape-by-construction renderer writes the HTML; each atom is
+ *      rendered by the `KindHtmlProjector` registered for its kind, or — when
+ *      none is — as escaped source with a notice.
+ *   4. EVERY string this module returns ends in the allow-list
+ *      (`sanitizeEngineHtml`, `@ai-matrx/print/safe-html`): no raw author
+ *      HTML, no author style, and each drop is announced by the parse.
+ *
+ * Skins: `document` / `article` keep print's class vocabulary (styled by the
+ * page CSS); `inline` writes every style onto the element (Google Docs and
+ * Word drop `<style>` and classes on paste). The inline styles are constants
+ * of this module and the allow-list admits exactly those values.
+ *
+ * Pure and DOM-free: runs in the browser, Node, a worker, the extension
+ * service worker and Tauri alike.
+ */
+
+/** A sentence a person reads, and what they can do about it. */
+interface EngineNotice {
+    code: string;
+    sentence: string;
+    remedy: string;
+}
+/** Private or signed images → share-safe URLs before the HTML is sealed. */
+interface EngineAssetResolver {
+    resolve(url: string, signal: AbortSignal): Promise<{
+        url: string;
+    } | null>;
+}
+/** A kind renders into the HTML through its projector; none = escaped source + notice. */
+interface KindHtmlProjector {
+    kindKey: string;
+    toHtml(value: unknown, escape: (s: string) => string): string;
+    toPlainText(value: unknown): string;
+}
+type EngineSkin = "document" | "article" | "inline";
+type EngineProfile = "generic" | "google-docs" | "word";
+/** One parse. Opaque to callers; hand it back to `fragment` / `document` / `plainText`. */
+interface EngineTree {
+    readonly doc: DocTree;
+    readonly atoms: readonly EngineAtom[];
+    readonly images: ReadonlyMap<string, string | null>;
+    readonly notices: readonly EngineNotice[];
+}
+interface EngineAtom {
+    kindKey: string;
+    raw: string;
+    inline: boolean;
+    value: unknown;
+    projector: KindHtmlProjector | null;
+}
+interface EngineParseOptions extends Omit<PrepareDocumentOptions, "onNotice"> {
+    onNotice?(notice: EngineNotice): void;
+    assets?: EngineAssetResolver;
+    signal?: AbortSignal;
+}
+interface MarkdownHtmlEngine {
+    parse(markdown: string, options?: EngineParseOptions): Promise<EngineTree>;
+    fragment(tree: EngineTree, options?: {
+        skin?: EngineSkin;
+        profile?: EngineProfile;
+    }): string;
+    document(tree: EngineTree, options?: {
+        title?: string;
+    }): string;
+    plainText(tree: EngineTree): string;
+}
+/** Create the engine. Projectors are keyed by kind; a second one for the same kind is refused. */
+declare function createMarkdownHtmlEngine(options?: {
+    projectors?: readonly KindHtmlProjector[];
+}): MarkdownHtmlEngine;
+
+export { type EngineAssetResolver, type EngineNotice, type EngineParseOptions, type EngineProfile, type EngineSkin, type EngineTree, type KindHtmlProjector, type MarkdownHtmlEngine, createMarkdownHtmlEngine };