tiptap-apcore 0.1.0

package/dist/builder/AnnotationCatalog.js

@@ -0,0 +1,269 @@
+/**
+ * AnnotationCatalog: Static mapping of TipTap command names to safety annotations.
+ *
+ * Maps all 79 known TipTap commands across 6 categories (query, format, content,
+ * destructive, selection, history) to their APCore annotation metadata.
+ */
+// ------------------------------------------------------------------
+// Shared annotation templates per category
+// ------------------------------------------------------------------
+const QUERY_ANNOTATIONS = Object.freeze({
+    readonly: true,
+    destructive: false,
+    idempotent: true,
+    requiresApproval: false,
+    openWorld: false,
+    streaming: false,
+});
+const FORMAT_ANNOTATIONS = Object.freeze({
+    readonly: false,
+    destructive: false,
+    idempotent: true,
+    requiresApproval: false,
+    openWorld: false,
+    streaming: false,
+});
+const FORMAT_NON_IDEMPOTENT_ANNOTATIONS = Object.freeze({
+    readonly: false,
+    destructive: false,
+    idempotent: false,
+    requiresApproval: false,
+    openWorld: false,
+    streaming: false,
+});
+const CONTENT_ANNOTATIONS = Object.freeze({
+    readonly: false,
+    destructive: false,
+    idempotent: false,
+    requiresApproval: false,
+    openWorld: false,
+    streaming: false,
+});
+const DESTRUCTIVE_ANNOTATIONS = Object.freeze({
+    readonly: false,
+    destructive: true,
+    idempotent: false,
+    requiresApproval: true,
+    openWorld: false,
+    streaming: false,
+});
+const SELECTION_ANNOTATIONS = Object.freeze({
+    readonly: false,
+    destructive: false,
+    idempotent: true,
+    requiresApproval: false,
+    openWorld: false,
+    streaming: false,
+});
+const HISTORY_ANNOTATIONS = Object.freeze({
+    readonly: false,
+    destructive: false,
+    idempotent: false,
+    requiresApproval: false,
+    openWorld: false,
+    streaming: false,
+});
+// ------------------------------------------------------------------
+// Helper to build an AnnotationEntry
+// ------------------------------------------------------------------
+function entry(annotations, tags, category, selectionEffect = "preserve") {
+    return { annotations, tags, category, selectionEffect };
+}
+// ------------------------------------------------------------------
+// Command lists per category
+// ------------------------------------------------------------------
+const QUERY_COMMANDS = [
+    "getHTML",
+    "getJSON",
+    "getText",
+    "isActive",
+    "getAttributes",
+    "isEmpty",
+    "isEditable",
+    "isFocused",
+    "getCharacterCount",
+    "getWordCount",
+];
+const FORMAT_COMMANDS = [
+    "toggleBold",
+    "toggleItalic",
+    "toggleStrike",
+    "toggleCode",
+    "toggleUnderline",
+    "toggleSubscript",
+    "toggleSuperscript",
+    "toggleHighlight",
+    "toggleHeading",
+    "toggleBulletList",
+    "toggleOrderedList",
+    "toggleTaskList",
+    "toggleCodeBlock",
+    "toggleBlockquote",
+    "setTextAlign",
+    "setMark",
+    "unsetMark",
+    "unsetAllMarks",
+    "clearNodes",
+    "updateAttributes",
+    "setLink",
+    "unsetLink",
+    "setBold",
+    "setItalic",
+    "setStrike",
+    "setCode",
+    "unsetBold",
+    "unsetItalic",
+    "unsetStrike",
+    "unsetCode",
+    "setBlockquote",
+    "unsetBlockquote",
+    "setHeading",
+    "setParagraph",
+];
+/** Format commands that are NOT idempotent (they insert new elements). */
+const FORMAT_NON_IDEMPOTENT_COMMANDS = [
+    "setHardBreak",
+    "setHorizontalRule",
+];
+const CONTENT_COMMANDS = [
+    "insertContent",
+    "insertContentAt",
+    "setNode",
+    "splitBlock",
+    "liftListItem",
+    "sinkListItem",
+    "wrapIn",
+    "joinBackward",
+    "joinForward",
+    "lift",
+    "splitListItem",
+    "wrapInList",
+    "toggleList",
+    "exitCode",
+    "deleteNode",
+];
+const DESTRUCTIVE_COMMANDS = [
+    "clearContent",
+    "setContent",
+    "deleteSelection",
+    "deleteRange",
+    "deleteCurrentNode",
+    "cut",
+];
+const SELECTION_COMMANDS = [
+    "setTextSelection",
+    "setNodeSelection",
+    "selectAll",
+    "selectParentNode",
+    "selectTextblockStart",
+    "selectTextblockEnd",
+    "selectText", // Custom APCore command (not native TipTap)
+    "focus",
+    "blur",
+    "scrollIntoView",
+];
+const HISTORY_COMMANDS = ["undo", "redo"];
+// ------------------------------------------------------------------
+// Build the full catalog map
+// ------------------------------------------------------------------
+// ------------------------------------------------------------------
+// Per-command selection effect overrides.
+// Default: category-level (query=preserve, format=require, content=destroy,
+//          destructive=destroy, selection=preserve, history=preserve).
+// Commands listed here override the category default.
+// ------------------------------------------------------------------
+/** Mark-level format commands that require an active text selection */
+const MARK_FORMAT_COMMANDS = new Set([
+    "toggleBold", "toggleItalic", "toggleStrike", "toggleCode",
+    "toggleUnderline", "toggleSubscript", "toggleSuperscript", "toggleHighlight",
+    "setBold", "setItalic", "setStrike", "setCode", "setLink",
+    "setMark", "unsetMark", "unsetAllMarks",
+    "unsetBold", "unsetItalic", "unsetStrike", "unsetCode", "unsetLink",
+]);
+/** Node-level format commands that operate on block at cursor (no selection needed) */
+const NODE_FORMAT_COMMANDS = new Set([
+    "toggleHeading", "setHeading", "setParagraph",
+    "toggleBlockquote", "setBlockquote", "unsetBlockquote",
+    "toggleBulletList", "toggleOrderedList", "toggleTaskList", "toggleCodeBlock",
+    "setTextAlign", "clearNodes", "updateAttributes",
+]);
+/** Category-level defaults for selectionEffect */
+const CATEGORY_SELECTION_DEFAULTS = {
+    query: "preserve",
+    format: "require", // overridden per-command below
+    content: "destroy",
+    destructive: "destroy",
+    selection: "preserve",
+    history: "preserve",
+};
+function getSelectionEffect(cmd, category) {
+    // Per-command overrides for format category
+    if (category === "format") {
+        if (MARK_FORMAT_COMMANDS.has(cmd))
+            return "require";
+        if (NODE_FORMAT_COMMANDS.has(cmd))
+            return "none";
+        // Non-idempotent formats (setHardBreak, setHorizontalRule) insert content
+        return "destroy";
+    }
+    // Content commands that don't destroy selection
+    if (category === "content") {
+        // List manipulation and structural commands preserve cursor context
+        if (["splitBlock", "liftListItem", "sinkListItem", "wrapIn",
+            "joinBackward", "joinForward", "lift", "splitListItem",
+            "wrapInList", "toggleList", "exitCode", "setNode"].includes(cmd)) {
+            return "none";
+        }
+        return "destroy";
+    }
+    return CATEGORY_SELECTION_DEFAULTS[category] ?? "preserve";
+}
+function buildCatalog() {
+    const map = new Map();
+    for (const cmd of QUERY_COMMANDS) {
+        map.set(cmd, entry(QUERY_ANNOTATIONS, ["query"], "query", getSelectionEffect(cmd, "query")));
+    }
+    for (const cmd of FORMAT_COMMANDS) {
+        map.set(cmd, entry(FORMAT_ANNOTATIONS, ["format"], "format", getSelectionEffect(cmd, "format")));
+    }
+    for (const cmd of FORMAT_NON_IDEMPOTENT_COMMANDS) {
+        map.set(cmd, entry(FORMAT_NON_IDEMPOTENT_ANNOTATIONS, ["format"], "format", getSelectionEffect(cmd, "format")));
+    }
+    for (const cmd of CONTENT_COMMANDS) {
+        map.set(cmd, entry(CONTENT_ANNOTATIONS, ["content"], "content", getSelectionEffect(cmd, "content")));
+    }
+    for (const cmd of DESTRUCTIVE_COMMANDS) {
+        map.set(cmd, entry(DESTRUCTIVE_ANNOTATIONS, ["destructive"], "destructive", getSelectionEffect(cmd, "destructive")));
+    }
+    for (const cmd of SELECTION_COMMANDS) {
+        map.set(cmd, entry(SELECTION_ANNOTATIONS, ["selection"], "selection", getSelectionEffect(cmd, "selection")));
+    }
+    for (const cmd of HISTORY_COMMANDS) {
+        map.set(cmd, entry(HISTORY_ANNOTATIONS, ["history"], "history", getSelectionEffect(cmd, "history")));
+    }
+    return map;
+}
+// ------------------------------------------------------------------
+// Public API
+// ------------------------------------------------------------------
+export class AnnotationCatalog {
+    catalog;
+    constructor() {
+        this.catalog = buildCatalog();
+    }
+    /**
+     * Look up the annotation entry for a command name.
+     * Returns `null` when the command is not in the catalog.
+     */
+    get(commandName) {
+        return this.catalog.get(commandName) ?? null;
+    }
+    /**
+     * Convenience helper that returns the category string for a command,
+     * or `"unknown"` when the command is not in the catalog.
+     */
+    getCategory(commandName) {
+        return this.catalog.get(commandName)?.category ?? "unknown";
+    }
+}
+//# sourceMappingURL=AnnotationCatalog.js.map

package/dist/builder/AnnotationCatalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AnnotationCatalog.js","sourceRoot":"","sources":["../../src/builder/AnnotationCatalog.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,qEAAqE;AACrE,2CAA2C;AAC3C,qEAAqE;AAErE,MAAM,iBAAiB,GAAsB,MAAM,CAAC,MAAM,CAAC;IACzD,QAAQ,EAAE,IAAI;IACd,WAAW,EAAE,KAAK;IAClB,UAAU,EAAE,IAAI;IAChB,gBAAgB,EAAE,KAAK;IACvB,SAAS,EAAE,KAAK;IAChB,SAAS,EAAE,KAAK;CACjB,CAAC,CAAC;AAEH,MAAM,kBAAkB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC1D,QAAQ,EAAE,KAAK;IACf,WAAW,EAAE,KAAK;IAClB,UAAU,EAAE,IAAI;IAChB,gBAAgB,EAAE,KAAK;IACvB,SAAS,EAAE,KAAK;IAChB,SAAS,EAAE,KAAK;CACjB,CAAC,CAAC;AAEH,MAAM,iCAAiC,GAAsB,MAAM,CAAC,MAAM,CAAC;IACzE,QAAQ,EAAE,KAAK;IACf,WAAW,EAAE,KAAK;IAClB,UAAU,EAAE,KAAK;IACjB,gBAAgB,EAAE,KAAK;IACvB,SAAS,EAAE,KAAK;IAChB,SAAS,EAAE,KAAK;CACjB,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC3D,QAAQ,EAAE,KAAK;IACf,WAAW,EAAE,KAAK;IAClB,UAAU,EAAE,KAAK;IACjB,gBAAgB,EAAE,KAAK;IACvB,SAAS,EAAE,KAAK;IAChB,SAAS,EAAE,KAAK;CACjB,CAAC,CAAC;AAEH,MAAM,uBAAuB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC/D,QAAQ,EAAE,KAAK;IACf,WAAW,EAAE,IAAI;IACjB,UAAU,EAAE,KAAK;IACjB,gBAAgB,EAAE,IAAI;IACtB,SAAS,EAAE,KAAK;IAChB,SAAS,EAAE,KAAK;CACjB,CAAC,CAAC;AAEH,MAAM,qBAAqB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC7D,QAAQ,EAAE,KAAK;IACf,WAAW,EAAE,KAAK;IAClB,UAAU,EAAE,IAAI;IAChB,gBAAgB,EAAE,KAAK;IACvB,SAAS,EAAE,KAAK;IAChB,SAAS,EAAE,KAAK;CACjB,CAAC,CAAC;AAEH,MAAM,mBAAmB,GAAsB,MAAM,CAAC,MAAM,CAAC;IAC3D,QAAQ,EAAE,KAAK;IACf,WAAW,EAAE,KAAK;IAClB,UAAU,EAAE,KAAK;IACjB,gBAAgB,EAAE,KAAK;IACvB,SAAS,EAAE,KAAK;IAChB,SAAS,EAAE,KAAK;CACjB,CAAC,CAAC;AAEH,qEAAqE;AACrE,qCAAqC;AACrC,qEAAqE;AAErE,SAAS,KAAK,CACZ,WAA8B,EAC9B,IAAc,EACd,QAAgB,EAChB,kBAAmC,UAAU;IAE7C,OAAO,EAAE,WAAW,EAAE,IAAI,EAAE,QAAQ,EAAE,eAAe,EAAE,CAAC;AAC1D,CAAC;AAED,qEAAqE;AACrE,6BAA6B;AAC7B,qEAAqE;AAErE,MAAM,cAAc,GAAa;IAC/B,SAAS;IACT,SAAS;IACT,SAAS;IACT,UAAU;IACV,eAAe;IACf,SAAS;IACT,YAAY;IACZ,WAAW;IACX,mBAAmB;IACnB,cAAc;CACf,CAAC;AAEF,MAAM,eAAe,GAAa;IAChC,YAAY;IACZ,cAAc;IACd,cAAc;IACd,YAAY;IACZ,iBAAiB;IACjB,iBAAiB;IACjB,mBAAmB;IACnB,iBAAiB;IACjB,eAAe;IACf,kBAAkB;IAClB,mBAAmB;IACnB,gBAAgB;IAChB,iBAAiB;IACjB,kBAAkB;IAClB,cAAc;IACd,SAAS;IACT,WAAW;IACX,eAAe;IACf,YAAY;IACZ,kBAAkB;IAClB,SAAS;IACT,WAAW;IACX,SAAS;IACT,WAAW;IACX,WAAW;IACX,SAAS;IACT,WAAW;IACX,aAAa;IACb,aAAa;IACb,WAAW;IACX,eAAe;IACf,iBAAiB;IACjB,YAAY;IACZ,cAAc;CACf,CAAC;AAEF,0EAA0E;AAC1E,MAAM,8BAA8B,GAAa;IAC/C,cAAc;IACd,mBAAmB;CACpB,CAAC;AAEF,MAAM,gBAAgB,GAAa;IACjC,eAAe;IACf,iBAAiB;IACjB,SAAS;IACT,YAAY;IACZ,cAAc;IACd,cAAc;IACd,QAAQ;IACR,cAAc;IACd,aAAa;IACb,MAAM;IACN,eAAe;IACf,YAAY;IACZ,YAAY;IACZ,UAAU;IACV,YAAY;CACb,CAAC;AAEF,MAAM,oBAAoB,GAAa;IACrC,cAAc;IACd,YAAY;IACZ,iBAAiB;IACjB,aAAa;IACb,mBAAmB;IACnB,KAAK;CACN,CAAC;AAEF,MAAM,kBAAkB,GAAa;IACnC,kBAAkB;IAClB,kBAAkB;IAClB,WAAW;IACX,kBAAkB;IAClB,sBAAsB;IACtB,oBAAoB;IACpB,YAAY,EAAE,4CAA4C;IAC1D,OAAO;IACP,MAAM;IACN,gBAAgB;CACjB,CAAC;AAEF,MAAM,gBAAgB,GAAa,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;AAEpD,qEAAqE;AACrE,6BAA6B;AAC7B,qEAAqE;AAErE,qEAAqE;AACrE,0CAA0C;AAC1C,4EAA4E;AAC5E,uEAAuE;AACvE,sDAAsD;AACtD,qEAAqE;AAErE,uEAAuE;AACvE,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC;IACnC,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,YAAY;IAC1D,iBAAiB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,iBAAiB;IAC5E,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,SAAS;IACzD,SAAS,EAAE,WAAW,EAAE,eAAe;IACvC,WAAW,EAAE,aAAa,EAAE,aAAa,EAAE,WAAW,EAAE,WAAW;CACpE,CAAC,CAAC;AAEH,uFAAuF;AACvF,MAAM,oBAAoB,GAAG,IAAI,GAAG,CAAC;IACnC,eAAe,EAAE,YAAY,EAAE,cAAc;IAC7C,kBAAkB,EAAE,eAAe,EAAE,iBAAiB;IACtD,kBAAkB,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,iBAAiB;IAC5E,cAAc,EAAE,YAAY,EAAE,kBAAkB;CACjD,CAAC,CAAC;AAEH,kDAAkD;AAClD,MAAM,2BAA2B,GAAoC;IACnE,KAAK,EAAE,UAAU;IACjB,MAAM,EAAE,SAAS,EAAO,+BAA+B;IACvD,OAAO,EAAE,SAAS;IAClB,WAAW,EAAE,SAAS;IACtB,SAAS,EAAE,UAAU;IACrB,OAAO,EAAE,UAAU;CACpB,CAAC;AAEF,SAAS,kBAAkB,CAAC,GAAW,EAAE,QAAgB;IACvD,4CAA4C;IAC5C,IAAI,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC1B,IAAI,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,SAAS,CAAC;QACpD,IAAI,oBAAoB,CAAC,GAAG,CAAC,GAAG,CAAC;YAAE,OAAO,MAAM,CAAC;QACjD,0EAA0E;QAC1E,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,gDAAgD;IAChD,IAAI,QAAQ,KAAK,SAAS,EAAE,CAAC;QAC3B,oEAAoE;QACpE,IAAI,CAAC,YAAY,EAAE,cAAc,EAAE,cAAc,EAAE,QAAQ;YACtD,cAAc,EAAE,aAAa,EAAE,MAAM,EAAE,eAAe;YACtD,YAAY,EAAE,YAAY,EAAE,UAAU,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC;YACtE,OAAO,MAAM,CAAC;QAChB,CAAC;QACD,OAAO,SAAS,CAAC;IACnB,CAAC;IACD,OAAO,2BAA2B,CAAC,QAAQ,CAAC,IAAI,UAAU,CAAC;AAC7D,CAAC;AAED,SAAS,YAAY;IACnB,MAAM,GAAG,GAAG,IAAI,GAAG,EAA2B,CAAC;IAE/C,KAAK,MAAM,GAAG,IAAI,cAAc,EAAE,CAAC;QACjC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,iBAAiB,EAAE,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,kBAAkB,CAAC,GAAG,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/F,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,eAAe,EAAE,CAAC;QAClC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,kBAAkB,EAAE,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,kBAAkB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,CAAC;IACnG,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,8BAA8B,EAAE,CAAC;QACjD,GAAG,CAAC,GAAG,CACL,GAAG,EACH,KAAK,CAAC,iCAAiC,EAAE,CAAC,QAAQ,CAAC,EAAE,QAAQ,EAAE,kBAAkB,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAClG,CAAC;IACJ,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACnC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,mBAAmB,EAAE,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,kBAAkB,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACvG,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,oBAAoB,EAAE,CAAC;QACvC,GAAG,CAAC,GAAG,CACL,GAAG,EACH,KAAK,CAAC,uBAAuB,EAAE,CAAC,aAAa,CAAC,EAAE,aAAa,EAAE,kBAAkB,CAAC,GAAG,EAAE,aAAa,CAAC,CAAC,CACvG,CAAC;IACJ,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,kBAAkB,EAAE,CAAC;QACrC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,qBAAqB,EAAE,CAAC,WAAW,CAAC,EAAE,WAAW,EAAE,kBAAkB,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC;IAC/G,CAAC;IAED,KAAK,MAAM,GAAG,IAAI,gBAAgB,EAAE,CAAC;QACnC,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,mBAAmB,EAAE,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,kBAAkB,CAAC,GAAG,EAAE,SAAS,CAAC,CAAC,CAAC,CAAC;IACvG,CAAC;IAED,OAAO,GAAG,CAAC;AACb,CAAC;AAED,qEAAqE;AACrE,aAAa;AACb,qEAAqE;AAErE,MAAM,OAAO,iBAAiB;IACpB,OAAO,CAA+B;IAE9C;QACE,IAAI,CAAC,OAAO,GAAG,YAAY,EAAE,CAAC;IAChC,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,WAAmB;QACrB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,IAAI,CAAC;IAC/C,CAAC;IAED;;;OAGG;IACH,WAAW,CAAC,WAAmB;QAC7B,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,WAAW,CAAC,EAAE,QAAQ,IAAI,SAAS,CAAC;IAC9D,CAAC;CACF"}

package/dist/builder/ModuleBuilder.d.ts

@@ -0,0 +1,42 @@
+/**
+ * ModuleBuilder: Transforms TipTap command names into APCore ModuleDescriptor objects.
+ *
+ * Combines metadata from the AnnotationCatalog (safety annotations, tags, categories)
+ * and SchemaCatalog (input/output JSON schemas) to produce complete ModuleDescriptor
+ * objects suitable for registration in an APCore Registry.
+ */
+import type { ModuleDescriptor, ExtensionCommandInfo } from "../types.js";
+export declare class ModuleBuilder {
+    private annotationCatalog;
+    private schemaCatalog;
+    private prefix;
+    constructor(prefix?: string);
+    /**
+     * Build a complete ModuleDescriptor for the given TipTap command.
+     */
+    build(commandName: string, extensionInfo: ExtensionCommandInfo): ModuleDescriptor;
+    /**
+     * Build the dot-separated module ID for a command.
+     *
+     * @example buildModuleId("toggleBold")      → "tiptap.format.toggleBold"
+     * @example buildModuleId("getHTML")          → "tiptap.query.getHTML"
+     * @example buildModuleId("clearContent")     → "tiptap.destructive.clearContent"
+     * @example buildModuleId("customCmd")        → "tiptap.unknown.customCmd"
+     */
+    buildModuleId(commandName: string, category?: string): string;
+    /**
+     * Generate a human-readable description string.
+     *
+     * Template: "<Verb> <humanized command name> (from <Extension> extension)"
+     */
+    private generateDescription;
+    /**
+     * Convert a camelCase command name into a human-readable phrase.
+     *
+     * "toggleBold"     → "toggle bold"
+     * "getHTML"         → "get HTML"
+     * "insertContentAt" → "insert content at"
+     */
+    private humanize;
+}
+//# sourceMappingURL=ModuleBuilder.d.ts.map

package/dist/builder/ModuleBuilder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ModuleBuilder.d.ts","sourceRoot":"","sources":["../../src/builder/ModuleBuilder.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAmC1E,qBAAa,aAAa;IACxB,OAAO,CAAC,iBAAiB,CAAoB;IAC7C,OAAO,CAAC,aAAa,CAAgB;IACrC,OAAO,CAAC,MAAM,CAAS;gBAEX,MAAM,GAAE,MAAiB;IAMrC;;OAEG;IACH,KAAK,CACH,WAAW,EAAE,MAAM,EACnB,aAAa,EAAE,oBAAoB,GAClC,gBAAgB;IAyBnB;;;;;;;OAOG;IACH,aAAa,CAAC,WAAW,EAAE,MAAM,EAAE,QAAQ,CAAC,EAAE,MAAM,GAAG,MAAM;IAM7D;;;;OAIG;IACH,OAAO,CAAC,mBAAmB;IAU3B;;;;;;OAMG;IACH,OAAO,CAAC,QAAQ;CAUjB"}

package/dist/builder/ModuleBuilder.js

@@ -0,0 +1,106 @@
+/**
+ * ModuleBuilder: Transforms TipTap command names into APCore ModuleDescriptor objects.
+ *
+ * Combines metadata from the AnnotationCatalog (safety annotations, tags, categories)
+ * and SchemaCatalog (input/output JSON schemas) to produce complete ModuleDescriptor
+ * objects suitable for registration in an APCore Registry.
+ */
+import { AnnotationCatalog } from "./AnnotationCatalog.js";
+import { SchemaCatalog } from "./SchemaCatalog.js";
+// ------------------------------------------------------------------
+// Description templates per category
+// ------------------------------------------------------------------
+const CATEGORY_VERB = {
+    query: "Query",
+    format: "Apply",
+    content: "Modify content via",
+    destructive: "Destructively perform",
+    selection: "Adjust selection via",
+    history: "Perform history action",
+    unknown: "Execute",
+};
+// ------------------------------------------------------------------
+// Default annotations for unknown commands
+// ------------------------------------------------------------------
+const DEFAULT_ANNOTATIONS = {
+    readonly: false,
+    destructive: false,
+    idempotent: false,
+    requiresApproval: false,
+    openWorld: false,
+    streaming: false,
+};
+// ------------------------------------------------------------------
+// Public API
+// ------------------------------------------------------------------
+export class ModuleBuilder {
+    annotationCatalog;
+    schemaCatalog;
+    prefix;
+    constructor(prefix = "tiptap") {
+        this.annotationCatalog = new AnnotationCatalog();
+        this.schemaCatalog = new SchemaCatalog();
+        this.prefix = prefix;
+    }
+    /**
+     * Build a complete ModuleDescriptor for the given TipTap command.
+     */
+    build(commandName, extensionInfo) {
+        const annotationEntry = this.annotationCatalog.get(commandName);
+        const schemaEntry = this.schemaCatalog.get(commandName);
+        const category = annotationEntry?.category ?? "unknown";
+        const moduleId = this.buildModuleId(commandName, category);
+        return {
+            moduleId,
+            description: this.generateDescription(commandName, extensionInfo, category),
+            inputSchema: schemaEntry.inputSchema,
+            outputSchema: schemaEntry.outputSchema,
+            annotations: annotationEntry?.annotations ?? { ...DEFAULT_ANNOTATIONS },
+            tags: annotationEntry?.tags ?? ["unknown"],
+            version: "0.1.0",
+            documentation: `https://tiptap.dev/docs/editor/api/commands/${commandName}`,
+            metadata: {
+                selectionEffect: annotationEntry?.selectionEffect ?? "preserve",
+            },
+        };
+    }
+    /**
+     * Build the dot-separated module ID for a command.
+     *
+     * @example buildModuleId("toggleBold")      → "tiptap.format.toggleBold"
+     * @example buildModuleId("getHTML")          → "tiptap.query.getHTML"
+     * @example buildModuleId("clearContent")     → "tiptap.destructive.clearContent"
+     * @example buildModuleId("customCmd")        → "tiptap.unknown.customCmd"
+     */
+    buildModuleId(commandName, category) {
+        const cat = category ?? this.annotationCatalog.getCategory(commandName);
+        return `${this.prefix}.${cat}.${commandName}`;
+    }
+    /**
+     * Generate a human-readable description string.
+     *
+     * Template: "<Verb> <humanized command name> (from <Extension> extension)"
+     */
+    generateDescription(commandName, extensionInfo, category) {
+        const verb = CATEGORY_VERB[category] ?? CATEGORY_VERB.unknown;
+        const humanized = this.humanize(commandName);
+        return `${verb} ${humanized} (from ${extensionInfo.extensionName} extension)`;
+    }
+    /**
+     * Convert a camelCase command name into a human-readable phrase.
+     *
+     * "toggleBold"     → "toggle bold"
+     * "getHTML"         → "get HTML"
+     * "insertContentAt" → "insert content at"
+     */
+    humanize(commandName) {
+        // Insert a space before each uppercase letter that follows a lowercase letter,
+        // or before a sequence of uppercase letters followed by a lowercase letter.
+        const spaced = commandName
+            .replace(/([a-z])([A-Z])/g, "$1 $2")
+            .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2");
+        // Lowercase the first character and preserve acronym casing
+        return spaced.charAt(0).toLowerCase() + spaced.slice(1);
+    }
+}
+//# sourceMappingURL=ModuleBuilder.js.map

package/dist/builder/ModuleBuilder.js.map

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

package/dist/builder/SchemaCatalog.d.ts

@@ -0,0 +1,20 @@
+/**
+ * SchemaCatalog: Static mapping of TipTap command names to JSON Schema
+ * input/output definitions.
+ *
+ * Every known command has explicit schemas with additionalProperties: false.
+ * Unknown commands fall back to a permissive default schema.
+ */
+import type { SchemaEntry } from "../types.js";
+export declare class SchemaCatalog {
+    private catalog;
+    private static readonly DEFAULT_ENTRY;
+    constructor();
+    /**
+     * Returns the SchemaEntry for the given command name.
+     * Falls back to a permissive default for unknown commands.
+     */
+    get(commandName: string): SchemaEntry;
+    private populate;
+}
+//# sourceMappingURL=SchemaCatalog.d.ts.map

package/dist/builder/SchemaCatalog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SchemaCatalog.d.ts","sourceRoot":"","sources":["../../src/builder/SchemaCatalog.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAc,MAAM,aAAa,CAAC;AAoF3D,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAA2B;IAE1C,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,aAAa,CAGnC;;IAOF;;;OAGG;IACH,GAAG,CAAC,WAAW,EAAE,MAAM,GAAG,WAAW;IAMrC,OAAO,CAAC,QAAQ;CAiiBjB"}