@liminis/editor 0.1.0-rc.1

package/dist/contract.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@liminis/editor/contract` — the host-message contract, and nothing else.
+ *
+ * A DOM- and React-free entry point so a preload script (or any other boundary
+ * that must not pull renderer code into its bundle) can `import type` the
+ * message shapes without dragging in Lexical.
+ */
+export * from './types.js';

package/dist/contract.js

@@ -0,0 +1,8 @@
+/**
+ * `@liminis/editor/contract` — the host-message contract, and nothing else.
+ *
+ * A DOM- and React-free entry point so a preload script (or any other boundary
+ * that must not pull renderer code into its bundle) can `import type` the
+ * message shapes without dragging in Lexical.
+ */
+export * from './types.js';

package/dist/headless.d.ts

@@ -0,0 +1,40 @@
+/**
+ * `@liminis/editor/headless` — the DOM-free surface.
+ *
+ * Consumed by the Electron **main** process, which declares `lib: ["ES2024"]`
+ * and no DOM libs. Nothing exported from here may reference a DOM global or
+ * transitively import Lexical, `react-dom` (client), or anything that touches
+ * `document`/`window`. `renderC4DiagramToSVG` uses `react-dom/server`, which is
+ * DOM-free; the MathJax *lite* adaptor is typed over `LiteElement`, not
+ * `HTMLElement`, which is why only the lite factory appears here.
+ *
+ * **Known exception, carried over unchanged: `./mathjax-config`.** Its
+ * `createLiteAdaptorDocument` export is DOM-free, but the module statically
+ * imports `browserAdaptor` alongside `liteAdaptor` at top level, so anything
+ * that loads this entry evaluates a DOM-adaptor module. That is *not* a
+ * regression introduced by the extraction — before it, `main/remote-session/
+ * routes.ts` imported `shared/mathjax-config` directly and pulled in the very
+ * same graph; main's runtime imports are byte-for-byte what they were. It is
+ * called out here because this entry's contract would otherwise read as
+ * stronger than it is. Splitting the module into lite and browser halves is the
+ * real fix and belongs with #940's build work, where the entry graphs get
+ * enforced rather than documented.
+ *
+ * **This contract is by convention, not by compiler enforcement.** Main's
+ * `lib: ["ES2024"]` does *not* currently make `Document`/`HTMLElement` unresolvable
+ * — some dependency already in `src/main`'s own graph pulls the DOM lib in (this
+ * predates the package extraction; `@types/node` alone does not do it). So a
+ * DOM-typed export added here would compile silently rather than failing main's
+ * typecheck. Widening this entry therefore requires reading the addition's import
+ * graph yourself. The fix for a violation is always to prune that graph, never to
+ * widen main's `lib`.
+ */
+export { renderC4DiagramToSVG } from './app/editor/c4/render-to-string.js';
+export { parseC4, validateC4 } from './app/editor/c4/parser.js';
+export { layoutC4Diagram } from './app/editor/c4/layout.js';
+export { isSystem, isContainer, isComponent, isPerson, isExternal, isBoundary, } from './app/editor/c4/types.js';
+export type { C4ElementType, C4Shape, C4Direction, C4Style, C4Properties, C4Element, C4Relationship, C4Diagram, Point, LayoutNode, LayoutEdge, LayoutResult, LayoutOptions, ParseError, ParseResult, ManualLayout, } from './app/editor/c4/types.js';
+export { createLiteAdaptorDocument, TEX_PACKAGES } from './mathjax-config.js';
+export type { TeXPackage, MathDocument, LiteMathJaxInstance } from './mathjax-config.js';
+export { getFileType } from './utils/file-types.js';
+export type { FileType } from './utils/file-types.js';

package/dist/headless.js

@@ -0,0 +1,45 @@
+/**
+ * `@liminis/editor/headless` — the DOM-free surface.
+ *
+ * Consumed by the Electron **main** process, which declares `lib: ["ES2024"]`
+ * and no DOM libs. Nothing exported from here may reference a DOM global or
+ * transitively import Lexical, `react-dom` (client), or anything that touches
+ * `document`/`window`. `renderC4DiagramToSVG` uses `react-dom/server`, which is
+ * DOM-free; the MathJax *lite* adaptor is typed over `LiteElement`, not
+ * `HTMLElement`, which is why only the lite factory appears here.
+ *
+ * **Known exception, carried over unchanged: `./mathjax-config`.** Its
+ * `createLiteAdaptorDocument` export is DOM-free, but the module statically
+ * imports `browserAdaptor` alongside `liteAdaptor` at top level, so anything
+ * that loads this entry evaluates a DOM-adaptor module. That is *not* a
+ * regression introduced by the extraction — before it, `main/remote-session/
+ * routes.ts` imported `shared/mathjax-config` directly and pulled in the very
+ * same graph; main's runtime imports are byte-for-byte what they were. It is
+ * called out here because this entry's contract would otherwise read as
+ * stronger than it is. Splitting the module into lite and browser halves is the
+ * real fix and belongs with #940's build work, where the entry graphs get
+ * enforced rather than documented.
+ *
+ * **This contract is by convention, not by compiler enforcement.** Main's
+ * `lib: ["ES2024"]` does *not* currently make `Document`/`HTMLElement` unresolvable
+ * — some dependency already in `src/main`'s own graph pulls the DOM lib in (this
+ * predates the package extraction; `@types/node` alone does not do it). So a
+ * DOM-typed export added here would compile silently rather than failing main's
+ * typecheck. Widening this entry therefore requires reading the addition's import
+ * graph yourself. The fix for a violation is always to prune that graph, never to
+ * widen main's `lib`.
+ */
+// C4 diagram subsystem — parse, layout, and server-side SVG rendering
+export { renderC4DiagramToSVG } from './app/editor/c4/render-to-string.js';
+export { parseC4, validateC4 } from './app/editor/c4/parser.js';
+export { layoutC4Diagram } from './app/editor/c4/layout.js';
+export { isSystem, isContainer, isComponent, isPerson, isExternal, isBoundary, } from './app/editor/c4/types.js';
+// MathJax lite-adaptor factory (equation rendering, server-side export).
+//
+// `createBrowserAdaptorDocument` / `BrowserMathJaxInstance` are deliberately NOT
+// re-exported here: they are typed over `Document` and `HTMLElement`, which would
+// contradict this entry's DOM-free contract. Their only consumer is
+// `EquationComponent.tsx` inside the package, which imports them directly.
+export { createLiteAdaptorDocument, TEX_PACKAGES } from './mathjax-config.js';
+// File-type detection, used by both the mdast mapper and app-side callers
+export { getFileType } from './utils/file-types.js';

package/dist/host/context.d.ts

@@ -0,0 +1,20 @@
+/**
+ * React context carrying the injected host services.
+ *
+ * Context rather than prop drilling: five separate mount sites in liminis-app
+ * plus ~20 deeply nested plugins would otherwise have to thread a services
+ * object through `App` → `Editor` → every plugin (see ADR-075).
+ */
+import { type ReactNode } from 'react';
+import type { EditorHostServices, ResolvedEditorHostServices } from './types.js';
+export interface EditorHostProviderProps {
+    /** Host services. Any omitted member falls back to a safe default. */
+    services?: EditorHostServices;
+    children: ReactNode;
+}
+export declare function EditorHostProvider({ services, children }: EditorHostProviderProps): import("react").JSX.Element;
+/**
+ * Access the host services. Usable without a provider — an absent provider
+ * yields the same all-defaults object a provider with no services would.
+ */
+export declare function useEditorHost(): ResolvedEditorHostServices;

package/dist/host/context.js

@@ -0,0 +1,24 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * React context carrying the injected host services.
+ *
+ * Context rather than prop drilling: five separate mount sites in liminis-app
+ * plus ~20 deeply nested plugins would otherwise have to thread a services
+ * object through `App` → `Editor` → every plugin (see ADR-075).
+ */
+import { createContext, useContext, useMemo } from 'react';
+import { resolveHostServices } from './defaults.js';
+const EditorHostContext = createContext(null);
+export function EditorHostProvider({ services, children }) {
+    const resolved = useMemo(() => resolveHostServices(services), [services]);
+    return _jsx(EditorHostContext.Provider, { value: resolved, children: children });
+}
+/**
+ * Access the host services. Usable without a provider — an absent provider
+ * yields the same all-defaults object a provider with no services would.
+ */
+export function useEditorHost() {
+    const value = useContext(EditorHostContext);
+    return value ?? FALLBACK_SERVICES;
+}
+const FALLBACK_SERVICES = resolveHostServices(undefined);

package/dist/host/defaults.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Safe defaults for every host service.
+ *
+ * FR-003 / US2-AC2: a host that supplies no logger, no bridge and no resolvers
+ * must still get a working `<Editor>`. Nothing here throws, and nothing here
+ * touches a global that only exists inside Electron.
+ */
+import type { EditorHostBridge, EditorHostServices, EditorLoggerFactory, ResolvedEditorHostServices } from './types.js';
+/** Console-backed logger namespaced the same way liminis-app's logger is. */
+export declare const defaultLoggerFactory: EditorLoggerFactory;
+/**
+ * Bridge that drops outbound messages and never delivers inbound ones.
+ *
+ * This is the correct standalone behaviour: with no host there is nothing to
+ * apply edits to, so the editor simply behaves as an uncontrolled component.
+ */
+export declare const noopBridge: EditorHostBridge;
+/** Last-resort error surface when the host provides no toast mechanism. */
+export declare const defaultNotifyError: (message: string, description?: string) => void;
+/** Fill in every unsupplied service with its safe default. */
+export declare function resolveHostServices(services: EditorHostServices | undefined): ResolvedEditorHostServices;

package/dist/host/defaults.js

@@ -0,0 +1,47 @@
+/**
+ * Safe defaults for every host service.
+ *
+ * FR-003 / US2-AC2: a host that supplies no logger, no bridge and no resolvers
+ * must still get a working `<Editor>`. Nothing here throws, and nothing here
+ * touches a global that only exists inside Electron.
+ */
+/** Console-backed logger namespaced the same way liminis-app's logger is. */
+export const defaultLoggerFactory = (namespace) => ({
+    debug: (...args) => console.debug(`[${namespace}]`, ...args),
+    info: (...args) => console.info(`[${namespace}]`, ...args),
+    warn: (...args) => console.warn(`[${namespace}]`, ...args),
+    error: (...args) => console.error(`[${namespace}]`, ...args),
+});
+/**
+ * Bridge that drops outbound messages and never delivers inbound ones.
+ *
+ * This is the correct standalone behaviour: with no host there is nothing to
+ * apply edits to, so the editor simply behaves as an uncontrolled component.
+ */
+export const noopBridge = {
+    postMessage: () => { },
+    addMessageHandler: () => () => { },
+};
+/** Last-resort error surface when the host provides no toast mechanism. */
+export const defaultNotifyError = (message, description) => {
+    if (description) {
+        console.error(message, description);
+    }
+    else {
+        console.error(message);
+    }
+};
+/** Fill in every unsupplied service with its safe default. */
+export function resolveHostServices(services) {
+    return {
+        bridge: services?.bridge ?? noopBridge,
+        logger: services?.logger ?? defaultLoggerFactory,
+        notifyError: services?.notifyError ?? defaultNotifyError,
+        // Left undefined on purpose when absent: the plugins that use these treat
+        // "service missing" as "feature unavailable, do nothing" — exactly what the
+        // pre-extraction host-API presence guards did.
+        resolveWikiLinks: services?.resolveWikiLinks,
+        onScrollToAnchor: services?.onScrollToAnchor,
+        corrections: services?.corrections,
+    };
+}

package/dist/host/messages.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Host message helpers, rebuilt on top of `EditorHostBridge.postMessage`.
+ *
+ * These used to live in `liminis-app/src/editor/messaging-electron.ts`. Keeping
+ * them package-side means every host adapter only has to implement
+ * `postMessage` + `addMessageHandler`, and the wire payloads are identical by
+ * construction rather than by convention.
+ */
+import type { TextEdit, UIToHostMessage } from '../types.js';
+import type { EditorHostBridge, EditorLogger } from './types.js';
+/**
+ * Members are declared as function-typed properties rather than methods on
+ * purpose: callers destructure them (`const { openLink } = useHostMessages()`),
+ * which the `unbound-method` lint rule rightly flags for real methods.
+ */
+export interface HostMessageApi {
+    postMessage: (message: UIToHostMessage) => void;
+    requestInit: () => void;
+    requestSettings: () => void;
+    applyTextEdits: (edits: TextEdit[], reason: 'typing' | 'drag' | 'paste' | 'format') => void;
+    writeAsset: (dataUri: string, suggestedName?: string) => void;
+    openLink: (url: string) => void;
+}
+export declare function createHostMessageApi(bridge: EditorHostBridge, log: EditorLogger): HostMessageApi;
+/** Hook form of {@link createHostMessageApi}, bound to the ambient host services. */
+export declare function useHostMessages(): HostMessageApi;

package/dist/host/messages.js

@@ -0,0 +1,47 @@
+/**
+ * Host message helpers, rebuilt on top of `EditorHostBridge.postMessage`.
+ *
+ * These used to live in `liminis-app/src/editor/messaging-electron.ts`. Keeping
+ * them package-side means every host adapter only has to implement
+ * `postMessage` + `addMessageHandler`, and the wire payloads are identical by
+ * construction rather than by convention.
+ */
+import { useMemo } from 'react';
+import { useEditorHost } from './context.js';
+export function createHostMessageApi(bridge, log) {
+    const postMessage = (message) => {
+        bridge.postMessage(message);
+    };
+    return {
+        postMessage,
+        requestInit: () => {
+            log.info('Requesting init from host');
+            postMessage({ type: 'REQUEST_INIT' });
+        },
+        requestSettings: () => {
+            postMessage({ type: 'REQUEST_SETTINGS' });
+        },
+        applyTextEdits: (edits, reason) => {
+            log.debug('applyTextEdits', {
+                reason,
+                edits: edits.map((e) => ({ start: e.start, end: e.end, newTextLen: e.newText.length })),
+            });
+            postMessage({ type: 'APPLY_TEXT_EDITS', edits, reason });
+        },
+        writeAsset: (dataUri, suggestedName) => {
+            postMessage({ type: 'WRITE_ASSET', dataUri, suggestedName });
+        },
+        openLink: (url) => {
+            log.debug('openLink', { url });
+            postMessage({ type: 'OPEN_LINK', url });
+        },
+    };
+}
+/** Hook form of {@link createHostMessageApi}, bound to the ambient host services. */
+export function useHostMessages() {
+    const { bridge, logger } = useEditorHost();
+    return useMemo(() => createHostMessageApi(bridge, makeLog(logger)), [bridge, logger]);
+}
+function makeLog(logger) {
+    return logger('slashmd/messaging');
+}

package/dist/host/types.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The host seam for `@liminis/editor`.
+ *
+ * The package boundary is drawn at **persistence**: anything about text ranges,
+ * marks, rendering and in-document UX lives in this package; storage, lifecycle,
+ * identity and higher-level panels live in the embedding application. Everything
+ * the package needs from its host crosses that seam through the interfaces below
+ * (see ADR-075).
+ *
+ * Every member is optional and has a safe default (see `./defaults.ts`), so
+ * `<Editor>` renders in a host that supplies nothing at all.
+ */
+import type { HostToUIMessage, UIToHostMessage } from '../types.js';
+/** Minimal logging surface. Structurally compatible with liminis-app's `Logger`. */
+export interface EditorLogger {
+    debug: (...args: unknown[]) => void;
+    info: (...args: unknown[]) => void;
+    warn: (...args: unknown[]) => void;
+    error: (...args: unknown[]) => void;
+}
+/** Factory producing a namespaced logger, e.g. `createLogger('slashmd/App')`. */
+export type EditorLoggerFactory = (namespace: string) => EditorLogger;
+/**
+ * The channel through which the package talks to its embedding environment.
+ *
+ * Deliberately two methods: all higher-level helpers (`requestInit`,
+ * `applyTextEdits`, `writeAsset`, `openLink`) are built on `postMessage`
+ * inside the package, so every host adapter emits byte-identical payloads.
+ */
+export interface EditorHostBridge {
+    postMessage(message: UIToHostMessage): void;
+    /** Subscribe to host → UI messages. Returns an unsubscribe function. */
+    addMessageHandler(handler: (message: HostToUIMessage) => void): () => void;
+}
+/**
+ * Persistence and knowledge-graph services backing the correction feature.
+ *
+ * The in-editor correction UI is package-side; reading and writing the
+ * corrections document and driving the knowledge tools stays host-side. That
+ * split is the package boundary drawn at persistence (`docs/decisions/adr-075.md`):
+ * this package renders and edits, and never decides where bytes live or which
+ * knowledge pipeline consumes them.
+ */
+export interface CorrectionHostServices {
+    /** Raw YAML text of the corrections file, or `null` when it does not exist. */
+    readCorrections(): Promise<string | null>;
+    /** Persist the corrections file. The host owns mkdir and atomic-write semantics. */
+    writeCorrections(yaml: string): Promise<void>;
+    /** Entity-name suggestions for an autocomplete query. */
+    suggestEntities(query: string, numResults: number): Promise<string[]>;
+    /** Passage/source-name suggestions for an autocomplete query. */
+    suggestPassages(query: string, numResults: number, minScore: number): Promise<string[]>;
+    /** Apply pending corrections to the knowledge graph. Resolves true on success. */
+    applyCorrections(): Promise<boolean>;
+}
+/** Everything the package may ask of its host. */
+export interface EditorHostServices {
+    /** Host message channel (Electron IPC in liminis-app). */
+    bridge?: EditorHostBridge;
+    /** Namespaced logger factory. */
+    logger?: EditorLoggerFactory;
+    /**
+     * Resolve wiki-link targets to existing paths. Returns a map of target →
+     * resolved path, or `null` for targets that do not resolve.
+     */
+    resolveWikiLinks?: (targets: string[]) => Promise<Record<string, string | null>>;
+    /** Subscribe to host-driven "scroll to this anchor" requests. */
+    onScrollToAnchor?: (callback: (anchor: string) => void) => () => void;
+    /** Surface a user-visible error (a toast in liminis-app). */
+    notifyError?: (message: string, description?: string) => void;
+    /** Correction persistence + knowledge-graph services. */
+    corrections?: CorrectionHostServices;
+}
+/** `EditorHostServices` with every member resolved to a concrete implementation. */
+export type ResolvedEditorHostServices = Required<Pick<EditorHostServices, 'bridge' | 'logger' | 'notifyError'>> & Pick<EditorHostServices, 'resolveWikiLinks' | 'onScrollToAnchor' | 'corrections'>;

package/dist/host/types.js

@@ -0,0 +1,13 @@
+/**
+ * The host seam for `@liminis/editor`.
+ *
+ * The package boundary is drawn at **persistence**: anything about text ranges,
+ * marks, rendering and in-document UX lives in this package; storage, lifecycle,
+ * identity and higher-level panels live in the embedding application. Everything
+ * the package needs from its host crosses that seam through the interfaces below
+ * (see ADR-075).
+ *
+ * Every member is optional and has a safe default (see `./defaults.ts`), so
+ * `<Editor>` renders in a host that supplies nothing at all.
+ */
+export {};

package/dist/index.d.ts

@@ -0,0 +1,35 @@
+/**
+ * `@liminis/editor` — the curated public entry point.
+ *
+ * Consumers import from here (or from one of the other three declared
+ * subpaths: `./headless`, `./contract`, `./styles.css`) and never from a deep
+ * path into package internals (FR-002 / SC-002). If a consumer needs something
+ * that is not exported here, the answer is to add a considered export — never a
+ * deep import, and never a re-exported internals barrel.
+ */
+export { EditorHostProvider, useEditorHost } from './host/context.js';
+export type { EditorHostProviderProps } from './host/context.js';
+export { resolveHostServices, defaultLoggerFactory, defaultNotifyError, noopBridge, } from './host/defaults.js';
+export { createHostMessageApi, useHostMessages } from './host/messages.js';
+export type { HostMessageApi } from './host/messages.js';
+export type { CorrectionHostServices, EditorHostBridge, EditorHostServices, EditorLogger, EditorLoggerFactory, ResolvedEditorHostServices, } from './host/types.js';
+export { App } from './app/App.js';
+export type { CursorState } from './app/App.js';
+export { Editor } from './app/editor/index.js';
+export type { SweepFn } from './app/editor/AmbientCorrectionPlugin.js';
+export type { SelectionContextMenuEvent } from './app/editor/SelectionContextMenuPlugin.js';
+export { OPEN_ANNOTATION_COMPOSER_COMMAND } from './app/editor/annotationCommands.js';
+export type { AnnotationCreateEvent } from './app/editor/AnnotationPlugin.js';
+export type { Annotation, AnnotationKind, AnnotationKindConfig, AnnotationKindConfigs, AnnotationCreateAffordance, AnnotationMarkerStyle, AnnotationPresentation, AnnotationEditorHandle, MarkerTarget, } from './annotations/types.js';
+export { parseMarkdown } from './markdown/parse.js';
+export type { ParseOptions, ParseResult } from './markdown/parse.js';
+export { isParagraph, isHeading, isList, isListItem, isBlockquote, isCode, isThematicBreak, isTable, isImage, isLink, isHtml, isText, isStrong, isEmphasis, isInlineCode, isDelete, } from './markdown/parse.js';
+export { stringifyMarkdown } from './markdown/stringify.js';
+export type { StringifyOptions } from './markdown/stringify.js';
+export { importMarkdownToLexical, exportLexicalToMdast } from './app/mapper/index.js';
+export type { ExportOptions, WikiLinkPromotionMode } from './app/mapper/index.js';
+export * from './types.js';
+export { useEditorStore } from './stores/editorStore.js';
+export { findSvgElement } from './app/editor/nodes/diagram-utils.js';
+export * from './headless.js';
+export type { ParseResult as C4ParseResult, ParseError as C4ParseError, } from './app/editor/c4/types.js';

package/dist/index.js

@@ -0,0 +1,51 @@
+/**
+ * `@liminis/editor` — the curated public entry point.
+ *
+ * Consumers import from here (or from one of the other three declared
+ * subpaths: `./headless`, `./contract`, `./styles.css`) and never from a deep
+ * path into package internals (FR-002 / SC-002). If a consumer needs something
+ * that is not exported here, the answer is to add a considered export — never a
+ * deep import, and never a re-exported internals barrel.
+ */
+// --- Host seam -------------------------------------------------------------
+// Injected services are how the package reaches its embedding environment.
+export { EditorHostProvider, useEditorHost } from './host/context.js';
+export { resolveHostServices, defaultLoggerFactory, defaultNotifyError, noopBridge, } from './host/defaults.js';
+export { createHostMessageApi, useHostMessages } from './host/messages.js';
+// --- Components ------------------------------------------------------------
+export { App } from './app/App.js';
+export { Editor } from './app/editor/index.js';
+// --- Annotations, React surface (ADR-077) ---------------------------------
+// The kind-configuration types a host needs to turn the mechanism on, plus the
+// create-event shape. The DOM-free anchor model, resolver and marker-target
+// helpers live on the `./annotations` subpath instead, so they stay callable
+// outside a rendered editor.
+export { OPEN_ANNOTATION_COMPOSER_COMMAND } from './app/editor/annotationCommands.js';
+// --- Markdown pipeline -----------------------------------------------------
+export { parseMarkdown } from './markdown/parse.js';
+export { isParagraph, isHeading, isList, isListItem, isBlockquote, isCode, isThematicBreak, isTable, isImage, isLink, isHtml, isText, isStrong, isEmphasis, isInlineCode, isDelete, } from './markdown/parse.js';
+export { stringifyMarkdown } from './markdown/stringify.js';
+export { importMarkdownToLexical, exportLexicalToMdast } from './app/mapper/index.js';
+// --- Host message contract -------------------------------------------------
+export * from './types.js';
+// --- Editor-owned stores ---------------------------------------------------
+// `useEditorStore` is public: `EditorColumn` drives the frontmatter tray from
+// the app toolbar.
+//
+// `useCorrectionStore` is deliberately NOT exported. ADR-075 justifies keeping
+// it package-side on the grounds that it has no consumer outside the two
+// editor plugins; publishing it would invite exactly the app-side consumer that
+// invalidates that reasoning, with nothing at the boundary to catch it.
+export { useEditorStore } from './stores/editorStore.js';
+// --- Utilities the host also needs ----------------------------------------
+export { findSvgElement } from './app/editor/nodes/diagram-utils.js';
+// --- DOM-free surface, re-exported for renderer-side convenience ----------
+// Renderer consumers may import these from here; the Electron main process must
+// use '@liminis/editor/headless' instead (it has no DOM libs).
+//
+// NOTE: `./headless` also exports a `ParseResult` (the C4 parser's `{diagram,
+// errors}`), which this entry's explicit markdown `ParseResult` above shadows —
+// explicit exports win over `export *` in both ES and TypeScript. The C4 shape is
+// therefore reachable from here only under the alias below. `./headless` itself
+// exports it unaliased, where there is no collision.
+export * from './headless.js';

package/dist/markdown/annotate-sentinels.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The Unicode Private-Use-Area sentinel tokens annotated-serialize mode
+ * brackets a live annotation mark's content with, plus the one helper that
+ * removes them again.
+ *
+ * They live here — below both the mapper and the stringifier — because the
+ * *invariant* they exist to serve reaches into both. Annotate mode must differ
+ * from a plain export by the tokens and nothing else (see
+ * `lexicalToMdast.ts`'s annotated-serialize header): the whole recovered-range
+ * calculation in `annotation-marks.ts` is offset arithmetic against a plain
+ * export of the same state. So every *decision* either module makes from a
+ * piece of text — "does this list item already carry an explicit `[ ]`
+ * marker?", "does this paragraph end in a colon?" — has to be made against the
+ * sentinel-free form, or enabling annotate mode changes output somewhere the
+ * caller never looks (Liminis #970).
+ */
+export declare const SENTINEL_OPEN_START = "\uE000";
+export declare const SENTINEL_OPEN_END = "\uE001";
+export declare const SENTINEL_CLOSE_START = "\uE002";
+export declare const SENTINEL_CLOSE_END = "\uE003";
+/**
+ * `text` with every annotate-mode sentinel token removed. A no-op — and cheap
+ * — for the overwhelmingly common case of a string that contains none, which
+ * is every string on the disk-write path.
+ */
+export declare function stripAnnotateSentinels(text: string): string;
+export interface SentinelSplitPart {
+    text: string;
+    isSentinel: boolean;
+}
+/**
+ * Split `text` into alternating sentinel-token and plain-text parts.
+ *
+ * Used by `stringify.ts`'s force-escape handling (#17): a force-escaped
+ * text node's `getTextContent()` can have a sentinel token spliced onto
+ * either end by `sentinelAugmentedText` (annotate-serialize mode, see the
+ * module doc comment above) before the force-escape data is read, so
+ * treating the whole string as "one force-escaped run" would wrap the
+ * token's own characters in escape placeholders too. Splitting first lets
+ * the caller escape only the real content and leave token parts verbatim.
+ */
+export declare function splitOnSentinelTokens(text: string): SentinelSplitPart[];

package/dist/markdown/annotate-sentinels.js

@@ -0,0 +1,86 @@
+/**
+ * The Unicode Private-Use-Area sentinel tokens annotated-serialize mode
+ * brackets a live annotation mark's content with, plus the one helper that
+ * removes them again.
+ *
+ * They live here — below both the mapper and the stringifier — because the
+ * *invariant* they exist to serve reaches into both. Annotate mode must differ
+ * from a plain export by the tokens and nothing else (see
+ * `lexicalToMdast.ts`'s annotated-serialize header): the whole recovered-range
+ * calculation in `annotation-marks.ts` is offset arithmetic against a plain
+ * export of the same state. So every *decision* either module makes from a
+ * piece of text — "does this list item already carry an explicit `[ ]`
+ * marker?", "does this paragraph end in a colon?" — has to be made against the
+ * sentinel-free form, or enabling annotate mode changes output somewhere the
+ * caller never looks (Liminis #970).
+ */
+export const SENTINEL_OPEN_START = '\u{E000}';
+export const SENTINEL_OPEN_END = '\u{E001}';
+export const SENTINEL_CLOSE_START = '\u{E002}';
+export const SENTINEL_CLOSE_END = '\u{E003}';
+/**
+ * Matches one whole sentinel token — an open pair or a close pair, with an
+ * annotation id between them.
+ *
+ * Two things keep this from eating real content, and both are load-bearing:
+ *
+ * 1. **The id is a negated character class** excluding all four delimiters, so
+ *    the run cannot cross a delimiter and the match is forced to end at the
+ *    first one it meets. Greediness is irrelevant for that reason — do not
+ *    "simplify" this to `.*?`. A lazy dot matches delimiters happily, so on
+ *    `…␀b␀id␁…` it would span from the *stray* opener to the first closer and
+ *    delete the real text `b` along with the token.
+ * 2. **Each alternative pairs its own delimiters** — open-with-open,
+ *    close-with-close. Choosing the two ends from independent classes would
+ *    also match an open *paired with a close*, which the emitters never
+ *    produce (see `openToken`/`closeToken` in `lexicalToMdast.ts`); on
+ *    `…␀real text␃…` that mismatched span would be deleted, taking the real
+ *    text with it. Only well-formed tokens should ever be removed, because
+ *    this function feeds *decisions* — the explicit task-marker test and the
+ *    ends-with-a-colon join rule — where a wrong strip silently changes
+ *    output.
+ */
+const SENTINEL_ID_RUN = `[^${SENTINEL_OPEN_START}${SENTINEL_OPEN_END}${SENTINEL_CLOSE_START}${SENTINEL_CLOSE_END}]*`;
+const SENTINEL_TOKEN = new RegExp(`${SENTINEL_OPEN_START}${SENTINEL_ID_RUN}${SENTINEL_OPEN_END}` +
+    `|${SENTINEL_CLOSE_START}${SENTINEL_ID_RUN}${SENTINEL_CLOSE_END}`, 'gu');
+/**
+ * `text` with every annotate-mode sentinel token removed. A no-op — and cheap
+ * — for the overwhelmingly common case of a string that contains none, which
+ * is every string on the disk-write path.
+ */
+export function stripAnnotateSentinels(text) {
+    if (!text.includes(SENTINEL_OPEN_START) && !text.includes(SENTINEL_CLOSE_START))
+        return text;
+    return text.replace(SENTINEL_TOKEN, '');
+}
+/**
+ * Split `text` into alternating sentinel-token and plain-text parts.
+ *
+ * Used by `stringify.ts`'s force-escape handling (#17): a force-escaped
+ * text node's `getTextContent()` can have a sentinel token spliced onto
+ * either end by `sentinelAugmentedText` (annotate-serialize mode, see the
+ * module doc comment above) before the force-escape data is read, so
+ * treating the whole string as "one force-escaped run" would wrap the
+ * token's own characters in escape placeholders too. Splitting first lets
+ * the caller escape only the real content and leave token parts verbatim.
+ */
+export function splitOnSentinelTokens(text) {
+    if (!text.includes(SENTINEL_OPEN_START) && !text.includes(SENTINEL_CLOSE_START)) {
+        return [{ text, isSentinel: false }];
+    }
+    const parts = [];
+    let cursor = 0;
+    SENTINEL_TOKEN.lastIndex = 0;
+    let match;
+    while ((match = SENTINEL_TOKEN.exec(text)) !== null) {
+        if (match.index > cursor) {
+            parts.push({ text: text.slice(cursor, match.index), isSentinel: false });
+        }
+        parts.push({ text: match[0], isSentinel: true });
+        cursor = match.index + match[0].length;
+    }
+    if (cursor < text.length) {
+        parts.push({ text: text.slice(cursor), isSentinel: false });
+    }
+    return parts;
+}