@aparte/plugin-marked 0.19.3 → 0.21.0

package/README.md

@@ -15,6 +15,21 @@ setupMarkedProvider({ gfm: true, breaks: true }); // options are optional
 ```
 
 `@aparte/core` and `marked` are **peer dependencies**. For token-by-token incremental rendering during
-streaming, add `@aparte/plugin-streaming-markdown` alongside this.
+streaming, add `@aparte/plugin-streaming-markdown` alongside this — or use marked for the stream too:
+
+## Stream with marked
+
+```ts
+import { setupMarkedStreamingProvider } from '@aparte/plugin-marked/streaming';
+
+setupMarkedStreamingProvider(); // replaces setupMarkedProvider(); same options
+```
+
+marked formats the reply while it streams and once it is done, so a finished reply looks exactly as
+it did at its last chunk. The block being written is completed by Vercel's
+[`remend`](https://www.npmjs.com/package/remend) before marked reads it — `**bold` shows bold before
+its closing `**`, a link shows as a link from its first character — and drawn again at each chunk;
+the blocks above it are not. Every block goes through the config's sanitizer. `remend` is a
+dependency of this plugin, imported by the `/streaming` entry only.
 
 > ESM-only. Part of the aparté monorepo.

package/dist/streaming.d.ts

@@ -0,0 +1,30 @@
+import { type AparteConfig } from '@aparte/core';
+import { type MarkedExtension } from 'marked';
+/**
+ * Register [marked](https://marked.js.org) as aparté's Markdown renderer for a reply
+ * WHILE it streams and once it is finished — one parser on both sides, so a reply
+ * looks the same at its last chunk as when it settles.
+ *
+ * While a reply streams, the block being written is completed by Vercel's
+ * [`remend`](https://www.npmjs.com/package/remend) before marked parses it:
+ * `**bold` shows bold before its closing `**` arrives, and a link shows as a link
+ * from its first character, clickable once its URL is complete. Blocks already
+ * written are not drawn again, so a selection in them survives the stream. Every
+ * block goes through the config's sanitizer before it reaches the page.
+ *
+ * It takes both of aparté's Markdown seams — `setMarkdownProvider` and
+ * `setStreamingMarkdownProvider` — so it replaces `setupMarkedProvider` and
+ * `@aparte/plugin-streaming-markdown` rather than going beside them.
+ *
+ * Call once at application startup.
+ *
+ * @param options Optional marked extension(s), as for `setupMarkedProvider`: applied
+ *   to a private marked instance, to the streaming and the finished render alike.
+ * @param config The config to register on. Defaults to the global one.
+ *
+ * @example
+ * import { setupMarkedStreamingProvider } from '@aparte/plugin-marked/streaming';
+ * setupMarkedStreamingProvider({ gfm: true });
+ */
+export declare function setupMarkedStreamingProvider(options?: MarkedExtension, config?: AparteConfig): void;
+//# sourceMappingURL=streaming.d.ts.map

package/dist/streaming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.d.ts","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"AAAA,OAAO,EAAsB,KAAK,YAAY,EAAwC,MAAM,cAAc,CAAC;AAC3G,OAAO,EAAkB,KAAK,eAAe,EAAE,MAAM,QAAQ,CAAC;AAqF9D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,4BAA4B,CAAC,OAAO,CAAC,EAAE,eAAe,EAAE,MAAM,GAAE,YAAiC,GAAG,IAAI,CAKvH"}

package/dist/streaming.js

@@ -0,0 +1,61 @@
+import { aparteGlobalConfig } from "@aparte/core";
+import { Marked, marked } from "marked";
+import remend from "remend";
+const PENDING = "streamdown:";
+const BARE_OPENER = /(^|[ \t])[*_~`]+$/;
+function heal(raw) {
+  return remend(raw.replace(BARE_OPENER, "$1"));
+}
+function blockNodes(html, healed, config) {
+  const template = document.createElement("template");
+  template.innerHTML = html;
+  if (healed) {
+    for (const a of template.content.querySelectorAll(`a[href^="${PENDING}"]`)) a.removeAttribute("href");
+    for (const img of template.content.querySelectorAll(`img[src^="${PENDING}"]`)) img.remove();
+  }
+  template.innerHTML = config.sanitizeHtml(template.innerHTML);
+  return Array.from(template.content.childNodes);
+}
+function createRenderer(target, parser, config) {
+  let source = "";
+  let drawn = [];
+  const draw = (healLast) => {
+    const blocks = parser.lexer(source);
+    let from = 0;
+    while (from < blocks.length && from < drawn.length) {
+      const healed = healLast && from === blocks.length - 1;
+      const old = drawn[from];
+      if (old.raw !== blocks[from].raw || old.healed !== healed) break;
+      from++;
+    }
+    for (const old of drawn.slice(from)) for (const node of old.nodes) node.remove();
+    const next = drawn.slice(0, from);
+    for (let i = from; i < blocks.length; i++) {
+      const raw = blocks[i].raw;
+      const healed = healLast && i === blocks.length - 1;
+      const html = parser.parse(healed ? heal(raw) : raw, { async: false });
+      const nodes = blockNodes(html, healed, config);
+      target.append(...nodes);
+      next.push({ raw, healed, nodes });
+    }
+    drawn = next;
+  };
+  return {
+    write(chunk) {
+      source += chunk;
+      draw(true);
+    },
+    end() {
+      draw(false);
+    }
+  };
+}
+function setupMarkedStreamingProvider(options, config = aparteGlobalConfig) {
+  const parser = options ? new Marked(options) : marked;
+  config.setMarkdownProvider((raw) => parser.parse(raw, { async: false }));
+  config.setStreamingMarkdownProvider((target) => createRenderer(target, parser, config));
+}
+export {
+  setupMarkedStreamingProvider
+};
+//# sourceMappingURL=streaming.js.map

package/dist/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sources":["../src/streaming.ts"],"sourcesContent":["import { aparteGlobalConfig, type AparteConfig, type AparteStreamingMarkdownRenderer } from '@aparte/core';\nimport { Marked, marked, type MarkedExtension } from 'marked';\nimport remend from 'remend';\n\n/*\n * What remend writes where a link or an image has no destination yet. Not a URL\n * anyone can follow: a pending link loses its `href`, so it reads as a link from its\n * first character without going anywhere, and a pending image is left out, since\n * there is nothing to show until its URL is complete.\n */\nconst PENDING = 'streamdown:';\n\n/*\n * A marker that opens and has nothing after it yet — `I am a **`. remend completes\n * `**scr` but has nothing to complete here, so the marker would show as typed until\n * the next chunk. After a space it can only open (a closer follows a character, not\n * a space), so holding it back never hides one that closes.\n */\nconst BARE_OPENER = /(^|[ \\t])[*_~`]+$/;\n\n/** The block being written, completed so that marked reads it as it will end. */\nfunction heal(raw: string): string {\n    return remend(raw.replace(BARE_OPENER, '$1'));\n}\n\n/** One top-level Markdown block as it was last drawn. */\ninterface DrawnBlock {\n    /** The block's source, which is what decides whether it has to be drawn again. */\n    raw: string;\n    /** Whether it was drawn completed by remend, as the block still being written is. */\n    healed: boolean;\n    /** The nodes it put in the target, in order. */\n    nodes: ChildNode[];\n}\n\nfunction blockNodes(html: string, healed: boolean, config: AparteConfig): ChildNode[] {\n    const template = document.createElement('template');\n    template.innerHTML = html;\n    if (healed) {\n        for (const a of template.content.querySelectorAll(`a[href^=\"${PENDING}\"]`)) a.removeAttribute('href');\n        for (const img of template.content.querySelectorAll(`img[src^=\"${PENDING}\"]`)) img.remove();\n    }\n    // Model-authored, like everything a Markdown provider returns: the config's own\n    // sanitizer runs before any of it reaches the page, external links included.\n    template.innerHTML = config.sanitizeHtml(template.innerHTML);\n    return Array.from(template.content.childNodes);\n}\n\nfunction createRenderer(target: HTMLElement, parser: Marked, config: AparteConfig): AparteStreamingMarkdownRenderer {\n    let source = '';\n    let drawn: DrawnBlock[] = [];\n\n    const draw = (healLast: boolean): void => {\n        const blocks = parser.lexer(source);\n        // The first block whose source moved; everything before it keeps its DOM.\n        let from = 0;\n        while (from < blocks.length && from < drawn.length) {\n            const healed = healLast && from === blocks.length - 1;\n            const old = drawn[from]!;\n            if (old.raw !== blocks[from]!.raw || old.healed !== healed) break;\n            from++;\n        }\n        for (const old of drawn.slice(from)) for (const node of old.nodes) node.remove();\n        const next = drawn.slice(0, from);\n        for (let i = from; i < blocks.length; i++) {\n            const raw = blocks[i]!.raw;\n            const healed = healLast && i === blocks.length - 1;\n            const html = parser.parse(healed ? heal(raw) : raw, { async: false }) as string;\n            const nodes = blockNodes(html, healed, config);\n            target.append(...nodes);\n            next.push({ raw, healed, nodes });\n        }\n        drawn = next;\n    };\n\n    return {\n        write(chunk: string): void {\n            source += chunk;\n            draw(true);\n        },\n        end(): void {\n            draw(false);\n        },\n    };\n}\n\n/**\n * Register [marked](https://marked.js.org) as aparté's Markdown renderer for a reply\n * WHILE it streams and once it is finished — one parser on both sides, so a reply\n * looks the same at its last chunk as when it settles.\n *\n * While a reply streams, the block being written is completed by Vercel's\n * [`remend`](https://www.npmjs.com/package/remend) before marked parses it:\n * `**bold` shows bold before its closing `**` arrives, and a link shows as a link\n * from its first character, clickable once its URL is complete. Blocks already\n * written are not drawn again, so a selection in them survives the stream. Every\n * block goes through the config's sanitizer before it reaches the page.\n *\n * It takes both of aparté's Markdown seams — `setMarkdownProvider` and\n * `setStreamingMarkdownProvider` — so it replaces `setupMarkedProvider` and\n * `@aparte/plugin-streaming-markdown` rather than going beside them.\n *\n * Call once at application startup.\n *\n * @param options Optional marked extension(s), as for `setupMarkedProvider`: applied\n *   to a private marked instance, to the streaming and the finished render alike.\n * @param config The config to register on. Defaults to the global one.\n *\n * @example\n * import { setupMarkedStreamingProvider } from '@aparte/plugin-marked/streaming';\n * setupMarkedStreamingProvider({ gfm: true });\n */\nexport function setupMarkedStreamingProvider(options?: MarkedExtension, config: AparteConfig = aparteGlobalConfig): void {\n    // Private instance when options are given, for the reason `setupMarkedProvider` gives.\n    const parser = options ? new Marked(options) : marked;\n    config.setMarkdownProvider((raw) => parser.parse(raw, { async: false }) as string);\n    config.setStreamingMarkdownProvider((target) => createRenderer(target, parser as Marked, config));\n}\n"],"names":[],"mappings":";;;AAUA,MAAM,UAAU;AAQhB,MAAM,cAAc;AAGpB,SAAS,KAAK,KAAqB;AAC/B,SAAO,OAAO,IAAI,QAAQ,aAAa,IAAI,CAAC;AAChD;AAYA,SAAS,WAAW,MAAc,QAAiB,QAAmC;AAClF,QAAM,WAAW,SAAS,cAAc,UAAU;AAClD,WAAS,YAAY;AACrB,MAAI,QAAQ;AACR,eAAW,KAAK,SAAS,QAAQ,iBAAiB,YAAY,OAAO,IAAI,EAAG,GAAE,gBAAgB,MAAM;AACpG,eAAW,OAAO,SAAS,QAAQ,iBAAiB,aAAa,OAAO,IAAI,EAAG,KAAI,OAAA;AAAA,EACvF;AAGA,WAAS,YAAY,OAAO,aAAa,SAAS,SAAS;AAC3D,SAAO,MAAM,KAAK,SAAS,QAAQ,UAAU;AACjD;AAEA,SAAS,eAAe,QAAqB,QAAgB,QAAuD;AAChH,MAAI,SAAS;AACb,MAAI,QAAsB,CAAA;AAE1B,QAAM,OAAO,CAAC,aAA4B;AACtC,UAAM,SAAS,OAAO,MAAM,MAAM;AAElC,QAAI,OAAO;AACX,WAAO,OAAO,OAAO,UAAU,OAAO,MAAM,QAAQ;AAChD,YAAM,SAAS,YAAY,SAAS,OAAO,SAAS;AACpD,YAAM,MAAM,MAAM,IAAI;AACtB,UAAI,IAAI,QAAQ,OAAO,IAAI,EAAG,OAAO,IAAI,WAAW,OAAQ;AAC5D;AAAA,IACJ;AACA,eAAW,OAAO,MAAM,MAAM,IAAI,cAAc,QAAQ,IAAI,MAAO,MAAK,OAAA;AACxE,UAAM,OAAO,MAAM,MAAM,GAAG,IAAI;AAChC,aAAS,IAAI,MAAM,IAAI,OAAO,QAAQ,KAAK;AACvC,YAAM,MAAM,OAAO,CAAC,EAAG;AACvB,YAAM,SAAS,YAAY,MAAM,OAAO,SAAS;AACjD,YAAM,OAAO,OAAO,MAAM,SAAS,KAAK,GAAG,IAAI,KAAK,EAAE,OAAO,MAAA,CAAO;AACpE,YAAM,QAAQ,WAAW,MAAM,QAAQ,MAAM;AAC7C,aAAO,OAAO,GAAG,KAAK;AACtB,WAAK,KAAK,EAAE,KAAK,QAAQ,OAAO;AAAA,IACpC;AACA,YAAQ;AAAA,EACZ;AAEA,SAAO;AAAA,IACH,MAAM,OAAqB;AACvB,gBAAU;AACV,WAAK,IAAI;AAAA,IACb;AAAA,IACA,MAAY;AACR,WAAK,KAAK;AAAA,IACd;AAAA,EAAA;AAER;AA4BO,SAAS,6BAA6B,SAA2B,SAAuB,oBAA0B;AAErH,QAAM,SAAS,UAAU,IAAI,OAAO,OAAO,IAAI;AAC/C,SAAO,oBAAoB,CAAC,QAAQ,OAAO,MAAM,KAAK,EAAE,OAAO,MAAA,CAAO,CAAW;AACjF,SAAO,6BAA6B,CAAC,WAAW,eAAe,QAAQ,QAAkB,MAAM,CAAC;AACpG;"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aparte/plugin-marked",
-  "version": "0.19.3",
+  "version": "0.21.0",
   "homepage": "https://apartejs.dev/plugins/marked/",
   "description": "Markdown rendering for aparté via marked — register it as the one-shot Markdown provider.",
   "type": "module",
@@ -14,6 +14,12 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./streaming": {
+      "@aparte-workspace/source": "./src/streaming.ts",
+      "types": "./dist/streaming.d.ts",
+      "import": "./dist/streaming.js",
+      "default": "./dist/streaming.js"
     }
   },
   "files": [
@@ -24,21 +30,25 @@
   "engines": {
     "node": ">=18"
   },
+  "dependencies": {
+    "remend": "^1.4.0"
+  },
   "peerDependencies": {
-    "@aparte/core": ">=0.19.3 <1.0.0",
+    "@aparte/core": ">=0.21.0 <1.0.0",
     "marked": "^18.0.0"
   },
   "devDependencies": {
     "marked": "^18.0.0",
     "typescript": "^5.4.0",
     "vite": "^6.0.0",
-    "@aparte/core": "0.19.3"
+    "@aparte/core": "0.21.0"
   },
   "keywords": [
     "aparte",
     "plugin",
     "markdown",
-    "marked"
+    "marked",
+    "streaming"
   ],
   "license": "MIT",
   "repository": {
@@ -51,7 +61,7 @@
   },
   "scripts": {
     "dev": "vite",
-    "build": "vite build && tsc -b --emitDeclarationOnly --force",
+    "build": "vite build && tsc -b --emitDeclarationOnly --force && node ../../../scripts/stamp-dist.mjs",
     "preview": "vite preview",
     "test": "vitest",
     "test:run": "vitest run",