Upgrade-to-rspress-v2

.changeset/bright-rspack-ignore.md

@@ -0,0 +1,5 @@
+---
+"@lix-js/sdk": patch
+---
+
+Add webpack/rspack ignore hints to dynamic inline plugin imports and document usage with a JSDoc example.

packages/lix/docs/package.json

@@ -17,22 +17,23 @@
     "@lix-js/plugin-json": "workspace:*",
     "@lix-js/sdk": "workspace:*",
     "@monaco-editor/react": "^4.7.0",
-    "@rspress/shared": "^1.44.0",
+    "@rspress/core": "2.0.0-rc.1",
+    "@rspress/plugin-llms": "2.0.0-rc.1",
+    "@rspress/plugin-sitemap": "2.0.0-rc.1",
     "@tailwindcss/postcss": "^4.1.10",
+    "@types/mdast": "^4.0.4",
     "@types/react": "^19.0.12",
     "@types/react-dom": "^19.0.4",
     "dayjs": "^1.11.11",
     "debug": "^4.3.4",
-    "mermaid": "^11.7.0",
+    "prettier": "^3.6.2",
     "react": "^19.1.0",
     "react-dom": "^19.1.0",
-    "rspress": "^1.40.2",
-    "rspress-plugin-mermaid": "^0.3.0",
-    "prettier": "^3.6.2",
     "tailwindcss": "^4.1.11",
     "typedoc": "0.28.12",
     "typedoc-plugin-markdown": "4.7.0",
     "typescript": "5.8.3",
+    "unist-util-visit": "^5.0.0",
     "vitest": "^3.2.4"
   },
   "keywords": [
@@ -46,6 +47,7 @@
   "author": "Opral, Inc.",
   "license": "MIT",
   "dependencies": {
+    "mermaid": "^11.7.0",
     "shiki": "^3.7.0"
   }
 }

packages/lix/docs/rspress-plugins/remark-mermaid.ts

@@ -0,0 +1,74 @@
+import path from "node:path";
+import { visit } from "unist-util-visit";
+import type { Code, Parent } from "mdast";
+import type { RspressPlugin } from "@rspress/core";
+
+type MdxJsxFlowElement = {
+  type: "mdxJsxFlowElement";
+  name: string;
+  attributes: Array<{
+    type: "mdxJsxAttribute";
+    name: string;
+    value: string;
+  }>;
+  children: [];
+  data?: Record<string, unknown>;
+};
+
+export const mermaidComponentPath = path.join(
+  __dirname,
+  "../src/docs/components/Mermaid.tsx",
+);
+
+/**
+ * Remark plugin that converts mermaid code fences into MDX components.
+ *
+ * @example
+ * remarkMermaid();
+ */
+export const remarkMermaid = () => (tree: unknown) => {
+  visit(tree, "code", (node: Code, index, parent) => {
+    if (
+      node.lang !== "mermaid" ||
+      parent === null ||
+      parent === undefined ||
+      typeof index !== "number"
+    ) {
+      return;
+    }
+
+    const mermaidNode: MdxJsxFlowElement = {
+      type: "mdxJsxFlowElement",
+      name: "Mermaid",
+      attributes: [
+        {
+          type: "mdxJsxAttribute",
+          name: "code",
+          value: node.value,
+        },
+      ],
+      children: [],
+      data: {
+        _mdxExplicitJsx: true,
+      },
+    };
+
+    (parent as Parent).children.splice(index, 1, mermaidNode);
+  });
+};
+
+/**
+ * Transforms ```mermaid code fences into a Mermaid React component so diagrams render at runtime.
+ *
+ * @example
+ * mermaidPlugin();
+ */
+export function mermaidPlugin(): RspressPlugin {
+  return {
+    name: "local-mermaid",
+    markdown: {
+      globalComponents: [mermaidComponentPath],
+      remarkPlugins: [remarkMermaid],
+    },
+  };
+}

packages/lix/docs/rspress-plugins/sync-react-utils-readme.ts

@@ -1,6 +1,6 @@
 import path from "node:path";
 import fs from "node:fs/promises";
-import type { RspressPlugin } from "@rspress/shared";
+import type { RspressPlugin } from "@rspress/core";
 
 export function syncReactUtilsReadmePlugin(): RspressPlugin {
   return {

packages/lix/docs/rspress-plugins/typedoc-plugin.ts

@@ -1,7 +1,7 @@
 import path from "node:path";
 import fs from "node:fs/promises";
 import * as fsSync from "node:fs";
-import type { RspressPlugin } from "@rspress/shared";
+import type { RspressPlugin } from "@rspress/core";
 import { Application, TypeDocOptions } from "typedoc";
 
 export interface CustomTypeDocOptions {
@@ -25,7 +25,7 @@ async function patchLinks(outputDir: string) {
       (_match, p1, p2) => {
         if (
           // 2. [foo](./bar) -> [foo](./bar) no change
-          ["/", "."].includes(p2[0]) ||
+          ["/", ".", "#"].includes(p2[0]) ||
           // 3. [foo](http(s)://...) -> [foo](http(s)://...) no change
           p2.startsWith("http://") ||
           p2.startsWith("https://")
@@ -130,7 +130,7 @@ Welcome to the comprehensive Lix SDK API documentation. This reference provides
 
 ## Need Help?
 
-If you're new to Lix, consider starting with our [Getting Started Guide](/docs/quick-start) before diving into the API reference.
+If you're new to Lix, consider starting with our [Getting Started Guide](/docs/getting-started) before diving into the API reference.
 
 Browse the API documentation using the sidebar to find the specific functionality you need.`,
     );

packages/lix/docs/rspress.config.ts

@@ -1,11 +1,16 @@
 import * as path from "node:path";
-import { defineConfig } from "rspress/config";
-import mermaid from "rspress-plugin-mermaid";
+import { defineConfig } from "@rspress/core";
+import { pluginLlms } from "@rspress/plugin-llms";
 import { syncReactUtilsReadmePlugin } from "./rspress-plugins/sync-react-utils-readme";
 import {
   generateApiDocs,
   generateApiSidebar,
 } from "./rspress-plugins/typedoc-plugin";
+import {
+  mermaidComponentPath,
+  remarkMermaid,
+} from "./rspress-plugins/remark-mermaid";
+import { pluginSitemap } from "@rspress/plugin-sitemap";
 
 // Generate API docs before creating the config
 // We need to generate the API docs at the top level (before defineConfig) because
@@ -30,18 +35,33 @@ export default defineConfig({
     "Official documentation for the Lix SDK - a change control system that runs in the browser",
   icon: "/logo.svg",
   globalStyles: path.join(__dirname, "src/styles/index.css"),
+  // Use the shared theme directory (not inside src) so custom MDX components load, including the LLM copy button.
+  themeDir: path.join(__dirname, "theme"),
   route: {
     cleanUrls: true,
-    exclude: ["**/*.test.ts", "**/*.test.tsx", "**/*.spec.ts", "**/*.spec.tsx"],
+    exclude: [
+      "**/*.test.ts",
+      "**/*.test.tsx",
+      "**/*.spec.ts",
+      "**/*.spec.tsx",
+      "**/examples/**/*.ts",
+      "**/components/**/*.{ts,tsx}",
+    ],
   },
   markdown: {
     // Disable Rust MDX compiler to support global components
     mdxRs: false,
     globalComponents: [
       path.join(__dirname, "src/docs/components/InteractiveExampleCard.tsx"),
+      mermaidComponentPath,
     ],
+    remarkPlugins: [remarkMermaid],
   },
   builderConfig: {
+    dev: {
+      // Disable lazy compilation to avoid giant dev proxy requests from Shiki/highlighter
+      lazyCompilation: false,
+    },
     tools: {
       rspack: {
         module: {
@@ -62,7 +82,13 @@ export default defineConfig({
       },
     },
   },
-  plugins: [mermaid(), syncReactUtilsReadmePlugin()],
+  plugins: [
+    pluginLlms(),
+    pluginSitemap({
+      siteUrl: "https://lix.dev",
+    }),
+    syncReactUtilsReadmePlugin(),
+  ],
   themeConfig: {
     darkMode: false,
     nav: [

packages/lix/docs/src/docs/components/Mermaid.tsx

@@ -0,0 +1,49 @@
+import { useEffect, useId, useState } from "react";
+import mermaid, { type MermaidConfig } from "mermaid";
+
+interface MermaidProps {
+  code: string;
+  config?: MermaidConfig;
+}
+
+/**
+ * Renders a Mermaid diagram from fenced code blocks.
+ *
+ * @example
+ * <Mermaid code="graph TD; A-->B;" />
+ */
+export default function Mermaid({ code, config }: MermaidProps) {
+  const [svg, setSvg] = useState("");
+  const [hasError, setHasError] = useState(false);
+  const id = useId().replace(/:/g, "");
+
+  useEffect(() => {
+    const theme = document.documentElement.classList.contains("dark")
+      ? "dark"
+      : "default";
+
+    const mergedConfig: MermaidConfig = {
+      startOnLoad: false,
+      securityLevel: "loose",
+      theme,
+      ...config,
+    };
+
+    Promise.resolve()
+      .then(() => {
+        mermaid.initialize(mergedConfig);
+        return mermaid.render(id, code);
+      })
+      .then(({ svg }) => {
+        setSvg(svg);
+        setHasError(false);
+      })
+      .catch(() => setHasError(true));
+  }, [code, config, id]);
+
+  if (hasError) {
+    return null;
+  }
+
+  return <div dangerouslySetInnerHTML={{ __html: svg }} />;
+}

packages/lix/docs/src/docs/components/landing-page.tsx

@@ -439,10 +439,9 @@ function LandingPage() {
             </h1>
 
             <p className="text-gray-600 text-base sm:text-xl max-w-3xl mx-auto leading-relaxed mt-12">
-              Lix is a JavaScript SDK that enables Git-like capabilities for
-              apps and agents:
-              <br />
-              Change proposals, versions (branches), history, blame, etc.
+              Lix is a change control system that enables Git-like features for
+              applications and AI agents such as change proposals, versions
+              (branching), history, and blame.
             </p>
 
             <div className="flex flex-col sm:flex-row items-center justify-center gap-4 mb-16  mt-8">

packages/lix/docs/src/docs/deterministic-mode.md

@@ -187,8 +187,8 @@ The following functions provide deterministic behavior when `lix_deterministic_m
 
 | Function                      | Purpose                          | Docs                                                       |
 | ----------------------------- | -------------------------------- | ---------------------------------------------------------- |
-| `getTimestamp({ lix })`       | Logical clock timestamps         | [API docs](/api/functions/timestamp)                       |
-| `random({ lix })`             | Reproducible random numbers      | [API docs](/api/functions/random)                          |
-| `uuidV7({ lix })`             | Deterministic UUID v7 generation | [API docs](/api/functions/uuidV7)                          |
-| `nanoId({ lix })`             | Deterministic nano ID generation | [API docs](/api/functions/nanoId)                          |
-| `nextSequenceNumber({ lix })` | Monotonic counter (advanced)     | [API docs](/api/functions/nextDeterministicSequenceNumber) |
+| `getTimestamp({ lix })`       | Logical clock timestamps         | [API docs](/docs/api/functions/getTimestamp)                    |
+| `random({ lix })`             | Reproducible random numbers      | [API docs](/docs/api/functions/random)                          |
+| `uuidV7({ lix })`             | Deterministic UUID v7 generation | [API docs](/docs/api/functions/uuidV7)                          |
+| `nanoId({ lix })`             | Deterministic nano ID generation | [API docs](/docs/api/functions/nanoId)                          |
+| `nextSequenceNumber({ lix })` | Monotonic counter (advanced)     | [API docs](/docs/api/functions/nextSequenceNumber)             |

packages/lix/docs/src/docs/metadata.md

@@ -4,7 +4,7 @@ In Lix, **metadata** refers to arbitrary, structured data that you can attach to
 
 ## When to Use Metadata
 
-The answer is simple: Use metadata when an [entity](./entity) is not owned by your application, but for interoperability reasons, you need to use that entity or its schema. In such cases, you can attach metadata to add your application's specific information without altering the original entity's schema.
+The answer is simple: Use metadata when an [entity](/docs/data-model#entities-meaningful-units-of-data) is not owned by your application, but for interoperability reasons, you need to use that entity or its schema. In such cases, you can attach metadata to add your application's specific information without altering the original entity's schema.
 
 Here are some examples:
 

packages/lix/docs/src/docs/plugins.md

@@ -145,4 +145,4 @@ Community plugins: Check the [Lix GitHub organization](https://github.com/opral/
 
 - Learn about [Data Model](/docs/data-model) to understand entities and schemas
 - See [Querying Changes](/docs/querying-changes) to work with plugin-detected changes
-- Explore the [API Reference](/api/) for detailed plugin interfaces
+- Explore the [API Reference](/docs/api/) for detailed plugin interfaces

packages/lix/docs/src/docs/versions.mdx

@@ -108,7 +108,7 @@ Versions let you work with different states of your data in isolation. Here's a
 
 | Function / Type      | Purpose                     | Docs                                   |
 | -------------------- | --------------------------- | -------------------------------------- |
-| `createVersion()`    | Create a new version branch | [API](/api/functions/createVersion)    |
-| `switchVersion()`    | Change active version       | [API](/api/functions/switchVersion)    |
-| `createCheckpoint()` | Create a labeled commit     | [API](/api/functions/createCheckpoint) |
-| `LixVersion`         | Version type definition     | [API](/api/types/LixVersion)           |
+| `createVersion()`    | Create a new version branch | [API](/docs/api/functions/createVersion)    |
+| `switchVersion()`    | Change active version       | [API](/docs/api/functions/switchVersion)    |
+| `createCheckpoint()` | Create a labeled commit     | [API](/docs/api/functions/createCheckpoint) |
+| `LixVersion`         | Version type definition     | [API](/docs/api/types/LixVersion)           |

packages/lix/docs/src/docs/what-is-lix.md

@@ -1,17 +1,19 @@
 # What is Lix?
 
-Lix is a JavaScript SDK for change control that enables Git-like capabilities for apps and agents: [Change proposals](/docs/change-proposals), [versions](/docs/versions) (branching), [history](/docs/history), [blame](/docs/attribution), and more.
+Lix is a change control system that enables Git-like features for applications and AI agents such as [Change Proposals](/docs/change-proposals), [Versions](/docs/versions) (branching), [History](/docs/history), and [Blame](/docs/attribution).
+
+What makes lix unique:
 
 - 🌐 Embeddable - Works is in the Browser, Node.js, etc.
 - 📄 Supports any data format (Excel, JSON, CSV, etc.)
-- 🛠️ SDK-first - Provides a SQL API to query changes, history, etc. 
+- 🛠️ SDK-first - Designed for applications
 
-## Features
+## Use Cases
 
-- [History](/docs/history) - Query the complete history of any entity
-- [Diffs](/docs/diffs) - Compare changes across time and versions
-- [Change Proposals](/docs/change-proposals) - Submit and review changes before applying
-- [Conversations](/docs/conversations) - Discuss changes with your team
-- [Restore](/docs/restore) - Restore previous states and undo changes
+- AI agent safety rails: agents propose edits instead of applying directly; humans review diffs and restore if needed.
+- Collaborative editing in apps: multi-user workflows with change proposals, conversations, and history/blame for structured data.
+- Approval workflows: branch/merge-style reviews for non-code data before changes go live.
+- Auditable data changes: track who changed what and when with versioned history and diff views.
+- Product experiments and variants: spin up versions of data models or content, compare diffs, and merge back selectively.
 
 ![Lix features](/lix-features.svg)