@owomark/react 0.1.6 → 0.1.7

package/README.md

@@ -52,7 +52,7 @@ function App() {
 | `coreRef` | `Ref<OwoMarkCore \| null>` | — | Direct access to the underlying OwoMarkCore instance |
 | `controller` | `OwoMarkSharedStateController` | — | Auto-connects editor to shared state (recommended for split editor) |
 | `indentMode` | `'auto' \| '2' \| '4'` | `'auto'` | Tab indent width |
-| `config` | `OwoMarkEditorConfig` | — | Unified editor config (`indentMode`, `enableSideAnnotation`, `enableMath`) |
+| `config` | `OwoMarkEditorConfig` | — | Unified editor config (`indentMode`, `enableSideAnnotation`, `enableMath`, `enableComponents`) |
 | `ariaLabel` | `string` | — | Accessibility label |
 
 When `config` is provided, it becomes the unified configuration surface for editor behavior:
@@ -66,6 +66,7 @@ When `config` is provided, it becomes the unified configuration surface for edit
     indentMode: '2',
     enableSideAnnotation: true,
     enableMath: true,
+    enableComponents: true,
   }}
 />
 ```
@@ -157,6 +158,8 @@ async function renderBlock(
 
 OwoMark supports right-side annotations for preview rendering and editor workflows. The feature is enabled by default and can be turned off with `config.enableSideAnnotation = false`.
 
+The canonical syntax, type table, MDX boundary, and future descriptor contract are frozen in [docs/specs/owomark-side-annotation.md](/home/qq/proj/qblog/docs/specs/owomark-side-annotation.md).
+
 ```tsx
 <OwoMarkEditor
   value={md}
@@ -274,7 +277,11 @@ import '@owomark/view/style.css'; // includes owomark.css + side-annotation.css
 import '@owomark/processor/mdx-components.css'; // built-in MDX component styles
 ```
 
-Built-in MDX components currently include `Callout`, `Note`, `CodeDemo`, `Steps`, `Tabs`, `FileTree`, and `Kbd`.
+The current built-in MDX runtime registry includes `Note`, `Callout`, `CodeDemo`, `CodeTab`, `Details`, `LinkCard`, `Steps`, `Step`, `Tabs`, `Tab`, `FileTree`, and `Kbd`.
+
+For the canonical built-in component contract and the full official component registry, see [docs/specs/owomark-components-extension.md](/home/qq/proj/qblog/docs/specs/owomark-components-extension.md). This README stays at the usage-summary level for the components that are actually exported today.
+
+For the canonical math parsing, normalization, and slash-entry contract, see [docs/specs/owomark-math.md](/home/qq/proj/qblog/docs/specs/owomark-math.md).
 
 Use `Note` for supplemental explanation, editor notes, and neutral guidance. Keep `Callout` for stronger feedback semantics such as `info`, `warn`, `error`, or `success`.
 

package/dist/.build-manifest.json

@@ -0,0 +1,58 @@
+{
+  "schemaVersion": 1,
+  "packageName": "@owomark/react",
+  "packagePath": "owomark/packages/owomark-react",
+  "packageFingerprint": "cd194512b0273bc2317f818bca9056dd119e2b2e3148f0441e36e626429122c8",
+  "workspaceFingerprint": "29c91b05781cfd51984ade38b2b582f8dab1013dfaaf87ed5b2b6e9723653157",
+  "builtAt": "2026-04-23T03:06:11.526Z",
+  "builderVersion": "2026-04-22-industrialization-v1",
+  "inputFiles": [
+    "owomark/package.json",
+    "owomark/packages/owomark-react/package.json",
+    "owomark/packages/owomark-react/src/AsyncCodeBlock.tsx",
+    "owomark/packages/owomark-react/src/MdxComponentShell.tsx",
+    "owomark/packages/owomark-react/src/MdxPreview.tsx",
+    "owomark/packages/owomark-react/src/MdxSkeleton.tsx",
+    "owomark/packages/owomark-react/src/OwoMarkEditor.tsx",
+    "owomark/packages/owomark-react/src/OwoMarkPreview.tsx",
+    "owomark/packages/owomark-react/src/config.ts",
+    "owomark/packages/owomark-react/src/editor/EditorBlock.tsx",
+    "owomark/packages/owomark-react/src/editor/EditorDecorator.tsx",
+    "owomark/packages/owomark-react/src/editor/EditorLeaf.tsx",
+    "owomark/packages/owomark-react/src/editor/index.ts",
+    "owomark/packages/owomark-react/src/highlight-cache-key.ts",
+    "owomark/packages/owomark-react/src/highlight-types.ts",
+    "owomark/packages/owomark-react/src/highlight-worker-manager.ts",
+    "owomark/packages/owomark-react/src/highlight.worker.ts",
+    "owomark/packages/owomark-react/src/index.ts",
+    "owomark/packages/owomark-react/src/mdx-error.ts",
+    "owomark/packages/owomark-react/src/mdx-preview-utils.tsx",
+    "owomark/packages/owomark-react/src/mdx-runtime.ts",
+    "owomark/packages/owomark-react/src/mdx.worker.ts",
+    "owomark/packages/owomark-react/src/slash/SlashMenu.tsx",
+    "owomark/packages/owomark-react/src/slash/caret-position.ts",
+    "owomark/packages/owomark-react/src/slash/index.ts",
+    "owomark/packages/owomark-react/src/toolbar/Toolbar.tsx",
+    "owomark/packages/owomark-react/src/toolbar/index.ts",
+    "owomark/packages/owomark-react/src/useBlockContext.ts",
+    "owomark/packages/owomark-react/src/useMdxPreviewCompilation.ts",
+    "owomark/packages/owomark-react/src/useOwoMarkCore.ts",
+    "owomark/packages/owomark-react/src/useOwoMarkSharedState.ts",
+    "owomark/packages/owomark-react/src/useScrollController.ts",
+    "owomark/packages/owomark-react/src/useVirtualList.ts",
+    "owomark/packages/owomark-react/tsconfig.json",
+    "owomark/packages/owomark-react/tsup.config.ts",
+    "package-lock.json"
+  ],
+  "artifactFiles": [
+    "dist/highlight.worker.js",
+    "dist/index.d.ts",
+    "dist/index.js",
+    "dist/mdx.worker.js"
+  ],
+  "localDependencyFingerprints": {
+    "@owomark/core": "32024bd874bc287d8de92d6142487720dd3e31af4477e6f91a54b8e8db3aec4e",
+    "@owomark/processor": "edb4a27eeff05c48b721444470988e0e0b715fff56767e9a2da706f44fef425f",
+    "@owomark/view": "f70b7037c41905c87554e2d2a912d682e65e87ef960675bb32ee9a3776c4efd6"
+  }
+}

package/dist/highlight.worker.js

@@ -0,0 +1,113 @@
+// src/highlight.worker.ts
+import {
+  bundledLanguages,
+  bundledLanguagesAlias,
+  bundledThemes,
+  createHighlighter,
+  createJavaScriptRegexEngine
+} from "shiki";
+
+// src/highlight-types.ts
+var DEFAULT_HIGHLIGHT_THEME = "vitesse-light";
+
+// src/highlight.worker.ts
+var cancelledTaskIds = /* @__PURE__ */ new Set();
+var highlighterPromise = null;
+var loadedLanguages = /* @__PURE__ */ new Set();
+var loadedThemes = /* @__PURE__ */ new Set();
+function resolveLanguage(language) {
+  if (!language) {
+    return "text";
+  }
+  const normalized = language.trim().toLowerCase();
+  if (normalized in bundledLanguages) {
+    return normalized;
+  }
+  if (normalized in bundledLanguagesAlias) {
+    return bundledLanguagesAlias[normalized];
+  }
+  return "text";
+}
+function resolveTheme(themeKey) {
+  return themeKey in bundledThemes ? themeKey : DEFAULT_HIGHLIGHT_THEME;
+}
+async function getHighlighter() {
+  if (!highlighterPromise) {
+    highlighterPromise = createHighlighter({
+      langs: [],
+      themes: [DEFAULT_HIGHLIGHT_THEME],
+      engine: createJavaScriptRegexEngine()
+    });
+    loadedThemes.add(DEFAULT_HIGHLIGHT_THEME);
+  }
+  return highlighterPromise;
+}
+async function ensureAssets(highlighter, language, theme) {
+  if (language !== "text" && !loadedLanguages.has(language)) {
+    await highlighter.loadLanguage(language);
+    loadedLanguages.add(language);
+  }
+  if (!loadedThemes.has(theme)) {
+    await highlighter.loadTheme(theme);
+    loadedThemes.add(theme);
+  }
+}
+function wrapHighlightedHtml(preHtml, language, theme) {
+  const codeTag = `<code data-language="${language ?? "text"}" data-theme="${theme}" style="display:grid">`;
+  return preHtml.replace("<pre ", `<pre data-language="${language ?? "text"}" data-theme="${theme}" `).replace("<code>", codeTag).replaceAll('<span class="line">', '<span data-line="">');
+}
+async function highlight(request) {
+  const language = resolveLanguage(request.language);
+  const theme = resolveTheme(request.themeKey);
+  const highlighter = await getHighlighter();
+  await ensureAssets(highlighter, language, theme);
+  const html = highlighter.codeToHtml(request.code, {
+    lang: language,
+    theme
+  });
+  return wrapHighlightedHtml(html, request.language, theme);
+}
+self.onmessage = (event) => {
+  const message = event.data;
+  if (message.type === "cancel") {
+    cancelledTaskIds.add(message.taskId);
+    return;
+  }
+  void handleHighlight(message);
+};
+async function handleHighlight(request) {
+  const taskId = request.requestId;
+  try {
+    const html = await highlight(request);
+    if (cancelledTaskIds.has(taskId)) {
+      cancelledTaskIds.delete(taskId);
+      return;
+    }
+    self.postMessage({
+      type: "highlight-result",
+      taskId,
+      requestId: request.requestId,
+      documentVersion: request.documentVersion,
+      blockInstanceId: request.blockInstanceId,
+      cacheKey: request.cacheKey,
+      ok: true,
+      html
+    });
+  } catch (error) {
+    if (cancelledTaskIds.has(taskId)) {
+      cancelledTaskIds.delete(taskId);
+      return;
+    }
+    const message = error instanceof Error ? error.message : "Code highlighting failed";
+    self.postMessage({
+      type: "highlight-error",
+      taskId,
+      requestId: request.requestId,
+      documentVersion: request.documentVersion,
+      blockInstanceId: request.blockInstanceId,
+      cacheKey: request.cacheKey,
+      ok: false,
+      error: message
+    });
+  }
+}

package/dist/index.d.ts

@@ -1,13 +1,19 @@
 import * as react from 'react';
-import { Ref, MutableRefObject, CSSProperties, ReactNode, ComponentType } from 'react';
-import { IndentMode, OwoMarkSelection, OwoMarkCommands, OwoMarkCore, OwoMarkSharedStateController, OwoMarkSharedStateStore, PreviewBlock, CreateSharedStateOptions, OwoMarkSharedState, OwoMarkDocument, SlashState, BlockContext, BlockNode, VisibleRange, VirtualRow, Decorator } from '@owomark/core';
-export { BlockContext, BlockContextType, BlockInsertType, CommandDefinition, OwoMarkCommands, OwoMarkCore, OwoMarkEditorInstance, OwoMarkSelection, OwoMarkSharedState, OwoMarkSharedStateController, OwoMarkSharedStateStore, PreviewBlock, PreviewBlockKind, SlashState } from '@owomark/core';
+import react__default, { Ref, MutableRefObject, CSSProperties, ReactNode, ComponentType } from 'react';
+import { IndentMode, OwoMarkSelection, OwoMarkCommands, OwoMarkCore, OwoMarkSharedStateController, OwoMarkScrollController, OwoMarkSharedStateStore, PreviewBlock, CreateSharedStateOptions, OwoMarkSharedState, OwoMarkDocument, SlashState, BlockContext, BlockNode, VisibleRange, VirtualRow, Decorator } from '@owomark/core';
+export { BlockContext, BlockContextType, BlockInsertType, CommandDefinition, GlobalScrollPosition, OwoMarkCommands, OwoMarkCore, OwoMarkScrollController, OwoMarkScrollProjectionSegment, OwoMarkScrollProjectionSnapshot, OwoMarkSelection, OwoMarkSharedState, OwoMarkSharedStateController, OwoMarkSharedStateStore, OwoMarkSurfaceGeometrySegment, OwoMarkSurfaceGeometrySnapshot, PreviewBlock, PreviewBlockKind, ScrollResolutionResult, ScrollSurface, ScrollToScrollPositionOptions, ScrollToScrollPositionResult, SlashState, ViewportMetrics } from '@owomark/core';
 import { OwoMarkThemeName, PreviewStrategy, PreviewRendererRegistry, PreviewRenderContext } from '@owomark/view';
 export { OwoMarkThemeName, PreviewRenderContext, PreviewRenderResult, PreviewRendererDefinition, PreviewRendererRegistry, THEME_DARK_CLASS, THEME_LIGHT_CLASS, getThemeClassName } from '@owomark/view';
 import { OwoMarkProcessorOptions, PluginDescriptor, PluginEntry, MdxComponentMap } from '@owomark/processor';
 export { registerPlugin } from '@owomark/processor';
 import * as react_jsx_runtime from 'react/jsx-runtime';
+import { createScrollController } from '@owomark/core/browser';
 
+type BuiltInComponentCommandId = 'component-note' | 'component-callout' | 'component-code-demo' | 'component-details' | 'component-steps' | 'component-tabs' | 'component-link-card' | 'component-file-tree';
+type OwoMarkToolbarConfig = {
+    componentCommands?: BuiltInComponentCommandId[];
+};
+declare const DEFAULT_TOOLBAR_COMPONENT_COMMANDS: BuiltInComponentCommandId[];
 type OwoMarkEditorConfig = {
     /** Indent mode: 'auto' | '2' | '4'. Default: 'auto'. */
     indentMode?: IndentMode;
@@ -15,12 +21,16 @@ type OwoMarkEditorConfig = {
     enableSideAnnotation?: boolean;
     /** Enable math (KaTeX) rendering. Default: true. */
     enableMath?: boolean;
+    /** Enable built-in component extension syntax (:::note, :kbd, etc.). Default: true. */
+    enableComponents?: boolean;
     /** Enable fenced markdown sandbox rendering. Default: true. */
     enableMarkdownSandbox?: boolean;
     /** Minimum backtick count required for markdown sandbox fences. Default: 4. */
     markdownSandbox?: {
         outerFenceTicks?: number;
     };
+    /** Toolbar configuration for component quick-insert buttons. */
+    toolbarConfig?: OwoMarkToolbarConfig;
 };
 declare const DEFAULT_EDITOR_CONFIG: Required<OwoMarkEditorConfig>;
 declare function resolveEditorConfig(config?: OwoMarkEditorConfig): Required<OwoMarkEditorConfig>;
@@ -48,6 +58,7 @@ type OwoMarkEditorProps = {
      * shared state controller.
      */
     controller?: OwoMarkSharedStateController;
+    scrollController?: OwoMarkScrollController;
     indentMode?: IndentMode;
     ariaLabel?: string;
     /**
@@ -63,6 +74,7 @@ type OwoMarkMdxOptions = {
     enableSideAnnotation?: boolean;
     enableCodeHighlight?: boolean;
     sourceAnchors?: boolean;
+    forceFullDocumentCompile?: boolean;
     extraRemarkDescriptors?: PluginDescriptor[];
     extraRehypeDescriptors?: PluginDescriptor[];
     extraRemarkPlugins?: PluginEntry[];
@@ -70,30 +82,101 @@ type OwoMarkMdxOptions = {
     components?: MdxComponentMap;
 };
 
+type OwoMarkScrollSyncMode = 'off' | 'bidirectional';
 type OwoMarkPreviewProps = {
     state: OwoMarkSharedStateStore;
+    markdown?: string;
     className?: string;
     strategy?: PreviewStrategy;
     themeKey?: string;
     registry?: PreviewRendererRegistry;
     viewportFirst?: boolean;
     ariaLabel?: string;
-    /**
-     * External block renderer. When provided, the preview engine uses this
-     * to render each block instead of the built-in lightweight renderer.
-     * Typically backed by the host's unified/remark/rehype/Shiki pipeline.
-     *
-     * Engine is recreated when this prop transitions between defined/undefined.
-     * Identity changes of the function itself do NOT cause engine recreation —
-     * the latest reference is always used via a stable ref.
-     */
+    scrollController?: OwoMarkScrollController;
+    scrollSync?: OwoMarkScrollSyncMode;
+    onScroll?: react__default.UIEventHandler<HTMLDivElement>;
     renderBlock?: (block: PreviewBlock, context: PreviewRenderContext) => Promise<string>;
-    /** MDX runtime configuration used by `strategy="mdx"`. */
     mdx?: OwoMarkMdxOptions;
-    /** Called after each successful DOM update. Use to trigger scroll sync. */
     onContentUpdate?: () => void;
 };
-declare const OwoMarkPreview: (props: OwoMarkPreviewProps) => react_jsx_runtime.JSX.Element;
+declare const OwoMarkPreview: react__default.ForwardRefExoticComponent<OwoMarkPreviewProps & react__default.RefAttributes<HTMLDivElement>>;
+
+type HighlightRequest = {
+    requestId: string;
+    documentVersion: number;
+    blockInstanceId: string;
+    cacheKey: string;
+    code: string;
+    language: string | null;
+    themeKey: string;
+    meta: string | null;
+};
+type HighlightSuccessResponse = {
+    requestId: string;
+    documentVersion: number;
+    blockInstanceId: string;
+    cacheKey: string;
+    ok: true;
+    html: string;
+};
+type HighlightErrorResponse = {
+    requestId: string;
+    documentVersion: number;
+    blockInstanceId: string;
+    cacheKey: string;
+    ok: false;
+    error: string;
+};
+type HighlightResponse = HighlightSuccessResponse | HighlightErrorResponse;
+type HighlightTaskHandle = {
+    request: HighlightRequest;
+    promise: Promise<HighlightResponse>;
+    cancel: () => void;
+};
+
+type HighlightWorkerManagerOptions = {
+    timeoutMs?: number;
+    cacheMaxEntries?: number;
+    workerFactory?: () => Worker | null;
+};
+declare class HighlightWorkerManager {
+    private readonly timeoutMs;
+    private readonly cacheMaxEntries;
+    private readonly workerFactory?;
+    private worker;
+    private workerFailureCount;
+    private requestCounter;
+    private readonly cache;
+    private readonly inflightByCacheKey;
+    private readonly inflightByTaskId;
+    constructor(options?: HighlightWorkerManagerOptions);
+    highlight(input: Omit<HighlightRequest, 'requestId' | 'themeKey'> & {
+        themeKey?: string;
+    }): HighlightTaskHandle;
+    resetForTesting(): void;
+    private ensureWorker;
+    private startTask;
+    private handleWorkerMessage;
+    private cancelRequest;
+    private cancelTask;
+    private finishTaskWithError;
+    private clearTaskTimeout;
+    private getCached;
+    private setCached;
+}
+
+type AsyncCodeBlockProps = {
+    code: string;
+    language: string | null;
+    meta: string | null;
+    themeKey: string;
+    documentVersion: number;
+    className?: string;
+    codeProps?: Record<string, unknown>;
+    preProps?: Record<string, unknown>;
+    manager?: HighlightWorkerManager;
+};
+declare function AsyncCodeBlock(props: AsyncCodeBlockProps): react_jsx_runtime.JSX.Element;
 
 type UseOwoMarkSharedStateOptions = CreateSharedStateOptions;
 /**
@@ -108,6 +191,7 @@ declare function useOwoMarkSharedState(options?: UseOwoMarkSharedStateOptions):
  * Returns the current OwoMarkSharedState, triggering re-renders on changes.
  */
 declare function useSharedStateSnapshot(controller: OwoMarkSharedStateController): OwoMarkSharedState;
+declare function useSharedStateSelector<T>(store: OwoMarkSharedStateStore, selector: (state: OwoMarkSharedState) => T, isEqual?: (prev: T, next: T) => boolean): T;
 
 /**
  * React hook that creates and manages an OwoMarkCore instance
@@ -140,6 +224,9 @@ declare function useOwoMarkCore(options: UseOwoMarkCoreOptions): UseOwoMarkCoreR
 
 declare function useBlockContext(core: OwoMarkCore): BlockContext;
 
+type UseScrollControllerReturn = ReturnType<typeof createScrollController>;
+declare function useScrollController(controller: OwoMarkSharedStateController): UseScrollControllerReturn;
+
 type UseVirtualListOptions = {
     blocks: readonly BlockNode[];
     /** The scrollable container element. */
@@ -225,6 +312,12 @@ declare function computeMenuPosition(caret: CaretRect, menuHeight: number, menuW
     left: number;
 };
 
+type ToolbarProps = {
+    core: OwoMarkCore;
+    toolbarConfig: OwoMarkToolbarConfig;
+};
+declare const Toolbar: react.NamedExoticComponent<ToolbarProps>;
+
 type MdxSkeletonProps = {
     height?: number;
     lines?: number;
@@ -250,4 +343,4 @@ type CancellableCompile = {
 declare function acquireMdxWorker(): void;
 declare function releaseMdxWorker(): void;
 
-export { type CancellableCompile, type CaretRect, DEFAULT_EDITOR_CONFIG, EditorBlock, type EditorBlockProps, EditorDecorator, type EditorDecoratorProps, EditorLeaf, type EditorLeafProps, MdxComponentShell, type MdxComponentShellProps, MdxSkeleton, type MdxSkeletonProps, OwoMarkEditor, type OwoMarkEditorConfig, type OwoMarkEditorProps, type OwoMarkMdxOptions, OwoMarkPreview, type OwoMarkPreviewProps, SlashMenu, type SlashMenuProps, type UseOwoMarkCoreOptions, type UseOwoMarkCoreReturn, type UseOwoMarkSharedStateOptions, type UseVirtualListOptions, type UseVirtualListResult, acquireMdxWorker, clearComponentHeightCache, computeMenuPosition, deriveProcessorOptions, getCaretRect, releaseMdxWorker, resolveEditorConfig, useBlockContext, useOwoMarkCore, useOwoMarkSharedState, useSharedStateSnapshot, useVirtualList, wrapWithShell };
+export { AsyncCodeBlock, type BuiltInComponentCommandId, type CancellableCompile, type CaretRect, DEFAULT_EDITOR_CONFIG, DEFAULT_TOOLBAR_COMPONENT_COMMANDS, EditorBlock, type EditorBlockProps, EditorDecorator, type EditorDecoratorProps, EditorLeaf, type EditorLeafProps, MdxComponentShell, type MdxComponentShellProps, MdxSkeleton, type MdxSkeletonProps, OwoMarkEditor, type OwoMarkEditorConfig, type OwoMarkEditorProps, type OwoMarkMdxOptions, OwoMarkPreview, type OwoMarkPreviewProps, type OwoMarkScrollSyncMode, type OwoMarkToolbarConfig, SlashMenu, type SlashMenuProps, Toolbar, type ToolbarProps, type UseOwoMarkCoreOptions, type UseOwoMarkCoreReturn, type UseOwoMarkSharedStateOptions, type UseScrollControllerReturn, type UseVirtualListOptions, type UseVirtualListResult, acquireMdxWorker, clearComponentHeightCache, computeMenuPosition, deriveProcessorOptions, getCaretRect, releaseMdxWorker, resolveEditorConfig, useBlockContext, useOwoMarkCore, useOwoMarkSharedState, useScrollController, useSharedStateSelector, useSharedStateSnapshot, useVirtualList, wrapWithShell };