### Install and Run Monorepo

Source: https://github.com/lyfie-org/luthor/blob/main/README.md

Use these commands to install dependencies and start the development server for the monorepo. Ensure Node.js version 20 or higher and pnpm version 10.4.1 are installed.

```bash
pnpm install
pnpm dev
```

--------------------------------

### Headless Editor System Setup

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/getting-started/quickstart-headless.md

Set up a headless editor system with typed extensions and integrate it into a React application. This example shows how to create a custom toolbar that interacts with the editor commands.

```tsx
import {
  createEditorSystem,
  RichText,
  richTextExtension,
  boldExtension,
} from '@lyfie/luthor-headless';

const extensions = [richTextExtension, boldExtension] as const;
const { Provider, useEditor } = createEditorSystem<typeof extensions>();

function Toolbar() {
  const { commands } = useEditor();
  return <button onClick={() => commands.formatText('bold')}>Bold</button>;
}

export function App() {
  return (
    <Provider extensions={extensions}>
      <Toolbar />
      <RichText placeholder="Type here..." />
    </Provider>
  );
}
```

--------------------------------

### Install Luthor Presets Package

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/getting-started/installation.md

Use this command to install the @lyfie/luthor package, which includes preset editors and bundled styles. This is suitable for users who want a quick setup with pre-configured styles.

```bash
pnpm add @lyfie/luthor
```

--------------------------------

### Basic ExtensiveEditor Setup

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/getting-started/quickstart-luthor.md

Import the necessary styles and the ExtensiveEditor component. Configure available modes and a placeholder for the editor.

```tsx
import '@lyfie/luthor/styles.css';
import { ExtensiveEditor } from '@lyfie/luthor';

export function App() {
  return (
    <ExtensiveEditor
      placeholder="Write anything..."
      availableModes={['visual-editor', 'json', 'markdown', 'html']}
    />
  );
}
```

--------------------------------

### Optional Dependency Installation

Source: https://github.com/lyfie-org/luthor/blob/main/packages/headless/README.md

Install the optional @emoji-mart/data package if emoji support is needed.

```bash
pnpm add @emoji-mart/data
```

--------------------------------

### Install Luthor and Astro React Integration

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/integrations/astro.md

Install the necessary packages for Luthor and Astro's React integration using pnpm.

```bash
pnpm add @lyfie/luthor @astrojs/react
```

--------------------------------

### Core Workflow Commands

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/getting-started/contributor-guide.md

Run these commands to install dependencies, lint code, build the project, and execute tests for both headless and luthor packages.

```bash
pnpm install
pnpm lint
pnpm build
pnpm -C packages/headless test
pnpm -C packages/luthor test
```

--------------------------------

### Basic Editor Setup with Toolbar

Source: https://github.com/lyfie-org/luthor/blob/main/packages/headless/README.md

Demonstrates setting up a basic editor with bold and italic functionality using the createEditorSystem hook and custom Toolbar component. Ensure all necessary extensions are imported and passed to the Provider.

```tsx
import {
  createEditorSystem,
  richTextExtension,
  boldExtension,
  italicExtension,
  RichText,
} from "@lyfie/luthor-headless";

const extensions = [richTextExtension, boldExtension, italicExtension] as const;
const { Provider, useEditor } = createEditorSystem<typeof extensions>();

function Toolbar() {
  const { commands, activeStates } = useEditor();

  return (
    <div>
      <button onClick={() => commands.toggleBold()} aria-pressed={activeStates.bold}>Bold</button>
      <button onClick={() => commands.toggleItalic()} aria-pressed={activeStates.italic}>Italic</button>
    </div>
  );
}

export function Editor() {
  return (
    <Provider extensions={extensions} config={{ namespace: "MyEditor" }}>
      <Toolbar />
      <RichText placeholder="Write something..." />
    </Provider>
  );
}
```

--------------------------------

### Install Luthor Headless Runtime

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/getting-started/installation.md

Install the @lyfie/luthor-headless package along with its peer dependencies. This approach gives you full control over UI and CSS, making it ideal for custom implementations.

```bash
pnpm add @lyfie/luthor-headless lexical @lexical/react @lexical/rich-text @lexical/list @lexical/link @lexical/code @lexical/table @lexical/markdown @lexical/html @lexical/selection @lexical/utils
```

--------------------------------

### Install Luthor Package

Source: https://github.com/lyfie-org/luthor/blob/main/apps/playground/README.md

Install the Luthor package along with React and ReactDOM dependencies.

```bash
pnpm add @lyfie/luthor react react-dom
```

--------------------------------

### Render Editor in a Client Component

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/integrations/nextjs.md

Import the Luthor styles and the ExtensiveEditor component within a 'use client' directive to ensure it runs on the client side. This example demonstrates a basic setup for rendering the editor in a Next.js application.

```tsx
'use client';

import '@lyfie/luthor/styles.css';
import { ExtensiveEditor } from '@lyfie/luthor';

export default function EditorClient() {
  return <ExtensiveEditor placeholder="Write here..." />;
}
```

--------------------------------

### Basic Markdown Editor Setup

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/luthor/presets/md-editor.md

Import and render the MarkDownEditor component with the initial mode set to 'markdown'. Ensure Luthor styles are imported.

```tsx
import '@lyfie/luthor/styles.css';
import { MarkDownEditor } from '@lyfie/luthor';

export function App() {
  return <MarkDownEditor initialMode="markdown" />;
}
```

--------------------------------

### Basic HTMLEditor with HTML Mode

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/luthor/presets/html-editor.md

This snippet shows how to initialize the HTMLEditor to start in HTML mode. It also demonstrates disabling code intelligence.

```tsx
<HTMLEditor
  initialMode="html"
  featureFlags={{ codeIntelligence: false }}
/>
```

--------------------------------

### Importing and Using HTMLEditor in React

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/luthor/presets/html-editor.md

This example demonstrates how to import the necessary CSS and the HTMLEditor component into a React application. It initializes the editor in HTML mode.

```tsx
import '@lyfie/luthor/styles.css';
import { HTMLEditor } from '@lyfie/luthor';

export function App() {
  return <HTMLEditor initialMode="html" />;
}
```

--------------------------------

### Add Luthor Headless Dependencies

Source: https://github.com/lyfie-org/luthor/blob/main/README.md

Install the necessary dependencies for the headless Luthor runtime, including Lexical and related packages, for full UI control and custom workflows.

```bash
pnpm add @lyfie/luthor-headless lexical @lexical/code @lexical/link @lexical/list @lexical/markdown @lexical/react @lexical/rich-text @lexical/selection @lexical/table @lexical/utils react react-dom
```

--------------------------------

### Windows + WSL Workflow for Cloudflare/OpenNext

Source: https://github.com/lyfie-org/luthor/blob/main/README.md

These commands are specific to a Windows environment using WSL for Cloudflare and OpenNext operations. They facilitate previewing and deploying web applications within this setup.

```bash
pnpm run web:preview:wsl
pnpm run web:deploy:wsl
```

--------------------------------

### Documentation Workflow Commands

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/getting-started/contributor-guide.md

Execute these commands to synchronize documentation for the web application and its associated LLM features.

```bash
pnpm -C apps/web run sync:docs
pnpm -C apps/web run sync:llms
```

--------------------------------

### Monorepo Quality Gates

Source: https://github.com/lyfie-org/luthor/blob/main/README.md

Execute these commands to ensure code quality, build the project, and check for linting and formatting issues. These are essential steps before contributing or deploying.

```bash
pnpm build
pnpm lint
pnpm format
pnpm size:check
pnpm check:rule-contracts
```

--------------------------------

### Initialize LegacyRichEditor with Basic Props

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/luthor/presets/legacy-rich-editor.md

Import and initialize the LegacyRichEditor component with specified source format and initial mode. Remember to include the Luthor styles.

```tsx
import '@lyfie/luthor/styles.css';
import { LegacyRichEditor } from '@lyfie/luthor';

export function App() {
  return <LegacyRichEditor sourceFormat="both" initialMode="visual" />;
}
```

--------------------------------

### Basic Extensive Editor Initialization

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/luthor/presets/extensive-editor.md

Import and render the `ExtensiveEditor` component with a placeholder. Ensure Luthor styles are imported.

```tsx
import '@lyfie/luthor/styles.css';
import { ExtensiveEditor } from '@lyfie/luthor';

export function App() {
  return <ExtensiveEditor placeholder="Write anything..." />;
}
```

--------------------------------

### Remix Editor Route Component

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/integrations/remix.md

Example of a Remix route component that renders the ExtensiveEditor. Ensure the Luthor CSS is imported in a parent layout or the route itself.

```tsx
import '@lyfie/luthor/styles.css';
import { ExtensiveEditor } from '@lyfie/luthor';

export default function EditorRoute() {
  return <ExtensiveEditor placeholder="Write here..." />;
}
```

--------------------------------

### Core Theming APIs

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/luthor-headless/features/customization-and-theming.md

These APIs are used for managing and creating editor themes.

```APIDOC
## defaultLuthorTheme

### Description
Provides the default theme configuration for the Luthor editor.

## mergeThemes

### Description
Merges multiple themes into a single theme object.

## createEditorThemeStyleVars

### Description
Creates CSS variables for theme styles, allowing for dynamic theming.

## createCustomNodeExtension

### Description
Allows for the creation of custom node extensions to extend editor functionality.
```

--------------------------------

### Papyra Editor Usage in React

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/luthor/presets/papyra-editor.md

Demonstrates how to integrate the PapyraEditor component into a React application. It shows setting default content, implementing the adapter functions for media, note navigation, and search, and accessing the editor instance via `useRef` to call imperative methods like `getMarkdown`.

```tsx
import '@lyfie/luthor/styles.css';
import { PapyraEditor, type PapyraEditorRef } from '@lyfie/luthor';
import { useRef } from 'react';

export function NoteCanvas({ body }: { body: string }) {
  const ref = useRef<PapyraEditorRef>(null);

  return (
    <PapyraEditor
      ref={ref}
      defaultContent={body}
      adapter={{
        resolveMediaUrl: (name) => `/api/media/${name}`,
        uploadMedia: async (file) => {
          const stored = await upload(file);
          return { filename: stored.name };
        },
        openNote: ({ title }) => router.push(`/notes/${title}`),
        searchNotes: (q) => api.searchNotes(q),
      }}
      onReady={(editor) => {
        // Read the body imperatively — never a controlled value.
        console.log(editor.getMarkdown());
      }}
    />
  );
}
```

--------------------------------

### Basic Vite Integration with ExtensiveEditor

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/integrations/vite.md

Import the necessary CSS and the ExtensiveEditor component from @lyfie/luthor to use it within a Vite-powered React application.

```tsx
import '@lyfie/luthor/styles.css';
import { ExtensiveEditor } from '@lyfie/luthor';

export function App() {
  return <ExtensiveEditor placeholder="Write here..." />;
}
```

--------------------------------

### Custom Upload Handlers for Extensive Editor

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/luthor/presets/extensive-editor.md

Configure custom handlers for image and GIF uploads. If `gifUploadHandler` is omitted, GIFs will use the `imageUploadHandler`. For production, return persistent URLs; `blob:` URLs may cause issues in development StrictMode.

```tsx
<ExtensiveEditor
  imageUploadHandler={async (file) => uploadToCdn(file)}
  gifUploadHandler={async (file) => uploadGifToMediaStore(file)}
/>
```

--------------------------------

### Papyra Editor Adapter Interface

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/luthor/presets/papyra-editor.md

Defines the contract between the Papyra Editor and its host, specifying methods for resolving media URLs, uploading media, opening notes, searching notes, and optionally resolving blocks or cards. The host implements this interface to integrate editor functionalities with its own backend or routing.

```typescript
interface PapyraEditorAdapter {
  resolveMediaUrl(filename: string): string;                 // ![[file]] → URL
  uploadMedia(file: File): Promise<{ filename: string }>;    // drop/paste → store
  openNote(ref: { title?: string; id?: string }): void;      // [[Note]] → navigate
  searchNotes(q: string): Promise<Array<{ id: string; title: string; color?: string }>>;
  resolveBlock?(ref: { note: string; blockId: string }): Promise<string | null>;
  resolveCard?(url: string): Promise<{ 
    title?: string;
    description?: string;
    image?: string;
    favicon?: string;
    siteName?: string;
  } | null>;                                                 // ![[card:url]] → metadata
  onMentions?(usernames: string[]): void;
}
```

--------------------------------

### Papyra Editor Subpath Import

Source: https://github.com/lyfie-org/luthor/blob/main/apps/web/src/content/docs/luthor/presets/papyra-editor.md

Shows an alternative way to import the PapyraEditor component using a subpath export, which might be useful for specific module resolution needs.

```typescript
import { PapyraEditor } from '@lyfie/luthor/presets/papyra';
```