@liminis/editor 0.1.0-rc.1

package/dist/types.d.ts

@@ -0,0 +1,296 @@
+import { z } from 'zod';
+export declare const TextEditSchema: z.ZodObject<{
+    start: z.ZodNumber;
+    end: z.ZodNumber;
+    newText: z.ZodString;
+}, z.core.$strip>;
+export declare const CodeThemeSchema: z.ZodEnum<{
+    auto: "auto";
+    dark: "dark";
+    light: "light";
+    "github-dark": "github-dark";
+    "github-light": "github-light";
+    monokai: "monokai";
+}>;
+export declare const ImagePathResolutionSchema: z.ZodEnum<{
+    document: "document";
+    workspace: "workspace";
+}>;
+export declare const ThemeOverridesSchema: z.ZodRecord<z.ZodString, z.ZodString>;
+export declare const SlashMDSettingsSchema: z.ZodObject<{
+    assetsFolder: z.ZodString;
+    imagePathResolution: z.ZodEnum<{
+        document: "document";
+        workspace: "workspace";
+    }>;
+    formatWrap: z.ZodNumber;
+    calloutsStyle: z.ZodEnum<{
+        admonition: "admonition";
+        emoji: "emoji";
+    }>;
+    togglesSyntax: z.ZodEnum<{
+        details: "details";
+        list: "list";
+    }>;
+    mathEnabled: z.ZodBoolean;
+    mermaidEnabled: z.ZodBoolean;
+    codeTheme: z.ZodEnum<{
+        auto: "auto";
+        dark: "dark";
+        light: "light";
+        "github-dark": "github-dark";
+        "github-light": "github-light";
+        monokai: "monokai";
+    }>;
+    headingColor: z.ZodString;
+    h1Color: z.ZodString;
+    h2Color: z.ZodString;
+    h3Color: z.ZodString;
+    h4Color: z.ZodString;
+    h5Color: z.ZodString;
+    h1Indent: z.ZodString;
+    h2Indent: z.ZodString;
+    h3Indent: z.ZodString;
+    h4Indent: z.ZodString;
+    h5Indent: z.ZodString;
+    boldColor: z.ZodString;
+    italicColor: z.ZodString;
+}, z.core.$strip>;
+export declare const DocInitMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"DOC_INIT">;
+    text: z.ZodString;
+    settings: z.ZodObject<{
+        assetsFolder: z.ZodString;
+        imagePathResolution: z.ZodEnum<{
+            document: "document";
+            workspace: "workspace";
+        }>;
+        formatWrap: z.ZodNumber;
+        calloutsStyle: z.ZodEnum<{
+            admonition: "admonition";
+            emoji: "emoji";
+        }>;
+        togglesSyntax: z.ZodEnum<{
+            details: "details";
+            list: "list";
+        }>;
+        mathEnabled: z.ZodBoolean;
+        mermaidEnabled: z.ZodBoolean;
+        codeTheme: z.ZodEnum<{
+            auto: "auto";
+            dark: "dark";
+            light: "light";
+            "github-dark": "github-dark";
+            "github-light": "github-light";
+            monokai: "monokai";
+        }>;
+        headingColor: z.ZodString;
+        h1Color: z.ZodString;
+        h2Color: z.ZodString;
+        h3Color: z.ZodString;
+        h4Color: z.ZodString;
+        h5Color: z.ZodString;
+        h1Indent: z.ZodString;
+        h2Indent: z.ZodString;
+        h3Indent: z.ZodString;
+        h4Indent: z.ZodString;
+        h5Indent: z.ZodString;
+        boldColor: z.ZodString;
+        italicColor: z.ZodString;
+    }, z.core.$strip>;
+    assetBaseUri: z.ZodOptional<z.ZodString>;
+    documentDirUri: z.ZodOptional<z.ZodString>;
+    themeOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export declare const DocChangedMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"DOC_CHANGED">;
+    text: z.ZodString;
+    range: z.ZodOptional<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const AssetWrittenMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ASSET_WRITTEN">;
+    relPath: z.ZodString;
+    webviewUri: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const AssetWriteFailedMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ASSET_WRITE_FAILED">;
+}, z.core.$strip>;
+export declare const SettingsChangedMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"SETTINGS_CHANGED">;
+    settings: z.ZodObject<{
+        assetsFolder: z.ZodString;
+        imagePathResolution: z.ZodEnum<{
+            document: "document";
+            workspace: "workspace";
+        }>;
+        formatWrap: z.ZodNumber;
+        calloutsStyle: z.ZodEnum<{
+            admonition: "admonition";
+            emoji: "emoji";
+        }>;
+        togglesSyntax: z.ZodEnum<{
+            details: "details";
+            list: "list";
+        }>;
+        mathEnabled: z.ZodBoolean;
+        mermaidEnabled: z.ZodBoolean;
+        codeTheme: z.ZodEnum<{
+            auto: "auto";
+            dark: "dark";
+            light: "light";
+            "github-dark": "github-dark";
+            "github-light": "github-light";
+            monokai: "monokai";
+        }>;
+        headingColor: z.ZodString;
+        h1Color: z.ZodString;
+        h2Color: z.ZodString;
+        h3Color: z.ZodString;
+        h4Color: z.ZodString;
+        h5Color: z.ZodString;
+        h1Indent: z.ZodString;
+        h2Indent: z.ZodString;
+        h3Indent: z.ZodString;
+        h4Indent: z.ZodString;
+        h5Indent: z.ZodString;
+        boldColor: z.ZodString;
+        italicColor: z.ZodString;
+    }, z.core.$strip>;
+    themeOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>;
+export declare const ErrorMessageSchema: z.ZodObject<{
+    type: z.ZodLiteral<"ERROR">;
+    message: z.ZodString;
+}, z.core.$strip>;
+export declare const HostToUIMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    type: z.ZodLiteral<"DOC_INIT">;
+    text: z.ZodString;
+    settings: z.ZodObject<{
+        assetsFolder: z.ZodString;
+        imagePathResolution: z.ZodEnum<{
+            document: "document";
+            workspace: "workspace";
+        }>;
+        formatWrap: z.ZodNumber;
+        calloutsStyle: z.ZodEnum<{
+            admonition: "admonition";
+            emoji: "emoji";
+        }>;
+        togglesSyntax: z.ZodEnum<{
+            details: "details";
+            list: "list";
+        }>;
+        mathEnabled: z.ZodBoolean;
+        mermaidEnabled: z.ZodBoolean;
+        codeTheme: z.ZodEnum<{
+            auto: "auto";
+            dark: "dark";
+            light: "light";
+            "github-dark": "github-dark";
+            "github-light": "github-light";
+            monokai: "monokai";
+        }>;
+        headingColor: z.ZodString;
+        h1Color: z.ZodString;
+        h2Color: z.ZodString;
+        h3Color: z.ZodString;
+        h4Color: z.ZodString;
+        h5Color: z.ZodString;
+        h1Indent: z.ZodString;
+        h2Indent: z.ZodString;
+        h3Indent: z.ZodString;
+        h4Indent: z.ZodString;
+        h5Indent: z.ZodString;
+        boldColor: z.ZodString;
+        italicColor: z.ZodString;
+    }, z.core.$strip>;
+    assetBaseUri: z.ZodOptional<z.ZodString>;
+    documentDirUri: z.ZodOptional<z.ZodString>;
+    themeOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"DOC_CHANGED">;
+    text: z.ZodString;
+    range: z.ZodOptional<z.ZodObject<{
+        start: z.ZodNumber;
+        end: z.ZodNumber;
+    }, z.core.$strip>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ASSET_WRITTEN">;
+    relPath: z.ZodString;
+    webviewUri: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ASSET_WRITE_FAILED">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"SETTINGS_CHANGED">;
+    settings: z.ZodObject<{
+        assetsFolder: z.ZodString;
+        imagePathResolution: z.ZodEnum<{
+            document: "document";
+            workspace: "workspace";
+        }>;
+        formatWrap: z.ZodNumber;
+        calloutsStyle: z.ZodEnum<{
+            admonition: "admonition";
+            emoji: "emoji";
+        }>;
+        togglesSyntax: z.ZodEnum<{
+            details: "details";
+            list: "list";
+        }>;
+        mathEnabled: z.ZodBoolean;
+        mermaidEnabled: z.ZodBoolean;
+        codeTheme: z.ZodEnum<{
+            auto: "auto";
+            dark: "dark";
+            light: "light";
+            "github-dark": "github-dark";
+            "github-light": "github-light";
+            monokai: "monokai";
+        }>;
+        headingColor: z.ZodString;
+        h1Color: z.ZodString;
+        h2Color: z.ZodString;
+        h3Color: z.ZodString;
+        h4Color: z.ZodString;
+        h5Color: z.ZodString;
+        h1Indent: z.ZodString;
+        h2Indent: z.ZodString;
+        h3Indent: z.ZodString;
+        h4Indent: z.ZodString;
+        h5Indent: z.ZodString;
+        boldColor: z.ZodString;
+        italicColor: z.ZodString;
+    }, z.core.$strip>;
+    themeOverrides: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"ERROR">;
+    message: z.ZodString;
+}, z.core.$strip>], "type">;
+export type TextEdit = z.infer<typeof TextEditSchema>;
+export type CodeTheme = z.infer<typeof CodeThemeSchema>;
+export type ImagePathResolution = z.infer<typeof ImagePathResolutionSchema>;
+export type ThemeOverrides = z.infer<typeof ThemeOverridesSchema>;
+export type SlashMDSettings = z.infer<typeof SlashMDSettingsSchema>;
+export type HostToUIMessage = z.infer<typeof HostToUIMessageSchema>;
+export type UIToHostMessage = {
+    type: 'APPLY_TEXT_EDITS';
+    edits: TextEdit[];
+    reason: 'typing' | 'drag' | 'paste' | 'format';
+} | {
+    type: 'WRITE_ASSET';
+    dataUri: string;
+    suggestedName?: string;
+} | {
+    type: 'REQUEST_INIT';
+} | {
+    type: 'REQUEST_SETTINGS';
+} | {
+    type: 'OPEN_LINK';
+    url: string;
+};
+export declare function validateHostToUIMessage(data: unknown): HostToUIMessage | null;
+export type BlockType = 'paragraph' | 'heading1' | 'heading2' | 'heading3' | 'bulletList' | 'numberedList' | 'todoList' | 'quote' | 'code' | 'divider' | 'image' | 'table' | 'toggle' | 'callout' | 'link';
+export type CalloutType = 'note' | 'tip' | 'warning' | 'important' | 'caution';

package/dist/types.js

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+// =============================================================================
+// ZOD SCHEMAS - Runtime validation
+// =============================================================================
+export const TextEditSchema = z.object({
+    start: z.number().int().min(0),
+    end: z.number().int().min(0),
+    newText: z.string().max(10_000_000),
+});
+// Code theme options
+export const CodeThemeSchema = z.enum(['auto', 'dark', 'light', 'github-dark', 'github-light', 'monokai']);
+// Image path resolution options
+export const ImagePathResolutionSchema = z.enum(['document', 'workspace']);
+// Theme overrides - CSS variable values
+export const ThemeOverridesSchema = z.record(z.string(), z.string());
+export const SlashMDSettingsSchema = z.object({
+    assetsFolder: z.string().max(256),
+    imagePathResolution: ImagePathResolutionSchema,
+    formatWrap: z.number().int().min(0).max(1000),
+    calloutsStyle: z.enum(['admonition', 'emoji']),
+    togglesSyntax: z.enum(['details', 'list']),
+    mathEnabled: z.boolean(),
+    mermaidEnabled: z.boolean(),
+    codeTheme: CodeThemeSchema,
+    headingColor: z.string().max(64),
+    h1Color: z.string().max(64),
+    h2Color: z.string().max(64),
+    h3Color: z.string().max(64),
+    h4Color: z.string().max(64),
+    h5Color: z.string().max(64),
+    h1Indent: z.string().max(64),
+    h2Indent: z.string().max(64),
+    h3Indent: z.string().max(64),
+    h4Indent: z.string().max(64),
+    h5Indent: z.string().max(64),
+    boldColor: z.string().max(64),
+    italicColor: z.string().max(64),
+});
+// Host → UI message schemas
+export const DocInitMessageSchema = z.object({
+    type: z.literal('DOC_INIT'),
+    text: z.string(),
+    settings: SlashMDSettingsSchema,
+    assetBaseUri: z.string().optional(),
+    documentDirUri: z.string().optional(),
+    themeOverrides: ThemeOverridesSchema.optional(),
+});
+export const DocChangedMessageSchema = z.object({
+    type: z.literal('DOC_CHANGED'),
+    text: z.string(),
+    range: z.object({
+        start: z.number().int().min(0),
+        end: z.number().int().min(0),
+    }).optional(),
+});
+export const AssetWrittenMessageSchema = z.object({
+    type: z.literal('ASSET_WRITTEN'),
+    relPath: z.string().max(1024),
+    webviewUri: z.string().optional(),
+});
+export const AssetWriteFailedMessageSchema = z.object({
+    type: z.literal('ASSET_WRITE_FAILED'),
+});
+export const SettingsChangedMessageSchema = z.object({
+    type: z.literal('SETTINGS_CHANGED'),
+    settings: SlashMDSettingsSchema,
+    themeOverrides: ThemeOverridesSchema.optional(),
+});
+export const ErrorMessageSchema = z.object({
+    type: z.literal('ERROR'),
+    message: z.string().max(10000),
+});
+export const HostToUIMessageSchema = z.discriminatedUnion('type', [
+    DocInitMessageSchema,
+    DocChangedMessageSchema,
+    AssetWrittenMessageSchema,
+    AssetWriteFailedMessageSchema,
+    SettingsChangedMessageSchema,
+    ErrorMessageSchema,
+]);
+// =============================================================================
+// VALIDATION HELPER
+// =============================================================================
+export function validateHostToUIMessage(data) {
+    const result = HostToUIMessageSchema.safeParse(data);
+    if (!result.success) {
+        console.error('SlashMD: Invalid Host→UI message:', result.error.message);
+        return null;
+    }
+    return result.data;
+}

package/dist/utils/file-types.d.ts

@@ -0,0 +1,10 @@
+/**
+ * File type detection utilities for determining how to render files in the editor.
+ */
+export type FileType = 'markdown' | 'image' | 'pdf' | 'mermaid' | 'code' | 'remarkable-document' | 'unknown';
+/**
+ * Determine the file type based on path and extension.
+ * @param path - The file path to check
+ * @returns The detected file type
+ */
+export declare function getFileType(path: string | null): FileType;

package/dist/utils/file-types.js

@@ -0,0 +1,46 @@
+/**
+ * File type detection utilities for determining how to render files in the editor.
+ */
+/**
+ * Determine the file type based on path and extension.
+ * @param path - The file path to check
+ * @returns The detected file type
+ */
+export function getFileType(path) {
+    if (!path)
+        return 'unknown';
+    const ext = path.toLowerCase().split('.').pop() || '';
+    // Check for remarkable document - files inside a remarkable document folder
+    // Structure: remarkable/DocName/document.pdf, remarkable/DocName/pages/page_001.png, etc.
+    // But NOT remarkable/index.md (which is the section index markdown)
+    if (path.startsWith('remarkable/')) {
+        const parts = path.split('/');
+        // parts[0] = 'remarkable', parts[1] = DocName or filename
+        // If parts.length >= 3, it's inside a document folder (e.g., remarkable/DocName/document.pdf)
+        // If parts.length === 2 and NOT a markdown file, treat as remarkable document folder
+        if (parts.length >= 3) {
+            return 'remarkable-document';
+        }
+        // parts.length === 2: remarkable/something - check if it's the index.md or a doc folder reference
+        if (parts.length === 2 && !['md', 'mdc'].includes(ext)) {
+            return 'remarkable-document';
+        }
+        // Fall through to normal extension checking for remarkable/index.md
+    }
+    if (['md', 'mdc'].includes(ext))
+        return 'markdown';
+    if (['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg'].includes(ext))
+        return 'image';
+    if (ext === 'pdf')
+        return 'pdf';
+    if (ext === 'mmd')
+        return 'mermaid';
+    // Text and data files - use code type for syntax highlighting (aligned with EditorColumn)
+    if (['txt', 'log', 'csv', 'json', 'xml', 'yml', 'yaml'].includes(ext))
+        return 'code';
+    // Code file extensions
+    const codeExtensions = ['py', 'js', 'ts', 'jsx', 'tsx', 'java', 'c', 'cpp', 'h', 'hpp', 'rs', 'go', 'rb', 'php', 'sh', 'bash', 'mjs', 'mts', 'zsh'];
+    if (codeExtensions.includes(ext))
+        return 'code';
+    return 'unknown';
+}

package/docs/annotations.md

@@ -0,0 +1,134 @@
+# Annotations
+
+An **annotation** is a range-anchored marker over document text whose anchor
+survives edits to the surrounding document.
+
+Comments and corrections are not separate features here. They are two *kinds*,
+differing only by the configuration record a host supplies. If you are building
+something that marks up a passage and hangs your own domain object off it, you
+are configuring a kind.
+
+## The seam
+
+The package owns anchor mechanics and marker rendering. Identity, storage and
+lifecycle stay in your application:
+
+- `id` is **opaque** to the package. You mint it and you persist it.
+- `payload` is **carried through untouched** and handed back on activation, so
+  you can round-trip your own domain object without the package understanding it.
+- Resolution outcomes are **computed by you** — via `resolveAnchors` or your own
+  store. The package never classifies on your behalf.
+
+## Turning it on
+
+Supplying `annotationKinds` is the switch. With it absent, no annotation module
+is loaded, no command is registered and nothing renders — the surface sits
+behind a `React.lazy()` boundary, so it is not in the chunk your app downloads.
+
+```tsx
+<Editor
+  initialContent={markdown}
+  onChange={setMarkdown}
+  annotationKinds={{
+    comment: {
+      markerStyle: 'highlight',
+      createAffordance: { surface: 'toolbar', label: 'Comment' },
+      retainMarkOnCreate: true,
+    },
+  }}
+  annotations={annotations}
+  activeAnnotationId={activeId}
+  onCreateAnnotation={handleCreate}
+  onActivateAnnotation={setActiveId}
+/>
+```
+
+### `AnnotationKindConfig`
+
+| Field | Type | Meaning |
+|---|---|---|
+| `markerStyle` | `'highlight' \| 'squiggle' \| 'none'` | How the kind paints. `none` places no visible marker at all — used by kinds that adopt the anchor model but render nothing themselves. |
+| `createAffordance` | `{ surface: 'toolbar' \| 'contextMenu', label?: string } \| null` | Where a user-initiated create action is offered. Omit or `null` for host-injected annotations only. |
+| `livemarkPolicy` | `(annotation) => boolean` | Whether an annotation gets a live `MarkNode` in the document. Defaults to `shouldPlaceLiveMark(outcome)`. Consulted only when `markerStyle` is not `none`. |
+| `retainMarkOnCreate` | `boolean` | Whether the transient capture mark stays after an anchor is captured. A composer that highlights the passage wants `true`; a kind that captures and dismisses wants `false`. |
+
+`AnnotationKindConfigs` is `Record<string, AnnotationKindConfig>`. Kind names are
+plain strings — the package has no closed set and gives no kind special status.
+
+### `Annotation`
+
+```ts
+interface Annotation<TPayload = unknown> {
+  id: string
+  kind: string
+  anchor: Anchor
+  outcome?: 'unchanged' | 're-attached' | 'flagged' | 'orphaned'   // default 'unchanged'
+  presentation?: { className?: string; label?: string }
+  payload?: TPayload
+}
+```
+
+## Anchors
+
+```ts
+import { captureAnchor, resolveAnchors, ANCHOR_SCHEMA } from '@liminis/editor/annotations'
+```
+
+This subpath is DOM-, React- and Lexical-free, so anchors can be captured,
+stored and resolved anywhere — a server, a worker, an Electron main process, a
+test with no DOM. (It does depend on `zod`, which is why it is a subpath of its
+own rather than part of `./markdown`.)
+
+### Capture
+
+```ts
+const anchor = captureAnchor(documentText, { start, end }, docVersion)
+```
+
+An anchor stores the quoted text plus `CONTEXT_WINDOW_CHARS` (40) of surrounding
+context on each side, along with structural context and the document version it
+was captured against. `ANCHOR_SCHEMA` and `ANCHOR_RESOLUTION_SCHEMA` are zod
+schemas for persisting them.
+
+### Resolution
+
+When the document changes, re-resolve:
+
+```ts
+const result = await resolveAnchors(anchors, newDocumentText, newDocumentVersion)
+```
+
+Each anchor lands in one of four outcomes:
+
+| Outcome | Meaning | Live mark placed? |
+|---|---|---|
+| `unchanged` | The exact range still matches | yes |
+| `re-attached` | Found at a new offset, similarity ≥ `REATTACH_THRESHOLD` (0.6) | yes |
+| `flagged` | A candidate exists but is uncertain, similarity ≥ `FLAG_THRESHOLD` (0.35) | no — panel only |
+| `orphaned` | Nothing matches | no — nothing left to point at |
+
+`flagged` and `orphaned` deliberately get no in-document mark: one would be
+pointing at text that may not be the right text, the other at nothing. Both stay
+visible in whatever panel your app renders. `shouldPlaceLiveMark(outcome)`
+encodes this, and `deriveMarkerTargets` applies it across a set.
+
+`resolveAnchor` handles a single anchor. `similarity(a, b)` is the scoring
+function, exported so you can reuse the same measure in your own UI.
+
+### Semantic relocation
+
+`resolveAnchors` accepts an optional `proposeSemanticRelocation` seam: an
+async function that gets a chance to relocate an anchor the textual matcher
+could not place — an LLM call, typically. `noopProposeSemanticRelocation` is the
+default and returns `null`, so nothing is relocated unless you opt in.
+
+## Marker styling
+
+Markers are styled by `@liminis/editor/styles.css` (the `annotation-mark-*`
+rules). **If you do not import that stylesheet, markers are invisible** — the
+mark nodes are placed in the document, they just have no appearance. Nothing
+errors. This is the single most likely reason "annotations don't work" for a new
+consumer.
+
+Per-annotation overrides go through `presentation.className`, which is applied
+to that annotation's marker element in addition to the kind's own class.

package/docs/decisions/README.md

@@ -0,0 +1,72 @@
+# Architectural Decision Records
+
+The decisions that govern this package. Each one is a **verbatim copy** of the
+record as it stood in `verveguy/liminis` at commit `34f0d828`, the point at which
+this package was extracted into its own repository (verveguy/liminis#995).
+
+| ADR | Title |
+|-----|-------|
+| [ADR-075](adr-075.md) | The `@liminis/editor` Package Boundary Is Drawn at Persistence |
+| [ADR-076](adr-076.md) | Markdown Serialization Is a Fixed Point, at the Cost of a One-Time Canonicalization |
+| [ADR-077](adr-077.md) | Comments and Corrections Are Two Kinds of One Annotation Mechanism |
+| [ADR-078](adr-078.md) | `@liminis/editor` Is Delivered by a Non-Bundling `tsc` Emit Behind `publishConfig` |
+| [ADR-079](adr-079.md) | A Seventh Export Subpath, `./nodes`, for the Headless Mapper |
+
+## Why these five, and why copies rather than moves
+
+These are the ADRs that the package's own source cites. ADR-075, ADR-077 and
+ADR-078 are cited from the host application as well, so removing them from
+`verveguy/liminis` would have left dangling citations *there*. ADR-076 and
+ADR-079 are package-only, but were copied rather than moved so that the source
+repository's decision index has no holes in its numbering.
+
+The duplication is deliberate and it is a known cost: two copies can diverge.
+Reconciling them is a single pass scheduled against a settled repository, as part
+of the eventual decision to make this repository public. Until then, treat the
+copies here as the record for questions about the package and the originals as
+the record for questions about the application.
+
+## Numbers cited inside these documents that are not in this table
+
+The bodies below cite other ADRs — ADR-002, 007, 008, 010, 012, 024, 025, 027,
+034, 042, 057, 070, 080. Those are decisions about the **host application**, not
+about this package, and they are not reproduced here; importing them would drag
+most of an unrelated decision index in behind them.
+
+They are not dangling. Every one of them resolves in the source repository, at
+`docs/project_notes/decisions/adr-0NNN.md` in `verveguy/liminis`.
+
+The documents are kept byte-identical to their originals rather than rewritten to
+remove those references. Rewriting them would fork the two copies on day one and
+make the reconciliation pass above a manual read instead of a `diff`. Where one
+of those application decisions was cited *by this package's own code*, the
+citation was removed and its reasoning inlined at the call site instead — see
+`docs/provenance.md`.
+
+## Cross-references to records that stayed behind
+
+These records were extracted from a larger decision log. Where one of them cites
+an ADR that is **not** in this directory, that record is a Liminis *application*
+decision — about the Electron shell, IPC, agent integration, the knowledge graph
+or settings persistence — which deliberately did not travel, because it does not
+govern this package.
+
+Currently referenced but not present:
+
+| cited | what it is | cited by |
+|---|---|---|
+| ADR-003 | Claude Agent SDK for AI integration | `adr-080` |
+| ADR-008 | MCP server integration with per-chat permissions | `adr-077`, `adr-080` |
+| ADR-012 | Component/BOM system for workspace tracking | `adr-077`, `adr-080` |
+| ADR-032 | Main process owns all state; renderer is reactive | `adr-080` |
+| ADR-034 | Claude Code configuration strategy | `adr-075` |
+| ADR-042 | Context graph concurrent read/write architecture | `adr-075`, `adr-077` |
+| ADR-055 | Atomic, serialized settings persistence | `adr-057` |
+
+Chasing these to closure would import most of an 81-record log describing an
+application this package does not depend on. The citations are left intact
+rather than edited out, so the records stay verbatim copies and the reasoning
+remains traceable for anyone who does have access to the Liminis repository.
+
+**No document outside `docs/decisions/` cites a missing record** — the package's
+own documentation (`README.md`, `docs/*.md`) is self-contained.

package/docs/decisions/adr-002.md

@@ -0,0 +1,27 @@
+# ADR-002: Lexical for Rich Text Editing (2026-01-25)
+
+**Context:**
+- Need a markdown editor with rich features (wikilinks, frontmatter, tables, math, mermaid)
+- Must support custom node types for specialized rendering
+- Performance matters for large documents
+- Need full control over editing behavior
+
+**Decision:**
+- Use Lexical (Meta's editor framework) as the foundation
+- Build custom nodes for: wikilinks, frontmatter, callouts, toggles, equations, mermaid diagrams, images
+- Implement bidirectional markdown conversion (mdast ↔ Lexical)
+- Use plugin architecture for features (slash menu, drag handles, shortcuts)
+
+**Alternatives Considered:**
+- ProseMirror → Rejected: steeper learning curve, more boilerplate
+- TipTap → Rejected: ProseMirror wrapper adds abstraction layer
+- Monaco Editor → Rejected: better for code, not rich markdown
+- ContentEditable directly → Rejected: too low-level, browser inconsistencies
+
+**Consequences:**
+- ✅ Extensible node system for custom markdown features
+- ✅ Good performance with large documents
+- ✅ Active development and community
+- ✅ Better control than contenteditable alternatives
+- ❌ Requires custom markdown parsing/serialization layer
+- ❌ Learning curve for Lexical's architecture