Linux Mint/Ubuntu desktop fixes + plugin-API extensions + NEN 1414 stamp fix (v1.46.0)

[FreekHeijting]

Why this PR exists

Open PDF Studio is the substrate we use to build a domain-specific draftboard for Symitech (NL inspection-engineering firm). To make that possible, the original PR opened in April was scoped to fix three independent issues we ran into while bringing the app up on Linux Mint 22.3:

1. The window did not show up reliably on certain WebKitGTK + Mesa combinations.
2. CLI flag handling silently squatted DBus single-instance, breaking subsequent launches.
3. Custom plugin annotation types had no way to render, persist, or own their UI.

While iterating on that work the same branch grew the plumbing needed by a real plugin (symitech.tools) until the plumbing itself stabilised. We are surfacing the whole branch now because the parts are tightly co-evolved: the Linux fixes unblock daily work for our team, the plugin-API additions are pure additions that other plugin authors can use today, and the NEN 1414 stamp fix is a one-line glob update riding along because it shares the version bump. CI is green on all three platforms.

Table of contents

• A. Linux Mint/Ubuntu desktop fixes (4 commits)
• B. NEN 1414 stamp + Vite 7 (1 commit)
• C. Plugin-API extensions (10 commits)
  • Foundations
  • New hooks
• Test coverage
• Risk and limitations
• Follow-up roadmap
• Suggested review path

---

A. Linux Mint/Ubuntu desktop fixes (4 commits)

Independent desktop-integration fixes. Each lands a real bug we hit on Mint 22.3 / Ubuntu 24.04 daily-driver setups; CI confirms they do not regress Windows or macOS.

e9fab7b5 fix: show window immediately after init on Linux

Field	Detail
Problem	App starts, Rust side reaches Tauri::run(), but the window never becomes visible. Mouse-in-tray confirms the process is alive.
Root cause	The frontend gates appWindow.show() on a double requestAnimationFrame to wait for first paint. On WebKitGTK builds where the accelerated compositor stalls before the first paint (reproduced on Mint 22.3 + Mesa 25.2.8 + Intel UHD CML GT2), the inner rAF never fires, the outer Promise never resolves, and show() is never called.
Fix	Drop the rAF gate and call appWindow.show() directly after init. The pre-paint flash users were trying to avoid is barely visible in practice and a permanently hidden window is strictly worse.
Files	js/main.js (-12 / +7)
How to verify	Boot a Mint 22.3 VM with MESA_LOADER_DRIVER_OVERRIDE=iris, run a debug build, confirm the window appears.

ae1bb2b6 fix: handle --version and --help before starting the event loop

Field	Detail
Problem	open-pdf-studio --version printed nothing, exited with code 0, and any subsequent normal launch silently exited as if another instance were running.
Root cause	Flag parsing happened inside tauri::Builder::default().run(). The full event loop started, the single-instance DBus name was registered, the process then exited without printing, and the squatted DBus name made later launches think a peer instance owned the slot.
Fix	Parse --version / -V / --help / -h from std::env::args() before any Tauri builder runs. Print + std::process::exit(0).
Files	src-tauri/src/lib.rs (-1 / +27)
How to verify	target/release/open-pdf-studio --version prints the version and exits cleanly. Immediately afterwards a normal launch creates a window without "another instance is already running" complaints.

d4a606c8 fix: register application/pdf MIME type for Linux file associations

Field	Detail
Problem	The "Set as default PDF reader" button did nothing on Linux because xdg-mime had no record of Open PDF Studio claiming PDFs.
Root cause	The fileAssociations entry for .pdf was missing the mimeType field, so tauri-bundler could not emit MimeType=application/pdf into the generated .desktop file.
Fix	Add mimeType: ["application/pdf"] and a short description. The Tauri bundler translates this into the right MimeType= line, after which xdg-mime query default application/pdf can resolve to open-pdf-studio.desktop.
Files	src-tauri/tauri.conf.json (+2)
How to verify	Build a .deb, install, run xdg-mime query default application/pdf after pressing the in-app "Set as default" button.

4a894a27 feat(linux): implement default PDF handler via xdg-mime

Field	Detail
Problem	is_default_pdf_app and open_default_apps_settings were Windows-only. The "Set as default" banner was permanently shown on Linux (because is_default_pdf_app always returned false), and clicking the button returned Ok(false) without any side effect.
Root cause	The implementation predated Linux support for that feature.
Fix	Add Linux branches to both functions. is_default_pdf_app shells out to xdg-mime query default application/pdf and matches against open-pdf-studio.desktop. open_default_apps_settings calls xdg-mime default open-pdf-studio.desktop application/pdf so the in-app button can complete the round-trip without dragging users into a settings dialog.
Files	src-tauri/src/lib.rs (-3 / +35)
How to verify	On Linux, click "Set as default", then xdg-mime query default application/pdf returns open-pdf-studio.desktop and the banner disappears on next launch.

macOS note: A macOS branch for is_default_pdf_app / open_default_apps_settings is missing. The Linux branch returns false on macOS, so the feature degrades gracefully (banner stays, button does nothing). To be addressed in a follow-up PR; out of scope here.

---

B. NEN 1414 stamp + Vite 7 (1 commit)

3ae68466 fix: NEN 1414 symbols below 4 KB rendered as broken stamps

Field	Detail
Problem	A subset of NEN 1414 symbols rendered as image not found placeholders in the stamp tool. The set varied with build mode (dev vs prod).
Root cause	Vite inlines PNG assets smaller than 4 KB as data: URIs. rasterSvg() was prepending window.location.origin to every URL that did not start with http, producing corrupt strings such as http://localhost:3041data:image/png;base64,....
Fix	Prepend the origin only when the URL is root-relative (starts with /). Update the glob to Vite 7 syntax (import.meta.glob('...', { query: '?url', import: 'default' })) since as: 'url' is deprecated. Bump package.json from 1.45.0 to 1.46.0 to mark the user-visible fix.
Files	js/solid/data/nen1414Library.js, package.json, package-lock.json, Cargo.toml, Cargo.lock, tauri.conf.json (-10 / +11)
How to verify	Run a prod build, open the stamp tool, drop any of the previously-broken symbols (e.g. small valves) onto a page; they now render.

Version bump caveat: If upstream prefers to manage versioning on its own cadence, the 1.45.0 → 1.46.0 part of this commit is straightforward to revert independently. Happy to split if requested.

---

C. Plugin-API extensions (10 commits)

Plugins author custom annotation types today, but until this branch they could not render those annotations into thumbnails, persist them into the saved PDF, mount their own UI in place of the built-in property panel, or react to selection events without scraping the DOM. Each addition below is a pure addition: existing plugins are unaffected, all new fields and methods are optional.

These extensions are in production use by the private Symitech Tekentool V2 plugin (symitech.tools). We can demo it on request.

Foundations (4 commits)

Commit	What	Why it matters
9621cfc8	serializeToPdf hook on plugin handlers	Plugins persist custom annotation types into saved PDFs. The saver in js/pdf/saver.js falls back to the plugin annotation-type registry for unknown types and awaits an optional serializeToPdf({ pdfDoc, page, annotation, convertX, convertY }).
884db08d	Page-pt dimensions + DPR in state	pluginClickTool augments the state object passed to typeHandler.create() with pageWidth, pageHeight, docScale, and devicePixelRatio. Eliminates fragile ctx-matrix sniffing.
c313bd78	__pdfViewport singleton sync for blank docs	Blank ("Nieuw") documents skip the vector render path that normally calls setPage(), so window.__pdfViewport.pageW/pageH stayed at 0 and plugin handlers fell back to A4 defaults regardless of actual page size. Now the singleton is updated for blank docs too.
b15ded06	doc.pageDims cache + zoom controls + page centering	Blank docs now store page dimensions on the document object directly (single source of truth), zoom controls work from the first frame, and the canvas is centered horizontally instead of left-aligned. Three small fixes that cluster around the same root cause.

New hooks (6 commits)

b844e54f api.registerPropertyPanel(typeName, renderFn)

Plugins replace the built-in properties panel for their own annotation types.

api.registerPropertyPanel('symitech.titlebar', (annotation, updateAnnotProp, onCommit, onCancel) => {
  const root = document.createElement('div');
  // build custom DOM, wire inputs to updateAnnotProp(...)
  return root;
});

renderFn returns the root element, OPPS mounts it into the panel slot. null falls through to default rendering.

Files: js/plugins/plugin-api.js, js/plugins/property-panel-registry.js (NEW), js/solid/components/properties-panel/CustomPluginPanel.jsx (NEW), js/solid/components/properties-panel/PropertiesPanel.jsx, js/solid/stores/propertiesStore.js.

1ea2964a Dot-path support in default updateAnnotProp branch

Plugin custom panels need to write nested annotation fields. Before this commit, updateAnnotProp('data.address.email', x) created a literal string-keyed property. Now: when the key contains ., the default branch splits, walks/creates intermediate objects, and writes to the leaf. Mirroring into the flat Solid store is skipped for nested writes (those are plugin-owned).

updateAnnotProp('data.address.email', 'info@example.com');
// annotation.data.address.email === 'info@example.com'

Files: js/solid/stores/propertiesStore.js (-2 / +22).

f041bd09 drawMode: 'polyline' for plugin handlers

Plugins registering a handler with drawMode: 'polyline' are now correctly routed by the tool-dispatcher and the polyline-tool. On finish, the plugin handler's create() is called with state.polylinePoints set. Previously polyline-mode fell through to the box-tool, producing a drag-rectangle and a generic type: 'polyline' annotation that ignored the plugin handler.

const handler = {
  type: 'symitech.scheur',
  drawMode: 'polyline',
  create: (sx, sy, ex, ey, e, state) => ({
    type: 'symitech.scheur',
    points: state.polylinePoints,
  }),
};

Files: js/tools/tool-dispatcher.js, js/tools/tools/polyline-tool.js.

2a0ecc71 registerSelectionListener + setNativePanelVisible + descriptor cssClass

Three small additions that let plugins mount UI outside the native properties panel without DOM-scraping or MutationObserver fallbacks.

api.registerSelectionListener('symitech.titlebar', (annotation) => {
  if (annotation) mountInOwnPalette(annotation);
  else unmountFromOwnPalette();
});

const descriptor = {
  cssClass: 'symitech-plugin', // applied directly to the .tp-ext root
  // ...
};

fireSelectionChange() is called from propertiesStore on storeShowProperties / storeHideProperties / storeClosePanel / storeShowMultiSelection. cssClass removes the need for plugins to scan the DOM looking for their own palette root.

Files: js/plugins/plugin-api.js, js/plugins/selection-listener-registry.js (NEW), js/plugins/palette-registry.js, js/solid/components/ExtensionToolPalette.jsx, js/solid/components/properties-panel/PropertiesPanel.jsx, js/solid/components/properties-panel/CustomPluginPanel.jsx, js/solid/stores/propertiesStore.js.

3d1063bd Overlay plugin/Solid-store annotations on page-thumbnails

The thumbnails panel renders pages via the Rust backend (render_thumbnail invoke with skip_images=true) or via the PDF.js fallback with annotationMode: 0. Both paths skipped plugin and Solid-store annotations, so previews showed empty pages.

After each render path, renderThumbnailToDataURL now overlays all annotations for that page on the thumbnail canvas at thumbnail scale. Tolerant per-annotation try/catch so one broken handler does not break the whole thumbnail. Zero-cost early-exit when the page has no annotations.

Files: js/ui/panels/left-panel.js (-1 / +63).

686c3bf6 Tool-group state + features.toolGroups flag

Foundation for sub-menu palette buttons. A ToolDefinition can now declare an optional subTools: ToolDefinition[], turning the entry into a sub-menu group. tool-group-state.js (NEW) tracks the active sub-tool per group. The host gate (features.toolGroups) defaults to false so this is a no-op for plugins that do not opt in. Render layer (G4b) follows in a later PR.

Files: js/plugins/palette-registry.js, js/plugins/plugin-api.js, js/plugins/tool-group-state.js (NEW).

---

Test coverage

Layer	Status
CI build matrix	✅ ubuntu-22.04, windows-latest, macos-latest
Linux Mint 22.3 manual	✅ daily-driver, validated with Symitech plugin (titelblok edit-flow, schade symbols, polyline-mode, thumbnail overlay)
Windows 11 manual	⏳ CI build only, no runtime smoke
macOS 14 manual	⏳ CI build only, no runtime smoke
Unit tests for new plugin-API hooks	⏳ none added in this PR; happy to add if reviewers want them as a precondition

Risk and limitations

Risk	Severity	Mitigation
Hardware-specific window-show fix (e9fab7b5) drops a defensive gate	Medium	Open to suggestions; a short timeout-fallback (show after 250ms regardless of paint) is a reasonable middle ground.
xdg-mime shell-out (4a894a27) assumes xdg-utils is installed	Low	Standard on every desktop Linux distribution we have tested; fails gracefully with Ok(false) if missing.
macOS branch for default-PDF handler missing	Low	Linux branch returns false on macOS, banner stays visible. Not regressing existing behaviour.
Plugin-API extensions break a hypothetical existing plugin	Very low	All hooks are optional and additive. Default behaviour unchanged when a plugin does not register anything.
Version bump in 3ae68466 clashes with upstream release flow	Low	Trivial to revert if upstream wants to manage versions independently.

Follow-up roadmap

Items intentionally left out of this PR, in rough priority order:

1. macOS branch for is_default_pdf_app / open_default_apps_settings (LaunchServices via LSCopyDefaultApplicationURLForContentType + a defaults write round-trip).
2. Defensive window-show with a short timeout-fallback instead of unconditional show(), addressing reviewer concern about e9fab7b5.
3. Tool-group render layer (G4b): button group expands into a fly-out, current sub-tool icon morphs into the parent button. State plumbing is already merged here.
4. Unit tests for the new plugin-API hooks (registerPropertyPanel, registerSelectionListener, serializeToPdf, dot-path updateAnnotProp).

Suggested review path

The branch is structured so that each commit compiles and ships independently. Suggested order for reviewers who want to land this incrementally:

1. Section A (4 commits) is small, scoped, low-risk, and resolves daily Linux pain. Easiest to ship first.
2. Section C (10 commits, foundations first then hooks) is the largest delta but every commit is additive. Foundations (9621cfc8, 884db08d, c313bd78, b15ded06) are mechanically obvious; the new hooks (b844e54f, 1ea2964a, f041bd09, 2a0ecc71, 3d1063bd, 686c3bf6) are each self-contained and have a real plugin (Symitech) exercising them.
3. Section B (1 commit) is a one-liner glob fix riding along with a version bump.

If splitting this PR into three is preferred, happy to do so; the branch was kept whole because the parts were authored in a tight loop and CI is already validating them together.

[FreekHeijting]

Quality-audit follow-up (4 commits)

After re-auditing the plugin-API and thumbnail-overlay commits we pushed earlier, four issues were worth fixing before this PR is reviewed. All four are additive and do not change any existing public contract.

Commit	What	Why it matters
efb329b5 fix(plugin-api): CustomPluginPanel reactivity + dot-path JSDoc	Read annotProps.id reactively inside the createEffect that mounts the plugin renderer. Document the dot-path contract on updateAnnotProp.	Without the reactive read, selecting annotation B after A within the same plugin-type left the panel showing A's DOM, because customPanelRender() returned the same renderFn reference and the effect did not re-run. The JSDoc clarifies the literal-. restriction so plugin authors can rely on it.
e09af662 fix(thumbnails): generation-token guard + log overlay-render errors	Per-doc per-page generation counter, bumped on invalidateThumbnail. Render-completions whose generation no longer matches are discarded. Empty catches around drawAnnotation replaced with console.warn including pageNum + annotation id/type.	Rapid invalidate sequences (e.g. annotation edits during a Rust render) could let a stale render result overwrite a fresher cache entry. Silent catches were also masking real plugin-render bugs in production.
e37bc4e8 fix(linux): friendlier xdg-mime errors when setting default PDF handler	Detect NotFound and return an install hint (apt install xdg-utils). On non-zero exit, mention the most likely cause (Open PDF Studio.desktop not registered because the app is running from a dev build rather than the bundled .deb/.AppImage).	Both paths previously surfaced as opaque error strings in the settings dialog, leaving users without a next step.
e8e94a6f fix(ui): custom <select> rendering on Linux Chromium for dark-theme	Force appearance:none + CSS-drawn dropdown arrow on .new-doc-select, plus matching colours on <option>/<optgroup>.	Linux/Chromium ignores background-color/color on native <select> and falls back to the OS widget, which leaves the new-document dropdown unreadable in dark-theme.

No behavioural changes to the existing public APIs introduced by the earlier commits in this PR. All fixes are scoped to a single file each. CI is rerunning on macOS, Ubuntu 22.04 and Windows.

[FreekHeijting]

Ready for review @mojtabakarimi — no rush, please review whenever it suits your schedule. CI is green on all three platforms and the PR description has a structured walkthrough (sections A/B/C) to make it easier to navigate. Happy to address any feedback.

[FreekHeijting]

Plugin-API addition (1 commit)

Field-testing the Symitech inspectie-dashboard plugin against this branch surfaced one missing API. Adding it here keeps the PR self-contained.

Commit	What	Why it matters
c502d094 feat(plugin-api): expose getAnnotations + getPageCount	Two new optional methods: api.getAnnotations() returns the live store-array of annotations on the active document (each entry has a 1-indexed page field), api.getPageCount() returns the total page-count.	Plugins building analytics widgets (count-by-type dashboards, per-page summaries) need read-access to existing annotations without subscribing to every mutation. Without this, the only path was reading window.app.documentManager, which OPPS does not expose — so plugin-side counts silently stayed at zero. Both methods are additive and feature-detectable.

CI is rerunning; expect the same green result as before.