inkpen 0.7.1

data/app/assets/javascripts/inkpen/controllers/sticky_toolbar_controller.js

@@ -0,0 +1,667 @@
+import { Controller } from "@hotwired/stimulus"
+
+/**
+ * Inkpen Sticky Toolbar Controller
+ *
+ * Fixed-position toolbar for block/media/widget insertion.
+ * Supports horizontal (bottom) and vertical (left/right) layouts.
+ *
+ * Follows Fizzy patterns:
+ * - Single responsibility (toolbar positioning + commands)
+ * - Declarative data-* configuration
+ * - Event-driven communication with editor
+ *
+ * Usage:
+ * <div data-controller="inkpen--editor inkpen--sticky-toolbar"
+ *      data-inkpen--sticky-toolbar-position-value="bottom"
+ *      data-inkpen--sticky-toolbar-buttons-value='["table","code_block","image"]'>
+ *   ...
+ * </div>
+ */
+export default class extends Controller {
+  static targets = ["button", "widgetModal", "widgetList"]
+
+  static values = {
+    position: { type: String, default: "bottom" },
+    buttons: { type: Array, default: [] },
+    widgetTypes: { type: Array, default: [] },
+    vertical: { type: Boolean, default: false },
+    showExport: { type: Boolean, default: false },
+    exportFormats: { type: Array, default: ["markdown", "html", "pdf"] }
+  }
+
+  #exportMenuOpen = false
+  #boundCloseExportMenu = null
+
+  connect() {
+    this.editorController = null
+    this.findEditorController()
+
+    // Prevent duplicate toolbars on reconnect
+    if (!this.toolbarElement) {
+      this.createToolbarElement()
+      this.buildToolbar()
+      this.applyLayout()
+    }
+
+    // Bind document click to close export menu
+    this.#boundCloseExportMenu = this.#closeExportMenuOnClickOutside.bind(this)
+    document.addEventListener("click", this.#boundCloseExportMenu)
+  }
+
+  disconnect() {
+    this.closeWidgetModal()
+    this.#closeExportMenu()
+    this.removeToolbarElement()
+    this.removeModalElement()
+    document.removeEventListener("click", this.#boundCloseExportMenu)
+  }
+
+  // --- Toolbar Element Management ---
+
+  createToolbarElement() {
+    // Create the sticky toolbar container as a sibling to the editor
+    this.toolbarElement = document.createElement("div")
+    this.toolbarElement.className = "inkpen-sticky-toolbar"
+
+    // Insert after the editor element
+    this.element.parentNode.insertBefore(this.toolbarElement, this.element.nextSibling)
+  }
+
+  removeToolbarElement() {
+    if (this.toolbarElement && this.toolbarElement.parentNode) {
+      this.toolbarElement.parentNode.removeChild(this.toolbarElement)
+    }
+  }
+
+  // Create modal element and append to body (avoids transform containing block issues)
+  createModalElement() {
+    // Prevent duplicate modals
+    if (this.modalElement) return
+
+    const wrapper = document.createElement("div")
+    wrapper.innerHTML = this.renderWidgetModal()
+    this.modalElement = wrapper.firstElementChild
+    document.body.appendChild(this.modalElement)
+
+    // Bind modal event handlers
+    this.bindModalEvents()
+  }
+
+  removeModalElement() {
+    if (this.modalElement && this.modalElement.parentNode) {
+      this.modalElement.parentNode.removeChild(this.modalElement)
+    }
+  }
+
+  bindModalEvents() {
+    if (!this.modalElement) return
+
+    const backdrop = this.modalElement.querySelector(".inkpen-widget-modal__backdrop")
+    if (backdrop) {
+      backdrop.addEventListener("click", () => this.closeWidgetModal())
+    }
+
+    const closeBtn = this.modalElement.querySelector(".inkpen-widget-modal__close")
+    if (closeBtn) {
+      closeBtn.addEventListener("click", () => this.closeWidgetModal())
+    }
+
+    this.modalElement.querySelectorAll("[data-widget-type]").forEach(btn => {
+      btn.addEventListener("click", (e) => this.insertWidget(e))
+    })
+  }
+
+  // --- Layout Management ---
+
+  applyLayout() {
+    if (!this.toolbarElement) return
+
+    this.toolbarElement.classList.toggle("inkpen-sticky-toolbar--vertical", this.verticalValue)
+    this.toolbarElement.classList.toggle("inkpen-sticky-toolbar--horizontal", !this.verticalValue)
+    this.toolbarElement.dataset.position = this.positionValue
+  }
+
+  positionValueChanged() {
+    this.verticalValue = ["left", "right"].includes(this.positionValue)
+    this.applyLayout()
+  }
+
+  // --- Toolbar Building ---
+
+  buildToolbar() {
+    if (!this.toolbarElement) return
+
+    const buttons = this.buttonsValue.length > 0 ? this.buttonsValue : this.defaultButtons()
+
+    // Build toolbar buttons only (modal is appended to body separately)
+    this.toolbarElement.innerHTML = `
+      <div class="inkpen-sticky-toolbar__buttons">
+        ${buttons.map(btn => this.renderButton(btn)).join("")}
+        ${this.showExportValue ? this.#renderExportButton() : ""}
+      </div>
+    `
+
+    // Bind toolbar button handlers
+    this.bindToolbarEvents()
+
+    // Create modal as child of body to avoid transform containing block issues
+    this.createModalElement()
+  }
+
+  bindToolbarEvents() {
+    if (!this.toolbarElement) return
+
+    // Button click handlers with mousedown prevention to preserve editor selection
+    this.toolbarElement.querySelectorAll("[data-command]").forEach(btn => {
+      btn.addEventListener("mousedown", (e) => e.preventDefault())
+      btn.addEventListener("click", (e) => this.executeCommand(e))
+    })
+
+    // Export menu toggle
+    const exportToggle = this.toolbarElement.querySelector("[data-export-toggle]")
+    if (exportToggle) {
+      exportToggle.addEventListener("mousedown", (e) => e.preventDefault())
+      exportToggle.addEventListener("click", (e) => {
+        e.stopPropagation()
+        this.#toggleExportMenu()
+      })
+    }
+
+    // Export menu item handlers
+    this.toolbarElement.querySelectorAll("[data-export-format]").forEach(btn => {
+      btn.addEventListener("mousedown", (e) => e.preventDefault())
+      btn.addEventListener("click", (e) => this.#handleExport(e))
+    })
+  }
+
+  defaultButtons() {
+    return ["table", "code_block", "divider", "image", "youtube", "divider", "widget"]
+  }
+
+  renderButton(btn) {
+    if (btn === "divider") {
+      return '<span class="inkpen-sticky-toolbar__divider"></span>'
+    }
+
+    const config = this.buttonConfig(btn)
+    return `
+      <button type="button"
+              class="inkpen-sticky-toolbar__btn"
+              data-command="${btn}"
+              title="${config.title}">
+        ${config.icon}
+      </button>
+    `
+  }
+
+  buttonConfig(name) {
+    const configs = {
+      table: {
+        title: "Insert Table",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="18" height="18" rx="2"/><line x1="3" y1="9" x2="21" y2="9"/><line x1="3" y1="15" x2="21" y2="15"/><line x1="9" y1="3" x2="9" y2="21"/><line x1="15" y1="3" x2="15" y2="21"/></svg>'
+      },
+      code_block: {
+        title: "Code Block",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><polyline points="16 18 22 12 16 6"/><polyline points="8 6 2 12 8 18"/></svg>'
+      },
+      blockquote: {
+        title: "Quote Block",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M3 21c3 0 7-1 7-8V5c0-1.25-.756-2.017-2-2H4c-1.25 0-2 .75-2 1.972V11c0 1.25.75 2 2 2 1 0 1 0 1 1v1c0 1-1 2-2 2s-1 .008-1 1.031V21z"/><path d="M15 21c3 0 7-1 7-8V5c0-1.25-.757-2.017-2-2h-4c-1.25 0-2 .75-2 1.972V11c0 1.25.75 2 2 2h.75c0 2.25.25 4-2.75 4v3z"/></svg>'
+      },
+      horizontal_rule: {
+        title: "Divider Line",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="3" y1="12" x2="21" y2="12"/></svg>'
+      },
+      task_list: {
+        title: "Task List",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="5" width="6" height="6" rx="1"/><path d="m3.5 8 2 2 3-3"/><line x1="13" y1="8" x2="21" y2="8"/><rect x="3" y="14" width="6" height="6" rx="1"/><line x1="13" y1="17" x2="21" y2="17"/></svg>'
+      },
+      image: {
+        title: "Insert Image",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="8.5" cy="8.5" r="1.5"/><path d="m21 15-5-5L5 21"/></svg>'
+      },
+      youtube: {
+        title: "YouTube Video",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M2.5 17a24.12 24.12 0 0 1 0-10 2 2 0 0 1 1.4-1.4 49.56 49.56 0 0 1 16.2 0A2 2 0 0 1 21.5 7a24.12 24.12 0 0 1 0 10 2 2 0 0 1-1.4 1.4 49.55 49.55 0 0 1-16.2 0A2 2 0 0 1 2.5 17"/><path d="m10 15 5-3-5-3z"/></svg>'
+      },
+      embed: {
+        title: "Embed Content",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m18 16 4-4-4-4"/><path d="m6 8-4 4 4 4"/><path d="m14.5 4-5 16"/></svg>'
+      },
+      widget: {
+        title: "Insert Widget",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="7" height="7" rx="1"/><rect x="14" y="3" width="7" height="7" rx="1"/><rect x="3" y="14" width="7" height="7" rx="1"/><rect x="14" y="14" width="7" height="7" rx="1"/></svg>'
+      },
+      section: {
+        title: "Insert Section",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="18" height="18" rx="2"/><line x1="3" y1="9" x2="21" y2="9"/><line x1="3" y1="15" x2="21" y2="15"/></svg>'
+      },
+      preformatted: {
+        title: "Preformatted Text (ASCII)",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="18" height="18" rx="2"/><text x="6" y="10" font-size="5" font-family="monospace" fill="currentColor">┌──┐</text><text x="6" y="15" font-size="5" font-family="monospace" fill="currentColor">│  │</text><text x="6" y="20" font-size="5" font-family="monospace" fill="currentColor">└──┘</text></svg>'
+      },
+      export: {
+        title: "Export",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4"/><polyline points="7 10 12 15 17 10"/><line x1="12" y1="15" x2="12" y2="3"/></svg>'
+      },
+      callout: {
+        title: "Callout Block",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="M12 2C6.48 2 2 6.48 2 12s4.48 10 10 10 10-4.48 10-10S17.52 2 12 2z"/><path d="M12 16v-4"/><path d="M12 8h.01"/></svg>'
+      },
+      toggle: {
+        title: "Toggle Block",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m9 18 6-6-6-6"/><line x1="4" y1="12" x2="15" y2="12"/><line x1="4" y1="6" x2="11" y2="6"/><line x1="4" y1="18" x2="11" y2="18"/></svg>'
+      },
+      columns: {
+        title: "Multi-Column Layout",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="18" height="18" rx="2"/><line x1="12" y1="3" x2="12" y2="21"/></svg>'
+      },
+      table_of_contents: {
+        title: "Table of Contents",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><line x1="4" y1="6" x2="20" y2="6"/><line x1="4" y1="12" x2="14" y2="12"/><line x1="4" y1="18" x2="18" y2="18"/><circle cx="4" cy="6" r="1" fill="currentColor"/><circle cx="4" cy="12" r="1" fill="currentColor"/><circle cx="4" cy="18" r="1" fill="currentColor"/></svg>'
+      },
+      file_attachment: {
+        title: "Attach File",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><path d="m21.44 11.05-9.19 9.19a6 6 0 0 1-8.49-8.49l8.57-8.57a4 4 0 1 1 5.66 5.66l-8.58 8.58a2 2 0 0 1-2.83-2.83l8.49-8.48"/></svg>'
+      }
+    }
+
+    return configs[name] || { title: name, icon: name }
+  }
+
+  #exportFormatConfig(format) {
+    const configs = {
+      markdown: {
+        label: "Markdown",
+        description: "Export as .md file",
+        icon: "M↓",
+        shortcut: "⌘⌥M"
+      },
+      html: {
+        label: "HTML",
+        description: "Export as .html file",
+        icon: "<>",
+        shortcut: "⌘⌥H"
+      },
+      pdf: {
+        label: "PDF",
+        description: "Export as .pdf file",
+        icon: "📄",
+        shortcut: "⌘⌥P"
+      },
+      copy_markdown: {
+        label: "Copy as Markdown",
+        description: "Copy content to clipboard",
+        icon: "📋",
+        shortcut: "⌘⌥⇧M"
+      },
+      copy_html: {
+        label: "Copy as HTML",
+        description: "Copy HTML to clipboard",
+        icon: "📋",
+        shortcut: "⌘⌥⇧H"
+      }
+    }
+
+    return configs[format] || { label: format, description: "", icon: "", shortcut: "" }
+  }
+
+  // --- Widget Modal ---
+
+  renderWidgetModal() {
+    const widgets = this.widgetTypesValue.length > 0 ? this.widgetTypesValue : ["form", "gallery", "poll"]
+
+    return `
+      <div class="inkpen-widget-modal hidden" role="dialog" aria-modal="true">
+        <div class="inkpen-widget-modal__backdrop"></div>
+        <div class="inkpen-widget-modal__content">
+          <div class="inkpen-widget-modal__header">
+            <h3>Insert Widget</h3>
+            <button type="button" class="inkpen-widget-modal__close">
+              <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+                <line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/>
+              </svg>
+            </button>
+          </div>
+          <div class="inkpen-widget-modal__list">
+            ${widgets.map(w => this.renderWidgetOption(w)).join("")}
+          </div>
+        </div>
+      </div>
+    `
+  }
+
+  renderWidgetOption(type) {
+    const config = this.widgetConfig(type)
+    return `
+      <button type="button" class="inkpen-widget-modal__option" data-widget-type="${type}">
+        <span class="inkpen-widget-modal__option-icon">${config.icon}</span>
+        <div class="inkpen-widget-modal__option-text">
+          <span class="inkpen-widget-modal__option-label">${config.label}</span>
+          <span class="inkpen-widget-modal__option-desc">${config.description}</span>
+        </div>
+      </button>
+    `
+  }
+
+  widgetConfig(type) {
+    const configs = {
+      form: {
+        label: "Form",
+        description: "Embed a contact or signup form",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="18" height="18" rx="2"/><line x1="7" y1="8" x2="17" y2="8"/><line x1="7" y1="12" x2="17" y2="12"/><line x1="7" y1="16" x2="12" y2="16"/></svg>'
+      },
+      gallery: {
+        label: "Gallery",
+        description: "Display an image gallery",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="18" height="18" rx="2"/><rect x="7" y="7" width="3" height="3"/><rect x="14" y="7" width="3" height="3"/><rect x="7" y="14" width="3" height="3"/><rect x="14" y="14" width="3" height="3"/></svg>'
+      },
+      poll: {
+        label: "Poll",
+        description: "Create an interactive poll",
+        icon: '<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"><rect x="3" y="3" width="18" height="18" rx="2"/><rect x="7" y="8" width="10" height="2"/><rect x="7" y="14" width="6" height="2"/></svg>'
+      }
+    }
+
+    return configs[type] || { label: type, description: "", icon: "" }
+  }
+
+  openWidgetModal() {
+    if (this.modalElement) {
+      this.modalElement.classList.remove("hidden")
+      document.body.style.overflow = "hidden"
+    }
+  }
+
+  closeWidgetModal() {
+    if (this.modalElement) {
+      this.modalElement.classList.add("hidden")
+      document.body.style.overflow = ""
+    }
+  }
+
+  insertWidget(event) {
+    const type = event.currentTarget.dataset.widgetType
+    this.closeWidgetModal()
+
+    // Dispatch event for host app to handle widget insertion
+    this.element.dispatchEvent(
+      new CustomEvent("inkpen:insert-widget", {
+        bubbles: true,
+        detail: { type, controller: this }
+      })
+    )
+  }
+
+  // --- Command Execution ---
+
+  findEditorController() {
+    // The sticky toolbar controller is on the same element as the editor controller
+    this.editorController = this.application.getControllerForElementAndIdentifier(
+      this.element,
+      "inkpen--editor"
+    )
+  }
+
+  executeCommand(event) {
+    const command = event.currentTarget.dataset.command
+    if (!this.editorController) {
+      this.findEditorController()
+    }
+    if (!this.editorController) return
+
+    switch (command) {
+      case "table":
+        this.editorController.insertTable(3, 3, true)
+        break
+      case "code_block":
+        this.editorController.toggleCodeBlock()
+        break
+      case "blockquote":
+        this.editorController.toggleBlockquote()
+        break
+      case "horizontal_rule":
+        this.editorController.insertHorizontalRule()
+        break
+      case "task_list":
+        this.editorController.toggleTaskList()
+        break
+      case "image":
+        this.promptForImage()
+        break
+      case "youtube":
+        this.promptForYoutubeUrl()
+        break
+      case "embed":
+        this.promptForEmbed()
+        break
+      case "widget":
+        this.openWidgetModal()
+        break
+      case "section":
+        this.editorController.insertSection()
+        break
+      case "preformatted":
+        this.editorController.insertPreformatted()
+        break
+      case "callout":
+        this.editorController.insertCallout()
+        break
+      case "toggle":
+        this.editorController.insertToggle()
+        break
+      case "columns":
+        this.editorController.insertColumns()
+        break
+      case "table_of_contents":
+        this.editorController.insertTableOfContents()
+        break
+      case "file_attachment":
+        this.promptForFileAttachment()
+        break
+    }
+  }
+
+  promptForFileAttachment() {
+    // Dispatch event for host app to handle file attachment
+    this.element.dispatchEvent(
+      new CustomEvent("inkpen:request-file", {
+        bubbles: true,
+        detail: { controller: this }
+      })
+    )
+  }
+
+  promptForImage() {
+    // Dispatch event for host app to handle image upload
+    this.element.dispatchEvent(
+      new CustomEvent("inkpen:request-image", {
+        bubbles: true,
+        detail: { controller: this }
+      })
+    )
+  }
+
+  promptForYoutubeUrl() {
+    const url = prompt("Enter YouTube URL:", "https://www.youtube.com/watch?v=")
+    if (url && url !== "https://www.youtube.com/watch?v=") {
+      this.editorController.insertYoutubeVideo(url)
+    }
+  }
+
+  promptForEmbed() {
+    // Dispatch event for host app to handle embed
+    this.element.dispatchEvent(
+      new CustomEvent("inkpen:request-embed", {
+        bubbles: true,
+        detail: { controller: this }
+      })
+    )
+  }
+
+  // --- Export Menu ---
+
+  #renderExportButton() {
+    const config = this.buttonConfig("export")
+    const formats = this.exportFormatsValue
+
+    return `
+      <span class="inkpen-sticky-toolbar__divider"></span>
+      <div class="inkpen-export-dropdown">
+        <button type="button"
+                class="inkpen-sticky-toolbar__btn inkpen-export-dropdown__toggle"
+                data-export-toggle
+                title="${config.title}">
+          ${config.icon}
+          <span class="inkpen-export-dropdown__caret">▾</span>
+        </button>
+        <div class="inkpen-export-dropdown__menu">
+          <div class="inkpen-export-dropdown__header">Download</div>
+          ${formats.map(format => this.#renderExportMenuItem(format)).join("")}
+          <div class="inkpen-export-dropdown__divider"></div>
+          <div class="inkpen-export-dropdown__header">Copy</div>
+          ${this.#renderExportMenuItem("copy_markdown")}
+          ${this.#renderExportMenuItem("copy_html")}
+        </div>
+      </div>
+    `
+  }
+
+  #renderExportMenuItem(format) {
+    const config = this.#exportFormatConfig(format)
+    return `
+      <button type="button"
+              class="inkpen-export-dropdown__item"
+              data-export-format="${format}">
+        <span class="inkpen-export-dropdown__icon">${config.icon}</span>
+        <span class="inkpen-export-dropdown__label">${config.label}</span>
+        ${config.shortcut ? `<span class="inkpen-export-dropdown__shortcut">${config.shortcut}</span>` : ""}
+      </button>
+    `
+  }
+
+  #toggleExportMenu() {
+    this.#exportMenuOpen = !this.#exportMenuOpen
+    const menu = this.toolbarElement?.querySelector(".inkpen-export-dropdown__menu")
+    const toggle = this.toolbarElement?.querySelector("[data-export-toggle]")
+
+    if (menu) {
+      menu.classList.toggle("is-open", this.#exportMenuOpen)
+    }
+    if (toggle) {
+      toggle.classList.toggle("is-active", this.#exportMenuOpen)
+    }
+  }
+
+  #closeExportMenu() {
+    this.#exportMenuOpen = false
+    const menu = this.toolbarElement?.querySelector(".inkpen-export-dropdown__menu")
+    const toggle = this.toolbarElement?.querySelector("[data-export-toggle]")
+
+    if (menu) {
+      menu.classList.remove("is-open")
+    }
+    if (toggle) {
+      toggle.classList.remove("is-active")
+    }
+  }
+
+  #closeExportMenuOnClickOutside(event) {
+    if (!this.#exportMenuOpen) return
+
+    const dropdown = this.toolbarElement?.querySelector(".inkpen-export-dropdown")
+    if (dropdown && !dropdown.contains(event.target)) {
+      this.#closeExportMenu()
+    }
+  }
+
+  async #handleExport(event) {
+    const format = event.currentTarget.dataset.exportFormat
+    this.#closeExportMenu()
+
+    if (!this.editorController) {
+      this.findEditorController()
+    }
+    if (!this.editorController) return
+
+    try {
+      switch (format) {
+        case "markdown":
+          this.editorController.downloadAsMarkdown()
+          this.#showExportSuccess("Downloaded as Markdown")
+          break
+        case "html":
+          this.editorController.downloadAsHTML()
+          this.#showExportSuccess("Downloaded as HTML")
+          break
+        case "pdf":
+          await this.editorController.downloadAsPDF()
+          this.#showExportSuccess("Downloaded as PDF")
+          break
+        case "copy_markdown":
+          const mdSuccess = await this.editorController.copyAsMarkdown()
+          if (mdSuccess) {
+            this.#showExportSuccess("Copied as Markdown")
+          }
+          break
+        case "copy_html":
+          const htmlSuccess = await this.editorController.copyAsHTML()
+          if (htmlSuccess) {
+            this.#showExportSuccess("Copied as HTML")
+          }
+          break
+      }
+    } catch (error) {
+      console.error("Export failed:", error)
+      this.#showExportError("Export failed")
+    }
+  }
+
+  #showExportSuccess(message) {
+    this.element.dispatchEvent(
+      new CustomEvent("inkpen:export-success", {
+        bubbles: true,
+        detail: { message, controller: this }
+      })
+    )
+  }
+
+  #showExportError(message) {
+    this.element.dispatchEvent(
+      new CustomEvent("inkpen:export-error", {
+        bubbles: true,
+        detail: { message, controller: this }
+      })
+    )
+  }
+
+  // --- Public API ---
+
+  /**
+   * Insert an image at the current cursor position.
+   * Call this from host app after uploading an image.
+   * @param {string} src - The image URL
+   * @param {string} alt - Alt text for the image
+   */
+  insertImage(src, alt = "") {
+    if (this.editorController?.editor) {
+      this.editorController.editor.chain().focus().setImage({ src, alt }).run()
+    }
+  }
+
+  /**
+   * Insert a widget placeholder at the current cursor position.
+   * @param {string} type - Widget type (form, gallery, poll)
+   * @param {object} data - Widget configuration data
+   */
+  insertWidgetBlock(type, data = {}) {
+    // Dispatch event with widget data for host app to insert custom node
+    this.element.dispatchEvent(
+      new CustomEvent("inkpen:widget-inserted", {
+        bubbles: true,
+        detail: { type, data, controller: this }
+      })
+    )
+  }
+}