P3-01: Plugin system (dylib-based)

[hybridmachine]

Description

Dynamic plugin loading system for extending the editor.

Implementation

• dlopen/dlsym based plugin loading from ~/Library/Application Support/MacNote++/plugins/
• C interface similar to Windows N++ plugin API
• Required exports: setInfo, getName, getFuncsArray, beNotified, messageProc
• Plugin menu integration (Plugins menu populated from loaded plugins)
• Plugin Admin panel for enable/disable
• Plugin API documentation
• Sample plugin project

Key Files

• macos/platform/main_phase7.mm (or new plugin_manager files)

[hybridmachine]

Implementation Plan: Source-Code-Compatible Plugin System

Goal

A Notepad++ plugin developer can take their existing plugin source, compile it on macOS (producing a .dylib instead of .dll), and load it into MacNote++ with zero source code changes.

Strategic Decision: New Plugin Loader

Build a new, lightweight MacPluginManager rather than wiring up the existing PluginsManager.cpp. The existing code has deep dependencies on NppParameters, pluginsAdmin (WinInet), NppXml, Version, and shortcut.h — none of which are functional in the macOS port. The core loading logic is ~80 lines of dlsym calls + setInfo + getFuncsArray + menu building, which we reimplement cleanly atop the existing Win32 shim.

---

Step 1: Plugin Manager Core

New files: macos/platform/plugin_manager.h, macos/platform/plugin_manager.mm

• MacPluginInfo struct: HINSTANCE _hLib, HMENU _pluginMenu, 6 function pointers (same types as PluginInterface.h), FuncItem*, int _nbFuncItem, std::wstring _moduleName
• MacPluginManager class:
  • init(const NppData&) — stores handles for main window + both Scintilla views
  • loadPlugins() — scans ~/Library/Application Support/MacNote++/plugins/ via NSFileManager. For each subdirectory <Name>, looks for <Name>/<Name>.dylib
  • loadPluginFromPath() — Mach-O arch validation (<mach-o/loader.h>), then LoadLibraryExW → GetProcAddress for all 6 exports → setInfo() → getFuncsArray() → CreateMenu()
  • initMenu(HMENU) — populates Plugins submenu with per-plugin submenus
  • runPluginCommand(size_t) — executes matching PFUNCPLUGINCMD
  • notify(const SCNotification*) — broadcasts to all plugins' beNotified
  • relayNppMessages() — calls messageProc on all plugins
  • allocateCmdID/allocateMarker/allocateIndicator — using IDAllocator from PowerEditor/src/MISC/PluginsManager/IDAllocator.h
• Command ID ranges from resource.h: ID_PLUGINS_CMD (22000) through ID_PLUGINS_CMD_DYNAMIC_LIMIT (24999)

Step 2: Plugin Menu Integration

Modify: macos/platform/menu_builder.mm

Insert a "Plugins" submenu between "Tools" and "Language" (after line 197). Starts empty — MacPluginManager::initMenu() populates it after plugins load.

Step 3: Wire Plugin Commands into WndProc

Modify: macos/platform/wndproc.mm

Add range check in WM_COMMAND handler for plugin command IDs (22000–24999) → routes to pluginManager().runPluginCommand().

Step 4: NPPM_* Message Handler

New files: macos/platform/nppm_handler.h, macos/platform/nppm_handler.mm

Handles SendMessage(nppHandle, NPPM_*, wParam, lParam) calls from plugins. Route in MainWndProc for NPPMSG range (WM_USER+1000 through +1200).

Minimum viable messages (20):

Message	Implementation
NPPM_GETCURRENTSCINTILLA	ctx().activeView via *(int*)lParam
NPPM_GETCURRENTLANGTYPE	Active doc's languageIndex
NPPM_SETCURRENTLANGTYPE	applyLanguage(lParam)
NPPM_GETNBOPENFILES	docs.size() for requested view
NPPM_GETCURRENTBUFFERID	Active doc index
NPPM_GETFULLCURRENTPATH	Active doc's filePath → (wchar_t*)lParam
NPPM_GETFILENAME	Extract filename from path
NPPM_GETCURRENTDIRECTORY	Extract directory from path
NPPM_GETNAMEPART	Filename without extension
NPPM_GETEXTPART	File extension
NPPM_GETNPPVERSION	Hardcoded version
NPPM_GETPLUGINSCONFIGDIR	~/Library/Application Support/MacNote++/plugins/Config/
NPPM_GETCURRENTVIEW	ctx().activeView
NPPM_SETMENUITEMCHECK	CheckMenuItem(hMenu, cmdId, checked)
NPPM_MENUCOMMAND	SendMessage(hWnd, WM_COMMAND, lParam, 0)
NPPM_ALLOCATECMDID	pluginManager().allocateCmdID()
NPPM_ALLOCATEMARKER	pluginManager().allocateMarker()
NPPM_ALLOCATEINDICATOR	pluginManager().allocateIndicator()
NPPM_GETCURRENTLINE	Scintilla SCI_LINEFROMPOSITION(SCI_GETCURRENTPOS)
NPPM_GETCURRENTCOLUMN	Scintilla SCI_GETCOLUMN(SCI_GETCURRENTPOS)

Unhandled messages return 0 with NSLog debug, allowing gradual expansion.

Step 5: SCNotification Forwarding to Plugins

Modify: macos/platform/app_delegate.mm (line 262-372 notification callback)

After existing notification handling, forward to plugins:

pluginManager().notify(reinterpret_cast<const SCNotification*>(scn));

NPPN_ lifecycle notifications:*

Notification	Where
NPPN_READY	End of applicationDidFinishLaunching:
NPPN_SHUTDOWN	Start of applicationWillTerminate:
NPPN_FILEOPENED	file_operations.mm after open
NPPN_FILESAVED	file_operations.mm after save
NPPN_FILEBEFORECLOSE / NPPN_FILECLOSED	document_manager.mm around tab close
NPPN_BUFFERACTIVATED	document_manager.mm after tab switch
NPPN_LANGCHANGED	wndproc.mm after language change

Also modify: macos/platform/split_view.mm — same forwarding for view 2's callback.

Step 6: Plugin Initialization in App Lifecycle

Modify: macos/platform/app_delegate.mm

In applicationDidFinishLaunching:, after Scintilla setup and menu bar creation (~line 258):

1. Create plugin directory if missing
2. Init pluginManager() with NppData (main HWND + both Scintilla HWNDs)
3. Call loadPlugins() and initMenu()
4. At end of method, broadcast NPPN_READY

Step 7: Plugin SDK Package

New directory: macos/plugin-sdk/

macos/plugin-sdk/
    include/           (symlinks or copies)
        PluginInterface.h, Notepad_plus_msgs.h, menuCmdID.h,
        Scintilla.h, Sci_Position.h
    shim/              (symlinks to macos/shim/include/)
        windows.h, windef.h, winnt.h, winuser.h, winbase.h, etc.
    example/
        HelloMacNote/
            HelloMacNote.cpp   (standard N++ plugin)
            CMakeLists.txt
    CMakeLists.txt             (SDK-level CMake for building plugins)

Step 8: Sample Plugin (HelloMacNote)

New file: macos/plugin-sdk/example/HelloMacNote/HelloMacNote.cpp

Standard N++ plugin exercising:

• All 6 required exports
• Menu commands: "Hello World" (MessageBox), "Insert Timestamp" (NPPM_GETCURRENTSCINTILLA + SCI_REPLACESEL), "Show Version" (NPPM_GETNPPVERSION)
• NPPN_READY / NPPN_SHUTDOWN handling
• Compiles identically on Windows (.dll) and macOS (.dylib) with no #ifdef

Step 9: Build System Changes

Modify: macos/CMakeLists.txt

1. Add plugin_manager.mm and nppm_handler.mm to MacNotePlusPlus target
2. Add include path for IDAllocator.h: ${NPP_SRC_DIR}/MISC/PluginsManager
3. Add HelloMacNote MODULE library target
4. Post-build step copies .dylib to ~/Library/Application Support/MacNote++/plugins/HelloMacNote/

---

Known Limitations (deferred, not blocked)

• Docking manager: NPPM_DMMREGASDCKDLG not implemented. Plugins requiring dockable panels won't have panels visible.
• Lexer plugins: Lexilla plugin detection (GetLexerCount/CreateLexer) deferred. Standard command-based plugins work first.
• Plugin Admin: No marketplace/update UI. Manual install only.
• Complex dialogs: Plugins using custom Win32 controls beyond MessageBox/simple dialogs need additional shim work.

---

Verification

1. Build MacNotePlusPlus — compiles with new files
2. Build HelloMacNote.dylib — compiles using only standard N++ plugin headers
3. Launch app — "Plugins" menu appears with "HelloMacNote" submenu
4. Click "Hello World" — MessageBox appears
5. Click "Insert Timestamp" — text inserted at cursor
6. Click "Show Version" — displays version
7. Console.app shows NPPN_READY/NPPN_SHUTDOWN lifecycle notifications
8. HelloMacNote.cpp compiles on Windows targeting .dll with no #ifdef __APPLE__

Critical Files

Action	File
Create	macos/platform/plugin_manager.h
Create	macos/platform/plugin_manager.mm
Create	macos/platform/nppm_handler.h
Create	macos/platform/nppm_handler.mm
Create	macos/plugin-sdk/example/HelloMacNote/HelloMacNote.cpp
Create	macos/plugin-sdk/example/HelloMacNote/CMakeLists.txt
Create	macos/plugin-sdk/CMakeLists.txt
Modify	macos/platform/menu_builder.mm
Modify	macos/platform/wndproc.mm
Modify	macos/platform/app_delegate.mm
Modify	macos/platform/split_view.mm
Modify	macos/platform/file_operations.mm
Modify	macos/platform/document_manager.mm
Modify	macos/CMakeLists.txt

Existing code reused (not modified): PluginInterface.h, Notepad_plus_msgs.h, IDAllocator.h, entire macos/shim/ layer.

[hybridmachine]

This is a good direction overall — a clean macOS-native loader is probably lower risk than trying to wire up PluginsManager.cpp wholesale. The places I'd tighten before implementation:

1. Scintilla handles are not real HWNDs today. applicationDidFinishLaunching and doSplit() create editor views via ScintillaBridge_createView, not CreateWindowExW("Scintilla", ...), so plugin code currently has nothing it can safely use with SendMessage(..., SCI_...). The plan needs an explicit compatibility step here: either create/register shim HWND wrappers for both existing Scintilla views, or change editor creation so NppData gets real Scintilla handles.
2. Buffer semantics are the biggest architecture mismatch. The macOS port keeps separate documents / documents2 vectors and clones a document into view 2 on split. That means NPPM_GETCURRENTBUFFERID, NPPN_BUFFERACTIVATED, and any other buffer-based API cannot use “active doc index”; plugins expect a stable buffer identity that survives tab moves and view switches. I'd add a dedicated buffer-id layer first, or explicitly narrow V1 to plugins that never touch buffer APIs.
3. Step 4 mixes two message families. NPPM_GETFULLCURRENTPATH, GETFILENAME, GETCURRENTDIRECTORY, GETNAMEPART, GETEXTPART, GETCURRENTLINE, and GETCURRENTCOLUMN are RUNCOMMAND_USER messages (WM_USER + 3000), not the NPPMSG block. Also several of the listed APIs are pointer/buffer-size contracts, not simple return-value getters, so the implementation needs to match the exact Windows calling convention to be source-compatible.
4. Command ID allocation should follow upstream split ranges. FuncItem._cmdID population belongs in the fixed ID_PLUGINS_CMD range, while NPPM_ALLOCATECMDID should reserve from ID_PLUGINS_CMD_DYNAMIC..LIMIT. Treating 22000–24999 as one pool will create collisions or at least behavior differences.
5. messageProc needs a real call site. The plan defines relayNppMessages(), but I don't see a step that actually invokes it from the main wndproc path. Without that, a non-trivial class of existing plugins will load but behave strangely.

My main recommendation is to re-scope V1 explicitly to command-oriented, non-docking plugins and make the first milestone a source-compatible subset rather than universal zero-source compatibility. If you want to keep the stronger goal, I'd move Scintilla HWND compatibility + stable buffer IDs ahead of menu wiring and the NPPM handler, because those look like the real foundation pieces.

[hybridmachine]

Amended Plan (addressing review feedback)

All five points are valid. Here's the revised plan with the foundational issues resolved first.

---

Revised Scope: V1 = Command-Oriented, Non-Docking Plugins

V1 explicitly targets plugins that:

• Register menu commands via FuncItem
• Call SendMessage(sciHandle, SCI_*, ...) to interact with the editor
• Use NPPM_GETCURRENTSCINTILLA, NPPM_GETPLUGINSCONFIGDIR, NPPM_GETNPPVERSION, and the RUNCOMMAND_USER file-path getters
• Receive SCNotification callbacks and lifecycle notifications

V1 explicitly excludes:

• Buffer-based APIs (NPPM_GETCURRENTBUFFERID, NPPM_GETBUFFERLANGTYPE, NPPN_BUFFERACTIVATED with buffer semantics) — deferred until a stable buffer-id layer exists
• Docking panel APIs (NPPM_DMMREGASDCKDLG)
• Lexer plugins

---

New Step 0 (Foundation): Scintilla HWND Registration

Problem: ScintillaBridge_createView() returns a raw void* (ScintillaView pointer) stored in ctx().scintillaView. These are NOT registered with HandleRegistry, so there are no HWNDs for them. When a plugin calls SendMessage(sciHandle, SCI_SETTEXT, ...), the shim's SendMessageW looks up HandleRegistry::getWindowInfo(hWnd) and checks info->isScintilla to route to the bridge. Without registration, this fails silently.

Fix: After each ScintillaBridge_createView() call, register the view with HandleRegistry:

Modify: macos/platform/app_delegate.mm (after line 247):

ctx().scintillaView = ScintillaBridge_createView((__bridge void*)ctx().editorContainer, 0, 0, 0, 0);
// Register as HWND so plugins can SendMessage(sciHandle, SCI_*, ...)
HandleRegistry::WindowInfo sciInfo{};
sciInfo.nativeView = ctx().scintillaView;
sciInfo.className = L"Scintilla";
sciInfo.isScintilla = true;
sciInfo.parent = ctx().mainHwnd;
ctx().scintillaMainHwnd = HandleRegistry::createWindow(std::move(sciInfo));

Modify: macos/platform/split_view.mm (after line 128, ScintillaBridge_createView for view 2):

ctx().scintillaView2 = ScintillaBridge_createView((__bridge void*)ctx().sciContainer2, 0, 0, 0, 0);
HandleRegistry::WindowInfo sci2Info{};
sci2Info.nativeView = ctx().scintillaView2;
sci2Info.className = L"Scintilla";
sci2Info.isScintilla = true;
sci2Info.parent = ctx().mainHwnd;
ctx().scintillaSecondHwnd = HandleRegistry::createWindow(std::move(sci2Info));

Modify: macos/platform/app_state.h — add HWND scintillaMainHwnd and HWND scintillaSecondHwnd fields to AppContext.

Verification: After this step, SendMessageW(ctx().scintillaMainHwnd, SCI_GETTEXT, ...) routes through the existing Scintilla path in win32_message.mm. This is testable independently of the plugin system.

---

Revised Step 1: Plugin Manager Core (same as before, but NppData uses registered HWNDs)

Plugin initialization now passes real registered HWNDs:

NppData nppData;
nppData._nppHandle = ctx().mainHwnd;
nppData._scintillaMainHandle = ctx().scintillaMainHwnd;
nppData._scintillaSecondHandle = ctx().scintillaSecondHwnd; // may be nullptr until split

When doSplit() creates view 2 and registers its HWND, update the plugin manager's _nppData._scintillaSecondHandle. Plugins that cache the handle from setInfo won't see the update, but this matches N++ behavior where the second view handle is always set at init time (N++ creates both views at startup, even if hidden).

Alternative: Create and register the second Scintilla view at startup (hidden), so NppData always has both handles. Defer showing it until doSplit(). This gives better compatibility with plugins that cache the handle.

---

Revised Step 4: NPPM_* and RUNCOMMAND_USER Message Handler

Corrected message routing in wndproc.mm:

default:
    // NPPMSG range: WM_USER + 1000 through +1200
    if (msg >= NPPMSG && msg < NPPMSG + 200)
    {
        // First relay to plugins' messageProc
        pluginManager().relayNppMessages(msg, wParam, lParam);
        return handleNppmMessage(hWnd, msg, wParam, lParam);
    }
    // RUNCOMMAND_USER range: WM_USER + 3000 through +3020
    if (msg >= RUNCOMMAND_USER && msg < RUNCOMMAND_USER + 20)
    {
        pluginManager().relayNppMessages(msg, wParam, lParam);
        return handleRunCommandMessage(hWnd, msg, wParam, lParam);
    }
    break;

Two separate handler functions to reflect the two message families:

handleNppmMessage() — for NPPMSG range:

Message	Range	Implementation
NPPM_GETCURRENTSCINTILLA	NPPMSG+4	*(int*)lParam = ctx().activeView
NPPM_GETCURRENTLANGTYPE	NPPMSG+5	*(int*)lParam = doc.languageIndex
NPPM_SETCURRENTLANGTYPE	NPPMSG+6	applyLanguage(lParam)
NPPM_GETNBOPENFILES	NPPMSG+7	docs.size() for view
NPPM_GETNPPVERSION	NPPMSG+11	Hardcoded version
NPPM_GETPLUGINSCONFIGDIR	NPPMSG+46	~/Library/Application Support/MacNote++/plugins/Config/ → (wchar_t*)lParam (buffer-size contract: wParam = max chars)
NPPM_GETCURRENTVIEW	NPPMSG+88	ctx().activeView
NPPM_SETMENUITEMCHECK	NPPMSG+40	CheckMenuItem()
NPPM_MENUCOMMAND	NPPMSG+48	SendMessage(hWnd, WM_COMMAND, lParam, 0)
NPPM_MODELESSDIALOG	NPPMSG+12	Store/remove HWND for keyboard dispatch
NPPM_ALLOCATECMDID	NPPMSG+97	pluginManager().allocateCmdID() — dynamic range only (23000-24999)
NPPM_ALLOCATEMARKER	NPPMSG+113	pluginManager().allocateMarker()
NPPM_ALLOCATEINDICATOR	NPPMSG+114	pluginManager().allocateIndicator()

handleRunCommandMessage() — for RUNCOMMAND_USER range (all use buffer-size contracts):

Message	Range	Notes
NPPM_GETFULLCURRENTPATH	RUNCOMMAND+1	wParam = buffer size, lParam = wchar_t* output
NPPM_GETCURRENTDIRECTORY	RUNCOMMAND+2	Same contract
NPPM_GETFILENAME	RUNCOMMAND+3	Same contract
NPPM_GETNAMEPART	RUNCOMMAND+4	Same contract
NPPM_GETEXTPART	RUNCOMMAND+5	Same contract
NPPM_GETCURRENTWORD	RUNCOMMAND+6	Query Scintilla for word at cursor
NPPM_GETCURRENTLINE	RUNCOMMAND+16	Return value (no buffer)
NPPM_GETCURRENTCOLUMN	RUNCOMMAND+17	Return value (no buffer)

---

Revised Step 3: Command ID Allocation (corrected ranges)

Static range (ID_PLUGINS_CMD 22000 → ID_PLUGINS_CMD_LIMIT 22999): Used for FuncItem._cmdID assignment during plugin loading. Each plugin's FuncItem entries get sequential IDs starting from the current allocation point. This is what the existing N++ PluginsManager::addInMenuFromPMIndex does (line 589 of PluginsManager.cpp).

Dynamic range (ID_PLUGINS_CMD_DYNAMIC 23000 → ID_PLUGINS_CMD_DYNAMIC_LIMIT 24999): Reserved for NPPM_ALLOCATECMDID requests from plugins at runtime.

The MacPluginManager tracks two IDAllocator instances:

IDAllocator _staticCmdAlloc{ID_PLUGINS_CMD, ID_PLUGINS_CMD_LIMIT};     // for FuncItem IDs
IDAllocator _dynamicCmdAlloc{ID_PLUGINS_CMD_DYNAMIC, ID_PLUGINS_CMD_DYNAMIC_LIMIT}; // for NPPM_ALLOCATECMDID

Revised Step 5: messageProc call site (explicit)

The relayNppMessages() call is now explicitly shown in the revised Step 4 routing code above. For every NPPM_* and RUNCOMMAND_USER message that arrives at MainWndProc, we first call pluginManager().relayNppMessages(msg, wParam, lParam) which iterates all loaded plugins and invokes their messageProc(msg, wParam, lParam). This gives plugins the chance to intercept or observe messages before the host handles them.

---

Buffer ID Strategy (V2, documented for context)

The macOS port uses std::vector<DocumentData> with index-based addressing. N++ uses Buffer* pointers as stable BufferID values. For V1, we:

• Do NOT implement NPPM_GETCURRENTBUFFERID (returns 0)
• Do NOT send NPPN_BUFFERACTIVATED (plugins won't get buffer-switch notifications)
• DO send NPPN_FILEOPENED, NPPN_FILESAVED, NPPN_FILECLOSED with nmhdr.hwndFrom set to the main window handle (no buffer ID in these notifications)

For V2, the plan is to add a uint64_t bufferId field to DocumentData (monotonically increasing, assigned at creation) and use that as the stable identifier across tab switches and view moves.

---

Revised Step Order

Step	Description	Dependencies
0	Register Scintilla views with HandleRegistry	None — testable independently
1	Plugin manager core (load dylibs, resolve exports, call setInfo)	Step 0 (needs real HWNDs for NppData)
2	Plugin menu integration in menu_builder.mm	Step 1
3	WndProc routing (plugin commands + NPPM + RUNCOMMAND_USER)	Steps 1, 4
4	NPPM_* and RUNCOMMAND_USER handlers (two families)	Step 0
5	SCNotification forwarding + lifecycle notifications	Step 1
6	Plugin init in app_delegate.mm	Steps 0-5
7	Plugin SDK package (headers + shim)	Step 0 (for shim includes)
8	Sample plugin (HelloMacNote)	All above
9	Build system changes	All above

Steps 0 and 4 are the foundation. Steps 7-8 can be developed in parallel with 2-6.

[hybridmachine]

Amended Plan V2 (addressing all 5 review points)

Changes from V1

1. New Step 0 (Foundation): Scintilla HWND Registration — Register both ScintillaView instances with HandleRegistry after creation, giving plugins real HWNDs that route SCI_* messages through the existing bridge in win32_message.mm
2. Buffer semantics — V1 explicitly excludes buffer APIs (NPPM_GETCURRENTBUFFERID, NPPN_BUFFERACTIVATED). V2 strategy documented (monotonic bufferId field in DocumentData)
3. RUNCOMMAND_USER messages — Split into two handler functions with correct buffer-size calling conventions
4. Command ID ranges — Two separate IDAllocator instances: static (22000–22999) for FuncItem._cmdID, dynamic (23000–24999) for NPPM_ALLOCATECMDID
5. messageProc call site — relayNppMessages() explicitly called in WndProc routing before each handler

---

V1 Scope: Command-Oriented, Non-Docking Plugins

V1 targets plugins that:

• Register menu commands via FuncItem
• Call SendMessage(sciHandle, SCI_*, ...) to interact with the editor
• Use NPPM_GETCURRENTSCINTILLA, NPPM_GETPLUGINSCONFIGDIR, NPPM_GETNPPVERSION, and RUNCOMMAND_USER file-path getters
• Receive SCNotification callbacks and lifecycle notifications

V1 explicitly excludes:

• Buffer-based APIs (NPPM_GETCURRENTBUFFERID, NPPM_GETBUFFERLANGTYPE, NPPN_BUFFERACTIVATED with buffer semantics) — deferred until a stable buffer-id layer exists
• Docking panel APIs (NPPM_DMMREGASDCKDLG)
• Lexer plugins

---

Step 0 (Foundation): Register Scintilla Views with HandleRegistry

Problem: ScintillaBridge_createView() returns a raw void* (ScintillaView pointer) stored in ctx().scintillaView. These are NOT registered with HandleRegistry, so there are no HWNDs for them. When a plugin calls SendMessage(sciHandle, SCI_SETTEXT, ...), the shim's SendMessageW looks up HandleRegistry::getWindowInfo(hWnd) and checks info->isScintilla to route to the bridge. Without registration, this fails silently.

Modify: macos/platform/app_state.h — add HWND scintillaMainHwnd and HWND scintillaSecondHwnd fields.

Modify: macos/platform/app_delegate.mm (after line 247):

ctx().scintillaView = ScintillaBridge_createView((__bridge void*)ctx().editorContainer, 0, 0, 0, 0);
HandleRegistry::WindowInfo sciInfo{};
sciInfo.nativeView = ctx().scintillaView;
sciInfo.className = L"Scintilla";
sciInfo.isScintilla = true;
sciInfo.parent = ctx().mainHwnd;
ctx().scintillaMainHwnd = HandleRegistry::createWindow(std::move(sciInfo));

Modify: macos/platform/split_view.mm (after line 128):

ctx().scintillaView2 = ScintillaBridge_createView((__bridge void*)ctx().sciContainer2, 0, 0, 0, 0);
HandleRegistry::WindowInfo sci2Info{};
sci2Info.nativeView = ctx().scintillaView2;
sci2Info.className = L"Scintilla";
sci2Info.isScintilla = true;
sci2Info.parent = ctx().mainHwnd;
ctx().scintillaSecondHwnd = HandleRegistry::createWindow(std::move(sci2Info));

Consideration: Create the second Scintilla view at startup (hidden) so NppData always has both handles.

Verification: SendMessageW(ctx().scintillaMainHwnd, SCI_GETTEXT, ...) routes correctly. Testable independently.

---

Step 1: Plugin Manager Core

New files: macos/platform/plugin_manager.h, macos/platform/plugin_manager.mm

• MacPluginInfo struct with HINSTANCE _hLib, HMENU _pluginMenu, 6 function pointers, FuncItem*, int _nbFuncItem, std::wstring _moduleName
• MacPluginManager class:
  • init(const NppData&) — uses registered HWNDs from Step 0
  • loadPlugins() — scans ~/Library/Application Support/MacNote++/plugins/
  • loadPluginFromPath() — Mach-O arch validation, dlopen, resolve 6 exports, setInfo(), getFuncsArray()
  • initMenu(HMENU), runPluginCommand(int cmdId), notify(), relayNppMessages()
  • allocateCmdID/allocateMarker/allocateIndicator

Command ID allocation (corrected):

IDAllocator _staticCmdAlloc{ID_PLUGINS_CMD, ID_PLUGINS_CMD_LIMIT};       // 22000-22999 for FuncItem
IDAllocator _dynamicCmdAlloc{ID_PLUGINS_CMD_DYNAMIC, ID_PLUGINS_CMD_DYNAMIC_LIMIT}; // 23000-24999 for NPPM_ALLOCATECMDID

---

Step 2: Plugin Menu Integration

Modify: macos/platform/menu_builder.mm — insert "Plugins" submenu between Tools and Language (after line 197). Expose hPluginsMenu for the plugin manager.

---

Step 3: Wire Plugin Commands and Messages into WndProc

Modify: macos/platform/wndproc.mm

In WM_COMMAND handler:

if (cmdId >= ID_PLUGINS_CMD && cmdId < ID_PLUGINS_CMD_DYNAMIC_LIMIT)
{
    pluginManager().runPluginCommand(cmdId);
    return 0;
}

In default case (with explicit relayNppMessages() call):

default:
    if (msg >= NPPMSG && msg < NPPMSG + 200)
    {
        pluginManager().relayNppMessages(msg, wParam, lParam);
        return handleNppmMessage(hWnd, msg, wParam, lParam);
    }
    if (msg >= RUNCOMMAND_USER && msg < RUNCOMMAND_USER + 20)
    {
        pluginManager().relayNppMessages(msg, wParam, lParam);
        return handleRunCommandMessage(hWnd, msg, wParam, lParam);
    }
    break;

---

Step 4: NPPM_* and RUNCOMMAND_USER Message Handlers

New files: macos/platform/nppm_handler.h, macos/platform/nppm_handler.mm

handleNppmMessage() — NPPMSG range (WM_USER + 1000):

Message	Implementation
NPPM_GETCURRENTSCINTILLA (NPPMSG+4)	*(int*)lParam = ctx().activeView
NPPM_GETCURRENTLANGTYPE (NPPMSG+5)	*(int*)lParam = doc.languageIndex
NPPM_SETCURRENTLANGTYPE (NPPMSG+6)	applyLanguage(lParam)
NPPM_GETNBOPENFILES (NPPMSG+7)	docs.size() for view
NPPM_GETNPPVERSION (NPPMSG+11)	Hardcoded version
NPPM_MODELESSDIALOG (NPPMSG+12)	Store/remove HWND
NPPM_SETMENUITEMCHECK (NPPMSG+40)	CheckMenuItem()
NPPM_GETPLUGINSCONFIGDIR (NPPMSG+46)	Buffer-size contract: wParam=max chars, lParam=wchar_t*
NPPM_MENUCOMMAND (NPPMSG+48)	SendMessage(hWnd, WM_COMMAND, lParam, 0)
NPPM_GETCURRENTVIEW (NPPMSG+88)	ctx().activeView
NPPM_ALLOCATECMDID (NPPMSG+97)	Dynamic range only (23000-24999)
NPPM_ALLOCATEMARKER (NPPMSG+113)	pluginManager().allocateMarker()
NPPM_ALLOCATEINDICATOR (NPPMSG+114)	pluginManager().allocateIndicator()

handleRunCommandMessage() — RUNCOMMAND_USER range (WM_USER + 3000):

Message	Notes
NPPM_GETFULLCURRENTPATH (RUNCOMMAND+1)	wParam=buf size, lParam=wchar_t*
NPPM_GETCURRENTDIRECTORY (RUNCOMMAND+2)	Same buffer-size contract
NPPM_GETFILENAME (RUNCOMMAND+3)	Same contract
NPPM_GETNAMEPART (RUNCOMMAND+4)	Same contract
NPPM_GETEXTPART (RUNCOMMAND+5)	Same contract
NPPM_GETCURRENTWORD (RUNCOMMAND+6)	Query Scintilla for word at cursor
NPPM_GETCURRENTLINE (RUNCOMMAND+16)	Return value (no buffer)
NPPM_GETCURRENTCOLUMN (RUNCOMMAND+17)	Return value (no buffer)

Unhandled messages return 0 with NSLog debug.

---

Step 5: SCNotification Forwarding + Lifecycle Notifications

Modify: macos/platform/app_delegate.mm (notification callback, line 262-372)

After existing handling: pluginManager().notify(reinterpret_cast<const SCNotification*>(scn));

Lifecycle notifications:

Notification	Where
NPPN_READY	End of applicationDidFinishLaunching:
NPPN_SHUTDOWN	Start of applicationWillTerminate:
NPPN_FILEOPENED	file_operations.mm after open
NPPN_FILESAVED	file_operations.mm after save
NPPN_FILEBEFORECLOSE/NPPN_FILECLOSED	document_manager.mm around tab close
NPPN_LANGCHANGED	wndproc.mm after language change

NOT sent in V1: NPPN_BUFFERACTIVATED (no stable buffer IDs).

Also modify: macos/platform/split_view.mm — same forwarding for view 2.

---

Step 6: Plugin Initialization in App Lifecycle

Modify: macos/platform/app_delegate.mm

1. Create plugin directory if missing
2. Init pluginManager() with NppData (registered HWNDs from Step 0)
3. loadPlugins() + initMenu(hPluginsMenu)
4. Broadcast NPPN_READY at end of init
5. Broadcast NPPN_SHUTDOWN at start of applicationWillTerminate:

---

Steps 7-9: SDK, Sample Plugin, Build System

Same as original plan — see initial comment for full details.

---

Buffer ID Strategy (V2)

V1: No buffer APIs. V2: Add monotonic uint64_t bufferId to DocumentData, use as stable identifier across tab switches and view moves.

---

Step Order

Step	Description	Dependencies
0	Register Scintilla views with HandleRegistry	None — testable independently
1	Plugin manager core	Step 0
2	Plugin menu integration	Step 1
3	WndProc routing + relayNppMessages	Steps 1, 4
4	NPPM + RUNCOMMAND_USER handlers	Step 0
5	SCNotification + lifecycle notifications	Step 1
6	Plugin init in app_delegate	Steps 0-5
7-8	SDK + sample plugin (parallel with 2-6)	Step 0
9	Build system	All above

Critical Files

Action	File
Create	macos/platform/plugin_manager.h
Create	macos/platform/plugin_manager.mm
Create	macos/platform/nppm_handler.h
Create	macos/platform/nppm_handler.mm
Create	macos/plugin-sdk/ (SDK + example)
Modify	macos/platform/app_state.h — Scintilla HWND fields
Modify	macos/platform/app_delegate.mm — register HWNDs, init plugins, notifications
Modify	macos/platform/split_view.mm — register view 2 HWND, forwarding
Modify	macos/platform/menu_builder.mm — Plugins menu
Modify	macos/platform/wndproc.mm — command + message routing
Modify	macos/platform/file_operations.mm — file notifications
Modify	macos/platform/document_manager.mm — close notifications
Modify	macos/CMakeLists.txt — new sources, SDK target

[hybridmachine]

Plan V3 — Corrections from issue-49-plan-suggestions.md

All 5 points addressed:

1. Dynamic plugin commands: fixed routing

Split static vs dynamic in WM_COMMAND handler (matching upstream NppCommands.cpp:4253-4261):

// Static FuncItem commands → direct function call
if (cmdId >= ID_PLUGINS_CMD && cmdId < ID_PLUGINS_CMD_LIMIT)
{
    int i = cmdId - ID_PLUGINS_CMD;
    pluginManager().runPluginCommand(i);
    return 0;
}
// Dynamic commands (allocated via NPPM_ALLOCATECMDID) → relay through messageProc
if (pluginManager().inDynamicRange(cmdId))
{
    pluginManager().relayNppMessages(WM_COMMAND, cmdId, 0);
    return 0;
}

2. messageProc relay: broadened to match upstream

Upstream (NppBigSwitch.cpp:4431) relays every message that reaches the main WndProc to plugins' messageProc, at the END of the proc after host processing. V1 now mirrors this:

LRESULT CALLBACK MainWndProc(HWND hWnd, UINT msg, WPARAM wParam, LPARAM lParam)
{
    LRESULT result = 0;
    switch (msg) {
        case WM_COMMAND: /* ... static + dynamic routing ... */ break;
        default:
            if (msg >= NPPMSG && msg < NPPMSG + 200)
                result = handleNppmMessage(hWnd, msg, wParam, lParam);
            else if (msg >= RUNCOMMAND_USER && msg < RUNCOMMAND_USER + 20)
                result = handleRunCommandMessage(hWnd, msg, wParam, lParam);
            break;
    }
    // Catch-all relay to plugins' messageProc (matches upstream)
    pluginManager().relayNppMessages(msg, wParam, lParam);
    return result;
}

3. Scintilla HWND lifecycle: explicit

Firm choice: create both Scintilla views at startup. Second view is created hidden (zero-size) during applicationDidFinishLaunching: so NppData._scintillaSecondHandle is always valid. doSplit() shows/resizes the existing view.

Teardown:

• On unsplit: do NOT destroy scintillaSecondHwnd — keep registered but hidden (matches N++)
• On app shutdown (applicationWillTerminate:): send NPPN_SHUTDOWN, then HandleRegistry::destroyWindow() for both HWNDs to release retained native views

4. Message constants: corrected from Notepad_plus_msgs.h

Message	Correct Offset	Previous (wrong)
NPPM_GETNPPVERSION	NPPMSG + 50	+11
NPPM_ALLOCATECMDID	NPPMSG + 81	+97
NPPM_ALLOCATEMARKER	NPPMSG + 82	+113
NPPM_ALLOCATEINDICATOR	NPPMSG + 113	+114

Return semantics now documented per-message:

• NPPM_GETPLUGINSCONFIGDIR (+46): Two-call contract — 1st with lParam=NULL returns wchar_t count; 2nd copies to buffer, returns TRUE/FALSE
• NPPM_GETNPPVERSION (+50): Returns MAKELONG(minor, major) with optional zero-padding if wParam=TRUE
• NPPM_ALLOCATECMDID (+81): wParam=count, lParam=int* start; returns TRUE/FALSE
• RUNCOMMAND_USER path getters: All use same two-call contract (NULL probe, then copy)

5. Intro scope: corrected

Opening goal now reads:

"source code compatibility for command-oriented plugins: a developer can take their existing Notepad++ plugin source (one that uses menu commands, Scintilla messaging, and file-path APIs), compile it on macOS as a .dylib, and load it without source modifications. Plugins requiring docking panels, buffer-based APIs, or lexer integration are out of V1 scope."

---

Full updated plan is in the plan file (fuzzy-imagining-newt.md). Ready for implementation pending approval.

[hybridmachine]

Plan V4 — Final corrections from issue-49-plan-additional-suggestions.md

1. Deferred file/language notifications

V1 now only sends NPPN_READY and NPPN_SHUTDOWN (which don't use BufferID). All other NPPN_* notifications are deferred to V2:

• NPPN_FILEOPENED, NPPN_FILESAVED, NPPN_FILEBEFORECLOSE, NPPN_FILECLOSED — all carry nmhdr.idFrom = BufferID upstream
• NPPN_BUFFERACTIVATED, NPPN_LANGCHANGED — same BufferID dependency

Removed file_operations.mm and document_manager.mm from the modify list.

2. Dropped NPPM_MODELESSDIALOG from V1

Removed from the NPPM message handler table. IsDialogMessageW() is still a stub, so registration would be bookkeeping-only without the actual keyboard dispatch behavior. Added to Known Limitations.

3. messageProc relay ordering (already correct)

V3 already had the catch-all pluginManager().relayNppMessages(msg, wParam, lParam) at the END of MainWndProc (after host processing). No change needed — just confirming the relay order is: host handles message first, then broadcasts to plugins' messageProc.

4. Second Scintilla handle (already decided)

V3 already made the firm decision: "create both views at startup, view 2 hidden". No ambiguity remains.

5. Sample plugin deployment now opt-in

Changed from automatic post-build step to an explicit custom target: cmake --build . --target install_sample_plugin. The HelloMacNote library still builds as part of the normal build, but isn't copied to ~/Library/Application Support/ unless the user explicitly runs the install target.

---

Updated plan file reflects all changes. Ready for implementation.