@xenosystem/blocks 0.20.0 → 0.22.0

package/dist/docs/core.d.ts

@@ -0,0 +1,300 @@
+import { XenoDocNode } from './format.js';
+export { DOCUMENT_MARK_TYPES, DOCUMENT_NODE_TYPES, JSONContent, LIMITS, SAFE_IMAGE, SAFE_LINK, ValidateOptions, XDOC_EXTENSION, XDOC_FORMAT, XDOC_VERSION, XdocError, XenoDocFile, XenoDocMark, XenoDocProblem, documentToMarkdown, emptyContent, markdownToDocument, nodeTypesIn, pageLinksIn, parseXdoc, plainText, serializeXdoc, validateContent, wordCount } from './format.js';
+import * as _tiptap_core from '@tiptap/core';
+import { Node, Mark, AnyExtension, Editor } from '@tiptap/core';
+import * as _tiptap_extension_image from '@tiptap/extension-image';
+
+/**
+ * Callout block extension for TipTap
+ * Renders info/warning/error/success/tip callout blocks with colored left border
+ * Pattern: Notion-style callout blocks
+ */
+
+type CalloutType = 'info' | 'warning' | 'error' | 'success' | 'tip';
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        callout: {
+            setCallout: (attrs?: {
+                type?: CalloutType;
+            }) => ReturnType;
+            toggleCallout: (attrs?: {
+                type?: CalloutType;
+            }) => ReturnType;
+        };
+    }
+}
+declare const Callout: Node<any, any>;
+
+/**
+ * Toggle (collapsible) block extension for TipTap
+ * Renders a summary/details-style collapsible content block
+ * Pattern: Notion toggle blocks
+ */
+
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        toggleBlock: {
+            setToggleBlock: () => ReturnType;
+        };
+    }
+}
+declare const ToggleBlock: Node<any, any>;
+
+/**
+ * Page break extension for TipTap
+ * Inserts a page break that translates to a real page break in PDF/DOCX export.
+ *
+ * Pattern: Google Docs page break (Ctrl+Enter)
+ *
+ * MOVED from xeno-docs `src/renderer/src/extensions/PageBreak.ts` (2026-10-23). The node is identical
+ * (`pageBreak`, `div[data-page-break]`); what changed is that it no longer paints itself — the old
+ * file carried its own dashed rule colours and label size inline, which a block may not
+ * (`test/no-visual-value.test.ts`). The host styles `.page-break` and its two `.page-break-rule`
+ * halves; `page-break-after: always` stays, because that is print behaviour, not chrome.
+ */
+
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        pageBreak: {
+            /** Insert a page break at the current cursor position */
+            setPageBreak: () => ReturnType;
+        };
+    }
+}
+declare const PageBreak: Node<any, any>;
+
+/**
+ * TipTap extension for bi-directional [[wiki links]].
+ *
+ * Implements:
+ * - Inline mark that renders [[target]] or [[target|alias]] as clickable links
+ * - Input rule: typing [[ triggers the link creation
+ * - The mark stores pageId and pageTitle for resolution
+ *
+ * Approach: Custom TipTap Mark extension (similar to how Obsidian handles it).
+ * The mark wraps the display text and stores metadata in attrs.
+ */
+
+interface WikiLinkOptions {
+    /** Callback when a wiki link is clicked */
+    onClickLink: (pageId: string, pageTitle: string) => void;
+    /** HTML attributes for the link element */
+    HTMLAttributes: Record<string, unknown>;
+}
+declare module '@tiptap/core' {
+    interface Commands<ReturnType> {
+        wikiLink: {
+            setWikiLink: (attrs: {
+                pageId: string;
+                pageTitle: string;
+            }) => ReturnType;
+            unsetWikiLink: () => ReturnType;
+        };
+    }
+}
+declare const WikiLinkMark: Mark<WikiLinkOptions, any>;
+
+/**
+ * The image node, refusing at PARSE time any source the format refuses — so a pasted image whose
+ * source is a script URL or a tracking pixel over http never enters the document, instead of
+ * entering it and making the next save fail.
+ */
+declare const SafeImage: _tiptap_core.Node<_tiptap_extension_image.ImageOptions, any>;
+/** Options for {@link createDocumentExtensions}. */
+interface DocumentExtensionOptions {
+    /** The empty-editor hint. */
+    placeholder?: string;
+    /** `false` when a collaboration extension owns undo (Y.js brings its own history). */
+    history?: boolean;
+    /**
+     * The code-block extension. Default: StarterKit's plain `codeBlock`. XENO Docs passes
+     * `CodeBlockLowlight` for highlighting — same node name, same JSON.
+     */
+    codeBlock?: AnyExtension;
+    /** Called when a page link (`wikiLink`) is clicked — the host navigates; the editor never does. */
+    onOpenPage?: (pageId: string, pageTitle: string) => void;
+    /** Table column resizing (on in XENO Docs). */
+    resizableTables?: boolean;
+}
+/**
+ * The shared extension list. Order matters only for priority, and it is the order XENO Docs has
+ * always used.
+ */
+declare function createDocumentExtensions(options?: DocumentExtensionOptions): AnyExtension[];
+
+/**
+ * The document block's CONTROLLER — framework-free state over one open document.
+ *
+ * It never saves, never navigates and never fetches: it emits INTENTS (`save`, `openPage`, `dirty`)
+ * and the host performs them, then reports back with {@link DocumentController.saved} or
+ * {@link DocumentController.setStatus}. The editing itself is TipTap's, bound through
+ * {@link DocumentEditorHandle} by `./surface`, so this file imports no editor and runs in a test.
+ *
+ * @module
+ */
+
+/** What the host hands the block: one document, as the host stored it. */
+interface XenoDocumentInput {
+    /** The host's stable id for the document (the platform: its Storage file id). */
+    id: string;
+    /** The host's id for THIS version — round-tripped as `expectedVersion` so a stale save is refused. */
+    versionId?: string;
+    title: string;
+    /** A `.xdoc` file (text or parsed) — or bare content, for a host that keeps the envelope itself. */
+    xdoc?: string | unknown;
+    content?: XenoDocNode;
+    readOnly?: boolean;
+    created?: number;
+}
+/** The `save` intent: everything the host needs to write the next version. */
+interface XenoDocumentSave {
+    id: string;
+    expectedVersion?: string;
+    title: string;
+    /** The `.xdoc` text, validated — the host stores these bytes. */
+    xdoc: string;
+    content: XenoDocNode;
+    text: string;
+    pageLinks: string[];
+}
+/** The `openPage` intent: a page link was followed. */
+interface XenoDocumentOpenPage {
+    pageId: string;
+    pageTitle: string;
+}
+/** Where the open document stands. */
+type XenoDocumentStatus = 'empty' | 'ready' | 'saving' | 'saved' | 'conflict' | 'failed' | 'unsupported';
+/** The controller's state, for a view. */
+interface DocumentState {
+    id: string | null;
+    versionId: string | null;
+    title: string;
+    readOnly: boolean;
+    /** True when the document contains a block this schema cannot render — it opens read-only. */
+    unsupported: string[];
+    dirty: boolean;
+    status: XenoDocumentStatus;
+    message: string | null;
+    content: XenoDocNode;
+    revision: number;
+}
+/** The slice of a TipTap `Editor` the controller drives. `./surface` supplies the real one. */
+interface DocumentEditorHandle {
+    getJSON(): XenoDocNode;
+    setContent(content: XenoDocNode): void;
+    setEditable(editable: boolean): void;
+    focus(): void;
+    run(command: DocumentFormatCommand, arg?: unknown): boolean;
+    isActive(command: DocumentFormatCommand): boolean;
+    insertText(text: string): void;
+    insertPageLink(pageId: string, pageTitle: string, label?: string): void;
+}
+/** Every format command the toolbar, a keyboard or an agent can ask for. */
+declare const DOCUMENT_FORMAT_COMMANDS: readonly ["paragraph", "h1", "h2", "h3", "bold", "italic", "underline", "strike", "code", "highlight", "bulletList", "orderedList", "taskList", "blockquote", "codeBlock", "callout", "toggle", "pageBreak", "horizontalRule", "link", "unlink", "undo", "redo"];
+type DocumentFormatCommand = (typeof DOCUMENT_FORMAT_COMMANDS)[number];
+/** The host side the controller talks to. */
+interface DocumentHostBridge {
+    emit(portId: 'save' | 'openPage' | 'dirty', value: unknown): void;
+}
+interface DocumentControllerOptions {
+    host: DocumentHostBridge;
+}
+/** The toolbar, in order: what XENO Docs' own toolbar leads with. */
+declare const DOCUMENT_TOOLBAR: readonly {
+    command: DocumentFormatCommand;
+    label: string;
+}[];
+/** The controller. One per mounted document block. */
+declare class DocumentController {
+    private readonly host;
+    private state;
+    private created;
+    /** XENO Docs' comment threads, carried through a save untouched (this block does not edit comments). */
+    private commentThreads;
+    private editor;
+    private listeners;
+    constructor(options: DocumentControllerOptions);
+    /** Subscribe to state changes (a view re-renders on each). */
+    subscribe(fn: () => void): () => void;
+    getState(): DocumentState;
+    private set;
+    /**
+     * Open a document. A file the shared schema cannot render is NOT coerced: it opens read-only with
+     * the unknown types listed, so nothing the user wrote elsewhere is lost on a save here.
+     */
+    load(input: XenoDocumentInput): void;
+    /** Bind the live editor (`./surface` does this). Returns the unbind. */
+    attach(editor: DocumentEditorHandle): () => void;
+    hasEditor(): boolean;
+    /** The editor reported an edit. */
+    contentChanged(): void;
+    /** The cursor moved: a view re-reads which format commands are active. No state changes. */
+    selectionChanged(): void;
+    setTitle(title: string): void;
+    /** The content as it stands — the live editor's when bound. */
+    currentContent(): XenoDocNode;
+    /** Run a format command against the live editor. */
+    format(command: DocumentFormatCommand, arg?: unknown): boolean;
+    isActive(command: DocumentFormatCommand): boolean;
+    insertText(text: string): boolean;
+    insertPageLink(pageId: string, pageTitle: string, label?: string): boolean;
+    /** A page link was clicked — the host navigates. */
+    openPage(pageId: string, pageTitle: string): void;
+    /** The `.xdoc` for the document as it stands. Throws {@link XdocError} if it would not validate. */
+    toXdoc(): string;
+    /** Ask the host to save. Refused (false) when read-only, when nothing is open, or mid-save. */
+    save(): boolean;
+    /** The host saved: adopt its new version id. */
+    saved(versionId?: string): void;
+    /** The host reports an outcome that is not success (`conflict`, `failed`) or a message. */
+    setStatus(status: XenoDocumentStatus, message?: string): void;
+    /** What an agent reads. The status travels with the words so "empty" is never a guess. */
+    describe(): {
+        id: string | null;
+        title: string;
+        status: XenoDocumentStatus;
+        readOnly: boolean;
+        dirty: boolean;
+        text: string;
+        wordCount: number;
+        pageLinks: string[];
+        unsupported: string[];
+    };
+    serialize(): unknown;
+    deserialize(_state: unknown): void;
+    dispose(): void;
+}
+
+/**
+ * The document SURFACE — XENO Docs' editor (TipTap over the shared schema) mounted into one element,
+ * framework-free. The React view mounts this; so does a host that draws its own chrome (the platform
+ * workspace), which is why it needs no React.
+ *
+ * The element is the editor's: ProseMirror owns its DOM, and builds it ONLY from the schema's
+ * `renderHTML` specs. Nothing a document carries is ever assigned as HTML.
+ *
+ * @module
+ */
+
+/** Options for {@link mountDocumentSurface}. */
+interface DocumentSurfaceOptions extends Omit<DocumentExtensionOptions, 'onOpenPage'> {
+    /** A product's own extensions, appended to the shared set (XENO Docs: math, mermaid…). */
+    extensions?: AnyExtension[];
+    /** Called for a link the user asks to set (`format('link')` with no href). Return the address. */
+    promptLink?: (current: string | null) => string | null;
+    /** Class names for the editable element — the host's typography, never the block's. */
+    editorClass?: string;
+    /** Accessible name for the text area. */
+    label?: string;
+}
+/** Run one format command on a TipTap editor. Exported so XENO Docs' toolbar uses the SAME map. */
+declare function runFormat(editor: Editor, command: DocumentFormatCommand, arg?: unknown, promptLink?: DocumentSurfaceOptions['promptLink']): boolean;
+/** A {@link DocumentEditorHandle} over a TipTap editor. */
+declare function editorHandle(editor: Editor, promptLink?: DocumentSurfaceOptions['promptLink']): DocumentEditorHandle;
+/**
+ * Mount the editor into `element` and bind it to `controller`. Returns the teardown, which destroys
+ * the editor — call it before the element is removed.
+ */
+declare function mountDocumentSurface(element: HTMLElement, controller: DocumentController, options?: DocumentSurfaceOptions): () => void;
+
+export { Callout, type CalloutType, DOCUMENT_FORMAT_COMMANDS, DOCUMENT_TOOLBAR, DocumentController, type DocumentControllerOptions, type DocumentEditorHandle, type DocumentExtensionOptions, type DocumentFormatCommand, type DocumentHostBridge, type DocumentState, type DocumentSurfaceOptions, PageBreak, SafeImage, ToggleBlock, WikiLinkMark, type WikiLinkOptions, XenoDocNode, type XenoDocumentInput, type XenoDocumentOpenPage, type XenoDocumentSave, type XenoDocumentStatus, createDocumentExtensions, editorHandle, mountDocumentSurface, runFormat };

package/dist/docs/core.js

@@ -0,0 +1,70 @@
+import {
+  Callout,
+  DOCUMENT_FORMAT_COMMANDS,
+  DOCUMENT_TOOLBAR,
+  DocumentController,
+  PageBreak,
+  SafeImage,
+  ToggleBlock,
+  WikiLinkMark,
+  createDocumentExtensions,
+  editorHandle,
+  mountDocumentSurface,
+  runFormat
+} from "../chunk-5VOA3OSG.js";
+import "../chunk-HDP35LGH.js";
+import {
+  DOCUMENT_MARK_TYPES,
+  DOCUMENT_NODE_TYPES,
+  LIMITS,
+  SAFE_IMAGE,
+  SAFE_LINK,
+  XDOC_EXTENSION,
+  XDOC_FORMAT,
+  XDOC_VERSION,
+  XdocError,
+  documentToMarkdown,
+  emptyContent,
+  markdownToDocument,
+  nodeTypesIn,
+  pageLinksIn,
+  parseXdoc,
+  plainText,
+  serializeXdoc,
+  validateContent,
+  wordCount
+} from "../chunk-NFOBZJDF.js";
+import "../chunk-2KG3PWR4.js";
+export {
+  Callout,
+  DOCUMENT_FORMAT_COMMANDS,
+  DOCUMENT_MARK_TYPES,
+  DOCUMENT_NODE_TYPES,
+  DOCUMENT_TOOLBAR,
+  DocumentController,
+  LIMITS,
+  PageBreak,
+  SAFE_IMAGE,
+  SAFE_LINK,
+  SafeImage,
+  ToggleBlock,
+  WikiLinkMark,
+  XDOC_EXTENSION,
+  XDOC_FORMAT,
+  XDOC_VERSION,
+  XdocError,
+  createDocumentExtensions,
+  documentToMarkdown,
+  editorHandle,
+  emptyContent,
+  markdownToDocument,
+  mountDocumentSurface,
+  nodeTypesIn,
+  pageLinksIn,
+  parseXdoc,
+  plainText,
+  runFormat,
+  serializeXdoc,
+  validateContent,
+  wordCount
+};

package/dist/docs/format.d.ts

@@ -0,0 +1,145 @@
+/**
+ * The XENO document FORMAT — `.xdoc`, XENO Docs' native file, now the one format every surface that
+ * edits a document reads and writes (XENO Docs, XENO Notes' link mark, the platform workspace's
+ * Write and Notes).
+ *
+ * A `.xdoc` is JSON: an envelope around a ProseMirror document (`content`, the TipTap `getJSON()`
+ * shape). It is NOT HTML and is never rendered as HTML: a surface turns `content` into DOM through
+ * the schema in `./schema`, which only knows the node and mark types listed here. That is the whole
+ * XSS argument, and this module is what keeps it true at every boundary that accepts a file:
+ *
+ *   - every node / mark type must be one of {@link DOCUMENT_NODE_TYPES} / {@link DOCUMENT_MARK_TYPES}
+ *     (a product may widen the set for ITS OWN extensions with `extraNodes` / `extraMarks`);
+ *   - every attribute is checked against the type's own rule — a link's `href` must be http(s) or
+ *     mailto, an image's `src` https or a raster `data:` image, a page link's id a UUID;
+ *   - depth and node count are bounded.
+ *
+ * {@link validateContent} reports what it refused instead of dropping it: a server refuses the file,
+ * a surface opens it read-only. Silently dropping an unknown block would lose the user's words on the
+ * next save — the same outcome as a bug, with a better excuse.
+ *
+ * This module imports nothing (no TipTap, no DOM), so a server, a migration script or a test can use
+ * it without an editor.
+ *
+ * @module
+ */
+/** The `format` field every `.xdoc` written from now on carries. */
+declare const XDOC_FORMAT = "xeno.xdoc";
+/** The current envelope version. */
+declare const XDOC_VERSION = 1;
+/** The file extension XENO Docs ships (`DocumentEditor.tsx` — `${title}.xdoc`). */
+declare const XDOC_EXTENSION = ".xdoc";
+/** One ProseMirror node, as TipTap's `getJSON()` writes it. */
+interface XenoDocNode {
+    type: string;
+    attrs?: Record<string, unknown>;
+    content?: XenoDocNode[];
+    marks?: XenoDocMark[];
+    text?: string;
+}
+/** One mark on a text node. */
+interface XenoDocMark {
+    type: string;
+    attrs?: Record<string, unknown>;
+}
+/**
+ * The `.xdoc` envelope. Field names are exactly the ones XENO Docs' autosave has always written
+ * (`id, title, content, lastModified, created, wordCount`), so every existing file still parses;
+ * `format` and `version` are the additive part.
+ */
+interface XenoDocFile {
+    format: typeof XDOC_FORMAT;
+    version: number;
+    id?: string;
+    title: string;
+    content: XenoDocNode;
+    created: number;
+    lastModified: number;
+    wordCount: number;
+    /**
+     * XENO Docs' comment threads (its `Comment` mark points into them; XENO Docs keeps them as an object keyed by thread id). Carried through untouched by every surface,
+     * so a document that round-trips through the workspace keeps its comments; only XENO Docs reads them.
+     */
+    commentThreads?: unknown;
+}
+/** Node types the shared schema renders. A file with any other type is refused, never coerced. */
+declare const DOCUMENT_NODE_TYPES: readonly ["doc", "paragraph", "text", "heading", "blockquote", "bulletList", "orderedList", "listItem", "taskList", "taskItem", "codeBlock", "horizontalRule", "hardBreak", "table", "tableRow", "tableCell", "tableHeader", "image", "callout", "toggleBlock", "pageBreak"];
+/** Mark types the shared schema renders. */
+declare const DOCUMENT_MARK_TYPES: readonly ["bold", "italic", "strike", "code", "underline", "link", "subscript", "superscript", "highlight", "wikiLink"];
+/** A link a reader can follow without running anything. */
+declare const SAFE_LINK: RegExp;
+/** An image a reader can load without running anything: https, or a raster image inline. */
+declare const SAFE_IMAGE: RegExp;
+/** Limits a file must stay inside. */
+declare const LIMITS: Readonly<{
+    depth: 64;
+    nodes: 50000;
+    text: 2000000;
+}>;
+/** One reason a document was refused. `path` points at the offending node (`content[2].content[0]`). */
+interface XenoDocProblem {
+    path: string;
+    code: 'unknown_node' | 'unknown_mark' | 'bad_attr' | 'bad_shape' | 'too_deep' | 'too_large';
+    detail: string;
+}
+/** Options for {@link validateContent}: a product's own extensions, allowed in ITS files only. */
+interface ValidateOptions {
+    extraNodes?: Iterable<string>;
+    extraMarks?: Iterable<string>;
+}
+/**
+ * Check a ProseMirror document against the shared schema. Pure; never throws for bad input.
+ *
+ * Types in `extraNodes` / `extraMarks` are accepted with their attributes unchecked: they belong to the
+ * product that declared them, and only that product's surface renders them.
+ */
+declare function validateContent(content: unknown, options?: ValidateOptions): XenoDocProblem[];
+/** The error {@link parseXdoc} throws: the problems ride on it so a caller can say exactly what is wrong. */
+declare class XdocError extends Error {
+    readonly problems: XenoDocProblem[];
+    constructor(message: string, problems?: XenoDocProblem[]);
+}
+/** An empty document: one empty paragraph, which is what TipTap writes for a blank editor. */
+declare const emptyContent: () => XenoDocNode;
+/**
+ * Parse a `.xdoc` file (text or an already-parsed object). Accepts the legacy XENO Docs envelope with
+ * no `format` field. Throws {@link XdocError} for anything the shared schema would not render.
+ */
+declare function parseXdoc(input: string | unknown, options?: ValidateOptions): XenoDocFile;
+/** Write a `.xdoc`. Validates first: a surface must never write a file the next surface refuses. */
+declare function serializeXdoc(doc: Omit<XenoDocFile, 'format' | 'version' | 'wordCount'> & {
+    wordCount?: number;
+}, options?: ValidateOptions & {
+    pretty?: boolean;
+}): string;
+/** The document's words without structure — what search indexes and an excerpt shows. */
+declare function plainText(content: XenoDocNode | undefined): string;
+/** Words, the way XENO Docs' status bar counts them. */
+declare function wordCount(content: XenoDocNode | undefined): number;
+/** The ids every page link (`wikiLink` mark) in the document points at, deduplicated, in order. */
+declare function pageLinksIn(content: XenoDocNode | undefined): string[];
+/** Every node type in a document — what a surface checks before it decides it can edit it. */
+declare function nodeTypesIn(content: XenoDocNode | undefined): Set<string>;
+
+/**
+ * Markdown import/export engine
+ * Converts between TipTap JSON document model and Markdown text
+ * Uses a hand-written converter for full control over formatting fidelity
+ * Pattern: Typora/Obsidian markdown handling
+ */
+
+/** TipTap's JSONContent, restated so this file imports no editor (attrs are as loose as TipTap's). */
+interface JSONContent {
+    type?: string;
+    attrs?: Record<string, any>;
+    content?: JSONContent[];
+    marks?: {
+        type: string;
+        attrs?: Record<string, any>;
+    }[];
+    text?: string;
+}
+declare function documentToMarkdown(doc: JSONContent): string;
+declare function markdownToDocument(md: string): XenoDocNode;
+
+export { DOCUMENT_MARK_TYPES, DOCUMENT_NODE_TYPES, type JSONContent, LIMITS, SAFE_IMAGE, SAFE_LINK, type ValidateOptions, XDOC_EXTENSION, XDOC_FORMAT, XDOC_VERSION, XdocError, type XenoDocFile, type XenoDocMark, type XenoDocNode, type XenoDocProblem, documentToMarkdown, emptyContent, markdownToDocument, nodeTypesIn, pageLinksIn, parseXdoc, plainText, serializeXdoc, validateContent, wordCount };

package/dist/docs/format.js

@@ -0,0 +1,44 @@
+import "../chunk-HDP35LGH.js";
+import {
+  DOCUMENT_MARK_TYPES,
+  DOCUMENT_NODE_TYPES,
+  LIMITS,
+  SAFE_IMAGE,
+  SAFE_LINK,
+  XDOC_EXTENSION,
+  XDOC_FORMAT,
+  XDOC_VERSION,
+  XdocError,
+  documentToMarkdown,
+  emptyContent,
+  markdownToDocument,
+  nodeTypesIn,
+  pageLinksIn,
+  parseXdoc,
+  plainText,
+  serializeXdoc,
+  validateContent,
+  wordCount
+} from "../chunk-NFOBZJDF.js";
+import "../chunk-2KG3PWR4.js";
+export {
+  DOCUMENT_MARK_TYPES,
+  DOCUMENT_NODE_TYPES,
+  LIMITS,
+  SAFE_IMAGE,
+  SAFE_LINK,
+  XDOC_EXTENSION,
+  XDOC_FORMAT,
+  XDOC_VERSION,
+  XdocError,
+  documentToMarkdown,
+  emptyContent,
+  markdownToDocument,
+  nodeTypesIn,
+  pageLinksIn,
+  parseXdoc,
+  plainText,
+  serializeXdoc,
+  validateContent,
+  wordCount
+};