# Agent instructions — @naatchaal/editor

You are integrating or customizing **Naat Editor**, Naatchaal’s first-party React WYSIWYG.

**North star:** highly customizable to the deep — but simple.

## Hard rules (myths to kill)

1. **NOT TipTap / Lexical / Quill / Slate / Draft.js** — do not add those packages or invent their APIs (`value`, `useEditor`, extensions, ProseMirror plugins, etc.).
2. **Styles (as of 1.0.1):** importing `@naatchaal/editor` auto-loads CSS. `import "@naatchaal/editor/styles.css"` is **optional** (explicit order / non-bundlers) — do **not** tell users they must import it.
3. **Prefer simple path:** bare `<NaatEditor />` + Client Component (`"use client"`). `config` is optional — omit unless customizing.
4. **Prefill / edit:** `initialContent` + remount with `key={id}`. No controlled `value` prop.
5. **Read-only:** `<NaatEditorViewer content={…} />` (XSS-hardened). Forms: `validateContent` / `isEmptyContent` / `error={…}`; hooks optional.
6. **MCP first:** call `get_agent_rules`, then `generate_integration` with `style: "simple"` by default. Use `"customized"` / `build_toolbar` / `validate_config` only when the user asks for theme/toolbar.
7. **Never** tell apps to `dangerouslySetInnerHTML` raw UGC; use `NaatEditorViewer` or `sanitizeHtmlForView`.

## Two layers

1. **Start here (≈90%)** — `<NaatEditor />`, `initialContent` + `key`, `onChange`, form helpers. View with `<NaatEditorViewer />`. Omit `config`.
2. **Customize deeply (≈10%)** — `config.theme`, toolbar display/items/icons, `renderLayout`, or Provider + Toolbar + Surface.

## Install

```bash
npm i @naatchaal/editor
```

## Canonical imports

```ts
import {
  NaatEditor,
  NaatEditorViewer,
  parseContent,
  isEmptyContent,
  getPlainText,
  getTextLength,
  validateContent,
  buildGroupedToolbar,
  buildFlatToolbar,
  createEditorConfig,
  type DocNode,
  type EditorConfig,
  type ToolbarActionId,
} from "@naatchaal/editor";
// optional only: import "@naatchaal/editor/styles.css";
```

## Implementation checklist (start here)

1. Install peers (`react` / `react-dom`). Styles come with the package import.
2. Client Component wrapper.
3. `initialContent` (DocNode | HTML | plain) or empty.
4. Wire `onChange` → form / API.
5. Remount with `key={recordId}` when editing another row.
6. Validate → `error={…}` on `<NaatEditor />`.
7. Only then add `config` if defaults are not enough.

## Customization map (go deeper)

| Need | Do this |
|------|---------|
| Fewer toolbar buttons | Subset of `ToolbarActionId`s; or `buildFlatToolbar` / `buildGroupedToolbar` |
| Headings in a menu | Dropdown `{ type:"dropdown", id:"heading", label:"Heading", items:["heading1","heading2","heading3","paragraph"] }` |
| Icon / label chrome | `toolbar.display: "icon" \| "label" \| "icon-label"` |
| Swap icons | `icons={{ bold: MyIcon }}` / `renderIcon` |
| Brand tokens | `config.theme.accent` (+ nested toolbar/surface/button/menu) |
| Own layout | `renderLayout` or Provider + Toolbar + Surface |
| Disable code blocks | Omit from toolbar + `enabledBlocks` |
| Reload server doc | `<NaatEditor key={id} initialContent={doc} />` |
| Required / length | `validateContent` / `isEmptyContent` / `getTextLength` + `error` |
| Hide error chrome | `showError={false}` |
| Placeholder | `placeholder` on `NaatEditor` / `NaatSurface` |
| Link hover preview | `linkPreview` (default on) / `false` / `renderLinkPreview` |
| Preview modal | Default toolbar has `preview`; omit to hide; optional `previewTitle` |
| View saved content | `<NaatEditorViewer content={…} />` (hardened view path; prefer over raw HTML) |
| Input height | `theme.surface.minHeight` + optional `maxHeight` |
| Drafts | App-owned → `initialContent` + `key` / `onChange` |
| Optional hooks | `useNaatEditorField` / `useNaatEditorValidation` only if helpful |

Other: media URLs `https`/`http`/`blob` only; height via theme surface (not ad-hoc props); no package `localStorage`.

**Security:** Viewer/preview never set unsanitized HTML. `contentToViewerHtml` / `sanitizeHtmlForView` strip scripts, `on*` handlers, dangerous URL schemes, and untrusted iframes. `docToHtml` / link marks reject `javascript:`/`data:`. Paste is plain-text only. For multi-tenant UGC still sanitize server-side before store; package hardens the render path. Do not `dangerouslySetInnerHTML` raw UGC without `sanitizeHtmlForView`.

## AI doc sources

- Short: package `llms.txt` or https://naat.tools/editor/llms.txt
- Full: package `llms-full.txt` or https://naat.tools/editor/llms-full.txt
- MCP: `npx -y @naatchaal/editor-mcp` → `get_agent_rules` + `generate_integration` (`style: "simple"`)

## Anti-patterns

- Inventing TipTap / Lexical / Quill APIs or packages
- Requiring `styles.css` (auto-loads since 1.0.1; optional only)
- Controlled `value` (remount with `key`)
- Forcing full `config` when defaults suffice
- Requiring hooks for Start here
- Inventing draft/text hooks or built-in localStorage
- Server Components calling document APIs
- Assuming tables / collab exist