@stream-mdx/unified 0.0.0-stage → 1.0.0

package/dist/index.d.cts

@@ -0,0 +1,87 @@
+import * as unified from 'unified';
+import { PluggableList } from 'unified';
+export { PluggableList } from 'unified';
+import * as hast from 'hast';
+import * as mdast from 'mdast';
+import React$1 from 'react';
+import { UrlTransform, BlockResolvedLinkReference } from '@stream-mdx/core';
+import { NodePresentations, ComponentRegistry } from '@stream-mdx/react';
+
+interface UnifiedBlockErrorContext {
+    readonly id: string;
+    readonly type: string;
+    readonly finalized: boolean;
+}
+interface UnifiedRendererOptions {
+    remarkPlugins?: PluggableList;
+    rehypePlugins?: PluggableList;
+    components?: NodePresentations;
+    hastComponents?: Record<string, React.ComponentType<Record<string, unknown>>>;
+    /**
+     * Block types to route through the unified pipeline.
+     * Defaults to: ["paragraph", "heading", "blockquote", "list", "table", "code", "hr"]
+     */
+    blockTypes?: string[];
+    /**
+     * Enable math support (remark-math). Defaults to false.
+     */
+    math?: boolean;
+    /**
+     * Enable GitHub Flavored Markdown (remark-gfm). Defaults to true.
+     */
+    gfm?: boolean;
+    /**
+     * Maximum number of rendered blocks to retain in LRU cache. Defaults to 500.
+     */
+    cacheSize?: number;
+    /**
+     * Explicit callback invoked when a unified plugin encounters an error.
+     * When provided, errors are forwarded here instead of only being logged.
+     */
+    onError?: (error: Error, context: UnifiedBlockErrorContext) => void;
+    urlTransform?: UrlTransform;
+}
+type UnifiedRenderer = NodePresentations & {
+    clearCache(): void;
+    options: UnifiedRendererOptions;
+};
+
+declare function buildProcessor(options: UnifiedRendererOptions): unified.Processor<mdast.Root, mdast.Root, hast.Root, undefined, undefined>;
+type UnifiedProcessor = ReturnType<typeof buildProcessor>;
+type JobOutcome = {
+    readonly kind: "success";
+    readonly node: React$1.ReactNode;
+} | {
+    readonly kind: "error";
+    readonly error: Error;
+};
+interface UnifiedJob {
+    readonly promise: Promise<JobOutcome>;
+    outcome?: JobOutcome;
+}
+declare class BoundedLruCache<K, V> {
+    private readonly maxEntries;
+    private readonly map;
+    constructor(maxEntries?: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    clear(): void;
+    get size(): number;
+}
+interface UnifiedBlockItemProps {
+    id: string;
+    type: string;
+    finalized: boolean;
+    source: string;
+    linkReferences?: readonly BlockResolvedLinkReference[];
+    element: React$1.ReactElement;
+    processor: UnifiedProcessor;
+    options: UnifiedRendererOptions;
+    cache: BoundedLruCache<string, React$1.ReactNode>;
+    inflightJobs: Map<string, UnifiedJob>;
+    registry: ComponentRegistry | null;
+}
+declare const UnifiedBlockItem: React$1.FC<UnifiedBlockItemProps>;
+declare function createUnifiedRenderer(options?: UnifiedRendererOptions): UnifiedRenderer;
+
+export { type UnifiedBlockErrorContext, UnifiedBlockItem, type UnifiedRenderer, type UnifiedRendererOptions, createUnifiedRenderer };

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+import * as unified from 'unified';
+import { PluggableList } from 'unified';
+export { PluggableList } from 'unified';
+import * as hast from 'hast';
+import * as mdast from 'mdast';
+import React$1 from 'react';
+import { UrlTransform, BlockResolvedLinkReference } from '@stream-mdx/core';
+import { NodePresentations, ComponentRegistry } from '@stream-mdx/react';
+
+interface UnifiedBlockErrorContext {
+    readonly id: string;
+    readonly type: string;
+    readonly finalized: boolean;
+}
+interface UnifiedRendererOptions {
+    remarkPlugins?: PluggableList;
+    rehypePlugins?: PluggableList;
+    components?: NodePresentations;
+    hastComponents?: Record<string, React.ComponentType<Record<string, unknown>>>;
+    /**
+     * Block types to route through the unified pipeline.
+     * Defaults to: ["paragraph", "heading", "blockquote", "list", "table", "code", "hr"]
+     */
+    blockTypes?: string[];
+    /**
+     * Enable math support (remark-math). Defaults to false.
+     */
+    math?: boolean;
+    /**
+     * Enable GitHub Flavored Markdown (remark-gfm). Defaults to true.
+     */
+    gfm?: boolean;
+    /**
+     * Maximum number of rendered blocks to retain in LRU cache. Defaults to 500.
+     */
+    cacheSize?: number;
+    /**
+     * Explicit callback invoked when a unified plugin encounters an error.
+     * When provided, errors are forwarded here instead of only being logged.
+     */
+    onError?: (error: Error, context: UnifiedBlockErrorContext) => void;
+    urlTransform?: UrlTransform;
+}
+type UnifiedRenderer = NodePresentations & {
+    clearCache(): void;
+    options: UnifiedRendererOptions;
+};
+
+declare function buildProcessor(options: UnifiedRendererOptions): unified.Processor<mdast.Root, mdast.Root, hast.Root, undefined, undefined>;
+type UnifiedProcessor = ReturnType<typeof buildProcessor>;
+type JobOutcome = {
+    readonly kind: "success";
+    readonly node: React$1.ReactNode;
+} | {
+    readonly kind: "error";
+    readonly error: Error;
+};
+interface UnifiedJob {
+    readonly promise: Promise<JobOutcome>;
+    outcome?: JobOutcome;
+}
+declare class BoundedLruCache<K, V> {
+    private readonly maxEntries;
+    private readonly map;
+    constructor(maxEntries?: number);
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    clear(): void;
+    get size(): number;
+}
+interface UnifiedBlockItemProps {
+    id: string;
+    type: string;
+    finalized: boolean;
+    source: string;
+    linkReferences?: readonly BlockResolvedLinkReference[];
+    element: React$1.ReactElement;
+    processor: UnifiedProcessor;
+    options: UnifiedRendererOptions;
+    cache: BoundedLruCache<string, React$1.ReactNode>;
+    inflightJobs: Map<string, UnifiedJob>;
+    registry: ComponentRegistry | null;
+}
+declare const UnifiedBlockItem: React$1.FC<UnifiedBlockItemProps>;
+declare function createUnifiedRenderer(options?: UnifiedRendererOptions): UnifiedRenderer;
+
+export { type UnifiedBlockErrorContext, UnifiedBlockItem, type UnifiedRenderer, type UnifiedRendererOptions, createUnifiedRenderer };

package/dist/index.mjs

@@ -0,0 +1,326 @@
+"use client";
+
+// src/unified-renderer.tsx
+import React, { useEffect, useMemo, useState } from "react";
+import { jsx, jsxs, Fragment } from "react/jsx-runtime";
+import { unified } from "unified";
+import remarkParse from "remark-parse";
+import remarkGfm from "remark-gfm";
+import remarkMath from "remark-math";
+import remarkRehype from "remark-rehype";
+import { toJsxRuntime } from "hast-util-to-jsx-runtime";
+import { defaultUrlTransform, isForbiddenAttribute } from "@stream-mdx/core";
+import { ComponentRegistry, createRendererStore, renderNodePresentation } from "@stream-mdx/react";
+import { Fragment as Fragment2, jsx as jsx2 } from "react/jsx-runtime";
+function sanitizeHastUrls(node, transform) {
+  if (!node || typeof node !== "object") return;
+  const record = node;
+  if (record.type === "element" && record.properties && typeof record.properties === "object") {
+    const properties = record.properties;
+    for (const key of Object.keys(properties)) {
+      if (isForbiddenAttribute(key)) {
+        delete properties[key];
+      }
+    }
+    if (properties.href !== void 0 && properties.href !== null) {
+      const safe = transform(String(properties.href), "href", { source: "markdown" });
+      if (safe != null) {
+        properties.href = safe;
+      } else {
+        delete properties.href;
+      }
+    }
+    if (properties.src !== void 0 && properties.src !== null) {
+      const safe = transform(String(properties.src), "src", { source: "markdown" });
+      if (safe != null) {
+        properties.src = safe;
+      } else {
+        delete properties.src;
+      }
+    }
+    if (properties.action !== void 0 && properties.action !== null) {
+      const safe = transform(String(properties.action), "href", { source: "html" });
+      if (safe != null) {
+        properties.action = safe;
+      } else {
+        delete properties.action;
+      }
+    }
+    if (properties.formAction !== void 0 && properties.formAction !== null) {
+      const safe = transform(String(properties.formAction), "href", { source: "html" });
+      if (safe != null) {
+        properties.formAction = safe;
+      } else {
+        delete properties.formAction;
+      }
+    }
+    if (properties.xlinkHref !== void 0 && properties.xlinkHref !== null) {
+      const safe = transform(String(properties.xlinkHref), "href", { source: "html" });
+      if (safe != null) {
+        properties.xlinkHref = safe;
+      } else {
+        delete properties.xlinkHref;
+      }
+    }
+    if (properties["xlink:href"] !== void 0 && properties["xlink:href"] !== null) {
+      const safe = transform(String(properties["xlink:href"]), "href", { source: "html" });
+      if (safe != null) {
+        properties["xlink:href"] = safe;
+      } else {
+        delete properties["xlink:href"];
+      }
+    }
+  }
+  if (Array.isArray(record.children)) {
+    for (const child of record.children) {
+      sanitizeHastUrls(child, transform);
+    }
+  }
+}
+function buildProcessor(options) {
+  const transform = options.urlTransform ?? defaultUrlTransform;
+  return unified().use(remarkParse).use(options.gfm === false ? [] : [remarkGfm]).use(options.math ? [remarkMath] : []).use(options.remarkPlugins ?? []).use(remarkRehype).use(options.rehypePlugins ?? []).use(() => (tree) => {
+    sanitizeHastUrls(tree, transform);
+  }).freeze();
+}
+var DEFAULT_ROUTED_BLOCK_TYPES = {
+  paragraph: true,
+  heading: true,
+  blockquote: true,
+  list: true,
+  table: true,
+  code: true,
+  hr: true
+};
+var BoundedLruCache = class {
+  constructor(maxEntries = 500) {
+    this.map = /* @__PURE__ */ new Map();
+    this.maxEntries = Math.max(1, maxEntries);
+  }
+  get(key) {
+    const value = this.map.get(key);
+    if (value !== void 0) {
+      this.map.delete(key);
+      this.map.set(key, value);
+    }
+    return value;
+  }
+  set(key, value) {
+    if (this.map.has(key)) {
+      this.map.delete(key);
+    } else if (this.map.size >= this.maxEntries) {
+      const oldestKey = this.map.keys().next().value;
+      if (oldestKey !== void 0) {
+        this.map.delete(oldestKey);
+      }
+    }
+    this.map.set(key, value);
+  }
+  clear() {
+    this.map.clear();
+  }
+  get size() {
+    return this.map.size;
+  }
+};
+function formatLinkDefinitions(refs) {
+  const lines = [];
+  for (const ref of refs) {
+    if (!ref.label || !ref.href) continue;
+    const cleanHref = `<${ref.href.replace(/>/g, "%3E")}>`;
+    if (ref.title) {
+      const cleanTitle = ref.title.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
+      lines.push(`[${ref.label}]: ${cleanHref} "${cleanTitle}"`);
+    } else {
+      lines.push(`[${ref.label}]: ${cleanHref}`);
+    }
+  }
+  return lines.join("\n");
+}
+function getOrCreateJob(cacheKey, input, context, processor, options, cache, inflightJobs) {
+  const existing = inflightJobs.get(cacheKey);
+  if (existing) {
+    return existing;
+  }
+  let resolve;
+  const promise = new Promise((res) => {
+    resolve = res;
+  });
+  const job = { promise };
+  inflightJobs.set(cacheKey, job);
+  let mdast;
+  try {
+    mdast = processor.parse(input);
+  } catch (parseError) {
+    const error = parseError instanceof Error ? parseError : new Error(String(parseError));
+    const outcome = { kind: "error", error };
+    job.outcome = outcome;
+    inflightJobs.delete(cacheKey);
+    resolve(outcome);
+    if (options.onError) {
+      options.onError(error, context);
+    } else {
+      console.error("Unified markdown parse failed:", error);
+    }
+    return job;
+  }
+  processor.run(mdast, (runError, hast) => {
+    if (runError || !hast) {
+      const error = runError instanceof Error ? runError : new Error(String(runError ?? "Unified block transformation failed"));
+      const outcome = { kind: "error", error };
+      job.outcome = outcome;
+      inflightJobs.delete(cacheKey);
+      resolve(outcome);
+      if (options.onError) {
+        options.onError(error, context);
+      } else {
+        console.error("Unified block transformation failed:", error);
+      }
+      return;
+    }
+    try {
+      const node = toJsxRuntime(hast, {
+        Fragment,
+        jsx,
+        jsxs,
+        components: options.hastComponents
+      });
+      const outcome = { kind: "success", node };
+      job.outcome = outcome;
+      cache.set(cacheKey, node);
+      inflightJobs.delete(cacheKey);
+      resolve(outcome);
+    } catch (renderError) {
+      const error = renderError instanceof Error ? renderError : new Error(String(renderError));
+      const outcome = { kind: "error", error };
+      job.outcome = outcome;
+      inflightJobs.delete(cacheKey);
+      resolve(outcome);
+      if (options.onError) {
+        options.onError(error, context);
+      } else {
+        console.error("Unified JSX runtime conversion failed:", error);
+      }
+    }
+  });
+  return job;
+}
+var UnifiedBlockItem = ({
+  id,
+  type,
+  finalized,
+  source,
+  linkReferences,
+  element,
+  processor,
+  options,
+  cache,
+  inflightJobs,
+  registry
+}) => {
+  const block = useMemo(() => ({
+    id,
+    type,
+    isFinalized: finalized,
+    payload: {
+      raw: source,
+      ...linkReferences === void 0 ? {} : { meta: { linkReferences } }
+    }
+  }), [finalized, id, linkReferences, source, type]);
+  const presentationStore = useMemo(
+    () => registry === null ? null : createRendererStore([block]),
+    [block, registry]
+  );
+  const metaRefs = linkReferences;
+  const serializedRefs = metaRefs && metaRefs.length > 0 ? JSON.stringify(metaRefs) : "";
+  const cacheKey = `${id}::${type}::${source}::${serializedRefs}`;
+  const cached = cache.get(cacheKey);
+  const job = useMemo(() => {
+    if (cached !== void 0) {
+      return void 0;
+    }
+    const linkDefs = metaRefs && metaRefs.length > 0 ? formatLinkDefinitions(metaRefs) : "";
+    const input = linkDefs ? `${linkDefs}
+
+${source}` : source;
+    return getOrCreateJob(cacheKey, input, { id, type, finalized }, processor, options, cache, inflightJobs);
+  }, [cacheKey, cached, block, processor, options, cache, inflightJobs, metaRefs, source, finalized, id, type]);
+  const [asyncState, setAsyncState] = useState(null);
+  useEffect(() => {
+    if (!job || job.outcome !== void 0) {
+      return;
+    }
+    let cancelled = false;
+    job.promise.then((outcome) => {
+      if (!cancelled && outcome.kind === "success") {
+        setAsyncState({ key: cacheKey, node: outcome.node });
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  }, [cacheKey, job]);
+  let output = element;
+  if (cached !== void 0) {
+    output = cached;
+  } else if (job?.outcome !== void 0) {
+    if (job.outcome.kind === "success") {
+      output = job.outcome.node;
+    }
+  } else if (asyncState !== null && asyncState.key === cacheKey) {
+    output = asyncState.node;
+  }
+  const presentedOutput = registry === null || presentationStore === null ? output : renderNodePresentation(block, output, presentationStore, registry);
+  if (React.isValidElement(presentedOutput)) {
+    return presentedOutput;
+  }
+  return /* @__PURE__ */ jsx2(Fragment2, { children: presentedOutput });
+};
+function createUnifiedRenderer(options = {}) {
+  const cache = new BoundedLruCache(options.cacheSize ?? 500);
+  const inflightJobs = /* @__PURE__ */ new Map();
+  const processor = buildProcessor(options);
+  const registry = Object.keys(options.components ?? {}).length > 0 ? new ComponentRegistry({ components: options.components }) : null;
+  const routedTypeMap = options.blockTypes ? Object.fromEntries(options.blockTypes.map((type) => [type, true])) : DEFAULT_ROUTED_BLOCK_TYPES;
+  const presentationTypes = options.blockTypes ?? Object.keys(DEFAULT_ROUTED_BLOCK_TYPES);
+  const renderUnifiedBlock = ({ metadata, actions, children }) => {
+    if (!metadata.isFinalized || !routedTypeMap[metadata.type]) return /* @__PURE__ */ jsx2(Fragment2, { children });
+    const element = React.isValidElement(children) ? children : /* @__PURE__ */ jsx2(Fragment2, { children });
+    return /* @__PURE__ */ jsx2(
+      UnifiedBlockItem,
+      {
+        id: metadata.id,
+        type: metadata.type,
+        finalized: metadata.isFinalized,
+        source: actions.readSource(),
+        linkReferences: metadata.linkReferences,
+        element,
+        processor,
+        options,
+        cache,
+        inflightJobs,
+        registry
+      },
+      metadata.id
+    );
+  };
+  const renderer = {
+    ...Object.fromEntries(
+      presentationTypes.map((type) => [type, { wrapper: renderUnifiedBlock }])
+    ),
+    clearCache() {
+      cache.clear();
+      inflightJobs.clear();
+    },
+    options
+  };
+  Object.defineProperties(renderer, {
+    clearCache: { enumerable: false },
+    options: { enumerable: false }
+  });
+  return renderer;
+}
+export {
+  UnifiedBlockItem,
+  createUnifiedRenderer
+};

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "@stream-mdx/unified",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Remark and Rehype unified plugin adapter for StreamMDX",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kmccleary3301/stream-mdx.git",
+    "directory": "packages/markdown-v2-unified"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "npm run clean && tsup",
+    "test": "tsx ../../scripts/run-tests.ts __tests__",
+    "clean": "rm -rf dist",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "hast-util-to-jsx-runtime": "^2.3.6",
+    "remark-gfm": "^4.0.1",
+    "remark-math": "^6.0.0",
+    "remark-parse": "^11.0.0",
+    "remark-rehype": "^11.1.2",
+    "unified": "^11.0.5"
+  },
+  "peerDependencies": {
+    "@stream-mdx/core": "^1.0.0",
+    "@stream-mdx/react": "^1.0.0",
+    "react": ">=18.2.0",
+    "react-dom": ">=18.2.0"
+  },
+  "peerDependenciesMeta": {
+    "@stream-mdx/core": {
+      "optional": true
+    },
+    "@stream-mdx/react": {
+      "optional": true
+    }
+  }
+}