markstream-solid 0.0.0-stage → 2.0.23

package/dist/utils/performance-monitor.d.ts

@@ -0,0 +1,121 @@
+/**
+ * Performance monitoring utility for KaTeX rendering
+ * Helps determine if Worker is beneficial in production
+ */
+interface RenderMetrics {
+    type: 'worker' | 'direct' | 'cache-hit';
+    duration: number;
+    formulaLength: number;
+    timestamp: number;
+    success: boolean;
+    error?: string;
+}
+declare class PerformanceMonitor {
+    private metrics;
+    private enabled;
+    private maxMetrics;
+    enable(): void;
+    disable(): void;
+    recordRender(metrics: RenderMetrics): void;
+    getStats(): {
+        totalRenders: number;
+        cacheHitRate: number;
+        averageWorkerTime: number;
+        averageDirectTime: number;
+        averageCacheHitTime: number;
+        workerSavings: number;
+        recommendation: string;
+        cacheHits?: undefined;
+        workerCalls?: undefined;
+        directCalls?: undefined;
+    } | {
+        totalRenders: number;
+        cacheHits: number;
+        cacheHitRate: string;
+        workerCalls: number;
+        directCalls: number;
+        averageWorkerTime: string;
+        averageDirectTime: string;
+        averageCacheHitTime: string;
+        workerSavings: string;
+        recommendation: string;
+    };
+    printReport(): {
+        totalRenders: number;
+        cacheHitRate: number;
+        averageWorkerTime: number;
+        averageDirectTime: number;
+        averageCacheHitTime: number;
+        workerSavings: number;
+        recommendation: string;
+        cacheHits?: undefined;
+        workerCalls?: undefined;
+        directCalls?: undefined;
+    } | {
+        totalRenders: number;
+        cacheHits: number;
+        cacheHitRate: string;
+        workerCalls: number;
+        directCalls: number;
+        averageWorkerTime: string;
+        averageDirectTime: string;
+        averageCacheHitTime: string;
+        workerSavings: string;
+        recommendation: string;
+    };
+    reset(): void;
+    exportMetrics(): {
+        metrics: RenderMetrics[];
+        stats: {
+            totalRenders: number;
+            cacheHitRate: number;
+            averageWorkerTime: number;
+            averageDirectTime: number;
+            averageCacheHitTime: number;
+            workerSavings: number;
+            recommendation: string;
+            cacheHits?: undefined;
+            workerCalls?: undefined;
+            directCalls?: undefined;
+        } | {
+            totalRenders: number;
+            cacheHits: number;
+            cacheHitRate: string;
+            workerCalls: number;
+            directCalls: number;
+            averageWorkerTime: string;
+            averageDirectTime: string;
+            averageCacheHitTime: string;
+            workerSavings: string;
+            recommendation: string;
+        };
+        timestamp: number;
+    };
+}
+export declare const perfMonitor: PerformanceMonitor;
+export declare function enablePerfMonitoring(): void;
+export declare function disablePerfMonitoring(): void;
+export declare function getPerfReport(): {
+    totalRenders: number;
+    cacheHitRate: number;
+    averageWorkerTime: number;
+    averageDirectTime: number;
+    averageCacheHitTime: number;
+    workerSavings: number;
+    recommendation: string;
+    cacheHits?: undefined;
+    workerCalls?: undefined;
+    directCalls?: undefined;
+} | {
+    totalRenders: number;
+    cacheHits: number;
+    cacheHitRate: string;
+    workerCalls: number;
+    directCalls: number;
+    averageWorkerTime: string;
+    averageDirectTime: string;
+    averageCacheHitTime: string;
+    workerSavings: string;
+    recommendation: string;
+};
+export {};

package/dist/utils/resolveLanguageIcon.d.ts

@@ -0,0 +1,2 @@
+import type { LanguageIconResolver } from './languageIcon';
+export declare function resolveLanguageIcon(lang: string, appScopedResolver?: LanguageIconResolver | null): string;

package/dist/utils/safeRaf.d.ts

@@ -0,0 +1,2 @@
+export declare function safeRaf(cb: FrameRequestCallback): any;
+export declare function safeCancelRaf(id: number | null): void;

package/dist/utils/virtualItemMeasurement.d.ts

@@ -0,0 +1,5 @@
+export type VirtualItemLayoutReadCounter = (label: string) => void;
+export declare function readElementBoxHeight(element: HTMLElement | null | undefined, countRead?: VirtualItemLayoutReadCounter): number;
+export declare function readElementOuterHeight(element: HTMLElement | null | undefined, countRead?: VirtualItemLayoutReadCounter): number;
+export declare function findMarkstreamRenderer(element: HTMLElement | null | undefined): HTMLElement | null;
+export declare function getMarkdownItemChromeHeight(element: HTMLElement | null | undefined, countRead?: VirtualItemLayoutReadCounter, outerHeight?: number): number;

package/dist/virtual-adapter.d.ts

@@ -0,0 +1,165 @@
+import type { Accessor } from 'solid-js';
+import type { MarkstreamVirtualMetrics, MarkstreamVirtualState, NodeRendererMode, NodeRendererProps } from './types/node-renderer-props';
+type MaybeAccessor<T> = T | Accessor<T>;
+export type MarkstreamTimelineItemKey = string | number;
+export interface MarkstreamTimelineItem {
+    id: MarkstreamTimelineItemKey;
+    kind?: string;
+    content?: string;
+    final?: boolean;
+    revision?: MarkstreamTimelineItemKey;
+    text?: string;
+    label?: string;
+    status?: string;
+    message?: string;
+    component?: unknown;
+}
+export interface MarkstreamVirtualTimelineProps<T = MarkstreamTimelineItem> {
+    items: readonly T[];
+    threadKey?: MarkstreamTimelineItemKey;
+    /**
+     * Optional external layout invalidation token.
+     *
+     * When provided, MarkstreamVirtualTimeline skips per-item content/kind scanning
+     * and rebuilds the Fenwick layout only when this token or item count changes.
+     * Bump it whenever item key/kind/markdown-ness/component/estimated-height inputs change.
+     * Pure markdown content/final updates can keep the same value.
+     */
+    layoutRevision?: MarkstreamTimelineItemKey;
+    getKey?: (item: T, index: number) => MarkstreamTimelineItemKey;
+    getKind?: (item: T, index: number) => string;
+    getContent?: (item: T, index: number) => string;
+    getFinal?: (item: T, index: number) => boolean;
+    getRevision?: (item: T, index: number) => MarkstreamTimelineItemKey | undefined;
+    estimateItemHeight?: (item: T, index: number) => number;
+    overscan?: number;
+    overscanPx?: number;
+    stickToBottom?: boolean | 'auto';
+    measurementKey?: string | number;
+    markdownMode?: NodeRendererMode;
+    renderCodeBlocksAsPre?: boolean;
+    /**
+     * Initial state for the active thread.
+     *
+     * Pass this before first render if the host persisted a previous state.
+     * This prevents a first-frame jump from estimated scrollTop to restored scrollTop.
+     */
+    initialThreadState?: MarkstreamThreadVirtualState | null;
+    /**
+     * Default: false.
+     */
+    markdownFade?: boolean;
+    /**
+     * Default: false. Keep restore loading visible until the viewport is ready.
+     */
+    restoreMaxLoadingMs?: number | false;
+    debug?: boolean;
+}
+export interface MarkstreamVisibleRange {
+    start: number;
+    end: number;
+}
+export interface MarkstreamOuterVirtualizerAdapter {
+    getScrollElement: () => HTMLElement | null;
+    getScrollTop: () => number;
+    setScrollTop: (value: number) => void;
+    getViewportHeight: () => number;
+    getTotalHeight: () => number;
+    getItemOffset: (key: string) => number;
+    getItemSize: (key: string) => number;
+    setItemSize: (key: string, size: number) => void;
+    getVisibleRange: () => MarkstreamVisibleRange;
+    scrollToOffset: (offset: number) => void;
+    scrollToIndex: (index: number, align?: 'start' | 'center' | 'end') => void;
+    measureElement?: (key: string, el: HTMLElement) => void;
+}
+export interface MarkstreamOuterAnchor {
+    type: 'item';
+    itemKey: string;
+    offsetWithinItemPx: number;
+}
+export interface MarkstreamBottomAnchor {
+    type: 'bottom';
+    distanceFromBottomPx: number;
+}
+export type MarkstreamThreadAnchor = MarkstreamOuterAnchor | MarkstreamBottomAnchor;
+export interface MarkstreamThreadVirtualState {
+    threadKey?: string;
+    measurementKey?: string;
+    widthBucket?: number;
+    outerAnchor?: MarkstreamThreadAnchor;
+    itemHeights: Record<string, number>;
+    itemSizeSources?: Record<string, {
+        sourceKey: string;
+        measurementKey?: string;
+        widthBucket?: number;
+    }>;
+    markdownStates: Record<string, MarkstreamVirtualState>;
+}
+export interface MarkstreamVirtualMarkdownProps extends Pick<NodeRendererProps, 'content' | 'final' | 'indexKey' | 'nodeVirtual' | 'maxLiveNodes' | 'liveNodeBuffer' | 'virtualScroll' | 'fade' | 'mode' | 'renderCodeBlocksAsPre'> {
+    onHeightChange: (metrics: MarkstreamVirtualMetrics) => void;
+    onVirtualStateChange: (state: MarkstreamVirtualState) => void;
+}
+export interface UseMarkstreamVirtualAdapterOptions<T = MarkstreamTimelineItem> {
+    items: MaybeAccessor<readonly T[]>;
+    threadKey?: MaybeAccessor<MarkstreamTimelineItemKey | undefined>;
+    layoutRevision?: MaybeAccessor<MarkstreamTimelineItemKey | undefined>;
+    getKey?: (item: T, index: number) => MarkstreamTimelineItemKey;
+    getKind?: (item: T, index: number) => string;
+    getContent?: (item: T, index: number) => string;
+    getFinal?: (item: T, index: number) => boolean;
+    getRevision?: (item: T, index: number) => MarkstreamTimelineItemKey | undefined;
+    estimateItemHeight?: (item: T, index: number) => number;
+    measurementKey?: MaybeAccessor<string | number | undefined>;
+    markdownMode?: MaybeAccessor<NodeRendererMode | undefined>;
+    renderCodeBlocksAsPre?: MaybeAccessor<boolean | undefined>;
+    /**
+     * Default: false.
+     */
+    markdownFade?: boolean;
+    /**
+     * Preserve the outer scroll anchor when markdown logical height or measured
+     * item height changes.
+     *
+     * Set false if the host virtualizer already performs equivalent scroll
+     * anchoring.
+     *
+     * Default: 'auto'
+     */
+    preserveScrollAnchor?: boolean | 'auto';
+    /**
+     * Used when preserveScrollAnchor is enabled.
+     * Default: 48
+     */
+    bottomThresholdPx?: number;
+    debug?: boolean;
+    virtualizer: MarkstreamOuterVirtualizerAdapter;
+}
+export interface MarkstreamVirtualAdapterController<T = MarkstreamTimelineItem> {
+    itemHeights: Map<string, number>;
+    markdownStates: Map<string, MarkstreamVirtualState>;
+    getItemKey: (item: T, index: number) => string;
+    isMarkdownItem: (item: T, index: number) => boolean;
+    isRestoringThread: () => boolean;
+    measureItem: (item: T, index: number, el: Element | {
+        $el?: Element | null;
+    } | null | undefined) => void;
+    /** Release the measurement bookkeeping (DOM ref + ResizeObserver) of one item key. */
+    unobserveItem: (key: string) => void;
+    /** Drop measurement bookkeeping for entries whose element left the DOM. Returns the released count. */
+    releaseDetached: () => number;
+    markdownProps: (item: T, index: number) => MarkstreamVirtualMarkdownProps;
+    captureThreadState: () => MarkstreamThreadVirtualState;
+    preloadThreadState: (state: MarkstreamThreadVirtualState | null | undefined) => void;
+    restoreThreadState: (state: MarkstreamThreadVirtualState | null | undefined) => void;
+    dispose: () => void;
+}
+export declare function getMarkstreamTimelineItemKey<T>(item: T, index: number, options: Pick<UseMarkstreamVirtualAdapterOptions<T>, 'getKey'>): string;
+export declare function getMarkstreamTimelineItemKind<T>(item: T, index: number, options: Pick<UseMarkstreamVirtualAdapterOptions<T>, 'getKind'>): string;
+export declare function getMarkstreamTimelineItemContent<T>(item: T, index: number, options: Pick<UseMarkstreamVirtualAdapterOptions<T>, 'getContent'>): string;
+export declare function getMarkstreamTimelineItemFinal<T>(item: T, index: number, options: Pick<UseMarkstreamVirtualAdapterOptions<T>, 'getFinal'>): boolean;
+export declare function getMarkstreamTimelineItemRevision<T>(item: T, index: number, options: Pick<UseMarkstreamVirtualAdapterOptions<T>, 'getRevision'>): MarkstreamTimelineItemKey | undefined;
+export declare function isMarkstreamMarkdownTimelineItem<T>(item: T, index: number, options: Pick<UseMarkstreamVirtualAdapterOptions<T>, 'getKind' | 'getContent'>): boolean;
+export declare function estimateMarkstreamTimelineItemHeight<T>(item: T, index: number, options: Pick<UseMarkstreamVirtualAdapterOptions<T>, 'estimateItemHeight' | 'getKind' | 'getContent'>): number;
+export declare function useMarkstreamVirtualAdapter<T = MarkstreamTimelineItem>(options: UseMarkstreamVirtualAdapterOptions<T>): MarkstreamVirtualAdapterController<T>;
+export {};

package/dist/workers/katexCdnWorker.d.ts

@@ -0,0 +1,20 @@
+export type KaTeXCDNWorkerMode = 'classic' | 'module';
+export interface KaTeXCDNWorkerOptions {
+    katexUrl: string;
+    mhchemUrl?: string;
+    mode?: KaTeXCDNWorkerMode;
+    debug?: boolean;
+    workerOptions?: WorkerOptions;
+    renderOptions?: {
+        throwOnError?: boolean;
+        output?: string;
+        strict?: string;
+    };
+}
+export interface KaTeXCDNWorkerHandle {
+    worker: Worker | null;
+    dispose: () => void;
+    source: string;
+}
+export declare function buildKaTeXCDNWorkerSource(options: KaTeXCDNWorkerOptions): string;
+export declare function createKaTeXWorkerFromCDN(options: KaTeXCDNWorkerOptions): KaTeXCDNWorkerHandle;

package/dist/workers/katexRenderer.worker.d.ts

@@ -0,0 +1 @@
+import 'katex/dist/contrib/mhchem';

package/dist/workers/katexWorkerClient.d.ts

@@ -0,0 +1,35 @@
+export declare const WORKER_BUSY_CODE = "WORKER_BUSY";
+export declare function setKaTeXWorker(nextWorker: Worker): void;
+export declare function clearKaTeXWorker(): void;
+export declare function setKaTeXWorkerDebug(enabled: boolean): void;
+export declare function renderKaTeXInWorker(content: string, displayMode?: boolean, timeout?: number, signal?: AbortSignal): Promise<string>;
+export declare function setKaTeXCache(content: string, displayMode: boolean | undefined, html: string): void;
+export declare function getKaTeXWorkerLoad(): {
+    inFlight: number;
+    max: number;
+};
+export declare function setKaTeXWorkerMaxConcurrency(value: number): void;
+export declare function isKaTeXWorkerBusy(): boolean;
+export declare function waitForKaTeXWorkerSlot(timeout?: number, signal?: AbortSignal): Promise<void>;
+export interface BackpressureOptions {
+    timeout?: number;
+    waitTimeout?: number;
+    backoffMs?: number;
+    maxRetries?: number;
+    signal?: AbortSignal;
+}
+declare const defaultBackpressure: {
+    timeout: number;
+    waitTimeout: number;
+    backoffMs: number;
+    maxRetries: number;
+};
+export declare function setKaTeXBackpressureDefaults(options: Partial<typeof defaultBackpressure>): void;
+export declare function getKaTeXBackpressureDefaults(): {
+    timeout: number;
+    waitTimeout: number;
+    backoffMs: number;
+    maxRetries: number;
+};
+export declare function renderKaTeXWithBackpressure(content: string, displayMode?: boolean, options?: BackpressureOptions): Promise<string>;
+export {};

package/dist/workers/mermaidCdnWorker.d.ts

@@ -0,0 +1,15 @@
+export type MermaidCDNWorkerMode = 'classic' | 'module';
+export interface MermaidCDNWorkerOptions {
+    mermaidUrl: string;
+    mode?: MermaidCDNWorkerMode;
+    debug?: boolean;
+    workerOptions?: WorkerOptions;
+    initializeOptions?: Record<string, any>;
+}
+export interface MermaidCDNWorkerHandle {
+    worker: Worker | null;
+    dispose: () => void;
+    source: string;
+}
+export declare function buildMermaidCDNWorkerSource(options: MermaidCDNWorkerOptions): string;
+export declare function createMermaidWorkerFromCDN(options: MermaidCDNWorkerOptions): MermaidCDNWorkerHandle;

package/dist/workers/mermaidParser.worker.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/workers/mermaidWorkerClient.d.ts

@@ -0,0 +1,15 @@
+type Theme = 'light' | 'dark';
+export declare function setMermaidWorkerClientDebug(enabled: boolean): void;
+export declare function setMermaidWorkerMaxConcurrency(value: number): void;
+export declare function getMermaidWorkerLoad(): {
+    inFlight: number;
+    max: number;
+};
+export declare const MERMAID_WORKER_BUSY_CODE = "WORKER_BUSY";
+export declare const MERMAID_DISABLED_CODE = "MERMAID_DISABLED";
+export declare function setMermaidWorker(nextWorker: Worker): void;
+export declare function clearMermaidWorker(): void;
+export declare function canParseOffthread(code: string, theme: Theme, timeout?: number): Promise<boolean>;
+export declare function findPrefixOffthread(code: string, theme: Theme, timeout?: number): Promise<string | null>;
+export declare function terminateWorker(): void;
+export {};

package/package.json

@@ -1,6 +1,152 @@
 {
   "name": "markstream-solid",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "type": "module",
+  "version": "2.0.23",
+  "description": "SolidJS streaming Markdown renderer for AI chat, incremental Markdown and long document restoration.",
+  "author": "Simon He",
+  "license": "MIT",
+  "homepage": "https://markstream.simonhe.me/frameworks/solid",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Simon-He95/markstream-vue.git",
+    "directory": "packages/markstream-solid"
+  },
+  "bugs": {
+    "url": "https://github.com/Simon-He95/markstream-vue/issues"
+  },
+  "keywords": [
+    "solid",
+    "solidjs",
+    "markdown",
+    "streaming-markdown",
+    "ai-chat",
+    "sse",
+    "ssr",
+    "katex",
+    "mermaid",
+    "markstream-solid"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "browser": "./dist/client/index.js",
+      "node": "./dist/server/index.js",
+      "import": "./dist/client/index.js"
+    },
+    "./index.css": "./dist/index.css",
+    "./index.px.css": "./dist/index.px.css",
+    "./index.tailwind.css": "./dist/index.tailwind.css",
+    "./utils": {
+      "types": "./dist/utils/index.d.ts",
+      "browser": "./dist/client/utils/index.js",
+      "node": "./dist/server/utils/index.js",
+      "import": "./dist/client/utils/index.js"
+    },
+    "./utils/katex-threshold": {
+      "types": "./dist/utils/katex-threshold.d.ts",
+      "browser": "./dist/client/utils/katex-threshold.js",
+      "node": "./dist/server/utils/katex-threshold.js",
+      "import": "./dist/client/utils/katex-threshold.js"
+    },
+    "./utils/performance-monitor": {
+      "types": "./dist/utils/performance-monitor.d.ts",
+      "browser": "./dist/client/utils/performance-monitor.js",
+      "node": "./dist/server/utils/performance-monitor.js",
+      "import": "./dist/client/utils/performance-monitor.js"
+    },
+    "./utils/safeRaf": {
+      "types": "./dist/utils/safeRaf.d.ts",
+      "browser": "./dist/client/utils/safeRaf.js",
+      "node": "./dist/server/utils/safeRaf.js",
+      "import": "./dist/client/utils/safeRaf.js"
+    },
+    "./workers/katexWorkerClient": {
+      "types": "./dist/workers/katexWorkerClient.d.ts",
+      "browser": "./dist/client/workers/katexWorkerClient.js",
+      "node": "./dist/server/workers/katexWorkerClient.js",
+      "import": "./dist/client/workers/katexWorkerClient.js"
+    },
+    "./workers/mermaidWorkerClient": {
+      "types": "./dist/workers/mermaidWorkerClient.d.ts",
+      "browser": "./dist/client/workers/mermaidWorkerClient.js",
+      "node": "./dist/server/workers/mermaidWorkerClient.js",
+      "import": "./dist/client/workers/mermaidWorkerClient.js"
+    },
+    "./workers/katexCdnWorker": {
+      "types": "./dist/workers/katexCdnWorker.d.ts",
+      "browser": "./dist/client/workers/katexCdnWorker.js",
+      "node": "./dist/server/workers/katexCdnWorker.js",
+      "import": "./dist/client/workers/katexCdnWorker.js"
+    },
+    "./workers/mermaidCdnWorker": {
+      "types": "./dist/workers/mermaidCdnWorker.d.ts",
+      "browser": "./dist/client/workers/mermaidCdnWorker.js",
+      "node": "./dist/server/workers/mermaidCdnWorker.js",
+      "import": "./dist/client/workers/mermaidCdnWorker.js"
+    },
+    "./workers/katexRenderer.worker": "./dist/client/workers/katexRenderer.worker.js",
+    "./workers/mermaidParser.worker": "./dist/client/workers/mermaidParser.worker.js",
+    "./tailwind": {
+      "types": "./dist/tailwind.d.ts",
+      "import": "./dist/tailwind.js"
+    }
+  },
+  "main": "./dist/server/index.js",
+  "module": "./dist/client/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "peerDependencies": {
+    "@antv/infographic": "^0.2.3",
+    "@terrastruct/d2": ">=0.1.33",
+    "katex": ">=0.16.22",
+    "mermaid": ">=11",
+    "solid-js": "^1.9.0",
+    "stream-diffs": ">=0.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@antv/infographic": {
+      "optional": true
+    },
+    "@terrastruct/d2": {
+      "optional": true
+    },
+    "katex": {
+      "optional": true
+    },
+    "mermaid": {
+      "optional": true
+    },
+    "stream-diffs": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@floating-ui/dom": "^1.8.0",
+    "markstream-core": "2.0.23",
+    "stream-markdown-parser": "1.2.24"
+  },
+  "devDependencies": {
+    "jsdom": "^24.1.3",
+    "postcss-cli": "^11.0.1",
+    "postcss-import": "^15.1.0",
+    "solid-js": "^1.9.0",
+    "typescript": "^5.9.3",
+    "vite": "^7.3.6",
+    "vite-plugin-solid": "^2.11.0",
+    "vitest": "^4.1.10"
+  },
+  "scripts": {
+    "build": "pnpm --dir ../markdown-parser build && pnpm --dir ../markstream-core build && vite build --mode client && vite build --mode server && tsc -p tsconfig.build.json && postcss src/index.css -o dist/index.css && node scripts/finalize-build.mjs && node ../../scripts/generate-px-css.mjs && pnpm run check:parity",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:ssr": "vitest run --config vitest.ssr.config.ts",
+    "check:parity": "node scripts/check-vue3-parity.mjs",
+    "check:workspace-deps-published": "node ../../scripts/check-workspace-deps-published.mjs --package-json package.json",
+    "release": "pnpm run check:workspace-deps-published && bumpp --commit --no-tag --no-push --execute 'pnpm --workspace-root run docs:llms:generate' && DIST_TAG=\"$(node ../../scripts/dist-tag.mjs)\" && pnpm publish --access public --tag \"${DIST_TAG}\" && node ../../scripts/tag-package.mjs --package-json package.json --push"
+  }
 }