Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Fmode Plugin (@lapis-notes/fmode)

Source: packages/plugins/plugin-fmode/src/

Manifest: id fmode, version 0.0.1, min app version 1.7.7.

The fmode package owns bundled hint-based keyboard navigation for workspace chrome that explicitly opts into a shared hint-target contract.

Runtime Surface

  • Command: toggle-fmode
  • Default hotkey: Mod+Shift+F
  • Declarative settings namespace: fmode.*
  • Package exports: plugin runtime entry at @lapis-notes/fmode, inline overlay stylesheet at @lapis-notes/fmode/app.css, and standalone stylesheet artifact at @lapis-notes/fmode/styles.css

Key Behaviors

  • Opens a temporary fixed-position overlay that labels currently visible hint targets with unique prefix-free hint codes, so no visible hint is a prefix of another and longer hints remain selectable.
  • Keeps hint badges aligned to their targets while the current pane scrolls or resizes, and anchors each badge to the target’s bottom-right corner by default. Badge visibility and placement respect both the browser viewport and clipping ancestors such as split-pane scroll containers, so hints disappear when a target scrolls out of its pane and visible hints stay inside the clipped pane edge.
  • Collects targets through Workspace.getVisibleHintTargets(), which scans visible DOM nodes marked with data-hint-target and related data-hint-* metadata.
  • Uses a plugin-owned modal Scope registration with wildcard key matching plus a capture-phase document keydown listener so hint input and editor keys are consumed by the overlay instead of leaking into the active editor, view, or browser host while fmode is open.
  • Narrows the visible hint set as the user types, activates on an exact match, and exits on Escape or after a successful selection.
  • Supports click and focus targets plus command-backed targets through data-hint-command-id metadata.
  • Initial bundled target coverage includes markdown preview links, file explorer rows and toolbar actions, search result rows and match rows, view-header navigation and action buttons, and top, stacked, and sidebar tab chrome.
  • Reads declarative fmode.* configuration on each activation so users can customize the hint alphabet, opt surfaces in or out, switch between detailed and compact HUDs, choose whether invalid input flashes or closes the overlay, and override the overlay accent color or badge text detail.
  • fmode.hudMode = "minimal" hides the top-right HUD and renders only the hint code next to each target, suppressing label and description chrome for a less intrusive presentation.

CSS Ownership

The package owns the fmode-overlay__... selector family and follows the shared Plugin CSS Contract for first-party plugin chrome.

Testing

Focused Vitest coverage lives with the package for hint-label generation, query filtering, and settings normalization. Shared API coverage for target discovery and modal wildcard key handling stays in @lapis-notes/api, and workspace e2e coverage includes scroll-stack and split-pane clipping regressions for rendered badge visibility.