refactor(editor): cleanup turbo renderer entry config with doc guide (#11605)

blocksuite/affine/gfx/turbo-renderer/src/turbo-renderer.ts

@@ -42,6 +42,30 @@ const defaultOptions: RendererOptions = {
 export const TurboRendererConfigFactory =
   ConfigExtensionFactory<TurboRendererConfig>('viewport-turbo-renderer');
 
+/**
+ * Manages the Turbo Rendering process for the viewport, coordinating between the main thread and a painter worker.
+ * Turbo Rendering optimizes performance by rendering block content onto a canvas bitmap,
+ * falling back to standard DOM rendering during interactions.
+ *
+ * To add Turbo Rendering support for a new block type (e.g., 'affine:my-block'):
+ *
+ * 1.  **In the block's package (e.g., `blocksuite/affine/blocks/my-block`):**
+ *   a.  Add `@blocksuite/affine/gfx/turbo-renderer` as a dependency in `package.json` and create a `src/turbo` directory.
+ *   b.  Implement the Layout Handler (e.g., `MyBlockLayoutHandlerExtension`) and Painter Worker (e.g., `MyBlockLayoutPainterExtension`). Refer to `ParagraphLayoutHandlerExtension` and `ParagraphLayoutPainterExtension` in `blocksuite/affine/blocks/block-paragraph` for implementation examples.
+ *   c.  Export the Layout Handler and Painter Worker extensions from the block package's main `src/index.ts`.
+ *   d.  Add an export mapping for the painter worker in `package.json` under the `exports` field (e.g., `"./turbo-painter": "./src/turbo/my-block-painter.worker.ts"`).
+ *   e.  Add a TypeScript project reference to `blocksuite/affine/gfx/turbo-renderer` in `tsconfig.json`.
+ *
+ * 2.  **In the application integration point (e.g., `packages/frontend/core/src/blocksuite/extensions` and `blocksuite/integration-test/src/__tests__/utils/renderer-entry.ts`):**
+ *   a.  In `turbo-renderer.ts` (or the file setting up `TurboRendererConfigFactory`):
+ *     - Import and add the new Layout Handler extension to the `patchTurboRendererExtension` array (or equivalent DI setup). See how `ParagraphLayoutHandlerExtension` is added as a reference.
+ *   b.  In `turbo-painter.worker.ts` (the painter worker entry point):
+ *     - Import and add the new Painter Worker extension to the `ViewportLayoutPainter` constructor's extension array. See how `ParagraphLayoutPainterExtension` is added as a reference.
+ *
+ * 3.  **Run `yarn affine init`** from the workspace root to update generated configuration files (`workspace.gen.ts`) and the lockfile (`yarn.lock`).
+ *
+ * **Note:** Always ensure the directory structure and export patterns match the `paragraph` block (`blocksuite/affine/blocks/block-paragraph`) for consistency.
+ */
 export class ViewportTurboRendererExtension extends GfxExtension {
   static override key = 'viewportTurboRenderer';
 

blocksuite/integration-test/src/__tests__/utils/renderer-entry.ts

@@ -1,3 +1,4 @@
+import { ListLayoutHandlerExtension } from '@blocksuite/affine/blocks/list';
 import { ParagraphLayoutHandlerExtension } from '@blocksuite/affine/blocks/paragraph';
 import {
   TurboRendererConfigFactory,
@@ -11,6 +12,7 @@ import { createPainterWorker, setupEditor } from './setup.js';
 async function init() {
   setupEditor('edgeless', [
     ParagraphLayoutHandlerExtension,
+    ListLayoutHandlerExtension,
     TurboRendererConfigFactory({
       painterWorkerEntry: createPainterWorker,
     }),

blocksuite/integration-test/src/__tests__/utils/setup.ts

@@ -103,7 +103,7 @@ async function createEditor(
 
 export function createPainterWorker() {
   const worker = new Worker(
-    new URL('./turbo-painter-entry.worker.ts', import.meta.url),
+    new URL('./turbo-painter.worker.ts', import.meta.url),
     {
       type: 'module',
     }

blocksuite/integration-test/src/__tests__/utils/turbo-painter.worker.ts

@@ -1,4 +1,8 @@
+import { ListLayoutPainterExtension } from '@blocksuite/affine-block-list/turbo-painter';
 import { ParagraphLayoutPainterExtension } from '@blocksuite/affine-block-paragraph/turbo-painter';
 import { ViewportLayoutPainter } from '@blocksuite/affine-gfx-turbo-renderer/painter';
 
-new ViewportLayoutPainter([ParagraphLayoutPainterExtension]);
+new ViewportLayoutPainter([
+  ParagraphLayoutPainterExtension,
+  ListLayoutPainterExtension,
+]);