feat(metrics): markdown editor usage instrumentation

Adds new EVENT_TYPE.MD = "md" and instruments the high-value markdown
editor surfaces. All payloads are metadata-only — no markdown content,
file paths, image data, or user keystrokes cross any boundary.

Bridge:
- New mdviewrMetric event in MarkdownSync routes
  { kind, subcat, label, value? } from the iframe to Metrics.countEvent
  / valueEvent under EVENT_TYPE.MD with type validation.
- src-mdviewer/src/bridge.js exports metricCount / metricValue helpers
  iframe modules call directly.

Host-side metrics (MarkdownSync.js + main.js + EditorCommandHandlers):
- md/theme/{dark,light}     initial theme on iframe-ready, plus every
                            mdviewrThemeToggle.
- md/mode/{edit,reader}     every mode transition.
- md/doc/edited             at most once per file per session (first
                            iframe content change).
- md/upsell/shown           live-preview md edit upsell opens for a
                            free user (mirror of the existing
                            lp-edit/mdEditUpsell/show metric).
- md/image/pasteCM          image pasted in the CodeMirror markdown
                            editor.

Iframe-side metrics (via mdviewrMetric):
- md/nav/formatClick        bold / italic / strike / underline /
                            inline code / heading dropdown.
- md/nav/itemClick          every other top-toolbar button (link,
                            lists, task, quote, hr, table, codeblock,
                            image-url, image-upload).
- md/image/insert           image-insert toolbar buttons (paired
                            with the itemClick above for cross-
                            feature roll-up).
- md/image/pasteLP          image paste inside the LP iframe.
- md/print/click            print toolbar button.
- md/slash/popup            slash menu becomes visible.
- md/slash/select           a slash item was picked (no item id
                            recorded; recordUsage already tracks
                            local prioritisation).
- md/table/{rowEdit,colEdit} any row-handle / column-handle menu
                             action — single bucket per type so we
                             keep cardinality low.

Author: abose

src-mdviewer/src/bridge.js

@@ -1430,3 +1430,16 @@ function sendToParent(eventName, payload) {
         ...payload
     }, "*");
 }
+
+// ─── Metrics helpers ───────────────────────────────────────────────
+// Forwards metric events to the host (MarkdownSync.js) which routes them
+// to Metrics.countEvent / valueEvent under EVENT_TYPE.MD. Only metadata
+// (subcat, label, optional numeric value) crosses the boundary — never
+// markdown content, file paths, or user keystrokes.
+export function metricCount(subcat, label) {
+    sendToParent("mdviewrMetric", { kind: "count", subcat, label });
+}
+
+export function metricValue(subcat, label, value) {
+    sendToParent("mdviewrMetric", { kind: "value", subcat, label, value });
+}

src-mdviewer/src/components/editor.js

@@ -12,6 +12,7 @@ import { initImagePopover, destroyImagePopover } from "./image-popover.js";
 import { initLangPicker, destroyLangPicker, isLangPickerDropdownOpen } from "./lang-picker.js";
 import { highlightCode, renderAfterHTML, normalizeCodeLanguages } from "./viewer.js";
 import { initMermaidEditor, destroyMermaidEditor, insertMermaidBlock, attachOverlays } from "./mermaid-editor.js";
+import { metricCount } from "../bridge.js";
 
 const devLog = import.meta.env.DEV ? console.log.bind(console, "[editor]") : () => {};
 let turndown = null;
@@ -713,6 +714,10 @@ function handleImagePaste(e, contentEl) {
     for (let i = 0; i < items.length; i++) {
         if (items[i].kind === "file" && ALLOWED_IMAGE_TYPES.includes(items[i].type)) {
             e.preventDefault();
+            // Image paste in the live-preview iframe (paired with
+            // md/image/pasteCM for the CodeMirror editor path). No
+            // image data is recorded — just the count.
+            metricCount("image", "pasteLP");
             const blob = items[i].getAsFile();
             const fileName = blob.name || ("image." + blob.type.split("/")[1]);
             const uploadId = _insertUploadPlaceholder(contentEl);
@@ -1005,6 +1010,17 @@ function showHandleMenu(anchor, type, ctx, contentEl, wrapper, clickX) {
         ];
     }
 
+    // Wrap each action so picking any row/col menu item raises a single
+    // metric (md/table/rowEdit or colEdit). We don't record which
+    // specific edit — just that one happened — to keep cardinality low.
+    const editLabel = type === "row" ? "rowEdit" : "colEdit";
+    items.forEach((it) => {
+        if (it.action) {
+            const orig = it.action;
+            it.action = () => { metricCount("table", editLabel); orig(); };
+        }
+    });
+
     menu.innerHTML = "";
     items.forEach((item) => {
         if (item.divider) {

src-mdviewer/src/components/embedded-toolbar.js

@@ -40,6 +40,16 @@ import {
 import { on, emit } from "../core/events.js";
 import { getState, setState } from "../core/state.js";
 import { t, tp } from "../core/i18n.js";
+import { metricCount } from "../bridge.js";
+
+// Toolbar buttons whose clicks roll up under md/nav/formatClick (text-
+// formatting and heading switches). Anything not in this set is treated
+// as a generic md/nav/itemClick so we capture toolbar usage without
+// fragmenting the metric across every button id.
+const FORMAT_CLICK_IDS = new Set([
+    "emb-bold", "emb-italic", "emb-strike", "emb-underline", "emb-code",
+    "emb-block-type" // heading dropdown
+]);
 
 let toolbar = null;
 let resizeObserver = null;
@@ -264,6 +274,14 @@ function wireFormatButtons() {
         if (el) {
             el.addEventListener("mousedown", (e) => {
                 e.preventDefault();
+                // Generic toolbar usage metric: format vs item bucket.
+                // Image insert specifically is also tracked under
+                // md/image/insert below for cross-feature roll-up.
+                metricCount("nav",
+                    FORMAT_CLICK_IDS.has(binding.id) ? "formatClick" : "itemClick");
+                if (binding.id === "emb-image-url" || binding.id === "emb-image-upload") {
+                    metricCount("image", "insert");
+                }
                 emit("action:format", { command: binding.command, value: binding.value });
             });
         }
@@ -274,6 +292,9 @@ function wireBlockTypeSelect() {
     const blockTypeSelect = document.getElementById("emb-block-type");
     if (blockTypeSelect) {
         blockTypeSelect.addEventListener("change", (e) => {
+            // Heading dropdown rolls up under formatClick (heading
+            // selection is a formatting action, just delivered via select).
+            metricCount("nav", "formatClick");
             emit("action:format", { command: "formatBlock", value: e.target.value });
             e.target.blur();
         });
@@ -347,6 +368,7 @@ function wirePrintButton() {
     const printBtn = document.getElementById("emb-print-btn");
     if (printBtn) {
         printBtn.addEventListener("click", () => {
+            metricCount("print", "click");
             window.print();
         });
     }

src-mdviewer/src/components/slash-menu.js

@@ -20,6 +20,7 @@ import {
 import { emit } from "../core/events.js";
 import { getSelectionRect } from "./editor.js";
 import { t } from "../core/i18n.js";
+import { metricCount } from "../bridge.js";
 
 let menu = null;
 let contentEl = null;
@@ -221,6 +222,9 @@ function show() {
   const rect = _savedSlashRect;
   const anchor = document.getElementById("slash-menu-anchor");
   if (!anchor) return;
+  // Slash popup appearance metric — fires when the menu actually
+  // becomes visible, not on every keystroke that filters items.
+  metricCount("slash", "popup");
 
   // Position anchor below the cursor line with gap
   const lineHeight = rect.bottom - rect.top;
@@ -273,6 +277,9 @@ function selectItem(index) {
   if (index < 0 || index >= filteredItems.length) return;
   const item = filteredItems[index];
   recordUsage(item.labelKey);
+  // Slash selection metric — does not record which item was picked
+  // (recordUsage already tracks that locally for prioritisation).
+  metricCount("slash", "select");
 
   // Capture slashRange before hide() clears it
   const savedRange = slashRange;

src/editor/EditorCommandHandlers.js

@@ -41,6 +41,7 @@ define(function (require, exports, module) {
         ChangeHelper = require("editor/EditorHelper/ChangeHelper"),
         LanguageManager = require("language/LanguageManager"),
         ImageUploadManager = require("features/ImageUploadManager"),
+        Metrics = require("utils/Metrics"),
         Dialogs = require("widgets/Dialogs"),
         AppInit = require("utils/AppInit");
 
@@ -1316,6 +1317,11 @@ define(function (require, exports, module) {
 
         event.preventDefault();
 
+        // Metric: image paste in the CodeMirror markdown editor view
+        // (paired with md/image/pasteLP for the live-preview iframe path).
+        // No image data or filename is recorded — just the count.
+        Metrics.countEvent(Metrics.EVENT_TYPE.MD, "image", "pasteCM");
+
         const blob = imageItem.getAsFile();
         const fileName = blob.name || ("image." + blob.type.split("/")[1]);
         const provider = ImageUploadManager.getImageUploadProvider();

src/extensionsIntegrated/Phoenix-live-preview/MarkdownSync.js

@@ -29,6 +29,7 @@ define(function (require, exports, module) {
         CommandManager = require("command/CommandManager"),
         Commands = require("command/Commands"),
         KeyBindingManager = require("command/KeyBindingManager"),
+        Metrics = require("utils/Metrics"),
         utils = require("./utils");
 
     // Commands whose shortcuts, when forwarded from the md viewer iframe,
@@ -42,6 +43,11 @@ define(function (require, exports, module) {
         Commands.CMD_FIND_IN_FILES
     ];
 
+    // Set of file paths the user has edited in the markdown viewer this
+    // session. Used to fire md/doc/edited at most once per file so the
+    // metric tells us "users who edit at least one md doc" without
+    // inflating with every keystroke.
+    const _mdEditedFiles = new Set();
     let _active = false;
     let _doc = null;
     let _$iframe = null;
@@ -127,6 +133,12 @@ define(function (require, exports, module) {
                 _handleRedo();
                 break;
             case "mdviewrEditModeChanged":
+                // Mode switch metric — reader/edit are the only two
+                // states the iframe reports. Fires on every transition
+                // (including init) so we see how often users go in and
+                // out of edit mode.
+                Metrics.countEvent(Metrics.EVENT_TYPE.MD, "mode",
+                    data.editMode ? "edit" : "reader");
                 // When switching to reader, send CM content so the iframe
                 // can re-render with accurate data-source-line for cursor sync.
                 if (!data.editMode && _doc) {
@@ -161,6 +173,30 @@ define(function (require, exports, module) {
                 if (_onThemeToggle) {
                     _onThemeToggle(data.theme);
                 }
+                // Theme switch metric — fires on every user toggle. The
+                // initial state (light vs dark) is reported separately
+                // when the viewer first activates a markdown doc.
+                if (data.theme === "dark" || data.theme === "light") {
+                    Metrics.countEvent(Metrics.EVENT_TYPE.MD, "theme", data.theme);
+                }
+                break;
+            case "mdviewrMetric":
+                // Generic metric forwarder for events the iframe wants
+                // to record. Schema:
+                //   { kind: "count" | "value", subcat, label, [value] }
+                // We validate types before forwarding so a malformed
+                // payload from the iframe can't break the metrics
+                // pipeline. Category is always EVENT_TYPE.MD.
+                if (data && typeof data.subcat === "string" && data.subcat &&
+                        typeof data.label === "string" && data.label) {
+                    if (data.kind === "value" && Number.isFinite(data.value)) {
+                        Metrics.valueEvent(Metrics.EVENT_TYPE.MD,
+                            data.subcat, data.label, data.value);
+                    } else {
+                        Metrics.countEvent(Metrics.EVENT_TYPE.MD,
+                            data.subcat, data.label);
+                    }
+                }
                 break;
             case "mdviewrImageUploadRequest":
                 _handleImageUploadFromIframe(data);
@@ -390,6 +426,15 @@ define(function (require, exports, module) {
         _sendTheme();
         _sendLocale();
         _sendSkipRefocusShortcuts();
+        // Record the effective theme the user is starting in
+        // (light vs dark). Mirror of mdviewrThemeToggle so the dark/
+        // light counter reflects both initial state and toggles.
+        const initialTheme = _themeOverride
+            || ((ThemeManager.getCurrentTheme() && ThemeManager.getCurrentTheme().dark)
+                ? "dark" : "light");
+        if (initialTheme === "dark" || initialTheme === "light") {
+            Metrics.countEvent(Metrics.EVENT_TYPE.MD, "theme", initialTheme);
+        }
         if (_onIframeReadyCallback) {
             _onIframeReadyCallback();
         }
@@ -622,6 +667,14 @@ define(function (require, exports, module) {
 
         _applyDiffToEditor(markdown);
 
+        // First-edit metric per file per session — fires at most once
+        // per document so "users who edit any md file" is a clean count.
+        const editedPath = _doc && _doc.file && _doc.file.fullPath;
+        if (editedPath && !_mdEditedFiles.has(editedPath)) {
+            _mdEditedFiles.add(editedPath);
+            Metrics.countEvent(Metrics.EVENT_TYPE.MD, "doc", "edited");
+        }
+
         // Send back the actual CM text so the iframe can compute accurate
         // data-source-line attributes. The markdown from convertToMarkdown
         // may differ slightly from CM's content (e.g. table formatting),

src/extensionsIntegrated/Phoenix-live-preview/main.js

@@ -1626,6 +1626,9 @@ define(function (require, exports, module) {
                         text: buttonGetProText }
                 ];
                 Metrics.countEvent(Metrics.EVENT_TYPE.LP_EDIT, "mdEditUpsell", "show");
+                // Mirror under the MD category so it groups with the rest
+                // of the markdown-editor metrics on the dashboard.
+                Metrics.countEvent(Metrics.EVENT_TYPE.MD, "upsell", "shown");
                 Dialogs.showModalDialog(Dialogs.DIALOG_ID_INFO,
                     Strings.AVAILABLE_IN_PRO_TITLE,
                     Strings.MD_EDIT_UPSELL_MESSAGE, buttons)

src/utils/Metrics.js

@@ -131,6 +131,7 @@ define(function (require, exports, module) {
         PRO: "pro",
         AI: "ai",
         TERMINAL: "term",
+        MD: "md",
         GUIDE: "guide"
     };