fix(engine): expose Engine instance type from CherryEngine

.changeset/typed-engine-constructor.md

@@ -0,0 +1,5 @@
+---
+'cherry-markdown': patch
+---
+
+fix: declare CherryEngine's constructor result as Engine while retaining its static APIs

packages/cherry-markdown/src/index.engine.core.js

@@ -61,8 +61,10 @@ class CherryEngine extends CherryStatic {
 export { SyntaxHookBase, MenuHookBase };
 
 /**
- * @typedef {typeof CherryStatic & (new (options: Partial<import('~types/cherry').CherryOptions>) => Engine)}
+ * Preserve the static API while declaring the Engine instance returned by the
+ * compatibility constructor. A class declaration alone cannot express this.
+ * @typedef {Omit<typeof CherryEngine, 'prototype'> & (new (options?: ConstructorParameters<typeof CherryEngine>[0]) => Engine)} CherryEngineConstructor
  */
-const CherryEngineExport = CherryEngine;
+const CherryEngineExport = /** @type {CherryEngineConstructor} */ (/** @type {unknown} */ (CherryEngine));
 
 export default CherryEngineExport;

packages/cherry-markdown/test/Previewer.spec.ts

@@ -6,7 +6,6 @@ import { createPreviewer } from './helpers/previewer';
 type EngineOptions = ConstructorParameters<typeof CherryEngine>[0];
 
 function createEngine(options: EngineOptions = {}): Engine {
-  // @ts-expect-error CherryEngine's compatibility constructor returns an Engine instance.
   return new CherryEngine(options);
 }
 

packages/cherry-markdown/test/addons/combined-rendering.spec.ts

@@ -45,7 +45,6 @@ describe('addons/combined Markdown rendering', () => {
     PlantUMLCodeEngine.install(options, {});
     const engine = new CherryEngine(options);
     const container = document.createElement('div');
-    // @ts-expect-error CherryEngine's compatibility constructor returns an Engine instance.
     container.innerHTML = engine.makeHtml(`
 # Release diagrams
 
@@ -95,7 +94,6 @@ $$
       },
     });
     const container = document.createElement('div');
-    // @ts-expect-error CherryEngine's compatibility constructor returns an Engine instance.
     container.innerHTML = engine.makeHtml('## Fallback\n\n```mermaid\ngraph TD; A-->B\n```\n\nAfter the diagram.');
     const codeBlock = container.querySelector('[data-type="codeBlock"][data-lang="mermaid"]');
 

packages/cherry-markdown/test/addons/echarts.spec.ts

@@ -151,11 +151,9 @@ describe('addons/EChartsCodeBlockEngine', () => {
     const engine = new CherryEngine({
       engine: { syntax: { codeBlock: { customRenderer: { echarts: renderer } } } },
     });
-    // @ts-expect-error CherryEngine's compatibility constructor returns an Engine instance.
     Object.defineProperty(engine.$cherry, 'previewer', {
       value: { getDom: () => environment.previewerDom },
     });
-    // @ts-expect-error CherryEngine's compatibility constructor returns an Engine instance.
     const html = engine.makeHtml('```echarts\n{ series: [{ type: "bar", data: [3, 5] }] }\n```');
     environment.previewerDom.innerHTML = html;
     const wrapper = environment.previewerDom.querySelector('[data-type="echarts"]');

packages/cherry-markdown/test/addons/mermaid.spec.ts

@@ -387,7 +387,6 @@ describe('addons/MermaidCodeEngine', () => {
     MermaidCodeEngine.install(options, { mermaidAPI: { initialize, render } });
     const engine = new CherryEngine(options);
     const container = document.createElement('div');
-    // @ts-expect-error CherryEngine's compatibility constructor returns an Engine instance.
     container.innerHTML = engine.makeHtml('```mermaid\ngraph TD; A-->B\n```');
     const figure = container.querySelector('figure[data-type="mermaid"]');
     const svg = figure?.querySelector('svg');

packages/cherry-markdown/test/addons/plantuml.spec.ts

@@ -87,7 +87,6 @@ describe('addons/PlantUMLCodeEngine', () => {
     PlantUMLCodeEngine.install(options, {});
     const engine = new CherryEngine(options);
     const container = document.createElement('div');
-    // @ts-expect-error CherryEngine's compatibility constructor returns an Engine instance.
     container.innerHTML = engine.makeHtml('```plantuml\n@startuml\nAlice -> Bob: Hello\n@enduml\n```');
     const wrapper = container.querySelector('[data-type="plantuml"]');
     const image = wrapper?.querySelector('img');

packages/cherry-markdown/test/core/CommonMark.spec.ts

@@ -57,7 +57,6 @@ describe('engine', () => {
     vi.stubGlobal('BUILD_ENV', 'production');
   });
   it.each(suites)('CommonMark-$example', (item) => {
-    // @ts-expect-error CherryEngine 构造器实际返回 Engine 实例
     const cherryHtml = cherryEngine.makeHtml(String(item.markdown));
 
     expect(cherryHtml).toMatchSnapshot();

packages/cherry-markdown/test/core/Engine.spec.ts

@@ -8,7 +8,6 @@ import hooksConfig from '../../src/core/HooksConfig';
 type EngineOptions = ConstructorParameters<typeof CherryEngine>[0];
 
 function createEngine(options: EngineOptions = {}): Engine {
-  // @ts-expect-error CherryEngine's compatibility constructor returns an Engine instance.
   return new CherryEngine(options);
 }
 

packages/cherry-markdown/test/core/EngineDeterminism.spec.ts

@@ -19,7 +19,6 @@ import Engine from '../../src/Engine';
 type EngineOptions = ConstructorParameters<typeof CherryEngine>[0];
 
 function createEngine(options: EngineOptions = {}): Engine {
-  // @ts-expect-error CherryEngine's compatibility constructor returns an Engine instance.
   return new CherryEngine(options);
 }
 

packages/cherry-markdown/test/core/MarkdownRendering.spec.ts

@@ -19,7 +19,6 @@ const createEngine = (options = {}) =>
 const render = (markdown: string, options = {}) => {
   const engine = createEngine(options);
   const container = document.createElement('div');
-  // @ts-expect-error CherryEngine's compatibility constructor returns an Engine instance.
   container.innerHTML = engine.makeHtml(markdown);
   return container;
 };