@rtif-sdk/web 1.0.0

package/dist/plugin-kit.d.ts

@@ -0,0 +1,265 @@
+/**
+ * Plugin kit — DX helper for defining custom RTIF web plugins.
+ *
+ * Provides typed factory functions that bundle an engine {@link Plugin} with
+ * web-layer renderers ({@link MarkRenderer}, {@link BlockRenderer},
+ * {@link BlockAttrRenderer}, {@link SpanReplacer}) in a single
+ * {@link WebPlugin} definition.
+ *
+ * Three factories cover the most common plugin patterns:
+ * - {@link defineBooleanMark} — on/off marks (highlight, subscript, etc.)
+ * - {@link defineParameterizedMark} — value-carrying marks (colors, sizes)
+ * - {@link defineBlockType} — toggle block types (aside, blockquote-style)
+ *
+ * The {@link installWebPlugins} utility registers all engine plugins and
+ * renderers from an array of {@link WebPlugin} objects.
+ *
+ * @module
+ */
+import type { Plugin, ShortcutDescriptor, IEditorEngine } from '@rtif-sdk/engine';
+import type { MarkRenderer, MarkRendererRegistry, SpanReplacer } from './mark-renderer.js';
+import type { BlockRenderer, BlockAttrRenderer, BlockRendererRegistry } from './block-renderer.js';
+/**
+ * A web plugin bundles an engine plugin with optional web-layer renderers.
+ *
+ * Pass an array of these to `createWebEditor({ webPlugins: [...] })` or
+ * call {@link installWebPlugins} manually.
+ *
+ * @example
+ * ```ts
+ * const highlight = defineBooleanMark({
+ *   markType: 'highlight',
+ *   shortcut: { key: 'h', mod: true, shift: true },
+ *   renderer: { apply(el) { el.style.backgroundColor = 'yellow'; } },
+ * });
+ * createWebEditor({ ..., webPlugins: [highlight] });
+ * ```
+ */
+export interface WebPlugin {
+    /** The engine plugin (registered via `engine.use()`). */
+    readonly plugin: Plugin;
+    /** Mark renderers keyed by mark type. */
+    readonly marks?: Readonly<Record<string, MarkRenderer>>;
+    /** Block renderers keyed by block type. */
+    readonly blocks?: Readonly<Record<string, BlockRenderer>>;
+    /** Block attribute renderers keyed by attribute name. */
+    readonly attrs?: Readonly<Record<string, BlockAttrRenderer>>;
+    /** Span replacers keyed by mark type. */
+    readonly replacers?: Readonly<Record<string, SpanReplacer>>;
+}
+/**
+ * Configuration for {@link defineBooleanMark}.
+ */
+export interface BooleanMarkDef {
+    /** The mark type string (e.g., "highlight", "subscript"). */
+    readonly markType: string;
+    /**
+     * Custom plugin ID. Defaults to `"mark-<markType>"`.
+     * Use reverse-DNS for published plugins.
+     */
+    readonly pluginId?: string;
+    /**
+     * Custom toggle command name. Defaults to `"toggleMark:<markType>"`.
+     */
+    readonly commandName?: string;
+    /** Optional keyboard shortcut for the toggle command. */
+    readonly shortcut?: ShortcutDescriptor;
+    /** The mark renderer applied to span elements. */
+    readonly renderer: MarkRenderer;
+}
+/**
+ * Define a boolean (on/off) mark plugin.
+ *
+ * Creates a {@link WebPlugin} that registers a mark type with `validate: v === true`,
+ * a toggle command via `createToggleMarkCommand()`, an optional keyboard shortcut,
+ * and a mark renderer.
+ *
+ * @param config - Boolean mark definition
+ * @returns A WebPlugin ready for `createWebEditor({ webPlugins: [...] })`
+ *
+ * @example
+ * ```ts
+ * const highlight = defineBooleanMark({
+ *   markType: 'highlight',
+ *   shortcut: { key: 'h', mod: true, shift: true },
+ *   renderer: { apply(el) { el.style.backgroundColor = 'yellow'; } },
+ * });
+ * ```
+ */
+export declare function defineBooleanMark(config: BooleanMarkDef): WebPlugin;
+/**
+ * Configuration for the set command in {@link ParameterizedMarkDef}.
+ */
+export interface SetMarkCommandDef {
+    /** The command name (e.g., "setBgColor"). */
+    readonly name: string;
+    /**
+     * Extract the mark value from the command payload.
+     *
+     * @param payload - The payload passed to `engine.exec()`
+     * @returns The value to set on the mark
+     *
+     * @example
+     * ```ts
+     * extractValue: (p) => (p as { color: string }).color
+     * ```
+     */
+    readonly extractValue: (payload: unknown) => unknown;
+    /** Optional keyboard shortcut for the set command. */
+    readonly shortcut?: ShortcutDescriptor;
+}
+/**
+ * Configuration for {@link defineParameterizedMark}.
+ */
+export interface ParameterizedMarkDef {
+    /** The mark type string (e.g., "bgColor", "highlight-color"). */
+    readonly markType: string;
+    /**
+     * Custom plugin ID. Defaults to `"mark-<markType>"`.
+     */
+    readonly pluginId?: string;
+    /**
+     * Validate mark values. Return `true` if the value is valid.
+     *
+     * @param value - The mark value to validate
+     * @returns Whether the value is valid
+     */
+    readonly validate: (value: unknown) => boolean;
+    /** Configuration for the "set" command. */
+    readonly setCommand: SetMarkCommandDef;
+    /** Name of the "remove" command (e.g., "removeBgColor"). */
+    readonly removeCommand: string;
+    /** The mark renderer applied to span elements. */
+    readonly renderer: MarkRenderer;
+}
+/**
+ * Define a parameterized (value-carrying) mark plugin.
+ *
+ * Creates a {@link WebPlugin} that registers a mark type with custom validation,
+ * a "set" command via `createSetMarkCommand()`, a "remove" command via
+ * `createRemoveMarkCommand()`, optional keyboard shortcuts, and a mark renderer.
+ *
+ * @param config - Parameterized mark definition
+ * @returns A WebPlugin ready for `createWebEditor({ webPlugins: [...] })`
+ *
+ * @example
+ * ```ts
+ * const bgColor = defineParameterizedMark({
+ *   markType: 'bgColor',
+ *   validate: (v) => typeof v === 'string' && v.length > 0,
+ *   setCommand: {
+ *     name: 'setBgColor',
+ *     extractValue: (p) => (p as { color: string }).color,
+ *   },
+ *   removeCommand: 'removeBgColor',
+ *   renderer: { apply(el, value) { el.style.backgroundColor = value as string; } },
+ * });
+ * ```
+ */
+export declare function defineParameterizedMark(config: ParameterizedMarkDef): WebPlugin;
+/**
+ * Input rule definition for {@link BlockTypeDef}.
+ */
+export interface BlockInputRuleDef {
+    /** Regex tested against block text after insert. Must match at block start. */
+    readonly pattern: RegExp;
+    /** If true, no further rules are tested after this one matches. */
+    readonly exclusive?: boolean;
+    /** Optional attrs to set on the block when the rule fires. */
+    readonly attrs?: Record<string, unknown>;
+}
+/**
+ * Shortcut definition for {@link BlockTypeDef}.
+ */
+export interface BlockShortcutDef {
+    /** The keyboard shortcut descriptor. */
+    readonly shortcut: ShortcutDescriptor;
+    /** Optional payload passed to the toggle command. */
+    readonly payload?: unknown;
+}
+/**
+ * Configuration for {@link defineBlockType}.
+ */
+export interface BlockTypeDef {
+    /** The block type string (e.g., "aside", "note"). */
+    readonly blockType: string;
+    /**
+     * Custom plugin ID. Defaults to `"block-<blockType>"`.
+     */
+    readonly pluginId?: string;
+    /** Default attrs applied when a block of this type is created. */
+    readonly defaultAttrs?: Record<string, unknown>;
+    /** Validator for block attrs. Return `true` if valid. */
+    readonly validate?: (attrs: Record<string, unknown>) => boolean;
+    /**
+     * Toggle command configuration.
+     *
+     * - A `string` registers a simple toggle command (no attrs).
+     * - An object with `name` and `attrs` registers a toggle with static attrs.
+     *
+     * Omit to skip command registration.
+     */
+    readonly toggleCommand?: string | {
+        readonly name: string;
+        readonly attrs?: Record<string, unknown>;
+    };
+    /**
+     * Input rules that convert typed prefixes into this block type.
+     * Each rule fires `delete_text` + `set_block_type` + optional `set_block_attrs`.
+     */
+    readonly inputRules?: ReadonlyArray<BlockInputRuleDef>;
+    /**
+     * Keyboard shortcuts. Each maps to the toggle command with optional payload.
+     * Requires `toggleCommand` to be set.
+     */
+    readonly shortcuts?: ReadonlyArray<BlockShortcutDef>;
+    /** The block renderer applied to block elements. */
+    readonly renderer: BlockRenderer;
+    /** Optional attr renderers keyed by attribute name. */
+    readonly attrRenderers?: Readonly<Record<string, BlockAttrRenderer>>;
+}
+/**
+ * Define a block type plugin.
+ *
+ * Creates a {@link WebPlugin} that registers a block type with optional
+ * validation, a toggle command via `createToggleBlockTypeCommand()`,
+ * input rules for prefix-based conversion, keyboard shortcuts, and
+ * a block renderer.
+ *
+ * @param config - Block type definition
+ * @returns A WebPlugin ready for `createWebEditor({ webPlugins: [...] })`
+ *
+ * @example
+ * ```ts
+ * const aside = defineBlockType({
+ *   blockType: 'aside',
+ *   toggleCommand: 'toggleAside',
+ *   inputRules: [{ pattern: /^!> $/, exclusive: true }],
+ *   shortcuts: [{ shortcut: { key: 'a', mod: true, alt: true } }],
+ *   renderer: { apply(el) { el.classList.add('rtif-aside'); } },
+ * });
+ * ```
+ */
+export declare function defineBlockType(config: BlockTypeDef): WebPlugin;
+/**
+ * Install an array of {@link WebPlugin} objects into an engine and renderer registries.
+ *
+ * For each plugin:
+ * 1. Calls `engine.use(wp.plugin)` to register the engine plugin.
+ * 2. Registers all mark renderers from `wp.marks`.
+ * 3. Registers all block renderers from `wp.blocks`.
+ * 4. Registers all attr renderers from `wp.attrs`.
+ * 5. Registers all span replacers from `wp.replacers`.
+ *
+ * @param plugins - The web plugins to install
+ * @param engine - The RTIF engine instance
+ * @param markRenderers - The mark renderer registry
+ * @param blockRenderers - The block renderer registry
+ *
+ * @example
+ * ```ts
+ * installWebPlugins([highlight, aside], engine, markRenderers, blockRenderers);
+ * ```
+ */
+export declare function installWebPlugins(plugins: ReadonlyArray<WebPlugin>, engine: IEditorEngine, markRenderers: MarkRendererRegistry, blockRenderers: BlockRendererRegistry): void;
+//# sourceMappingURL=plugin-kit.d.ts.map

package/dist/plugin-kit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-kit.d.ts","sourceRoot":"","sources":["../src/plugin-kit.ts"],"names":[],"mappings":"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"}

package/dist/plugin-kit.js

@@ -0,0 +1,234 @@
+/**
+ * Plugin kit — DX helper for defining custom RTIF web plugins.
+ *
+ * Provides typed factory functions that bundle an engine {@link Plugin} with
+ * web-layer renderers ({@link MarkRenderer}, {@link BlockRenderer},
+ * {@link BlockAttrRenderer}, {@link SpanReplacer}) in a single
+ * {@link WebPlugin} definition.
+ *
+ * Three factories cover the most common plugin patterns:
+ * - {@link defineBooleanMark} — on/off marks (highlight, subscript, etc.)
+ * - {@link defineParameterizedMark} — value-carrying marks (colors, sizes)
+ * - {@link defineBlockType} — toggle block types (aside, blockquote-style)
+ *
+ * The {@link installWebPlugins} utility registers all engine plugins and
+ * renderers from an array of {@link WebPlugin} objects.
+ *
+ * @module
+ */
+import { createToggleMarkCommand, createSetMarkCommand, createRemoveMarkCommand } from './plugins/mark-utils.js';
+import { createToggleBlockTypeCommand, getBlockStartOffset } from './plugins/block-utils.js';
+/**
+ * Define a boolean (on/off) mark plugin.
+ *
+ * Creates a {@link WebPlugin} that registers a mark type with `validate: v === true`,
+ * a toggle command via `createToggleMarkCommand()`, an optional keyboard shortcut,
+ * and a mark renderer.
+ *
+ * @param config - Boolean mark definition
+ * @returns A WebPlugin ready for `createWebEditor({ webPlugins: [...] })`
+ *
+ * @example
+ * ```ts
+ * const highlight = defineBooleanMark({
+ *   markType: 'highlight',
+ *   shortcut: { key: 'h', mod: true, shift: true },
+ *   renderer: { apply(el) { el.style.backgroundColor = 'yellow'; } },
+ * });
+ * ```
+ */
+export function defineBooleanMark(config) {
+    const { markType, pluginId = `mark-${markType}`, commandName = `toggleMark:${markType}`, shortcut, renderer, } = config;
+    const plugin = {
+        id: pluginId,
+        init(ctx) {
+            ctx.registerMarkType(markType, {
+                validate: (value) => value === true,
+            });
+            ctx.registerCommand(commandName, createToggleMarkCommand(markType));
+            if (shortcut) {
+                ctx.registerShortcut(shortcut, commandName);
+            }
+        },
+    };
+    return {
+        plugin,
+        marks: { [markType]: renderer },
+    };
+}
+/**
+ * Define a parameterized (value-carrying) mark plugin.
+ *
+ * Creates a {@link WebPlugin} that registers a mark type with custom validation,
+ * a "set" command via `createSetMarkCommand()`, a "remove" command via
+ * `createRemoveMarkCommand()`, optional keyboard shortcuts, and a mark renderer.
+ *
+ * @param config - Parameterized mark definition
+ * @returns A WebPlugin ready for `createWebEditor({ webPlugins: [...] })`
+ *
+ * @example
+ * ```ts
+ * const bgColor = defineParameterizedMark({
+ *   markType: 'bgColor',
+ *   validate: (v) => typeof v === 'string' && v.length > 0,
+ *   setCommand: {
+ *     name: 'setBgColor',
+ *     extractValue: (p) => (p as { color: string }).color,
+ *   },
+ *   removeCommand: 'removeBgColor',
+ *   renderer: { apply(el, value) { el.style.backgroundColor = value as string; } },
+ * });
+ * ```
+ */
+export function defineParameterizedMark(config) {
+    const { markType, pluginId = `mark-${markType}`, validate, setCommand, removeCommand, renderer, } = config;
+    const plugin = {
+        id: pluginId,
+        init(ctx) {
+            ctx.registerMarkType(markType, { validate });
+            ctx.registerCommand(setCommand.name, createSetMarkCommand(markType, setCommand.extractValue));
+            ctx.registerCommand(removeCommand, createRemoveMarkCommand(markType));
+            if (setCommand.shortcut) {
+                ctx.registerShortcut(setCommand.shortcut, setCommand.name);
+            }
+        },
+    };
+    return {
+        plugin,
+        marks: { [markType]: renderer },
+    };
+}
+/**
+ * Define a block type plugin.
+ *
+ * Creates a {@link WebPlugin} that registers a block type with optional
+ * validation, a toggle command via `createToggleBlockTypeCommand()`,
+ * input rules for prefix-based conversion, keyboard shortcuts, and
+ * a block renderer.
+ *
+ * @param config - Block type definition
+ * @returns A WebPlugin ready for `createWebEditor({ webPlugins: [...] })`
+ *
+ * @example
+ * ```ts
+ * const aside = defineBlockType({
+ *   blockType: 'aside',
+ *   toggleCommand: 'toggleAside',
+ *   inputRules: [{ pattern: /^!> $/, exclusive: true }],
+ *   shortcuts: [{ shortcut: { key: 'a', mod: true, alt: true } }],
+ *   renderer: { apply(el) { el.classList.add('rtif-aside'); } },
+ * });
+ * ```
+ */
+export function defineBlockType(config) {
+    const { blockType, pluginId = `block-${blockType}`, defaultAttrs, validate, toggleCommand, inputRules, shortcuts, renderer, attrRenderers, } = config;
+    // Resolve toggle command name and attrs
+    const commandName = typeof toggleCommand === 'string'
+        ? toggleCommand
+        : toggleCommand?.name;
+    const commandAttrs = typeof toggleCommand === 'object'
+        ? toggleCommand.attrs
+        : undefined;
+    const plugin = {
+        id: pluginId,
+        init(ctx) {
+            // Register block type
+            const blockConfig = {};
+            if (defaultAttrs !== undefined) {
+                blockConfig.defaultAttrs = defaultAttrs;
+            }
+            if (validate !== undefined) {
+                blockConfig.validate = validate;
+            }
+            ctx.registerBlockType(blockType, blockConfig);
+            // Register toggle command
+            if (commandName) {
+                ctx.registerCommand(commandName, createToggleBlockTypeCommand(blockType, commandAttrs));
+            }
+            // Register input rules
+            if (inputRules) {
+                for (const rule of inputRules) {
+                    ctx.registerInputRule({
+                        pattern: rule.pattern,
+                        exclusive: rule.exclusive,
+                        handler(engine, match, blockId) {
+                            const blockStart = getBlockStartOffset(engine.state.doc, blockId);
+                            const prefixLength = match[0].length;
+                            const ops = [
+                                { type: 'delete_text', offset: blockStart, count: prefixLength },
+                                { type: 'set_block_type', blockId, blockType },
+                            ];
+                            if (rule.attrs) {
+                                ops.push({ type: 'set_block_attrs', blockId, attrs: rule.attrs });
+                            }
+                            engine.dispatch(ops);
+                        },
+                    });
+                }
+            }
+            // Register shortcuts
+            if (shortcuts && commandName) {
+                for (const s of shortcuts) {
+                    ctx.registerShortcut(s.shortcut, commandName, s.payload);
+                }
+            }
+        },
+    };
+    const result = {
+        plugin,
+        blocks: { [blockType]: renderer },
+    };
+    if (attrRenderers && Object.keys(attrRenderers).length > 0) {
+        result.attrs = attrRenderers;
+    }
+    return result;
+}
+// ---------------------------------------------------------------------------
+// installWebPlugins
+// ---------------------------------------------------------------------------
+/**
+ * Install an array of {@link WebPlugin} objects into an engine and renderer registries.
+ *
+ * For each plugin:
+ * 1. Calls `engine.use(wp.plugin)` to register the engine plugin.
+ * 2. Registers all mark renderers from `wp.marks`.
+ * 3. Registers all block renderers from `wp.blocks`.
+ * 4. Registers all attr renderers from `wp.attrs`.
+ * 5. Registers all span replacers from `wp.replacers`.
+ *
+ * @param plugins - The web plugins to install
+ * @param engine - The RTIF engine instance
+ * @param markRenderers - The mark renderer registry
+ * @param blockRenderers - The block renderer registry
+ *
+ * @example
+ * ```ts
+ * installWebPlugins([highlight, aside], engine, markRenderers, blockRenderers);
+ * ```
+ */
+export function installWebPlugins(plugins, engine, markRenderers, blockRenderers) {
+    for (const wp of plugins) {
+        engine.use(wp.plugin);
+        if (wp.marks) {
+            for (const [markType, renderer] of Object.entries(wp.marks)) {
+                markRenderers.register(markType, renderer);
+            }
+        }
+        if (wp.blocks) {
+            for (const [blockType, renderer] of Object.entries(wp.blocks)) {
+                blockRenderers.register(blockType, renderer);
+            }
+        }
+        if (wp.attrs) {
+            for (const [attrName, renderer] of Object.entries(wp.attrs)) {
+                blockRenderers.registerAttrRenderer(attrName, renderer);
+            }
+        }
+        if (wp.replacers) {
+            for (const [markType, replacer] of Object.entries(wp.replacers)) {
+                markRenderers.registerReplacer(markType, replacer);
+            }
+        }
+    }
+}
+//# sourceMappingURL=plugin-kit.js.map

package/dist/plugin-kit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin-kit.js","sourceRoot":"","sources":["../src/plugin-kit.ts"],"names":[],"mappings":"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"}

package/dist/plugins/alignment-plugin.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Alignment paragraph formatting plugin — registers four commands that set or
+ * remove the `align` block attr on the block at the cursor.
+ *
+ * Unlike block type plugins, the alignment plugin does NOT change the block's
+ * `type`. It works on any block type by setting `attrs.align` via
+ * `set_block_attrs`.
+ *
+ * @module
+ */
+import type { Plugin } from '@rtif-sdk/engine';
+/**
+ * Command name constants for the alignment plugin.
+ *
+ * @example
+ * ```ts
+ * engine.exec(AlignmentCommands.CENTER);
+ * engine.exec(AlignmentCommands.LEFT);
+ * ```
+ */
+export declare const AlignmentCommands: {
+    readonly LEFT: "align:left";
+    readonly CENTER: "align:center";
+    readonly RIGHT: "align:right";
+    readonly JUSTIFY: "align:justify";
+};
+/**
+ * The four supported alignment values.
+ *
+ * `'left'` is the default alignment and is represented by the absence of the
+ * `align` attr (i.e., `align: null` or `align: undefined`).
+ *
+ * @example
+ * ```ts
+ * const alignment: Alignment = 'center';
+ * ```
+ */
+export type Alignment = 'left' | 'center' | 'right' | 'justify';
+/**
+ * Create the alignment paragraph formatting plugin.
+ *
+ * Registers four commands:
+ * - `align:left` — removes the `align` attr (left is the default)
+ * - `align:center` — sets `align` to `'center'`
+ * - `align:right` — sets `align` to `'right'`
+ * - `align:justify` — sets `align` to `'justify'`
+ *
+ * Each command's `isActive()` returns `true` when the cursor block has the
+ * matching alignment. `align:left` is active when there is no `align` attr.
+ *
+ * No input rules, no keyboard shortcuts, no block type registrations.
+ *
+ * @returns A plugin instance ready for `engine.use()`
+ *
+ * @example
+ * ```ts
+ * const engine = createEngine(initialDoc);
+ * engine.use(alignmentPlugin());
+ *
+ * // Center the block at the cursor
+ * engine.exec(AlignmentCommands.CENTER);
+ *
+ * // Revert to default left alignment
+ * engine.exec(AlignmentCommands.LEFT);
+ * ```
+ */
+export declare function alignmentPlugin(): Plugin;
+//# sourceMappingURL=alignment-plugin.d.ts.map

package/dist/plugins/alignment-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alignment-plugin.d.ts","sourceRoot":"","sources":["../../src/plugins/alignment-plugin.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAiB,MAAM,kBAAkB,CAAC;AAG9D;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB;;;;;CAKpB,CAAC;AAEX;;;;;;;;;;GAUG;AACH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,GAAG,SAAS,CAAC;AAkBhE;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AACH,wBAAgB,eAAe,IAAI,MAAM,CAgCxC"}

package/dist/plugins/alignment-plugin.js

@@ -0,0 +1,98 @@
+/**
+ * Alignment paragraph formatting plugin — registers four commands that set or
+ * remove the `align` block attr on the block at the cursor.
+ *
+ * Unlike block type plugins, the alignment plugin does NOT change the block's
+ * `type`. It works on any block type by setting `attrs.align` via
+ * `set_block_attrs`.
+ *
+ * @module
+ */
+import { getBlockAtCursor } from './block-utils.js';
+/**
+ * Command name constants for the alignment plugin.
+ *
+ * @example
+ * ```ts
+ * engine.exec(AlignmentCommands.CENTER);
+ * engine.exec(AlignmentCommands.LEFT);
+ * ```
+ */
+export const AlignmentCommands = {
+    LEFT: 'align:left',
+    CENTER: 'align:center',
+    RIGHT: 'align:right',
+    JUSTIFY: 'align:justify',
+};
+/**
+ * Read the current alignment of a block, defaulting to `'left'` when no
+ * `align` attr is present.
+ *
+ * @param engine - The editor engine instance
+ * @returns The current alignment of the cursor block
+ */
+function getCurrentAlignment(engine) {
+    const block = getBlockAtCursor(engine);
+    const align = block.attrs?.align;
+    if (align === 'center' || align === 'right' || align === 'justify') {
+        return align;
+    }
+    return 'left';
+}
+/**
+ * Create the alignment paragraph formatting plugin.
+ *
+ * Registers four commands:
+ * - `align:left` — removes the `align` attr (left is the default)
+ * - `align:center` — sets `align` to `'center'`
+ * - `align:right` — sets `align` to `'right'`
+ * - `align:justify` — sets `align` to `'justify'`
+ *
+ * Each command's `isActive()` returns `true` when the cursor block has the
+ * matching alignment. `align:left` is active when there is no `align` attr.
+ *
+ * No input rules, no keyboard shortcuts, no block type registrations.
+ *
+ * @returns A plugin instance ready for `engine.use()`
+ *
+ * @example
+ * ```ts
+ * const engine = createEngine(initialDoc);
+ * engine.use(alignmentPlugin());
+ *
+ * // Center the block at the cursor
+ * engine.exec(AlignmentCommands.CENTER);
+ *
+ * // Revert to default left alignment
+ * engine.exec(AlignmentCommands.LEFT);
+ * ```
+ */
+export function alignmentPlugin() {
+    return {
+        id: 'attr-alignment',
+        init(ctx) {
+            const alignments = ['left', 'center', 'right', 'justify'];
+            for (const alignment of alignments) {
+                ctx.registerCommand(`align:${alignment}`, {
+                    execute(engine) {
+                        const block = getBlockAtCursor(engine);
+                        // 'left' is the default — remove the attr instead of storing it
+                        const value = alignment === 'left' ? null : alignment;
+                        engine.dispatch({
+                            type: 'set_block_attrs',
+                            blockId: block.id,
+                            attrs: { align: value },
+                        });
+                    },
+                    canExecute(_engine) {
+                        return true;
+                    },
+                    isActive(engine) {
+                        return getCurrentAlignment(engine) === alignment;
+                    },
+                });
+            }
+        },
+    };
+}
+//# sourceMappingURL=alignment-plugin.js.map