chore: Upgrade docusaurus to 3.4.0 + new patch (#3129)

* upgrade docusaurus to 3.4.0 + new patch

* remove old patch

* move patch

* fix patch

* WIP

* Update patch for start command

* docs: test @apilink tags for rendering links

* Add graph back

---------

Co-authored-by: Kamran Ayub <kamran@hey.com>

site/docs/02-fundamentals/03-actors.mdx

@@ -79,6 +79,74 @@ An actor has a basic lifecycle that dictates how it is initialized, updated, and
 
 ![Actor Lifecycle](ActorLifecycle.png)
 
+```mermaid mermaid
+---
+title: Entity/Actor
+---
+classDiagram
+    class Component {
+        +owner: Entity
+    }
+
+    class Entity {
+        +components: components[]
+        +get(type: Component)
+    }
+
+    class Actor {
+        +transform: TransformComponent
+        +motion: MotionComponent
+        +body: BodyComponent
+        +collider: ColliderComponent
+        +graphics: GraphicsComponent
+    }
+    Component <|-- TransformComponent
+    Component <|-- MotionComponent
+    Component <|-- BodyComponent
+    Component <|-- ColliderComponent
+    Component <|-- GraphicsComponent
+
+    Entity <|-- Actor : Is A
+    Entity --* Component: Has Many
+    Actor --* TransformComponent
+    Actor --* MotionComponent
+    Actor --* BodyComponent
+    Actor --* GraphicsComponent
+
+    class TransformComponent {
+        +pos: Vector
+        +rotation: number
+        +scale: Vector
+        +z: number
+    }
+
+    class MotionComponent {
+        +vel: Vector
+        +acc: Vector
+        +angularVelocity: number
+    }
+
+    class BodyComponent {
+        +mass: number
+        +inertia: number
+        +motion: number
+        +friction: number
+        +bounciness: number
+        +collisionType: CollisionType
+        +group: CollisionGroup
+        +applyImpulse(vec: Vector)
+    }
+    class GraphicsComponent {
+        +current: Graphic
+        +opacity: number
+        +use(graphic: Graphic)
+    }
+    class ColliderComponent {
+        +set(collider: Collider)
+        +get(): Collider
+    }
+```
+
 ## Updating actors
 
 In most games, things are happening on screen: the background is parallax-ing, your hero responds to input, and enemies shoot bullets. In Excalibur, the logic that updates game state is run during the [update loop](/docs/engine#engine-lifecycle). Actors are a way to encapsulate that logic, such as a `Player`, `Enemy`, and `MenuButton`. Actors are designed to be pretty much anything!

site/docs/02-fundamentals/04-architecture.mdx

@@ -4,6 +4,7 @@ slug: /engine
 section: Fundamentals
 ---
 
+
 Excalibur uses the HTML5 Canvas API for drawing your game to the screen.
 The canvas is available to all `draw` functions for raw manipulation,
 but Excalibur is meant to simplify or completely remove the need to use
@@ -59,6 +60,24 @@ scene, which means any actors will not be updated/drawn if they are part of a de
 
 ![Engine Lifecycle](EngineLifecycle.png)
 
+```mermaid mermaid
+sequenceDiagram
+  Engine ->>+ Clock: start()
+  Clock ->> Clock: tick()
+  Clock --)- Engine: mainloop()
+  Engine ->> Loader: Load()
+  Loader --) Engine: Ready
+  loop Every tick Engine.mainloop()
+      opt Not Ready
+          Loader ->> Loader: Update()
+          Loader ->> Loader: Draw()
+      end
+      Engine ->> Current Scene: Update
+      Current Scene ->> ECS World: Update Systems
+  end
+
+```
+
 **Scene Graph**
 
 ```

site/docs/02-fundamentals/04-scenes.mdx

@@ -47,6 +47,25 @@ the engine it will follow this lifecycle:
 
 ![Scene Lifecycle](SceneLifecycle.png)
 
+```mermaid mermaid
+sequenceDiagram
+    loop Every tick Engine.mainloop()
+        
+        alt Update
+            Current Scene ->> ECS World: Update Systems
+        else Draw
+            Current Scene ->> ECS World: Draw Systems
+        end
+
+        ECS World ->> System: Update
+        System ->> ECS World: Entity Query
+        ECS World --) System: Query Changed
+        loop Entity Query 
+           System ->> System: Update
+        end
+    end
+```
+
 For more complex games, you might want more control over a scene in which
 case you can extend [[Scene]]. This is useful for menus, custom loaders,
 and levels.

site/docs/04-graphics/04.4-graphics-context.mdx

@@ -10,6 +10,36 @@ section: Graphics
 
 The default implementation in Excalibur uses WebGL, however Excalibur can fallback to the 2D Canvas implementation if WebGL isn't supported or there isn't browser hardware acceleration. [Read more](#performance)
 
+```mermaid mermaid
+sequenceDiagram
+    participant Entity
+    participant Engine
+    participant ExcaliburGraphicsContext
+    participant RenderPlugin
+    loop Current Frame Draws
+    Entity ->> ExcaliburGraphicsContext: draw(renderer, ...params)
+    ExcaliburGraphicsContext ->> Draw Call Pool: 
+    Draw Call Pool ->> ExcaliburGraphicsContext: Batch Call
+    Note right of Draw Call Pool: Captures current state/transform/renderer
+    end
+    Engine ->> ExcaliburGraphicsContext: End of Frame flush() 
+    Note right of ExcaliburGraphicsContext: Sort Draw Calls By Z
+    loop flush() Every Draw Call
+        ExcaliburGraphicsContext ->> RenderPlugin: Renderer.draw(params)
+        Note right of RenderPlugin: Build up buffers for GPU
+        alt Renderer Switch/Batch Full
+            RenderPlugin ->> RenderTarget: flush() Batch Draw
+        end
+        loop Every Post Process
+            RenderTarget ->> RenderTarget: Post Process 
+        end
+        RenderTarget ->> Screen: blit()
+    end
+
+
+
+```
+
 ### Canvas support
 
 If you have need to switch to 2D canvas based rendering turn on the flag before engine construction.

site/docusaurus.config.ts

@@ -1,4 +1,5 @@
 import { Config } from '@docusaurus/types';
+import type * as Preset from '@docusaurus/preset-classic';
 import { Options as ClassicPresetOptions, ThemeConfig as ClassicPresetThemeConfig } from '@docusaurus/preset-classic';
 import { ReflectionKind } from 'typedoc';
 import path from 'path';
@@ -7,6 +8,7 @@ import { themes } from 'prism-react-renderer';
 import typedocSymbolLinks from 'remark-typedoc-symbol-links';
 import rehypeRaw from 'rehype-raw';
 
+
 const lightCodeTheme = themes.github;
 const darkCodeTheme = themes.dracula;
 
@@ -16,6 +18,10 @@ const rehypeRawOptions = {
 };
 
 const config: Config = {
+  themes: ['@docusaurus/theme-mermaid'],
+  markdown: {
+    mermaid: true,
+  },
   title: 'Excalibur.js',
   tagline: 'Your friendly TypeScript 2D game engine for the web.',
   favicon: 'img/favicon.ico',
@@ -49,11 +55,10 @@ const config: Config = {
   presets: [
     [
       'classic',
-      /** @type {import('@docusaurus/preset-classic').Options} */
       {
         docs: {
           sidebarCollapsed: false,
-          sidebarPath: require.resolve('./sidebars.js'),
+          sidebarPath: './sidebars.ts',
           // Please change this to your repo.
           // Remove this to remove the "edit this page" links.
           editUrl: 'https://github.com/excaliburjs/Excalibur/tree/main/site/',
@@ -81,24 +86,24 @@ const config: Config = {
 
         },
         theme: {
-          customCss: require.resolve('./src/css/custom.css')
+          customCss: './src/css/custom.css'
         }
-      } as ClassicPresetOptions
+      } satisfies Preset.Options,
     ],
     [
       'docusaurus-preset-shiki-twoslash',
       {
         themes: ['github-light', 'github-dark'],
-        ignoreCodeblocksWithCodefenceMeta: ['live']
+        ignoreCodeblocksWithCodefenceMeta: ['live', 'mermaid']
       }
     ]
   ],
 
   plugins: [
-    async function excaliburPlugin(context) {
+    async function excaliburStackblitzPlugin(context) {
       return {
-        name: 'excalibur-plugin',
-        configureWebpack() {
+        name: 'excalibur-stackblitz-plugin',
+        configureWebpack(): webpack.Configuration {
           return {
             devServer: {
               client: {
@@ -109,18 +114,9 @@ const config: Config = {
                 }
               }
             }
-          };
+          } as webpack.Configuration; // Force dev server config
         },
         configureAdditionalWebpack(): webpack.Configuration {
-          // const isCssLoader = (rule: webpack.RuleSetRule) => rule.test && rule.test.toString().includes('.css$');
-          // const postCssLoader = config.module.rules.find(isCssLoader) as webpack.RuleSetRule | undefined;
-
-          // if (postCssLoader) {
-          //   // Exclude engine CSS files from postcss because they will be inlined
-          //   // during engine build
-          //   postCssLoader.exclude = [postCssLoader.exclude, path.resolve(__dirname, '../src/engine')];
-          // }
-
           return {
             name: 'excalibur',
             devtool: false,