@lyads/visual-editor 0.0.0-stage → 1.0.1

package/dist/composition/block-factory.d.ts

@@ -0,0 +1,84 @@
+import { BlockDocument } from '../core/block-document';
+import type { BlockDocumentData } from '../core/block-document';
+import type { AnyDocument } from '../core/any-document';
+import type { DocumentKind, EditorDocumentData, SourceInput } from '../core/document';
+import { BlockEditorSession } from '../application/block-session';
+import type { BlockStorePort } from '../application/block-session';
+import { BlockDefinitionRegistry } from '../blocks/definitions';
+import type { OutputMode } from '../blocks/block-type';
+import type { GeneratedMjml, GeneratedMjmlCompilerPort } from '../compilation/generated-mjml';
+import type { MjmlCompilerPort } from '../renderers/email-renderer';
+import { SelectionPreviewRenderer } from '../renderers/selection-preview';
+import { BlockTemplateCatalog } from '../templates/blocks/catalog';
+import { BlockEditorController } from '../vue/block-controller';
+/** A compiler of both kinds of MJML; the browser and the Node compilers are. */
+export type BlockCompiler = MjmlCompilerPort & GeneratedMjmlCompilerPort & {
+    dispose?(): void;
+};
+export interface BlockToolkitOptions {
+    /** A compiler the host owns; otherwise the toolkit creates one and disposes of it. */
+    readonly compiler?: BlockCompiler;
+    /** Placeholders accepted as whole link addresses, e.g. `{{unsubscribe_url}}`. */
+    readonly exactUrlPlaceholders?: readonly string[];
+}
+/**
+ * What a host needs of block pieces (schema 2) without the editor: validate what it stores,
+ * generate and compile the output, and convert a piece to the HTML document (schema 1).
+ */
+export interface BlockToolkit {
+    readonly registry: BlockDefinitionRegistry;
+    readonly templates: BlockTemplateCatalog;
+    /** A stored piece of either schema; throws `DocumentValidationError` (or a subclass). */
+    parse(input: unknown): AnyDocument;
+    /** A block piece; throws `BlockDocumentError`. */
+    parseBlocks(input: unknown): BlockDocument;
+    /** A new piece of a kind, blank or from a template, with fresh block ids. */
+    /**
+     * A new piece from a template (the blank one by default), with the texts in `language`
+     * (pt-BR by default; English and Spanish are written too).
+     */
+    create(kind: DocumentKind, documentId: string, templateId?: string, language?: string): BlockDocument;
+    /** The HTML and CSS of a page piece. */
+    generatePage(document: BlockDocument, mode?: OutputMode): SourceInput;
+    /** The MJML of an e-mail piece, with the raw regions only the compilers accept. */
+    generateMjml(document: BlockDocument, mode?: OutputMode): GeneratedMjml;
+    /** The compiled HTML of an e-mail piece, checked against the e-mail rules. */
+    compileEmail(document: BlockDocument): Promise<SourceInput>;
+    /** The final output of a piece of either kind: what is stored, sent or published. */
+    render(document: BlockDocument): Promise<SourceInput>;
+    /** "Convert to editable HTML": one way only, to a schema 1 document. */
+    convert(document: BlockDocument): Promise<EditorDocumentData>;
+    dispose(): void;
+}
+export interface BlockEditorOptions extends BlockToolkitOptions {
+    readonly kind?: DocumentKind;
+    /** A stored piece (schema 2); validated here. */
+    readonly document?: BlockDocumentData;
+    /** The template a new piece starts from; the blank one of its kind by default. */
+    readonly template?: string;
+    /** Language of the texts of a new piece and of the templates applied to it. */
+    readonly language?: string;
+    /** Id of a new piece. */
+    readonly documentId?: string;
+    readonly readOnly?: boolean;
+    readonly persistedRevision?: number;
+    readonly store?: BlockStorePort;
+    readonly previewImageOrigins?: readonly string[];
+    readonly onObserverError?: (error: unknown) => void;
+}
+export interface BlockEditorInstance {
+    readonly session: BlockEditorSession;
+    readonly controller: BlockEditorController;
+    readonly selectionRenderer: SelectionPreviewRenderer;
+    readonly toolkit: BlockToolkit;
+    dispose(): void;
+}
+/** The only place that builds the graph of block pieces; every instance owns its state. */
+export declare class BlockEditorFactory {
+    private readonly compilerFactory;
+    constructor(compilerFactory: () => BlockCompiler);
+    toolkit(options?: BlockToolkitOptions): BlockToolkit;
+    create(options?: BlockEditorOptions): BlockEditorInstance;
+    private static ofKind;
+    private parts;
+}

package/dist/composition/browser.d.ts

@@ -0,0 +1,48 @@
+import type { EditorOptions } from './factory';
+import type { BlockEditorInstance, BlockEditorOptions, BlockToolkit, BlockToolkitOptions } from './block-factory';
+export declare function createEditor(options?: EditorOptions): import("./factory").EditorInstance;
+/** An editor of a block piece (schema 2), compiling e-mails in a browser worker. */
+export declare function createBlockEditor(options?: BlockEditorOptions): BlockEditorInstance;
+/** Parse, generate, compile and convert block pieces in the browser, without an editor. */
+export declare function createBlockToolkit(options?: BlockToolkitOptions): BlockToolkit;
+export { EditorFactory, InitialDocumentError } from './factory';
+export type { EditorOptions, EditorInstance } from './factory';
+export { EditorDocument, EditorDocumentSchema, DocumentNodeSchema, DOCUMENT_LIMITS, } from '../core/document';
+export type { EditorDocumentData, DocumentNode, Diagnostic, DiagnosticSeverity, DocumentKind, SourceInput, } from '../core/document';
+export { EditorSession } from '../application/session';
+export type { EditorState } from '../application/session';
+export type { HostAdapters, StorePort, AssetPort, SlotsPort, AssetReference, } from '../application/host';
+export { ContentPolicy, ContentPolicyError } from '../security/policy';
+export type { SanitizedDocument } from '../security/policy';
+export type { ContentInventory, ExternalReference } from '../security/content-inventory';
+export { HtmlDocumentCodec } from '../codecs/html';
+export { CssDocumentCodec } from '../codecs/css';
+export { BrowserMjmlCompiler } from '../compilation/browser-compiler';
+export { PreviewDocument } from '../renderers/preview-document';
+export { HtmlDocumentAssembler } from '../renderers/preview-document';
+export { SelectionPreviewRenderer } from '../renderers/selection-preview';
+export { UrlPolicy } from '../security/url-policy';
+export { BlockEditorFactory } from './block-factory';
+export type { BlockCompiler, BlockEditorInstance, BlockEditorOptions, BlockToolkit, BlockToolkitOptions, } from './block-factory';
+export { BlockDocument, BlockDocumentError, BlockDocumentSchema, BLOCK_DOCUMENT_LIMITS, BLOCK_NODE_TYPES, } from '../core/block-document';
+export type { Block, BlockDocumentData, BlockNodeType, BlockPropValue, BlockProps, BlockTarget, GlobalStyles, StylePatch, } from '../core/block-document';
+export { parseAnyDocument } from '../core/any-document';
+export type { AnyDocument } from '../core/any-document';
+export { BlockEditorSession } from '../application/block-session';
+export type { BlockEditorState, BlockImageChoice, BlockStorePort, } from '../application/block-session';
+export { BlockDefinitionRegistry } from '../blocks/definitions';
+export { GLOBAL_STYLE_GROUPS } from '../blocks/styles';
+export { BlockConversionError } from '../blocks/conversion';
+export type { OutputMode } from '../blocks/block-type';
+export { GeneratedMjml } from '../compilation/generated-mjml';
+export { BlockTemplateCatalog } from '../templates/blocks/catalog';
+export type { BlockTemplateDescriptor } from '../templates/blocks/catalog';
+export type { BlockPreviewInput } from '../renderers/marked-preview';
+export { BlockContentGuard } from '../blocks/content-guard';
+export { BlockMjmlGenerator } from '../blocks/email-generator';
+export { BlockPageGenerator } from '../blocks/page-generator';
+export { BlockEmailRenderer } from '../blocks/email-renderer';
+export { BlockToHtmlConversion } from '../blocks/conversion';
+export { BlockChecker, GMAIL_CLIP_BYTES, GMAIL_NEAR_CLIP_BYTES } from '../blocks/block-checks';
+export type { BlockCheck, BlockCheckCode } from '../blocks/block-checks';
+export type { BlockDevice } from '../core/block-document';

package/dist/composition/factory.d.ts

@@ -0,0 +1,48 @@
+import type { Diagnostic, DocumentKind, EditorDocumentData, SourceInput } from '../core/document';
+import type { HostAdapters } from '../application/host';
+import { EditorSession } from '../application/session';
+import { MjmlEmailRenderer } from '../renderers/email-renderer';
+import type { MjmlCompilerPort } from '../renderers/email-renderer';
+import { PageRenderer } from '../renderers/page-renderer';
+import { SelectionPreviewRenderer } from '../renderers/selection-preview';
+import { TemplateCatalog } from '../templates/catalog';
+import { EditorController } from '../vue/controller';
+export interface EditorOptions {
+    readonly kind?: DocumentKind;
+    readonly document?: EditorDocumentData;
+    readonly source?: SourceInput;
+    readonly readOnly?: boolean;
+    readonly persistedRevision?: number;
+    readonly host?: HostAdapters;
+    readonly compiler?: MjmlCompilerPort;
+    readonly exactUrlPlaceholders?: readonly string[];
+    readonly previewImageOrigins?: readonly string[];
+    /** Receives an exception thrown by a `session.subscribe` listener; the listener stays. */
+    readonly onObserverError?: (error: unknown) => void;
+}
+export interface EditorInstance {
+    readonly session: EditorSession;
+    readonly controller: EditorController;
+    readonly templates: TemplateCatalog;
+    readonly pageRenderer: PageRenderer;
+    readonly emailRenderer: MjmlEmailRenderer;
+    readonly selectionRenderer: SelectionPreviewRenderer;
+    dispose(): void;
+}
+/**
+ * The initial source could not become a document. Since the tolerant import this only
+ * happens over the limits or with markup no parser reads back the same; `diagnostics`
+ * carries the specific code (`DOCUMENT_TOO_LARGE`, `DOCUMENT_TOO_MANY_NODES`...).
+ */
+export declare class InitialDocumentError extends Error {
+    readonly diagnostics: readonly Diagnostic[];
+    constructor(diagnostics: readonly Diagnostic[]);
+}
+/** The only place that constructs the dependency graph. Every editor owns its state. */
+export declare class EditorFactory {
+    private readonly compilerFactory;
+    constructor(compilerFactory: () => MjmlCompilerPort & {
+        dispose?(): void;
+    });
+    create(options?: EditorOptions): EditorInstance;
+}

package/dist/composition/server.d.ts

@@ -0,0 +1,43 @@
+import type { EditorOptions } from './factory';
+import type { BlockToolkit, BlockToolkitOptions } from './block-factory';
+export declare function createServerEditor(options?: EditorOptions): import("./factory").EditorInstance;
+/**
+ * Parse, generate, compile and convert block pieces (schema 2) on the server, the source of
+ * truth: the e-mail is compiled by the isolated Node worker.
+ */
+export declare function createServerBlockToolkit(options?: BlockToolkitOptions): BlockToolkit;
+export { NodeMjmlCompiler } from '../compilation/node-compiler';
+export { EditorFactory, InitialDocumentError } from './factory';
+export type { EditorOptions, EditorInstance } from './factory';
+export { EditorDocument, DOCUMENT_LIMITS } from '../core/document';
+export type { EditorDocumentData, DocumentNode, SourceInput, Diagnostic, DiagnosticSeverity, } from '../core/document';
+export type { HostAdapters, StorePort, AssetPort, SlotsPort, AssetReference, } from '../application/host';
+export { ContentPolicy, ContentPolicyError } from '../security/policy';
+export type { SanitizedDocument } from '../security/policy';
+export type { ContentInventory, ExternalReference } from '../security/content-inventory';
+export { HtmlDocumentCodec } from '../codecs/html';
+export { CssDocumentCodec } from '../codecs/css';
+export { UrlPolicy } from '../security/url-policy';
+export { HtmlDocumentAssembler } from '../renderers/preview-document';
+export { BlockEditorFactory } from './block-factory';
+export type { BlockCompiler, BlockToolkit, BlockToolkitOptions } from './block-factory';
+export { BlockDocument, BlockDocumentError, BlockDocumentSchema, BLOCK_DOCUMENT_LIMITS, BLOCK_NODE_TYPES, } from '../core/block-document';
+export type { Block, BlockDocumentData, BlockNodeType, BlockPropValue, BlockProps, GlobalStyles, } from '../core/block-document';
+export { parseAnyDocument } from '../core/any-document';
+export type { AnyDocument } from '../core/any-document';
+export type { BlockStorePort } from '../application/block-session';
+export { BlockDefinitionRegistry } from '../blocks/definitions';
+export { BlockConversionError } from '../blocks/conversion';
+export type { OutputMode } from '../blocks/block-type';
+export { GeneratedMjml } from '../compilation/generated-mjml';
+export { BlockTemplateCatalog } from '../templates/blocks/catalog';
+export type { BlockTemplateDescriptor } from '../templates/blocks/catalog';
+export { BlockContentGuard } from '../blocks/content-guard';
+export { BlockMjmlGenerator } from '../blocks/email-generator';
+export { BlockPageGenerator } from '../blocks/page-generator';
+export { BlockEmailRenderer } from '../blocks/email-renderer';
+export { BlockToHtmlConversion } from '../blocks/conversion';
+export { BlockChecker, GMAIL_CLIP_BYTES, GMAIL_NEAR_CLIP_BYTES } from '../blocks/block-checks';
+export type { BlockCheck, BlockCheckCode } from '../blocks/block-checks';
+export { BLOCK_DEVICES } from '../core/block-document';
+export type { BlockDevice } from '../core/block-document';

package/dist/core/any-document.d.ts

@@ -0,0 +1,16 @@
+import { BlockDocument } from './block-document';
+import type { BlockRules } from './block-document';
+import { EditorDocument } from './document';
+/** A stored piece in either format. Nothing converts one into the other on the way in. */
+export type AnyDocument = {
+    readonly schemaVersion: 1;
+    readonly document: EditorDocument;
+} | {
+    readonly schemaVersion: 2;
+    readonly document: BlockDocument;
+};
+/**
+ * Dispatches by `schemaVersion`: 1 is the HTML document of the editor, 2 the block piece.
+ * Throws `DocumentValidationError` (or its `BlockDocumentError` subclass) like each format.
+ */
+export declare function parseAnyDocument(input: unknown, rules: BlockRules): AnyDocument;

package/dist/core/block-document.d.ts

@@ -0,0 +1,215 @@
+import * as v from 'valibot';
+import { DocumentValidationError } from './document';
+import type { DocumentKind } from './document';
+/**
+ * Schema 2: a piece made of blocks. Each block keeps only the values its author set; what is
+ * absent is inherited from the global styles of the piece, and those from the defaults of the
+ * catalog. The HTML of an e-mail and of a page is generated from this tree, never edited.
+ *
+ * The aggregate knows the shape of the tree and its invariants. What each block type accepts
+ * (children, properties, content rules) comes from a `BlockRules` port, implemented by the
+ * block definitions outside `core`.
+ */
+export declare const BLOCK_NODE_TYPES: readonly ["section", "column", "text", "heading", "image", "button", "divider", "spacer", "footer", "form", "html"];
+export type BlockNodeType = (typeof BLOCK_NODE_TYPES)[number];
+export type BlockPropValue = string | number | boolean;
+export type BlockProps = Readonly<Record<string, BlockPropValue>>;
+export type StyleValue = string | number;
+export type GlobalStyles = Readonly<Record<string, Readonly<Record<string, StyleValue>>>>;
+export interface Block {
+    readonly id: string;
+    readonly type: BlockNodeType;
+    readonly props: BlockProps;
+    /**
+     * Values the block uses on small screens instead of its own (or inherited) ones. Only the
+     * fields the rules call responsive may appear here; absent when the block has none.
+     */
+    readonly mobile?: BlockProps;
+    readonly children?: readonly Block[];
+}
+/** The screen a value applies to: `desktop` writes `props`, `mobile` writes `mobile`. */
+export type BlockDevice = 'desktop' | 'mobile';
+export declare const BLOCK_DEVICES: readonly BlockDevice[];
+export interface BlockDocumentMeta {
+    readonly lang: string;
+}
+export interface BlockDocumentData {
+    readonly schemaVersion: 2;
+    readonly id: string;
+    readonly kind: DocumentKind;
+    readonly revision: number;
+    /** Internal label of the piece. The subject, preheader and SEO title belong to the host. */
+    readonly title: string;
+    readonly meta: BlockDocumentMeta;
+    readonly styles: GlobalStyles;
+    readonly blocks: readonly Block[];
+}
+/** Where an inserted or moved block goes. `inside` without a parent means the root. */
+export type BlockTarget = {
+    readonly position: 'before' | 'after';
+    readonly id: string;
+} | {
+    readonly position: 'inside';
+    readonly parentId?: string;
+    readonly index?: number;
+};
+export type StylePatch = Readonly<Record<string, Readonly<Record<string, StyleValue>>>>;
+/** What a block type accepts. Implemented by the block definitions. */
+export interface BlockRules {
+    /** Types which may stand at the root of the piece. */
+    isRoot(type: BlockNodeType): boolean;
+    /** Types a block of this type may contain; empty for a leaf. */
+    childTypes(type: BlockNodeType): readonly BlockNodeType[];
+    childCount(type: BlockNodeType): {
+        readonly min: number;
+        readonly max: number;
+    };
+    allows(type: BlockNodeType, kind: DocumentKind): boolean;
+    /** Error code for the properties of one block, or undefined when they are valid. */
+    validateProps(type: BlockNodeType, props: BlockProps, kind: DocumentKind): string | undefined;
+    /** The value a command writes: normalized, or a thrown `BlockDocumentError`. */
+    normalizeProp(type: BlockNodeType, key: string, value: BlockPropValue, kind: DocumentKind): BlockPropValue;
+    /** Keys whose value is a text the author edits in place. */
+    textKeys(type: BlockNodeType): readonly string[];
+    /**
+     * Whether a property may take a value of its own on small screens. Without this method no
+     * block of the piece accepts mobile values.
+     */
+    responsive?(type: BlockNodeType, key: string, kind: DocumentKind): boolean;
+    validateStyles(styles: GlobalStyles, kind: DocumentKind): string | undefined;
+    /**
+     * Error code for the piece as a whole, once its tree is valid: e.g. an output larger than
+     * the compilation or the conversion accepts. Optional.
+     */
+    validateDocument?(data: BlockDocumentData): string | undefined;
+    normalizeStyle(group: string, key: string, value: StyleValue, kind: DocumentKind): StyleValue;
+}
+export declare const BLOCK_DOCUMENT_LIMITS: Readonly<{
+    blocks: 5000;
+    depth: 8;
+    childrenPerBlock: 500;
+    propsPerBlock: 64;
+    propValueLength: 500000;
+    styleGroups: 32;
+    stylesPerGroup: 32;
+    styleValueLength: 200;
+    titleLength: 1000;
+}>;
+/** Identifiers end up in class names, selectors and MJML attributes: nothing else is allowed. */
+export declare const BLOCK_ID_PATTERN: RegExp;
+/** A language tag as `<html lang>` takes it: `pt-BR`, `en`, `es-419`. */
+export declare const LANGUAGE_TAG_PATTERN: RegExp;
+export declare const BlockSchema: v.GenericSchema<Block>;
+export declare const GlobalStylesSchema: v.GenericSchema<GlobalStyles>;
+export declare const BlockDocumentSchema: v.GenericSchema<BlockDocumentData>;
+export declare class BlockDocumentError extends DocumentValidationError {
+    constructor(code: string);
+}
+/**
+ * Immutable aggregate of a block piece. Every operation is pure: it returns a new document
+ * with the next revision, validated as a whole, or throws `BlockDocumentError`.
+ */
+export declare class BlockDocument {
+    #private;
+    private constructor();
+    static from(input: unknown, rules: BlockRules): BlockDocument;
+    /** The invariants of the tree and of the piece, over data of the schema's shape. */
+    private static checked;
+    get id(): string;
+    get kind(): DocumentKind;
+    get revision(): number;
+    get title(): string;
+    get meta(): BlockDocumentMeta;
+    /** Frozen view of the overridden global styles. */
+    get styles(): GlobalStyles;
+    /** Frozen view of the tree; `snapshot()` gives an independent copy. */
+    get blocks(): readonly Block[];
+    snapshot(): BlockDocumentData;
+    /** The data itself, deeply frozen: what reads it never pays for a copy. */
+    get data(): BlockDocumentData;
+    /** Size of the JSON of the piece, for the byte budget of the history. */
+    serializedBytes(): number;
+    /**
+     * Only the revision changes: the validated tree is not checked a second time. A session uses
+     * it to move forward when it restores an earlier step of its history.
+     */
+    withRevision(revision: number): BlockDocument;
+    find(id: string): Block | undefined;
+    /** Id of the block which contains this one; undefined at the root or when absent. */
+    parentOf(id: string): string | undefined;
+    private index;
+    insert(block: Block, target: BlockTarget): BlockDocument;
+    /**
+     * `inside` with an index counts the slots of the parent as it is before the move, like a
+     * drop indicator between two blocks: moving the first of `[a, b]` to index 2 gives `[b, a]`.
+     */
+    move(id: string, target: BlockTarget): BlockDocument;
+    /** Copies a block and its children with new ids, right after the original. */
+    duplicate(id: string, nextId: () => string): BlockDocument;
+    remove(id: string): BlockDocument;
+    /**
+     * Sets values the author chose, for every screen or only for small ones; a patch which
+     * changes nothing returns this document. A mobile value equal to the one the block already
+     * uses on every screen is still kept: the author chose it for the small screen.
+     */
+    updateProps(id: string, patch: BlockProps, device?: BlockDevice): BlockDocument;
+    /**
+     * "Restore default": the keys disappear and the block inherits again. On mobile only the
+     * mobile values go, and the block uses its value of every screen again.
+     */
+    restoreDefault(id: string, keys: readonly string[], device?: BlockDevice): BlockDocument;
+    /** Whether this property of the block may take a value of its own on small screens. */
+    responsive(type: BlockNodeType, key: string): boolean;
+    /** The text of a block, in the rich-text projection its type accepts. */
+    updateText(id: string, key: string, value: string): BlockDocument;
+    updateStyles(patch: StylePatch): BlockDocument;
+    /**
+     * Back to the catalog defaults: every style without a group, a whole group without keys,
+     * or only the given keys of a group.
+     */
+    restoreStyleDefault(group?: string, keys?: readonly string[]): BlockDocument;
+    withMeta(meta: BlockDocumentMeta): BlockDocument;
+    withTitle(title: string): BlockDocument;
+    /**
+     * The next revision. The data was built here from a validated document and from values the
+     * rules normalized, so it keeps the shape of the schema; the parsing of the schema is not
+     * paid again, but every invariant of the tree and of the piece is checked as for any input.
+     */
+    private next;
+    /**
+     * The tree a command changes, copied on write: the root list is new, and `locate` copies
+     * only the blocks on the path to what it finds. Every other block stays the frozen object of
+     * this document, shared by the next one (and never validated again: see `assertTree`).
+     */
+    private mutableBlocks;
+    /** A block of the tree being changed, as a copy the command may write. */
+    private open;
+    private place;
+    private contains;
+    private reidentify;
+    private blockAt;
+    private require;
+    /**
+     * Where a block of this document stands in the tree being changed. The path comes from the
+     * index of this document (a command never moves a block inside itself), and each block on it
+     * is opened for writing, the found one included.
+     */
+    private locate;
+    private static assertStyles;
+    /**
+     * Frozen blocks whose own values were already accepted by these rules for a kind. The values
+     * of a block depend only on its type and the kind, and a frozen block never changes: a block
+     * shared by the next revision is not checked again. Its place in the tree always is.
+     */
+    private static readonly accepted;
+    private static acceptedFor;
+    private static assertTree;
+    /**
+     * Mobile values: at least one, each of a responsive property, each one a value the property
+     * accepts. They are checked over the values of every screen, so the rules see a whole block.
+     */
+    private static assertMobile;
+    /** Keys and values of the schema's shape, checked again for data built by a command. */
+    private static values;
+    private static freeze;
+}

package/dist/core/budget.d.ts

@@ -0,0 +1,32 @@
+export declare class DocumentBudgetError extends Error {
+    readonly code: string;
+    constructor(code: string);
+}
+/** Bounds are checked before recursive schemas and parsers inspect untrusted input. */
+export declare class DocumentBudget {
+    static readonly limits: Readonly<{
+        nodes: 50000;
+        totalNodes: 150000;
+        depth: 256;
+        sourceBytes: 2000000;
+        cssBytes: 500000;
+        jsonBytes: 64000000;
+        attributesPerNode: 256;
+        /** Ceiling of values typed or projected by the editor itself (links, rich text). */
+        attributeLength: 16384;
+        /** Ceiling of one attribute of an imported document, e.g. an inline `data:` image. */
+        documentAttributeLength: 2000000;
+    }>;
+    /** Strings of a JSON document: content, plus identifiers and keys of every node. */
+    static readonly jsonStringBytes: number;
+    /** UTF-8 length. Read by code unit: megabytes of source are measured on every change. */
+    byteLength(value: string): number;
+    private lowSurrogate;
+    assertSource(html: string, css: string): void;
+    assertInput(data: unknown): void;
+    /** White space between tags does not count against the node ceiling. */
+    countable(node: {
+        readonly type: string;
+        readonly value?: string;
+    }): boolean;
+}

package/dist/core/canvas-contract.d.ts

@@ -0,0 +1,29 @@
+/**
+ * What the host, the renderers, the message policy and the runtime of the frame agree on about the
+ * piece on screen. It has no DOM and no dependency, so every side imports the same definition.
+ */
+/** Every attribute the editor adds to the copy shown in the frame starts with this. */
+export declare const RESERVED_ATTRIBUTE_PREFIX = "data-visual-editor-";
+/** Marks a selectable block with the id of its node. */
+export declare const NODE_ATTRIBUTE = "data-visual-editor-node";
+/** Marks an element of an editable text which keeps attributes of its own. */
+export declare const TEXT_ORIGIN_ATTRIBUTE = "data-visual-editor-text-origin";
+/** Marks the element whose text may be edited in place. */
+export declare const EDIT_NODE_ATTRIBUTE = "data-visual-editor-edit-node";
+/** Set by the runtime on the selected block. */
+export declare const SELECTED_ATTRIBUTE = "data-visual-editor-selected";
+/** Set by the runtime on its own layer of controls. */
+export declare const CONTROLS_ATTRIBUTE = "data-visual-editor-controls";
+export declare function isReservedAttribute(name: string): boolean;
+/** What the action bar, the context menu and the keyboard may ask about one block. */
+export declare const CANVAS_BLOCK_ACTIONS: readonly ["duplicate", "remove", "up", "down", "html", "image"];
+export type CanvasBlockAction = (typeof CANVAS_BLOCK_ACTIONS)[number];
+/** Widest image a resize gesture may ask for, in CSS pixels. */
+export declare const CANVAS_IMAGE_WIDTH_LIMIT = 4000;
+/** Longest color value of the host theme which may reach the style of the controls. */
+export declare const THEME_COLOR_LENGTH = 80;
+/** A plain CSS color value: no url, no quotes, no semicolon, nothing which could end a rule. */
+export declare function isThemeColor(value: unknown): value is string;
+/** Largest corner radius of the controls, in pixels. */
+export declare const THEME_RADIUS_LIMIT = 24;
+export declare function isInfrastructureTag(tag: string): boolean;

package/dist/core/canvas-layout.d.ts

@@ -0,0 +1,66 @@
+import type { DocumentNode, EditorDocumentData } from './document';
+import { BlockCatalog } from './catalog';
+import type { BlockType } from './catalog';
+export type CanvasPlacement = 'before' | 'after' | 'inside';
+export interface CanvasTarget {
+    readonly parentId?: string;
+    /** Index after removing the moving source. Insertion indices have no removal adjustment. */
+    readonly index: number;
+}
+export interface CanvasMotion extends CanvasTarget {
+    readonly sourceId: string;
+}
+export interface CanvasMovementTarget {
+    readonly targetId: string;
+    readonly placements: readonly CanvasPlacement[];
+}
+export interface CanvasRegion {
+    readonly id: string;
+    readonly parentId: string | null;
+    readonly index: number;
+    readonly depth: number;
+    readonly kind: BlockType | 'container' | 'native';
+    readonly labelKey?: string;
+    readonly node: DocumentNode;
+    readonly editable: boolean;
+    readonly container: boolean;
+}
+/** Logical canvas regions and valid destinations derived from the canonical HTML tree. */
+export declare class CanvasLayout {
+    private readonly catalog;
+    constructor(catalog?: BlockCatalog);
+    regions(document: EditorDocumentData): readonly CanvasRegion[];
+    /** Content selection is independent of the HTML unit used by structural commands. */
+    selectionRegions(document: EditorDocumentData): readonly CanvasRegion[];
+    /**
+     * The closest selection region above each selection region, in document order; `undefined`
+     * for a region at the top. Plain markup between two regions is skipped, as in the piece.
+     */
+    selectionParents(document: EditorDocumentData): ReadonlyMap<string, string | undefined>;
+    resolveSelection(document: EditorDocumentData, id: string): CanvasRegion | undefined;
+    resolve(document: EditorDocumentData, id: string): CanvasRegion | undefined;
+    editableNode(document: EditorDocumentData, id: string): DocumentNode | undefined;
+    target(document: EditorDocumentData, sourceId: string, targetId: string, placement: CanvasPlacement): CanvasTarget | undefined;
+    motion(document: EditorDocumentData, sourceId: string, targetId: string, placement: CanvasPlacement): CanvasMotion | undefined;
+    validMovementTargets(document: EditorDocumentData, sourceId: string): readonly CanvasMovementTarget[];
+    actionUnit(document: EditorDocumentData, id: string): CanvasRegion | undefined;
+    insertionAt(document: EditorDocumentData, targetId: string, placement: CanvasPlacement): CanvasTarget | undefined;
+    insertionTarget(document: EditorDocumentData, selectedId?: string): CanvasTarget | undefined;
+    acceptsInsertion(document: EditorDocumentData, destination: CanvasTarget, nodes: readonly DocumentNode[]): boolean;
+    private movementProjection;
+    private resolveRegion;
+    private motionUsing;
+    private structuralTarget;
+    private regionDestination;
+    private acceptsAt;
+    private isContentUnit;
+    private region;
+    private rowContent;
+    private hasRichTextBlocks;
+    private isContentWrapper;
+    private contentTarget;
+    private locations;
+    private hasVisibleContent;
+    private contains;
+    private findTag;
+}

package/dist/core/catalog.d.ts

@@ -0,0 +1,35 @@
+import type { DocumentKind, DocumentNode } from './document';
+export type BlockType = 'heading' | 'text' | 'image' | 'button' | 'section' | 'columns' | 'divider' | 'spacer' | 'footer' | 'form' | 'html';
+export interface BlockProperty {
+    readonly name: string;
+    readonly labelKey: string;
+    readonly kind: 'text' | 'attribute' | 'style';
+}
+export interface BlockDescriptor {
+    readonly type: BlockType;
+    readonly labelKey: string;
+    readonly kinds: readonly DocumentKind[];
+    readonly tag: string;
+    readonly canContainChildren: boolean;
+    readonly properties: readonly BlockProperty[];
+}
+/** Recognition follows actual HTML structure; imported labels do not grant capabilities. */
+export declare class BlockCatalog {
+    private readonly model;
+    descriptors(kind?: DocumentKind): readonly BlockDescriptor[];
+    descriptor(type: BlockType): BlockDescriptor;
+    properties(node: DocumentNode): readonly BlockProperty[];
+    acceptsProperty(node: DocumentNode, name: string, kind: BlockProperty['kind']): boolean;
+    recognize(node: DocumentNode): BlockDescriptor | undefined;
+    canEditText(node: DocumentNode): boolean;
+    canEditRichText(node: DocumentNode): boolean;
+    acceptsRichText(parent: DocumentNode, children: readonly DocumentNode[]): boolean;
+    richTextAllowsBlocks(node: DocumentNode): boolean;
+    acceptsChildren(parent: DocumentNode, children: readonly DocumentNode[]): boolean;
+    acceptsRootChildren(children: readonly DocumentNode[]): boolean;
+    private validRichText;
+    private isColumns;
+    private hasContent;
+    private hasAnchor;
+    create(type: BlockType, id: string, kind: DocumentKind): DocumentNode;
+}

package/dist/core/document-presentation.d.ts

@@ -0,0 +1,21 @@
+import * as v from 'valibot';
+export declare const IMAGE_SIZE_LIMITS: Readonly<{
+    min: 1;
+    max: 10000;
+}>;
+export declare const DOCUMENT_STYLE_PROPERTIES: readonly ["font-family", "font-size", "line-height", "color", "background-color"];
+export type DocumentStyleProperty = (typeof DOCUMENT_STYLE_PROPERTIES)[number];
+declare const imageSizeSchema: v.StrictObjectSchema<{
+    readonly width: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.FiniteAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 10000, undefined>]>;
+    readonly height: v.ExactOptionalSchema<v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.FiniteAction<number, undefined>, v.MinValueAction<number, 1, undefined>, v.MaxValueAction<number, 10000, undefined>]>, undefined>;
+    readonly preserveRatio: v.ExactOptionalSchema<v.BooleanSchema<undefined>, undefined>;
+}, undefined>;
+export type ImageSizeSettings = v.InferOutput<typeof imageSizeSchema>;
+/** Canonical bounded presentation settings, independent of adapters. */
+export declare class DocumentPresentationPolicy {
+    image(input: unknown): ImageSizeSettings;
+    dimension(input: unknown): number;
+    safeDimension(input: unknown): number | undefined;
+    style(property: unknown, value: unknown): void;
+}
+export {};